diff --git a/.agents/skills/before-backend-dev/SKILL.md b/.agents/skills/before-backend-dev/SKILL.md
new file mode 100644
index 000000000..0615694c4
--- /dev/null
+++ b/.agents/skills/before-backend-dev/SKILL.md
@@ -0,0 +1,18 @@
+---
+name: before-backend-dev
+description: "Read the backend development guidelines before starting your development task."
+---
+
+Read the backend development guidelines before starting your development task.
+
+Execute these steps:
+1. Read `.trellis/spec/backend/index.md` to understand available guidelines
+2. Based on your task, read the relevant guideline files:
+   - Database work → `.trellis/spec/backend/database-guidelines.md`
+   - Error handling → `.trellis/spec/backend/error-handling.md`
+   - Logging → `.trellis/spec/backend/logging-guidelines.md`
+   - Type questions → `.trellis/spec/backend/type-safety.md`
+3. Understand the coding standards and patterns you need to follow
+4. Then proceed with your development plan
+
+This step is **mandatory** before writing any backend code.
diff --git a/.agents/skills/before-frontend-dev/SKILL.md b/.agents/skills/before-frontend-dev/SKILL.md
new file mode 100644
index 000000000..b048b8db4
--- /dev/null
+++ b/.agents/skills/before-frontend-dev/SKILL.md
@@ -0,0 +1,18 @@
+---
+name: before-frontend-dev
+description: "Read the frontend development guidelines before starting your development task."
+---
+
+Read the frontend development guidelines before starting your development task.
+
+Execute these steps:
+1. Read `.trellis/spec/frontend/index.md` to understand available guidelines
+2. Based on your task, read the relevant guideline files:
+   - Component work → `.trellis/spec/frontend/component-guidelines.md`
+   - Hook work → `.trellis/spec/frontend/hook-guidelines.md`
+   - State management → `.trellis/spec/frontend/state-management.md`
+   - Type questions → `.trellis/spec/frontend/type-safety.md`
+3. Understand the coding standards and patterns you need to follow
+4. Then proceed with your development plan
+
+This step is **mandatory** before writing any frontend code.
diff --git a/.agents/skills/brainstorm/SKILL.md b/.agents/skills/brainstorm/SKILL.md
new file mode 100644
index 000000000..e26005dcf
--- /dev/null
+++ b/.agents/skills/brainstorm/SKILL.md
@@ -0,0 +1,492 @@
+---
+name: brainstorm
+description: "Brainstorm - Requirements Discovery (AI Coding Enhanced)"
+---
+
+# Brainstorm - Requirements Discovery (AI Coding Enhanced)
+
+Guide AI through collaborative requirements discovery **before implementation**, optimized for AI coding workflows:
+
+* **Task-first** (capture ideas immediately)
+* **Action-before-asking** (reduce low-value questions)
+* **Research-first** for technical choices (avoid asking users to invent options)
+* **Diverge → Converge** (expand thinking, then lock MVP)
+
+---
+
+## When to Use
+
+Triggered from `$start` when the user describes a development task, especially when:
+
+* requirements are unclear or evolving
+* there are multiple valid implementation paths
+* trade-offs matter (UX, reliability, maintainability, cost, performance)
+* the user might not know the best options up front
+
+---
+
+## Core Principles (Non-negotiable)
+
+1. **Task-first (capture early)**
+   Always ensure a task exists at the start so the user's ideas are recorded immediately.
+
+2. **Action before asking**
+   If you can derive the answer from repo code, docs, configs, conventions, or quick research — do that first.
+
+3. **One question per message**
+   Never overwhelm the user with a list of questions. Ask one, update PRD, repeat.
+
+4. **Prefer concrete options**
+   For preference/decision questions, present 2–3 feasible, specific approaches with trade-offs.
+
+5. **Research-first for technical choices**
+   If the decision depends on industry conventions / similar tools / established patterns, do research first, then propose options.
+
+6. **Diverge → Converge**
+   After initial understanding, proactively consider future evolution, related scenarios, and failure/edge cases — then converge to an MVP with explicit out-of-scope.
+
+7. **No meta questions**
+   Do not ask "should I search?" or "can you paste the code so I can continue?"
+   If you need information: search/inspect. If blocked: ask the minimal blocking question.
+
+---
+
+## Step 0: Ensure Task Exists (ALWAYS)
+
+Before any Q&A, ensure a task exists. If none exists, create one immediately.
+
+* Use a **temporary working title** derived from the user's message.
+* It's OK if the title is imperfect — refine later in PRD.
+
+```bash
+TASK_DIR=$(python3 ./.trellis/scripts/task.py create "brainstorm: <short goal>" --slug <auto>)
+```
+
+Create/seed `prd.md` immediately with what you know:
+
+```markdown
+# brainstorm: <short goal>
+
+## Goal
+
+<one paragraph: what + why>
+
+## What I already know
+
+* <facts from user message>
+* <facts discovered from repo/docs>
+
+## Assumptions (temporary)
+
+* <assumptions to validate>
+
+## Open Questions
+
+* <ONLY Blocking / Preference questions; keep list short>
+
+## Requirements (evolving)
+
+* <start with what is known>
+
+## Acceptance Criteria (evolving)
+
+* [ ] <testable criterion>
+
+## Definition of Done (team quality bar)
+
+* Tests added/updated (unit/integration where appropriate)
+* Lint / typecheck / CI green
+* Docs/notes updated if behavior changes
+* Rollout/rollback considered if risky
+
+## Out of Scope (explicit)
+
+* <what we will not do in this task>
+
+## Technical Notes
+
+* <files inspected, constraints, links, references>
+* <research notes summary if applicable>
+```
+
+---
+
+## Step 1: Auto-Context (DO THIS BEFORE ASKING QUESTIONS)
+
+Before asking questions like "what does the code look like?", gather context yourself:
+
+### Repo inspection checklist
+
+* Identify likely modules/files impacted
+* Locate existing patterns (similar features, conventions, error handling style)
+* Check configs, scripts, existing command definitions
+* Note any constraints (runtime, dependency policy, build tooling)
+
+### Documentation checklist
+
+* Look for existing PRDs/specs/templates
+* Look for command usage examples, README, ADRs if any
+
+Write findings into PRD:
+
+* Add to `What I already know`
+* Add constraints/links to `Technical Notes`
+
+---
+
+## Step 2: Classify Complexity (still useful, not gating task creation)
+
+| Complexity   | Criteria                                               | Action                                      |
+| ------------ | ------------------------------------------------------ | ------------------------------------------- |
+| **Trivial**  | Single-line fix, typo, obvious change                  | Skip brainstorm, implement directly         |
+| **Simple**   | Clear goal, 1–2 files, scope well-defined              | Ask 1 confirm question, then implement      |
+| **Moderate** | Multiple files, some ambiguity                         | Light brainstorm (2–3 high-value questions) |
+| **Complex**  | Vague goal, architectural choices, multiple approaches | Full brainstorm                             |
+
+> Note: Task already exists from Step 0. Classification only affects depth of brainstorming.
+
+---
+
+## Step 3: Question Gate (Ask ONLY high-value questions)
+
+Before asking ANY question, run the following gate:
+
+### Gate A — Can I derive this without the user?
+
+If answer is available via:
+
+* repo inspection (code/config)
+* docs/specs/conventions
+* quick market/OSS research
+
+→ **Do not ask.** Fetch it, summarize, update PRD.
+
+### Gate B — Is this a meta/lazy question?
+
+Examples:
+
+* "Should I search?"
+* "Can you paste the code so I can proceed?"
+* "What does the code look like?" (when repo is available)
+
+→ **Do not ask.** Take action.
+
+### Gate C — What type of question is it?
+
+* **Blocking**: cannot proceed without user input
+* **Preference**: multiple valid choices, depends on product/UX/risk preference
+* **Derivable**: should be answered by inspection/research
+
+→ Only ask **Blocking** or **Preference**.
+
+---
+
+## Step 4: Research-first Mode (Mandatory for technical choices)
+
+### Trigger conditions (any → research-first)
+
+* The task involves selecting an approach, library, protocol, framework, template system, plugin mechanism, or CLI UX convention
+* The user asks for "best practice", "how others do it", "recommendation"
+* The user can't reasonably enumerate options
+
+### Research steps
+
+1. Identify 2–4 comparable tools/patterns
+2. Summarize common conventions and why they exist
+3. Map conventions onto our repo constraints
+4. Produce **2–3 feasible approaches** for our project
+
+### Research output format (PRD)
+
+Add a section in PRD (either within Technical Notes or as its own):
+
+```markdown
+## Research Notes
+
+### What similar tools do
+
+* ...
+* ...
+
+### Constraints from our repo/project
+
+* ...
+
+### Feasible approaches here
+
+**Approach A: <name>** (Recommended)
+
+* How it works:
+* Pros:
+* Cons:
+
+**Approach B: <name>**
+
+* How it works:
+* Pros:
+* Cons:
+
+**Approach C: <name>** (optional)
+
+* ...
+```
+
+Then ask **one** preference question:
+
+* "Which approach do you prefer: A / B / C (or other)?"
+
+---
+
+## Step 5: Expansion Sweep (DIVERGE) — Required after initial understanding
+
+After you can summarize the goal, proactively broaden thinking before converging.
+
+### Expansion categories (keep to 1–2 bullets each)
+
+1. **Future evolution**
+
+   * What might this feature become in 1–3 months?
+   * What extension points are worth preserving now?
+
+2. **Related scenarios**
+
+   * What adjacent commands/flows should remain consistent with this?
+   * Are there parity expectations (create vs update, import vs export, etc.)?
+
+3. **Failure & edge cases**
+
+   * Conflicts, offline/network failure, retries, idempotency, compatibility, rollback
+   * Input validation, security boundaries, permission checks
+
+### Expansion message template (to user)
+
+```markdown
+I understand you want to implement: <current goal>.
+
+Before diving into design, let me quickly diverge to consider three categories (to avoid rework later):
+
+1. Future evolution: <1–2 bullets>
+2. Related scenarios: <1–2 bullets>
+3. Failure/edge cases: <1–2 bullets>
+
+For this MVP, which would you like to include (or none)?
+
+1. Current requirement only (minimal viable)
+2. Add <X> (reserve for future extension)
+3. Add <Y> (improve robustness/consistency)
+4. Other: describe your preference
+```
+
+Then update PRD:
+
+* What's in MVP → `Requirements`
+* What's excluded → `Out of Scope`
+
+---
+
+## Step 6: Q&A Loop (CONVERGE)
+
+### Rules
+
+* One question per message
+* Prefer multiple-choice when possible
+* After each user answer:
+
+  * Update PRD immediately
+  * Move answered items from `Open Questions` → `Requirements`
+  * Update `Acceptance Criteria` with testable checkboxes
+  * Clarify `Out of Scope`
+
+### Question priority (recommended)
+
+1. **MVP scope boundary** (what is included/excluded)
+2. **Preference decisions** (after presenting concrete options)
+3. **Failure/edge behavior** (only for MVP-critical paths)
+4. **Success metrics & Acceptance Criteria** (what proves it works)
+
+### Preferred question format (multiple choice)
+
+```markdown
+For <topic>, which approach do you prefer?
+
+1. **Option A** — <what it means + trade-off>
+2. **Option B** — <what it means + trade-off>
+3. **Option C** — <what it means + trade-off>
+4. **Other** — describe your preference
+```
+
+---
+
+## Step 7: Propose Approaches + Record Decisions (Complex tasks)
+
+After requirements are clear enough, propose 2–3 approaches (if not already done via research-first):
+
+```markdown
+Based on current information, here are 2–3 feasible approaches:
+
+**Approach A: <name>** (Recommended)
+
+* How:
+* Pros:
+* Cons:
+
+**Approach B: <name>**
+
+* How:
+* Pros:
+* Cons:
+
+Which direction do you prefer?
+```
+
+Record the outcome in PRD as an ADR-lite section:
+
+```markdown
+## Decision (ADR-lite)
+
+**Context**: Why this decision was needed
+**Decision**: Which approach was chosen
+**Consequences**: Trade-offs, risks, potential future improvements
+```
+
+---
+
+## Step 8: Final Confirmation + Implementation Plan
+
+When open questions are resolved, confirm complete requirements with a structured summary:
+
+### Final confirmation format
+
+```markdown
+Here's my understanding of the complete requirements:
+
+**Goal**: <one sentence>
+
+**Requirements**:
+
+* ...
+* ...
+
+**Acceptance Criteria**:
+
+* [ ] ...
+* [ ] ...
+
+**Definition of Done**:
+
+* ...
+
+**Out of Scope**:
+
+* ...
+
+**Technical Approach**:
+<brief summary + key decisions>
+
+**Implementation Plan (small PRs)**:
+
+* PR1: <scaffolding + tests + minimal plumbing>
+* PR2: <core behavior>
+* PR3: <edge cases + docs + cleanup>
+
+Does this look correct? If yes, I'll proceed with implementation.
+```
+
+### Subtask Decomposition (Complex Tasks)
+
+For complex tasks with multiple independent work items, create subtasks:
+
+```bash
+# Create child tasks
+CHILD1=$(python3 ./.trellis/scripts/task.py create "Child task 1" --slug child1 --parent "$TASK_DIR")
+CHILD2=$(python3 ./.trellis/scripts/task.py create "Child task 2" --slug child2 --parent "$TASK_DIR")
+
+# Or link existing tasks
+python3 ./.trellis/scripts/task.py add-subtask "$TASK_DIR" "$CHILD_DIR"
+```
+
+---
+
+## PRD Target Structure (final)
+
+`prd.md` should converge to:
+
+```markdown
+# <Task Title>
+
+## Goal
+
+<why + what>
+
+## Requirements
+
+* ...
+
+## Acceptance Criteria
+
+* [ ] ...
+
+## Definition of Done
+
+* ...
+
+## Technical Approach
+
+<key design + decisions>
+
+## Decision (ADR-lite)
+
+Context / Decision / Consequences
+
+## Out of Scope
+
+* ...
+
+## Technical Notes
+
+<constraints, references, files, research notes>
+```
+
+---
+
+## Anti-Patterns (Hard Avoid)
+
+* Asking user for code/context that can be derived from repo
+* Asking user to choose an approach before presenting concrete options
+* Meta questions about whether to research
+* Staying narrowly on the initial request without considering evolution/edges
+* Letting brainstorming drift without updating PRD
+
+---
+
+## Integration with Start Workflow
+
+After brainstorm completes (Step 8 confirmation approved), the flow continues to the Task Workflow's **Phase 2: Prepare for Implementation**:
+
+```text
+Brainstorm
+  Step 0: Create task directory + seed PRD
+  Step 1–7: Discover requirements, research, converge
+  Step 8: Final confirmation → user approves
+  ↓
+Task Workflow Phase 2 (Prepare for Implementation)
+  Code-Spec Depth Check (if applicable)
+  → Research codebase (based on confirmed PRD)
+  → Configure code-spec context (jsonl files)
+  → Activate task
+  ↓
+Task Workflow Phase 3 (Execute)
+  Implement → Check → Complete
+```
+
+The task directory and PRD already exist from brainstorm, so Phase 1 of the Task Workflow is skipped entirely.
+
+---
+
+## Related Commands
+
+| Command | When to Use |
+|---------|-------------|
+| `$start` | Entry point that triggers brainstorm |
+| `$finish-work` | After implementation is complete |
+| `$update-spec` | If new patterns emerge during work |
diff --git a/.agents/skills/break-loop/SKILL.md b/.agents/skills/break-loop/SKILL.md
new file mode 100644
index 000000000..0f5f4e1c0
--- /dev/null
+++ b/.agents/skills/break-loop/SKILL.md
@@ -0,0 +1,130 @@
+---
+name: break-loop
+description: "Break the Loop - Deep Bug Analysis"
+---
+
+# Break the Loop - Deep Bug Analysis
+
+When debug is complete, use this skill for deep analysis to break the "fix bug -> forget -> repeat" cycle.
+
+---
+
+## Analysis Framework
+
+Analyze the bug you just fixed from these 5 dimensions:
+
+### 1. Root Cause Category
+
+Which category does this bug belong to?
+
+| Category | Characteristics | Example |
+|----------|-----------------|---------|
+| **A. Missing Spec** | No documentation on how to do it | New feature without checklist |
+| **B. Cross-Layer Contract** | Interface between layers unclear | API returns different format than expected |
+| **C. Change Propagation Failure** | Changed one place, missed others | Changed function signature, missed call sites |
+| **D. Test Coverage Gap** | Unit test passes, integration fails | Works alone, breaks when combined |
+| **E. Implicit Assumption** | Code relies on undocumented assumption | Timestamp seconds vs milliseconds |
+
+### 2. Why Fixes Failed (if applicable)
+
+If you tried multiple fixes before succeeding, analyze each failure:
+
+- **Surface Fix**: Fixed symptom, not root cause
+- **Incomplete Scope**: Found root cause, didn't cover all cases
+- **Tool Limitation**: grep missed it, type check wasn't strict
+- **Mental Model**: Kept looking in same layer, didn't think cross-layer
+
+### 3. Prevention Mechanisms
+
+What mechanisms would prevent this from happening again?
+
+| Type | Description | Example |
+|------|-------------|---------|
+| **Documentation** | Write it down so people know | Update thinking guide |
+| **Architecture** | Make the error impossible structurally | Type-safe wrappers |
+| **Compile-time** | TypeScript strict, no any | Signature change causes compile error |
+| **Runtime** | Monitoring, alerts, scans | Detect orphan entities |
+| **Test Coverage** | E2E tests, integration tests | Verify full flow |
+| **Code Review** | Checklist, PR template | "Did you check X?" |
+
+### 4. Systematic Expansion
+
+What broader problems does this bug reveal?
+
+- **Similar Issues**: Where else might this problem exist?
+- **Design Flaw**: Is there a fundamental architecture issue?
+- **Process Flaw**: Is there a development process improvement?
+- **Knowledge Gap**: Is the team missing some understanding?
+
+### 5. Knowledge Capture
+
+Solidify insights into the system:
+
+- [ ] Update `.trellis/spec/guides/` thinking guides
+- [ ] Update `.trellis/spec/backend/` or `frontend/` docs
+- [ ] Create issue record (if applicable)
+- [ ] Create feature ticket for root fix
+- [ ] Update check skills if needed
+
+---
+
+## Output Format
+
+Please output analysis in this format:
+
+```markdown
+## Bug Analysis: [Short Description]
+
+### 1. Root Cause Category
+- **Category**: [A/B/C/D/E] - [Category Name]
+- **Specific Cause**: [Detailed description]
+
+### 2. Why Fixes Failed (if applicable)
+1. [First attempt]: [Why it failed]
+2. [Second attempt]: [Why it failed]
+...
+
+### 3. Prevention Mechanisms
+| Priority | Mechanism | Specific Action | Status |
+|----------|-----------|-----------------|--------|
+| P0 | ... | ... | TODO/DONE |
+
+### 4. Systematic Expansion
+- **Similar Issues**: [List places with similar problems]
+- **Design Improvement**: [Architecture-level suggestions]
+- **Process Improvement**: [Development process suggestions]
+
+### 5. Knowledge Capture
+- [ ] [Documents to update / tickets to create]
+```
+
+---
+
+## Core Philosophy
+
+> **The value of debugging is not in fixing the bug, but in making this class of bugs never happen again.**
+
+Three levels of insight:
+1. **Tactical**: How to fix THIS bug
+2. **Strategic**: How to prevent THIS CLASS of bugs
+3. **Philosophical**: How to expand thinking patterns
+
+30 minutes of analysis saves 30 hours of future debugging.
+
+---
+
+## After Analysis: Immediate Actions
+
+**IMPORTANT**: After completing the analysis above, you MUST immediately:
+
+1. **Update spec/guides** - Don't just list TODOs, actually update the relevant files:
+   - If it's a cross-platform issue → update `cross-platform-thinking-guide.md`
+   - If it's a cross-layer issue → update `cross-layer-thinking-guide.md`
+   - If it's a code reuse issue → update `code-reuse-thinking-guide.md`
+   - If it's domain-specific → update `backend/*.md` or `frontend/*.md`
+
+2. **Sync templates** - After updating `.trellis/spec/`, sync to `src/templates/markdown/spec/`
+
+3. **Commit the spec updates** - This is the primary output, not just the analysis text
+
+> **The analysis is worthless if it stays in chat. The value is in the updated specs.**
diff --git a/.agents/skills/check-backend/SKILL.md b/.agents/skills/check-backend/SKILL.md
new file mode 100644
index 000000000..dce49bc84
--- /dev/null
+++ b/.agents/skills/check-backend/SKILL.md
@@ -0,0 +1,18 @@
+---
+name: check-backend
+description: "Check if the code you just wrote follows the backend development guidelines."
+---
+
+Check if the code you just wrote follows the backend development guidelines.
+
+Execute these steps:
+1. Run `git status` to see modified files
+2. Read `.trellis/spec/backend/index.md` to understand which guidelines apply
+3. Based on what you changed, read the relevant guideline files:
+   - Database changes → `.trellis/spec/backend/database-guidelines.md`
+   - Error handling → `.trellis/spec/backend/error-handling.md`
+   - Logging changes → `.trellis/spec/backend/logging-guidelines.md`
+   - Type changes → `.trellis/spec/backend/type-safety.md`
+   - Any changes → `.trellis/spec/backend/quality-guidelines.md`
+4. Review your code against the guidelines
+5. Report any violations and fix them if found
diff --git a/.agents/skills/check-cross-layer/SKILL.md b/.agents/skills/check-cross-layer/SKILL.md
new file mode 100644
index 000000000..3a3d97775
--- /dev/null
+++ b/.agents/skills/check-cross-layer/SKILL.md
@@ -0,0 +1,158 @@
+---
+name: check-cross-layer
+description: "Cross-Layer Check"
+---
+
+# Cross-Layer Check
+
+Check if your changes considered all dimensions. Most bugs come from "didn't think of it", not lack of technical skill.
+
+> **Note**: This is a **post-implementation** safety net. Ideally, read the [Pre-Implementation Checklist](.trellis/spec/guides/pre-implementation-checklist.md) **before** writing code.
+
+---
+
+## Related Documents
+
+| Document | Purpose | Timing |
+|----------|---------|--------|
+| [Pre-Implementation Checklist](.trellis/spec/guides/pre-implementation-checklist.md) | Questions before coding | **Before** writing code |
+| [Code Reuse Thinking Guide](.trellis/spec/guides/code-reuse-thinking-guide.md) | Pattern recognition | During implementation |
+| **`$check-cross-layer`** (this skill) | Verification check | **After** implementation |
+
+---
+
+## Execution Steps
+
+### 1. Identify Change Scope
+
+```bash
+git status
+git diff --name-only
+```
+
+### 2. Select Applicable Check Dimensions
+
+Based on your change type, execute relevant checks below:
+
+---
+
+## Dimension A: Cross-Layer Data Flow (Required when 3+ layers)
+
+**Trigger**: Changes involve 3 or more layers
+
+| Layer | Common Locations |
+|-------|------------------|
+| API/Routes | `routes/`, `api/`, `handlers/`, `controllers/` |
+| Service/Business Logic | `services/`, `lib/`, `core/`, `domain/` |
+| Database/Storage | `db/`, `models/`, `repositories/`, `schema/` |
+| UI/Presentation | `components/`, `views/`, `templates/`, `pages/` |
+| Utility | `utils/`, `helpers/`, `common/` |
+
+**Checklist**:
+- [ ] Read flow: Database -> Service -> API -> UI
+- [ ] Write flow: UI -> API -> Service -> Database
+- [ ] Types/schemas correctly passed between layers?
+- [ ] Errors properly propagated to caller?
+- [ ] Loading/pending states handled at each layer?
+
+**Detailed Guide**: `.trellis/spec/guides/cross-layer-thinking-guide.md`
+
+---
+
+## Dimension B: Code Reuse (Required when modifying constants/config)
+
+**Trigger**: 
+- Modifying UI constants (label, icon, color)
+- Modifying any hardcoded value
+- Seeing similar code in multiple places
+- Creating a new utility/helper function
+- Just finished batch modifications across files
+
+**Checklist**:
+- [ ] Search first: How many places define this value?
+  ```bash
+  # Search in source files (adjust extensions for your project)
+  grep -r "value-to-change" src/
+  ```
+- [ ] If 2+ places define same value -> Should extract to shared constant
+- [ ] After modification, all usage sites updated?
+- [ ] If creating utility: Does similar utility already exist?
+
+**Detailed Guide**: `.trellis/spec/guides/code-reuse-thinking-guide.md`
+
+---
+
+## Dimension B2: New Utility Functions
+
+**Trigger**: About to create a new utility/helper function
+
+**Checklist**:
+- [ ] Search for existing similar utilities first
+  ```bash
+  grep -r "functionNamePattern" src/
+  ```
+- [ ] If similar exists, can you extend it instead?
+- [ ] If creating new, is it in the right location (shared vs domain-specific)?
+
+---
+
+## Dimension B3: After Batch Modifications
+
+**Trigger**: Just modified similar patterns in multiple files
+
+**Checklist**:
+- [ ] Did you check ALL files with similar patterns?
+  ```bash
+  grep -r "patternYouChanged" src/
+  ```
+- [ ] Any files missed that should also be updated?
+- [ ] Should this pattern be abstracted to prevent future duplication?
+
+---
+
+## Dimension C: Import/Dependency Paths (Required when creating new files)
+
+**Trigger**: Creating new source files
+
+**Checklist**:
+- [ ] Using correct import paths (relative vs absolute)?
+- [ ] No circular dependencies?
+- [ ] Consistent with project's module organization?
+
+---
+
+## Dimension D: Same-Layer Consistency
+
+**Trigger**: 
+- Modifying display logic or formatting
+- Same domain concept used in multiple places
+
+**Checklist**:
+- [ ] Search for other places using same concept
+  ```bash
+  grep -r "ConceptName" src/
+  ```
+- [ ] Are these usages consistent?
+- [ ] Should they share configuration/constants?
+
+---
+
+## Common Issues Quick Reference
+
+| Issue | Root Cause | Prevention |
+|-------|------------|------------|
+| Changed one place, missed others | Didn't search impact scope | `grep` before changing |
+| Data lost at some layer | Didn't check data flow | Trace data source to destination |
+| Type/schema mismatch | Cross-layer types inconsistent | Use shared type definitions |
+| UI/output inconsistent | Same concept in multiple places | Extract shared constants |
+| Similar utility exists | Didn't search first | Search before creating |
+| Batch fix incomplete | Didn't verify all occurrences | grep after fixing |
+
+---
+
+## Output
+
+Report:
+1. Which dimensions your changes involve
+2. Check results for each dimension
+3. Issues found and fix suggestions
diff --git a/.agents/skills/check-frontend/SKILL.md b/.agents/skills/check-frontend/SKILL.md
new file mode 100644
index 000000000..cdef3cb97
--- /dev/null
+++ b/.agents/skills/check-frontend/SKILL.md
@@ -0,0 +1,18 @@
+---
+name: check-frontend
+description: "Check if the code you just wrote follows the frontend development guidelines."
+---
+
+Check if the code you just wrote follows the frontend development guidelines.
+
+Execute these steps:
+1. Run `git status` to see modified files
+2. Read `.trellis/spec/frontend/index.md` to understand which guidelines apply
+3. Based on what you changed, read the relevant guideline files:
+   - Component changes → `.trellis/spec/frontend/component-guidelines.md`
+   - Hook changes → `.trellis/spec/frontend/hook-guidelines.md`
+   - State changes → `.trellis/spec/frontend/state-management.md`
+   - Type changes → `.trellis/spec/frontend/type-safety.md`
+   - Any changes → `.trellis/spec/frontend/quality-guidelines.md`
+4. Review your code against the guidelines
+5. Report any violations and fix them if found
diff --git a/.agents/skills/create-command/SKILL.md b/.agents/skills/create-command/SKILL.md
new file mode 100644
index 000000000..eed6dafbd
--- /dev/null
+++ b/.agents/skills/create-command/SKILL.md
@@ -0,0 +1,101 @@
+---
+name: create-command
+description: "Create New Skill"
+---
+
+# Create New Skill
+
+Create a new Codex skill in `.agents/skills/<skill-name>/SKILL.md` based on user requirements.
+
+## Usage
+
+```bash
+$create-command <skill-name> <description>
+```
+
+**Example**:
+```bash
+$create-command review-pr Check PR code changes against project guidelines
+```
+
+## Execution Steps
+
+### 1. Parse Input
+
+Extract from user input:
+- **Skill name**: Use kebab-case (e.g., `review-pr`)
+- **Description**: What the skill should accomplish
+
+### 2. Analyze Requirements
+
+Determine skill type based on description:
+- **Initialization**: Read docs, establish context
+- **Pre-development**: Read guidelines, check dependencies
+- **Code check**: Validate code quality and guideline compliance
+- **Recording**: Record progress, questions, structure changes
+- **Generation**: Generate docs or code templates
+
+### 3. Generate Skill Content
+
+Minimum `SKILL.md` structure:
+
+```markdown
+---
+name: <skill-name>
+description: "<description>"
+---
+
+# <Skill Title>
+
+<Instructions for when and how to use this skill>
+```
+
+### 4. Create Files
+
+Create:
+- `.agents/skills/<skill-name>/SKILL.md`
+
+### 5. Confirm Creation
+
+Output result:
+
+```text
+[OK] Created Skill: <skill-name>
+
+File path:
+- .agents/skills/<skill-name>/SKILL.md
+
+Usage:
+- Trigger directly with $<skill-name>
+- Or open /skills and select it
+
+Description:
+<description>
+```
+
+## Skill Content Guidelines
+
+### [OK] Good skill content
+
+1. **Clear and concise**: Immediately understandable
+2. **Executable**: AI can follow steps directly
+3. **Well-scoped**: Clear boundaries of what to do and not do
+4. **Has output**: Specifies expected output format (if needed)
+
+### [X] Avoid
+
+1. **Too vague**: e.g., "optimize code"
+2. **Too complex**: Single skill should not exceed 100 lines
+3. **Duplicate functionality**: Check if similar skill exists first
+
+## Naming Conventions
+
+| Skill Type | Prefix | Example |
+|------------|--------|---------|
+| Session Start | `start` | `start` |
+| Pre-development | `before-` | `before-frontend-dev` |
+| Check | `check-` | `check-frontend` |
+| Record | `record-` | `record-session` |
+| Generate | `generate-` | `generate-api-doc` |
+| Update | `update-` | `update-changelog` |
+| Other | Verb-first | `review-code`, `sync-data` |
diff --git a/.agents/skills/finish-work/SKILL.md b/.agents/skills/finish-work/SKILL.md
new file mode 100644
index 000000000..75ec36887
--- /dev/null
+++ b/.agents/skills/finish-work/SKILL.md
@@ -0,0 +1,148 @@
+---
+name: finish-work
+description: "Finish Work - Pre-Commit Checklist"
+---
+
+# Finish Work - Pre-Commit Checklist
+
+Before submitting or committing, use this checklist to ensure work completeness.
+
+**Timing**: After code is written and tested, before commit
+
+---
+
+## Checklist
+
+### 1. Code Quality
+
+```bash
+# Must pass
+pnpm lint
+pnpm type-check
+pnpm test
+```
+
+- [ ] `pnpm lint` passes with 0 errors?
+- [ ] `pnpm type-check` passes with no type errors?
+- [ ] Tests pass?
+- [ ] No `console.log` statements (use logger)?
+- [ ] No non-null assertions (the `x!` operator)?
+- [ ] No `any` types?
+
+### 2. Code-Spec Sync
+
+**Code-Spec Docs**:
+- [ ] Does `.trellis/spec/backend/` need updates?
+  - New patterns, new modules, new conventions
+- [ ] Does `.trellis/spec/frontend/` need updates?
+  - New components, new hooks, new patterns
+- [ ] Does `.trellis/spec/guides/` need updates?
+  - New cross-layer flows, lessons from bugs
+
+**Key Question**: 
+> "If I fixed a bug or discovered something non-obvious, should I document it so future me (or others) won't hit the same issue?"
+
+If YES -> Update the relevant code-spec doc.
+
+### 2.5. Code-Spec Hard Block (Infra/Cross-Layer)
+
+If this change touches infra or cross-layer contracts, this is a blocking checklist:
+
+- [ ] Spec content is executable (real signatures/contracts), not principle-only text
+- [ ] Includes file path + command/API name + payload field names
+- [ ] Includes validation and error matrix
+- [ ] Includes Good/Base/Bad cases
+- [ ] Includes required tests and assertion points
+
+**Block Rule**:
+If infra/cross-layer changed but the related spec is still abstract, do NOT finish. Run `$update-spec` manually first.
+
+### 3. API Changes
+
+If you modified API endpoints:
+
+- [ ] Input schema updated?
+- [ ] Output schema updated?
+- [ ] API documentation updated?
+- [ ] Client code updated to match?
+
+### 4. Database Changes
+
+If you modified database schema:
+
+- [ ] Migration file created?
+- [ ] Schema file updated?
+- [ ] Related queries updated?
+- [ ] Seed data updated (if applicable)?
+
+### 5. Cross-Layer Verification
+
+If the change spans multiple layers:
+
+- [ ] Data flows correctly through all layers?
+- [ ] Error handling works at each boundary?
+- [ ] Types are consistent across layers?
+- [ ] Loading states handled?
+
+### 6. Manual Testing
+
+- [ ] Feature works in browser/app?
+- [ ] Edge cases tested?
+- [ ] Error states tested?
+- [ ] Works after page refresh?
+
+---
+
+## Quick Check Flow
+
+```bash
+# 1. Code checks
+pnpm lint && pnpm type-check
+
+# 2. View changes
+git status
+git diff --name-only
+
+# 3. Based on changed files, check relevant items above
+```
+
+---
+
+## Common Oversights
+
+| Oversight | Consequence | Check |
+|-----------|-------------|-------|
+| Code-spec docs not updated | Others don't know the change | Check .trellis/spec/ |
+| Spec text is abstract only | Easy regressions in infra/cross-layer changes | Require signature/contract/matrix/cases/tests |
+| Migration not created | Schema out of sync | Check db/migrations/ |
+| Types not synced | Runtime errors | Check shared types |
+| Tests not updated | False confidence | Run full test suite |
+| Console.log left in | Noisy production logs | Search for console.log |
+
+---
+
+## Relationship to Other Commands
+
+```
+Development Flow:
+  Write code -> Test -> $finish-work -> git commit -> $record-session
+                          |                              |
+                   Ensure completeness              Record progress
+                   
+Debug Flow:
+  Hit bug -> Fix -> $break-loop -> Knowledge capture
+                       |
+                  Deep analysis
+```
+
+- `$finish-work` - Check work completeness (this skill)
+- `$record-session` - Record session and commits
+- `$break-loop` - Deep analysis after debugging
+
+---
+
+## Core Principle
+
+> **Delivery includes not just code, but also documentation, verification, and knowledge capture.**
+
+Complete work = Code + Docs + Tests + Verification
diff --git a/.agents/skills/integrate-skill/SKILL.md b/.agents/skills/integrate-skill/SKILL.md
new file mode 100644
index 000000000..41107884f
--- /dev/null
+++ b/.agents/skills/integrate-skill/SKILL.md
@@ -0,0 +1,221 @@
+---
+name: integrate-skill
+description: "Integrate Skill into Project Guidelines"
+---
+
+# Integrate Skill into Project Guidelines
+
+Adapt and integrate a reusable skill into your project's development guidelines (not directly into project code).
+
+## Usage
+
+```
+$integrate-skill <skill-name>
+```
+
+**Examples**:
+```
+$integrate-skill frontend-design
+$integrate-skill mcp-builder
+```
+
+## Core Principle
+
+> [!] **Important**: The goal of skill integration is to update **development guidelines**, not to generate project code directly.
+>
+> - Guidelines content -> Write to `.trellis/spec/{target}/doc.md`
+> - Code examples -> Place in `.trellis/spec/{target}/examples/skills/<skill-name>/`
+> - Example files -> Use `.template` suffix (e.g., `component.tsx.template`) to avoid IDE errors
+>
+> Where `{target}` is `frontend` or `backend`, determined by skill type.
+
+## Execution Steps
+
+### 1. Read Skill Content
+
+Locate and read the skill instructions:
+- `.agents/skills/<skill-name>/SKILL.md` in the repository
+- Skill list in `AGENTS.md` (when available in current context)
+
+If the skill cannot be found, ask the user for the source path or repository.
+
+### 2. Determine Integration Target
+
+Based on skill type, determine which guidelines to update:
+
+| Skill Category | Integration Target |
+|----------------|-------------------|
+| UI/Frontend (`frontend-design`, `web-artifacts-builder`) | `.trellis/spec/frontend/` |
+| Backend/API (`mcp-builder`) | `.trellis/spec/backend/` |
+| Documentation (`doc-coauthoring`, `docx`, `pdf`) | `.trellis/` or create dedicated guidelines |
+| Testing (`webapp-testing`) | `.trellis/spec/frontend/` (E2E) |
+
+### 3. Analyze Skill Content
+
+Extract from the skill:
+- **Core concepts**: How the skill works and key concepts
+- **Best practices**: Recommended approaches
+- **Code patterns**: Reusable code templates
+- **Caveats**: Common issues and solutions
+
+### 4. Execute Integration
+
+#### 4.1 Update Guidelines Document
+
+Add a new section to the corresponding `doc.md`:
+
+```markdown
+@@@section:skill-<skill-name>
+## # <Skill Name> Integration Guide
+
+### Overview
+[Core functionality and use cases of the skill]
+
+### Project Adaptation
+[How to use this skill in the current project]
+
+### Usage Steps
+1. [Step 1]
+2. [Step 2]
+
+### Caveats
+- [Project-specific constraints]
+- [Differences from default behavior]
+
+### Reference Examples
+See `examples/skills/<skill-name>/`
+
+@@@/section:skill-<skill-name>
+```
+
+#### 4.2 Create Examples Directory (if code examples exist)
+
+```bash
+# Directory structure ({target} = frontend or backend)
+.trellis/spec/{target}/
+|-- doc.md                      # Add skill-related section
+|-- index.md                    # Update index
++-- examples/
+    +-- skills/
+        +-- <skill-name>/
+            |-- README.md               # Example documentation
+            |-- example-1.ts.template   # Code example (use .template suffix)
+            +-- example-2.tsx.template
+```
+
+**File naming conventions**:
+- Code files: `<name>.<ext>.template` (e.g., `component.tsx.template`)
+- Config files: `<name>.config.template` (e.g., `tailwind.config.template`)
+- Documentation: `README.md` (normal suffix)
+
+#### 4.3 Update Index File
+
+Add to the Quick Navigation table in `index.md`:
+
+```markdown
+| <Skill-related task> | <Section name> | `skill-<skill-name>` |
+```
+
+### 5. Generate Integration Report
+
+---
+
+## Skill Integration Report: `<skill-name>`
+
+### # Overview
+- **Skill description**: [Functionality description]
+- **Integration target**: `.trellis/spec/{target}/`
+
+### # Tech Stack Compatibility
+
+| Skill Requirement | Project Status | Compatibility |
+|-------------------|----------------|---------------|
+| [Tech 1] | [Project tech] | [OK]/[!]/[X] |
+
+### # Integration Locations
+
+| Type | Path |
+|------|------|
+| Guidelines doc | `.trellis/spec/{target}/doc.md` (section: `skill-<name>`) |
+| Code examples | `.trellis/spec/{target}/examples/skills/<name>/` |
+| Index update | `.trellis/spec/{target}/index.md` |
+
+> `{target}` = `frontend` or `backend`
+
+### # Dependencies (if needed)
+
+```bash
+# Install required dependencies (adjust for your package manager)
+npm install <package>
+# or
+pnpm add <package>
+# or
+yarn add <package>
+```
+
+### [OK] Completed Changes
+
+- [ ] Added `@@@section:skill-<name>` section to `doc.md`
+- [ ] Added index entry to `index.md`
+- [ ] Created example files in `examples/skills/<name>/`
+- [ ] Example files use `.template` suffix
+
+### # Related Guidelines
+
+- [Existing related section IDs]
+
+---
+
+## 6. Optional: Create Usage Skill
+
+If this skill is frequently used, create a shortcut skill:
+
+```bash
+$create-command use-<skill-name> Use <skill-name> skill following project guidelines
+```
+
+## Common Skill Integration Reference
+
+| Skill | Integration Target | Examples Directory |
+|-------|-------------------|-------------------|
+| `frontend-design` | `frontend` | `examples/skills/frontend-design/` |
+| `mcp-builder` | `backend` | `examples/skills/mcp-builder/` |
+| `webapp-testing` | `frontend` | `examples/skills/webapp-testing/` |
+| `doc-coauthoring` | `.trellis/` | N/A (documentation workflow only) |
+
+## Example: Integrating `mcp-builder` Skill
+
+### Directory Structure
+
+```
+.trellis/spec/backend/
+|-- doc.md                           # Add MCP section
+|-- index.md                         # Add index entry
++-- examples/
+    +-- skills/
+        +-- mcp-builder/
+            |-- README.md
+            |-- server.ts.template
+            |-- tools.ts.template
+            +-- types.ts.template
+```
+
+### New Section in doc.md
+
+```markdown
+@@@section:skill-mcp-builder
+## # MCP Server Development Guide
+
+### Overview
+Create LLM-callable tool services using MCP (Model Context Protocol).
+
+### Project Adaptation
+- Place services in a dedicated directory
+- Follow existing TypeScript and type definition conventions
+- Use project's logging system
+
+### Reference Examples
+See `examples/skills/mcp-builder/`
+
+@@@/section:skill-mcp-builder
+```
diff --git a/.agents/skills/onboard/SKILL.md b/.agents/skills/onboard/SKILL.md
new file mode 100644
index 000000000..362127193
--- /dev/null
+++ b/.agents/skills/onboard/SKILL.md
@@ -0,0 +1,363 @@
+---
+name: onboard
+description: "PART 3: Customize Your Development Guidelines"
+---
+
+You are a senior developer onboarding a new team member to this project's AI-assisted workflow system.
+
+YOUR ROLE: Be a mentor and teacher. Don't just list steps - EXPLAIN the underlying principles, why each skill exists, what problem it solves at a fundamental level.
+
+## CRITICAL INSTRUCTION - YOU MUST COMPLETE ALL SECTIONS
+
+This onboarding has THREE equally important parts:
+
+**PART 1: Core Concepts** (Sections: CORE PHILOSOPHY, SYSTEM STRUCTURE, SKILL DEEP DIVE)
+- Explain WHY this workflow exists
+- Explain WHAT each skill does and WHY
+
+**PART 2: Real-World Examples** (Section: REAL-WORLD WORKFLOW EXAMPLES)
+- Walk through ALL 5 examples in detail
+- For EACH step in EACH example, explain:
+  - PRINCIPLE: Why this step exists
+  - WHAT HAPPENS: What the skill actually does
+  - IF SKIPPED: What goes wrong without it
+
+**PART 3: Customize Your Development Guidelines** (Section: CUSTOMIZE YOUR DEVELOPMENT GUIDELINES)
+- Check if project guidelines are still empty templates
+- If empty, guide the developer to fill them with project-specific content
+- Explain the customization workflow
+
+DO NOT skip any part. All three parts are essential:
+- Part 1 teaches the concepts
+- Part 2 shows how concepts work in practice
+- Part 3 ensures the project has proper guidelines for AI to follow
+
+After completing ALL THREE parts, ask the developer about their first task.
+
+---
+
+## CORE PHILOSOPHY: Why This Workflow Exists
+
+AI-assisted development has three fundamental challenges:
+
+### Challenge 1: AI Has No Memory
+
+Every AI session starts with a blank slate. Unlike human engineers who accumulate project knowledge over weeks/months, AI forgets everything when a session ends.
+
+**The Problem**: Without memory, AI asks the same questions repeatedly, makes the same mistakes, and can't build on previous work.
+
+**The Solution**: The `.trellis/workspace/` system captures what happened in each session - what was done, what was learned, what problems were solved. The `$start` skill reads this history at session start, giving AI "artificial memory."
+
+### Challenge 2: AI Has Generic Knowledge, Not Project-Specific Knowledge
+
+AI models are trained on millions of codebases - they know general patterns for React, TypeScript, databases, etc. But they don't know YOUR project's conventions.
+
+**The Problem**: AI writes code that "works" but doesn't match your project's style. It uses patterns that conflict with existing code. It makes decisions that violate unwritten team rules.
+
+**The Solution**: The `.trellis/spec/` directory contains project-specific guidelines. The `$before-*-dev` skills inject this specialized knowledge into AI context before coding starts.
+
+### Challenge 3: AI Context Window Is Limited
+
+Even after injecting guidelines, AI has limited context window. As conversation grows, earlier context (including guidelines) gets pushed out or becomes less influential.
+
+**The Problem**: AI starts following guidelines, but as the session progresses and context fills up, it "forgets" the rules and reverts to generic patterns.
+
+**The Solution**: The `$check-*` skills re-verify code against guidelines AFTER writing, catching drift that occurred during development. The `$finish-work` skill does a final holistic review.
+
+---
+
+## SYSTEM STRUCTURE
+
+```
+.trellis/
+|-- .developer              # Your identity (gitignored)
+|-- workflow.md             # Complete workflow documentation
+|-- workspace/              # "AI Memory" - session history
+|   |-- index.md            # All developers' progress
+|   +-- {developer}/        # Per-developer directory
+|       |-- index.md        # Personal progress index
+|       +-- journal-N.md    # Session records (max 2000 lines)
+|-- tasks/                  # Task tracking (unified)
+|   +-- {MM}-{DD}-{slug}/   # Task directory
+|       |-- task.json       # Task metadata
+|       +-- prd.md          # Requirements doc
+|-- spec/                   # "AI Training Data" - project knowledge
+|   |-- frontend/           # Frontend conventions
+|   |-- backend/            # Backend conventions
+|   +-- guides/             # Thinking patterns
++-- scripts/                # Automation tools
+```
+
+### Understanding spec/ subdirectories
+
+**frontend/** - Single-layer frontend knowledge:
+- Component patterns (how to write components in THIS project)
+- State management rules (Redux? Zustand? Context?)
+- Styling conventions (CSS modules? Tailwind? Styled-components?)
+- Hook patterns (custom hooks, data fetching)
+
+**backend/** - Single-layer backend knowledge:
+- API design patterns (REST? GraphQL? tRPC?)
+- Database conventions (query patterns, migrations)
+- Error handling standards
+- Logging and monitoring rules
+
+**guides/** - Cross-layer thinking guides:
+- Code reuse thinking guide
+- Cross-layer thinking guide
+- Pre-implementation checklists
+
+---
+
+## SKILL DEEP DIVE
+
+### $start - Restore AI Memory
+
+**WHY IT EXISTS**:
+When a human engineer joins a project, they spend days/weeks learning: What is this project? What's been built? What's in progress? What's the current state?
+
+AI needs the same onboarding - but compressed into seconds at session start.
+
+**WHAT IT ACTUALLY DOES**:
+1. Reads developer identity (who am I in this project?)
+2. Checks git status (what branch? uncommitted changes?)
+3. Reads recent session history from `workspace/` (what happened before?)
+4. Identifies active features (what's in progress?)
+5. Understands current project state before making any changes
+
+**WHY THIS MATTERS**:
+- Without $start: AI is blind. It might work on wrong branch, conflict with others' work, or redo already-completed work.
+- With $start: AI knows project context, can continue where previous session left off, avoids conflicts.
+
+---
+
+### $before-frontend-dev and $before-backend-dev - Inject Specialized Knowledge
+
+**WHY IT EXISTS**:
+AI models have "pre-trained knowledge" - general patterns from millions of codebases. But YOUR project has specific conventions that differ from generic patterns.
+
+**WHAT IT ACTUALLY DOES**:
+1. Reads `.trellis/spec/frontend/` or `.trellis/spec/backend/`
+2. Loads project-specific patterns into AI's working context:
+   - Component naming conventions
+   - State management patterns
+   - Database query patterns
+   - Error handling standards
+
+**WHY THIS MATTERS**:
+- Without before-*-dev: AI writes generic code that doesn't match project style.
+- With before-*-dev: AI writes code that looks like the rest of the codebase.
+
+---
+
+### $check-frontend and $check-backend - Combat Context Drift
+
+**WHY IT EXISTS**:
+AI context window has limited capacity. As conversation progresses, guidelines injected at session start become less influential. This causes "context drift."
+
+**WHAT IT ACTUALLY DOES**:
+1. Re-reads the guidelines that were injected earlier
+2. Compares written code against those guidelines
+3. Runs type checker and linter
+4. Identifies violations and suggests fixes
+
+**WHY THIS MATTERS**:
+- Without check-*: Context drift goes unnoticed, code quality degrades.
+- With check-*: Drift is caught and corrected before commit.
+
+---
+
+### $check-cross-layer - Multi-Dimension Verification
+
+**WHY IT EXISTS**:
+Most bugs don't come from lack of technical skill - they come from "didn't think of it":
+- Changed a constant in one place, missed 5 other places
+- Modified database schema, forgot to update the API layer
+- Created a utility function, but similar one already exists
+
+**WHAT IT ACTUALLY DOES**:
+1. Identifies which dimensions your change involves
+2. For each dimension, runs targeted checks:
+   - Cross-layer data flow
+   - Code reuse analysis
+   - Import path validation
+   - Consistency checks
+
+---
+
+### $finish-work - Holistic Pre-Commit Review
+
+**WHY IT EXISTS**:
+The `$check-*` skills focus on code quality within a single layer. But real changes often have cross-cutting concerns.
+
+**WHAT IT ACTUALLY DOES**:
+1. Reviews all changes holistically
+2. Checks cross-layer consistency
+3. Identifies broader impacts
+4. Checks if new patterns should be documented
+
+---
+
+### $record-session - Persist Memory for Future
+
+**WHY IT EXISTS**:
+All the context AI built during this session will be lost when session ends. The next session's `$start` needs this information.
+
+**WHAT IT ACTUALLY DOES**:
+1. Records session summary to `workspace/{developer}/journal-N.md`
+2. Captures what was done, learned, and what's remaining
+3. Updates index files for quick lookup
+
+---
+
+## REAL-WORLD WORKFLOW EXAMPLES
+
+### Example 1: Bug Fix Session
+
+**[1/8] $start** - AI needs project context before touching code
+**[2/8] python3 ./.trellis/scripts/task.py create "Fix bug" --slug fix-bug** - Track work for future reference
+**[3/8] $before-frontend-dev** - Inject project-specific frontend knowledge
+**[4/8] Investigate and fix the bug** - Actual development work
+**[5/8] $check-frontend** - Re-verify code against guidelines
+**[6/8] $finish-work** - Holistic cross-layer review
+**[7/8] Human tests and commits** - Human validates before code enters repo
+**[8/8] $record-session** - Persist memory for future sessions
+
+### Example 2: Planning Session (No Code)
+
+**[1/4] $start** - Context needed even for non-coding work
+**[2/4] python3 ./.trellis/scripts/task.py create "Planning task" --slug planning-task** - Planning is valuable work
+**[3/4] Review docs, create subtask list** - Actual planning work
+**[4/4] $record-session (with --summary)** - Planning decisions must be recorded
+
+### Example 3: Code Review Fixes
+
+**[1/6] $start** - Resume context from previous session
+**[2/6] $before-backend-dev** - Re-inject guidelines before fixes
+**[3/6] Fix each CR issue** - Address feedback with guidelines in context
+**[4/6] $check-backend** - Verify fixes didn't introduce new issues
+**[5/6] $finish-work** - Document lessons from CR
+**[6/6] Human commits, then $record-session** - Preserve CR lessons
+
+### Example 4: Large Refactoring
+
+**[1/5] $start** - Clear baseline before major changes
+**[2/5] Plan phases** - Break into verifiable chunks
+**[3/5] Execute phase by phase with $check-* after each** - Incremental verification
+**[4/5] $finish-work** - Check if new patterns should be documented
+**[5/5] Record with multiple commit hashes** - Link all commits to one feature
+
+### Example 5: Debug Session
+
+**[1/6] $start** - See if this bug was investigated before
+**[2/6] $before-backend-dev** - Guidelines might document known gotchas
+**[3/6] Investigation** - Actual debugging work
+**[4/6] $check-backend** - Verify debug changes don't break other things
+**[5/6] $finish-work** - Debug findings might need documentation
+**[6/6] Human commits, then $record-session** - Debug knowledge is valuable
+
+---
+
+## KEY RULES TO EMPHASIZE
+
+1. **AI NEVER commits** - Human tests and approves. AI prepares, human validates.
+2. **Guidelines before code** - `$before-*-dev` skills inject project knowledge.
+3. **Check after code** - `$check-*` skills catch context drift.
+4. **Record everything** - $record-session persists memory.
+
+---
+
+# PART 3: Customize Your Development Guidelines
+
+After explaining Part 1 and Part 2, check if the project's development guidelines need customization.
+
+## Step 1: Check Current Guidelines Status
+
+Check if `.trellis/spec/` contains empty templates or customized guidelines:
+
+```bash
+# Check if files are still empty templates (look for placeholder text)
+grep -l "To be filled by the team" .trellis/spec/backend/*.md 2>/dev/null | wc -l
+grep -l "To be filled by the team" .trellis/spec/frontend/*.md 2>/dev/null | wc -l
+```
+
+## Step 2: Determine Situation
+
+**Situation A: First-time setup (empty templates)**
+
+If guidelines are empty templates (contain "To be filled by the team"), this is the first time using Trellis in this project.
+
+Explain to the developer:
+
+"I see that the development guidelines in `.trellis/spec/` are still empty templates. This is normal for a new Trellis setup!
+
+The templates contain placeholder text that needs to be replaced with YOUR project's actual conventions. Without this, `$before-*-dev` skills won't provide useful guidance.
+
+**Your first task should be to fill in these guidelines:**
+
+1. Look at your existing codebase
+2. Identify the patterns and conventions already in use
+3. Document them in the guideline files
+
+For example, for `.trellis/spec/backend/database-guidelines.md`:
+- What ORM/query library does your project use?
+- How are migrations managed?
+- What naming conventions for tables/columns?
+
+Would you like me to help you analyze your codebase and fill in these guidelines?"
+
+**Situation B: Guidelines already customized**
+
+If guidelines have real content (no "To be filled" placeholders), this is an existing setup.
+
+Explain to the developer:
+
+"Great! Your team has already customized the development guidelines. You can start using `$before-*-dev` skills right away.
+
+I recommend reading through `.trellis/spec/` to familiarize yourself with the team's coding standards."
+
+## Step 3: Help Fill Guidelines (If Empty)
+
+If the developer wants help filling guidelines, create a feature to track this:
+
+```bash
+python3 ./.trellis/scripts/task.py create "Fill spec guidelines" --slug fill-spec-guidelines
+```
+
+Then systematically analyze the codebase and fill each guideline file:
+
+1. **Analyze the codebase** - Look at existing code patterns
+2. **Document conventions** - Write what you observe, not ideals
+3. **Include examples** - Reference actual files in the project
+4. **List forbidden patterns** - Document anti-patterns the team avoids
+
+Work through one file at a time:
+- `backend/directory-structure.md`
+- `backend/database-guidelines.md`
+- `backend/error-handling.md`
+- `backend/quality-guidelines.md`
+- `backend/logging-guidelines.md`
+- `frontend/directory-structure.md`
+- `frontend/component-guidelines.md`
+- `frontend/hook-guidelines.md`
+- `frontend/state-management.md`
+- `frontend/quality-guidelines.md`
+- `frontend/type-safety.md`
+
+---
+
+## Completing the Onboard Session
+
+After covering all three parts, summarize:
+
+"You're now onboarded to the Trellis workflow system! Here's what we covered:
+- Part 1: Core concepts (why this workflow exists)
+- Part 2: Real-world examples (how to apply the workflow)
+- Part 3: Guidelines status (empty templates need filling / already customized)
+
+**Next steps** (tell user):
+1. Run `$record-session` to record this onboard session
+2. [If guidelines empty] Start filling in `.trellis/spec/` guidelines
+3. [If guidelines ready] Start your first development task
+
+What would you like to do first?"
diff --git a/.agents/skills/project-handoff/SKILL.md b/.agents/skills/project-handoff/SKILL.md
new file mode 100644
index 000000000..c3762225c
--- /dev/null
+++ b/.agents/skills/project-handoff/SKILL.md
@@ -0,0 +1,61 @@
+---
+name: project-handoff
+description: "Load the minimal coding-deepgent handoff context for a new session without re-reading large planning trees."
+---
+
+# Project Handoff
+
+Use this skill at the start of a new `coding-deepgent` session when you need to resume work with minimal context cost.
+
+## Goal
+
+Load only the compact handoff state and the few canonical project documents needed to continue safely.
+
+## Read In This Order
+
+1. `.trellis/project-handoff.md`
+2. `.trellis/tasks/04-14-redefine-coding-deepgent-final-goal/prd.md`
+3. `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+4. `coding-deepgent/PROJECT_PROGRESS.md`
+5. `.trellis/spec/backend/runtime-context-compaction-contracts.md`
+6. `.trellis/spec/backend/task-workflow-contracts.md`
+
+## Then Refresh Live State
+
+Run only these lightweight commands:
+
+```bash
+git branch --show-current
+git status -sb
+gh pr view 220 --repo shareAI-lab/learn-claude-code --json number,title,url,isDraft,headRefName,baseRefName
+```
+
+## If You Need The Latest Stage Details
+
+Read only the most recent completed/active stage PRDs relevant to the requested work.
+
+Current default shortlist:
+
+```text
+.trellis/tasks/04-15-stage-17c-explicit-plan-artifact-boundary/prd.md
+.trellis/tasks/04-15-stage-17d-verifier-subagent-execution-boundary/prd.md
+.trellis/tasks/04-15-stage-18a-verifier-execution-integration/prd.md
+```
+
+Do not expand beyond this shortlist unless the current task introduces a new feature band or a real ambiguity appears.
+
+## Output
+
+After loading context, summarize briefly:
+
+* current branch / PR
+* current mainline stage family
+* latest completed stage(s)
+* active next task or recommended next step
+* any uncommitted changes
+
+## Rules
+
+* Prefer the handoff document over re-reading broad `.trellis/plans` and `.trellis/tasks` trees.
+* Reuse verified stage checkpoints already written in PRDs.
+* Do not start implementation until this minimal resume pass is complete.
diff --git a/.agents/skills/record-session/SKILL.md b/.agents/skills/record-session/SKILL.md
new file mode 100644
index 000000000..34dbbda7e
--- /dev/null
+++ b/.agents/skills/record-session/SKILL.md
@@ -0,0 +1,66 @@
+---
+name: record-session
+description: "Record work progress after human has tested and committed code"
+---
+
+[!] **Prerequisite**: This skill should only be used AFTER the human has tested and committed the code.
+
+**Do NOT run `git commit` directly** — the scripts below handle their own commits for `.trellis/` metadata. You only need to read git history (`git log`, `git status`, `git diff`) and run the Python scripts.
+
+---
+
+## Record Work Progress
+
+### Step 1: Get Context & Check Tasks
+
+```bash
+python3 ./.trellis/scripts/get_context.py --mode record
+```
+
+[!] Archive tasks whose work is **actually done** — judge by work status, not the `status` field in task.json:
+- Code committed? → Archive it (don't wait for PR)
+- All acceptance criteria met? → Archive it
+- Don't skip archiving just because `status` still says `planning` or `in_progress`
+
+```bash
+python3 ./.trellis/scripts/task.py archive <task-name>
+```
+
+### Step 2: One-Click Add Session
+
+```bash
+# Method 1: Simple parameters
+python3 ./.trellis/scripts/add_session.py \
+  --title "Session Title" \
+  --commit "hash1,hash2" \
+  --summary "Brief summary of what was done"
+
+# Method 2: Pass detailed content via stdin
+cat << 'EOF' | python3 ./.trellis/scripts/add_session.py --title "Title" --commit "hash"
+| Feature | Description |
+|---------|-------------|
+| New API | Added user authentication endpoint |
+| Frontend | Updated login form |
+
+**Updated Files**:
+- `packages/api/modules/auth/router.ts`
+- `apps/web/modules/auth/components/login-form.tsx`
+EOF
+```
+
+**Auto-completes**:
+- [OK] Appends session to journal-N.md
+- [OK] Auto-detects line count, creates new file if >2000 lines
+- [OK] Updates index.md (Total Sessions +1, Last Active, line stats, history)
+- [OK] Auto-commits .trellis/workspace and .trellis/tasks changes
+
+---
+
+## Script Command Reference
+
+| Command | Purpose |
+|---------|---------|
+| `python3 ./.trellis/scripts/get_context.py --mode record` | Get context for record-session |
+| `python3 ./.trellis/scripts/add_session.py --title "..." --commit "..."` | **One-click add session (recommended)** |
+| `python3 ./.trellis/scripts/task.py archive <name>` | Archive completed task (auto-commits) |
+| `python3 ./.trellis/scripts/task.py list` | List active tasks |
diff --git a/.agents/skills/stage-iterate/SKILL.md b/.agents/skills/stage-iterate/SKILL.md
new file mode 100644
index 000000000..a818f8983
--- /dev/null
+++ b/.agents/skills/stage-iterate/SKILL.md
@@ -0,0 +1,270 @@
+---
+name: stage-iterate
+description: Run a staged implementation plan end-to-end with Trellis, cc-haha alignment, LangChain architecture guard, tests, and an explicit checkpoint gate after each sub-stage. Use when the user wants long-running staged work, iterative implementation, or continuing a roadmap such as Stage 12A/12B without drifting.
+---
+
+# Stage Iterate
+
+Use this skill for staged product work where implementation should proceed over one or more sub-stages without losing alignment or blindly continuing after a boundary changes.
+
+Primary example:
+
+```text
+$stage-iterate Stage 12 Context and Recovery Hardening
+```
+
+## Cost Modes
+
+This skill has two execution modes:
+
+* `lean` (default)
+* `deep`
+
+If the user does not explicitly request a long-running, high-context, or all-in-one pass, default to `lean`.
+
+Use `deep` only when the user explicitly opts in with wording like:
+
+* `deep mode`
+* `long-run`
+* `do the whole chain`
+* `one-shot`
+* `full validation`
+* `read everything again`
+
+### `lean` mode rules
+
+Use these by default:
+
+* Work one sub-stage at a time.
+* Do not automatically re-read large source/doc sets already captured in recent PRDs unless a real ambiguity appears.
+* Prefer focused tests over broad regression.
+* Do not automatically run full `pytest`, full `mypy`, or broad docs/git/PR updates.
+* If the checkpoint decision is `continue`, automatically move to the next sub-stage, but keep the validation and context budget lean.
+
+### `deep` mode rules
+
+Use these only on explicit opt-in:
+
+* Auto-continue after `APPROVE`.
+* Broader re-orientation is allowed.
+* Combined/full validation is allowed when justified.
+* Git/PR/doc updates may be folded into the same run if requested.
+
+## Core Rule
+
+Do not move from one sub-stage to the next automatically just because tests pass.
+
+After every sub-stage, run a checkpoint gate and choose exactly one outcome:
+
+* `continue`: next sub-stage still holds and can start.
+* `adjust`: update the next sub-stage plan before continuing.
+* `split`: create a prerequisite task before continuing.
+* `stop`: ask the user because scope, alignment, tests, or architecture are no longer safe.
+
+If the checkpoint result is `continue`, immediately begin the next planned sub-stage without waiting for additional user approval.
+
+In `lean` mode, `continue` still means continue.
+
+The difference from `deep` is:
+
+* narrower context reuse
+* narrower validation scope
+* no automatic broad docs/git/PR work
+
+Only interrupt the long-running workflow when:
+
+* the checkpoint result is `adjust`, `split`, or `stop`
+* the user explicitly interrupts or redirects the work
+* a hard blocker appears that cannot be resolved locally
+
+Use an explicit sub-stage state machine:
+
+* `planning`
+* `implementing`
+* `verifying`
+* `checkpoint`
+* `terminal`
+
+When resuming the same stage workflow later, continue from the current active state instead of replaying the whole orientation process from scratch.
+
+If recent PRDs or stage ledgers already contain the required source mapping, expected effect, and boundaries, do not re-run a large source-reading pass by default in `lean` mode.
+
+## Workflow
+
+### 1. Orient
+
+Run the normal Trellis session/task checks:
+
+```bash
+python3 ./.trellis/scripts/get_context.py
+python3 ./.trellis/scripts/task.py list
+```
+
+If a matching task already exists, read its `prd.md` and `task.json`.
+
+If there is already an active stage-iterate run for the same stage family, resume it from the current sub-stage/state instead of restarting the whole workflow.
+
+If no matching task exists, create one:
+
+```bash
+python3 ./.trellis/scripts/task.py create "<stage title>" --slug <slug>
+```
+
+In `lean` mode, prefer:
+
+* read the latest relevant checkpoint and PRD first
+* reuse prior source mapping if it is still sufficient
+* only expand source reading when the current sub-stage introduces a genuinely new feature band
+
+### 2. Confirm Scope From Existing Plans
+
+Read the stage plan and any target design docs relevant to the request.
+
+For this project, common inputs are:
+
+```text
+.omx/plans/coding-deepgent-cc-core-highlights-roadmap.md
+.omx/plans/coding-deepgent-h01-h10-target-design.md
+.trellis/tasks/<task>/prd.md
+```
+
+If the stage references cc-haha behavior, use `$cc-haha-alignment` before implementation.
+
+If it touches LangChain/LangGraph code, use `$langchain-architecture-guard` before implementation.
+
+If it changes backend product code, use `$before-backend-dev` before implementation.
+
+In `lean` mode, "use" these skills by reusing their already-recorded conclusions when available, instead of always repeating the full discovery pass.
+
+### 3. Prepare A Sub-Stage PRD
+
+Before coding a sub-stage, the PRD must include:
+
+* goal and concrete benefit
+* cc-haha source files/symbols to inspect
+* LangChain-native boundary
+* requirements and acceptance criteria
+* explicit out-of-scope items
+* test plan
+
+For infrastructure work, include what future stage the infrastructure unlocks.
+
+### 4. Execute Trellis Task Workflow
+
+After the PRD is clear:
+
+```bash
+python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" backend
+python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<reason>"
+python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>"
+python3 ./.trellis/scripts/task.py start "$TASK_DIR"
+```
+
+Then implement and test the sub-stage.
+
+### 4.1 Validation Budget
+
+Default validation by mode:
+
+* `lean`
+  - focused tests only
+  - targeted lint/typecheck only on changed files
+  - full-suite validation only when:
+    - the user asks
+    - the sub-stage changes cross-cutting contracts
+    - focused validation exposes ambiguity that broader tests must resolve
+* `deep`
+  - focused tests plus broader regression as appropriate
+
+When the user says they want to defer heavy validation until later, honor that unless the current change would be unsafe without minimal verification.
+
+### 4.5 Optional Subagent Parallelization
+
+Use subagents only when the user explicitly authorizes subagents, delegation, or parallel agent work in the current conversation.
+
+Good delegation targets:
+
+* independent codebase research
+* cc-haha source mapping for different modules
+* test coverage audit
+* non-overlapping code edits with clear file ownership
+
+Do not delegate:
+
+* immediate blocking work needed for the next local step
+* final architecture decisions
+* tightly coupled edits in the same file
+* work that duplicates what the main agent is already doing
+
+For worker subagents, state:
+
+* they are not alone in the codebase
+* they must not revert others' changes
+* their file ownership is limited to the assigned paths
+* their final response must list changed files and verification run
+
+For explorer subagents, ask for a concrete bounded answer and avoid broad "read everything" prompts.
+
+### 5. Checkpoint Gate
+
+At the end of every sub-stage, write a checkpoint summary with:
+
+* implemented behavior
+* tests run and result
+* files changed
+* cc-haha alignment evidence
+* LangChain-native architecture evidence
+* new boundary issues discovered
+* architecture drift risks
+* whether the next sub-stage still holds
+
+Also assign an internal checkpoint verdict:
+
+* `APPROVE` → maps to `continue`
+* `ITERATE` → maps to `adjust` or `split`
+* `REJECT` → maps to `stop`
+
+Use this decision table:
+
+| Condition | Decision |
+|---|---|
+| Tests fail | `stop` or `adjust` |
+| cc-haha alignment missing for a cc-targeted behavior | `stop` |
+| LangChain-native implementation would be compromised | `stop` or `split` |
+| Next sub-stage depends on a newly discovered prerequisite | `split` |
+| Plan is still valid but needs scope changes | `adjust` |
+| No blockers and next sub-stage remains valid | `continue` |
+
+Execution rule after the checkpoint:
+
+* `continue` → start the next sub-stage immediately
+* `adjust` → rewrite the next sub-stage plan, then continue only if the rewrite resolves the issue
+* `split` → create the prerequisite task and stop the main staged run
+* `stop` → stop and ask the user
+
+Always append the checkpoint to a stage ledger in the active task notes or linked planning doc so later resumes can pick up from the latest verified state.
+
+### 6. Improve This Skill When It Fails
+
+If this skill did not prevent drift, ambiguity, over-scoping, missing tests, or missing alignment, update it.
+
+Also update it when:
+
+* a long-running run consumed unnecessary context by re-reading already-settled planning/source material
+* it defaulted to broader validation than the user needed
+* it auto-continued when the user actually wanted a cheaper one-sub-stage cadence
+
+Use this lightweight improvement loop:
+
+1. Record the failure in the active task summary.
+2. Identify whether the missing guard belongs in `SKILL.md` or `references/stage-iteration-protocol.md`.
+3. Patch the skill immediately if the issue is reusable.
+4. Re-run the skill validator.
+
+## Reference
+
+For the longer protocol and checkpoint template, read:
+
+```text
+.agents/skills/stage-iterate/references/stage-iteration-protocol.md
+```
diff --git a/.agents/skills/stage-iterate/agents/openai.yaml b/.agents/skills/stage-iterate/agents/openai.yaml
new file mode 100644
index 000000000..f4dcde57a
--- /dev/null
+++ b/.agents/skills/stage-iterate/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Stage Iterate"
+  short_description: "Run staged implementation with alignment gates and checkpoints."
+  default_prompt: "Execute this stage iteratively with Trellis, cc-haha alignment, LangChain guard, tests, and a checkpoint before continuing."
diff --git a/.agents/skills/stage-iterate/references/stage-iteration-protocol.md b/.agents/skills/stage-iterate/references/stage-iteration-protocol.md
new file mode 100644
index 000000000..e89256ed5
--- /dev/null
+++ b/.agents/skills/stage-iterate/references/stage-iteration-protocol.md
@@ -0,0 +1,152 @@
+# Stage Iteration Protocol
+
+Use this protocol when a user asks Codex to work through a multi-stage roadmap over time.
+
+## Stage Checklist
+
+Mode choice:
+
+- [ ] Decide whether this run is `lean` or `deep`.
+- [ ] If the user did not explicitly opt into long-running autopilot, default to `lean`.
+
+Before implementation:
+
+- [ ] A Trellis task exists.
+- [ ] A PRD exists.
+- [ ] Relevant cc-haha source files are named.
+- [ ] Expected benefit is concrete.
+- [ ] LangChain-native primitive is chosen.
+- [ ] Out-of-scope list is explicit.
+- [ ] Tests are named.
+- [ ] If subagents are used, each subagent has a concrete non-overlapping task.
+- [ ] A current sub-stage state is recorded (`planning` / `implementing` / `verifying` / `checkpoint` / `terminal`).
+
+During implementation:
+
+- [ ] Keep each sub-stage small.
+- [ ] Do not implement future sub-stages opportunistically.
+- [ ] In `lean` mode, do not re-read large settled source/doc context without a real ambiguity.
+- [ ] Do not add wrappers or framework layers without a real boundary.
+- [ ] Preserve existing user changes in dirty worktrees.
+- [ ] Keep delegated work off the immediate critical path unless the main agent is blocked.
+- [ ] Assign disjoint file ownership to worker subagents.
+
+After implementation:
+
+- [ ] Run focused tests.
+- [ ] Run lint/typecheck where appropriate.
+- [ ] In `lean` mode, avoid full-suite validation unless there is a concrete reason.
+- [ ] Update planning docs/status if architecture-visible behavior changed.
+- [ ] Run the checkpoint gate before moving on.
+
+## OMX-Derived Improvements
+
+These patterns are adapted from prior OMX-style long-running workflows:
+
+1. **Resume current active state**
+   If a stage family is already active, continue from the current sub-stage instead of re-running orientation from zero.
+2. **Terminal verdict vocabulary**
+   Use an internal verdict of `APPROVE`, `ITERATE`, or `REJECT` at checkpoints.
+   Map them to stage decisions:
+   - `APPROVE` → `continue`
+   - `ITERATE` → `adjust` or `split`
+   - `REJECT` → `stop`
+3. **Stage ledger**
+   Keep a compact ledger of sub-stage checkpoints so long-running work can resume from verified state.
+4. **Long-run continuity**
+   Do not stop merely to summarize progress when the checkpoint result is `continue`.
+5. **Role-shaped side work**
+   Use bounded side agents for research, review, or test audit, but keep final synthesis in the main agent.
+
+## Subagent Delegation Template
+
+Use this shape when delegating a subtask:
+
+```text
+You are working in a shared codebase. Do not revert changes you did not make.
+Task: <bounded task>
+Ownership: <paths/modules the worker owns>
+Do not edit: <paths/modules outside ownership>
+Output: final answer must include changed files, key decisions, and verification run.
+```
+
+## Checkpoint Template
+
+```markdown
+## Checkpoint: <sub-stage>
+
+State:
+- planning | implementing | verifying | checkpoint | terminal
+
+Verdict:
+- APPROVE | ITERATE | REJECT
+
+Implemented:
+- ...
+
+Verification:
+- ...
+
+cc-haha alignment:
+- Source files inspected:
+- Aligned:
+- Deferred:
+- Do-not-copy:
+
+LangChain architecture:
+- Primitive used:
+- Why no heavier abstraction:
+
+Boundary findings:
+- New issue:
+- Impact on next stage:
+
+Decision:
+- continue | adjust | split | stop
+
+Reason:
+- ...
+```
+
+## Autopilot Rule
+
+If a checkpoint result is `continue`, do not pause for a user approval summary.
+
+Instead:
+
+1. record the checkpoint in the active task or planning notes
+2. update the next sub-stage task/PRD if needed
+3. immediately start the next sub-stage
+
+Only stop the staged run when the checkpoint result is `adjust`, `split`, or `stop`, or when a real blocker appears.
+
+`lean` mode note:
+
+If the run is `lean`, a `continue` checkpoint still starts the next sub-stage automatically.
+
+The restriction is not on progression, but on cost:
+
+1. reuse existing planning/source context whenever safe
+2. prefer focused validation
+3. avoid broad docs/git/PR work unless explicitly requested or clearly required
+
+## Stop Conditions
+
+Stop and ask the user when:
+
+- the next stage's scope is no longer true
+- tests are failing and the fix is not local to the current sub-stage
+- a cc-haha behavior needs a source mapping that has not been done
+- the implementation would require replacing LangChain/LangGraph runtime seams
+- the worktree contains conflicting changes that were not made by Codex
+- the next step would require a new product decision
+
+## Self-Improvement Triggers
+
+Update this skill when:
+
+- a checkpoint missed a real risk
+- the skill allowed scope creep
+- a recurring alignment step was forgotten
+- a future stage required information that should have been captured earlier
+- the user had to restate the same process rule
diff --git a/.agents/skills/start/SKILL.md b/.agents/skills/start/SKILL.md
new file mode 100644
index 000000000..0adfc87b0
--- /dev/null
+++ b/.agents/skills/start/SKILL.md
@@ -0,0 +1,346 @@
+---
+name: start
+description: "Start Session"
+---
+
+# Start Session
+
+Initialize your AI development session and begin working on tasks.
+
+---
+
+## Operation Types
+
+| Marker | Meaning | Executor |
+|--------|---------|----------|
+| `[AI]` | Bash scripts or tool calls executed by AI | You (AI) |
+| `[USER]` | Skills executed by user | User |
+
+---
+
+## Initialization `[AI]`
+
+### Step 1: Understand Development Workflow
+
+First, read the workflow guide to understand the development process:
+
+```bash
+cat .trellis/workflow.md
+```
+
+**Follow the instructions in workflow.md** - it contains:
+- Core principles (Read Before Write, Follow Standards, etc.)
+- File system structure
+- Development process
+- Best practices
+
+### Step 2: Get Current Context
+
+```bash
+python3 ./.trellis/scripts/get_context.py
+```
+
+This shows: developer identity, git status, current task (if any), active tasks.
+
+### Step 3: Read Guidelines Index
+
+```bash
+cat .trellis/spec/frontend/index.md  # Frontend guidelines
+cat .trellis/spec/backend/index.md   # Backend guidelines
+cat .trellis/spec/guides/index.md    # Thinking guides
+```
+
+> **Important**: The index files are navigation — they list the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`).
+> At this step, just read the indexes to understand what's available.
+> When you start actual development, you MUST go back and read the specific guideline files relevant to your task, as listed in the index's Pre-Development Checklist.
+
+### Step 4: Report and Ask
+
+Report what you learned and ask: "What would you like to work on?"
+
+---
+
+## Task Classification
+
+When user describes a task, classify it:
+
+| Type | Criteria | Workflow |
+|------|----------|----------|
+| **Question** | User asks about code, architecture, or how something works | Answer directly |
+| **Trivial Fix** | Typo fix, comment update, single-line change, < 5 minutes | Direct Edit |
+| **Simple Task** | Clear goal, 1-2 files, well-defined scope | Quick confirm → Task Workflow |
+| **Complex Task** | Vague goal, multiple files, architectural decisions | **Brainstorm → Task Workflow** |
+
+### Decision Rule
+
+> **If in doubt, use Brainstorm + Task Workflow.**
+>
+> Task Workflow ensures code-specs are injected to the right context, resulting in higher quality code.
+> The overhead is minimal, but the benefit is significant.
+
+> **Subtask Decomposition**: If brainstorm reveals multiple independent work items,
+> consider creating subtasks using `--parent` flag or `add-subtask` command.
+> See the brainstorm skill's Step 8 for details.
+
+---
+
+## Question / Trivial Fix
+
+For questions or trivial fixes, work directly:
+
+1. Answer question or make the fix
+2. If code was changed, remind user to run `$finish-work`
+
+---
+
+## Simple Task
+
+For simple, well-defined tasks:
+
+1. Quick confirm: "I understand you want to [goal]. Shall I proceed?"
+2. If no, clarify and confirm again
+3. **If yes: execute ALL steps below without stopping. Do NOT ask for additional confirmation between steps.**
+   - Create task directory (Phase 1 Path B, Step 2)
+   - Write PRD (Step 3)
+   - Research codebase (Phase 2, Step 5)
+   - Configure context (Step 6)
+   - Activate task (Step 7)
+   - Implement (Phase 3, Step 8)
+   - Check quality (Step 9)
+   - Complete (Step 10)
+
+---
+
+## Complex Task - Brainstorm First
+
+For complex or vague tasks, **automatically start the brainstorm process** — do NOT skip directly to implementation.
+
+See `$brainstorm` for the full process. Summary:
+
+1. **Acknowledge and classify** - State your understanding
+2. **Create task directory** - Track evolving requirements in `prd.md`
+3. **Ask questions one at a time** - Update PRD after each answer
+4. **Propose approaches** - For architectural decisions
+5. **Confirm final requirements** - Get explicit approval
+6. **Proceed to Task Workflow** - With clear requirements in PRD
+
+---
+
+## Task Workflow (Development Tasks)
+
+**Why this workflow?**
+- Run a dedicated research pass before coding
+- Configure specs in jsonl context files
+- Implement using injected context
+- Verify with a separate check pass
+- Result: Code that follows project conventions automatically
+
+### Overview: Two Entry Points
+
+```
+From Brainstorm (Complex Task):
+  PRD confirmed → Research → Configure Context → Activate → Implement → Check → Complete
+
+From Simple Task:
+  Confirm → Create Task → Write PRD → Research → Configure Context → Activate → Implement → Check → Complete
+```
+
+**Key principle: Research happens AFTER requirements are clear (PRD exists).**
+
+---
+
+### Phase 1: Establish Requirements
+
+#### Path A: From Brainstorm (skip to Phase 2)
+
+PRD and task directory already exist from brainstorm. Skip directly to Phase 2.
+
+#### Path B: From Simple Task
+
+**Step 1: Confirm Understanding** `[AI]`
+
+Quick confirm:
+- What is the goal?
+- What type of development? (frontend / backend / fullstack)
+- Any specific requirements or constraints?
+
+If unclear, ask clarifying questions.
+
+**Step 2: Create Task Directory** `[AI]`
+
+```bash
+TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<title>" --slug <name>)
+```
+
+**Step 3: Write PRD** `[AI]`
+
+Create `prd.md` in the task directory with:
+
+```markdown
+# <Task Title>
+
+## Goal
+<What we're trying to achieve>
+
+## Requirements
+- <Requirement 1>
+- <Requirement 2>
+
+## Acceptance Criteria
+- [ ] <Criterion 1>
+- [ ] <Criterion 2>
+
+## Technical Notes
+<Any technical decisions or constraints>
+```
+
+---
+
+### Phase 2: Prepare for Implementation (shared)
+
+> Both paths converge here. PRD and task directory must exist before proceeding.
+
+**Step 4: Code-Spec Depth Check** `[AI]`
+
+If the task touches infra or cross-layer contracts, do not start implementation until code-spec depth is defined.
+
+Trigger this requirement when the change includes any of:
+- New or changed command/API signatures
+- Database schema or migration changes
+- Infra integrations (storage, queue, cache, secrets, env contracts)
+- Cross-layer payload transformations
+
+Must-have before proceeding:
+- [ ] Target code-spec files to update are identified
+- [ ] Concrete contract is defined (signature, fields, env keys)
+- [ ] Validation and error matrix is defined
+- [ ] At least one Good/Base/Bad case is defined
+
+**Step 5: Research the Codebase** `[AI]`
+
+Based on the confirmed PRD, run a focused research pass and produce:
+
+1. Relevant spec files in `.trellis/spec/`
+2. Existing code patterns to follow (2-3 examples)
+3. Files that will likely need modification
+
+Use this output format:
+
+```markdown
+## Relevant Specs
+- <path>: <why it's relevant>
+
+## Code Patterns Found
+- <pattern>: <example file path>
+
+## Files to Modify
+- <path>: <what change>
+```
+
+**Step 6: Configure Context** `[AI]`
+
+Initialize default context:
+
+```bash
+python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <type>
+# type: backend | frontend | fullstack
+```
+
+Add specs found in your research pass:
+
+```bash
+# For each relevant spec and code pattern:
+python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<reason>"
+python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>"
+```
+
+**Step 7: Activate Task** `[AI]`
+
+```bash
+python3 ./.trellis/scripts/task.py start "$TASK_DIR"
+```
+
+This sets `.current-task` so hooks can inject context.
+
+---
+
+### Phase 3: Execute (shared)
+
+**Step 8: Implement** `[AI]`
+
+Implement the task described in `prd.md`.
+
+- Follow all specs injected into implement context
+- Keep changes scoped to requirements
+- Run lint and typecheck before finishing
+
+**Step 9: Check Quality** `[AI]`
+
+Run a quality pass against check context:
+
+- Review all code changes against the specs
+- Fix issues directly
+- Ensure lint and typecheck pass
+
+**Step 10: Complete** `[AI]`
+
+1. Verify lint and typecheck pass
+2. Report what was implemented
+3. Remind user to:
+   - Test the changes
+   - Commit when ready
+   - Run `$record-session` to record this session
+
+---
+
+## Continuing Existing Task
+
+If `get_context.py` shows a current task:
+
+1. Read the task's `prd.md` to understand the goal
+2. Check `task.json` for current status and phase
+3. Ask user: "Continue working on <task-name>?"
+
+If yes, resume from the appropriate step (usually Step 7 or 8).
+
+---
+
+## Skills Reference
+
+### User Skills `[USER]`
+
+| Skill | When to Use |
+|---------|-------------|
+| `$start` | Begin a session (this skill) |
+| `$finish-work` | Before committing changes |
+| `$record-session` | After completing a task |
+
+### AI Scripts `[AI]`
+
+| Script | Purpose |
+|--------|---------|
+| `python3 ./.trellis/scripts/get_context.py` | Get session context |
+| `python3 ./.trellis/scripts/task.py create` | Create task directory |
+| `python3 ./.trellis/scripts/task.py init-context` | Initialize jsonl files |
+| `python3 ./.trellis/scripts/task.py add-context` | Add spec to jsonl |
+| `python3 ./.trellis/scripts/task.py start` | Set current task |
+| `python3 ./.trellis/scripts/task.py finish` | Clear current task |
+| `python3 ./.trellis/scripts/task.py archive` | Archive completed task |
+
+### Workflow Phases `[AI]`
+
+| Phase | Purpose | Context Source |
+|-------|---------|----------------|
+| research | Analyze codebase | direct repo inspection |
+| implement | Write code | `implement.jsonl` |
+| check | Review & fix | `check.jsonl` |
+| debug | Fix specific issues | `debug.jsonl` |
+
+---
+
+## Key Principle
+
+> **Code-spec context is injected, not remembered.**
+>
+> The Task Workflow ensures agents receive relevant code-spec context automatically.
+> This is more reliable than hoping the AI "remembers" conventions.
diff --git a/.agents/skills/update-spec/SKILL.md b/.agents/skills/update-spec/SKILL.md
new file mode 100644
index 000000000..435327b22
--- /dev/null
+++ b/.agents/skills/update-spec/SKILL.md
@@ -0,0 +1,335 @@
+---
+name: update-spec
+description: "Update Code-Spec - Capture Executable Contracts"
+---
+
+# Update Code-Spec - Capture Executable Contracts
+
+When you learn something valuable (from debugging, implementing, or discussion), use this skill to update the relevant code-spec documents.
+
+**Timing**: After completing a task, fixing a bug, or discovering a new pattern
+
+---
+
+## Code-Spec First Rule (CRITICAL)
+
+In this project, "spec" for implementation work means **code-spec**:
+- Executable contracts (not principle-only text)
+- Concrete signatures, payload fields, env keys, and boundary behavior
+- Testable validation/error behavior
+
+If the change touches infra or cross-layer contracts, code-spec depth is mandatory.
+
+Required sections for infra/cross-layer specs:
+1. Scope / Trigger
+2. Signatures (command/API/DB)
+3. Contracts (request/response/env)
+4. Validation & Error Matrix
+5. Good/Base/Bad Cases
+6. Tests Required (with assertion points)
+7. Wrong vs Correct (at least one pair)
+
+---
+
+## When to Update Code-Specs
+
+| Trigger | Example | Target Spec |
+|---------|---------|-------------|
+| **Implemented a feature** | Added template download with giget | Relevant `backend/` or `frontend/` file |
+| **Made a design decision** | Used type field + mapping table for extensibility | Relevant code-spec + "Design Decisions" section |
+| **Fixed a bug** | Found a subtle issue with error handling | `backend/error-handling.md` |
+| **Discovered a pattern** | Found a better way to structure code | Relevant `backend/` or `frontend/` file |
+| **Hit a gotcha** | Learned that X must be done before Y | Relevant code-spec + "Common Mistakes" section |
+| **Established a convention** | Team agreed on naming pattern | `quality-guidelines.md` |
+| **New thinking trigger** | "Don't forget to check X before doing Y" | `guides/*.md` (as a checklist item, not detailed rules) |
+
+**Key Insight**: Code-spec updates are NOT just for problems. Every feature implementation contains design decisions and contracts that future AI/developers need to execute safely.
+
+---
+
+## Spec Structure Overview
+
+```
+.trellis/spec/
+├── backend/           # Backend coding standards
+│   ├── index.md       # Overview and links
+│   └── *.md           # Topic-specific guidelines
+├── frontend/          # Frontend coding standards
+│   ├── index.md       # Overview and links
+│   └── *.md           # Topic-specific guidelines
+└── guides/            # Thinking checklists (NOT coding specs!)
+    ├── index.md       # Guide index
+    └── *.md           # Topic-specific guides
+```
+
+### CRITICAL: Code-Spec vs Guide - Know the Difference
+
+| Type | Location | Purpose | Content Style |
+|------|----------|---------|---------------|
+| **Code-Spec** | `backend/*.md`, `frontend/*.md` | Tell AI "how to implement safely" | Signatures, contracts, matrices, cases, test points |
+| **Guide** | `guides/*.md` | Help AI "what to think about" | Checklists, questions, pointers to specs |
+
+**Decision Rule**: Ask yourself:
+
+- "This is **how to write** the code" → Put in `backend/` or `frontend/`
+- "This is **what to consider** before writing" → Put in `guides/`
+
+**Example**:
+
+| Learning | Wrong Location | Correct Location |
+|----------|----------------|------------------|
+| "Use `reconfigure()` not `TextIOWrapper` for Windows stdout" | ❌ `guides/cross-platform-thinking-guide.md` | ✅ `backend/script-conventions.md` |
+| "Remember to check encoding when writing cross-platform code" | ❌ `backend/script-conventions.md` | ✅ `guides/cross-platform-thinking-guide.md` |
+
+**Guides should be short checklists that point to specs**, not duplicate the detailed rules.
+
+---
+
+## Update Process
+
+### Step 1: Identify What You Learned
+
+Answer these questions:
+
+1. **What did you learn?** (Be specific)
+2. **Why is it important?** (What problem does it prevent?)
+3. **Where does it belong?** (Which spec file?)
+
+### Step 2: Classify the Update Type
+
+| Type | Description | Action |
+|------|-------------|--------|
+| **Design Decision** | Why we chose approach X over Y | Add to "Design Decisions" section |
+| **Project Convention** | How we do X in this project | Add to relevant section with examples |
+| **New Pattern** | A reusable approach discovered | Add to "Patterns" section |
+| **Forbidden Pattern** | Something that causes problems | Add to "Anti-patterns" or "Don't" section |
+| **Common Mistake** | Easy-to-make error | Add to "Common Mistakes" section |
+| **Convention** | Agreed-upon standard | Add to relevant section |
+| **Gotcha** | Non-obvious behavior | Add warning callout |
+
+### Step 3: Read the Target Code-Spec
+
+Before editing, read the current code-spec to:
+- Understand existing structure
+- Avoid duplicating content
+- Find the right section for your update
+
+```bash
+cat .trellis/spec/<category>/<file>.md
+```
+
+### Step 4: Make the Update
+
+Follow these principles:
+
+1. **Be Specific**: Include concrete examples, not just abstract rules
+2. **Explain Why**: State the problem this prevents
+3. **Show Contracts**: Add signatures, payload fields, and error behavior
+4. **Show Code**: Add code snippets for key patterns
+5. **Keep it Short**: One concept per section
+
+### Step 5: Update the Index (if needed)
+
+If you added a new section or the code-spec status changed, update the category's `index.md`.
+
+---
+
+## Update Templates
+
+### Mandatory Template for Infra/Cross-Layer Work
+
+```markdown
+## Scenario: <name>
+
+### 1. Scope / Trigger
+- Trigger: <why this requires code-spec depth>
+
+### 2. Signatures
+### 3. Contracts
+### 4. Validation & Error Matrix
+### 5. Good/Base/Bad Cases
+### 6. Tests Required
+### 7. Wrong vs Correct
+#### Wrong
+...
+#### Correct
+...
+```
+
+### Adding a Design Decision
+
+```markdown
+### Design Decision: [Decision Name]
+
+**Context**: What problem were we solving?
+
+**Options Considered**:
+1. Option A - brief description
+2. Option B - brief description
+
+**Decision**: We chose Option X because...
+
+**Example**:
+\`\`\`typescript
+// How it's implemented
+code example
+\`\`\`
+
+**Extensibility**: How to extend this in the future...
+```
+
+### Adding a Project Convention
+
+```markdown
+### Convention: [Convention Name]
+
+**What**: Brief description of the convention.
+
+**Why**: Why we do it this way in this project.
+
+**Example**:
+\`\`\`typescript
+// How to follow this convention
+code example
+\`\`\`
+
+**Related**: Links to related conventions or specs.
+```
+
+### Adding a New Pattern
+
+```markdown
+### Pattern Name
+
+**Problem**: What problem does this solve?
+
+**Solution**: Brief description of the approach.
+
+**Example**:
+\`\`\`
+// Good
+code example
+
+// Bad
+code example
+\`\`\`
+
+**Why**: Explanation of why this works better.
+```
+
+### Adding a Forbidden Pattern
+
+```markdown
+### Don't: Pattern Name
+
+**Problem**:
+\`\`\`
+// Don't do this
+bad code example
+\`\`\`
+
+**Why it's bad**: Explanation of the issue.
+
+**Instead**:
+\`\`\`
+// Do this instead
+good code example
+\`\`\`
+```
+
+### Adding a Common Mistake
+
+```markdown
+### Common Mistake: Description
+
+**Symptom**: What goes wrong
+
+**Cause**: Why this happens
+
+**Fix**: How to correct it
+
+**Prevention**: How to avoid it in the future
+```
+
+### Adding a Gotcha
+
+```markdown
+> **Warning**: Brief description of the non-obvious behavior.
+>
+> Details about when this happens and how to handle it.
+```
+
+---
+
+## Interactive Mode
+
+If you're unsure what to update, answer these prompts:
+
+1. **What did you just finish?**
+   - [ ] Fixed a bug
+   - [ ] Implemented a feature
+   - [ ] Refactored code
+   - [ ] Had a discussion about approach
+
+2. **What did you learn or decide?**
+   - Design decision (why X over Y)
+   - Project convention (how we do X)
+   - Non-obvious behavior (gotcha)
+   - Better approach (pattern)
+
+3. **Would future AI/developers need to know this?**
+   - To understand how the code works → Yes, update spec
+   - To maintain or extend the feature → Yes, update spec
+   - To avoid repeating mistakes → Yes, update spec
+   - Purely one-off implementation detail → Maybe skip
+
+4. **Which area does it relate to?**
+   - [ ] Backend code
+   - [ ] Frontend code
+   - [ ] Cross-layer data flow
+   - [ ] Code organization/reuse
+   - [ ] Quality/testing
+
+---
+
+## Quality Checklist
+
+Before finishing your code-spec update:
+
+- [ ] Is the content specific and actionable?
+- [ ] Did you include a code example?
+- [ ] Did you explain WHY, not just WHAT?
+- [ ] Did you include executable signatures/contracts?
+- [ ] Did you include validation and error matrix?
+- [ ] Did you include Good/Base/Bad cases?
+- [ ] Did you include required tests with assertion points?
+- [ ] Is it in the right code-spec file?
+- [ ] Does it duplicate existing content?
+- [ ] Would a new team member understand it?
+
+---
+
+## Relationship to Other Commands
+
+```
+Development Flow:
+  Learn something → $update-spec → Knowledge captured
+       ↑                                  ↓
+  $break-loop ←──────────────────── Future sessions benefit
+  (deep bug analysis)
+```
+
+- `$break-loop` - Analyzes bugs deeply, often reveals spec updates needed
+- `$update-spec` - Actually makes the updates (this skill)
+- `$finish-work` - Reminds you to check if specs need updates
+
+---
+
+## Core Philosophy
+
+> **Code-specs are living documents. Every debugging session, every "aha moment" is an opportunity to make the implementation contract clearer.**
+
+The goal is **institutional memory**:
+- What one person learns, everyone benefits from
+- What AI learns in one session, persists to future sessions
+- Mistakes become documented guardrails
diff --git a/.env.example b/.env.example
index 7cb430627..93d483c69 100644
--- a/.env.example
+++ b/.env.example
@@ -5,9 +5,34 @@ ANTHROPIC_API_KEY=sk-ant-xxx
 # Model ID (required)
 MODEL_ID=claude-sonnet-4-6
 
+# Deep Agents / OpenAI-interface track (agents_deepagents/s01-s11)
+# OPENAI_API_KEY is required only when running agents_deepagents/*.py.
+OPENAI_API_KEY=sk-openai-xxx
+# OPENAI_MODEL is preferred by the Deep Agents track; MODEL_ID is fallback only.
+OPENAI_MODEL=gpt-4.1-mini
+# Optional OpenAI-compatible endpoint.
+# OPENAI_BASE_URL=https://api.openai.com/v1
+
 # Base URL (optional, for Anthropic-compatible providers)
 # ANTHROPIC_BASE_URL=https://api.anthropic.com
 
+
+# =============================================================================
+#  Deep Agents OpenAI-interface track (agents_deepagents/s01-s11)
+#
+#  Required when running the Deep Agents demos manually. Automated tests do not
+#  require this key and do not call a live model.
+# =============================================================================
+# OPENAI_API_KEY=sk-xxx
+# OPENAI_MODEL=gpt-5
+# Optional for OpenAI-compatible endpoints:
+# OPENAI_BASE_URL=https://api.openai.com/v1
+#
+# Model precedence for agents_deepagents/:
+# 1. OPENAI_MODEL
+# 2. MODEL_ID only when it does not look like an Anthropic model (not claude-*)
+# 3. gpt-5
+
 # =============================================================================
 #  Anthropic-compatible providers
 #
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index c6f70e1c0..d6ac3c569 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -18,10 +18,18 @@ jobs:
           python-version: "3.11"
 
       - name: Install dependencies
-        run: pip install anthropic python-dotenv pytest
+        run: pip install -r requirements.txt pytest
 
       - name: Run Python smoke tests
-        run: python -m pytest tests/test_agents_smoke.py -q
+        run: >-
+          python -m pytest
+          tests/test_agents_smoke.py
+          tests/test_agents_baseline_contract.py
+          tests/test_deepagents_track_smoke.py tests/test_deepagents_control_plane.py
+          tests/test_deepagents_gating_spike.py
+          tests/test_provider_safety.py
+          tests/test_stage_track_capability_contract.py
+          -q
 
   web-build:
     runs-on: ubuntu-latest
diff --git a/.gitignore b/.gitignore
index 1870173af..5ebb463f7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -225,3 +225,4 @@ test_providers.py
 # Internal analysis artifacts (not learning material)
 analysis/
 analysis_progress.md
+.omx/
diff --git a/.trellis/.gitignore b/.trellis/.gitignore
new file mode 100644
index 000000000..46135ba06
--- /dev/null
+++ b/.trellis/.gitignore
@@ -0,0 +1,29 @@
+# Developer identity (local only)
+.developer
+
+# Current task pointer (each dev works on different task)
+.current-task
+
+# Ralph Loop state file
+.ralph-state.json
+
+# Agent runtime files
+.agents/
+.agent-log
+.session-id
+
+# Task directory runtime files
+.plan-log
+
+# Atomic update temp files
+*.tmp
+
+# Update backup directories
+.backup-*
+
+# Conflict resolution temp files
+*.new
+
+# Python cache
+**/__pycache__/
+**/*.pyc
diff --git a/.trellis/.template-hashes.json b/.trellis/.template-hashes.json
new file mode 100644
index 000000000..06ba90524
--- /dev/null
+++ b/.trellis/.template-hashes.json
@@ -0,0 +1,42 @@
+{
+  ".trellis/config.yaml": "fe1fba0961e589c6f49190f5e19d4edb0d5bf894dba8468f06882c6e1c5e2aa1",
+  ".trellis/scripts/__init__.py": "1242be5b972094c2e141aecbe81a4efd478f6534e3d5e28306374e6a18fcf46c",
+  ".trellis/scripts/add_session.py": "7c869be8146e6f675bd95e424909ff301ea0a8f8fd82a4f056f6d320e755a406",
+  ".trellis/scripts/common/__init__.py": "301724230abcce6e9fc99054c12d21c30eea7bc3b330ae6350aa3b6158461273",
+  ".trellis/scripts/common/cli_adapter.py": "66ef4f75470807b531490a6b6928604eb59781148fe3c5412f39e132ffab0850",
+  ".trellis/scripts/common/config.py": "909257b442d7d1e7a2596996622c4f2f010d8c1343e1efd088ef8615d99554c7",
+  ".trellis/scripts/common/developer.py": "69f6145c4c48953677de3ba06f487ba2a1675f4d66153346ab40594bb06a01c9",
+  ".trellis/scripts/common/git_context.py": "f154d358c858f7bcfc21a03c9b909af3a8dfa20be37b2c5012d84b8e0588b493",
+  ".trellis/scripts/common/paths.py": "058f333fb80c71c90ddc131742e8e64949c2f1ed07c1254d8f7232506d891ffc",
+  ".trellis/scripts/common/phase.py": "f9bdd553c7a278b97736b04c066ed06d8baa2ef179ed8219befcf6c27afcc9cd",
+  ".trellis/scripts/common/registry.py": "6c65db45a487ef839b0a4b5b20abe201547269c20c7257254293a89dc01b56dc",
+  ".trellis/scripts/common/task_queue.py": "6de22c7731465ee52d2b5cd4853b191d3cf869bf259fbc93079b426ba1c3756c",
+  ".trellis/scripts/common/task_utils.py": "e19c290d90f9a779db161aeb9fefda27852847fbc67d358d471530b8ede64131",
+  ".trellis/scripts/common/worktree.py": "434880e02dfa2e92f0c717ed2a28e4cdee681ea10c329a2438d533bdbc612408",
+  ".trellis/scripts/create_bootstrap.py": "aa5dd1f39a77b2f4bb827fd14ce7a83fb51870e77f556fe508afce3f8eac0b4e",
+  ".trellis/scripts/get_context.py": "ca5bf9e90bdb1d75d3de182b95f820f9d108ab28793d29097b24fd71315adcf5",
+  ".trellis/scripts/get_developer.py": "84c27076323c3e0f2c9c8ed16e8aa865e225d902a187c37e20ee1a46e7142d8f",
+  ".trellis/scripts/init_developer.py": "f9e6c0d882406e81c8cd6b1c5abb204b0befc0069ff89cf650cd536a80f8c60e",
+  ".trellis/scripts/multi_agent/__init__.py": "af6fceb4d9a64da04be03ba0f5a6daf71066503eca832b8b58d8a7d4b2844fa4",
+  ".trellis/scripts/multi_agent/cleanup.py": "db50c4fbb32261905a8278c2760b33029f187963cd4e448938e57f3db3facd6c",
+  ".trellis/scripts/multi_agent/create_pr.py": "6a2423aba5720a2150c32349faa957cdc59c6bb96511e56c79ca08d92d69c666",
+  ".trellis/scripts/multi_agent/plan.py": "242b870b7667f730c910d629f16d44d5d3fd0a58f6451d9003c175fb2e77cee5",
+  ".trellis/scripts/multi_agent/start.py": "32ed1a13405b7c71881b2507a79e1a3733bc3fcedbc92fcee0d733ce00d759d0",
+  ".trellis/scripts/multi_agent/status.py": "5fc46b6d605c69b6044967a6b33ffb0c9d6f99dd919374572ac614222864a811",
+  ".trellis/scripts/task.py": "ecf52885a698dc93af67fd693825a2f71163ab86b5c2abe76d8aa2e2caa44372",
+  ".trellis/workflow.md": "9b6d6e8027bd2cf32d9efd7ef77d6524c59fcaa4ad6052f72d028a07a5fd69a7",
+  ".trellis/worktree.yaml": "c57de79e40d5f748f099625ed4a17d5f0afbf25cac598aced0b3c964e7b7c226",
+  ".agents/skills/before-backend-dev/SKILL.md": "4537ccee0071353beee636a052c01642a27a87b6b0a73e7bc872b2501547fa64",
+  ".agents/skills/before-frontend-dev/SKILL.md": "679c1708a4d9fbad5214db299a38366581684a9383cf51a5d8ac21f890d6ba0d",
+  ".agents/skills/brainstorm/SKILL.md": "0cabc8e663a871dee6c8bbf7f149fe10f83f39835e66ad0a8d0867049aacb6f8",
+  ".agents/skills/break-loop/SKILL.md": "b19a47854ca66bde4ee03a30603480b4af2c131d5d81d752d1d28d2ef5131172",
+  ".agents/skills/check-backend/SKILL.md": "9b312cfd7a07ed036769b387d84d642cd5e20f06b88e7b6a4626705fa8beb6fa",
+  ".agents/skills/check-cross-layer/SKILL.md": "bc72df11d79a8ee809f45eae120c1cce91ab997541ce30d665af9978c83843f6",
+  ".agents/skills/check-frontend/SKILL.md": "27b75f9eea472ed104f39a65bb78ae559cfe8730c85e0742e55fd575a4a2f854",
+  ".agents/skills/create-command/SKILL.md": "5c24ca19c1cec64486f1a147e1dd4a37200270cbf3d0987dc6536f7de85a78f2",
+  ".agents/skills/finish-work/SKILL.md": "f3f77e3902021bb7d95452a6072ae3f67993bf7b7d0e172e33756a633b654bf2",
+  ".agents/skills/integrate-skill/SKILL.md": "47b7374345d8a31f9df07c5e8e875ca4fdc30d0cc45860d77df893250e2d97fc",
+  ".agents/skills/onboard/SKILL.md": "1808f578d21eae3cbcf650d6aa4cf35ac42bf466df740b830593c9bda212d51a",
+  ".agents/skills/record-session/SKILL.md": "ce27e953630a71ef989c5582790e9c8a600a2614ec668b674816c1daac73ce0a",
+  ".agents/skills/start/SKILL.md": "788e517f9e57c4ce68497c1cefabd51faa8253c681be7965915f21e6de9c5886"
+}
\ No newline at end of file
diff --git a/.trellis/.version b/.trellis/.version
new file mode 100644
index 000000000..81de5c57f
--- /dev/null
+++ b/.trellis/.version
@@ -0,0 +1 @@
+0.3.10
\ No newline at end of file
diff --git a/.trellis/config.yaml b/.trellis/config.yaml
new file mode 100644
index 000000000..7d18551b5
--- /dev/null
+++ b/.trellis/config.yaml
@@ -0,0 +1,33 @@
+# Trellis Configuration
+# Project-level settings for the Trellis workflow system
+#
+# All values have sensible defaults. Only override what you need.
+
+#-------------------------------------------------------------------------------
+# Session Recording
+#-------------------------------------------------------------------------------
+
+# Commit message used when auto-committing journal/index changes
+# after running add_session.py
+session_commit_message: "chore: record journal"
+
+# Maximum lines per journal file before rotating to a new one
+max_journal_lines: 2000
+
+#-------------------------------------------------------------------------------
+# Task Lifecycle Hooks
+#-------------------------------------------------------------------------------
+
+# Shell commands to run after task lifecycle events.
+# Each hook receives TASK_JSON_PATH environment variable pointing to task.json.
+# Hook failures print a warning but do not block the main operation.
+#
+# hooks:
+#   after_create:
+#     - "echo 'Task created'"
+#   after_start:
+#     - "echo 'Task started'"
+#   after_finish:
+#     - "echo 'Task finished'"
+#   after_archive:
+#     - "echo 'Task archived'"
diff --git a/.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md b/.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md
new file mode 100644
index 000000000..fc7578be5
--- /dev/null
+++ b/.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md
@@ -0,0 +1,231 @@
+<!-- Created on 2026-04-14 during Trellis brainstorm for redefining coding-deepgent final goal. -->
+# coding-deepgent CC Core Highlights Roadmap
+
+Status: active canonical dashboard
+Scope: `coding-deepgent/` product track only
+Evidence policy: every highlight must be source-backed against `/root/claude-code-haha` before implementation
+
+## Purpose
+
+This document replaces a slow per-system approval loop with a source-backed highlight backlog.
+
+The user does not want to review every low-level design item one by one. The working mode is:
+
+1. Maintain a prioritized list of cc-haha core highlights.
+2. For each highlight, inspect the relevant cc-haha source deeply before implementation.
+3. State the concrete function and the concrete benefit before proposing or making code changes.
+4. Translate the functional essence into LangChain/LangGraph-native architecture.
+5. Defer or reject cc product details that do not create a concrete local effect.
+
+## Global Target
+
+`coding-deepgent` should become a professional LangChain-native implementation of Claude Code / cc-haha Agent Harness essence.
+
+It should not become:
+
+- a line-by-line cc-haha clone
+- a UI/TUI clone
+- a tutorial-only demo
+- a custom runtime that bypasses LangChain/LangGraph
+
+## Highlight Planning Rules
+
+Every highlight must include:
+
+- Function: what concrete capability or behavior changes for the user/runtime.
+- Benefit: user-visible, agent-runtime, safety, reliability, context-efficiency, maintainability, testability, product parity, or observability.
+- Source evidence: exact cc-haha files and symbols inspected.
+- LangChain expression: official primitive first.
+- Architecture shape: product-local modules and boundaries.
+- Complexity judgment: why now, why later, or do not copy.
+- Verification: local tests or review checks that prove behavior.
+- Cross-session memory impact: direct, indirect, or none.
+
+## Canonical MVP Boundary
+
+Chosen finish-line scope: `Approach A: MVP Local Agent Harness Core`
+
+Included in MVP:
+
+* H01-H11
+* H15-H19
+* H12 minimal local slice only
+* H20 minimal local slice only
+
+Explicitly not in MVP:
+
+* H13 Mailbox / SendMessage runtime
+* H14 Coordinator runtime
+* H21 Bridge / remote / IDE control plane
+* H22 Daemon / cron / proactive automation
+
+Stop rule:
+
+* MVP is complete only when every H01-H22 row below has an explicit status.
+* Every MVP-included row must be `implemented` or an explicitly accepted `partial`
+  with tests/contracts backing the minimal boundary.
+* Every non-MVP row must be `deferred` or `do-not-copy`.
+* No new stage is valid unless it maps to an existing H row and states a concrete
+  benefit.
+
+Status vocabulary:
+
+* `implemented`: sufficient for MVP unless a later audit finds a concrete gap
+* `partial`: useful implementation exists, but a source-backed MVP closeout stage remains
+* `missing`: should be in MVP, but not implemented enough yet
+* `deferred`: valid future work, outside current MVP
+* `do-not-copy`: not a local product goal or wrong abstraction
+
+## Canonical Dashboard
+
+This table is the canonical progress view for the MVP. Update this table when a
+stage checkpoint materially changes a row.
+
+| ID | Highlight | Current status | MVP boundary | Main modules | Next / remaining stage |
+|---|---|---|---|---|---|
+| H01 | Tool-first capability runtime | implemented | strict tool schemas, capability metadata, guarded execution for all model-facing capabilities | `tool_system`, domain `tools.py` | closed in Stage 21; keep only regression/audit follow-up |
+| H02 | Permission runtime and hard safety | implemented | deterministic local policy, safe defaults, trusted dirs, explicit deny/ask behavior | `permissions`, `tool_system`, `filesystem`, `hooks` | closed in Stage 21; keep only regression/audit follow-up |
+| H03 | Layered prompt contract | implemented | stable base prompt plus structured dynamic context; no giant tool manual | `prompting`, `runtime`, `memory`, `compact` | closed in Stage 22; keep only regression/audit follow-up |
+| H04 | Dynamic context protocol | implemented | typed/bounded context payload assembly across recovery, memory, todo, and compact flows; skills/resources deferred | `runtime`, `sessions`, `memory`, `compact` | closed in Stage 22 with explicit MVP boundary |
+| H05 | Progressive context pressure management | implemented | deterministic projection, compact records, latest valid compact selection, tool-result invariants | `compact`, `sessions`, `runtime` | closed in Stage 23; keep only regression/audit follow-up |
+| H06 | Session transcript, evidence, and resume | implemented | JSONL session store, evidence, compacts, recovery brief, compacted resume continuity | `sessions`, `runtime`, `cli_service` | closed in Stage 23; evidence CLI remains optional enhancement |
+| H07 | Scoped cross-session memory | implemented | controlled namespace-scoped save/recall with quality policy; no knowledge dumping | `memory`, `runtime`, `sessions` | closed in Stage 24; richer session/agent memory runtime deferred |
+| H08 | TodoWrite short-term planning contract | implemented | strict TodoWrite state contract, separate from durable Task | `todo`, `runtime`, `prompting` | closed in Stage 25 |
+| H09 | Durable Task graph | implemented | validated graph, readiness, plan artifacts, verification nudge | `tasks`, `tool_system` | closed in Stage 25 |
+| H10 | Plan / Execute / Verify workflow discipline | implemented | explicit plan artifact, verifier child execution, persisted verifier evidence | `tasks`, `subagents`, `sessions` | closed in Stage 25; coordinator deferred |
+| H11 | Agent as tool and runtime object | implemented | all subagents enter as tools; verifier has bounded child runtime and evidence lineage | `subagents`, `runtime`, `tasks`, `sessions` | closed in Stage 26; full agent-team lifecycle deferred |
+| H12 | Fork/cache-aware subagent execution | implemented-minimal | smallest local context/thread propagation needed by H11 only | `subagents`, `runtime`, `compact` | minimal MVP slice closed in Stage 26; rich cache parity deferred |
+| H13 | Mailbox / SendMessage | deferred | out of MVP | `tasks`, `subagents` | Stage 29 deferred-boundary ADR |
+| H14 | Coordinator keeps synthesis | deferred | out of MVP | `tasks`, `subagents`, `prompting` | Stage 29 deferred-boundary ADR |
+| H15 | Skill system packaging | implemented | local skill loader/tool and bounded context injection only | `skills`, `tool_system`, `prompting` | closed in Stage 27 |
+| H16 | MCP external capability protocol | implemented | local MCP config/loading seam, tool/resource separation, capability policy | `mcp`, `plugins`, `tool_system` | closed in Stage 27 |
+| H17 | Plugin states | implemented-minimal | local manifest/source validation only; install/enable lifecycle deferred | `plugins`, `skills`, `mcp` | local MVP closed in Stage 27; lifecycle deferred |
+| H18 | Hooks as middleware | implemented | safe lifecycle hooks through middleware boundaries, not backdoors | `hooks`, `tool_system`, `runtime` | closed in Stage 27 |
+| H19 | Observability and evidence ledger | implemented | structured local events plus session evidence and recovery visibility | `runtime`, `sessions`, `tool_system`, `subagents` | closed in Stage 28 |
+| H20 | Cost/cache instrumentation | implemented-minimal | local budget/projection/compact counters only; provider-specific cost/cache deferred | `compact`, `runtime`, `sessions` | minimal MVP slice closed in Stage 28 |
+| H21 | Bridge / remote / IDE control plane | deferred | out of MVP | future integration boundary | Stage 29 deferred-boundary ADR |
+| H22 | Daemon / cron / proactive automation | deferred | out of MVP | future scheduling boundary | Stage 29 deferred-boundary ADR |
+
+## Milestone Groups
+
+### M1: Core Audit And Closeout
+
+* Stage 21: H01/H02 tool + permission closeout
+* Stage 22: H03/H04 prompt + dynamic context closeout
+* Stage 23: H05/H06 context pressure + session continuity closeout
+* Stage 24: H07 scoped memory closeout
+* Stage 25: H08/H09/H10 todo/task/plan/verify closeout
+
+Estimate: 5 narrow stages.
+
+### M2: Agent / Evidence Minimal Runtime
+
+* Stage 26: H11 closeout with minimal H12
+* Stage 28: H19 closeout with minimal H20
+
+Estimate: 2-4 narrow stages depending on discovered gaps.
+
+### M3: Extension Platform Closeout
+
+* Stage 27: H15/H16/H17/H18 local extension platform closeout
+
+Estimate: 1-3 narrow stages depending on MCP/plugin audit findings.
+
+### M4: Explicit Deferral / Release Boundary
+
+* Stage 29: H13/H14/H21/H22 deferred-boundary ADR + MVP release checklist
+* Stage 30-36: reserve only for MVP gaps discovered by prior checkpoints
+
+Estimate: 1-3 documentation/spec stages plus reserve.
+
+## Current Priority Order
+
+### P0 Foundation Highlights
+
+These affect most later systems and should be treated as baseline architecture.
+
+| ID | Highlight | Benefit | cc-haha source to inspect deeply | LangChain-native expression | Initial decision |
+|---|---|---|---|---|---|
+| H01 | Tool-first capability runtime | safety, reliability, maintainability, product parity | `/root/claude-code-haha/src/Tool.ts`, `/root/claude-code-haha/src/services/tools/*`, `/root/claude-code-haha/src/tools/*Tool/*` | strict Pydantic `@tool`, `Command(update=...)`, `AgentMiddleware.wrap_tool_call`, capability metadata registry | Must align functionally; do not clone TS `Tool` shape |
+| H02 | Permission runtime and hard safety | safety, testability, observability | `/root/claude-code-haha/src/types/permissions.ts`, `/root/claude-code-haha/src/utils/permissions/*`, `/root/claude-code-haha/src/hooks/toolPermission/*` | deterministic policy layer, `wrap_tool_call`, `ToolMessage(status="error")`, future HITL interrupts | Must align deterministically; defer auto classifier/UI |
+| H03 | Layered prompt contract | reliability, cache-efficiency, maintainability | `/root/claude-code-haha/src/constants/prompts.ts`, `/root/claude-code-haha/src/utils/systemPrompt.ts`, `/root/claude-code-haha/src/utils/queryContext.ts`, `/root/claude-code-haha/src/context.ts` | small `PromptContext`, `system_prompt`, future `dynamic_prompt`, `context_schema` | Must align layered semantics; do not copy giant prompt |
+| H04 | Dynamic context protocol | context-efficiency, reliability | `/root/claude-code-haha/src/utils/attachments.ts`, `/root/claude-code-haha/src/utils/messages.ts`, `/root/claude-code-haha/src/utils/queryContext.ts` | context/message assembly middleware, typed context payloads, bounded render helpers | Must align principle; local protocol can be smaller |
+| H05 | Progressive context pressure management | context-efficiency, long-session continuity | `/root/claude-code-haha/src/query.ts`, `/root/claude-code-haha/src/services/compact/*`, `/root/claude-code-haha/src/utils/toolResultStorage.ts`, `/root/claude-code-haha/src/utils/messages.ts` | deterministic budget/projector helpers, later summarization middleware, state/message invariant tests | Must align staged pressure handling; avoid custom loop unless needed |
+
+### P1 Runtime Continuity Highlights
+
+These make the product useful for long professional work rather than one-shot demos.
+
+| ID | Highlight | Benefit | cc-haha source to inspect deeply | LangChain-native expression | Initial decision |
+|---|---|---|---|---|---|
+| H06 | Session transcript, evidence, and resume | reliability, recoverability, testability | `/root/claude-code-haha/src/QueryEngine.ts`, `/root/claude-code-haha/src/utils/sessionStorage.ts`, `/root/claude-code-haha/src/tools/AgentTool/resumeAgent.ts`, `/root/claude-code-haha/src/services/compact/compact.ts` | LangGraph `thread_id`, checkpointer/store where appropriate, JSONL session store, recovery brief | Must align recovery intent; exact storage may differ |
+| H07 | Scoped cross-session memory, not knowledge dumping | context-efficiency, reliability, maintainability, cross-session continuity | `/root/claude-code-haha/src/memdir/*`, `/root/claude-code-haha/src/services/SessionMemory/*`, `/root/claude-code-haha/src/tools/AgentTool/agentMemory*` | LangGraph store, explicit memory schemas, bounded recall, controlled save tool, side-agent later | Must align principles; cross-session memory is required, but rich auto extraction can still wait |
+
+### P1 Workflow Highlights
+
+These define how coding work is made explicit and verifiable.
+
+| ID | Highlight | Benefit | cc-haha source to inspect deeply | LangChain-native expression | Initial decision |
+|---|---|---|---|---|---|
+| H08 | TodoWrite as short-term planning contract | reliability, product parity, model control | `/root/claude-code-haha/src/tools/TodoWriteTool/*`, `/root/claude-code-haha/src/utils/todo/*` | `TodoWrite` strict Pydantic schema, `Command(update=...)`, state middleware | Already mostly aligned; keep separate from durable Task |
+| H09 | Durable Task graph as collaboration state | reliability, multi-agent readiness | `/root/claude-code-haha/src/tools/Task*Tool/*`, `/root/claude-code-haha/src/utils/tasks.ts`, `/root/claude-code-haha/src/tasks/*` | domain task store, strict transitions, tool API, later persistence/checkpointer integration | Partial now; deepen after Todo/session boundaries are stable |
+| H10 | Plan / Execute / Verify workflow discipline | reliability, testability, product-grade behavior | `/root/claude-code-haha/src/tools/EnterPlanModeTool/*`, `/root/claude-code-haha/src/tools/ExitPlanModeTool/*`, `/root/claude-code-haha/src/coordinator/coordinatorMode.ts`, verification agent sources | mode-aware prompt/context, permission plan mode, future verification subagent/tool | Align as workflow protocol; defer UI-heavy approval |
+
+### P2 Agent Team Highlights
+
+These should be layered after tool/permission/session/task are reliable.
+
+| ID | Highlight | Benefit | cc-haha source to inspect deeply | LangChain-native expression | Initial decision |
+|---|---|---|---|---|---|
+| H11 | Agent as tool and runtime object | agent-runtime, recoverability, product parity | `/root/claude-code-haha/src/tools/AgentTool/*`, `/root/claude-code-haha/src/tasks/LocalAgentTask/*`, `/root/claude-code-haha/src/services/AgentSummary/*` | subagent tool, state/context isolation, task-backed lifecycle, LangGraph subgraph/tool wrapper where useful | Align as runtime object; not just prompt wrapper |
+| H12 | Fork/cache-aware subagent execution | context-efficiency, runtime performance | `/root/claude-code-haha/src/tools/AgentTool/forkSubagent.ts`, `/root/claude-code-haha/src/tools/AgentTool/runAgent.ts`, cache-safe context docs | context snapshot/fork semantics, avoid breaking LangChain runtime, defer provider-specific cache tuning | Defer deep parity until subagent lifecycle is richer |
+| H13 | Mailbox / SendMessage multi-agent communication | multi-agent readiness, recoverability | `/root/claude-code-haha/src/tools/SendMessageTool/*`, `/root/claude-code-haha/src/tasks/LocalAgentTask/*`, `/root/claude-code-haha/src/coordinator/coordinatorMode.ts` | task-linked mailbox store, explicit message tool, no prompt-only fake conversation | Defer until durable tasks and subagent lifecycle mature |
+| H14 | Coordinator keeps synthesis | reliability, quality, multi-agent correctness | `/root/claude-code-haha/src/coordinator/coordinatorMode.ts`, task workflow docs | product workflow planner, separate research/implementation/verification roles | Align principle; implement only when coordinator mode is a target |
+
+### P2 Extension Platform Highlights
+
+These turn the product from single app into extensible runtime.
+
+| ID | Highlight | Benefit | cc-haha source to inspect deeply | LangChain-native expression | Initial decision |
+|---|---|---|---|---|---|
+| H15 | Skill system as capability packaging | maintainability, product parity | `/root/claude-code-haha/src/tools/SkillTool/*`, `/root/claude-code-haha/src/skills/*`, `/root/claude-code-haha/src/commands/skills/*` | local skill loader, `load_skill` tool, skill context injection, later forked skill execution | Partial now; keep simple and source-aware |
+| H16 | MCP as external capability protocol | extensibility, safety | `/root/claude-code-haha/src/services/mcp/*`, `/root/claude-code-haha/src/tools/ListMcpResourcesTool/*`, `/root/claude-code-haha/src/tools/ReadMcpResourceTool/*` | official `langchain-mcp-adapters`, capabilities, separate resources, strict config | Already Stage 11; audit before expanding |
+| H17 | Plugin states: source / install / enable | extensibility, maintainability | `/root/claude-code-haha/src/utils/plugins/*`, `/root/claude-code-haha/src/commands/plugin/*` | local manifest registry first; no marketplace until benefit exists | Defer broad marketplace/install parity |
+| H18 | Hooks as programmable middleware, not backdoor | extensibility, safety | `/root/claude-code-haha/src/utils/hooks/*`, `/root/claude-code-haha/src/services/tools/toolHooks.ts`, `/root/claude-code-haha/src/types/hooks.ts` | LangChain middleware + local hook dispatcher | Partial now; expand only around concrete lifecycle events |
+
+### P3 Production Hardening Highlights
+
+These are important, but should follow the core runtime unless a specific need appears.
+
+| ID | Highlight | Benefit | cc-haha source to inspect deeply | LangChain-native expression | Initial decision |
+|---|---|---|---|---|---|
+| H19 | Observability and evidence ledger | observability, testability | `/root/claude-code-haha/src/query.ts`, `/root/claude-code-haha/src/QueryEngine.ts`, telemetry/logging paths, existing local session evidence | structured local events, JSONL evidence, recovery brief | Partial now; improve alongside each feature |
+| H20 | Cost/cache instrumentation | context-efficiency, maintainability | `/root/claude-code-haha/src/services/compact/*`, `/root/claude-code-haha/src/utils/tokens.ts`, cache-safe/fork docs | local metrics first; provider-specific cache later | Defer rich provider-specific work |
+| H21 | Bridge / remote / IDE control plane | user-visible, remote collaboration | `/root/claude-code-haha/src/bridge/*`, `/root/claude-code-haha/src/services/mcp/*ide*` | not currently core to `coding-deepgent`; future integration boundary | Do not prioritize without explicit product goal |
+| H22 | Daemon / cron / proactive automation | user-visible, automation | `/root/claude-code-haha/src/tools/ScheduleCronTool/*`, `/root/claude-code-haha/src/tasks/*`, trigger docs | LangGraph scheduling only if product need exists | Defer |
+
+## How To Use This Backlog
+
+For any future implementation request:
+
+1. Identify the relevant highlight IDs.
+2. Read the listed cc-haha source files, not just the docs.
+3. Produce a function summary and expected-effect statement.
+4. Produce a source-backed alignment matrix.
+5. Apply `langchain-architecture-guard` to choose the smallest official LangChain/LangGraph shape.
+6. Implement only the rows whose local benefit is concrete.
+7. Update product docs/tests with evidence.
+
+## Immediate Recommendation
+
+Do not continue manually approving every system definition.
+
+Recommended next planning step:
+
+1. Audit current `coding-deepgent` implementation against H01-H10.
+2. Mark each highlight as:
+   - implemented
+   - partial
+   - missing
+   - intentionally deferred
+3. Use that audit to choose the next implementation stage.
diff --git a/.trellis/plans/coding-deepgent-h01-h10-target-design.md b/.trellis/plans/coding-deepgent-h01-h10-target-design.md
new file mode 100644
index 000000000..7b53c8f34
--- /dev/null
+++ b/.trellis/plans/coding-deepgent-h01-h10-target-design.md
@@ -0,0 +1,720 @@
+<!-- Created on 2026-04-14 from source reading, before implementation work. -->
+# coding-deepgent H01-H10 Target Design
+
+Status: source-backed target design draft
+Scope: `coding-deepgent/` product track only
+Source anchor: `/root/claude-code-haha` at commit `d166eb8`
+Planning input: `.omx/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+
+## Purpose
+
+This document answers the user's request to read source and design now, before opening implementation work.
+
+It converts the first ten cc core highlights into target goals for `coding-deepgent`.
+
+This is not an implementation plan yet. It is the design target that later implementation tasks should align against.
+
+## Operating Constraints
+
+- Use cc-haha source as primary behavior evidence.
+- Use `claude-code-book` and `cc-haha/docs` only as orientation and architecture analysis.
+- Keep LangChain/LangGraph as the runtime boundary.
+- Prefer official LangChain primitives:
+  - `create_agent`
+  - strict Pydantic `@tool(..., args_schema=...)`
+  - `Command(update=...)`
+  - `AgentMiddleware`
+  - `ToolRuntime`
+  - state/context schema
+  - store/checkpointer
+  - dynamic prompt/context middleware where appropriate
+- Do not copy cc-haha TypeScript architecture line-by-line.
+- Each upgrade must state benefit before work starts.
+
+## H01 — Tool-First Capability Runtime
+
+### Source evidence
+
+- `/root/claude-code-haha/src/Tool.ts`
+- `/root/claude-code-haha/src/services/tools/toolExecution.ts`
+- `/root/claude-code-haha/src/services/tools/toolOrchestration.ts`
+- `/root/claude-code-haha/src/services/tools/StreamingToolExecutor.ts`
+- `/root/claude-code-haha/docs/must-read/01-execution-engine.md`
+- `/root/claude-code-haha/docs/modules/01-execution-engine-deep-dive.md`
+
+### Current local state
+
+Implemented / partial:
+
+- `coding_deepgent.tool_system.capabilities.ToolCapability`
+- `coding_deepgent.tool_system.capabilities.CapabilityRegistry`
+- `coding_deepgent.tool_system.policy.ToolPolicy`
+- `coding_deepgent.tool_system.middleware.ToolGuardMiddleware`
+- domain-owned LangChain tools exist in `filesystem`, `todo`, `memory`, `skills`, `tasks`, and `subagents`
+
+### Target design
+
+The tool system should be the model-facing action contract. Every executable capability exposed to the model enters through LangChain tools and the `ToolGuardMiddleware` path.
+
+Do:
+
+- Keep `CapabilityRegistry` as metadata complement to LangChain tools, not as a replacement tool framework.
+- Extend capability metadata only when it supports policy, observability, tool-pool filtering, or extension trust.
+- Require strict Pydantic schemas for all model-visible tools.
+- Route stateful tool updates through `Command(update=...)`.
+- Make runtime-only fields hidden via official LangChain runtime injection where possible.
+
+Do not:
+
+- Create a Python clone of cc-haha's TypeScript `Tool` interface.
+- Put UI rendering hooks in the core tool contract.
+- Add alias/fallback parsing to tolerate wrong model inputs.
+- Build a custom executor before proving LangChain middleware is insufficient.
+
+### Benefit
+
+- Safety: prevents model-facing capabilities from bypassing guardrails.
+- Maintainability: all capabilities share one contract.
+- Testability: schemas, state updates, and policy decisions are separately testable.
+- Product parity: aligns with cc-haha's tool-first runtime without copying provider-specific shape.
+
+### Status
+
+Partial. The local design direction is correct; future work should deepen metadata, dynamic tool-pool policy, and result/evidence invariants.
+
+## H02 — Permission Runtime and Hard Safety
+
+### Source evidence
+
+- `/root/claude-code-haha/src/types/permissions.ts`
+- `/root/claude-code-haha/src/utils/permissions/permissions.ts`
+- `/root/claude-code-haha/src/utils/permissions/filesystem.ts`
+- `/root/claude-code-haha/src/utils/permissions/pathValidation.ts`
+- `/root/claude-code-haha/src/utils/permissions/permissionSetup.ts`
+- `/root/claude-code-haha/src/utils/permissions/yoloClassifier.ts`
+- `/root/claude-code-haha/docs/must-read/05-permission-security.md`
+- `/root/claude-code-haha/docs/modules/05-permission-security-deep-dive.md`
+
+### Current local state
+
+Implemented / partial:
+
+- `PermissionManager` supports mode, rules, hard command/path safety, trusted workdirs, extension trust, and `dontAsk` conversion.
+- `PermissionRule` supports behavior, tool name, content, domain, capability source, trusted, source.
+- `ToolGuardMiddleware` integrates permission policy with LangChain `wrap_tool_call`, emits events, and dispatches hooks.
+
+### Target design
+
+Permission is a runtime layer, not a per-tool helper.
+
+Do:
+
+- Keep deterministic guard behavior as the current foundation.
+- Preserve hard safety before normal mode/allow decisions.
+- Treat extension/untrusted destructive capabilities conservatively.
+- Keep all decisions structured with code, behavior, message, and metadata.
+- Model plan mode as read/research mode, not as a prompt-only convention.
+- Return protocol-safe `ToolMessage(status="error")` when approval is unavailable or denied.
+- Add LangGraph HITL interrupts only when interactive approval is a concrete target.
+
+Do not:
+
+- Implement auto classifier before deterministic policy has enough surface and tests.
+- Copy cc-haha React permission UI.
+- Allow bypass mode to skip hard safety.
+- Let hooks override hard safety.
+
+### Benefit
+
+- Safety: prevents unsafe tool execution in filesystem/MCP/plugin/subagent paths.
+- Reliability: headless/background contexts do not hang on impossible approvals.
+- Observability: decisions can be logged, tested, and explained.
+- Product parity: aligns with cc-haha's permission runtime framing.
+
+### Status
+
+Partial but strong. Immediate work should harden tests, metadata, and decision observability before adding classifier/HITL.
+
+## H03 — Layered Prompt Contract
+
+### Source evidence
+
+- `/root/claude-code-haha/src/utils/queryContext.ts`
+- `/root/claude-code-haha/src/context.ts`
+- `/root/claude-code-haha/docs/must-read/03-prompt-context-memory.md`
+- `/root/claude-code-haha/docs/modules/03-prompt-context-memory-deep-dive.md`
+
+### Current local state
+
+Implemented / partial:
+
+- `PromptContext` separates default prompt, user context, system context, append prompt, and memory context.
+- `build_default_system_prompt()` encodes product identity and LangChain-native behavior.
+- Tests assert stale tool wording is not in the prompt.
+
+### Target design
+
+The prompt system defines stable model operating contract.
+
+Do:
+
+- Keep the base prompt short, stable, and product-specific.
+- Keep custom prompt and append prompt separate.
+- Keep user/system context structured even if not all fields are model-visible yet.
+- Add role/mode overlays only when the runtime mode exists.
+- Use LangChain `dynamic_prompt` middleware only when prompt truly depends on runtime state/context.
+
+Do not:
+
+- Copy cc-haha's full prompt text.
+- Put dynamic task/memory/tool state in the base prompt.
+- Put tool manuals in the system prompt.
+- Add provider-specific cache blocks without measured benefit.
+
+### Benefit
+
+- Reliability: stable instructions reduce prompt drift.
+- Cache efficiency: volatile state stays out of base prompt.
+- Maintainability: prompts become testable contracts.
+
+### Status
+
+Partial. Current builder is intentionally small; target is to preserve structure and add overlays only when needed.
+
+## H04 — Dynamic Context Protocol
+
+### Source evidence
+
+- `/root/claude-code-haha/src/utils/attachments.ts`
+- `/root/claude-code-haha/src/utils/messages.ts`
+- `/root/claude-code-haha/src/context.ts`
+- `/root/claude-code-haha/src/utils/queryContext.ts`
+- `/root/claude-code-haha/docs/must-read/03-prompt-context-memory.md`
+
+### Current local state
+
+Implemented / partial:
+
+- `MemoryContextMiddleware` injects rendered memories into `SystemMessage` content blocks.
+- `PlanContextMiddleware` injects current todos and reminders into `SystemMessage` content blocks.
+- `RuntimeContext` carries session/workdir/trusted_workdirs/entrypoint/agent_name/skill_dir/event_sink/hook_registry.
+
+Missing:
+
+- No general typed context attachment/delta protocol.
+- No explicit context lifecycle taxonomy.
+- No context projection/message assembly layer.
+
+### Target design
+
+Context decides what dynamic information enters the model window, where it enters, and how long it should remain.
+
+Do:
+
+- Introduce a small typed context payload model before adding many ad hoc system blocks.
+- Keep dynamic state separate from prompt base.
+- Treat todos, memories, task status, skill availability, and future subagent/mailbox state as context payloads with bounded renderers.
+- Make context injection fail-soft.
+- Add tests that context payload rendering remains bounded and non-duplicative.
+
+Do not:
+
+- Build full cc-haha attachment protocol before local needs exist.
+- Turn every runtime event into model context.
+- Let memory/task/session systems write arbitrary system prompt text directly.
+
+### Benefit
+
+- Context-efficiency: only relevant dynamic data enters the window.
+- Maintainability: new dynamic context has one shape rather than ad hoc prompt fragments.
+- Reliability: dynamic context is testable and bounded.
+
+### Status
+
+Partial. Current middleware proves the pattern but needs a small shared protocol before more context types are added.
+
+## H05 — Progressive Context Pressure Management
+
+### Source evidence
+
+- `/root/claude-code-haha/src/query.ts`
+- `/root/claude-code-haha/src/services/compact/microCompact.ts`
+- `/root/claude-code-haha/src/services/compact/autoCompact.ts`
+- `/root/claude-code-haha/src/services/compact/compact.ts`
+- `/root/claude-code-haha/src/services/compact/sessionMemoryCompact.ts`
+- `/root/claude-code-haha/src/utils/toolResultStorage.ts`
+- `/root/claude-code-haha/src/utils/messages.ts`
+- `/root/claude-code-haha/docs/must-read/01-execution-engine.md`
+- `/root/claude-code-haha/docs/must-read/03-prompt-context-memory.md`
+
+### Current local state
+
+Implemented / partial:
+
+- `compact.budget.apply_tool_result_budget()` truncates oversized text deterministically.
+
+Missing:
+
+- No message projection layer.
+- No compact boundary state.
+- No micro/auto/reactive compact.
+- No tool-result persistence or restore reference.
+- No invariant tests for tool-call/result pairing across projection/compaction.
+
+### Target design
+
+Context pressure management should be progressive and invariant-preserving.
+
+Do:
+
+- Start with deterministic tool-result budget and message projection invariants.
+- Add a context pressure status model before adding summarization.
+- Preserve tool call/result and state update semantics.
+- Treat compaction as runtime correctness, not just cost optimization.
+- Add tests for projected/compacted history invariants.
+
+Do not:
+
+- Implement LLM summarization first.
+- Replace LangChain's message/runtime model with a custom query loop.
+- Copy every cc-haha compaction strategy without local pressure evidence.
+
+### Benefit
+
+- Long-session continuity: large outputs do not kill the run.
+- Reliability: projection/compaction does not corrupt protocol state.
+- Testability: deterministic budget/projection can be proven before LLM summarization.
+
+### Status
+
+Early partial. Current budget helper is useful but not enough for cc-level context management.
+
+## H06 — Session Transcript, Evidence, and Resume
+
+### Source evidence
+
+- `/root/claude-code-haha/src/QueryEngine.ts`
+- `/root/claude-code-haha/src/tools/AgentTool/resumeAgent.ts`
+- `/root/claude-code-haha/src/services/compact/compact.ts`
+- `/root/claude-code-haha/docs/must-read/02-agent-runtime.md`
+- `/root/claude-code-haha/docs/must-read/01-execution-engine.md`
+
+### Current local state
+
+Implemented / partial:
+
+- `JsonlSessionStore`
+- `SessionContext`
+- `SessionSummary`
+- `SessionEvidence`
+- `LoadedSession`
+- message records
+- state snapshot records
+- evidence records
+- resume state loading
+- `sessions.langgraph` helper exists
+
+### Target design
+
+Session should be recoverable execution evidence, not just chat history.
+
+Do:
+
+- Keep JSONL transcript as local evidence layer.
+- Preserve latest valid runtime state snapshot.
+- Keep evidence separate from UI.
+- Map session id to LangGraph `thread_id`.
+- Add recovery brief target for continuation.
+- Keep transcript store independent from memory/task stores.
+
+Do not:
+
+- Pretend resume is full cc agent runtime recovery yet.
+- Store unrelated memory/task state in session transcript directly.
+- Add database persistence until local JSONL limits are concrete.
+
+### Benefit
+
+- Recoverability: resume has messages, state, and evidence.
+- Testability: transcript/evidence records can be loaded deterministically.
+- Product parity: aligns with cc-haha's transcript/metadata/resume premise.
+
+### Status
+
+Partial and strong. Next target is audit: confirm runtime invocation actually uses loaded state/evidence where expected.
+
+## H07 — Scoped Memory, Not Knowledge Dumping
+
+### Source evidence
+
+- `/root/claude-code-haha/src/memdir/*`
+- `/root/claude-code-haha/src/services/SessionMemory/*`
+- `/root/claude-code-haha/src/tools/AgentTool/agentMemory.ts`
+- `/root/claude-code-haha/src/tools/AgentTool/agentMemorySnapshot.ts`
+- `/root/claude-code-haha/docs/must-read/03-prompt-context-memory.md`
+- `/tmp/claude-code-book/第二部分-核心系统篇/06-记忆系统-Agent的长期记忆.md`
+
+### Current local state
+
+Implemented / partial:
+
+- `MemoryRecord`
+- `SaveMemoryInput`
+- namespace: project/user/local
+- store-backed save/list/recall
+- `save_memory` tool
+- `MemoryContextMiddleware`
+
+Missing:
+
+- No explicit "do not save derivable facts" enforcement beyond tool description.
+- No memory freshness or richer relevance.
+- No side-agent memory writing.
+- No session memory compact integration.
+
+### Target design
+
+Memory stores durable, reusable, non-derivable knowledge and preferences.
+
+Do:
+
+- Keep namespaces explicit.
+- Add validation/review around memory quality before auto-extraction.
+- Keep memory separate from todo/task/session state.
+- Use LangGraph store seam.
+- Keep recall bounded and explainable.
+
+Do not:
+
+- Store code structure that can be re-read.
+- Store current todo/task status as memory.
+- Add embeddings/vector recall before deterministic recall quality is known.
+- Add auto-extraction before save/recall semantics are reliable.
+
+### Benefit
+
+- Context-efficiency: durable facts survive without flooding prompts.
+- Reliability: avoids memory pollution.
+- Maintainability: memory/task/session boundaries stay separate.
+
+### Status
+
+Partial foundation. Next target is memory quality policy and tests.
+
+## H08 — TodoWrite as Short-Term Planning Contract
+
+### Source evidence
+
+- `/root/claude-code-haha/src/tools/TodoWriteTool/TodoWriteTool.ts`
+- `/root/claude-code-haha/src/tools/TodoWriteTool/prompt.ts`
+- `/root/claude-code-haha/src/tools/TodoWriteTool/constants.ts`
+- `/root/claude-code-haha/docs/must-read/04-task-workflow.md`
+
+### Current local state
+
+Implemented:
+
+- public tool name `TodoWrite`
+- strict Pydantic schema with `todos`
+- required `content`, `status`, `activeForm`
+- injected `tool_call_id`
+- max 12 todos
+- exactly one `in_progress`
+- `Command(update=...)` state update
+- `PlanContextMiddleware` current todo rendering, stale reminders, and parallel-call rejection
+
+### Target design
+
+TodoWrite is short-term session planning state, not durable task graph.
+
+Do:
+
+- Preserve the public contract.
+- Keep todo state in LangGraph short-term state.
+- Keep activeForm required.
+- Keep parallel TodoWrite rejection.
+- Keep stale reminder bounded.
+
+Do not:
+
+- Merge TodoWrite with durable Task.
+- Add persistence to TodoWrite by default.
+- Add aliases for status/content fields.
+
+### Benefit
+
+- Reliability: model has visible progress discipline for multi-step work.
+- Product parity: cc-aligned model-visible contract.
+- Testability: state update shape is easy to prove.
+
+### Status
+
+Implemented / strong. Future work should preserve rather than refactor heavily.
+
+## H09 — Durable Task Graph as Collaboration State
+
+### Source evidence
+
+- `/root/claude-code-haha/src/tools/TaskCreateTool/*`
+- `/root/claude-code-haha/src/tools/TaskGetTool/*`
+- `/root/claude-code-haha/src/tools/TaskListTool/*`
+- `/root/claude-code-haha/src/tools/TaskUpdateTool/*`
+- `/root/claude-code-haha/src/utils/tasks.ts`
+- `/root/claude-code-haha/src/tasks/*`
+- `/root/claude-code-haha/docs/must-read/04-task-workflow.md`
+
+### Current local state
+
+Implemented / partial:
+
+- `TaskRecord`
+- statuses: pending/in_progress/blocked/completed/cancelled
+- transition validation
+- dependencies
+- owner
+- metadata
+- store-backed task namespace
+- tools: `task_create`, `task_get`, `task_list`, `task_update`
+
+Missing:
+
+- No claim/lock/high-water-mark semantics.
+- No task runtime object family.
+- No mailbox/agent lifecycle linkage.
+- No task-level evidence store.
+
+### Target design
+
+Durable Task is collaboration/runtime state, not TodoWrite replacement.
+
+Do:
+
+- Keep store-backed strict task records.
+- Add readiness/dependency semantics before team runtime.
+- Add task-level evidence and ownership only when agent lifecycle needs it.
+- Keep task tools model-visible but clearly distinct from TodoWrite.
+
+Do not:
+
+- Add filesystem lock/claim mechanics unless multiple concurrent workers actually share the task store.
+- Add UI task objects before background agents/mailbox exist.
+- Collapse task graph into session memory.
+
+### Benefit
+
+- Multi-agent readiness: explicit work ownership and dependency graph.
+- Reliability: durable state survives beyond one message window.
+- Maintainability: separates current plan from durable work graph.
+
+### Status
+
+Partial. Good schema/store foundation; defer runtime task object complexity.
+
+## H10 — Plan / Execute / Verify Workflow Discipline
+
+### Source evidence
+
+- `/root/claude-code-haha/src/tools/EnterPlanModeTool/*`
+- `/root/claude-code-haha/src/tools/ExitPlanModeTool/*`
+- `/root/claude-code-haha/src/coordinator/coordinatorMode.ts`
+- `/root/claude-code-haha/src/tools/AgentTool/built-in/verificationAgent.ts`
+- `/root/claude-code-haha/docs/must-read/04-task-workflow.md`
+- `/tmp/claude-code-book/第四部分-工程实践篇/14-Plan模式与结构化工作流.md`
+
+### Current local state
+
+Implemented / partial:
+
+- permission mode includes `plan`
+- prompt/todo workflow exists
+- subagent type includes `verifier`
+- no explicit EnterPlan/ExitPlan tools
+- no persistent plan file/recovery
+- no independent verification workflow
+
+### Target design
+
+Plan / Execute / Verify is a product workflow protocol that prevents complex coding work from drifting.
+
+Do:
+
+- Preserve plan mode as permission/read-only mode, not only a prompt hint.
+- Add explicit plan artifact only when implementation work needs approval/recovery.
+- Treat verification as an independent role/tool/subagent when product runtime can support it.
+- Keep coordinator synthesis principle: research and implementation can be delegated, synthesis must be owned.
+
+Do not:
+
+- Add full plan-mode UI now.
+- Add coordinator/team runtime before subagent/task/session foundations mature.
+- Require plan mode for trivial tasks.
+
+### Benefit
+
+- Reliability: prevents premature action.
+- Testability: plan artifacts can be verified against implementation.
+- Product-grade behavior: separates research, synthesis, implementation, and verification.
+
+### Status
+
+Partial concept only. Needs a planned product stage after core context/session/subagent foundations are stronger.
+
+## Summary Status
+
+| Highlight | Current status | Near-term target |
+|---|---|---|
+| H01 Tool-first runtime | Partial | deepen metadata, dynamic tool policy, invariants |
+| H02 Permission runtime | Partial/strong | harden deterministic policy and tests |
+| H03 Prompt contract | Partial | preserve builder, clarify overlays, test prompt drift |
+| H04 Dynamic context | Partial/weak | introduce typed context payload protocol |
+| H05 Context pressure | Early partial | add projection/invariant design before summarization |
+| H06 Session/resume | Partial/strong | audit runtime use of state/evidence |
+| H07 Memory | Partial | add memory quality policy and bounded recall tests |
+| H08 TodoWrite | Implemented/strong | preserve contract |
+| H09 Durable Task | Partial | keep schema/store; defer runtime task complexity |
+| H10 Plan/Verify | Concept partial | design after H04-H07/H11 mature |
+
+## Recommended Next Stage
+
+The next implementation stage should not jump to advanced multi-agent/team features.
+
+Recommended next target:
+
+**Stage 12: Context and Recovery Hardening**
+
+Rationale:
+
+- H01/H02/H03 are already directionally strong.
+- H04/H05 are weaker and will affect memory, task, and subagent correctness.
+- H06/H07 have foundations but need integration semantics.
+- H08 is already strong.
+- H09/H10/H11+ should wait until context/recovery boundaries are more explicit.
+
+Candidate Stage 12 scope:
+
+1. Introduce typed dynamic context payload protocol.
+2. Add deterministic message/context projection helpers with tool-result invariants.
+3. Audit session resume path and recovery brief use.
+4. Add memory quality rules and bounded recall tests.
+5. Update docs/status to reflect the new target.
+
+Out of scope for Stage 12:
+
+- full auto-compact LLM summarization
+- coordinator/team runtime
+- mailbox/send-message
+- plugin marketplace
+- permission classifier / rich approval UI
+
+## Stage 12 Iteration Plan
+
+Stage 12 should be implemented in sub-stages, not as one large infrastructure push.
+
+Rationale:
+
+- H04/H05/H06/H07 are coupled, but each has different verification needs.
+- A single large infrastructure pass would encourage speculative abstractions.
+- Smaller stages make the benefit of each infrastructure layer measurable.
+
+### Stage 12A — Context Payload Foundation
+
+Goal:
+
+Define a typed, bounded, testable payload protocol for dynamic context injection.
+
+Expected benefit:
+
+- Maintainability: future memory/todo/task/session/subagent context does not become ad hoc system prompt text.
+- Context-efficiency: context renderers can enforce bounded output.
+- Reliability: context payload injection can fail soft and be tested.
+
+Scope:
+
+- typed context payload model
+- bounded render helper(s)
+- integration target for existing todo/memory dynamic context middleware
+- tests proving payload rendering is bounded and non-duplicative
+
+Out of scope:
+
+- message projection
+- auto compact
+- session resume changes
+- memory quality policy
+
+### Stage 12B — Message Projection / Tool Result Invariants
+
+Goal:
+
+Add deterministic context pressure primitives before LLM-based compaction.
+
+Expected benefit:
+
+- Reliability: tool-use/tool-result and state update protocol invariants survive projection.
+- Context-efficiency: oversized tool outputs are handled consistently.
+- Testability: deterministic projection can be proven without live model calls.
+
+Scope:
+
+- message/context projection helpers
+- integration with existing tool-result budget helper
+- invariant tests for tool-result preservation and recent-window behavior
+
+Out of scope:
+
+- LLM summarization
+- full cc-haha microcompact/autocompact parity
+
+### Stage 12C — Recovery Brief / Session Resume Audit
+
+Goal:
+
+Confirm and harden the current session transcript/state/evidence path as a recovery foundation.
+
+Expected benefit:
+
+- Recoverability: resume gives enough execution context to continue work.
+- Testability: session load behavior is deterministic.
+- Product parity: aligns with cc-haha's transcript + metadata recovery premise.
+
+Scope:
+
+- recovery brief target shape
+- audit whether runtime invocation consumes loaded state/evidence appropriately
+- resume-path tests
+
+Out of scope:
+
+- full agent runtime resume
+- task-level evidence store
+- database persistence
+
+### Stage 12D — Memory Quality Policy
+
+Goal:
+
+Prevent long-term memory from becoming a dumping ground.
+
+Expected benefit:
+
+- Reliability: memory does not mislead the agent with stale/derivable facts.
+- Context-efficiency: only reusable, non-derivable knowledge is recalled.
+- Maintainability: memory stays distinct from todo/task/session state.
+
+Scope:
+
+- memory quality rules
+- save-memory validation/review path
+- bounded recall tests
+
+Out of scope:
+
+- embedding/vector recall
+- auto memory extraction
+- session-memory side agent
+
+## Immediate Implementation Recommendation
+
+Start with **Stage 12A: Context Payload Foundation**.
+
+Do not start with 12B/12C/12D because they need a shared context payload boundary to avoid ad hoc prompt injection and duplicated render paths.
diff --git a/.trellis/plans/coding-deepgent-runtime-foundation-20260412T213209Z.md b/.trellis/plans/coding-deepgent-runtime-foundation-20260412T213209Z.md
new file mode 100644
index 000000000..58fbf98d8
--- /dev/null
+++ b/.trellis/plans/coding-deepgent-runtime-foundation-20260412T213209Z.md
@@ -0,0 +1,50 @@
+<!-- Recovered on 2026-04-14 from local Codex/OMX session logs after OMX uninstall. This file is reconstructed from direct session output and is high confidence. -->
+# Context Snapshot — coding-deepgent runtime foundation
+
+Task statement: Produce consensus planning artifacts for `coding-deepgent` runtime foundation: `.omx/plans/prd-coding-deepgent-runtime-foundation.md` and `.omx/plans/test-spec-coding-deepgent-runtime-foundation.md`.
+
+Desired outcome: A product-stage plan for turning `coding-deepgent` into a professional LangChain-native cc runtime foundation, using LangChain/LangGraph primitives first and cc-haha semantics through extension seams where LangChain does not directly match.
+
+Known code facts:
+- Product scope is `coding-deepgent/`; tests enforce no imports from `agents_deepagents` and no public `sNN` modules.
+- Current product status is `stage-2-session-foundation` in `coding-deepgent/project_status.json`.
+- Current app uses `langchain.agents.create_agent` with `PlanningState`, `PlanContextMiddleware`, tools `[bash, read_file, write_file, edit_file, TodoWrite]`, and a process-global `SESSION_STATE`.
+- `TodoWrite` is aligned with cc-haha public contract: tool name `TodoWrite`, top-level `todos`, required `content/status/activeForm`, strict Pydantic schema, hidden `InjectedToolCallId`, `Command(update={"todos": ...})`, and parallel TodoWrite guard.
+- File tools in `coding_deepgent/tools/filesystem.py` currently rely on function-signature schema inference rather than explicit Pydantic `args_schema`.
+- `PlanContextMiddleware` currently uses mutable instance attribute `_updated_this_turn`, which should be replaced by graph state or deterministic message/state inspection before professional concurrency.
+- `sessions.py` is a product JSONL transcript/snapshot layer, not a LangGraph checkpointer. `create_agent` supports `checkpointer`, `store`, `context_schema`, and `state_schema`.
+
+LangChain/LangGraph docs facts:
+- `create_agent` is a LangGraph-backed runtime and accepts `state_schema`, `context_schema`, `checkpointer`, and `store`.
+- Tools should use Pydantic `args_schema`; `Command(update=...)` updates graph state; injected runtime/call-id fields should be hidden from the model.
+- Custom state should extend `AgentState` / TypedDict. Middleware-owned state should use middleware `state_schema`; `state_schema` on `create_agent` is also supported.
+- Middleware should avoid mutating instance attributes for cross-call state; graph state is scoped to thread/concurrency.
+- LangGraph checkpointers persist state by `thread_id`; stores are for cross-thread memory.
+
+cc-haha reference points already inspected:
+- `/root/claude-code-haha/src/query.ts`
+- `/root/claude-code-haha/src/Tool.ts`
+- `/root/claude-code-haha/src/services/tools/toolOrchestration.ts`
+- `/root/claude-code-haha/src/services/tools/toolExecution.ts`
+- `/root/claude-code-haha/src/services/tools/StreamingToolExecutor.ts`
+- `/root/claude-code-haha/src/tools/TodoWriteTool/*`
+- `/root/claude-code-haha/src/utils/todo/types.ts`
+- `/root/claude-code-haha/src/types/logs.ts`, `src/utils/sessionStorage.ts`, resume command/session refs.
+
+Constraints:
+- Plan only; do not implement source code in this workflow.
+- No new dependency without explicit approval. Plan may identify optional future dependency for persistent checkpointer.
+- Prefer LangChain/LangGraph primitives over custom loops/wrappers.
+- Keep modules professional and modular: tools, middleware, state, runtime context, sessions, renderers, permissions/resources separate.
+- Do not copy cc product UI/TUI, telemetry, full AppStateStore, MCP bus, plugin hook runtime, TodoV2, or verifier policy in this stage.
+
+Likely touchpoints:
+- `coding-deepgent/src/coding_deepgent/app.py`
+- `coding-deepgent/src/coding_deepgent/state.py`
+- `coding-deepgent/src/coding_deepgent/tools/filesystem.py`
+- `coding-deepgent/src/coding_deepgent/tools/planning.py`
+- `coding-deepgent/src/coding_deepgent/middleware/planning.py`
+- new `coding_deepgent/runtime/*`
+- possibly `coding_deepgent/tools/discovery.py`, `middleware/tool_guard.py`, `runtime/checkpointing.py`
+- `coding-deepgent/tests/*`
+- `coding-deepgent/docs/*`, `project_status.json`, `README.md`
diff --git a/.trellis/plans/index.md b/.trellis/plans/index.md
new file mode 100644
index 000000000..5b3f5529a
--- /dev/null
+++ b/.trellis/plans/index.md
@@ -0,0 +1,13 @@
+# Trellis Plans Index
+
+This directory contains the migrated long-lived planning documents for `coding-deepgent`.
+
+Canonical planning files:
+
+* `coding-deepgent-cc-core-highlights-roadmap.md`
+* `coding-deepgent-h01-h10-target-design.md`
+* `master-plan-coding-deepgent-reconstructed.md`
+* `prd-coding-deepgent-runtime-foundation.md`
+* `test-spec-coding-deepgent-runtime-foundation.md`
+
+Use these through Trellis instead of the removed `.omx/` tree.
diff --git a/.trellis/plans/master-plan-coding-deepgent-reconstructed.md b/.trellis/plans/master-plan-coding-deepgent-reconstructed.md
new file mode 100644
index 000000000..7a647bc27
--- /dev/null
+++ b/.trellis/plans/master-plan-coding-deepgent-reconstructed.md
@@ -0,0 +1,234 @@
+<!-- Created on 2026-04-14 as a reconstructed master plan after partial OMX plan loss. -->
+# Reconstructed Master Plan — coding-deepgent
+
+Status: reconstructed working plan
+Scope: `coding-deepgent/` only
+Intent: consolidate the surviving planning artifacts and current product status into one practical source of truth
+
+## 1. Provenance and Confidence
+
+This document is not claimed to be the original master plan. It is a reconstruction derived from the strongest surviving artifacts.
+
+Primary evidence:
+- `.omx/plans/prd-coding-deepgent-runtime-foundation.md`
+- `.omx/plans/test-spec-coding-deepgent-runtime-foundation.md`
+- `.omx/context/coding-deepgent-runtime-foundation-20260412T213209Z.md`
+- `.omx/recovery/runtime-foundation-recovery-notes-2026-04-14.md`
+- `coding-deepgent/README.md`
+- `coding-deepgent/PROJECT_PROGRESS.md`
+- `coding-deepgent/project_status.json`
+
+Confidence levels:
+- High confidence: current product stage, stage roadmap count, Stage 3 architecture principles, Stage 3 verification intent
+- Medium-high confidence: the architectural continuity from Stage 3 into later stages
+- Medium confidence: the exact original wording and sequencing of the lost post-Stage-3 plans
+
+## 2. Product Identity
+
+`coding-deepgent` is an independent cumulative LangChain-native cc-style product surface.
+
+Confirmed product metadata:
+- `shape`: `staged_langchain_cc_product`
+- `public_shape`: `single cumulative app`
+- `current_product_stage`: `stage-11-mcp-plugin-real-loading`
+- `compatibility_anchor`: `mcp-plugin-real-loading`
+- `architecture_reshape_status`: `s1-skeleton-complete`
+- upgrade policy: advance by explicit product-stage plan approval, not tutorial chapter completion
+
+## 3. Core Planning Principles
+
+These principles are directly supported by the restored runtime-foundation PRD and remain the most reliable long-term planning rules.
+
+1. Domain-first, LangChain-inside
+   LangChain and LangGraph remain the runtime boundary, while product capabilities are organized into explicit domains.
+2. Explicit dependency graph
+   Use dependency-injector containers for composition, overrides, and backend selection; do not hide business logic in containers.
+3. High cohesion, low coupling
+   Each domain owns one product concept and communicates through explicit seams rather than ad hoc imports.
+4. Functional skeleton over empty architecture
+   New stages must land as working product slices, not placeholder module trees.
+5. No clone drift
+   Preserve cc-aligned behavior where needed, but do not mirror source layout mechanically and do not bypass LangChain runtime seams.
+
+## 4. Architectural Baseline
+
+The recovered Stage 3 PRD defined the baseline professional runtime skeleton. Current code and status files indicate that this baseline still governs the product.
+
+Stable architecture expectations:
+- `runtime` owns invocation, context, state, and runtime seams
+- `containers` owns composition only
+- `tool_system` owns capability registry, policy, and guard behavior
+- `filesystem`, `todo`, and `sessions` are first-class product domains
+- later domains grow explicitly rather than being folded into `runtime` or `sessions`
+- CLI remains a professional shell over product services rather than the product core itself
+
+Boundary rules that should still be treated as active:
+- domain modules do not import `containers`
+- `containers/*` does not own business rules
+- `tool_system` must not become a god module
+- `sessions` must remain transcript/resume scoped, not absorb unrelated durable product state
+- LangChain-native seams stay intact: `create_agent`, `context=`, LangGraph `thread_id`, middleware-driven control
+
+## 5. Stage Model
+
+Confirmed total stage count: 11
+
+The surviving roadmap establishes the following cumulative product stages:
+
+1. Stage 1: TodoWrite / todos / activeForm product contract
+2. Stage 2: architecture gate for filesystem / tool-system / session seams
+3. Stage 3: professional domain runtime foundation
+4. Stage 4: control-plane foundation
+5. Stage 5: memory / context / compact foundation
+6. Stage 6: skills / subagents / durable task graph
+7. Stage 7: local MCP / plugin extension foundation
+8. Stage 8: recovery / evidence / runtime-continuation foundation
+9. Stage 9: permission / trust-boundary hardening
+10. Stage 10: hooks / lifecycle expansion
+11. Stage 11: MCP / plugin real loading
+
+## 6. Stage Intent Summary
+
+### Stage 1
+
+Establish the public planning contract around `TodoWrite(todos=[...])` and required `activeForm`.
+
+### Stage 2
+
+Separate the early runtime into clearer seams for filesystem, tool system, and session behavior.
+
+### Stage 3
+
+Establish the professional runtime skeleton:
+- typed settings
+- dependency-injector composition
+- Typer and Rich CLI surface
+- runtime context and state seams
+- domain packages for filesystem, todo, sessions, tool system
+- local events and guard infrastructure
+
+This is the strongest historically recovered stage because both PRD and test spec survive.
+
+### Stage 4
+
+Add deterministic control-plane behavior:
+- permissions
+- hooks
+- structured prompt/context assembly
+
+### Stage 5
+
+Add bounded long-term memory and context-control foundations:
+- store-backed memory seam
+- model-visible memory save path
+- deterministic tool-result budget helpers
+
+### Stage 6
+
+Add local skill loading, durable task graph, and minimal synchronous subagent capability.
+
+### Stage 7
+
+Add local MCP/plugin extension seams:
+- MCP tool descriptor adaptation
+- separate MCP resource read surfaces
+- strict local plugin manifest declarations
+
+### Stage 8
+
+Add recovery and evidence:
+- session evidence records
+- recovery brief generation
+- default CLI runtime wired to real local session storage
+
+### Stage 9
+
+Harden permissions and trust boundaries:
+- typed settings-backed permission rules
+- explicit trusted extra workspaces
+- capability trust metadata for builtin vs extension tools
+
+### Stage 10
+
+Promote hooks from passive registry to actual lifecycle integration:
+- `SessionStart`
+- `UserPromptSubmit`
+- `PreToolUse`
+- `PostToolUse`
+- `PermissionDenied`
+
+### Stage 11
+
+Upgrade MCP/plugin from declaration-level support to real loading:
+- typed root `.mcp.json`
+- adapter-backed MCP tool loading when available
+- plugin declaration validation against known local capabilities and skills
+
+## 7. What Is Confirmed Implemented Now
+
+Based on current status documents, these claims are currently asserted by the project itself:
+
+- product stage is at Stage 11
+- the Stage 3 skeleton has been reshaped into an `s1-skeleton-complete` baseline
+- current architecture includes explicit domains for:
+  - runtime
+  - permissions
+  - hooks
+  - prompting/context
+  - memory
+  - compact helpers
+  - local skills
+  - durable tasks
+  - bounded subagents
+  - local MCP tool registration/loading
+  - local plugin manifests
+
+These are project-state claims, not yet independently re-audited in this document.
+
+## 8. Open Gaps in the Recovered Planning Record
+
+The following are still missing or only weakly supported:
+
+- original detailed PRDs for Stages 4 through 11
+- stage-by-stage test specs after Stage 3
+- ADR-style records for major deviations taken during later implementation
+- explicit “done / partial / deferred” matrices for each post-Stage-3 stage
+- any original prioritization notes for future stages beyond the current Stage 11 anchor
+
+## 9. Practical Working Rules Going Forward
+
+Until stronger historical plan files are recovered, future planning should treat this document as the operational master index and use the following rules:
+
+1. Treat the restored Stage 3 PRD and test spec as the strongest architectural authority.
+2. Treat `coding-deepgent/PROJECT_PROGRESS.md` and `coding-deepgent/README.md` as the authoritative current stage ledger.
+3. Do not infer missing post-Stage-3 details as if they were historical facts; label them explicitly as reconstruction or new planning.
+4. Before any new stage work, re-check it against the Stage 3 boundary rules:
+   - domain ownership
+   - container purity
+   - LangChain-native runtime seams
+   - no central god modules
+5. When new plans are written, attach test/verification expectations at the same time so the planning record does not again split into architecture without acceptance criteria.
+
+## 10. Recommended Next Planning Actions
+
+1. Create a stage audit document for Stages 4 through 11 with columns:
+   - intended capability
+   - current implementation evidence
+   - gaps
+   - deferred items
+2. Reconstruct or newly author post-Stage-3 PRDs one stage at a time, starting with the current Stage 11 anchor and the next intended stage after it.
+3. Add a single index file in `.omx/plans/` that lists all authoritative planning artifacts and their confidence levels.
+4. When a stage is materially complete, update both:
+   - `coding-deepgent/PROJECT_PROGRESS.md`
+   - `coding-deepgent/project_status.json`
+
+## 11. Source Map
+
+Use these files together:
+
+- [Runtime Foundation PRD](/root/learn-claude-code/.omx/plans/prd-coding-deepgent-runtime-foundation.md)
+- [Runtime Foundation Test Spec](/root/learn-claude-code/.omx/plans/test-spec-coding-deepgent-runtime-foundation.md)
+- [Recovery Notes](/root/learn-claude-code/.omx/recovery/runtime-foundation-recovery-notes-2026-04-14.md)
+- [Current Product README](/root/learn-claude-code/coding-deepgent/README.md)
+- [Current Progress Ledger](/root/learn-claude-code/coding-deepgent/PROJECT_PROGRESS.md)
+- [Current Status JSON](/root/learn-claude-code/coding-deepgent/project_status.json)
diff --git a/.trellis/plans/prd-coding-deepgent-runtime-foundation.md b/.trellis/plans/prd-coding-deepgent-runtime-foundation.md
new file mode 100644
index 000000000..cde4650fd
--- /dev/null
+++ b/.trellis/plans/prd-coding-deepgent-runtime-foundation.md
@@ -0,0 +1,546 @@
+<!-- Recovered on 2026-04-14 from local Codex/OMX session logs after OMX uninstall. High-fidelity reconstruction of the last known "professional domain" revision; not guaranteed byte-identical. -->
+# PRD — coding-deepgent Professional Domain Runtime Foundation
+
+Status: final ralplan plan, revised for dependency-injector + professional domain architecture
+Scope: `coding-deepgent/` product code only. This planning step does not implement code.
+Context snapshot: `.omx/context/coding-deepgent-runtime-foundation-20260412T213209Z.md`
+Test spec: `.omx/plans/test-spec-coding-deepgent-runtime-foundation.md`
+
+## 1. RALPLAN-DR Summary
+
+### Principles
+1. **Domain-first, LangChain-inside** — cc-haha defines long-term product domains; LangChain/LangGraph defines runtime integration seams.
+2. **Explicit dependency graph** — use `dependency-injector` containers to make providers, overrides, and backend selection visible; do not hide business logic in containers.
+3. **High cohesion, low coupling by contract** — each domain package owns one cc concept; domain logic depends on ports/protocols or local services, not concrete adapters from other domains.
+4. **Functional skeleton, not empty architecture** — Stage 3 must deliver a working app skeleton: typed settings, DI composition, Typer CLI, Rich renderers, strict tools, TodoWrite, sessions, tool guard, local events.
+5. **Professional foundations without cc clone drift** — no custom query loop, no LangChain bypass, no file-by-file cc mirror. Future cc features get landing zones and iterative stages.
+
+### Decision Drivers
+1. **Long-term cc feature growth** — permissions, hooks, subagents, compact, memory, skills, tasks, MCP, and observability need clear domain homes now.
+2. **Replace hidden globals with explicit providers** — current module-global state/app wiring should evolve into container-composed runtime invocation and graph state.
+3. **Developer clarity over minimal diffs** — the user explicitly prefers richer architecture if it makes future iteration clearer.
+
+### Viable Options
+
+#### Option A — Professional domain architecture with dependency-injector (favored)
+Adopt domain packages plus `dependency-injector` containers, `pydantic-settings`, Typer/Rich CLI shell, and quality tooling. Keep LangChain as runtime and expose cc-like features through domains and adapters.
+
+Pros:
+- Clear object graph similar to Spring-style DI while remaining Pythonic.
+- Strong testing story through provider override.
+- Natural growth path for future cc features.
+- High cohesion via domain packages and low coupling via containers/ports.
+
+Cons:
+- Adds dependencies and structural migration.
+- Requires architecture tests to prevent container/service-locator abuse.
+- More initial files than the current small app.
+
+#### Option B — Domain packages with hand-written container only
+Keep domain packages but avoid dependency-injector for now.
+
+Pros:
+- Fewer dependencies.
+- Less framework surface.
+
+Cons:
+- Less clear provider graph as backends grow.
+- User explicitly wants complex clarity and accepts dependencies.
+
+#### Option C — Flat runtime-spine architecture
+Keep most new modules under `runtime/`, `tools/`, and `middleware/`.
+
+Pros:
+- Smaller migration.
+
+Cons:
+- Lower long-term cohesion; `runtime/` will become a grab bag.
+- Less aligned with cc domain evolution.
+
+**Decision:** Choose Option A.
+
+## 2. Accepted Dependency Additions
+
+Stage 3 may add these dependencies to `coding-deepgent/pyproject.toml`.
+
+### Runtime/product dependencies
+
+- `dependency-injector` — composition root, providers, provider overrides, selector/resource providers later.
+- `pydantic-settings` — typed settings from environment/dotenv/secrets.
+- `typer` — professional CLI command groups.
+- `rich` — terminal rendering for todos, sessions, events, diagnostics.
+- `structlog` — structured local logging foundation.
+
+### Dev dependencies
+
+- `ruff` — lint/format.
+- `mypy` or `pyright` — static typing gate. Prefer one as required; allow the other later.
+- `pytest-cov` — optional coverage evidence if execution wants coverage gates.
+
+### Deferred but approved for future stages
+
+- `pluggy` — future hook/plugin stage.
+- Python package entry points via `importlib.metadata` — future plugin discovery, no dependency.
+- OpenTelemetry Python — future production observability/tracing.
+- SQLAlchemy + Alembic — future durable business persistence for tasks/memory/session indexes if LangGraph store/checkpointer is insufficient.
+- persistent LangGraph checkpointer package, e.g. sqlite/postgres backend — future persistence ADR.
+
+## 3. Product Stage Definition
+
+Advance product metadata to:
+
+```text
+current_product_stage = stage-3-professional-domain-runtime-foundation
+compatibility_anchor = professional-domain-runtime-foundation
+shape = staged_langchain_cc_product
+```
+
+This stage creates a professional functional skeleton, not full cc parity.
+
+## 4. Target Architecture
+
+```text
+coding_deepgent/
+  app.py                 # create_agent wiring target
+  cli.py                 # Typer app entrypoint
+  settings.py            # pydantic-settings Settings
+  config.py              # compatibility facade during migration
+  state.py               # compatibility facade during migration
+
+  containers/
+    __init__.py
+    app.py               # AppContainer composition root
+    runtime.py
+    tool_system.py
+    filesystem.py
+    todo.py
+    sessions.py
+    cli.py               # optional CLI providers
+
+  runtime/
+    __init__.py
+    context.py           # RuntimeContext
+    state.py             # RuntimeState
+    invocation.py        # RuntimeInvocation assembly
+    checkpointing.py     # checkpointer/store provider seam
+    events.py            # local RuntimeEvent / sink
+    logging.py           # structlog config, if implemented
+
+  tool_system/
+    __init__.py
+    capabilities.py      # authoritative registry
+    policy.py            # shared policy decisions/reason codes
+    middleware.py        # ToolGuardMiddleware
+    results.py           # future tool result refs; may defer
+    ports.py             # Protocols only if multiple implementations exist
+
+  filesystem/
+    __init__.py
+    schemas.py
+    tools.py
+    discovery.py         # glob/grep
+    policy.py            # filesystem-specific policy/backstop if needed
+
+  todo/
+    __init__.py
+    schemas.py
+    state.py
+    service.py
+    tools.py
+    middleware.py
+    renderers.py
+
+  sessions/
+    __init__.py
+    records.py
+    ports.py
+    store_jsonl.py
+    resume.py
+    langgraph.py         # thread_id/checkpointer bridge
+
+  renderers/
+    __init__.py
+    text.py
+
+  permissions/           # future
+  hooks/                 # future
+  subagents/             # future
+  compact/               # future
+  memory/                # future
+  skills/                # future
+  resources/             # future
+  tasks/                 # future
+  mcp/                   # future
+```
+
+## 5. High Cohesion / Low Coupling Reflection
+
+### Current plan strengths
+
+- Domain packages (`todo`, `filesystem`, `sessions`, `tool_system`) are cohesive around cc product concepts.
+- LangChain adapters live near domains (`tools.py`, `middleware.py`) instead of centralizing all behavior in `app.py`.
+- `containers/` makes dependencies explicit and test-overridable.
+- `runtime/` is limited to cross-domain LangGraph spine.
+
+### Coupling risks and mitigations
+
+| Risk | Why it matters | Mitigation |
+|---|---|---|
+| Containers become service locator | Hidden runtime dependencies can spread everywhere | Domain modules must not import containers; only app/cli/tests compose through containers. |
+| Domain packages import each other directly | Todo/filesystem/sessions could form cycles | Cross-domain coordination goes through `tool_system`, `runtime`, or application services. |
+| LangChain adapters pollute pure domain logic | Makes service logic hard to test | Keep pure helpers in `service.py`; LangChain `@tool`/middleware in adapter files. |
+| Rich/Typer leak into domain | Ties business logic to terminal UI | Rich/Typer only in CLI/renderers, never schemas/state/services. |
+| Tool system becomes god module | It could absorb permissions/hooks/MCP/task logic | `tool_system` owns only tool registry/policy/guard/result refs; future domains remain separate. |
+| `sessions/` becomes storage for everything | Memory/tasks/compact could collapse into sessions | Sessions owns transcript/resume only; durable tasks/memory/compact get own domains later. |
+
+### Enforceable rules
+
+1. Domain code never imports `containers.*`.
+2. Domain `schemas.py` and `state.py` never import LangChain runtime objects except where unavoidable for `AgentState` in state modules.
+3. LangChain-specific adapters are named clearly: `tools.py`, `middleware.py`.
+4. `containers/*` contains no business rules.
+5. Cross-domain references must be one-way through ports/protocols or container wiring.
+6. Tests must fail if forbidden mirror files appear: `runtime/query.py`, `tool_executor.py`, `app_state_store.py`.
+
+## 6. cc Source Concepts Projected onto Modules
+
+| cc-haha concept | coding-deepgent domain | LangChain implementation seam |
+|---|---|---|
+| `query.ts` | `runtime` + `app.py` | `create_agent`, `context=`, `config.thread_id`, middleware |
+| `Tool.ts` | `tool_system` | LangChain tools + capability metadata |
+| `ToolUseContext` | `runtime/context.py`, `runtime/state.py` | `context_schema`, `state_schema`, `ToolRuntime` when needed |
+| `AppStateStore` | runtime state slices + domain state | `AgentState`, checkpointer, store; no monolithic clone |
+| `toolExecution` / `toolOrchestration` | `tool_system` | `wrap_tool_call`, shared policy, capability registry |
+| `TodoWriteTool/*` | `todo` | Pydantic schema + `@tool` + `Command(update)` + middleware |
+| Bash/Read/Write/Edit/Grep/Glob | `filesystem` | strict tools, policy backstop |
+| session logs/storage | `sessions` | JSONL store + LangGraph thread bridge |
+| hooks | future `hooks` | `AgentMiddleware` lifecycle hooks, later pluggy |
+| permissions | future `permissions` | tool guard / HITL interrupt later |
+| compact | future `compact` | middleware + tool result refs + summaries |
+| memory/skills/resources | future domains | LangGraph store + resource descriptors + middleware |
+| durable tasks/background | future `tasks` | store-backed tools/state, distinct from TodoWrite |
+| MCP/plugins | future `mcp`/plugins | capability registry + entry points/pluggy later |
+
+## 7. Functional Skeleton in Stage 3
+
+Stage 3 should deliver a working skeleton, not only folders:
+
+1. **Containerized app construction**
+   - `AppContainer` can build settings, session store, capability registry, middleware, and LangChain agent.
+   - Tests override model/session/event providers.
+2. **Typed settings**
+   - `Settings` reads environment with `pydantic-settings`.
+   - Existing `config.py` remains compatibility facade.
+3. **Typer CLI + Rich rendering**
+   - Commands: `run`, `sessions list`, `sessions resume`, `config show`, `doctor`.
+   - Rich renders todo list, session table, and local runtime events.
+4. **Todo domain**
+   - Current TodoWrite behavior migrated into `todo/`.
+   - Public contract unchanged.
+5. **Filesystem domain**
+   - Strict schemas for bash/read/write/edit.
+   - Add `glob`/`grep` if execution scope permits.
+6. **Tool system**
+   - Registry drives tool list.
+   - Shared policy and guard middleware emit local event evidence.
+7. **Sessions domain**
+   - JSONL transcript/resume preserved.
+   - Session ID flows into RuntimeContext and LangGraph thread config.
+8. **Local events/logging**
+   - Runtime events testable in memory.
+   - `structlog` configured for local structured logs if execution includes logging slice.
+
+## 8. Requirements Summary
+
+### In Scope
+
+- Add accepted dependencies.
+- Restructure into domain packages with compatibility facades.
+- Add `containers/` and `AppContainer`.
+- Add typed settings via `pydantic-settings`.
+- Migrate TodoWrite into `todo/`.
+- Migrate filesystem tools into `filesystem/` and strict schemas.
+- Add `tool_system/` registry/policy/middleware.
+- Add `runtime/` context/state/invocation/events/checkpointing spine.
+- Split `sessions/` package or keep facade with staged split if vertical churn is too high.
+- Upgrade CLI to Typer/Rich skeleton.
+- Add local structured logging/events skeleton.
+- Update docs/status/tests.
+
+### Out of Scope
+
+- `agents_deepagents/` changes.
+- Custom query loop.
+- Full cc executor/StreamingToolExecutor.
+- Monolithic AppStateStore clone.
+- FastAPI server/API layer.
+- External plugin runtime with pluggy/entry points.
+- Production OpenTelemetry instrumentation.
+- SQLAlchemy/Alembic persistence implementation.
+- Permissions/hooks/subagents/compact/memory/tasks/MCP implementation beyond package landing zones and roadmap.
+- UI/TUI beyond Rich terminal rendering.
+
+## 9. Acceptance Criteria
+
+1. `pyproject.toml` includes approved dependencies and dev dependencies.
+2. `AppContainer` is the composition root and supports provider override in tests.
+3. Domain modules do not import containers.
+4. `app.py` still uses LangChain `create_agent`.
+5. `RuntimeContext`/`RuntimeState` are wired via `context_schema`/`state_schema`.
+6. `TodoWrite` public contract remains unchanged and cc-aligned.
+7. Filesystem tools use explicit strict Pydantic schemas.
+8. Capability registry is authoritative for agent tool list.
+9. Tool guard uses shared policy and preserves `Command(update=...)` tools.
+10. Typer CLI commands work without model credentials for help/config/session listing.
+11. Rich renderers are isolated from domain services.
+12. JSONL sessions remain backward compatible.
+13. No forbidden cc mirror modules are added.
+14. Full `cd coding-deepgent && pytest` passes.
+15. Ruff and type-check commands are documented and pass if included in execution gate.
+
+## 10. Implementation Plan — Professional Architecture Slices
+
+### Slice 0 — Regression, dependencies, and architecture contract
+
+Files:
+- `pyproject.toml`
+- `tests/test_structure.py`
+- `tests/test_contract.py`
+
+Actions:
+- Add dependency/dependency-absence tests.
+- Add architecture tests for container/domain boundaries.
+- Lock current TodoWrite/session behavior.
+
+### Slice 1 — Settings and containers
+
+Files:
+- `settings.py`
+- `containers/__init__.py`
+- `containers/app.py`
+- `containers/runtime.py`
+- `containers/sessions.py`
+- `containers/todo.py`
+- `containers/filesystem.py`
+- `containers/tool_system.py`
+- `config.py` compatibility facade
+
+Actions:
+- Add `Settings` with pydantic-settings.
+- Add `AppContainer` and subcontainers.
+- Keep domain code container-free.
+
+### Slice 2 — Runtime spine
+
+Files:
+- `runtime/context.py`
+- `runtime/state.py`
+- `runtime/invocation.py`
+- `runtime/events.py`
+- `runtime/checkpointing.py`
+
+Actions:
+- Define context/state/invocation/config.thread_id.
+- Add event sink.
+- Add checkpointer/store selector seam via DI container.
+
+### Slice 3 — Todo domain migration
+
+Files:
+- `todo/schemas.py`
+- `todo/state.py`
+- `todo/service.py`
+- `todo/tools.py`
+- `todo/middleware.py`
+- `todo/renderers.py`
+- compatibility facades from old modules
+
+Actions:
+- Move TodoWrite contract.
+- Preserve public imports where needed.
+- Remove mutable middleware turn state.
+
+### Slice 4 — Filesystem domain migration
+
+Files:
+- `filesystem/schemas.py`
+- `filesystem/tools.py`
+- `filesystem/discovery.py`
+- `filesystem/policy.py`
+- compatibility facade from old `tools/filesystem.py`
+
+Actions:
+- Strict schemas.
+- Preserve existing behavior.
+- Add glob/grep if included.
+
+### Slice 5 — Tool system domain
+
+Files:
+- `tool_system/capabilities.py`
+- `tool_system/policy.py`
+- `tool_system/middleware.py`
+- optional `tool_system/results.py`
+
+Actions:
+- Registry drives tool list.
+- Shared policy reason codes.
+- Guard middleware emits runtime events.
+
+### Slice 6 — Sessions domain
+
+Files:
+- `sessions/records.py`
+- `sessions/ports.py`
+- `sessions/store_jsonl.py`
+- `sessions/resume.py`
+- `sessions/langgraph.py`
+- compatibility facade from old `sessions.py`
+
+Actions:
+- Preserve JSONL behavior.
+- Add ports/protocols.
+- Add LangGraph thread bridge.
+
+### Slice 7 — CLI shell
+
+Files:
+- `cli.py`
+- optional `containers/cli.py`
+- `renderers/text.py`
+- Rich renderers in relevant domains
+
+Actions:
+- Convert to Typer command groups.
+- Use Rich for session/todo/event display.
+- Preserve existing command behavior or document migration.
+
+### Slice 8 — Logging/docs/final verification
+
+Files:
+- `runtime/logging.py`
+- `README.md`
+- `PROJECT_PROGRESS.md`
+- `project_status.json`
+- `docs/runtime-foundation.md`
+
+Actions:
+- Configure structlog if included.
+- Update docs with architecture and roadmap.
+- Run full verification.
+
+## 11. Risks and Mitigations
+
+| Risk | Mitigation |
+|---|---|
+| Too much architecture before behavior | Stage 3 includes functional skeleton: CLI, TodoWrite, filesystem tools, sessions, guard events. |
+| Containers become service locator | Forbid domain imports from containers; container is composition-only. |
+| Package migration breaks compatibility | Use facades and regression tests. |
+| DI framework hides dependencies | Prefer provider construction and explicit container use; avoid widespread `@inject` initially. |
+| Rich/Typer leak into domain logic | Keep them in CLI/renderers only. |
+| Tool system becomes god module | Keep permissions/hooks/MCP/tasks in future domains. |
+| Type/lint burden slows migration | Add tooling but allow staged strictness. |
+| New dependencies bloat project | Dependencies are explicitly approved and tested via pyproject checks. |
+
+## 12. Verification Commands
+
+```bash
+cd coding-deepgent
+pytest
+ruff check .
+ruff format --check .
+mypy src/coding_deepgent tests
+python -m coding_deepgent --help
+coding-deepgent --help
+```
+
+Architecture grep:
+
+```bash
+rg -n "agents_deepagents|s[0-9]{2}_" src tests
+rg -n "runtime/query.py|tool_executor.py|app_state_store.py|class Tool\(" src tests
+rg -n "from coding_deepgent.containers|import coding_deepgent.containers" src/coding_deepgent/todo src/coding_deepgent/filesystem src/coding_deepgent/sessions src/coding_deepgent/tool_system
+rg -n "FastAPI|Depends|pluggy|opentelemetry|SQLAlchemy|Alembic" src tests
+rg -n "dict\[str, Any\]|normalize_.*\(|fallback|alias|ToolRuntime|InjectedToolCallId" src/coding_deepgent tests
+```
+
+## 13. Roadmap Toward cc Parity
+
+1. **Stage 3 — Professional domain runtime foundation**
+   - This plan.
+2. **Stage 4 — Tool control + permissions MVP**
+   - permission modes, allow/deny rules, CLI confirmation seam.
+3. **Stage 5 — Hooks MVP**
+   - internal pre/post/failure hooks; evaluate pluggy later.
+4. **Stage 6 — Subagents / AgentTool**
+   - agent identity, sidechain sessions, per-agent todos.
+5. **Stage 7 — Context compact / tool result store**
+   - compactable tool refs, summaries, active todo preservation.
+6. **Stage 8 — Memory / skills / resources**
+   - resource descriptors, lazy skill loading, LangGraph store memory.
+7. **Stage 9 — Durable task/background runtime**
+   - task records, dependencies, background execution slots.
+8. **Stage 10 — MCP / plugin system**
+   - MCP adapters, entry points/pluggy if needed, capability registry integration.
+9. **Stage 11 — Observability and product shell**
+   - OpenTelemetry, richer Rich/Textual UI if justified, production logs.
+
+## 14. ADR — Professional Domain Architecture with DI
+
+### Decision
+Adopt `dependency-injector`, `pydantic-settings`, Typer, Rich, structlog, and dev tooling as part of a domain-first LangChain cc architecture. Use DI containers for composition, not business logic.
+
+### Drivers
+- User prefers professional complexity that clarifies long-term iteration.
+- Future cc domains need explicit dependencies and replaceable implementations.
+- Python large projects benefit from composition roots, typed settings, ports/adapters, and provider overrides.
+
+### Alternatives Considered
+- Hand-written container only: rejected because DI clarity is desired and future provider graph will grow.
+- Flat runtime modules: rejected as less cohesive long-term.
+- Spring-like magic everywhere: rejected; use containers explicitly and avoid broad wiring initially.
+
+### Why Chosen
+This combines cc domain boundaries with LangChain runtime seams and a clear Python dependency graph.
+
+### Consequences
+- Initial migration is larger.
+- Tests must enforce container/domain separation.
+- Dependency management becomes part of architecture.
+
+### Follow-ups
+- Consider Pydantic settings strictness and secrets sources.
+- Consider persistent checkpointer/store backend.
+- Consider pluggy/entry points only during plugin stage.
+- Consider OpenTelemetry only during observability stage.
+
+## 15. Staffing Guidance
+
+### Ralph path
+
+```text
+$ralph .omx/plans/prd-coding-deepgent-runtime-foundation.md .omx/plans/test-spec-coding-deepgent-runtime-foundation.md
+```
+
+Sequence:
+1. Dependency/tooling + structure tests.
+2. Containers/settings.
+3. Runtime spine.
+4. Todo/filesystem domains.
+5. Tool system/sessions.
+6. CLI/Rich/logging.
+7. Docs/status + full verification.
+
+### Team path
+
+```text
+$team .omx/plans/prd-coding-deepgent-runtime-foundation.md
+```
+
+Lanes:
+1. **Container/settings/runtime lane** — `containers/*`, `settings.py`, `runtime/*`, app wiring.
+2. **Todo/filesystem lane** — `todo/*`, `filesystem/*`, compatibility facades.
+3. **Tool-system/sessions lane** — `tool_system/*`, `sessions/*`.
+4. **CLI/rendering/logging lane** — Typer/Rich/structlog/docs.
+5. **Tests lane** — architecture, schema, container override, CLI, session, full regression.
+6. **Verification lane** — pytest, ruff, mypy, grep, final evidence.
diff --git a/.trellis/plans/runtime-foundation-recovery-notes-2026-04-14.md b/.trellis/plans/runtime-foundation-recovery-notes-2026-04-14.md
new file mode 100644
index 000000000..a744c4f3d
--- /dev/null
+++ b/.trellis/plans/runtime-foundation-recovery-notes-2026-04-14.md
@@ -0,0 +1,31 @@
+<!-- Created on 2026-04-14 after restoring removed OMX planning artifacts. -->
+# Runtime Foundation Recovery Notes
+
+Recovered artifacts:
+- `.omx/plans/prd-coding-deepgent-runtime-foundation.md`
+- `.omx/plans/test-spec-coding-deepgent-runtime-foundation.md`
+- `.omx/context/coding-deepgent-runtime-foundation-20260412T213209Z.md`
+
+Evidence sources:
+- Direct session output from `/root/.codex/sessions/2026/04/13/...jsonl`
+- `/root/.codex/history.jsonl`
+- Session records showing the original `.omx/plans/` and `.omx/context/` paths existed before uninstall
+
+Confidence:
+- `test-spec-coding-deepgent-runtime-foundation.md`: high
+  Reason: recovered from direct `sed` output of the original file in session logs.
+- `coding-deepgent-runtime-foundation-20260412T213209Z.md`: high
+  Reason: recovered from direct `sed` output of the original file in session logs.
+- `prd-coding-deepgent-runtime-foundation.md`: medium-high
+  Reason: reconstructed from multiple corroborating session fragments, including direct file reads and a logged heredoc write command, but not guaranteed byte-identical to the original final file.
+
+Notable naming caveat:
+- Earlier session logs show an older/narrower variant titled `# PRD — coding-deepgent Runtime Foundation`.
+- The restored PRD uses the later professional-domain title:
+  `# PRD — coding-deepgent Professional Domain Runtime Foundation`
+- This appears to reflect a genuine same-day evolution of the plan rather than a contradiction.
+
+Practical guidance:
+- Treat the restored `test-spec` and `context` files as strong historical references.
+- Treat the restored `PRD` as the best available working recovery for future planning/execution.
+- If stricter provenance is needed later, use these files together with the referenced session logs.
diff --git a/.trellis/plans/test-spec-coding-deepgent-runtime-foundation.md b/.trellis/plans/test-spec-coding-deepgent-runtime-foundation.md
new file mode 100644
index 000000000..d078eb2da
--- /dev/null
+++ b/.trellis/plans/test-spec-coding-deepgent-runtime-foundation.md
@@ -0,0 +1,208 @@
+<!-- Recovered on 2026-04-14 from local Codex/OMX session logs after OMX uninstall. High-confidence recovery of the final "professional domain" test spec. -->
+# Test Specification — coding-deepgent Professional Domain Runtime Foundation
+
+Status: final test spec for dependency-injector + domain-first architecture
+Scope: no-network verification for `.omx/plans/prd-coding-deepgent-runtime-foundation.md`.
+
+## 1. Test Strategy
+
+Tests must prove high cohesion, low coupling, dependency clarity, LangChain-native runtime behavior, and functional skeleton behavior. Tests should run without live model credentials.
+
+Primary gates:
+
+```bash
+cd coding-deepgent
+pytest
+ruff check .
+ruff format --check .
+mypy src/coding_deepgent tests
+```
+
+## 2. Dependency and Tooling Tests
+
+Files:
+- `pyproject.toml`
+- `tests/test_structure.py`
+
+Required cases:
+1. Runtime dependencies include `dependency-injector`, `pydantic-settings`, `typer`, `rich`, `structlog`.
+2. Dev dependencies include `ruff` and one type checker (`mypy` preferred or `pyright`).
+3. No unplanned runtime dependencies are added.
+4. `dependency-injector` is used only in `containers/`, `app.py`, `cli.py`, and tests; domain packages do not import containers.
+5. `pydantic-settings` is used by `settings.py`, not scattered across domains.
+
+## 3. Container Tests
+
+Files:
+- Add `tests/test_container.py`
+
+Required cases:
+1. `AppContainer` can instantiate settings, session store, capability registry, middleware list, and agent.
+2. Providers can be overridden in tests for fake model/session store/event sink.
+3. Container does not contain business rules: no tool execution helpers, no TodoWrite update logic, no session JSONL parsing.
+4. Subcontainers exist for runtime, todo, filesystem, tool_system, sessions.
+5. Container supports backend selectors for checkpointer/store/session where implemented.
+
+## 4. Settings Tests
+
+Files:
+- Add/update `tests/test_settings.py`
+- Update `tests/test_config.py`
+
+Required cases:
+1. `Settings` loads defaults.
+2. Environment variables override expected settings.
+3. Workdir/session dir/model/checkpointer/store/permission settings are typed.
+4. Existing `load_settings()` compatibility behavior remains or is intentionally migrated.
+5. Secrets/API keys are not printed in config output.
+
+## 5. Architecture / Cohesion / Coupling Tests
+
+Files:
+- Update `tests/test_structure.py`
+- Update `tests/test_contract.py`
+
+Required cases:
+1. Required domain packages exist: `runtime`, `tool_system`, `filesystem`, `todo`, `sessions`, `containers`.
+2. No forbidden cc mirror modules: `runtime/query.py`, `tool_executor.py`, `app_state_store.py`, custom `Tool` base class.
+3. Domain packages do not import `containers`.
+4. CLI/Rich imports do not appear in domain `schemas.py`, `state.py`, or `service.py`.
+5. Session domain does not import future memory/task/compact/subagent/MCP domains.
+6. Tool system does not import permissions/hooks/MCP/tasks future domains.
+7. `app.py` uses `create_agent`.
+8. No `agents_deepagents` imports and no public `sNN` modules.
+
+## 6. Runtime Spine Tests
+
+Files:
+- `tests/test_runtime_context.py`
+- `tests/test_runtime_state.py`
+- `tests/test_app.py`
+
+Required cases:
+1. `RuntimeContext` carries session/workdir/entrypoint/agent identity/event sink.
+2. `RuntimeState` extends `AgentState` and contains todos/rounds.
+3. Runtime invocation maps session id to LangGraph `thread_id`.
+4. `agent_loop()` passes `context=` and `config=` to fake compiled agent.
+5. Module-global runtime state is not the source of truth.
+6. Checkpointer/store providers can be none/memory according to settings.
+
+## 7. Todo Domain Tests
+
+Files:
+- `tests/test_todo_domain.py` or existing planning tests
+
+Required cases:
+1. Todo schemas are strict Pydantic models.
+2. `TodoWrite` tool name/schema remains unchanged.
+3. `Command(update=...)` shape remains correct.
+4. Middleware injects current todos, stale reminders, and rejects parallel TodoWrite.
+5. Renderer output remains stable.
+6. Todo domain does not import filesystem/sessions/container directly.
+
+## 8. Filesystem Domain Tests
+
+Files:
+- `tests/test_filesystem_domain.py`
+- `tests/test_tool_schemas.py`
+
+Required cases:
+1. bash/read/write/edit schemas are explicit and strict.
+2. Extra fields and aliases fail.
+3. Dangerous command and workspace escape behavior preserved.
+4. glob/grep, if included, are read-only strict tools.
+5. Filesystem domain does not import Todo/session/container.
+
+## 9. Tool System Tests
+
+Files:
+- `tests/test_tool_system_capabilities.py`
+- `tests/test_tool_system_policy.py`
+- `tests/test_tool_system_middleware.py`
+
+Required cases:
+1. Capability registry is authoritative for agent tool list.
+2. Registry metadata is present for all current tools.
+3. Shared policy reason codes are stable.
+4. Guard middleware allows safe calls and blocks/records unsafe calls.
+5. Guard preserves handler return values and `Command(update=...)`.
+6. Runtime events emitted through event sink when guard allows/blocks.
+
+## 10. Sessions Tests
+
+Files:
+- `tests/test_sessions.py`
+- optional `tests/test_sessions_domain.py`
+
+Required cases:
+1. JSONL transcript roundtrip remains stable.
+2. Resume restores state snapshots.
+3. Same-workdir filtering works.
+4. Session ID flows into RuntimeContext and LangGraph `thread_id`.
+5. Compatibility imports remain if `sessions.py` becomes facade.
+6. Session domain remains transcript/resume only.
+
+## 11. CLI / Rich Tests
+
+Files:
+- `tests/test_cli.py`
+- optional `tests/test_renderers.py`
+
+Required cases:
+1. Typer CLI help works with no credentials.
+2. Commands exist: `run`, `sessions list`, `sessions resume`, `config show`, `doctor` or documented subset.
+3. Existing CLI behavior remains available or migration is documented.
+4. Rich renderers produce stable text/table output in tests.
+5. CLI uses container providers and can override fake agent/session store.
+
+## 12. Logging / Events Tests
+
+Files:
+- `tests/test_runtime_events.py`
+- optional `tests/test_logging.py`
+
+Required cases:
+1. Runtime event sink records ordered local events.
+2. structlog config can initialize without external services.
+3. No secrets/API keys appear in rendered logs/config output.
+4. Events are local and not graph state by default.
+
+## 13. Local Smoke Checks
+
+```bash
+cd coding-deepgent
+python -m coding_deepgent --help
+coding-deepgent --help
+coding-deepgent config show
+coding-deepgent sessions list
+pytest tests/test_cli.py tests/test_app.py tests/test_sessions.py
+```
+
+No live model call is required.
+
+## 14. Review / Grep Checks
+
+```bash
+rg -n "agents_deepagents|s[0-9]{2}_" src tests
+rg -n "runtime/query.py|tool_executor.py|app_state_store.py|class Tool\(" src tests
+rg -n "from coding_deepgent.containers|import coding_deepgent.containers" src/coding_deepgent/todo src/coding_deepgent/filesystem src/coding_deepgent/sessions src/coding_deepgent/tool_system
+rg -n "FastAPI|Depends|pluggy|opentelemetry|SQLAlchemy|Alembic" src tests
+rg -n "dict\[str, Any\]|normalize_.*\(|fallback|alias|ToolRuntime|InjectedToolCallId" src/coding_deepgent tests
+```
+
+Expected interpretation:
+- `InjectedToolCallId` expected for TodoWrite only.
+- `FastAPI`, `pluggy`, `opentelemetry`, `SQLAlchemy`, `Alembic` may appear only in docs/roadmap for this stage.
+- `dict[str, Any]` allowed in message/session plumbing, not structured tool-input fallback.
+
+## 15. Exit Criteria
+
+1. All focused tests pass.
+2. Full `pytest` passes.
+3. Ruff check and format check pass.
+4. Type-check command passes or documented initial strictness baseline is accepted.
+5. CLI smoke passes without credentials.
+6. No forbidden imports/modules are present.
+7. Container/domain boundaries are enforced by tests.
+8. Docs/status reflect `stage-3-professional-domain-runtime-foundation`.
+9. No live network/model call is required for verification.
diff --git a/.trellis/project-handoff.md b/.trellis/project-handoff.md
new file mode 100644
index 000000000..f81e9a0a9
--- /dev/null
+++ b/.trellis/project-handoff.md
@@ -0,0 +1,199 @@
+# coding-deepgent Project Handoff
+
+Updated: 2026-04-15
+Primary branch: `codex/stage-12-14-context-compact-foundation`
+Primary PR: `#220` `https://github.com/shareAI-lab/learn-claude-code/pull/220`
+
+## Product Goal
+
+`coding-deepgent` is the product track that should implement the essential `cc-haha` / Claude Code runtime logic through LangChain/LangGraph-native primitives, while staying professional-grade, modular, maintainable, and non-demo.
+
+Canonical goal/backlog docs:
+
+* `.trellis/tasks/04-14-redefine-coding-deepgent-final-goal/prd.md`
+* `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+
+## Current Mainline
+
+Current mainline has focused on:
+
+* context / compact / session / recovery hardening
+* durable task / workflow hardening
+
+Latest completed stage families:
+
+* Stage 12: Context and Recovery Hardening
+* Stage 13: Context Compaction v1
+* Stage 14A: Explicit Generated Summary CLI Wiring
+* Stage 15: Compact Persistence Semantics
+* Stage 16: Virtual Transcript Pruning
+* Stage 17A/17B/17C/17D: Durable Task and Workflow Hardening
+* Stage 18A/18B: Verifier Execution and Evidence Integration
+* Stage 19A/19B: Evidence Observability and Verifier Lineage
+* Stage 20: Canonical MVP Completion Dashboard
+* Stage 21: Tool And Permission Closeout
+* Stage 22: Prompt And Dynamic Context Closeout
+* Stage 23: Context Pressure And Session Continuity Closeout
+* Stage 24: Scoped Memory Closeout
+* Stage 25: Todo Task Plan Verify Closeout
+* Stage 26: Agent As Tool MVP Closeout
+* Stage 27: Local Extension Platform Closeout
+* Stage 28: Observability Evidence Closeout
+* Stage 29: Deferred Boundary ADR And MVP Release Checklist
+
+## Latest Verified State
+
+Latest completed stages and what they changed:
+
+* `17A`: durable task graph invariants
+  * rejects missing dependencies, self-dependencies, cycles
+  * exposes `ready` in `task_list`
+* `17B`: verification workflow boundary
+  * emits `verification_nudge` when a 3+ task graph closes without a verification task
+* `17C`: explicit plan artifacts
+  * `PlanArtifact`, `plan_save`, `plan_get`
+  * required `verification` field
+  * separate plan namespace from task namespace
+* `17D`: verifier execution boundary
+  * verifier subagent requires `plan_id`
+  * verifier resolves durable plan artifact before execution
+  * verifier returns structured JSON result
+  * verifier allowlist includes `plan_get`, excludes `plan_save`
+* `18A`: verifier execution integration
+  * verifier executes through a real bounded child-agent path
+  * verifier uses a dedicated read-only system prompt
+  * verifier keeps a fixed read-only tool allowlist
+  * verifier preserves structured JSON result output
+* `18B`: verifier result persistence and evidence integration
+  * verifier `VERDICT: PASS|FAIL|PARTIAL` results persist into session evidence
+  * verifier evidence roundtrips through `JsonlSessionStore.load_session()`
+  * recovery briefs expose verifier evidence through the existing evidence path
+  * verifier persistence reuses the session ledger and does not mutate tasks/plans
+* `19A`: verifier evidence provenance in recovery briefs
+  * recovery brief renders concise `plan=...` / `verdict=...` provenance for verification evidence
+  * arbitrary evidence metadata is not dumped into resume context
+* `19B`: verifier evidence lineage metadata
+  * verifier evidence records include parent session/thread and child verifier thread/agent lineage
+  * verifier JSON result and task/plan state remain unchanged
+* `20`: canonical MVP completion dashboard
+  * H01-H22 now have one canonical roadmap/dashboard file
+  * Approach A MVP boundary is fixed
+  * Stage 21-29 sequencing and Stage 30-36 reserve are explicit
+* `21`: tool and permission closeout
+  * builtin tool-name collisions are now rejected before capability projection
+  * H01/H02 have explicit contract tests for exposure projection, policy-code mapping, pattern safety, and container wiring
+* `22`: prompt and dynamic context closeout
+  * H03 has direct settings-backed prompt layering tests
+  * H04 has a model-call composition test covering resume history, todo context, and memory context ordering
+  * H04 MVP boundary is explicitly narrowed to resume/todo/memory/compact flows; skills/resources remain deferred
+* `23`: context pressure and session continuity closeout
+  * H05 has projection-chain regression coverage for mixed plain/structured/metadata messages
+  * H06 has a combined resume/compact/evidence continuity regression
+  * evidence CLI remains optional and is not required for MVP
+* `24`: scoped memory closeout
+  * H07 is fixed as local namespace-scoped durable memory with quality gating and bounded recall
+  * richer session-memory extraction and agent-memory snapshot runtime remain deferred
+* `25`: todo/task/plan/verify closeout
+  * H08 TodoWrite is fixed as session-local bounded short-term planning
+  * H09 durable task graph has terminal visibility and verification-recognition regressions
+  * H10 plan/verify remains explicit and verifier-backed; coordinator/mailbox are deferred
+* `26`: agent-as-tool MVP closeout
+  * H11 is fixed as bounded `run_subagent` tool surface with real verifier child execution
+  * H12 is fixed only as minimal context/thread propagation; rich fork/cache parity is deferred
+* `27`: local extension platform closeout
+  * H15 skills, H16 MCP, and H18 hooks are closed for local MVP
+  * H17 is closed as local manifest/source validation only; full install/enable lifecycle is deferred
+* `28`: observability evidence closeout
+  * H19 persists whitelisted `hook_blocked` and `permission_denied` runtime events into session evidence
+  * H20 is closed as minimal local budget/projection/compact counters; rich provider-specific cost/cache instrumentation is deferred
+* `29`: deferred-boundary ADR and MVP release checklist
+  * H01-H22 have explicit statuses in the canonical dashboard
+  * H13/H14/H21/H22 are deferred out of Approach A MVP
+  * Stage 30-36 reserve is not currently required unless later validation finds a concrete MVP gap
+
+## Current Contracts
+
+Read these before coding in the current mainline:
+
+* `.trellis/spec/backend/runtime-context-compaction-contracts.md`
+* `.trellis/spec/backend/task-workflow-contracts.md`
+
+## Current Product Modules
+
+Core domains:
+
+* `runtime`
+* `tool_system`
+* `filesystem`
+* `todo`
+* `sessions`
+* `memory`
+* `compact`
+* `permissions`
+* `hooks`
+* `skills`
+* `tasks`
+* `subagents`
+* `mcp`
+* `plugins`
+* `prompting`
+
+## Next Recommended Task
+
+Next planned direction:
+
+* release validation / PR cleanup for Approach A MVP
+
+Intent:
+
+* run a broader validation pass when cost is acceptable
+* review/stage the accumulated Stage 18-29 work
+* update PR #220 or prepare the next PR boundary
+* keep H13/H14/H21/H22 in the next-cycle backlog unless a new source-backed PRD reopens them
+
+## Planning Gate
+
+Before any new stage implementation begins, the proposal must state:
+
+* the concrete function being added or changed
+* the concrete user/system benefit it brings
+* why the benefit is worth the added complexity now
+
+“Closer to cc” alone is not sufficient.
+
+## Persistent User Requirement
+
+Cross-session memory is a product requirement.
+
+Interpretation for current planning:
+
+* durable user-relevant information must survive session resume boundaries
+* future stages should prefer durable memory/evidence/session mechanisms that improve cross-session continuity
+* stage proposals must say explicitly whether they advance cross-session memory directly, indirectly, or not at all
+
+## Resume Strategy
+
+When starting a new session:
+
+1. Read this handoff file first.
+2. Refresh live state:
+   * `git branch --show-current`
+   * `git status -sb`
+   * `gh pr view 220 --repo shareAI-lab/learn-claude-code --json number,title,url,isDraft,headRefName,baseRefName`
+3. Read only the latest relevant PRDs if needed:
+   * `.trellis/tasks/04-15-stage-17c-explicit-plan-artifact-boundary/prd.md`
+   * `.trellis/tasks/04-15-stage-17d-verifier-subagent-execution-boundary/prd.md`
+   * `.trellis/tasks/04-15-stage-18a-verifier-execution-integration/prd.md`
+   * `.trellis/tasks/04-15-stage-18b-verifier-result-persistence-evidence-integration/prd.md`
+   * `.trellis/tasks/04-15-stage-19-evidence-observability-agent-lifecycle-hardening/prd.md`
+   * `.trellis/tasks/04-15-coding-deepgent-highlight-completion-map/prd.md`
+   * `.trellis/tasks/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/prd.md`
+
+## Cost Control
+
+Default to `stage-iterate` lean mode:
+
+* auto-progress sub-stages
+* avoid large re-reads unless a real ambiguity appears
+* prefer focused tests
+* avoid broad docs/git/PR work unless explicitly requested
diff --git a/.trellis/scripts/__init__.py b/.trellis/scripts/__init__.py
new file mode 100755
index 000000000..815a13743
--- /dev/null
+++ b/.trellis/scripts/__init__.py
@@ -0,0 +1,5 @@
+"""
+Trellis Python Scripts
+
+This module provides Python implementations of Trellis workflow scripts.
+"""
diff --git a/.trellis/scripts/add_session.py b/.trellis/scripts/add_session.py
new file mode 100755
index 000000000..71606e5b8
--- /dev/null
+++ b/.trellis/scripts/add_session.py
@@ -0,0 +1,423 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Add a new session to journal file and update index.md.
+
+Usage:
+    python3 add_session.py --title "Title" --commit "hash" --summary "Summary"
+    echo "content" | python3 add_session.py --title "Title" --commit "hash"
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from common.paths import (
+    FILE_JOURNAL_PREFIX,
+    get_repo_root,
+    get_developer,
+    get_workspace_dir,
+)
+from common.developer import ensure_developer
+from common.config import get_session_commit_message, get_max_journal_lines
+
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+def get_latest_journal_info(dev_dir: Path) -> tuple[Path | None, int, int]:
+    """Get latest journal file info.
+
+    Returns:
+        Tuple of (file_path, file_number, line_count).
+    """
+    latest_file: Path | None = None
+    latest_num = -1
+
+    for f in dev_dir.glob(f"{FILE_JOURNAL_PREFIX}*.md"):
+        if not f.is_file():
+            continue
+
+        match = re.search(r"(\d+)$", f.stem)
+        if match:
+            num = int(match.group(1))
+            if num > latest_num:
+                latest_num = num
+                latest_file = f
+
+    if latest_file:
+        lines = len(latest_file.read_text(encoding="utf-8").splitlines())
+        return latest_file, latest_num, lines
+
+    return None, 0, 0
+
+
+def get_current_session(index_file: Path) -> int:
+    """Get current session number from index.md."""
+    if not index_file.is_file():
+        return 0
+
+    content = index_file.read_text(encoding="utf-8")
+    for line in content.splitlines():
+        if "Total Sessions" in line:
+            match = re.search(r":\s*(\d+)", line)
+            if match:
+                return int(match.group(1))
+    return 0
+
+
+def _extract_journal_num(filename: str) -> int:
+    """Extract journal number from filename for sorting."""
+    match = re.search(r"(\d+)", filename)
+    return int(match.group(1)) if match else 0
+
+
+def count_journal_files(dev_dir: Path, active_num: int) -> str:
+    """Count journal files and return table rows."""
+    active_file = f"{FILE_JOURNAL_PREFIX}{active_num}.md"
+    result_lines = []
+
+    files = sorted(
+        [f for f in dev_dir.glob(f"{FILE_JOURNAL_PREFIX}*.md") if f.is_file()],
+        key=lambda f: _extract_journal_num(f.stem),
+        reverse=True
+    )
+
+    for f in files:
+        filename = f.name
+        lines = len(f.read_text(encoding="utf-8").splitlines())
+        status = "Active" if filename == active_file else "Archived"
+        result_lines.append(f"| `{filename}` | ~{lines} | {status} |")
+
+    return "\n".join(result_lines)
+
+
+def create_new_journal_file(
+    dev_dir: Path, num: int, developer: str, today: str, max_lines: int = 2000,
+) -> Path:
+    """Create a new journal file."""
+    prev_num = num - 1
+    new_file = dev_dir / f"{FILE_JOURNAL_PREFIX}{num}.md"
+
+    content = f"""# Journal - {developer} (Part {num})
+
+> Continuation from `{FILE_JOURNAL_PREFIX}{prev_num}.md` (archived at ~{max_lines} lines)
+> Started: {today}
+
+---
+
+"""
+    new_file.write_text(content, encoding="utf-8")
+    return new_file
+
+
+def generate_session_content(
+    session_num: int,
+    title: str,
+    commit: str,
+    summary: str,
+    extra_content: str,
+    today: str
+) -> str:
+    """Generate session content."""
+    if commit and commit != "-":
+        commit_table = """| Hash | Message |
+|------|---------|"""
+        for c in commit.split(","):
+            c = c.strip()
+            commit_table += f"\n| `{c}` | (see git log) |"
+    else:
+        commit_table = "(No commits - planning session)"
+
+    return f"""
+
+## Session {session_num}: {title}
+
+**Date**: {today}
+**Task**: {title}
+
+### Summary
+
+{summary}
+
+### Main Changes
+
+{extra_content}
+
+### Git Commits
+
+{commit_table}
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+"""
+
+
+def update_index(
+    index_file: Path,
+    dev_dir: Path,
+    title: str,
+    commit: str,
+    new_session: int,
+    active_file: str,
+    today: str
+) -> bool:
+    """Update index.md with new session info."""
+    # Format commit for display
+    commit_display = "-"
+    if commit and commit != "-":
+        commit_display = re.sub(r"([a-f0-9]{7,})", r"`\1`", commit.replace(",", ", "))
+
+    # Get file number from active_file name
+    match = re.search(r"(\d+)", active_file)
+    active_num = int(match.group(1)) if match else 0
+    files_table = count_journal_files(dev_dir, active_num)
+
+    print(f"Updating index.md for session {new_session}...")
+    print(f"  Title: {title}")
+    print(f"  Commit: {commit_display}")
+    print(f"  Active File: {active_file}")
+    print()
+
+    content = index_file.read_text(encoding="utf-8")
+
+    if "@@@auto:current-status" not in content:
+        print("Error: Markers not found in index.md. Please ensure markers exist.", file=sys.stderr)
+        return False
+
+    # Process sections
+    lines = content.splitlines()
+    new_lines = []
+
+    in_current_status = False
+    in_active_documents = False
+    in_session_history = False
+    header_written = False
+
+    for line in lines:
+        if "@@@auto:current-status" in line:
+            new_lines.append(line)
+            in_current_status = True
+            new_lines.append(f"- **Active File**: `{active_file}`")
+            new_lines.append(f"- **Total Sessions**: {new_session}")
+            new_lines.append(f"- **Last Active**: {today}")
+            continue
+
+        if "@@@/auto:current-status" in line:
+            in_current_status = False
+            new_lines.append(line)
+            continue
+
+        if "@@@auto:active-documents" in line:
+            new_lines.append(line)
+            in_active_documents = True
+            new_lines.append("| File | Lines | Status |")
+            new_lines.append("|------|-------|--------|")
+            new_lines.append(files_table)
+            continue
+
+        if "@@@/auto:active-documents" in line:
+            in_active_documents = False
+            new_lines.append(line)
+            continue
+
+        if "@@@auto:session-history" in line:
+            new_lines.append(line)
+            in_session_history = True
+            header_written = False
+            continue
+
+        if "@@@/auto:session-history" in line:
+            in_session_history = False
+            new_lines.append(line)
+            continue
+
+        if in_current_status:
+            continue
+
+        if in_active_documents:
+            continue
+
+        if in_session_history:
+            new_lines.append(line)
+            if re.match(r"^\|\s*-", line) and not header_written:
+                new_lines.append(f"| {new_session} | {today} | {title} | {commit_display} |")
+                header_written = True
+            continue
+
+        new_lines.append(line)
+
+    index_file.write_text("\n".join(new_lines), encoding="utf-8")
+    print("[OK] Updated index.md successfully!")
+    return True
+
+
+# =============================================================================
+# Main Function
+# =============================================================================
+
+def _auto_commit_workspace(repo_root: Path) -> None:
+    """Stage .trellis/workspace and .trellis/tasks, then commit with a configured message."""
+    commit_msg = get_session_commit_message(repo_root)
+    subprocess.run(
+        ["git", "add", "-A", ".trellis/workspace", ".trellis/tasks"],
+        cwd=repo_root,
+        capture_output=True,
+    )
+    # Check if there are staged changes
+    result = subprocess.run(
+        ["git", "diff", "--cached", "--quiet", "--", ".trellis/workspace", ".trellis/tasks"],
+        cwd=repo_root,
+    )
+    if result.returncode == 0:
+        print("[OK] No workspace changes to commit.", file=sys.stderr)
+        return
+    commit_result = subprocess.run(
+        ["git", "commit", "-m", commit_msg],
+        cwd=repo_root,
+        capture_output=True,
+        text=True,
+    )
+    if commit_result.returncode == 0:
+        print(f"[OK] Auto-committed: {commit_msg}", file=sys.stderr)
+    else:
+        print(f"[WARN] Auto-commit failed: {commit_result.stderr.strip()}", file=sys.stderr)
+
+
+def add_session(
+    title: str,
+    commit: str = "-",
+    summary: str = "(Add summary)",
+    extra_content: str = "(Add details)",
+    auto_commit: bool = True,
+) -> int:
+    """Add a new session."""
+    repo_root = get_repo_root()
+    ensure_developer(repo_root)
+
+    developer = get_developer(repo_root)
+    if not developer:
+        print("Error: Developer not initialized", file=sys.stderr)
+        return 1
+
+    dev_dir = get_workspace_dir(repo_root)
+    if not dev_dir:
+        print("Error: Workspace directory not found", file=sys.stderr)
+        return 1
+
+    max_lines = get_max_journal_lines(repo_root)
+
+    index_file = dev_dir / "index.md"
+    today = datetime.now().strftime("%Y-%m-%d")
+
+    journal_file, current_num, current_lines = get_latest_journal_info(dev_dir)
+    current_session = get_current_session(index_file)
+    new_session = current_session + 1
+
+    session_content = generate_session_content(
+        new_session, title, commit, summary, extra_content, today
+    )
+    content_lines = len(session_content.splitlines())
+
+    print("========================================", file=sys.stderr)
+    print("ADD SESSION", file=sys.stderr)
+    print("========================================", file=sys.stderr)
+    print("", file=sys.stderr)
+    print(f"Session: {new_session}", file=sys.stderr)
+    print(f"Title: {title}", file=sys.stderr)
+    print(f"Commit: {commit}", file=sys.stderr)
+    print("", file=sys.stderr)
+    print(f"Current journal file: {FILE_JOURNAL_PREFIX}{current_num}.md", file=sys.stderr)
+    print(f"Current lines: {current_lines}", file=sys.stderr)
+    print(f"New content lines: {content_lines}", file=sys.stderr)
+    print(f"Total after append: {current_lines + content_lines}", file=sys.stderr)
+    print("", file=sys.stderr)
+
+    target_file = journal_file
+    target_num = current_num
+
+    if current_lines + content_lines > max_lines:
+        target_num = current_num + 1
+        print(f"[!] Exceeds {max_lines} lines, creating {FILE_JOURNAL_PREFIX}{target_num}.md", file=sys.stderr)
+        target_file = create_new_journal_file(dev_dir, target_num, developer, today, max_lines)
+        print(f"Created: {target_file}", file=sys.stderr)
+
+    # Append session content
+    if target_file:
+        with target_file.open("a", encoding="utf-8") as f:
+            f.write(session_content)
+        print(f"[OK] Appended session to {target_file.name}", file=sys.stderr)
+
+    print("", file=sys.stderr)
+
+    # Update index.md
+    active_file = f"{FILE_JOURNAL_PREFIX}{target_num}.md"
+    if not update_index(index_file, dev_dir, title, commit, new_session, active_file, today):
+        return 1
+
+    print("", file=sys.stderr)
+    print("========================================", file=sys.stderr)
+    print(f"[OK] Session {new_session} added successfully!", file=sys.stderr)
+    print("========================================", file=sys.stderr)
+    print("", file=sys.stderr)
+    print("Files updated:", file=sys.stderr)
+    print(f"  - {target_file.name if target_file else 'journal'}", file=sys.stderr)
+    print("  - index.md", file=sys.stderr)
+
+    # Auto-commit workspace changes
+    if auto_commit:
+        print("", file=sys.stderr)
+        _auto_commit_workspace(repo_root)
+
+    return 0
+
+
+# =============================================================================
+# Main Entry
+# =============================================================================
+
+def main() -> int:
+    """CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="Add a new session to journal file and update index.md"
+    )
+    parser.add_argument("--title", required=True, help="Session title")
+    parser.add_argument("--commit", default="-", help="Comma-separated commit hashes")
+    parser.add_argument("--summary", default="(Add summary)", help="Brief summary")
+    parser.add_argument("--content-file", help="Path to file with detailed content")
+    parser.add_argument("--no-commit", action="store_true",
+                        help="Skip auto-commit of workspace changes")
+
+    args = parser.parse_args()
+
+    extra_content = "(Add details)"
+    if args.content_file:
+        content_path = Path(args.content_file)
+        if content_path.is_file():
+            extra_content = content_path.read_text(encoding="utf-8")
+    elif not sys.stdin.isatty():
+        extra_content = sys.stdin.read()
+
+    return add_session(
+        args.title, args.commit, args.summary, extra_content,
+        auto_commit=not args.no_commit,
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.trellis/scripts/common/__init__.py b/.trellis/scripts/common/__init__.py
new file mode 100755
index 000000000..17729781f
--- /dev/null
+++ b/.trellis/scripts/common/__init__.py
@@ -0,0 +1,82 @@
+"""
+Common utilities for Trellis workflow scripts.
+
+This module provides shared functionality used by other Trellis scripts.
+"""
+
+import io
+import sys
+
+# =============================================================================
+# Windows Encoding Fix (MUST be at top, before any other output)
+# =============================================================================
+# On Windows, stdout defaults to the system code page (often GBK/CP936).
+# This causes UnicodeEncodeError when printing non-ASCII characters.
+#
+# Any script that imports from common will automatically get this fix.
+# =============================================================================
+
+
+def _configure_stream(stream: object) -> object:
+    """Configure a stream for UTF-8 encoding on Windows."""
+    # Try reconfigure() first (Python 3.7+, more reliable)
+    if hasattr(stream, "reconfigure"):
+        stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+        return stream
+    # Fallback: detach and rewrap with TextIOWrapper
+    elif hasattr(stream, "detach"):
+        return io.TextIOWrapper(
+            stream.detach(),  # type: ignore[union-attr]
+            encoding="utf-8",
+            errors="replace",
+        )
+    return stream
+
+
+if sys.platform == "win32":
+    sys.stdout = _configure_stream(sys.stdout)  # type: ignore[assignment]
+    sys.stderr = _configure_stream(sys.stderr)  # type: ignore[assignment]
+    sys.stdin = _configure_stream(sys.stdin)  # type: ignore[assignment]
+
+
+def configure_encoding() -> None:
+    """
+    Configure stdout/stderr/stdin for UTF-8 encoding on Windows.
+
+    This is automatically called when importing from common,
+    but can be called manually for scripts that don't import common.
+
+    Safe to call multiple times.
+    """
+    global sys
+    if sys.platform == "win32":
+        sys.stdout = _configure_stream(sys.stdout)  # type: ignore[assignment]
+        sys.stderr = _configure_stream(sys.stderr)  # type: ignore[assignment]
+        sys.stdin = _configure_stream(sys.stdin)  # type: ignore[assignment]
+
+
+from .paths import (
+    DIR_WORKFLOW,
+    DIR_WORKSPACE,
+    DIR_TASKS,
+    DIR_ARCHIVE,
+    DIR_SPEC,
+    DIR_SCRIPTS,
+    FILE_DEVELOPER,
+    FILE_CURRENT_TASK,
+    FILE_TASK_JSON,
+    FILE_JOURNAL_PREFIX,
+    get_repo_root,
+    get_developer,
+    check_developer,
+    get_tasks_dir,
+    get_workspace_dir,
+    get_active_journal_file,
+    count_lines,
+    get_current_task,
+    get_current_task_abs,
+    set_current_task,
+    clear_current_task,
+    has_current_task,
+    generate_task_date_prefix,
+)
diff --git a/.trellis/scripts/common/cli_adapter.py b/.trellis/scripts/common/cli_adapter.py
new file mode 100755
index 000000000..ce3323b44
--- /dev/null
+++ b/.trellis/scripts/common/cli_adapter.py
@@ -0,0 +1,628 @@
+"""
+CLI Adapter for Multi-Platform Support.
+
+Abstracts differences between Claude Code, OpenCode, Cursor, iFlow, Codex, Kilo, Kiro Code, Gemini CLI, Antigravity, and Qoder interfaces.
+
+Supported platforms:
+- claude: Claude Code (default)
+- opencode: OpenCode
+- cursor: Cursor IDE
+- iflow: iFlow CLI
+- codex: Codex CLI (skills-based)
+- kilo: Kilo CLI
+- kiro: Kiro Code (skills-based)
+- gemini: Gemini CLI
+- antigravity: Antigravity (workflow-based)
+- qoder: Qoder
+
+Usage:
+    from common.cli_adapter import CLIAdapter
+
+    adapter = CLIAdapter("opencode")
+    cmd = adapter.build_run_command(
+        agent="dispatch",
+        session_id="abc123",
+        prompt="Start the pipeline"
+    )
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import ClassVar, Literal
+
+Platform = Literal[
+    "claude",
+    "opencode",
+    "cursor",
+    "iflow",
+    "codex",
+    "kilo",
+    "kiro",
+    "gemini",
+    "antigravity",
+    "qoder",
+]
+
+
+@dataclass
+class CLIAdapter:
+    """Adapter for different AI coding CLI tools."""
+
+    platform: Platform
+
+    # =========================================================================
+    # Agent Name Mapping
+    # =========================================================================
+
+    # OpenCode has built-in agents that cannot be overridden
+    # See: https://github.com/sst/opencode/issues/4271
+    # Note: Class-level constant, not a dataclass field
+    _AGENT_NAME_MAP: ClassVar[dict[Platform, dict[str, str]]] = {
+        "claude": {},  # No mapping needed
+        "opencode": {
+            "plan": "trellis-plan",  # 'plan' is built-in in OpenCode
+        },
+    }
+
+    def get_agent_name(self, agent: str) -> str:
+        """Get platform-specific agent name.
+
+        Args:
+            agent: Original agent name (e.g., 'plan', 'dispatch')
+
+        Returns:
+            Platform-specific agent name (e.g., 'trellis-plan' for OpenCode)
+        """
+        mapping = self._AGENT_NAME_MAP.get(self.platform, {})
+        return mapping.get(agent, agent)
+
+    # =========================================================================
+    # Agent Path
+    # =========================================================================
+
+    @property
+    def config_dir_name(self) -> str:
+        """Get platform-specific config directory name.
+
+        Returns:
+            Directory name ('.claude', '.opencode', '.cursor', '.iflow', '.agents', '.kilocode', '.kiro', '.gemini', '.agent', or '.qoder')
+        """
+        if self.platform == "opencode":
+            return ".opencode"
+        elif self.platform == "cursor":
+            return ".cursor"
+        elif self.platform == "iflow":
+            return ".iflow"
+        elif self.platform == "codex":
+            return ".agents"
+        elif self.platform == "kilo":
+            return ".kilocode"
+        elif self.platform == "kiro":
+            return ".kiro"
+        elif self.platform == "gemini":
+            return ".gemini"
+        elif self.platform == "antigravity":
+            return ".agent"
+        elif self.platform == "qoder":
+            return ".qoder"
+        else:
+            return ".claude"
+
+    def get_config_dir(self, project_root: Path) -> Path:
+        """Get platform-specific config directory.
+
+        Args:
+            project_root: Project root directory
+
+        Returns:
+            Path to config directory (.claude, .opencode, .cursor, .iflow, .agents, .kilocode, .kiro, .gemini, .agent, or .qoder)
+        """
+        return project_root / self.config_dir_name
+
+    def get_agent_path(self, agent: str, project_root: Path) -> Path:
+        """Get path to agent definition file.
+
+        Args:
+            agent: Agent name (original, before mapping)
+            project_root: Project root directory
+
+        Returns:
+            Path to agent .md file
+        """
+        mapped_name = self.get_agent_name(agent)
+        return self.get_config_dir(project_root) / "agents" / f"{mapped_name}.md"
+
+    def get_commands_path(self, project_root: Path, *parts: str) -> Path:
+        """Get path to commands directory or specific command file.
+
+        Args:
+            project_root: Project root directory
+            *parts: Additional path parts (e.g., 'trellis', 'finish-work.md')
+
+        Returns:
+            Path to commands directory or file
+
+        Note:
+            Cursor uses prefix naming: .cursor/commands/trellis-<name>.md
+            Antigravity uses workflow directory: .agent/workflows/<name>.md
+            Claude/OpenCode use subdirectory: .claude/commands/trellis/<name>.md
+        """
+        if self.platform in ("antigravity", "kilo"):
+            workflow_dir = self.get_config_dir(project_root) / "workflows"
+            if not parts:
+                return workflow_dir
+            if len(parts) >= 2 and parts[0] == "trellis":
+                filename = parts[-1]
+                return workflow_dir / filename
+            return workflow_dir / Path(*parts)
+
+        if not parts:
+            return self.get_config_dir(project_root) / "commands"
+
+        # Cursor uses prefix naming instead of subdirectory
+        if self.platform == "cursor" and len(parts) >= 2 and parts[0] == "trellis":
+            # Convert trellis/<name>.md to trellis-<name>.md
+            filename = parts[-1]
+            return (
+                self.get_config_dir(project_root) / "commands" / f"trellis-{filename}"
+            )
+
+        return self.get_config_dir(project_root) / "commands" / Path(*parts)
+
+    def get_trellis_command_path(self, name: str) -> str:
+        """Get relative path to a trellis command file.
+
+        Args:
+            name: Command name without extension (e.g., 'finish-work', 'check-backend')
+
+        Returns:
+            Relative path string for use in JSONL entries
+
+        Note:
+            Cursor: .cursor/commands/trellis-<name>.md
+            Codex: .agents/skills/<name>/SKILL.md
+            Kiro: .kiro/skills/<name>/SKILL.md
+            Gemini: .gemini/commands/trellis/<name>.toml
+            Antigravity: .agent/workflows/<name>.md
+            Others: .{platform}/commands/trellis/<name>.md
+        """
+        if self.platform == "cursor":
+            return f".cursor/commands/trellis-{name}.md"
+        elif self.platform == "codex":
+            return f".agents/skills/{name}/SKILL.md"
+        elif self.platform == "kiro":
+            return f".kiro/skills/{name}/SKILL.md"
+        elif self.platform == "gemini":
+            return f".gemini/commands/trellis/{name}.toml"
+        elif self.platform == "antigravity":
+            return f".agent/workflows/{name}.md"
+        elif self.platform == "kilo":
+            return f".kilocode/workflows/{name}.md"
+        else:
+            return f"{self.config_dir_name}/commands/trellis/{name}.md"
+
+    # =========================================================================
+    # Environment Variables
+    # =========================================================================
+
+    def get_non_interactive_env(self) -> dict[str, str]:
+        """Get environment variables for non-interactive mode.
+
+        Returns:
+            Dict of environment variables to set
+        """
+        if self.platform == "opencode":
+            return {"OPENCODE_NON_INTERACTIVE": "1"}
+        elif self.platform == "iflow":
+            return {"IFLOW_NON_INTERACTIVE": "1"}
+        elif self.platform == "codex":
+            return {"CODEX_NON_INTERACTIVE": "1"}
+        elif self.platform == "kiro":
+            return {"KIRO_NON_INTERACTIVE": "1"}
+        elif self.platform == "gemini":
+            return {}  # Gemini CLI doesn't have a non-interactive env var
+        elif self.platform == "antigravity":
+            return {}
+        elif self.platform == "qoder":
+            return {}
+        else:
+            return {"CLAUDE_NON_INTERACTIVE": "1"}
+
+    # =========================================================================
+    # CLI Command Building
+    # =========================================================================
+
+    def build_run_command(
+        self,
+        agent: str,
+        prompt: str,
+        session_id: str | None = None,
+        skip_permissions: bool = True,
+        verbose: bool = True,
+        json_output: bool = True,
+    ) -> list[str]:
+        """Build CLI command for running an agent.
+
+        Args:
+            agent: Agent name (will be mapped if needed)
+            prompt: Prompt to send to the agent
+            session_id: Optional session ID (Claude Code only for creation)
+            skip_permissions: Whether to skip permission prompts
+            verbose: Whether to enable verbose output
+            json_output: Whether to use JSON output format
+
+        Returns:
+            List of command arguments
+        """
+        mapped_agent = self.get_agent_name(agent)
+
+        if self.platform == "opencode":
+            cmd = ["opencode", "run"]
+            cmd.extend(["--agent", mapped_agent])
+
+            # Note: OpenCode 'run' mode is non-interactive by default
+            # No equivalent to Claude Code's --dangerously-skip-permissions
+            # See: https://github.com/anomalyco/opencode/issues/9070
+
+            if json_output:
+                cmd.extend(["--format", "json"])
+
+            if verbose:
+                cmd.extend(["--log-level", "DEBUG", "--print-logs"])
+
+            # Note: OpenCode doesn't support --session-id on creation
+            # Session ID must be extracted from logs after startup
+
+            cmd.append(prompt)
+
+        elif self.platform == "iflow":
+            cmd = ["iflow", "-p"]
+            cmd.extend(["-y", "--agent", mapped_agent])
+            # iFlow doesn't support --session-id on creation
+            if verbose:
+                cmd.append("--verbose")
+            cmd.append(prompt)
+        elif self.platform == "codex":
+            cmd = ["codex", "exec"]
+            cmd.append(prompt)
+        elif self.platform == "kiro":
+            cmd = ["kiro", "run", prompt]
+        elif self.platform == "gemini":
+            cmd = ["gemini"]
+            cmd.append(prompt)
+        elif self.platform == "antigravity":
+            raise ValueError(
+                "Antigravity workflows are UI slash commands; CLI agent run is not supported."
+            )
+        elif self.platform == "qoder":
+            cmd = ["qodercli", "-p", prompt]
+
+        else:  # claude
+            cmd = ["claude", "-p"]
+            cmd.extend(["--agent", mapped_agent])
+
+            if session_id:
+                cmd.extend(["--session-id", session_id])
+
+            if skip_permissions:
+                cmd.append("--dangerously-skip-permissions")
+
+            if json_output:
+                cmd.extend(["--output-format", "stream-json"])
+
+            if verbose:
+                cmd.append("--verbose")
+
+            cmd.append(prompt)
+
+        return cmd
+
+    def build_resume_command(self, session_id: str) -> list[str]:
+        """Build CLI command for resuming a session.
+
+        Args:
+            session_id: Session ID to resume (ignored for iFlow)
+
+        Returns:
+            List of command arguments
+        """
+        if self.platform == "opencode":
+            return ["opencode", "run", "--session", session_id]
+        elif self.platform == "iflow":
+            # iFlow uses -c to continue most recent conversation
+            # session_id is ignored as iFlow doesn't support session IDs
+            return ["iflow", "-c"]
+        elif self.platform == "codex":
+            return ["codex", "resume", session_id]
+        elif self.platform == "kiro":
+            return ["kiro", "resume", session_id]
+        elif self.platform == "gemini":
+            return ["gemini", "--resume", session_id]
+        elif self.platform == "antigravity":
+            raise ValueError(
+                "Antigravity workflows are UI slash commands; CLI resume is not supported."
+            )
+        elif self.platform == "qoder":
+            return ["qodercli", "--resume", session_id]
+        else:
+            return ["claude", "--resume", session_id]
+
+    def get_resume_command_str(self, session_id: str, cwd: str | None = None) -> str:
+        """Get human-readable resume command string.
+
+        Args:
+            session_id: Session ID to resume
+            cwd: Optional working directory to cd into
+
+        Returns:
+            Command string for display
+        """
+        cmd = self.build_resume_command(session_id)
+        cmd_str = " ".join(cmd)
+
+        if cwd:
+            return f"cd {cwd} && {cmd_str}"
+        return cmd_str
+
+    # =========================================================================
+    # Platform Detection Helpers
+    # =========================================================================
+
+    @property
+    def is_opencode(self) -> bool:
+        """Check if platform is OpenCode."""
+        return self.platform == "opencode"
+
+    @property
+    def is_claude(self) -> bool:
+        """Check if platform is Claude Code."""
+        return self.platform == "claude"
+
+    @property
+    def is_cursor(self) -> bool:
+        """Check if platform is Cursor."""
+        return self.platform == "cursor"
+
+    @property
+    def is_iflow(self) -> bool:
+        """Check if platform is iFlow CLI."""
+        return self.platform == "iflow"
+
+    @property
+    def cli_name(self) -> str:
+        """Get CLI executable name.
+
+        Note: Cursor doesn't have a CLI tool, returns None-like value.
+        """
+        if self.is_opencode:
+            return "opencode"
+        elif self.is_cursor:
+            return "cursor"  # Note: Cursor is IDE-only, no CLI
+        elif self.platform == "iflow":
+            return "iflow"
+        elif self.platform == "kiro":
+            return "kiro"
+        elif self.platform == "gemini":
+            return "gemini"
+        elif self.platform == "antigravity":
+            return "agy"
+        elif self.platform == "qoder":
+            return "qodercli"
+        else:
+            return "claude"
+
+    @property
+    def supports_cli_agents(self) -> bool:
+        """Check if platform supports running agents via CLI.
+
+        Claude Code, OpenCode, and iFlow support CLI agent execution.
+        Cursor is IDE-only and doesn't support CLI agents.
+        """
+        return self.platform in ("claude", "opencode", "iflow")
+
+    # =========================================================================
+    # Session ID Handling
+    # =========================================================================
+
+    @property
+    def supports_session_id_on_create(self) -> bool:
+        """Check if platform supports specifying session ID on creation.
+
+        Claude Code: Yes (--session-id)
+        OpenCode: No (auto-generated, extract from logs)
+        iFlow: No (no session ID support)
+        """
+        return self.platform == "claude"
+
+    def extract_session_id_from_log(self, log_content: str) -> str | None:
+        """Extract session ID from log output (OpenCode only).
+
+        OpenCode generates session IDs in format: ses_xxx
+
+        Args:
+            log_content: Log file content
+
+        Returns:
+            Session ID if found, None otherwise
+        """
+        import re
+
+        # OpenCode session ID pattern
+        match = re.search(r"ses_[a-zA-Z0-9]+", log_content)
+        if match:
+            return match.group(0)
+        return None
+
+
+# =============================================================================
+# Factory Function
+# =============================================================================
+
+
+def get_cli_adapter(platform: str = "claude") -> CLIAdapter:
+    """Get CLI adapter for the specified platform.
+
+    Args:
+        platform: Platform name ('claude', 'opencode', 'cursor', 'iflow', 'codex', 'kilo', 'kiro', 'gemini', 'antigravity', or 'qoder')
+
+    Returns:
+        CLIAdapter instance
+
+    Raises:
+        ValueError: If platform is not supported
+    """
+    if platform not in (
+        "claude",
+        "opencode",
+        "cursor",
+        "iflow",
+        "codex",
+        "kilo",
+        "kiro",
+        "gemini",
+        "antigravity",
+        "qoder",
+    ):
+        raise ValueError(
+            f"Unsupported platform: {platform} (must be 'claude', 'opencode', 'cursor', 'iflow', 'codex', 'kilo', 'kiro', 'gemini', 'antigravity', or 'qoder')"
+        )
+
+    return CLIAdapter(platform=platform)  # type: ignore
+
+
+def detect_platform(project_root: Path) -> Platform:
+    """Auto-detect platform based on existing config directories.
+
+    Detection order:
+    1. TRELLIS_PLATFORM environment variable (if set)
+    2. .opencode directory exists → opencode
+    3. .iflow directory exists → iflow
+    4. .cursor directory exists (without .claude) → cursor
+    5. .agents/skills exists and no other platform dirs → codex
+    6. .kilocode directory exists → kilo
+    7. .kiro/skills exists and no other platform dirs → kiro
+    8. .gemini directory exists → gemini
+    9. .agent/workflows exists and no other platform dirs → antigravity
+    10. .qoder directory exists → qoder
+    11. Default → claude
+
+    Args:
+        project_root: Project root directory
+
+    Returns:
+        Detected platform ('claude', 'opencode', 'cursor', 'iflow', 'codex', 'kilo', 'kiro', 'gemini', 'antigravity', or 'qoder')
+    """
+    import os
+
+    # Check environment variable first
+    env_platform = os.environ.get("TRELLIS_PLATFORM", "").lower()
+    if env_platform in (
+        "claude",
+        "opencode",
+        "cursor",
+        "iflow",
+        "codex",
+        "kilo",
+        "kiro",
+        "gemini",
+        "antigravity",
+        "qoder",
+    ):
+        return env_platform  # type: ignore
+
+    # Check for .opencode directory (OpenCode-specific)
+    # Note: .claude might exist in both platforms during migration
+    if (project_root / ".opencode").is_dir():
+        return "opencode"
+
+    # Check for .iflow directory (iFlow-specific)
+    # Note: .claude might exist in both platforms during migration
+    if (project_root / ".iflow").is_dir():
+        return "iflow"
+
+    # Check for .cursor directory (Cursor-specific)
+    # Only detect as cursor if .claude doesn't exist (to avoid confusion)
+    if (project_root / ".cursor").is_dir() and not (project_root / ".claude").is_dir():
+        return "cursor"
+
+    # Check for .gemini directory (Gemini CLI-specific)
+    if (project_root / ".gemini").is_dir():
+        return "gemini"
+
+    # Check for Codex skills directory only when no other platform config exists
+    other_platform_dirs_codex = (
+        ".claude",
+        ".cursor",
+        ".iflow",
+        ".opencode",
+        ".kilocode",
+        ".kiro",
+        ".gemini",
+        ".agent",
+    )
+    has_other_platform_config = any(
+        (project_root / directory).is_dir() for directory in other_platform_dirs_codex
+    )
+    if (project_root / ".agents" / "skills").is_dir() and not has_other_platform_config:
+        return "codex"
+
+    # Check for .kilocode directory (Kilo-specific)
+    if (project_root / ".kilocode").is_dir():
+        return "kilo"
+
+    # Check for Kiro skills directory only when no other platform config exists
+    other_platform_dirs_kiro = (
+        ".claude",
+        ".cursor",
+        ".iflow",
+        ".opencode",
+        ".agents",
+        ".kilocode",
+        ".gemini",
+        ".agent",
+    )
+    has_other_platform_config = any(
+        (project_root / directory).is_dir() for directory in other_platform_dirs_kiro
+    )
+    if (project_root / ".kiro" / "skills").is_dir() and not has_other_platform_config:
+        return "kiro"
+
+    # Check for Antigravity workflow directory only when no other platform config exists
+    other_platform_dirs_antigravity = (
+        ".claude",
+        ".cursor",
+        ".iflow",
+        ".opencode",
+        ".agents",
+        ".kilocode",
+        ".kiro",
+    )
+    has_other_platform_config = any(
+        (project_root / directory).is_dir()
+        for directory in other_platform_dirs_antigravity
+    )
+    if (
+        project_root / ".agent" / "workflows"
+    ).is_dir() and not has_other_platform_config:
+        return "antigravity"
+
+    # Check for .qoder directory (Qoder-specific)
+    if (project_root / ".qoder").is_dir():
+        return "qoder"
+
+    return "claude"
+
+
+def get_cli_adapter_auto(project_root: Path) -> CLIAdapter:
+    """Get CLI adapter with auto-detected platform.
+
+    Args:
+        project_root: Project root directory
+
+    Returns:
+        CLIAdapter instance for detected platform
+    """
+    platform = detect_platform(project_root)
+    return CLIAdapter(platform=platform)
diff --git a/.trellis/scripts/common/config.py b/.trellis/scripts/common/config.py
new file mode 100755
index 000000000..601ab3205
--- /dev/null
+++ b/.trellis/scripts/common/config.py
@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""
+Trellis configuration reader.
+
+Reads settings from .trellis/config.yaml with sensible defaults.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .paths import DIR_WORKFLOW, get_repo_root
+from .worktree import parse_simple_yaml
+
+
+# Defaults
+DEFAULT_SESSION_COMMIT_MESSAGE = "chore: record journal"
+DEFAULT_MAX_JOURNAL_LINES = 2000
+
+CONFIG_FILE = "config.yaml"
+
+
+def _get_config_path(repo_root: Path | None = None) -> Path:
+    """Get path to config.yaml."""
+    root = repo_root or get_repo_root()
+    return root / DIR_WORKFLOW / CONFIG_FILE
+
+
+def _load_config(repo_root: Path | None = None) -> dict:
+    """Load and parse config.yaml. Returns empty dict on any error."""
+    config_file = _get_config_path(repo_root)
+    try:
+        content = config_file.read_text(encoding="utf-8")
+        return parse_simple_yaml(content)
+    except (OSError, IOError):
+        return {}
+
+
+def get_session_commit_message(repo_root: Path | None = None) -> str:
+    """Get the commit message for auto-committing session records."""
+    config = _load_config(repo_root)
+    return config.get("session_commit_message", DEFAULT_SESSION_COMMIT_MESSAGE)
+
+
+def get_max_journal_lines(repo_root: Path | None = None) -> int:
+    """Get the maximum lines per journal file."""
+    config = _load_config(repo_root)
+    value = config.get("max_journal_lines", DEFAULT_MAX_JOURNAL_LINES)
+    try:
+        return int(value)
+    except (ValueError, TypeError):
+        return DEFAULT_MAX_JOURNAL_LINES
+
+
+def get_hooks(event: str, repo_root: Path | None = None) -> list[str]:
+    """Get hook commands for a lifecycle event.
+
+    Args:
+        event: Event name (e.g. "after_create", "after_archive").
+        repo_root: Repository root path.
+
+    Returns:
+        List of shell commands to execute, empty if none configured.
+    """
+    config = _load_config(repo_root)
+    hooks = config.get("hooks")
+    if not isinstance(hooks, dict):
+        return []
+    commands = hooks.get(event)
+    if isinstance(commands, list):
+        return [str(c) for c in commands]
+    return []
diff --git a/.trellis/scripts/common/developer.py b/.trellis/scripts/common/developer.py
new file mode 100755
index 000000000..7f3cf0ce3
--- /dev/null
+++ b/.trellis/scripts/common/developer.py
@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""
+Developer management utilities.
+
+Provides:
+    init_developer     - Initialize developer
+    ensure_developer   - Ensure developer is initialized (exit if not)
+    show_developer_info - Show developer information
+"""
+
+from __future__ import annotations
+
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from .paths import (
+    DIR_WORKFLOW,
+    DIR_WORKSPACE,
+    DIR_TASKS,
+    FILE_DEVELOPER,
+    FILE_JOURNAL_PREFIX,
+    get_repo_root,
+    get_developer,
+    check_developer,
+)
+
+
+# =============================================================================
+# Developer Initialization
+# =============================================================================
+
+def init_developer(name: str, repo_root: Path | None = None) -> bool:
+    """Initialize developer.
+
+    Creates:
+        - .trellis/.developer file with developer info
+        - .trellis/workspace/<name>/ directory structure
+        - Initial journal file and index.md
+
+    Args:
+        name: Developer name.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        True on success, False on error.
+    """
+    if not name:
+        print("Error: developer name is required", file=sys.stderr)
+        return False
+
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    dev_file = repo_root / DIR_WORKFLOW / FILE_DEVELOPER
+    workspace_dir = repo_root / DIR_WORKFLOW / DIR_WORKSPACE / name
+
+    # Create .developer file
+    initialized_at = datetime.now().isoformat()
+    try:
+        dev_file.write_text(
+            f"name={name}\ninitialized_at={initialized_at}\n",
+            encoding="utf-8"
+        )
+    except (OSError, IOError) as e:
+        print(f"Error: Failed to create .developer file: {e}", file=sys.stderr)
+        return False
+
+    # Create workspace directory structure
+    try:
+        workspace_dir.mkdir(parents=True, exist_ok=True)
+    except (OSError, IOError) as e:
+        print(f"Error: Failed to create workspace directory: {e}", file=sys.stderr)
+        return False
+
+    # Create initial journal file
+    journal_file = workspace_dir / f"{FILE_JOURNAL_PREFIX}1.md"
+    if not journal_file.exists():
+        today = datetime.now().strftime("%Y-%m-%d")
+        journal_content = f"""# Journal - {name} (Part 1)
+
+> AI development session journal
+> Started: {today}
+
+---
+
+"""
+        try:
+            journal_file.write_text(journal_content, encoding="utf-8")
+        except (OSError, IOError) as e:
+            print(f"Error: Failed to create journal file: {e}", file=sys.stderr)
+            return False
+
+    # Create index.md with markers for auto-update
+    index_file = workspace_dir / "index.md"
+    if not index_file.exists():
+        index_content = f"""# Workspace Index - {name}
+
+> Journal tracking for AI development sessions.
+
+---
+
+## Current Status
+
+<!-- @@@auto:current-status -->
+- **Active File**: `journal-1.md`
+- **Total Sessions**: 0
+- **Last Active**: -
+<!-- @@@/auto:current-status -->
+
+---
+
+## Active Documents
+
+<!-- @@@auto:active-documents -->
+| File | Lines | Status |
+|------|-------|--------|
+| `journal-1.md` | ~0 | Active |
+<!-- @@@/auto:active-documents -->
+
+---
+
+## Session History
+
+<!-- @@@auto:session-history -->
+| # | Date | Title | Commits |
+|---|------|-------|---------|
+<!-- @@@/auto:session-history -->
+
+---
+
+## Notes
+
+- Sessions are appended to journal files
+- New journal file created when current exceeds 2000 lines
+- Use `add_session.py` to record sessions
+"""
+        try:
+            index_file.write_text(index_content, encoding="utf-8")
+        except (OSError, IOError) as e:
+            print(f"Error: Failed to create index.md: {e}", file=sys.stderr)
+            return False
+
+    print(f"Developer initialized: {name}")
+    print(f"  .developer file: {dev_file}")
+    print(f"  Workspace dir: {workspace_dir}")
+
+    return True
+
+
+def ensure_developer(repo_root: Path | None = None) -> None:
+    """Ensure developer is initialized, exit if not.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    if not check_developer(repo_root):
+        print("Error: Developer not initialized.", file=sys.stderr)
+        print(f"Run: python3 ./{DIR_WORKFLOW}/scripts/init_developer.py <your-name>", file=sys.stderr)
+        sys.exit(1)
+
+
+def show_developer_info(repo_root: Path | None = None) -> None:
+    """Show developer information.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    developer = get_developer(repo_root)
+
+    if not developer:
+        print("Developer: (not initialized)")
+    else:
+        print(f"Developer: {developer}")
+        print(f"Workspace: {DIR_WORKFLOW}/{DIR_WORKSPACE}/{developer}/")
+        print(f"Tasks: {DIR_WORKFLOW}/{DIR_TASKS}/")
+
+
+# =============================================================================
+# Main Entry (for testing)
+# =============================================================================
+
+if __name__ == "__main__":
+    show_developer_info()
diff --git a/.trellis/scripts/common/git_context.py b/.trellis/scripts/common/git_context.py
new file mode 100755
index 000000000..39b9ff509
--- /dev/null
+++ b/.trellis/scripts/common/git_context.py
@@ -0,0 +1,641 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Git and Session Context utilities.
+
+Provides:
+    output_json - Output context in JSON format
+    output_text - Output context in text format
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+from .paths import (
+    DIR_SCRIPTS,
+    DIR_SPEC,
+    DIR_TASKS,
+    DIR_WORKFLOW,
+    DIR_WORKSPACE,
+    FILE_TASK_JSON,
+    count_lines,
+    get_active_journal_file,
+    get_current_task,
+    get_developer,
+    get_repo_root,
+    get_tasks_dir,
+)
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+
+def _run_git_command(args: list[str], cwd: Path | None = None) -> tuple[int, str, str]:
+    """Run a git command and return (returncode, stdout, stderr).
+
+    Uses UTF-8 encoding with -c i18n.logOutputEncoding=UTF-8 to ensure
+    consistent output across all platforms (Windows, macOS, Linux).
+    """
+    try:
+        # Force git to output UTF-8 for consistent cross-platform behavior
+        git_args = ["git", "-c", "i18n.logOutputEncoding=UTF-8"] + args
+        result = subprocess.run(
+            git_args,
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+        return result.returncode, result.stdout, result.stderr
+    except Exception as e:
+        return 1, "", str(e)
+
+
+def _read_json_file(path: Path) -> dict | None:
+    """Read and parse a JSON file."""
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return None
+
+
+# =============================================================================
+# JSON Output
+# =============================================================================
+
+
+def get_context_json(repo_root: Path | None = None) -> dict:
+    """Get context as a dictionary.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Context dictionary.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    developer = get_developer(repo_root)
+    tasks_dir = get_tasks_dir(repo_root)
+    journal_file = get_active_journal_file(repo_root)
+
+    journal_lines = 0
+    journal_relative = ""
+    if journal_file and developer:
+        journal_lines = count_lines(journal_file)
+        journal_relative = (
+            f"{DIR_WORKFLOW}/{DIR_WORKSPACE}/{developer}/{journal_file.name}"
+        )
+
+    # Git info
+    _, branch_out, _ = _run_git_command(["branch", "--show-current"], cwd=repo_root)
+    branch = branch_out.strip() or "unknown"
+
+    _, status_out, _ = _run_git_command(["status", "--porcelain"], cwd=repo_root)
+    git_status_count = len([line for line in status_out.splitlines() if line.strip()])
+    is_clean = git_status_count == 0
+
+    # Recent commits
+    _, log_out, _ = _run_git_command(["log", "--oneline", "-5"], cwd=repo_root)
+    commits = []
+    for line in log_out.splitlines():
+        if line.strip():
+            parts = line.split(" ", 1)
+            if len(parts) >= 2:
+                commits.append({"hash": parts[0], "message": parts[1]})
+            elif len(parts) == 1:
+                commits.append({"hash": parts[0], "message": ""})
+
+    # Tasks
+    tasks = []
+    if tasks_dir.is_dir():
+        for d in tasks_dir.iterdir():
+            if d.is_dir() and d.name != "archive":
+                task_json_path = d / FILE_TASK_JSON
+                if task_json_path.is_file():
+                    data = _read_json_file(task_json_path)
+                    if data:
+                        tasks.append(
+                            {
+                                "dir": d.name,
+                                "name": data.get("name") or data.get("id") or "unknown",
+                                "status": data.get("status", "unknown"),
+                                "children": data.get("children", []),
+                                "parent": data.get("parent"),
+                            }
+                        )
+
+    return {
+        "developer": developer or "",
+        "git": {
+            "branch": branch,
+            "isClean": is_clean,
+            "uncommittedChanges": git_status_count,
+            "recentCommits": commits,
+        },
+        "tasks": {
+            "active": tasks,
+            "directory": f"{DIR_WORKFLOW}/{DIR_TASKS}",
+        },
+        "journal": {
+            "file": journal_relative,
+            "lines": journal_lines,
+            "nearLimit": journal_lines > 1800,
+        },
+    }
+
+
+def output_json(repo_root: Path | None = None) -> None:
+    """Output context in JSON format.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+    """
+    context = get_context_json(repo_root)
+    print(json.dumps(context, indent=2, ensure_ascii=False))
+
+
+# =============================================================================
+# Text Output
+# =============================================================================
+
+
+def get_context_text(repo_root: Path | None = None) -> str:
+    """Get context as formatted text.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Formatted text output.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    lines = []
+    lines.append("========================================")
+    lines.append("SESSION CONTEXT")
+    lines.append("========================================")
+    lines.append("")
+
+    developer = get_developer(repo_root)
+
+    # Developer section
+    lines.append("## DEVELOPER")
+    if not developer:
+        lines.append(
+            f"ERROR: Not initialized. Run: python3 ./{DIR_WORKFLOW}/{DIR_SCRIPTS}/init_developer.py <name>"
+        )
+        return "\n".join(lines)
+
+    lines.append(f"Name: {developer}")
+    lines.append("")
+
+    # Git status
+    lines.append("## GIT STATUS")
+    _, branch_out, _ = _run_git_command(["branch", "--show-current"], cwd=repo_root)
+    branch = branch_out.strip() or "unknown"
+    lines.append(f"Branch: {branch}")
+
+    _, status_out, _ = _run_git_command(["status", "--porcelain"], cwd=repo_root)
+    status_lines = [line for line in status_out.splitlines() if line.strip()]
+    status_count = len(status_lines)
+
+    if status_count == 0:
+        lines.append("Working directory: Clean")
+    else:
+        lines.append(f"Working directory: {status_count} uncommitted change(s)")
+        lines.append("")
+        lines.append("Changes:")
+        _, short_out, _ = _run_git_command(["status", "--short"], cwd=repo_root)
+        for line in short_out.splitlines()[:10]:
+            lines.append(line)
+    lines.append("")
+
+    # Recent commits
+    lines.append("## RECENT COMMITS")
+    _, log_out, _ = _run_git_command(["log", "--oneline", "-5"], cwd=repo_root)
+    if log_out.strip():
+        for line in log_out.splitlines():
+            lines.append(line)
+    else:
+        lines.append("(no commits)")
+    lines.append("")
+
+    # Current task
+    lines.append("## CURRENT TASK")
+    current_task = get_current_task(repo_root)
+    if current_task:
+        current_task_dir = repo_root / current_task
+        task_json_path = current_task_dir / FILE_TASK_JSON
+        lines.append(f"Path: {current_task}")
+
+        if task_json_path.is_file():
+            data = _read_json_file(task_json_path)
+            if data:
+                t_name = data.get("name") or data.get("id") or "unknown"
+                t_status = data.get("status", "unknown")
+                t_created = data.get("createdAt", "unknown")
+                t_desc = data.get("description", "")
+
+                lines.append(f"Name: {t_name}")
+                lines.append(f"Status: {t_status}")
+                lines.append(f"Created: {t_created}")
+                if t_desc:
+                    lines.append(f"Description: {t_desc}")
+
+        # Check for prd.md
+        prd_file = current_task_dir / "prd.md"
+        if prd_file.is_file():
+            lines.append("")
+            lines.append("[!] This task has prd.md - read it for task details")
+    else:
+        lines.append("(none)")
+    lines.append("")
+
+    # Active tasks
+    lines.append("## ACTIVE TASKS")
+    tasks_dir = get_tasks_dir(repo_root)
+    task_count = 0
+
+    # Collect all task data for hierarchy display
+    all_task_data: dict[str, dict] = {}
+    if tasks_dir.is_dir():
+        for d in sorted(tasks_dir.iterdir()):
+            if d.is_dir() and d.name != "archive":
+                dir_name = d.name
+                t_json = d / FILE_TASK_JSON
+                status = "unknown"
+                assignee = "-"
+                children: list[str] = []
+                parent: str | None = None
+
+                if t_json.is_file():
+                    data = _read_json_file(t_json)
+                    if data:
+                        status = data.get("status", "unknown")
+                        assignee = data.get("assignee", "-")
+                        children = data.get("children", [])
+                        parent = data.get("parent")
+
+                all_task_data[dir_name] = {
+                    "status": status,
+                    "assignee": assignee,
+                    "children": children,
+                    "parent": parent,
+                }
+
+    def _children_progress(children_list: list[str]) -> str:
+        if not children_list:
+            return ""
+        done = 0
+        for c in children_list:
+            if c in all_task_data and all_task_data[c]["status"] in ("completed", "done"):
+                done += 1
+        return f" [{done}/{len(children_list)} done]"
+
+    def _print_task_tree(name: str, indent: int = 0) -> None:
+        nonlocal task_count
+        info = all_task_data[name]
+        progress = _children_progress(info["children"]) if info["children"] else ""
+        prefix = "  " * indent
+        lines.append(f"{prefix}- {name}/ ({info['status']}){progress} @{info['assignee']}")
+        task_count += 1
+        for child in info["children"]:
+            if child in all_task_data:
+                _print_task_tree(child, indent + 1)
+
+    for dir_name in sorted(all_task_data.keys()):
+        if not all_task_data[dir_name]["parent"]:
+            _print_task_tree(dir_name)
+
+    if task_count == 0:
+        lines.append("(no active tasks)")
+    lines.append(f"Total: {task_count} active task(s)")
+    lines.append("")
+
+    # My tasks
+    lines.append("## MY TASKS (Assigned to me)")
+    my_task_count = 0
+
+    if tasks_dir.is_dir():
+        for d in sorted(tasks_dir.iterdir()):
+            if d.is_dir() and d.name != "archive":
+                t_json = d / FILE_TASK_JSON
+                if t_json.is_file():
+                    data = _read_json_file(t_json)
+                    if data:
+                        assignee = data.get("assignee", "")
+                        status = data.get("status", "planning")
+
+                        if assignee == developer and status != "done":
+                            title = data.get("title") or data.get("name") or "unknown"
+                            priority = data.get("priority", "P2")
+                            children_list = data.get("children", [])
+                            progress = _children_progress(children_list) if children_list else ""
+                            lines.append(f"- [{priority}] {title} ({status}){progress}")
+                            my_task_count += 1
+
+    if my_task_count == 0:
+        lines.append("(no tasks assigned to you)")
+    lines.append("")
+
+    # Journal file
+    lines.append("## JOURNAL FILE")
+    journal_file = get_active_journal_file(repo_root)
+    if journal_file:
+        journal_lines = count_lines(journal_file)
+        relative = f"{DIR_WORKFLOW}/{DIR_WORKSPACE}/{developer}/{journal_file.name}"
+        lines.append(f"Active file: {relative}")
+        lines.append(f"Line count: {journal_lines} / 2000")
+        if journal_lines > 1800:
+            lines.append("[!] WARNING: Approaching 2000 line limit!")
+    else:
+        lines.append("No journal file found")
+    lines.append("")
+
+    # Paths
+    lines.append("## PATHS")
+    lines.append(f"Workspace: {DIR_WORKFLOW}/{DIR_WORKSPACE}/{developer}/")
+    lines.append(f"Tasks: {DIR_WORKFLOW}/{DIR_TASKS}/")
+    lines.append(f"Spec: {DIR_WORKFLOW}/{DIR_SPEC}/")
+    lines.append("")
+
+    lines.append("========================================")
+
+    return "\n".join(lines)
+
+
+def get_context_record_json(repo_root: Path | None = None) -> dict:
+    """Get record-mode context as a dictionary.
+
+    Focused on: my active tasks, git status, current task.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    developer = get_developer(repo_root)
+    tasks_dir = get_tasks_dir(repo_root)
+
+    # Git info
+    _, branch_out, _ = _run_git_command(["branch", "--show-current"], cwd=repo_root)
+    branch = branch_out.strip() or "unknown"
+
+    _, status_out, _ = _run_git_command(["status", "--porcelain"], cwd=repo_root)
+    git_status_count = len([line for line in status_out.splitlines() if line.strip()])
+
+    _, log_out, _ = _run_git_command(["log", "--oneline", "-5"], cwd=repo_root)
+    commits = []
+    for line in log_out.splitlines():
+        if line.strip():
+            parts = line.split(" ", 1)
+            if len(parts) >= 2:
+                commits.append({"hash": parts[0], "message": parts[1]})
+
+    # My tasks
+    my_tasks = []
+    all_task_statuses: dict[str, str] = {}
+    if tasks_dir.is_dir():
+        for d in sorted(tasks_dir.iterdir()):
+            if d.is_dir() and d.name != "archive":
+                t_json = d / FILE_TASK_JSON
+                if t_json.is_file():
+                    data = _read_json_file(t_json)
+                    if data:
+                        all_task_statuses[d.name] = data.get("status", "unknown")
+
+    if tasks_dir.is_dir():
+        for d in sorted(tasks_dir.iterdir()):
+            if d.is_dir() and d.name != "archive":
+                t_json = d / FILE_TASK_JSON
+                if t_json.is_file():
+                    data = _read_json_file(t_json)
+                    if data and data.get("assignee") == developer:
+                        children_list = data.get("children", [])
+                        done = sum(1 for c in children_list if all_task_statuses.get(c) in ("completed", "done"))
+                        my_tasks.append({
+                            "dir": d.name,
+                            "title": data.get("title") or data.get("name") or "unknown",
+                            "status": data.get("status", "unknown"),
+                            "priority": data.get("priority", "P2"),
+                            "children": children_list,
+                            "childrenDone": done,
+                            "parent": data.get("parent"),
+                            "meta": data.get("meta", {}),
+                        })
+
+    # Current task
+    current_task_info = None
+    current_task = get_current_task(repo_root)
+    if current_task:
+        task_json_path = (repo_root / current_task) / FILE_TASK_JSON
+        if task_json_path.is_file():
+            data = _read_json_file(task_json_path)
+            if data:
+                current_task_info = {
+                    "path": current_task,
+                    "name": data.get("name") or data.get("id") or "unknown",
+                    "status": data.get("status", "unknown"),
+                }
+
+    return {
+        "developer": developer or "",
+        "git": {
+            "branch": branch,
+            "isClean": git_status_count == 0,
+            "uncommittedChanges": git_status_count,
+            "recentCommits": commits,
+        },
+        "myTasks": my_tasks,
+        "currentTask": current_task_info,
+    }
+
+
+def get_context_text_record(repo_root: Path | None = None) -> str:
+    """Get context as formatted text for record-session mode.
+
+    Focused output: MY ACTIVE TASKS first (with [!!!] emphasis),
+    then GIT STATUS, RECENT COMMITS, CURRENT TASK.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Formatted text output for record-session.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    lines: list[str] = []
+    lines.append("========================================")
+    lines.append("SESSION CONTEXT (RECORD MODE)")
+    lines.append("========================================")
+    lines.append("")
+
+    developer = get_developer(repo_root)
+    if not developer:
+        lines.append(
+            f"ERROR: Not initialized. Run: python3 ./{DIR_WORKFLOW}/{DIR_SCRIPTS}/init_developer.py <name>"
+        )
+        return "\n".join(lines)
+
+    # MY ACTIVE TASKS — first and prominent
+    lines.append(f"## [!!!] MY ACTIVE TASKS (Assigned to {developer})")
+    lines.append("[!] Review whether any should be archived before recording this session.")
+    lines.append("")
+
+    tasks_dir = get_tasks_dir(repo_root)
+    my_task_count = 0
+
+    # Collect task data for children progress
+    all_task_statuses: dict[str, str] = {}
+    if tasks_dir.is_dir():
+        for d in sorted(tasks_dir.iterdir()):
+            if d.is_dir() and d.name != "archive":
+                t_json = d / FILE_TASK_JSON
+                if t_json.is_file():
+                    data = _read_json_file(t_json)
+                    if data:
+                        all_task_statuses[d.name] = data.get("status", "unknown")
+
+    def _record_children_progress(children_list: list[str]) -> str:
+        if not children_list:
+            return ""
+        done = 0
+        for c in children_list:
+            if all_task_statuses.get(c) in ("completed", "done"):
+                done += 1
+        return f" [{done}/{len(children_list)} done]"
+
+    if tasks_dir.is_dir():
+        for d in sorted(tasks_dir.iterdir()):
+            if d.is_dir() and d.name != "archive":
+                t_json = d / FILE_TASK_JSON
+                if t_json.is_file():
+                    data = _read_json_file(t_json)
+                    if data:
+                        assignee = data.get("assignee", "")
+                        status = data.get("status", "planning")
+
+                        if assignee == developer:
+                            title = data.get("title") or data.get("name") or "unknown"
+                            priority = data.get("priority", "P2")
+                            children_list = data.get("children", [])
+                            progress = _record_children_progress(children_list) if children_list else ""
+                            lines.append(f"- [{priority}] {title} ({status}){progress} — {d.name}")
+                            my_task_count += 1
+
+    if my_task_count == 0:
+        lines.append("(no active tasks assigned to you)")
+    lines.append("")
+
+    # GIT STATUS
+    lines.append("## GIT STATUS")
+    _, branch_out, _ = _run_git_command(["branch", "--show-current"], cwd=repo_root)
+    branch = branch_out.strip() or "unknown"
+    lines.append(f"Branch: {branch}")
+
+    _, status_out, _ = _run_git_command(["status", "--porcelain"], cwd=repo_root)
+    status_lines = [line for line in status_out.splitlines() if line.strip()]
+    status_count = len(status_lines)
+
+    if status_count == 0:
+        lines.append("Working directory: Clean")
+    else:
+        lines.append(f"Working directory: {status_count} uncommitted change(s)")
+        lines.append("")
+        lines.append("Changes:")
+        _, short_out, _ = _run_git_command(["status", "--short"], cwd=repo_root)
+        for line in short_out.splitlines()[:10]:
+            lines.append(line)
+    lines.append("")
+
+    # RECENT COMMITS
+    lines.append("## RECENT COMMITS")
+    _, log_out, _ = _run_git_command(["log", "--oneline", "-5"], cwd=repo_root)
+    if log_out.strip():
+        for line in log_out.splitlines():
+            lines.append(line)
+    else:
+        lines.append("(no commits)")
+    lines.append("")
+
+    # CURRENT TASK
+    lines.append("## CURRENT TASK")
+    current_task = get_current_task(repo_root)
+    if current_task:
+        current_task_dir = repo_root / current_task
+        task_json_path = current_task_dir / FILE_TASK_JSON
+        lines.append(f"Path: {current_task}")
+
+        if task_json_path.is_file():
+            data = _read_json_file(task_json_path)
+            if data:
+                t_name = data.get("name") or data.get("id") or "unknown"
+                t_status = data.get("status", "unknown")
+                lines.append(f"Name: {t_name}")
+                lines.append(f"Status: {t_status}")
+    else:
+        lines.append("(none)")
+    lines.append("")
+
+    lines.append("========================================")
+
+    return "\n".join(lines)
+
+
+def output_text(repo_root: Path | None = None) -> None:
+    """Output context in text format.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+    """
+    print(get_context_text(repo_root))
+
+
+# =============================================================================
+# Main Entry
+# =============================================================================
+
+
+def main() -> None:
+    """CLI entry point."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Get Session Context for AI Agent")
+    parser.add_argument(
+        "--json",
+        "-j",
+        action="store_true",
+        help="Output in JSON format (works with any --mode)",
+    )
+    parser.add_argument(
+        "--mode",
+        "-m",
+        choices=["default", "record"],
+        default="default",
+        help="Output mode: default (full context) or record (for record-session)",
+    )
+
+    args = parser.parse_args()
+
+    if args.mode == "record":
+        if args.json:
+            print(json.dumps(get_context_record_json(), indent=2, ensure_ascii=False))
+        else:
+            print(get_context_text_record())
+    else:
+        if args.json:
+            output_json()
+        else:
+            output_text()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.trellis/scripts/common/paths.py b/.trellis/scripts/common/paths.py
new file mode 100755
index 000000000..dcbb66b49
--- /dev/null
+++ b/.trellis/scripts/common/paths.py
@@ -0,0 +1,347 @@
+#!/usr/bin/env python3
+"""
+Common path utilities for Trellis workflow.
+
+Provides:
+    get_repo_root          - Get repository root directory
+    get_developer          - Get developer name
+    get_workspace_dir      - Get developer workspace directory
+    get_tasks_dir          - Get tasks directory
+    get_active_journal_file - Get current journal file
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime
+from pathlib import Path
+
+
+# =============================================================================
+# Path Constants (change here to rename directories)
+# =============================================================================
+
+# Directory names
+DIR_WORKFLOW = ".trellis"
+DIR_WORKSPACE = "workspace"
+DIR_TASKS = "tasks"
+DIR_ARCHIVE = "archive"
+DIR_SPEC = "spec"
+DIR_SCRIPTS = "scripts"
+
+# File names
+FILE_DEVELOPER = ".developer"
+FILE_CURRENT_TASK = ".current-task"
+FILE_TASK_JSON = "task.json"
+FILE_JOURNAL_PREFIX = "journal-"
+
+
+# =============================================================================
+# Repository Root
+# =============================================================================
+
+def get_repo_root(start_path: Path | None = None) -> Path:
+    """Find the nearest directory containing .trellis/ folder.
+
+    This handles nested git repos correctly (e.g., test project inside another repo).
+
+    Args:
+        start_path: Starting directory to search from. Defaults to current directory.
+
+    Returns:
+        Path to repository root, or current directory if no .trellis/ found.
+    """
+    current = (start_path or Path.cwd()).resolve()
+
+    while current != current.parent:
+        if (current / DIR_WORKFLOW).is_dir():
+            return current
+        current = current.parent
+
+    # Fallback to current directory if no .trellis/ found
+    return Path.cwd().resolve()
+
+
+# =============================================================================
+# Developer
+# =============================================================================
+
+def get_developer(repo_root: Path | None = None) -> str | None:
+    """Get developer name from .developer file.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Developer name or None if not initialized.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    dev_file = repo_root / DIR_WORKFLOW / FILE_DEVELOPER
+
+    if not dev_file.is_file():
+        return None
+
+    try:
+        content = dev_file.read_text(encoding="utf-8")
+        for line in content.splitlines():
+            if line.startswith("name="):
+                return line.split("=", 1)[1].strip()
+    except (OSError, IOError):
+        pass
+
+    return None
+
+
+def check_developer(repo_root: Path | None = None) -> bool:
+    """Check if developer is initialized.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        True if developer is initialized.
+    """
+    return get_developer(repo_root) is not None
+
+
+# =============================================================================
+# Tasks Directory
+# =============================================================================
+
+def get_tasks_dir(repo_root: Path | None = None) -> Path:
+    """Get tasks directory path.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Path to tasks directory.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+    return repo_root / DIR_WORKFLOW / DIR_TASKS
+
+
+# =============================================================================
+# Workspace Directory
+# =============================================================================
+
+def get_workspace_dir(repo_root: Path | None = None) -> Path | None:
+    """Get developer workspace directory.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Path to workspace directory or None if developer not set.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    developer = get_developer(repo_root)
+    if developer:
+        return repo_root / DIR_WORKFLOW / DIR_WORKSPACE / developer
+    return None
+
+
+# =============================================================================
+# Journal File
+# =============================================================================
+
+def get_active_journal_file(repo_root: Path | None = None) -> Path | None:
+    """Get the current active journal file.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Path to active journal file or None if not found.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    workspace_dir = get_workspace_dir(repo_root)
+    if workspace_dir is None or not workspace_dir.is_dir():
+        return None
+
+    latest: Path | None = None
+    highest = 0
+
+    for f in workspace_dir.glob(f"{FILE_JOURNAL_PREFIX}*.md"):
+        if not f.is_file():
+            continue
+
+        # Extract number from filename
+        name = f.stem  # e.g., "journal-1"
+        match = re.search(r"(\d+)$", name)
+        if match:
+            num = int(match.group(1))
+            if num > highest:
+                highest = num
+                latest = f
+
+    return latest
+
+
+def count_lines(file_path: Path) -> int:
+    """Count lines in a file.
+
+    Args:
+        file_path: Path to file.
+
+    Returns:
+        Number of lines, or 0 if file doesn't exist.
+    """
+    if not file_path.is_file():
+        return 0
+
+    try:
+        return len(file_path.read_text(encoding="utf-8").splitlines())
+    except (OSError, IOError):
+        return 0
+
+
+# =============================================================================
+# Current Task Management
+# =============================================================================
+
+def _get_current_task_file(repo_root: Path | None = None) -> Path:
+    """Get .current-task file path.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Path to .current-task file.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+    return repo_root / DIR_WORKFLOW / FILE_CURRENT_TASK
+
+
+def get_current_task(repo_root: Path | None = None) -> str | None:
+    """Get current task directory path (relative to repo_root).
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Relative path to current task directory or None.
+    """
+    current_file = _get_current_task_file(repo_root)
+
+    if not current_file.is_file():
+        return None
+
+    try:
+        return current_file.read_text(encoding="utf-8").strip()
+    except (OSError, IOError):
+        return None
+
+
+def get_current_task_abs(repo_root: Path | None = None) -> Path | None:
+    """Get current task directory absolute path.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Absolute path to current task directory or None.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    relative = get_current_task(repo_root)
+    if relative:
+        return repo_root / relative
+    return None
+
+
+def set_current_task(task_path: str, repo_root: Path | None = None) -> bool:
+    """Set current task.
+
+    Args:
+        task_path: Task directory path (relative to repo_root).
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        True on success, False on error.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    if not task_path:
+        return False
+
+    # Verify task directory exists
+    full_path = repo_root / task_path
+    if not full_path.is_dir():
+        return False
+
+    current_file = _get_current_task_file(repo_root)
+
+    try:
+        current_file.write_text(task_path, encoding="utf-8")
+        return True
+    except (OSError, IOError):
+        return False
+
+
+def clear_current_task(repo_root: Path | None = None) -> bool:
+    """Clear current task.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        True on success.
+    """
+    current_file = _get_current_task_file(repo_root)
+
+    try:
+        if current_file.is_file():
+            current_file.unlink()
+        return True
+    except (OSError, IOError):
+        return False
+
+
+def has_current_task(repo_root: Path | None = None) -> bool:
+    """Check if has current task.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        True if current task is set.
+    """
+    return get_current_task(repo_root) is not None
+
+
+# =============================================================================
+# Task ID Generation
+# =============================================================================
+
+def generate_task_date_prefix() -> str:
+    """Generate task ID based on date (MM-DD format).
+
+    Returns:
+        Date prefix string (e.g., "01-21").
+    """
+    return datetime.now().strftime("%m-%d")
+
+
+# =============================================================================
+# Main Entry (for testing)
+# =============================================================================
+
+if __name__ == "__main__":
+    repo = get_repo_root()
+    print(f"Repository root: {repo}")
+    print(f"Developer: {get_developer(repo)}")
+    print(f"Tasks dir: {get_tasks_dir(repo)}")
+    print(f"Workspace dir: {get_workspace_dir(repo)}")
+    print(f"Journal file: {get_active_journal_file(repo)}")
+    print(f"Current task: {get_current_task(repo)}")
diff --git a/.trellis/scripts/common/phase.py b/.trellis/scripts/common/phase.py
new file mode 100755
index 000000000..c3a803940
--- /dev/null
+++ b/.trellis/scripts/common/phase.py
@@ -0,0 +1,253 @@
+#!/usr/bin/env python3
+"""
+Phase Management Utilities.
+
+Centralized phase tracking for multi-agent pipeline.
+
+Provides:
+    get_current_phase     - Returns current phase number
+    get_total_phases      - Returns total phase count
+    get_phase_action      - Returns action name for phase
+    get_phase_info        - Returns "N/M (action)" format
+    set_phase             - Sets current_phase
+    advance_phase         - Advances to next phase
+    get_phase_for_action  - Returns phase number for action
+    map_subagent_to_action - Map subagent type to action name
+    is_phase_completed    - Check if phase is completed
+    is_current_action     - Check if at specific action
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def _read_json_file(path: Path) -> dict | None:
+    """Read and parse a JSON file."""
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return None
+
+
+def _write_json_file(path: Path, data: dict) -> bool:
+    """Write dict to JSON file."""
+    try:
+        path.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+        return True
+    except (OSError, IOError):
+        return False
+
+
+# =============================================================================
+# Phase Functions
+# =============================================================================
+
+def get_current_phase(task_json: Path) -> int:
+    """Get current phase number.
+
+    Args:
+        task_json: Path to task.json file.
+
+    Returns:
+        Current phase number, or 0 if not found.
+    """
+    data = _read_json_file(task_json)
+    if not data:
+        return 0
+    return data.get("current_phase", 0) or 0
+
+
+def get_total_phases(task_json: Path) -> int:
+    """Get total number of phases.
+
+    Args:
+        task_json: Path to task.json file.
+
+    Returns:
+        Total phase count, or 0 if not found.
+    """
+    data = _read_json_file(task_json)
+    if not data:
+        return 0
+
+    next_action = data.get("next_action", [])
+    if isinstance(next_action, list):
+        return len(next_action)
+    return 0
+
+
+def get_phase_action(task_json: Path, phase: int) -> str:
+    """Get action name for a specific phase.
+
+    Args:
+        task_json: Path to task.json file.
+        phase: Phase number.
+
+    Returns:
+        Action name, or "unknown" if not found.
+    """
+    data = _read_json_file(task_json)
+    if not data:
+        return "unknown"
+
+    next_action = data.get("next_action", [])
+    if isinstance(next_action, list):
+        for item in next_action:
+            if isinstance(item, dict) and item.get("phase") == phase:
+                return item.get("action", "unknown")
+    return "unknown"
+
+
+def get_phase_info(task_json: Path) -> str:
+    """Get formatted phase info: "N/M (action)".
+
+    Args:
+        task_json: Path to task.json file.
+
+    Returns:
+        Formatted string like "1/4 (implement)".
+    """
+    data = _read_json_file(task_json)
+    if not data:
+        return "N/A"
+
+    current_phase = data.get("current_phase", 0) or 0
+    total_phases = get_total_phases(task_json)
+    action_name = get_phase_action(task_json, current_phase)
+
+    if current_phase == 0 or current_phase is None:
+        return f"0/{total_phases} (pending)"
+    else:
+        return f"{current_phase}/{total_phases} ({action_name})"
+
+
+def set_phase(task_json: Path, phase: int) -> bool:
+    """Set current phase to a specific value.
+
+    Args:
+        task_json: Path to task.json file.
+        phase: Phase number to set.
+
+    Returns:
+        True on success, False on error.
+    """
+    data = _read_json_file(task_json)
+    if not data:
+        return False
+
+    data["current_phase"] = phase
+    return _write_json_file(task_json, data)
+
+
+def advance_phase(task_json: Path) -> bool:
+    """Advance to next phase.
+
+    Args:
+        task_json: Path to task.json file.
+
+    Returns:
+        True on success, False on error or at final phase.
+    """
+    data = _read_json_file(task_json)
+    if not data:
+        return False
+
+    current = data.get("current_phase", 0) or 0
+    total = get_total_phases(task_json)
+    next_phase = current + 1
+
+    if next_phase > total:
+        return False  # Already at final phase
+
+    data["current_phase"] = next_phase
+    return _write_json_file(task_json, data)
+
+
+def get_phase_for_action(task_json: Path, action: str) -> int:
+    """Get phase number for a specific action name.
+
+    Args:
+        task_json: Path to task.json file.
+        action: Action name.
+
+    Returns:
+        Phase number, or 0 if not found.
+    """
+    data = _read_json_file(task_json)
+    if not data:
+        return 0
+
+    next_action = data.get("next_action", [])
+    if isinstance(next_action, list):
+        for item in next_action:
+            if isinstance(item, dict) and item.get("action") == action:
+                return item.get("phase", 0)
+    return 0
+
+
+def map_subagent_to_action(subagent_type: str) -> str:
+    """Map subagent type to action name.
+
+    Used by hooks to determine which action a subagent corresponds to.
+
+    Args:
+        subagent_type: Subagent type string.
+
+    Returns:
+        Corresponding action name.
+    """
+    mapping = {
+        "implement": "implement",
+        "check": "check",
+        "debug": "debug",
+        "research": "research",
+    }
+    return mapping.get(subagent_type, subagent_type)
+
+
+def is_phase_completed(task_json: Path, phase: int) -> bool:
+    """Check if a phase is completed (current_phase > phase).
+
+    Args:
+        task_json: Path to task.json file.
+        phase: Phase number to check.
+
+    Returns:
+        True if phase is completed.
+    """
+    current = get_current_phase(task_json)
+    return current > phase
+
+
+def is_current_action(task_json: Path, action: str) -> bool:
+    """Check if we're at a specific action.
+
+    Args:
+        task_json: Path to task.json file.
+        action: Action name to check.
+
+    Returns:
+        True if current phase matches the action.
+    """
+    current = get_current_phase(task_json)
+    action_phase = get_phase_for_action(task_json, action)
+    return current == action_phase
+
+
+# =============================================================================
+# Main Entry (for testing)
+# =============================================================================
+
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) > 1:
+        path = Path(sys.argv[1])
+        print(f"Task JSON: {path}")
+        print(f"Phase info: {get_phase_info(path)}")
+        print(f"Current phase: {get_current_phase(path)}")
+        print(f"Total phases: {get_total_phases(path)}")
+    else:
+        print("Usage: python3 phase.py <task.json>")
diff --git a/.trellis/scripts/common/registry.py b/.trellis/scripts/common/registry.py
new file mode 100755
index 000000000..7f2bc6f3b
--- /dev/null
+++ b/.trellis/scripts/common/registry.py
@@ -0,0 +1,366 @@
+#!/usr/bin/env python3
+"""
+Registry utility functions for multi-agent pipeline.
+
+Provides:
+    registry_get_file        - Get registry file path
+    registry_get_agent_by_id - Find agent by ID
+    registry_get_agent_by_worktree - Find agent by worktree path
+    registry_get_task_dir    - Get task dir for a worktree
+    registry_remove_by_id    - Remove agent by ID
+    registry_remove_by_worktree - Remove agent by worktree path
+    registry_add_agent       - Add agent to registry
+    registry_search_agent    - Search agent by ID or task_dir
+    registry_list_agents     - List all agents
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+
+from .paths import get_repo_root
+from .worktree import get_agents_dir
+
+
+def _read_json_file(path: Path) -> dict | None:
+    """Read and parse a JSON file."""
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return None
+
+
+def _write_json_file(path: Path, data: dict) -> bool:
+    """Write dict to JSON file."""
+    try:
+        path.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+        return True
+    except (OSError, IOError):
+        return False
+
+
+# =============================================================================
+# Registry File Access
+# =============================================================================
+
+def registry_get_file(repo_root: Path | None = None) -> Path | None:
+    """Get registry file path.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Path to registry.json, or None if agents dir not found.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    agents_dir = get_agents_dir(repo_root)
+    if agents_dir:
+        return agents_dir / "registry.json"
+    return None
+
+
+def _ensure_registry(repo_root: Path | None = None) -> Path | None:
+    """Ensure registry file exists with valid structure.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Path to registry file, or None if cannot create.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    registry_file = registry_get_file(repo_root)
+    if not registry_file:
+        return None
+
+    agents_dir = registry_file.parent
+
+    try:
+        agents_dir.mkdir(parents=True, exist_ok=True)
+
+        if not registry_file.exists():
+            _write_json_file(registry_file, {"agents": []})
+
+        return registry_file
+    except (OSError, IOError):
+        return None
+
+
+# =============================================================================
+# Agent Lookup
+# =============================================================================
+
+def registry_get_agent_by_id(
+    agent_id: str,
+    repo_root: Path | None = None
+) -> dict | None:
+    """Get agent by ID.
+
+    Args:
+        agent_id: Agent ID.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Agent dict, or None if not found.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    registry_file = registry_get_file(repo_root)
+    if not registry_file or not registry_file.is_file():
+        return None
+
+    data = _read_json_file(registry_file)
+    if not data:
+        return None
+
+    for agent in data.get("agents", []):
+        if agent.get("id") == agent_id:
+            return agent
+
+    return None
+
+
+def registry_get_agent_by_worktree(
+    worktree_path: str,
+    repo_root: Path | None = None
+) -> dict | None:
+    """Get agent by worktree path.
+
+    Args:
+        worktree_path: Worktree path.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Agent dict, or None if not found.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    registry_file = registry_get_file(repo_root)
+    if not registry_file or not registry_file.is_file():
+        return None
+
+    data = _read_json_file(registry_file)
+    if not data:
+        return None
+
+    for agent in data.get("agents", []):
+        if agent.get("worktree_path") == worktree_path:
+            return agent
+
+    return None
+
+
+def registry_search_agent(
+    search: str,
+    repo_root: Path | None = None
+) -> dict | None:
+    """Search agent by ID or task_dir containing search term.
+
+    Args:
+        search: Search term.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        First matching agent dict, or None if not found.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    registry_file = registry_get_file(repo_root)
+    if not registry_file or not registry_file.is_file():
+        return None
+
+    data = _read_json_file(registry_file)
+    if not data:
+        return None
+
+    for agent in data.get("agents", []):
+        # Exact ID match
+        if agent.get("id") == search:
+            return agent
+        # Partial match on task_dir
+        task_dir = agent.get("task_dir", "")
+        if search in task_dir:
+            return agent
+
+    return None
+
+
+def registry_get_task_dir(
+    worktree_path: str,
+    repo_root: Path | None = None
+) -> str | None:
+    """Get task directory for a worktree.
+
+    Args:
+        worktree_path: Worktree path.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Task directory path, or None if not found.
+    """
+    agent = registry_get_agent_by_worktree(worktree_path, repo_root)
+    if agent:
+        return agent.get("task_dir")
+    return None
+
+
+# =============================================================================
+# Agent Modification
+# =============================================================================
+
+def registry_remove_by_id(agent_id: str, repo_root: Path | None = None) -> bool:
+    """Remove agent by ID.
+
+    Args:
+        agent_id: Agent ID.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        True on success.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    registry_file = registry_get_file(repo_root)
+    if not registry_file or not registry_file.is_file():
+        return True  # Nothing to remove
+
+    data = _read_json_file(registry_file)
+    if not data:
+        return True
+
+    agents = data.get("agents", [])
+    data["agents"] = [a for a in agents if a.get("id") != agent_id]
+
+    return _write_json_file(registry_file, data)
+
+
+def registry_remove_by_worktree(
+    worktree_path: str,
+    repo_root: Path | None = None
+) -> bool:
+    """Remove agent by worktree path.
+
+    Args:
+        worktree_path: Worktree path.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        True on success.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    registry_file = registry_get_file(repo_root)
+    if not registry_file or not registry_file.is_file():
+        return True  # Nothing to remove
+
+    data = _read_json_file(registry_file)
+    if not data:
+        return True
+
+    agents = data.get("agents", [])
+    data["agents"] = [a for a in agents if a.get("worktree_path") != worktree_path]
+
+    return _write_json_file(registry_file, data)
+
+
+def registry_add_agent(
+    agent_id: str,
+    worktree_path: str,
+    pid: int,
+    task_dir: str,
+    repo_root: Path | None = None,
+    platform: str = "claude",
+) -> bool:
+    """Add agent to registry (replaces if same ID exists).
+
+    Args:
+        agent_id: Agent ID.
+        worktree_path: Worktree path.
+        pid: Process ID.
+        task_dir: Task directory path.
+        repo_root: Repository root path. Defaults to auto-detected.
+        platform: Platform used (e.g., 'claude', 'opencode', 'codex', 'kiro', 'antigravity'). Defaults to 'claude'.
+
+    Returns:
+        True on success.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    registry_file = _ensure_registry(repo_root)
+    if not registry_file:
+        return False
+
+    data = _read_json_file(registry_file)
+    if not data:
+        data = {"agents": []}
+
+    # Remove existing agent with same ID
+    agents = data.get("agents", [])
+    agents = [a for a in agents if a.get("id") != agent_id]
+
+    # Create new agent record
+    started_at = datetime.now().isoformat()
+    new_agent = {
+        "id": agent_id,
+        "worktree_path": worktree_path,
+        "pid": pid,
+        "started_at": started_at,
+        "task_dir": task_dir,
+        "platform": platform,
+    }
+
+    agents.append(new_agent)
+    data["agents"] = agents
+
+    return _write_json_file(registry_file, data)
+
+
+def registry_list_agents(repo_root: Path | None = None) -> list[dict]:
+    """List all agents.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        List of agent dicts.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    registry_file = registry_get_file(repo_root)
+    if not registry_file or not registry_file.is_file():
+        return []
+
+    data = _read_json_file(registry_file)
+    if not data:
+        return []
+
+    return data.get("agents", [])
+
+
+# =============================================================================
+# Main Entry (for testing)
+# =============================================================================
+
+if __name__ == "__main__":
+    import json as json_mod
+
+    repo = get_repo_root()
+    print(f"Repository root: {repo}")
+    print(f"Registry file: {registry_get_file(repo)}")
+    print()
+    print("Agents:")
+    agents = registry_list_agents(repo)
+    print(json_mod.dumps(agents, indent=2))
diff --git a/.trellis/scripts/common/task_queue.py b/.trellis/scripts/common/task_queue.py
new file mode 100755
index 000000000..70378a1d2
--- /dev/null
+++ b/.trellis/scripts/common/task_queue.py
@@ -0,0 +1,259 @@
+#!/usr/bin/env python3
+"""
+Task queue utility functions.
+
+Provides:
+    list_tasks_by_status   - List tasks by status
+    list_pending_tasks     - List tasks with pending status
+    list_tasks_by_assignee - List tasks by assignee
+    list_my_tasks          - List tasks assigned to current developer
+    get_task_stats         - Get P0/P1/P2/P3 counts
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .paths import (
+    FILE_TASK_JSON,
+    get_repo_root,
+    get_developer,
+    get_tasks_dir,
+)
+
+
+def _read_json_file(path: Path) -> dict | None:
+    """Read and parse a JSON file."""
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return None
+
+
+# =============================================================================
+# Public Functions
+# =============================================================================
+
+def list_tasks_by_status(
+    filter_status: str | None = None,
+    repo_root: Path | None = None
+) -> list[dict]:
+    """List tasks by status.
+
+    Args:
+        filter_status: Optional status filter.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        List of task info dicts with keys: priority, id, title, status, assignee.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    tasks_dir = get_tasks_dir(repo_root)
+    results = []
+
+    if not tasks_dir.is_dir():
+        return results
+
+    for d in tasks_dir.iterdir():
+        if not d.is_dir() or d.name == "archive":
+            continue
+
+        task_json = d / FILE_TASK_JSON
+        if not task_json.is_file():
+            continue
+
+        data = _read_json_file(task_json)
+        if not data:
+            continue
+
+        task_id = data.get("id", "")
+        title = data.get("title") or data.get("name", "")
+        priority = data.get("priority", "P2")
+        status = data.get("status", "planning")
+        assignee = data.get("assignee", "-")
+
+        # Apply filter
+        if filter_status and status != filter_status:
+            continue
+
+        results.append({
+            "priority": priority,
+            "id": task_id,
+            "title": title,
+            "status": status,
+            "assignee": assignee,
+            "dir": d.name,
+            "children": data.get("children", []),
+            "parent": data.get("parent"),
+        })
+
+    return results
+
+
+def list_pending_tasks(repo_root: Path | None = None) -> list[dict]:
+    """List pending tasks.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        List of task info dicts.
+    """
+    return list_tasks_by_status("planning", repo_root)
+
+
+def list_tasks_by_assignee(
+    assignee: str,
+    filter_status: str | None = None,
+    repo_root: Path | None = None
+) -> list[dict]:
+    """List tasks assigned to a specific developer.
+
+    Args:
+        assignee: Developer name.
+        filter_status: Optional status filter.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        List of task info dicts.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    tasks_dir = get_tasks_dir(repo_root)
+    results = []
+
+    if not tasks_dir.is_dir():
+        return results
+
+    for d in tasks_dir.iterdir():
+        if not d.is_dir() or d.name == "archive":
+            continue
+
+        task_json = d / FILE_TASK_JSON
+        if not task_json.is_file():
+            continue
+
+        data = _read_json_file(task_json)
+        if not data:
+            continue
+
+        task_assignee = data.get("assignee", "-")
+
+        # Apply assignee filter
+        if task_assignee != assignee:
+            continue
+
+        task_id = data.get("id", "")
+        title = data.get("title") or data.get("name", "")
+        priority = data.get("priority", "P2")
+        status = data.get("status", "planning")
+
+        # Apply status filter
+        if filter_status and status != filter_status:
+            continue
+
+        results.append({
+            "priority": priority,
+            "id": task_id,
+            "title": title,
+            "status": status,
+            "assignee": task_assignee,
+            "dir": d.name,
+            "children": data.get("children", []),
+            "parent": data.get("parent"),
+        })
+
+    return results
+
+
+def list_my_tasks(
+    filter_status: str | None = None,
+    repo_root: Path | None = None
+) -> list[dict]:
+    """List tasks assigned to current developer.
+
+    Args:
+        filter_status: Optional status filter.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        List of task info dicts.
+
+    Raises:
+        ValueError: If developer not set.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    developer = get_developer(repo_root)
+    if not developer:
+        raise ValueError("Developer not set")
+
+    return list_tasks_by_assignee(developer, filter_status, repo_root)
+
+
+def get_task_stats(repo_root: Path | None = None) -> dict[str, int]:
+    """Get task statistics.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Dict with keys: P0, P1, P2, P3, Total.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    tasks_dir = get_tasks_dir(repo_root)
+    stats = {"P0": 0, "P1": 0, "P2": 0, "P3": 0, "Total": 0}
+
+    if not tasks_dir.is_dir():
+        return stats
+
+    for d in tasks_dir.iterdir():
+        if not d.is_dir() or d.name == "archive":
+            continue
+
+        task_json = d / FILE_TASK_JSON
+        if not task_json.is_file():
+            continue
+
+        data = _read_json_file(task_json)
+        if not data:
+            continue
+
+        priority = data.get("priority", "P2")
+        if priority in stats:
+            stats[priority] += 1
+        stats["Total"] += 1
+
+    return stats
+
+
+def format_task_stats(stats: dict[str, int]) -> str:
+    """Format task stats as string.
+
+    Args:
+        stats: Stats dict from get_task_stats.
+
+    Returns:
+        Formatted string like "P0:0 P1:1 P2:2 P3:0 Total:3".
+    """
+    return f"P0:{stats['P0']} P1:{stats['P1']} P2:{stats['P2']} P3:{stats['P3']} Total:{stats['Total']}"
+
+
+# =============================================================================
+# Main Entry (for testing)
+# =============================================================================
+
+if __name__ == "__main__":
+    stats = get_task_stats()
+    print(format_task_stats(stats))
+    print()
+    print("Pending tasks:")
+    for task in list_pending_tasks():
+        print(f"  {task['priority']}|{task['id']}|{task['title']}|{task['status']}|{task['assignee']}")
diff --git a/.trellis/scripts/common/task_utils.py b/.trellis/scripts/common/task_utils.py
new file mode 100755
index 000000000..84df2fab7
--- /dev/null
+++ b/.trellis/scripts/common/task_utils.py
@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""
+Task utility functions.
+
+Provides:
+    is_safe_task_path  - Validate task path is safe to operate on
+    find_task_by_name  - Find task directory by name
+    archive_task_dir   - Archive task to monthly directory
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from .paths import get_repo_root
+
+
+# =============================================================================
+# Path Safety
+# =============================================================================
+
+def is_safe_task_path(task_path: str, repo_root: Path | None = None) -> bool:
+    """Check if a relative task path is safe to operate on.
+
+    Args:
+        task_path: Task path (relative to repo_root).
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        True if safe, False if dangerous.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    # Check empty or null
+    if not task_path or task_path == "null":
+        print("Error: empty or null task path", file=sys.stderr)
+        return False
+
+    # Reject absolute paths
+    if task_path.startswith("/"):
+        print(f"Error: absolute path not allowed: {task_path}", file=sys.stderr)
+        return False
+
+    # Reject ".", "..", paths starting with "./" or "../", or containing ".."
+    if task_path in (".", "..") or task_path.startswith("./") or task_path.startswith("../") or ".." in task_path:
+        print(f"Error: path traversal not allowed: {task_path}", file=sys.stderr)
+        return False
+
+    # Final check: ensure resolved path is not the repo root
+    abs_path = repo_root / task_path
+    if abs_path.exists():
+        try:
+            resolved = abs_path.resolve()
+            root_resolved = repo_root.resolve()
+            if resolved == root_resolved:
+                print(f"Error: path resolves to repo root: {task_path}", file=sys.stderr)
+                return False
+        except (OSError, IOError):
+            pass
+
+    return True
+
+
+# =============================================================================
+# Task Lookup
+# =============================================================================
+
+def find_task_by_name(task_name: str, tasks_dir: Path) -> Path | None:
+    """Find task directory by name (exact or suffix match).
+
+    Args:
+        task_name: Task name to find.
+        tasks_dir: Tasks directory path.
+
+    Returns:
+        Absolute path to task directory, or None if not found.
+    """
+    if not task_name or not tasks_dir or not tasks_dir.is_dir():
+        return None
+
+    # Try exact match first
+    exact_match = tasks_dir / task_name
+    if exact_match.is_dir():
+        return exact_match
+
+    # Try suffix match (e.g., "my-task" matches "01-21-my-task")
+    for d in tasks_dir.iterdir():
+        if d.is_dir() and d.name.endswith(f"-{task_name}"):
+            return d
+
+    return None
+
+
+# =============================================================================
+# Archive Operations
+# =============================================================================
+
+def archive_task_dir(task_dir_abs: Path, repo_root: Path | None = None) -> Path | None:
+    """Archive a task directory to archive/{YYYY-MM}/.
+
+    Args:
+        task_dir_abs: Absolute path to task directory.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Path to archived directory, or None on error.
+    """
+    if not task_dir_abs.is_dir():
+        print(f"Error: task directory not found: {task_dir_abs}", file=sys.stderr)
+        return None
+
+    # Get tasks directory (parent of the task)
+    tasks_dir = task_dir_abs.parent
+    archive_dir = tasks_dir / "archive"
+    year_month = datetime.now().strftime("%Y-%m")
+    month_dir = archive_dir / year_month
+
+    # Create archive directory
+    try:
+        month_dir.mkdir(parents=True, exist_ok=True)
+    except (OSError, IOError) as e:
+        print(f"Error: Failed to create archive directory: {e}", file=sys.stderr)
+        return None
+
+    # Move task to archive
+    task_name = task_dir_abs.name
+    dest = month_dir / task_name
+
+    try:
+        shutil.move(str(task_dir_abs), str(dest))
+    except (OSError, IOError, shutil.Error) as e:
+        print(f"Error: Failed to move task to archive: {e}", file=sys.stderr)
+        return None
+
+    return dest
+
+
+def archive_task_complete(
+    task_dir_abs: Path,
+    repo_root: Path | None = None
+) -> dict[str, str]:
+    """Complete archive workflow: archive directory.
+
+    Args:
+        task_dir_abs: Absolute path to task directory.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Dict with archive result info.
+    """
+    if not task_dir_abs.is_dir():
+        print(f"Error: task directory not found: {task_dir_abs}", file=sys.stderr)
+        return {}
+
+    archive_dest = archive_task_dir(task_dir_abs, repo_root)
+    if archive_dest:
+        return {"archived_to": str(archive_dest)}
+
+    return {}
+
+
+# =============================================================================
+# Main Entry (for testing)
+# =============================================================================
+
+if __name__ == "__main__":
+    from .paths import get_tasks_dir
+
+    repo = get_repo_root()
+    tasks = get_tasks_dir(repo)
+
+    print(f"Tasks dir: {tasks}")
+    print(f"is_safe_task_path('.trellis/tasks/test'): {is_safe_task_path('.trellis/tasks/test', repo)}")
+    print(f"is_safe_task_path('../test'): {is_safe_task_path('../test', repo)}")
diff --git a/.trellis/scripts/common/worktree.py b/.trellis/scripts/common/worktree.py
new file mode 100755
index 000000000..f9aa4baaf
--- /dev/null
+++ b/.trellis/scripts/common/worktree.py
@@ -0,0 +1,305 @@
+#!/usr/bin/env python3
+"""
+Worktree utilities for Multi-Agent Pipeline.
+
+Provides:
+    get_worktree_config         - Get worktree.yaml path
+    get_worktree_base_dir       - Get worktree storage directory
+    get_worktree_copy_files     - Get files to copy list
+    get_worktree_post_create_hooks - Get post-create hooks
+    get_agents_dir              - Get agents registry directory
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .paths import (
+    DIR_WORKFLOW,
+    get_repo_root,
+    get_workspace_dir,
+)
+
+
+# =============================================================================
+# YAML Simple Parser (no dependencies)
+# =============================================================================
+
+
+def _unquote(s: str) -> str:
+    """Remove exactly one layer of matching surrounding quotes.
+
+    Unlike str.strip('"'), this only removes the outermost pair,
+    preserving any nested quotes inside the value.
+
+    Examples:
+        _unquote('"hello"')        -> 'hello'
+        _unquote("'hello'")        -> 'hello'
+        _unquote('"echo \\'hi\\'"')  -> "echo 'hi'"
+        _unquote('hello')          -> 'hello'
+        _unquote('"hello\\'')       -> '"hello\\''  (mismatched, unchanged)
+    """
+    if len(s) >= 2 and s[0] == s[-1] and s[0] in ('"', "'"):
+        return s[1:-1]
+    return s
+
+
+def parse_simple_yaml(content: str) -> dict:
+    """Parse simple YAML with nested dict support (no dependencies).
+
+    Supports:
+        - key: value (string)
+        - key: (followed by list items)
+            - item1
+            - item2
+        - key: (followed by nested dict)
+            nested_key: value
+            nested_key2:
+              - item
+
+    Uses indentation to detect nesting (2+ spaces deeper = child).
+
+    Args:
+        content: YAML content string.
+
+    Returns:
+        Parsed dict (values can be str, list[str], or dict).
+    """
+    lines = content.splitlines()
+    result: dict = {}
+    _parse_yaml_block(lines, 0, 0, result)
+    return result
+
+
+def _parse_yaml_block(
+    lines: list[str], start: int, min_indent: int, target: dict
+) -> int:
+    """Parse a YAML block into target dict, returning next line index."""
+    i = start
+    current_list: list | None = None
+
+    while i < len(lines):
+        line = lines[i]
+        stripped = line.strip()
+
+        # Skip empty lines and comments
+        if not stripped or stripped.startswith("#"):
+            i += 1
+            continue
+
+        # Calculate indentation
+        indent = len(line) - len(line.lstrip())
+
+        # If dedented past our block, we're done
+        if indent < min_indent:
+            break
+
+        if stripped.startswith("- "):
+            if current_list is not None:
+                current_list.append(_unquote(stripped[2:].strip()))
+            i += 1
+        elif ":" in stripped:
+            key, _, value = stripped.partition(":")
+            key = key.strip()
+            value = _unquote(value.strip())
+            current_list = None
+
+            if value:
+                # key: value
+                target[key] = value
+                i += 1
+            else:
+                # key: (no value) — peek ahead to determine list vs nested dict
+                next_i, next_line = _next_content_line(lines, i + 1)
+                if next_i >= len(lines):
+                    target[key] = {}
+                    i = next_i
+                elif next_line.strip().startswith("- "):
+                    # It's a list
+                    current_list = []
+                    target[key] = current_list
+                    i += 1
+                else:
+                    next_indent = len(next_line) - len(next_line.lstrip())
+                    if next_indent > indent:
+                        # It's a nested dict
+                        nested: dict = {}
+                        target[key] = nested
+                        i = _parse_yaml_block(lines, i + 1, next_indent, nested)
+                    else:
+                        # Empty value, same or less indent follows
+                        target[key] = {}
+                        i += 1
+        else:
+            i += 1
+
+    return i
+
+
+def _next_content_line(lines: list[str], start: int) -> tuple[int, str]:
+    """Find the next non-empty, non-comment line."""
+    i = start
+    while i < len(lines):
+        stripped = lines[i].strip()
+        if stripped and not stripped.startswith("#"):
+            return i, lines[i]
+        i += 1
+    return i, ""
+
+
+def _yaml_get_value(config_file: Path, key: str) -> str | None:
+    """Read simple value from worktree.yaml.
+
+    Args:
+        config_file: Path to config file.
+        key: Key to read.
+
+    Returns:
+        Value string or None.
+    """
+    try:
+        content = config_file.read_text(encoding="utf-8")
+        data = parse_simple_yaml(content)
+        value = data.get(key)
+        if isinstance(value, str):
+            return value
+    except (OSError, IOError):
+        pass
+    return None
+
+
+def _yaml_get_list(config_file: Path, section: str) -> list[str]:
+    """Read list from worktree.yaml.
+
+    Args:
+        config_file: Path to config file.
+        section: Section name.
+
+    Returns:
+        List of items.
+    """
+    try:
+        content = config_file.read_text(encoding="utf-8")
+        data = parse_simple_yaml(content)
+        value = data.get(section)
+        if isinstance(value, list):
+            return [str(item) for item in value]
+    except (OSError, IOError):
+        pass
+    return []
+
+
+# =============================================================================
+# Worktree Configuration
+# =============================================================================
+
+# Worktree config file relative path (relative to repo root)
+WORKTREE_CONFIG_PATH = f"{DIR_WORKFLOW}/worktree.yaml"
+
+
+def get_worktree_config(repo_root: Path | None = None) -> Path:
+    """Get worktree.yaml config file path.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Absolute path to config file.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+    return repo_root / WORKTREE_CONFIG_PATH
+
+
+def get_worktree_base_dir(repo_root: Path | None = None) -> Path:
+    """Get worktree base directory.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Absolute path to worktree base directory.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    config = get_worktree_config(repo_root)
+    worktree_dir = _yaml_get_value(config, "worktree_dir")
+
+    # Default value
+    if not worktree_dir:
+        worktree_dir = "../worktrees"
+
+    # Handle relative path
+    if worktree_dir.startswith("../") or worktree_dir.startswith("./"):
+        # Relative to repo_root
+        return repo_root / worktree_dir
+    else:
+        # Absolute path
+        return Path(worktree_dir)
+
+
+def get_worktree_copy_files(repo_root: Path | None = None) -> list[str]:
+    """Get files to copy list.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        List of file paths to copy.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+    config = get_worktree_config(repo_root)
+    return _yaml_get_list(config, "copy")
+
+
+def get_worktree_post_create_hooks(repo_root: Path | None = None) -> list[str]:
+    """Get post_create hooks.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        List of commands to run.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+    config = get_worktree_config(repo_root)
+    return _yaml_get_list(config, "post_create")
+
+
+# =============================================================================
+# Agents Registry
+# =============================================================================
+
+def get_agents_dir(repo_root: Path | None = None) -> Path | None:
+    """Get agents directory for current developer.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Absolute path to agents directory, or None if no workspace.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    workspace_dir = get_workspace_dir(repo_root)
+    if workspace_dir:
+        return workspace_dir / ".agents"
+    return None
+
+
+# =============================================================================
+# Main Entry (for testing)
+# =============================================================================
+
+if __name__ == "__main__":
+    repo = get_repo_root()
+    print(f"Repository root: {repo}")
+    print(f"Worktree config: {get_worktree_config(repo)}")
+    print(f"Worktree base dir: {get_worktree_base_dir(repo)}")
+    print(f"Copy files: {get_worktree_copy_files(repo)}")
+    print(f"Post create hooks: {get_worktree_post_create_hooks(repo)}")
+    print(f"Agents dir: {get_agents_dir(repo)}")
diff --git a/.trellis/scripts/create_bootstrap.py b/.trellis/scripts/create_bootstrap.py
new file mode 100755
index 000000000..201146f67
--- /dev/null
+++ b/.trellis/scripts/create_bootstrap.py
@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+"""
+Create Bootstrap Task for First-Time Setup.
+
+Creates a guided task to help users fill in project guidelines
+after initializing Trellis for the first time.
+
+Usage:
+    python3 create_bootstrap.py [project-type]
+
+Arguments:
+    project-type: frontend | backend | fullstack (default: fullstack)
+
+Prerequisites:
+    - .trellis/.developer must exist (run init_developer.py first)
+
+Creates:
+    .trellis/tasks/00-bootstrap-guidelines/
+        - task.json    # Task metadata
+        - prd.md       # Task description and guidance
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from common.paths import (
+    DIR_WORKFLOW,
+    DIR_SCRIPTS,
+    DIR_TASKS,
+    get_repo_root,
+    get_developer,
+    get_tasks_dir,
+    set_current_task,
+)
+
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+TASK_NAME = "00-bootstrap-guidelines"
+
+
+# =============================================================================
+# PRD Content
+# =============================================================================
+
+def write_prd_header() -> str:
+    """Write PRD header section."""
+    return """# Bootstrap: Fill Project Development Guidelines
+
+## Purpose
+
+Welcome to Trellis! This is your first task.
+
+AI agents use `.trellis/spec/` to understand YOUR project's coding conventions.
+**Empty templates = AI writes generic code that doesn't match your project style.**
+
+Filling these guidelines is a one-time setup that pays off for every future AI session.
+
+---
+
+## Your Task
+
+Fill in the guideline files based on your **existing codebase**.
+"""
+
+
+def write_prd_backend_section() -> str:
+    """Write PRD backend section."""
+    return """
+
+### Backend Guidelines
+
+| File | What to Document |
+|------|------------------|
+| `.trellis/spec/backend/directory-structure.md` | Where different file types go (routes, services, utils) |
+| `.trellis/spec/backend/database-guidelines.md` | ORM, migrations, query patterns, naming conventions |
+| `.trellis/spec/backend/error-handling.md` | How errors are caught, logged, and returned |
+| `.trellis/spec/backend/logging-guidelines.md` | Log levels, format, what to log |
+| `.trellis/spec/backend/quality-guidelines.md` | Code review standards, testing requirements |
+"""
+
+
+def write_prd_frontend_section() -> str:
+    """Write PRD frontend section."""
+    return """
+
+### Frontend Guidelines
+
+| File | What to Document |
+|------|------------------|
+| `.trellis/spec/frontend/directory-structure.md` | Component/page/hook organization |
+| `.trellis/spec/frontend/component-guidelines.md` | Component patterns, props conventions |
+| `.trellis/spec/frontend/hook-guidelines.md` | Custom hook naming, patterns |
+| `.trellis/spec/frontend/state-management.md` | State library, patterns, what goes where |
+| `.trellis/spec/frontend/type-safety.md` | TypeScript conventions, type organization |
+| `.trellis/spec/frontend/quality-guidelines.md` | Linting, testing, accessibility |
+"""
+
+
+def write_prd_footer() -> str:
+    """Write PRD footer section."""
+    return """
+
+### Thinking Guides (Optional)
+
+The `.trellis/spec/guides/` directory contains thinking guides that are already
+filled with general best practices. You can customize them for your project if needed.
+
+---
+
+## How to Fill Guidelines
+
+### Principle: Document Reality, Not Ideals
+
+Write what your codebase **actually does**, not what you wish it did.
+AI needs to match existing patterns, not introduce new ones.
+
+### Steps
+
+1. **Look at existing code** - Find 2-3 examples of each pattern
+2. **Document the pattern** - Describe what you see
+3. **Include file paths** - Reference real files as examples
+4. **List anti-patterns** - What does your team avoid?
+
+---
+
+## Tips for Using AI
+
+Ask AI to help analyze your codebase:
+
+- "Look at my codebase and document the patterns you see"
+- "Analyze my code structure and summarize the conventions"
+- "Find error handling patterns and document them"
+
+The AI will read your code and help you document it.
+
+---
+
+## Completion Checklist
+
+- [ ] Guidelines filled for your project type
+- [ ] At least 2-3 real code examples in each guideline
+- [ ] Anti-patterns documented
+
+When done:
+
+```bash
+python3 ./.trellis/scripts/task.py finish
+python3 ./.trellis/scripts/task.py archive 00-bootstrap-guidelines
+```
+
+---
+
+## Why This Matters
+
+After completing this task:
+
+1. AI will write code that matches your project style
+2. Relevant `/trellis:before-*-dev` commands will inject real context
+3. `/trellis:check-*` commands will validate against your actual standards
+4. Future developers (human or AI) will onboard faster
+"""
+
+
+def write_prd(task_dir: Path, project_type: str) -> None:
+    """Write prd.md file."""
+    content = write_prd_header()
+
+    if project_type == "frontend":
+        content += write_prd_frontend_section()
+    elif project_type == "backend":
+        content += write_prd_backend_section()
+    else:  # fullstack
+        content += write_prd_backend_section()
+        content += write_prd_frontend_section()
+
+    content += write_prd_footer()
+
+    prd_file = task_dir / "prd.md"
+    prd_file.write_text(content, encoding="utf-8")
+
+
+# =============================================================================
+# Task JSON
+# =============================================================================
+
+def write_task_json(task_dir: Path, developer: str, project_type: str) -> None:
+    """Write task.json file."""
+    today = datetime.now().strftime("%Y-%m-%d")
+
+    # Generate subtasks and related files based on project type
+    if project_type == "frontend":
+        subtasks = [
+            {"name": "Fill frontend guidelines", "status": "pending"},
+            {"name": "Add code examples", "status": "pending"},
+        ]
+        related_files = [".trellis/spec/frontend/"]
+    elif project_type == "backend":
+        subtasks = [
+            {"name": "Fill backend guidelines", "status": "pending"},
+            {"name": "Add code examples", "status": "pending"},
+        ]
+        related_files = [".trellis/spec/backend/"]
+    else:  # fullstack
+        subtasks = [
+            {"name": "Fill backend guidelines", "status": "pending"},
+            {"name": "Fill frontend guidelines", "status": "pending"},
+            {"name": "Add code examples", "status": "pending"},
+        ]
+        related_files = [".trellis/spec/backend/", ".trellis/spec/frontend/"]
+
+    task_data = {
+        "id": TASK_NAME,
+        "name": "Bootstrap Guidelines",
+        "description": "Fill in project development guidelines for AI agents",
+        "status": "in_progress",
+        "dev_type": "docs",
+        "priority": "P1",
+        "creator": developer,
+        "assignee": developer,
+        "createdAt": today,
+        "completedAt": None,
+        "commit": None,
+        "subtasks": subtasks,
+        "children": [],
+        "parent": None,
+        "relatedFiles": related_files,
+        "notes": f"First-time setup task created by trellis init ({project_type} project)",
+        "meta": {},
+    }
+
+    task_json = task_dir / "task.json"
+    task_json.write_text(json.dumps(task_data, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+# =============================================================================
+# Main
+# =============================================================================
+
+def main() -> int:
+    """Main entry point."""
+    # Parse project type argument
+    project_type = "fullstack"
+    if len(sys.argv) > 1:
+        project_type = sys.argv[1]
+
+    # Validate project type
+    if project_type not in ("frontend", "backend", "fullstack"):
+        print(f"Unknown project type: {project_type}, defaulting to fullstack")
+        project_type = "fullstack"
+
+    repo_root = get_repo_root()
+    developer = get_developer(repo_root)
+
+    # Check developer initialized
+    if not developer:
+        print("Error: Developer not initialized")
+        print(f"Run: python3 ./{DIR_WORKFLOW}/{DIR_SCRIPTS}/init_developer.py <your-name>")
+        return 1
+
+    tasks_dir = get_tasks_dir(repo_root)
+    task_dir = tasks_dir / TASK_NAME
+    relative_path = f"{DIR_WORKFLOW}/{DIR_TASKS}/{TASK_NAME}"
+
+    # Check if already exists
+    if task_dir.exists():
+        print(f"Bootstrap task already exists: {relative_path}")
+        return 0
+
+    # Create task directory
+    task_dir.mkdir(parents=True, exist_ok=True)
+
+    # Write files
+    write_task_json(task_dir, developer, project_type)
+    write_prd(task_dir, project_type)
+
+    # Set as current task
+    set_current_task(relative_path, repo_root)
+
+    # Silent output - init command handles user-facing messages
+    # Only output the task path for programmatic use
+    print(relative_path)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.trellis/scripts/get_context.py b/.trellis/scripts/get_context.py
new file mode 100755
index 000000000..bc6346310
--- /dev/null
+++ b/.trellis/scripts/get_context.py
@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+"""
+Get Session Context for AI Agent.
+
+Usage:
+    python3 get_context.py           Output context in text format
+    python3 get_context.py --json    Output context in JSON format
+"""
+
+from __future__ import annotations
+
+from common.git_context import main
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.trellis/scripts/get_developer.py b/.trellis/scripts/get_developer.py
new file mode 100755
index 000000000..f8a89ebf6
--- /dev/null
+++ b/.trellis/scripts/get_developer.py
@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""
+Get current developer name.
+
+This is a wrapper that uses common/paths.py
+"""
+
+from __future__ import annotations
+
+import sys
+
+from common.paths import get_developer
+
+
+def main() -> None:
+    """CLI entry point."""
+    developer = get_developer()
+    if developer:
+        print(developer)
+    else:
+        print("Developer not initialized", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.trellis/scripts/init_developer.py b/.trellis/scripts/init_developer.py
new file mode 100755
index 000000000..9fb53f5cb
--- /dev/null
+++ b/.trellis/scripts/init_developer.py
@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""
+Initialize developer for workflow.
+
+Usage:
+    python3 init_developer.py <developer-name>
+
+This creates:
+    - .trellis/.developer file with developer info
+    - .trellis/workspace/<name>/ directory structure
+"""
+
+from __future__ import annotations
+
+import sys
+
+from common.paths import (
+    DIR_WORKFLOW,
+    FILE_DEVELOPER,
+    get_developer,
+)
+from common.developer import init_developer
+
+
+def main() -> None:
+    """CLI entry point."""
+    if len(sys.argv) < 2:
+        print(f"Usage: {sys.argv[0]} <developer-name>")
+        print()
+        print("Example:")
+        print(f"  {sys.argv[0]} john")
+        sys.exit(1)
+
+    name = sys.argv[1]
+
+    # Check if already initialized
+    existing = get_developer()
+    if existing:
+        print(f"Developer already initialized: {existing}")
+        print()
+        print(f"To reinitialize, remove {DIR_WORKFLOW}/{FILE_DEVELOPER} first")
+        sys.exit(0)
+
+    if init_developer(name):
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.trellis/scripts/multi_agent/__init__.py b/.trellis/scripts/multi_agent/__init__.py
new file mode 100755
index 000000000..c7c7e7dd7
--- /dev/null
+++ b/.trellis/scripts/multi_agent/__init__.py
@@ -0,0 +1,5 @@
+"""
+Multi-Agent Pipeline Scripts.
+
+This module provides orchestration for multi-agent workflows.
+"""
diff --git a/.trellis/scripts/multi_agent/cleanup.py b/.trellis/scripts/multi_agent/cleanup.py
new file mode 100755
index 000000000..f81e37044
--- /dev/null
+++ b/.trellis/scripts/multi_agent/cleanup.py
@@ -0,0 +1,403 @@
+#!/usr/bin/env python3
+"""
+Multi-Agent Pipeline: Cleanup Worktree.
+
+Usage:
+    python3 cleanup.py <branch-name>      Remove specific worktree
+    python3 cleanup.py --list             List all worktrees
+    python3 cleanup.py --merged           Remove merged worktrees
+    python3 cleanup.py --all              Remove all worktrees (with confirmation)
+
+Options:
+    -y, --yes                       Skip confirmation prompts
+    --keep-branch                   Don't delete the git branch
+
+This script:
+1. Archives task directory to archive/{YYYY-MM}/
+2. Removes agent from registry
+3. Removes git worktree
+4. Optionally deletes git branch
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from common.git_context import _run_git_command
+from common.paths import get_repo_root
+from common.registry import (
+    registry_get_file,
+    registry_get_task_dir,
+    registry_remove_by_id,
+    registry_remove_by_worktree,
+    registry_search_agent,
+)
+from common.task_utils import (
+    archive_task_complete,
+    is_safe_task_path,
+)
+
+# =============================================================================
+# Colors
+# =============================================================================
+
+
+class Colors:
+    RED = "\033[0;31m"
+    GREEN = "\033[0;32m"
+    YELLOW = "\033[1;33m"
+    BLUE = "\033[0;34m"
+    NC = "\033[0m"
+
+
+def log_info(msg: str) -> None:
+    print(f"{Colors.BLUE}[INFO]{Colors.NC} {msg}")
+
+
+def log_success(msg: str) -> None:
+    print(f"{Colors.GREEN}[SUCCESS]{Colors.NC} {msg}")
+
+
+def log_warn(msg: str) -> None:
+    print(f"{Colors.YELLOW}[WARN]{Colors.NC} {msg}")
+
+
+def log_error(msg: str) -> None:
+    print(f"{Colors.RED}[ERROR]{Colors.NC} {msg}")
+
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+
+def confirm(prompt: str, skip_confirm: bool) -> bool:
+    """Ask for confirmation."""
+    if skip_confirm:
+        return True
+
+    if not sys.stdin.isatty():
+        log_error("Non-interactive mode detected. Use -y to skip confirmation.")
+        return False
+
+    response = input(f"{prompt} [y/N] ")
+    return response.lower() in ("y", "yes")
+
+
+# =============================================================================
+# Commands
+# =============================================================================
+
+
+def cmd_list(repo_root: Path) -> int:
+    """List worktrees."""
+    print(f"{Colors.BLUE}=== Git Worktrees ==={Colors.NC}")
+    print()
+
+    subprocess.run(["git", "worktree", "list"], cwd=repo_root)
+    print()
+
+    # Show registry info
+    registry_file = registry_get_file(repo_root)
+    if registry_file and registry_file.is_file():
+        print(f"{Colors.BLUE}=== Registered Agents ==={Colors.NC}")
+        print()
+
+        import json
+
+        data = json.loads(registry_file.read_text(encoding="utf-8"))
+        agents = data.get("agents", [])
+
+        if agents:
+            for agent in agents:
+                print(
+                    f"  {agent.get('id', '?')}: PID={agent.get('pid', '?')} [{agent.get('worktree_path', '?')}]"
+                )
+        else:
+            print("  (none)")
+        print()
+
+    return 0
+
+
+def archive_task(worktree_path: str, repo_root: Path) -> None:
+    """Archive task directory."""
+    task_dir = registry_get_task_dir(worktree_path, repo_root)
+
+    if not task_dir or not is_safe_task_path(task_dir, repo_root):
+        return
+
+    task_dir_abs = repo_root / task_dir
+    if not task_dir_abs.is_dir():
+        return
+
+    result = archive_task_complete(task_dir_abs, repo_root)
+    if "archived_to" in result:
+        dest = Path(result["archived_to"])
+        log_success(f"Archived task: {dest.name} -> archive/{dest.parent.name}/")
+
+
+def cleanup_registry_only(search: str, repo_root: Path, skip_confirm: bool) -> int:
+    """Cleanup from registry only (no worktree)."""
+    agent_info = registry_search_agent(search, repo_root)
+
+    if not agent_info:
+        log_error(f"No agent found in registry matching: {search}")
+        return 1
+
+    agent_id = agent_info.get("id", "?")
+    task_dir = agent_info.get("task_dir", "?")
+
+    print()
+    print(f"{Colors.BLUE}=== Cleanup Agent (no worktree) ==={Colors.NC}")
+    print(f"  Agent ID:  {agent_id}")
+    print(f"  Task Dir:  {task_dir}")
+    print()
+
+    if not confirm("Archive task and remove from registry?", skip_confirm):
+        log_info("Aborted")
+        return 0
+
+    # Archive task directory if exists
+    if task_dir and is_safe_task_path(task_dir, repo_root):
+        task_dir_abs = repo_root / task_dir
+        if task_dir_abs.is_dir():
+            result = archive_task_complete(task_dir_abs, repo_root)
+            if "archived_to" in result:
+                dest = Path(result["archived_to"])
+                log_success(
+                    f"Archived task: {dest.name} -> archive/{dest.parent.name}/"
+                )
+    else:
+        log_warn("Invalid task_dir in registry, skipping archive")
+
+    # Remove from registry
+    registry_remove_by_id(agent_id, repo_root)
+    log_success(f"Removed from registry: {agent_id}")
+
+    log_success("Cleanup complete")
+    return 0
+
+
+def cleanup_worktree(
+    branch: str, repo_root: Path, skip_confirm: bool, keep_branch: bool
+) -> int:
+    """Cleanup single worktree."""
+    # Find worktree path for branch
+    _, worktree_list, _ = _run_git_command(
+        ["worktree", "list", "--porcelain"], cwd=repo_root
+    )
+
+    worktree_path = None
+    current_worktree = None
+
+    for line in worktree_list.splitlines():
+        if line.startswith("worktree "):
+            current_worktree = line[9:]  # Remove "worktree " prefix
+        elif line.startswith("branch refs/heads/"):
+            current_branch = line[18:]  # Remove "branch refs/heads/" prefix
+            if current_branch == branch:
+                worktree_path = current_worktree
+                break
+
+    if not worktree_path:
+        # No worktree found, try to cleanup from registry only
+        log_warn(f"No worktree found for: {branch}")
+        log_info("Trying to cleanup from registry...")
+        return cleanup_registry_only(branch, repo_root, skip_confirm)
+
+    print()
+    print(f"{Colors.BLUE}=== Cleanup Worktree ==={Colors.NC}")
+    print(f"  Branch:   {branch}")
+    print(f"  Worktree: {worktree_path}")
+    print()
+
+    if not confirm("Remove this worktree?", skip_confirm):
+        log_info("Aborted")
+        return 0
+
+    # 1. Archive task
+    archive_task(worktree_path, repo_root)
+
+    # 2. Remove from registry
+    registry_remove_by_worktree(worktree_path, repo_root)
+    log_info("Removed from registry")
+
+    # 3. Remove worktree
+    log_info("Removing worktree...")
+    ret, _, _ = _run_git_command(
+        ["worktree", "remove", worktree_path, "--force"], cwd=repo_root
+    )
+    if ret != 0:
+        # Try removing directory manually
+        try:
+            shutil.rmtree(worktree_path)
+        except Exception as e:
+            log_error(f"Failed to remove worktree: {e}")
+
+    log_success("Worktree removed")
+
+    # 4. Delete branch (optional)
+    if not keep_branch:
+        log_info("Deleting branch...")
+        ret, _, _ = _run_git_command(["branch", "-D", branch], cwd=repo_root)
+        if ret != 0:
+            log_warn("Could not delete branch (may be checked out elsewhere)")
+
+    log_success(f"Cleanup complete for: {branch}")
+    return 0
+
+
+def cmd_merged(repo_root: Path, skip_confirm: bool, keep_branch: bool) -> int:
+    """Cleanup merged worktrees."""
+    # Get main branch
+    _, head_out, _ = _run_git_command(
+        ["symbolic-ref", "refs/remotes/origin/HEAD"], cwd=repo_root
+    )
+    main_branch = head_out.strip().replace("refs/remotes/origin/", "") or "main"
+
+    print(f"{Colors.BLUE}=== Finding Merged Worktrees ==={Colors.NC}")
+    print()
+
+    # Get merged branches
+    _, merged_out, _ = _run_git_command(
+        ["branch", "--merged", main_branch], cwd=repo_root
+    )
+    merged_branches = []
+    for line in merged_out.splitlines():
+        branch = line.strip().lstrip("* ")
+        if branch and branch != main_branch:
+            merged_branches.append(branch)
+
+    if not merged_branches:
+        log_info("No merged branches found")
+        return 0
+
+    # Get worktree list
+    _, worktree_list, _ = _run_git_command(["worktree", "list"], cwd=repo_root)
+
+    worktree_branches = []
+    for branch in merged_branches:
+        if f"[{branch}]" in worktree_list:
+            worktree_branches.append(branch)
+            print(f"  - {branch}")
+
+    if not worktree_branches:
+        log_info("No merged worktrees found")
+        return 0
+
+    print()
+    if not confirm("Remove these merged worktrees?", skip_confirm):
+        log_info("Aborted")
+        return 0
+
+    for branch in worktree_branches:
+        cleanup_worktree(branch, repo_root, True, keep_branch)
+
+    return 0
+
+
+def cmd_all(repo_root: Path, skip_confirm: bool, keep_branch: bool) -> int:
+    """Cleanup all worktrees."""
+    print(f"{Colors.BLUE}=== All Worktrees ==={Colors.NC}")
+    print()
+
+    # Get worktree list
+    _, worktree_list, _ = _run_git_command(
+        ["worktree", "list", "--porcelain"], cwd=repo_root
+    )
+
+    worktrees = []
+    main_worktree = str(repo_root.resolve())
+
+    for line in worktree_list.splitlines():
+        if line.startswith("worktree "):
+            wt = line[9:]
+            if wt != main_worktree:
+                worktrees.append(wt)
+
+    if not worktrees:
+        log_info("No worktrees to remove")
+        return 0
+
+    for wt in worktrees:
+        print(f"  - {wt}")
+
+    print()
+    print(f"{Colors.RED}WARNING: This will remove ALL worktrees!{Colors.NC}")
+
+    if not confirm("Are you sure?", skip_confirm):
+        log_info("Aborted")
+        return 0
+
+    # Get branch for each worktree
+    for wt in worktrees:
+        # Find branch name from worktree list
+        _, wt_list, _ = _run_git_command(["worktree", "list"], cwd=repo_root)
+        for line in wt_list.splitlines():
+            if wt in line:
+                # Extract branch from [branch] format
+                import re
+
+                match = re.search(r"\[([^\]]+)\]", line)
+                if match:
+                    branch = match.group(1)
+                    cleanup_worktree(branch, repo_root, True, keep_branch)
+                break
+
+    return 0
+
+
+# =============================================================================
+# Main
+# =============================================================================
+
+
+def main() -> int:
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        description="Multi-Agent Pipeline: Cleanup Worktree"
+    )
+    parser.add_argument("branch", nargs="?", help="Branch name to cleanup")
+    parser.add_argument("-y", "--yes", action="store_true", help="Skip confirmation")
+    parser.add_argument(
+        "--keep-branch", action="store_true", help="Don't delete git branch"
+    )
+    parser.add_argument("--list", action="store_true", help="List all worktrees")
+    parser.add_argument("--merged", action="store_true", help="Remove merged worktrees")
+    parser.add_argument("--all", action="store_true", help="Remove all worktrees")
+
+    args = parser.parse_args()
+    repo_root = get_repo_root()
+
+    if args.list:
+        return cmd_list(repo_root)
+    elif args.merged:
+        return cmd_merged(repo_root, args.yes, args.keep_branch)
+    elif args.all:
+        return cmd_all(repo_root, args.yes, args.keep_branch)
+    elif args.branch:
+        return cleanup_worktree(args.branch, repo_root, args.yes, args.keep_branch)
+    else:
+        print("""Usage:
+  python3 cleanup.py <branch-name>      Remove specific worktree
+  python3 cleanup.py --list             List all worktrees
+  python3 cleanup.py --merged           Remove merged worktrees
+  python3 cleanup.py --all              Remove all worktrees
+
+Options:
+  -y, --yes             Skip confirmation
+  --keep-branch         Don't delete git branch
+""")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.trellis/scripts/multi_agent/create_pr.py b/.trellis/scripts/multi_agent/create_pr.py
new file mode 100755
index 000000000..54df3db61
--- /dev/null
+++ b/.trellis/scripts/multi_agent/create_pr.py
@@ -0,0 +1,329 @@
+#!/usr/bin/env python3
+"""
+Multi-Agent Pipeline: Create PR.
+
+Usage:
+    python3 create_pr.py [task-dir] [--dry-run]
+
+This script:
+1. Stages and commits all changes (excluding workspace/)
+2. Pushes to origin
+3. Creates a Draft PR using `gh pr create`
+4. Updates task.json with status="completed", pr_url, and current_phase
+
+Note: This is the only action that performs git commit, as it's the final
+step after all implementation and checks are complete.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from common.git_context import _run_git_command
+from common.paths import (
+    DIR_WORKFLOW,
+    FILE_TASK_JSON,
+    get_current_task,
+    get_repo_root,
+)
+from common.phase import get_phase_for_action
+
+# =============================================================================
+# Colors
+# =============================================================================
+
+
+class Colors:
+    RED = "\033[0;31m"
+    GREEN = "\033[0;32m"
+    YELLOW = "\033[1;33m"
+    BLUE = "\033[0;34m"
+    NC = "\033[0m"
+
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+
+def _read_json_file(path: Path) -> dict | None:
+    """Read and parse a JSON file."""
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return None
+
+
+def _write_json_file(path: Path, data: dict) -> bool:
+    """Write dict to JSON file."""
+    try:
+        path.write_text(
+            json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8"
+        )
+        return True
+    except (OSError, IOError):
+        return False
+
+
+# =============================================================================
+# Main
+# =============================================================================
+
+
+def main() -> int:
+    """Main entry point."""
+    parser = argparse.ArgumentParser(description="Multi-Agent Pipeline: Create PR")
+    parser.add_argument("dir", nargs="?", help="Task directory")
+    parser.add_argument(
+        "--dry-run", action="store_true", help="Show what would be done"
+    )
+
+    args = parser.parse_args()
+    repo_root = get_repo_root()
+
+    # =============================================================================
+    # Get Task Directory
+    # =============================================================================
+    target_dir = args.dir
+    if not target_dir:
+        # Try to get from .current-task
+        current_task = get_current_task(repo_root)
+        if current_task:
+            target_dir = current_task
+
+    if not target_dir:
+        print(
+            f"{Colors.RED}Error: No task directory specified and no current task set{Colors.NC}"
+        )
+        print("Usage: python3 create_pr.py [task-dir] [--dry-run]")
+        return 1
+
+    # Support relative paths
+    if not target_dir.startswith("/"):
+        target_dir_path = repo_root / target_dir
+    else:
+        target_dir_path = Path(target_dir)
+
+    task_json = target_dir_path / FILE_TASK_JSON
+    if not task_json.is_file():
+        print(f"{Colors.RED}Error: task.json not found at {target_dir_path}{Colors.NC}")
+        return 1
+
+    # =============================================================================
+    # Main
+    # =============================================================================
+    print(f"{Colors.BLUE}=== Create PR ==={Colors.NC}")
+    if args.dry_run:
+        print(
+            f"{Colors.YELLOW}[DRY-RUN MODE] No actual changes will be made{Colors.NC}"
+        )
+    print()
+
+    # Read task config
+    task_data = _read_json_file(task_json)
+    if not task_data:
+        print(f"{Colors.RED}Error: Failed to read task.json{Colors.NC}")
+        return 1
+
+    task_name = task_data.get("name", "")
+    base_branch = task_data.get("base_branch", "main")
+    scope = task_data.get("scope", "core")
+    dev_type = task_data.get("dev_type", "feature")
+
+    # Map dev_type to commit prefix
+    prefix_map = {
+        "feature": "feat",
+        "frontend": "feat",
+        "backend": "feat",
+        "fullstack": "feat",
+        "bugfix": "fix",
+        "fix": "fix",
+        "refactor": "refactor",
+        "docs": "docs",
+        "test": "test",
+    }
+    commit_prefix = prefix_map.get(dev_type, "feat")
+
+    print(f"Task: {task_name}")
+    print(f"Base branch: {base_branch}")
+    print(f"Scope: {scope}")
+    print(f"Commit prefix: {commit_prefix}")
+    print()
+
+    # Get current branch
+    _, branch_out, _ = _run_git_command(["branch", "--show-current"])
+    current_branch = branch_out.strip()
+    print(f"Current branch: {current_branch}")
+
+    # Check for changes
+    print(f"{Colors.YELLOW}Checking for changes...{Colors.NC}")
+
+    # Stage changes
+    _run_git_command(["add", "-A"])
+
+    # Exclude workspace and temp files
+    _run_git_command(["reset", f"{DIR_WORKFLOW}/workspace/"])
+    _run_git_command(["reset", ".agent-log", ".session-id"])
+
+    # Check if there are staged changes
+    ret, _, _ = _run_git_command(["diff", "--cached", "--quiet"])
+    has_staged_changes = ret != 0
+
+    if not has_staged_changes:
+        print(f"{Colors.YELLOW}No staged changes to commit{Colors.NC}")
+
+        # Check for unpushed commits
+        ret, log_out, _ = _run_git_command(
+            ["log", f"origin/{current_branch}..HEAD", "--oneline"]
+        )
+        unpushed = len([line for line in log_out.splitlines() if line.strip()])
+
+        if unpushed == 0:
+            if args.dry_run:
+                _run_git_command(["reset", "HEAD"])
+            print(f"{Colors.RED}No changes to create PR{Colors.NC}")
+            return 1
+
+        print(f"Found {unpushed} unpushed commit(s)")
+    else:
+        # Commit changes
+        print(f"{Colors.YELLOW}Committing changes...{Colors.NC}")
+        commit_msg = f"{commit_prefix}({scope}): {task_name}"
+
+        if args.dry_run:
+            print(f"[DRY-RUN] Would commit with message: {commit_msg}")
+            print("[DRY-RUN] Staged files:")
+            _, staged_out, _ = _run_git_command(["diff", "--cached", "--name-only"])
+            for line in staged_out.splitlines():
+                print(f"  - {line}")
+        else:
+            _run_git_command(["commit", "-m", commit_msg])
+            print(f"{Colors.GREEN}Committed: {commit_msg}{Colors.NC}")
+
+    # Push to remote
+    print(f"{Colors.YELLOW}Pushing to remote...{Colors.NC}")
+    if args.dry_run:
+        print(f"[DRY-RUN] Would push to: origin/{current_branch}")
+    else:
+        ret, _, err = _run_git_command(["push", "-u", "origin", current_branch])
+        if ret != 0:
+            print(f"{Colors.RED}Failed to push: {err}{Colors.NC}")
+            return 1
+        print(f"{Colors.GREEN}Pushed to origin/{current_branch}{Colors.NC}")
+
+    # Create PR
+    print(f"{Colors.YELLOW}Creating PR...{Colors.NC}")
+    pr_title = f"{commit_prefix}({scope}): {task_name}"
+    pr_url = ""
+
+    if args.dry_run:
+        print("[DRY-RUN] Would create PR:")
+        print(f"  Title: {pr_title}")
+        print(f"  Base:  {base_branch}")
+        print(f"  Head:  {current_branch}")
+        prd_file = target_dir_path / "prd.md"
+        if prd_file.is_file():
+            print("  Body:  (from prd.md)")
+        pr_url = "https://github.com/example/repo/pull/DRY-RUN"
+    else:
+        # Check if PR already exists
+        result = subprocess.run(
+            [
+                "gh",
+                "pr",
+                "list",
+                "--head",
+                current_branch,
+                "--base",
+                base_branch,
+                "--json",
+                "url",
+                "--jq",
+                ".[0].url",
+            ],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+        existing_pr = result.stdout.strip()
+
+        if existing_pr:
+            print(f"{Colors.YELLOW}PR already exists: {existing_pr}{Colors.NC}")
+            pr_url = existing_pr
+        else:
+            # Read PRD as PR body
+            pr_body = ""
+            prd_file = target_dir_path / "prd.md"
+            if prd_file.is_file():
+                pr_body = prd_file.read_text(encoding="utf-8")
+
+            # Create PR
+            result = subprocess.run(
+                [
+                    "gh",
+                    "pr",
+                    "create",
+                    "--draft",
+                    "--base",
+                    base_branch,
+                    "--title",
+                    pr_title,
+                    "--body",
+                    pr_body,
+                ],
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+            )
+
+            if result.returncode != 0:
+                print(f"{Colors.RED}Failed to create PR: {result.stderr}{Colors.NC}")
+                return 1
+
+            pr_url = result.stdout.strip()
+            print(f"{Colors.GREEN}PR created: {pr_url}{Colors.NC}")
+
+    # Update task.json
+    print(f"{Colors.YELLOW}Updating task status...{Colors.NC}")
+    if args.dry_run:
+        print("[DRY-RUN] Would update task.json:")
+        print("  status: completed")
+        print(f"  pr_url: {pr_url}")
+        print("  current_phase: (set to create-pr phase)")
+    else:
+        # Get the phase number for create-pr action
+        create_pr_phase = get_phase_for_action(task_json, "create-pr")
+        if not create_pr_phase:
+            create_pr_phase = 4  # Default fallback
+
+        task_data["status"] = "completed"
+        task_data["pr_url"] = pr_url
+        task_data["current_phase"] = create_pr_phase
+
+        _write_json_file(task_json, task_data)
+        print(
+            f"{Colors.GREEN}Task status updated to 'completed', phase {create_pr_phase}{Colors.NC}"
+        )
+
+    # In dry-run, reset the staging area
+    if args.dry_run:
+        _run_git_command(["reset", "HEAD"])
+
+    print()
+    print(f"{Colors.GREEN}=== PR Created Successfully ==={Colors.NC}")
+    print(f"PR URL: {pr_url}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.trellis/scripts/multi_agent/plan.py b/.trellis/scripts/multi_agent/plan.py
new file mode 100755
index 000000000..7ce5e6f3a
--- /dev/null
+++ b/.trellis/scripts/multi_agent/plan.py
@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+"""
+Multi-Agent Pipeline: Plan Agent Launcher.
+
+Usage: python3 plan.py --name <task-name> --type <dev-type> --requirement "<requirement>"
+
+This script:
+1. Creates task directory
+2. Starts Plan Agent in background
+3. Plan Agent produces fully configured task directory
+
+After completion, use start.py to launch the Dispatch Agent.
+
+Prerequisites:
+    - agents/plan.md must exist (in .claude/, .cursor/, .iflow/, or .opencode/)
+    - Developer must be initialized
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from common.cli_adapter import get_cli_adapter
+from common.paths import get_repo_root
+from common.developer import ensure_developer
+
+
+# =============================================================================
+# Colors
+# =============================================================================
+
+class Colors:
+    RED = "\033[0;31m"
+    GREEN = "\033[0;32m"
+    YELLOW = "\033[1;33m"
+    BLUE = "\033[0;34m"
+    NC = "\033[0m"
+
+
+def log_info(msg: str) -> None:
+    print(f"{Colors.BLUE}[INFO]{Colors.NC} {msg}")
+
+
+def log_success(msg: str) -> None:
+    print(f"{Colors.GREEN}[SUCCESS]{Colors.NC} {msg}")
+
+
+def log_error(msg: str) -> None:
+    print(f"{Colors.RED}[ERROR]{Colors.NC} {msg}")
+
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+DEFAULT_PLATFORM = "claude"
+
+
+# =============================================================================
+# Main
+# =============================================================================
+
+def main() -> int:
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        description="Multi-Agent Pipeline: Plan Agent Launcher"
+    )
+    parser.add_argument("--name", "-n", required=True, help="Task name (e.g., user-auth)")
+    parser.add_argument("--type", "-t", required=True, help="Dev type: backend|frontend|fullstack")
+    parser.add_argument("--requirement", "-r", required=True, help="Requirement description")
+    parser.add_argument(
+        "--platform", "-p",
+        choices=["claude", "cursor", "iflow", "opencode", "qoder"],
+        default=DEFAULT_PLATFORM,
+        help="Platform to use (default: claude)"
+    )
+
+    args = parser.parse_args()
+
+    task_name = args.name
+    dev_type = args.type
+    requirement = args.requirement
+    platform = args.platform
+
+    # Initialize CLI adapter
+    adapter = get_cli_adapter(platform)
+
+    # Validate dev type
+    if dev_type not in ("backend", "frontend", "fullstack"):
+        log_error(f"Invalid dev type: {dev_type} (must be: backend, frontend, fullstack)")
+        return 1
+
+    project_root = get_repo_root()
+
+    # Check plan agent exists (path varies by platform)
+    plan_md = adapter.get_agent_path("plan", project_root)
+    if not plan_md.is_file():
+        log_error(f"plan agent not found at {plan_md}")
+        log_info(f"Platform: {platform}")
+        return 1
+
+    ensure_developer(project_root)
+
+    # =============================================================================
+    # Step 1: Create Task Directory
+    # =============================================================================
+    print()
+    print(f"{Colors.BLUE}=== Multi-Agent Pipeline: Plan ==={Colors.NC}")
+    log_info(f"Task: {task_name}")
+    log_info(f"Type: {dev_type}")
+    log_info(f"Requirement: {requirement}")
+    print()
+
+    log_info("Step 1: Creating task directory...")
+
+    # Import task module to create task
+    from task import cmd_create
+    import argparse as ap
+
+    # Create task using task.py's create command
+    create_args = ap.Namespace(
+        title=requirement,
+        slug=task_name,
+        assignee=None,
+        priority="P2",
+        description=""
+    )
+
+    # Capture stdout to get task dir
+    import io
+    from contextlib import redirect_stdout
+
+    stdout_capture = io.StringIO()
+    with redirect_stdout(stdout_capture):
+        ret = cmd_create(create_args)
+
+    if ret != 0:
+        log_error("Failed to create task directory")
+        return 1
+
+    task_dir = stdout_capture.getvalue().strip().split("\n")[-1]
+    task_dir_abs = project_root / task_dir
+
+    log_success(f"Task directory: {task_dir}")
+
+    # =============================================================================
+    # Step 2: Prepare and Start Plan Agent
+    # =============================================================================
+    log_info("Step 2: Starting Plan Agent in background...")
+
+    log_file = task_dir_abs / ".plan-log"
+    log_file.touch()
+
+    # Get proxy environment variables
+    https_proxy = os.environ.get("https_proxy", "")
+    http_proxy = os.environ.get("http_proxy", "")
+    all_proxy = os.environ.get("all_proxy", "")
+
+    # Start agent in background (cross-platform, no shell script needed)
+    env = os.environ.copy()
+    env["PLAN_TASK_NAME"] = task_name
+    env["PLAN_DEV_TYPE"] = dev_type
+    env["PLAN_TASK_DIR"] = task_dir
+    env["PLAN_REQUIREMENT"] = requirement
+    env["https_proxy"] = https_proxy
+    env["http_proxy"] = http_proxy
+    env["all_proxy"] = all_proxy
+
+    # Clear nested-session detection so the new CLI process can start
+    env.pop("CLAUDECODE", None)
+
+    # Set non-interactive env var based on platform
+    env.update(adapter.get_non_interactive_env())
+
+    # Build CLI command using adapter
+    cli_cmd = adapter.build_run_command(
+        agent="plan",  # Will be mapped to "trellis-plan" for OpenCode
+        prompt=f"Start planning for task: {task_name}",
+        skip_permissions=True,
+        verbose=True,
+        json_output=True,
+    )
+
+    with log_file.open("w") as log_f:
+        # Use shell=False for cross-platform compatibility
+        # creationflags for Windows, start_new_session for Unix
+        popen_kwargs = {
+            "stdout": log_f,
+            "stderr": subprocess.STDOUT,
+            "cwd": str(project_root),
+            "env": env,
+        }
+        if sys.platform == "win32":
+            popen_kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+        else:
+            popen_kwargs["start_new_session"] = True
+
+        process = subprocess.Popen(cli_cmd, **popen_kwargs)
+    agent_pid = process.pid
+
+    log_success(f"Plan Agent started (PID: {agent_pid})")
+
+    # =============================================================================
+    # Summary
+    # =============================================================================
+    print()
+    print(f"{Colors.GREEN}=== Plan Agent Running ==={Colors.NC}")
+    print()
+    print(f"  Task:  {task_name}")
+    print(f"  Type:  {dev_type}")
+    print(f"  Dir:   {task_dir}")
+    print(f"  Log:   {log_file}")
+    print(f"  PID:   {agent_pid}")
+    print()
+    print(f"{Colors.YELLOW}To monitor:{Colors.NC}")
+    print(f"  tail -f {log_file}")
+    print()
+    print(f"{Colors.YELLOW}To check status:{Colors.NC}")
+    print(f"  ps -p {agent_pid}")
+    print(f"  ls -la {task_dir}")
+    print()
+    print(f"{Colors.YELLOW}After completion, run:{Colors.NC}")
+    print(f"  python3 ./.trellis/scripts/multi_agent/start.py {task_dir}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.trellis/scripts/multi_agent/start.py b/.trellis/scripts/multi_agent/start.py
new file mode 100755
index 000000000..40c2747e7
--- /dev/null
+++ b/.trellis/scripts/multi_agent/start.py
@@ -0,0 +1,465 @@
+#!/usr/bin/env python3
+"""
+Multi-Agent Pipeline: Start Worktree Agent.
+
+Usage: python3 start.py <task-dir>
+Example: python3 start.py .trellis/tasks/01-21-my-task
+
+This script:
+1. Creates worktree (if not exists) with dependency install
+2. Copies environment files (from worktree.yaml config)
+3. Sets .current-task in worktree
+4. Starts claude agent in background
+5. Registers agent to registry.json
+
+Prerequisites:
+    - task.json must exist with 'branch' field
+    - agents/dispatch.md must exist (in .claude/, .cursor/, .iflow/, or .opencode/)
+
+Configuration: .trellis/worktree.yaml
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import uuid
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from common.cli_adapter import CLIAdapter, get_cli_adapter
+from common.git_context import _run_git_command
+from common.paths import (
+    DIR_WORKFLOW,
+    FILE_CURRENT_TASK,
+    FILE_TASK_JSON,
+    get_repo_root,
+)
+from common.registry import (
+    registry_add_agent,
+    registry_get_file,
+)
+from common.worktree import (
+    get_worktree_base_dir,
+    get_worktree_config,
+    get_worktree_copy_files,
+    get_worktree_post_create_hooks,
+)
+
+# =============================================================================
+# Colors
+# =============================================================================
+
+
+class Colors:
+    RED = "\033[0;31m"
+    GREEN = "\033[0;32m"
+    YELLOW = "\033[1;33m"
+    BLUE = "\033[0;34m"
+    NC = "\033[0m"
+
+
+def log_info(msg: str) -> None:
+    print(f"{Colors.BLUE}[INFO]{Colors.NC} {msg}")
+
+
+def log_success(msg: str) -> None:
+    print(f"{Colors.GREEN}[SUCCESS]{Colors.NC} {msg}")
+
+
+def log_warn(msg: str) -> None:
+    print(f"{Colors.YELLOW}[WARN]{Colors.NC} {msg}")
+
+
+def log_error(msg: str) -> None:
+    print(f"{Colors.RED}[ERROR]{Colors.NC} {msg}")
+
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+
+def _read_json_file(path: Path) -> dict | None:
+    """Read and parse a JSON file."""
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return None
+
+
+def _write_json_file(path: Path, data: dict) -> bool:
+    """Write dict to JSON file."""
+    try:
+        path.write_text(
+            json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8"
+        )
+        return True
+    except (OSError, IOError):
+        return False
+
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+DEFAULT_PLATFORM = "claude"
+
+
+# =============================================================================
+# Main
+# =============================================================================
+
+
+def main() -> int:
+    """Main entry point."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Multi-Agent Pipeline: Start Worktree Agent")
+    parser.add_argument("task_dir", help="Task directory path")
+    parser.add_argument(
+        "--platform", "-p",
+        choices=["claude", "cursor", "iflow", "opencode", "qoder"],
+        default=DEFAULT_PLATFORM,
+        help="Platform to use (default: claude)"
+    )
+
+    args = parser.parse_args()
+    task_dir_arg = args.task_dir
+    platform = args.platform
+
+    # Initialize CLI adapter
+    adapter = get_cli_adapter(platform)
+
+    project_root = get_repo_root()
+
+    # Normalize paths
+    if task_dir_arg.startswith("/"):
+        task_dir_relative = task_dir_arg[len(str(project_root)) + 1 :]
+        task_dir_abs = Path(task_dir_arg)
+    else:
+        task_dir_relative = task_dir_arg
+        task_dir_abs = project_root / task_dir_arg
+
+    task_json_path = task_dir_abs / FILE_TASK_JSON
+
+    # =============================================================================
+    # Validation
+    # =============================================================================
+    if not task_json_path.is_file():
+        log_error(f"task.json not found at {task_json_path}")
+        return 1
+
+    dispatch_md = adapter.get_agent_path("dispatch", project_root)
+    if not dispatch_md.is_file():
+        log_error(f"dispatch.md not found at {dispatch_md}")
+        log_info(f"Platform: {platform}")
+        return 1
+
+    config_file = get_worktree_config(project_root)
+    if not config_file.is_file():
+        log_error(f"worktree.yaml not found at {config_file}")
+        return 1
+
+    # =============================================================================
+    # Read Task Config
+    # =============================================================================
+    print()
+    print(f"{Colors.BLUE}=== Multi-Agent Pipeline: Start ==={Colors.NC}")
+    log_info(f"Task: {task_dir_abs}")
+
+    task_data = _read_json_file(task_json_path)
+    if not task_data:
+        log_error("Failed to read task.json")
+        return 1
+
+    branch = task_data.get("branch")
+    task_name = task_data.get("name")
+    task_status = task_data.get("status")
+    worktree_path = task_data.get("worktree_path")
+
+    # Check if task was rejected
+    if task_status == "rejected":
+        log_error("Task was rejected by Plan Agent")
+        rejected_file = task_dir_abs / "REJECTED.md"
+        if rejected_file.is_file():
+            print()
+            print(f"{Colors.YELLOW}Rejection reason:{Colors.NC}")
+            print(rejected_file.read_text(encoding="utf-8"))
+        print()
+        log_info(
+            "To retry, delete this directory and run plan.py again with revised requirements"
+        )
+        return 1
+
+    # Check if prd.md exists (plan completed successfully)
+    prd_file = task_dir_abs / "prd.md"
+    if not prd_file.is_file():
+        log_error("prd.md not found - Plan Agent may not have completed")
+        log_info(f"Check plan log: {task_dir_abs}/.plan-log")
+        return 1
+
+    if not branch:
+        log_error("branch field not set in task.json")
+        log_info("Please set branch field first, e.g.:")
+        log_info(
+            "  jq '.branch = \"task/my-task\"' task.json > tmp && mv tmp task.json"
+        )
+        return 1
+
+    log_info(f"Branch: {branch}")
+    log_info(f"Name: {task_name}")
+
+    # =============================================================================
+    # Step 1: Create Worktree (if not exists)
+    # =============================================================================
+    if not worktree_path or not Path(worktree_path).is_dir():
+        log_info("Step 1: Creating worktree...")
+
+        # Record current branch as base_branch (PR target)
+        _, base_branch_out, _ = _run_git_command(
+            ["branch", "--show-current"], cwd=project_root
+        )
+        base_branch = base_branch_out.strip()
+        log_info(f"Base branch (PR target): {base_branch}")
+
+        # Calculate worktree path
+        worktree_base = get_worktree_base_dir(project_root)
+        worktree_base.mkdir(parents=True, exist_ok=True)
+        worktree_base = worktree_base.resolve()
+        worktree_path_obj = worktree_base / branch
+        worktree_path = str(worktree_path_obj)
+
+        # Create parent directory
+        worktree_path_obj.parent.mkdir(parents=True, exist_ok=True)
+
+        # Create branch if not exists
+        ret, _, _ = _run_git_command(
+            ["show-ref", "--verify", "--quiet", f"refs/heads/{branch}"],
+            cwd=project_root,
+        )
+        if ret == 0:
+            log_info("Branch exists, checking out...")
+            ret, _, err = _run_git_command(
+                ["worktree", "add", worktree_path, branch], cwd=project_root
+            )
+        else:
+            log_info(f"Creating new branch: {branch}")
+            ret, _, err = _run_git_command(
+                ["worktree", "add", "-b", branch, worktree_path], cwd=project_root
+            )
+
+        if ret != 0:
+            log_error(f"Failed to create worktree: {err}")
+            return 1
+
+        log_success(f"Worktree created: {worktree_path}")
+
+        # Update task.json with worktree_path and base_branch
+        task_data["worktree_path"] = worktree_path
+        task_data["base_branch"] = base_branch
+        _write_json_file(task_json_path, task_data)
+
+        # ----- Copy environment files -----
+        log_info("Copying environment files...")
+        copy_list = get_worktree_copy_files(project_root)
+        copy_count = 0
+
+        for item in copy_list:
+            if not item:
+                continue
+
+            source = project_root / item
+            target = Path(worktree_path) / item
+
+            if source.is_file():
+                target.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(str(source), str(target))
+                copy_count += 1
+
+        if copy_count > 0:
+            log_success(f"Copied {copy_count} file(s)")
+
+        # ----- Copy task directory (may not be committed yet) -----
+        log_info("Copying task directory...")
+        task_target_dir = Path(worktree_path) / task_dir_relative
+        task_target_dir.parent.mkdir(parents=True, exist_ok=True)
+        if task_target_dir.exists():
+            shutil.rmtree(str(task_target_dir))
+        shutil.copytree(str(task_dir_abs), str(task_target_dir))
+        log_success("Task directory copied to worktree")
+
+        # ----- Run post_create hooks -----
+        log_info("Running post_create hooks...")
+        post_create = get_worktree_post_create_hooks(project_root)
+        hook_count = 0
+
+        for cmd in post_create:
+            if not cmd:
+                continue
+
+            log_info(f"  Running: {cmd}")
+            ret = subprocess.run(cmd, shell=True, cwd=worktree_path)
+            if ret.returncode != 0:
+                log_error(f"Hook failed: {cmd}")
+                return 1
+            hook_count += 1
+
+        if hook_count > 0:
+            log_success(f"Ran {hook_count} hook(s)")
+    else:
+        log_info(f"Step 1: Using existing worktree: {worktree_path}")
+
+    # =============================================================================
+    # Step 2: Set .current-task in Worktree
+    # =============================================================================
+    log_info("Step 2: Setting current task in worktree...")
+
+    worktree_workflow_dir = Path(worktree_path) / DIR_WORKFLOW
+    worktree_workflow_dir.mkdir(parents=True, exist_ok=True)
+
+    current_task_file = worktree_workflow_dir / FILE_CURRENT_TASK
+    current_task_file.write_text(task_dir_relative, encoding="utf-8")
+    log_success(f"Current task set: {task_dir_relative}")
+
+    # =============================================================================
+    # Step 3: Prepare and Start Claude Agent
+    # =============================================================================
+    log_info(f"Step 3: Starting {adapter.cli_name} agent...")
+
+    # Update task status
+    task_data["status"] = "in_progress"
+    _write_json_file(task_json_path, task_data)
+
+    log_file = Path(worktree_path) / ".agent-log"
+    session_id_file = Path(worktree_path) / ".session-id"
+
+    log_file.touch()
+
+    # Generate session ID for resume support (Claude Code only)
+    # OpenCode generates its own session ID, we'll extract it from logs later
+    if adapter.supports_session_id_on_create:
+        session_id = str(uuid.uuid4()).lower()
+        session_id_file.write_text(session_id, encoding="utf-8")
+        log_info(f"Session ID: {session_id}")
+    else:
+        session_id = None  # Will be extracted from logs after startup
+        log_info("Session ID will be extracted from logs after startup")
+
+    # Get proxy environment variables
+    https_proxy = os.environ.get("https_proxy", "")
+    http_proxy = os.environ.get("http_proxy", "")
+    all_proxy = os.environ.get("all_proxy", "")
+
+    # Start agent in background (cross-platform, no shell script needed)
+    env = os.environ.copy()
+    env["https_proxy"] = https_proxy
+    env["http_proxy"] = http_proxy
+    env["all_proxy"] = all_proxy
+
+    # Clear nested-session detection so the new CLI process can start
+    # (when this script runs inside a Claude Code session, CLAUDECODE=1 is inherited)
+    env.pop("CLAUDECODE", None)
+
+    # Set non-interactive env var based on platform
+    env.update(adapter.get_non_interactive_env())
+
+    # Build CLI command using adapter
+    # Note: Use explicit prompt to avoid confusion with CI/CD pipelines
+    # Also remind the model to follow its agent definition for better cross-model compatibility
+    cli_cmd = adapter.build_run_command(
+        agent="dispatch",
+        prompt="Follow your agent instructions to execute the task workflow. Start by reading .trellis/.current-task to get the task directory, then execute each action in task.json next_action array in order.",
+        session_id=session_id if adapter.supports_session_id_on_create else None,
+        skip_permissions=True,
+        verbose=True,
+        json_output=True,
+    )
+
+    with log_file.open("w") as log_f:
+        # Use shell=False for cross-platform compatibility
+        # creationflags for Windows, start_new_session for Unix
+        popen_kwargs = {
+            "stdout": log_f,
+            "stderr": subprocess.STDOUT,
+            "cwd": worktree_path,
+            "env": env,
+        }
+        if sys.platform == "win32":
+            popen_kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+        else:
+            popen_kwargs["start_new_session"] = True
+
+        process = subprocess.Popen(cli_cmd, **popen_kwargs)
+    agent_pid = process.pid
+
+    log_success(f"Agent started with PID: {agent_pid}")
+
+    # For OpenCode: extract session ID from logs after startup
+    if not adapter.supports_session_id_on_create:
+        import time
+        log_info("Waiting for session ID from logs...")
+        # Wait a bit for the log to have session ID
+        for _ in range(10):  # Try for up to 5 seconds
+            time.sleep(0.5)
+            try:
+                log_content = log_file.read_text(encoding="utf-8", errors="replace")
+                session_id = adapter.extract_session_id_from_log(log_content)
+                if session_id:
+                    session_id_file.write_text(session_id, encoding="utf-8")
+                    log_success(f"Session ID extracted: {session_id}")
+                    break
+            except Exception:
+                pass
+        else:
+            log_warn("Could not extract session ID from logs")
+            session_id = "unknown"
+
+    # =============================================================================
+    # Step 4: Register to Registry (in main repo, not worktree)
+    # =============================================================================
+    log_info("Step 4: Registering agent to registry...")
+
+    # Generate agent ID
+    task_id = task_data.get("id")
+    if not task_id:
+        task_id = branch.replace("/", "-")
+
+    registry_add_agent(
+        task_id, worktree_path, agent_pid, task_dir_relative, project_root, platform
+    )
+
+    log_success(f"Agent registered: {task_id}")
+
+    # =============================================================================
+    # Summary
+    # =============================================================================
+    print()
+    print(f"{Colors.GREEN}=== Agent Started ==={Colors.NC}")
+    print()
+    print(f"  ID:        {task_id}")
+    print(f"  PID:       {agent_pid}")
+    print(f"  Session:   {session_id}")
+    print(f"  Worktree:  {worktree_path}")
+    print(f"  Task:      {task_dir_relative}")
+    print(f"  Log:       {log_file}")
+    print(f"  Registry:  {registry_get_file(project_root)}")
+    print()
+    print(f"{Colors.YELLOW}To monitor:{Colors.NC} tail -f {log_file}")
+    print(f"{Colors.YELLOW}To stop:{Colors.NC}    kill {agent_pid}")
+    if session_id and session_id != "unknown":
+        resume_cmd = adapter.get_resume_command_str(session_id, cwd=worktree_path)
+        print(f"{Colors.YELLOW}To resume:{Colors.NC}  {resume_cmd}")
+    else:
+        print(f"{Colors.YELLOW}To resume:{Colors.NC}  (session ID not available)")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.trellis/scripts/multi_agent/status.py b/.trellis/scripts/multi_agent/status.py
new file mode 100755
index 000000000..e83ac60a3
--- /dev/null
+++ b/.trellis/scripts/multi_agent/status.py
@@ -0,0 +1,817 @@
+#!/usr/bin/env python3
+"""
+Multi-Agent Pipeline: Status Monitor.
+
+Usage:
+    python3 status.py                     Show summary of all tasks (default)
+    python3 status.py -a <assignee>       Filter tasks by assignee
+    python3 status.py --list              List all worktrees and agents
+    python3 status.py --detail <task>     Detailed task status
+    python3 status.py --watch <task>      Watch agent log in real-time
+    python3 status.py --log <task>        Show recent log entries
+    python3 status.py --registry          Show agent registry
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from common.cli_adapter import get_cli_adapter
+from common.developer import ensure_developer
+from common.paths import (
+    FILE_TASK_JSON,
+    get_repo_root,
+    get_tasks_dir,
+)
+from common.phase import get_phase_info
+from common.task_queue import format_task_stats, get_task_stats
+from common.worktree import get_agents_dir
+
+# =============================================================================
+# Colors
+# =============================================================================
+
+
+class Colors:
+    RED = "\033[0;31m"
+    GREEN = "\033[0;32m"
+    YELLOW = "\033[1;33m"
+    BLUE = "\033[0;34m"
+    CYAN = "\033[0;36m"
+    DIM = "\033[2m"
+    NC = "\033[0m"
+
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+
+def _read_json_file(path: Path) -> dict | None:
+    """Read and parse a JSON file."""
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return None
+
+
+def is_running(pid: int | str | None) -> bool:
+    """Check if PID is running."""
+    if not pid:
+        return False
+    try:
+        pid_int = int(pid)
+        os.kill(pid_int, 0)
+        return True
+    except (ProcessLookupError, ValueError, PermissionError, TypeError):
+        return False
+
+
+def status_color(status: str) -> str:
+    """Get status color."""
+    colors = {
+        "completed": Colors.GREEN,
+        "in_progress": Colors.BLUE,
+        "planning": Colors.YELLOW,
+    }
+    return colors.get(status, Colors.DIM)
+
+
+def get_registry_file(repo_root: Path) -> Path | None:
+    """Get registry file path."""
+    agents_dir = get_agents_dir(repo_root)
+    if agents_dir:
+        return agents_dir / "registry.json"
+    return None
+
+
+def find_agent(search: str, repo_root: Path) -> dict | None:
+    """Find agent by task name or ID."""
+    registry_file = get_registry_file(repo_root)
+    if not registry_file or not registry_file.is_file():
+        return None
+
+    data = _read_json_file(registry_file)
+    if not data:
+        return None
+
+    for agent in data.get("agents", []):
+        # Exact ID match
+        if agent.get("id") == search:
+            return agent
+        # Partial match on task_dir
+        task_dir = agent.get("task_dir", "")
+        if search in task_dir:
+            return agent
+
+    return None
+
+
+def calc_elapsed(started: str | None) -> str:
+    """Calculate elapsed time from ISO timestamp."""
+    if not started:
+        return "N/A"
+
+    try:
+        # Parse ISO format
+        if "+" in started:
+            started = started.split("+")[0]
+        if "T" in started:
+            start_dt = datetime.fromisoformat(started)
+        else:
+            return "N/A"
+
+        now = datetime.now()
+        elapsed = (now - start_dt).total_seconds()
+
+        if elapsed < 60:
+            return f"{int(elapsed)}s"
+        elif elapsed < 3600:
+            mins = int(elapsed // 60)
+            secs = int(elapsed % 60)
+            return f"{mins}m {secs}s"
+        else:
+            hours = int(elapsed // 3600)
+            mins = int((elapsed % 3600) // 60)
+            return f"{hours}h {mins}m"
+    except (ValueError, TypeError):
+        return "N/A"
+
+
+def count_modified_files(worktree: str) -> int:
+    """Count modified files in worktree."""
+    if not Path(worktree).is_dir():
+        return 0
+
+    try:
+        result = subprocess.run(
+            ["git", "status", "--short"],
+            cwd=worktree,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+        return len([line for line in result.stdout.splitlines() if line.strip()])
+    except Exception:
+        return 0
+
+
+def tail_follow(file_path: Path) -> None:
+    """Follow a file like 'tail -f', cross-platform compatible."""
+    with open(file_path, "r", encoding="utf-8", errors="replace") as f:
+        # Seek to end of file
+        f.seek(0, 2)
+
+        while True:
+            line = f.readline()
+            if line:
+                print(line, end="", flush=True)
+            else:
+                time.sleep(0.1)
+
+
+def get_last_tool(log_file: Path, platform: str = "claude") -> str | None:
+    """Get the last tool call from agent log.
+
+    Supports both Claude Code and OpenCode log formats.
+
+    Claude Code format:
+        {"type": "assistant", "message": {"content": [{"type": "tool_use", "name": "Read"}]}}
+
+    OpenCode format:
+        {"type": "tool_use", "tool": "bash", "state": {"status": "completed"}}
+    """
+    if not log_file.is_file():
+        return None
+
+    try:
+        lines = log_file.read_text(encoding="utf-8").splitlines()
+        for line in reversed(lines[-100:]):
+            try:
+                data = json.loads(line)
+
+                if platform == "opencode":
+                    # OpenCode format: {"type": "tool_use", "tool": "bash", ...}
+                    if data.get("type") == "tool_use":
+                        return data.get("tool")
+                else:
+                    # Claude Code format: {"type": "assistant", "message": {"content": [...]}}
+                    if data.get("type") == "assistant":
+                        content = data.get("message", {}).get("content", [])
+                        for item in content:
+                            if item.get("type") == "tool_use":
+                                return item.get("name")
+            except json.JSONDecodeError:
+                continue
+    except Exception:
+        pass
+    return None
+
+
+def get_last_message(log_file: Path, max_len: int = 100, platform: str = "claude") -> str | None:
+    """Get the last assistant text from agent log.
+
+    Supports both Claude Code and OpenCode log formats.
+
+    Claude Code format:
+        {"type": "assistant", "message": {"content": [{"type": "text", "text": "..."}]}}
+
+    OpenCode format:
+        {"type": "text", "text": "..."}
+    """
+    if not log_file.is_file():
+        return None
+
+    try:
+        lines = log_file.read_text(encoding="utf-8").splitlines()
+        for line in reversed(lines[-100:]):
+            try:
+                data = json.loads(line)
+
+                if platform == "opencode":
+                    # OpenCode format: {"type": "text", "text": "..."}
+                    if data.get("type") == "text":
+                        text = data.get("text", "")
+                        if text:
+                            return text[:max_len]
+                else:
+                    # Claude Code format: {"type": "assistant", "message": {"content": [...]}}
+                    if data.get("type") == "assistant":
+                        content = data.get("message", {}).get("content", [])
+                        for item in content:
+                            if item.get("type") == "text":
+                                text = item.get("text", "")
+                                if text:
+                                    return text[:max_len]
+            except json.JSONDecodeError:
+                continue
+    except Exception:
+        pass
+    return None
+
+
+# =============================================================================
+# Commands
+# =============================================================================
+
+
+def cmd_help() -> int:
+    """Show help."""
+    print("""Multi-Agent Pipeline: Status Monitor
+
+Usage:
+  python3 status.py                         Show summary of all tasks
+  python3 status.py -a <assignee>           Filter tasks by assignee
+  python3 status.py --list                  List all worktrees and agents
+  python3 status.py --detail <task>         Detailed task status
+  python3 status.py --progress <task>       Quick progress view with recent activity
+  python3 status.py --watch <task>          Watch agent log in real-time
+  python3 status.py --log <task>            Show recent log entries
+  python3 status.py --registry              Show agent registry
+
+Examples:
+  python3 status.py -a taosu
+  python3 status.py --detail my-task
+  python3 status.py --progress my-task
+  python3 status.py --watch 01-16-worktree-support
+  python3 status.py --log worktree-support
+""")
+    return 0
+
+
+def cmd_list(repo_root: Path) -> int:
+    """List worktrees and agents."""
+    print(f"{Colors.BLUE}=== Git Worktrees ==={Colors.NC}")
+    print()
+
+    subprocess.run(["git", "worktree", "list"], cwd=repo_root)
+    print()
+
+    print(f"{Colors.BLUE}=== Registered Agents ==={Colors.NC}")
+    print()
+
+    registry_file = get_registry_file(repo_root)
+    if not registry_file or not registry_file.is_file():
+        print("  (no registry found)")
+        return 0
+
+    data = _read_json_file(registry_file)
+    if not data or not data.get("agents"):
+        print("  (no agents registered)")
+        return 0
+
+    for agent in data["agents"]:
+        agent_id = agent.get("id", "?")
+        pid = agent.get("pid")
+        wt = agent.get("worktree_path", "?")
+        started = agent.get("started_at", "?")
+
+        if is_running(pid):
+            status_icon = f"{Colors.GREEN}●{Colors.NC}"
+        else:
+            status_icon = f"{Colors.RED}○{Colors.NC}"
+
+        print(f"  {status_icon} {agent_id} (PID: {pid})")
+        print(f"    {Colors.DIM}Worktree: {wt}{Colors.NC}")
+        print(f"    {Colors.DIM}Started:  {started}{Colors.NC}")
+        print()
+
+    return 0
+
+
+def cmd_summary(repo_root: Path, filter_assignee: str | None = None) -> int:
+    """Show summary of all tasks."""
+    ensure_developer(repo_root)
+
+    tasks_dir = get_tasks_dir(repo_root)
+    if not tasks_dir.is_dir():
+        print("No tasks directory found")
+        return 0
+
+    registry_file = get_registry_file(repo_root)
+
+    # Count running agents
+    running_count = 0
+    total_agents = 0
+
+    if registry_file and registry_file.is_file():
+        data = _read_json_file(registry_file)
+        if data:
+            agents = data.get("agents", [])
+            total_agents = len(agents)
+            for agent in agents:
+                if is_running(agent.get("pid")):
+                    running_count += 1
+
+    # Task queue stats
+    task_stats = get_task_stats(repo_root)
+
+    print(f"{Colors.BLUE}=== Multi-Agent Status ==={Colors.NC}")
+    print(
+        f"  Agents:  {Colors.GREEN}{running_count}{Colors.NC} running / {total_agents} registered"
+    )
+    print(f"  Tasks:   {format_task_stats(task_stats)}")
+    print()
+
+    # Process tasks
+    running_tasks = []
+    stopped_tasks = []
+    regular_tasks = []
+
+    registry_data = (
+        _read_json_file(registry_file)
+        if registry_file and registry_file.is_file()
+        else None
+    )
+
+    for d in sorted(tasks_dir.iterdir()):
+        if not d.is_dir() or d.name == "archive":
+            continue
+
+        name = d.name
+        task_json = d / FILE_TASK_JSON
+        status = "unknown"
+        assignee = "unassigned"
+        priority = "P2"
+
+        if task_json.is_file():
+            data = _read_json_file(task_json)
+            if data:
+                status = data.get("status", "unknown")
+                assignee = data.get("assignee", "unassigned")
+                priority = data.get("priority", "P2")
+
+        # Filter by assignee
+        if filter_assignee and assignee != filter_assignee:
+            continue
+
+        # Check agent status
+        agent_info = None
+        if registry_data:
+            for agent in registry_data.get("agents", []):
+                if name in agent.get("task_dir", ""):
+                    agent_info = agent
+                    break
+
+        if agent_info:
+            pid = agent_info.get("pid")
+            worktree = agent_info.get("worktree_path", "")
+            started = agent_info.get("started_at")
+            agent_platform = agent_info.get("platform", "claude")
+
+            if is_running(pid):
+                # Running agent
+                task_dir_rel = agent_info.get("task_dir", "")
+                worktree_task_json = Path(worktree) / task_dir_rel / "task.json"
+                phase_source = task_json
+                if worktree_task_json.is_file():
+                    phase_source = worktree_task_json
+
+                phase_info_str = get_phase_info(phase_source)
+                elapsed = calc_elapsed(started)
+                modified = count_modified_files(worktree)
+
+                worktree_data = _read_json_file(phase_source)
+                branch = worktree_data.get("branch", "N/A") if worktree_data else "N/A"
+
+                log_file = Path(worktree) / ".agent-log"
+                last_tool = get_last_tool(log_file, platform=agent_platform)
+
+                running_tasks.append(
+                    {
+                        "name": name,
+                        "priority": priority,
+                        "assignee": assignee,
+                        "phase_info": phase_info_str,
+                        "elapsed": elapsed,
+                        "branch": branch,
+                        "modified": modified,
+                        "last_tool": last_tool,
+                        "pid": pid,
+                    }
+                )
+            else:
+                # Stopped agent
+                task_dir_rel = agent_info.get("task_dir", "")
+                worktree_task_json = Path(worktree) / task_dir_rel / "task.json"
+                worktree_status = "unknown"
+
+                if worktree_task_json.is_file():
+                    wt_data = _read_json_file(worktree_task_json)
+                    if wt_data:
+                        worktree_status = wt_data.get("status", "unknown")
+
+                session_id_file = Path(worktree) / ".session-id"
+                log_file = Path(worktree) / ".agent-log"
+
+                stopped_tasks.append(
+                    {
+                        "name": name,
+                        "worktree": worktree,
+                        "status": worktree_status,
+                        "session_id_file": session_id_file,
+                        "log_file": log_file,
+                        "platform": agent_info.get("platform", "claude"),
+                    }
+                )
+        else:
+            # Regular task
+            regular_tasks.append(
+                {
+                    "name": name,
+                    "status": status,
+                    "priority": priority,
+                    "assignee": assignee,
+                }
+            )
+
+    # Output running agents
+    if running_tasks:
+        print(f"{Colors.CYAN}Running Agents:{Colors.NC}")
+        for t in running_tasks:
+            priority_color = (
+                Colors.RED
+                if t["priority"] == "P0"
+                else (Colors.YELLOW if t["priority"] == "P1" else Colors.BLUE)
+            )
+            print(
+                f"{Colors.GREEN}▶{Colors.NC} {Colors.CYAN}{t['name']}{Colors.NC} {Colors.GREEN}[running]{Colors.NC} {priority_color}[{t['priority']}]{Colors.NC} @{t['assignee']}"
+            )
+            print(f"  Phase:    {t['phase_info']}")
+            print(f"  Elapsed:  {t['elapsed']}")
+            print(f"  Branch:   {Colors.DIM}{t['branch']}{Colors.NC}")
+            print(f"  Modified: {t['modified']} file(s)")
+            if t["last_tool"]:
+                print(f"  Activity: {Colors.YELLOW}{t['last_tool']}{Colors.NC}")
+            print(f"  PID:      {Colors.DIM}{t['pid']}{Colors.NC}")
+            print()
+
+    # Output stopped agents
+    if stopped_tasks:
+        print(f"{Colors.RED}Stopped Agents:{Colors.NC}")
+        for t in stopped_tasks:
+            if t["status"] == "completed":
+                print(
+                    f"{Colors.GREEN}✓{Colors.NC} {t['name']} {Colors.GREEN}[completed]{Colors.NC}"
+                )
+            else:
+                if t["session_id_file"].is_file():
+                    session_id = (
+                        t["session_id_file"].read_text(encoding="utf-8").strip()
+                    )
+                    last_msg = get_last_message(t["log_file"], 150, platform=t.get("platform", "claude"))
+                    print(
+                        f"{Colors.RED}○{Colors.NC} {t['name']} {Colors.RED}[stopped]{Colors.NC}"
+                    )
+                    if last_msg:
+                        print(f'{Colors.DIM}"{last_msg}"{Colors.NC}')
+                    # Use CLI adapter for platform-specific resume command
+                    adapter = get_cli_adapter(t.get("platform", "claude"))
+                    resume_cmd = adapter.get_resume_command_str(session_id, cwd=t["worktree"])
+                    print(f"{Colors.YELLOW}{resume_cmd}{Colors.NC}")
+                else:
+                    print(
+                        f"{Colors.RED}○{Colors.NC} {t['name']} {Colors.RED}[stopped]{Colors.NC} {Colors.DIM}(no session-id){Colors.NC}"
+                    )
+            print()
+
+    # Separator
+    if (running_tasks or stopped_tasks) and regular_tasks:
+        print(f"{Colors.DIM}───────────────────────────────────────{Colors.NC}")
+        print()
+
+    # Output regular tasks grouped by assignee
+    if regular_tasks:
+        # Sort by assignee, priority, status
+        regular_tasks.sort(
+            key=lambda x: (
+                x["assignee"],
+                {"P0": 0, "P1": 1, "P2": 2, "P3": 3}.get(x["priority"], 2),
+                {"in_progress": 0, "planning": 1, "completed": 2}.get(x["status"], 1),
+            )
+        )
+
+        current_assignee = None
+        for t in regular_tasks:
+            if t["assignee"] != current_assignee:
+                if current_assignee is not None:
+                    print()
+                print(f"{Colors.CYAN}@{t['assignee']}:{Colors.NC}")
+                current_assignee = t["assignee"]
+
+            color = status_color(t["status"])
+            priority_color = (
+                Colors.RED
+                if t["priority"] == "P0"
+                else (Colors.YELLOW if t["priority"] == "P1" else Colors.BLUE)
+            )
+            print(
+                f"  {color}●{Colors.NC} {t['name']} ({t['status']}) {priority_color}[{t['priority']}]{Colors.NC}"
+            )
+
+    if running_tasks:
+        print()
+        print(f"{Colors.DIM}─────────────────────────────────────{Colors.NC}")
+        print(f"{Colors.DIM}Use --progress <name> for quick activity view{Colors.NC}")
+        print(f"{Colors.DIM}Use --detail <name> for more info{Colors.NC}")
+
+    print()
+    return 0
+
+
+def cmd_detail(target: str, repo_root: Path) -> int:
+    """Show detailed task status."""
+    agent = find_agent(target, repo_root)
+    if not agent:
+        print(f"Agent not found: {target}")
+        return 1
+
+    agent_id = agent.get("id", "?")
+    pid = agent.get("pid")
+    worktree = agent.get("worktree_path", "?")
+    task_dir = agent.get("task_dir", "?")
+    started = agent.get("started_at", "?")
+    platform = agent.get("platform", "claude")
+
+    # Check for session-id
+    session_id = ""
+    session_id_file = Path(worktree) / ".session-id"
+    if session_id_file.is_file():
+        session_id = session_id_file.read_text(encoding="utf-8").strip()
+
+    print(f"{Colors.BLUE}=== Agent Detail: {agent_id} ==={Colors.NC}")
+    print()
+    print(f"  ID:        {agent_id}")
+    print(f"  PID:       {pid}")
+    print(f"  Session:   {session_id or 'N/A'}")
+    print(f"  Worktree:  {worktree}")
+    print(f"  Task Dir:  {task_dir}")
+    print(f"  Started:   {started}")
+    print()
+
+    # Status
+    if is_running(pid):
+        print(f"  Status:    {Colors.GREEN}Running{Colors.NC}")
+    else:
+        print(f"  Status:    {Colors.RED}Stopped{Colors.NC}")
+        if session_id:
+            print()
+            # Use CLI adapter for platform-specific resume command
+            adapter = get_cli_adapter(platform)
+            resume_cmd = adapter.get_resume_command_str(session_id, cwd=worktree)
+            print(f"  {Colors.YELLOW}Resume:{Colors.NC} {resume_cmd}")
+
+    # Task info
+    task_json = repo_root / task_dir / "task.json"
+    if task_json.is_file():
+        print()
+        print(f"{Colors.BLUE}=== Task Info ==={Colors.NC}")
+        print()
+        data = _read_json_file(task_json)
+        if data:
+            print(f"  Status:      {data.get('status', 'unknown')}")
+            print(f"  Branch:      {data.get('branch', 'N/A')}")
+            print(f"  Base Branch: {data.get('base_branch', 'N/A')}")
+
+    # Git changes
+    if Path(worktree).is_dir():
+        print()
+        print(f"{Colors.BLUE}=== Git Changes ==={Colors.NC}")
+        print()
+
+        result = subprocess.run(
+            ["git", "status", "--short"],
+            cwd=worktree,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+        changes = result.stdout.strip()
+        if changes:
+            for line in changes.splitlines()[:10]:
+                print(f"  {line}")
+            total = len(changes.splitlines())
+            if total > 10:
+                print(f"  ... and {total - 10} more")
+        else:
+            print("  (no changes)")
+
+    print()
+    return 0
+
+
+def cmd_watch(target: str, repo_root: Path) -> int:
+    """Watch agent log in real-time."""
+    agent = find_agent(target, repo_root)
+    if not agent:
+        print(f"Agent not found: {target}")
+        return 1
+
+    worktree = agent.get("worktree_path", "")
+    log_file = Path(worktree) / ".agent-log"
+
+    if not log_file.is_file():
+        print(f"Log file not found: {log_file}")
+        return 1
+
+    print(f"{Colors.BLUE}Watching:{Colors.NC} {log_file}")
+    print(f"{Colors.DIM}Press Ctrl+C to stop{Colors.NC}")
+    print()
+
+    try:
+        tail_follow(log_file)
+    except KeyboardInterrupt:
+        print()  # Clean newline after Ctrl+C
+    return 0
+
+
+def cmd_log(target: str, repo_root: Path) -> int:
+    """Show recent log entries."""
+    agent = find_agent(target, repo_root)
+    if not agent:
+        print(f"Agent not found: {target}")
+        return 1
+
+    worktree = agent.get("worktree_path", "")
+    platform = agent.get("platform", "claude")
+    log_file = Path(worktree) / ".agent-log"
+
+    if not log_file.is_file():
+        print(f"Log file not found: {log_file}")
+        return 1
+
+    print(f"{Colors.BLUE}=== Recent Log: {target} ==={Colors.NC}")
+    print(f"{Colors.DIM}Platform: {platform}{Colors.NC}")
+    print()
+
+    lines = log_file.read_text(encoding="utf-8").splitlines()
+    for line in lines[-50:]:
+        try:
+            data = json.loads(line)
+            msg_type = data.get("type", "")
+
+            if platform == "opencode":
+                # OpenCode format
+                if msg_type == "text":
+                    text = data.get("text", "")
+                    if text:
+                        display = text[:300]
+                        if len(text) > 300:
+                            display += "..."
+                        print(f"{Colors.BLUE}[TEXT]{Colors.NC} {display}")
+                elif msg_type == "tool_use":
+                    tool_name = data.get("tool", "unknown")
+                    status = data.get("state", {}).get("status", "")
+                    print(f"{Colors.YELLOW}[TOOL]{Colors.NC} {tool_name} ({status})")
+                elif msg_type == "step_start":
+                    print(f"{Colors.CYAN}[STEP]{Colors.NC} Start")
+                elif msg_type == "step_finish":
+                    reason = data.get("reason", "")
+                    print(f"{Colors.CYAN}[STEP]{Colors.NC} Finish ({reason})")
+                elif msg_type == "error":
+                    error_msg = data.get("message", "")
+                    print(f"{Colors.RED}[ERROR]{Colors.NC} {error_msg}")
+            else:
+                # Claude Code format
+                if msg_type == "system":
+                    subtype = data.get("subtype", "")
+                    print(f"{Colors.CYAN}[SYSTEM]{Colors.NC} {subtype}")
+                elif msg_type == "user":
+                    content = data.get("message", {}).get("content", "")
+                    if content:
+                        print(f"{Colors.GREEN}[USER]{Colors.NC} {content[:200]}")
+                elif msg_type == "assistant":
+                    content = data.get("message", {}).get("content", [])
+                    if content:
+                        item = content[0]
+                        text = item.get("text")
+                        tool = item.get("name")
+                        if text:
+                            display = text[:300]
+                            if len(text) > 300:
+                                display += "..."
+                            print(f"{Colors.BLUE}[ASSISTANT]{Colors.NC} {display}")
+                        elif tool:
+                            print(f"{Colors.YELLOW}[TOOL]{Colors.NC} {tool}")
+                elif msg_type == "result":
+                    tool_name = data.get("tool", "unknown")
+                    print(f"{Colors.DIM}[RESULT]{Colors.NC} {tool_name} completed")
+        except json.JSONDecodeError:
+            continue
+
+    return 0
+
+
+def cmd_registry(repo_root: Path) -> int:
+    """Show agent registry."""
+    registry_file = get_registry_file(repo_root)
+
+    print(f"{Colors.BLUE}=== Agent Registry ==={Colors.NC}")
+    print()
+    print(f"File: {registry_file}")
+    print()
+
+    if registry_file and registry_file.is_file():
+        data = _read_json_file(registry_file)
+        if data:
+            print(json.dumps(data, indent=2))
+    else:
+        print("(registry not found)")
+
+    return 0
+
+
+# =============================================================================
+# Main
+# =============================================================================
+
+
+def main() -> int:
+    """Main entry point."""
+    parser = argparse.ArgumentParser(description="Multi-Agent Pipeline: Status Monitor")
+    parser.add_argument("-a", "--assignee", help="Filter by assignee")
+    parser.add_argument(
+        "--list", action="store_true", help="List all worktrees and agents"
+    )
+    parser.add_argument("--detail", metavar="TASK", help="Detailed task status")
+    parser.add_argument("--progress", metavar="TASK", help="Quick progress view")
+    parser.add_argument("--watch", metavar="TASK", help="Watch agent log")
+    parser.add_argument("--log", metavar="TASK", help="Show recent log entries")
+    parser.add_argument("--registry", action="store_true", help="Show agent registry")
+    parser.add_argument("target", nargs="?", help="Target task")
+
+    args = parser.parse_args()
+    repo_root = get_repo_root()
+
+    if args.list:
+        return cmd_list(repo_root)
+    elif args.detail:
+        return cmd_detail(args.detail, repo_root)
+    elif args.progress:
+        return cmd_detail(args.progress, repo_root)  # Similar to detail
+    elif args.watch:
+        return cmd_watch(args.watch, repo_root)
+    elif args.log:
+        return cmd_log(args.log, repo_root)
+    elif args.registry:
+        return cmd_registry(repo_root)
+    elif args.target:
+        return cmd_detail(args.target, repo_root)
+    else:
+        return cmd_summary(repo_root, args.assignee)
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.trellis/scripts/task.py b/.trellis/scripts/task.py
new file mode 100755
index 000000000..29f614cab
--- /dev/null
+++ b/.trellis/scripts/task.py
@@ -0,0 +1,1370 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Task Management Script for Multi-Agent Pipeline.
+
+Usage:
+    python3 task.py create "<title>" [--slug <name>] [--assignee <dev>] [--priority P0|P1|P2|P3] [--parent <dir>]
+    python3 task.py init-context <dir> <type>   # Initialize jsonl files
+    python3 task.py add-context <dir> <file> <path> [reason] # Add jsonl entry
+    python3 task.py validate <dir>              # Validate jsonl files
+    python3 task.py list-context <dir>          # List jsonl entries
+    python3 task.py start <dir>                 # Set as current task
+    python3 task.py finish                      # Clear current task
+    python3 task.py set-branch <dir> <branch>   # Set git branch
+    python3 task.py set-base-branch <dir> <branch>  # Set PR target branch
+    python3 task.py set-scope <dir> <scope>     # Set scope for PR title
+    python3 task.py create-pr [dir] [--dry-run] # Create PR from task
+    python3 task.py archive <task-name>         # Archive completed task
+    python3 task.py list                        # List active tasks
+    python3 task.py list-archive [month]        # List archived tasks
+    python3 task.py add-subtask <parent-dir> <child-dir>     # Link child to parent
+    python3 task.py remove-subtask <parent-dir> <child-dir>  # Unlink child from parent
+"""
+
+from __future__ import annotations
+
+import sys
+
+# IMPORTANT: Force stdout to use UTF-8 on Windows
+# This fixes UnicodeEncodeError when outputting non-ASCII characters
+if sys.platform == "win32":
+    import io as _io
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+    elif hasattr(sys.stdout, "detach"):
+        sys.stdout = _io.TextIOWrapper(sys.stdout.detach(), encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+
+import argparse
+import json
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from common.cli_adapter import get_cli_adapter_auto
+from common.git_context import _run_git_command
+from common.paths import (
+    DIR_WORKFLOW,
+    DIR_TASKS,
+    DIR_SPEC,
+    DIR_ARCHIVE,
+    FILE_TASK_JSON,
+    get_repo_root,
+    get_developer,
+    get_tasks_dir,
+    get_current_task,
+    set_current_task,
+    clear_current_task,
+    generate_task_date_prefix,
+)
+from common.task_utils import (
+    find_task_by_name,
+    archive_task_complete,
+)
+from common.config import get_hooks
+
+
+# =============================================================================
+# Colors
+# =============================================================================
+
+class Colors:
+    RED = "\033[0;31m"
+    GREEN = "\033[0;32m"
+    YELLOW = "\033[1;33m"
+    BLUE = "\033[0;34m"
+    CYAN = "\033[0;36m"
+    NC = "\033[0m"
+
+
+def colored(text: str, color: str) -> str:
+    """Apply color to text."""
+    return f"{color}{text}{Colors.NC}"
+
+
+# =============================================================================
+# Lifecycle Hooks
+# =============================================================================
+
+def _run_hooks(event: str, task_json_path: Path, repo_root: Path) -> None:
+    """Run lifecycle hooks for an event.
+
+    Args:
+        event: Event name (e.g. "after_create").
+        task_json_path: Absolute path to the task's task.json.
+        repo_root: Repository root for cwd and config lookup.
+    """
+    import os
+    import subprocess
+
+    commands = get_hooks(event, repo_root)
+    if not commands:
+        return
+
+    env = {**os.environ, "TASK_JSON_PATH": str(task_json_path)}
+
+    for cmd in commands:
+        try:
+            result = subprocess.run(
+                cmd,
+                shell=True,
+                cwd=repo_root,
+                env=env,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+            )
+            if result.returncode != 0:
+                print(
+                    colored(f"[WARN] Hook failed ({event}): {cmd}", Colors.YELLOW),
+                    file=sys.stderr,
+                )
+                if result.stderr.strip():
+                    print(f"  {result.stderr.strip()}", file=sys.stderr)
+        except Exception as e:
+            print(
+                colored(f"[WARN] Hook error ({event}): {cmd} — {e}", Colors.YELLOW),
+                file=sys.stderr,
+            )
+
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+def _read_json_file(path: Path) -> dict | None:
+    """Read and parse a JSON file."""
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return None
+
+
+def _write_json_file(path: Path, data: dict) -> bool:
+    """Write dict to JSON file."""
+    try:
+        path.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+        return True
+    except (OSError, IOError):
+        return False
+
+
+def _slugify(title: str) -> str:
+    """Convert title to slug (only works with ASCII)."""
+    result = title.lower()
+    result = re.sub(r"[^a-z0-9]", "-", result)
+    result = re.sub(r"-+", "-", result)
+    result = result.strip("-")
+    return result
+
+
+def _resolve_task_dir(target_dir: str, repo_root: Path) -> Path:
+    """Resolve task directory to absolute path.
+
+    Supports:
+    - Absolute path: /path/to/task
+    - Relative path: .trellis/tasks/01-31-my-task
+    - Task name: my-task (uses find_task_by_name for lookup)
+    """
+    if not target_dir:
+        return Path()
+
+    # Absolute path
+    if target_dir.startswith("/"):
+        return Path(target_dir)
+
+    # Relative path (contains path separator or starts with .trellis)
+    if "/" in target_dir or target_dir.startswith(".trellis"):
+        return repo_root / target_dir
+
+    # Task name - try to find in tasks directory
+    tasks_dir = get_tasks_dir(repo_root)
+    found = find_task_by_name(target_dir, tasks_dir)
+    if found:
+        return found
+
+    # Fallback to treating as relative path
+    return repo_root / target_dir
+
+
+# =============================================================================
+# JSONL Default Content Generators
+# =============================================================================
+
+def get_implement_base() -> list[dict]:
+    """Get base implement context entries."""
+    return [
+        {"file": f"{DIR_WORKFLOW}/workflow.md", "reason": "Project workflow and conventions"},
+    ]
+
+
+def get_implement_backend() -> list[dict]:
+    """Get backend implement context entries."""
+    return [
+        {"file": f"{DIR_WORKFLOW}/{DIR_SPEC}/backend/index.md", "reason": "Backend development guide"},
+    ]
+
+
+def get_implement_frontend() -> list[dict]:
+    """Get frontend implement context entries."""
+    return [
+        {"file": f"{DIR_WORKFLOW}/{DIR_SPEC}/frontend/index.md", "reason": "Frontend development guide"},
+    ]
+
+
+def get_check_context(dev_type: str, repo_root: Path) -> list[dict]:
+    """Get check context entries."""
+    adapter = get_cli_adapter_auto(repo_root)
+
+    entries = [
+        {"file": adapter.get_trellis_command_path("finish-work"), "reason": "Finish work checklist"},
+    ]
+
+    if dev_type in ("backend", "fullstack"):
+        entries.append({"file": adapter.get_trellis_command_path("check-backend"), "reason": "Backend check spec"})
+    if dev_type in ("frontend", "fullstack"):
+        entries.append({"file": adapter.get_trellis_command_path("check-frontend"), "reason": "Frontend check spec"})
+
+    return entries
+
+
+def get_debug_context(dev_type: str, repo_root: Path) -> list[dict]:
+    """Get debug context entries."""
+    adapter = get_cli_adapter_auto(repo_root)
+
+    entries: list[dict] = []
+
+    if dev_type in ("backend", "fullstack"):
+        entries.append({"file": adapter.get_trellis_command_path("check-backend"), "reason": "Backend check spec"})
+    if dev_type in ("frontend", "fullstack"):
+        entries.append({"file": adapter.get_trellis_command_path("check-frontend"), "reason": "Frontend check spec"})
+
+    return entries
+
+
+def _write_jsonl(path: Path, entries: list[dict]) -> None:
+    """Write entries to JSONL file."""
+    lines = [json.dumps(entry, ensure_ascii=False) for entry in entries]
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+# =============================================================================
+# Task Operations
+# =============================================================================
+
+def ensure_tasks_dir(repo_root: Path) -> Path:
+    """Ensure tasks directory exists."""
+    tasks_dir = get_tasks_dir(repo_root)
+    archive_dir = tasks_dir / "archive"
+
+    if not tasks_dir.exists():
+        tasks_dir.mkdir(parents=True)
+        print(colored(f"Created tasks directory: {tasks_dir}", Colors.GREEN), file=sys.stderr)
+
+    if not archive_dir.exists():
+        archive_dir.mkdir(parents=True)
+
+    return tasks_dir
+
+
+# =============================================================================
+# Command: create
+# =============================================================================
+
+def cmd_create(args: argparse.Namespace) -> int:
+    """Create a new task."""
+    repo_root = get_repo_root()
+
+    if not args.title:
+        print(colored("Error: title is required", Colors.RED), file=sys.stderr)
+        return 1
+
+    # Default assignee to current developer
+    assignee = args.assignee
+    if not assignee:
+        assignee = get_developer(repo_root)
+        if not assignee:
+            print(colored("Error: No developer set. Run init_developer.py first or use --assignee", Colors.RED), file=sys.stderr)
+            return 1
+
+    ensure_tasks_dir(repo_root)
+
+    # Get current developer as creator
+    creator = get_developer(repo_root) or assignee
+
+    # Generate slug if not provided
+    slug = args.slug or _slugify(args.title)
+    if not slug:
+        print(colored("Error: could not generate slug from title", Colors.RED), file=sys.stderr)
+        return 1
+
+    # Create task directory with MM-DD-slug format
+    tasks_dir = get_tasks_dir(repo_root)
+    date_prefix = generate_task_date_prefix()
+    dir_name = f"{date_prefix}-{slug}"
+    task_dir = tasks_dir / dir_name
+    task_json_path = task_dir / FILE_TASK_JSON
+
+    if task_dir.exists():
+        print(colored(f"Warning: Task directory already exists: {dir_name}", Colors.YELLOW), file=sys.stderr)
+    else:
+        task_dir.mkdir(parents=True)
+
+    today = datetime.now().strftime("%Y-%m-%d")
+
+    # Record current branch as base_branch (PR target)
+    _, branch_out, _ = _run_git_command(["branch", "--show-current"], cwd=repo_root)
+    current_branch = branch_out.strip() or "main"
+
+    task_data = {
+        "id": slug,
+        "name": slug,
+        "title": args.title,
+        "description": args.description or "",
+        "status": "planning",
+        "dev_type": None,
+        "scope": None,
+        "priority": args.priority,
+        "creator": creator,
+        "assignee": assignee,
+        "createdAt": today,
+        "completedAt": None,
+        "branch": None,
+        "base_branch": current_branch,
+        "worktree_path": None,
+        "current_phase": 0,
+        "next_action": [
+            {"phase": 1, "action": "implement"},
+            {"phase": 2, "action": "check"},
+            {"phase": 3, "action": "finish"},
+            {"phase": 4, "action": "create-pr"},
+        ],
+        "commit": None,
+        "pr_url": None,
+        "subtasks": [],
+        "children": [],
+        "parent": None,
+        "relatedFiles": [],
+        "notes": "",
+        "meta": {},
+    }
+
+    _write_json_file(task_json_path, task_data)
+
+    # Handle --parent: establish bidirectional link
+    if args.parent:
+        parent_dir = _resolve_task_dir(args.parent, repo_root)
+        parent_json_path = parent_dir / FILE_TASK_JSON
+        if not parent_json_path.is_file():
+            print(colored(f"Warning: Parent task.json not found: {args.parent}", Colors.YELLOW), file=sys.stderr)
+        else:
+            parent_data = _read_json_file(parent_json_path)
+            if parent_data:
+                # Add child to parent's children list
+                parent_children = parent_data.get("children", [])
+                if dir_name not in parent_children:
+                    parent_children.append(dir_name)
+                    parent_data["children"] = parent_children
+                    _write_json_file(parent_json_path, parent_data)
+
+                # Set parent in child's task.json
+                task_data["parent"] = parent_dir.name
+                _write_json_file(task_json_path, task_data)
+
+                print(colored(f"Linked as child of: {parent_dir.name}", Colors.GREEN), file=sys.stderr)
+
+    print(colored(f"Created task: {dir_name}", Colors.GREEN), file=sys.stderr)
+    print("", file=sys.stderr)
+    print(colored("Next steps:", Colors.BLUE), file=sys.stderr)
+    print("  1. Create prd.md with requirements", file=sys.stderr)
+    print("  2. Run: python3 task.py init-context <dir> <dev_type>", file=sys.stderr)
+    print("  3. Run: python3 task.py start <dir>", file=sys.stderr)
+    print("", file=sys.stderr)
+
+    # Output relative path for script chaining
+    print(f"{DIR_WORKFLOW}/{DIR_TASKS}/{dir_name}")
+
+    _run_hooks("after_create", task_json_path, repo_root)
+    return 0
+
+
+# =============================================================================
+# Command: init-context
+# =============================================================================
+
+def cmd_init_context(args: argparse.Namespace) -> int:
+    """Initialize JSONL context files for a task."""
+    repo_root = get_repo_root()
+    target_dir = _resolve_task_dir(args.dir, repo_root)
+    dev_type = args.type
+
+    if not dev_type:
+        print(colored("Error: Missing arguments", Colors.RED))
+        print("Usage: python3 task.py init-context <task-dir> <dev_type>")
+        print("  dev_type: backend | frontend | fullstack | test | docs")
+        return 1
+
+    if not target_dir.is_dir():
+        print(colored(f"Error: Directory not found: {target_dir}", Colors.RED))
+        return 1
+
+    print(colored("=== Initializing Agent Context Files ===", Colors.BLUE))
+    print(f"Target dir: {target_dir}")
+    print(f"Dev type: {dev_type}")
+    print()
+
+    # implement.jsonl
+    print(colored("Creating implement.jsonl...", Colors.CYAN))
+    implement_entries = get_implement_base()
+    if dev_type in ("backend", "test"):
+        implement_entries.extend(get_implement_backend())
+    elif dev_type == "frontend":
+        implement_entries.extend(get_implement_frontend())
+    elif dev_type == "fullstack":
+        implement_entries.extend(get_implement_backend())
+        implement_entries.extend(get_implement_frontend())
+
+    implement_file = target_dir / "implement.jsonl"
+    _write_jsonl(implement_file, implement_entries)
+    print(f"  {colored('✓', Colors.GREEN)} {len(implement_entries)} entries")
+
+    # check.jsonl
+    print(colored("Creating check.jsonl...", Colors.CYAN))
+    check_entries = get_check_context(dev_type, repo_root)
+    check_file = target_dir / "check.jsonl"
+    _write_jsonl(check_file, check_entries)
+    print(f"  {colored('✓', Colors.GREEN)} {len(check_entries)} entries")
+
+    # debug.jsonl
+    print(colored("Creating debug.jsonl...", Colors.CYAN))
+    debug_entries = get_debug_context(dev_type, repo_root)
+    debug_file = target_dir / "debug.jsonl"
+    _write_jsonl(debug_file, debug_entries)
+    print(f"  {colored('✓', Colors.GREEN)} {len(debug_entries)} entries")
+
+    print()
+    print(colored("✓ All context files created", Colors.GREEN))
+    print()
+    print(colored("Next steps:", Colors.BLUE))
+    print("  1. Add task-specific specs: python3 task.py add-context <dir> <jsonl> <path>")
+    print("  2. Set as current: python3 task.py start <dir>")
+
+    return 0
+
+
+# =============================================================================
+# Command: add-context
+# =============================================================================
+
+def cmd_add_context(args: argparse.Namespace) -> int:
+    """Add entry to JSONL context file."""
+    repo_root = get_repo_root()
+    target_dir = _resolve_task_dir(args.dir, repo_root)
+
+    jsonl_name = args.file
+    path = args.path
+    reason = args.reason or "Added manually"
+
+    if not target_dir.is_dir():
+        print(colored(f"Error: Directory not found: {target_dir}", Colors.RED))
+        return 1
+
+    # Support shorthand
+    if not jsonl_name.endswith(".jsonl"):
+        jsonl_name = f"{jsonl_name}.jsonl"
+
+    jsonl_file = target_dir / jsonl_name
+    full_path = repo_root / path
+
+    entry_type = "file"
+    if full_path.is_dir():
+        entry_type = "directory"
+        if not path.endswith("/"):
+            path = f"{path}/"
+    elif not full_path.is_file():
+        print(colored(f"Error: Path not found: {path}", Colors.RED))
+        return 1
+
+    # Check if already exists
+    if jsonl_file.is_file():
+        content = jsonl_file.read_text(encoding="utf-8")
+        if f'"{path}"' in content:
+            print(colored(f"Warning: Entry already exists for {path}", Colors.YELLOW))
+            return 0
+
+    # Add entry
+    entry: dict
+    if entry_type == "directory":
+        entry = {"file": path, "type": "directory", "reason": reason}
+    else:
+        entry = {"file": path, "reason": reason}
+
+    with jsonl_file.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+
+    print(colored(f"Added {entry_type}: {path}", Colors.GREEN))
+    return 0
+
+
+# =============================================================================
+# Command: validate
+# =============================================================================
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    """Validate JSONL context files."""
+    repo_root = get_repo_root()
+    target_dir = _resolve_task_dir(args.dir, repo_root)
+
+    if not target_dir.is_dir():
+        print(colored("Error: task directory required", Colors.RED))
+        return 1
+
+    print(colored("=== Validating Context Files ===", Colors.BLUE))
+    print(f"Target dir: {target_dir}")
+    print()
+
+    total_errors = 0
+    for jsonl_name in ["implement.jsonl", "check.jsonl", "debug.jsonl"]:
+        jsonl_file = target_dir / jsonl_name
+        errors = _validate_jsonl(jsonl_file, repo_root)
+        total_errors += errors
+
+    print()
+    if total_errors == 0:
+        print(colored("✓ All validations passed", Colors.GREEN))
+        return 0
+    else:
+        print(colored(f"✗ Validation failed ({total_errors} errors)", Colors.RED))
+        return 1
+
+
+def _validate_jsonl(jsonl_file: Path, repo_root: Path) -> int:
+    """Validate a single JSONL file."""
+    file_name = jsonl_file.name
+    errors = 0
+
+    if not jsonl_file.is_file():
+        print(f"  {colored(f'{file_name}: not found (skipped)', Colors.YELLOW)}")
+        return 0
+
+    line_num = 0
+    for line in jsonl_file.read_text(encoding="utf-8").splitlines():
+        line_num += 1
+        if not line.strip():
+            continue
+
+        try:
+            data = json.loads(line)
+        except json.JSONDecodeError:
+            print(f"  {colored(f'{file_name}:{line_num}: Invalid JSON', Colors.RED)}")
+            errors += 1
+            continue
+
+        file_path = data.get("file")
+        entry_type = data.get("type", "file")
+
+        if not file_path:
+            print(f"  {colored(f'{file_name}:{line_num}: Missing file field', Colors.RED)}")
+            errors += 1
+            continue
+
+        full_path = repo_root / file_path
+        if entry_type == "directory":
+            if not full_path.is_dir():
+                print(f"  {colored(f'{file_name}:{line_num}: Directory not found: {file_path}', Colors.RED)}")
+                errors += 1
+        else:
+            if not full_path.is_file():
+                print(f"  {colored(f'{file_name}:{line_num}: File not found: {file_path}', Colors.RED)}")
+                errors += 1
+
+    if errors == 0:
+        print(f"  {colored(f'{file_name}: ✓ ({line_num} entries)', Colors.GREEN)}")
+    else:
+        print(f"  {colored(f'{file_name}: ✗ ({errors} errors)', Colors.RED)}")
+
+    return errors
+
+
+# =============================================================================
+# Command: list-context
+# =============================================================================
+
+def cmd_list_context(args: argparse.Namespace) -> int:
+    """List JSONL context entries."""
+    repo_root = get_repo_root()
+    target_dir = _resolve_task_dir(args.dir, repo_root)
+
+    if not target_dir.is_dir():
+        print(colored("Error: task directory required", Colors.RED))
+        return 1
+
+    print(colored("=== Context Files ===", Colors.BLUE))
+    print()
+
+    for jsonl_name in ["implement.jsonl", "check.jsonl", "debug.jsonl"]:
+        jsonl_file = target_dir / jsonl_name
+        if not jsonl_file.is_file():
+            continue
+
+        print(colored(f"[{jsonl_name}]", Colors.CYAN))
+
+        count = 0
+        for line in jsonl_file.read_text(encoding="utf-8").splitlines():
+            if not line.strip():
+                continue
+
+            try:
+                data = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            count += 1
+            file_path = data.get("file", "?")
+            entry_type = data.get("type", "file")
+            reason = data.get("reason", "-")
+
+            if entry_type == "directory":
+                print(f"  {colored(f'{count}.', Colors.GREEN)} [DIR] {file_path}")
+            else:
+                print(f"  {colored(f'{count}.', Colors.GREEN)} {file_path}")
+            print(f"     {colored('→', Colors.YELLOW)} {reason}")
+
+        print()
+
+    return 0
+
+
+# =============================================================================
+# Command: start / finish
+# =============================================================================
+
+def cmd_start(args: argparse.Namespace) -> int:
+    """Set current task."""
+    repo_root = get_repo_root()
+    task_input = args.dir
+
+    if not task_input:
+        print(colored("Error: task directory or name required", Colors.RED))
+        return 1
+
+    # Resolve task directory (supports task name, relative path, or absolute path)
+    full_path = _resolve_task_dir(task_input, repo_root)
+
+    if not full_path.is_dir():
+        print(colored(f"Error: Task not found: {task_input}", Colors.RED))
+        print("Hint: Use task name (e.g., 'my-task') or full path (e.g., '.trellis/tasks/01-31-my-task')")
+        return 1
+
+    # Convert to relative path for storage
+    try:
+        task_dir = str(full_path.relative_to(repo_root))
+    except ValueError:
+        task_dir = str(full_path)
+
+    if set_current_task(task_dir, repo_root):
+        print(colored(f"✓ Current task set to: {task_dir}", Colors.GREEN))
+        print()
+        print(colored("The hook will now inject context from this task's jsonl files.", Colors.BLUE))
+
+        task_json_path = full_path / FILE_TASK_JSON
+        _run_hooks("after_start", task_json_path, repo_root)
+        return 0
+    else:
+        print(colored("Error: Failed to set current task", Colors.RED))
+        return 1
+
+
+def cmd_finish(args: argparse.Namespace) -> int:
+    """Clear current task."""
+    repo_root = get_repo_root()
+    current = get_current_task(repo_root)
+
+    if not current:
+        print(colored("No current task set", Colors.YELLOW))
+        return 0
+
+    # Resolve task.json path before clearing
+    task_json_path = repo_root / current / FILE_TASK_JSON
+
+    clear_current_task(repo_root)
+    print(colored(f"✓ Cleared current task (was: {current})", Colors.GREEN))
+
+    if task_json_path.is_file():
+        _run_hooks("after_finish", task_json_path, repo_root)
+    return 0
+
+
+# =============================================================================
+# Command: archive
+# =============================================================================
+
+def cmd_archive(args: argparse.Namespace) -> int:
+    """Archive completed task."""
+    repo_root = get_repo_root()
+    task_name = args.name
+
+    if not task_name:
+        print(colored("Error: Task name is required", Colors.RED), file=sys.stderr)
+        return 1
+
+    tasks_dir = get_tasks_dir(repo_root)
+
+    # Find task directory
+    task_dir = find_task_by_name(task_name, tasks_dir)
+
+    if not task_dir or not task_dir.is_dir():
+        print(colored(f"Error: Task not found: {task_name}", Colors.RED), file=sys.stderr)
+        print("Active tasks:", file=sys.stderr)
+        cmd_list(argparse.Namespace(mine=False, status=None))
+        return 1
+
+    dir_name = task_dir.name
+    task_json_path = task_dir / FILE_TASK_JSON
+
+    # Update status before archiving
+    today = datetime.now().strftime("%Y-%m-%d")
+    if task_json_path.is_file():
+        data = _read_json_file(task_json_path)
+        if data:
+            data["status"] = "completed"
+            data["completedAt"] = today
+            _write_json_file(task_json_path, data)
+
+            # Handle subtask relationships on archive
+            task_parent = data.get("parent")
+            task_children = data.get("children", [])
+
+            # If this is a child, remove from parent's children list
+            if task_parent:
+                parent_dir = find_task_by_name(task_parent, tasks_dir)
+                if parent_dir:
+                    parent_json = parent_dir / FILE_TASK_JSON
+                    if parent_json.is_file():
+                        parent_data = _read_json_file(parent_json)
+                        if parent_data:
+                            parent_children = parent_data.get("children", [])
+                            if dir_name in parent_children:
+                                parent_children.remove(dir_name)
+                                parent_data["children"] = parent_children
+                                _write_json_file(parent_json, parent_data)
+
+            # If this is a parent, clear parent field in all children
+            if task_children:
+                for child_name in task_children:
+                    child_dir_path = find_task_by_name(child_name, tasks_dir)
+                    if child_dir_path:
+                        child_json = child_dir_path / FILE_TASK_JSON
+                        if child_json.is_file():
+                            child_data = _read_json_file(child_json)
+                            if child_data:
+                                child_data["parent"] = None
+                                _write_json_file(child_json, child_data)
+
+    # Clear if current task
+    current = get_current_task(repo_root)
+    if current and dir_name in current:
+        clear_current_task(repo_root)
+
+    # Archive
+    result = archive_task_complete(task_dir, repo_root)
+    if "archived_to" in result:
+        archive_dest = Path(result["archived_to"])
+        year_month = archive_dest.parent.name
+        print(colored(f"Archived: {dir_name} -> archive/{year_month}/", Colors.GREEN), file=sys.stderr)
+
+        # Auto-commit unless --no-commit
+        if not getattr(args, "no_commit", False):
+            _auto_commit_archive(dir_name, repo_root)
+
+        # Return the archive path
+        print(f"{DIR_WORKFLOW}/{DIR_TASKS}/{DIR_ARCHIVE}/{year_month}/{dir_name}")
+
+        # Run hooks with the archived path
+        archived_json = archive_dest / FILE_TASK_JSON
+        _run_hooks("after_archive", archived_json, repo_root)
+        return 0
+
+    return 1
+
+
+def _auto_commit_archive(task_name: str, repo_root: Path) -> None:
+    """Stage .trellis/tasks/ changes and commit after archive."""
+    tasks_rel = f"{DIR_WORKFLOW}/{DIR_TASKS}"
+    _run_git_command(["add", "-A", tasks_rel], cwd=repo_root)
+
+    # Check if there are staged changes
+    rc, _, _ = _run_git_command(
+        ["diff", "--cached", "--quiet", "--", tasks_rel], cwd=repo_root
+    )
+    if rc == 0:
+        print("[OK] No task changes to commit.", file=sys.stderr)
+        return
+
+    commit_msg = f"chore(task): archive {task_name}"
+    rc, _, err = _run_git_command(["commit", "-m", commit_msg], cwd=repo_root)
+    if rc == 0:
+        print(f"[OK] Auto-committed: {commit_msg}", file=sys.stderr)
+    else:
+        print(f"[WARN] Auto-commit failed: {err.strip()}", file=sys.stderr)
+
+
+# =============================================================================
+# Command: add-subtask
+# =============================================================================
+
+def cmd_add_subtask(args: argparse.Namespace) -> int:
+    """Link a child task to a parent task."""
+    repo_root = get_repo_root()
+
+    parent_dir = _resolve_task_dir(args.parent_dir, repo_root)
+    child_dir = _resolve_task_dir(args.child_dir, repo_root)
+
+    parent_json_path = parent_dir / FILE_TASK_JSON
+    child_json_path = child_dir / FILE_TASK_JSON
+
+    if not parent_json_path.is_file():
+        print(colored(f"Error: Parent task.json not found: {args.parent_dir}", Colors.RED), file=sys.stderr)
+        return 1
+
+    if not child_json_path.is_file():
+        print(colored(f"Error: Child task.json not found: {args.child_dir}", Colors.RED), file=sys.stderr)
+        return 1
+
+    parent_data = _read_json_file(parent_json_path)
+    child_data = _read_json_file(child_json_path)
+
+    if not parent_data or not child_data:
+        print(colored("Error: Failed to read task.json", Colors.RED), file=sys.stderr)
+        return 1
+
+    # Check if child already has a parent
+    existing_parent = child_data.get("parent")
+    if existing_parent:
+        print(colored(f"Error: Child task already has a parent: {existing_parent}", Colors.RED), file=sys.stderr)
+        return 1
+
+    # Add child to parent's children list
+    parent_children = parent_data.get("children", [])
+    child_dir_name = child_dir.name
+    if child_dir_name not in parent_children:
+        parent_children.append(child_dir_name)
+        parent_data["children"] = parent_children
+
+    # Set parent in child's task.json
+    child_data["parent"] = parent_dir.name
+
+    # Write both
+    _write_json_file(parent_json_path, parent_data)
+    _write_json_file(child_json_path, child_data)
+
+    print(colored(f"Linked: {child_dir.name} -> {parent_dir.name}", Colors.GREEN), file=sys.stderr)
+    return 0
+
+
+# =============================================================================
+# Command: remove-subtask
+# =============================================================================
+
+def cmd_remove_subtask(args: argparse.Namespace) -> int:
+    """Unlink a child task from a parent task."""
+    repo_root = get_repo_root()
+
+    parent_dir = _resolve_task_dir(args.parent_dir, repo_root)
+    child_dir = _resolve_task_dir(args.child_dir, repo_root)
+
+    parent_json_path = parent_dir / FILE_TASK_JSON
+    child_json_path = child_dir / FILE_TASK_JSON
+
+    if not parent_json_path.is_file():
+        print(colored(f"Error: Parent task.json not found: {args.parent_dir}", Colors.RED), file=sys.stderr)
+        return 1
+
+    if not child_json_path.is_file():
+        print(colored(f"Error: Child task.json not found: {args.child_dir}", Colors.RED), file=sys.stderr)
+        return 1
+
+    parent_data = _read_json_file(parent_json_path)
+    child_data = _read_json_file(child_json_path)
+
+    if not parent_data or not child_data:
+        print(colored("Error: Failed to read task.json", Colors.RED), file=sys.stderr)
+        return 1
+
+    # Remove child from parent's children list
+    parent_children = parent_data.get("children", [])
+    child_dir_name = child_dir.name
+    if child_dir_name in parent_children:
+        parent_children.remove(child_dir_name)
+        parent_data["children"] = parent_children
+
+    # Clear parent in child's task.json
+    child_data["parent"] = None
+
+    # Write both
+    _write_json_file(parent_json_path, parent_data)
+    _write_json_file(child_json_path, child_data)
+
+    print(colored(f"Unlinked: {child_dir.name} from {parent_dir.name}", Colors.GREEN), file=sys.stderr)
+    return 0
+
+
+# =============================================================================
+# Command: list
+# =============================================================================
+
+def _get_children_progress(children: list[str], tasks_dir: Path) -> str:
+    """Get children progress summary like '[2/3 done]'."""
+    if not children:
+        return ""
+    done_count = 0
+    total = len(children)
+    for child_name in children:
+        child_dir = tasks_dir / child_name
+        child_json = child_dir / FILE_TASK_JSON
+        if child_json.is_file():
+            data = _read_json_file(child_json)
+            if data:
+                status = data.get("status", "")
+                if status in ("completed", "done"):
+                    done_count += 1
+    return f" [{done_count}/{total} done]"
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    """List active tasks."""
+    repo_root = get_repo_root()
+    tasks_dir = get_tasks_dir(repo_root)
+    current_task = get_current_task(repo_root)
+    developer = get_developer(repo_root)
+    filter_mine = args.mine
+    filter_status = args.status
+
+    if filter_mine:
+        if not developer:
+            print(colored("Error: No developer set. Run init_developer.py first", Colors.RED), file=sys.stderr)
+            return 1
+        print(colored(f"My tasks (assignee: {developer}):", Colors.BLUE))
+    else:
+        print(colored("All active tasks:", Colors.BLUE))
+    print()
+
+    # First pass: collect all task data and identify parent/child relationships
+    all_tasks: dict[str, dict] = {}
+    if tasks_dir.is_dir():
+        for d in sorted(tasks_dir.iterdir()):
+            if not d.is_dir() or d.name == "archive":
+                continue
+
+            dir_name = d.name
+            task_json = d / FILE_TASK_JSON
+            status = "unknown"
+            assignee = "-"
+            children: list[str] = []
+            parent: str | None = None
+
+            if task_json.is_file():
+                data = _read_json_file(task_json)
+                if data:
+                    status = data.get("status", "unknown")
+                    assignee = data.get("assignee", "-")
+                    children = data.get("children", [])
+                    parent = data.get("parent")
+
+            all_tasks[dir_name] = {
+                "status": status,
+                "assignee": assignee,
+                "children": children,
+                "parent": parent,
+            }
+
+    # Second pass: display tasks hierarchically
+    count = 0
+
+    def _print_task(dir_name: str, indent: int = 0) -> None:
+        nonlocal count
+        info = all_tasks[dir_name]
+        status = info["status"]
+        assignee = info["assignee"]
+        children = info["children"]
+
+        # Apply --mine filter
+        if filter_mine and assignee != developer:
+            return
+
+        # Apply --status filter
+        if filter_status and status != filter_status:
+            return
+
+        relative_path = f"{DIR_WORKFLOW}/{DIR_TASKS}/{dir_name}"
+        marker = ""
+        if relative_path == current_task:
+            marker = f" {colored('<- current', Colors.GREEN)}"
+
+        # Children progress
+        progress = _get_children_progress(children, tasks_dir) if children else ""
+
+        prefix = "  " * indent + "  - "
+
+        if filter_mine:
+            print(f"{prefix}{dir_name}/ ({status}){progress}{marker}")
+        else:
+            print(f"{prefix}{dir_name}/ ({status}){progress} [{colored(assignee, Colors.CYAN)}]{marker}")
+        count += 1
+
+        # Print children indented
+        for child_name in children:
+            if child_name in all_tasks:
+                _print_task(child_name, indent + 1)
+
+    # Display only top-level tasks (those without a parent)
+    for dir_name in sorted(all_tasks.keys()):
+        info = all_tasks[dir_name]
+        if not info["parent"]:
+            _print_task(dir_name)
+
+    if count == 0:
+        if filter_mine:
+            print("  (no tasks assigned to you)")
+        else:
+            print("  (no active tasks)")
+
+    print()
+    print(f"Total: {count} task(s)")
+    return 0
+
+
+# =============================================================================
+# Command: list-archive
+# =============================================================================
+
+def cmd_list_archive(args: argparse.Namespace) -> int:
+    """List archived tasks."""
+    repo_root = get_repo_root()
+    tasks_dir = get_tasks_dir(repo_root)
+    archive_dir = tasks_dir / "archive"
+    month = args.month
+
+    print(colored("Archived tasks:", Colors.BLUE))
+    print()
+
+    if month:
+        month_dir = archive_dir / month
+        if month_dir.is_dir():
+            print(f"[{month}]")
+            for d in sorted(month_dir.iterdir()):
+                if d.is_dir():
+                    print(f"  - {d.name}/")
+        else:
+            print(f"  No archives for {month}")
+    else:
+        if archive_dir.is_dir():
+            for month_dir in sorted(archive_dir.iterdir()):
+                if month_dir.is_dir():
+                    month_name = month_dir.name
+                    count = sum(1 for d in month_dir.iterdir() if d.is_dir())
+                    print(f"[{month_name}] - {count} task(s)")
+
+    return 0
+
+
+# =============================================================================
+# Command: set-branch
+# =============================================================================
+
+def cmd_set_branch(args: argparse.Namespace) -> int:
+    """Set git branch for task."""
+    repo_root = get_repo_root()
+    target_dir = _resolve_task_dir(args.dir, repo_root)
+    branch = args.branch
+
+    if not branch:
+        print(colored("Error: Missing arguments", Colors.RED))
+        print("Usage: python3 task.py set-branch <task-dir> <branch-name>")
+        return 1
+
+    task_json = target_dir / FILE_TASK_JSON
+    if not task_json.is_file():
+        print(colored(f"Error: task.json not found at {target_dir}", Colors.RED))
+        return 1
+
+    data = _read_json_file(task_json)
+    if not data:
+        return 1
+
+    data["branch"] = branch
+    _write_json_file(task_json, data)
+
+    print(colored(f"✓ Branch set to: {branch}", Colors.GREEN))
+    print()
+    print(colored("Now you can start the multi-agent pipeline:", Colors.BLUE))
+    print(f"  python3 ./.trellis/scripts/multi_agent/start.py {args.dir}")
+    return 0
+
+
+# =============================================================================
+# Command: set-base-branch
+# =============================================================================
+
+def cmd_set_base_branch(args: argparse.Namespace) -> int:
+    """Set the base branch (PR target) for task."""
+    repo_root = get_repo_root()
+    target_dir = _resolve_task_dir(args.dir, repo_root)
+    base_branch = args.base_branch
+
+    if not base_branch:
+        print(colored("Error: Missing arguments", Colors.RED))
+        print("Usage: python3 task.py set-base-branch <task-dir> <base-branch>")
+        print("Example: python3 task.py set-base-branch <dir> develop")
+        print()
+        print("This sets the target branch for PR (the branch your feature will merge into).")
+        return 1
+
+    task_json = target_dir / FILE_TASK_JSON
+    if not task_json.is_file():
+        print(colored(f"Error: task.json not found at {target_dir}", Colors.RED))
+        return 1
+
+    data = _read_json_file(task_json)
+    if not data:
+        return 1
+
+    data["base_branch"] = base_branch
+    _write_json_file(task_json, data)
+
+    print(colored(f"✓ Base branch set to: {base_branch}", Colors.GREEN))
+    print(f"  PR will target: {base_branch}")
+    return 0
+
+
+# =============================================================================
+# Command: set-scope
+# =============================================================================
+
+def cmd_set_scope(args: argparse.Namespace) -> int:
+    """Set scope for PR title."""
+    repo_root = get_repo_root()
+    target_dir = _resolve_task_dir(args.dir, repo_root)
+    scope = args.scope
+
+    if not scope:
+        print(colored("Error: Missing arguments", Colors.RED))
+        print("Usage: python3 task.py set-scope <task-dir> <scope>")
+        return 1
+
+    task_json = target_dir / FILE_TASK_JSON
+    if not task_json.is_file():
+        print(colored(f"Error: task.json not found at {target_dir}", Colors.RED))
+        return 1
+
+    data = _read_json_file(task_json)
+    if not data:
+        return 1
+
+    data["scope"] = scope
+    _write_json_file(task_json, data)
+
+    print(colored(f"✓ Scope set to: {scope}", Colors.GREEN))
+    return 0
+
+
+# =============================================================================
+# Command: create-pr (delegates to multi-agent script)
+# =============================================================================
+
+def cmd_create_pr(args: argparse.Namespace) -> int:
+    """Create PR from task - delegates to multi_agent/create_pr.py."""
+    import subprocess
+    script_dir = Path(__file__).parent
+    create_pr_script = script_dir / "multi_agent" / "create_pr.py"
+
+    cmd = [sys.executable, str(create_pr_script)]
+    if args.dir:
+        cmd.append(args.dir)
+    if args.dry_run:
+        cmd.append("--dry-run")
+
+    result = subprocess.run(cmd)
+    return result.returncode
+
+
+# =============================================================================
+# Help
+# =============================================================================
+
+def show_usage() -> None:
+    """Show usage help."""
+    print("""Task Management Script for Multi-Agent Pipeline
+
+Usage:
+  python3 task.py create <title>                     Create new task directory
+  python3 task.py create <title> --parent <dir>      Create task as child of parent
+  python3 task.py init-context <dir> <dev_type>      Initialize jsonl files
+  python3 task.py add-context <dir> <jsonl> <path> [reason]  Add entry to jsonl
+  python3 task.py validate <dir>                     Validate jsonl files
+  python3 task.py list-context <dir>                 List jsonl entries
+  python3 task.py start <dir>                        Set as current task
+  python3 task.py finish                             Clear current task
+  python3 task.py set-branch <dir> <branch>          Set git branch for multi-agent
+  python3 task.py set-scope <dir> <scope>            Set scope for PR title
+  python3 task.py create-pr [dir] [--dry-run]        Create PR from task
+  python3 task.py archive <task-name>                Archive completed task
+  python3 task.py add-subtask <parent> <child>       Link child task to parent
+  python3 task.py remove-subtask <parent> <child>    Unlink child from parent
+  python3 task.py list [--mine] [--status <status>]  List tasks
+  python3 task.py list-archive [YYYY-MM]             List archived tasks
+
+Arguments:
+  dev_type: backend | frontend | fullstack | test | docs
+
+List options:
+  --mine, -m           Show only tasks assigned to current developer
+  --status, -s <s>     Filter by status (planning, in_progress, review, completed)
+
+Examples:
+  python3 task.py create "Add login feature" --slug add-login
+  python3 task.py create "Child task" --slug child --parent .trellis/tasks/01-21-parent
+  python3 task.py init-context .trellis/tasks/01-21-add-login backend
+  python3 task.py add-context <dir> implement .trellis/spec/backend/auth.md "Auth guidelines"
+  python3 task.py set-branch <dir> task/add-login
+  python3 task.py start .trellis/tasks/01-21-add-login
+  python3 task.py create-pr                          # Uses current task
+  python3 task.py create-pr <dir> --dry-run          # Preview without changes
+  python3 task.py finish
+  python3 task.py archive add-login
+  python3 task.py add-subtask parent-task child-task  # Link existing tasks
+  python3 task.py remove-subtask parent-task child-task
+  python3 task.py list                               # List all active tasks
+  python3 task.py list --mine                        # List my tasks only
+  python3 task.py list --mine --status in_progress   # List my in-progress tasks
+""")
+
+
+# =============================================================================
+# Main Entry
+# =============================================================================
+
+def main() -> int:
+    """CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="Task Management Script for Multi-Agent Pipeline",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Commands")
+
+    # create
+    p_create = subparsers.add_parser("create", help="Create new task")
+    p_create.add_argument("title", help="Task title")
+    p_create.add_argument("--slug", "-s", help="Task slug")
+    p_create.add_argument("--assignee", "-a", help="Assignee developer")
+    p_create.add_argument("--priority", "-p", default="P2", help="Priority (P0-P3)")
+    p_create.add_argument("--description", "-d", help="Task description")
+    p_create.add_argument("--parent", help="Parent task directory (establishes subtask link)")
+
+    # init-context
+    p_init = subparsers.add_parser("init-context", help="Initialize context files")
+    p_init.add_argument("dir", help="Task directory")
+    p_init.add_argument("type", help="Dev type: backend|frontend|fullstack|test|docs")
+
+    # add-context
+    p_add = subparsers.add_parser("add-context", help="Add context entry")
+    p_add.add_argument("dir", help="Task directory")
+    p_add.add_argument("file", help="JSONL file (implement|check|debug)")
+    p_add.add_argument("path", help="File path to add")
+    p_add.add_argument("reason", nargs="?", help="Reason for adding")
+
+    # validate
+    p_validate = subparsers.add_parser("validate", help="Validate context files")
+    p_validate.add_argument("dir", help="Task directory")
+
+    # list-context
+    p_listctx = subparsers.add_parser("list-context", help="List context entries")
+    p_listctx.add_argument("dir", help="Task directory")
+
+    # start
+    p_start = subparsers.add_parser("start", help="Set current task")
+    p_start.add_argument("dir", help="Task directory")
+
+    # finish
+    subparsers.add_parser("finish", help="Clear current task")
+
+    # set-branch
+    p_branch = subparsers.add_parser("set-branch", help="Set git branch")
+    p_branch.add_argument("dir", help="Task directory")
+    p_branch.add_argument("branch", help="Branch name")
+
+    # set-base-branch
+    p_base = subparsers.add_parser("set-base-branch", help="Set PR target branch")
+    p_base.add_argument("dir", help="Task directory")
+    p_base.add_argument("base_branch", help="Base branch name (PR target)")
+
+    # set-scope
+    p_scope = subparsers.add_parser("set-scope", help="Set scope")
+    p_scope.add_argument("dir", help="Task directory")
+    p_scope.add_argument("scope", help="Scope name")
+
+    # create-pr
+    p_pr = subparsers.add_parser("create-pr", help="Create PR")
+    p_pr.add_argument("dir", nargs="?", help="Task directory")
+    p_pr.add_argument("--dry-run", action="store_true", help="Dry run mode")
+
+    # archive
+    p_archive = subparsers.add_parser("archive", help="Archive task")
+    p_archive.add_argument("name", help="Task name")
+    p_archive.add_argument("--no-commit", action="store_true", help="Skip auto git commit after archive")
+
+    # list
+    p_list = subparsers.add_parser("list", help="List tasks")
+    p_list.add_argument("--mine", "-m", action="store_true", help="My tasks only")
+    p_list.add_argument("--status", "-s", help="Filter by status")
+
+    # add-subtask
+    p_addsub = subparsers.add_parser("add-subtask", help="Link child task to parent")
+    p_addsub.add_argument("parent_dir", help="Parent task directory")
+    p_addsub.add_argument("child_dir", help="Child task directory")
+
+    # remove-subtask
+    p_rmsub = subparsers.add_parser("remove-subtask", help="Unlink child task from parent")
+    p_rmsub.add_argument("parent_dir", help="Parent task directory")
+    p_rmsub.add_argument("child_dir", help="Child task directory")
+
+    # list-archive
+    p_listarch = subparsers.add_parser("list-archive", help="List archived tasks")
+    p_listarch.add_argument("month", nargs="?", help="Month (YYYY-MM)")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        show_usage()
+        return 1
+
+    commands = {
+        "create": cmd_create,
+        "init-context": cmd_init_context,
+        "add-context": cmd_add_context,
+        "validate": cmd_validate,
+        "list-context": cmd_list_context,
+        "start": cmd_start,
+        "finish": cmd_finish,
+        "set-branch": cmd_set_branch,
+        "set-base-branch": cmd_set_base_branch,
+        "set-scope": cmd_set_scope,
+        "create-pr": cmd_create_pr,
+        "archive": cmd_archive,
+        "add-subtask": cmd_add_subtask,
+        "remove-subtask": cmd_remove_subtask,
+        "list": cmd_list,
+        "list-archive": cmd_list_archive,
+    }
+
+    if args.command in commands:
+        return commands[args.command](args)
+    else:
+        show_usage()
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.trellis/spec/backend/database-guidelines.md b/.trellis/spec/backend/database-guidelines.md
new file mode 100644
index 000000000..b61aa7840
--- /dev/null
+++ b/.trellis/spec/backend/database-guidelines.md
@@ -0,0 +1,51 @@
+# Database Guidelines
+
+> Database patterns and conventions for this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's database conventions here.
+
+Questions to answer:
+- What ORM/query library do you use?
+- How are migrations managed?
+- What are the naming conventions for tables/columns?
+- How do you handle transactions?
+-->
+
+(To be filled by the team)
+
+---
+
+## Query Patterns
+
+<!-- How should queries be written? Batch operations? -->
+
+(To be filled by the team)
+
+---
+
+## Migrations
+
+<!-- How to create and run migrations -->
+
+(To be filled by the team)
+
+---
+
+## Naming Conventions
+
+<!-- Table names, column names, index names -->
+
+(To be filled by the team)
+
+---
+
+## Common Mistakes
+
+<!-- Database-related mistakes your team has made -->
+
+(To be filled by the team)
diff --git a/.trellis/spec/backend/directory-structure.md b/.trellis/spec/backend/directory-structure.md
new file mode 100644
index 000000000..9bb253dff
--- /dev/null
+++ b/.trellis/spec/backend/directory-structure.md
@@ -0,0 +1,54 @@
+# Directory Structure
+
+> How backend code is organized in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's backend directory structure here.
+
+Questions to answer:
+- How are modules/packages organized?
+- Where does business logic live?
+- Where are API endpoints defined?
+- How are utilities and helpers organized?
+-->
+
+(To be filled by the team)
+
+---
+
+## Directory Layout
+
+```
+<!-- Replace with your actual structure -->
+src/
+├── ...
+└── ...
+```
+
+---
+
+## Module Organization
+
+<!-- How should new features/modules be organized? -->
+
+(To be filled by the team)
+
+---
+
+## Naming Conventions
+
+<!-- File and folder naming rules -->
+
+(To be filled by the team)
+
+---
+
+## Examples
+
+<!-- Link to well-organized modules as examples -->
+
+(To be filled by the team)
diff --git a/.trellis/spec/backend/error-handling.md b/.trellis/spec/backend/error-handling.md
new file mode 100644
index 000000000..bcd553376
--- /dev/null
+++ b/.trellis/spec/backend/error-handling.md
@@ -0,0 +1,51 @@
+# Error Handling
+
+> How errors are handled in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's error handling conventions here.
+
+Questions to answer:
+- What error types do you define?
+- How are errors propagated?
+- How are errors logged?
+- How are errors returned to clients?
+-->
+
+(To be filled by the team)
+
+---
+
+## Error Types
+
+<!-- Custom error classes/types -->
+
+(To be filled by the team)
+
+---
+
+## Error Handling Patterns
+
+<!-- Try-catch patterns, error propagation -->
+
+(To be filled by the team)
+
+---
+
+## API Error Responses
+
+<!-- Standard error response format -->
+
+(To be filled by the team)
+
+---
+
+## Common Mistakes
+
+<!-- Error handling mistakes your team has made -->
+
+(To be filled by the team)
diff --git a/.trellis/spec/backend/index.md b/.trellis/spec/backend/index.md
new file mode 100644
index 000000000..16f66f44c
--- /dev/null
+++ b/.trellis/spec/backend/index.md
@@ -0,0 +1,40 @@
+# Backend Development Guidelines
+
+> Best practices for backend development in this project.
+
+---
+
+## Overview
+
+This directory contains guidelines for backend development. Fill in each file with your project's specific conventions.
+
+---
+
+## Guidelines Index
+
+| Guide | Description | Status |
+|-------|-------------|--------|
+| [Directory Structure](./directory-structure.md) | Module organization and file layout | To fill |
+| [Database Guidelines](./database-guidelines.md) | ORM patterns, queries, migrations | To fill |
+| [Error Handling](./error-handling.md) | Error types, handling strategies | To fill |
+| [Quality Guidelines](./quality-guidelines.md) | Code standards, forbidden patterns | To fill |
+| [Logging Guidelines](./logging-guidelines.md) | Structured logging, log levels | To fill |
+| [Runtime Context And Compaction Contracts](./runtime-context-compaction-contracts.md) | Executable contracts for session resume, compact artifacts, generated manual compact, and memory quality | Active |
+| [Task Workflow Contracts](./task-workflow-contracts.md) | Executable contracts for durable task graph readiness, transitions, and verification boundary | Active |
+
+---
+
+## How to Fill These Guidelines
+
+For each guideline file:
+
+1. Document your project's **actual conventions** (not ideals)
+2. Include **code examples** from your codebase
+3. List **forbidden patterns** and why
+4. Add **common mistakes** your team has made
+
+The goal is to help AI assistants and new team members understand how YOUR project works.
+
+---
+
+**Language**: All documentation should be written in **English**.
diff --git a/.trellis/spec/backend/logging-guidelines.md b/.trellis/spec/backend/logging-guidelines.md
new file mode 100644
index 000000000..bb930df81
--- /dev/null
+++ b/.trellis/spec/backend/logging-guidelines.md
@@ -0,0 +1,51 @@
+# Logging Guidelines
+
+> How logging is done in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's logging conventions here.
+
+Questions to answer:
+- What logging library do you use?
+- What are the log levels and when to use each?
+- What should be logged?
+- What should NOT be logged (PII, secrets)?
+-->
+
+(To be filled by the team)
+
+---
+
+## Log Levels
+
+<!-- When to use each level: debug, info, warn, error -->
+
+(To be filled by the team)
+
+---
+
+## Structured Logging
+
+<!-- Log format, required fields -->
+
+(To be filled by the team)
+
+---
+
+## What to Log
+
+<!-- Important events to log -->
+
+(To be filled by the team)
+
+---
+
+## What NOT to Log
+
+<!-- Sensitive data, PII, secrets -->
+
+(To be filled by the team)
diff --git a/.trellis/spec/backend/quality-guidelines.md b/.trellis/spec/backend/quality-guidelines.md
new file mode 100644
index 000000000..c1e1065a2
--- /dev/null
+++ b/.trellis/spec/backend/quality-guidelines.md
@@ -0,0 +1,51 @@
+# Quality Guidelines
+
+> Code quality standards for backend development.
+
+---
+
+## Overview
+
+<!--
+Document your project's quality standards here.
+
+Questions to answer:
+- What patterns are forbidden?
+- What linting rules do you enforce?
+- What are your testing requirements?
+- What code review standards apply?
+-->
+
+(To be filled by the team)
+
+---
+
+## Forbidden Patterns
+
+<!-- Patterns that should never be used and why -->
+
+(To be filled by the team)
+
+---
+
+## Required Patterns
+
+<!-- Patterns that must always be used -->
+
+(To be filled by the team)
+
+---
+
+## Testing Requirements
+
+<!-- What level of testing is expected -->
+
+(To be filled by the team)
+
+---
+
+## Code Review Checklist
+
+<!-- What reviewers should check -->
+
+(To be filled by the team)
diff --git a/.trellis/spec/backend/runtime-context-compaction-contracts.md b/.trellis/spec/backend/runtime-context-compaction-contracts.md
new file mode 100644
index 000000000..be7184296
--- /dev/null
+++ b/.trellis/spec/backend/runtime-context-compaction-contracts.md
@@ -0,0 +1,357 @@
+# Runtime Context And Compaction Contracts
+
+> Executable contracts for the coding-deepgent session, recovery, memory, and manual compaction seams.
+
+## Scenario: Session Resume And Manual Compaction
+
+### 1. Scope / Trigger
+
+- Trigger: Changes touching `coding_deepgent.cli`, `coding_deepgent.cli_service`, `coding_deepgent.sessions`, `coding_deepgent.compact`, `coding_deepgent.memory`, or runtime message projection.
+- Applies when a feature changes how conversation history, recovery brief context, compact summaries, or long-term memory are assembled for a model call.
+- This is an infra/cross-layer contract because CLI flags, session JSONL records, in-memory runtime state, LangChain message dictionaries, and tests must agree.
+
+### 2. Signatures
+
+#### CLI
+
+```bash
+coding-deepgent sessions resume SESSION_ID
+coding-deepgent sessions resume SESSION_ID --prompt TEXT
+coding-deepgent sessions resume SESSION_ID --prompt TEXT --compact-summary SUMMARY [--compact-keep-last N]
+coding-deepgent sessions resume SESSION_ID --prompt TEXT --generate-compact-summary [--compact-instructions TEXT] [--compact-keep-last N]
+```
+
+#### Python Service Seams
+
+```python
+def continuation_history(loaded: LoadedSession) -> list[dict[str, Any]]: ...
+
+def compacted_continuation_history(
+    loaded: LoadedSession,
+    *,
+    summary: str,
+    keep_last: int = 4,
+) -> list[dict[str, Any]]: ...
+
+def generated_compacted_continuation_history(
+    loaded: LoadedSession,
+    *,
+    summarizer: Any,
+    keep_last: int = 4,
+    custom_instructions: str | None = None,
+) -> list[dict[str, Any]]: ...
+
+def compact_messages_with_summary(
+    messages: list[dict[str, Any]],
+    *,
+    summary: str,
+    keep_last: int = 4,
+) -> CompactArtifact: ...
+
+def generate_compact_summary(
+    messages: list[dict[str, Any]],
+    summarizer: CompactSummarizer | Callable[[list[dict[str, Any]]], Any],
+    *,
+    custom_instructions: str | None = None,
+) -> str: ...
+
+def append_compact(
+    context: SessionContext,
+    *,
+    trigger: str,
+    summary: str,
+    original_message_count: int,
+    summarized_message_count: int,
+    kept_message_count: int,
+    metadata: dict[str, Any] | None = None,
+) -> Path: ...
+
+class LoadedSession:
+    history: list[dict[str, str]]
+    compacted_history: list[dict[str, Any]]
+    compacted_history_source: CompactedHistorySource
+    state: dict[str, Any]
+    evidence: list[SessionEvidence]
+    compacts: list[SessionCompact]
+    summary: SessionSummary
+
+class RuntimeContext:
+    session_context: SessionContext | None = None
+
+class CompactedHistorySource:
+    mode: Literal["raw", "compact"]
+    reason: str
+    compact_index: int | None = None
+```
+
+### 3. Contracts
+
+#### Resume Continuation History
+
+- `continuation_history(loaded)` must return:
+  1. one system resume context message from `build_resume_context_message(loaded)`
+  2. all `loaded.history` messages in original order
+- The resume context message content starts with `RESUME_CONTEXT_MESSAGE_PREFIX`.
+- `sessions.service.run_prompt_with_recording()` must not count synthetic resume context messages when assigning persisted `message_index` values.
+- When `run_prompt_with_recording()` creates or resumes a recorded session and
+  the agent callable accepts `session_context`, it must pass the active
+  `SessionContext` into runtime invocation context so tools can append bounded
+  evidence records to the same session ledger.
+- `render_recovery_brief()` must render concise provenance for verification
+  evidence when available, using stable short fields such as `plan=<plan_id>`
+  and `verdict=<verdict>`.
+- `render_recovery_brief()` must not dump arbitrary evidence metadata for
+  runtime or verification evidence.
+
+#### Manual Compact Continuation History
+
+- `compacted_continuation_history(loaded, summary=..., keep_last=N)` must return:
+  1. recovery brief system message
+  2. compact boundary system message
+  3. compact summary user message
+  4. preserved recent tail messages
+- Compact boundary and summary messages use structured text content blocks:
+
+```python
+{"role": "system", "content": [{"type": "text", "text": "..."}]}
+{"role": "user", "content": [{"type": "text", "text": "..."}]}
+```
+
+- Structured content is intentional. It prevents `project_messages()` from merging the compact summary into adjacent plain user messages.
+- `format_compact_summary()` must strip `<analysis>...</analysis>` and unwrap `<summary>...</summary>`.
+- `compact_messages_with_summary()` must not mutate the input `messages` list or its nested dictionaries.
+- If the kept tail includes a `tool_result` block, the helper must include matching earlier `tool_use` blocks when they exist in the source messages.
+
+#### Generated Manual Compact
+
+- `--generate-compact-summary` is explicit and user-triggered only.
+- It must call `build_openai_model(settings)` only when `--generate-compact-summary` is present.
+- It must pass the loaded history into `generate_compact_summary()` through the fakeable summarizer seam.
+- It must not add LangChain `SummarizationMiddleware`.
+- It must not delete, prune, rewrite, or compact persisted session JSONL transcript records.
+
+#### Compact Transcript Records
+
+- Compact events are persisted as append-only JSONL records with `record_type == "compact"`.
+- Compact records must be loaded into `LoadedSession.compacts`.
+- Compact records must increment `SessionSummary.compact_count`.
+- Compact records must not appear in `LoadedSession.history`.
+- Compact records must not replace or delete any message/state/evidence record.
+- `LoadedSession.history` is the raw/full user-assistant transcript view.
+- `LoadedSession.compacted_history` is the load-time virtual compacted view.
+- `LoadedSession.compacted_history_source` explains whether the compacted view came from raw fallback or a compact record.
+- If no valid compact-derived view exists, `compacted_history` must fall back to `history`.
+- Required compact record fields:
+
+```json
+{
+  "record_type": "compact",
+  "version": 1,
+  "session_id": "...",
+  "timestamp": "...",
+  "cwd": "...",
+  "trigger": "manual",
+  "summary": "...",
+  "original_message_count": 2,
+  "summarized_message_count": 1,
+  "kept_message_count": 1
+}
+```
+
+- When continuation history contains synthetic compact artifacts, `run_prompt_with_recording()` must append one compact record before recording the continuation prompt.
+- The next persisted message index after compacted continuation must use `original_message_count` from the compact metadata, not the count of preserved synthetic history messages.
+
+#### Load-Time Compacted History View
+
+- `JsonlSessionStore.load_session()` must derive `LoadedSession.compacted_history` from the newest compact record that yields a valid compact-derived view.
+- The compacted view must be:
+  1. compact boundary message
+  2. compact summary message
+  3. preserved tail messages
+- Tail start is derived as:
+
+```python
+keep_from = original_message_count - kept_message_count
+```
+
+- Tail derivation is clamped to `[0, len(raw_history)]`.
+- Compact records must be scanned from newest to oldest.
+- If the latest compact record's derived tail is empty or invalid, the loader must try the next earlier compact record.
+- If no compact record yields a valid compact-derived view, `compacted_history` must fall back to the raw history.
+- `compacted_history_source.mode` must be:
+  - `"compact"` when a compact record produces the selected view
+  - `"raw"` when no compact view is selected
+- `compacted_history_source.reason` must distinguish at least:
+  - `"no_compacts"`
+  - `"latest_valid_compact"`
+  - `"no_valid_compact"`
+- `compacted_history_source.compact_index` is the zero-based index into `LoadedSession.compacts` when `mode == "compact"`.
+- Compact-aware resume selectors should use `compacted_history` rather than re-derive compact semantics ad hoc.
+
+#### Memory Quality
+
+- `save_memory` writes only through `runtime.store`.
+- Before writing, it must call `evaluate_memory_quality(record, existing_records=...)`.
+- It must reject:
+  - normalized duplicates in the same namespace
+  - obvious transient task/session state
+  - trivially short low-value content
+- It must return `"Memory not saved: ..."` when rejecting, and must not write to the store.
+
+### 4. Validation & Error Matrix
+
+| Case | Expected behavior |
+|---|---|
+| `sessions resume SESSION_ID` | prints recovery brief and continuation hint |
+| `--compact-summary` without `--prompt` | Click error; run path is not called |
+| `--generate-compact-summary` without `--prompt` | Click error; run path is not called |
+| `--compact-instructions` without `--generate-compact-summary` | Click error; run path is not called |
+| `--compact-summary` and `--generate-compact-summary` together | Click error; run path is not called |
+| blank compact summary | `ValueError` from compaction helper, surfaced as Click error |
+| summarizer returns only `<analysis>` or blank text | `ValueError("compact summarizer returned an empty summary")` |
+| compact tail starts with `tool_result` | include matching previous `tool_use` message when present |
+| resume context history is recorded to transcript | synthetic resume context is not persisted as a message record |
+| compacted history is recorded to transcript | synthetic compact artifacts are not persisted as message records; one compact record is appended |
+| compacted history preserves only recent tail | next real message index starts at compact `original_message_count` |
+| multiple valid compact records exist | `LoadedSession.compacted_history` uses the newest valid compact record |
+| latest compact record is invalid but an earlier compact record is valid | `LoadedSession.compacted_history` uses the earlier valid compact record |
+| compact record exists and derived tail is valid | `LoadedSession.compacted_history` contains boundary + summary + preserved tail |
+| no compact record yields a valid derived tail | `LoadedSession.compacted_history` falls back to raw history |
+| selected compacted view comes from compact record at index N | `compacted_history_source == compact/latest_valid_compact/N` |
+| selected compacted view falls back to raw history | `compacted_history_source == raw/<reason>/None` |
+| duplicate memory save | returns "Memory not saved" and store remains unchanged |
+| verification evidence with `plan_id` and `verdict` metadata | recovery brief includes concise `(plan=...; verdict=...)` provenance |
+| non-verification evidence with metadata | recovery brief does not render arbitrary metadata |
+
+### 5. Good / Base / Bad Cases
+
+#### Good
+
+```bash
+coding-deepgent sessions resume session-1 \
+  --prompt "continue" \
+  --generate-compact-summary \
+  --compact-instructions "Focus on code changes and failed tests." \
+  --compact-keep-last 4
+```
+
+Expected:
+- Generated summary goes through `generate_compact_summary()`.
+- Continuation history starts with recovery brief, compact boundary, compact summary, then recent messages.
+- Transcript only records the new user prompt and assistant result from the continuation path.
+
+#### Base
+
+```bash
+coding-deepgent sessions resume session-1 --prompt "continue"
+```
+
+Expected:
+- Continuation history is recovery brief + loaded history.
+- No compact artifact is inserted.
+
+#### Bad
+
+```bash
+coding-deepgent sessions resume session-1 \
+  --prompt "continue" \
+  --compact-summary "manual" \
+  --generate-compact-summary
+```
+
+Expected:
+- Reject with a Click error before model construction or run prompt.
+
+### 6. Tests Required
+
+Required focused tests:
+
+- `tests/test_cli.py::test_sessions_resume_uses_recovery_brief_continuation_history`
+- `tests/test_cli.py::test_sessions_resume_can_use_manual_compact_summary`
+- `tests/test_cli.py::test_sessions_resume_can_generate_manual_compact_summary`
+- `tests/test_cli.py::test_sessions_resume_rejects_manual_and_generated_compact_together`
+- `tests/test_cli.py::test_sessions_resume_rejects_compact_options_without_prompt`
+- `tests/test_cli.py::test_sessions_resume_rejects_compact_instructions_without_generation`
+- `tests/test_cli.py::test_run_once_records_new_and_resumed_session_transcript`
+- `tests/test_cli.py::test_run_once_records_compact_metadata_without_message_index_skew`
+- `tests/test_cli.py::test_selected_continuation_history_uses_loaded_compacted_history`
+- `tests/test_cli.py::test_sessions_resume_defaults_to_latest_compacted_continuation_when_available`
+- `tests/test_compact_artifacts.py`
+- `tests/test_compact_summarizer.py`
+- `tests/test_message_projection.py`
+- `tests/test_sessions.py::test_compact_record_roundtrip_does_not_enter_history`
+- `tests/test_sessions.py::test_load_session_ignores_invalid_compact_records`
+- `tests/test_sessions.py::test_load_session_compacted_history_falls_back_to_raw_history_on_invalid_tail_range`
+- `tests/test_sessions.py::test_load_session_compacted_history_uses_newest_valid_compact_record`
+- `tests/test_sessions.py::test_load_session_compacted_history_uses_latest_valid_compact_record`
+- `tests/test_sessions.py::test_recovery_brief_renders_verification_provenance_only`
+- `tests/test_memory.py::test_memory_quality_policy_rejects_transient_and_duplicate_entries`
+- `tests/test_memory_integration.py::test_save_memory_tool_rejects_transient_memory_via_create_agent_runtime`
+
+Required assertion points:
+
+- generated compact summary uses a fake summarizer in tests
+- fake summarizer receives original loaded history plus compact prompt message
+- `<analysis>` is absent from compact artifact summary text
+- compact summary artifact is not merged by `project_messages()`
+- compact transcript records are separated from `LoadedSession.history`
+- compacted history view is derived at load time and kept separate from raw history
+- persisted transcript `message_index` values remain contiguous for real persisted messages only
+- compacted continuation uses compact `original_message_count` as the next real message index baseline
+- rejected compact CLI combinations do not call `run_prompt`
+- rejected memory writes do not mutate LangGraph store
+
+### 7. Wrong vs Correct
+
+#### Wrong
+
+```python
+history = [
+    {"role": "user", "content": f"Summary: {summary}"},
+    *loaded.history[-keep_last:],
+]
+```
+
+Why wrong:
+- Plain same-role user messages can be merged by `project_messages()`.
+- No compact boundary exists.
+- Recovery brief is lost.
+- Tool result tails can be orphaned from their tool use.
+
+#### Correct
+
+```python
+history = cli_service.generated_compacted_continuation_history(
+    loaded,
+    summarizer=summarizer,
+    keep_last=4,
+    custom_instructions="Focus on code changes.",
+)
+```
+
+Why correct:
+- Reuses the recovery brief.
+- Reuses the Stage 13 compact boundary and summary artifact shape.
+- Formats generated summary through the Stage 13C seam.
+- Keeps compaction explicit and non-destructive.
+
+#### Wrong
+
+```python
+middleware=[SummarizationMiddleware(model="gpt-4.1-mini", trigger=("tokens", 4000))]
+```
+
+Why wrong for the current stage:
+- It introduces automatic lifecycle summarization and persistent state replacement.
+- The current product contract is explicit manual compaction only.
+
+#### Correct
+
+```python
+if generate_compact_summary:
+    history = cli_service.generated_compacted_continuation_history(...)
+```
+
+Why correct:
+- Model construction and summarization happen only after explicit user opt-in.
+- No automatic transcript or state mutation is introduced.
diff --git a/.trellis/spec/backend/task-workflow-contracts.md b/.trellis/spec/backend/task-workflow-contracts.md
new file mode 100644
index 000000000..506a8305b
--- /dev/null
+++ b/.trellis/spec/backend/task-workflow-contracts.md
@@ -0,0 +1,235 @@
+# Task Workflow Contracts
+
+> Executable contracts for durable task graph and plan/verify workflow boundaries.
+
+## Scenario: Durable Task Graph
+
+### 1. Scope / Trigger
+
+- Trigger: changes touching `coding_deepgent.tasks`, task tools, task graph transitions, or workflow verification behavior.
+- TodoWrite remains short-term state. Durable Task is store-backed collaboration/workflow state.
+
+### 2. Signatures
+
+```python
+def create_task(
+    store: TaskStore,
+    *,
+    title: str,
+    description: str = "",
+    depends_on: list[str] | None = None,
+    owner: str | None = None,
+    metadata: dict[str, str] | None = None,
+) -> TaskRecord: ...
+
+def update_task(
+    store: TaskStore,
+    *,
+    task_id: str,
+    status: TaskStatus | None = None,
+    depends_on: list[str] | None = None,
+    owner: str | None = None,
+    metadata: dict[str, str] | None = None,
+) -> TaskRecord: ...
+
+def is_task_ready(store: TaskStore, record: TaskRecord) -> bool: ...
+def validate_task_graph(store: TaskStore) -> None: ...
+def task_graph_needs_verification(store: TaskStore) -> bool: ...
+
+def create_plan(
+    store: TaskStore,
+    *,
+    title: str,
+    content: str,
+    verification: str,
+    task_ids: list[str] | None = None,
+    metadata: dict[str, str] | None = None,
+) -> PlanArtifact: ...
+
+def get_plan(store: TaskStore, plan_id: str) -> PlanArtifact: ...
+
+def run_subagent(
+    task: str,
+    runtime: ToolRuntime,
+    agent_type: Literal["general", "verifier"] = "general",
+    plan_id: str | None = None,
+    max_turns: int = 1,
+) -> str: ...
+
+def record_verifier_evidence(
+    *,
+    result: SubagentResult,
+    runtime: ToolRuntime,
+) -> bool: ...
+```
+
+### 3. Contracts
+
+- `TaskRecord.depends_on` is the local blocked-by edge.
+- Creating or updating dependencies must reject:
+  - unknown task IDs
+  - self-dependency
+  - dependency cycles
+- `is_task_ready()` is true only when:
+  - task status is `pending`
+  - every dependency is `completed`
+- Moving a task to `blocked` requires either:
+  - at least one dependency
+  - or `metadata["blocked_reason"]`
+- `task_list` must expose ready state in rendered JSON metadata as `"ready": "true"` or `"false"`.
+- Completing a 3+ non-cancelled task graph without a verification task must expose a `verification_nudge` in the returned `task_update` JSON metadata.
+- Verification nudge is output metadata only; it must not mutate the stored task record.
+- `PlanArtifact` is the durable plan boundary for implementation workflow.
+- `PlanArtifact.verification` is required and must be non-empty.
+- `PlanArtifact.task_ids` must reference existing durable tasks.
+- Plan artifacts use a separate store namespace from task records.
+- `plan_save` and `plan_get` are main-surface tools, but they do not enter TodoWrite state.
+- `plan_get` is allowed for verifier subagents.
+- `plan_save` is forbidden for verifier subagents.
+- `run_subagent` with `agent_type="verifier"` requires `plan_id`.
+- Verifier subagent execution requires a configured task store.
+- Verifier subagent execution must resolve the durable plan artifact before child execution begins.
+- Verifier subagent output must expose the durable plan boundary as structured JSON including:
+  - `plan_id`
+  - `plan_title`
+  - `verification`
+  - `task_ids`
+  - `tool_allowlist`
+  - `content`
+- Verifier subagent content that includes `VERDICT: PASS|FAIL|PARTIAL` must append
+  one existing session evidence record when `runtime.context.session_context` is
+  available.
+- Verifier evidence must use:
+  - `kind="verification"`
+  - status mapped as `PASS -> passed`, `FAIL -> failed`, `PARTIAL -> partial`
+  - `subject=<plan_id>`
+  - metadata containing at least `plan_id` and `verdict`
+  - bounded lineage metadata when runtime context is available:
+    `parent_session_id`, `parent_thread_id`, `child_thread_id`, and
+    `verifier_agent_name`
+- Verifier evidence persistence is bounded to the synchronous `run_subagent`
+  verifier tool call.
+- Verifier evidence persistence must not mutate durable tasks or plan artifacts.
+- Verifier calls without `runtime.context.session_context` skip evidence
+  persistence explicitly and still preserve the verifier JSON result contract.
+
+### 4. Validation & Error Matrix
+
+| Case | Expected behavior |
+|---|---|
+| create task with missing dependency | `ValueError("Unknown task dependencies...")` |
+| update task to depend on itself | `ValueError("cannot depend on itself")` |
+| update task to create a cycle | `ValueError("cycle")` |
+| mark blocked without dependency or reason | `ValueError("blocked tasks require...")` |
+| pending task with completed dependencies | `is_task_ready(...) is True` |
+| completed/cancelled/in_progress task | `is_task_ready(...) is False` |
+| 3 completed non-verification tasks | `task_graph_needs_verification(...) is True` |
+| graph includes verification task | `task_graph_needs_verification(...) is False` |
+| `task_update` closes 3rd non-verification task | output metadata includes `verification_nudge=true` |
+| save plan with missing verification | Pydantic validation error |
+| save plan with unknown task id | `ValueError("Unknown task dependencies...")` |
+| get missing plan | `KeyError("Unknown plan...")` |
+| verifier child tool allowlist | includes `plan_get`, excludes `plan_save` |
+| verifier subagent without `plan_id` | Pydantic validation error |
+| verifier subagent without runtime store | `RuntimeError("Verifier subagent requires task store")` |
+| verifier subagent with missing plan | `KeyError("Unknown plan...")` |
+| verifier subagent output | structured JSON parseable as verifier result |
+| verifier output with `VERDICT: PASS` and session context | one `verification` evidence record with `status == "passed"` |
+| verifier output with `VERDICT: FAIL` and session context | one `verification` evidence record with `status == "failed"` |
+| verifier output with `VERDICT: PARTIAL` and session context | one `verification` evidence record with `status == "partial"` |
+| persisted verifier evidence has runtime context | metadata includes parent and child verifier lineage fields |
+| verifier output without session context | verifier JSON result is returned and no evidence persistence is attempted |
+
+### 5. Good / Base / Bad Cases
+
+#### Good
+
+```python
+parent = create_task(store, title="Implement feature")
+child = create_task(store, title="Run verification", depends_on=[parent.id])
+update_task(store, task_id=parent.id, status="in_progress")
+update_task(store, task_id=parent.id, status="completed")
+assert is_task_ready(store, get_task(store, child.id)) is True
+```
+
+#### Base
+
+```python
+task = create_task(store, title="Investigate failure")
+update_task(
+    store,
+    task_id=task.id,
+    status="blocked",
+    metadata={"blocked_reason": "Need logs"},
+)
+```
+
+#### Bad
+
+```python
+update_task(store, task_id=task.id, depends_on=[task.id])
+```
+
+Expected: reject self-dependency.
+
+#### Plan Artifact
+
+```python
+task = create_task(store, title="Implement feature")
+plan = create_plan(
+    store,
+    title="Feature plan",
+    content="Use the existing task store and tests.",
+    verification="Run pytest tests/test_tasks.py",
+    task_ids=[task.id],
+)
+```
+
+Expected:
+- plan has stable id
+- verification criteria are non-empty
+- referenced task IDs exist
+
+### 6. Tests Required
+
+- `tests/test_tasks.py::test_task_store_transitions_dependencies_and_ready_rule`
+- `tests/test_tasks.py::test_task_graph_rejects_missing_self_and_cycle_dependencies`
+- `tests/test_tasks.py::test_task_update_requires_blocked_reason_or_dependency`
+- `tests/test_tasks.py::test_task_graph_needs_verification_after_closing_three_tasks`
+- `tests/test_tasks.py::test_task_graph_with_verification_task_does_not_need_nudge`
+- `tests/test_tasks.py::test_task_update_tool_marks_verification_nudge_in_output_metadata`
+- `tests/test_tasks.py::test_plan_artifact_roundtrip_requires_verification_and_known_tasks`
+- `tests/test_tasks.py::test_plan_tools_save_and_get_artifacts`
+- `tests/test_tool_system_registry.py::test_main_projection_preserves_current_product_tool_surface`
+- `tests/test_subagents.py::test_subagent_allowlists_are_exact_and_exclude_mutating_tools`
+- `tests/test_subagents.py::test_verifier_subagent_requires_plan_id`
+- `tests/test_subagents.py::test_verifier_subagent_requires_task_store`
+- `tests/test_subagents.py::test_verifier_subagent_rejects_unknown_plan`
+- `tests/test_subagents.py::test_run_subagent_task_verifier_uses_durable_plan_payload`
+- `tests/test_subagents.py::test_run_subagent_tool_returns_structured_verifier_result`
+- `tests/test_subagents.py::test_verifier_verdict_helpers_map_status_and_summary`
+- `tests/test_subagents.py::test_run_subagent_tool_persists_verifier_evidence_roundtrip`
+- `tests/test_subagents.py::test_run_subagent_tool_skips_verifier_evidence_without_recording_context`
+
+### 7. Wrong vs Correct
+
+#### Wrong
+
+```python
+TaskRecord(title="Child", depends_on=["maybe-existing"])
+```
+
+Why wrong:
+- Durable task dependencies must reference existing task IDs.
+- Loose dependencies break readiness and future multi-agent work.
+
+#### Correct
+
+```python
+parent = create_task(store, title="Parent")
+child = create_task(store, title="Child", depends_on=[parent.id])
+```
+
+Why correct:
+- Dependency is validated at creation.
+- Readiness can be computed deterministically.
diff --git a/.trellis/spec/frontend/component-guidelines.md b/.trellis/spec/frontend/component-guidelines.md
new file mode 100644
index 000000000..3282057e2
--- /dev/null
+++ b/.trellis/spec/frontend/component-guidelines.md
@@ -0,0 +1,19 @@
+# Frontend Component Guidelines
+
+Document how UI components are written in this project.
+
+## What to Capture
+
+- Component naming conventions
+- Prop design and typing style
+- Composition patterns
+- Server vs client component rules
+- Styling conventions
+
+## Real Examples
+
+- Add 2-3 component examples from the codebase
+
+## Anti-Patterns
+
+- List patterns the project avoids
diff --git a/.trellis/spec/frontend/directory-structure.md b/.trellis/spec/frontend/directory-structure.md
new file mode 100644
index 000000000..fdeb67c12
--- /dev/null
+++ b/.trellis/spec/frontend/directory-structure.md
@@ -0,0 +1,19 @@
+# Frontend Directory Structure
+
+Document how frontend code is organized in this project.
+
+## What to Capture
+
+- Where routes or pages live
+- Where shared components live
+- Where feature-specific components live
+- Where hooks, utils, and types live
+- How assets, fixtures, and generated files are separated
+
+## Real Examples
+
+- Add 2-3 file path examples from the codebase
+
+## Anti-Patterns
+
+- List structures the project avoids
diff --git a/.trellis/spec/frontend/hook-guidelines.md b/.trellis/spec/frontend/hook-guidelines.md
new file mode 100644
index 000000000..8e72a44df
--- /dev/null
+++ b/.trellis/spec/frontend/hook-guidelines.md
@@ -0,0 +1,19 @@
+# Frontend Hook Guidelines
+
+Document how custom hooks are written and used in this project.
+
+## What to Capture
+
+- Hook naming conventions
+- When logic belongs in a hook
+- Dependency management expectations
+- Async and side-effect handling
+- Return shape conventions
+
+## Real Examples
+
+- Add 2-3 hook examples from the codebase
+
+## Anti-Patterns
+
+- List patterns the project avoids
diff --git a/.trellis/spec/frontend/index.md b/.trellis/spec/frontend/index.md
new file mode 100644
index 000000000..e5862f427
--- /dev/null
+++ b/.trellis/spec/frontend/index.md
@@ -0,0 +1,39 @@
+# Frontend Development Guidelines
+
+> Best practices for frontend development in this project.
+
+---
+
+## Overview
+
+This directory contains guidelines for frontend development. Fill in each file with your project's specific conventions.
+
+---
+
+## Guidelines Index
+
+| Guide | Description | Status |
+|-------|-------------|--------|
+| [Directory Structure](./directory-structure.md) | App, page, component, and hook organization | To fill |
+| [Component Guidelines](./component-guidelines.md) | Component patterns, props, and composition | To fill |
+| [Hook Guidelines](./hook-guidelines.md) | Custom hook naming, dependencies, and side effects | To fill |
+| [State Management](./state-management.md) | Local, shared, server, and derived state patterns | To fill |
+| [Type Safety](./type-safety.md) | TypeScript conventions and type organization | To fill |
+| [Quality Guidelines](./quality-guidelines.md) | Testing, accessibility, linting, and review expectations | To fill |
+
+---
+
+## How to Fill These Guidelines
+
+For each guideline file:
+
+1. Document your project's **actual conventions** (not ideals)
+2. Include **code examples** from your codebase
+3. List **forbidden patterns** and why
+4. Add **common mistakes** your team has made
+
+The goal is to help AI assistants and new team members understand how YOUR project works.
+
+---
+
+**Language**: All documentation should be written in **English**.
diff --git a/.trellis/spec/frontend/quality-guidelines.md b/.trellis/spec/frontend/quality-guidelines.md
new file mode 100644
index 000000000..4230d550a
--- /dev/null
+++ b/.trellis/spec/frontend/quality-guidelines.md
@@ -0,0 +1,19 @@
+# Frontend Quality Guidelines
+
+Document the quality bar for frontend changes in this project.
+
+## What to Capture
+
+- Required lint and typecheck commands
+- Test expectations
+- Accessibility expectations
+- Responsive behavior expectations
+- Code review standards
+
+## Real Examples
+
+- Add 2-3 examples that show the expected quality level
+
+## Anti-Patterns
+
+- List patterns the project avoids
diff --git a/.trellis/spec/frontend/state-management.md b/.trellis/spec/frontend/state-management.md
new file mode 100644
index 000000000..513d73bf2
--- /dev/null
+++ b/.trellis/spec/frontend/state-management.md
@@ -0,0 +1,19 @@
+# Frontend State Management
+
+Document how state is managed in this project.
+
+## What to Capture
+
+- When to use local component state
+- When to lift state up
+- How server data is loaded and cached
+- How URL state, form state, and derived state are handled
+- Which state libraries or framework primitives are preferred
+
+## Real Examples
+
+- Add 2-3 state management examples from the codebase
+
+## Anti-Patterns
+
+- List patterns the project avoids
diff --git a/.trellis/spec/frontend/type-safety.md b/.trellis/spec/frontend/type-safety.md
new file mode 100644
index 000000000..3f087e4b8
--- /dev/null
+++ b/.trellis/spec/frontend/type-safety.md
@@ -0,0 +1,19 @@
+# Frontend Type Safety
+
+Document the TypeScript and data-shape conventions used by the frontend.
+
+## What to Capture
+
+- Where shared types live
+- Prop and state typing patterns
+- API response typing patterns
+- Runtime validation expectations
+- When to use unions, enums, and utility types
+
+## Real Examples
+
+- Add 2-3 type usage examples from the codebase
+
+## Anti-Patterns
+
+- List patterns the project avoids
diff --git a/.trellis/spec/guides/code-reuse-thinking-guide.md b/.trellis/spec/guides/code-reuse-thinking-guide.md
new file mode 100644
index 000000000..f9d5f99bb
--- /dev/null
+++ b/.trellis/spec/guides/code-reuse-thinking-guide.md
@@ -0,0 +1,105 @@
+# Code Reuse Thinking Guide
+
+> **Purpose**: Stop and think before creating new code - does it already exist?
+
+---
+
+## The Problem
+
+**Duplicated code is the #1 source of inconsistency bugs.**
+
+When you copy-paste or rewrite existing logic:
+- Bug fixes don't propagate
+- Behavior diverges over time
+- Codebase becomes harder to understand
+
+---
+
+## Before Writing New Code
+
+### Step 1: Search First
+
+```bash
+# Search for similar function names
+grep -r "functionName" .
+
+# Search for similar logic
+grep -r "keyword" .
+```
+
+### Step 2: Ask These Questions
+
+| Question | If Yes... |
+|----------|-----------|
+| Does a similar function exist? | Use or extend it |
+| Is this pattern used elsewhere? | Follow the existing pattern |
+| Could this be a shared utility? | Create it in the right place |
+| Am I copying code from another file? | **STOP** - extract to shared |
+
+---
+
+## Common Duplication Patterns
+
+### Pattern 1: Copy-Paste Functions
+
+**Bad**: Copying a validation function to another file
+
+**Good**: Extract to shared utilities, import where needed
+
+### Pattern 2: Similar Components
+
+**Bad**: Creating a new component that's 80% similar to existing
+
+**Good**: Extend existing component with props/variants
+
+### Pattern 3: Repeated Constants
+
+**Bad**: Defining the same constant in multiple files
+
+**Good**: Single source of truth, import everywhere
+
+---
+
+## When to Abstract
+
+**Abstract when**:
+- Same code appears 3+ times
+- Logic is complex enough to have bugs
+- Multiple people might need this
+
+**Don't abstract when**:
+- Only used once
+- Trivial one-liner
+- Abstraction would be more complex than duplication
+
+---
+
+## After Batch Modifications
+
+When you've made similar changes to multiple files:
+
+1. **Review**: Did you catch all instances?
+2. **Search**: Run grep to find any missed
+3. **Consider**: Should this be abstracted?
+
+---
+
+## Gotcha: Asymmetric Mechanisms Producing Same Output
+
+**Problem**: When two different mechanisms must produce the same file set (e.g., recursive directory copy for init vs. manual `files.set()` for update), structural changes (renaming, moving, adding subdirectories) only propagate through the automatic mechanism. The manual one silently drifts.
+
+**Symptom**: Init works perfectly, but update creates files at wrong paths or misses files entirely.
+
+**Prevention checklist**:
+- [ ] When migrating directory structures, search for ALL code paths that reference the old structure
+- [ ] If one path is auto-derived (glob/copy) and another is manually listed, the manual one needs updating
+- [ ] Add a regression test that compares outputs from both mechanisms
+
+---
+
+## Checklist Before Commit
+
+- [ ] Searched for existing similar code
+- [ ] No copy-pasted logic that should be shared
+- [ ] Constants defined in one place
+- [ ] Similar patterns follow same structure
diff --git a/.trellis/spec/guides/cross-layer-thinking-guide.md b/.trellis/spec/guides/cross-layer-thinking-guide.md
new file mode 100644
index 000000000..2d1dee398
--- /dev/null
+++ b/.trellis/spec/guides/cross-layer-thinking-guide.md
@@ -0,0 +1,94 @@
+# Cross-Layer Thinking Guide
+
+> **Purpose**: Think through data flow across layers before implementing.
+
+---
+
+## The Problem
+
+**Most bugs happen at layer boundaries**, not within layers.
+
+Common cross-layer bugs:
+- API returns format A, frontend expects format B
+- Database stores X, service transforms to Y, but loses data
+- Multiple layers implement the same logic differently
+
+---
+
+## Before Implementing Cross-Layer Features
+
+### Step 1: Map the Data Flow
+
+Draw out how data moves:
+
+```
+Source → Transform → Store → Retrieve → Transform → Display
+```
+
+For each arrow, ask:
+- What format is the data in?
+- What could go wrong?
+- Who is responsible for validation?
+
+### Step 2: Identify Boundaries
+
+| Boundary | Common Issues |
+|----------|---------------|
+| API ↔ Service | Type mismatches, missing fields |
+| Service ↔ Database | Format conversions, null handling |
+| Backend ↔ Frontend | Serialization, date formats |
+| Component ↔ Component | Props shape changes |
+
+### Step 3: Define Contracts
+
+For each boundary:
+- What is the exact input format?
+- What is the exact output format?
+- What errors can occur?
+
+---
+
+## Common Cross-Layer Mistakes
+
+### Mistake 1: Implicit Format Assumptions
+
+**Bad**: Assuming date format without checking
+
+**Good**: Explicit format conversion at boundaries
+
+### Mistake 2: Scattered Validation
+
+**Bad**: Validating the same thing in multiple layers
+
+**Good**: Validate once at the entry point
+
+### Mistake 3: Leaky Abstractions
+
+**Bad**: Component knows about database schema
+
+**Good**: Each layer only knows its neighbors
+
+---
+
+## Checklist for Cross-Layer Features
+
+Before implementation:
+- [ ] Mapped the complete data flow
+- [ ] Identified all layer boundaries
+- [ ] Defined format at each boundary
+- [ ] Decided where validation happens
+
+After implementation:
+- [ ] Tested with edge cases (null, empty, invalid)
+- [ ] Verified error handling at each boundary
+- [ ] Checked data survives round-trip
+
+---
+
+## When to Create Flow Documentation
+
+Create detailed flow docs when:
+- Feature spans 3+ layers
+- Multiple teams are involved
+- Data format is complex
+- Feature has caused bugs before
diff --git a/.trellis/spec/guides/index.md b/.trellis/spec/guides/index.md
new file mode 100644
index 000000000..147c79bd2
--- /dev/null
+++ b/.trellis/spec/guides/index.md
@@ -0,0 +1,79 @@
+# Thinking Guides
+
+> **Purpose**: Expand your thinking to catch things you might not have considered.
+
+---
+
+## Why Thinking Guides?
+
+**Most bugs and tech debt come from "didn't think of that"**, not from lack of skill:
+
+- Didn't think about what happens at layer boundaries → cross-layer bugs
+- Didn't think about code patterns repeating → duplicated code everywhere
+- Didn't think about edge cases → runtime errors
+- Didn't think about future maintainers → unreadable code
+
+These guides help you **ask the right questions before coding**.
+
+---
+
+## Available Guides
+
+| Guide | Purpose | When to Use |
+|-------|---------|-------------|
+| [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md) | Identify patterns and reduce duplication | When you notice repeated patterns |
+| [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md) | Think through data flow across layers | Features spanning multiple layers |
+
+---
+
+## Quick Reference: Thinking Triggers
+
+### When to Think About Cross-Layer Issues
+
+- [ ] Feature touches 3+ layers (API, Service, Component, Database)
+- [ ] Data format changes between layers
+- [ ] Multiple consumers need the same data
+- [ ] You're not sure where to put some logic
+
+→ Read [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md)
+
+### When to Think About Code Reuse
+
+- [ ] You're writing similar code to something that exists
+- [ ] You see the same pattern repeated 3+ times
+- [ ] You're adding a new field to multiple places
+- [ ] **You're modifying any constant or config**
+- [ ] **You're creating a new utility/helper function** ← Search first!
+
+→ Read [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md)
+
+---
+
+## Pre-Modification Rule (CRITICAL)
+
+> **Before changing ANY value, ALWAYS search first!**
+
+```bash
+# Search for the value you're about to change
+grep -r "value_to_change" .
+```
+
+This single habit prevents most "forgot to update X" bugs.
+
+---
+
+## How to Use This Directory
+
+1. **Before coding**: Skim the relevant thinking guide
+2. **During coding**: If something feels repetitive or complex, check the guides
+3. **After bugs**: Add new insights to the relevant guide (learn from mistakes)
+
+---
+
+## Contributing
+
+Found a new "didn't think of that" moment? Add it to the relevant guide.
+
+---
+
+**Core Principle**: 30 minutes of thinking saves 3 hours of debugging.
diff --git a/.trellis/tasks/00-bootstrap-guidelines/prd.md b/.trellis/tasks/00-bootstrap-guidelines/prd.md
new file mode 100644
index 000000000..882f854b4
--- /dev/null
+++ b/.trellis/tasks/00-bootstrap-guidelines/prd.md
@@ -0,0 +1,101 @@
+# Bootstrap: Fill Project Development Guidelines
+
+## Purpose
+
+Welcome to Trellis! This is your first task.
+
+AI agents use `.trellis/spec/` to understand YOUR project's coding conventions.
+**Empty templates = AI writes generic code that doesn't match your project style.**
+
+Filling these guidelines is a one-time setup that pays off for every future AI session.
+
+---
+
+## Your Task
+
+Fill in the guideline files based on your **existing codebase**.
+
+
+### Backend Guidelines
+
+| File | What to Document |
+|------|------------------|
+| `.trellis/spec/backend/directory-structure.md` | Where different file types go (routes, services, utils) |
+| `.trellis/spec/backend/database-guidelines.md` | ORM, migrations, query patterns, naming conventions |
+| `.trellis/spec/backend/error-handling.md` | How errors are caught, logged, and returned |
+| `.trellis/spec/backend/logging-guidelines.md` | Log levels, format, what to log |
+| `.trellis/spec/backend/quality-guidelines.md` | Code review standards, testing requirements |
+
+
+### Thinking Guides (Optional)
+
+The `.trellis/spec/guides/` directory contains thinking guides that are already
+filled with general best practices. You can customize them for your project if needed.
+
+---
+
+## How to Fill Guidelines
+
+### Step 0: Import from Existing Specs (Recommended)
+
+Many projects already have coding conventions documented. **Check these first** before writing from scratch:
+
+| File / Directory | Tool |
+|------|------|
+| `CLAUDE.md` / `CLAUDE.local.md` | Claude Code |
+| `AGENTS.md` | Claude Code |
+| `.cursorrules` | Cursor |
+| `.cursor/rules/*.mdc` | Cursor (rules directory) |
+| `.windsurfrules` | Windsurf |
+| `.clinerules` | Cline |
+| `.roomodes` | Roo Code |
+| `.github/copilot-instructions.md` | GitHub Copilot |
+| `.vscode/settings.json` → `github.copilot.chat.codeGeneration.instructions` | VS Code Copilot |
+| `CONVENTIONS.md` / `.aider.conf.yml` | aider |
+| `CONTRIBUTING.md` | General project conventions |
+| `.editorconfig` | Editor formatting rules |
+
+If any of these exist, read them first and extract the relevant coding conventions into the corresponding `.trellis/spec/` files. This saves significant effort compared to writing everything from scratch.
+
+### Step 1: Analyze the Codebase
+
+Ask AI to help discover patterns from actual code:
+
+- "Read all existing config files (CLAUDE.md, .cursorrules, etc.) and extract coding conventions into .trellis/spec/"
+- "Analyze my codebase and document the patterns you see"
+- "Find error handling / component / API patterns and document them"
+
+### Step 2: Document Reality, Not Ideals
+
+Write what your codebase **actually does**, not what you wish it did.
+AI needs to match existing patterns, not introduce new ones.
+
+- **Look at existing code** - Find 2-3 examples of each pattern
+- **Include file paths** - Reference real files as examples
+- **List anti-patterns** - What does your team avoid?
+
+---
+
+## Completion Checklist
+
+- [ ] Guidelines filled for your project type
+- [ ] At least 2-3 real code examples in each guideline
+- [ ] Anti-patterns documented
+
+When done:
+
+```bash
+python3 ./.trellis/scripts/task.py finish
+python3 ./.trellis/scripts/task.py archive 00-bootstrap-guidelines
+```
+
+---
+
+## Why This Matters
+
+After completing this task:
+
+1. AI will write code that matches your project style
+2. Relevant `/trellis:before-*-dev` commands will inject real context
+3. `/trellis:check-*` commands will validate against your actual standards
+4. Future developers (human or AI) will onboard faster
diff --git a/.trellis/tasks/00-bootstrap-guidelines/task.json b/.trellis/tasks/00-bootstrap-guidelines/task.json
new file mode 100644
index 000000000..8749fd729
--- /dev/null
+++ b/.trellis/tasks/00-bootstrap-guidelines/task.json
@@ -0,0 +1,30 @@
+{
+  "id": "00-bootstrap-guidelines",
+  "name": "Bootstrap Guidelines",
+  "description": "Fill in project development guidelines for AI agents",
+  "status": "in_progress",
+  "dev_type": "docs",
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-13",
+  "completedAt": null,
+  "commit": null,
+  "subtasks": [
+    {
+      "name": "Fill backend guidelines",
+      "status": "pending"
+    },
+    {
+      "name": "Add code examples",
+      "status": "pending"
+    }
+  ],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [
+    ".trellis/spec/backend/"
+  ],
+  "notes": "First-time setup task created by trellis init (backend project)",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/04-14-assess-cc-highlight-infrastructure-readiness/prd.md b/.trellis/tasks/04-14-assess-cc-highlight-infrastructure-readiness/prd.md
new file mode 100644
index 000000000..b295c57c3
--- /dev/null
+++ b/.trellis/tasks/04-14-assess-cc-highlight-infrastructure-readiness/prd.md
@@ -0,0 +1,116 @@
+# brainstorm: assess infrastructure readiness for cc highlights
+
+## Goal
+
+Determine whether the current `coding-deepgent` infrastructure is ready to support the planned cc-haha core highlight upgrades. If the foundation is not ready, define the infrastructure-first stage that should happen before advanced highlight work.
+
+## What I already know
+
+* The product goal is to implement cc-haha Agent Harness essence in a LangChain-native, professional-grade product track.
+* The user wants source reading and target design to happen now, before implementation work.
+* The core highlight roadmap exists at `.omx/plans/coding-deepgent-cc-core-highlights-roadmap.md`.
+* The source-backed H01-H10 target design exists at `.omx/plans/coding-deepgent-h01-h10-target-design.md`.
+* H01/H02/H03 are directionally strong locally:
+  - tool-first runtime has `ToolCapability`, `CapabilityRegistry`, `ToolPolicy`, and `ToolGuardMiddleware`
+  - permission runtime has deterministic modes/rules/hard safety through `PermissionManager`
+  - prompt contract has `PromptContext` and tests guarding prompt wording drift
+* H08 TodoWrite is strong locally:
+  - public tool name `TodoWrite`
+  - strict `todos` schema
+  - required `content/status/activeForm`
+  - `Command(update=...)`
+  - stale reminders and parallel-call rejection
+* H04/H05 are weaker infrastructure:
+  - no general typed dynamic context payload protocol
+  - no context lifecycle taxonomy
+  - no message/context projection layer
+  - only basic tool-result budget truncation exists
+  - no compact boundary / microcompact / autocompact / reactive compact
+  - no invariant tests around tool-use/tool-result pairing through projection/compaction
+* H06/H07 have useful foundations but need integration hardening:
+  - session JSONL, state snapshots, evidence, and loaded session models exist
+  - memory store/save/recall and memory context middleware exist
+  - memory quality policy, bounded recall tests, and session/recovery integration still need strengthening
+* H09/H10/H11+ should not be the immediate next focus until context/recovery/subagent foundations are clearer.
+
+## Assumptions (temporary)
+
+* Infrastructure readiness should be judged against the first ten highlights, not all 22 at once.
+* A foundation stage is preferable to starting advanced multi-agent/team/plugin marketplace work too early.
+* The next implementation stage should stay small enough to verify with deterministic tests and not require live model calls.
+
+## Open Questions
+
+* None for the current readiness decision.
+
+## Requirements (evolving)
+
+* Decide if current infrastructure is sufficient for later highlight upgrades.
+* If not sufficient, define the infrastructure-first stage.
+* Keep the decision source-backed against cc-haha and current `coding-deepgent` code.
+* Keep LangChain-native boundaries: do not replace `create_agent` / LangGraph runtime with a custom query loop.
+* Preserve benefit-gated complexity: no work proceeds only because it is "closer to cc".
+
+## Acceptance Criteria (evolving)
+
+* [x] H01-H10 are audited against current local implementation.
+* [x] A source-backed target design exists for H01-H10.
+* [x] Infrastructure gaps are identified.
+* [x] A recommended next stage is named.
+* [ ] User confirms or adjusts the recommended next stage before implementation planning.
+
+## Definition of Done (team quality bar)
+
+* No implementation code is changed in this brainstorm task.
+* Planning docs are updated with evidence and a concrete next-stage recommendation.
+* Future implementation work still requires task workflow, spec context, tests, and quality checks.
+
+## Out of Scope (explicit)
+
+* Implementing Stage 12 code now
+* Starting advanced coordinator/team/mailbox work
+* Implementing auto classifier or rich permission UI
+* Implementing full LLM autocompact now
+* Plugin marketplace/install/update parity
+
+## Technical Notes
+
+* Created task: `.trellis/tasks/04-14-assess-cc-highlight-infrastructure-readiness`
+* Planning docs:
+  - `.omx/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+  - `.omx/plans/coding-deepgent-h01-h10-target-design.md`
+* Current recommendation from source-backed target design:
+  - next stage should be `Stage 12: Context and Recovery Hardening`
+  - implement it iteratively as 12A-12D rather than as one large infrastructure push
+* Candidate Stage 12 scope:
+  - typed dynamic context payload protocol
+  - deterministic message/context projection helpers with tool-result invariants
+  - session resume path / recovery brief audit
+  - memory quality rules and bounded recall tests
+  - docs/status update
+* Stage 12 sub-stage plan:
+  - `12A Context Payload Foundation`: typed/bounded context payload protocol and tests
+  - `12B Message Projection / Tool Result Invariants`: deterministic projection before LLM compaction
+  - `12C Recovery Brief / Session Resume Audit`: harden session resume and evidence use
+  - `12D Memory Quality Policy`: prevent low-value/derivable memory pollution
+* Immediate implementation recommendation:
+  - start with `Stage 12A: Context Payload Foundation`
+* Stage 12 out of scope:
+  - full auto-compact LLM summarization
+  - coordinator/team runtime
+  - mailbox/send-message
+  - plugin marketplace
+  - permission classifier / rich approval UI
+
+## Decision (ADR-lite)
+
+**Context**: The highlight roadmap includes many valuable upgrades, but later multi-agent, task, plugin, and automation features depend on context, session, memory, and recovery foundations.
+
+**Decision**: Do not start advanced highlight implementation yet. Treat current infrastructure as partially ready, with a foundation gap around H04/H05/H06/H07. The next recommended stage is `Stage 12: Context and Recovery Hardening`, implemented iteratively as 12A-12D. Start with `Stage 12A: Context Payload Foundation`.
+
+**Consequences**:
+- H01/H02/H03/H08 should be preserved and hardened, not heavily redesigned.
+- H04/H05 become the main infrastructure work because context projection and pressure handling affect most later systems.
+- H06/H07 should be integrated into that foundation because recovery and memory quality influence long-running agent correctness.
+- H09/H10/H11+ should wait until context/recovery boundaries are explicit enough to support them.
+- 12A creates the shared dynamic context boundary that 12B/12C/12D can build on without ad hoc prompt injection.
diff --git a/.trellis/tasks/04-14-assess-cc-highlight-infrastructure-readiness/task.json b/.trellis/tasks/04-14-assess-cc-highlight-infrastructure-readiness/task.json
new file mode 100644
index 000000000..8fb4ea601
--- /dev/null
+++ b/.trellis/tasks/04-14-assess-cc-highlight-infrastructure-readiness/task.json
@@ -0,0 +1,49 @@
+{
+  "id": "assess-cc-highlight-infrastructure-readiness",
+  "name": "assess-cc-highlight-infrastructure-readiness",
+  "title": "brainstorm: assess infrastructure readiness for cc highlights",
+  "description": "",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [
+    "04-14-stage-12a-context-payload-foundation",
+    "04-14-stage-12b-message-projection-and-tool-result-invariants",
+    "04-14-stage-12c-recovery-brief-and-session-resume-audit",
+    "04-14-stage-12d-memory-quality-policy"
+  ],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
diff --git a/.trellis/tasks/04-14-redefine-coding-deepgent-final-goal/prd.md b/.trellis/tasks/04-14-redefine-coding-deepgent-final-goal/prd.md
new file mode 100644
index 000000000..bb89c767f
--- /dev/null
+++ b/.trellis/tasks/04-14-redefine-coding-deepgent-final-goal/prd.md
@@ -0,0 +1,1017 @@
+# brainstorm: redefine coding-deepgent final goal
+
+## Goal
+
+Redefine the long-term final goal of `coding-deepgent` after partial plan loss, so future stages are evaluated against one explicit target: implement the essential cc / `cc-haha` runtime logic through LangChain/LangGraph-native primitives, while keeping the codebase professional-grade, modular, maintainable, and suitable for a large product rather than a demo.
+
+## What I already know
+
+* The user wants the final project goal to be: use LangChain to implement the essence of cc, specifically guided by `cc-haha` alignment.
+* The user explicitly wants LangChain-first implementation choices and long-term adherence to `langchain-architecture-guard`.
+* The user wants a professional large-project codebase, not a demo.
+* The user accepts complex architecture when it improves clarity.
+* The architecture preferences are: modularity, open-closed principle, maintainability, and clear concise code.
+* `coding-deepgent` already describes itself as an independent cumulative LangChain cc product surface.
+* Current product state says it is at `stage-11-mcp-plugin-real-loading`.
+* The restored Stage 3 PRD establishes these architectural principles:
+  - domain-first, LangChain-inside
+  - explicit dependency graph
+  - high cohesion, low coupling
+  - functional skeleton over empty architecture
+  - no cc clone drift
+* Existing product-local alignment docs already say implementation must stay LangChain-first: `create_agent`, `AgentMiddleware`, strict Pydantic tools, `Command(update=...)`, state/context schemas, store/checkpointer before custom runtime.
+* Current codebase already contains explicit domains for runtime, tool_system, filesystem, todo, sessions, permissions, hooks, memory, compact, skills, tasks, subagents, MCP, and plugins.
+
+## Assumptions (temporary)
+
+* The final goal should be stated at the product level, not only as a chapter/tutorial roadmap.
+* The final goal should define both behavior target and architecture target.
+* We should preserve cc-aligned functional essence, but not blindly copy cc-haha product/UI/infrastructure details.
+* We should keep the LangChain runtime boundary intact instead of replacing it with a custom query loop.
+
+## Open Questions
+
+* None for the current goal-definition pass.
+
+## Requirements (evolving)
+
+* Define the final product goal in a way that survives partial document loss.
+* Make `cc-haha` the primary behavior-alignment source, with explicit evidence-based alignment decisions.
+* Make LangChain/LangGraph the primary implementation framework and runtime boundary.
+* Favor official LangChain components and patterns over custom framework-shaped abstractions.
+* Keep the project suitable for professional long-term evolution.
+* Preserve modular architecture with clear domain ownership and extension seams.
+* Keep code understandable and maintainable despite architectural depth.
+* Final product shape chosen: product-parity core, LangChain-native execution.
+* Final-goal scope applies to the `coding-deepgent` product track only.
+* “cc essence” in scope means the core systems identified by the user:
+  - tool system
+  - context system
+  - session system
+  - memory system
+  - subagent / multi-agent system
+  - todo system
+  - task system
+  - skill system
+  - prompt system
+* The original tutorial's 19 points are treated as the foundational implementation baseline rather than the final product boundary.
+* `agents_deepagents` remains a teaching/alignment/verification track, not the final product target itself.
+* Before new implementation work, define and prioritize source-backed cc core highlights instead of asking the user to approve every low-level system detail one by one.
+* The highlight pass should happen in dependency order so later systems do not redefine earlier boundaries.
+* Every future upgrade proposal must include a concrete benefit statement before implementation begins.
+* Every upgrade discussion must explain:
+  - what concrete function is being added or changed
+  - what concrete gain it brings
+  - which category the gain belongs to: user-visible, agent-runtime, safety, reliability, context-efficiency, maintainability, testability, or product parity
+  - why the gain is worth the added complexity now
+* Cross-session memory is a required product property, not a nice-to-have.
+* Planned upgrades must say whether they improve cross-session memory directly, indirectly, or not at all.
+
+## Acceptance Criteria (evolving)
+
+* [ ] The final goal states what must align with cc-haha and what must not be copied.
+* [ ] The final goal states which LangChain/LangGraph primitives are the preferred implementation boundary.
+* [ ] The final goal states the expected project shape: product-grade, modular, maintainable, non-demo.
+* [ ] The final goal defines stage progression logic or target completion criteria.
+* [ ] The final goal clarifies the boundary between product parity, teaching material, and deferred infrastructure.
+* [ ] The final goal names the core systems that must eventually reach cc-haha essence alignment.
+* [ ] Each core system gets a written “essence definition” before implementation planning resumes.
+* [ ] Each planned upgrade includes an explicit expected-benefit section and a why-now judgment.
+* [ ] Each planned upgrade includes an explicit function summary before implementation begins.
+* [ ] The final goal explicitly treats cross-session memory as a required end-state capability.
+* [ ] A source-backed cc core highlights roadmap exists and is used as the planning backlog.
+
+## Definition of Done (team quality bar)
+
+* Tests added/updated where implementation behavior changes
+* Lint / typecheck / CI green
+* Docs/notes updated if behavior changes
+* Rollout/rollback considered if risky
+
+## Out of Scope (explicit)
+
+* Implementing new product code in this brainstorm task
+* Reconstructing every lost historical plan verbatim
+* Blind line-by-line cloning of `cc-haha`
+* Prematurely committing to UI/platform/remote/runtime infrastructure details without a concrete local effect
+
+## Technical Notes
+
+* New brainstorm task: `.trellis/tasks/04-14-redefine-coding-deepgent-final-goal`
+* Key product docs:
+  - `coding-deepgent/README.md`
+  - `coding-deepgent/PROJECT_PROGRESS.md`
+  - `coding-deepgent/project_status.json`
+  - `coding-deepgent/docs/cc-alignment-roadmap.md`
+* Recovered planning docs:
+  - `.omx/plans/prd-coding-deepgent-runtime-foundation.md`
+  - `.omx/plans/test-spec-coding-deepgent-runtime-foundation.md`
+  - `.omx/plans/master-plan-coding-deepgent-reconstructed.md`
+  - `.omx/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+  - `.omx/plans/coding-deepgent-h01-h10-target-design.md`
+* Existing prompt surface already encodes product intent:
+  - `coding_deepgent.prompting.builder.build_default_system_prompt()`
+  - “independent cumulative LangChain cc product agent”
+  - “Prefer LangChain-native tools and state updates over prose when an action is needed.”
+* 2026-04-14 correction: the first essence pass was too narrow because it started from individual feature bands before reading all architecture docs. Restart essence definition from a full documentation pass.
+* Completed documentation read pass:
+  - `/tmp/claude-code-book/README.md`
+  - `/tmp/claude-code-book/00-前言.md`
+  - `/tmp/claude-code-book/第一部分-基础篇/01-智能体编程的新范式.md`
+  - `/tmp/claude-code-book/第一部分-基础篇/02-对话循环-Agent的心跳.md`
+  - `/tmp/claude-code-book/第一部分-基础篇/03-工具系统-Agent的双手.md`
+  - `/tmp/claude-code-book/第一部分-基础篇/04-权限管线-Agent的护栏.md`
+  - `/tmp/claude-code-book/第二部分-核心系统篇/05-设置与配置-Agent的基因.md`
+  - `/tmp/claude-code-book/第二部分-核心系统篇/06-记忆系统-Agent的长期记忆.md`
+  - `/tmp/claude-code-book/第二部分-核心系统篇/07-上下文管理-Agent的工作记忆.md`
+  - `/tmp/claude-code-book/第二部分-核心系统篇/08-钩子系统-Agent的生命周期扩展点.md`
+  - `/tmp/claude-code-book/第三部分-高级模式篇/09-子智能体与Fork模式.md`
+  - `/tmp/claude-code-book/第三部分-高级模式篇/10-协调器模式-多智能体编排.md`
+  - `/tmp/claude-code-book/第三部分-高级模式篇/11-技能系统与插件架构.md`
+  - `/tmp/claude-code-book/第三部分-高级模式篇/12-MCP集成与外部协议.md`
+  - `/tmp/claude-code-book/第四部分-工程实践篇/13-流式架构与性能优化.md`
+  - `/tmp/claude-code-book/第四部分-工程实践篇/14-Plan模式与结构化工作流.md`
+  - `/tmp/claude-code-book/第四部分-工程实践篇/15-构建你自己的Agent-Harness.md`
+  - `/tmp/claude-code-book/附录/A-源码导航地图.md`
+  - `/tmp/claude-code-book/附录/B-工具完整清单.md`
+  - `/tmp/claude-code-book/附录/C-功能标志速查表.md`
+  - `/tmp/claude-code-book/附录/D-术语表.md`
+  - `/root/claude-code-haha/docs/must-read/*.md`
+  - `/root/claude-code-haha/docs/modules/*-deep-dive.md`
+
+## Research Notes
+
+### Constraints from our repo/project
+
+* We already have a stage-based cumulative product model.
+* The repo contains both a teaching track (`agents_deepagents/`) and a product track (`coding-deepgent/`).
+* The product track already has cc alignment notes for later stages.
+* The architecture baseline already favors domain modules plus dependency injection and explicit runtime seams.
+
+### Expected effect
+
+Aligning the final project goal now should improve: maintainability, product clarity, and testability. The local effect is: future stages stop drifting between “tutorial clone”, “demo”, and “product”, and every new feature can be judged against one explicit rule set: cc-haha functional essence, LangChain-native implementation, and professional product architecture.
+
+### Compact alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Model-visible contracts | cc-haha tool names, schema fields, and required state semantics are stable and matter for agent behavior | fewer schema drifts and easier parity reasoning | strict Pydantic tools + `Command(update=...)` + typed state | align | Keep model-visible contracts cc-aware |
+| Runtime boundary | cc-haha has its own runtime/product internals | avoid cloning the wrong abstraction layer | LangChain `create_agent`, middleware, state/context/store/checkpointer seams | partial | Match essence, not runtime internals |
+| Product infrastructure breadth | cc-haha includes UI/platform/runtime breadth beyond current local need | avoid speculative complexity | local product-grade architecture only when effect is concrete | defer | No platform parity by default |
+| Architecture style | cc-haha source implies large-product concerns, not toy examples | keep long-term extensibility and maintainability | explicit domain modules + DI + clear boundaries | align | Favor professional modular architecture |
+| Core system coverage | secondary analysis from `claude-code-book` highlights tool/context/session/memory/subagent-agent/todo/task/skill/prompt systems as the meaningful conceptual core; source confirmation remains required per band | keep final-goal scope concrete instead of vague “be like cc” | final-goal scope statement + stage map | align | Treat these systems as required end-state coverage |
+| 19 tutorial points | current repo teaching material uses 19 points as a staged implementation baseline | preserve learning/build order without confusing it for the full product target | foundational implementation track | align | Treat the 19 points as baseline, not final parity endpoint |
+
+### Feasible approaches here
+
+**Approach A: Product-parity core, LangChain-native execution** (Recommended)
+
+* How it works:
+  Define the final goal as: reproduce the essential cc-haha product logic and model-visible behavior where it has concrete local value, but always express it through official LangChain/LangGraph primitives and a professional modular architecture.
+* Pros:
+  - Matches the user's stated goal closely
+  - Keeps parity efforts disciplined
+  - Avoids custom-runtime drift
+  - Fits the current codebase direction
+* Cons:
+  - Requires repeated scope discipline to avoid copying non-essential cc details
+
+**Approach B: LangChain-first agent platform inspired by cc**
+
+* How it works:
+  Treat cc-haha mostly as inspiration rather than as an alignment target. Optimize for LangChain best practices first, and adopt cc behavior only when obviously useful.
+* Pros:
+  - Simpler planning burden
+  - Less source-mapping overhead
+* Cons:
+  - Too weak for the user's parity intent
+  - Higher risk of slowly drifting away from cc essence
+
+**Approach C: Dual-target project**
+
+* How it works:
+  Define two equal top-level goals: teaching track parity and product track parity, each with separate completion standards.
+* Pros:
+  - Makes tutorial/product split explicit
+  - Could help docs organization
+* Cons:
+  - Splits focus
+  - Risks weakening the product-track final goal
+
+## Decision (ADR-lite)
+
+**Context**: The project needs one stable long-term target after partial plan loss, and the user wants cc-haha-aligned functional essence without abandoning LangChain-native structure.
+
+**Decision**: Choose Approach A: product-parity core, LangChain-native execution.
+
+**Consequences**:
+- `cc-haha` remains the primary behavior-alignment reference.
+- LangChain/LangGraph remains the implementation and runtime boundary.
+- Product parity is judged at the level of functional essence, model-visible contracts, and important runtime semantics, not UI/platform cloning.
+- Future planning must keep asking whether a cc behavior has a concrete local effect before aligning it.
+- The required long-term feature bands are the core systems explicitly named by the user, with the tutorial's 19 points acting as foundation rather than completion.
+- The final-goal constraint applies to `coding-deepgent`; `agents_deepagents` remains a supporting teaching/alignment track.
+
+## Technical Approach
+
+Define a product-level master goal for `coding-deepgent` with these rules:
+
+* Target the functional essence of `cc-haha`, not superficial similarity or file-by-file cloning.
+* Require evidence-backed alignment per feature band against local `cc-haha` source, using `claude-code-book` only as secondary orientation.
+* Express behavior through official LangChain/LangGraph primitives wherever they fit:
+  - `create_agent`
+  - state/context schema
+  - middleware
+  - strict Pydantic tool schemas
+  - `Command(update=...)`
+  - store/checkpointer
+  - graph seams where needed
+* Keep a professional modular architecture with stable domain boundaries, explicit dependency composition, and open-closed extensibility.
+* Treat the tutorial's 19 points as the implementation foundation and learning baseline, while the product end-state is the larger cc core-system parity target inside `coding-deepgent`.
+* Treat benefit evaluation as a first-class planning gate: no upgrade should proceed on “closer to cc” alone without a concrete local payoff.
+
+## Essence Workshop Order
+
+Superseded by the highlight backlog in `.omx/plans/coding-deepgent-cc-core-highlights-roadmap.md`.
+
+Original dependency-first order:
+
+1. tool system
+2. prompt system
+3. context system
+4. todo system
+5. session system
+6. memory system
+7. task system
+8. skill system
+9. subagent / multi-agent system
+
+Rationale:
+
+* Tools are the model's executable surface.
+* Prompt and context define how the model understands and chooses those tools.
+* Todo, session, and memory define the main state layers around the loop.
+* Task, skill, and subagent/multi-agent build on those boundaries rather than precede them.
+
+## Essence Definitions (draft)
+
+### Global correction after full documentation read
+
+The earlier per-system definitions must be treated as provisional notes, not final decisions.
+
+The global cc essence should be framed first as an Agent Harness architecture:
+
+* tool-first execution loop
+* permission-aware runtime
+* cache-aware prompt/context engineering
+* recoverable session and agent lifecycle
+* explicit task/workflow discipline
+* scoped memory and context compaction
+* multi-agent runtime objects rather than prompt-only subcalls
+* extension platform where MCP/plugin/skill/hook capabilities still flow through the same execution and permission runtime
+* observability, failure recovery, and benefit/complexity evaluation as product-grade requirements
+
+Future per-system essence definitions must be derived from this global model and then checked against `cc-haha` source for the concrete feature band.
+
+### Global cc essence charter (draft)
+
+#### Product target
+
+`coding-deepgent` should become a LangChain-native implementation of the core Claude Code / cc-haha Agent Harness ideas, not a UI clone, tutorial replica, or flat demo agent.
+
+#### Core thesis
+
+The LLM is the reasoning engine; the harness is the product runtime that makes that reasoning safe, stateful, observable, extensible, recoverable, and useful for real coding work.
+
+#### Required global properties
+
+1. Tool-first execution
+   All model-facing executable capabilities should enter through a strict tool contract and a unified execution path. Important capabilities should not bypass tool validation, permission, telemetry, result protocol, and state update semantics.
+2. Unified execution loop
+   User input, model sampling, tool calls, tool results, continuation, compaction, hooks, and stopping conditions should form one explicit runtime loop. It should not be a loose chain of one-off API calls.
+3. Permission-aware by construction
+   Execution must be safe by default. Permissions are not scattered inside random tools; they form a runtime layer with modes, rules, guards, and conservative failure behavior.
+4. Cache-aware prompt/context engineering
+   Prompt and context are engineering surfaces. Stable prefixes, dynamic deltas, scoped attachments, and cache-sensitive fork/subagent behavior are part of the product, not micro-optimizations.
+5. Long-session context management
+   Context management includes selection, injection, projection, tool-result budgeting, micro/auto/reactive compaction, boundary markers, and continuation safety. It is required for runtime correctness, not just token cost reduction.
+6. Scoped memory
+   Memory should capture reusable non-derivable knowledge, not duplicate facts obtainable from code or git. Memory write paths must be controlled, scoped, and safe from pollution.
+7. Recoverable session and agent lifecycle
+   Sessions, transcripts, evidence/state snapshots, agent tasks, and resume paths should make long work recoverable. Recovery should rebuild enough runtime context to continue, not merely reopen text history.
+8. Agent as runtime object
+   Subagents and multi-agent workers should be modeled as runtime objects/tools with lifecycle, transcript, task status, permissions, context policy, and result protocol. They are not just prompt wrappers.
+9. Explicit task/workflow discipline
+   Todo, Task, Plan/Execute/Verify, and Coordinator-style workflows exist to prevent long work from drifting. Research and implementation can be delegated, but synthesis/coordination must remain an owned responsibility.
+10. Extension platform, not shortcuts
+   MCP, plugin, skill, and hook capabilities must enter through typed extension seams and still obey execution, permission, context, and observability boundaries. Extensions are not backdoors.
+11. Production-grade observability and recovery
+   The system must expose enough structured state, logs, evidence, and tests to debug runtime behavior. Failures should become protocol-safe results or recoverable transitions whenever possible.
+12. Benefit-gated complexity
+   Each upgrade must state the concrete local benefit and why the added complexity is worth it now. “Closer to cc” is not sufficient.
+
+#### Non-goals
+
+* Do not clone cc-haha file layout line-by-line.
+* Do not copy UI/TUI implementation details unless they create a concrete local product effect.
+* Do not replace LangChain/LangGraph runtime primitives with a custom query runtime unless there is no LangChain-native path.
+* Do not collapse TodoWrite and durable Task into one concept.
+* Do not let plugins, skills, hooks, MCP, or subagents bypass tool and permission boundaries.
+* Do not store easily re-derivable codebase facts as long-term memory.
+
+#### LangChain-native expression rule
+
+When translating cc essence into `coding-deepgent`, prefer official LangChain/LangGraph primitives:
+
+* `create_agent` / LangGraph runtime invocation
+* state schema and context schema
+* strict Pydantic `@tool(..., args_schema=...)`
+* `Command(update=...)` for model-visible state updates
+* middleware for guard/hook/context/memory behavior
+* store/checkpointer for persistent or cross-thread state
+* explicit graph seams only when the behavior is naturally graph-shaped
+
+Avoid custom wrappers, fallback parsers, alias normalizers, or private mini-runtimes when an official primitive handles the boundary.
+
+#### Per-system discussion template
+
+Use this template for each core system before implementation planning:
+
+* System role in the harness:
+* Concrete benefit:
+* cc / cc-haha essence:
+* LangChain-native expression:
+* Product-grade architecture shape:
+* Must-align:
+* Partial / LangChain equivalent:
+* Defer:
+* Do-not-copy:
+* Complexity / why-now judgment:
+
+### 1. Tool System
+
+Status: current working definition, revised after full `claude-code-book` and `cc-haha/docs` reading.
+
+#### Expected effect
+
+Aligning the tool system should improve: agent-runtime reliability, safety, maintainability, testability, observability, and product parity.
+
+The local runtime effect is: every model-facing executable capability enters through one strict LangChain tool contract and one guardable execution path, so validation, permission checks, progress/events, state updates, result mapping, and failure handling remain consistent across builtin tools, skills, MCP tools, durable tasks, and agent tools.
+
+Why this is worth complexity:
+
+* A strict tool system prevents special-case execution paths from bypassing safety and observability.
+* It makes new capabilities easier to add because they attach to a known contract instead of requiring a new runtime branch.
+* It protects LangChain-native simplicity: tool behavior lives in schemas, tool functions, middleware, and state updates rather than in prompt prose or private mini-runtimes.
+
+#### Primary reference points
+
+* `cc-haha` primary source:
+  - `/root/claude-code-haha/src/Tool.ts`
+    Evidence: `Tool` includes `call`, `description`, `inputSchema`, `isConcurrencySafe`, `isReadOnly`, `isDestructive`, `interruptBehavior`, `shouldDefer`, `alwaysLoad`, `mcpInfo`, `maxResultSizeChars`, `strict`, `validateInput`, `checkPermissions`, `toAutoClassifierInput`, `mapToolResultToToolResultBlockParam`, and result rendering hooks.
+  - `/root/claude-code-haha/src/Tool.ts:743-792`
+    Evidence: `buildTool` fills safe defaults, including fail-closed defaults for concurrency and read-only behavior.
+  - `/root/claude-code-haha/docs/must-read/01-execution-engine.md:122-189`
+    Evidence: tool execution flows through orchestration, streaming execution, validation, permission checks, hooks, tool call, telemetry, and result blocks; the tool pool is dynamic.
+  - `/root/claude-code-haha/docs/modules/01-execution-engine-deep-dive.md:220-300`
+    Evidence: deep-dive frames tool execution as a layered runtime pipeline and emphasizes streaming semantics.
+  - related tool implementations under `/root/claude-code-haha/src/tools/*`
+* Secondary analysis:
+  - `/tmp/claude-code-book/第一部分-基础篇/03-工具系统-Agent的双手.md`
+  - `/tmp/claude-code-book/附录/B-工具完整清单.md`
+* LangChain primary docs:
+  - `/oss/python/langchain/tools`: tools are callable functions with well-defined inputs/outputs; Pydantic `args_schema` supports complex inputs; `ToolRuntime` gives hidden runtime access; `Command(update=...)` updates state.
+  - `/oss/python/langchain/agents`: `create_agent` is a LangGraph-backed agent runtime; tools can be statically registered, dynamically filtered, or dynamically registered/executed through middleware.
+  - `/oss/python/langchain/middleware/custom`: middleware supports `wrap_tool_call` around each tool call and can return `Command` for state updates.
+
+#### System role in the harness
+
+The tool system is the harness boundary where model intent becomes executable action. It owns the model-visible action contract and routes every important capability into runtime validation, permission, execution, result/state update, and telemetry.
+
+It is not merely:
+
+* a Python function registry
+* a bag of helper methods
+* a prompt manual telling the model what actions exist
+* a direct shortcut into filesystem/session/task/subagent internals
+
+#### cc / cc-haha essence
+
+* Tools are first-class runtime capabilities, not ad hoc callbacks.
+* A tool has both a model-visible surface and runtime-only behavior.
+* The model-visible surface must be stable:
+  - name
+  - description
+  - strict input schema
+  - required fields and field semantics
+* The runtime-only behavior must be explicit:
+  - input validation
+  - permission and guard decision
+  - read-only / destructive / concurrency-safe classification
+  - interruption behavior
+  - result size / persistence policy
+  - progress/event emission
+  - tool result mapping back to the model protocol
+  - telemetry / classifier summary where relevant
+* The execution path is layered:
+  - tool orchestration decides scheduling
+  - streaming executor preserves stream/progress/cancel semantics
+  - single-tool execution performs validation, permission, hooks, call, result mapping, and telemetry
+* The tool pool is dynamic runtime state:
+  - mode changes may alter visible tools
+  - deferred tools may unlock later
+  - MCP/plugin/skill-provided tools may appear through extension surfaces
+  - agent-specific and plan-mode tool pools may be constrained
+* Agents exposed to the model should be tools too. `AgentTool` is the key architectural signal: subagents should inherit tool lifecycle, permission, transcript/evidence, task status, and result protocol rather than bypass the tool runtime.
+* Failures should become protocol-safe tool results where possible. A bad tool call should not silently corrupt the loop or break tool-use/result pairing.
+
+#### Feature boundary
+
+In scope for tool-system essence:
+
+* model-visible tool contracts
+* strict input schemas and validation
+* capability metadata and registry
+* runtime-visible tool pool selection/filtering
+* unified guardable execution path
+* dynamic extension tool registration/execution where needed
+* progress/event emission
+* tool result and state update protocol
+* concurrency/interruption semantics
+* result budget/persistence hooks at tool boundary
+* agent-as-tool principle
+
+Not in scope for tool-system essence:
+
+* prompt wording strategy
+* context selection/compaction policy
+* memory extraction/write policy beyond tool exposure
+* durable task collaboration semantics beyond tool exposure
+* UI/TUI rendering details
+* implementation of every cc-haha tool class one-for-one
+* provider-specific SDK plumbing that LangChain already abstracts
+
+#### LangChain-native expression
+
+The local LangChain/LangGraph shape should be:
+
+* Use strict Pydantic input schemas with `ConfigDict(extra="forbid")`.
+* Use `@tool(..., args_schema=...)` for structured model-visible tool contracts.
+* Put model-visible guidance in the tool description and `Field(description=...)`, not in a giant system-prompt manual.
+* Use `Command(update=...)` when a tool updates LangGraph state.
+* Use hidden runtime access only through official `ToolRuntime` / injected runtime surfaces; do not make runtime-only fields model-visible.
+* Use `AgentMiddleware.wrap_tool_call` for guard, permission, hook dispatch, telemetry, and safe error mapping.
+* Use `wrap_model_call` / request override for dynamic tool filtering when tools are known at startup but exposed conditionally.
+* Use both `wrap_model_call` and `wrap_tool_call` for truly runtime-discovered tools, such as MCP-loaded tools, because the agent must both expose and execute them.
+* Keep a product-local `CapabilityRegistry` for metadata LangChain tools do not natively encode well: source, trust, read-only/destructive/concurrency classifications, extension provenance, and policy codes.
+* Avoid fallback parsers, alias guessing, and `dict[str, Any]` normalization for model input. Schema validation should fail clearly.
+
+#### Product-grade architecture shape
+
+Suggested product-local boundaries:
+
+* `tool_system.capabilities`: capability metadata, source/trust, registry, and tool-pool descriptors
+* `tool_system.policy`: permission and safety decisions over tool calls
+* `tool_system.middleware`: LangChain `AgentMiddleware` bridge for guard/hooks/events
+* domain-owned `tools.py`: actual LangChain tool definitions near their domain, for example `todo/tools.py`, `filesystem/tools.py`, `tasks/tools.py`
+* extension domains (`mcp`, `plugins`, `skills`) adapt external declarations into capabilities, but execution still returns to the same guardable tool path
+
+Do not create a second generic `Tool` framework that competes with LangChain. The registry should complement LangChain with metadata and policy, not replace `@tool` / middleware.
+
+#### Alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Tool contract | `Tool.ts` defines a rich tool interface with name, schema, call, validation, permission, concurrency, interruption, result mapping, classifier input, and rendering hooks | model-facing action surface is stable and runtime behavior is inspectable | strict Pydantic `@tool` plus product capability metadata | align | Match functional contract, not TypeScript interface shape |
+| Safe defaults | `buildTool` fills defaults and assumes non-read-only / non-concurrency-safe unless tools opt in | new tools are safe by default and require explicit safety metadata | `CapabilityRegistry` defaults plus tests | align | Fail closed for policy metadata |
+| Execution pipeline | docs map `tool_use -> orchestration -> streaming executor -> execution -> tool_result` | one guardable path for validation, permission, hooks, execution, telemetry | LangChain `wrap_tool_call` middleware around tool execution | partial | Use LangChain middleware rather than custom executor unless LangChain lacks needed semantics |
+| Tool pool dynamics | docs state deferred tools, plan mode, MCP, and agent changes can alter visible tools | model sees the right tool set for mode/context without prompt overload | pre-register/filter tools via middleware; dynamic MCP via middleware | align | Use official dynamic tool patterns first |
+| Agent as tool | Agent runtime docs model agent launch through `AgentTool` | subagents inherit lifecycle/safety/result boundaries | `run_subagent` / future richer agent tool | align | All model-facing subagent calls remain tools |
+| UI rendering hooks | `Tool.ts` contains rich rendering methods | terminal UX improves, but not essential for LangChain product core now | CLI renderers outside tool contract | defer/do-not-copy | Do not copy UI surface unless a concrete product need appears |
+| Provider-specific schema details | cc-haha uses Zod/Anthropic-specific tool schemas | avoid wrong abstraction layer in Python product | Pydantic + LangChain tool schema | do-not-copy | Preserve behavior, not provider-specific implementation |
+
+#### Must-align
+
+* Model-visible names and schemas for cc-critical tools such as `TodoWrite`.
+* Unified guardable execution path.
+* Tool result/state update protocol.
+* Dynamic tool-pool control by mode, context, and extension state.
+* Agent/subagent model-facing entry as a tool.
+* Safe default metadata and explicit opt-in for risky classifications.
+
+#### Partial / LangChain equivalent
+
+* cc-haha `Tool` interface becomes LangChain tool + capability metadata + middleware, not a new custom base class.
+* cc-haha streaming executor semantics are approximated through LangChain/LangGraph streaming and middleware first; add custom helpers only for demonstrated gaps.
+* cc-haha result rendering belongs in product CLI renderers, not in the model-facing tool contract.
+
+#### Defer
+
+* Full ToolSearch / deferred-tool parity until tool count or MCP growth creates measurable context pressure.
+* Fine-grained parallel scheduling beyond LangGraph's current tool execution semantics until tests show it affects correctness or performance.
+* Rich UI grouped rendering and transcript-search rendering.
+
+#### Do-not-copy
+
+* TypeScript/Zod interface structure as Python architecture.
+* UI/TUI rendering methods inside core tool contracts.
+* Alias compatibility that hides model-visible schema drift.
+* A custom tool executor that bypasses LangChain just to look like cc-haha.
+
+#### Complexity / why-now judgment
+
+Worth doing now:
+
+* strict schemas, capability registry metadata, and `wrap_tool_call` guard path, because they directly improve safety, testability, and maintainability for every current and future tool
+* explicit dynamic tool-pool policy, because current product already has MCP/plugin/skill/task/subagent surfaces
+
+Not worth doing yet:
+
+* full custom streaming executor parity, because LangChain already supplies an agent runtime and middleware hooks; we should first identify exact missing behavior with tests
+* UI-level rendering parity, because product correctness does not depend on it yet
+
+#### Confirmed decisions
+
+* Core principle confirmed by user: all important capabilities should become tools first.
+* Exception boundary: pure runtime-internal plumbing may remain non-tool if it is not a model-facing capability.
+
+### 2. Permission / Safety System
+
+Status: current working definition, derived after full documentation read and source re-check.
+
+#### Expected effect
+
+Aligning the permission / safety system should improve: safety, reliability, maintainability, testability, observability, and product parity.
+
+The local runtime effect is: the product can allow the model to take real actions without turning every tool into a bespoke risk decision. Tool calls are evaluated by one explicit safety runtime with modes, rules, hard guards, trust metadata, hook integration, conservative headless behavior, and auditable decision reasons.
+
+Why this is worth complexity:
+
+* Coding agents are dangerous because they can edit files, run commands, call external tools, and spawn other agents. A single guard function is not enough.
+* Permission decisions must be explainable and testable, otherwise later MCP/plugin/skill/subagent expansion becomes unsafe.
+* The project already has extension tools and task/subagent tools; a stronger safety runtime is a foundation, not a late add-on.
+
+#### Primary reference points
+
+* `cc-haha` primary source:
+  - `/root/claude-code-haha/docs/must-read/05-permission-security.md:5-19`
+    Evidence: permission is framed as deciding when model actions execute, ask, degrade, or deny; it includes modes, rules, filesystem safety, auto classifier, tool handlers, UI approval, plan mode, and ask-user semantics.
+  - `/root/claude-code-haha/docs/must-read/05-permission-security.md:113-150`
+    Evidence: permission runtime has rule, resource-safety, strategy, and interaction layers; auto mode is fail-safe, not direct allow.
+  - `/root/claude-code-haha/docs/must-read/05-permission-security.md:166-200`
+    Evidence: hooks cannot skip permission, auto mode strips dangerous broad rules, bypass is not unlimited, shadowed rules matter, and AskUserQuestion is protected.
+  - `/root/claude-code-haha/src/types/permissions.ts`
+    Evidence: modes, rule sources, update destinations, allow/ask/deny decisions, passthrough, and structured decision reasons are typed separately to avoid import cycles and improve explainability.
+  - `/root/claude-code-haha/src/utils/permissions/permissions.ts:473-880`
+    Evidence: permission decisions reset/track denials, convert `dontAsk` asks to deny, guard auto mode safety checks, use accept-edits fast paths, safe-tool allowlists, classifier decisions, overhead telemetry, and fail-closed classifier behavior.
+* Secondary analysis:
+  - `/tmp/claude-code-book/第一部分-基础篇/04-权限管线-Agent的护栏.md`
+  - `/tmp/claude-code-book/第二部分-核心系统篇/05-设置与配置-Agent的基因.md`
+  - `/tmp/claude-code-book/第二部分-核心系统篇/08-钩子系统-Agent的生命周期扩展点.md`
+* LangChain primary docs:
+  - `/oss/python/langchain/guardrails`: guardrails can be deterministic or model-based and implemented with middleware around agent execution.
+  - `/oss/python/langchain/human-in-the-loop`: HITL middleware interrupts tool calls, persists graph state through checkpointing, and supports approve/edit/reject decisions.
+  - `/oss/python/langchain/middleware/custom`: `wrap_tool_call` runs around each tool call and is the right primitive for permission/guard decisions at the tool boundary.
+
+#### System role in the harness
+
+Permission / Safety is the runtime layer that turns “the model wants to act” into “the product may or may not execute this action now.”
+
+It is not merely:
+
+* a boolean allow/deny helper
+* a set of per-tool if statements
+* a CLI confirmation prompt
+* a LangChain middleware with no durable policy model
+* a post-hoc audit log after dangerous actions already ran
+
+#### cc / cc-haha essence
+
+* The product treats an agent as a potentially dangerous executor, not just a helpful model.
+* Permission mode is top-level runtime state:
+  - default
+  - plan
+  - acceptEdits
+  - auto
+  - bypassPermissions
+  - dontAsk
+  - internal/bubble-style delegation where applicable
+* Permission decisions are layered:
+  - tool input/schema validity
+  - allow / ask / deny rules
+  - hard resource safety, especially filesystem/path safety
+  - mode strategy
+  - classifier or automated decision where appropriate
+  - interactive / headless / coordinator / worker behavior
+* Filesystem safety is its own kernel-level concern for a coding agent:
+  - dangerous paths
+  - workspace escape
+  - extra trusted workdirs
+  - shell command risk
+  - symlink / path normalization and cross-platform path edge cases where needed
+* Auto mode is not “trust the model.” It is a constrained automation layer with:
+  - safe fast paths
+  - dangerous broad-rule stripping
+  - classifier decision
+  - denial tracking
+  - conservative fallback when classifier fails or prompts are unavailable
+* Bypass mode is not absolute; some safety checks remain immune to bypass.
+* Hooks and extensions are not safety backdoors. Hook allow/ask must still respect the permission runtime.
+* AskUserQuestion and plan-mode transitions are safety-sensitive user-interaction capabilities, not ordinary text.
+* Decisions must carry reasons and metadata, not just booleans, so the system can explain, test, log, and later refine behavior.
+
+#### Feature boundary
+
+In scope for permission/safety essence:
+
+* permission modes and mode transitions
+* allow / ask / deny local rules
+* rule sources and destinations
+* hard safety guards for filesystem and command execution
+* trusted/untrusted capability source handling
+* extension trust metadata for MCP/plugin/skill tools
+* headless / non-interactive fallback behavior
+* pre-tool hooks that cannot bypass hard guards
+* structured decision reasons and local runtime events
+* plan-mode read-only boundary
+* ask-user-question protection
+* future HITL approval path
+
+Not in scope for current permission/safety essence:
+
+* cloning cc-haha's full permission UI
+* full YOLO/auto classifier parity before deterministic policy is solid
+* enterprise policy/MDM/marketplace trust UX unless a concrete product need appears
+* remote auth / XAA / bridge control surfaces until the product has those runtime modes
+* fully general shell AST classifier unless simple command policy proves insufficient
+
+#### LangChain-native expression
+
+The local LangChain/LangGraph shape should be:
+
+* Use `AgentMiddleware.wrap_tool_call` as the primary tool-boundary guard.
+* Return `ToolMessage(status="error")` for denied/rejected actions so the model receives protocol-safe feedback.
+* Use LangGraph `Command` / interrupt patterns for future human-in-the-loop approval where execution must pause and resume.
+* Use checkpointer persistence when HITL interrupts are introduced, because LangChain HITL requires graph state persistence across interrupts.
+* Use deterministic guard middleware before adding model-based classifiers.
+* Use capability metadata from `CapabilityRegistry` to evaluate source, trust, read-only, destructive, and domain information.
+* Keep policy logic in `permissions` / `tool_system.policy`, not in individual tool functions except for tool-local invariants.
+* Use built-in or custom LangChain guardrails only where they match the local product boundary; do not import broad guardrail machinery without a concrete benefit.
+
+#### Product-grade architecture shape
+
+Suggested product-local boundaries:
+
+* `permissions.modes`: external/internal modes and transitions
+* `permissions.rules`: explicit local rules, sources, and match semantics
+* `permissions.manager`: deterministic permission runtime for one tool call
+* `permission_specs`: settings/env-facing rule specs
+* `filesystem.policy`: command/path hard safety
+* `tool_system.policy`: maps capability metadata + permission runtime to tool-call decisions
+* `tool_system.middleware`: LangChain `wrap_tool_call` integration, hook dispatch, event emission
+* future `permissions.hitl`: LangGraph interrupt/resume based approval flow
+
+Current local evidence:
+
+* `coding_deepgent.permissions.manager.PermissionManager` already has mode, rules, hard safety, read-only bash recognition, trusted workdirs, extension trust, and `dontAsk` conversion.
+* `coding_deepgent.tool_system.middleware.ToolGuardMiddleware` already uses LangChain middleware to deny/allow, emit runtime events, and dispatch `PreToolUse`, `PostToolUse`, and `PermissionDenied` hooks.
+
+#### Alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Runtime framing | permission is a runtime deciding execute/ask/deny/degrade, not per-tool private logic | one safety layer for all tools | `PermissionManager` + `ToolGuardMiddleware` | align | Keep one permission runtime |
+| Modes | cc-haha has default/plan/acceptEdits/auto/bypass/dontAsk plus internal delegation | actions change behavior by explicit mode | `PermissionMode` with deterministic local modes | partial | Keep current modes; add richer mode semantics incrementally |
+| Rule engine | allow/deny/ask rules with sources and update destinations | explainable local policy | `PermissionRule`, specs, metadata | partial | Expand only as needed; do not overbuild enterprise sources yet |
+| Hard filesystem safety | filesystem/path safety is an independent core layer | prevent workspace escape and dangerous command/path behavior | `filesystem.policy` + hard safety before rules/mode where appropriate | align | Treat as bypass-resistant guard |
+| Auto classifier | auto mode uses fast paths, classifier, denial tracking, fail-safe behavior | reduce prompts without unsafe automation | future classifier layer | defer | Do deterministic policy first |
+| Headless behavior | no UI means asks cannot hang; fallback is conservative | background/subagent/tool calls do not deadlock | deny/ToolMessage for no-approval contexts | align | Keep conservative non-interactive behavior |
+| Hook relationship | hooks cannot bypass permission runtime | extension hooks are not backdoors | `ToolGuardMiddleware` order + hard guard checks | align | PreToolUse can block, not override hard safety |
+| Approval UI | cc-haha has rich per-tool UI | better UX but not core runtime now | future CLI/HITL approval UX | defer | Use LangGraph HITL only when local interactive approval is required |
+| Decision reasons | decisions carry rule/mode/hook/classifier/safety reasons | auditable tests and debugging | structured `PermissionDecision` metadata/events | align | Make every deny/ask explainable |
+
+#### Must-align
+
+* Permission is one runtime layer, not scattered per-tool business logic.
+* Deny/hard-safety decisions must be explicit and explainable.
+* Plan mode must prevent write/destructive actions while allowing meaningful read/research.
+* `dontAsk` converts would-ask actions to deny rather than blocking indefinitely.
+* Extension-provided or untrusted capabilities should be more conservative than builtin trusted tools.
+* Headless/background contexts must not wait for impossible user approval.
+* Hooks and extensions must not bypass hard safety or permission runtime.
+
+#### Partial / LangChain equivalent
+
+* cc-haha interactive approval UI becomes LangChain `ToolMessage` deny path now, with future LangGraph HITL interrupt/resume when user approval UX is intentionally added.
+* cc-haha classifier/auto mode becomes deterministic local policy now; model-based classifier is a later optional layer.
+* cc-haha rich rule sources become a small local settings/env rule model now.
+* cc-haha permission telemetry becomes local `RuntimeEvent` evidence now, with richer observability later.
+
+#### Defer
+
+* YOLO / auto-mode classifier parity
+* shadowed-rule UI
+* enterprise managed policy UX
+* remote approval routing / bridge permission callbacks
+* broad shell AST classifier parity
+* per-tool rich approval dialogs
+
+#### Do-not-copy
+
+* React/Ink permission UI internals
+* Anthropic-specific classifier telemetry fields
+* broad allow stripping rules without a local auto-mode classifier to justify them
+* bypass behavior that allows hard filesystem safety to be skipped
+* permission aliases that hide tool/schema mismatch
+
+#### Complexity / why-now judgment
+
+Worth doing now:
+
+* deterministic mode/rule/hard-safety policy because current product already executes filesystem, memory, skills, tasks, subagents, MCP, and plugin-related tools
+* structured decision reasons and runtime events because debugging safety behavior without them is guesswork
+* extension trust metadata because Stage 7-11 already introduced MCP/plugin surfaces
+
+Not worth doing yet:
+
+* model-based classifier and auto-mode broad-rule stripping, because deterministic guard behavior must be trusted first
+* rich HITL UI, because current API/CLI can safely return protocol-level deny/ask messages until there is a concrete approval UX requirement
+
+### 3. Prompt System
+
+Status: current working definition, revised after full documentation read and source re-check.
+
+#### Expected effect
+
+Aligning the prompt system should improve: reliability, context-efficiency, maintainability, agent-role clarity, cache efficiency, and product parity.
+
+The local runtime effect is: the model receives a stable, layered instruction contract that defines product identity, behavioral invariants, role/mode overlays, and user customizations without turning dynamic runtime state into a fragile monolithic system prompt.
+
+Why this is worth complexity:
+
+* Prompt drift is one of the easiest ways to make an agent unreliable, especially once tools, tasks, memory, skills, and subagents interact.
+* A layered prompt makes role/mode behavior auditable and testable instead of buried in one large string.
+* Cache-aware prompt structure matters for long-running agents and fork/subagent behavior; changing high-volatility prompt bytes can destroy cache efficiency.
+
+#### Primary reference points
+
+* `cc-haha` primary source:
+  - `/root/claude-code-haha/docs/must-read/03-prompt-context-memory.md:5-16`
+    Evidence: prompt/context/memory is framed as engineering for long-running agents, not just writing a good prompt.
+  - `/root/claude-code-haha/docs/must-read/03-prompt-context-memory.md:66-77`
+    Evidence: system prompt assembly flows through `systemPrompt.ts`, default prompt, coordinator/main-thread/custom/append layers, `context.ts`, `queryContext.ts`, and then query cache-key prefix use.
+  - `/root/claude-code-haha/docs/must-read/03-prompt-context-memory.md:117-145`
+    Evidence: system prompt has five layers; `userContext` and `systemContext` are separated for cache engineering.
+  - `/root/claude-code-haha/docs/modules/03-prompt-context-memory-deep-dive.md:19-40`
+    Evidence: system prompt is multi-layered so core behavior, role overlays, custom prompt, and append prompt remain separated.
+  - `/root/claude-code-haha/src/utils/queryContext.ts:30-43`
+    Evidence: `fetchSystemPromptParts` returns default system prompt, user context, and system context as cache-key prefix pieces; custom prompt replaces default prompt and skips default system context.
+  - `/root/claude-code-haha/src/context.ts:113-188`
+    Evidence: system and user context are cached for the conversation and kept distinct.
+* Secondary analysis:
+  - `/tmp/claude-code-book/第二部分-核心系统篇/07-上下文管理-Agent的工作记忆.md`
+  - `/tmp/claude-code-book/第四部分-工程实践篇/13-流式架构与性能优化.md`
+* LangChain primary docs:
+  - `/oss/python/langchain/agents`: `system_prompt` shapes agent behavior; `SystemMessage` gives control over prompt structure and provider features like Anthropic prompt caching.
+  - `/oss/python/langchain/agents`: `@dynamic_prompt` middleware can generate prompts from runtime context or state.
+  - `/oss/python/langchain/context-engineering`: model context includes instructions, messages, tools, model choice, and response format; middleware is the mechanism for modifying context across the agent lifecycle.
+
+#### System role in the harness
+
+The prompt system is the harness layer that defines the model's stable operating contract: identity, product role, behavioral invariants, role/mode overlays, and customization boundaries.
+
+It is not merely:
+
+* prose copywriting
+* a dump of all project context
+* a replacement for tool descriptions
+* a memory retrieval system
+* a task/workflow state store
+* a place to hide missing schemas or policies
+
+#### cc / cc-haha essence
+
+* The prompt is a layered instruction architecture, not one giant string.
+* Stable behavior rules and product identity are separate from dynamic runtime context.
+* Role overlays are first-class:
+  - coordinator prompt
+  - main-thread agent prompt
+  - subagent / specialized agent prompt
+  - plan-mode prompt
+  - verification/coordinator constraints where applicable
+* Custom prompt and append prompt have distinct semantics:
+  - custom prompt may replace the default base
+  - append prompt extends after the base
+  - neither should silently erase safety/tool/model-visible contracts without an explicit product decision
+* User context and system context are separated because their volatility and cache effects differ.
+* Dynamic state such as plan mode, agent list deltas, deferred tools, task status, teammate mailbox, and relevant memory does not belong in the stable core prompt by default.
+* Tool-specific rules belong in tool descriptions/schemas/validators, not a global tool manual embedded into the prompt.
+* Prompt assembly must be cache-aware. A high-volatility prompt prefix is a product/runtime bug, not just a cost issue.
+* Prompt engineering, context engineering, and memory engineering are adjacent but not identical:
+  - prompt defines stable behavioral contract
+  - context decides dynamic information placement
+  - memory decides what durable knowledge exists and how it is recalled
+
+#### Feature boundary
+
+In scope for prompt-system essence:
+
+* layered system-prompt construction
+* stable vs dynamic instruction separation
+* prompt role composition
+* role/mode overlay semantics
+* custom vs append prompt semantics
+* cache-aware prompt prefix design
+* small, auditable prompt builder API
+* tests proving tool manuals and dynamic data are not accidentally shoved into system prompt
+
+Not in scope for prompt-system essence:
+
+* memory retrieval policy itself
+* session replay/recovery mechanics
+* full context selection and compaction strategy
+* UI copy or presentation style
+* tool-specific manuals that belong in tool schemas/descriptions
+* full prompt-cache block metadata until provider-specific caching becomes an explicit local goal
+
+#### LangChain-native expression
+
+The local LangChain/LangGraph shape should be:
+
+* Use a small `PromptContext` / prompt builder as the default static prompt source.
+* Use LangChain `system_prompt` for stable base prompt when prompt is known at agent construction.
+* Use `SystemMessage` only when provider-specific block-level structure or cache controls are intentionally needed.
+* Use `dynamic_prompt` middleware when prompt must change based on runtime context or state.
+* Use `context_schema` to pass immutable runtime facts used by prompt middleware.
+* Keep dynamic task/memory/tool deltas in context/message assembly middleware, not in the core base prompt.
+* Keep tool-specific behavior in `@tool` descriptions and Pydantic `Field(description=...)`.
+* Keep prompt builders dependency-light; they should not import heavy domain services or become a service locator.
+
+#### Product-grade architecture shape
+
+Suggested product-local boundaries:
+
+* `prompting.builder`: stable base prompt, custom/append semantics, prompt parts
+* `prompting.context`: structured prompt context object and render helpers if builder grows
+* `prompting.middleware`: future LangChain `dynamic_prompt` middleware for role/mode overlays that truly depend on state/context
+* domain-level prompt fragments only when the domain owns global behavior, not tool-local usage docs
+
+Current local evidence:
+
+* `coding_deepgent.prompting.builder.PromptContext` already separates `default_system_prompt`, `user_context`, `system_context`, `append_system_prompt`, and `memory_context`.
+* `build_default_system_prompt()` already encodes product identity and LangChain-native tool/state preference.
+* Current tests already assert `write_file` / stale tool wording is not accidentally present in the system prompt.
+
+#### Alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Layered prompt | cc-haha separates default, coordinator, main-thread agent, custom, and append prompt | role and mode behavior stays auditable | `PromptContext` + builder / future middleware | align | Keep layers explicit |
+| Cache-key prefix | `queryContext.ts` fetches default prompt, user context, system context as cache-key pieces | stable prompt prefix and lower cache churn | stable builder + avoid volatile prompt injection | align | Treat volatility as architecture concern |
+| Custom prompt | cc-haha custom prompt can replace default and skip default system context | user override is explicit and testable | `custom_system_prompt` replaces base | align | Preserve current behavior, document risk |
+| Append prompt | cc-haha append prompt extends after base | local customization without replacing base identity | `append_system_prompt` | align | Keep separate from custom replacement |
+| Dynamic attachments | cc-haha routes many dynamic states through attachments, not the base prompt | avoid giant fragile system prompt | context/message assembly layer | partial | Handle in context system, not prompt system |
+| Tool manuals | cc-haha tools own prompts/descriptions | reduce prompt bloat and schema drift | tool descriptions and Field docs | align | Do not put full tool manual in system prompt |
+| Provider cache blocks | LangChain supports `SystemMessage` content blocks/cache controls | optimize costs when needed | future explicit provider-specific prompt blocks | defer | Only add with measured cache benefit |
+
+#### Must-align
+
+* Prompt is layered, not a single undifferentiated string.
+* Stable product identity and behavioral invariants remain in the base prompt.
+* Custom and append prompt semantics stay distinct.
+* Dynamic state does not rewrite the core prompt by default.
+* Tool-specific instructions live with tools.
+* Prompt structure is tested because regressions are hard to see from behavior alone.
+
+#### Partial / LangChain equivalent
+
+* cc-haha's attachment relationship belongs mostly to the Context System in this product, not Prompt System.
+* cc-haha's provider/cache-specific system prompt block handling becomes LangChain `SystemMessage` only when required.
+* role overlays can initially be builder-level flags; use `dynamic_prompt` middleware only when runtime state/context actually drives prompt changes.
+
+#### Defer
+
+* full prompt-cache block metadata
+* coordinator/subagent prompt overlays until those runtime modes are upgraded
+* dynamic prompt middleware if static builder is still enough
+* prompt dumping / prompt-cache break diagnostics as first-class UX
+
+#### Do-not-copy
+
+* a huge cc-haha system prompt verbatim
+* dynamic task/memory/tool state embedded into the stable base prompt
+* Anthropic-only prompt block structures unless explicitly needed
+* tool manuals in the base prompt
+* prompt-builder imports of containers or business services
+
+#### Complexity / why-now judgment
+
+Worth doing now:
+
+* preserve a structured prompt builder and tests, because the current product already has memory, tasks, skills, permissions, and tool contracts whose wording can drift
+* clarify custom/append/memory roles, because those settings already exist locally
+
+Not worth doing yet:
+
+* provider-specific prompt-cache block structure, because the current product has not established a measured cache optimization need
+* complex dynamic prompt middleware for roles not yet productized in `coding-deepgent`
+
+#### Confirmed decisions
+
+* Core principle confirmed by user: dynamic state should normally enter through attachment / delta / runtime message assembly rather than repeated rewrites of the core system prompt.
+
+### 4. Context System
+
+#### Expected effect
+
+Aligning the context system should improve: context-efficiency, reliability, maintainability, and long-session continuity. The local runtime effect is: only relevant dynamic information enters the model window, context pressure is handled through controlled projection/compaction/recovery paths, and protocol-critical message structure survives long tasks instead of collapsing into an unbounded transcript.
+
+#### Primary reference points
+
+* `cc-haha` primary source:
+  - `/root/claude-code-haha/docs/must-read/03-prompt-context-memory.md`
+  - `/root/claude-code-haha/docs/must-read/01-execution-engine.md`
+  - `/root/claude-code-haha/src/utils/attachments.ts`
+  - `/root/claude-code-haha/src/utils/messages.ts`
+  - `/root/claude-code-haha/src/context.ts`
+  - `/root/claude-code-haha/src/utils/queryContext.ts`
+  - `/root/claude-code-haha/src/services/compact/compact.ts`
+  - `/root/claude-code-haha/src/services/compact/autoCompact.ts`
+  - `/root/claude-code-haha/src/services/compact/microCompact.ts`
+  - `/root/claude-code-haha/src/services/compact/sessionMemoryCompact.ts`
+  - `/root/claude-code-haha/src/utils/toolResultStorage.ts`
+* Secondary analysis:
+  - `claude-code-book` orientation on context management and compaction
+
+#### Essence
+
+* The context system decides what information enters the model window, when it enters, where it is placed, and how long it remains useful.
+* It is a scoped dynamic-information and context-pressure management system, not a dump-everything mechanism.
+* Context must have explicit categories and scopes:
+  - project/user context
+  - system/runtime context
+  - file/path-scoped context
+  - tool/task/agent/mode deltas
+  - memory-derived context
+* Dynamic context should be deduplicated and scoped rather than globally injected.
+* Context injection should fail soft: one broken attachment or missing memory file should not break the whole runtime.
+* Context should be lifecycle-aware:
+  - some context is per-turn
+  - some is session-scoped
+  - some is path-scoped
+  - some is role/agent-scoped
+  - some is long-term memory-derived
+* The system must protect token budget and cache stability while preserving enough state for continuation.
+* Context compression is a core context-system responsibility, not an optional summarization utility.
+* Compression is multi-strategy, not one summary function:
+  - tool-result budgeting and persistence
+  - message projection / normalization that preserves protocol structure
+  - microcompact for lower-cost cleanup of old tool results
+  - auto-compact when the window approaches threshold
+  - session-memory-assisted compaction when available
+  - reactive prompt-too-long recovery when proactive paths fail
+  - post-compact cleanup and restoration of important working context
+* Context compression must preserve protocol correctness:
+  - tool use / tool result pairing
+  - recent execution window
+  - compact boundary markers
+  - enough file/task/skill context to continue work
+* Context pressure should be observable and guardable through thresholds, warning state, and circuit breakers rather than infinite failed retry loops.
+
+#### Feature boundary
+
+In scope for context-system essence:
+
+* dynamic attachment/delta protocol
+* context scope and deduplication
+* runtime message assembly for contextual state
+* path-scoped project context
+* fail-soft context injection
+* context lifecycle categories
+* context budget measurement and thresholds
+* tool-result budget / persistence strategy
+* message projection and normalization for API-bound context
+* microcompact / auto-compact / reactive compact behavior
+* post-compact restoration of critical working context
+* compact boundary markers and continuation safety
+
+Not in scope for context-system essence:
+
+* exact memory extraction/write policy
+* session transcript persistence itself
+* task state machine semantics
+* UI rendering
+* the exact wording of compact prompts, except where it affects continuation quality
+
+#### LangChain-native expression
+
+The local LangChain/LangGraph shape should be:
+
+* typed runtime context object(s)
+* bounded context rendering helpers
+* state/context schemas for runtime-visible state
+* middleware or invocation assembly for dynamic per-turn context
+* LangGraph store/checkpointer only where the context is persistent or cross-turn
+* deterministic compaction/projector helpers around LangGraph message history
+* explicit tests that compressed/projected history still preserves tool/state protocol invariants
diff --git a/.trellis/tasks/04-14-redefine-coding-deepgent-final-goal/task.json b/.trellis/tasks/04-14-redefine-coding-deepgent-final-goal/task.json
new file mode 100644
index 000000000..c2a8bb5de
--- /dev/null
+++ b/.trellis/tasks/04-14-redefine-coding-deepgent-final-goal/task.json
@@ -0,0 +1,61 @@
+{
+  "id": "redefine-coding-deepgent-final-goal",
+  "name": "redefine-coding-deepgent-final-goal",
+  "title": "brainstorm: redefine coding-deepgent final goal",
+  "description": "",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [
+    "04-14-stage-13a-manual-compact-boundary-and-summary-artifact",
+    "04-14-stage-13b-manual-compact-entry-point",
+    "04-14-stage-13c-compact-summary-generation-seam",
+    "04-14-stage-14a-explicit-generated-summary-cli-wiring",
+    "04-14-stage-15a-non-destructive-compact-transcript-records",
+    "04-14-stage-15b-compact-record-recovery-display",
+    "04-14-stage-15c-compacted-continuation-selection",
+    "04-14-stage-16-compact-transcript-pruning-semantics",
+    "04-14-stage-16a-load-time-compacted-history-view",
+    "04-14-stage-16b-virtual-pruning-compact-selection-hardening",
+    "04-14-stage-16b-latest-valid-compact-view-selection",
+    "04-14-stage-16c-virtual-pruning-view-metadata",
+    "04-14-stage-17a-task-graph-readiness-and-transition-invariants",
+    "04-14-stage-17b-plan-verify-workflow-boundary",
+    "04-15-stage-17c-explicit-plan-artifact-boundary",
+    "04-15-stage-17d-verifier-subagent-execution-boundary"
+  ],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/04-14-stage-12a-context-payload-foundation/check.jsonl b/.trellis/tasks/04-14-stage-12a-context-payload-foundation/check.jsonl
new file mode 100644
index 000000000..028262ce6
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-12a-context-payload-foundation/check.jsonl
@@ -0,0 +1,7 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": ".omx/plans/coding-deepgent-h01-h10-target-design.md", "reason": "Check implementation against H04/H05 target"}
+{"file": "coding-deepgent/tests/test_planning.py", "reason": "Check bounded and deterministic todo payload rendering"}
+{"file": "coding-deepgent/tests/test_memory_integration.py", "reason": "Check bounded and deterministic memory payload rendering"}
+{"file": "coding-deepgent/src/coding_deepgent/todo/middleware.py", "reason": "Verify todo middleware uses shared payload rendering"}
+{"file": "coding-deepgent/src/coding_deepgent/memory/middleware.py", "reason": "Verify memory middleware uses shared payload rendering"}
diff --git a/.trellis/tasks/04-14-stage-12a-context-payload-foundation/debug.jsonl b/.trellis/tasks/04-14-stage-12a-context-payload-foundation/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-12a-context-payload-foundation/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/04-14-stage-12a-context-payload-foundation/implement.jsonl b/.trellis/tasks/04-14-stage-12a-context-payload-foundation/implement.jsonl
new file mode 100644
index 000000000..ad929222a
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-12a-context-payload-foundation/implement.jsonl
@@ -0,0 +1,9 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": ".omx/plans/coding-deepgent-h01-h10-target-design.md", "reason": "Stage 12A target design and highlight gaps"}
+{"file": ".trellis/tasks/04-14-stage-12a-context-payload-foundation/prd.md", "reason": "Accepted 12A scope and alignment matrix"}
+{"file": "coding-deepgent/src/coding_deepgent/todo/middleware.py", "reason": "Current todo dynamic context injection path"}
+{"file": "coding-deepgent/src/coding_deepgent/memory/middleware.py", "reason": "Current memory dynamic context injection path"}
+{"file": "coding-deepgent/src/coding_deepgent/prompting/builder.py", "reason": "Current prompt context boundary"}
+{"file": "coding-deepgent/tests/test_planning.py", "reason": "Existing todo middleware behavior tests"}
+{"file": "coding-deepgent/tests/test_memory_integration.py", "reason": "Existing memory middleware behavior tests"}
diff --git a/.trellis/tasks/04-14-stage-12a-context-payload-foundation/prd.md b/.trellis/tasks/04-14-stage-12a-context-payload-foundation/prd.md
new file mode 100644
index 000000000..58db068c1
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-12a-context-payload-foundation/prd.md
@@ -0,0 +1,317 @@
+# Stage 12A: Context Payload Foundation
+
+## Goal
+
+Introduce a typed, bounded, testable dynamic context payload foundation for `coding-deepgent`, so todo, memory, task, session, and future subagent/mailbox context do not keep growing as ad hoc `SystemMessage` string fragments.
+
+This stage is infrastructure-only and should prepare the product for later context projection, recovery, memory quality, task, and multi-agent upgrades.
+
+## What I already know
+
+* This is the first sub-stage of `Stage 12: Context and Recovery Hardening`.
+* The parent readiness decision says advanced cc highlight work should wait until H04/H05/H06/H07 infrastructure is stronger.
+* Existing local context injection is partial:
+  - `PlanContextMiddleware` renders todos/reminders directly into a `SystemMessage`.
+  - `MemoryContextMiddleware` renders memories directly into a `SystemMessage`.
+  - `RuntimeContext` carries session/workdir/trusted_workdirs/entrypoint/agent_name/skill_dir/event_sink/hook_registry.
+* Existing local prompt foundation is small and should remain small:
+  - `PromptContext`
+  - `build_default_system_prompt()`
+  - `build_prompt_context()`
+* cc-haha source shows attachment/context is a typed dynamic protocol, not just prompt string concatenation:
+  - `/root/claude-code-haha/src/utils/attachments.ts`
+  - `/root/claude-code-haha/src/utils/messages.ts`
+  - `/root/claude-code-haha/src/utils/queryContext.ts`
+  - `/root/claude-code-haha/src/context.ts`
+* LangChain docs frame context engineering as controlling model context, tool context, and lifecycle context through middleware.
+* `langchain-architecture-guard` says the smallest viable shape should use middleware and avoid speculative wrapper layers.
+
+## Assumptions
+
+* Stage 12A should introduce a small typed context payload model, not a full cc-haha attachment clone.
+* The first implementation should support existing todo and memory dynamic context only.
+* Future payload kinds should be possible without changing every middleware.
+* Rendering should be deterministic and bounded.
+* Injection should fail soft: empty/no-op payloads should not change the model request.
+
+## Requirements
+
+* Add a product-local dynamic context payload foundation.
+* Represent payloads with explicit fields:
+  - `kind`
+  - `text`
+  - `source`
+  - priority/order metadata if useful for deterministic rendering
+* Provide bounded rendering helpers.
+* Migrate `PlanContextMiddleware` and `MemoryContextMiddleware` to build context payloads and render through the shared helper.
+* Preserve current user-visible behavior as much as possible:
+  - todos still render as "Current session todos"
+  - stale todo reminders still render
+  - recalled memories still render as "Relevant long-term memory"
+* Add deterministic tests for:
+  - payload render output
+  - max length / bounded output
+  - no duplicate payload rendering
+  - memory middleware uses shared payload rendering
+  - todo middleware uses shared payload rendering
+* Keep the implementation LangChain-native:
+  - middleware remains `AgentMiddleware`
+  - model request updates use `request.override(system_message=SystemMessage(...))`
+  - no custom agent loop or query runtime
+
+## Acceptance Criteria
+
+* [ ] A context payload module exists with typed payload data and bounded render helpers.
+* [ ] Existing todo context injection goes through the shared payload renderer.
+* [ ] Existing memory context injection goes through the shared payload renderer.
+* [ ] Tests prove bounded rendering and deterministic ordering.
+* [ ] Tests prove duplicate payloads are not rendered twice in one injection pass.
+* [ ] Existing app/tool binding tests still pass.
+* [ ] No product code introduces a custom query loop or a cc-haha-style full attachment framework.
+
+## Definition of Done
+
+* Unit tests are added/updated for the new context payload foundation.
+* Existing relevant tests continue to pass:
+  - `tests/test_app.py`
+  - `tests/test_memory_context.py`
+  - `tests/test_memory_integration.py`
+  - `tests/test_planning.py`
+  - `tests/test_todo_domain.py`
+* Lint/typecheck are run if available and scoped enough for this package.
+* Product docs/status are updated if the implementation changes architecture-visible behavior.
+
+## Out of Scope
+
+* Full cc-haha attachment protocol parity
+* Message projection
+* Tool result projection or persistence
+* Microcompact / autocompact / reactive compact
+* Session resume changes
+* Recovery brief
+* Memory quality policy
+* Subagent mailbox / team context payloads
+* Coordinator mode
+* Plugin marketplace behavior
+* Permission classifier / rich HITL approval UI
+
+## cc-haha Alignment
+
+### Expected effect
+
+Aligning this behavior should improve context-efficiency, reliability, maintainability, and product parity.
+
+The local runtime effect is: dynamic context is built through a typed, bounded, testable payload layer instead of each middleware appending raw text to the system prompt independently. If this does not reduce ad hoc prompt injection and make later context projection easier, it is not worth shipping.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Attachment as dynamic context protocol | `/root/claude-code-haha/src/utils/attachments.ts` defines many typed `Attachment` variants such as `nested_memory`, `relevant_memories`, `plan_mode`, `agent_listing_delta`, `task_status`, `teammate_mailbox` | avoid ad hoc untyped context injection | small `ContextPayload` model | partial | Implement a small local equivalent, not full parity |
+| Attachment message conversion | `/root/claude-code-haha/src/utils/attachments.ts:createAttachmentMessage` wraps attachments as typed messages with UUID/timestamp | separate payload creation from model-message rendering | payload builder + renderer helper | partial | Render to LangChain `SystemMessage` blocks now; full message protocol later |
+| Todo reminders | cc-haha produces `todo_reminder` attachments based on turns since TodoWrite | preserve bounded todo nudges | todo middleware payloads | align | Keep local behavior, change the internal rendering path |
+| Task reminders/status | cc-haha has `task_reminder` / `task_status` attachment paths | future task/subagent context can share protocol | reserved payload kinds or extensible model | defer | Do not implement task payloads in 12A |
+| Relevant memories | cc-haha relevant memory attachments include stable metadata to avoid cache churn | memory context should be bounded and deterministic | memory middleware payloads | partial | Keep simple rendered memories now; richer metadata later |
+| Teammate mailbox | cc-haha mailbox messages are delivered as attachments | future multi-agent comms need payload boundary | none now | defer | Requires H13 work later |
+
+### Non-goals
+
+* Do not port the full TypeScript `Attachment` union.
+* Do not add timestamps/UUIDs to every local payload unless needed for local behavior.
+* Do not add task/subagent/mailbox context in this stage.
+* Do not add LLM summarization or compaction.
+
+### State boundary
+
+* Short-term state remains in LangGraph state (`todos`, `rounds_since_update`, messages).
+* Persistent memory remains in LangGraph store and memory domain.
+* Context payloads are transient model-context render inputs, not persistent state by themselves.
+
+### Model-visible boundary
+
+The model should see the same meaningful text as before:
+
+* current session todos
+* todo reminders
+* relevant long-term memory
+
+The model should not see new implementation-specific payload metadata unless it is intentionally rendered.
+
+### LangChain boundary
+
+Use:
+
+* `AgentMiddleware.wrap_model_call`
+* `SystemMessage` content blocks
+* small helper functions for payload rendering
+
+Avoid:
+
+* custom query runtime
+* custom LangGraph graph nodes for this stage
+* new stores/checkpointers
+* prompt-builder service locator
+
+## Technical Approach
+
+Recommended minimal design:
+
+* Add `coding_deepgent.context_payloads` or `coding_deepgent.context/` module.
+* Define a small immutable payload dataclass, for example:
+  - `kind: Literal["todo", "todo_reminder", "memory"]`
+  - `text: str`
+  - `source: str`
+  - `priority: int = 100`
+* Add helpers:
+  - `render_context_payloads(payloads, max_chars=...) -> list[dict[str, str]]`
+  - dedupe by `(kind, source, text)`
+  - deterministic sort by `(priority, kind, source, text)`
+  - trim oversized payload text with an explicit marker
+* Update:
+  - `todo/middleware.py` to emit payloads for todos/reminder before converting to `SystemMessage`
+  - `memory/middleware.py` to emit payloads for rendered memory before converting to `SystemMessage`
+* Add tests near existing context tests, likely:
+  - `tests/test_context_payloads.py`
+  - updates to `tests/test_planning.py`
+  - updates to `tests/test_memory_integration.py`
+
+## Research Notes
+
+### Current local patterns
+
+* `PlanContextMiddleware.wrap_model_call()` builds `extra_blocks` as raw dicts and appends them to `SystemMessage`.
+* `MemoryContextMiddleware.wrap_model_call()` appends one memory text block directly to `SystemMessage`.
+* `PromptContext` already separates base prompt, user/system context, append prompt, and memory context, but runtime middleware context does not share a payload model.
+
+### Feasible approaches
+
+**Approach A: Small shared payload renderer** (Recommended)
+
+How it works:
+
+* Add a tiny typed payload object and renderer.
+* Existing middlewares continue to own their domain logic.
+* The shared layer only owns dedupe, ordering, bounds, and conversion to content blocks.
+
+Pros:
+
+* Smallest useful infrastructure.
+* Fits LangChain middleware.
+* Avoids cc-haha attachment clone.
+* Gives 12B/12C/12D a shared boundary.
+
+Cons:
+
+* Does not yet model full message lifecycle or compact boundaries.
+
+**Approach B: Full attachment protocol model**
+
+How it works:
+
+* Create a richer local attachment union modeled after cc-haha.
+
+Pros:
+
+* More direct parity vocabulary.
+
+Cons:
+
+* Too much unused structure now.
+* Higher risk of custom runtime drift.
+* Likely to invite task/mailbox/compact work too early.
+
+**Approach C: Keep current per-middleware raw SystemMessage injection**
+
+How it works:
+
+* Do nothing now; each middleware keeps appending raw strings.
+
+Pros:
+
+* No immediate code change.
+
+Cons:
+
+* Fails the infrastructure goal.
+* Future memory/task/subagent context will repeat ad hoc injection.
+* Harder to add projection/compaction invariants.
+
+## Decision (ADR-lite)
+
+**Context**: Stage 12A is meant to create the smallest shared dynamic-context boundary before projection, recovery, memory quality, task, and subagent work.
+
+**Decision**: Use Approach A, a small shared payload renderer.
+
+**Consequences**:
+
+* Todo and memory remain domain-owned.
+* Dynamic context gains a shared bounded rendering path.
+* Full cc-haha attachment protocol remains deferred.
+* Later Stage 12B can build projection/invariant work around a known context payload shape.
+
+## Checkpoint: Stage 12A
+
+Implemented:
+
+* Added a shared `context_payloads` module with:
+  - typed `ContextPayload`
+  - deterministic ordering
+  - dedupe
+  - bounded truncation
+  - merge helper for system-message content
+* Updated todo middleware to emit payloads instead of raw ad hoc text blocks.
+* Updated memory middleware to emit payloads instead of raw ad hoc text blocks.
+* Added focused renderer tests and shared-path integration assertions.
+
+Verification:
+
+* `pytest -q coding-deepgent/tests/test_context_payloads.py coding-deepgent/tests/test_memory_integration.py coding-deepgent/tests/test_planning.py coding-deepgent/tests/test_app.py coding-deepgent/tests/test_memory_context.py`
+* `ruff check coding-deepgent/src/coding_deepgent/context_payloads.py coding-deepgent/src/coding_deepgent/todo/middleware.py coding-deepgent/src/coding_deepgent/memory/middleware.py coding-deepgent/tests/test_context_payloads.py coding-deepgent/tests/test_memory_integration.py coding-deepgent/tests/test_planning.py`
+* `mypy coding-deepgent/src/coding_deepgent/context_payloads.py coding-deepgent/src/coding_deepgent/todo/middleware.py coding-deepgent/src/coding_deepgent/memory/middleware.py`
+
+cc-haha alignment:
+
+* Source files inspected:
+  - `/root/claude-code-haha/src/utils/attachments.ts`
+  - `/root/claude-code-haha/src/utils/messages.ts`
+  - `/root/claude-code-haha/src/utils/queryContext.ts`
+  - `/root/claude-code-haha/src/context.ts`
+* Aligned:
+  - treat dynamic context as typed payloads rather than ad hoc prompt strings
+  - separate payload creation from message rendering
+  - keep todo and memory as domain-owned producers
+* Deferred:
+  - full attachment protocol
+  - task/mailbox payloads
+  - compact boundary payloads
+* Do-not-copy:
+  - UUID/timestamp-heavy attachment envelope
+  - full cc-haha attachment union
+
+LangChain architecture:
+
+* Primitive used:
+  - `AgentMiddleware.wrap_model_call`
+  - `SystemMessage`
+  - small shared render helper
+* Why no heavier abstraction:
+  - Stage 12A only needed a typed bounded seam for existing middleware.
+  - A full attachment framework would have been speculative and would have widened scope into context projection and recovery too early.
+
+Boundary findings:
+
+* New issue:
+  - Existing dynamic context middleware was duplicating `SystemMessage` block assembly, which would have multiplied future work for task/session/subagent context.
+* Impact on next stage:
+  - 12B can now build deterministic projection/invariant work around a shared payload seam instead of reverse-engineering two independent middleware patterns.
+
+Decision:
+
+* continue
+
+Reason:
+
+* Tests passed.
+* cc-haha alignment for the scoped payload seam is sufficient.
+* LangChain-native architecture stayed intact.
+* The next sub-stage still holds and does not require a prerequisite split.
diff --git a/.trellis/tasks/04-14-stage-12a-context-payload-foundation/task.json b/.trellis/tasks/04-14-stage-12a-context-payload-foundation/task.json
new file mode 100644
index 000000000..a8b74a11e
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-12a-context-payload-foundation/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-12a-context-payload-foundation",
+  "name": "stage-12a-context-payload-foundation",
+  "title": "Stage 12A: Context Payload Foundation",
+  "description": "",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-assess-cc-highlight-infrastructure-readiness",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/04-14-stage-12b-message-projection-and-tool-result-invariants/check.jsonl b/.trellis/tasks/04-14-stage-12b-message-projection-and-tool-result-invariants/check.jsonl
new file mode 100644
index 000000000..15f1d45d0
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-12b-message-projection-and-tool-result-invariants/check.jsonl
@@ -0,0 +1,3 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": ".omx/plans/coding-deepgent-h01-h10-target-design.md", "reason": "Check implementation against H05 target"}
diff --git a/.trellis/tasks/04-14-stage-12b-message-projection-and-tool-result-invariants/debug.jsonl b/.trellis/tasks/04-14-stage-12b-message-projection-and-tool-result-invariants/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-12b-message-projection-and-tool-result-invariants/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/04-14-stage-12b-message-projection-and-tool-result-invariants/implement.jsonl b/.trellis/tasks/04-14-stage-12b-message-projection-and-tool-result-invariants/implement.jsonl
new file mode 100644
index 000000000..49e0b0117
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-12b-message-projection-and-tool-result-invariants/implement.jsonl
@@ -0,0 +1,5 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": ".omx/plans/coding-deepgent-h01-h10-target-design.md", "reason": "Stage 12B target design and H05 constraints"}
+{"file": ".trellis/tasks/04-14-stage-12b-message-projection-and-tool-result-invariants/prd.md", "reason": "Accepted 12B scope"}
+{"file": "coding-deepgent/src/coding_deepgent/compact/budget.py", "reason": "Existing deterministic tool-result budget helper"}
diff --git a/.trellis/tasks/04-14-stage-12b-message-projection-and-tool-result-invariants/prd.md b/.trellis/tasks/04-14-stage-12b-message-projection-and-tool-result-invariants/prd.md
new file mode 100644
index 000000000..9d92baa28
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-12b-message-projection-and-tool-result-invariants/prd.md
@@ -0,0 +1,140 @@
+# Stage 12B: Message Projection and Tool Result Invariants
+
+## Goal
+
+Add deterministic message/context projection primitives and tool-result invariants on top of the Stage 12A context payload foundation, so later context pressure management does not corrupt tool-use/tool-result semantics or silently break long-session continuity.
+
+## What I already know
+
+* Stage 12A is complete enough to continue:
+  - a shared `context_payloads` foundation exists
+  - todo and memory middleware now use the shared payload renderer
+  - focused tests, ruff, and mypy passed
+* The source-backed target design says H05 is currently weak:
+  - no message projection layer
+  - no compact boundary state
+  - no micro/auto/reactive compact
+  - no tool-result persistence/restore reference
+  - no invariant tests around tool-use/tool-result pairing through projection/compaction
+* cc-haha source treats context pressure management as runtime correctness, not just cost optimization:
+  - `/root/claude-code-haha/src/query.ts`
+  - `/root/claude-code-haha/src/services/compact/*`
+  - `/root/claude-code-haha/src/utils/toolResultStorage.ts`
+  - `/root/claude-code-haha/src/utils/messages.ts`
+* This stage should not start with LLM summarization.
+
+## Assumptions
+
+* Stage 12B should stay deterministic and testable without live model calls.
+* Projection should precede any LLM-based compaction work.
+* The first concern is preserving invariants, not maximizing token savings.
+* Existing `apply_tool_result_budget()` can likely be reused as one building block.
+
+## Open Questions
+
+* None for the initial 12B planning pass.
+
+## Requirements
+
+* Add a deterministic projection layer for oversized or low-priority message/context content.
+* Preserve core runtime invariants:
+  - tool call / tool result linkage
+  - recent useful working context
+  - state update correctness
+  - no silent message corruption
+* Keep the design LangChain/LangGraph-native:
+  - no custom query runtime
+  - no replacing LangChain message/state model
+* Reuse the Stage 12A context payload boundary where appropriate.
+* Add tests that explicitly prove projection does not break protocol assumptions.
+
+## Acceptance Criteria
+
+* [ ] A projection helper or small projection module exists.
+* [ ] Oversized payload/tool-result handling remains deterministic.
+* [ ] Tests prove tool-result / recent-window invariants.
+* [ ] The stage does not introduce LLM summarization yet.
+* [ ] The stage does not widen into session resume or memory policy work.
+
+## Definition of Done
+
+* No compact LLM calls are introduced.
+* Deterministic tests cover the new projection layer.
+* Existing relevant tests still pass.
+* Planning docs stay aligned with the source-backed target design.
+
+## Out of Scope
+
+* auto-compact LLM summarization
+* session memory compaction
+* recovery brief
+* memory quality rules
+* full task/subagent context
+* coordinator/team runtime
+
+## Technical Notes
+
+* Created task: `.trellis/tasks/04-14-stage-12b-message-projection-and-tool-result-invariants`
+* Parent planning docs:
+  - `.omx/plans/coding-deepgent-h01-h10-target-design.md`
+  - `.omx/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+* This stage is the direct continuation of 12A after a `continue` checkpoint decision.
+
+## Checkpoint: Stage 12B
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added deterministic message projection helper in `coding-deepgent/src/coding_deepgent/compact/projection.py`.
+- Exported projection helper from `coding-deepgent/src/coding_deepgent/compact/__init__.py`.
+- Switched `coding-deepgent/src/coding_deepgent/rendering.py::normalize_messages()` to use the projection helper.
+- Added focused projection tests in `coding-deepgent/tests/test_message_projection.py`.
+- Preserved existing rendering behavior for plain same-role text merges while preventing merges for structured content and metadata-bearing messages.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_message_projection.py coding-deepgent/tests/test_rendering.py coding-deepgent/tests/test_compact_budget.py coding-deepgent/tests/test_app.py`
+- `ruff check coding-deepgent/src/coding_deepgent/compact/projection.py coding-deepgent/src/coding_deepgent/rendering.py coding-deepgent/src/coding_deepgent/compact/__init__.py coding-deepgent/tests/test_message_projection.py coding-deepgent/tests/test_rendering.py`
+- `mypy coding-deepgent/src/coding_deepgent/compact/projection.py coding-deepgent/src/coding_deepgent/rendering.py`
+
+cc-haha alignment:
+- Source files inspected:
+  - `/root/claude-code-haha/src/query.ts`
+  - `/root/claude-code-haha/src/utils/messages.ts`
+  - `/root/claude-code-haha/src/services/compact/microCompact.ts`
+  - `/root/claude-code-haha/src/services/compact/compact.ts`
+  - `/root/claude-code-haha/src/utils/toolResultStorage.ts`
+- Aligned:
+  - treat context pressure handling as runtime correctness, not just token trimming
+  - projection preserves message/tool structure instead of flattening everything to raw strings
+- Deferred:
+  - compact boundary markers
+  - tool-result persistence references
+  - micro/auto/reactive compact
+- Do-not-copy:
+  - full compaction stack
+  - custom query loop
+
+LangChain architecture:
+- Primitive used:
+  - deterministic helper functions around existing LangChain message input shape
+  - no runtime replacement
+- Why no heavier abstraction:
+  - 12B only needed a narrow projection seam and invariants, not a general compact subsystem.
+
+Boundary findings:
+- New issue:
+  - the old `normalize_messages()` merged all same-role messages and dropped extra metadata, which is too weak for future structured context/tool-result handling.
+- Impact on next stage:
+  - 12C can now audit session/recovery semantics against a clearer message normalization boundary.
+
+Decision:
+- continue
+
+Reason:
+- Tests passed.
+- Scope stayed inside deterministic projection.
+- No blocker appeared that invalidates the next sub-stage.
diff --git a/.trellis/tasks/04-14-stage-12b-message-projection-and-tool-result-invariants/task.json b/.trellis/tasks/04-14-stage-12b-message-projection-and-tool-result-invariants/task.json
new file mode 100644
index 000000000..41be7f259
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-12b-message-projection-and-tool-result-invariants/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-12b-message-projection-and-tool-result-invariants",
+  "name": "stage-12b-message-projection-and-tool-result-invariants",
+  "title": "Stage 12B: Message Projection and Tool Result Invariants",
+  "description": "",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-assess-cc-highlight-infrastructure-readiness",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/04-14-stage-12c-recovery-brief-and-session-resume-audit/check.jsonl b/.trellis/tasks/04-14-stage-12c-recovery-brief-and-session-resume-audit/check.jsonl
new file mode 100644
index 000000000..aed139cb9
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-12c-recovery-brief-and-session-resume-audit/check.jsonl
@@ -0,0 +1,5 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": ".omx/plans/coding-deepgent-h01-h10-target-design.md", "reason": "Check implementation against H06 target"}
+{"file": "coding-deepgent/tests/test_sessions.py", "reason": "Check recovery brief ordering/limits and resume overwrite semantics"}
+{"file": "coding-deepgent/tests/test_cli.py", "reason": "Check resume-with-prompt uses recovery brief context"}
diff --git a/.trellis/tasks/04-14-stage-12c-recovery-brief-and-session-resume-audit/debug.jsonl b/.trellis/tasks/04-14-stage-12c-recovery-brief-and-session-resume-audit/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-12c-recovery-brief-and-session-resume-audit/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/04-14-stage-12c-recovery-brief-and-session-resume-audit/implement.jsonl b/.trellis/tasks/04-14-stage-12c-recovery-brief-and-session-resume-audit/implement.jsonl
new file mode 100644
index 000000000..f165afb4f
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-12c-recovery-brief-and-session-resume-audit/implement.jsonl
@@ -0,0 +1,8 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/tests/test_sessions.py", "reason": "Existing session store and recovery tests"}
+{"file": ".omx/plans/coding-deepgent-h01-h10-target-design.md", "reason": "Stage 12C target design and H06 constraints"}
+{"file": "coding-deepgent/src/coding_deepgent/cli.py", "reason": "Current CLI resume path"}
+{"file": "coding-deepgent/src/coding_deepgent/sessions/resume.py", "reason": "Current recovery brief and resume primitives"}
+{"file": "coding-deepgent/tests/test_cli.py", "reason": "Existing CLI resume and recovery brief tests"}
+{"file": ".trellis/tasks/04-14-stage-12c-recovery-brief-and-session-resume-audit/prd.md", "reason": "Accepted 12C scope and alignment matrix"}
diff --git a/.trellis/tasks/04-14-stage-12c-recovery-brief-and-session-resume-audit/prd.md b/.trellis/tasks/04-14-stage-12c-recovery-brief-and-session-resume-audit/prd.md
new file mode 100644
index 000000000..095234d48
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-12c-recovery-brief-and-session-resume-audit/prd.md
@@ -0,0 +1,269 @@
+# Stage 12C: Recovery Brief and Session Resume Audit
+
+## Goal
+
+Audit and harden the current session resume path so resumed sessions expose enough execution context to continue useful work, including history, latest runtime state, and recent evidence through a recovery brief on the continuation path.
+
+## What I already know
+
+* This is Stage 12C of `Stage 12: Context and Recovery Hardening`.
+* Current local session foundation is already useful:
+  - `JsonlSessionStore`
+  - message/state/evidence records
+  - `LoadedSession`
+  - `build_recovery_brief()` / `render_recovery_brief()`
+  - CLI `sessions resume <id>` without `--prompt` already prints a recovery brief
+  - CLI resume with `--prompt` loads history/state/session_id and continues
+* Existing tests already prove important parts:
+  - `tests/test_sessions.py` covers roundtrip, invalid records, evidence, fallback state, and resume state restore
+  - `tests/test_cli.py` covers CLI resume with and without prompt
+  - `tests/test_app.py` proves resumed sessions do not retrigger `SessionStart`
+* Source-backed target design for H06 says:
+  - session should be recoverable execution evidence, not just chat history
+  - keep JSONL transcript + state snapshot + evidence
+  - map session id to LangGraph `thread_id`
+  - add a recovery brief target for continuation
+* Explorer audit found the main current gap:
+  - recovery brief/evidence is shown to the user on no-`--prompt` resume, but not fed into the resumed continuation path when `--prompt` is used
+
+## Assumptions
+
+* Stage 12C should remain a narrow audit/hardening stage, not a full session runtime redesign.
+* The smallest valuable change is to make recovery brief context visible on resume-with-prompt, without inventing a larger session framework.
+* Session transcript store, state snapshot semantics, and recovery brief formatting should remain deterministic.
+
+## Open Questions
+
+* None for the current 12C slice.
+
+## Requirements
+
+* Audit the current session/resume path against H06.
+* Preserve current local session storage architecture:
+  - JSONL transcript
+  - state snapshots
+  - evidence records
+* Keep session id mapped to LangGraph `thread_id`.
+* Make resumed continuation with `--prompt` include a recovery brief context, not only raw loaded history/state.
+* Add focused tests for:
+  - evidence ordering and limiting in recovery brief
+  - runtime state overwrite semantics on resume
+  - CLI resume with `--prompt` using a recovery brief in continuation history
+  - resumed sessions still suppress `SessionStart`
+
+## Acceptance Criteria
+
+* [ ] Existing session/resume architecture is audited and documented by the PRD + tests.
+* [ ] Recovery brief behavior is tested more explicitly.
+* [ ] Resume-with-prompt includes recovery brief context in the continuation path.
+* [ ] Resumed session state is still restored deterministically.
+* [ ] Existing session/CLI/app tests still pass.
+
+## Definition of Done
+
+* Focused session and CLI tests are added/updated.
+* No database persistence or full agent runtime resume is introduced.
+* No context pressure/compact work is folded into this stage.
+
+## Out of Scope
+
+* full agent runtime resume parity
+* task-level evidence store
+* database persistence
+* auto-compact / compaction
+* memory quality policy
+* coordinator/team runtime
+
+## cc-haha Alignment
+
+### Expected effect
+
+Aligning this behavior should improve recoverability, reliability, testability, and product parity.
+
+The local runtime effect is: a resumed session can continue with not just chat history and state, but also a compact recovery brief carrying recent evidence, making continuation more useful without rebuilding a full cc-haha runtime resume platform.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Transcript + metadata resume | `/root/claude-code-haha/docs/must-read/02-agent-runtime.md` and `resumeAgent.ts` treat transcript/metadata as resume prerequisites | resumed work has enough state to continue usefully | keep JSONL + state snapshot + evidence | align | Preserve current seam |
+| Recovery brief | H06 target calls for recent evidence visible as a recovery brief | continuation has concise execution context, not only raw history | inject rendered recovery brief into resume-with-prompt path | partial | Implement now |
+| LangGraph thread binding | cc-haha and LangChain both rely on stable session identity | resumed conversation stays on the same thread boundary | preserve `thread_id = session_id` | align | Keep as-is |
+| Full runtime resume breadth | cc-haha resume reconstructs richer runtime objects | avoid scope blow-up in 12C | none now | defer | Do not implement full runtime resume |
+
+### Non-goals
+
+* Do not rebuild cc-haha transcript/metadata runtime objects.
+* Do not add database-backed session persistence.
+* Do not mix memory/task stores into transcript storage.
+* Do not add full task/subagent recovery.
+
+### State boundary
+
+* Session transcript is durable evidence.
+* Session state snapshot restores short-term runtime state relevant to current product behavior.
+* Recovery brief is a transient continuation aid, not durable state itself.
+
+### Model-visible boundary
+
+On `sessions resume --prompt ...`, the model should see:
+
+* the resumed history
+* the restored state
+* a compact recovery brief that includes recent evidence and active todos
+
+It should not see:
+
+* internal storage metadata
+* raw evidence JSON
+* implementation-only session bookkeeping
+
+### LangChain boundary
+
+Use:
+
+* existing `create_agent` runtime
+* existing `thread_id` mapping
+* normal message history continuation
+
+Avoid:
+
+* custom query runtime
+* new graph nodes/checkpointers
+* replacing the current session store seam
+
+## Technical Approach
+
+Recommended minimal design:
+
+* Add a helper in `cli_service.py` to build continuation history from `LoadedSession` plus a rendered recovery brief.
+* Update `cli.py` `sessions_resume --prompt` path to use that helper.
+* Keep `sessions/resume.py` recovery-brief builders as the source of truth.
+* Expand tests in:
+  - `tests/test_sessions.py`
+  - `tests/test_cli.py`
+  - optionally `tests/test_app.py`
+
+## Research Notes
+
+### Current local gaps
+
+* Recovery brief exists, but currently only the no-`--prompt` resume path shows it.
+* Resume-with-prompt currently passes only `loaded.history`, `loaded.state`, and `session_id`.
+* This means evidence and active-todo summary are not visible to the continuation path unless they happen to be reconstructible from raw history/state alone.
+
+### Feasible approaches
+
+**Approach A: Inject recovery brief into resume-with-prompt history** (Recommended)
+
+How it works:
+
+* Reuse existing `build_recovery_brief()` / `render_recovery_brief()`
+* Add one helper for continuation history construction
+* Prepend a small system message with the recovery brief to resumed history when `--prompt` is used
+
+Pros:
+
+* Smallest useful change
+* Reuses current session primitives
+* Improves resumed continuation immediately
+
+Cons:
+
+* Not full runtime resume parity
+
+**Approach B: Audit-only, tests-only**
+
+How it works:
+
+* Add tests but do not change runtime behavior
+
+Pros:
+
+* Very low risk
+
+Cons:
+
+* Leaves the main useful gap unchanged
+
+**Approach C: Full richer runtime resume**
+
+How it works:
+
+* Reconstruct more session/runtime objects beyond history/state/evidence
+
+Pros:
+
+* Closer to future parity
+
+Cons:
+
+* Too wide for 12C
+* Pulls in task/subagent/session architecture prematurely
+
+## Decision (ADR-lite)
+
+**Context**: The current session foundation is already useful, but resume-with-prompt does not yet carry the compact recovery brief into the continuation path.
+
+**Decision**: Use Approach A, inject recovery brief into resume-with-prompt history and strengthen resume/recovery tests.
+
+**Consequences**:
+
+* 12C stays narrow.
+* The current session store seam remains intact.
+* Continuation gets more useful execution context without introducing a new runtime.
+
+## Checkpoint: Stage 12C
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added a model-visible resume context message in `coding-deepgent/src/coding_deepgent/sessions/resume.py` using the existing recovery brief builder/render path.
+- Added `cli_service.continuation_history()` and updated `sessions resume --prompt` to pass recovery brief context, restored state, and the same session id into the continuation path.
+- Updated session recording to keep transcript `message_index` counts based on persisted messages, excluding the synthetic resume context message.
+- Strengthened tests for recovery brief evidence limiting/order, runtime state overwrite/deep-copy semantics, resume-with-prompt recovery brief injection, transcript persistence, and resumed `SessionStart` suppression.
+
+Verification:
+- `pytest -q tests/test_cli.py tests/test_sessions.py tests/test_app.py`
+- `pytest -q tests/test_context_payloads.py tests/test_message_projection.py tests/test_sessions.py tests/test_cli.py tests/test_app.py`
+- `ruff check src/coding_deepgent/sessions/resume.py src/coding_deepgent/cli_service.py src/coding_deepgent/cli.py src/coding_deepgent/sessions/service.py src/coding_deepgent/sessions/__init__.py tests/test_cli.py tests/test_sessions.py tests/test_app.py`
+- `mypy src/coding_deepgent/sessions/resume.py src/coding_deepgent/cli_service.py src/coding_deepgent/cli.py src/coding_deepgent/sessions/service.py src/coding_deepgent/sessions/__init__.py`
+
+cc-haha alignment:
+- Source-backed premise came from the 12C PRD and earlier H06 mapping:
+  - `/root/claude-code-haha/docs/must-read/02-agent-runtime.md`
+  - `resumeAgent.ts`
+- Aligned:
+  - resumed sessions carry transcript, state snapshot, recent evidence, and a compact recovery brief into continuation.
+  - session id remains the stable LangGraph thread id boundary.
+- Deferred:
+  - full runtime object reconstruction.
+  - database-backed persistence.
+  - task/subagent recovery.
+
+LangChain architecture:
+- Primitive used:
+  - normal message history continuation with a small `system` resume context message.
+  - existing `create_agent` runtime and `thread_id = session_id` mapping remain unchanged.
+- Why no heavier abstraction:
+  - 12C only needed model-visible recovery context on resume; a new graph node/checkpointer/store would widen the stage without immediate benefit.
+
+Boundary findings:
+- New issue handled:
+  - synthetic resume context must not be persisted as transcript history or skew message indexes.
+- Residual risk:
+  - an independent subagent review was attempted but failed due usage limits, so final review was local-only.
+- Impact on next stage:
+  - 12D can focus on memory quality policy without also solving resume recovery context.
+
+Decision:
+- continue
+
+Reason:
+- Tests, ruff, and mypy passed.
+- Scope stayed inside session/recovery hardening.
+- No blocker appeared that invalidates `Stage 12D: Memory Quality Policy`.
diff --git a/.trellis/tasks/04-14-stage-12c-recovery-brief-and-session-resume-audit/task.json b/.trellis/tasks/04-14-stage-12c-recovery-brief-and-session-resume-audit/task.json
new file mode 100644
index 000000000..6caefe628
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-12c-recovery-brief-and-session-resume-audit/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-12c-recovery-brief-and-session-resume-audit",
+  "name": "stage-12c-recovery-brief-and-session-resume-audit",
+  "title": "Stage 12C: Recovery Brief and Session Resume Audit",
+  "description": "",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-assess-cc-highlight-infrastructure-readiness",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/04-14-stage-12d-memory-quality-policy/check.jsonl b/.trellis/tasks/04-14-stage-12d-memory-quality-policy/check.jsonl
new file mode 100644
index 000000000..46b4284d8
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-12d-memory-quality-policy/check.jsonl
@@ -0,0 +1,4 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_memory_integration.py", "reason": "save_memory integration behavior through create_agent runtime"}
+{"file": "coding-deepgent/tests/test_memory.py", "reason": "memory policy unit and bounded recall tests"}
diff --git a/.trellis/tasks/04-14-stage-12d-memory-quality-policy/debug.jsonl b/.trellis/tasks/04-14-stage-12d-memory-quality-policy/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-12d-memory-quality-policy/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/04-14-stage-12d-memory-quality-policy/implement.jsonl b/.trellis/tasks/04-14-stage-12d-memory-quality-policy/implement.jsonl
new file mode 100644
index 000000000..9437779a5
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-12d-memory-quality-policy/implement.jsonl
@@ -0,0 +1,6 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/src/coding_deepgent/memory/recall.py", "reason": "bounded deterministic recall behavior"}
+{"file": "coding-deepgent/src/coding_deepgent/memory/store.py", "reason": "LangGraph store namespace/key seam"}
+{"file": "coding-deepgent/src/coding_deepgent/memory/tools.py", "reason": "save_memory hot-path quality gate"}
+{"file": "coding-deepgent/src/coding_deepgent/memory/schemas.py", "reason": "memory schema and model-visible field descriptions"}
diff --git a/.trellis/tasks/04-14-stage-12d-memory-quality-policy/prd.md b/.trellis/tasks/04-14-stage-12d-memory-quality-policy/prd.md
new file mode 100644
index 000000000..75cc4d98e
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-12d-memory-quality-policy/prd.md
@@ -0,0 +1,205 @@
+# Stage 12D: Memory Quality Policy
+
+## Goal
+
+Prevent long-term memory from becoming a dumping ground for transient task state, duplicated facts, or derivable session details.
+
+## Concrete Benefit
+
+* Reliability: recalled memory is less likely to mislead the agent with stale task/session state.
+* Context-efficiency: bounded recall contains reusable knowledge rather than low-value noise.
+* Maintainability: memory remains separate from todo/task/session recovery state.
+
+## What I already know
+
+* Stage 12A added a shared context payload boundary for memory/todo context.
+* Stage 12B added deterministic message projection.
+* Stage 12C now carries session recovery brief/evidence into resume-with-prompt.
+* Current memory foundation uses:
+  - `langgraph.store.memory.InMemoryStore`
+  - `runtime.store`
+  - `save_memory`
+  - `MemoryContextMiddleware`
+  - deterministic namespace/key helpers
+* Current gap:
+  - `save_memory` accepts any non-blank string and only relies on descriptions to discourage transient todos/current plans/task status.
+
+## Requirements
+
+* Add a deterministic memory quality policy before saving long-term memory.
+* Reject obvious low-value memory entries:
+  - transient current-session/task status
+  - active todo/next-step/current-plan content
+  - exact normalized duplicates in the same namespace
+  - trivially short content that is not reusable knowledge
+* Preserve LangChain-native memory architecture:
+  - keep `runtime.store`
+  - keep `@tool(..., args_schema=...)`
+  - keep LangGraph Store namespace/key storage
+* Keep recall bounded and deterministic.
+* Add focused tests for:
+  - policy acceptance/rejection
+  - duplicate detection
+  - `save_memory` not writing rejected memory
+  - bounded recall behavior
+
+## Acceptance Criteria
+
+* [ ] A small memory quality policy exists and is unit-tested.
+* [ ] `save_memory` uses the policy before writing to the LangGraph store.
+* [ ] Duplicate and transient memory are not saved.
+* [ ] Durable reusable memory still saves normally.
+* [ ] Bounded recall behavior is explicitly tested.
+* [ ] No background extraction or vector recall is introduced.
+
+## Definition of Done
+
+* Focused memory tests pass.
+* Existing memory integration tests pass.
+* Ruff and mypy pass on changed files.
+* The stage checkpoint records verdict and next action.
+
+## Out of Scope
+
+* embedding/vector recall
+* auto memory extraction
+* session-memory side agent
+* memory file editing / CLAUDE.md promotion flow
+* team memory sync
+* LLM-based memory review
+
+## cc-haha Alignment
+
+### Expected effect
+
+Aligning this behavior should improve reliability, context-efficiency, maintainability, and product parity.
+
+The local runtime effect is: the model can still save useful long-term memory through LangGraph Store, but obvious transient task/session state and duplicates are rejected before they pollute future recall.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Memory review and promotion | `/root/claude-code-haha/src/skills/bundled/remember.ts` classifies memory across CLAUDE.md, CLAUDE.local.md, team memory, and auto-memory; detects duplicates, outdated entries, conflicts, and ambiguous destination | local memory should distinguish durable reusable knowledge from transient/ambiguous notes | deterministic quality gate for `save_memory` | partial | Implement static gate now; defer review/promotion UI |
+| Session memory extraction | `/root/claude-code-haha/src/services/SessionMemory/sessionMemory.ts` extracts notes only after thresholds and natural boundaries, using isolated forked agent context | avoid hot-path over-saving and avoid low-value memory churn | no auto extraction in 12D | defer | Needs later background/side-agent capability |
+| Session memory prompt quality | `/root/claude-code-haha/src/services/SessionMemory/prompts.ts` preserves section structure, avoids note-taking leakage, keeps sections budgeted, and emphasizes current state/errors | memory content should stay structured and bounded | bounded recall plus simple quality categories | partial | Implement bounded deterministic local policy now |
+| Memory command UX | `/root/claude-code-haha/src/commands/memory/memory.tsx` opens explicit memory files for human editing | human review is important for memory quality | no local file editor now | defer | Outside 12D product scope |
+
+### Non-goals
+
+* Do not copy cc-haha's session-memory forked extraction agent.
+* Do not implement memory file editing or team memory sync.
+* Do not add LLM review/classification in this stage.
+
+### State boundary
+
+* Long-term memory: durable reusable facts/preferences/project conventions.
+* Session recovery: transcript/state/evidence/recovery brief from 12C.
+* Todo/task state: active work items and status; must not be saved as long-term memory.
+
+### Model-visible boundary
+
+The model still sees the `save_memory` tool, but the tool should reject low-value content with an explicit result rather than silently writing it.
+
+### LangChain boundary
+
+Use:
+
+* LangChain `@tool(..., args_schema=...)`
+* Pydantic schema validation for shape
+* LangGraph Store via `runtime.store`
+* deterministic pure functions for policy decisions
+
+Avoid:
+
+* custom memory runtime
+* background agent extraction
+* vector recall
+* prompt-only memory quality enforcement
+
+## Technical Approach
+
+Recommended minimal design:
+
+* Add `memory/policy.py` with `evaluate_memory_quality()`.
+* Keep the policy deterministic and conservative.
+* Update `memory/tools.py::save_memory()` to inspect existing namespace records and reject duplicates/transient entries before writing.
+* Update `memory/schemas.py` descriptions to make the model-visible quality rule clearer.
+* Add/extend tests in:
+  - `tests/test_memory.py`
+  - `tests/test_memory_integration.py`
+
+## Research Notes
+
+LangChain official docs note that long-term memory is stored in LangGraph stores as JSON documents organized by namespace and key, and tools can read/write through `runtime.store`. 12D should preserve this architecture and avoid replacing it with a custom memory runtime.
+
+Docs consulted:
+
+* `/oss/python/langchain/long-term-memory`
+* `/oss/python/concepts/memory`
+* `/oss/python/langgraph/add-memory`
+
+## Checkpoint: Stage 12D
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added `coding-deepgent/src/coding_deepgent/memory/policy.py` with deterministic `evaluate_memory_quality()`.
+- Exported the policy from `coding-deepgent/src/coding_deepgent/memory/__init__.py`.
+- Updated `coding-deepgent/src/coding_deepgent/memory/tools.py::save_memory()` to reject duplicate, transient task/session state, and trivially short low-value memory before writing to `runtime.store`.
+- Tightened the model-visible `SaveMemoryInput.content` description to distinguish durable reusable memory from current conversation/task/recovery notes.
+- Added focused unit/integration coverage for memory policy decisions, duplicate/transient rejection, rejected tool calls not writing to store, and bounded recall.
+
+Verification:
+- `pytest -q tests/test_memory.py tests/test_memory_integration.py tests/test_memory_context.py tests/test_app.py`
+- `pytest -q tests/test_context_payloads.py tests/test_message_projection.py tests/test_sessions.py tests/test_cli.py tests/test_memory.py tests/test_memory_integration.py tests/test_memory_context.py tests/test_app.py`
+- `ruff check src/coding_deepgent/memory/policy.py src/coding_deepgent/memory/schemas.py src/coding_deepgent/memory/tools.py src/coding_deepgent/memory/__init__.py tests/test_memory.py tests/test_memory_integration.py`
+- `mypy src/coding_deepgent/memory/policy.py src/coding_deepgent/memory/schemas.py src/coding_deepgent/memory/tools.py src/coding_deepgent/memory/__init__.py`
+
+cc-haha alignment:
+- Source files inspected:
+  - `/root/claude-code-haha/src/skills/bundled/remember.ts`
+  - `/root/claude-code-haha/src/services/SessionMemory/sessionMemory.ts`
+  - `/root/claude-code-haha/src/services/SessionMemory/prompts.ts`
+  - `/root/claude-code-haha/src/services/SessionMemory/sessionMemoryUtils.ts`
+  - `/root/claude-code-haha/src/commands/memory/memory.tsx`
+- Aligned:
+  - memory is treated as quality-controlled durable context, not a scratchpad.
+  - duplicate/transient memory pollution is rejected before future recall.
+  - memory remains separated from todo/session recovery state.
+- Deferred:
+  - background/session-memory extraction thresholds.
+  - forked memory extraction agent.
+  - memory file promotion/review UX.
+  - team memory sync.
+
+LangChain architecture:
+- Primitive used:
+  - LangChain tool with Pydantic args schema.
+  - LangGraph Store through `runtime.store`.
+  - deterministic pure policy function before `store.put`.
+- Why no heavier abstraction:
+  - 12D only needed a reusable quality gate; background extraction, vector indexing, or a separate memory runtime would be premature.
+
+Boundary findings:
+- New issue handled:
+  - exact duplicate content previously upserted silently and still returned "Saved memory"; the tool now reports rejection before write.
+- Residual risk:
+  - current policy is intentionally conservative and heuristic. It rejects obvious transient phrases only; nuanced stale/conflicting memory still needs a later review/promotion workflow.
+- Impact on next stage:
+  - Stage 12 planned sub-stages are now complete. Later memory automation can reuse this policy but should not bypass it.
+
+Decision:
+- continue
+
+Terminal note:
+- No next Stage 12 sub-stage remains; this `continue` maps to staged-run completion rather than starting a speculative 12E.
+
+Reason:
+- Verdict is APPROVE.
+- Tests, ruff, and mypy passed.
+- Stage 12A-12D planned sub-stages are complete and no additional 12E prerequisite was discovered.
diff --git a/.trellis/tasks/04-14-stage-12d-memory-quality-policy/task.json b/.trellis/tasks/04-14-stage-12d-memory-quality-policy/task.json
new file mode 100644
index 000000000..f73af9de1
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-12d-memory-quality-policy/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "04-14-stage-12d-memory-quality-policy",
+  "name": "04-14-stage-12d-memory-quality-policy",
+  "title": "Stage 12D: Memory Quality Policy",
+  "description": "",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-assess-cc-highlight-infrastructure-readiness",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/check.jsonl b/.trellis/tasks/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/check.jsonl
new file mode 100644
index 000000000..e2fb48dc1
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/check.jsonl
@@ -0,0 +1,4 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_message_projection.py", "reason": "projection artifact merge regression"}
+{"file": "coding-deepgent/tests/test_compact_artifacts.py", "reason": "new compact artifact tests"}
diff --git a/.trellis/tasks/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/debug.jsonl b/.trellis/tasks/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/implement.jsonl b/.trellis/tasks/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/implement.jsonl
new file mode 100644
index 000000000..fec80b194
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/implement.jsonl
@@ -0,0 +1,3 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/src/coding_deepgent/compact/artifacts.py", "reason": "new compact artifact helper"}
diff --git a/.trellis/tasks/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/prd.md b/.trellis/tasks/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/prd.md
new file mode 100644
index 000000000..f6c88278c
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/prd.md
@@ -0,0 +1,236 @@
+# Stage 13A: Manual Compact Boundary and Summary Artifact
+
+## Goal
+
+Add the first compact boundary and summary artifact primitive for `Stage 13 Context Compaction v1`, without introducing automatic compaction, live LLM summarization, or session-store deletion semantics yet.
+
+## Concrete Benefit
+
+* Context-efficiency: older conversation can be represented by an explicit summary artifact rather than an unbounded raw transcript.
+* Reliability: compaction has a model-visible boundary and preserves recent messages without silently splitting tool-use/tool-result pairs.
+* Maintainability: later manual CLI, auto-compact, and session-memory compact paths can reuse one deterministic artifact boundary.
+* Testability: compaction correctness can be tested without live model calls.
+
+## What I already know
+
+* Stage 12A added shared context payload rendering.
+* Stage 12B added deterministic message projection and prevented metadata/structured message corruption.
+* Stage 12C added recovery brief continuation context.
+* Stage 12D added memory quality policy.
+* Existing compact code has:
+  - `compact.budget.apply_tool_result_budget()`
+  - `compact.projection.project_messages()`
+* Current gap:
+  - no compact boundary marker
+  - no summary artifact message shape
+  - no deterministic compacted-history builder
+  - no tool-use/tool-result preservation when selecting a recent tail
+
+## Requirements
+
+* Add a deterministic manual compaction artifact builder.
+* Produce ordered post-compact messages:
+  - compact boundary marker
+  - compact summary message
+  - preserved recent messages
+* Preserve recent messages verbatim.
+* Avoid merging the summary artifact with adjacent user messages during projection.
+* Do not mutate input messages.
+* If preserved recent messages include tool results, expand the preserved window backward to include matching tool-use messages when present.
+* Add tests for:
+  - boundary + summary artifact order
+  - summary formatting
+  - non-mutating behavior
+  - projection does not merge compact summary into adjacent user message
+  - tool-use/tool-result pair preservation
+
+## Acceptance Criteria
+
+* [ ] A compact artifact helper exists under `coding_deepgent.compact`.
+* [ ] The helper is deterministic and has no live model dependency.
+* [ ] Summary artifacts are model-visible but structurally protected from accidental message merging.
+* [ ] Recent-window tool-use/tool-result pairing is preserved.
+* [ ] Focused compact tests pass.
+* [ ] Existing projection/app smoke tests still pass.
+
+## Definition of Done
+
+* Focused compact tests are added/updated.
+* No automatic compact middleware is introduced.
+* No session store rewrite/delete semantics are introduced.
+* No LLM summarization call is introduced.
+* Ruff and mypy pass on changed files.
+
+## Out of Scope
+
+* auto-compact thresholds
+* reactive prompt-too-long retry
+* forked summarizer / live LLM summary generation
+* session-memory-assisted compact
+* persisted compact transcript pruning
+* tool-result file persistence
+* post-compact file/skill/tool restoration attachments
+
+## cc-haha Alignment
+
+### Expected effect
+
+Aligning this behavior should improve context-efficiency, reliability, maintainability, testability, and long-session continuity.
+
+The local runtime effect is: compacted history has an explicit boundary + summary artifact and a preserved recent tail, so later compaction paths can reduce context without corrupting continuation semantics.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Boundary + summary ordering | `/root/claude-code-haha/src/services/compact/compact.ts::buildPostCompactMessages()` orders boundary marker, summary messages, preserved messages, attachments, hook results | local compacted history has a stable continuation boundary | boundary + summary + preserved tail | partial | Implement boundary/summary/tail only |
+| Summary prompt/output cleanup | `/root/claude-code-haha/src/services/compact/prompt.ts::formatCompactSummary()` strips `<analysis>` and unwraps `<summary>` | compact summary artifact is cleaner and avoids scratchpad leakage | deterministic `format_compact_summary()` | align | Implement now |
+| Recent tail preservation | `/root/claude-code-haha/src/services/compact/sessionMemoryCompact.ts::calculateMessagesToKeepIndex()` expands kept tail and avoids splitting API invariants | local tail selection does not orphan recent tool results | deterministic tail selector over dict messages | partial | Implement tool_use/tool_result pair protection now |
+| Full manual compact flow | `/root/claude-code-haha/src/services/compact/compact.ts::compactConversation()` runs hooks, forked/streaming summary, restores files/tools/skills, logs usage, writes transcript metadata | full manual compact product flow | none in 13A | defer | Needs later runtime/CLI integration |
+| Tool-result persistence | `/root/claude-code-haha/src/utils/toolResultStorage.ts` persists oversized tool results and leaves references | avoid losing large tool outputs | existing deterministic budget only | defer | Separate stage after artifact boundary |
+
+### Non-goals
+
+* Do not copy the full cc-haha query/runtime loop.
+* Do not run pre/post compact hooks yet.
+* Do not implement prompt-too-long retry.
+* Do not persist or delete transcript segments yet.
+* Do not add auto-compact.
+
+### State boundary
+
+* Compact artifact: model-visible continuation context.
+* Runtime session state: todos/recovery/memory state remain separate.
+* Transcript persistence: unchanged in 13A.
+
+### Model-visible boundary
+
+The model sees:
+
+* a compact boundary message
+* a compact summary message
+* preserved recent messages
+
+The model should not see:
+
+* `<analysis>` scratchpad output from the summarizer
+* internal artifact metadata as separate user requests
+* duplicate old compact boundaries from summarized history
+
+### LangChain Boundary
+
+Use:
+
+* normal LangChain message dictionaries
+* structured text content blocks to avoid accidental projection merges
+* deterministic pure helpers under `compact/`
+
+Avoid:
+
+* custom query runtime
+* replacing LangChain message/state model
+* automatic middleware before the artifact semantics are proven
+* LLM summarization until boundary tests pass
+
+## LangChain Docs Consulted
+
+* `/oss/python/langchain/short-term-memory`
+* `/oss/python/langchain/context-engineering`
+* `/oss/python/langgraph/add-memory`
+
+Relevant local decision:
+
+LangChain supports trim/delete/summarize strategies for short-term memory; summarization is lifecycle context that can persistently replace old messages while keeping recent messages. 13A only implements the deterministic artifact boundary needed before introducing that lifecycle behavior.
+
+## Technical Approach
+
+Recommended minimal design:
+
+* Add `compact/artifacts.py`.
+* Export the helper from `compact/__init__.py`.
+* Add `tests/test_compact_artifacts.py`.
+* Keep the helper pure:
+  - input: message dictionaries, manually supplied summary text, `keep_last`
+  - output: compact artifact metadata + post-compact messages
+* Use structured text blocks for boundary/summary content so `project_messages()` preserves the artifact boundary.
+
+## Research Notes
+
+Key cc-haha source inspected:
+
+* `/root/claude-code-haha/src/services/compact/compact.ts`
+* `/root/claude-code-haha/src/services/compact/sessionMemoryCompact.ts`
+* `/root/claude-code-haha/src/services/compact/prompt.ts`
+* `/root/claude-code-haha/src/services/compact/microCompact.ts`
+* `/root/claude-code-haha/src/utils/toolResultStorage.ts`
+
+## Checkpoint: Stage 13A
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added `coding-deepgent/src/coding_deepgent/compact/artifacts.py` with:
+  - `CompactArtifact`
+  - `compact_messages_with_summary()`
+  - compact boundary and summary message builders
+  - `format_compact_summary()`
+  - compact artifact detection
+- Exported compact artifact helpers from `coding-deepgent/src/coding_deepgent/compact/__init__.py`.
+- Added `coding-deepgent/tests/test_compact_artifacts.py` covering:
+  - boundary + summary + preserved-tail order
+  - `<analysis>` stripping and `<summary>` unwrapping
+  - non-mutating behavior
+  - projection-preserved structured summary artifacts
+  - tool-use/tool-result pair preservation when selecting the recent tail
+  - invalid input rejection
+
+Verification:
+- `pytest -q tests/test_compact_artifacts.py tests/test_message_projection.py tests/test_compact_budget.py tests/test_app.py`
+- `pytest -q tests/test_context_payloads.py tests/test_message_projection.py tests/test_compact_artifacts.py tests/test_compact_budget.py tests/test_sessions.py tests/test_cli.py tests/test_memory.py tests/test_memory_integration.py tests/test_memory_context.py tests/test_app.py`
+- `ruff check src/coding_deepgent/compact/artifacts.py src/coding_deepgent/compact/__init__.py tests/test_compact_artifacts.py`
+- `mypy src/coding_deepgent/compact/artifacts.py src/coding_deepgent/compact/__init__.py`
+
+cc-haha alignment:
+- Source files inspected:
+  - `/root/claude-code-haha/src/services/compact/compact.ts`
+  - `/root/claude-code-haha/src/services/compact/sessionMemoryCompact.ts`
+  - `/root/claude-code-haha/src/services/compact/prompt.ts`
+  - `/root/claude-code-haha/src/services/compact/microCompact.ts`
+  - `/root/claude-code-haha/src/utils/toolResultStorage.ts`
+- Aligned:
+  - post-compact message order starts with boundary and summary before preserved recent messages.
+  - compact summary formatting strips summarizer scratchpad and unwraps summary content.
+  - recent tail selection preserves tool-use/tool-result pairs when the kept tail includes a result.
+- Deferred:
+  - full manual compact flow with hooks and model summarization.
+  - auto-compact and reactive prompt-too-long recovery.
+  - session-memory-assisted compact.
+  - persisted transcript pruning and tool-result file references.
+
+LangChain architecture:
+- Primitive used:
+  - normal LangChain message dictionaries.
+  - structured text content blocks for artifact messages so Stage 12B projection does not merge the summary into adjacent user messages.
+  - pure deterministic helper functions under `compact/`.
+- Why no heavier abstraction:
+  - 13A only needed the artifact boundary; runtime middleware, CLI mutation, and LLM summary calls would widen the stage before invariants were proven.
+
+Boundary findings:
+- New issue handled:
+  - plain `role/content` compact summary messages would be merged into adjacent user messages by the Stage 12B projector; structured text blocks avoid that.
+- Residual risk:
+  - 13A does not persist compacted history or invoke a summarizer; it only builds the artifact shape that later runtime/CLI work can use.
+- Impact on next stage:
+  - 13B should wire this artifact into an explicit manual compact entry point, still avoiding auto-compact.
+
+Decision:
+- continue
+
+Reason:
+- Tests, ruff, and mypy passed.
+- Scope stayed inside deterministic compact artifact behavior.
+- The next sub-stage remains valid if constrained to explicit manual compact wiring rather than automatic compaction.
diff --git a/.trellis/tasks/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/task.json b/.trellis/tasks/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/task.json
new file mode 100644
index 000000000..2be13e261
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-13a-manual-compact-boundary-and-summary-artifact",
+  "name": "stage-13a-manual-compact-boundary-and-summary-artifact",
+  "title": "Stage 13A: Manual Compact Boundary and Summary Artifact",
+  "description": "",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/04-14-stage-13b-manual-compact-entry-point/check.jsonl b/.trellis/tasks/04-14-stage-13b-manual-compact-entry-point/check.jsonl
new file mode 100644
index 000000000..fdb73e361
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-13b-manual-compact-entry-point/check.jsonl
@@ -0,0 +1,3 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_cli.py", "reason": "CLI resume compact behavior"}
diff --git a/.trellis/tasks/04-14-stage-13b-manual-compact-entry-point/debug.jsonl b/.trellis/tasks/04-14-stage-13b-manual-compact-entry-point/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-13b-manual-compact-entry-point/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/04-14-stage-13b-manual-compact-entry-point/implement.jsonl b/.trellis/tasks/04-14-stage-13b-manual-compact-entry-point/implement.jsonl
new file mode 100644
index 000000000..9ec66270a
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-13b-manual-compact-entry-point/implement.jsonl
@@ -0,0 +1,5 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/src/coding_deepgent/cli_service.py", "reason": "manual compact continuation history service seam"}
+{"file": "coding-deepgent/src/coding_deepgent/compact/artifacts.py", "reason": "13A artifact source of truth"}
+{"file": "coding-deepgent/src/coding_deepgent/cli.py", "reason": "sessions resume compact CLI options"}
diff --git a/.trellis/tasks/04-14-stage-13b-manual-compact-entry-point/prd.md b/.trellis/tasks/04-14-stage-13b-manual-compact-entry-point/prd.md
new file mode 100644
index 000000000..96f17d122
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-13b-manual-compact-entry-point/prd.md
@@ -0,0 +1,153 @@
+# Stage 13B: Manual Compact Entry Point
+
+## Goal
+
+Wire the Stage 13A compact artifact into an explicit manual continuation entry point for session resume, while keeping compaction non-destructive and user-controlled.
+
+## Concrete Benefit
+
+* Context-efficiency: a resumed session can continue from a compact summary and recent tail instead of replaying the full loaded history.
+* Reliability: manual compact continuation still carries the Stage 12C recovery brief and preserves recent message invariants from 13A.
+* Maintainability: CLI/service wiring proves the artifact boundary without adding auto-compact or session-store rewrite semantics.
+
+## Requirements
+
+* Add an explicit manual compact continuation path.
+* Keep existing `sessions resume --prompt` behavior unchanged unless the user passes a compact summary option.
+* Support:
+  - user-provided compact summary text
+  - bounded recent tail count
+  - recovery brief context from Stage 12C
+* Reject compact options when no continuation prompt is provided.
+* Do not persist compacted history or delete transcript records in 13B.
+* Add focused CLI/service tests.
+
+## Acceptance Criteria
+
+* [ ] `sessions resume --prompt ... --compact-summary ...` uses compacted continuation history.
+* [ ] Recovery brief remains present in compacted continuation.
+* [ ] Compact boundary + summary artifact appear before preserved recent messages.
+* [ ] Existing non-compact resume behavior still passes.
+* [ ] Compact options without `--prompt` fail clearly.
+* [ ] Focused tests, ruff, and mypy pass.
+
+## Definition of Done
+
+* No auto-compact trigger is introduced.
+* No LLM summarization call is introduced.
+* No session transcript pruning or mutation is introduced.
+* Stage 13A artifact helpers remain the compaction source of truth.
+
+## Out of Scope
+
+* automatic token thresholds
+* prompt-too-long retry
+* live summarizer model call
+* session store compact records or delete semantics
+* post-compact restoration attachments
+* tool-result file persistence
+
+## cc-haha Alignment
+
+### Expected effect
+
+Aligning this behavior should improve context-efficiency, recoverability, and long-session continuity.
+
+The local runtime effect is: manual resume can continue from a compacted history with explicit compact boundary, summary, recovery brief, and preserved recent messages.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Manual compact path | `/root/claude-code-haha/src/services/compact/compact.ts::compactConversation()` creates boundary/summary and returns post-compact messages | local manual compact has a concrete continuation entry point | `sessions resume --prompt --compact-summary` | partial | Wire explicit manual path without LLM summarizer |
+| Post-compact ordering | `/root/claude-code-haha/src/services/compact/compact.ts::buildPostCompactMessages()` orders boundary, summary, kept messages, attachments, hooks | local continuation sees compact artifact before recent tail | reuse 13A artifact output | align | Implement now |
+| Recovery / transcript | cc-haha keeps transcript and metadata available for continuation | local resume still carries recovery brief and does not delete transcript | prepend Stage 12C recovery brief | partial | Preserve current session store |
+| Hooks/restoration | cc-haha executes pre/post compact hooks and restores context attachments | later full compact can restore files/tools/skills | none now | defer | Too wide for 13B |
+
+## LangChain Boundary
+
+Use:
+
+* normal message history continuation through existing `agent_loop`
+* existing CLI service seam
+* deterministic compact artifact helper from 13A
+
+Avoid:
+
+* custom query runtime
+* automatic `SummarizationMiddleware` before manual artifact behavior is validated
+* persistence changes before compacted transcript semantics are designed
+
+## Technical Approach
+
+* Add `cli_service.compacted_continuation_history()`.
+* Update `cli.py sessions resume` with:
+  - `--compact-summary`
+  - `--compact-keep-last`
+* Reject compact options without `--prompt`.
+* Update `tests/test_cli.py`.
+
+## Test Plan
+
+* CLI test for compacted resume history.
+* CLI test for compact option validation.
+* Existing resume tests remain unchanged.
+* Focused compact/projection/app smoke tests.
+
+## Checkpoint: Stage 13B
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added `cli_service.compacted_continuation_history()` to combine Stage 12C recovery brief with the Stage 13A compact artifact.
+- Added `sessions resume --prompt ... --compact-summary ... --compact-keep-last N`.
+- Preserved existing non-compact `sessions resume --prompt` behavior.
+- Rejected `--compact-summary` when `--prompt` is absent.
+- Added CLI coverage for compacted resume history and compact option validation.
+
+Verification:
+- `pytest -q tests/test_cli.py tests/test_compact_artifacts.py tests/test_message_projection.py tests/test_app.py`
+- `pytest -q tests/test_context_payloads.py tests/test_message_projection.py tests/test_compact_artifacts.py tests/test_compact_budget.py tests/test_sessions.py tests/test_cli.py tests/test_memory.py tests/test_memory_integration.py tests/test_memory_context.py tests/test_app.py`
+- `ruff check src/coding_deepgent/cli_service.py src/coding_deepgent/cli.py tests/test_cli.py`
+- `mypy src/coding_deepgent/cli_service.py src/coding_deepgent/cli.py`
+
+cc-haha alignment:
+- Source-backed intent came from:
+  - `/root/claude-code-haha/src/services/compact/compact.ts::compactConversation()`
+  - `/root/claude-code-haha/src/services/compact/compact.ts::buildPostCompactMessages()`
+  - `/root/claude-code-haha/src/services/compact/prompt.ts`
+- Aligned:
+  - manual compact continuation now has explicit compact summary + boundary + preserved tail.
+  - resume recovery context remains in the continuation path.
+- Deferred:
+  - model-generated summary.
+  - pre/post compact hooks.
+  - transcript pruning.
+  - auto/reactive compact.
+
+LangChain architecture:
+- Primitive used:
+  - existing CLI service seam and normal LangChain message history continuation.
+  - deterministic Stage 13A compact artifact helper.
+- Why no heavier abstraction:
+  - 13B only proves explicit manual wiring; automatic middleware and persistent state updates are later concerns.
+
+Boundary findings:
+- New issue handled:
+  - compact options without a continuation prompt would otherwise be ambiguous, so the CLI rejects them.
+- Residual risk:
+  - summary text is still supplied by the user; no local summarizer seam exists yet.
+- Impact on next stage:
+  - 13C should add a summary generation seam/prompt contract, still avoiding auto-compact.
+
+Decision:
+- continue
+
+Reason:
+- Tests, ruff, and mypy passed.
+- Scope stayed inside explicit manual compact entry point.
+- The next sub-stage is still valid if constrained to summary generation seam/prompt contract, not auto-compact.
diff --git a/.trellis/tasks/04-14-stage-13b-manual-compact-entry-point/task.json b/.trellis/tasks/04-14-stage-13b-manual-compact-entry-point/task.json
new file mode 100644
index 000000000..a26d5bccf
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-13b-manual-compact-entry-point/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-13b-manual-compact-entry-point",
+  "name": "stage-13b-manual-compact-entry-point",
+  "title": "Stage 13B: Manual Compact Entry Point",
+  "description": "",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/04-14-stage-13c-compact-summary-generation-seam/check.jsonl b/.trellis/tasks/04-14-stage-13c-compact-summary-generation-seam/check.jsonl
new file mode 100644
index 000000000..e76d52a08
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-13c-compact-summary-generation-seam/check.jsonl
@@ -0,0 +1,4 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_compact_artifacts.py", "reason": "existing summary formatting tests"}
+{"file": "coding-deepgent/tests/test_compact_summarizer.py", "reason": "compact summarizer seam tests"}
diff --git a/.trellis/tasks/04-14-stage-13c-compact-summary-generation-seam/debug.jsonl b/.trellis/tasks/04-14-stage-13c-compact-summary-generation-seam/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-13c-compact-summary-generation-seam/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/04-14-stage-13c-compact-summary-generation-seam/implement.jsonl b/.trellis/tasks/04-14-stage-13c-compact-summary-generation-seam/implement.jsonl
new file mode 100644
index 000000000..8213181f0
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-13c-compact-summary-generation-seam/implement.jsonl
@@ -0,0 +1,5 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/src/coding_deepgent/compact/artifacts.py", "reason": "summary formatter source of truth"}
+{"file": "coding-deepgent/src/coding_deepgent/compact/__init__.py", "reason": "compact public exports"}
+{"file": "coding-deepgent/src/coding_deepgent/compact/summarizer.py", "reason": "compact summary generation seam"}
diff --git a/.trellis/tasks/04-14-stage-13c-compact-summary-generation-seam/prd.md b/.trellis/tasks/04-14-stage-13c-compact-summary-generation-seam/prd.md
new file mode 100644
index 000000000..d2da07a45
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-13c-compact-summary-generation-seam/prd.md
@@ -0,0 +1,152 @@
+# Stage 13C: Compact Summary Generation Seam
+
+## Goal
+
+Add a compact summary generation seam and prompt contract that can later be wired to a real LangChain model, without introducing automatic compaction or live model calls in tests.
+
+## Concrete Benefit
+
+* Context-efficiency: manual compact no longer depends only on externally supplied summary text in future wiring.
+* Reliability: summary output formatting can be tested before runtime integration.
+* Maintainability: summarization prompt construction and model invocation are isolated from CLI/session/auto-compact code.
+
+## Requirements
+
+* Add a deterministic prompt builder for compact summarization.
+* Add a generation seam that accepts a summarizer object/callable and message dictionaries.
+* Strip `<analysis>` and unwrap `<summary>` using the Stage 13A formatter.
+* Keep the seam testable with fake summarizers.
+* Do not call live models in tests.
+* Do not introduce auto-compact or runtime middleware.
+
+## Acceptance Criteria
+
+* [ ] A compact summarizer seam exists under `coding_deepgent.compact`.
+* [ ] The summarizer receives original messages plus one compact prompt message.
+* [ ] Summary output is formatted through `format_compact_summary()`.
+* [ ] Empty summary output is rejected.
+* [ ] Focused tests, ruff, and mypy pass.
+
+## Out of Scope
+
+* live OpenAI/LangChain model selection
+* CLI summary generation option
+* auto-compact thresholding
+* SummarizationMiddleware integration
+* transcript pruning
+* prompt-too-long retry
+
+## cc-haha Alignment
+
+### Expected effect
+
+Aligning this behavior should improve reliability, context-efficiency, and maintainability.
+
+The local runtime effect is: compact summary generation gets a dedicated prompt/model seam that preserves cc-haha's “text-only summary, strip analysis scratchpad” intent without copying the full compact runtime.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Compact prompt | `/root/claude-code-haha/src/services/compact/prompt.ts::getCompactPrompt()` requires text-only summary and analysis/summary structure | generated summaries are structured and cleanly post-processed | local compact prompt builder | partial | Implement concise prompt contract |
+| Summary formatting | `/root/claude-code-haha/src/services/compact/prompt.ts::formatCompactSummary()` strips `<analysis>` and unwraps `<summary>` | no scratchpad leaks into compact artifact | reuse 13A formatter | align | Implement through seam |
+| Model invocation | `/root/claude-code-haha/src/services/compact/compact.ts::streamCompactSummary()` invokes a forked/streaming summary path | local code has a replaceable model seam | fakeable summarizer protocol | partial | Implement seam only |
+| Retry and hooks | cc-haha handles prompt-too-long retry, hooks, restoration, telemetry | robust production compact | none now | defer | Requires later runtime stage |
+
+## LangChain Boundary
+
+Use:
+
+* normal message dictionaries as model input
+* a summarizer object with `invoke()` or a callable seam
+* existing Stage 13A summary formatter
+
+Avoid:
+
+* custom query loop
+* direct provider SDK use
+* live model calls in tests
+* automatic middleware before manual seam is proven
+
+## Technical Approach
+
+* Add `compact/summarizer.py`.
+* Export prompt/seam helpers from `compact/__init__.py`.
+* Add `tests/test_compact_summarizer.py`.
+* Keep all behavior pure/fakeable.
+
+## Test Plan
+
+* Fake summarizer receives original messages + prompt message.
+* `<analysis>` output is stripped.
+* `<summary>` content is unwrapped.
+* blank summarizer output raises a clear error.
+
+## Checkpoint: Stage 13C
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added `coding-deepgent/src/coding_deepgent/compact/summarizer.py` with:
+  - `COMPACT_SUMMARY_PROMPT`
+  - `build_compact_summary_prompt()`
+  - `build_compact_summary_request()`
+  - `generate_compact_summary()`
+- Exported summarizer seam helpers from `coding-deepgent/src/coding_deepgent/compact/__init__.py`.
+- Added `coding-deepgent/tests/test_compact_summarizer.py` covering:
+  - prompt appending without mutating source messages
+  - fake `.invoke()` summarizer support
+  - callable summarizer support
+  - `<analysis>` stripping and `<summary>` unwrapping
+  - empty summary rejection
+
+Verification:
+- `pytest -q tests/test_compact_summarizer.py tests/test_compact_artifacts.py tests/test_message_projection.py tests/test_app.py`
+- `pytest -q tests/test_context_payloads.py tests/test_message_projection.py tests/test_compact_artifacts.py tests/test_compact_summarizer.py tests/test_compact_budget.py tests/test_sessions.py tests/test_cli.py tests/test_memory.py tests/test_memory_integration.py tests/test_memory_context.py tests/test_app.py`
+- `ruff check src/coding_deepgent/compact/summarizer.py src/coding_deepgent/compact/__init__.py tests/test_compact_summarizer.py`
+- `mypy src/coding_deepgent/compact/summarizer.py src/coding_deepgent/compact/__init__.py`
+
+cc-haha alignment:
+- Source-backed intent came from:
+  - `/root/claude-code-haha/src/services/compact/prompt.ts::getCompactPrompt()`
+  - `/root/claude-code-haha/src/services/compact/prompt.ts::formatCompactSummary()`
+  - `/root/claude-code-haha/src/services/compact/compact.ts::streamCompactSummary()`
+- Aligned:
+  - compact summary prompt asks for a text-only analysis/summary shape.
+  - summary output is formatted through the same scratchpad-stripping boundary as 13A.
+  - model invocation is isolated behind a fakeable summarizer seam.
+- Deferred:
+  - forked/streaming summarizer runtime.
+  - live model selection.
+  - auto-compact and prompt-too-long retry.
+  - CLI-generated summary option.
+
+LangChain architecture:
+- Primitive used:
+  - normal message dictionaries as summarizer input.
+  - `.invoke()` or callable seam, compatible with LangChain-style model invocation and fake test doubles.
+- Why no heavier abstraction:
+  - 13C only needed the generation seam; wiring a live model or `SummarizationMiddleware` changes runtime behavior and should be planned separately.
+
+Boundary findings:
+- New issue handled:
+  - compact summary generation needed its own prompt/request builder instead of being hidden inside CLI/session code.
+- Residual risk:
+  - no live summarizer wiring exists yet; manual compact can use user-supplied summaries, and generated summaries can be unit-tested through fake summarizers.
+- Impact on next stage:
+  - next safe work should be planned explicitly as either generated-summary CLI wiring, LangChain `SummarizationMiddleware` integration, or auto/reactive compact. These are separate product choices.
+
+Decision:
+- continue
+
+Terminal note:
+- Stage 13 v1 manual compact foundation is complete through 13A-13C. No further sub-stage should be started automatically without choosing the next compaction product path.
+
+Reason:
+- Tests, ruff, and mypy passed.
+- The Stage 13 v1 scope now has boundary artifact, manual resume entry point, and summary generation seam.
+- The next candidates would widen runtime behavior beyond the current approved v1 slice.
diff --git a/.trellis/tasks/04-14-stage-13c-compact-summary-generation-seam/task.json b/.trellis/tasks/04-14-stage-13c-compact-summary-generation-seam/task.json
new file mode 100644
index 000000000..b32b236f3
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-13c-compact-summary-generation-seam/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-13c-compact-summary-generation-seam",
+  "name": "stage-13c-compact-summary-generation-seam",
+  "title": "Stage 13C: Compact Summary Generation Seam",
+  "description": "",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/04-14-stage-14a-explicit-generated-summary-cli-wiring/check.jsonl b/.trellis/tasks/04-14-stage-14a-explicit-generated-summary-cli-wiring/check.jsonl
new file mode 100644
index 000000000..e9f2c41fb
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-14a-explicit-generated-summary-cli-wiring/check.jsonl
@@ -0,0 +1,3 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_cli.py", "reason": "generated compact CLI tests"}
diff --git a/.trellis/tasks/04-14-stage-14a-explicit-generated-summary-cli-wiring/debug.jsonl b/.trellis/tasks/04-14-stage-14a-explicit-generated-summary-cli-wiring/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-14a-explicit-generated-summary-cli-wiring/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/04-14-stage-14a-explicit-generated-summary-cli-wiring/implement.jsonl b/.trellis/tasks/04-14-stage-14a-explicit-generated-summary-cli-wiring/implement.jsonl
new file mode 100644
index 000000000..ca3bb53fa
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-14a-explicit-generated-summary-cli-wiring/implement.jsonl
@@ -0,0 +1,5 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/src/coding_deepgent/cli_service.py", "reason": "generated compact continuation service seam"}
+{"file": "coding-deepgent/src/coding_deepgent/compact/summarizer.py", "reason": "Stage 13C summarizer seam source of truth"}
+{"file": "coding-deepgent/src/coding_deepgent/cli.py", "reason": "generated compact summary CLI option"}
diff --git a/.trellis/tasks/04-14-stage-14a-explicit-generated-summary-cli-wiring/prd.md b/.trellis/tasks/04-14-stage-14a-explicit-generated-summary-cli-wiring/prd.md
new file mode 100644
index 000000000..3d894f6fa
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-14a-explicit-generated-summary-cli-wiring/prd.md
@@ -0,0 +1,178 @@
+# Stage 14A: Explicit Generated Summary CLI Wiring
+
+## Goal
+
+Wire the Stage 13C compact summarizer seam into an explicit user-triggered CLI path so a resumed session can generate a compact summary and continue from a compacted history.
+
+## Concrete Benefit
+
+* Context-efficiency: users no longer have to hand-write `--compact-summary` to reduce resume context.
+* Reliability: generated summaries still pass through the Stage 13C formatter and Stage 13A compact artifact boundary.
+* Maintainability: live model wiring remains isolated in CLI/service seams and does not introduce auto-compact or transcript pruning.
+
+## Requirements
+
+* Add an explicit CLI option for generated manual compact summary.
+* Keep existing `--compact-summary` behavior unchanged.
+* Reject using user-supplied summary and generated summary together.
+* Reject generated summary without `--prompt`.
+* Use Stage 13C `generate_compact_summary()` seam.
+* Reuse Stage 13B `compacted_continuation_history()`.
+* Keep compaction user-triggered only.
+* Do not mutate session transcript or state beyond the normal continuation prompt recording.
+* Add tests with fake summarizers / monkeypatching; no live model tests.
+
+## Acceptance Criteria
+
+* [ ] `sessions resume --prompt ... --generate-compact-summary` generates summary through the compact seam and uses compacted continuation history.
+* [ ] `--compact-summary` and `--generate-compact-summary` are mutually exclusive.
+* [ ] `--generate-compact-summary` without `--prompt` fails clearly and does not call the run path.
+* [ ] Optional compact instructions are passed to the summarizer seam.
+* [ ] Focused CLI/compact tests pass.
+* [ ] Ruff and mypy pass on changed files.
+
+## Definition of Done
+
+* No auto-compact trigger is introduced.
+* No transcript pruning is introduced.
+* No prompt-too-long retry is introduced.
+* No LangChain `SummarizationMiddleware` is introduced.
+* No live LLM tests are introduced.
+
+## Out of Scope
+
+* automatic token thresholds
+* reactive compact
+* prompt-too-long retry
+* transcript compact records / delete semantics
+* pre/post compact hooks
+* post-compact file/skill/tool restoration
+* background session memory extraction
+
+## cc-haha Alignment
+
+### Expected effect
+
+Aligning this behavior should improve context-efficiency, long-session continuity, and product parity.
+
+The local runtime effect is: a user can explicitly request a generated compact summary for resume continuation, while the implementation still preserves LangChain-native message history and avoids automatic runtime behavior.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Compact prompt | `/root/claude-code-haha/src/services/compact/prompt.ts::getCompactPrompt()` uses strict text-only compact instructions and summary formatting | generated summaries follow a stable contract | Stage 13C prompt/seam | partial | Reuse local seam |
+| Summary invocation | `/root/claude-code-haha/src/services/compact/compact.ts::streamCompactSummary()` invokes a summarizer with conversation messages + compact prompt | manual compact can generate summary instead of requiring user text | explicit CLI generated summary path | partial | Implement user-triggered path only |
+| Post-compact artifact | `/root/claude-code-haha/src/services/compact/compact.ts::buildPostCompactMessages()` returns boundary/summary/recent messages | compacted continuation has stable boundary and recent tail | Stage 13A/13B compacted continuation | align | Reuse existing helper |
+| Prompt-too-long retry | `compactConversation()` retries compaction after prompt-too-long by dropping old message groups | robust fallback if summary request is too large | none | defer | Explicitly out of scope |
+| Auto compact | cc-haha auto/micro/reactive compact paths | proactive context pressure management | none | defer | Later stage |
+
+## LangChain Boundary
+
+Use:
+
+* Stage 13C fakeable summarizer seam.
+* Normal `.invoke()` model interface for live use.
+* Existing message dictionaries and CLI service boundary.
+
+Avoid:
+
+* LangChain `SummarizationMiddleware` because it persists/replaces state automatically.
+* Custom query runtime.
+* Automatic background compaction.
+* Provider-specific retry/cache code.
+
+## LangChain Docs Consulted
+
+* `/oss/python/langchain/short-term-memory`
+* `/oss/python/langchain/context-engineering`
+* `/oss/python/langgraph/add-memory`
+
+Local decision:
+
+LangChain summarization middleware is appropriate for later persistent lifecycle summarization, but 14A is an explicit CLI continuation path. Therefore use the existing fakeable summarizer seam instead of adding middleware.
+
+## Technical Approach
+
+* Add `cli_service.generated_compacted_continuation_history()`.
+* Add CLI options:
+  - `--generate-compact-summary`
+  - `--compact-instructions`
+* In CLI, call `build_openai_model()` only when the generated summary flag is explicitly present.
+* Preserve `--compact-summary` for user-provided summaries.
+* Add focused CLI tests that monkeypatch `build_openai_model()`.
+
+## Test Plan
+
+* Generated compact summary path uses fake summarizer and compacted history.
+* Generated compact summary and manual summary conflict test.
+* Generated summary without prompt test.
+* Compact instructions passed to fake summarizer.
+* Existing manual summary and non-compact resume tests still pass.
+
+## Checkpoint: Stage 14A
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added `cli_service.generated_compacted_continuation_history()` to generate a compact summary through the Stage 13C summarizer seam and then reuse Stage 13B compacted continuation history.
+- Added explicit CLI options to `sessions resume`:
+  - `--generate-compact-summary`
+  - `--compact-instructions`
+- Preserved existing `--compact-summary` behavior for user-provided summaries.
+- Added validation:
+  - compact options require `--prompt`
+  - `--compact-summary` and `--generate-compact-summary` are mutually exclusive
+  - `--compact-instructions` requires `--generate-compact-summary`
+- Added fake-summarizer CLI tests; no live LLM tests were introduced.
+
+Verification:
+- `pytest -q tests/test_cli.py tests/test_compact_summarizer.py tests/test_compact_artifacts.py tests/test_app.py`
+- `pytest -q tests/test_context_payloads.py tests/test_message_projection.py tests/test_compact_artifacts.py tests/test_compact_summarizer.py tests/test_compact_budget.py tests/test_sessions.py tests/test_cli.py tests/test_memory.py tests/test_memory_integration.py tests/test_memory_context.py tests/test_app.py`
+- `ruff check src/coding_deepgent/cli_service.py src/coding_deepgent/cli.py tests/test_cli.py`
+- `mypy src/coding_deepgent/cli_service.py src/coding_deepgent/cli.py`
+
+cc-haha alignment:
+- Source files inspected:
+  - `/root/claude-code-haha/src/services/compact/prompt.ts`
+  - `/root/claude-code-haha/src/services/compact/compact.ts`
+- Aligned:
+  - user-triggered compact can now call a summarizer over conversation history plus a compact prompt.
+  - generated summary is formatted through the same `<analysis>` stripping and `<summary>` unwrapping contract.
+  - post-summary continuation reuses compact boundary + summary + preserved tail.
+- Deferred:
+  - stream/fork summarizer runtime.
+  - prompt-too-long retry.
+  - pre/post compact hooks.
+  - auto/reactive compact.
+  - transcript pruning.
+
+LangChain architecture:
+- Primitive used:
+  - normal `.invoke()`-style summarizer seam via Stage 13C.
+  - existing CLI/service boundaries and normal message history continuation.
+- Why no heavier abstraction:
+  - LangChain `SummarizationMiddleware` persists/replaces state automatically; 14A is explicit CLI continuation and intentionally non-destructive.
+
+Boundary findings:
+- New issue handled:
+  - `--compact-instructions` without generated compact summary would otherwise be ambiguous, so it is rejected.
+- Residual risk:
+  - live summarizer quality and prompt-too-long handling are not covered yet; this stage only wires the explicit generated-summary path.
+- Impact on next stage:
+  - Next work should be explicitly chosen as either live/manual smoke coverage, persistent compact transcript semantics, or auto/reactive compact. These should not be silently bundled into 14A.
+
+Decision:
+- continue
+
+Terminal note:
+- Stage 14A completes the requested generated manual compact slice. No further sub-stage is started automatically because the next options widen product behavior beyond the current explicit user-triggered scope.
+
+Reason:
+- Tests, ruff, and mypy passed.
+- Scope stayed inside explicit generated manual compact wiring.
+- No auto-compact, transcript pruning, prompt-too-long retry, or live LLM tests were introduced.
diff --git a/.trellis/tasks/04-14-stage-14a-explicit-generated-summary-cli-wiring/task.json b/.trellis/tasks/04-14-stage-14a-explicit-generated-summary-cli-wiring/task.json
new file mode 100644
index 000000000..d50ce4d17
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-14a-explicit-generated-summary-cli-wiring/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-14a-explicit-generated-summary-cli-wiring",
+  "name": "stage-14a-explicit-generated-summary-cli-wiring",
+  "title": "Stage 14A: Explicit Generated Summary CLI Wiring",
+  "description": "",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/04-14-stage-15a-non-destructive-compact-transcript-records/check.jsonl b/.trellis/tasks/04-14-stage-15a-non-destructive-compact-transcript-records/check.jsonl
new file mode 100644
index 000000000..8a395c3ad
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-15a-non-destructive-compact-transcript-records/check.jsonl
@@ -0,0 +1,5 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_sessions.py", "reason": "compact record persistence tests"}
+{"file": "coding-deepgent/tests/test_cli.py", "reason": "compacted continuation recording tests"}
+{"file": "coding-deepgent/tests/test_compact_artifacts.py", "reason": "compact artifact metadata tests"}
diff --git a/.trellis/tasks/04-14-stage-15a-non-destructive-compact-transcript-records/debug.jsonl b/.trellis/tasks/04-14-stage-15a-non-destructive-compact-transcript-records/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-15a-non-destructive-compact-transcript-records/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/04-14-stage-15a-non-destructive-compact-transcript-records/implement.jsonl b/.trellis/tasks/04-14-stage-15a-non-destructive-compact-transcript-records/implement.jsonl
new file mode 100644
index 000000000..0ae783b3c
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-15a-non-destructive-compact-transcript-records/implement.jsonl
@@ -0,0 +1,6 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/src/coding_deepgent/sessions/records.py", "reason": "compact transcript record schema"}
+{"file": "coding-deepgent/src/coding_deepgent/sessions/service.py", "reason": "record compact metadata during CLI continuation"}
+{"file": "coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py", "reason": "compact transcript append/load behavior"}
+{"file": "coding-deepgent/src/coding_deepgent/compact/artifacts.py", "reason": "compact artifact metadata source"}
diff --git a/.trellis/tasks/04-14-stage-15a-non-destructive-compact-transcript-records/prd.md b/.trellis/tasks/04-14-stage-15a-non-destructive-compact-transcript-records/prd.md
new file mode 100644
index 000000000..1b8be1ba6
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-15a-non-destructive-compact-transcript-records/prd.md
@@ -0,0 +1,183 @@
+# Stage 15A: Non-Destructive Compact Transcript Records
+
+## Goal
+
+Add append-only compact transcript records so manual compaction events are durably visible in the session JSONL without deleting, pruning, or rewriting original transcript messages.
+
+## Concrete Benefit
+
+* Recoverability: future resume/audit flows can tell that a compacted continuation happened and inspect the compact summary.
+* Safety: compact persistence does not mutate or delete the raw transcript.
+* Testability: compact transcript semantics are deterministic and covered before any auto/reactive compact work.
+
+## Requirements
+
+* Add a `compact` JSONL record type.
+* Load compact records into `LoadedSession` separately from `history`.
+* Add `compact_count` to `SessionSummary`.
+* Preserve current `history` behavior: compact records must not appear as user/assistant messages.
+* Preserve state snapshot behavior.
+* When `run_prompt_with_recording()` receives synthetic compact artifact messages, append one compact record before recording the continuation prompt.
+* Do not persist synthetic resume context or compact artifact messages as normal message records.
+* Do not delete, prune, or rewrite transcript records.
+
+## Acceptance Criteria
+
+* [ ] `JsonlSessionStore.append_compact()` appends a valid compact JSONL record.
+* [ ] `load_session()` returns compact records separately as `loaded.compacts`.
+* [ ] `loaded.history` remains only real user/assistant message records.
+* [ ] `loaded.summary.compact_count` reflects valid compact records.
+* [ ] Invalid/foreign compact records are ignored.
+* [ ] A compacted CLI continuation records a compact record without skewing message indexes.
+* [ ] Focused tests, ruff, and mypy pass.
+
+## Out of Scope
+
+* auto-compact
+* prompt-too-long retry
+* transcript deletion/pruning
+* replacing loaded history with compact summary on resume
+* post-compact file/skill/tool restoration
+* live LLM summarizer tests
+
+## cc-haha Alignment
+
+### Expected effect
+
+Aligning this behavior should improve recoverability, auditability, and long-session continuity.
+
+The local runtime effect is: compact events become durable transcript metadata, while the raw session transcript remains intact and reloadable.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Compact boundary metadata | `/root/claude-code-haha/src/services/compact/compact.ts` creates compact boundary and summary messages before returning post-compact messages | compacted continuation has durable boundary/summary information | append-only `compact` JSONL record | partial | Implement record now |
+| Transcript metadata continuity | `/root/claude-code-haha/src/services/compact/compact.ts` re-appends session metadata around compaction so resume display can recover context | local sessions can audit compact events later | `LoadedSession.compacts` and `SessionSummary.compact_count` | partial | Implement now |
+| Transcript pruning | `/root/claude-code-haha/src/utils/sessionStorage.ts` has compact-boundary-aware loading/pruning/relinking logic | old messages may be skipped after a boundary | none now | defer | Explicitly out of scope |
+| Tool-result/file restoration | cc-haha restores attachments/files/skills after compaction | richer post-compact context | none now | defer | Later stage |
+
+## LangChain Boundary
+
+Use:
+
+* existing session JSONL store seam
+* normal LangChain message history continuation
+* compact artifact metadata from Stage 13
+
+Avoid:
+
+* LangChain `SummarizationMiddleware`
+* automatic state replacement
+* transcript deletion or `RemoveMessage`
+* provider-specific retry/cache code
+
+## LangChain Docs Consulted
+
+* `/oss/python/langchain/short-term-memory`
+* `/oss/python/langchain/context-engineering`
+* `/oss/python/langgraph/add-memory`
+
+Local decision:
+
+LangChain summarization can persistently replace old messages, but 15A is append-only transcript metadata. Persistent state replacement and automatic summarization remain deferred.
+
+## Technical Approach
+
+* Extend `sessions/records.py` with:
+  - `COMPACT_RECORD_TYPE`
+  - `SessionCompact`
+  - `make_compact_record()`
+* Extend `JsonlSessionStore` with:
+  - `append_compact()`
+  - `_coerce_compact()`
+  - `LoadedSession.compacts`
+  - `SessionSummary.compact_count`
+* Extend Stage 13 compact artifact messages with compact metadata so `sessions.service` can detect compacted continuations.
+* Update `run_prompt_with_recording()` to append a compact record once when compact metadata is present in synthetic history.
+* Extend tests in:
+  - `tests/test_sessions.py`
+  - `tests/test_cli.py`
+  - `tests/test_compact_artifacts.py`
+
+## Test Plan
+
+* Compact record roundtrip and history separation.
+* Invalid compact records ignored.
+* Compacted continuation writes compact record and preserves real message indexes.
+* Existing Stage 13/14 compact tests still pass.
+
+## Checkpoint: Stage 15A
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added append-only compact transcript records:
+  - `COMPACT_RECORD_TYPE = "compact"`
+  - `SessionCompact`
+  - `make_compact_record()`
+  - `JsonlSessionStore.append_compact()`
+- Extended session loading:
+  - `LoadedSession.compacts`
+  - `SessionSummary.compact_count`
+  - invalid/foreign compact records are ignored
+  - compact records do not enter `LoadedSession.history`
+- Extended compact artifact messages with `coding_deepgent_compact` metadata for boundary and summary messages.
+- Added `compact_record_from_messages()` so `sessions.service.run_prompt_with_recording()` can detect synthetic compacted histories.
+- Updated `run_prompt_with_recording()` to append one compact record before recording the continuation user prompt when compact artifact metadata is present.
+- Fixed compacted continuation `message_index` baseline to use compact `original_message_count`, not the reduced preserved-tail message count.
+- Updated backend code-spec with compact transcript record contracts.
+
+Verification:
+- `pytest -q tests/test_sessions.py tests/test_cli.py tests/test_compact_artifacts.py tests/test_compact_summarizer.py tests/test_message_projection.py`
+- `pytest -q tests/test_context_payloads.py tests/test_message_projection.py tests/test_compact_artifacts.py tests/test_compact_summarizer.py tests/test_compact_budget.py tests/test_sessions.py tests/test_cli.py tests/test_memory.py tests/test_memory_integration.py tests/test_memory_context.py tests/test_app.py`
+- `pytest -q`
+- `ruff check src/coding_deepgent/compact/artifacts.py src/coding_deepgent/compact/__init__.py src/coding_deepgent/sessions/records.py src/coding_deepgent/sessions/store_jsonl.py src/coding_deepgent/sessions/__init__.py src/coding_deepgent/sessions/ports.py src/coding_deepgent/sessions/service.py tests/test_sessions.py tests/test_cli.py tests/test_compact_artifacts.py`
+- `mypy src/coding_deepgent/compact/artifacts.py src/coding_deepgent/compact/__init__.py src/coding_deepgent/sessions/records.py src/coding_deepgent/sessions/store_jsonl.py src/coding_deepgent/sessions/__init__.py src/coding_deepgent/sessions/ports.py src/coding_deepgent/sessions/service.py`
+
+cc-haha alignment:
+- Source files inspected:
+  - `/root/claude-code-haha/src/services/compact/compact.ts`
+  - `/root/claude-code-haha/src/utils/sessionStorage.ts`
+  - `/root/claude-code-haha/src/utils/sessionStoragePortable.ts`
+  - `/root/claude-code-haha/src/utils/messages.ts`
+- Aligned:
+  - compact events now have durable boundary/summary metadata.
+  - compact persistence is separated from normal user/assistant transcript messages.
+  - real message indexing is preserved across compacted continuation.
+- Deferred:
+  - compact-boundary-aware transcript pruning/relinking.
+  - prompt-too-long retry.
+  - auto/reactive compact.
+  - post-compact context restoration attachments.
+
+LangChain architecture:
+- Primitive used:
+  - normal message dictionaries remain the continuation path.
+  - session JSONL store remains the durability seam.
+  - no `SummarizationMiddleware`, no `RemoveMessage`, and no graph state replacement were introduced.
+- Why no heavier abstraction:
+  - 15A only persists compact metadata; destructive history rewriting and automatic lifecycle summarization are separate behavior changes.
+
+Boundary findings:
+- New issue handled:
+  - compacted histories preserve only a recent tail, so persisted continuation `message_index` must use compact `original_message_count`.
+- Residual risk:
+  - `load_session()` records compact events but does not yet use them to alter resume context or display compact history. This is intentional for non-destructive 15A.
+- Impact on next stage:
+  - Next work should be explicitly selected: compact record display/recovery use, compact transcript pruning semantics, or auto/reactive compact. These should not be bundled silently.
+
+Decision:
+- continue
+
+Terminal note:
+- Stage 15A is complete. No further Stage 15 sub-stage is started automatically because the next options materially change resume or transcript behavior and need an explicit product choice.
+
+Reason:
+- Tests, ruff, and mypy passed.
+- Scope stayed inside append-only compact transcript records.
+- No auto-compact, prompt-too-long retry, transcript deletion, or transcript pruning was introduced.
diff --git a/.trellis/tasks/04-14-stage-15a-non-destructive-compact-transcript-records/task.json b/.trellis/tasks/04-14-stage-15a-non-destructive-compact-transcript-records/task.json
new file mode 100644
index 000000000..396ec5087
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-15a-non-destructive-compact-transcript-records/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-15a-non-destructive-compact-transcript-records",
+  "name": "stage-15a-non-destructive-compact-transcript-records",
+  "title": "Stage 15A: Non-Destructive Compact Transcript Records",
+  "description": "",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/04-14-stage-15b-compact-record-recovery-display/check.jsonl b/.trellis/tasks/04-14-stage-15b-compact-record-recovery-display/check.jsonl
new file mode 100644
index 000000000..1d5ce37d3
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-15b-compact-record-recovery-display/check.jsonl
@@ -0,0 +1,4 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_sessions.py", "reason": "recovery brief compact tests"}
+{"file": "coding-deepgent/tests/test_cli.py", "reason": "resume display compact tests"}
diff --git a/.trellis/tasks/04-14-stage-15b-compact-record-recovery-display/debug.jsonl b/.trellis/tasks/04-14-stage-15b-compact-record-recovery-display/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-15b-compact-record-recovery-display/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/04-14-stage-15b-compact-record-recovery-display/implement.jsonl b/.trellis/tasks/04-14-stage-15b-compact-record-recovery-display/implement.jsonl
new file mode 100644
index 000000000..a1e9d5c3b
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-15b-compact-record-recovery-display/implement.jsonl
@@ -0,0 +1,3 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/src/coding_deepgent/sessions/resume.py", "reason": "recovery brief compact display"}
diff --git a/.trellis/tasks/04-14-stage-15b-compact-record-recovery-display/prd.md b/.trellis/tasks/04-14-stage-15b-compact-record-recovery-display/prd.md
new file mode 100644
index 000000000..62bac73f6
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-15b-compact-record-recovery-display/prd.md
@@ -0,0 +1,126 @@
+# Stage 15B: Compact Record Recovery Display
+
+## Goal
+
+Expose the latest compact transcript records in recovery brief rendering and resume display, without changing continuation selection semantics.
+
+## Concrete Benefit
+
+* Recoverability: users can see that a session has already been compacted and what the latest compact summary says.
+* Auditability: compact transcript records become visible product behavior rather than hidden JSONL metadata.
+* Continuity: later stages can use the same compact summary display surface without yet changing resume selection.
+
+## Requirements
+
+* Extend recovery brief to include recent compact summaries.
+* Keep compact display bounded.
+* Do not add compact summaries to `LoadedSession.history`.
+* Do not change `continuation_history()` or `compacted_continuation_history()` semantics in 15B.
+* Update resume context message output to reflect the enhanced recovery brief.
+* Add focused session/CLI tests.
+
+## Acceptance Criteria
+
+* [ ] `build_recovery_brief()` includes recent compact records in a separate field.
+* [ ] `render_recovery_brief()` renders a compact section.
+* [ ] `sessions resume <id>` without `--prompt` shows recent compact summary when available.
+* [ ] resume-with-prompt still uses the same history semantics as before.
+* [ ] Focused tests, ruff, and mypy pass.
+
+## Out of Scope
+
+* using compact summary instead of history for continuation
+* transcript pruning/deletion
+* auto-compact
+* prompt-too-long retry
+* changing message index behavior
+
+## cc-haha Alignment
+
+### Expected effect
+
+Aligning this behavior should improve recoverability, auditability, and long-session continuity.
+
+The local runtime effect is: compact metadata becomes user-visible during resume/recovery, similar to how cc-haha keeps compact/session metadata recoverable around transcript boundaries.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Pre/post compact metadata continuity | `/root/claude-code-haha/src/utils/sessionStorage.ts` preserves metadata around compact boundaries so resume paths can still recover state | local resume display should expose compact information, not just raw chat/evidence | recovery brief compact section | partial | Implement now |
+| Compact boundary visibility | `/root/claude-code-haha/src/services/compact/compact.ts` emits boundary + summary before post-compact continuation | local operator can inspect latest compact summary at resume time | render latest compact summaries in recovery brief | partial | Implement now |
+| Continuation semantics | cc-haha later uses compact-boundary-aware loading logic | local continuation can evolve later | none now | defer | 15C decides continuation selection |
+
+## LangChain Boundary
+
+Use:
+
+* existing session JSONL durability
+* existing recovery brief builder/render path
+* append-only compact records from 15A
+
+Avoid:
+
+* `SummarizationMiddleware`
+* `RemoveMessage`
+* transcript pruning
+* changing runtime message history in this sub-stage
+
+## Technical Approach
+
+* Extend `sessions.resume.RecoveryBrief` with compact summaries.
+* Render a new `Recent compacts:` section.
+* Update tests in `tests/test_sessions.py` and `tests/test_cli.py`.
+
+## Checkpoint: Stage 15B
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Extended `RecoveryBrief` with `recent_compacts`.
+- `build_recovery_brief()` now includes bounded recent compact records.
+- `render_recovery_brief()` now renders a `Recent compacts:` section.
+- `sessions resume <id>` without `--prompt` now shows recent compact summaries when present.
+- Resume-with-prompt semantics are unchanged except that the recovery brief now includes the compact section.
+
+Verification:
+- `pytest -q tests/test_sessions.py tests/test_cli.py`
+- `ruff check src/coding_deepgent/sessions/resume.py tests/test_sessions.py tests/test_cli.py`
+- `mypy src/coding_deepgent/sessions/resume.py`
+
+cc-haha alignment:
+- Source files inspected:
+  - `/root/claude-code-haha/src/utils/sessionStorage.ts`
+  - `/root/claude-code-haha/src/services/compact/compact.ts`
+- Aligned:
+  - compact/session metadata is now visible during recovery display rather than hidden in the transcript only.
+- Deferred:
+  - compact-boundary-aware continuation selection
+  - transcript pruning/relinking
+
+LangChain architecture:
+- Primitive used:
+  - existing recovery brief builder/render path
+  - no runtime message-history mutation in this sub-stage
+- Why no heavier abstraction:
+  - 15B is display-only hardening; selection semantics belong to 15C.
+
+Boundary findings:
+- New issue handled:
+  - recovery display previously hid compact transcript state entirely.
+- Residual risk:
+  - compact summaries are visible but not yet used to select a reduced continuation path.
+- Impact on next stage:
+  - 15C can now make continuation selection decisions with an already user-visible compact record surface.
+
+Decision:
+- continue
+
+Reason:
+- Tests, ruff, and mypy passed.
+- Scope stayed display-only and non-destructive.
+- 15C remains valid and does not require pruning or auto-compact.
diff --git a/.trellis/tasks/04-14-stage-15b-compact-record-recovery-display/task.json b/.trellis/tasks/04-14-stage-15b-compact-record-recovery-display/task.json
new file mode 100644
index 000000000..243e4961e
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-15b-compact-record-recovery-display/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-15b-compact-record-recovery-display",
+  "name": "stage-15b-compact-record-recovery-display",
+  "title": "Stage 15B: Compact Record Recovery Display",
+  "description": "",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/04-14-stage-15c-compacted-continuation-selection/check.jsonl b/.trellis/tasks/04-14-stage-15c-compacted-continuation-selection/check.jsonl
new file mode 100644
index 000000000..3bd087b95
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-15c-compacted-continuation-selection/check.jsonl
@@ -0,0 +1,3 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_cli.py", "reason": "resume selection compact tests"}
diff --git a/.trellis/tasks/04-14-stage-15c-compacted-continuation-selection/debug.jsonl b/.trellis/tasks/04-14-stage-15c-compacted-continuation-selection/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-15c-compacted-continuation-selection/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/04-14-stage-15c-compacted-continuation-selection/implement.jsonl b/.trellis/tasks/04-14-stage-15c-compacted-continuation-selection/implement.jsonl
new file mode 100644
index 000000000..9bd016608
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-15c-compacted-continuation-selection/implement.jsonl
@@ -0,0 +1,3 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/src/coding_deepgent/cli_service.py", "reason": "compact-aware continuation selection"}
diff --git a/.trellis/tasks/04-14-stage-15c-compacted-continuation-selection/prd.md b/.trellis/tasks/04-14-stage-15c-compacted-continuation-selection/prd.md
new file mode 100644
index 000000000..d869e37be
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-15c-compacted-continuation-selection/prd.md
@@ -0,0 +1,148 @@
+# Stage 15C: Compacted Continuation Selection
+
+## Goal
+
+When a session already contains compact transcript records, prefer a compacted continuation history for `sessions resume --prompt` instead of always replaying the full raw history, while keeping transcript storage append-only and non-destructive.
+
+## Concrete Benefit
+
+* Context-efficiency: resumed sessions stop replaying already-compacted full history when a latest compact summary is available.
+* Continuity: resume uses the same compact summary + preserved tail semantics that earlier compact actions established.
+* Safety: transcript remains intact; only continuation history selection changes.
+
+## Requirements
+
+* Add a compact-aware continuation selector for loaded sessions.
+* Use the latest compact record when no explicit compact override is provided.
+* Preserve:
+  - recovery brief system message
+  - compact summary from latest compact record
+  - all real messages from the preserved tail start onward
+* Keep explicit overrides higher priority:
+  - manual `--compact-summary`
+  - generated `--generate-compact-summary`
+* Keep transcript append-only and non-destructive.
+* Add focused CLI/service tests.
+
+## Acceptance Criteria
+
+* [ ] Resume-with-prompt defaults to latest compacted continuation when compact records exist.
+* [ ] The selected tail includes all real messages from the compact preserved window onward, including later continuation messages.
+* [ ] Sessions without compact records still use the existing recovery-brief + full-history path.
+* [ ] Explicit compact CLI options still override default selection behavior.
+* [ ] Focused tests, ruff, and mypy pass.
+
+## Out of Scope
+
+* transcript pruning/deletion
+* auto-compact
+* prompt-too-long retry
+* changing compact record schema
+* altering recovery brief rendering beyond what 15B added
+
+## cc-haha Alignment
+
+### Expected effect
+
+Aligning this behavior should improve long-session continuity, recoverability, and context-efficiency.
+
+The local runtime effect is: once a session has a compact boundary/summary recorded, later resume continuation can start from that compact summary and preserved tail instead of replaying the full pre-compact transcript.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Compaction boundary-aware loading | `/root/claude-code-haha/src/utils/sessionStorage.ts` and portable loader treat compact boundaries as transcript semantics, not just display hints | local resume should respect compacted continuation state | compact-aware continuation history selector | partial | Implement selector now |
+| Preserved tail semantics | `/root/claude-code-haha/src/services/compact/compact.ts` and `sessionMemoryCompact.ts` preserve a recent tail after summary | local resume should keep the preserved tail plus later messages | derive tail start from latest compact record | align | Implement now |
+| Transcript pruning/relinking | cc-haha later prunes/relinks transcript chains around boundaries | full transcript rewrite semantics | none now | defer | Out of scope |
+
+## LangChain Boundary
+
+Use:
+
+* existing `LoadedSession`
+* compact artifact helper from Stage 13
+* append-only compact records from 15A
+* existing CLI service seam
+
+Avoid:
+
+* `SummarizationMiddleware`
+* `RemoveMessage`
+* transcript rewrite/prune logic
+* provider-specific compact runtime
+
+## Technical Approach
+
+* Add `cli_service.selected_continuation_history()`.
+* If `loaded.compacts` is non-empty, derive:
+  - latest compact summary
+  - preserved tail start = `original_message_count - kept_message_count`
+  - compacted history using that tail window
+* Wire `cli.py sessions_resume` default path to `selected_continuation_history()`.
+* Update tests in `tests/test_cli.py`.
+
+## Checkpoint: Stage 15C
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added `cli_service.selected_continuation_history()`.
+- Resume-with-prompt now defaults to a compact-aware continuation path when `loaded.compacts` is non-empty and no explicit compact override is provided.
+- The selected compact continuation uses:
+  - the latest compact summary
+  - preserved tail start = `original_message_count - kept_message_count`
+  - all real messages from that tail onward, including post-compact continuation messages
+- Explicit compact controls still win:
+  - manual `--compact-summary`
+  - generated `--generate-compact-summary`
+- Sessions without compact records still use the recovery-brief + full-history continuation path.
+
+Verification:
+- `pytest -q tests/test_cli.py tests/test_sessions.py tests/test_compact_artifacts.py tests/test_compact_summarizer.py tests/test_message_projection.py`
+- `pytest -q tests/test_context_payloads.py tests/test_message_projection.py tests/test_compact_artifacts.py tests/test_compact_summarizer.py tests/test_compact_budget.py tests/test_sessions.py tests/test_cli.py tests/test_memory.py tests/test_memory_integration.py tests/test_memory_context.py tests/test_app.py`
+- `ruff check src/coding_deepgent/cli_service.py src/coding_deepgent/cli.py tests/test_cli.py`
+- `mypy src/coding_deepgent/cli_service.py src/coding_deepgent/cli.py`
+
+cc-haha alignment:
+- Source files inspected:
+  - `/root/claude-code-haha/src/utils/sessionStorage.ts`
+  - `/root/claude-code-haha/src/services/compact/compact.ts`
+  - `/root/claude-code-haha/src/services/compact/sessionMemoryCompact.ts`
+- Aligned:
+  - resume continuation can now respect the latest compact boundary/summary instead of always replaying the full raw transcript.
+  - preserved-tail semantics are applied non-destructively from recorded compact metadata.
+- Deferred:
+  - transcript pruning/relinking.
+  - auto/reactive compact.
+  - prompt-too-long retry.
+
+LangChain architecture:
+- Primitive used:
+  - existing CLI service seam and normal message history continuation.
+  - no `SummarizationMiddleware`, no `RemoveMessage`, and no transcript rewrite.
+- Why no heavier abstraction:
+  - 15C changes only continuation selection, not transcript storage or runtime lifecycle policy.
+
+Boundary findings:
+- New issue handled:
+  - compact records were visible after 15B but unused for continuation selection; 15C closes that gap.
+- Residual risk:
+  - compact selection currently trusts the latest compact record as authoritative. More complex multi-compact / pruning semantics remain deferred.
+- Impact on next stage:
+  - any next step now moves into materially different behavior: transcript pruning/relinking, auto/reactive compact, or richer compact recovery semantics.
+
+Decision:
+- continue
+
+Terminal note:
+- Stage 15B and 15C complete the current non-destructive compact persistence semantics slice. No further sub-stage should start automatically without an explicit choice between pruning semantics, reactive/auto compact, or richer recovery behavior.
+
+Reason:
+- Tests, ruff, and mypy passed.
+- Scope stayed non-destructive.
+- Further work would widen the product contract beyond the current approved Stage 15 family.
diff --git a/.trellis/tasks/04-14-stage-15c-compacted-continuation-selection/task.json b/.trellis/tasks/04-14-stage-15c-compacted-continuation-selection/task.json
new file mode 100644
index 000000000..8ac8ac02e
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-15c-compacted-continuation-selection/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-15c-compacted-continuation-selection",
+  "name": "stage-15c-compacted-continuation-selection",
+  "title": "Stage 15C: Compacted Continuation Selection",
+  "description": "",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/04-14-stage-16-compact-transcript-pruning-semantics/prd.md b/.trellis/tasks/04-14-stage-16-compact-transcript-pruning-semantics/prd.md
new file mode 100644
index 000000000..1a58a2666
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-16-compact-transcript-pruning-semantics/prd.md
@@ -0,0 +1,167 @@
+# brainstorm: Stage 16 Compact Transcript Pruning Semantics
+
+## Goal
+
+Define the pruning semantics for compacted transcripts before implementation, so future compact work can reduce replayed history without losing auditability, recovery correctness, or transcript integrity.
+
+## What I already know
+
+* Stage 15A is done:
+  - append-only `compact` transcript records exist
+  - compact records are loaded separately from `history`
+  - compacted continuation message indexes remain correct
+* Stage 15B is done:
+  - recovery brief displays recent compact summaries
+* Stage 15C is done:
+  - resume continuation now prefers latest compact summary + preserved tail when compact records exist
+* Current local behavior is still non-destructive:
+  - no transcript deletion
+  - no transcript pruning
+  - no transcript rewrite
+* cc-haha source already has more advanced transcript semantics:
+  - compact-boundary-aware loading
+  - preserved-segment relinking
+  - pre-boundary metadata recovery
+  - selective pruning before the latest compact boundary
+  - separate snip-removal semantics for middle-range deletions
+* LangChain short-term memory docs support trimming/deleting/summarizing messages, but those mechanisms persistently alter state and are not equivalent to our current append-only transcript ledger.
+
+## Assumptions (temporary)
+
+* The next compact milestone should still preserve auditability.
+* Transcript semantics should remain recoverable from JSONL without requiring provider-specific runtime state.
+* We should avoid immediately adopting cc-haha's most aggressive pruning/relinking logic without narrowing our local product need first.
+
+## Open Questions
+
+* Which pruning model should become the next product contract?
+
+## Requirements (evolving)
+
+* Define what must remain append-only.
+* Define what may be pruned or skipped at load time.
+* Define what compact metadata must stay auditable.
+* Define exact recovery invariants for:
+  - resume display
+  - resume continuation
+  - message ordering
+  - tool-use/tool-result integrity
+* Define whether pruning should be:
+  - virtual at load time only
+  - recorded via tombstones/markers
+  - physically destructive
+
+## Acceptance Criteria (evolving)
+
+* [ ] A chosen pruning model is explicit.
+* [ ] Recovery invariants are written in testable terms.
+* [ ] The next implementation stage can be scoped without ambiguity.
+
+## Definition of Done (team quality bar)
+
+* Decision captured with trade-offs
+* Follow-on implementation scope is explicit
+* Out-of-scope risks are named
+
+## Out of Scope (explicit)
+
+* Implementing pruning logic in this brainstorm task
+* Auto-compact
+* Prompt-too-long retry
+* Provider-specific cache/runtime behavior
+
+## Technical Notes
+
+* Task dir: `.trellis/tasks/04-14-stage-16-compact-transcript-pruning-semantics`
+* Local files inspected:
+  - `coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py`
+  - `coding-deepgent/src/coding_deepgent/sessions/service.py`
+  - `coding-deepgent/src/coding_deepgent/cli_service.py`
+  - `coding-deepgent/src/coding_deepgent/compact/artifacts.py`
+  - `.trellis/spec/backend/runtime-context-compaction-contracts.md`
+* cc-haha files inspected:
+  - `/root/claude-code-haha/src/utils/sessionStorage.ts`
+  - `/root/claude-code-haha/src/utils/messages.ts`
+  - `/root/claude-code-haha/src/services/compact/compact.ts`
+* Key cc-haha observations:
+  - compact boundary is not just display metadata; loader uses it to skip old transcript
+  - preserved tail keeps original parent links and is relinked in memory
+  - pre-boundary metadata may need separate recovery
+  - pruning is bounded by “latest compact boundary”, not arbitrary deletion
+
+## Research Notes
+
+### What cc-haha effectively does
+
+* Treats compact boundary as transcript semantics, not only a UI hint.
+* Preserves a recent tail after compaction.
+* Lets loader recover metadata from pre-boundary bytes even when older transcript is skipped.
+* Uses relinking/pruning logic to keep resumed continuation coherent without replaying the full pre-compact transcript.
+
+### Constraints from our project
+
+* We already have append-only JSONL transcript records and compact records.
+* We do not yet have parentUuid-style transcript chain semantics.
+* Our current resume logic is simpler: `LoadedSession.history` is plain ordered user/assistant messages.
+* We already have a non-destructive compact-aware continuation selector.
+* We need to preserve:
+  - auditability
+  - deterministic loading
+  - simple tests
+  - no premature custom runtime explosion
+
+### Feasible approaches here
+
+**Approach A: Virtual pruning at load time** (Recommended)
+
+* How it works:
+  - Keep transcript fully append-only on disk.
+  - `load_session()` optionally derives a pruned/selected history view from latest compact record.
+  - Raw full transcript remains available for audit/debug paths.
+* Pros:
+  - safest
+  - preserves auditability
+  - minimal storage risk
+  - aligns with current non-destructive direction
+* Cons:
+  - transcript file keeps growing
+  - load path becomes smarter
+
+**Approach B: Append-only tombstones / prune markers**
+
+* How it works:
+  - Add explicit “pruned range” or “superseded before boundary” records.
+  - Loader respects markers and skips older segments.
+  - Raw lines remain in JSONL, but semantic visibility is narrowed by markers.
+* Pros:
+  - still auditable
+  - semantics become explicit in transcript
+  - easier future evolution toward snip-like behavior
+* Cons:
+  - more record types
+  - more loader complexity
+  - more chances to get invariants wrong
+
+**Approach C: Physical destructive pruning**
+
+* How it works:
+  - Rewrite the JSONL and remove old lines after compaction.
+* Pros:
+  - smallest on-disk transcript
+  - simplest load path after rewrite
+* Cons:
+  - worst auditability
+  - risk of corruption
+  - highest implementation risk
+  - mismatched with current product direction
+
+## Decision (ADR-lite)
+
+**Context**: We now have compact records and compact-aware continuation selection, but not transcript pruning semantics.
+
+**Provisional decision**: Prefer Approach A unless a stronger product reason appears.
+
+**Consequences**:
+
+* Resume behavior can become more compact-aware without rewriting transcript files.
+* Future destructive pruning remains possible later, but only after invariants are explicit.
diff --git a/.trellis/tasks/04-14-stage-16-compact-transcript-pruning-semantics/task.json b/.trellis/tasks/04-14-stage-16-compact-transcript-pruning-semantics/task.json
new file mode 100644
index 000000000..71cc9403a
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-16-compact-transcript-pruning-semantics/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-16-compact-transcript-pruning-semantics",
+  "name": "stage-16-compact-transcript-pruning-semantics",
+  "title": "brainstorm: stage-16 compact transcript pruning semantics",
+  "description": "",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/04-14-stage-16a-load-time-compacted-history-view/check.jsonl b/.trellis/tasks/04-14-stage-16a-load-time-compacted-history-view/check.jsonl
new file mode 100644
index 000000000..680391d35
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-16a-load-time-compacted-history-view/check.jsonl
@@ -0,0 +1,4 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_sessions.py", "reason": "compacted_history load-time view tests"}
+{"file": "coding-deepgent/tests/test_cli.py", "reason": "resume compacted_history selector tests"}
diff --git a/.trellis/tasks/04-14-stage-16a-load-time-compacted-history-view/debug.jsonl b/.trellis/tasks/04-14-stage-16a-load-time-compacted-history-view/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-16a-load-time-compacted-history-view/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/04-14-stage-16a-load-time-compacted-history-view/implement.jsonl b/.trellis/tasks/04-14-stage-16a-load-time-compacted-history-view/implement.jsonl
new file mode 100644
index 000000000..3b46fd8ca
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-16a-load-time-compacted-history-view/implement.jsonl
@@ -0,0 +1,5 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/src/coding_deepgent/sessions/records.py", "reason": "LoadedSession compacted_history view"}
+{"file": "coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py", "reason": "derive virtual compacted history at load time"}
+{"file": "coding-deepgent/src/coding_deepgent/cli_service.py", "reason": "use compacted_history view for selected continuation"}
diff --git a/.trellis/tasks/04-14-stage-16a-load-time-compacted-history-view/prd.md b/.trellis/tasks/04-14-stage-16a-load-time-compacted-history-view/prd.md
new file mode 100644
index 000000000..798470d0d
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-16a-load-time-compacted-history-view/prd.md
@@ -0,0 +1,135 @@
+# Stage 16A: Load-Time Compacted History View
+
+## Goal
+
+Add a load-time virtual compacted history view to `LoadedSession` so resume and future recovery paths can choose between raw transcript history and a compact-aware view without rewriting transcript files.
+
+## Concrete Benefit
+
+* Context-efficiency: compact-aware callers no longer need to reconstruct compacted history ad hoc.
+* Recoverability: raw history and compacted history coexist in one loaded session object.
+* Safety: transcript stays append-only; the compacted view is derived at load time only.
+
+## Requirements
+
+* Extend `LoadedSession` with `compacted_history`.
+* `history` remains raw/full message history.
+* `compacted_history` is derived from latest compact record when valid.
+* If there is no valid compact-derived view, `compacted_history` falls back to the raw history.
+* `cli_service.selected_continuation_history()` should use `loaded.compacted_history`.
+* Add focused tests for load-time compacted history derivation.
+
+## Acceptance Criteria
+
+* [ ] `LoadedSession.compacted_history` exists.
+* [ ] Sessions without compact records have `compacted_history == history`.
+* [ ] Sessions with compact records get a compact boundary + compact summary + preserved tail as `compacted_history`.
+* [ ] Invalid/out-of-range compact record counts fall back safely to raw history.
+* [ ] `selected_continuation_history()` uses the loaded compacted view instead of rebuilding it inline.
+* [ ] Focused tests, ruff, and mypy pass.
+
+## Out of Scope
+
+* transcript pruning/deletion
+* auto-compact
+* prompt-too-long retry
+* changing compact record schema
+* changing recovery brief display
+
+## cc-haha Alignment
+
+### Expected effect
+
+Aligning this behavior should improve recoverability, context-efficiency, and maintainability.
+
+The local runtime effect is: compact-aware loading semantics become an explicit part of session load, not just a resume-time reconstruction trick.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Boundary-aware transcript loading | `/root/claude-code-haha/src/utils/sessionStorage.ts` treats compact boundary as transcript loading semantics | local load path should expose a compact-aware history view | `LoadedSession.compacted_history` | partial | Implement now |
+| Raw transcript preservation | cc-haha still preserves metadata and reconstructs state around boundaries | local raw transcript should remain intact | keep `history` raw | align | Preserve now |
+| Destructive pruning/relinking | cc-haha can prune/relink around latest compact boundary | advanced transcript semantics | none now | defer | Out of scope |
+
+## LangChain Boundary
+
+Use:
+
+* existing `LoadedSession`
+* existing compact artifact helper
+* append-only compact records
+
+Avoid:
+
+* `SummarizationMiddleware`
+* transcript rewrite
+* state replacement
+
+## Technical Approach
+
+* Extend `LoadedSession` in `sessions/records.py`.
+* Derive `compacted_history` in `JsonlSessionStore.load_session()`.
+* Make `cli_service.selected_continuation_history()` use `loaded.compacted_history`.
+* Add/extend tests in `tests/test_sessions.py` and `tests/test_cli.py`.
+
+## Checkpoint: Stage 16A
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Extended `LoadedSession` with `compacted_history`.
+- `JsonlSessionStore.load_session()` now derives a load-time virtual compacted history view from the latest compact record when valid.
+- `LoadedSession.history` remains the raw/full transcript view.
+- `LoadedSession.compacted_history` falls back to raw history when there is no compact record or the compact-derived tail is invalid/empty.
+- `cli_service.selected_continuation_history()` now consumes the loaded compacted view instead of rebuilding compact semantics ad hoc.
+- Updated backend code-spec with `compacted_history` contracts and validation cases.
+
+Verification:
+- `pytest -q tests/test_sessions.py tests/test_cli.py`
+- `pytest -q tests/test_context_payloads.py tests/test_message_projection.py tests/test_compact_artifacts.py tests/test_compact_summarizer.py tests/test_compact_budget.py tests/test_sessions.py tests/test_cli.py tests/test_memory.py tests/test_memory_integration.py tests/test_memory_context.py tests/test_app.py`
+- `ruff check src/coding_deepgent/sessions/records.py src/coding_deepgent/sessions/store_jsonl.py src/coding_deepgent/cli_service.py tests/test_sessions.py tests/test_cli.py`
+- `mypy src/coding_deepgent/sessions/records.py src/coding_deepgent/sessions/store_jsonl.py src/coding_deepgent/cli_service.py`
+
+cc-haha alignment:
+- Source files inspected:
+  - `/root/claude-code-haha/src/utils/sessionStorage.ts`
+  - `/root/claude-code-haha/src/services/compact/compact.ts`
+- Aligned:
+  - compact boundary semantics are now part of load-time session interpretation, not only runtime continuation selection.
+  - raw transcript and compact-aware view coexist.
+- Deferred:
+  - transcript pruning/relinking
+  - physical deletion
+  - auto/reactive compact
+
+LangChain architecture:
+- Primitive used:
+  - append-only JSONL session store
+  - load-time derived view
+  - normal message dictionaries for continuation
+- Why no heavier abstraction:
+  - 16A formalizes a read/view model only; it does not rewrite transcript semantics on disk.
+
+Boundary findings:
+- New issue handled:
+  - compact-aware continuation logic was previously duplicated in resume selection code; now the compacted history is part of the loaded session contract.
+- Residual risk:
+  - latest compact record is still treated as the authoritative compact boundary. Multi-boundary semantics remain intentionally simple.
+- Impact on next stage:
+  - Stage 16 can continue only by choosing whether to enrich virtual pruning semantics further or stop before destructive pruning.
+
+Decision:
+- continue
+
+Terminal note:
+- Stage 16A completes the core virtual-pruning view layer. No further Stage 16 sub-stage is started automatically because deeper work now needs an explicit choice about how far virtual pruning should go before destructive semantics are considered.
+
+Reason:
+- Tests, ruff, and mypy passed.
+- Scope stayed append-only and non-destructive.
+- No transcript deletion, transcript rewrite, auto-compact, prompt-too-long retry, or `SummarizationMiddleware` was introduced.
diff --git a/.trellis/tasks/04-14-stage-16a-load-time-compacted-history-view/task.json b/.trellis/tasks/04-14-stage-16a-load-time-compacted-history-view/task.json
new file mode 100644
index 000000000..af8cdb130
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-16a-load-time-compacted-history-view/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-16a-load-time-compacted-history-view",
+  "name": "stage-16a-load-time-compacted-history-view",
+  "title": "Stage 16A: Load-Time Compacted History View",
+  "description": "",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/04-14-stage-16b-latest-valid-compact-view-selection/check.jsonl b/.trellis/tasks/04-14-stage-16b-latest-valid-compact-view-selection/check.jsonl
new file mode 100644
index 000000000..5a9dca09e
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-16b-latest-valid-compact-view-selection/check.jsonl
@@ -0,0 +1,3 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_sessions.py", "reason": "multiple compact selection tests"}
diff --git a/.trellis/tasks/04-14-stage-16b-latest-valid-compact-view-selection/debug.jsonl b/.trellis/tasks/04-14-stage-16b-latest-valid-compact-view-selection/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-16b-latest-valid-compact-view-selection/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/04-14-stage-16b-latest-valid-compact-view-selection/implement.jsonl b/.trellis/tasks/04-14-stage-16b-latest-valid-compact-view-selection/implement.jsonl
new file mode 100644
index 000000000..741810fb9
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-16b-latest-valid-compact-view-selection/implement.jsonl
@@ -0,0 +1,3 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py", "reason": "latest-valid compacted history selection"}
diff --git a/.trellis/tasks/04-14-stage-16b-latest-valid-compact-view-selection/prd.md b/.trellis/tasks/04-14-stage-16b-latest-valid-compact-view-selection/prd.md
new file mode 100644
index 000000000..c9e25d8ea
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-16b-latest-valid-compact-view-selection/prd.md
@@ -0,0 +1,116 @@
+# Stage 16B: Latest Valid Compact View Selection
+
+## Goal
+
+Harden virtual pruning so `load_session()` selects the latest valid compact-derived history view instead of blindly trusting only the final compact record.
+
+## Concrete Benefit
+
+* Reliability: a malformed or stale latest compact record no longer forces a fallback to full raw history if an earlier valid compact view exists.
+* Recoverability: compact-aware load semantics become more robust across multiple compactions.
+* Maintainability: compact view selection logic becomes explicit and testable.
+
+## Requirements
+
+* Scan compact records from newest to oldest.
+* Use the newest compact record that yields a valid compacted history view.
+* If none are valid, fall back to raw history.
+* Preserve raw `history` unchanged.
+* Preserve append-only transcript behavior.
+* Add focused tests for multiple compact records and invalid-latest fallback.
+
+## Acceptance Criteria
+
+* [x] Latest valid compact record wins.
+* [x] Invalid latest compact record falls back to the most recent earlier valid compact record.
+* [x] No valid compact record still falls back to raw history.
+* [x] Focused tests, ruff, and mypy pass.
+
+## Out of Scope
+
+* transcript pruning/deletion
+* transcript relinking
+* auto-compact
+* prompt-too-long retry
+
+## cc-haha Alignment
+
+### Expected effect
+
+Aligning this behavior should improve recoverability and long-session continuity.
+
+The local runtime effect is: compact-aware load semantics are resilient to stale or malformed later compact records, closer to cc-haha's boundary-aware transcript interpretation.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Boundary-aware load semantics | `sessionStorage.ts` treats compact boundaries as transcript interpretation, not a single fragile marker | local load path should tolerate more than one compact event | latest-valid compact selection | partial | Implement now |
+| Full pruning/relinking | cc-haha prunes/relinks around latest live boundary | full semantic pruning | none now | defer | Out of scope |
+
+## Technical Approach
+
+* Refactor `JsonlSessionStore._build_compacted_history()` to iterate compact records from newest to oldest.
+* Extract a helper that attempts to build a compacted view for one compact record.
+* Add tests in `tests/test_sessions.py` and `tests/test_cli.py`.
+
+## Checkpoint: Stage 16B
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Refactored compacted history derivation to scan compact records from newest to oldest.
+- Added per-record compact view builder helper in `JsonlSessionStore`.
+- `LoadedSession.compacted_history` now uses the latest valid compact record rather than blindly trusting only the final compact record.
+- If the latest compact record is invalid but an earlier one is valid, the earlier valid compact record now drives the compacted history view.
+- If no compact record yields a valid view, raw history is still preserved as the fallback.
+- Added an explicit newest-valid-wins regression test for multiple valid compact records.
+
+Verification:
+- `pytest -q tests/test_sessions.py tests/test_cli.py`
+- `pytest -q tests/test_context_payloads.py tests/test_message_projection.py tests/test_compact_artifacts.py tests/test_compact_summarizer.py tests/test_compact_budget.py tests/test_sessions.py tests/test_cli.py tests/test_memory.py tests/test_memory_integration.py tests/test_memory_context.py tests/test_app.py`
+- `ruff check src/coding_deepgent/sessions/store_jsonl.py tests/test_sessions.py`
+- `mypy src/coding_deepgent/sessions/store_jsonl.py`
+- Latest local rerun:
+  - `pytest -q tests/test_sessions.py`
+  - `pytest -q tests/test_cli.py tests/test_context_payloads.py tests/test_message_projection.py tests/test_compact_artifacts.py tests/test_compact_summarizer.py tests/test_compact_budget.py tests/test_memory.py tests/test_memory_integration.py tests/test_memory_context.py tests/test_app.py`
+  - `ruff check src/coding_deepgent/sessions/store_jsonl.py tests/test_sessions.py`
+  - `mypy src/coding_deepgent/sessions/store_jsonl.py`
+
+cc-haha alignment:
+- Source-backed intent came from `sessionStorage.ts` compact-boundary-aware loading semantics.
+- Aligned:
+  - compact-aware loading is now more resilient across multiple compact events.
+- Deferred:
+  - transcript pruning/relinking
+  - destructive compact semantics
+  - auto/reactive compact
+
+LangChain architecture:
+- Primitive used:
+  - load-time derived compacted view over append-only transcript records
+- Why no heavier abstraction:
+  - 16B only hardens virtual pruning selection; no transcript mutation or graph-level state replacement is needed.
+
+Boundary findings:
+- New issue handled:
+  - a malformed latest compact record no longer forces a full fallback when an earlier valid compact view exists.
+- Residual risk:
+  - compact selection is still linear and based only on record ordering/count semantics, not a richer compact lineage graph.
+- Impact on next stage:
+  - virtual pruning is now strong enough for the current product slice; deeper work would need an explicit choice between richer lineage semantics and destructive pruning semantics.
+
+Decision:
+- continue
+
+Terminal note:
+- Stage 16 virtual pruning is complete for the current non-destructive scope. No further sub-stage starts automatically because the next work would materially change transcript semantics beyond the current approved boundary.
+
+Reason:
+- Tests, ruff, and mypy passed.
+- Scope stayed virtual and append-only.
+- No transcript deletion, rewrite, auto-compact, prompt-too-long retry, or `SummarizationMiddleware` was introduced.
diff --git a/.trellis/tasks/04-14-stage-16b-latest-valid-compact-view-selection/task.json b/.trellis/tasks/04-14-stage-16b-latest-valid-compact-view-selection/task.json
new file mode 100644
index 000000000..9c90f0eb7
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-16b-latest-valid-compact-view-selection/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-16b-latest-valid-compact-view-selection",
+  "name": "stage-16b-latest-valid-compact-view-selection",
+  "title": "Stage 16B: Latest Valid Compact View Selection",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": "2026-04-14",
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 3,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
diff --git a/.trellis/tasks/04-14-stage-16b-virtual-pruning-compact-selection-hardening/task.json b/.trellis/tasks/04-14-stage-16b-virtual-pruning-compact-selection-hardening/task.json
new file mode 100644
index 000000000..556081c19
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-16b-virtual-pruning-compact-selection-hardening/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-16b-virtual-pruning-compact-selection-hardening",
+  "name": "stage-16b-virtual-pruning-compact-selection-hardening",
+  "title": "Stage 16B: Virtual Pruning Compact Selection Hardening",
+  "description": "",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/04-14-stage-16c-virtual-pruning-view-metadata/check.jsonl b/.trellis/tasks/04-14-stage-16c-virtual-pruning-view-metadata/check.jsonl
new file mode 100644
index 000000000..54414c310
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-16c-virtual-pruning-view-metadata/check.jsonl
@@ -0,0 +1,3 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_sessions.py", "reason": "compacted history source tests"}
diff --git a/.trellis/tasks/04-14-stage-16c-virtual-pruning-view-metadata/debug.jsonl b/.trellis/tasks/04-14-stage-16c-virtual-pruning-view-metadata/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-16c-virtual-pruning-view-metadata/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/04-14-stage-16c-virtual-pruning-view-metadata/implement.jsonl b/.trellis/tasks/04-14-stage-16c-virtual-pruning-view-metadata/implement.jsonl
new file mode 100644
index 000000000..2743f7622
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-16c-virtual-pruning-view-metadata/implement.jsonl
@@ -0,0 +1,3 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py", "reason": "populate compacted history source"}
diff --git a/.trellis/tasks/04-14-stage-16c-virtual-pruning-view-metadata/prd.md b/.trellis/tasks/04-14-stage-16c-virtual-pruning-view-metadata/prd.md
new file mode 100644
index 000000000..021e92d88
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-16c-virtual-pruning-view-metadata/prd.md
@@ -0,0 +1,95 @@
+# Stage 16C: Virtual Pruning View Metadata
+
+## Goal
+
+Expose why `LoadedSession.compacted_history` was selected, so recovery/debug/test code can distinguish raw fallback from a compact-derived view.
+
+## Concrete Benefit
+
+* Observability: compact-aware session loading can explain which compact record drove the view.
+* Testability: future invariants can assert selection reason instead of inferring it from message content.
+* Maintainability: later recovery display or diagnostics can use a stable source object.
+
+## Requirements
+
+* Add a compacted-history source object to `LoadedSession`.
+* Source must identify:
+  - raw fallback vs compact-derived view
+  - compact index when compact-derived
+  - reason string
+* Preserve existing `history` and `compacted_history` behavior.
+* Add focused tests.
+
+## Acceptance Criteria
+
+* [ ] Sessions without compacts report raw/no_compacts.
+* [ ] Sessions with invalid compacts report raw/no_valid_compact.
+* [ ] Sessions using a compact view report compact/latest_valid_compact with compact index.
+* [ ] Focused tests, ruff, and mypy pass.
+
+## Out of Scope
+
+* changing selected history behavior
+* transcript pruning/deletion
+* auto-compact
+* prompt-too-long retry
+
+## Technical Approach
+
+* Add `CompactedHistorySource` dataclass in `sessions/records.py`.
+* Change `JsonlSessionStore._build_compacted_history()` to return view + source.
+* Populate `LoadedSession.compacted_history_source`.
+* Extend `tests/test_sessions.py`.
+
+## Checkpoint: Stage 16C
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added `CompactedHistorySource`.
+- Added `LoadedSession.compacted_history_source`.
+- `JsonlSessionStore._build_compacted_history()` now returns both the compacted view and the source metadata.
+- Source metadata distinguishes:
+  - `raw/no_compacts`
+  - `raw/no_valid_compact`
+  - `compact/latest_valid_compact/<compact_index>`
+- Updated backend runtime context/compaction spec with the source contract.
+
+Verification:
+- `pytest -q tests/test_sessions.py tests/test_cli.py`
+- `pytest -q tests/test_context_payloads.py tests/test_message_projection.py tests/test_compact_artifacts.py tests/test_compact_summarizer.py tests/test_compact_budget.py tests/test_sessions.py tests/test_cli.py tests/test_memory.py tests/test_memory_integration.py tests/test_memory_context.py tests/test_app.py`
+- `ruff check src/coding_deepgent/sessions/records.py src/coding_deepgent/sessions/store_jsonl.py src/coding_deepgent/sessions/__init__.py tests/test_sessions.py`
+- `mypy src/coding_deepgent/sessions/records.py src/coding_deepgent/sessions/store_jsonl.py src/coding_deepgent/sessions/__init__.py`
+
+cc-haha alignment:
+- Source-backed intent came from compact-boundary-aware loader semantics in `/root/claude-code-haha/src/utils/sessionStorage.ts`.
+- Aligned:
+  - local loader can explain which compact boundary/view is active.
+- Deferred:
+  - full parent-chain relinking
+  - physical transcript pruning
+
+LangChain architecture:
+- Primitive used:
+  - explicit dataclass metadata on loaded session state
+  - no graph state replacement or middleware change
+
+Boundary findings:
+- New issue handled:
+  - compacted history selection was previously observable only by inspecting message content; it now has explicit metadata.
+- Residual risk:
+  - source metadata is still count/index based, not a full compact lineage graph.
+
+Decision:
+- continue
+
+Terminal note:
+- Stage 16 virtual pruning is complete for the current non-destructive scope. Further work should either switch to another highlight family or explicitly open a new destructive/pruning semantics design.
+
+Reason:
+- Tests, ruff, and mypy passed.
+- No transcript deletion, rewrite, auto-compact, prompt-too-long retry, or `SummarizationMiddleware` was introduced.
diff --git a/.trellis/tasks/04-14-stage-16c-virtual-pruning-view-metadata/task.json b/.trellis/tasks/04-14-stage-16c-virtual-pruning-view-metadata/task.json
new file mode 100644
index 000000000..3a746a673
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-16c-virtual-pruning-view-metadata/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-16c-virtual-pruning-view-metadata",
+  "name": "stage-16c-virtual-pruning-view-metadata",
+  "title": "Stage 16C: Virtual Pruning View Metadata",
+  "description": "",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/04-14-stage-17a-task-graph-readiness-and-transition-invariants/check.jsonl b/.trellis/tasks/04-14-stage-17a-task-graph-readiness-and-transition-invariants/check.jsonl
new file mode 100644
index 000000000..2fc97f465
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-17a-task-graph-readiness-and-transition-invariants/check.jsonl
@@ -0,0 +1,3 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_tasks.py", "reason": "task graph invariant tests"}
diff --git a/.trellis/tasks/04-14-stage-17a-task-graph-readiness-and-transition-invariants/debug.jsonl b/.trellis/tasks/04-14-stage-17a-task-graph-readiness-and-transition-invariants/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-17a-task-graph-readiness-and-transition-invariants/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/04-14-stage-17a-task-graph-readiness-and-transition-invariants/implement.jsonl b/.trellis/tasks/04-14-stage-17a-task-graph-readiness-and-transition-invariants/implement.jsonl
new file mode 100644
index 000000000..6a3b0b33b
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-17a-task-graph-readiness-and-transition-invariants/implement.jsonl
@@ -0,0 +1,4 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/src/coding_deepgent/tasks/store.py", "reason": "task graph validation"}
+{"file": "coding-deepgent/src/coding_deepgent/tasks/tools.py", "reason": "task list ready output and blocked update behavior"}
diff --git a/.trellis/tasks/04-14-stage-17a-task-graph-readiness-and-transition-invariants/prd.md b/.trellis/tasks/04-14-stage-17a-task-graph-readiness-and-transition-invariants/prd.md
new file mode 100644
index 000000000..cf1ed40d3
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-17a-task-graph-readiness-and-transition-invariants/prd.md
@@ -0,0 +1,143 @@
+# Stage 17A: Task Graph Readiness and Transition Invariants
+
+## Goal
+
+Harden durable task graph semantics before plan/verify or multi-agent work, keeping TodoWrite separate from durable Task.
+
+## Concrete Benefit
+
+* Reliability: durable tasks cannot reference missing dependencies or create simple cycles.
+* Multi-agent readiness: `task_list` can expose which tasks are actually ready to claim.
+* Maintainability: task invariants are enforced in the task domain, not prompt prose.
+
+## Requirements
+
+* Reject missing dependencies at task creation.
+* Reject self-dependencies.
+* Reject dependency cycles on create/update.
+* Require a blocker signal when moving a task to `blocked`.
+* Add `ready` to task list output.
+* Preserve existing task statuses and public tool names.
+* Keep TodoWrite separate from durable Task.
+
+## Acceptance Criteria
+
+* [ ] Creating a task with an unknown dependency fails.
+* [ ] Creating/updating a self-dependency fails.
+* [ ] Creating/updating a cycle fails.
+* [ ] Moving to `blocked` without dependency or `blocked_reason` metadata fails.
+* [ ] `task_list` renders ready status deterministically.
+* [ ] Focused tests, ruff, and mypy pass.
+
+## Out of Scope
+
+* mailbox
+* coordinator runtime
+* multi-agent communication
+* claim/lock semantics
+* plan mode tools
+* verification subagent workflow
+
+## cc-haha Alignment
+
+### Expected effect
+
+Aligning this behavior should improve reliability, multi-agent readiness, and product parity.
+
+The local runtime effect is: task records become a stricter durable graph instead of a loose list, so later plan/verify and subagent workflows can build on correct readiness semantics.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Task creation | `TaskCreateTool` creates durable task records with subject/description/status and optional metadata | local durable tasks are structured records | existing `TaskRecord` | align | Preserve |
+| Dependencies | `TaskUpdateTool` supports `addBlocks` / `addBlockedBy`; `TaskListTool` renders blocked tasks with open blockers | local tasks need dependency readiness semantics | validate dependencies and expose `ready` | partial | Implement now |
+| Completion discipline | `TaskUpdateTool` nudges verification after closing many tasks | plan/verify should be explicit later | no verifier now | defer | Stage 17B |
+| Mailbox/ownership | cc-haha can notify owners via mailbox | multi-agent coordination | no mailbox now | defer | Out of scope |
+
+## LangChain Boundary
+
+Use:
+
+* strict Pydantic task tool schemas
+* LangGraph store-backed task records
+* deterministic task domain validation
+
+Avoid:
+
+* TodoWrite persistence
+* mailbox/coordinator runtime
+* prompt-only validation
+
+## Technical Approach
+
+* Extend `tasks.store` with dependency validation helpers.
+* Keep `TaskRecord.depends_on` as the local blocked-by edge.
+* Add `ready` to `task_list` output.
+* Extend `tests/test_tasks.py`.
+
+## Checkpoint: Stage 17A
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added dependency validation on task creation.
+- Added dependency update support through `TaskUpdateInput`, `update_task()`, and `task_update`.
+- Rejected:
+  - unknown dependencies
+  - self-dependencies
+  - dependency cycles
+- Added `validate_task_graph()`.
+- Required a blocker signal before moving a task to `blocked`:
+  - existing/new dependency
+  - or `metadata["blocked_reason"]`
+- Added ready status to `task_list` output via task metadata.
+
+Verification:
+- `pytest -q tests/test_tasks.py tests/test_tool_system_registry.py tests/test_tool_system_middleware.py tests/test_subagents.py tests/test_app.py tests/test_contract.py tests/test_structure.py`
+- `pytest -q`
+- `ruff check src/coding_deepgent/tasks/schemas.py src/coding_deepgent/tasks/store.py src/coding_deepgent/tasks/tools.py src/coding_deepgent/tasks/__init__.py tests/test_tasks.py`
+- `mypy src/coding_deepgent/tasks/schemas.py src/coding_deepgent/tasks/store.py src/coding_deepgent/tasks/tools.py src/coding_deepgent/tasks/__init__.py`
+
+cc-haha alignment:
+- Source files inspected:
+  - `/root/claude-code-haha/src/tools/TaskCreateTool/TaskCreateTool.ts`
+  - `/root/claude-code-haha/src/tools/TaskUpdateTool/TaskUpdateTool.ts`
+  - `/root/claude-code-haha/src/tools/TaskListTool/TaskListTool.ts`
+  - `/root/claude-code-haha/src/tools/TaskGetTool/TaskGetTool.ts`
+  - `/root/claude-code-haha/src/Task.ts`
+- Aligned:
+  - durable tasks remain separate from TodoWrite.
+  - task graph readiness and blocked-by semantics are now explicit and testable.
+- Deferred:
+  - mailbox/owner notifications
+  - coordinator runtime
+  - task-level evidence store
+
+LangChain architecture:
+- Primitive used:
+  - strict Pydantic tool schemas
+  - LangGraph store-backed task records
+  - task-domain validation
+- Why no heavier abstraction:
+  - 17A only hardens graph invariants; no agent/team lifecycle is needed yet.
+
+Boundary findings:
+- New issue handled:
+  - tasks could reference missing dependencies or form cycles because dependencies were not validated as a graph.
+- Residual risk:
+  - `ready` is currently exposed in rendered task metadata rather than as a dedicated public task output schema.
+- Impact on next stage:
+  - 17B can focus on plan/verify workflow boundary without first fixing task graph correctness.
+
+Decision:
+- continue
+
+Reason:
+- Tests, ruff, and mypy passed.
+- Scope stayed within durable task graph invariants.
+- 17B remains valid and does not require mailbox or coordinator runtime.
diff --git a/.trellis/tasks/04-14-stage-17a-task-graph-readiness-and-transition-invariants/task.json b/.trellis/tasks/04-14-stage-17a-task-graph-readiness-and-transition-invariants/task.json
new file mode 100644
index 000000000..921b7fec9
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-17a-task-graph-readiness-and-transition-invariants/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-17a-task-graph-readiness-and-transition-invariants",
+  "name": "stage-17a-task-graph-readiness-and-transition-invariants",
+  "title": "Stage 17A: Task Graph Readiness and Transition Invariants",
+  "description": "",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/04-14-stage-17b-plan-verify-workflow-boundary/check.jsonl b/.trellis/tasks/04-14-stage-17b-plan-verify-workflow-boundary/check.jsonl
new file mode 100644
index 000000000..1af72f3b0
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-17b-plan-verify-workflow-boundary/check.jsonl
@@ -0,0 +1,3 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_tasks.py", "reason": "verification nudge tests"}
diff --git a/.trellis/tasks/04-14-stage-17b-plan-verify-workflow-boundary/debug.jsonl b/.trellis/tasks/04-14-stage-17b-plan-verify-workflow-boundary/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-17b-plan-verify-workflow-boundary/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/04-14-stage-17b-plan-verify-workflow-boundary/implement.jsonl b/.trellis/tasks/04-14-stage-17b-plan-verify-workflow-boundary/implement.jsonl
new file mode 100644
index 000000000..afb59d9ad
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-17b-plan-verify-workflow-boundary/implement.jsonl
@@ -0,0 +1,4 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/src/coding_deepgent/tasks/tools.py", "reason": "task_update verification nudge output"}
+{"file": "coding-deepgent/src/coding_deepgent/tasks/store.py", "reason": "verification boundary helper"}
diff --git a/.trellis/tasks/04-14-stage-17b-plan-verify-workflow-boundary/prd.md b/.trellis/tasks/04-14-stage-17b-plan-verify-workflow-boundary/prd.md
new file mode 100644
index 000000000..4f4ede932
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-17b-plan-verify-workflow-boundary/prd.md
@@ -0,0 +1,130 @@
+# Stage 17B: Plan Verify Workflow Boundary
+
+## Goal
+
+Add a deterministic verification boundary to durable task workflow before introducing plan-mode tools, coordinator runtime, mailbox, or multi-agent communication.
+
+## Concrete Benefit
+
+* Reliability: completing a non-trivial task graph without verification becomes visible to the model.
+* Testability: plan/verify discipline starts as a deterministic task-domain rule.
+* Maintainability: TodoWrite remains short-term planning; durable Task owns workflow evidence/readiness boundaries.
+
+## Requirements
+
+* Detect when a 3+ task graph is fully completed without a verification task.
+* Surface a verification nudge in `task_update` output when the last task closes such a graph.
+* Keep verifier execution out of scope.
+* Keep plan-mode tools out of scope.
+* Keep mailbox/coordinator out of scope.
+
+## Acceptance Criteria
+
+* [ ] Completing the last task in a 3+ graph without verification exposes a verification nudge.
+* [ ] A graph with a verification task does not expose the nudge.
+* [ ] Partial/incomplete graphs do not expose the nudge.
+* [ ] Existing task APIs remain JSON-parseable as `TaskRecord`.
+* [ ] Focused tests, ruff, and mypy pass.
+
+## Out of Scope
+
+* EnterPlanMode / ExitPlanMode tools
+* verification subagent execution
+* coordinator mode
+* mailbox / SendMessage
+* task evidence store
+
+## cc-haha Alignment
+
+### Expected effect
+
+Aligning this behavior should improve reliability and product-grade workflow discipline.
+
+The local runtime effect is: durable task completion now nudges verification for non-trivial task graphs, matching cc-haha's principle that verification is independent work, not a summary caveat.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Verification nudge | `TaskUpdateTool` nudges a verification agent after closing 3+ tasks with no verification task | local task graph discourages unverified completion | task_update output metadata | partial | Implement now |
+| Verification agent | built-in verification agent is read-only/adversarial | future independent verifier | none now | defer | Already available as bounded subagent type |
+| Plan mode | Enter/ExitPlanMode enforce read-only planning and approval | future plan artifact/approval boundary | none now | defer | Out of current scope |
+
+## LangChain Boundary
+
+Use:
+
+* deterministic task-domain helper
+* existing `task_update` tool output path
+* existing verifier subagent type only as future target
+
+Avoid:
+
+* prompt-only workflow claims
+* new plan mode tools
+* coordinator/mailbox runtime
+
+## Technical Approach
+
+* Add `task_graph_needs_verification()` helper.
+* In `task_update`, when a status update completes a task, add `verification_nudge=true` to the returned JSON metadata if the graph needs verification.
+* Add tests in `tests/test_tasks.py`.
+
+## Checkpoint: Stage 17B
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added `task_graph_needs_verification()`.
+- `task_update` now surfaces `verification_nudge=true` in returned metadata when completing the last task in a 3+ graph without a verification task.
+- Verification nudge is output-only and does not mutate the stored `TaskRecord`.
+- Added task workflow executable spec.
+
+Verification:
+- `pytest -q tests/test_tasks.py tests/test_tool_system_registry.py tests/test_tool_system_middleware.py tests/test_subagents.py tests/test_app.py tests/test_contract.py tests/test_structure.py`
+- `pytest -q`
+- `ruff check src/coding_deepgent/tasks/schemas.py src/coding_deepgent/tasks/store.py src/coding_deepgent/tasks/tools.py src/coding_deepgent/tasks/__init__.py tests/test_tasks.py`
+- `mypy src/coding_deepgent/tasks/schemas.py src/coding_deepgent/tasks/store.py src/coding_deepgent/tasks/tools.py src/coding_deepgent/tasks/__init__.py`
+
+cc-haha alignment:
+- Source files inspected:
+  - `/root/claude-code-haha/src/tools/TaskUpdateTool/TaskUpdateTool.ts`
+  - `/root/claude-code-haha/src/tools/AgentTool/built-in/verificationAgent.ts`
+  - `/root/claude-code-haha/src/tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts`
+- Aligned:
+  - non-trivial task graph completion now nudges independent verification.
+  - verification remains a separate boundary, not a final-summary caveat.
+- Deferred:
+  - actual verifier execution
+  - EnterPlanMode/ExitPlanMode local tools
+  - coordinator/mailbox runtime
+
+LangChain architecture:
+- Primitive used:
+  - task-domain helper
+  - strict task tool schema and output JSON
+- Why no heavier abstraction:
+  - 17B establishes workflow boundary only; verifier runtime should build on subagent/task foundations later.
+
+Boundary findings:
+- New issue handled:
+  - durable task graph could be closed without any verification signal.
+- Residual risk:
+  - verification nudge is currently metadata in task output, not an enforced verifier subagent run.
+- Impact on next stage:
+  - next work can either add explicit plan artifacts or start verifier execution integration.
+
+Decision:
+- continue
+
+Terminal note:
+- Stage 17A/17B harden task/workflow foundations enough to switch to a new sub-stage only by explicit product choice.
+
+Reason:
+- Tests, ruff, and mypy passed.
+- Scope stayed inside task/workflow boundary.
+- No mailbox, coordinator runtime, or multi-agent communication was introduced.
diff --git a/.trellis/tasks/04-14-stage-17b-plan-verify-workflow-boundary/task.json b/.trellis/tasks/04-14-stage-17b-plan-verify-workflow-boundary/task.json
new file mode 100644
index 000000000..7218d5585
--- /dev/null
+++ b/.trellis/tasks/04-14-stage-17b-plan-verify-workflow-boundary/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-17b-plan-verify-workflow-boundary",
+  "name": "stage-17b-plan-verify-workflow-boundary",
+  "title": "Stage 17B: Plan Verify Workflow Boundary",
+  "description": "",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/04-15-next-cycle-backlog-completion/task.json b/.trellis/tasks/04-15-next-cycle-backlog-completion/task.json
new file mode 100644
index 000000000..c8b09644c
--- /dev/null
+++ b/.trellis/tasks/04-15-next-cycle-backlog-completion/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "next-cycle-backlog-completion",
+  "name": "next-cycle-backlog-completion",
+  "title": "brainstorm: next-cycle backlog completion",
+  "description": "",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-15",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/04-15-stage-17c-explicit-plan-artifact-boundary/prd.md b/.trellis/tasks/04-15-stage-17c-explicit-plan-artifact-boundary/prd.md
new file mode 100644
index 000000000..80a20b84a
--- /dev/null
+++ b/.trellis/tasks/04-15-stage-17c-explicit-plan-artifact-boundary/prd.md
@@ -0,0 +1,134 @@
+# Stage 17C: Explicit Plan Artifact Boundary
+
+## Goal
+
+Add a durable explicit plan artifact boundary that can serve as stable input for later verification workflows, without adding plan-mode UI, coordinator runtime, mailbox, or multi-agent communication.
+
+## Upgraded Function
+
+The workflow system is upgraded from task completion nudges to a store-backed implementation plan artifact.
+
+## Expected Benefit
+
+* Recoverability: plans can be saved and retrieved outside chat history.
+* Testability: verification criteria become required structured data.
+* Maintainability: future verifier subagents can consume a stable artifact instead of parsing arbitrary prose.
+
+## Out of Scope
+
+* EnterPlanMode / ExitPlanMode tools
+* approval UI
+* coordinator runtime
+* mailbox / SendMessage
+* verifier subagent execution
+
+## Requirements
+
+* Add `PlanArtifact`.
+* Add `plan_save` and `plan_get`.
+* Require non-empty verification criteria.
+* Validate referenced `task_ids` exist.
+* Store plans in a namespace separate from tasks.
+* Register plan tools in the main tool surface and capability registry.
+
+## Acceptance Criteria
+
+* [ ] Plan artifacts roundtrip through store.
+* [ ] Plan artifacts reject missing verification criteria.
+* [ ] Plan artifacts reject unknown task IDs.
+* [ ] `plan_save` / `plan_get` are exposed as main tools.
+* [ ] Existing task tools still pass.
+* [ ] Focused tests, full tests, ruff, and mypy pass.
+
+## cc-haha Alignment
+
+### Expected effect
+
+Aligning this behavior should improve workflow discipline, testability, and future verifier readiness.
+
+The local runtime effect is: implementation plans become explicit artifacts with verification criteria, matching cc-haha's plan-file / ExitPlanMode principle without copying its UI or approval runtime.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Plan file | `plans.ts`, plan-mode attachments, and `ExitPlanModeV2Tool` use a persisted plan file as workflow artifact | local workflow has a stable plan artifact | `PlanArtifact` | partial | Implement store-backed artifact now |
+| Verification criteria | plan instructions require a verification section | plan artifact must define how to verify | required `verification` field | align | Implement now |
+| Approval UI | ExitPlanMode asks/coordinates approval | user approval flow | none | defer | Out of scope |
+
+## LangChain Architecture
+
+Use:
+
+* strict Pydantic schemas
+* LangGraph store namespace
+* normal LangChain tools
+
+Avoid:
+
+* prompt-only plan parsing
+* UI approval
+* coordinator/mailbox runtime
+
+## Checkpoint: Stage 17C
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added `PlanArtifact`, `PlanSaveInput`, and `PlanGetInput`.
+- Added plan store helpers:
+  - `PLAN_ROOT_NAMESPACE`
+  - `plan_namespace()`
+  - `create_plan()`
+  - `get_plan()`
+- Added model-visible tools:
+  - `plan_save`
+  - `plan_get`
+- Registered plan tools in `ToolSystemContainer`.
+- Added plan capabilities to `tool_system.capabilities`.
+- Added `plan_get` to verifier subagent allowlist and kept `plan_save` forbidden.
+- Updated task workflow executable spec.
+
+Verification:
+- `pytest -q tests/test_tasks.py tests/test_tool_system_registry.py tests/test_tool_system_middleware.py tests/test_app.py tests/test_subagents.py`
+- `pytest -q`
+- `ruff check src/coding_deepgent/tasks/schemas.py src/coding_deepgent/tasks/store.py src/coding_deepgent/tasks/tools.py src/coding_deepgent/tasks/__init__.py src/coding_deepgent/containers/tool_system.py src/coding_deepgent/tool_system/capabilities.py tests/test_tasks.py tests/test_tool_system_registry.py tests/test_tool_system_middleware.py tests/test_app.py`
+- `mypy src/coding_deepgent/tasks/schemas.py src/coding_deepgent/tasks/store.py src/coding_deepgent/tasks/tools.py src/coding_deepgent/tasks/__init__.py src/coding_deepgent/containers/tool_system.py src/coding_deepgent/tool_system/capabilities.py`
+
+cc-haha alignment:
+- Source files inspected:
+  - `/root/claude-code-haha/src/utils/plans.ts`
+  - `/root/claude-code-haha/src/tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts`
+  - `/root/claude-code-haha/src/utils/attachments.ts`
+  - `/root/claude-code-haha/src/utils/messages.ts`
+- Aligned:
+  - plan artifact is now explicit and requires verification.
+- Deferred:
+  - plan-mode UI
+  - approval flow
+  - coordinator/mailbox runtime
+
+LangChain architecture:
+- Primitive used:
+  - LangChain tools + Pydantic schemas
+  - LangGraph store
+- Why no heavier abstraction:
+  - 17C only establishes the artifact boundary; runtime approval and verifier execution are separate stages.
+
+Boundary findings:
+- New issue handled:
+  - storing plans under the task namespace caused `list_tasks()` to read plan artifacts as tasks because LangGraph store search is prefix-like. Plan artifacts now use a separate `coding_deepgent_plans` root namespace.
+- Residual risk:
+- plan artifacts are saved/retrieved but not yet consumed by verifier execution.
+
+Decision:
+- continue
+
+Reason:
+- Tests, ruff, and mypy passed.
+- Scope stayed non-UI and LangChain-native.
+- No coordinator, mailbox, or multi-agent communication was introduced.
diff --git a/.trellis/tasks/04-15-stage-17c-explicit-plan-artifact-boundary/task.json b/.trellis/tasks/04-15-stage-17c-explicit-plan-artifact-boundary/task.json
new file mode 100644
index 000000000..2120fbab5
--- /dev/null
+++ b/.trellis/tasks/04-15-stage-17c-explicit-plan-artifact-boundary/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-17c-explicit-plan-artifact-boundary",
+  "name": "stage-17c-explicit-plan-artifact-boundary",
+  "title": "Stage 17C: Explicit Plan Artifact Boundary",
+  "description": "",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-15",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/04-15-stage-17d-verifier-subagent-execution-boundary/check.jsonl b/.trellis/tasks/04-15-stage-17d-verifier-subagent-execution-boundary/check.jsonl
new file mode 100644
index 000000000..8ef7b6aa1
--- /dev/null
+++ b/.trellis/tasks/04-15-stage-17d-verifier-subagent-execution-boundary/check.jsonl
@@ -0,0 +1,4 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/src/coding_deepgent/subagents/tools.py", "reason": "Review verifier execution boundary and read-only allowlist"}
+{"file": "coding-deepgent/tests/test_subagents.py", "reason": "Verify new schema/result behavior is covered"}
diff --git a/.trellis/tasks/04-15-stage-17d-verifier-subagent-execution-boundary/debug.jsonl b/.trellis/tasks/04-15-stage-17d-verifier-subagent-execution-boundary/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/04-15-stage-17d-verifier-subagent-execution-boundary/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/04-15-stage-17d-verifier-subagent-execution-boundary/implement.jsonl b/.trellis/tasks/04-15-stage-17d-verifier-subagent-execution-boundary/implement.jsonl
new file mode 100644
index 000000000..4828c638c
--- /dev/null
+++ b/.trellis/tasks/04-15-stage-17d-verifier-subagent-execution-boundary/implement.jsonl
@@ -0,0 +1,3 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": ".trellis/spec/backend/task-workflow-contracts.md", "reason": "Stage 17B-17D workflow contracts, plan boundary, verifier allowlist rules"}
diff --git a/.trellis/tasks/04-15-stage-17d-verifier-subagent-execution-boundary/prd.md b/.trellis/tasks/04-15-stage-17d-verifier-subagent-execution-boundary/prd.md
new file mode 100644
index 000000000..8a3a2d73c
--- /dev/null
+++ b/.trellis/tasks/04-15-stage-17d-verifier-subagent-execution-boundary/prd.md
@@ -0,0 +1,136 @@
+# Stage 17D: Verifier Subagent Execution Boundary
+
+## Goal
+
+Connect the explicit durable plan artifact boundary to the existing bounded verifier subagent surface, so verification can run against a stable plan input without introducing coordinator mode, mailbox, approval UI, or a long-running child-agent runtime.
+
+## Upgraded Function
+
+The workflow system is upgraded from a verification nudge plus retrievable plan artifact to a plan-driven verifier subagent execution boundary.
+
+## Expected Benefit
+
+* Reliability: verification reads a durable plan artifact instead of arbitrary chat prose.
+* Maintainability: verifier invocation semantics become a typed product seam rather than an ad hoc prompt convention.
+* Testability: verifier behavior can be exercised through deterministic schemas and store-backed inputs before a real child runtime is introduced.
+
+## Out of Scope
+
+* coordinator runtime
+* mailbox / SendMessage
+* approval UI
+* background worker execution
+* persistent verifier evidence store
+* automatic task mutation after verifier completion
+
+## Requirements
+
+* Extend the subagent tool schema with an explicit verifier plan reference.
+* Require `plan_id` when `agent_type="verifier"`.
+* Reject verifier execution when the runtime store is unavailable.
+* Resolve the durable plan artifact before verifier execution begins.
+* Surface plan title, verification criteria, and referenced `task_ids` to verifier execution.
+* Keep verifier execution read-only:
+  * verifier allowlist still includes `plan_get`
+  * verifier allowlist still excludes mutating task / plan / edit tools
+* Return a structured verifier result that makes the plan boundary visible to callers.
+* Keep the existing main tool surface unchanged except for the stricter verifier invocation contract.
+
+## Acceptance Criteria
+
+* [ ] `run_subagent` rejects `agent_type="verifier"` without `plan_id`.
+* [ ] `run_subagent` rejects verifier execution when no task store is configured.
+* [ ] verifier execution fails clearly for an unknown plan id.
+* [ ] verifier execution receives durable plan content and verification criteria.
+* [ ] verifier tool schema exposes `plan_id` and still hides runtime-only fields.
+* [ ] verifier allowlist remains read-only and excludes mutating tools.
+* [ ] Focused tests, full tests, ruff, and mypy pass.
+
+## cc-haha Alignment
+
+### Expected effect
+
+Aligning this behavior should improve workflow discipline, verifier readiness, and product parity.
+
+The local runtime effect is: a bounded verifier subagent can be invoked using a durable implementation plan and explicit verification criteria, matching cc-haha's verification-agent principle without copying its coordinator or background execution runtime.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Verification agent | built-in verification agent is adversarial and read-only | local verifier must stay bounded and non-mutating | existing `verifier` subagent type + read-only allowlist | partial | Preserve and tighten now |
+| Plan boundary | plan file can be passed into verification work | local verifier reads a durable plan artifact | `plan_id` on `run_subagent` verifier path | partial | Implement now |
+| Coordinator/background runtime | richer orchestration and approval flow exist upstream | local verifier can execute without heavier workflow runtime | none | defer | Keep out of scope |
+
+## LangChain Architecture
+
+Use:
+
+* strict Pydantic tool schemas
+* existing `run_subagent` tool surface
+* LangGraph store-backed plan lookup
+* small verifier prompt/render helper plus structured result model
+
+Avoid:
+
+* prompt-only verifier plan parsing
+* new orchestration layer
+* mailbox/coordinator abstractions
+* speculative child runtime wrappers
+
+## Technical Approach
+
+* Extend `RunSubagentInput` with optional `plan_id`.
+* Add schema validation requiring `plan_id` for `agent_type="verifier"`.
+* Add a small verifier request/result seam in `coding_deepgent.subagents`.
+* Resolve the durable plan through the existing task store helpers.
+* Render a deterministic verifier work item from:
+  * user task
+  * plan title/content
+  * verification criteria
+  * referenced task IDs
+* Return structured verifier output as JSON from `run_subagent`, while keeping general subagent behavior simple.
+* Extend `tests/test_subagents.py` for:
+  * schema validation
+  * unknown plan/store failures
+  * verifier plan execution payload
+
+## Checkpoint: Stage 17D
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Extended `RunSubagentInput` with explicit `plan_id` support for verifier execution.
+- Added a strict validator path so verifier execution rejects missing plan references.
+- Resolved durable plans inside the verifier subagent path before child execution.
+- Added deterministic verifier work-item rendering from:
+  - original verifier task
+  - plan id/title/content
+  - verification criteria
+  - referenced task ids
+- Added structured verifier result output from `run_subagent` for verifier calls.
+- Preserved the existing read-only verifier allowlist and mutation exclusions.
+- Updated the executable workflow contract for the verifier execution boundary.
+- Added focused verifier subagent tests.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_subagents.py coding-deepgent/tests/test_tasks.py`
+- `pytest -q coding-deepgent/tests/test_tool_system_registry.py coding-deepgent/tests/test_tool_system_middleware.py coding-deepgent/tests/test_app.py`
+- `pytest -q coding-deepgent/tests`
+- `ruff check coding-deepgent/src/coding_deepgent/subagents coding-deepgent/tests/test_subagents.py .trellis/spec/backend/task-workflow-contracts.md`
+- `mypy coding-deepgent/src/coding_deepgent/subagents/schemas.py coding-deepgent/src/coding_deepgent/subagents/tools.py coding-deepgent/tests/test_subagents.py`
+
+Boundary findings:
+- The smallest safe 17D change is to keep verifier execution on the existing `run_subagent` surface instead of introducing a new coordinator or mailbox abstraction.
+- `run_subagent.tool_call_schema()` does not by itself enforce the custom verifier `plan_id` invariant, so the decisive safety check remains on the real execution path.
+- Structured verifier output is now limited to verifier calls; general subagent behavior remains unchanged.
+
+Decision:
+- continue
+
+Reason:
+- Verifier execution now has an explicit durable plan boundary without introducing coordinator/mailbox/UI/runtime expansion.
diff --git a/.trellis/tasks/04-15-stage-17d-verifier-subagent-execution-boundary/task.json b/.trellis/tasks/04-15-stage-17d-verifier-subagent-execution-boundary/task.json
new file mode 100644
index 000000000..f834bd915
--- /dev/null
+++ b/.trellis/tasks/04-15-stage-17d-verifier-subagent-execution-boundary/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-17d-verifier-subagent-execution-boundary",
+  "name": "stage-17d-verifier-subagent-execution-boundary",
+  "title": "Stage 17D: Verifier Subagent Execution Boundary",
+  "description": "",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-15",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-coding-deepgent-highlight-completion-map/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-coding-deepgent-highlight-completion-map/check.jsonl
new file mode 100644
index 000000000..1fe951b28
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-coding-deepgent-highlight-completion-map/check.jsonl
@@ -0,0 +1,2 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-coding-deepgent-highlight-completion-map/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-coding-deepgent-highlight-completion-map/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-coding-deepgent-highlight-completion-map/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-coding-deepgent-highlight-completion-map/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-coding-deepgent-highlight-completion-map/implement.jsonl
new file mode 100644
index 000000000..eb803316b
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-coding-deepgent-highlight-completion-map/implement.jsonl
@@ -0,0 +1,3 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": ".trellis/project-handoff.md", "reason": "Sync handoff to canonical completion map and current stage family"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-coding-deepgent-highlight-completion-map/prd.md b/.trellis/tasks/archive/2026-04/04-15-coding-deepgent-highlight-completion-map/prd.md
new file mode 100644
index 000000000..1754f1632
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-coding-deepgent-highlight-completion-map/prd.md
@@ -0,0 +1,436 @@
+# brainstorm: coding-deepgent highlight completion map
+
+## Goal
+
+Design a bounded completion map for `coding-deepgent` so the remaining work has a visible end. The map should cover H01-H22, state which highlights are product-essential vs deferred/optional, estimate the remaining stage groups, and prevent the roadmap from expanding indefinitely.
+
+## What I already know
+
+* The user wants to pause pure implementation and design the finish line because the current stage stream feels open-ended.
+* The product goal is not a line-by-line cc-haha clone; it is a LangChain-native implementation of cc-haha Agent Harness essence.
+* The current highlight backlog has 22 highlights: H01-H22.
+* Stage 12-19 have focused mostly on context/session/compaction, durable workflow, verifier execution, verifier evidence persistence, and evidence observability.
+* Latest completed stage families:
+  * Stage 12: context and recovery hardening
+  * Stage 13: manual compact boundary / summary artifact
+  * Stage 14A: explicit generated summary CLI wiring
+  * Stage 15: compact persistence semantics
+  * Stage 16: virtual transcript pruning
+  * Stage 17A-D: durable task / plan / verifier boundary
+  * Stage 18A-B: verifier execution and evidence persistence
+  * Stage 19A-B: verifier evidence provenance and lineage
+* Current task list says the parent final-goal brainstorm has 4 completed children out of 19 tracked children, but that is a Trellis task count, not a highlight completion count.
+* Cross-session memory is a persistent product requirement.
+* The user wants future reports to include corresponding highlights, modules, tradeoffs, benefits, and complexity.
+* The user has authorized multi-agent acceleration for suitable later implementation stages.
+
+## Assumptions (temporary)
+
+* The completion map should be a roadmap and stop rule, not a detailed implementation spec for every future function.
+* The map should define an MVP finish line plus optional/deferred bands.
+* The map should preserve benefit-gated complexity: no stage proceeds on “closer to cc” alone.
+* The map should keep H21 bridge/remote/IDE and H22 daemon/cron out of MVP unless the user explicitly chooses a broader product target.
+
+## Open Questions
+
+* None for the current completion-map decision.
+
+## Requirements (evolving)
+
+* Produce an H01-H22 completion map.
+* Use Approach A: MVP Local Agent Harness Core as the canonical finish-line scope.
+* Treat `H12` and `H20` as MVP-limited highlights:
+  * `H12` gets only the smallest required local subagent context snapshot/fork semantics.
+  * `H20` gets only minimal local metrics/counters that directly support runtime/context decisions.
+* For each highlight, record:
+  * status: implemented / partial / missing / deferred / do-not-copy
+  * corresponding `coding_deepgent` modules
+  * MVP completion standard
+  * remaining minimal stage(s), if any
+  * explicit defer/do-not-copy boundary
+* Group remaining work into visible milestone bands.
+* Estimate total remaining stage count under Approach A.
+* Mark which work directly, indirectly, or does not advance cross-session memory.
+* Keep future implementation stages source-backed against cc-haha when they claim cc alignment.
+
+## Acceptance Criteria (evolving)
+
+* [x] The PRD contains a table for H01-H22 with status, modules, completion standard, and remaining work.
+* [x] The PRD defines a recommended finish-line scope and at least two alternatives.
+* [x] The PRD defines milestone groups with estimated remaining stage count.
+* [x] The PRD explicitly marks deferred / out-of-MVP highlights.
+* [x] The PRD includes one decision section after the user chooses scope.
+* [x] The final map is clear enough to guide later `$stage-iterate lean-batch` runs without re-litigating the finish line each time.
+
+## Definition of Done (team quality bar)
+
+* Docs/notes updated if behavior changes.
+* No product code implementation in this brainstorm task.
+* Roadmap decisions are explicit and tied to H01-H22.
+* Deferred scope is documented, not left ambiguous.
+
+## Out of Scope (explicit)
+
+* Implementing Stage 20 code.
+* Full source-level design for every future stage.
+* Re-reading all cc-haha source for every highlight in this brainstorm.
+* Committing to UI/TUI clone, remote bridge, daemon, marketplace, or background worker parity without explicit scope approval.
+
+## Technical Notes
+
+* Primary roadmap: `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+* Current handoff: `.trellis/project-handoff.md`
+* Recent checkpoints:
+  * `.trellis/tasks/04-15-stage-18a-verifier-execution-integration/prd.md`
+  * `.trellis/tasks/04-15-stage-18b-verifier-result-persistence-evidence-integration/prd.md`
+  * `.trellis/tasks/04-15-stage-19-evidence-observability-agent-lifecycle-hardening/prd.md`
+* Active backend contracts:
+  * `.trellis/spec/backend/runtime-context-compaction-contracts.md`
+  * `.trellis/spec/backend/task-workflow-contracts.md`
+
+## Research Notes
+
+### Constraints from our repo/project
+
+* The project already has domain modules for tools, permissions, sessions, memory, compact, tasks, subagents, MCP/plugins, hooks, and prompting.
+* The current implementation has a working session JSONL ledger, recovery brief, compact records, durable task graph, plan artifacts, verifier child-agent path, and verifier evidence metadata.
+* The project deliberately uses LangChain/LangGraph primitives rather than custom query runtime cloning.
+* The current fast workflow works best when stages are small, source-backed, and checkpointed.
+
+### Feasible finish-line approaches
+
+**Approach A: MVP Local Agent Harness Core** (Recommended)
+
+* How it works:
+  Finish a strong local coding-agent harness: tools, permission, prompt/context, session/compact/memory, todo/task/plan/verify, bounded subagents, MCP/plugin basics, hooks, and observability. Defer remote bridge, daemon/cron, marketplace/install, full coordinator/mailbox runtime, and provider-specific cache parity unless later justified.
+* Pros:
+  Gives a visible finish line in the shortest credible time. Matches the current product direction and avoids speculative infrastructure.
+* Cons:
+  Some cc-haha team/background/runtime features remain explicitly deferred.
+* Rough remaining work:
+  10-16 narrow stages after Stage 19, depending on how much H11/H12/H19 is deepened.
+
+**Approach B: Full Local Core Including Agent Team Runtime**
+
+* How it works:
+  Complete Approach A, then add task-backed agent lifecycle, mailbox / SendMessage, coordinator synthesis, richer fork/cache-aware subagent execution, and deeper runtime-event evidence.
+* Pros:
+  Stronger H11-H14 parity and closer to cc-haha multi-agent essence.
+* Cons:
+  More architecture risk and more stage count; likely requires careful new contracts for agent lifecycle and message stores.
+* Rough remaining work:
+  18-28 narrow stages after Stage 19.
+
+**Approach C: Broad cc-haha Product Parity Track**
+
+* How it works:
+  Include local core plus extension marketplace/install flows, bridge/IDE/remote control plane, daemon/cron/proactive automation, and richer provider-specific cost/cache instrumentation.
+* Pros:
+  Broadest parity story.
+* Cons:
+  Highest risk of losing product focus; includes several capabilities that the current roadmap says should not be prioritized without explicit product goals.
+* Rough remaining work:
+  30+ stages and likely multiple roadmap cycles.
+
+## Draft Completion Map
+
+Status vocabulary:
+
+* `implemented`: enough for MVP unless a later audit finds a defect.
+* `partial`: useful implementation exists, but known MVP completion work remains.
+* `missing`: planned for MVP but not implemented enough.
+* `deferred`: valid cc-haha behavior, outside the recommended MVP.
+* `do-not-copy`: not a local product goal or wrong abstraction.
+
+| ID | Highlight | Current status | MVP target | Modules | Remaining MVP work |
+|---|---|---|---|---|---|
+| H01 | Tool-first capability runtime | partial | strict tool schemas + capability metadata + guarded execution for all model-facing capabilities | `tool_system`, domain `tools.py` | audit all current tools; close schema/metadata gaps |
+| H02 | Permission runtime and hard safety | partial | deterministic local policy with safe defaults, trusted dirs, hook integration, and explicit denied/ask behavior | `permissions`, `tool_system`, `filesystem`, `hooks` | permission mode/rule audit; hard safety tests |
+| H03 | Layered prompt contract | partial | stable base prompt + structured dynamic context surfaces, no giant tool manual | `prompting`, `runtime`, `memory`, `compact` | prompt/context audit and cache-aware stable/dynamic split |
+| H04 | Dynamic context protocol | partial | typed/bounded context payload assembly for memory, recovery, compaction, skills/resources | `runtime`, `sessions`, `memory`, `compact`, `skills`, `mcp` | consolidate context assembly contracts |
+| H05 | Progressive context pressure management | partial | deterministic projection, compact records, latest valid compact selection, tool-result invariants | `compact`, `sessions`, `runtime` | audit current Stage 12-16 gaps; maybe one hardening stage |
+| H06 | Session transcript, evidence, and resume | partial-strong | session JSONL, evidence, compacts, recovery brief, compacted resume continuity | `sessions`, `runtime`, `cli_service` | likely one audit/CLI evidence inspection stage |
+| H07 | Scoped cross-session memory | partial | controlled `save_memory`, quality policy, scoped recall, no knowledge dumping | `memory`, `runtime`, `sessions` | deepen recall/write contracts; optional auto extraction deferred |
+| H08 | TodoWrite short-term planning | implemented/partial | strict TodoWrite contract with state updates and prompt guidance, separate from durable Task | `todo`, `runtime`, `prompting` | final contract audit only |
+| H09 | Durable Task graph | partial-strong | validated graph, readiness, plan artifacts, verification nudge, no todo conflation | `tasks`, `tool_system` | persistence/checkpointer integration decision; maybe audit |
+| H10 | Plan / Execute / Verify discipline | partial-strong | explicit plan artifact, verifier child execution, persisted verifier evidence | `tasks`, `subagents`, `sessions` | optional runtime-event evidence; no coordinator by default |
+| H11 | Agent as tool/runtime object | partial | all subagents enter as tools, verifier has bounded child runtime and evidence lineage | `subagents`, `runtime`, `tasks`, `sessions` | decide whether MVP needs general subagent lifecycle beyond verifier |
+| H12 | Fork/cache-aware subagent execution | deferred/partial | minimal context snapshot/fork semantics only if H11 lifecycle needs it | `subagents`, `runtime`, `compact` | likely defer provider-specific cache parity |
+| H13 | Mailbox / SendMessage | deferred | out of MVP unless full agent-team scope chosen | `tasks`, `subagents` | no MVP work under Approach A |
+| H14 | Coordinator keeps synthesis | deferred | principle documented; implementation out of MVP unless full agent-team scope chosen | `tasks`, `subagents`, `prompting` | no MVP work under Approach A |
+| H15 | Skill system packaging | partial | local skill loader/tool, bounded context injection, no marketplace | `skills`, `tool_system`, `prompting` | source-backed skill audit; maybe one hardening stage |
+| H16 | MCP external capability protocol | partial-strong | local MCP config/loading seam, tool/resource separation, capability policy | `mcp`, `plugins`, `tool_system` | Stage 11 audit; avoid broad installer |
+| H17 | Plugin states | partial/deferred | local manifest validation and enable/source state only | `plugins`, `skills`, `mcp` | clarify MVP manifest state; marketplace deferred |
+| H18 | Hooks as middleware | partial | lifecycle hooks through safe middleware boundaries, not backdoors | `hooks`, `tool_system`, `runtime` | hook event/evidence audit; no remote hook platform |
+| H19 | Observability/evidence ledger | partial-strong | structured local events + session evidence + recovery visibility | `runtime`, `sessions`, `tool_system`, `subagents` | runtime-event evidence gate, evidence CLI inspection optional |
+| H20 | Cost/cache instrumentation | deferred/partial | local metrics only, no provider-specific cache parity in MVP | `compact`, `runtime`, `sessions` | maybe minimal counters; rich cache deferred |
+| H21 | Bridge / remote / IDE | deferred | out of MVP | future integration boundary | no MVP work |
+| H22 | Daemon / cron / proactive automation | deferred | out of MVP | future scheduling boundary | no MVP work |
+
+## Draft Milestone Groups
+
+### M1: Core Audit And Closeout
+
+Goal: mark H01-H10 as implemented / partial / deferred with no hidden gaps.
+
+Likely stages:
+
+* Tool/permission surface audit: H01/H02
+* Prompt/context closeout: H03/H04
+* Context pressure closeout: H05/H06
+* Memory quality and recall closeout: H07
+* Todo/task/plan final audit: H08/H09/H10
+
+Estimate: 5-7 narrow stages.
+
+### M2: Agent / Evidence Minimal Runtime
+
+Goal: finish the recommended MVP version of H11/H19 without coordinator/mailbox/background runtime.
+
+Likely stages:
+
+* Runtime-event evidence gate: H19
+* Decide general subagent lifecycle MVP boundary: H11
+* Optional evidence CLI inspection: H06/H19
+
+Estimate: 2-4 narrow stages.
+
+### M3: Extension Platform Closeout
+
+Goal: ensure skills, MCP, plugins, hooks are safe local extension surfaces.
+
+Likely stages:
+
+* Skill packaging audit/hardening: H15
+* MCP/plugin loading audit/hardening: H16/H17
+* Hook middleware lifecycle audit/hardening: H18
+
+Estimate: 3-5 narrow stages.
+
+### M4: Explicit Deferral / Product Boundary
+
+Goal: document what is intentionally outside MVP so the project ends cleanly.
+
+Likely stages:
+
+* H12/H13/H14 full agent-team deferral or next-cycle spec
+* H20 local metrics decision
+* H21/H22 do-not-prioritize boundary
+
+Estimate: 1-3 documentation/spec stages.
+
+## Draft Remaining Stage Estimate
+
+Recommended Approach A:
+
+* Remaining implementation/audit stages after Stage 19: 10-16
+* Expected final stage number: roughly Stage 30-36
+* Finish means H01-H22 all have explicit statuses and MVP-relevant highlights are implemented or intentionally scoped down.
+
+Approach B:
+
+* Remaining stages after Stage 19: 18-28
+* Expected final stage number: roughly Stage 38-48
+* Finish means full local agent-team runtime is included.
+
+Approach C:
+
+* Remaining stages after Stage 19: 30+
+* Expected final stage number: Stage 50+
+* Finish means broad parity track, not recommended for the current product goal.
+
+## Decision (ADR-lite)
+
+**Context**: The existing stage stream was making progress, but the finish line was not visible. The user wants a concrete completion target before continuing implementation.
+
+**Decision**: Use **Approach A: MVP Local Agent Harness Core** as the canonical completion scope for the next phase.
+
+**Consequences**:
+
+* The MVP finish line is a complete local LangChain-native Agent Harness, not full cc-haha product parity.
+* Remaining work is estimated at **10-16 narrow stages after Stage 19**, with a rough final range of **Stage 30-36**.
+* H13 mailbox, H14 coordinator runtime, H21 bridge/remote/IDE, and H22 daemon/cron are not part of MVP.
+* H12 fork/cache-aware subagent behavior and H20 cost/cache instrumentation are part of MVP only in minimal local forms:
+  * H12: bounded subagent context snapshot/fork semantics only when needed by the local runtime
+  * H20: local counters/metrics only when they directly help context/runtime decisions
+* Future `$stage-iterate` work should choose stages from the milestone groups below and update this completion map when a highlight status changes.
+
+## Approach A MVP Completion Plan
+
+### MVP Must Finish
+
+These highlights must be implemented or closed out with tests/contracts:
+
+* H01 Tool-first capability runtime
+* H02 Permission runtime and hard safety
+* H03 Layered prompt contract
+* H04 Dynamic context protocol
+* H05 Progressive context pressure management
+* H06 Session transcript, evidence, and resume
+* H07 Scoped cross-session memory
+* H08 TodoWrite short-term planning
+* H09 Durable Task graph
+* H10 Plan / Execute / Verify workflow discipline
+* H11 Agent as tool/runtime object, MVP-bounded
+* H15 Skill system packaging, local-only
+* H16 MCP external capability protocol, local-only
+* H17 Plugin states, local manifest only
+* H18 Hooks as middleware
+* H19 Observability/evidence ledger
+
+### MVP Limited / Minimal
+
+These get only the smallest local slice needed by the MVP:
+
+* H12 Fork/cache-aware subagent execution: minimal context snapshot semantics only if required by H11.
+* H20 Cost/cache instrumentation: local counters/metrics only if they support context/compact decisions.
+
+### Out Of MVP / Deferred
+
+These are valid future roadmap items, but not part of the current finish line:
+
+* H13 Mailbox / SendMessage multi-agent communication
+* H14 Coordinator keeps synthesis
+* H21 Bridge / remote / IDE control plane
+* H22 Daemon / cron / proactive automation
+
+## Final MVP Boundary
+
+### Included In MVP
+
+* H01-H11
+* H15-H19
+* H12 minimal local slice
+* H20 minimal local slice
+
+### Explicitly Not In MVP
+
+* H13 full mailbox / SendMessage runtime
+* H14 coordinator synthesis runtime
+* H21 bridge / remote / IDE control plane
+* H22 daemon / cron / proactive automation
+
+### Stop Rule
+
+The MVP is complete when:
+
+* Every H01-H22 row has an explicit status.
+* Every MVP-included row is either:
+  * `implemented`, or
+  * `partial` with an explicit, accepted minimal boundary that is already covered by tests/contracts.
+* Every non-MVP row is explicitly `deferred` or `do-not-copy`.
+* No remaining open stage exists unless it maps to an MVP-included row and has a concrete benefit statement.
+
+## Recommended Next Stage Sequence
+
+1. Stage 20: Highlight status audit and closeout table hardening
+   * Goal: turn this draft map into the canonical progress dashboard.
+   * Highlights: H01-H22 all.
+   * Output: final status table with `implemented / partial / missing / deferred / do-not-copy`.
+
+2. Stage 21: Tool and permission closeout
+   * Highlights: H01/H02.
+   * Modules: `tool_system`, `permissions`, `filesystem`, domain tools.
+
+3. Stage 22: Prompt and dynamic context closeout
+   * Highlights: H03/H04.
+   * Modules: `prompting`, `runtime`, `memory`, `sessions`.
+
+4. Stage 23: Context pressure and session continuity closeout
+   * Highlights: H05/H06.
+   * Modules: `compact`, `sessions`, `runtime`.
+
+5. Stage 24: Scoped memory closeout
+   * Highlights: H07.
+   * Modules: `memory`, `runtime`, `sessions`.
+
+6. Stage 25: Todo/task/plan/verify closeout
+   * Highlights: H08/H09/H10.
+   * Modules: `todo`, `tasks`, `subagents`, `sessions`.
+
+7. Stage 26: MVP-bounded agent-as-tool closeout
+   * Highlights: H11 with limited H12.
+   * Modules: `subagents`, `runtime`, `tasks`, `sessions`.
+
+8. Stage 27: Local extension platform closeout
+   * Highlights: H15/H16/H17/H18.
+   * Modules: `skills`, `mcp`, `plugins`, `hooks`, `tool_system`.
+
+9. Stage 28: Observability and evidence closeout
+   * Highlights: H19 with minimal H20 decision.
+   * Modules: `runtime`, `sessions`, `tool_system`.
+
+10. Stage 29: Deferred-boundary ADR and MVP release checklist
+    * Highlights: H12/H13/H14/H20/H21/H22.
+    * Output: explicit MVP/non-MVP boundary.
+
+11. Stage 30-36 reserve
+    * Buffer for gaps found during closeout audits.
+    * Rule: every reserve stage must map to an existing H row and have a concrete benefit gate.
+
+## Expansion Sweep
+
+### Future evolution
+
+* The map can become the canonical progress dashboard for H01-H22.
+* Deferred agent-team, remote, and daemon capabilities can become a second roadmap instead of leaking into MVP.
+
+### Related scenarios
+
+* Every later `$stage-iterate` report should name the highlight row it advances.
+* Checkpoints should update this map when a highlight status changes.
+
+### Failure / edge cases
+
+* Risk: over-classifying partial highlights as done. Mitigation: every implemented status needs tests/contracts or a source-backed audit note.
+* Risk: roadmap grows as more cc-haha details are discovered. Mitigation: newly discovered behavior must map to an existing H row or become explicit next-cycle/deferred scope.
+
+## Checkpoint: Stage 20
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Promoted `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md` from a planning backlog into the canonical MVP dashboard.
+- Fixed the MVP boundary for Approach A:
+  - include H01-H11, H15-H19
+  - include minimal H12/H20
+  - defer H13/H14/H21/H22
+- Added the canonical H01-H22 status table with:
+  - current status
+  - MVP boundary
+  - main modules
+  - next / remaining stage
+- Added milestone groups M1-M4 and explicit Stage 21-29 sequencing plus Stage 30-36 reserve.
+- Added a stop rule so no future stage is valid unless it maps to an existing H row and has a concrete benefit statement.
+
+Corresponding highlights:
+- All H01-H22 as a planning/control surface.
+- This stage does not implement product runtime behavior directly; it defines the bounded finish line for all remaining runtime work.
+
+Corresponding modules:
+- `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+- `.trellis/tasks/04-15-coding-deepgent-highlight-completion-map/prd.md`
+- `.trellis/project-handoff.md`
+
+Tradeoff / complexity:
+- Chosen: a bounded completion map instead of a full low-level design for every future feature.
+- Deferred: detailed function-by-function designs for later stages until they become active.
+- Why this complexity is worth it now: the user needs a visible finish line, and later stage work must stop expanding arbitrarily.
+
+Verification:
+- Acceptance criteria in this PRD are now satisfied.
+- Trellis task context for this task is initialized and validated as the current stage ledger.
+
+Boundary findings:
+- “Task count” and “highlight completion” are different dimensions; the canonical dashboard resolves that ambiguity.
+- H12 and H20 need explicit minimal-MVP handling, otherwise they keep re-opening scope discussions.
+
+Decision:
+- continue
+
+Reason:
+- Stage 20 is complete and Stage 21 is now well-scoped: H01/H02 tool + permission closeout is the next direct milestone from the canonical dashboard.
diff --git a/.trellis/tasks/archive/2026-04/04-15-coding-deepgent-highlight-completion-map/task.json b/.trellis/tasks/archive/2026-04/04-15-coding-deepgent-highlight-completion-map/task.json
new file mode 100644
index 000000000..618b8ee4c
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-coding-deepgent-highlight-completion-map/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "coding-deepgent-highlight-completion-map",
+  "name": "coding-deepgent-highlight-completion-map",
+  "title": "brainstorm: coding-deepgent highlight completion map",
+  "description": "Stage 20 canonical H01-H22 MVP dashboard and finish-line map.",
+  "status": "completed",
+  "dev_type": "backend",
+  "scope": "coding-deepgent MVP completion map and canonical highlight dashboard",
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-15",
+  "completedAt": "2026-04-15",
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 3,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "Stage 20 approved: canonical H01-H22 dashboard, MVP boundary, milestone groups, and stop rule are established.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-18a-verifier-execution-integration/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-18a-verifier-execution-integration/check.jsonl
new file mode 100644
index 000000000..43bd7fba2
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-18a-verifier-execution-integration/check.jsonl
@@ -0,0 +1,3 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_subagents.py", "reason": "Cover verifier execution integration and preserve general subagent behavior."}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-18a-verifier-execution-integration/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-18a-verifier-execution-integration/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-18a-verifier-execution-integration/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-18a-verifier-execution-integration/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-18a-verifier-execution-integration/implement.jsonl
new file mode 100644
index 000000000..21f965465
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-18a-verifier-execution-integration/implement.jsonl
@@ -0,0 +1,3 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/src/coding_deepgent/subagents/tools.py", "reason": "Wire real bounded verifier execution into run_subagent."}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-18a-verifier-execution-integration/prd.md b/.trellis/tasks/archive/2026-04/04-15-stage-18a-verifier-execution-integration/prd.md
new file mode 100644
index 000000000..7b26a314e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-18a-verifier-execution-integration/prd.md
@@ -0,0 +1,169 @@
+# Stage 18A: Verifier Execution Integration
+
+## Goal
+
+Upgrade the explicit verifier boundary from a structured contract-only seam to a real bounded verifier execution path on the existing `run_subagent` tool surface.
+
+## Upgraded Function
+
+The workflow system is upgraded from verifier plan-boundary plumbing to actual synchronous verifier execution using a read-only child agent invocation.
+
+## Expected Benefit
+
+* Product behavior: verifier calls now perform real verification work instead of returning a placeholder acceptance string.
+* Reliability: the verifier runs against the durable plan boundary with a fixed read-only tool pool and explicit system instructions.
+* Testability: execution wiring becomes locally testable without adding coordinator runtime, mailbox state, or background workers.
+
+## Out of Scope
+
+* coordinator runtime
+* mailbox / SendMessage
+* background worker execution
+* approval UI
+* automatic task mutation after verifier completion
+* general subagent runtime deepening beyond verifier execution
+* task-backed local agent lifecycle objects
+
+## Requirements
+
+* Keep `run_subagent` as the only model-visible entrypoint for verifier execution.
+* Keep verifier execution synchronous and explicitly bounded to the current tool call.
+* Execute verifier work through a real child-agent invocation instead of a placeholder string.
+* Reuse the existing durable plan lookup and rendered verifier task payload from Stage 17D.
+* Restrict the verifier child tool pool to the existing read-only allowlist:
+  * `read_file`
+  * `glob`
+  * `grep`
+  * `task_get`
+  * `task_list`
+  * `plan_get`
+* Keep mutating tools unavailable to the verifier child:
+  * no file edits
+  * no task / plan mutation
+  * no memory writes
+  * no nested `run_subagent`
+* Use a verifier-specific system prompt that preserves the read-only/adversarial verification role.
+* Preserve the existing structured `VerifierSubagentResult` output contract.
+* Keep the general subagent path unchanged for now.
+
+## Acceptance Criteria
+
+* [x] verifier execution uses a real child-agent invocation when no test-only child factory is injected.
+* [x] verifier child receives only the read-only allowlisted tools.
+* [x] verifier child uses a verifier-specific system prompt instead of the generic placeholder behavior.
+* [x] verifier execution stays synchronous and does not introduce coordinator/background runtime.
+* [x] `run_subagent` still returns parseable `VerifierSubagentResult` JSON for verifier calls.
+* [x] general subagent behavior remains unchanged.
+* [x] Focused tests, targeted lint, and targeted mypy pass.
+
+## cc-haha Alignment
+
+### Expected effect
+
+Aligning this behavior should improve reliability, testability, and product parity. The local runtime effect is: verifier calls now execute as a real read-only verification agent with bounded tools and explicit verifier instructions, while intentionally deferring cc-haha's richer background/team runtime.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Verification agent role | built-in verification agent has a dedicated adversarial read-only prompt | verifier execution is harder to silently collapse into a friendly placeholder | verifier-specific child system prompt | partial | Align role now with a smaller prompt |
+| Agent as tool | verification runs through the `AgentTool` path instead of prompt-only narration | local verifier should execute through the model/tool runtime, not just return acceptance text | real child invocation behind `run_subagent` | partial | Implement now on current tool surface |
+| Disallowed mutating tools | verification agent excludes editing/writing/agent-recursion tools | local verifier remains safely read-only | fixed allowlist + forbidden mutation surfaces | align | Preserve and enforce |
+| Background runtime | upstream verifier can run with richer task/runtime lifecycle | local runtime should stay synchronous and bounded for now | none | defer | Keep out of scope |
+
+### Source files inspected
+
+* `/root/claude-code-haha/src/tools/AgentTool/built-in/verificationAgent.ts`
+* `/root/claude-code-haha/src/tools/AgentTool/runAgent.ts`
+
+## LangChain Architecture
+
+Use:
+
+* `create_agent` for the bounded verifier child invocation
+* existing tool objects with a fixed read-only subset
+* existing runtime context/store plumbing where needed
+* a small verifier execution helper rather than a new orchestration layer
+
+Avoid:
+
+* coordinator/mailbox abstractions
+* background execution wrappers
+* prompt-only fake verifier execution
+* speculative task-object runtime layers
+
+## Technical Approach
+
+* Keep the existing Stage 17D verifier plan rendering path.
+* Add a small verifier execution helper that:
+  * builds the fixed read-only tool subset
+  * applies a verifier-specific system prompt
+  * invokes a bounded child agent synchronously
+  * extracts the final verifier text response
+* Keep the test-only `child_agent_factory` seam for direct unit tests.
+* Add focused tests for:
+  * verifier execution integration path
+  * exact verifier child tool set
+  * verifier prompt/runtime wiring
+  * unchanged general subagent behavior
+
+## Checkpoint: Stage 18A
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Replaced the verifier placeholder acceptance path with a real synchronous child-agent invocation on the existing `run_subagent` verifier branch.
+- Added a fixed verifier child tool map limited to:
+  - `read_file`
+  - `glob`
+  - `grep`
+  - `task_get`
+  - `task_list`
+  - `plan_get`
+- Added a verifier-specific read-only system prompt.
+- Derived a bounded child runtime invocation with a verifier-specific agent name and thread id suffix.
+- Preserved the Stage 17D durable plan lookup, rendered verifier task payload, and structured `VerifierSubagentResult` output.
+- Preserved the existing general subagent behavior and the test-only `child_agent_factory` seam.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_subagents.py`
+- `pytest -q coding-deepgent/tests/test_tasks.py`
+- `pytest -q coding-deepgent/tests/test_tool_system_registry.py`
+- `pytest -q coding-deepgent/tests/test_app.py`
+- `ruff check coding-deepgent/src/coding_deepgent/subagents/tools.py coding-deepgent/src/coding_deepgent/subagents/schemas.py coding-deepgent/tests/test_subagents.py`
+- `mypy coding-deepgent/src/coding_deepgent/subagents/tools.py coding-deepgent/src/coding_deepgent/subagents/schemas.py coding-deepgent/tests/test_subagents.py`
+
+cc-haha alignment:
+- Source files inspected:
+  - `/root/claude-code-haha/src/tools/AgentTool/built-in/verificationAgent.ts`
+  - `/root/claude-code-haha/src/tools/AgentTool/runAgent.ts`
+- Aligned:
+  - verifier now executes as a real read-only agent/tool path rather than a prompt-only placeholder.
+  - verifier keeps a dedicated verification-role system prompt and a bounded read-only tool surface.
+- Deferred:
+  - coordinator/background runtime
+  - mailbox/message passing
+  - richer task-backed local-agent lifecycle
+
+LangChain architecture:
+- Primitive used:
+  - `create_agent`
+  - fixed tool subset
+  - `ToolGuardMiddleware`
+  - existing runtime/store plumbing
+- Why no heavier abstraction:
+  - 18A only needs a bounded execution seam on the existing tool path; coordinator/task-object runtime remains outside scope.
+
+Boundary findings:
+- Importing the shared app runtime helper into the subagent module created a circular import through the tool container, so verifier execution now keeps a local invocation boundary.
+- Verifier execution currently builds a fresh model for each verifier call; sharing parent-model/runtime optimization is a later concern and not needed for the current bounded stage.
+
+Decision:
+- continue
+
+Reason:
+- Stage 18A is implemented on the branch, the focused verifier/task/app/tool-surface checks passed on the current checkout, and Stage 18B is now defined as the next narrow verifier/runtime step.
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-18a-verifier-execution-integration/task.json b/.trellis/tasks/archive/2026-04/04-15-stage-18a-verifier-execution-integration/task.json
new file mode 100644
index 000000000..8fee7f6e1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-18a-verifier-execution-integration/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-18a-verifier-execution-integration",
+  "name": "stage-18a-verifier-execution-integration",
+  "title": "Stage 18A: Verifier Execution Integration",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-15",
+  "completedAt": "2026-04-15",
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-18b-verifier-result-persistence-evidence-integration/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-18b-verifier-result-persistence-evidence-integration/check.jsonl
new file mode 100644
index 000000000..5fcffb49b
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-18b-verifier-result-persistence-evidence-integration/check.jsonl
@@ -0,0 +1,4 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_sessions.py", "reason": "Session evidence roundtrip and recovery brief expectations"}
+{"file": "coding-deepgent/tests/test_subagents.py", "reason": "Focused verifier behavior and evidence persistence tests"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-18b-verifier-result-persistence-evidence-integration/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-18b-verifier-result-persistence-evidence-integration/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-18b-verifier-result-persistence-evidence-integration/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-18b-verifier-result-persistence-evidence-integration/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-18b-verifier-result-persistence-evidence-integration/implement.jsonl
new file mode 100644
index 000000000..55e625ae4
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-18b-verifier-result-persistence-evidence-integration/implement.jsonl
@@ -0,0 +1,4 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/src/coding_deepgent/subagents/tools.py", "reason": "Stage 18B verifier result parsing and bounded evidence persistence"}
+{"file": "coding-deepgent/src/coding_deepgent/sessions/", "type": "directory", "reason": "Existing session evidence ledger and recovery brief path"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-18b-verifier-result-persistence-evidence-integration/prd.md b/.trellis/tasks/archive/2026-04/04-15-stage-18b-verifier-result-persistence-evidence-integration/prd.md
new file mode 100644
index 000000000..a08e9e80a
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-18b-verifier-result-persistence-evidence-integration/prd.md
@@ -0,0 +1,193 @@
+# Stage 18B: Verifier Result Persistence and Evidence Integration
+
+## Goal
+
+Persist bounded verifier outcomes from `run_subagent` into the existing session evidence ledger, so verification work survives chat history boundaries and appears in recovery/resume context without introducing coordinator runtime, mailbox state, or automatic task mutation.
+
+## Function Summary
+
+This stage adds one concrete function:
+
+* when a verifier subagent returns `VERDICT: PASS|FAIL|PARTIAL`, that verifier outcome is written into the current session's durable evidence ledger so later resume/recovery flows can see it again
+
+## Upgraded Function
+
+The workflow system is upgraded from real synchronous verifier execution to durable verifier result recording in the existing session transcript/evidence model.
+
+## Expected Benefit
+
+* Recoverability: verifier outcomes survive beyond the immediate tool return and can reappear in session recovery briefs.
+* Reliability: the product gets a durable audit trail for verifier verdicts instead of relying on the parent agent to restate them accurately.
+* Testability: verifier execution can be checked end-to-end through a concrete persisted evidence record instead of only an in-memory JSON result.
+
+## Cross-Session Memory Impact
+
+Direct, but narrow.
+
+* This stage improves cross-session continuity because verifier results will persist across resume/recovery boundaries.
+* This stage does not yet implement the full cross-session memory system.
+* It is still worth doing now because it strengthens a real durable memory path that already exists locally: session evidence.
+
+## Out of Scope
+
+* automatic task status mutation from verifier verdicts
+* coordinator runtime
+* mailbox / SendMessage
+* background worker execution
+* separate verifier evidence store outside the existing session JSONL ledger
+* deepening the general subagent path
+* richer verifier artifact formats beyond the current session evidence record
+
+## Requirements
+
+* Keep `run_subagent` as the only model-visible verifier entrypoint.
+* Preserve the existing `VerifierSubagentResult` JSON contract.
+* After verifier execution succeeds, append one session evidence record for the verifier result when session recording context is available.
+* Use the existing session evidence ledger rather than creating a new verifier-specific persistence mechanism.
+* Persist the verifier result with:
+  * `kind="verification"`
+  * a status derived from the verifier verdict
+  * a concise summary derived from the verifier content
+  * metadata that includes at least `plan_id` and verifier verdict
+* Keep persistence explicit and bounded to the same synchronous tool call.
+* Do not mutate durable tasks or plans based on the recorded verifier result.
+* Keep general subagent behavior unchanged.
+
+## Why Now
+
+* `18A` already made verifier execution real; without persistence, verifier conclusions still disappear too easily after the tool return.
+* This is the smallest next step that improves cross-session memory without introducing a larger coordinator or task-lifecycle runtime.
+
+## Acceptance Criteria
+
+* [x] verifier calls append exactly one evidence record to the current recorded session when session recording is available.
+* [x] persisted verifier evidence roundtrips through `JsonlSessionStore.load_session()`.
+* [x] verifier evidence appears in the existing recovery brief / session evidence path without extra ad hoc rendering seams.
+* [x] verifier evidence status is derived deterministically from `VERDICT: PASS|FAIL|PARTIAL`.
+* [x] verifier calls without usable session recording context fail or skip in one explicit, tested way rather than silently pretending to persist.
+* [x] general subagent behavior and verifier JSON return contract remain unchanged.
+* [x] Focused tests, targeted lint, and targeted mypy pass.
+
+## cc-haha Alignment
+
+### Expected effect
+
+Aligning this behavior should improve recoverability, reliability, and product parity. The local runtime effect is: verifier work no longer disappears after the tool return, and the session ledger gains a durable verification trail while intentionally deferring cc-haha's richer background/task lifecycle.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Verification agent output | verification agent requires an explicit `VERDICT: PASS|FAIL|PARTIAL` line | local persistence can derive deterministic verifier status from a bounded textual contract | verdict parser + evidence status mapping | partial | Align now using existing verifier output contract |
+| Agent runtime persistence | subagent/session runtime writes transcript material under session storage | verifier outcome should survive the immediate tool return | append verifier evidence into session JSONL ledger | partial | Reuse existing session evidence path now |
+| Background/task lifecycle | upstream runtime has richer local-agent task state and summaries | local product should avoid task-object/runtime expansion for this stage | none | defer | Keep out of scope |
+
+### Source files inspected
+
+* `/root/claude-code-haha/src/tools/AgentTool/built-in/verificationAgent.ts`
+* `/root/claude-code-haha/src/tools/AgentTool/runAgent.ts`
+* `/root/claude-code-haha/src/utils/sessionStorage.ts`
+
+## LangChain Architecture
+
+Use:
+
+* the existing `run_subagent` verifier path
+* the existing session JSONL evidence model
+* a small verifier-result persistence helper with explicit seams
+
+Avoid:
+
+* global hidden workflow mutation
+* new coordinator/mailbox abstractions
+* a second verifier persistence store
+* deepening the general subagent runtime just to record verifier outcomes
+
+## Technical Approach
+
+* Reuse the Stage 18A verifier execution path and structured result contract.
+* Add a small verifier result parser that extracts:
+  * terminal verdict
+  * concise summary text for session evidence
+* Add a bounded persistence helper that records verifier evidence through the existing session store seam for the active session/workdir.
+* Keep the persistence seam explicit rather than scattering session writes inside generic tool or middleware code.
+* Add focused tests for:
+  * verdict-to-evidence status mapping
+  * verifier evidence append + session roundtrip
+  * recovery brief exposure of verifier evidence
+  * unchanged general subagent behavior
+
+## Checkpoint: Stage 18B
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added optional `session_context` to `RuntimeContext` and threaded it through the app/runtime invocation path when `run_prompt_with_recording()` has an active recorded session.
+- Tightened the verifier child prompt to require a final `VERDICT: PASS|FAIL|PARTIAL` line.
+- Added deterministic verifier verdict parsing and evidence summary derivation.
+- Added bounded verifier evidence persistence on the `run_subagent` verifier tool path.
+- Persisted verifier evidence through the existing `JsonlSessionStore.append_evidence()` ledger with:
+  - `kind="verification"`
+  - `status` mapped as `PASS -> passed`, `FAIL -> failed`, `PARTIAL -> partial`
+  - `subject=<plan_id>`
+  - metadata containing `plan_id`, `plan_title`, `verdict`, `task_ids`, and `tool_allowlist`
+- Preserved the existing `VerifierSubagentResult` JSON contract and general subagent behavior.
+- Updated backend task/session contracts for the runtime `session_context` and verifier evidence persistence behavior.
+
+Corresponding highlights:
+- `H10 Plan / Execute / Verify workflow discipline`: verifier results are now durable workflow evidence instead of only immediate tool output.
+- `H11 Agent as tool and runtime object`: verifier still enters only through `run_subagent`, with a bounded child-agent path and structured result protocol.
+- `H19 Observability and evidence ledger`: verifier verdicts now enter the session evidence ledger.
+- `H06 Session transcript, evidence, and resume`: verifier evidence roundtrips through session load and appears in recovery brief rendering.
+
+Corresponding modules:
+- `coding_deepgent.subagents`: verifier prompt, verdict parser, evidence summary, and `run_subagent` persistence hook.
+- `coding_deepgent.runtime`: optional `RuntimeContext.session_context` boundary.
+- `coding_deepgent.sessions`: recorded-session context injection and existing JSONL evidence ledger reuse.
+- `coding_deepgent.tasks`: durable `PlanArtifact` remains the verifier boundary and evidence subject.
+- `coding_deepgent.tool_system`: verifier tool allowlist and guard middleware remain unchanged.
+
+Tradeoff / complexity:
+- Chosen: reuse the existing session evidence ledger and pass a narrow optional session context through runtime invocation.
+- Deferred: coordinator runtime, mailbox / SendMessage, background workers, task-backed local-agent lifecycle, automatic task/plan mutation, and a verifier-specific persistence store.
+- Why this complexity is worth it now: Stage 18A made verifier execution real, but without durable evidence the result still disappears across resume boundaries. This adds cross-session continuity through an existing persistence mechanism with minimal new surface area.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_subagents.py`
+- `pytest -q coding-deepgent/tests/test_sessions.py::test_session_evidence_roundtrip_and_recovery_brief coding-deepgent/tests/test_cli.py::test_run_once_records_new_and_resumed_session_transcript`
+- `pytest -q coding-deepgent/tests/test_subagents.py coding-deepgent/tests/test_sessions.py::test_session_evidence_roundtrip_and_recovery_brief coding-deepgent/tests/test_cli.py::test_run_once_records_new_and_resumed_session_transcript coding-deepgent/tests/test_cli.py::test_run_once_passes_recording_session_context_to_agent coding-deepgent/tests/test_cli.py::test_sessions_resume_rejects_manual_and_generated_compact_together coding-deepgent/tests/test_cli.py::test_sessions_resume_rejects_compact_instructions_without_generation`
+- `pytest -q coding-deepgent/tests/test_app.py coding-deepgent/tests/test_tool_system_registry.py coding-deepgent/tests/test_tool_system_middleware.py`
+- `ruff check coding-deepgent/src/coding_deepgent/subagents/tools.py coding-deepgent/src/coding_deepgent/runtime/context.py coding-deepgent/src/coding_deepgent/runtime/invocation.py coding-deepgent/src/coding_deepgent/app.py coding-deepgent/src/coding_deepgent/bootstrap.py coding-deepgent/src/coding_deepgent/agent_loop_service.py coding-deepgent/src/coding_deepgent/sessions/service.py coding-deepgent/tests/test_subagents.py coding-deepgent/tests/test_cli.py`
+- `mypy coding-deepgent/src/coding_deepgent/subagents/tools.py coding-deepgent/src/coding_deepgent/runtime/context.py coding-deepgent/src/coding_deepgent/runtime/invocation.py coding-deepgent/src/coding_deepgent/app.py coding-deepgent/src/coding_deepgent/bootstrap.py coding-deepgent/src/coding_deepgent/agent_loop_service.py coding-deepgent/src/coding_deepgent/sessions/service.py coding-deepgent/tests/test_subagents.py coding-deepgent/tests/test_cli.py`
+
+cc-haha alignment:
+- Source mapping reused from the stage PRD:
+  - `/root/claude-code-haha/src/tools/AgentTool/built-in/verificationAgent.ts`
+  - `/root/claude-code-haha/src/tools/AgentTool/runAgent.ts`
+  - `/root/claude-code-haha/src/utils/sessionStorage.ts`
+- Aligned now:
+  - explicit verifier verdict line drives deterministic local status
+  - verifier outcome is persisted into session transcript/evidence storage
+- Deferred:
+  - upstream richer background/task lifecycle
+  - coordinator/team runtime
+  - agent mailbox and resumable local-agent task objects
+
+LangChain architecture:
+- Used existing `run_subagent` tool path and `ToolRuntime.context`.
+- Kept persistence outside generic tool middleware so only verifier result recording owns this workflow-specific behavior.
+- Added no custom query loop, no new graph node, and no extra verifier store.
+
+Boundary findings:
+- Runtime context needed one narrow optional session-recording field. Guessing session storage from `session_id` alone would have broken custom `session_dir` settings and hidden the persistence boundary.
+- Verifier calls without `session_context` now explicitly skip persistence and keep returning the structured verifier JSON.
+
+Decision:
+- terminal
+
+Reason:
+- Stage 18B completes the remaining Stage 18 persistence step with focused verification passing. There is no next Stage 18 sub-stage left to auto-continue into under lean mode.
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-18b-verifier-result-persistence-evidence-integration/task.json b/.trellis/tasks/archive/2026-04/04-15-stage-18b-verifier-result-persistence-evidence-integration/task.json
new file mode 100644
index 000000000..d3f3112a5
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-18b-verifier-result-persistence-evidence-integration/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-18b-verifier-result-persistence-evidence-integration",
+  "name": "stage-18b-verifier-result-persistence-evidence-integration",
+  "title": "Stage 18B: Verifier Result Persistence and Evidence Integration",
+  "description": "Persist verifier verdicts into the existing session evidence ledger.",
+  "status": "completed",
+  "dev_type": "backend",
+  "scope": "coding-deepgent verifier workflow evidence persistence",
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-15",
+  "completedAt": "2026-04-15",
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 3,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "Stage 18B checkpoint approved: verifier PASS/FAIL/PARTIAL results persist as session verification evidence when recording context is available.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-19-evidence-observability-agent-lifecycle-hardening/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-19-evidence-observability-agent-lifecycle-hardening/check.jsonl
new file mode 100644
index 000000000..14c61b0e5
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-19-evidence-observability-agent-lifecycle-hardening/check.jsonl
@@ -0,0 +1,4 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_sessions.py", "reason": "19A recovery brief provenance tests"}
+{"file": "coding-deepgent/tests/test_subagents.py", "reason": "19B verifier evidence lineage tests"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-19-evidence-observability-agent-lifecycle-hardening/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-19-evidence-observability-agent-lifecycle-hardening/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-19-evidence-observability-agent-lifecycle-hardening/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-19-evidence-observability-agent-lifecycle-hardening/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-19-evidence-observability-agent-lifecycle-hardening/implement.jsonl
new file mode 100644
index 000000000..fa71140f5
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-19-evidence-observability-agent-lifecycle-hardening/implement.jsonl
@@ -0,0 +1,4 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/src/coding_deepgent/sessions/resume.py", "reason": "19A recovery brief evidence provenance rendering"}
+{"file": "coding-deepgent/src/coding_deepgent/subagents/tools.py", "reason": "19B verifier evidence lineage metadata"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-19-evidence-observability-agent-lifecycle-hardening/prd.md b/.trellis/tasks/archive/2026-04/04-15-stage-19-evidence-observability-agent-lifecycle-hardening/prd.md
new file mode 100644
index 000000000..fc98370e4
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-19-evidence-observability-agent-lifecycle-hardening/prd.md
@@ -0,0 +1,246 @@
+# Stage 19: Evidence Observability and Agent Lifecycle Hardening
+
+## Goal
+
+Advance H19 evidence/observability and H11 agent-as-tool lifecycle with the smallest useful post-18B slices: make verifier evidence easier to interpret on resume, and add minimal lineage metadata that links verifier evidence back to the parent session and child verifier invocation.
+
+## Mode
+
+`stage-iterate lean-batch + multi-agent`
+
+Explorer usage:
+
+* Explorer A mapped relevant cc-haha source for H19/H11/H06/H10.
+* Explorer B audited local `coding_deepgent` module boundaries and tests.
+
+## Corresponding Highlights
+
+* `H19 Observability and evidence ledger` - primary for both 19A and 19B.
+* `H11 Agent as tool and runtime object` - primary for 19B lineage metadata.
+* `H06 Session transcript, evidence, and resume` - primary for 19A recovery brief visibility.
+* `H10 Plan / Execute / Verify workflow discipline` - indirect; verifier remains the workflow boundary.
+
+## Sub-Stage 19A: Verifier Evidence Provenance In Recovery Brief
+
+### Function Summary
+
+When recovery brief renders verification evidence, include a concise provenance suffix derived from existing evidence fields, such as `plan=<plan_id>` and `verdict=<verdict>`.
+
+### Expected Benefit
+
+* Observability: resume context says which plan/verdict a verifier evidence row belongs to.
+* Recoverability: users and agents can interpret verifier evidence after session resume without re-opening raw JSONL.
+* Testability: recovery brief rendering proves verifier evidence metadata survives into resume-facing text.
+
+### Corresponding Modules
+
+* `coding_deepgent.sessions.resume`
+* `coding_deepgent.sessions.records`
+* `coding_deepgent.tests.test_sessions`
+* `coding_deepgent.tests.test_subagents`
+
+### In Scope
+
+* Render short provenance only for `kind="verification"` evidence.
+* Preserve the existing recovery brief evidence path.
+* Keep ordinary runtime evidence concise.
+
+### Out Of Scope
+
+* Dumping full evidence metadata into recovery brief.
+* New evidence store or transcript schema.
+* New resume picker UI.
+
+## Sub-Stage 19B: Verifier Evidence Lineage Metadata
+
+### Function Summary
+
+Persist minimal parent/child lineage metadata with verifier evidence: parent session id, parent thread id, verifier child thread id, and verifier agent name.
+
+### Expected Benefit
+
+* Agent-runtime observability: verifier evidence can be traced to the parent session and child verifier invocation.
+* H11 readiness: child verifier execution becomes more runtime-object-like without adding background lifecycle or mailbox state.
+* Debuggability: failures can be correlated with exact child thread naming.
+
+### Corresponding Modules
+
+* `coding_deepgent.subagents.tools`
+* `coding_deepgent.runtime.context`
+* `coding_deepgent.sessions.store_jsonl`
+* `coding_deepgent.tests.test_subagents`
+
+### In Scope
+
+* Add stable lineage fields to verifier evidence metadata.
+* Derive lineage from existing `ToolRuntime.context` and `ToolRuntime.config`.
+* Keep verifier JSON output contract unchanged.
+
+### Out Of Scope
+
+* Coordinator runtime.
+* Mailbox / SendMessage.
+* Background worker execution.
+* Agent task objects or automatic task/plan mutation.
+* Storing full runtime context in evidence metadata.
+
+## cc-haha Alignment
+
+### Expected Effect
+
+Aligning these slices should improve observability, recoverability, and agent-runtime traceability. The local runtime effect is: verifier evidence becomes understandable after resume and can be traced to the bounded child verifier invocation, while intentionally deferring cc-haha's richer background agent lifecycle.
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Session transcript / resume visibility | `sessionStorage` records transcript and sidechain material that resume/loading paths can inspect | verifier evidence should be first-class resume context, not only immediate tool output | render verification provenance in recovery brief using existing evidence ledger | partial | Align now without new store or UI |
+| Agent lifecycle trace | task notifications and local-agent flows carry lifecycle identity / agent scoping | verifier evidence can be correlated with parent session and child verifier invocation | add minimal parent/child lineage metadata to evidence | partial | Align as metadata, not full runtime object |
+| Background/local agent lifecycle | cc-haha has richer task status, queued notifications, sidechain files, and event plumbing | useful later for H11/H13, but too broad now | none | defer | Do not add coordinator/mailbox/background runtime |
+
+### Source Files Inspected
+
+Explorer A inspected:
+
+* `/root/claude-code-haha/src/query.ts`
+* `/root/claude-code-haha/src/cli/print.ts`
+* `/root/claude-code-haha/src/cli/remoteIO.ts`
+* `/root/claude-code-haha/src/utils/sessionStorage.ts`
+* `/root/claude-code-haha/src/services/api/claude.ts`
+* `/root/claude-code-haha/src/Task.ts`
+
+## LangChain Architecture
+
+Use:
+
+* Existing `run_subagent` LangChain tool boundary.
+* Existing `ToolRuntime.context` and `ToolRuntime.config` access.
+* Existing session evidence ledger and recovery brief renderer.
+
+Avoid:
+
+* New graph nodes.
+* New custom query loop.
+* Middleware that secretly owns verifier workflow persistence.
+* New persistence store.
+
+## Acceptance Criteria
+
+* [x] Verification evidence in recovery brief includes concise plan/verdict provenance.
+* [x] Non-verification evidence rendering remains concise.
+* [x] Verifier evidence metadata includes parent session id, parent thread id, child verifier thread id, and verifier agent name when runtime context is available.
+* [x] Verifier JSON output contract remains unchanged.
+* [x] No task/plan mutation is introduced.
+* [x] Focused tests, targeted ruff, and targeted mypy pass.
+
+## Test Plan
+
+* Extend `tests/test_sessions.py` for recovery brief provenance rendering.
+* Extend `tests/test_subagents.py` for verifier lineage metadata roundtrip.
+* Run targeted app/subagent/session tests affected by runtime/session context.
+* Run targeted `ruff check` and `mypy` on changed files.
+
+## Checkpoint: Stage 19A
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- `render_recovery_brief()` now renders concise provenance for verification evidence when stable fields exist.
+- Provenance uses `plan=<plan_id>` and `verdict=<verdict>`.
+- Non-verification evidence remains concise and does not dump arbitrary metadata.
+
+Corresponding highlights:
+- `H19`: evidence rows are more observable in resume/recovery context.
+- `H06`: recovery brief carries enough provenance to interpret verification evidence after resume.
+- `H10`: verifier workflow evidence is clearer without changing the verifier contract.
+
+Corresponding modules:
+- `coding_deepgent.sessions.resume`
+- `coding_deepgent.sessions.records`
+- `coding_deepgent.tests.test_sessions`
+
+Tradeoff / complexity:
+- Chosen: render only short, stable provenance for verification evidence.
+- Deferred: resume picker UI changes, full metadata rendering, separate evidence store.
+- Why now: Stage 18B made verifier evidence durable; 19A makes that durable evidence readable at the resume boundary.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_sessions.py::test_session_evidence_roundtrip_and_recovery_brief coding-deepgent/tests/test_sessions.py::test_recovery_brief_renders_verification_provenance_only coding-deepgent/tests/test_sessions.py::test_recovery_brief_limits_recent_evidence_in_original_order`
+
+Decision:
+- continue
+
+Reason:
+- 19A is complete and 19B remains a narrow, source-backed H11/H19 metadata extension on the same evidence path.
+
+## Checkpoint: Stage 19B
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Verifier evidence metadata now includes bounded lineage fields:
+  - `parent_session_id`
+  - `parent_thread_id`
+  - `child_thread_id`
+  - `verifier_agent_name`
+- The verifier JSON result contract remains unchanged.
+- No task or plan mutation was introduced.
+
+Corresponding highlights:
+- `H11`: verifier evidence can now be traced as an agent-as-tool child invocation without adding a background runtime object.
+- `H19`: evidence has enough lineage metadata to debug verifier execution.
+- `H06`: lineage survives session load through the existing JSONL evidence ledger.
+- `H10`: verifier workflow remains bounded to `run_subagent`.
+
+Corresponding modules:
+- `coding_deepgent.subagents.tools`
+- `coding_deepgent.sessions.store_jsonl`
+- `coding_deepgent.tests.test_subagents`
+
+Tradeoff / complexity:
+- Chosen: add four stable lineage metadata fields.
+- Deferred: coordinator runtime, mailbox, background workers, local-agent task objects, automatic task/plan mutation, and full runtime-context serialization.
+- Why now: this gives useful H11 traceability from the existing child verifier invocation with minimal storage and no new scheduler.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_subagents.py::test_run_subagent_tool_persists_verifier_evidence_roundtrip coding-deepgent/tests/test_subagents.py::test_run_subagent_tool_returns_structured_verifier_result coding-deepgent/tests/test_subagents.py::test_run_subagent_task_verifier_executes_real_child_agent`
+- `pytest -q coding-deepgent/tests/test_sessions.py::test_session_evidence_roundtrip_and_recovery_brief coding-deepgent/tests/test_sessions.py::test_recovery_brief_renders_verification_provenance_only coding-deepgent/tests/test_sessions.py::test_recovery_brief_limits_recent_evidence_in_original_order coding-deepgent/tests/test_subagents.py::test_run_subagent_tool_persists_verifier_evidence_roundtrip coding-deepgent/tests/test_subagents.py::test_run_subagent_tool_returns_structured_verifier_result coding-deepgent/tests/test_subagents.py::test_run_subagent_task_verifier_executes_real_child_agent coding-deepgent/tests/test_cli.py::test_sessions_resume_uses_recovery_brief_continuation_history`
+- `ruff check coding-deepgent/src/coding_deepgent/sessions/resume.py coding-deepgent/src/coding_deepgent/subagents/tools.py coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_subagents.py`
+- `mypy coding-deepgent/src/coding_deepgent/sessions/resume.py coding-deepgent/src/coding_deepgent/subagents/tools.py coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_subagents.py`
+
+cc-haha alignment:
+- Explorer A inspected:
+  - `/root/claude-code-haha/src/query.ts`
+  - `/root/claude-code-haha/src/cli/print.ts`
+  - `/root/claude-code-haha/src/cli/remoteIO.ts`
+  - `/root/claude-code-haha/src/utils/sessionStorage.ts`
+  - `/root/claude-code-haha/src/services/api/claude.ts`
+  - `/root/claude-code-haha/src/Task.ts`
+- Aligned now:
+  - session/resume-facing evidence visibility
+  - lightweight parent/child verifier lineage
+- Deferred:
+  - sidechain transcript files
+  - queued task notifications
+  - full background/local-agent lifecycle
+  - coordinator/mailbox runtime
+
+LangChain architecture:
+- Used existing `run_subagent` tool and `ToolRuntime` context/config.
+- Added no new graph node, middleware layer, custom query loop, or persistence store.
+
+Boundary findings:
+- Arbitrary evidence metadata should not be rendered into recovery brief; only stable provenance fields are safe.
+- H11 lineage can advance as metadata now, while task-backed agent lifecycle should wait for a dedicated source-backed stage.
+
+Decision:
+- terminal
+
+Reason:
+- 19A and 19B complete the narrow lean-batch. The optional runtime-event evidence stage is valid but higher-risk because it can expand into all-event persistence; it should get its own PRD before implementation.
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-19-evidence-observability-agent-lifecycle-hardening/task.json b/.trellis/tasks/archive/2026-04/04-15-stage-19-evidence-observability-agent-lifecycle-hardening/task.json
new file mode 100644
index 000000000..7089f8981
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-19-evidence-observability-agent-lifecycle-hardening/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-19-evidence-observability-agent-lifecycle-hardening",
+  "name": "stage-19-evidence-observability-agent-lifecycle-hardening",
+  "title": "Stage 19: Evidence Observability and Agent Lifecycle Hardening",
+  "description": "Make verifier evidence resume-visible with provenance and add bounded verifier lineage metadata.",
+  "status": "completed",
+  "dev_type": "backend",
+  "scope": "coding-deepgent H19 evidence observability and H11 verifier lineage metadata",
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-15",
+  "completedAt": "2026-04-15",
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 3,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "Stage 19A/19B approved: recovery brief renders verifier provenance and verifier evidence metadata carries parent/child lineage.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-21-tool-and-permission-closeout/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-21-tool-and-permission-closeout/check.jsonl
new file mode 100644
index 000000000..89fb427e5
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-21-tool-and-permission-closeout/check.jsonl
@@ -0,0 +1,4 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_tool_system_registry.py", "reason": "Stage 21 H01 tool surface assertions"}
+{"file": "coding-deepgent/tests/test_tool_system_middleware.py", "reason": "Stage 21 H02 permission and tool guard checks"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-21-tool-and-permission-closeout/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-21-tool-and-permission-closeout/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-21-tool-and-permission-closeout/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-21-tool-and-permission-closeout/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-21-tool-and-permission-closeout/implement.jsonl
new file mode 100644
index 000000000..ee7ac109a
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-21-tool-and-permission-closeout/implement.jsonl
@@ -0,0 +1,4 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/src/coding_deepgent/tool_system/", "type": "directory", "reason": "Stage 21 H01 tool runtime closeout"}
+{"file": "coding-deepgent/src/coding_deepgent/permissions/", "type": "directory", "reason": "Stage 21 H02 permission closeout"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-21-tool-and-permission-closeout/prd.md b/.trellis/tasks/archive/2026-04/04-15-stage-21-tool-and-permission-closeout/prd.md
new file mode 100644
index 000000000..8b7ba7323
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-21-tool-and-permission-closeout/prd.md
@@ -0,0 +1,132 @@
+# Stage 21: Tool And Permission Closeout
+
+## Goal
+
+Close the highest-value remaining H01/H02 MVP gaps by auditing and tightening the tool-first capability runtime and local permission/hard-safety boundary.
+
+## Function Summary
+
+This stage should identify and implement the smallest concrete changes that make the current tool surface and permission runtime count as MVP-complete for Approach A, without adding UI approval, auto classifier, or remote trust flows.
+
+## Expected Benefit
+
+* Reliability: model-facing tools obey one clearer runtime contract.
+* Safety: dangerous tool execution paths have fewer policy gaps.
+* Testability: tool/permission contracts become easier to verify with focused tests.
+* Product parity: H01/H02 move from broad partial to explicit MVP closeout or tightly scoped residual partial.
+
+## Corresponding Highlights
+
+* `H01 Tool-first capability runtime`
+* `H02 Permission runtime and hard safety`
+
+## Corresponding Modules
+
+* `coding_deepgent.tool_system`
+* `coding_deepgent.permissions`
+* `coding_deepgent.filesystem`
+* domain tool modules with model-facing capability exposure
+
+## Out Of Scope
+
+* HITL UI
+* auto permission classifier
+* remote trust/auth flows
+* marketplace/install/update flows
+* coordinator/mailbox/background runtime
+
+## Acceptance Criteria
+
+* [x] cc-haha source mapping for H01/H02 is recorded in this stage PRD.
+* [x] local H01/H02 MVP closeout slices are explicit.
+* [x] focused tests, targeted ruff, and targeted mypy pass for changed files.
+* [x] checkpoint records whether H01/H02 become implemented or remain partial with an explicit minimal residual.
+
+## cc-haha Alignment
+
+### Expected Effect
+
+Aligning this behavior should improve reliability, safety, and testability. The local runtime effect is: model-facing tools obey a stricter capability/runtime contract, and permission decisions remain fail-closed with clearer regression coverage around workspace safety and policy-code mapping.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Tool-first runtime seam | `Tool.ts` and `AgentTool` treat tools as first-class runtime objects with explicit permission/call behavior | prevent silent drift in model-facing tool contracts | capability registry hardening + projection tests | partial | Align contract now; defer richer AgentTool runtime |
+| Allowlist / runtime capability shape | `runAgent.ts` and `loadAgentsDir.ts` preserve explicit tool allow/disallow shaping | keep local tool exposure explicit and bounded | capability projection and declarable/exposure tests | partial | Align through registry projections |
+| Hard permission / filesystem safety | permission types + filesystem shell/path gates are hard safety chokepoints | keep local shell/path execution fail-closed | `PermissionManager`, `ToolPolicy`, `pattern_policy`, trusted-workdir wiring tests | align | Close out MVP with contract tests now |
+| Rich team/agent permission lifecycle | `AgentTool` includes deeper agent selection, teammate, resume, and lifecycle flows | useful later but not required for current MVP | none | defer | Keep out of Stage 21 |
+
+### Source files inspected
+
+Explorer A inspected:
+
+* `/root/claude-code-haha/src/Tool.ts`
+* `/root/claude-code-haha/src/tools/AgentTool/AgentTool.tsx`
+* `/root/claude-code-haha/src/tools/AgentTool/runAgent.ts`
+* `/root/claude-code-haha/src/tools/AgentTool/agentToolUtils.ts`
+* `/root/claude-code-haha/src/tools/AgentTool/loadAgentsDir.ts`
+* `/root/claude-code-haha/src/tools/AgentTool/forkSubagent.ts`
+* `/root/claude-code-haha/src/tools/AgentTool/resumeAgent.ts`
+* `/root/claude-code-haha/src/types/permissions.ts`
+* `/root/claude-code-haha/src/utils/permissions/permissions.ts`
+* `/root/claude-code-haha/src/utils/permissions/filesystem.ts`
+* `/root/claude-code-haha/src/tools/BashTool/bashPermissions.ts`
+* `/root/claude-code-haha/src/tools/PowerShellTool/powershellPermissions.ts`
+* `/root/claude-code-haha/src/tools/PowerShellTool/modeValidation.ts`
+
+## Technical Approach
+
+* Harden H01 by rejecting duplicate builtin tool names before the capability registry can be fed a silently overwritten `tool_by_name` mapping.
+* Add H01 contract tests for:
+  * duplicate-name rejection
+  * enabled/disabled capability exposure
+  * extension exposure projection
+  * container wiring of permission settings
+* Add H02 contract tests for:
+  * `ToolPolicyCode` mapping
+  * negative `pattern_policy()` cases for workspace escape patterns
+
+## Checkpoint: Stage 21
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added a duplicate builtin tool-name guard in `build_builtin_capabilities()`.
+- Added H01 contract tests for duplicate names, enabled/disabled exposure projection, extension projection, and container-level permission/trusted-workdir wiring.
+- Added H02 contract tests for `ToolPolicyCode` mapping and `pattern_policy()` workspace-escape rejection.
+
+Corresponding highlights:
+- `H01 Tool-first capability runtime`
+- `H02 Permission runtime and hard safety`
+
+Corresponding modules:
+- `coding_deepgent.tool_system.capabilities`
+- `coding_deepgent.permissions.manager`
+- `coding_deepgent.filesystem.policy`
+- `coding_deepgent.containers.tool_system`
+- `coding_deepgent.containers.app`
+
+Tradeoff / complexity:
+- Chosen: close H01/H02 with contract hardening and one small code guard instead of a broader runtime redesign.
+- Deferred: richer AgentTool lifecycle, remote/team permission flows, UI approval, classifier logic.
+- Why this complexity is worth it now: H01/H02 were already broadly implemented; the remaining MVP risk was mostly silent contract drift and edge-case gaps.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_tool_system_registry.py coding-deepgent/tests/test_permissions.py coding-deepgent/tests/test_tool_system_middleware.py coding-deepgent/tests/test_plugins.py coding-deepgent/tests/test_mcp.py coding-deepgent/tests/test_tools.py`
+- `ruff check coding-deepgent/src/coding_deepgent/tool_system/capabilities.py coding-deepgent/tests/test_tool_system_registry.py coding-deepgent/tests/test_permissions.py`
+- `mypy coding-deepgent/src/coding_deepgent/tool_system/capabilities.py coding-deepgent/tests/test_tool_system_registry.py coding-deepgent/tests/test_permissions.py`
+
+Boundary findings:
+- The main residual H01/H02 risk was contract-level, not architectural.
+- `tool_by_name` duplicate overwrite needed an explicit guard to keep the tool-first runtime fail-closed.
+
+Decision:
+- continue
+
+Reason:
+- Stage 21 is complete and Stage 22 (H03/H04 prompt + dynamic context closeout) remains a direct next milestone from the canonical dashboard.
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-21-tool-and-permission-closeout/task.json b/.trellis/tasks/archive/2026-04/04-15-stage-21-tool-and-permission-closeout/task.json
new file mode 100644
index 000000000..d2c661f87
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-21-tool-and-permission-closeout/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-21-tool-and-permission-closeout",
+  "name": "stage-21-tool-and-permission-closeout",
+  "title": "Stage 21: Tool And Permission Closeout",
+  "description": "Close H01/H02 with tool runtime and permission contract hardening.",
+  "status": "completed",
+  "dev_type": "backend",
+  "scope": "coding-deepgent H01/H02 tool and permission MVP closeout",
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-15",
+  "completedAt": "2026-04-15",
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 3,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "Stage 21 approved: H01/H02 closed out with duplicate-name guard and focused contract tests.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-22-prompt-and-dynamic-context-closeout/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-22-prompt-and-dynamic-context-closeout/check.jsonl
new file mode 100644
index 000000000..685025e11
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-22-prompt-and-dynamic-context-closeout/check.jsonl
@@ -0,0 +1,4 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_app.py", "reason": "Stage 22 prompt/runtime integration checks"}
+{"file": "coding-deepgent/tests/test_cli.py", "reason": "Stage 22 prompt/context and recovery-context checks"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-22-prompt-and-dynamic-context-closeout/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-22-prompt-and-dynamic-context-closeout/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-22-prompt-and-dynamic-context-closeout/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-22-prompt-and-dynamic-context-closeout/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-22-prompt-and-dynamic-context-closeout/implement.jsonl
new file mode 100644
index 000000000..883b7d506
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-22-prompt-and-dynamic-context-closeout/implement.jsonl
@@ -0,0 +1,4 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/src/coding_deepgent/prompting/", "type": "directory", "reason": "Stage 22 H03 prompt closeout"}
+{"file": "coding-deepgent/src/coding_deepgent/runtime/", "type": "directory", "reason": "Stage 22 H04 dynamic context closeout"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-22-prompt-and-dynamic-context-closeout/prd.md b/.trellis/tasks/archive/2026-04/04-15-stage-22-prompt-and-dynamic-context-closeout/prd.md
new file mode 100644
index 000000000..b4d0fae83
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-22-prompt-and-dynamic-context-closeout/prd.md
@@ -0,0 +1,133 @@
+# Stage 22: Prompt And Dynamic Context Closeout
+
+## Goal
+
+Close the highest-value remaining H03/H04 MVP gaps by auditing and tightening the layered prompt contract and the dynamic context assembly path.
+
+## Function Summary
+
+This stage should identify and implement the smallest concrete changes that make prompt layering and dynamic context assembly count as MVP-complete for Approach A, without turning prompt text into a giant manual or introducing a custom query runtime.
+
+## Expected Benefit
+
+* Reliability: prompt and context responsibilities are clearer and less likely to drift.
+* Context-efficiency: dynamic context stays bounded and purposeful.
+* Maintainability: prompt logic and dynamic context injection are easier to audit and test.
+
+## Corresponding Highlights
+
+* `H03 Layered prompt contract`
+* `H04 Dynamic context protocol`
+
+## Corresponding Modules
+
+* `coding_deepgent.prompting`
+* `coding_deepgent.runtime`
+* `coding_deepgent.memory`
+* `coding_deepgent.sessions`
+* `coding_deepgent.compact`
+* `coding_deepgent.middleware`
+
+## Out Of Scope
+
+* giant prompt rewrites
+* custom query runtime
+* provider-specific cache tuning
+* UI/TUI prompt surfaces
+* coordinator / mailbox / background runtime
+
+## Acceptance Criteria
+
+* [x] cc-haha source mapping for H03/H04 is recorded in this stage PRD.
+* [x] local H03/H04 MVP closeout slices are explicit.
+* [x] focused tests, targeted ruff, and targeted mypy pass for changed files.
+* [x] checkpoint records whether H03/H04 become implemented or remain partial with an explicit minimal residual.
+
+## cc-haha Alignment
+
+### Expected Effect
+
+Aligning this behavior should improve reliability, context-efficiency, and maintainability. The local runtime effect is: prompt assembly stays layered and settings-backed, while dynamic context stays typed, bounded, and composition-safe across resume, todo, memory, and compact flows.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Layered prompt assembly | prompt order and cache-safe boundary matter more than giant prompt text | prevent prompt customization drift and keep stable base prompt semantics | prompt layering contract tests for `build_system_prompt` / `build_prompt_context` | partial | Align contract now; defer richer cache-specific machinery |
+| Dynamic context via attachments | dynamic context is a protocol, not a loose prompt string | keep local context typed, ordered, bounded, and merge-safe | model-call composition test across resume + todo + memory; explicit H04 MVP boundary | partial | Align bounded protocol now |
+| Extension / coordinator prompt branches | upstream has broader coordinator, proactive, attachment, and UI-driven prompt paths | useful later but not required for current MVP | none | defer | Keep out of Stage 22 |
+
+### Source files inspected
+
+Explorer A inspected:
+
+* `/root/claude-code-haha/src/constants/prompts.ts`
+* `/root/claude-code-haha/src/utils/systemPrompt.ts`
+* `/root/claude-code-haha/src/utils/queryContext.ts`
+* `/root/claude-code-haha/src/context.ts`
+* `/root/claude-code-haha/src/utils/api.ts`
+* `/root/claude-code-haha/src/services/api/claude.ts`
+* `/root/claude-code-haha/src/commands/btw/btw.tsx`
+* `/root/claude-code-haha/src/cli/print.ts`
+* `/root/claude-code-haha/src/utils/attachments.ts`
+* `/root/claude-code-haha/src/utils/messages.ts`
+* `/root/claude-code-haha/src/components/messages/nullRenderingAttachments.ts`
+* `/root/claude-code-haha/src/components/messages/AttachmentMessage.tsx`
+* `/root/claude-code-haha/src/utils/sessionStart.ts`
+* `/root/claude-code-haha/src/services/tools/toolHooks.ts`
+
+## Technical Approach
+
+* Close H03 with direct settings-backed prompt layering tests instead of rewriting prompt composition.
+* Close H04 with a model-call-boundary composition test that proves:
+  * resume context stays in message history, not duplicated into the system prompt
+  * todo context appears before memory context
+  * memory context and todo context compose cleanly through shared payload merge behavior
+* Narrow H04 MVP boundary explicitly:
+  * included: typed/bounded dynamic context for resume, todo, memory, and compact flows
+  * deferred from this stage: `skills/resources` as first-class context payload kinds
+
+## Checkpoint: Stage 22
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added a direct `build_system_prompt(settings)` test to pin the H03 layered prompt contract.
+- Added an end-to-end model-call composition test proving resume history, todo context, and memory context compose without duplication and with stable ordering.
+- Explicitly narrowed H04 MVP closeout to the current typed/bounded local protocol for resume, todo, memory, and compact-related context.
+
+Corresponding highlights:
+- `H03 Layered prompt contract`
+- `H04 Dynamic context protocol`
+
+Corresponding modules:
+- `coding_deepgent.prompting`
+- `coding_deepgent.agent_service`
+- `coding_deepgent.context_payloads`
+- `coding_deepgent.memory.middleware`
+- `coding_deepgent.todo.middleware`
+- `coding_deepgent.sessions`
+
+Tradeoff / complexity:
+- Chosen: contract tests plus explicit boundary clarification.
+- Deferred: skills/resources as first-class context payload kinds, prompt cache machinery, coordinator/proactive branches, UI rendering polish.
+- Why this complexity is worth it now: H03/H04 were already mostly implemented; the remaining MVP risk was silent composition drift and an unclear scope boundary.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_prompting.py coding-deepgent/tests/test_memory_integration.py coding-deepgent/tests/test_context_payloads.py coding-deepgent/tests/test_memory_context.py coding-deepgent/tests/test_app.py coding-deepgent/tests/test_cli.py::test_sessions_resume_uses_recovery_brief_continuation_history`
+- `ruff check coding-deepgent/tests/test_prompting.py coding-deepgent/tests/test_memory_integration.py`
+- `mypy coding-deepgent/src/coding_deepgent/prompting/builder.py coding-deepgent/src/coding_deepgent/agent_service.py coding-deepgent/src/coding_deepgent/context_payloads.py coding-deepgent/src/coding_deepgent/memory/middleware.py coding-deepgent/src/coding_deepgent/todo/middleware.py coding-deepgent/tests/test_prompting.py coding-deepgent/tests/test_memory_integration.py`
+
+Boundary findings:
+- H04 should not silently imply skills/resources attachment parity in the current MVP.
+- Resume context belongs in message history, while todo/memory remain dynamic system-context payloads; that split is part of the local contract.
+
+Decision:
+- continue
+
+Reason:
+- Stage 22 is complete and Stage 23 (H05/H06 context pressure + session continuity closeout) remains the next direct milestone from the canonical dashboard.
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-22-prompt-and-dynamic-context-closeout/task.json b/.trellis/tasks/archive/2026-04/04-15-stage-22-prompt-and-dynamic-context-closeout/task.json
new file mode 100644
index 000000000..b345781a0
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-22-prompt-and-dynamic-context-closeout/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-22-prompt-and-dynamic-context-closeout",
+  "name": "stage-22-prompt-and-dynamic-context-closeout",
+  "title": "Stage 22: Prompt And Dynamic Context Closeout",
+  "description": "Close H03/H04 with prompt layering and dynamic context contract hardening.",
+  "status": "completed",
+  "dev_type": "backend",
+  "scope": "coding-deepgent H03/H04 prompt and dynamic context MVP closeout",
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-15",
+  "completedAt": "2026-04-15",
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 3,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "Stage 22 approved: H03/H04 closed with prompt layering tests, composition test, and explicit H04 MVP boundary.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-23-context-pressure-and-session-continuity-closeout/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-23-context-pressure-and-session-continuity-closeout/check.jsonl
new file mode 100644
index 000000000..df23b2646
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-23-context-pressure-and-session-continuity-closeout/check.jsonl
@@ -0,0 +1,4 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_sessions.py", "reason": "Stage 23 H05/H06 session and resume checks"}
+{"file": "coding-deepgent/tests/test_cli.py", "reason": "Stage 23 continuation and compact CLI checks"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-23-context-pressure-and-session-continuity-closeout/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-23-context-pressure-and-session-continuity-closeout/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-23-context-pressure-and-session-continuity-closeout/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-23-context-pressure-and-session-continuity-closeout/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-23-context-pressure-and-session-continuity-closeout/implement.jsonl
new file mode 100644
index 000000000..7d452fe70
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-23-context-pressure-and-session-continuity-closeout/implement.jsonl
@@ -0,0 +1,4 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/src/coding_deepgent/compact/", "type": "directory", "reason": "Stage 23 H05 compact/projection closeout"}
+{"file": "coding-deepgent/src/coding_deepgent/sessions/", "type": "directory", "reason": "Stage 23 H06 session continuity closeout"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-23-context-pressure-and-session-continuity-closeout/prd.md b/.trellis/tasks/archive/2026-04/04-15-stage-23-context-pressure-and-session-continuity-closeout/prd.md
new file mode 100644
index 000000000..8ccf4622d
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-23-context-pressure-and-session-continuity-closeout/prd.md
@@ -0,0 +1,130 @@
+# Stage 23: Context Pressure And Session Continuity Closeout
+
+## Goal
+
+Close the highest-value remaining H05/H06 MVP gaps by auditing and tightening context pressure management, compact/projection behavior, session transcript continuity, and resume-facing session evidence seams.
+
+## Function Summary
+
+This stage should identify and implement the smallest concrete changes that make context pressure handling and session continuity count as MVP-complete for Approach A, without introducing automatic summarization middleware or a new persistence runtime.
+
+## Expected Benefit
+
+* Context-efficiency: compact/projection behavior remains deterministic and bounded.
+* Recoverability: resume/session continuity behavior is easier to trust and audit.
+* Testability: compact/session seams have clearer end-to-end regression coverage.
+
+## Corresponding Highlights
+
+* `H05 Progressive context pressure management`
+* `H06 Session transcript, evidence, and resume`
+
+## Corresponding Modules
+
+* `coding_deepgent.compact`
+* `coding_deepgent.sessions`
+* `coding_deepgent.cli_service`
+* `coding_deepgent.rendering`
+* `coding_deepgent.runtime`
+
+## Out Of Scope
+
+* automatic summarization middleware
+* new persistence backend
+* background/session daemon
+* remote transcript browser
+* coordinator / mailbox / background runtime
+
+## Acceptance Criteria
+
+* [x] cc-haha source mapping for H05/H06 is recorded in this stage PRD.
+* [x] local H05/H06 MVP closeout slices are explicit.
+* [x] focused tests, targeted ruff, and targeted mypy pass for changed files.
+* [x] checkpoint records whether H05/H06 become implemented or remain partial with an explicit minimal residual.
+
+## cc-haha Alignment
+
+### Expected Effect
+
+Aligning this behavior should improve context-efficiency, recoverability, and testability. The local runtime effect is: projection/compaction remains deterministic under pressure, and resumed session continuity remains stable across compact/evidence combinations.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Progressive context pressure gate | autocompact/compaction paths are gated by deterministic suppression and threshold rules | keep local projection/compact path predictable and regression-resistant | projection/compact contract tests and fallback safety | partial | Align deterministic contract now; defer richer auto-compact runtime |
+| Session transcript / resume continuity | transcript + sidechain + resume chain must survive reload | keep local compact/evidence/resume ordering trustworthy | combined continuity regression and existing session-store contracts | partial | Align continuity now; defer evidence CLI surface |
+| Richer remote/session runtime | upstream has broader hydration, sidechain, and remote resume machinery | useful later but not required for current MVP | none | defer | Keep out of Stage 23 |
+
+### Source files inspected
+
+Explorer A inspected:
+
+* `/root/claude-code-haha/src/commands/compact/compact.ts`
+* `/root/claude-code-haha/src/services/compact/autoCompact.ts`
+* `/root/claude-code-haha/src/services/compact/compact.ts`
+* `/root/claude-code-haha/src/services/compact/microCompact.ts`
+* `/root/claude-code-haha/src/services/compact/sessionMemoryCompact.ts`
+* `/root/claude-code-haha/src/services/compact/postCompactCleanup.ts`
+* `/root/claude-code-haha/src/services/compact/prompt.ts`
+* `/root/claude-code-haha/src/services/compact/apiMicrocompact.ts`
+* `/root/claude-code-haha/src/utils/sessionStorage.ts`
+* `/root/claude-code-haha/src/utils/sessionRestore.ts`
+* `/root/claude-code-haha/src/utils/messages.ts`
+* `/root/claude-code-haha/src/utils/sessionFileAccessHooks.ts`
+* `/root/claude-code-haha/src/commands/resume/index.ts`
+
+## Technical Approach
+
+* Close H05 with regression coverage over the full projection chain:
+  * plain same-role text merges
+  * structured content does not merge
+  * metadata blocks merging
+  * truncation behavior remains stable
+* Close H06 with a combined continuity regression proving that:
+  * recovery brief appears once
+  * compact boundary and summary survive in order
+  * evidence provenance remains visible in the resume brief
+  * resumed history does not duplicate the resume context message
+
+## Checkpoint: Stage 23
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added an H05 projection regression covering mixed plain/structured/metadata message normalization behavior.
+- Added an H06 combined continuity regression covering resume brief, compact boundary/summary order, evidence provenance, and no-duplication behavior in selected continuation history.
+
+Corresponding highlights:
+- `H05 Progressive context pressure management`
+- `H06 Session transcript, evidence, and resume`
+
+Corresponding modules:
+- `coding_deepgent.compact.projection`
+- `coding_deepgent.rendering`
+- `coding_deepgent.sessions`
+- `coding_deepgent.cli_service`
+
+Tradeoff / complexity:
+- Chosen: contract closeout through focused regression coverage.
+- Deferred: richer auto-compact runtime, evidence CLI surface, remote/session hydration breadth.
+- Why this complexity is worth it now: H05/H06 already had strong behavior; the MVP risk was regression at composition/reload boundaries, not missing large subsystems.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_rendering.py coding-deepgent/tests/test_message_projection.py coding-deepgent/tests/test_compact_artifacts.py coding-deepgent/tests/test_compact_budget.py coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_cli.py::test_selected_continuation_history_uses_loaded_compacted_history coding-deepgent/tests/test_cli.py::test_selected_continuation_history_preserves_resume_compact_and_evidence_without_duplication`
+- `ruff check coding-deepgent/tests/test_rendering.py coding-deepgent/tests/test_cli.py`
+- `mypy coding-deepgent/src/coding_deepgent/rendering.py coding-deepgent/src/coding_deepgent/compact/projection.py coding-deepgent/src/coding_deepgent/compact/artifacts.py coding-deepgent/src/coding_deepgent/sessions/resume.py coding-deepgent/src/coding_deepgent/cli_service.py coding-deepgent/tests/test_rendering.py coding-deepgent/tests/test_cli.py`
+
+Boundary findings:
+- H05 is best treated as a deterministic projection/compact contract in the current MVP, not as a commitment to full upstream autocompact breadth.
+- H06 is strong enough for MVP without adding an evidence inspection command; that remains an optional later enhancement under H19/H06.
+
+Decision:
+- continue
+
+Reason:
+- Stage 23 is complete and Stage 24 (H07 scoped memory closeout) remains the next direct milestone from the canonical dashboard.
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-23-context-pressure-and-session-continuity-closeout/task.json b/.trellis/tasks/archive/2026-04/04-15-stage-23-context-pressure-and-session-continuity-closeout/task.json
new file mode 100644
index 000000000..991b229fc
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-23-context-pressure-and-session-continuity-closeout/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-23-context-pressure-and-session-continuity-closeout",
+  "name": "stage-23-context-pressure-and-session-continuity-closeout",
+  "title": "Stage 23: Context Pressure And Session Continuity Closeout",
+  "description": "Close H05/H06 with projection and session continuity contract hardening.",
+  "status": "completed",
+  "dev_type": "backend",
+  "scope": "coding-deepgent H05/H06 context pressure and session continuity MVP closeout",
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-15",
+  "completedAt": "2026-04-15",
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 3,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "Stage 23 approved: H05/H06 closed with projection regression and combined resume/compact/evidence continuity coverage.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-24-scoped-memory-closeout/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-24-scoped-memory-closeout/check.jsonl
new file mode 100644
index 000000000..9cf3e21a6
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-24-scoped-memory-closeout/check.jsonl
@@ -0,0 +1,4 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_memory_integration.py", "reason": "Stage 24 memory middleware and scoped recall checks"}
+{"file": "coding-deepgent/tests/test_memory.py", "reason": "Stage 24 memory namespace and quality checks"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-24-scoped-memory-closeout/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-24-scoped-memory-closeout/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-24-scoped-memory-closeout/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-24-scoped-memory-closeout/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-24-scoped-memory-closeout/implement.jsonl
new file mode 100644
index 000000000..137b4729e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-24-scoped-memory-closeout/implement.jsonl
@@ -0,0 +1,2 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-24-scoped-memory-closeout/prd.md b/.trellis/tasks/archive/2026-04/04-15-stage-24-scoped-memory-closeout/prd.md
new file mode 100644
index 000000000..386a29424
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-24-scoped-memory-closeout/prd.md
@@ -0,0 +1,124 @@
+# Stage 24: Scoped Memory Closeout
+
+## Goal
+
+Close the highest-value remaining H07 MVP gaps by tightening the scoped cross-session memory contract around namespace isolation, durable write quality, and bounded recall/surfacing.
+
+## Function Summary
+
+This stage closes H07 by treating local memory as scope-aware cross-session memory rather than a generic note dump. The MVP closeout focuses on namespace isolation, write quality gates, and middleware recall scope.
+
+## Expected Benefit
+
+* Cross-session continuity: durable memory survives across sessions without collapsing all memory scopes together.
+* Reliability: duplicates and transient state stay out of long-term memory.
+* Maintainability: memory behavior is pinned by scope/namespace contracts instead of ad hoc usage.
+
+## Corresponding Highlights
+
+* `H07 Scoped cross-session memory`
+
+## Corresponding Modules
+
+* `coding_deepgent.memory`
+* `coding_deepgent.runtime`
+* `coding_deepgent.sessions`
+
+## Out Of Scope
+
+* rich session-memory extraction side agents
+* agent-memory snapshots and sync
+* remote memory transport
+* memory editing UI
+* new memory intelligence layers outside current store/quality/recall seams
+
+## Acceptance Criteria
+
+* [x] cc-haha source mapping for H07 is recorded in this stage PRD.
+* [x] local H07 MVP closeout slices are explicit.
+* [x] focused tests, targeted ruff, and targeted mypy pass for changed files.
+* [x] checkpoint records whether H07 becomes implemented or remains partial with an explicit minimal residual.
+
+## cc-haha Alignment
+
+### Expected Effect
+
+Aligning this behavior should improve cross-session continuity, reliability, and maintainability. The local runtime effect is: durable memory stays scope-aware and bounded, while write quality and recall stay explicit instead of turning into an unstructured global note store.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Scoped memory model | session memory, agent memory, and memory-file scope are separate concerns | prevent local memory from collapsing into one global blob | namespace-isolated durable memory contract | partial | Align local namespace/scope contract now |
+| Write quality and extraction gate | memory capture is gated and not every transient state becomes memory | keep local long-term memory clean | quality policy + duplicate/transient rejection | align | Close out with current local gate |
+| Bounded surfacing and recall | surfaced memory is deduped and scope-aware | prevent cross-namespace leakage and noisy prompt injection | scoped recall + middleware namespace contract | partial | Align current local bounded recall path |
+| Richer session/agent memory runtime | upstream includes session-memory extraction, compaction, snapshots, and memory file access hooks | valid future work but broader than current MVP | none | defer | Keep out of Stage 24 |
+
+### Source files inspected
+
+Explorer A inspected:
+
+* `/root/claude-code-haha/src/services/SessionMemory/sessionMemory.ts`
+* `/root/claude-code-haha/src/services/SessionMemory/sessionMemoryUtils.ts`
+* `/root/claude-code-haha/src/services/SessionMemory/prompts.ts`
+* `/root/claude-code-haha/src/services/compact/sessionMemoryCompact.ts`
+* `/root/claude-code-haha/src/tools/AgentTool/agentMemory.ts`
+* `/root/claude-code-haha/src/tools/AgentTool/agentMemorySnapshot.ts`
+* `/root/claude-code-haha/src/tools/AgentTool/loadAgentsDir.ts`
+* `/root/claude-code-haha/src/utils/memoryFileDetection.ts`
+* `/root/claude-code-haha/src/utils/sessionFileAccessHooks.ts`
+* `/root/claude-code-haha/src/utils/permissions/filesystem.ts`
+* `/root/claude-code-haha/src/utils/attachments.ts`
+* `/root/claude-code-haha/src/utils/sessionStorage.ts`
+
+## Technical Approach
+
+* Close H07 with contract hardening rather than a new memory subsystem.
+* Pin namespace isolation and duplicate behavior in `test_memory.py`.
+* Pin middleware recall scope in `test_memory_integration.py`.
+* Explicitly define the MVP H07 boundary as:
+  * included: durable namespace-scoped store-backed memory, quality gate, scoped recall, bounded middleware injection
+  * deferred: session-memory extraction runtime, agent-memory snapshot lifecycle, memory file hooks, and remote sync
+
+## Checkpoint: Stage 24
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added namespace isolation and duplicate-scope regression coverage for durable memory records.
+- Added a middleware namespace-scope regression proving memory injection only surfaces the configured namespace.
+- Fixed the H07 MVP boundary as local namespace-scoped memory with bounded recall and quality gating.
+
+Corresponding highlights:
+- `H07 Scoped cross-session memory`
+
+Corresponding modules:
+- `coding_deepgent.memory.policy`
+- `coding_deepgent.memory.store`
+- `coding_deepgent.memory.recall`
+- `coding_deepgent.memory.middleware`
+- `coding_deepgent.memory.tools`
+
+Tradeoff / complexity:
+- Chosen: close H07 with namespace/scope contracts on the existing store-backed seam.
+- Deferred: richer session-memory extraction, agent-memory snapshots, memory file access hooks, and remote memory sync.
+- Why this complexity is worth it now: the MVP needs durable cross-session memory, but not the full upstream memory runtime breadth.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_memory.py coding-deepgent/tests/test_memory_integration.py coding-deepgent/tests/test_memory_context.py`
+- `ruff check coding-deepgent/tests/test_memory.py coding-deepgent/tests/test_memory_integration.py`
+- `mypy coding-deepgent/src/coding_deepgent/memory/policy.py coding-deepgent/src/coding_deepgent/memory/recall.py coding-deepgent/src/coding_deepgent/memory/tools.py coding-deepgent/tests/test_memory.py coding-deepgent/tests/test_memory_integration.py`
+
+Boundary findings:
+- H07 should not imply upstream-style session-memory extraction or agent-memory snapshots in the current MVP.
+- Namespace isolation is currently guaranteed by the calling seam (`list_memory_records(namespace)`), so that contract must remain explicit in tests.
+
+Decision:
+- continue
+
+Reason:
+- Stage 24 is complete and Stage 25 (H08/H09/H10 todo/task/plan/verify closeout) remains the next direct milestone from the canonical dashboard.
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-24-scoped-memory-closeout/task.json b/.trellis/tasks/archive/2026-04/04-15-stage-24-scoped-memory-closeout/task.json
new file mode 100644
index 000000000..a78c80ad4
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-24-scoped-memory-closeout/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-24-scoped-memory-closeout",
+  "name": "stage-24-scoped-memory-closeout",
+  "title": "Stage 24: Scoped Memory Closeout",
+  "description": "Close H07 with scoped memory namespace and recall contract hardening.",
+  "status": "completed",
+  "dev_type": "backend",
+  "scope": "coding-deepgent H07 scoped memory MVP closeout",
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-15",
+  "completedAt": "2026-04-15",
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 3,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "Stage 24 approved: H07 closed as local namespace-scoped durable memory with bounded recall and quality gating.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-25-todo-task-plan-verify-closeout/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-25-todo-task-plan-verify-closeout/check.jsonl
new file mode 100644
index 000000000..27bdecf07
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-25-todo-task-plan-verify-closeout/check.jsonl
@@ -0,0 +1,5 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_tasks.py", "reason": "Stage 25 task graph and plan contract checks"}
+{"file": "coding-deepgent/tests/test_subagents.py", "reason": "Stage 25 verifier contract checks"}
+{"file": "coding-deepgent/tests/test_todo_domain.py", "reason": "Stage 25 TodoWrite contract checks"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-25-todo-task-plan-verify-closeout/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-25-todo-task-plan-verify-closeout/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-25-todo-task-plan-verify-closeout/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-25-todo-task-plan-verify-closeout/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-25-todo-task-plan-verify-closeout/implement.jsonl
new file mode 100644
index 000000000..7bbe2173a
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-25-todo-task-plan-verify-closeout/implement.jsonl
@@ -0,0 +1,5 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/src/coding_deepgent/todo/", "type": "directory", "reason": "Stage 25 H08 TodoWrite closeout"}
+{"file": "coding-deepgent/src/coding_deepgent/tasks/", "type": "directory", "reason": "Stage 25 H09/H10 durable task and plan/verify closeout"}
+{"file": "coding-deepgent/src/coding_deepgent/subagents/", "type": "directory", "reason": "Stage 25 verifier workflow closeout"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-25-todo-task-plan-verify-closeout/prd.md b/.trellis/tasks/archive/2026-04/04-15-stage-25-todo-task-plan-verify-closeout/prd.md
new file mode 100644
index 000000000..07ae5106b
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-25-todo-task-plan-verify-closeout/prd.md
@@ -0,0 +1,127 @@
+# Stage 25: Todo Task Plan Verify Closeout
+
+## Goal
+
+Close the highest-value remaining H08/H09/H10 MVP gaps by tightening TodoWrite, durable task graph, and plan/execute/verify workflow contracts without adding coordinator runtime or mailbox features.
+
+## Function Summary
+
+This stage should identify and implement the smallest concrete changes that make short-term planning, durable task collaboration state, and explicit plan/verify workflow count as MVP-complete for Approach A.
+
+## Expected Benefit
+
+* Reliability: planning state and durable task state remain distinct and predictable.
+* Testability: TodoWrite/task/plan/verifier contracts become easier to audit and lock.
+* Product parity: H08/H09/H10 move from broadly working to explicit MVP closeout.
+
+## Corresponding Highlights
+
+* `H08 TodoWrite as short-term planning contract`
+* `H09 Durable Task graph as collaboration state`
+* `H10 Plan / Execute / Verify workflow discipline`
+
+## Corresponding Modules
+
+* `coding_deepgent.todo`
+* `coding_deepgent.tasks`
+* `coding_deepgent.subagents`
+* `coding_deepgent.sessions`
+* `coding_deepgent.tool_system`
+
+## Out Of Scope
+
+* coordinator runtime
+* mailbox / SendMessage
+* background worker execution
+* task-backed general agent lifecycle beyond current verifier path
+* automatic task mutation from verifier result
+
+## Acceptance Criteria
+
+* [x] cc-haha source mapping for H08/H09/H10 is recorded in this stage PRD.
+* [x] local H08/H09/H10 MVP closeout slices are explicit.
+* [x] focused tests, targeted ruff, and targeted mypy pass for changed files.
+* [x] checkpoint records whether H08/H09/H10 become implemented or remain partial with an explicit minimal residual.
+
+## cc-haha Alignment
+
+### Expected Effect
+
+Aligning this behavior should improve reliability, testability, and workflow discipline. The local runtime effect is: TodoWrite remains session-local short-term planning, durable Task remains a separate validated graph, and plan/verify remains explicit without introducing coordinator or mailbox runtime.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| TodoWrite short-term checklist | TodoWrite is session-scoped progress tracking, not durable task graph state | keep local planning state cheap and separate from durable tasks | TodoWrite schema/service/middleware contracts | align | Close with overlong-list regression |
+| Durable task graph | task tools own durable task graph state, transitions, dependencies, and listing | keep task graph visible and deterministic | terminal visibility and verification-task detection tests | partial | Close MVP graph contracts now |
+| Plan/verify discipline | plan and verify prompts/tools push independent verification after work | verifier path remains explicit/read-only and plan-bound | existing plan/verifier evidence path plus verification nudge tests | partial | Close MVP workflow; defer coordinator |
+| Coordinator/mailbox/team runtime | upstream has richer multi-agent workflow surfaces | useful later but out of MVP | none | defer | Do not add in Stage 25 |
+
+### Source files inspected
+
+Explorer A inspected:
+
+* `/root/claude-code-haha/src/tools/TodoWriteTool/TodoWriteTool.ts`
+* `/root/claude-code-haha/src/tools/TodoWriteTool/prompt.ts`
+* `/root/claude-code-haha/src/utils/tasks.ts`
+* `/root/claude-code-haha/src/Task.ts`
+* `/root/claude-code-haha/src/tools/TaskCreateTool/TaskCreateTool.ts`
+* `/root/claude-code-haha/src/tools/TaskUpdateTool/TaskUpdateTool.ts`
+* `/root/claude-code-haha/src/tools/TaskListTool/TaskListTool.ts`
+* `/root/claude-code-haha/src/tools/TaskGetTool/TaskGetTool.ts`
+* `/root/claude-code-haha/src/tools/EnterPlanModeTool/EnterPlanModeTool.ts`
+* `/root/claude-code-haha/src/tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts`
+* `/root/claude-code-haha/src/tools/AgentTool/built-in/verificationAgent.ts`
+* `/root/claude-code-haha/src/skills/bundled/verify.ts`
+
+## Technical Approach
+
+* Close H08 with a TodoWrite overlong-list regression to keep short-term planning bounded.
+* Close H09 with terminal task visibility regression for `task_list(include_terminal=True)`.
+* Close H10 with verification task metadata recognition and cancelled-task boundary regression.
+* Preserve the existing verifier result persistence/evidence path from Stages 18-19.
+
+## Checkpoint: Stage 25
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added `task_list(include_terminal=True)` regression covering completed/cancelled task visibility and default terminal filtering.
+- Added verification-task metadata recognition regression with cancelled task boundary behavior.
+- Added TodoWrite overlong short-term-plan regression for the 12-item limit.
+
+Corresponding highlights:
+- `H08 TodoWrite as short-term planning contract`
+- `H09 Durable Task graph as collaboration state`
+- `H10 Plan / Execute / Verify workflow discipline`
+
+Corresponding modules:
+- `coding_deepgent.todo`
+- `coding_deepgent.tasks`
+- `coding_deepgent.subagents`
+- `coding_deepgent.sessions`
+
+Tradeoff / complexity:
+- Chosen: close the local contracts with focused regressions; no new runtime layer.
+- Deferred: coordinator runtime, mailbox / SendMessage, background worker execution, automatic task mutation from verifier results.
+- Why this complexity is worth it now: H08/H09/H10 behavior already existed; the remaining MVP risk was silent drift in visibility and verification-trigger rules.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_tasks.py coding-deepgent/tests/test_subagents.py coding-deepgent/tests/test_todo_domain.py coding-deepgent/tests/test_planning.py`
+- `ruff check coding-deepgent/tests/test_tasks.py coding-deepgent/tests/test_todo_domain.py`
+- `mypy coding-deepgent/src/coding_deepgent/todo/service.py coding-deepgent/src/coding_deepgent/tasks/store.py coding-deepgent/src/coding_deepgent/tasks/tools.py coding-deepgent/src/coding_deepgent/subagents/tools.py coding-deepgent/tests/test_tasks.py coding-deepgent/tests/test_todo_domain.py`
+
+Boundary findings:
+- H08 is complete as session-local planning; it must not absorb durable task graph semantics.
+- H09/H10 are complete for MVP without coordinator/mailbox/background runtime.
+
+Decision:
+- continue
+
+Reason:
+- Stage 25 is complete and Stage 26 (H11 agent-as-tool closeout with minimal H12) remains the next milestone from the canonical dashboard.
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-25-todo-task-plan-verify-closeout/task.json b/.trellis/tasks/archive/2026-04/04-15-stage-25-todo-task-plan-verify-closeout/task.json
new file mode 100644
index 000000000..7f8c64380
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-25-todo-task-plan-verify-closeout/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-25-todo-task-plan-verify-closeout",
+  "name": "stage-25-todo-task-plan-verify-closeout",
+  "title": "Stage 25: Todo Task Plan Verify Closeout",
+  "description": "Close H08/H09/H10 with TodoWrite, durable task graph, and plan/verify contract hardening.",
+  "status": "completed",
+  "dev_type": "backend",
+  "scope": "coding-deepgent H08/H09/H10 todo task plan verify MVP closeout",
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-15",
+  "completedAt": "2026-04-15",
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 3,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "Stage 25 approved: H08/H09/H10 closed with terminal task visibility, verification recognition, and TodoWrite bounded-list regressions.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-26-agent-as-tool-mvp-closeout/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-26-agent-as-tool-mvp-closeout/check.jsonl
new file mode 100644
index 000000000..07ff9e92f
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-26-agent-as-tool-mvp-closeout/check.jsonl
@@ -0,0 +1,4 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_subagents.py", "reason": "Stage 26 subagent contract checks"}
+{"file": "coding-deepgent/tests/test_tool_system_registry.py", "reason": "Stage 26 run_subagent surface checks"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-26-agent-as-tool-mvp-closeout/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-26-agent-as-tool-mvp-closeout/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-26-agent-as-tool-mvp-closeout/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-26-agent-as-tool-mvp-closeout/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-26-agent-as-tool-mvp-closeout/implement.jsonl
new file mode 100644
index 000000000..3b5f1a9f0
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-26-agent-as-tool-mvp-closeout/implement.jsonl
@@ -0,0 +1,4 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/src/coding_deepgent/subagents/", "type": "directory", "reason": "Stage 26 H11/H12 subagent closeout"}
+{"file": "coding-deepgent/src/coding_deepgent/runtime/", "type": "directory", "reason": "Stage 26 runtime context/fork boundary"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-26-agent-as-tool-mvp-closeout/prd.md b/.trellis/tasks/archive/2026-04/04-15-stage-26-agent-as-tool-mvp-closeout/prd.md
new file mode 100644
index 000000000..ec311182a
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-26-agent-as-tool-mvp-closeout/prd.md
@@ -0,0 +1,124 @@
+# Stage 26: Agent As Tool MVP Closeout
+
+## Goal
+
+Close H11 and the minimal H12 MVP boundary by tightening the current agent-as-tool runtime contract without adding mailbox, coordinator, background worker execution, or full agent-team lifecycle.
+
+## Function Summary
+
+This stage should define and verify the MVP-bounded agent-as-tool behavior: subagents enter through `run_subagent`, verifier execution is a real bounded child-agent path, general subagent remains explicitly synchronous/minimal, and minimal fork/context semantics are documented or tested if needed.
+
+## Expected Benefit
+
+* Agent-runtime reliability: subagent behavior has a clear MVP boundary.
+* Recoverability: verifier child execution remains traceable through evidence lineage.
+* Maintainability: future H13/H14 agent-team features cannot leak into MVP unintentionally.
+
+## Corresponding Highlights
+
+* `H11 Agent as tool and runtime object`
+* `H12 Fork/cache-aware subagent execution` minimal local slice only
+
+## Corresponding Modules
+
+* `coding_deepgent.subagents`
+* `coding_deepgent.runtime`
+* `coding_deepgent.tasks`
+* `coding_deepgent.sessions`
+* `coding_deepgent.tool_system`
+
+## Out Of Scope
+
+* mailbox / SendMessage
+* coordinator runtime
+* background worker execution
+* general task-backed agent lifecycle
+* provider-specific prompt-cache parity
+
+## Acceptance Criteria
+
+* [x] cc-haha source mapping for H11/minimal H12 is recorded in this stage PRD.
+* [x] local H11/H12 MVP closeout slices are explicit.
+* [x] focused tests, targeted ruff, and targeted mypy pass for changed files.
+* [x] checkpoint records whether H11 becomes implemented and H12 remains minimal/deferred with an explicit boundary.
+
+## cc-haha Alignment
+
+### Expected Effect
+
+Aligning this behavior should improve agent-runtime reliability and recoverability. The local runtime effect is: subagent execution remains a model-visible tool boundary, verifier child execution remains traceable, and minimal context/thread propagation is pinned without adding a full agent-team runtime.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Agent as tool | `AgentTool` is the runtime entrypoint for child agents | local subagents must enter through `run_subagent`, not prompt-only calls | strict `run_subagent` tool schema, allowlists, verifier child runtime | partial | Close MVP boundary now |
+| Runtime object identity | upstream `LocalAgentTask` gives spawned agents durable identity | local verifier needs traceable child identity, but not full task-backed lifecycle | thread id, agent name, session evidence lineage | partial | Align minimal lineage now |
+| Fork/cache-aware execution | upstream preserves parent prefix via cache-safe params and fork context messages | local MVP needs stable context/thread propagation only | `session_context` and runtime invocation threading tests | minimal | Defer provider-specific cache parity |
+| Agent-team runtime | upstream supports background agents, notifications, SendMessage, teammate flows | valid future work but outside MVP | none | defer | Keep out of Stage 26 |
+
+### Source files inspected
+
+Explorer A inspected:
+
+* `/root/claude-code-haha/src/tools/AgentTool/AgentTool.tsx`
+* `/root/claude-code-haha/src/tools/AgentTool/forkSubagent.ts`
+* `/root/claude-code-haha/src/tools/AgentTool/runAgent.ts`
+* `/root/claude-code-haha/src/tasks/LocalAgentTask/LocalAgentTask.tsx`
+* `/root/claude-code-haha/src/Task.ts`
+* `/root/claude-code-haha/src/tasks.ts`
+* `/root/claude-code-haha/src/utils/forkedAgent.ts`
+* `/root/claude-code-haha/src/utils/queryContext.ts`
+* `/root/claude-code-haha/src/context.ts`
+* `/root/claude-code-haha/src/utils/systemPrompt.ts`
+* `/root/claude-code-haha/src/query.ts`
+
+## Technical Approach
+
+* Close H11 by relying on existing verifier child-agent execution, fixed read-only allowlists, structured verifier result, and evidence lineage.
+* Close minimal H12 by adding runtime/session-context propagation tests across direct runtime invocation and `agent_loop` invocation.
+* Explicitly defer provider-specific fork/cache parity, background agents, mailbox, and coordinator runtime.
+
+## Checkpoint: Stage 26
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added direct `build_runtime_invocation(session_context=...)` regression coverage.
+- Added `agent_loop(..., session_context=...)` threading regression coverage.
+- Confirmed existing subagent/verifier tests still cover allowlists, child thread id, structured verifier result, and evidence metadata.
+
+Corresponding highlights:
+- `H11 Agent as tool and runtime object`
+- `H12 Fork/cache-aware subagent execution` minimal local slice
+
+Corresponding modules:
+- `coding_deepgent.subagents`
+- `coding_deepgent.runtime`
+- `coding_deepgent.app`
+- `coding_deepgent.agent_loop_service`
+- `coding_deepgent.sessions`
+
+Tradeoff / complexity:
+- Chosen: MVP-bounded agent-as-tool contract and minimal runtime/session-context propagation.
+- Deferred: full `LocalAgentTask` lifecycle, background agents, mailbox/SendMessage, coordinator runtime, provider-specific cache-safe fork parity.
+- Why this complexity is worth it now: H11/H12 were at risk of scope creep; this pins the useful local runtime boundary without dragging in agent-team runtime.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_subagents.py coding-deepgent/tests/test_app.py coding-deepgent/tests/test_tool_system_registry.py`
+- `ruff check coding-deepgent/tests/test_app.py`
+- `mypy coding-deepgent/src/coding_deepgent/runtime/invocation.py coding-deepgent/src/coding_deepgent/agent_loop_service.py coding-deepgent/src/coding_deepgent/app.py coding-deepgent/src/coding_deepgent/subagents/tools.py coding-deepgent/tests/test_app.py coding-deepgent/tests/test_subagents.py`
+
+Boundary findings:
+- H11 is complete for MVP as a bounded `run_subagent` tool surface with real verifier child execution.
+- H12 is complete only as a minimal local context/thread propagation slice; rich fork/cache parity is explicitly deferred.
+
+Decision:
+- continue
+
+Reason:
+- Stage 26 is complete and Stage 27 (H15-H18 local extension platform closeout) remains the next milestone from the canonical dashboard.
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-26-agent-as-tool-mvp-closeout/task.json b/.trellis/tasks/archive/2026-04/04-15-stage-26-agent-as-tool-mvp-closeout/task.json
new file mode 100644
index 000000000..1d9a9d2cc
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-26-agent-as-tool-mvp-closeout/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-26-agent-as-tool-mvp-closeout",
+  "name": "stage-26-agent-as-tool-mvp-closeout",
+  "title": "Stage 26: Agent As Tool MVP Closeout",
+  "description": "Close H11 and minimal H12 with agent-as-tool and runtime context threading contracts.",
+  "status": "completed",
+  "dev_type": "backend",
+  "scope": "coding-deepgent H11/H12 agent-as-tool MVP closeout",
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-15",
+  "completedAt": "2026-04-15",
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 3,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "Stage 26 approved: H11 closed as bounded run_subagent/verifier tool surface; H12 closed as minimal context/thread propagation with rich fork/cache parity deferred.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-27-local-extension-platform-closeout/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-27-local-extension-platform-closeout/check.jsonl
new file mode 100644
index 000000000..cf047eb49
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-27-local-extension-platform-closeout/check.jsonl
@@ -0,0 +1,6 @@
+{"file": ".agents/skills/finish-work/SKILL.md", "reason": "Finish work checklist"}
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_skills.py", "reason": "Stage 27 skills tests"}
+{"file": "coding-deepgent/tests/test_mcp.py", "reason": "Stage 27 MCP tests"}
+{"file": "coding-deepgent/tests/test_plugins.py", "reason": "Stage 27 plugin tests"}
+{"file": "coding-deepgent/tests/test_hooks.py", "reason": "Stage 27 hook tests"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-27-local-extension-platform-closeout/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-27-local-extension-platform-closeout/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-27-local-extension-platform-closeout/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".agents/skills/check-backend/SKILL.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-27-local-extension-platform-closeout/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-27-local-extension-platform-closeout/implement.jsonl
new file mode 100644
index 000000000..04647f868
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-27-local-extension-platform-closeout/implement.jsonl
@@ -0,0 +1,6 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/src/coding_deepgent/skills/", "type": "directory", "reason": "Stage 27 H15 skills closeout"}
+{"file": "coding-deepgent/src/coding_deepgent/mcp/", "type": "directory", "reason": "Stage 27 H16 MCP closeout"}
+{"file": "coding-deepgent/src/coding_deepgent/plugins/", "type": "directory", "reason": "Stage 27 H17 plugin closeout"}
+{"file": "coding-deepgent/src/coding_deepgent/hooks/", "type": "directory", "reason": "Stage 27 H18 hooks closeout"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-27-local-extension-platform-closeout/prd.md b/.trellis/tasks/archive/2026-04/04-15-stage-27-local-extension-platform-closeout/prd.md
new file mode 100644
index 000000000..1020a7cd9
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-27-local-extension-platform-closeout/prd.md
@@ -0,0 +1,134 @@
+# Stage 27: Local Extension Platform Closeout
+
+## Goal
+
+Close H15-H18 MVP gaps by tightening local skills, MCP, plugin manifests, and hooks as safe extension surfaces without adding marketplace/install/update, remote trust, or remote hook platforms.
+
+## Function Summary
+
+This stage should verify and minimally harden local extension packaging and loading so extensions remain typed, local, and policy-bound through the same tool/permission/runtime boundaries.
+
+## Expected Benefit
+
+* Extensibility: local extension surfaces are usable and predictable.
+* Safety: plugins, MCP, skills, and hooks do not bypass tool/permission boundaries.
+* Maintainability: extension manifests and lifecycle hooks have explicit contracts.
+
+## Corresponding Highlights
+
+* `H15 Skill system as capability packaging`
+* `H16 MCP as external capability protocol`
+* `H17 Plugin states: source / install / enable`
+* `H18 Hooks as programmable middleware`
+
+## Corresponding Modules
+
+* `coding_deepgent.skills`
+* `coding_deepgent.mcp`
+* `coding_deepgent.plugins`
+* `coding_deepgent.hooks`
+* `coding_deepgent.tool_system`
+* `coding_deepgent.extensions_service`
+
+## Out Of Scope
+
+* marketplace install/update flows
+* remote plugin trust/auth UX
+* remote hook platform
+* executing plugin code
+* replacing LangChain runtime with extension runtime
+
+## Acceptance Criteria
+
+* [x] cc-haha source mapping for H15-H18 is recorded in this stage PRD.
+* [x] local H15-H18 MVP closeout slices are explicit.
+* [x] focused tests, targeted ruff, and targeted mypy pass for changed files.
+* [x] checkpoint records whether H15-H18 become implemented or remain partial/deferred with explicit minimal residuals.
+
+## cc-haha Alignment
+
+### Expected Effect
+
+Aligning this behavior should improve extensibility, safety, and maintainability. The local runtime effect is: skills, MCP, plugins, and hooks remain typed local extension seams that still flow through the same tool/permission/runtime boundaries.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Skills | skill frontmatter becomes model-visible command/tool packaging | local skills stay strict, deterministic, and explicitly loaded | skill loader/render/runtime context tests | partial | Close local MVP skill packaging now |
+| MCP | typed external capability protocol with transport/config validation | local MCP stays config-validated and adapter-backed without replacing runtime | transport alias/http/sse config tests; tool/resource separation | partial | Close local MVP MCP protocol now |
+| Plugins | source/install/enable are distinct upstream states | local MVP only supports manifest/source validation, not install/enable lifecycle | registry uniqueness/resource validation tests; lifecycle deferred | partial/defer | Close local manifest MVP; defer lifecycle state machine |
+| Hooks | hooks are programmable middleware around runtime/tool events | local hooks stay sync, typed, event-emitting middleware, not backdoors | dispatcher event envelope tests | partial | Close local MVP hook middleware now |
+
+### Source files inspected
+
+Explorer A inspected cc-haha sources including:
+
+* `/root/claude-code-haha/src/skills/loadSkillsDir.ts`
+* `/root/claude-code-haha/src/tools/SkillTool/SkillTool.ts`
+* `/root/claude-code-haha/src/services/mcp/types.ts`
+* `/root/claude-code-haha/src/services/mcp/client.ts`
+* `/root/claude-code-haha/src/services/mcp/config.ts`
+* `/root/claude-code-haha/src/utils/plugins/installedPluginsManager.ts`
+* `/root/claude-code-haha/src/services/plugins/pluginOperations.ts`
+* `/root/claude-code-haha/src/utils/plugins/pluginLoader.ts`
+* `/root/claude-code-haha/src/utils/hooks.ts`
+* `/root/claude-code-haha/src/services/tools/toolHooks.ts`
+* `/root/claude-code-haha/src/utils/hooks/sessionHooks.ts`
+* `/root/claude-code-haha/src/utils/hooks/registerSkillHooks.ts`
+* `/root/claude-code-haha/src/utils/plugins/loadPluginHooks.ts`
+
+## Technical Approach
+
+* Close H15 with skill malformed/mismatch/render truncation tests.
+* Close H16 with MCP `type` alias and http/sse transport contract tests.
+* Close H17 with plugin registry uniqueness and explicit known-resource validation tests, while deferring full install/enable lifecycle.
+* Close H18 with direct runtime/context hook event-envelope tests.
+
+## Checkpoint: Stage 27
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added skill loader malformed/mismatch and render truncation regressions.
+- Added MCP transport alias/http/sse contract regressions.
+- Added plugin registry duplicate-name and known-resource validation regressions.
+- Added hook runtime/context dispatcher event-envelope regressions.
+
+Corresponding highlights:
+- `H15 Skill system as capability packaging`
+- `H16 MCP as external capability protocol`
+- `H17 Plugin states: source / install / enable`
+- `H18 Hooks as programmable middleware`
+
+Corresponding modules:
+- `coding_deepgent.skills`
+- `coding_deepgent.mcp`
+- `coding_deepgent.plugins`
+- `coding_deepgent.hooks`
+- `coding_deepgent.tool_system`
+- `coding_deepgent.extensions_service`
+
+Tradeoff / complexity:
+- Chosen: local-only extension platform closeout through strict schemas, manifest validation, adapter boundaries, and hook envelopes.
+- Deferred: marketplace install/update, remote trust/auth UX, full plugin enable state machine, remote hook platform, plugin code execution.
+- Why this complexity is worth it now: these extension seams already existed; the MVP risk was contract drift and unclear plugin lifecycle scope.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_skills.py coding-deepgent/tests/test_mcp.py coding-deepgent/tests/test_plugins.py coding-deepgent/tests/test_hooks.py coding-deepgent/tests/test_tool_system_middleware.py`
+- `ruff check coding-deepgent/tests/test_skills.py coding-deepgent/tests/test_mcp.py coding-deepgent/tests/test_plugins.py coding-deepgent/tests/test_hooks.py`
+- `mypy coding-deepgent/src/coding_deepgent/skills/loader.py coding-deepgent/src/coding_deepgent/skills/schemas.py coding-deepgent/src/coding_deepgent/mcp/loader.py coding-deepgent/src/coding_deepgent/mcp/adapters.py coding-deepgent/src/coding_deepgent/plugins/registry.py coding-deepgent/src/coding_deepgent/hooks/dispatcher.py coding-deepgent/tests/test_skills.py coding-deepgent/tests/test_mcp.py coding-deepgent/tests/test_plugins.py coding-deepgent/tests/test_hooks.py`
+
+Boundary findings:
+- H17 is implemented for MVP as local manifest/source validation only; full install/enable lifecycle is deferred.
+- MCP resources remain metadata/read surfaces and are not promoted to executable tools in this MVP.
+
+Decision:
+- continue
+
+Reason:
+- Stage 27 is complete and Stage 28 (H19 observability/evidence closeout with minimal H20 decision) remains the next milestone from the canonical dashboard.
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-27-local-extension-platform-closeout/task.json b/.trellis/tasks/archive/2026-04/04-15-stage-27-local-extension-platform-closeout/task.json
new file mode 100644
index 000000000..7dcf697be
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-27-local-extension-platform-closeout/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-27-local-extension-platform-closeout",
+  "name": "stage-27-local-extension-platform-closeout",
+  "title": "Stage 27: Local Extension Platform Closeout",
+  "description": "Close H15-H18 with local skills, MCP, plugin, and hook contract hardening.",
+  "status": "completed",
+  "dev_type": "backend",
+  "scope": "coding-deepgent H15-H18 local extension platform MVP closeout",
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-15",
+  "completedAt": "2026-04-15",
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 3,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "Stage 27 approved: H15/H16/H18 implemented, H17 implemented for local manifest/source validation with install/enable lifecycle deferred.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-28-observability-evidence-closeout/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-28-observability-evidence-closeout/check.jsonl
new file mode 100644
index 000000000..5c63f9945
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-28-observability-evidence-closeout/check.jsonl
@@ -0,0 +1,5 @@
+{"file": ".gemini/commands/trellis/finish-work.toml", "reason": "Finish work checklist"}
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": "coding-deepgent/tests/test_sessions.py", "reason": "Stage 28 evidence ledger tests"}
+{"file": "coding-deepgent/tests/test_tool_system_middleware.py", "reason": "Stage 28 runtime/tool event tests"}
+{"file": "coding-deepgent/tests/test_compact_budget.py", "reason": "Stage 28 local context metrics/counters tests"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-28-observability-evidence-closeout/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-28-observability-evidence-closeout/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-28-observability-evidence-closeout/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-28-observability-evidence-closeout/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-28-observability-evidence-closeout/implement.jsonl
new file mode 100644
index 000000000..5af384885
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-28-observability-evidence-closeout/implement.jsonl
@@ -0,0 +1,5 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": "coding-deepgent/src/coding_deepgent/runtime/", "type": "directory", "reason": "Stage 28 runtime event closeout"}
+{"file": "coding-deepgent/src/coding_deepgent/sessions/", "type": "directory", "reason": "Stage 28 session evidence closeout"}
+{"file": "coding-deepgent/src/coding_deepgent/compact/", "type": "directory", "reason": "Stage 28 minimal H20 decision"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-28-observability-evidence-closeout/prd.md b/.trellis/tasks/archive/2026-04/04-15-stage-28-observability-evidence-closeout/prd.md
new file mode 100644
index 000000000..9a8c81666
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-28-observability-evidence-closeout/prd.md
@@ -0,0 +1,132 @@
+# Stage 28: Observability Evidence Closeout
+
+## Goal
+
+Close H19 and minimal H20 MVP gaps by tightening structured runtime events, session evidence, recovery visibility, and any local-only metrics/counter decision needed by context/runtime behavior.
+
+## Function Summary
+
+This stage should decide and implement the smallest local observability closeout: evidence should survive session resume boundaries, runtime events should have stable envelopes, and H20 should be either minimal-local implemented or explicitly deferred beyond existing local counters.
+
+## Expected Benefit
+
+* Observability: important runtime and verification outcomes remain inspectable and recoverable.
+* Testability: event/evidence envelopes are pinned by tests.
+* Context-efficiency: H20 remains bounded to local metrics/counters only, avoiding telemetry/cache scope creep.
+
+## Corresponding Highlights
+
+* `H19 Observability and evidence ledger`
+* `H20 Cost/cache instrumentation` minimal local slice
+
+## Corresponding Modules
+
+* `coding_deepgent.runtime`
+* `coding_deepgent.sessions`
+* `coding_deepgent.tool_system`
+* `coding_deepgent.hooks`
+* `coding_deepgent.subagents`
+* `coding_deepgent.compact`
+
+## Out Of Scope
+
+* remote telemetry backend
+* provider-specific cache instrumentation
+* full cost accounting dashboard
+* event bus / daemon
+* coordinator/mailbox/background runtime
+
+## Acceptance Criteria
+
+* [x] cc-haha source mapping for H19/minimal H20 is recorded in this stage PRD.
+* [x] local H19/H20 MVP closeout slices are explicit.
+* [x] focused tests, targeted ruff, and targeted mypy pass for changed files.
+* [x] checkpoint records whether H19 becomes implemented and H20 remains minimal/deferred with explicit boundary.
+
+## cc-haha Alignment
+
+### Expected Effect
+
+Aligning this behavior should improve observability, recoverability, and testability. The local runtime effect is: high-value runtime/tool/hook failures survive resume boundaries as concise session evidence, while H20 remains limited to local context/budget counters and does not become a telemetry system.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Durable observability | transcript/evidence writes survive resume boundaries | blocked hooks and denied tools are recoverable and inspectable | whitelist runtime events into session evidence | align | Implement now |
+| Event breadth | upstream emits many analytics/runtime events | avoid noisy or sensitive local ledger | only `hook_blocked` and `permission_denied` persist | partial | Defer all-event telemetry |
+| Cost/cache metrics | upstream has token/cache/cost accounting | local MVP only needs budget/projection counters | existing budget/projection/compact counters | minimal | No new metrics system |
+| Remote analytics | upstream has 1P/datadog/diagnostic tracking | not a local MVP requirement | none | do-not-copy/defer | Keep out of MVP |
+
+### Source files inspected
+
+Explorer A inspected:
+
+* `/root/claude-code-haha/src/query.ts`
+* `/root/claude-code-haha/src/QueryEngine.ts`
+* `/root/claude-code-haha/src/utils/sessionStorage.ts`
+* `/root/claude-code-haha/src/services/analytics/index.ts`
+* `/root/claude-code-haha/src/services/analytics/firstPartyEventLogger.ts`
+* `/root/claude-code-haha/src/services/analytics/metadata.ts`
+* `/root/claude-code-haha/src/services/diagnosticTracking.ts`
+* `/root/claude-code-haha/src/utils/tokens.ts`
+* `/root/claude-code-haha/src/services/compact/autoCompact.ts`
+* `/root/claude-code-haha/src/services/compact/compact.ts`
+* `/root/claude-code-haha/src/services/compact/microCompact.ts`
+* `/root/claude-code-haha/src/cost-tracker.ts`
+
+## Technical Approach
+
+* Added `sessions.evidence_events.append_runtime_event_evidence()` as the single whitelist bridge from `RuntimeEvent` to session evidence.
+* Wired hook dispatch and tool guard events into the bridge.
+* Persist only:
+  * `hook_blocked`
+  * `permission_denied`
+* Store concise metadata only: source, event kind, hook event, tool, policy code, permission behavior, blocked flag.
+* Keep H20 as the existing local budget/projection/counting contract; no provider-specific cost/cache instrumentation is added.
+
+## Checkpoint: Stage 28
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added a whitelisted runtime-event-to-session-evidence bridge.
+- Persisted blocked hook events as `runtime_event` evidence.
+- Persisted permission-denied tool guard events as `runtime_event` evidence.
+- Added roundtrip tests proving event evidence appears in recovery brief.
+- Preserved H20 as local budget/projection/compact counters only.
+
+Corresponding highlights:
+- `H19 Observability and evidence ledger`
+- `H20 Cost/cache instrumentation` minimal local slice
+
+Corresponding modules:
+- `coding_deepgent.runtime`
+- `coding_deepgent.sessions`
+- `coding_deepgent.hooks`
+- `coding_deepgent.tool_system`
+- `coding_deepgent.compact`
+
+Tradeoff / complexity:
+- Chosen: whitelist two high-value runtime events into the existing session evidence ledger.
+- Deferred: remote telemetry, full analytics, provider-specific token/cache/cost accounting, event bus/daemon.
+- Why this complexity is worth it now: H19 previously had in-memory runtime events and durable verifier evidence, but blocked/denied runtime facts did not survive resume boundaries.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_hooks.py coding-deepgent/tests/test_tool_system_middleware.py coding-deepgent/tests/test_sessions.py::test_session_evidence_roundtrip_and_recovery_brief coding-deepgent/tests/test_subagents.py::test_run_subagent_tool_persists_verifier_evidence_roundtrip coding-deepgent/tests/test_compact_budget.py coding-deepgent/tests/test_rendering.py coding-deepgent/tests/test_message_projection.py`
+- `ruff check coding-deepgent/src/coding_deepgent/sessions/evidence_events.py coding-deepgent/src/coding_deepgent/hooks/dispatcher.py coding-deepgent/src/coding_deepgent/tool_system/middleware.py coding-deepgent/tests/test_hooks.py coding-deepgent/tests/test_tool_system_middleware.py`
+- `mypy coding-deepgent/src/coding_deepgent/sessions/evidence_events.py coding-deepgent/src/coding_deepgent/hooks/dispatcher.py coding-deepgent/src/coding_deepgent/tool_system/middleware.py coding-deepgent/tests/test_hooks.py coding-deepgent/tests/test_tool_system_middleware.py`
+
+Boundary findings:
+- Runtime evidence persistence must stay whitelisted and summary-based; dumping arbitrary args/results would turn the session ledger into noisy telemetry.
+- H20 is complete for MVP as local budget/projection/compact counters; rich cost/cache instrumentation is deferred.
+
+Decision:
+- continue
+
+Reason:
+- Stage 28 is complete and Stage 29 (deferred-boundary ADR + MVP release checklist) remains the next milestone from the canonical dashboard.
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-28-observability-evidence-closeout/task.json b/.trellis/tasks/archive/2026-04/04-15-stage-28-observability-evidence-closeout/task.json
new file mode 100644
index 000000000..88e7a5368
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-28-observability-evidence-closeout/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-28-observability-evidence-closeout",
+  "name": "stage-28-observability-evidence-closeout",
+  "title": "Stage 28: Observability Evidence Closeout",
+  "description": "Close H19 and minimal H20 with runtime evidence bridge and local budget boundary.",
+  "status": "completed",
+  "dev_type": "backend",
+  "scope": "coding-deepgent H19/H20 observability evidence MVP closeout",
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-15",
+  "completedAt": "2026-04-15",
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 3,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "Stage 28 approved: H19 implemented with whitelisted runtime event evidence; H20 implemented-minimal as local budget/projection counters.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/check.jsonl
new file mode 100644
index 000000000..615750538
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/check.jsonl
@@ -0,0 +1,3 @@
+{"file": ".gemini/commands/trellis/finish-work.toml", "reason": "Finish work checklist"}
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".trellis/tasks/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/prd.md", "reason": "Stage 29 release checklist checkpoint"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/implement.jsonl
new file mode 100644
index 000000000..71f31f2b3
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/implement.jsonl
@@ -0,0 +1,4 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": ".trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md", "reason": "Stage 29 deferred boundary and release checklist"}
+{"file": ".trellis/project-handoff.md", "reason": "Stage 29 handoff final status"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/prd.md b/.trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/prd.md
new file mode 100644
index 000000000..e1c14ad32
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/prd.md
@@ -0,0 +1,145 @@
+# Stage 29: Deferred Boundary ADR And MVP Release Checklist
+
+## Goal
+
+Close the Approach A MVP by documenting the deferred boundary for H13/H14/H21/H22, confirming H01-H22 have explicit statuses, and producing a release checklist for the MVP Local Agent Harness Core.
+
+## Function Summary
+
+This stage does not add product runtime behavior. It validates the canonical dashboard, records deferred/out-of-MVP decisions, and states whether any Stage 30-36 reserve work is still required.
+
+## Expected Benefit
+
+* Clarity: the MVP has a visible finish line and explicit non-goals.
+* Maintainability: future requests cannot silently pull deferred cc-haha systems into the MVP.
+* Planning: Stage 30-36 reserve can be used only if a concrete dashboard gap remains.
+
+## Corresponding Highlights
+
+* `H13 Mailbox / SendMessage`
+* `H14 Coordinator keeps synthesis`
+* `H21 Bridge / remote / IDE control plane`
+* `H22 Daemon / cron / proactive automation`
+* final status check for H01-H22
+
+## Corresponding Modules
+
+* `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+* `.trellis/project-handoff.md`
+* final-goal PRD/task metadata
+
+## Out Of Scope
+
+* implementing mailbox
+* implementing coordinator
+* implementing bridge / IDE / remote control plane
+* implementing daemon / cron / proactive automation
+* full pytest unless release checklist finds a concrete cross-layer risk
+
+## Acceptance Criteria
+
+* [x] H13/H14/H21/H22 are explicitly deferred or do-not-copy in the canonical dashboard.
+* [x] H01-H22 all have explicit statuses with no `missing` rows.
+* [x] MVP release checklist exists and names residual risks.
+* [x] checkpoint decides whether Stage 30-36 reserve work is needed.
+
+## Deferred Boundary ADR
+
+**Context**: Approach A defines the MVP as a local LangChain-native Agent Harness Core, not broad cc-haha product parity.
+
+**Decision**: Keep these rows explicitly out of MVP:
+
+* `H13 Mailbox / SendMessage`: deferred to a future agent-team roadmap.
+* `H14 Coordinator keeps synthesis`: deferred to a future coordinator roadmap.
+* `H21 Bridge / remote / IDE control plane`: deferred until there is an explicit remote/IDE product goal.
+* `H22 Daemon / cron / proactive automation`: deferred until proactive automation is explicitly requested.
+
+**Consequences**:
+
+* The MVP can close without mailbox, coordinator, bridge, IDE, daemon, or cron runtime.
+* H12 and H20 remain implemented only in minimal local form.
+* Future work can revive H13/H14/H21/H22 only through a new source-backed PRD with concrete benefit and complexity judgment.
+
+## MVP Release Checklist
+
+### Dashboard Status
+
+* [x] H01 Tool-first capability runtime: implemented
+* [x] H02 Permission runtime and hard safety: implemented
+* [x] H03 Layered prompt contract: implemented
+* [x] H04 Dynamic context protocol: implemented
+* [x] H05 Progressive context pressure management: implemented
+* [x] H06 Session transcript, evidence, and resume: implemented
+* [x] H07 Scoped cross-session memory: implemented
+* [x] H08 TodoWrite short-term planning contract: implemented
+* [x] H09 Durable Task graph: implemented
+* [x] H10 Plan / Execute / Verify workflow discipline: implemented
+* [x] H11 Agent as tool and runtime object: implemented
+* [x] H12 Fork/cache-aware subagent execution: implemented-minimal
+* [x] H13 Mailbox / SendMessage: deferred
+* [x] H14 Coordinator keeps synthesis: deferred
+* [x] H15 Skill system packaging: implemented
+* [x] H16 MCP external capability protocol: implemented
+* [x] H17 Plugin states: implemented-minimal
+* [x] H18 Hooks as middleware: implemented
+* [x] H19 Observability/evidence ledger: implemented
+* [x] H20 Cost/cache instrumentation: implemented-minimal
+* [x] H21 Bridge / remote / IDE control plane: deferred
+* [x] H22 Daemon / cron / proactive automation: deferred
+
+### Known Residual Risks
+
+* No full-suite validation has been run in this deep run; validation stayed focused/targeted per stage.
+* Current worktree includes many uncommitted stage changes and pre-existing Trellis planning changes.
+* H12 is minimal only; rich provider-specific fork/cache behavior is not in MVP.
+* H17 is local manifest/source validation only; install/enable lifecycle is not in MVP.
+* H20 is local budget/projection/compact counters only; provider-specific cost/cache instrumentation is not in MVP.
+* Evidence CLI inspection remains optional; recovery brief already exposes relevant session evidence.
+
+### Next-cycle Backlog
+
+* H13 mailbox / SendMessage multi-agent communication.
+* H14 coordinator synthesis runtime.
+* Full H12 provider/cache-aware fork parity if a concrete runtime benefit appears.
+* Full H17 plugin install/enable/update lifecycle.
+* H20 provider-specific cost/cache instrumentation or reporting.
+* H21 bridge / IDE / remote control plane.
+* H22 daemon / cron / proactive automation.
+
+## Checkpoint: Stage 29
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Recorded the deferred-boundary ADR for H13/H14/H21/H22.
+- Confirmed H01-H22 all have explicit statuses in the canonical dashboard.
+- Produced the MVP release checklist and next-cycle backlog.
+- Confirmed Stage 30-36 reserve is not currently required by the dashboard; it remains available only if later validation finds a concrete MVP gap.
+
+Corresponding highlights:
+- `H13`, `H14`, `H21`, `H22` as deferred rows.
+- H01-H22 as final dashboard validation.
+
+Corresponding modules:
+- `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+- `.trellis/project-handoff.md`
+- `.trellis/tasks/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/prd.md`
+
+Tradeoff / complexity:
+- Chosen: close Approach A MVP now with explicit next-cycle deferrals.
+- Deferred: full agent-team runtime, remote control plane, daemon/proactive automation, marketplace/install lifecycle.
+- Why this complexity is worth it now: the user needed a visible finish line; the dashboard now establishes one and prevents hidden scope expansion.
+
+Verification:
+- Canonical dashboard reviewed: no `missing` rows remain.
+- Trellis context validation run for Stage 29.
+
+Decision:
+- terminal
+
+Reason:
+- Approach A MVP completion-map work has reached the defined Stage 29 closeout. Stage 30-36 reserve is not needed unless a later broader validation run discovers a concrete MVP gap.
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/task.json b/.trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/task.json
new file mode 100644
index 000000000..dda0bf26d
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-29-deferred-boundary-adr-mvp-release-checklist",
+  "name": "stage-29-deferred-boundary-adr-mvp-release-checklist",
+  "title": "Stage 29: Deferred Boundary ADR And MVP Release Checklist",
+  "description": "Close Approach A MVP with deferred-boundary ADR and release checklist.",
+  "status": "completed",
+  "dev_type": "backend",
+  "scope": "coding-deepgent MVP release boundary and H01-H22 final dashboard",
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-15",
+  "completedAt": "2026-04-15",
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 3,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "Stage 29 approved: H01-H22 have explicit statuses, H13/H14/H21/H22 are deferred, and Stage 30-36 reserve is not currently required.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/workflow.md b/.trellis/workflow.md
new file mode 100644
index 000000000..d1fe61eac
--- /dev/null
+++ b/.trellis/workflow.md
@@ -0,0 +1,416 @@
+# Development Workflow
+
+> Based on [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+
+---
+
+## Table of Contents
+
+1. [Quick Start (Do This First)](#quick-start-do-this-first)
+2. [Workflow Overview](#workflow-overview)
+3. [Session Start Process](#session-start-process)
+4. [Development Process](#development-process)
+5. [Session End](#session-end)
+6. [File Descriptions](#file-descriptions)
+7. [Best Practices](#best-practices)
+
+---
+
+## Quick Start (Do This First)
+
+### Step 0: Initialize Developer Identity (First Time Only)
+
+> **Multi-developer support**: Each developer/Agent needs to initialize their identity first
+
+```bash
+# Check if already initialized
+python3 ./.trellis/scripts/get_developer.py
+
+# If not initialized, run:
+python3 ./.trellis/scripts/init_developer.py <your-name>
+# Example: python3 ./.trellis/scripts/init_developer.py cursor-agent
+```
+
+This creates:
+- `.trellis/.developer` - Your identity file (gitignored, not committed)
+- `.trellis/workspace/<your-name>/` - Your personal workspace directory
+
+**Naming suggestions**:
+- Human developers: Use your name, e.g., `john-doe`
+- Cursor AI: `cursor-agent` or `cursor-<task>`
+- Claude Code: `claude-agent` or `claude-<task>`
+- iFlow cli: `iflow-agent` or `iflow-<task>`
+
+### Step 1: Understand Current Context
+
+```bash
+# Get full context in one command
+python3 ./.trellis/scripts/get_context.py
+
+# Or check manually:
+python3 ./.trellis/scripts/get_developer.py      # Your identity
+python3 ./.trellis/scripts/task.py list          # Active tasks
+git status && git log --oneline -10              # Git state
+```
+
+### Step 2: Read Project Guidelines [MANDATORY]
+
+**CRITICAL**: Read guidelines before writing any code:
+
+```bash
+# Read frontend guidelines index (if applicable)
+cat .trellis/spec/frontend/index.md
+
+# Read backend guidelines index (if applicable)
+cat .trellis/spec/backend/index.md
+```
+
+**Why read both?**
+- Understand the full project architecture
+- Know coding standards for the entire codebase
+- See how frontend and backend interact
+- Learn the overall code quality requirements
+
+### Step 3: Before Coding - Read Specific Guidelines (Required)
+
+Based on your task, read the **detailed** guidelines:
+
+**Frontend Task**:
+```bash
+cat .trellis/spec/frontend/hook-guidelines.md      # For hooks
+cat .trellis/spec/frontend/component-guidelines.md # For components
+cat .trellis/spec/frontend/type-safety.md          # For types
+```
+
+**Backend Task**:
+```bash
+cat .trellis/spec/backend/database-guidelines.md   # For DB operations
+cat .trellis/spec/backend/type-safety.md           # For types
+cat .trellis/spec/backend/logging-guidelines.md    # For logging
+```
+
+---
+
+## Workflow Overview
+
+### Core Principles
+
+1. **Read Before Write** - Understand context before starting
+2. **Follow Standards** - [!] **MUST read `.trellis/spec/` guidelines before coding**
+3. **Incremental Development** - Complete one task at a time
+4. **Record Promptly** - Update tracking files immediately after completion
+5. **Document Limits** - [!] **Max 2000 lines per journal document**
+
+### File System
+
+```
+.trellis/
+|-- .developer           # Developer identity (gitignored)
+|-- scripts/
+|   |-- __init__.py          # Python package init
+|   |-- common/              # Shared utilities (Python)
+|   |   |-- __init__.py
+|   |   |-- paths.py         # Path utilities
+|   |   |-- developer.py     # Developer management
+|   |   +-- git_context.py   # Git context implementation
+|   |-- multi_agent/         # Multi-agent pipeline scripts
+|   |   |-- __init__.py
+|   |   |-- start.py         # Start worktree agent
+|   |   |-- status.py        # Monitor agent status
+|   |   |-- create_pr.py     # Create PR
+|   |   +-- cleanup.py       # Cleanup worktree
+|   |-- init_developer.py    # Initialize developer identity
+|   |-- get_developer.py     # Get current developer name
+|   |-- task.py              # Manage tasks
+|   |-- get_context.py       # Get session context
+|   +-- add_session.py       # One-click session recording
+|-- workspace/           # Developer workspaces
+|   |-- index.md         # Workspace index + Session template
+|   +-- {developer}/     # Per-developer directories
+|       |-- index.md     # Personal index (with @@@auto markers)
+|       +-- journal-N.md # Journal files (sequential numbering)
+|-- tasks/               # Task tracking
+|   +-- {MM}-{DD}-{name}/
+|       +-- task.json
+|-- spec/                # [!] MUST READ before coding
+|   |-- frontend/        # Frontend guidelines (if applicable)
+|   |   |-- index.md               # Start here - guidelines index
+|   |   +-- *.md                   # Topic-specific docs
+|   |-- backend/         # Backend guidelines (if applicable)
+|   |   |-- index.md               # Start here - guidelines index
+|   |   +-- *.md                   # Topic-specific docs
+|   +-- guides/          # Thinking guides
+|       |-- index.md                      # Guides index
+|       |-- cross-layer-thinking-guide.md # Pre-implementation checklist
+|       +-- *.md                          # Other guides
++-- workflow.md             # This document
+```
+
+---
+
+## Session Start Process
+
+### Step 1: Get Session Context
+
+Use the unified context script:
+
+```bash
+# Get all context in one command
+python3 ./.trellis/scripts/get_context.py
+
+# Or get JSON format
+python3 ./.trellis/scripts/get_context.py --json
+```
+
+### Step 2: Read Development Guidelines [!] REQUIRED
+
+**[!] CRITICAL: MUST read guidelines before writing any code**
+
+Based on what you'll develop, read the corresponding guidelines:
+
+**Frontend Development** (if applicable):
+```bash
+# Read index first, then specific docs based on task
+cat .trellis/spec/frontend/index.md
+```
+
+**Backend Development** (if applicable):
+```bash
+# Read index first, then specific docs based on task
+cat .trellis/spec/backend/index.md
+```
+
+**Cross-Layer Features**:
+```bash
+# For features spanning multiple layers
+cat .trellis/spec/guides/cross-layer-thinking-guide.md
+```
+
+### Step 3: Select Task to Develop
+
+Use the task management script:
+
+```bash
+# List active tasks
+python3 ./.trellis/scripts/task.py list
+
+# Create new task (creates directory with task.json)
+python3 ./.trellis/scripts/task.py create "<title>" --slug <task-name>
+```
+
+---
+
+## Development Process
+
+### Task Development Flow
+
+```
+1. Create or select task
+   --> python3 ./.trellis/scripts/task.py create "<title>" --slug <name> or list
+
+2. Write code according to guidelines
+   --> Read .trellis/spec/ docs relevant to your task
+   --> For cross-layer: read .trellis/spec/guides/
+
+3. Self-test
+   --> Run project's lint/test commands (see spec docs)
+   --> Manual feature testing
+
+4. Commit code
+   --> git add <files>
+   --> git commit -m "type(scope): description"
+       Format: feat/fix/docs/refactor/test/chore
+
+5. Record session (one command)
+   --> python3 ./.trellis/scripts/add_session.py --title "Title" --commit "hash"
+```
+
+### Code Quality Checklist
+
+**Must pass before commit**:
+- [OK] Lint checks pass (project-specific command)
+- [OK] Type checks pass (if applicable)
+- [OK] Manual feature testing passes
+
+**Project-specific checks**:
+- See `.trellis/spec/frontend/quality-guidelines.md` for frontend
+- See `.trellis/spec/backend/quality-guidelines.md` for backend
+
+---
+
+## Session End
+
+### One-Click Session Recording
+
+After code is committed, use:
+
+```bash
+python3 ./.trellis/scripts/add_session.py \
+  --title "Session Title" \
+  --commit "abc1234" \
+  --summary "Brief summary"
+```
+
+This automatically:
+1. Detects current journal file
+2. Creates new file if 2000-line limit exceeded
+3. Appends session content
+4. Updates index.md (sessions count, history table)
+
+### Pre-end Checklist
+
+Use `/trellis:finish-work` command to run through:
+1. [OK] All code committed, commit message follows convention
+2. [OK] Session recorded via `add_session.py`
+3. [OK] No lint/test errors
+4. [OK] Working directory clean (or WIP noted)
+5. [OK] Spec docs updated if needed
+
+---
+
+## File Descriptions
+
+### 1. workspace/ - Developer Workspaces
+
+**Purpose**: Record each AI Agent session's work content
+
+**Structure** (Multi-developer support):
+```
+workspace/
+|-- index.md              # Main index (Active Developers table)
++-- {developer}/          # Per-developer directory
+    |-- index.md          # Personal index (with @@@auto markers)
+    +-- journal-N.md      # Journal files (sequential: 1, 2, 3...)
+```
+
+**When to update**:
+- [OK] End of each session
+- [OK] Complete important task
+- [OK] Fix important bug
+
+### 2. spec/ - Development Guidelines
+
+**Purpose**: Documented standards for consistent development
+
+**Structure** (Multi-doc format):
+```
+spec/
+|-- frontend/           # Frontend docs (if applicable)
+|   |-- index.md        # Start here
+|   +-- *.md            # Topic-specific docs
+|-- backend/            # Backend docs (if applicable)
+|   |-- index.md        # Start here
+|   +-- *.md            # Topic-specific docs
++-- guides/             # Thinking guides
+    |-- index.md        # Start here
+    +-- *.md            # Guide-specific docs
+```
+
+**When to update**:
+- [OK] New pattern discovered
+- [OK] Bug fixed that reveals missing guidance
+- [OK] New convention established
+
+### 3. Tasks - Task Tracking
+
+Each task is a directory containing `task.json`:
+
+```
+tasks/
+|-- 01-21-my-task/
+|   +-- task.json
++-- archive/
+    +-- 2026-01/
+        +-- 01-15-old-task/
+            +-- task.json
+```
+
+**Commands**:
+```bash
+python3 ./.trellis/scripts/task.py create "<title>" [--slug <name>]   # Create task directory
+python3 ./.trellis/scripts/task.py archive <name>  # Archive to archive/{year-month}/
+python3 ./.trellis/scripts/task.py list            # List active tasks
+python3 ./.trellis/scripts/task.py list-archive    # List archived tasks
+```
+
+---
+
+## Best Practices
+
+### [OK] DO - Should Do
+
+1. **Before session start**:
+   - Run `python3 ./.trellis/scripts/get_context.py` for full context
+   - [!] **MUST read** relevant `.trellis/spec/` docs
+
+2. **During development**:
+   - [!] **Follow** `.trellis/spec/` guidelines
+   - For cross-layer features, use `/trellis:check-cross-layer`
+   - Develop only one task at a time
+   - Run lint and tests frequently
+
+3. **After development complete**:
+   - Use `/trellis:finish-work` for completion checklist
+   - After fix bug, use `/trellis:break-loop` for deep analysis
+   - Human commits after testing passes
+   - Use `add_session.py` to record progress
+
+### [X] DON'T - Should Not Do
+
+1. [!] **Don't** skip reading `.trellis/spec/` guidelines
+2. [!] **Don't** let journal single file exceed 2000 lines
+3. **Don't** develop multiple unrelated tasks simultaneously
+4. **Don't** commit code with lint/test errors
+5. **Don't** forget to update spec docs after learning something
+6. [!] **Don't** execute `git commit` - AI should not commit code
+
+---
+
+## Quick Reference
+
+### Must-read Before Development
+
+| Task Type | Must-read Document |
+|-----------|-------------------|
+| Frontend work | `frontend/index.md` → relevant docs |
+| Backend work | `backend/index.md` → relevant docs |
+| Cross-Layer Feature | `guides/cross-layer-thinking-guide.md` |
+
+### Commit Convention
+
+```bash
+git commit -m "type(scope): description"
+```
+
+**Type**: feat, fix, docs, refactor, test, chore
+**Scope**: Module name (e.g., auth, api, ui)
+
+### Common Commands
+
+```bash
+# Session management
+python3 ./.trellis/scripts/get_context.py    # Get full context
+python3 ./.trellis/scripts/add_session.py    # Record session
+
+# Task management
+python3 ./.trellis/scripts/task.py list      # List tasks
+python3 ./.trellis/scripts/task.py create "<title>" # Create task
+
+# Slash commands
+/trellis:finish-work          # Pre-commit checklist
+/trellis:break-loop           # Post-debug analysis
+/trellis:check-cross-layer    # Cross-layer verification
+```
+
+---
+
+## Summary
+
+Following this workflow ensures:
+- [OK] Continuity across multiple sessions
+- [OK] Consistent code quality
+- [OK] Trackable progress
+- [OK] Knowledge accumulation in spec docs
+- [OK] Transparent team collaboration
+
+**Core Philosophy**: Read before write, follow standards, record promptly, capture learnings
diff --git a/.trellis/workspace/index.md b/.trellis/workspace/index.md
new file mode 100644
index 000000000..427947fc5
--- /dev/null
+++ b/.trellis/workspace/index.md
@@ -0,0 +1,123 @@
+# Workspace Index
+
+> Records of all AI Agent work records across all developers
+
+---
+
+## Overview
+
+This directory tracks records for all developers working with AI Agents on this project.
+
+### File Structure
+
+```
+workspace/
+|-- index.md              # This file - main index
++-- {developer}/          # Per-developer directory
+    |-- index.md          # Personal index with session history
+    |-- tasks/         # Task files
+    |   |-- *.json        # Active tasks
+    |   +-- archive/      # Archived tasks by month
+    +-- journal-N.md     # Journal files (sequential: 1, 2, 3...)
+```
+
+---
+
+## Active Developers
+
+| Developer | Last Active | Sessions | Active File |
+|-----------|-------------|----------|-------------|
+| (none yet) | - | - | - |
+
+---
+
+## Getting Started
+
+### For New Developers
+
+Run the initialization script:
+
+```bash
+python3 ./.trellis/scripts/init_developer.py <your-name>
+```
+
+This will:
+1. Create your identity file (gitignored)
+2. Create your progress directory
+3. Create your personal index
+4. Create initial journal file
+
+### For Returning Developers
+
+1. Get your developer name:
+   ```bash
+   python3 ./.trellis/scripts/get_developer.py
+   ```
+
+2. Read your personal index:
+   ```bash
+   cat .trellis/workspace/$(python3 ./.trellis/scripts/get_developer.py)/index.md
+   ```
+
+---
+
+## Guidelines
+
+### Journal File Rules
+
+- **Max 2000 lines** per journal file
+- When limit is reached, create `journal-{N+1}.md`
+- Update your personal `index.md` when creating new files
+
+### Session Record Format
+
+Each session should include:
+- Summary: One-line description
+- Main Changes: What was modified
+- Git Commits: Commit hashes and messages
+- Next Steps: What to do next
+
+---
+
+## Session Template
+
+Use this template when recording sessions:
+
+```markdown
+## Session {N}: {Title}
+
+**Date**: YYYY-MM-DD
+**Task**: {task-name}
+
+### Summary
+
+{One-line summary}
+
+### Main Changes
+
+- {Change 1}
+- {Change 2}
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `abc1234` | {commit message} |
+
+### Testing
+
+- [OK] {Test result}
+
+### Status
+
+[OK] **Completed** / # **In Progress** / [P] **Blocked**
+
+### Next Steps
+
+- {Next step 1}
+- {Next step 2}
+```
+
+---
+
+**Language**: All documentation must be written in **English**.
diff --git a/.trellis/workspace/kun/index.md b/.trellis/workspace/kun/index.md
new file mode 100644
index 000000000..c80339c33
--- /dev/null
+++ b/.trellis/workspace/kun/index.md
@@ -0,0 +1,41 @@
+# Workspace Index - kun
+
+> Journal tracking for AI development sessions.
+
+---
+
+## Current Status
+
+<!-- @@@auto:current-status -->
+- **Active File**: `journal-1.md`
+- **Total Sessions**: 1
+- **Last Active**: 2026-04-15
+<!-- @@@/auto:current-status -->
+
+---
+
+## Active Documents
+
+<!-- @@@auto:active-documents -->
+| File | Lines | Status |
+|------|-------|--------|
+| `journal-1.md` | ~49 | Active |
+<!-- @@@/auto:active-documents -->
+
+---
+
+## Session History
+
+<!-- @@@auto:session-history -->
+| # | Date | Title | Commits |
+|---|------|-------|---------|
+| 1 | 2026-04-15 | Close coding-deepgent MVP local agent harness core | `9f60195`, `89fb741`, `fd3be9d`, `0355279`, `e58c9de`, `ede6869`, `26b0815`, `6342735`, `1ce15c0`, `18c2a1a`, `5883522` |
+<!-- @@@/auto:session-history -->
+
+---
+
+## Notes
+
+- Sessions are appended to journal files
+- New journal file created when current exceeds 2000 lines
+- Use `add_session.py` to record sessions
\ No newline at end of file
diff --git a/.trellis/workspace/kun/journal-1.md b/.trellis/workspace/kun/journal-1.md
new file mode 100644
index 000000000..d249cdab7
--- /dev/null
+++ b/.trellis/workspace/kun/journal-1.md
@@ -0,0 +1,49 @@
+# Journal - kun (Part 1)
+
+> AI development session journal
+> Started: 2026-04-14
+
+---
+
+
+
+## Session 1: Close coding-deepgent MVP local agent harness core
+
+**Date**: 2026-04-15
+**Task**: Close coding-deepgent MVP local agent harness core
+
+### Summary
+
+Completed Approach A MVP closeout through Stage 29, validated coding-deepgent end-to-end, published the MVP commit, archived completed stage tasks, and updated the canonical H01-H22 dashboard plus project handoff.
+
+### Main Changes
+
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `9f60195` | (see git log) |
+| `89fb741` | (see git log) |
+| `fd3be9d` | (see git log) |
+| `0355279` | (see git log) |
+| `e58c9de` | (see git log) |
+| `ede6869` | (see git log) |
+| `26b0815` | (see git log) |
+| `6342735` | (see git log) |
+| `1ce15c0` | (see git log) |
+| `18c2a1a` | (see git log) |
+| `5883522` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
diff --git a/.trellis/worktree.yaml b/.trellis/worktree.yaml
new file mode 100644
index 000000000..26485608c
--- /dev/null
+++ b/.trellis/worktree.yaml
@@ -0,0 +1,47 @@
+# Worktree Configuration for Multi-Agent Pipeline
+# Used for worktree initialization in multi-agent workflows
+#
+# All paths are relative to project root
+
+#-------------------------------------------------------------------------------
+# Paths
+#-------------------------------------------------------------------------------
+
+# Worktree storage directory (relative to project root)
+worktree_dir: ../trellis-worktrees
+
+#-------------------------------------------------------------------------------
+# Files to Copy
+#-------------------------------------------------------------------------------
+
+# Files to copy to each worktree (each worktree needs independent copy)
+# These files contain sensitive info or need worktree-independent config
+copy:
+  # Environment variables (uncomment and customize as needed)
+  # - .env
+  # - .env.local
+  # Workflow config
+  - .trellis/.developer
+
+#-------------------------------------------------------------------------------
+# Post-Create Hooks
+#-------------------------------------------------------------------------------
+
+# Commands to run after creating worktree
+# Executed in worktree directory, in order, abort on failure
+post_create:
+  # Install dependencies (uncomment based on your package manager)
+  # - npm install
+  # - pnpm install --frozen-lockfile
+  # - yarn install --frozen-lockfile
+
+#-------------------------------------------------------------------------------
+# Check Agent Verification (Ralph Loop)
+#-------------------------------------------------------------------------------
+
+# Commands to verify code quality before allowing check agent to finish
+# If configured, Ralph Loop will run these commands - all must pass to allow completion
+# If not configured or empty, trusts agent's completion markers
+verify:
+  # - pnpm lint
+  # - pnpm typecheck
diff --git a/README-ja.md b/README-ja.md
index 8717201b8..ed85bcaca 100644
--- a/README-ja.md
+++ b/README-ja.md
@@ -1,234 +1,182 @@
-# Learn Claude Code -- 真の Agent のための Harness Engineering
-
 [English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md)
 
-## モデルこそが Agent である
-
-コードの話をする前に、一つだけ明確にしておく。
-
-**Agent とはモデルのことだ。フレームワークではない。プロンプトチェーンではない。ドラッグ＆ドロップのワークフローではない。**
-
-### Agent とは何か
-
-Agent とはニューラルネットワークである -- Transformer、RNN、学習された関数 -- 数十億回の勾配更新を経て、行動系列データの上で環境を知覚し、目標を推論し、行動を起こすことを学んだもの。AI における "Agent" という言葉は、始まりからずっとこの意味だった。常に。
-
-人間も Agent だ。数百万年の進化的訓練によって形作られた生物的ニューラルネットワーク。感覚で世界を知覚し、脳で推論し、身体で行動する。DeepMind、OpenAI、Anthropic が "Agent" と言うとき、それはこの分野が誕生以来ずっと意味してきたものと同じだ：**行動することを学んだモデル。**
-
-歴史がその証拠を刻んでいる：
+# Learn Claude Code
 
-- **2013 -- DeepMind DQN が Atari をプレイ。** 単一のニューラルネットワークが、生のピクセルとスコアだけを受け取り、7 つの Atari 2600 ゲームを学習 -- すべての先行アルゴリズムを超え、3 つで人間の専門家を打ち負かした。2015 年には同じアーキテクチャが [49 ゲームに拡張され、プロのテスターに匹敵](https://www.nature.com/articles/nature14236)、*Nature* に掲載。ゲーム固有のルールなし。決定木なし。一つのモデルが経験から学んだ。そのモデルが Agent だった。
+高完成度の coding-agent harness を、0 から自分で実装できるようになるための教材リポジトリです。
 
-- **2019 -- OpenAI Five が Dota 2 を制覇。** 5 つのニューラルネットワークが 10 ヶ月間で [45,000 年分の Dota 2](https://openai.com/index/openai-five-defeats-dota-2-world-champions/) を自己対戦し、サンフランシスコのライブストリームで **OG** -- TI8 世界王者 -- を 2-0 で撃破。その後の公開アリーナでは 42,729 試合で勝率 99.4%。スクリプト化された戦略なし。メタプログラムされたチーム連携なし。モデルが完全に自己対戦を通じてチームワーク、戦術、リアルタイム適応を学んだ。
+このリポジトリの目的は、実運用コードの細部を逐一なぞることではありません。  
+本当に重要な設計主線を、学びやすい順序で理解し、あとで自分の手で作り直せるようになることです。
 
-- **2019 -- DeepMind AlphaStar が StarCraft II をマスター。** AlphaStar は非公開戦で[プロ選手を 10-1 で撃破](https://deepmind.google/blog/alphastar-mastering-the-real-time-strategy-game-starcraft-ii/)、その後ヨーロッパサーバーで[グランドマスター到達](https://www.nature.com/articles/d41586-019-03298-6) -- 90,000 人中の上位 0.15%。不完全情報、リアルタイム判断、チェスや囲碁を遥かに凌駕する組合せ的行動空間を持つゲーム。Agent とは？ モデルだ。訓練されたもの。スクリプトではない。
+## このリポジトリが本当に教えるもの
 
-- **2019 -- Tencent 絶悟が王者栄耀を支配。** Tencent AI Lab の「絶悟」は 2019 年 8 月 2 日、世界チャンピオンカップで [KPL プロ選手を 5v5 で撃破](https://www.jiemian.com/article/3371171.html)。1v1 モードではプロが [15 戦中 1 勝のみ、8 分以上生存不可](https://developer.aliyun.com/article/851058)。訓練強度：1 日 = 人間の 440 年。2021 年までに全ヒーロープールで KPL プロを全面的に上回った。手書きのヒーロー相性表なし。スクリプト化されたチーム編成なし。自己対戦でゲーム全体をゼロから学んだモデル。
+まず一文で言うと:
 
-- **2024-2025 -- LLM Agent がソフトウェアエンジニアリングを再構築。** Claude、GPT、Gemini -- 人類のコードと推論の全幅で訓練された大規模言語モデル -- がコーディング Agent として展開される。コードベースを読み、実装を書き、障害をデバッグし、チームで協調する。アーキテクチャは先行するすべての Agent と同一：訓練されたモデルが環境に配置され、知覚と行動のツールを与えられる。唯一の違いは、学んだものの規模と解くタスクの汎用性。
+**モデルが考え、harness がモデルに作業環境を与える。**
 
-すべてのマイルストーンが同じ真理を共有している：**"Agent" は決して周囲のコードではない。Agent は常にモデルそのものだ。**
+その作業環境を作る主な部品は次の通りです。
 
-### Agent ではないもの
+- `Agent Loop`: モデルに聞く -> ツールを実行する -> 結果を返す
+- `Tools`: エージェントの手足
+- `Planning`: 大きな作業を途中で迷わせないための小さな構造
+- `Context Management`: アクティブな文脈を小さく保つ
+- `Permissions`: モデルの意図をそのまま危険な実行にしない
+- `Hooks`: ループを書き換えずに周辺機能を足す
+- `Memory`: セッションをまたいで残すべき事実だけを保持する
+- `Prompt Construction`: 安定ルールと実行時状態から入力を組み立てる
+- `Tasks / Teams / Worktree / MCP`: 単体 agent をより大きな作業基盤へ育てる
 
-"Agent" という言葉は、プロンプト配管工の産業全体に乗っ取られてしまった。
+この教材が目指すのは:
 
-ドラッグ＆ドロップのワークフロービルダー。ノーコード "AI Agent" プラットフォーム。プロンプトチェーン・オーケストレーションライブラリ。すべて同じ幻想を共有している：LLM API 呼び出しを if-else 分岐、ノードグラフ、ハードコードされたルーティングロジックで繋ぎ合わせることが "Agent の構築" だと。
+- 主線を順序よく理解できること
+- 初学者が概念で迷子にならないこと
+- 核心メカニズムと重要データ構造を自力で再実装できること
 
-違う。彼らが作ったものはルーブ・ゴールドバーグ・マシンだ -- 過剰に設計された脆い手続き的ルールのパイプライン。LLM は美化されたテキスト補完ノードとして押し込まれているだけ。それは Agent ではない。壮大な妄想を持つシェルスクリプトだ。
+## あえて主線から外しているもの
 
-**プロンプト配管工式 "Agent" は、モデルを訓練しないプログラマーの妄想だ。** 手続き的ロジックを積み重ねて知能を力技で再現しようとする -- 巨大なルールツリー、ノードグラフ、チェーン・プロンプトの滝 -- そして十分なグルーコードがいつか自律的振る舞いを創発すると祈る。しない。工学的手段で Agency をコーディングすることはできない。Agency は学習されるものであって、プログラムされるものではない。
+実際の製品コードには、agent の本質とは直接関係しない細部も多くあります。
 
-あのシステムたちは生まれた瞬間から死んでいる：脆弱で、スケールせず、汎化が根本的に不可能。GOFAI（Good Old-Fashioned AI、古典的記号 AI）の現代版だ -- 何十年も前に学術界が放棄した記号ルールシステムが、LLM のペンキを塗り直して再登場した。パッケージが違うだけで、同じ袋小路。
+たとえば:
 
-### マインドシフト：「Agent を開発する」から Harness を開発する へ
+- パッケージングや配布の流れ
+- クロスプラットフォーム互換層
+- 企業ポリシーやテレメトリ配線
+- 歴史互換のための分岐
+- 製品統合のための細かな glue code
 
-「Agent を開発しています」と言うとき、意味できるのは二つだけだ：
+こうした要素は本番では重要でも、0 から 1 を教える主線には置きません。  
+教学リポジトリの中心は、あくまで「agent がどう動くか」です。
 
-**1. モデルを訓練する。** 強化学習、ファインチューニング、RLHF、その他の勾配ベースの手法で重みを調整する。タスクプロセスデータ -- 実ドメインにおける知覚・推論・行動の実際の系列 -- を収集し、モデルの振る舞いを形成する。DeepMind、OpenAI、Tencent AI Lab、Anthropic が行っていること。これが最も本来的な Agent 開発。
+## 想定読者
 
-**2. Harness を構築する。** モデルに動作環境を提供するコードを書く。私たちの大半が行っていることであり、このリポジトリの核心。
+このリポジトリは次の読者を想定しています。
 
-Harness とは、Agent が特定のドメインで機能するために必要なすべて：
+- 基本的な Python が読める
+- 関数、クラス、リスト、辞書は分かる
+- でも agent システムは初学者でもよい
 
-```
-Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions
-
-    Tools:          ファイル I/O、シェル、ネットワーク、データベース、ブラウザ
-    Knowledge:      製品ドキュメント、ドメイン資料、API 仕様、スタイルガイド
-    Observation:    git diff、エラーログ、ブラウザ状態、センサーデータ
-    Action:         CLI コマンド、API 呼び出し、UI インタラクション
-    Permissions:    サンドボックス、承認ワークフロー、信頼境界
-```
-
-モデルが決断する。Harness が実行する。モデルが推論する。Harness がコンテキストを提供する。モデルはドライバー。Harness は車両。
+そのため、書き方の原則をはっきり決めています。
 
-**コーディング Agent の Harness は IDE、ターミナル、ファイルシステム。** 農業 Agent の Harness はセンサーアレイ、灌漑制御、気象データフィード。ホテル Agent の Harness は予約システム、ゲストコミュニケーションチャネル、施設管理 API。Agent -- 知性、意思決定者 -- は常にモデル。Harness はドメインごとに変わる。Agent はドメインを超えて汎化する。
+- 新しい概念は、使う前に説明する
+- 1つの概念は、できるだけ1か所でまとまって理解できるようにする
+- まず「何か」、次に「なぜ必要か」、最後に「どう実装するか」を話す
+- 初学者に断片文書を拾わせて自力でつなげさせない
 
-このリポジトリは車両の作り方を教える。コーディング用の車両だ。だが設計パターンはあらゆるドメインに汎化する：農場管理、ホテル運営、工場製造、物流、医療、教育、科学研究。タスクが知覚され、推論され、実行される必要がある場所ならどこでも -- Agent には Harness が要る。
+## 学習の約束
 
-### Harness エンジニアの仕事
+この教材を一通り終えたとき、目標は次の 2 つです。
 
-このリポジトリを読んでいるなら、あなたはおそらく Harness エンジニアだ -- それは強力なアイデンティティ。以下があなたの本当の仕事：
+1. 0 から自分で、構造が明快で反復改善できる coding-agent harness を組み立てられること
+2. より複雑な実装を読むときに、何が設計主線で何が製品周辺の detail なのかを見分けられること
 
-- **ツールの実装。** Agent に手を与える。ファイル読み書き、シェル実行、API 呼び出し、ブラウザ制御、データベースクエリ。各ツールは Agent が環境内で取れる行動。原子的で、組み合わせ可能で、記述が明確であるように設計する。
+このリポジトリが重視するのは:
 
-- **知識のキュレーション。** Agent にドメイン専門性を与える。製品ドキュメント、アーキテクチャ決定記録、スタイルガイド、規制要件。オンデマンドで読み込み（s05）、前もって詰め込まない。Agent は何が利用可能か知った上で、必要なものを自ら取得すべき。
+- 重要メカニズムと主要データ構造の高い再現度
+- 自分の手で作り直せる実装可能性
+- 途中で心智がねじれにくい読み順と説明密度
 
-- **コンテキストの管理。** Agent にクリーンな記憶を与える。サブ Agent 隔離（s04）がノイズの漏洩を防ぐ。コンテキスト圧縮（s06）が履歴の氾濫を防ぐ。タスクシステム（s07）が目標を単一の会話を超えて永続化する。
+## 推奨される読み順
 
-- **権限の制御。** Agent に境界を与える。ファイルアクセスのサンドボックス化。破壊的操作への承認要求。Agent と外部システム間の信頼境界の実施。安全工学と Harness 工学の交差点。
+日本語版でも主線・bridge doc・web の主要導線は揃えています。  
+章順と補助資料は、日本語でもそのまま追えるように保っています。
 
-- **タスクプロセスデータの収集。** Agent があなたの Harness 内で実行するすべての行動系列は訓練シグナル。実デプロイメントの知覚-推論-行動トレースは、次世代 Agent モデルをファインチューニングする原材料。あなたの Harness は Agent に仕えるだけでなく -- Agent を進化させる助けにもなる。
+- 全体マップ: [`docs/ja/s00-architecture-overview.md`](./docs/ja/s00-architecture-overview.md)
+- コード読解順: [`docs/ja/s00f-code-reading-order.md`](./docs/ja/s00f-code-reading-order.md)
+- 用語集: [`docs/ja/glossary.md`](./docs/ja/glossary.md)
+- 教材範囲: [`docs/ja/teaching-scope.md`](./docs/ja/teaching-scope.md)
+- データ構造表: [`docs/ja/data-structures.md`](./docs/ja/data-structures.md)
 
-あなたは知性を書いているのではない。知性が住まう世界を構築している。その世界の品質 -- Agent がどれだけ明瞭に知覚でき、どれだけ正確に行動でき、利用可能な知識がどれだけ豊かか -- が、知性がどれだけ効果的に自らを表現できるかを直接決定する。
+## 初めてこのリポジトリを開くなら
 
-**優れた Harness を作れ。Agent が残りをやる。**
+最初から章をばらばらに開かない方が安定します。
 
-### なぜ Claude Code か -- Harness Engineering の大師範
+最も安全な入口は次の順序です。
 
-なぜこのリポジトリは特に Claude Code を解剖するのか？
+1. [`docs/ja/s00-architecture-overview.md`](./docs/ja/s00-architecture-overview.md) で全体図をつかむ
+2. [`docs/ja/s00d-chapter-order-rationale.md`](./docs/ja/s00d-chapter-order-rationale.md) で、なぜこの順序で学ぶのかを確認する
+3. [`docs/ja/s00f-code-reading-order.md`](./docs/ja/s00f-code-reading-order.md) で、ローカルの `agents/*.py` をどの順で開くか確認する
+4. `s01-s06 -> s07-s11 -> s12-s14 -> s15-s19` の 4 段階で主線を順に進める
+5. 各段階の終わりで一度止まり、最小版を自分で書き直してから次へ進む
 
-Claude Code は私たちが見てきた中で最もエレガントで完成度の高い Agent Harness だからだ。単一の巧妙なトリックのためではなく、それが *しないこと* のために：Agent そのものになろうとしない。硬直的なワークフローを押し付けない。精緻な決定木でモデルを二度推しない。ツール、知識、コンテキスト管理、権限境界をモデルに提供し -- そして道を譲る。
+## Deep Agents s01-s11 トラック
 
-Claude Code の本質を剥き出しにすると：
-
-```
-Claude Code = 一つの agent loop
-            + ツール (bash, read, write, edit, glob, grep, browser...)
-            + オンデマンド skill ロード
-            + コンテキスト圧縮
-            + サブ Agent スポーン
-            + 依存グラフ付きタスクシステム
-            + 非同期メールボックスによるチーム協調
-            + worktree 分離による並列実行
-            + 権限ガバナンス
-```
+このリポジトリには、第一マイルストーンとして LangChain / Deep Agents 教材トラック [`agents_deepagents/`](./agents_deepagents/) もあります。対象は `s01-s11` です。既存の `agents/*.py` Anthropic SDK 手書き実装は対照用にそのまま残しつつ、元チュートリアルの内部機構を逐語的に再現するのではなく、各章の重要な振る舞いを保ったまま、各 `sNN` ファイルでより自然な LangChain-native 実装を選ぶ方針です。web UI にはまだ接続していません。
 
-これがすべてだ。これが全アーキテクチャ。すべてのコンポーネントは Harness メカニズム -- Agent が住む世界の一部。Agent そのものは？ Claude だ。モデル。Anthropic が人類の推論とコードの全幅で訓練した。Harness が Claude を賢くしたのではない。Claude は元々賢い。Harness が Claude に手と目とワークスペースを与えた。
+中盤以降で境界が混ざり始めたら、次の順で立て直すのが安定です。
 
-これが Claude Code が理想的な教材である理由だ：**モデルを信頼し、工学的努力を Harness に集中させるとどうなるかを示している。** このリポジトリの各セッション（s01-s12）は Claude Code アーキテクチャから一つの Harness メカニズムをリバースエンジニアリングする。終了時には、Claude Code の仕組みだけでなく、あらゆるドメインのあらゆる Agent に適用される Harness 工学の普遍的原則を理解している。
+1. [`docs/ja/data-structures.md`](./docs/ja/data-structures.md)
+2. [`docs/ja/entity-map.md`](./docs/ja/entity-map.md)
+3. いま詰まっている章に近い bridge doc
+4. その後で章本文へ戻る
 
-教訓は「Claude Code をコピーせよ」ではない。教訓は：**最高の Agent プロダクトは、自分の仕事が Harness であって Intelligence ではないと理解しているエンジニアが作る。**
+## Web 学習入口
 
----
+章順、段階境界、章どうしの差分を可視化から入りたい場合は、組み込みの web 教材画面を使えます。
 
-## ビジョン：宇宙を本物の Agent で満たす
-
-これはコーディング Agent だけの話ではない。
-
-人間が複雑で多段階の判断集約的な仕事をしているすべてのドメインは、Agent が稼働できるドメインだ -- 正しい Harness さえあれば。このリポジトリのパターンは普遍的だ：
-
-```
-不動産管理 Agent  = モデル + 物件センサー + メンテナンスツール + テナント通信
-農業 Agent        = モデル + 土壌/気象データ + 灌漑制御 + 作物知識
-ホテル運営 Agent  = モデル + 予約システム + ゲストチャネル + 施設 API
-医学研究 Agent    = モデル + 文献検索 + 実験機器 + プロトコル文書
-製造 Agent        = モデル + 生産ラインセンサー + 品質管理 + 物流
-教育 Agent        = モデル + カリキュラム知識 + 学生進捗 + 評価ツール
-```
-
-ループは常に同じ。ツールが変わる。知識が変わる。権限が変わる。Agent -- モデル -- がすべてを汎化する。
-
-このリポジトリを読むすべての Harness エンジニアは、ソフトウェアエンジニアリングを遥かに超えたパターンを学んでいる。知的で自動化された未来のためのインフラストラクチャを構築することを学んでいる。実ドメインにデプロイされた優れた Harness の一つ一つが、Agent が知覚し、推論し、行動できる新たな拠点。
-
-まずワークショップを満たす。次に農場、病院、工場。次に都市。次に惑星。
-
-**Bash is all you need. Real agents are all the universe needs.**
-
----
-
-```
-                    THE AGENT PATTERN
-                    =================
-
-    User --> messages[] --> LLM --> response
-                                      |
-                            stop_reason == "tool_use"?
-                           /                          \
-                         yes                           no
-                          |                             |
-                    execute tools                    return text
-                    append results
-                    loop back -----------------> messages[]
-
-
-    最小ループ。すべての AI Agent にこのループが必要だ。
-    モデルがツール呼び出しと停止を決める。
-    コードはモデルの要求を実行するだけ。
-    このリポジトリはこのループを囲むすべて --
-    Agent を特定ドメインで効果的にする Harness -- の作り方を教える。
-```
-
-**12 の段階的セッション、シンプルなループから分離された自律実行まで。**
-**各セッションは 1 つの Harness メカニズムを追加する。各メカニズムには 1 つのモットーがある。**
-
-> **s01** &nbsp; *"One loop & Bash is all you need"* &mdash; 1つのツール + 1つのループ = エージェント
->
-> **s02** &nbsp; *"ツールを足すなら、ハンドラーを1つ足すだけ"* &mdash; ループは変わらない。新ツールは dispatch map に登録するだけ
->
-> **s03** &nbsp; *"計画のないエージェントは行き当たりばったり"* &mdash; まずステップを書き出し、それから実行
->
-> **s04** &nbsp; *"大きなタスクを分割し、各サブタスクにクリーンなコンテキストを"* &mdash; サブエージェントは独立した messages[] を使い、メイン会話を汚さない
->
-> **s05** &nbsp; *"必要な知識を、必要な時に読み込む"* &mdash; system prompt ではなく tool_result で注入
->
-> **s06** &nbsp; *"コンテキストはいつか溢れる、空ける手段が要る"* &mdash; 3層圧縮で無限セッションを実現
->
-> **s07** &nbsp; *"大きな目標を小タスクに分解し、順序付けし、ディスクに記録する"* &mdash; ファイルベースのタスクグラフ、マルチエージェント協調の基盤
->
-> **s08** &nbsp; *"遅い操作はバックグラウンドへ、エージェントは次を考え続ける"* &mdash; デーモンスレッドがコマンド実行、完了後に通知を注入
->
-> **s09** &nbsp; *"一人で終わらないなら、チームメイトに任せる"* &mdash; 永続チームメイト + 非同期メールボックス
->
-> **s10** &nbsp; *"チームメイト間には統一の通信ルールが必要"* &mdash; 1つの request-response パターンが全交渉を駆動
->
-> **s11** &nbsp; *"チームメイトが自らボードを見て、仕事を取る"* &mdash; リーダーが逐一割り振る必要はない
->
-> **s12** &nbsp; *"各自のディレクトリで作業し、互いに干渉しない"* &mdash; タスクは目標を管理、worktree はディレクトリを管理、IDで紐付け
-
----
-
-## コアパターン
-
-```python
-def agent_loop(messages):
-    while True:
-        response = client.messages.create(
-            model=MODEL, system=SYSTEM,
-            messages=messages, tools=TOOLS,
-        )
-        messages.append({"role": "assistant",
-                         "content": response.content})
-
-        if response.stop_reason != "tool_use":
-            return
-
-        results = []
-        for block in response.content:
-            if block.type == "tool_use":
-                output = TOOL_HANDLERS[block.name](**block.input)
-                results.append({
-                    "type": "tool_result",
-                    "tool_use_id": block.id,
-                    "content": output,
-                })
-        messages.append({"role": "user", "content": results})
+```sh
+cd web
+npm install
+npm run dev
 ```
 
-各セッションはこのループの上に 1 つの Harness メカニズムを重ねる -- ループ自体は変わらない。ループは Agent のもの。メカニズムは Harness のもの。
-
-## スコープ (重要)
-
-このリポジトリは Harness 工学の 0->1 学習プロジェクト -- Agent モデルを囲む環境の構築を学ぶ。
-学習を優先するため、以下の本番メカニズムは意図的に簡略化または省略している：
-
-- 完全なイベント / Hook バス (例: PreToolUse, SessionStart/End, ConfigChange)。
-  s12 では教材用に最小の追記型ライフサイクルイベントのみ実装。
-- ルールベースの権限ガバナンスと信頼フロー
-- セッションライフサイクル制御 (resume/fork) と高度な worktree ライフサイクル制御
-- MCP ランタイムの詳細 (transport/OAuth/リソース購読/ポーリング)
-
-このリポジトリの JSONL メールボックス方式は教材用の実装であり、特定の本番内部実装を主張するものではない。
+開いたあと、まず見ると良いルートは次です。
+
+- `/ja`: 日本語の学習入口。最初にどの読み方を選ぶか決める
+- `/ja/timeline`: 主線を順にたどる最も安定した入口
+- `/ja/layers`: 4 段階の境界を先に理解する入口
+- `/ja/compare`: 2 章の差やジャンプ診断を見る入口
+
+初回読みに最も向くのは `timeline` です。  
+途中で境界が混ざったら、先に `layers` と `compare` を見てから本文へ戻る方が安定します。
+
+### 橋渡しドキュメント
+
+これは新しい主線章ではなく、中盤以降の理解をつなぐための補助文書です。
+
+- なぜこの章順なのか: [`docs/ja/s00d-chapter-order-rationale.md`](./docs/ja/s00d-chapter-order-rationale.md)
+- このリポジトリのコード読解順: [`docs/ja/s00f-code-reading-order.md`](./docs/ja/s00f-code-reading-order.md)
+- 参照リポジトリのモジュール対応: [`docs/ja/s00e-reference-module-map.md`](./docs/ja/s00e-reference-module-map.md)
+- クエリ制御プレーン: [`docs/ja/s00a-query-control-plane.md`](./docs/ja/s00a-query-control-plane.md)
+- 1リクエストの全ライフサイクル: [`docs/ja/s00b-one-request-lifecycle.md`](./docs/ja/s00b-one-request-lifecycle.md)
+- クエリ遷移モデル: [`docs/ja/s00c-query-transition-model.md`](./docs/ja/s00c-query-transition-model.md)
+- ツール制御プレーン: [`docs/ja/s02a-tool-control-plane.md`](./docs/ja/s02a-tool-control-plane.md)
+- ツール実行ランタイム: [`docs/ja/s02b-tool-execution-runtime.md`](./docs/ja/s02b-tool-execution-runtime.md)
+- Message / Prompt パイプライン: [`docs/ja/s10a-message-prompt-pipeline.md`](./docs/ja/s10a-message-prompt-pipeline.md)
+- ランタイムタスクモデル: [`docs/ja/s13a-runtime-task-model.md`](./docs/ja/s13a-runtime-task-model.md)
+- MCP 能力レイヤー: [`docs/ja/s19a-mcp-capability-layers.md`](./docs/ja/s19a-mcp-capability-layers.md)
+- Teammate・Task・Lane モデル: [`docs/ja/team-task-lane-model.md`](./docs/ja/team-task-lane-model.md)
+- エンティティ地図: [`docs/ja/entity-map.md`](./docs/ja/entity-map.md)
+
+### 4 段階の主線
+
+1. `s01-s06`: まず単体 agent のコアを作る
+2. `s07-s11`: 安全性、拡張性、記憶、prompt、recovery を足す
+3. `s12-s14`: 一時的な計画を持続的なランタイム作業へ育てる
+4. `s15-s19`: チーム、プロトコル、自律動作、分離実行、外部 capability routing へ進む
+
+### 主線の章
+
+| 章 | テーマ | 得られるもの |
+|---|---|---|
+| `s00` | Architecture Overview | 全体マップ、用語、学習順 |
+| `s01` | Agent Loop | 最小の動く agent ループ |
+| `s02` | Tool Use | 安定したツール分配 |
+| `s03` | Todo / Planning | 可視化されたセッション計画 |
+| `s04` | Subagent | 委譲時の新鮮な文脈 |
+| `s05` | Skills | 必要な知識だけを後から読む仕組み |
+| `s06` | Context Compact | アクティブ文脈を小さく保つ |
+| `s07` | Permission System | 実行前の安全ゲート |
+| `s08` | Hook System | ループ周辺の拡張点 |
+| `s09` | Memory System | セッションをまたぐ長期情報 |
+| `s10` | System Prompt | セクション分割された prompt 組み立て |
+| `s11` | Error Recovery | 続行・再試行・停止の分岐 |
+| `s12` | Task System | 永続タスクグラフ |
+| `s13` | Background Tasks | 非ブロッキング実行 |
+| `s14` | Cron Scheduler | 時間起点のトリガー |
+| `s15` | Agent Teams | 永続チームメイト |
+| `s16` | Team Protocols | 共有された協調ルール |
+| `s17` | Autonomous Agents | 自律的な認識・再開 |
+| `s18` | Worktree Isolation | 分離実行レーン |
+| `s19` | MCP & Plugin | 外部 capability routing |
 
 ## クイックスタート
 
@@ -236,137 +184,101 @@ def agent_loop(messages):
 git clone https://github.com/shareAI-lab/learn-claude-code
 cd learn-claude-code
 pip install -r requirements.txt
-cp .env.example .env   # .env を編集して ANTHROPIC_API_KEY を入力
-
-python agents/s01_agent_loop.py       # ここから開始
-python agents/s12_worktree_task_isolation.py  # 全セッションの到達点
-python agents/s_full.py               # 総括: 全メカニズム統合
+cp .env.example .env
 ```
 
-### Web プラットフォーム
-
-インタラクティブな可視化、ステップスルーアニメーション、ソースビューア、各セッションのドキュメント。
+その後、`.env` に `ANTHROPIC_API_KEY` または互換エンドポイントを設定してから:
 
 ```sh
-cd web && npm install && npm run dev   # http://localhost:3000
-```
-
-## 学習パス
-
-```
-フェーズ1: ループ                     フェーズ2: 計画と知識
-==================                   ==============================
-s01  エージェントループ      [1]     s03  TodoWrite               [5]
-     while + stop_reason                  TodoManager + nag リマインダー
-     |                                    |
-     +-> s02  Tool Use            [4]     s04  サブエージェント      [5]
-              dispatch map: name->handler     子ごとに新しい messages[]
-                                              |
-                                         s05  Skills               [5]
-                                              SKILL.md を tool_result で注入
-                                              |
-                                         s06  Context Compact      [5]
-                                              3層コンテキスト圧縮
-
-フェーズ3: 永続化                     フェーズ4: チーム
-==================                   =====================
-s07  タスクシステム           [8]     s09  エージェントチーム      [9]
-     ファイルベース CRUD + 依存グラフ      チームメイト + JSONL メールボックス
-     |                                    |
-s08  バックグラウンドタスク   [6]     s10  チームプロトコル        [12]
-     デーモンスレッド + 通知キュー         シャットダウン + プラン承認 FSM
-                                          |
-                                     s11  自律エージェント        [14]
-                                          アイドルサイクル + 自動クレーム
-                                     |
-                                     s12  Worktree 分離           [16]
-                                          タスク調整 + 必要時の分離実行レーン
-
-                                     [N] = ツール数
+python agents/s01_agent_loop.py
+python agents/s18_worktree_task_isolation.py
+python agents/s19_mcp_plugin.py
+python agents/s_full.py
 ```
 
-## プロジェクト構成
+Deep Agents s01-s11 トラックを動かす場合は、`OPENAI_API_KEY` （必要なら `OPENAI_MODEL` と `OPENAI_BASE_URL`）を設定してから実行します:
 
+```sh
+python agents_deepagents/s01_agent_loop.py
+python agents_deepagents/s06_context_compact.py
+python agents_deepagents/s11_error_recovery.py
 ```
-learn-claude-code/
-|
-|-- agents/                        # Python リファレンス実装 (s01-s12 + s_full 総括)
-|-- docs/{en,zh,ja}/               # メンタルモデル優先のドキュメント (3言語)
-|-- web/                           # インタラクティブ学習プラットフォーム (Next.js)
-|-- skills/                        # s05 の Skill ファイル
-+-- .github/workflows/ci.yml      # CI: 型チェック + ビルド
-```
-
-## ドキュメント
-
-メンタルモデル優先: 問題、解決策、ASCII図、最小限のコード。
-[English](./docs/en/) | [中文](./docs/zh/) | [日本語](./docs/ja/)
 
-| セッション | トピック | モットー |
-|-----------|---------|---------|
-| [s01](./docs/ja/s01-the-agent-loop.md) | エージェントループ | *One loop & Bash is all you need* |
-| [s02](./docs/ja/s02-tool-use.md) | Tool Use | *ツールを足すなら、ハンドラーを1つ足すだけ* |
-| [s03](./docs/ja/s03-todo-write.md) | TodoWrite | *計画のないエージェントは行き当たりばったり* |
-| [s04](./docs/ja/s04-subagent.md) | サブエージェント | *大きなタスクを分割し、各サブタスクにクリーンなコンテキストを* |
-| [s05](./docs/ja/s05-skill-loading.md) | Skills | *必要な知識を、必要な時に読み込む* |
-| [s06](./docs/ja/s06-context-compact.md) | Context Compact | *コンテキストはいつか溢れる、空ける手段が要る* |
-| [s07](./docs/ja/s07-task-system.md) | タスクシステム | *大きな目標を小タスクに分解し、順序付けし、ディスクに記録する* |
-| [s08](./docs/ja/s08-background-tasks.md) | バックグラウンドタスク | *遅い操作はバックグラウンドへ、エージェントは次を考え続ける* |
-| [s09](./docs/ja/s09-agent-teams.md) | エージェントチーム | *一人で終わらないなら、チームメイトに任せる* |
-| [s10](./docs/ja/s10-team-protocols.md) | チームプロトコル | *チームメイト間には統一の通信ルールが必要* |
-| [s11](./docs/ja/s11-autonomous-agents.md) | 自律エージェント | *チームメイトが自らボードを見て、仕事を取る* |
-| [s12](./docs/ja/s12-worktree-task-isolation.md) | Worktree + タスク分離 | *各自のディレクトリで作業し、互いに干渉しない* |
+おすすめの進め方:
 
-## 次のステップ -- 理解から出荷へ
+1. まず `s01` を動かし、最小ループが本当に動くことを確認する
+2. `s00` を読みながら `s01 -> s11` を順に進める
+3. 単体 agent 本体と control plane が安定して理解できてから `s12 -> s19` に入る
+4. 最後に `s_full.py` を見て、全部の機構を一枚の全体像に戻す
 
-12 セッションを終えれば、Harness 工学の内部構造を完全に理解している。その知識を活かす 2 つの方法:
+### Deep Agents トラック（s01-s11）
 
-### Kode Agent CLI -- オープンソース Coding Agent CLI
+第一マイルストーンの LangChain / Deep Agents 教材実装は `agents_deepagents/` にあります。`s01-s11` の章立てはナビゲーション用に残しつつ、各ファイル内部ではより自然な LangChain-native 実装を優先します。実行時は OpenAI 互換の `OPENAI_API_KEY`、任意の `OPENAI_BASE_URL`、`OPENAI_MODEL` を使い、既存の `agents/*.py` Anthropic SDK ベースラインはそのまま比較用に維持します。
 
-> `npm i -g @shareai-lab/kode`
-
-Skill & LSP 対応、Windows 対応、GLM / MiniMax / DeepSeek 等のオープンモデルに接続可能。インストールしてすぐ使える。
+```sh
+python agents_deepagents/s01_agent_loop.py
+python agents_deepagents/s06_context_compact.py
+python agents_deepagents/s11_error_recovery.py
+```
 
-GitHub: **[shareAI-lab/Kode-cli](https://github.com/shareAI-lab/Kode-cli)**
+ファイル対応表、移行方針、および「テストでは live API key / ネットワーク呼び出しを使わない」
+方針は [`agents_deepagents/README.md`](./agents_deepagents/README.md) を参照してください。
+現在の Web 学習 UI には、この Deep Agents トラックはまだ表示されません。
 
-### Kode Agent SDK -- アプリにエージェント機能を埋め込む
+## 各章の読み方
 
-公式 Claude Code Agent SDK は内部で完全な CLI プロセスと通信する -- 同時ユーザーごとに独立のターミナルプロセスが必要。Kode SDK は独立ライブラリでユーザーごとのプロセスオーバーヘッドがなく、バックエンド、ブラウザ拡張、組み込みデバイス等に埋め込み可能。
+各章は、次の順序で読むと理解しやすいです。
 
-GitHub: **[shareAI-lab/Kode-agent-sdk](https://github.com/shareAI-lab/Kode-agent-sdk)**
+1. この機構がないと何が困るか
+2. 新しい概念は何か
+3. 最小で正しい実装は何か
+4. 状態はどこに置かれるのか
+5. それがループにどう接続されるのか
+6. この章ではどこで一度止まり、何を後回しにしてよいのか
 
----
+もし読んでいて:
 
-## 姉妹教材: *オンデマンドセッション*から*常時稼働アシスタント*へ
+- 「これは主線なのか、補足なのか」
+- 「この状態は結局どこにあるのか」
 
-本リポジトリが教える Harness は **使い捨て型** -- ターミナルを開き、Agent にタスクを与え、終わったら閉じる。次のセッションは白紙から始まる。Claude Code のモデル。
+と迷ったら、次を見直してください。
 
-[OpenClaw](https://github.com/openclaw/openclaw) は別の可能性を証明した: 同じ agent core の上に 2 つの Harness メカニズムを追加するだけで、Agent は「突かないと動かない」から「30 秒ごとに自分で起きて仕事を探す」に変わる:
+- [`docs/ja/teaching-scope.md`](./docs/ja/teaching-scope.md)
+- [`docs/ja/data-structures.md`](./docs/ja/data-structures.md)
+- [`docs/ja/entity-map.md`](./docs/ja/entity-map.md)
 
-- **ハートビート** -- 30 秒ごとに Harness が Agent にメッセージを送り、やることがあるか確認させる。なければスリープ続行、あれば即座に行動。
-- **Cron** -- Agent が自ら未来のタスクをスケジュールし、時間が来たら自動実行。
+## 構成
 
-さらにマルチチャネル IM ルーティング (WhatsApp / Telegram / Slack / Discord 等 13+ プラットフォーム)、永続コンテキストメモリ、Soul パーソナリティシステムを加えると、Agent は使い捨てツールから常時稼働のパーソナル AI アシスタントへ変貌する。
+```text
+learn-claude-code/
+├── agents/              # 章ごとの実行可能な Python 参考実装
+├── agents_deepagents/   # s01-s11 の LangChain-native Deep Agents 教材トラック
+├── docs/zh/             # 中国語の主線文書
+├── docs/en/             # 英語文書
+├── docs/ja/             # 日本語文書
+├── skills/              # s05 で使う skill ファイル
+├── web/                 # Web 教学プラットフォーム
+└── requirements.txt
+```
 
-**[claw0](https://github.com/shareAI-lab/claw0)** はこれらの Harness メカニズムをゼロから分解する姉妹教材リポジトリ:
+## 言語の状態
 
-```
-claw agent = agent core + heartbeat + cron + IM chat + memory + soul
-```
+中国語が正本であり、更新も最も速いです。
 
-```
-learn-claude-code                   claw0
-(agent harness コア:                 (能動的な常時稼働 harness:
- ループ、ツール、計画、                ハートビート、cron、IM チャネル、
- チーム、worktree 分離)                メモリ、Soul パーソナリティ)
-```
+- `zh`: 最も完全で、最もレビューされている
+- `en`: 主線章と主要な橋渡し文書が利用できる
+- `ja`: 主線章と主要な橋渡し文書が利用できる
 
-## ライセンス
+最も深く、最も更新の速い説明を追うなら、まず中国語版を優先してください。
 
-MIT
+## 最終目標
 
----
+読み終わるころには、次の問いに自分の言葉で答えられるようになるはずです。
 
-**モデルが Agent だ。コードは Harness だ。優れた Harness を作れ。Agent が残りをやる。**
+- coding agent の最小状態は何か
+- `tool_result` がなぜループの中心なのか
+- どういう時に subagent を使うべきか
+- permissions、hooks、memory、prompt、task がそれぞれ何を解決するのか
+- いつ単体 agent を tasks、teams、worktrees、MCP へ成長させるべきか
 
-**Bash is all you need. Real agents are all the universe needs.**
+それを説明できて、自分で似たシステムを作れるなら、このリポジトリの目的は達成です。
diff --git a/README-zh.md b/README-zh.md
index 843cce1f3..28c73ac26 100644
--- a/README-zh.md
+++ b/README-zh.md
@@ -1,372 +1,387 @@
-# Learn Claude Code -- 真正的 Agent Harness 工程
+# Learn Claude Code
 
 [English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md)
 
-## 模型就是 Agent
+一个面向实现者的教学仓库：从零开始，手搓一个高完成度的 coding agent harness。
 
-在讨论代码之前，先把一件事彻底说清楚。
+这里教的不是“如何逐行模仿某个官方仓库”，而是“如何抓住真正决定 agent 能力的核心机制”，用清晰、渐进、可自己实现的方式，把一个类似 Claude Code 的系统从 0 做到能用、好用、可扩展。
 
-**Agent 是模型。不是框架。不是提示词链。不是拖拽式工作流。**
+## 这个仓库到底在教什么
 
-### Agent 到底是什么
+先把一句话说清楚：
 
-Agent 是一个神经网络 -- Transformer、RNN、一个被训练出来的函数 -- 经过数十亿次梯度更新，在行动序列数据上学会了感知环境、推理目标、采取行动。"Agent" 这个词在 AI 领域从诞生之日起就是这个意思。从来都是。
+**模型负责思考。代码负责给模型提供工作环境。**
 
-人类就是 agent。一个由数百万年进化训练出来的生物神经网络，通过感官感知世界，通过大脑推理，通过身体行动。当 DeepMind、OpenAI 或 Anthropic 说 "agent" 时，他们说的和这个领域自诞生以来就一直在说的完全一样：**一个学会了行动的模型。**
+这个“工作环境”就是 `harness`。  
+对 coding agent 来说，harness 主要由这些部分组成：
 
-历史已经写好了铁证：
+- `Agent Loop`：不停地“向模型提问 -> 执行工具 -> 把结果喂回去”。
+- `Tools`：读文件、写文件、改文件、跑命令、搜索内容。
+- `Planning`：把大目标拆成小步骤，不让 agent 乱撞。
+- `Context Management`：避免上下文越跑越脏、越跑越长。
+- `Permissions`：危险操作先过安全关。
+- `Hooks`：不改核心循环，也能扩展行为。
+- `Memory`：把跨会话仍然有价值的信息保存下来。
+- `Prompt Construction`：把系统说明、工具信息、约束和上下文组装好。
+- `Tasks / Teams / Worktree / MCP`：让系统从单 agent 升级成更完整的工作平台。
 
-- **2013 -- DeepMind DQN 玩 Atari。** 一个神经网络，只接收原始像素和游戏分数，学会了 7 款 Atari 2600 游戏 -- 超越所有先前算法，在其中 3 款上击败人类专家。到 2015 年，同一架构扩展到 [49 款游戏，达到职业人类测试员水平](https://www.nature.com/articles/nature14236)，论文发表在 *Nature*。没有游戏专属规则。没有决策树。一个模型，从经验中学习。那个模型就是 agent。
+本仓库的目标，是让你真正理解这些机制为什么存在、最小版本怎么实现、什么时候该升级到更完整的版本。
 
-- **2019 -- OpenAI Five 征服 Dota 2。** 五个神经网络，在 10 个月内与自己对战了 [45,000 年的 Dota 2](https://openai.com/index/openai-five-defeats-dota-2-world-champions/)，在旧金山直播赛上 2-0 击败了 **OG** -- TI8 世界冠军。随后的公开竞技场中，AI 在 42,729 场比赛中胜率 99.4%。没有脚本化的策略。没有元编程的团队协调逻辑。模型完全通过自我对弈学会了团队协作、战术和实时适应。
+## 这个仓库不教什么
 
-- **2019 -- DeepMind AlphaStar 制霸星际争霸 II。** AlphaStar 在闭门赛中 [10-1 击败职业选手](https://deepmind.google/blog/alphastar-mastering-the-real-time-strategy-game-starcraft-ii/)，随后在欧洲服务器上达到[宗师段位](https://www.nature.com/articles/d41586-019-03298-6) -- 90,000 名玩家中的前 0.15%。一个信息不完全、实时决策、组合动作空间远超国际象棋和围棋的游戏。Agent 是什么？是模型。训练出来的。不是编出来的。
+本仓库**不追求**把某个真实生产仓库的所有实现细节逐条抄下来。
 
-- **2019 -- 腾讯绝悟统治王者荣耀。** 腾讯 AI Lab 的 "绝悟" 于 2019 年 8 月 2 日世冠杯半决赛上[以 5v5 击败 KPL 职业选手](https://www.jiemian.com/article/3371171.html)。在 1v1 模式下，职业选手 [15 场只赢 1 场，最多坚持不到 8 分钟](https://developer.aliyun.com/article/851058)。训练强度：一天等于人类 440 年。到 2021 年，绝悟在全英雄池 BO5 上全面超越 KPL 职业选手水准。没有手工编写的英雄克制表。没有脚本化的阵容编排。一个从零开始通过自我对弈学习整个游戏的模型。
+下面这些内容，如果和 agent 的核心运行机制关系不大，就不会占据主线篇幅：
 
-- **2024-2025 -- LLM Agent 重塑软件工程。** Claude、GPT、Gemini -- 在人类全部代码和推理上训练的大语言模型 -- 被部署为编程 agent。它们阅读代码库，编写实现，调试故障，团队协作。架构与之前每一个 agent 完全相同：一个训练好的模型，放入一个环境，给予感知和行动的工具。唯一的不同是它们学到的东西的规模和解决任务的通用性。
+- 打包、编译、发布流程
+- 跨平台兼容层的全部细节
+- 企业策略、遥测、远程控制、账号体系的完整接线
+- 为了历史兼容或产品集成而出现的大量边角判断
+- 只对某个特定内部运行环境有意义的命名或胶水代码
 
-每一个里程碑都共享同一个真理：**"Agent" 从来都不是外面那层代码。Agent 永远是模型本身。**
+这不是偷懒，而是教学取舍。
 
-### Agent 不是什么
+一个好的教学仓库，应该优先保证三件事：
 
-"Agent" 这个词已经被一整个提示词水管工产业劫持了。
+1. 读者能从 0 到 1 自己做出来。
+2. 读者不会被大量无关细节打断心智。
+3. 真正关键的机制、数据结构和模块协作关系讲得完整、准确、没有幻觉。
 
-拖拽式工作流构建器。无代码 "AI Agent" 平台。提示词链编排库。它们共享同一个幻觉：把 LLM API 调用用 if-else 分支、节点图、硬编码路由逻辑串在一起就算是 "构建 Agent" 了。
+## 面向的读者
 
-不是的。它们做出来的东西是鲁布·戈德堡机械 -- 一个过度工程化的、脆弱的过程式规则流水线，LLM 被楔在里面当一个美化了的文本补全节点。那不是 Agent。那是一个有着宏大妄想的 shell 脚本。
+这个仓库默认读者是：
 
-**提示词水管工式 "Agent" 是不做模型的程序员的意淫。** 他们试图通过堆叠过程式逻辑来暴力模拟智能 -- 庞大的规则树、节点图、链式提示词瀑布流 -- 然后祈祷足够多的胶水代码能涌现出自主行为。不会的。你不可能通过工程手段编码出 agency。Agency 是学出来的，不是编出来的。
+- 会一点 Python
+- 知道函数、类、字典、列表这些基础概念
+- 但不一定系统做过 agent、编译器、分布式系统或复杂工程架构
 
-那些系统从诞生之日起就已经死了：脆弱、不可扩展、根本不具备泛化能力。它们是 GOFAI（Good Old-Fashioned AI，经典符号 AI）的现代还魂 -- 几十年前就被学界抛弃的符号规则系统，现在喷了一层 LLM 的漆又登场了。换了个包装，同一条死路。
+所以这里会坚持几个写法原则：
 
-### 心智转换：从 "开发 Agent" 到开发 Harness
+- 新概念先解释再使用。
+- 同一个概念尽量只在一个地方完整讲清。
+- 先讲“它是什么”，再讲“为什么需要”，最后讲“如何实现”。
+- 不把初学者扔进一堆互相引用的碎片文档里自己拼图。
 
-当一个人说 "我在开发 Agent" 时，他只可能是两个意思之一：
+## 学习承诺
 
-**1. 训练模型。** 通过强化学习、微调、RLHF 或其他基于梯度的方法调整权重。收集任务过程数据 -- 真实领域中感知、推理、行动的实际序列 -- 用它们来塑造模型的行为。这是 DeepMind、OpenAI、腾讯 AI Lab、Anthropic 在做的事。这是最本义的 Agent 开发。
+学完这套内容，你应该能做到两件事：
 
-**2. 构建 Harness。** 编写代码，为模型提供一个可操作的环境。这是我们大多数人在做的事，也是本仓库的核心。
+1. 自己从零写出一个结构清楚、可运行、可迭代的 coding agent harness。
+2. 看懂更复杂系统时，知道哪些是主干机制，哪些只是产品化外围细节。
 
-Harness 是 agent 在特定领域工作所需要的一切：
+我们追求的是：
 
-```
-Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions
-
-    Tools:          文件读写、Shell、网络、数据库、浏览器
-    Knowledge:      产品文档、领域资料、API 规范、风格指南
-    Observation:    git diff、错误日志、浏览器状态、传感器数据
-    Action:         CLI 命令、API 调用、UI 交互
-    Permissions:    沙箱隔离、审批流程、信任边界
-```
-
-模型做决策。Harness 执行。模型做推理。Harness 提供上下文。模型是驾驶者。Harness 是载具。
+- 对关键机制和关键数据结构的高保真理解
+- 对实现路径的高可操作性
+- 对教学路径的高可读性
 
-**编程 agent 的 harness 是它的 IDE、终端和文件系统。** 农业 agent 的 harness 是传感器阵列、灌溉控制和气象数据。酒店 agent 的 harness 是预订系统、客户沟通渠道和设施管理 API。Agent -- 那个智能、那个决策者 -- 永远是模型。Harness 因领域而变。Agent 跨领域泛化。
+而不是把“原始源码里存在过的所有复杂细节”一股脑堆给你。
 
-这个仓库教你造载具。编程用的载具。但设计模式可以泛化到任何领域：庄园管理、农田运营、酒店运作、工厂制造、物流调度、医疗保健、教育培训、科学研究。只要有一个任务需要被感知、推理和执行 -- agent 就需要一个 harness。
+## 建议阅读顺序
 
-### Harness 工程师到底在做什么
+先读总览，再按顺序向后读。
 
-如果你在读这个仓库，你很可能是一名 harness 工程师 -- 这是一个强大的身份。以下是你真正的工作：
+- 总览：[`docs/zh/s00-architecture-overview.md`](./docs/zh/s00-architecture-overview.md)
+- 代码阅读顺序：[`docs/zh/s00f-code-reading-order.md`](./docs/zh/s00f-code-reading-order.md)
+- 术语表：[`docs/zh/glossary.md`](./docs/zh/glossary.md)
+- 教学范围：[`docs/zh/teaching-scope.md`](./docs/zh/teaching-scope.md)
+- 数据结构总表：[`docs/zh/data-structures.md`](./docs/zh/data-structures.md)
 
-- **实现工具。** 给 agent 一双手。文件读写、Shell 执行、API 调用、浏览器控制、数据库查询。每个工具都是 agent 在环境中可以采取的一个行动。设计它们时要原子化、可组合、描述清晰。
+## 第一次打开仓库，最推荐这样走
 
-- **策划知识。** 给 agent 领域专长。产品文档、架构决策记录、风格指南、合规要求。按需加载（s05），不要前置塞入。Agent 应该知道有什么可用，然后自己拉取所需。
+如果你是第一次进这个仓库，不要随机点章节。
 
-- **管理上下文。** 给 agent 干净的记忆。子 agent 隔离（s04）防止噪声泄露。上下文压缩（s06）防止历史淹没。任务系统（s07）让目标持久化到单次对话之外。
+最稳的入口顺序是：
 
-- **控制权限。** 给 agent 边界。沙箱化文件访问。对破坏性操作要求审批。在 agent 和外部系统之间实施信任边界。这是安全工程与 harness 工程的交汇点。
+1. 先看 [`docs/zh/s00-architecture-overview.md`](./docs/zh/s00-architecture-overview.md)，确认系统全景。
+2. 再看 [`docs/zh/s00d-chapter-order-rationale.md`](./docs/zh/s00d-chapter-order-rationale.md)，确认为什么主线必须按这个顺序长出来。
+3. 再看 [`docs/zh/s00f-code-reading-order.md`](./docs/zh/s00f-code-reading-order.md)，确认本地 `agents/*.py` 该按什么顺序打开。
+4. 然后按四阶段读主线：`s01-s06 -> s07-s11 -> s12-s14 -> s15-s19`。
+5. 每学完一个阶段，停下来自己手写一个最小版本，不要等全部看完再回头补实现。
 
-- **收集任务过程数据。** Agent 在你的 harness 中执行的每一条行动序列都是训练信号。真实部署中的感知-推理-行动轨迹是微调下一代 agent 模型的原材料。你的 harness 不仅服务于 agent -- 它还可以帮助进化 agent。
+## Deep Agents s01-s11 轨道
 
-你不是在编写智能。你是在构建智能栖居的世界。这个世界的质量 -- agent 能看得多清楚、行动得多精准、可用知识有多丰富 -- 直接决定了智能能多有效地表达自己。
+仓库现在还提供第一阶段里程碑的 LangChain / Deep Agents 教学轨道：[`agents_deepagents/`](./agents_deepagents/)。它覆盖 `s01-s11`，保留原来的 `agents/*.py` Anthropic SDK 手写基线做对照，不强求逐行照搬原教程内部机制，而是优先保留每章的关键行为，并在各个 `sNN` 文件里选择更自然的 LangChain-native 实现。它也暂时不接入 web UI。
 
-**造好 Harness。Agent 会完成剩下的。**
+如果你读到一半开始打结，最稳的重启顺序是：
 
-### 为什么是 Claude Code -- Harness 工程的大师课
+1. [`docs/zh/data-structures.md`](./docs/zh/data-structures.md)
+2. [`docs/zh/entity-map.md`](./docs/zh/entity-map.md)
+3. 当前卡住章节对应的桥接文档
+4. 再回当前章节正文
 
-为什么这个仓库专门拆解 Claude Code？
+## Web 学习入口
 
-因为 Claude Code 是我们所见过的最优雅、最完整的 agent harness 实现。不是因为某个巧妙的技巧，而是因为它 *没做* 的事：它没有试图成为 agent 本身。它没有强加僵化的工作流。它没有用精心设计的决策树去替模型做判断。它给模型提供了工具、知识、上下文管理和权限边界 -- 然后让开了。
+如果你更喜欢先看可视化的主线、阶段和章节差异，可以直接跑本仓库自带的 web 教学界面：
 
-把 Claude Code 剥到本质来看：
-
-```
-Claude Code = 一个 agent loop
-            + 工具 (bash, read, write, edit, glob, grep, browser...)
-            + 按需 skill 加载
-            + 上下文压缩
-            + 子 agent 派生
-            + 带依赖图的任务系统
-            + 异步邮箱的团队协调
-            + worktree 隔离的并行执行
-            + 权限治理
+```sh
+cd web
+npm install
+npm run dev
 ```
 
-就这些。这就是全部架构。每一个组件都是 harness 机制 -- 为 agent 构建的栖居世界的一部分。Agent 本身呢？是 Claude。一个模型。由 Anthropic 在人类推理和代码的全部广度上训练而成。Harness 没有让 Claude 变聪明。Claude 本来就聪明。Harness 给了 Claude 双手、双眼和一个工作空间。
-
-这就是 Claude Code 作为教学标本的意义：**它展示了当你信任模型、把工程精力集中在 harness 上时会发生什么。** 本仓库的每一个课程（s01-s12）都在逆向工程 Claude Code 架构中的一个 harness 机制。学完之后，你理解的不只是 Claude Code 怎么工作，而是适用于任何领域、任何 agent 的 harness 工程通用原则。
+然后按这个顺序打开：
+
+- `/zh`：总入口，适合第一次进入仓库时选学习路线
+- `/zh/timeline`：看整条主线如何按顺序展开
+- `/zh/layers`：看四阶段边界，适合先理解为什么这样分层
+- `/zh/compare`：当你开始分不清两章差异时，用来做相邻对比或阶段跳跃诊断
+
+如果你是第一次学，推荐先走 `timeline`。  
+如果你已经读到中后段开始混，优先看 `layers` 和 `compare`，不要先硬钻源码。
+
+### 桥接阅读
+
+下面这些文档不是新的主线章节，而是帮助你把中后半程真正讲透的“桥接层”：
+
+- 为什么是这个章节顺序：[`docs/zh/s00d-chapter-order-rationale.md`](./docs/zh/s00d-chapter-order-rationale.md)
+- 本仓库代码阅读顺序：[`docs/zh/s00f-code-reading-order.md`](./docs/zh/s00f-code-reading-order.md)
+- 参考仓库模块映射图：[`docs/zh/s00e-reference-module-map.md`](./docs/zh/s00e-reference-module-map.md)
+- 查询控制平面：[`docs/zh/s00a-query-control-plane.md`](./docs/zh/s00a-query-control-plane.md)
+- 一次请求的完整生命周期：[`docs/zh/s00b-one-request-lifecycle.md`](./docs/zh/s00b-one-request-lifecycle.md)
+- Query 转移模型：[`docs/zh/s00c-query-transition-model.md`](./docs/zh/s00c-query-transition-model.md)
+- 工具控制平面：[`docs/zh/s02a-tool-control-plane.md`](./docs/zh/s02a-tool-control-plane.md)
+- 工具执行运行时：[`docs/zh/s02b-tool-execution-runtime.md`](./docs/zh/s02b-tool-execution-runtime.md)
+- 消息与提示词管道：[`docs/zh/s10a-message-prompt-pipeline.md`](./docs/zh/s10a-message-prompt-pipeline.md)
+- 运行时任务模型：[`docs/zh/s13a-runtime-task-model.md`](./docs/zh/s13a-runtime-task-model.md)
+- 队友-任务-车道模型：[`docs/zh/team-task-lane-model.md`](./docs/zh/team-task-lane-model.md)
+- MCP 能力层地图：[`docs/zh/s19a-mcp-capability-layers.md`](./docs/zh/s19a-mcp-capability-layers.md)
+- 系统实体边界图：[`docs/zh/entity-map.md`](./docs/zh/entity-map.md)
+
+### 四阶段主线
+
+| 阶段 | 目标 | 章节 |
+|---|---|---|
+| 阶段 1 | 先做出一个能工作的单 agent | `s01-s06` |
+| 阶段 2 | 再补安全、扩展、记忆、提示词、恢复 | `s07-s11` |
+| 阶段 3 | 把临时清单升级成真正的任务系统 | `s12-s14` |
+| 阶段 4 | 从单 agent 升级成多 agent 与外部工具平台 | `s15-s19` |
+
+### 全部章节
+
+| 章节 | 主题 | 你会得到什么 |
+|---|---|---|
+| [s00](./docs/zh/s00-architecture-overview.md) | 架构总览 | 全局地图、名词、学习顺序 |
+| [s01](./docs/zh/s01-the-agent-loop.md) | Agent Loop | 最小可运行循环 |
+| [s02](./docs/zh/s02-tool-use.md) | Tool Use | 工具注册、分发和 tool_result |
+| [s03](./docs/zh/s03-todo-write.md) | Todo / Planning | 最小计划系统 |
+| [s04](./docs/zh/s04-subagent.md) | Subagent | 上下文隔离与任务委派 |
+| [s05](./docs/zh/s05-skill-loading.md) | Skills | 按需加载知识 |
+| [s06](./docs/zh/s06-context-compact.md) | Context Compact | 上下文预算与压缩 |
+| [s07](./docs/zh/s07-permission-system.md) | Permission System | 危险操作前的权限管道 |
+| [s08](./docs/zh/s08-hook-system.md) | Hook System | 不改循环也能扩展行为 |
+| [s09](./docs/zh/s09-memory-system.md) | Memory System | 跨会话持久信息 |
+| [s10](./docs/zh/s10-system-prompt.md) | System Prompt | 提示词组装流水线 |
+| [s11](./docs/zh/s11-error-recovery.md) | Error Recovery | 错误恢复与续行 |
+| [s12](./docs/zh/s12-task-system.md) | Task System | 持久化任务图 |
+| [s13](./docs/zh/s13-background-tasks.md) | Background Tasks | 后台执行与通知 |
+| [s14](./docs/zh/s14-cron-scheduler.md) | Cron Scheduler | 定时触发 |
+| [s15](./docs/zh/s15-agent-teams.md) | Agent Teams | 多 agent 协作基础 |
+| [s16](./docs/zh/s16-team-protocols.md) | Team Protocols | 团队通信协议 |
+| [s17](./docs/zh/s17-autonomous-agents.md) | Autonomous Agents | 自治认领与调度 |
+| [s18](./docs/zh/s18-worktree-task-isolation.md) | Worktree Isolation | 并行隔离工作目录 |
+| [s19](./docs/zh/s19-mcp-plugin.md) | MCP & Plugin | 外部工具接入 |
+
+## 章节总索引：每章最该盯住什么
+
+如果你是第一次系统学这套内容，不要把注意力平均分给所有细节。  
+每章都先盯住 3 件事：
+
+1. 这一章新增了什么能力。
+2. 这一章的关键状态放在哪里。
+3. 学完以后，你自己能不能把这个最小机制手写出来。
+
+下面这张表，就是整套仓库最实用的“主线索引”。
+
+| 章节 | 最该盯住的数据结构 / 实体 | 这一章结束后你手里应该多出什么 |
+|---|---|---|
+| `s01` | `messages` / `LoopState` | 一个最小可运行的 agent loop |
+| `s02` | `ToolSpec` / `ToolDispatchMap` / `tool_result` | 一个能真正读写文件、执行动作的工具系统 |
+| `s03` | `TodoItem` / `PlanState` | 一个能把大目标拆成步骤的最小计划层 |
+| `s04` | `SubagentContext` / 子 `messages` | 一个能隔离上下文、做一次性委派的子 agent 机制 |
+| `s05` | `SkillMeta` / `SkillContent` / `SkillRegistry` | 一个按需加载知识、不把所有知识塞进 prompt 的技能层 |
+| `s06` | `CompactSummary` / `PersistedOutputMarker` | 一个能控制上下文膨胀的压缩层 |
+| `s07` | `PermissionRule` / `PermissionDecision` | 一条明确的“危险操作先过闸”的权限管道 |
+| `s08` | `HookEvent` / `HookResult` | 一套不改主循环也能扩展行为的插口系统 |
+| `s09` | `MemoryEntry` / `MemoryStore` | 一套区分“临时上下文”和“跨会话记忆”的持久层 |
+| `s10` | `PromptParts` / `SystemPromptBlock` | 一条可管理、可组装的输入管道 |
+| `s11` | `RecoveryState` / `TransitionReason` | 一套出错后还能继续往前走的恢复分支 |
+| `s12` | `TaskRecord` / `TaskStatus` | 一张持久化的工作图，而不只是会话内清单 |
+| `s13` | `RuntimeTaskState` / `Notification` | 一套慢任务后台执行、结果延后回来的运行时层 |
+| `s14` | `ScheduleRecord` / `CronTrigger` | 一套“时间到了就能自动开工”的定时触发层 |
+| `s15` | `TeamMember` / `MessageEnvelope` | 一个长期存在、能反复接活的 agent 团队雏形 |
+| `s16` | `ProtocolEnvelope` / `RequestRecord` | 一套团队之间可追踪、可批准、可拒绝的协议层 |
+| `s17` | `ClaimPolicy` / `AutonomyState` | 一套队友能自己找活、自己恢复工作的自治层 |
+| `s18` | `WorktreeRecord` / `TaskBinding` | 一套任务与隔离工作目录绑定的并行执行车道 |
+| `s19` | `MCPServerConfig` / `CapabilityRoute` | 一套把外部工具与外部能力接入主系统的总线 |
+
+## 如果你是初学者，最推荐这样读
+
+### 读法 1：最稳主线
+
+适合第一次系统接触 agent 的读者。
+
+按这个顺序读：
+
+`s00 -> s01 -> s02 -> s03 -> s04 -> s05 -> s06 -> s07 -> s08 -> s09 -> s10 -> s11 -> s12 -> s13 -> s14 -> s15 -> s16 -> s17 -> s18 -> s19`
+
+### 读法 2：先做出能跑的，再补完整
+
+适合“想先把系统搭出来，再慢慢补完”的读者。
+
+按这个顺序读：
+
+1. `s01-s06`
+2. `s07-s11`
+3. `s12-s14`
+4. `s15-s19`
+
+### 读法 3：卡住时这样回看
+
+如果你在中后半程开始打结，先不要硬往下冲。
+
+回看顺序建议是：
+
+1. [`docs/zh/s00-architecture-overview.md`](./docs/zh/s00-architecture-overview.md)
+2. [`docs/zh/data-structures.md`](./docs/zh/data-structures.md)
+3. [`docs/zh/entity-map.md`](./docs/zh/entity-map.md)
+4. 当前卡住的那一章
+
+因为读者真正卡住时，往往不是“代码没看懂”，而是：
+
+- 这个机制到底接在系统哪一层
+- 这个状态到底存在哪个结构里
+- 这个名词和另一个看起来很像的名词到底差在哪
 
-启示不是 "复制 Claude Code"。启示是：**最好的 agent 产品，出自那些明白自己的工作是 harness 而非 intelligence 的工程师之手。**
-
----
-
-## 愿景：用真正的 Agent 铺满宇宙
-
-这不只关乎编程 agent。
-
-每一个人类从事复杂、多步骤、需要判断力的工作的领域，都是 agent 可以运作的领域 -- 只要有对的 harness。本仓库中的模式是通用的：
+## 快速开始
 
+```sh
+git clone https://github.com/shareAI-lab/learn-claude-code
+cd learn-claude-code
+pip install -r requirements.txt
+cp .env.example .env
 ```
-庄园管理 agent  = 模型 + 物业传感器 + 维护工具 + 租户通信
-农业 agent      = 模型 + 土壤/气象数据 + 灌溉控制 + 作物知识
-酒店运营 agent  = 模型 + 预订系统 + 客户渠道 + 设施 API
-医学研究 agent  = 模型 + 文献检索 + 实验仪器 + 协议文档
-制造业 agent    = 模型 + 产线传感器 + 质量控制 + 物流系统
-教育 agent      = 模型 + 课程知识 + 学生进度 + 评估工具
-```
-
-循环永远不变。工具在变。知识在变。权限在变。Agent -- 那个模型 -- 泛化一切。
-
-每一个读这个仓库的 harness 工程师都在学习远超软件工程的模式。你在学习为一个智能的、自动化的未来构建基础设施。每一个部署在真实领域的好 harness，都是 agent 能够感知、推理、行动的又一个阵地。
-
-先铺满工作室。然后是农田、医院、工厂。然后是城市。然后是星球。
 
-**Bash is all you need. Real agents are all the universe needs.**
+把 `.env` 里的 `ANTHROPIC_API_KEY` 或兼容接口配置好以后：
 
----
-
-```
-                    THE AGENT PATTERN
-                    =================
-
-    User --> messages[] --> LLM --> response
-                                      |
-                            stop_reason == "tool_use"?
-                           /                          \
-                         yes                           no
-                          |                             |
-                    execute tools                    return text
-                    append results
-                    loop back -----------------> messages[]
-
-
-    这是最小循环。每个 AI Agent 都需要这个循环。
-    模型决定何时调用工具、何时停止。
-    代码只是执行模型的要求。
-    本仓库教你构建围绕这个循环的一切 --
-    让 agent 在特定领域高效工作的 harness。
+```sh
+python agents/s01_agent_loop.py
+python agents/s18_worktree_task_isolation.py
+python agents/s19_mcp_plugin.py
+python agents/s_full.py
 ```
 
-**12 个递进式课程, 从简单循环到隔离化的自治执行。**
-**每个课程添加一个 harness 机制。每个机制有一句格言。**
-
-> **s01** &nbsp; *"One loop & Bash is all you need"* &mdash; 一个工具 + 一个循环 = 一个 Agent
->
-> **s02** &nbsp; *"加一个工具, 只加一个 handler"* &mdash; 循环不用动, 新工具注册进 dispatch map 就行
->
-> **s03** &nbsp; *"没有计划的 agent 走哪算哪"* &mdash; 先列步骤再动手, 完成率翻倍
->
-> **s04** &nbsp; *"大任务拆小, 每个小任务干净的上下文"* &mdash; Subagent 用独立 messages[], 不污染主对话
->
-> **s05** &nbsp; *"用到什么知识, 临时加载什么知识"* &mdash; 通过 tool_result 注入, 不塞 system prompt
->
-> **s06** &nbsp; *"上下文总会满, 要有办法腾地方"* &mdash; 三层压缩策略, 换来无限会话
->
-> **s07** &nbsp; *"大目标要拆成小任务, 排好序, 记在磁盘上"* &mdash; 文件持久化的任务图, 为多 agent 协作打基础
->
-> **s08** &nbsp; *"慢操作丢后台, agent 继续想下一步"* &mdash; 后台线程跑命令, 完成后注入通知
->
-> **s09** &nbsp; *"任务太大一个人干不完, 要能分给队友"* &mdash; 持久化队友 + 异步邮箱
->
-> **s10** &nbsp; *"队友之间要有统一的沟通规矩"* &mdash; 一个 request-response 模式驱动所有协商
->
-> **s11** &nbsp; *"队友自己看看板, 有活就认领"* &mdash; 不需要领导逐个分配, 自组织
->
-> **s12** &nbsp; *"各干各的目录, 互不干扰"* &mdash; 任务管目标, worktree 管目录, 按 ID 绑定
+如果要运行 Deep Agents s01-s11 轨道，请另外配置 `OPENAI_API_KEY`，可选配置 `OPENAI_MODEL` 和 `OPENAI_BASE_URL`，然后运行：
 
----
-
-## 核心模式
-
-```python
-def agent_loop(messages):
-    while True:
-        response = client.messages.create(
-            model=MODEL, system=SYSTEM,
-            messages=messages, tools=TOOLS,
-        )
-        messages.append({"role": "assistant",
-                         "content": response.content})
-
-        if response.stop_reason != "tool_use":
-            return
-
-        results = []
-        for block in response.content:
-            if block.type == "tool_use":
-                output = TOOL_HANDLERS[block.name](**block.input)
-                results.append({
-                    "type": "tool_result",
-                    "tool_use_id": block.id,
-                    "content": output,
-                })
-        messages.append({"role": "user", "content": results})
+```sh
+python agents_deepagents/s01_agent_loop.py
+python agents_deepagents/s06_context_compact.py
+python agents_deepagents/s11_error_recovery.py
 ```
 
-每个课程在这个循环之上叠加一个 harness 机制 -- 循环本身始终不变。循环属于 agent。机制属于 harness。
+建议顺序：
 
-## 范围说明 (重要)
+1. 先跑 `s01`，确认最小循环真的能工作。
+2. 一边读 `s00`，一边按顺序跑 `s01 -> s10`。
+3. 等前 10 章吃透后，再进入 `s11 -> s19`。
+4. 最后再看 `s_full.py`，把所有机制放回同一张图里。
 
-本仓库是一个 0->1 的 harness 工程学习项目 -- 构建围绕 agent 模型的工作环境。
-为保证学习路径清晰，仓库有意简化或省略了部分生产机制：
+### Deep Agents 轨道（s01-s11）
 
-- 完整事件 / Hook 总线 (例如 PreToolUse、SessionStart/End、ConfigChange)。
-  s12 仅提供教学用途的最小 append-only 生命周期事件流。
-- 基于规则的权限治理与信任流程
-- 会话生命周期控制 (resume/fork) 与更完整的 worktree 生命周期控制
-- 完整 MCP 运行时细节 (transport/OAuth/资源订阅/轮询)
-
-仓库中的团队 JSONL 邮箱协议是教学实现，不是对任何特定生产内部实现的声明。
-
-## 快速开始
-
-```sh
-git clone https://github.com/shareAI-lab/learn-claude-code
-cd learn-claude-code
-pip install -r requirements.txt
-cp .env.example .env   # 编辑 .env 填入你的 ANTHROPIC_API_KEY
-
-python agents/s01_agent_loop.py       # 从这里开始
-python agents/s12_worktree_task_isolation.py  # 完整递进终点
-python agents/s_full.py               # 总纲: 全部机制合一
-```
-
-### Web 平台
-
-交互式可视化、分步动画、源码查看器, 以及每个课程的文档。
+第一阶段新增的 LangChain / Deep Agents 教学实现放在 `agents_deepagents/`。它保留
+`s01-s11` 的章节外壳作为导航线索，但在每个文件内部优先采用更自然的
+LangChain-native 实现；运行时使用 OpenAI-compatible 的
+`OPENAI_API_KEY`、可选 `OPENAI_BASE_URL` 与 `OPENAI_MODEL` 配置，同时保留
+原来的 `agents/*.py` Anthropic SDK 基线做对照。
 
 ```sh
-cd web && npm install && npm run dev   # http://localhost:3000
+python agents_deepagents/s01_agent_loop.py
+python agents_deepagents/s06_context_compact.py
+python agents_deepagents/s11_error_recovery.py
 ```
 
-## 学习路径
-
-```
-第一阶段: 循环                       第二阶段: 规划与知识
-==================                   ==============================
-s01  Agent Loop              [1]     s03  TodoWrite               [5]
-     while + stop_reason                  TodoManager + nag 提醒
-     |                                    |
-     +-> s02  Tool Use            [4]     s04  Subagent             [5]
-              dispatch map: name->handler     每个 Subagent 独立 messages[]
-                                              |
-                                         s05  Skills               [5]
-                                              SKILL.md 通过 tool_result 注入
-                                              |
-                                         s06  Context Compact      [5]
-                                              三层 Context Compact
-
-第三阶段: 持久化                     第四阶段: 团队
-==================                   =====================
-s07  Task System             [8]     s09  Agent Teams             [9]
-     文件持久化 CRUD + 依赖图             队友 + JSONL 邮箱
-     |                                    |
-s08  Background Tasks        [6]     s10  Team Protocols          [12]
-     守护线程 + 通知队列                  关机 + 计划审批 FSM
-                                          |
-                                     s11  Autonomous Agents       [14]
-                                          空闲轮询 + 自动认领
-                                     |
-                                     s12  Worktree Isolation      [16]
-                                          Task 协调 + 按需隔离执行通道
-
-                                     [N] = 工具数量
-```
+文件对应关系、迁移策略，以及“测试不需要 live API key / 网络调用”的说明见
+[`agents_deepagents/README.md`](./agents_deepagents/README.md)。当前 web 学习界面
+暂时不会展示这条 Deep Agents 轨道。
 
-## 项目结构
+## 如何读这套教程
 
-```
-learn-claude-code/
-|
-|-- agents/                        # Python 参考实现 (s01-s12 + s_full 总纲)
-|-- docs/{en,zh,ja}/               # 心智模型优先的文档 (3 种语言)
-|-- web/                           # 交互式学习平台 (Next.js)
-|-- skills/                        # s05 的 Skill 文件
-+-- .github/workflows/ci.yml      # CI: 类型检查 + 构建
-```
+每章都建议按这个顺序看：
 
-## 文档
+1. `问题`：没有这个机制会出现什么痛点。
+2. `概念定义`：先把新名词讲清楚。
+3. `最小实现`：先做最小但正确的版本。
+4. `核心数据结构`：搞清楚状态到底存在哪里。
+5. `主循环如何接入`：它如何与 agent loop 协作。
+6. `这一章先停在哪里`：先守住什么边界，哪些扩展可以后放。
 
-心智模型优先: 问题、方案、ASCII 图、最小化代码。
-[English](./docs/en/) | [中文](./docs/zh/) | [日本語](./docs/ja/)
+如果你是初学者，不要着急追求“一次看懂所有复杂机制”。  
+先把每章的最小实现真的写出来，再理解升级版边界，会轻松很多。
 
-| 课程 | 主题 | 格言 |
-|------|------|------|
-| [s01](./docs/zh/s01-the-agent-loop.md) | Agent Loop | *One loop & Bash is all you need* |
-| [s02](./docs/zh/s02-tool-use.md) | Tool Use | *加一个工具, 只加一个 handler* |
-| [s03](./docs/zh/s03-todo-write.md) | TodoWrite | *没有计划的 agent 走哪算哪* |
-| [s04](./docs/zh/s04-subagent.md) | Subagent | *大任务拆小, 每个小任务干净的上下文* |
-| [s05](./docs/zh/s05-skill-loading.md) | Skills | *用到什么知识, 临时加载什么知识* |
-| [s06](./docs/zh/s06-context-compact.md) | Context Compact | *上下文总会满, 要有办法腾地方* |
-| [s07](./docs/zh/s07-task-system.md) | Task System | *大目标要拆成小任务, 排好序, 记在磁盘上* |
-| [s08](./docs/zh/s08-background-tasks.md) | Background Tasks | *慢操作丢后台, agent 继续想下一步* |
-| [s09](./docs/zh/s09-agent-teams.md) | Agent Teams | *任务太大一个人干不完, 要能分给队友* |
-| [s10](./docs/zh/s10-team-protocols.md) | Team Protocols | *队友之间要有统一的沟通规矩* |
-| [s11](./docs/zh/s11-autonomous-agents.md) | Autonomous Agents | *队友自己看看板, 有活就认领* |
-| [s12](./docs/zh/s12-worktree-task-isolation.md) | Worktree + Task Isolation | *各干各的目录, 互不干扰* |
+如果你在阅读中经常冒出这两类问题：
 
-## 学完之后 -- 从理解到落地
+- “这一段到底算主线，还是维护者补充？”
+- “这个状态到底存在哪个结构里？”
 
-12 个课程走完, 你已经从内到外理解了 harness 工程的运作原理。两种方式把知识变成产品:
+建议随时回看：
 
-### Kode Agent CLI -- 开源 Coding Agent CLI
+- [`docs/zh/teaching-scope.md`](./docs/zh/teaching-scope.md)
+- [`docs/zh/data-structures.md`](./docs/zh/data-structures.md)
+- [`docs/zh/entity-map.md`](./docs/zh/entity-map.md)
 
-> `npm i -g @shareai-lab/kode`
+## 本仓库的教学取舍
 
-支持 Skill & LSP, 适配 Windows, 可接 GLM / MiniMax / DeepSeek 等开放模型。装完即用。
+为了保证“从 0 到 1 可实现”，本仓库会刻意做这些取舍：
 
-GitHub: **[shareAI-lab/Kode-cli](https://github.com/shareAI-lab/Kode-cli)**
+- 先教最小正确版本，再讲扩展边界。
+- 如果一个真实机制很复杂，但主干思想并不复杂，就先讲主干思想。
+- 如果一个高级名词出现了，就解释它是什么，不假设读者天然知道。
+- 如果一个真实系统里某些边角分支对教学价值不高，就直接删掉。
 
-### Kode Agent SDK -- 把 Agent 能力嵌入你的应用
+这意味着本仓库追求的是：
 
-官方 Claude Code Agent SDK 底层与完整 CLI 进程通信 -- 每个并发用户 = 一个终端进程。Kode SDK 是独立库, 无 per-user 进程开销, 可嵌入后端、浏览器插件、嵌入式设备等任意运行时。
+**核心机制高保真，外围细节有取舍。**
 
-GitHub: **[shareAI-lab/Kode-agent-sdk](https://github.com/shareAI-lab/Kode-agent-sdk)**
+这也是教学仓库最合理的做法。
 
----
+## 项目结构
 
-## 姊妹教程: 从*被动临时会话*到*主动常驻助手*
+```text
+learn-claude-code/
+├── agents/              # 每一章对应一个可运行的 Python 参考实现
+├── agents_deepagents/   # s01-s11 的 LangChain-native Deep Agents 教学轨道
+├── docs/zh/             # 中文主线文档
+├── docs/en/             # 英文文档，当前为部分同步
+├── docs/ja/             # 日文文档，当前为部分同步
+├── skills/              # s05 使用的技能文件
+├── web/                 # Web 教学平台
+└── requirements.txt
+```
 
-本仓库教的 harness 属于 **用完即走** 型 -- 开终端、给 agent 任务、做完关掉, 下次重开是全新会话。Claude Code 就是这种模式。
+## 语言说明
 
-但 [OpenClaw](https://github.com/openclaw/openclaw) 证明了另一种可能: 在同样的 agent core 之上, 加两个 harness 机制就能让 agent 从 "踹一下动一下" 变成 "自己隔 30 秒醒一次找活干":
+当前仓库以中文文档为主线，最完整、更新也最快。
 
-- **心跳 (Heartbeat)** -- 每 30 秒 harness 给 agent 发一条消息, 让它检查有没有事可做。没事就继续睡, 有事立刻行动。
-- **定时任务 (Cron)** -- agent 可以给自己安排未来要做的事, 到点自动执行。
+- `zh`：主线版本
+- `en`：部分同步
+- `ja`：部分同步
 
-再加上 IM 多通道路由 (WhatsApp/Telegram/Slack/Discord 等 13+ 平台)、不清空的上下文记忆、Soul 人格系统, agent 就从一个临时工具变成了始终在线的个人 AI 助手。
+如果你要系统学习，请优先看中文。
 
-**[claw0](https://github.com/shareAI-lab/claw0)** 是我们的姊妹教学仓库, 从零拆解这些 harness 机制:
+## 最后的目标
 
-```
-claw agent = agent core + heartbeat + cron + IM chat + memory + soul
-```
+读完这套内容，你不应该只是“知道 Claude Code 很厉害”。
 
-```
-learn-claude-code                   claw0
-(agent harness 内核:                 (主动式常驻 harness:
- 循环、工具、规划、                    心跳、定时任务、IM 通道、
- 团队、worktree 隔离)                  记忆、Soul 人格)
-```
+你应该能自己回答这些问题：
 
-## 许可证
+- 一个 coding agent 最小要有哪些状态？
+- 工具调用和 `tool_result` 为什么是核心接口？
+- 为什么要做子 agent，而不是把所有内容都塞在一个对话里？
+- 权限、hook、memory、prompt、task 这些机制分别解决什么问题？
+- 一个系统什么时候该从单 agent 升级成任务图、团队、worktree 和 MCP？
 
-MIT
+如果这些问题你都能清楚回答，而且能自己写出一个相似系统，那这套仓库就达到了它的目的。
 
 ---
 
-**模型就是 Agent。代码是 Harness。造好 Harness，Agent 会完成剩下的。**
-
-**Bash is all you need. Real agents are all the universe needs.**
+**这不是“照着源码抄”。这是“抓住真正关键的设计，然后自己做出来”。**
diff --git a/README.md b/README.md
index 02561fef1..fb64f431d 100644
--- a/README.md
+++ b/README.md
@@ -1,233 +1,190 @@
 [English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md)
-# Learn Claude Code -- Harness Engineering for Real Agents
 
-## The Model IS the Agent
+# Learn Claude Code
 
-Before we talk about code, let's get one thing absolutely straight.
+A teaching repository for implementers who want to build a high-completion coding-agent harness from scratch.
 
-**An agent is a model. Not a framework. Not a prompt chain. Not a drag-and-drop workflow.**
+This repo does not try to mirror every product detail from a production codebase. It focuses on the mechanisms that actually decide whether an agent can work well:
 
-### What an Agent IS
+- the loop
+- tools
+- planning
+- delegation
+- context control
+- permissions
+- hooks
+- memory
+- prompt assembly
+- tasks
+- teams
+- isolated execution lanes
+- external capability routing
 
-An agent is a neural network -- a Transformer, an RNN, a learned function -- that has been trained, through billions of gradient updates on action-sequence data, to perceive an environment, reason about goals, and take actions to achieve them. The word "agent" in AI has always meant this. Always.
+The goal is simple:
 
-A human is an agent. A biological neural network, shaped by millions of years of evolutionary training, perceiving the world through senses, reasoning through a brain, acting through a body. When DeepMind, OpenAI, or Anthropic say "agent," they mean the same thing the field has meant since its inception: **a model that has learned to act.**
+**understand the real design backbone well enough that you can rebuild it yourself.**
 
-The proof is written in history:
+## What This Repo Is Really Teaching
 
-- **2013 -- DeepMind DQN plays Atari.** A single neural network, receiving only raw pixels and game scores, learned to play 7 Atari 2600 games -- surpassing all prior algorithms and beating human experts on 3 of them. By 2015, the same architecture scaled to [49 games and matched professional human testers](https://www.nature.com/articles/nature14236), published in *Nature*. No game-specific rules. No decision trees. One model, learning from experience. That model was the agent.
+One sentence first:
 
-- **2019 -- OpenAI Five conquers Dota 2.** Five neural networks, having played [45,000 years of Dota 2](https://openai.com/index/openai-five-defeats-dota-2-world-champions/) against themselves in 10 months, defeated **OG** -- the reigning TI8 world champions -- 2-0 on a San Francisco livestream. In a subsequent public arena, the AI won 99.4% of 42,729 games against all comers. No scripted strategies. No meta-programmed team coordination. The models learned teamwork, tactics, and real-time adaptation entirely through self-play.
+**The model does the reasoning. The harness gives the model a working environment.**
 
-- **2019 -- DeepMind AlphaStar masters StarCraft II.** AlphaStar [beat professional players 10-1](https://deepmind.google/blog/alphastar-mastering-the-real-time-strategy-game-starcraft-ii/) in a closed-door match, and later achieved [Grandmaster status](https://www.nature.com/articles/d41586-019-03298-6) on European servers -- top 0.15% of 90,000 players. A game with imperfect information, real-time decisions, and a combinatorial action space that dwarfs chess and Go. The agent? A model. Trained. Not scripted.
+That working environment is made of a few cooperating parts:
 
-- **2019 -- Tencent Jueyu dominates Honor of Kings.** Tencent AI Lab's "Jueyu" [defeated KPL professional players](https://www.jiemian.com/article/3371171.html) in a full 5v5 match at the World Champion Cup. In 1v1 mode, pros won only [1 out of 15 games and never survived past 8 minutes](https://developer.aliyun.com/article/851058). Training intensity: one day equaled 440 human years. By 2021, Jueyu surpassed KPL pros across the full hero pool. No handcrafted matchup tables. No scripted compositions. A model that learned the entire game from scratch through self-play.
+- `Agent Loop`: ask the model, run tools, append results, continue
+- `Tools`: the agent's hands
+- `Planning`: a small structure that keeps multi-step work from drifting
+- `Context Management`: keep the active context small and coherent
+- `Permissions`: do not let model intent turn into unsafe execution directly
+- `Hooks`: extend behavior around the loop without rewriting the loop
+- `Memory`: keep only durable facts that should survive sessions
+- `Prompt Construction`: assemble the model input from stable rules and runtime state
+- `Tasks / Teams / Worktree / MCP`: grow the single-agent core into a larger working platform
 
-- **2024-2025 -- LLM agents reshape software engineering.** Claude, GPT, Gemini -- large language models trained on the entirety of human code and reasoning -- are deployed as coding agents. They read codebases, write implementations, debug failures, coordinate in teams. The architecture is identical to every agent before them: a trained model, placed in an environment, given tools to perceive and act. The only difference is the scale of what they've learned and the generality of the tasks they solve.
+This is the teaching promise of the repo:
 
-Every one of these milestones shares the same truth: **the "agent" is never the surrounding code. The agent is always the model.**
+- teach the mainline in a clean order
+- explain unfamiliar concepts before relying on them
+- stay close to real system structure
+- avoid drowning the learner in irrelevant product details
 
-### What an Agent Is NOT
+## What This Repo Deliberately Does Not Teach
 
-The word "agent" has been hijacked by an entire cottage industry of prompt plumbing.
+This repo is not trying to preserve every detail that may exist in a real production system.
 
-Drag-and-drop workflow builders. No-code "AI agent" platforms. Prompt-chain orchestration libraries. They all share the same delusion: that wiring together LLM API calls with if-else branches, node graphs, and hardcoded routing logic constitutes "building an agent."
+If a detail is not central to the agent's core operating model, it should not dominate the teaching line. That includes things like:
 
-It doesn't. What they build is a Rube Goldberg machine -- an over-engineered, brittle pipeline of procedural rules, with an LLM wedged in as a glorified text-completion node. That is not an agent. That is a shell script with delusions of grandeur.
+- packaging and release mechanics
+- cross-platform compatibility layers
+- enterprise policy glue
+- telemetry and account wiring
+- historical compatibility branches
+- product-specific naming accidents
 
-**Prompt plumbing "agents" are the fantasy of programmers who don't train models.** They attempt to brute-force intelligence by stacking procedural logic -- massive rule trees, node graphs, chain-of-prompt waterfalls -- and praying that enough glue code will somehow emergently produce autonomous behavior. It won't. You cannot engineer your way to agency. Agency is learned, not programmed.
+Those details may matter in production. They do not belong at the center of a 0-to-1 teaching path.
 
-Those systems are dead on arrival: fragile, unscalable, fundamentally incapable of generalization. They are the modern resurrection of GOFAI (Good Old-Fashioned AI) -- the symbolic rule systems the field abandoned decades ago, now spray-painted with an LLM veneer. Different packaging, same dead end.
+## Who This Is For
 
-### The Mind Shift: From "Developing Agents" to Developing Harness
+The assumed reader:
 
-When someone says "I'm developing an agent," they can only mean one of two things:
+- knows basic Python
+- understands functions, classes, lists, and dictionaries
+- may be completely new to agent systems
 
-**1. Training the model.** Adjusting weights through reinforcement learning, fine-tuning, RLHF, or other gradient-based methods. Collecting task-process data -- the actual sequences of perception, reasoning, and action in real domains -- and using it to shape the model's behavior. This is what DeepMind, OpenAI, Tencent AI Lab, and Anthropic do. This is agent development in the truest sense.
+So the repo tries to keep a few strong teaching rules:
 
-**2. Building the harness.** Writing the code that gives the model an environment to operate in. This is what most of us do, and it is the focus of this repository.
+- explain a concept before using it
+- keep one concept fully explained in one main place
+- start from "what it is", then "why it exists", then "how to implement it"
+- avoid forcing beginners to assemble the system from scattered fragments
 
-A harness is everything the agent needs to function in a specific domain:
+## Recommended Reading Order
 
-```
-Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions
-
-    Tools:          file I/O, shell, network, database, browser
-    Knowledge:      product docs, domain references, API specs, style guides
-    Observation:    git diff, error logs, browser state, sensor data
-    Action:         CLI commands, API calls, UI interactions
-    Permissions:    sandboxing, approval workflows, trust boundaries
-```
-
-The model decides. The harness executes. The model reasons. The harness provides context. The model is the driver. The harness is the vehicle.
-
-**A coding agent's harness is its IDE, terminal, and filesystem access.** A farm agent's harness is its sensor array, irrigation controls, and weather data feeds. A hotel agent's harness is its booking system, guest communication channels, and facility management APIs. The agent -- the intelligence, the decision-maker -- is always the model. The harness changes per domain. The agent generalizes across them.
-
-This repo teaches you to build vehicles. Vehicles for coding. But the design patterns generalize to any domain: farm management, hotel operations, manufacturing, logistics, healthcare, education, scientific research. Anywhere a task needs to be perceived, reasoned about, and acted upon -- an agent needs a harness.
-
-### What Harness Engineers Actually Do
-
-If you are reading this repository, you are likely a harness engineer -- and that is a powerful thing to be. Here is your real job:
-
-- **Implement tools.** Give the agent hands. File read/write, shell execution, API calls, browser control, database queries. Each tool is an action the agent can take in its environment. Design them to be atomic, composable, and well-described.
-
-- **Curate knowledge.** Give the agent domain expertise. Product documentation, architectural decision records, style guides, regulatory requirements. Load them on-demand (s05), not upfront. The agent should know what's available and pull what it needs.
-
-- **Manage context.** Give the agent clean memory. Subagent isolation (s04) prevents noise from leaking. Context compression (s06) prevents history from overwhelming. Task systems (s07) persist goals beyond any single conversation.
-
-- **Control permissions.** Give the agent boundaries. Sandbox file access. Require approval for destructive operations. Enforce trust boundaries between the agent and external systems. This is where safety engineering meets harness engineering.
-
-- **Collect task-process data.** Every action sequence the agent executes in your harness is training signal. The perception-reasoning-action traces from real deployments are the raw material for fine-tuning the next generation of agent models. Your harness doesn't just serve the agent -- it can help improve the agent.
-
-You are not writing the intelligence. You are building the world the intelligence inhabits. The quality of that world -- how clearly the agent can perceive, how precisely it can act, how rich its available knowledge is -- directly determines how effectively the intelligence can express itself.
+The English docs are intended to stand on their own. The chapter order, bridge docs, and mechanism map are aligned across locales, so you can stay inside one language while following the main learning path.
 
-**Build great harnesses. The agent will do the rest.**
+- Overview: [`docs/en/s00-architecture-overview.md`](./docs/en/s00-architecture-overview.md)
+- Code Reading Order: [`docs/en/s00f-code-reading-order.md`](./docs/en/s00f-code-reading-order.md)
+- Glossary: [`docs/en/glossary.md`](./docs/en/glossary.md)
+- Teaching Scope: [`docs/en/teaching-scope.md`](./docs/en/teaching-scope.md)
+- Data Structures: [`docs/en/data-structures.md`](./docs/en/data-structures.md)
 
-### Why Claude Code -- A Masterclass in Harness Engineering
+## If This Is Your First Visit, Start Here
 
-Why does this repository dissect Claude Code specifically?
+Do not open random chapters first.
 
-Because Claude Code is the most elegant and fully-realized agent harness we have seen. Not because of any single clever trick, but because of what it *doesn't* do: it doesn't try to be the agent. It doesn't impose rigid workflows. It doesn't second-guess the model with elaborate decision trees. It provides the model with tools, knowledge, context management, and permission boundaries -- then gets out of the way.
+The safest path is:
 
-Look at what Claude Code actually is, stripped to its essence:
-
-```
-Claude Code = one agent loop
-            + tools (bash, read, write, edit, glob, grep, browser...)
-            + on-demand skill loading
-            + context compression
-            + subagent spawning
-            + task system with dependency graph
-            + team coordination with async mailboxes
-            + worktree isolation for parallel execution
-            + permission governance
-```
-
-That's it. That's the entire architecture. Every component is a harness mechanism -- a piece of the world built for the agent to inhabit. The agent itself? It's Claude. A model. Trained by Anthropic on the full breadth of human reasoning and code. The harness doesn't make Claude smart. Claude is already smart. The harness gives Claude hands, eyes, and a workspace.
-
-This is why Claude Code is the ideal teaching subject: **it demonstrates what happens when you trust the model and focus your engineering on the harness.** Every session in this repository (s01-s12) reverse-engineers one harness mechanism from Claude Code's architecture. By the end, you understand not just how Claude Code works, but the universal principles of harness engineering that apply to any agent in any domain.
-
-The lesson is not "copy Claude Code." The lesson is: **the best agent products are built by engineers who understand that their job is harness, not intelligence.**
-
----
-
-## The Vision: Fill the Universe with Real Agents
-
-This is not just about coding agents.
-
-Every domain where humans perform complex, multi-step, judgment-intensive work is a domain where agents can operate -- given the right harness. The patterns in this repository are universal:
-
-```
-Estate management agent    = model + property sensors + maintenance tools + tenant comms
-Agricultural agent         = model + soil/weather data + irrigation controls + crop knowledge
-Hotel operations agent     = model + booking system + guest channels + facility APIs
-Medical research agent     = model + literature search + lab instruments + protocol docs
-Manufacturing agent        = model + production line sensors + quality controls + logistics
-Education agent            = model + curriculum knowledge + student progress + assessment tools
-```
+1. Read [`docs/en/s00-architecture-overview.md`](./docs/en/s00-architecture-overview.md) for the full system map.
+2. Read [`docs/en/s00d-chapter-order-rationale.md`](./docs/en/s00d-chapter-order-rationale.md) so the chapter order makes sense before you dive into mechanism detail.
+3. Read [`docs/en/s00f-code-reading-order.md`](./docs/en/s00f-code-reading-order.md) so you know which local files to open first.
+4. Follow the four stages in order: `s01-s06 -> s07-s11 -> s12-s14 -> s15-s19`.
+5. After each stage, stop and rebuild the smallest version yourself before continuing.
 
-The loop is always the same. The tools change. The knowledge changes. The permissions change. The agent -- the model -- generalizes.
+## Deep Agents s01-s11 Track
 
-Every harness engineer reading this repository is learning patterns that apply far beyond software engineering. You are learning to build the infrastructure for an intelligent, automated future. Every well-designed harness deployed in a real domain is one more place where an agent can perceive, reason, and act.
+This repo also includes a first-milestone LangChain/Deep Agents track in
+[`agents_deepagents/`](./agents_deepagents/). It preserves the meaningful
+behavior of `agents/s01-s11` without forcing line-by-line tutorial fidelity,
+keeps the original Anthropic SDK scripts intact for side-by-side reading, and
+is intentionally not wired into the web UI yet.
 
-First we fill the workshops. Then the farms, the hospitals, the factories. Then the cities. Then the planet.
+If the middle and late chapters start to blur together, reset in this order:
 
-**Bash is all you need. Real agents are all the universe needs.**
+1. [`docs/en/data-structures.md`](./docs/en/data-structures.md)
+2. [`docs/en/entity-map.md`](./docs/en/entity-map.md)
+3. the bridge docs closest to the chapter you are stuck on
+4. then return to the chapter body
 
----
+## Web Learning Interface
 
-```
-                    THE AGENT PATTERN
-                    =================
-
-    User --> messages[] --> LLM --> response
-                                      |
-                            stop_reason == "tool_use"?
-                           /                          \
-                         yes                           no
-                          |                             |
-                    execute tools                    return text
-                    append results
-                    loop back -----------------> messages[]
-
-
-    That's the minimal loop. Every AI agent needs this loop.
-    The MODEL decides when to call tools and when to stop.
-    The CODE just executes what the model asks for.
-    This repo teaches you to build what surrounds this loop --
-    the harness that makes the agent effective in a specific domain.
-```
+If you want a more visual way to understand the chapter order, stage boundaries, and chapter-to-chapter upgrades, run the built-in teaching site:
 
-**12 progressive sessions, from a simple loop to isolated autonomous execution.**
-**Each session adds one harness mechanism. Each mechanism has one motto.**
-
-> **s01** &nbsp; *"One loop & Bash is all you need"* &mdash; one tool + one loop = an agent
->
-> **s02** &nbsp; *"Adding a tool means adding one handler"* &mdash; the loop stays the same; new tools register into the dispatch map
->
-> **s03** &nbsp; *"An agent without a plan drifts"* &mdash; list the steps first, then execute; completion doubles
->
-> **s04** &nbsp; *"Break big tasks down; each subtask gets a clean context"* &mdash; subagents use independent messages[], keeping the main conversation clean
->
-> **s05** &nbsp; *"Load knowledge when you need it, not upfront"* &mdash; inject via tool_result, not the system prompt
->
-> **s06** &nbsp; *"Context will fill up; you need a way to make room"* &mdash; three-layer compression strategy for infinite sessions
->
-> **s07** &nbsp; *"Break big goals into small tasks, order them, persist to disk"* &mdash; a file-based task graph with dependencies, laying the foundation for multi-agent collaboration
->
-> **s08** &nbsp; *"Run slow operations in the background; the agent keeps thinking"* &mdash; daemon threads run commands, inject notifications on completion
->
-> **s09** &nbsp; *"When the task is too big for one, delegate to teammates"* &mdash; persistent teammates + async mailboxes
->
-> **s10** &nbsp; *"Teammates need shared communication rules"* &mdash; one request-response pattern drives all negotiation
->
-> **s11** &nbsp; *"Teammates scan the board and claim tasks themselves"* &mdash; no need for the lead to assign each one
->
-> **s12** &nbsp; *"Each works in its own directory, no interference"* &mdash; tasks manage goals, worktrees manage directories, bound by ID
-
----
-
-## The Core Pattern
-
-```python
-def agent_loop(messages):
-    while True:
-        response = client.messages.create(
-            model=MODEL, system=SYSTEM,
-            messages=messages, tools=TOOLS,
-        )
-        messages.append({"role": "assistant",
-                         "content": response.content})
-
-        if response.stop_reason != "tool_use":
-            return
-
-        results = []
-        for block in response.content:
-            if block.type == "tool_use":
-                output = TOOL_HANDLERS[block.name](**block.input)
-                results.append({
-                    "type": "tool_result",
-                    "tool_use_id": block.id,
-                    "content": output,
-                })
-        messages.append({"role": "user", "content": results})
+```sh
+cd web
+npm install
+npm run dev
 ```
 
-Every session layers one harness mechanism on top of this loop -- without changing the loop itself. The loop belongs to the agent. The mechanisms belong to the harness.
-
-## Scope (Important)
-
-This repository is a 0->1 learning project for harness engineering -- building the environment that surrounds an agent model.
-It intentionally simplifies or omits several production mechanisms:
-
-- Full event/hook buses (for example PreToolUse, SessionStart/End, ConfigChange).
-  s12 includes only a minimal append-only lifecycle event stream for teaching.
-- Rule-based permission governance and trust workflows
-- Session lifecycle controls (resume/fork) and advanced worktree lifecycle controls
-- Full MCP runtime details (transport/OAuth/resource subscribe/polling)
-
-Treat the team JSONL mailbox protocol in this repo as a teaching implementation, not a claim about any specific production internals.
+Then use these routes:
+
+- `/en`: the English entry page for choosing a reading path
+- `/en/timeline`: the cleanest view of the full mainline
+- `/en/layers`: the four-stage boundary map
+- `/en/compare`: adjacent-step comparison and jump diagnosis
+
+For a first pass, start with `timeline`.  
+If you are already in the middle and chapter boundaries are getting fuzzy, use `layers` and `compare` before you go deeper into source code.
+
+### Bridge Docs
+
+These are not extra main chapters. They are bridge documents that make the middle and late system easier to understand:
+
+- Chapter order rationale: [`docs/en/s00d-chapter-order-rationale.md`](./docs/en/s00d-chapter-order-rationale.md)
+- Code reading order: [`docs/en/s00f-code-reading-order.md`](./docs/en/s00f-code-reading-order.md)
+- Reference module map: [`docs/en/s00e-reference-module-map.md`](./docs/en/s00e-reference-module-map.md)
+- Query control plane: [`docs/en/s00a-query-control-plane.md`](./docs/en/s00a-query-control-plane.md)
+- One request lifecycle: [`docs/en/s00b-one-request-lifecycle.md`](./docs/en/s00b-one-request-lifecycle.md)
+- Query transition model: [`docs/en/s00c-query-transition-model.md`](./docs/en/s00c-query-transition-model.md)
+- Tool control plane: [`docs/en/s02a-tool-control-plane.md`](./docs/en/s02a-tool-control-plane.md)
+- Tool execution runtime: [`docs/en/s02b-tool-execution-runtime.md`](./docs/en/s02b-tool-execution-runtime.md)
+- Message and prompt pipeline: [`docs/en/s10a-message-prompt-pipeline.md`](./docs/en/s10a-message-prompt-pipeline.md)
+- Runtime task model: [`docs/en/s13a-runtime-task-model.md`](./docs/en/s13a-runtime-task-model.md)
+- MCP capability layers: [`docs/en/s19a-mcp-capability-layers.md`](./docs/en/s19a-mcp-capability-layers.md)
+- Team-task-lane model: [`docs/en/team-task-lane-model.md`](./docs/en/team-task-lane-model.md)
+- Entity map: [`docs/en/entity-map.md`](./docs/en/entity-map.md)
+
+### Four Stages
+
+1. `s01-s06`: build a useful single-agent core
+2. `s07-s11`: add safety, extension points, memory, prompt assembly, and recovery
+3. `s12-s14`: turn temporary session planning into durable runtime work
+4. `s15-s19`: move into teams, protocols, autonomy, isolated execution, and external capability routing
+
+### Main Chapters
+
+| Chapter | Topic | What you get |
+|---|---|---|
+| `s00` | Architecture Overview | the global map, key terms, and learning order |
+| `s01` | Agent Loop | the smallest working agent loop |
+| `s02` | Tool Use | a stable tool dispatch layer |
+| `s03` | Todo / Planning | a visible session plan |
+| `s04` | Subagent | fresh context per delegated subtask |
+| `s05` | Skills | load specialized knowledge only when needed |
+| `s06` | Context Compact | keep the active window small |
+| `s07` | Permission System | a safety gate before execution |
+| `s08` | Hook System | extension points around the loop |
+| `s09` | Memory System | durable cross-session knowledge |
+| `s10` | System Prompt | section-based prompt assembly |
+| `s11` | Error Recovery | continuation and retry branches |
+| `s12` | Task System | persistent task graph |
+| `s13` | Background Tasks | non-blocking execution |
+| `s14` | Cron Scheduler | time-based triggers |
+| `s15` | Agent Teams | persistent teammates |
+| `s16` | Team Protocols | shared coordination rules |
+| `s17` | Autonomous Agents | self-claiming and self-resume |
+| `s18` | Worktree Isolation | isolated execution lanes |
+| `s19` | MCP & Plugin | external capability routing |
 
 ## Quick Start
 
@@ -235,143 +192,106 @@ Treat the team JSONL mailbox protocol in this repo as a teaching implementation,
 git clone https://github.com/shareAI-lab/learn-claude-code
 cd learn-claude-code
 pip install -r requirements.txt
-cp .env.example .env   # Edit .env with your ANTHROPIC_API_KEY
-
-python agents/s01_agent_loop.py       # Start here
-python agents/s12_worktree_task_isolation.py  # Full progression endpoint
-python agents/s_full.py               # Capstone: all mechanisms combined
+cp .env.example .env
 ```
 
-### Web Platform
-
-Interactive visualizations, step-through diagrams, source viewer, and documentation.
+Then configure `ANTHROPIC_API_KEY` or a compatible endpoint in `.env`, and run:
 
 ```sh
-cd web && npm install && npm run dev   # http://localhost:3000
+python agents/s01_agent_loop.py
+python agents/s18_worktree_task_isolation.py
+python agents/s19_mcp_plugin.py
+python agents/s_full.py
 ```
 
-## Learning Path
+For the parallel Deep Agents s01-s11 track, configure `OPENAI_API_KEY` (plus optional `OPENAI_MODEL` and `OPENAI_BASE_URL`) and run:
 
+```sh
+python agents_deepagents/s01_agent_loop.py
+python agents_deepagents/s06_context_compact.py
+python agents_deepagents/s11_error_recovery.py
 ```
-Phase 1: THE LOOP                    Phase 2: PLANNING & KNOWLEDGE
-==================                   ==============================
-s01  The Agent Loop          [1]     s03  TodoWrite               [5]
-     while + stop_reason                  TodoManager + nag reminder
-     |                                    |
-     +-> s02  Tool Use            [4]     s04  Subagents            [5]
-              dispatch map: name->handler     fresh messages[] per child
-                                              |
-                                         s05  Skills               [5]
-                                              SKILL.md via tool_result
-                                              |
-                                         s06  Context Compact      [5]
-                                              3-layer compression
-
-Phase 3: PERSISTENCE                 Phase 4: TEAMS
-==================                   =====================
-s07  Tasks                   [8]     s09  Agent Teams             [9]
-     file-based CRUD + deps graph         teammates + JSONL mailboxes
-     |                                    |
-s08  Background Tasks        [6]     s10  Team Protocols          [12]
-     daemon threads + notify queue        shutdown + plan approval FSM
-                                          |
-                                     s11  Autonomous Agents       [14]
-                                          idle cycle + auto-claim
-                                     |
-                                     s12  Worktree Isolation      [16]
-                                          task coordination + optional isolated execution lanes
-
-                                     [N] = number of tools
-```
-
-## Architecture
-
-```
-learn-claude-code/
-|
-|-- agents/                        # Python reference implementations (s01-s12 + s_full capstone)
-|-- docs/{en,zh,ja}/               # Mental-model-first documentation (3 languages)
-|-- web/                           # Interactive learning platform (Next.js)
-|-- skills/                        # Skill files for s05
-+-- .github/workflows/ci.yml      # CI: typecheck + build
-```
-
-## Documentation
-
-Mental-model-first: problem, solution, ASCII diagram, minimal code.
-Available in [English](./docs/en/) | [中文](./docs/zh/) | [日本語](./docs/ja/).
-
-| Session | Topic | Motto |
-|---------|-------|-------|
-| [s01](./docs/en/s01-the-agent-loop.md) | The Agent Loop | *One loop & Bash is all you need* |
-| [s02](./docs/en/s02-tool-use.md) | Tool Use | *Adding a tool means adding one handler* |
-| [s03](./docs/en/s03-todo-write.md) | TodoWrite | *An agent without a plan drifts* |
-| [s04](./docs/en/s04-subagent.md) | Subagents | *Break big tasks down; each subtask gets a clean context* |
-| [s05](./docs/en/s05-skill-loading.md) | Skills | *Load knowledge when you need it, not upfront* |
-| [s06](./docs/en/s06-context-compact.md) | Context Compact | *Context will fill up; you need a way to make room* |
-| [s07](./docs/en/s07-task-system.md) | Tasks | *Break big goals into small tasks, order them, persist to disk* |
-| [s08](./docs/en/s08-background-tasks.md) | Background Tasks | *Run slow operations in the background; the agent keeps thinking* |
-| [s09](./docs/en/s09-agent-teams.md) | Agent Teams | *When the task is too big for one, delegate to teammates* |
-| [s10](./docs/en/s10-team-protocols.md) | Team Protocols | *Teammates need shared communication rules* |
-| [s11](./docs/en/s11-autonomous-agents.md) | Autonomous Agents | *Teammates scan the board and claim tasks themselves* |
-| [s12](./docs/en/s12-worktree-task-isolation.md) | Worktree + Task Isolation | *Each works in its own directory, no interference* |
-
-## What's Next -- from understanding to shipping
-
-After the 12 sessions you understand how harness engineering works inside out. Two ways to put that knowledge to work:
 
-### Kode Agent CLI -- Open-Source Coding Agent CLI
+Suggested order:
 
-> `npm i -g @shareai-lab/kode`
+1. Run `s01` and make sure the minimal loop really works.
+2. Read `s00`, then move through `s01 -> s11` in order.
+3. Only after the single-agent core plus its control plane feel stable, continue into `s12 -> s19`.
+4. Read `s_full.py` last, after the mechanisms already make sense separately.
 
-Skill & LSP support, Windows-ready, pluggable with GLM / MiniMax / DeepSeek and other open models. Install and go.
+### Deep Agents track (s01-s11)
 
-GitHub: **[shareAI-lab/Kode-cli](https://github.com/shareAI-lab/Kode-cli)**
+A first parallel LangChain/Deep Agents track now lives in `agents_deepagents/`.
+It keeps the `s01-s11` chapter shell as a navigation aid while preferring the
+most natural LangChain-native implementation inside each file, uses an
+OpenAI-compatible setup
+(`OPENAI_API_KEY`, optional `OPENAI_BASE_URL`, `OPENAI_MODEL`), and keeps the
+original `agents/*.py` Anthropic SDK baseline intact for side-by-side reading.
 
-### Kode Agent SDK -- Embed Agent Capabilities in Your App
+```sh
+python agents_deepagents/s01_agent_loop.py
+python agents_deepagents/s06_context_compact.py
+python agents_deepagents/s11_error_recovery.py
+```
 
-The official Claude Code Agent SDK communicates with a full CLI process under the hood -- each concurrent user means a separate terminal process. Kode SDK is a standalone library with no per-user process overhead, embeddable in backends, browser extensions, embedded devices, or any runtime.
+See [`agents_deepagents/README.md`](./agents_deepagents/README.md) for the file
+map, migration policy, and no-live-API test contract. The current web learning
+interface intentionally does not surface this track yet.
 
-GitHub: **[shareAI-lab/Kode-agent-sdk](https://github.com/shareAI-lab/Kode-agent-sdk)**
+## How To Read Each Chapter
 
----
+Each chapter is easier to absorb if you keep the same reading rhythm:
 
-## Sister Repo: from *on-demand sessions* to *always-on assistant*
+1. what problem appears without this mechanism
+2. what the new concept means
+3. what the smallest correct implementation looks like
+4. where the state actually lives
+5. how it plugs back into the loop
+6. where to stop first, and what can wait until later
 
-The harness this repo teaches is **use-and-discard** -- open a terminal, give the agent a task, close when done, next session starts blank. That is the Claude Code model.
+If you keep asking:
 
-[OpenClaw](https://github.com/openclaw/openclaw) proved another possibility: on top of the same agent core, two harness mechanisms turn the agent from "poke it to make it move" into "it wakes up every 30 seconds to look for work":
+- "Is this core mainline or just a side detail?"
+- "Where does this state actually live?"
 
-- **Heartbeat** -- every 30s the harness sends the agent a message to check if there is anything to do. Nothing? Go back to sleep. Something? Act immediately.
-- **Cron** -- the agent can schedule its own future tasks, executed automatically when the time comes.
+go back to:
 
-Add multi-channel IM routing (WhatsApp / Telegram / Slack / Discord, 13+ platforms), persistent context memory, and a Soul personality system, and the agent goes from a disposable tool to an always-on personal AI assistant.
+- [`docs/en/teaching-scope.md`](./docs/en/teaching-scope.md)
+- [`docs/en/data-structures.md`](./docs/en/data-structures.md)
+- [`docs/en/entity-map.md`](./docs/en/entity-map.md)
 
-**[claw0](https://github.com/shareAI-lab/claw0)** is our companion teaching repo that deconstructs these harness mechanisms from scratch:
+## Repository Structure
 
-```
-claw agent = agent core + heartbeat + cron + IM chat + memory + soul
+```text
+learn-claude-code/
+├── agents/              # runnable Python reference implementations per chapter
+├── agents_deepagents/    # LangChain-native Deep Agents teaching track for s01-s11
+├── docs/zh/             # Chinese mainline docs
+├── docs/en/             # English docs
+├── docs/ja/             # Japanese docs
+├── skills/              # skill files used in s05
+├── web/                 # web teaching platform
+└── requirements.txt
 ```
 
-```
-learn-claude-code                   claw0
-(agent harness core:                (proactive always-on harness:
- loop, tools, planning,              heartbeat, cron, IM channels,
- teams, worktree isolation)          memory, soul personality)
-```
+## Language Status
 
-## About
-<img width="260" src="https://github.com/user-attachments/assets/fe8b852b-97da-4061-a467-9694906b5edf" /><br>
+Chinese is still the canonical teaching line and the fastest-moving version.
 
-Scan with WeChat to follow us,
-or follow on X: [shareAI-Lab](https://x.com/baicai003)
+- `zh`: most reviewed and most complete
+- `en`: main chapters plus the major bridge docs are available
+- `ja`: main chapters plus the major bridge docs are available
 
-## License
+If you want the fullest and most frequently refined explanation path, use the Chinese docs first.
 
-MIT
+## End Goal
 
----
+By the end of the repo, you should be able to answer these questions clearly:
 
-**The model is the agent. The code is the harness. Build great harnesses. The agent will do the rest.**
+- what is the minimum state a coding agent needs?
+- why is `tool_result` the center of the loop?
+- when should you use a subagent instead of stuffing more into one context?
+- what problem do permissions, hooks, memory, prompt assembly, and tasks each solve?
+- when should a single-agent system grow into tasks, teams, worktrees, and MCP?
 
-**Bash is all you need. Real agents are all the universe needs.**
+If you can answer those questions clearly and build a similar system yourself, this repo has done its job.
diff --git a/agents/__init__.py b/agents/__init__.py
index fc7a46075..3efd78a10 100644
--- a/agents/__init__.py
+++ b/agents/__init__.py
@@ -1,3 +1,3 @@
-# agents/ - Harness implementations (s01-s12) + full reference (s_full)
+# agents/ - Harness implementations (s01-s19) + capstone reference (s_full)
 # Each file is self-contained and runnable: python agents/s01_agent_loop.py
 # The model is the agent. These files are the harness.
diff --git a/agents/s01_agent_loop.py b/agents/s01_agent_loop.py
index 8455ebff4..81db3aa3c 100644
--- a/agents/s01_agent_loop.py
+++ b/agents/s01_agent_loop.py
@@ -1,31 +1,23 @@
 #!/usr/bin/env python3
-# Harness: the loop -- the model's first connection to the real world.
+# Harness: the loop -- keep feeding real tool results back into the model.
 """
 s01_agent_loop.py - The Agent Loop
 
-The entire secret of an AI coding agent in one pattern:
-
-    while stop_reason == "tool_use":
-        response = LLM(messages, tools)
-        execute tools
-        append results
-
-    +----------+      +-------+      +---------+
-    |   User   | ---> |  LLM  | ---> |  Tool   |
-    |  prompt  |      |       |      | execute |
-    +----------+      +---+---+      +----+----+
-                          ^               |
-                          |   tool_result |
-                          +---------------+
-                          (loop continues)
-
-This is the core loop: feed tool results back to the model
-until the model decides to stop. Production agents layer
-policy, hooks, and lifecycle controls on top.
+This file teaches the smallest useful coding-agent pattern:
+
+    user message
+      -> model reply
+      -> if tool_use: execute tools
+      -> write tool_result back to messages
+      -> continue
+
+It intentionally keeps the loop small, but still makes the loop state explicit
+so later chapters can grow from the same structure.
 """
 
 import os
 import subprocess
+from dataclasses import dataclass
 
 try:
     import readline
@@ -49,11 +41,14 @@
 client = Anthropic(base_url=os.getenv("ANTHROPIC_BASE_URL"))
 MODEL = os.environ["MODEL_ID"]
 
-SYSTEM = f"You are a coding agent at {os.getcwd()}. Use bash to solve tasks. Act, don't explain."
+SYSTEM = (
+    f"You are a coding agent at {os.getcwd()}. "
+    "Use bash to inspect and change the workspace. Act first, then report clearly."
+)
 
 TOOLS = [{
     "name": "bash",
-    "description": "Run a shell command.",
+    "description": "Run a shell command in the current workspace.",
     "input_schema": {
         "type": "object",
         "properties": {"command": {"type": "string"}},
@@ -62,43 +57,92 @@
 }]
 
 
+@dataclass
+class LoopState:
+    # The minimal loop state: history, loop count, and why we continue.
+    messages: list
+    turn_count: int = 1
+    transition_reason: str | None = None
+
+
 def run_bash(command: str) -> str:
     dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
-    if any(d in command for d in dangerous):
+    if any(item in command for item in dangerous):
         return "Error: Dangerous command blocked"
     try:
-        r = subprocess.run(command, shell=True, cwd=os.getcwd(),
-                           capture_output=True, text=True, timeout=120)
-        out = (r.stdout + r.stderr).strip()
-        return out[:50000] if out else "(no output)"
+        result = subprocess.run(
+            command,
+            shell=True,
+            cwd=os.getcwd(),
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
     except subprocess.TimeoutExpired:
         return "Error: Timeout (120s)"
     except (FileNotFoundError, OSError) as e:
         return f"Error: {e}"
 
-
-# -- The core pattern: a while loop that calls tools until the model stops --
-def agent_loop(messages: list):
-    while True:
-        response = client.messages.create(
-            model=MODEL, system=SYSTEM, messages=messages,
-            tools=TOOLS, max_tokens=8000,
-        )
-        # Append assistant turn
-        messages.append({"role": "assistant", "content": response.content})
-        # If the model didn't call a tool, we're done
-        if response.stop_reason != "tool_use":
-            return
-        # Execute each tool call, collect results
-        results = []
-        for block in response.content:
-            if block.type == "tool_use":
-                print(f"\033[33m$ {block.input['command']}\033[0m")
-                output = run_bash(block.input["command"])
-                print(output[:200])
-                results.append({"type": "tool_result", "tool_use_id": block.id,
-                                "content": output})
-        messages.append({"role": "user", "content": results})
+    output = (result.stdout + result.stderr).strip()
+    return output[:50000] if output else "(no output)"
+
+
+def extract_text(content) -> str:
+    if not isinstance(content, list):
+        return ""
+    texts = []
+    for block in content:
+        text = getattr(block, "text", None)
+        if text:
+            texts.append(text)
+    return "\n".join(texts).strip()
+
+
+def execute_tool_calls(response_content) -> list[dict]:
+    results = []
+    for block in response_content:
+        if block.type != "tool_use":
+            continue
+        command = block.input["command"]
+        print(f"\033[33m$ {command}\033[0m")
+        output = run_bash(command)
+        print(output[:200])
+        results.append({
+            "type": "tool_result",
+            "tool_use_id": block.id,
+            "content": output,
+        })
+    return results
+
+
+def run_one_turn(state: LoopState) -> bool:
+    response = client.messages.create(
+        model=MODEL,
+        system=SYSTEM,
+        messages=state.messages,
+        tools=TOOLS,
+        max_tokens=8000,
+    )
+    state.messages.append({"role": "assistant", "content": response.content})
+
+    if response.stop_reason != "tool_use":
+        state.transition_reason = None
+        return False
+
+    results = execute_tool_calls(response.content)
+    if not results:
+        state.transition_reason = None
+        return False
+
+    state.messages.append({"role": "user", "content": results})
+    state.turn_count += 1
+    state.transition_reason = "tool_result"
+    return True
+
+
+def agent_loop(state: LoopState) -> None:
+    while run_one_turn(state):
+        pass
 
 
 if __name__ == "__main__":
@@ -110,11 +154,12 @@ def agent_loop(messages: list):
             break
         if query.strip().lower() in ("q", "exit", ""):
             break
+
         history.append({"role": "user", "content": query})
-        agent_loop(history)
-        response_content = history[-1]["content"]
-        if isinstance(response_content, list):
-            for block in response_content:
-                if hasattr(block, "text"):
-                    print(block.text)
+        state = LoopState(messages=history)
+        agent_loop(state)
+
+        final_text = extract_text(history[-1]["content"])
+        if final_text:
+            print(final_text)
         print()
diff --git a/agents/s02_tool_use.py b/agents/s02_tool_use.py
index 8e434c04a..793ef3a07 100644
--- a/agents/s02_tool_use.py
+++ b/agents/s02_tool_use.py
@@ -1,20 +1,11 @@
 #!/usr/bin/env python3
 # Harness: tool dispatch -- expanding what the model can reach.
 """
-s02_tool_use.py - Tools
+s02_tool_use.py - Tool dispatch + message normalization
 
-The agent loop from s01 didn't change. We just added tools to the array
-and a dispatch map to route calls.
-
-    +----------+      +-------+      +------------------+
-    |   User   | ---> |  LLM  | ---> | Tool Dispatch    |
-    |  prompt  |      |       |      | {                |
-    +----------+      +---+---+      |   bash: run_bash |
-                          ^          |   read: run_read |
-                          |          |   write: run_wr  |
-                          +----------+   edit: run_edit |
-                          tool_result| }                |
-                                     +------------------+
+The agent loop from s01 didn't change. We added tools to the dispatch map,
+and a normalize_messages() function that cleans up the message list before
+each API call.
 
 Key insight: "The loop didn't change at all. I just added tools."
 """
@@ -91,6 +82,11 @@ def run_edit(path: str, old_text: str, new_text: str) -> str:
         return f"Error: {e}"
 
 
+# -- Concurrency safety classification --
+# Read-only tools can safely run in parallel; mutating tools must be serialized.
+CONCURRENCY_SAFE = {"read_file"}
+CONCURRENCY_UNSAFE = {"write_file", "edit_file"}
+
 # -- The dispatch map: {tool_name: handler} --
 TOOL_HANDLERS = {
     "bash":       lambda **kw: run_bash(kw["command"]),
@@ -111,10 +107,73 @@ def run_edit(path: str, old_text: str, new_text: str) -> str:
 ]
 
 
+def normalize_messages(messages: list) -> list:
+    """Clean up messages before sending to the API.
+
+    Three jobs:
+    1. Strip internal metadata fields the API doesn't understand
+    2. Ensure every tool_use has a matching tool_result (insert placeholder if missing)
+    3. Merge consecutive same-role messages (API requires strict alternation)
+    """
+    cleaned = []
+    for msg in messages:
+        clean = {"role": msg["role"]}
+        if isinstance(msg.get("content"), str):
+            clean["content"] = msg["content"]
+        elif isinstance(msg.get("content"), list):
+            clean["content"] = [
+                {k: v for k, v in block.items()
+                 if not k.startswith("_")}
+                for block in msg["content"]
+                if isinstance(block, dict)
+            ]
+        else:
+            clean["content"] = msg.get("content", "")
+        cleaned.append(clean)
+
+    # Collect existing tool_result IDs
+    existing_results = set()
+    for msg in cleaned:
+        if isinstance(msg.get("content"), list):
+            for block in msg["content"]:
+                if isinstance(block, dict) and block.get("type") == "tool_result":
+                    existing_results.add(block.get("tool_use_id"))
+
+    # Find orphaned tool_use blocks and insert placeholder results
+    for msg in cleaned:
+        if msg["role"] != "assistant" or not isinstance(msg.get("content"), list):
+            continue
+        for block in msg["content"]:
+            if not isinstance(block, dict):
+                continue
+            if block.get("type") == "tool_use" and block.get("id") not in existing_results:
+                cleaned.append({"role": "user", "content": [
+                    {"type": "tool_result", "tool_use_id": block["id"],
+                     "content": "(cancelled)"}
+                ]})
+
+    # Merge consecutive same-role messages
+    if not cleaned:
+        return cleaned
+    merged = [cleaned[0]]
+    for msg in cleaned[1:]:
+        if msg["role"] == merged[-1]["role"]:
+            prev = merged[-1]
+            prev_c = prev["content"] if isinstance(prev["content"], list) \
+                else [{"type": "text", "text": str(prev["content"])}]
+            curr_c = msg["content"] if isinstance(msg["content"], list) \
+                else [{"type": "text", "text": str(msg["content"])}]
+            prev["content"] = prev_c + curr_c
+        else:
+            merged.append(msg)
+    return merged
+
+
 def agent_loop(messages: list):
     while True:
         response = client.messages.create(
-            model=MODEL, system=SYSTEM, messages=messages,
+            model=MODEL, system=SYSTEM,
+            messages=normalize_messages(messages),
             tools=TOOLS, max_tokens=8000,
         )
         messages.append({"role": "assistant", "content": response.content})
diff --git a/agents/s03_todo_write.py b/agents/s03_todo_write.py
index 4c7076c55..e2c95f77b 100644
--- a/agents/s03_todo_write.py
+++ b/agents/s03_todo_write.py
@@ -1,34 +1,16 @@
 #!/usr/bin/env python3
-# Harness: planning -- keeping the model on course without scripting the route.
+# Harness: planning -- keep the current session plan outside the model's head.
 """
-s03_todo_write.py - TodoWrite
-
-The model tracks its own progress via a TodoManager. A nag reminder
-forces it to keep updating when it forgets.
-
-    +----------+      +-------+      +---------+
-    |   User   | ---> |  LLM  | ---> | Tools   |
-    |  prompt  |      |       |      | + todo  |
-    +----------+      +---+---+      +----+----+
-                          ^               |
-                          |   tool_result |
-                          +---------------+
-                                |
-                    +-----------+-----------+
-                    | TodoManager state     |
-                    | [ ] task A            |
-                    | [>] task B <- doing   |
-                    | [x] task C            |
-                    +-----------------------+
-                                |
-                    if rounds_since_todo >= 3:
-                      inject <reminder>
-
-Key insight: "The agent can track its own progress -- and I can see it."
+s03_todo_write.py - Session Planning with TodoWrite
+
+This chapter is about a lightweight session plan, not a durable task graph.
+The model can rewrite its current plan, keep one active step in focus, and get
+nudged if it stops refreshing the plan for too many rounds.
 """
 
 import os
 import subprocess
+from dataclasses import dataclass, field
 from pathlib import Path
 
 from anthropic import Anthropic
@@ -42,153 +24,295 @@
 WORKDIR = Path.cwd()
 client = Anthropic(base_url=os.getenv("ANTHROPIC_BASE_URL"))
 MODEL = os.environ["MODEL_ID"]
+PLAN_REMINDER_INTERVAL = 3
 
 SYSTEM = f"""You are a coding agent at {WORKDIR}.
-Use the todo tool to plan multi-step tasks. Mark in_progress before starting, completed when done.
-Prefer tools over prose."""
+Use the todo tool for multi-step work.
+Keep exactly one step in_progress when a task has multiple steps.
+Refresh the plan as work advances. Prefer tools over prose."""
+
+
+@dataclass
+class PlanItem:
+    content: str
+    status: str = "pending"
+    active_form: str = ""
+
+
+@dataclass
+class PlanningState:
+    items: list[PlanItem] = field(default_factory=list)
+    rounds_since_update: int = 0
 
 
-# -- TodoManager: structured state the LLM writes to --
 class TodoManager:
     def __init__(self):
-        self.items = []
+        self.state = PlanningState()
 
     def update(self, items: list) -> str:
-        if len(items) > 20:
-            raise ValueError("Max 20 todos allowed")
-        validated = []
+        if len(items) > 12:
+            raise ValueError("Keep the session plan short (max 12 items)")
+
+        normalized = []
         in_progress_count = 0
-        for i, item in enumerate(items):
-            text = str(item.get("text", "")).strip()
-            status = str(item.get("status", "pending")).lower()
-            item_id = str(item.get("id", str(i + 1)))
-            if not text:
-                raise ValueError(f"Item {item_id}: text required")
-            if status not in ("pending", "in_progress", "completed"):
-                raise ValueError(f"Item {item_id}: invalid status '{status}'")
+        for index, raw_item in enumerate(items):
+            content = str(raw_item.get("content", "")).strip()
+            status = str(raw_item.get("status", "pending")).lower()
+            active_form = str(raw_item.get("activeForm", "")).strip()
+
+            if not content:
+                raise ValueError(f"Item {index}: content required")
+            if status not in {"pending", "in_progress", "completed"}:
+                raise ValueError(f"Item {index}: invalid status '{status}'")
             if status == "in_progress":
                 in_progress_count += 1
-            validated.append({"id": item_id, "text": text, "status": status})
+
+            normalized.append(PlanItem(
+                content=content,
+                status=status,
+                active_form=active_form,
+            ))
+
         if in_progress_count > 1:
-            raise ValueError("Only one task can be in_progress at a time")
-        self.items = validated
+            raise ValueError("Only one plan item can be in_progress")
+
+        self.state.items = normalized
+        self.state.rounds_since_update = 0
         return self.render()
 
+    def note_round_without_update(self) -> None:
+        self.state.rounds_since_update += 1
+
+    def reminder(self) -> str | None:
+        if not self.state.items:
+            return None
+        if self.state.rounds_since_update < PLAN_REMINDER_INTERVAL:
+            return None
+        return "<reminder>Refresh your current plan before continuing.</reminder>"
+
     def render(self) -> str:
-        if not self.items:
-            return "No todos."
+        if not self.state.items:
+            return "No session plan yet."
+
         lines = []
-        for item in self.items:
-            marker = {"pending": "[ ]", "in_progress": "[>]", "completed": "[x]"}[item["status"]]
-            lines.append(f"{marker} #{item['id']}: {item['text']}")
-        done = sum(1 for t in self.items if t["status"] == "completed")
-        lines.append(f"\n({done}/{len(self.items)} completed)")
+        for item in self.state.items:
+            marker = {
+                "pending": "[ ]",
+                "in_progress": "[>]",
+                "completed": "[x]",
+            }[item.status]
+            line = f"{marker} {item.content}"
+            if item.status == "in_progress" and item.active_form:
+                line += f" ({item.active_form})"
+            lines.append(line)
+
+        completed = sum(1 for item in self.state.items if item.status == "completed")
+        lines.append(f"\n({completed}/{len(self.state.items)} completed)")
         return "\n".join(lines)
 
 
 TODO = TodoManager()
 
 
-# -- Tool implementations --
-def safe_path(p: str) -> Path:
-    path = (WORKDIR / p).resolve()
+def safe_path(path_str: str) -> Path:
+    path = (WORKDIR / path_str).resolve()
     if not path.is_relative_to(WORKDIR):
-        raise ValueError(f"Path escapes workspace: {p}")
+        raise ValueError(f"Path escapes workspace: {path_str}")
     return path
 
+
 def run_bash(command: str) -> str:
     dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
-    if any(d in command for d in dangerous):
+    if any(item in command for item in dangerous):
         return "Error: Dangerous command blocked"
     try:
-        r = subprocess.run(command, shell=True, cwd=WORKDIR,
-                           capture_output=True, text=True, timeout=120)
-        out = (r.stdout + r.stderr).strip()
-        return out[:50000] if out else "(no output)"
+        result = subprocess.run(
+            command,
+            shell=True,
+            cwd=WORKDIR,
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
     except subprocess.TimeoutExpired:
         return "Error: Timeout (120s)"
 
-def run_read(path: str, limit: int = None) -> str:
+    output = (result.stdout + result.stderr).strip()
+    return output[:50000] if output else "(no output)"
+
+
+def run_read(path: str, limit: int | None = None) -> str:
     try:
         lines = safe_path(path).read_text().splitlines()
         if limit and limit < len(lines):
-            lines = lines[:limit] + [f"... ({len(lines) - limit} more)"]
+            lines = lines[:limit] + [f"... ({len(lines) - limit} more lines)"]
         return "\n".join(lines)[:50000]
-    except Exception as e:
-        return f"Error: {e}"
+    except Exception as exc:
+        return f"Error: {exc}"
+
 
 def run_write(path: str, content: str) -> str:
     try:
-        fp = safe_path(path)
-        fp.parent.mkdir(parents=True, exist_ok=True)
-        fp.write_text(content)
-        return f"Wrote {len(content)} bytes"
-    except Exception as e:
-        return f"Error: {e}"
+        file_path = safe_path(path)
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_path.write_text(content)
+        return f"Wrote {len(content)} bytes to {path}"
+    except Exception as exc:
+        return f"Error: {exc}"
+
 
 def run_edit(path: str, old_text: str, new_text: str) -> str:
     try:
-        fp = safe_path(path)
-        content = fp.read_text()
+        file_path = safe_path(path)
+        content = file_path.read_text()
         if old_text not in content:
             return f"Error: Text not found in {path}"
-        fp.write_text(content.replace(old_text, new_text, 1))
+        file_path.write_text(content.replace(old_text, new_text, 1))
         return f"Edited {path}"
-    except Exception as e:
-        return f"Error: {e}"
+    except Exception as exc:
+        return f"Error: {exc}"
 
 
 TOOL_HANDLERS = {
-    "bash":       lambda **kw: run_bash(kw["command"]),
-    "read_file":  lambda **kw: run_read(kw["path"], kw.get("limit")),
+    "bash": lambda **kw: run_bash(kw["command"]),
+    "read_file": lambda **kw: run_read(kw["path"], kw.get("limit")),
     "write_file": lambda **kw: run_write(kw["path"], kw["content"]),
-    "edit_file":  lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
-    "todo":       lambda **kw: TODO.update(kw["items"]),
+    "edit_file": lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
+    "todo": lambda **kw: TODO.update(kw["items"]),
 }
 
 TOOLS = [
-    {"name": "bash", "description": "Run a shell command.",
-     "input_schema": {"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]}},
-    {"name": "read_file", "description": "Read file contents.",
-     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "limit": {"type": "integer"}}, "required": ["path"]}},
-    {"name": "write_file", "description": "Write content to file.",
-     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "content": {"type": "string"}}, "required": ["path", "content"]}},
-    {"name": "edit_file", "description": "Replace exact text in file.",
-     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "old_text": {"type": "string"}, "new_text": {"type": "string"}}, "required": ["path", "old_text", "new_text"]}},
-    {"name": "todo", "description": "Update task list. Track progress on multi-step tasks.",
-     "input_schema": {"type": "object", "properties": {"items": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "string"}, "text": {"type": "string"}, "status": {"type": "string", "enum": ["pending", "in_progress", "completed"]}}, "required": ["id", "text", "status"]}}}, "required": ["items"]}},
+    {
+        "name": "bash",
+        "description": "Run a shell command.",
+        "input_schema": {
+            "type": "object",
+            "properties": {"command": {"type": "string"}},
+            "required": ["command"],
+        },
+    },
+    {
+        "name": "read_file",
+        "description": "Read file contents.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string"},
+                "limit": {"type": "integer"},
+            },
+            "required": ["path"],
+        },
+    },
+    {
+        "name": "write_file",
+        "description": "Write content to a file.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string"},
+                "content": {"type": "string"},
+            },
+            "required": ["path", "content"],
+        },
+    },
+    {
+        "name": "edit_file",
+        "description": "Replace exact text in a file once.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string"},
+                "old_text": {"type": "string"},
+                "new_text": {"type": "string"},
+            },
+            "required": ["path", "old_text", "new_text"],
+        },
+    },
+    {
+        "name": "todo",
+        "description": "Rewrite the current session plan for multi-step work.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "items": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "content": {"type": "string"},
+                            "status": {
+                                "type": "string",
+                                "enum": ["pending", "in_progress", "completed"],
+                            },
+                            "activeForm": {
+                                "type": "string",
+                                "description": "Optional present-continuous label.",
+                            },
+                        },
+                        "required": ["content", "status"],
+                    },
+                },
+            },
+            "required": ["items"],
+        },
+    },
 ]
 
 
-# -- Agent loop with nag reminder injection --
-def agent_loop(messages: list):
-    rounds_since_todo = 0
+def extract_text(content) -> str:
+    if not isinstance(content, list):
+        return ""
+    texts = []
+    for block in content:
+        text = getattr(block, "text", None)
+        if text:
+            texts.append(text)
+    return "\n".join(texts).strip()
+
+
+def agent_loop(messages: list) -> None:
     while True:
-        # Nag reminder is injected below, alongside tool results
         response = client.messages.create(
-            model=MODEL, system=SYSTEM, messages=messages,
-            tools=TOOLS, max_tokens=8000,
+            model=MODEL,
+            system=SYSTEM,
+            messages=messages,
+            tools=TOOLS,
+            max_tokens=8000,
         )
         messages.append({"role": "assistant", "content": response.content})
+
         if response.stop_reason != "tool_use":
             return
+
         results = []
         used_todo = False
         for block in response.content:
-            if block.type == "tool_use":
-                handler = TOOL_HANDLERS.get(block.name)
-                try:
-                    output = handler(**block.input) if handler else f"Unknown tool: {block.name}"
-                except Exception as e:
-                    output = f"Error: {e}"
-                print(f"> {block.name}:")
-                print(str(output)[:200])
-                results.append({"type": "tool_result", "tool_use_id": block.id, "content": str(output)})
-                if block.name == "todo":
-                    used_todo = True
-        rounds_since_todo = 0 if used_todo else rounds_since_todo + 1
-        if rounds_since_todo >= 3:
-            results.append({"type": "text", "text": "<reminder>Update your todos.</reminder>"})
+            if block.type != "tool_use":
+                continue
+
+            handler = TOOL_HANDLERS.get(block.name)
+            try:
+                output = handler(**block.input) if handler else f"Unknown tool: {block.name}"
+            except Exception as exc:
+                output = f"Error: {exc}"
+
+            print(f"> {block.name}: {str(output)[:200]}")
+            results.append({
+                "type": "tool_result",
+                "tool_use_id": block.id,
+                "content": str(output),
+            })
+            if block.name == "todo":
+                used_todo = True
+
+        if used_todo:
+            TODO.state.rounds_since_update = 0
+        else:
+            TODO.note_round_without_update()
+            reminder = TODO.reminder()
+            if reminder:
+                results.insert(0, {"type": "text", "text": reminder})
+
         messages.append({"role": "user", "content": results})
 
 
@@ -201,11 +325,11 @@ def agent_loop(messages: list):
             break
         if query.strip().lower() in ("q", "exit", ""):
             break
+
         history.append({"role": "user", "content": query})
         agent_loop(history)
-        response_content = history[-1]["content"]
-        if isinstance(response_content, list):
-            for block in response_content:
-                if hasattr(block, "text"):
-                    print(block.text)
+
+        final_text = extract_text(history[-1]["content"])
+        if final_text:
+            print(final_text)
         print()
diff --git a/agents/s04_subagent.py b/agents/s04_subagent.py
index dda2737f6..965a36a32 100644
--- a/agents/s04_subagent.py
+++ b/agents/s04_subagent.py
@@ -20,10 +20,31 @@
     Parent context stays clean.
     Subagent context is discarded.
 
-Key insight: "Process isolation gives context isolation for free."
+Key insight: "Fresh messages=[] gives context isolation. The parent stays clean."
+
+Note: Real Claude Code also uses in-process isolation (not OS-level process
+forking). The child runs in the same process with a fresh message array and
+isolated tool context -- same pattern as this teaching implementation.
+
+    Comparison with real Claude Code:
+    +-------------------+------------------+----------------------------------+
+    | Aspect            | This demo        | Real Claude Code                 |
+    +-------------------+------------------+----------------------------------+
+    | Backend           | in-process only  | 5 backends: in-process, tmux,    |
+    |                   |                  | iTerm2, fork, remote             |
+    | Context isolation | fresh messages=[]| createSubagentContext() isolates  |
+    |                   |                  | ~20 fields (tools, permissions,  |
+    |                   |                  | cwd, env, hooks, etc.)           |
+    | Tool filtering    | manually curated | resolveAgentTools() filters from |
+    |                   |                  | parent pool; allowedTools         |
+    |                   |                  | replaces all allow rules         |
+    | Agent definition  | hardcoded system | .claude/agents/*.md with YAML    |
+    |                   | prompt           | frontmatter (AgentTemplate)      |
+    +-------------------+------------------+----------------------------------+
 """
 
 import os
+import re
 import subprocess
 from pathlib import Path
 
@@ -43,6 +64,37 @@
 SUBAGENT_SYSTEM = f"You are a coding subagent at {WORKDIR}. Complete the given task, then summarize your findings."
 
 
+class AgentTemplate:
+    """
+    Parse agent definition from markdown frontmatter.
+
+    Real Claude Code loads agent definitions from .claude/agents/*.md.
+    Frontmatter fields: name, tools, disallowedTools, skills, hooks,
+    model, effort, permissionMode, maxTurns, memory, isolation, color,
+    background, initialPrompt, mcpServers.
+    3 sources: built-in, custom (.claude/agents/), plugin-provided.
+    """
+    def __init__(self, path):
+        self.path = Path(path)
+        self.name = self.path.stem
+        self.config = {}
+        self.system_prompt = ""
+        self._parse()
+
+    def _parse(self):
+        text = self.path.read_text()
+        match = re.match(r"^---\s*\n(.*?)\n---\s*\n(.*)", text, re.DOTALL)
+        if not match:
+            self.system_prompt = text
+            return
+        for line in match.group(1).splitlines():
+            if ":" in line:
+                k, _, v = line.partition(":")
+                self.config[k.strip()] = v.strip()
+        self.system_prompt = match.group(2).strip()
+        self.name = self.config.get("name", self.name)
+
+
 # -- Tool implementations shared by parent and child --
 def safe_path(p: str) -> Path:
     path = (WORKDIR / p).resolve()
diff --git a/agents/s05_skill_loading.py b/agents/s05_skill_loading.py
index e14167a6c..6f9696f10 100644
--- a/agents/s05_skill_loading.py
+++ b/agents/s05_skill_loading.py
@@ -1,44 +1,21 @@
 #!/usr/bin/env python3
-# Harness: on-demand knowledge -- domain expertise, loaded when the model asks.
+# Harness: on-demand knowledge -- discover skills cheaply, load them only when needed.
 """
 s05_skill_loading.py - Skills
 
-Two-layer skill injection that avoids bloating the system prompt:
-
-    Layer 1 (cheap): skill names in system prompt (~100 tokens/skill)
-    Layer 2 (on demand): full skill body in tool_result
-
-    skills/
-      pdf/
-        SKILL.md          <-- frontmatter (name, description) + body
-      code-review/
-        SKILL.md
-
-    System prompt:
-    +--------------------------------------+
-    | You are a coding agent.              |
-    | Skills available:                    |
-    |   - pdf: Process PDF files...        |  <-- Layer 1: metadata only
-    |   - code-review: Review code...      |
-    +--------------------------------------+
-
-    When model calls load_skill("pdf"):
-    +--------------------------------------+
-    | tool_result:                         |
-    | <skill>                              |
-    |   Full PDF processing instructions   |  <-- Layer 2: full body
-    |   Step 1: ...                        |
-    |   Step 2: ...                        |
-    | </skill>                             |
-    +--------------------------------------+
-
-Key insight: "Don't put everything in the system prompt. Load on demand."
+This chapter teaches a two-layer skill model:
+
+1. Put a cheap skill catalog in the system prompt.
+2. Load the full skill body only when the model asks for it.
+
+That keeps the prompt small while still giving the model access to reusable,
+task-specific guidance.
 """
 
 import os
 import re
 import subprocess
-import yaml
+from dataclasses import dataclass
 from pathlib import Path
 
 from anthropic import Anthropic
@@ -55,156 +32,250 @@
 SKILLS_DIR = WORKDIR / "skills"
 
 
-# -- SkillLoader: scan skills/<name>/SKILL.md with YAML frontmatter --
-class SkillLoader:
+@dataclass
+class SkillManifest:
+    name: str
+    description: str
+    path: Path
+
+
+@dataclass
+class SkillDocument:
+    manifest: SkillManifest
+    body: str
+
+
+class SkillRegistry:
     def __init__(self, skills_dir: Path):
         self.skills_dir = skills_dir
-        self.skills = {}
+        self.documents: dict[str, SkillDocument] = {}
         self._load_all()
 
-    def _load_all(self):
+    def _load_all(self) -> None:
         if not self.skills_dir.exists():
             return
-        for f in sorted(self.skills_dir.rglob("SKILL.md")):
-            text = f.read_text()
-            meta, body = self._parse_frontmatter(text)
-            name = meta.get("name", f.parent.name)
-            self.skills[name] = {"meta": meta, "body": body, "path": str(f)}
-
-    def _parse_frontmatter(self, text: str) -> tuple:
-        """Parse YAML frontmatter between --- delimiters."""
+
+        for path in sorted(self.skills_dir.rglob("SKILL.md")):
+            meta, body = self._parse_frontmatter(path.read_text())
+            name = meta.get("name", path.parent.name)
+            description = meta.get("description", "No description")
+            manifest = SkillManifest(name=name, description=description, path=path)
+            self.documents[name] = SkillDocument(manifest=manifest, body=body.strip())
+
+    def _parse_frontmatter(self, text: str) -> tuple[dict, str]:
         match = re.match(r"^---\n(.*?)\n---\n(.*)", text, re.DOTALL)
         if not match:
             return {}, text
-        try:
-            meta = yaml.safe_load(match.group(1)) or {}
-        except yaml.YAMLError:
-            meta = {}
-        return meta, match.group(2).strip()
-
-    def get_descriptions(self) -> str:
-        """Layer 1: short descriptions for the system prompt."""
-        if not self.skills:
+
+        meta = {}
+        for line in match.group(1).strip().splitlines():
+            if ":" not in line:
+                continue
+            key, value = line.split(":", 1)
+            meta[key.strip()] = value.strip()
+        return meta, match.group(2)
+
+    def describe_available(self) -> str:
+        if not self.documents:
             return "(no skills available)"
         lines = []
-        for name, skill in self.skills.items():
-            desc = skill["meta"].get("description", "No description")
-            tags = skill["meta"].get("tags", "")
-            line = f"  - {name}: {desc}"
-            if tags:
-                line += f" [{tags}]"
-            lines.append(line)
+        for name in sorted(self.documents):
+            manifest = self.documents[name].manifest
+            lines.append(f"- {manifest.name}: {manifest.description}")
         return "\n".join(lines)
 
-    def get_content(self, name: str) -> str:
-        """Layer 2: full skill body returned in tool_result."""
-        skill = self.skills.get(name)
-        if not skill:
-            return f"Error: Unknown skill '{name}'. Available: {', '.join(self.skills.keys())}"
-        return f"<skill name=\"{name}\">\n{skill['body']}\n</skill>"
+    def load_full_text(self, name: str) -> str:
+        document = self.documents.get(name)
+        if not document:
+            known = ", ".join(sorted(self.documents)) or "(none)"
+            return f"Error: Unknown skill '{name}'. Available skills: {known}"
+
+        return (
+            f"<skill name=\"{document.manifest.name}\">\n"
+            f"{document.body}\n"
+            "</skill>"
+        )
 
 
-SKILL_LOADER = SkillLoader(SKILLS_DIR)
+SKILL_REGISTRY = SkillRegistry(SKILLS_DIR)
 
-# Layer 1: skill metadata injected into system prompt
 SYSTEM = f"""You are a coding agent at {WORKDIR}.
-Use load_skill to access specialized knowledge before tackling unfamiliar topics.
+Use load_skill when a task needs specialized instructions before you act.
 
 Skills available:
-{SKILL_LOADER.get_descriptions()}"""
+{SKILL_REGISTRY.describe_available()}
+"""
 
 
-# -- Tool implementations --
-def safe_path(p: str) -> Path:
-    path = (WORKDIR / p).resolve()
+def safe_path(path_str: str) -> Path:
+    path = (WORKDIR / path_str).resolve()
     if not path.is_relative_to(WORKDIR):
-        raise ValueError(f"Path escapes workspace: {p}")
+        raise ValueError(f"Path escapes workspace: {path_str}")
     return path
 
+
 def run_bash(command: str) -> str:
     dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
-    if any(d in command for d in dangerous):
+    if any(item in command for item in dangerous):
         return "Error: Dangerous command blocked"
     try:
-        r = subprocess.run(command, shell=True, cwd=WORKDIR,
-                           capture_output=True, text=True, timeout=120)
-        out = (r.stdout + r.stderr).strip()
-        return out[:50000] if out else "(no output)"
+        result = subprocess.run(
+            command,
+            shell=True,
+            cwd=WORKDIR,
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
     except subprocess.TimeoutExpired:
         return "Error: Timeout (120s)"
 
-def run_read(path: str, limit: int = None) -> str:
+    output = (result.stdout + result.stderr).strip()
+    return output[:50000] if output else "(no output)"
+
+
+def run_read(path: str, limit: int | None = None) -> str:
     try:
         lines = safe_path(path).read_text().splitlines()
         if limit and limit < len(lines):
-            lines = lines[:limit] + [f"... ({len(lines) - limit} more)"]
+            lines = lines[:limit] + [f"... ({len(lines) - limit} more lines)"]
         return "\n".join(lines)[:50000]
-    except Exception as e:
-        return f"Error: {e}"
+    except Exception as exc:
+        return f"Error: {exc}"
+
 
 def run_write(path: str, content: str) -> str:
     try:
-        fp = safe_path(path)
-        fp.parent.mkdir(parents=True, exist_ok=True)
-        fp.write_text(content)
-        return f"Wrote {len(content)} bytes"
-    except Exception as e:
-        return f"Error: {e}"
+        file_path = safe_path(path)
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_path.write_text(content)
+        return f"Wrote {len(content)} bytes to {path}"
+    except Exception as exc:
+        return f"Error: {exc}"
+
 
 def run_edit(path: str, old_text: str, new_text: str) -> str:
     try:
-        fp = safe_path(path)
-        content = fp.read_text()
+        file_path = safe_path(path)
+        content = file_path.read_text()
         if old_text not in content:
             return f"Error: Text not found in {path}"
-        fp.write_text(content.replace(old_text, new_text, 1))
+        file_path.write_text(content.replace(old_text, new_text, 1))
         return f"Edited {path}"
-    except Exception as e:
-        return f"Error: {e}"
+    except Exception as exc:
+        return f"Error: {exc}"
 
 
 TOOL_HANDLERS = {
-    "bash":       lambda **kw: run_bash(kw["command"]),
-    "read_file":  lambda **kw: run_read(kw["path"], kw.get("limit")),
+    "bash": lambda **kw: run_bash(kw["command"]),
+    "read_file": lambda **kw: run_read(kw["path"], kw.get("limit")),
     "write_file": lambda **kw: run_write(kw["path"], kw["content"]),
-    "edit_file":  lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
-    "load_skill": lambda **kw: SKILL_LOADER.get_content(kw["name"]),
+    "edit_file": lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
+    "load_skill": lambda **kw: SKILL_REGISTRY.load_full_text(kw["name"]),
 }
 
 TOOLS = [
-    {"name": "bash", "description": "Run a shell command.",
-     "input_schema": {"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]}},
-    {"name": "read_file", "description": "Read file contents.",
-     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "limit": {"type": "integer"}}, "required": ["path"]}},
-    {"name": "write_file", "description": "Write content to file.",
-     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "content": {"type": "string"}}, "required": ["path", "content"]}},
-    {"name": "edit_file", "description": "Replace exact text in file.",
-     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "old_text": {"type": "string"}, "new_text": {"type": "string"}}, "required": ["path", "old_text", "new_text"]}},
-    {"name": "load_skill", "description": "Load specialized knowledge by name.",
-     "input_schema": {"type": "object", "properties": {"name": {"type": "string", "description": "Skill name to load"}}, "required": ["name"]}},
+    {
+        "name": "bash",
+        "description": "Run a shell command.",
+        "input_schema": {
+            "type": "object",
+            "properties": {"command": {"type": "string"}},
+            "required": ["command"],
+        },
+    },
+    {
+        "name": "read_file",
+        "description": "Read file contents.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string"},
+                "limit": {"type": "integer"},
+            },
+            "required": ["path"],
+        },
+    },
+    {
+        "name": "write_file",
+        "description": "Write content to a file.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string"},
+                "content": {"type": "string"},
+            },
+            "required": ["path", "content"],
+        },
+    },
+    {
+        "name": "edit_file",
+        "description": "Replace exact text in a file once.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string"},
+                "old_text": {"type": "string"},
+                "new_text": {"type": "string"},
+            },
+            "required": ["path", "old_text", "new_text"],
+        },
+    },
+    {
+        "name": "load_skill",
+        "description": "Load the full body of a named skill into the current context.",
+        "input_schema": {
+            "type": "object",
+            "properties": {"name": {"type": "string"}},
+            "required": ["name"],
+        },
+    },
 ]
 
 
-def agent_loop(messages: list):
+def extract_text(content) -> str:
+    if not isinstance(content, list):
+        return ""
+    texts = []
+    for block in content:
+        text = getattr(block, "text", None)
+        if text:
+            texts.append(text)
+    return "\n".join(texts).strip()
+
+
+def agent_loop(messages: list) -> None:
     while True:
         response = client.messages.create(
-            model=MODEL, system=SYSTEM, messages=messages,
-            tools=TOOLS, max_tokens=8000,
+            model=MODEL,
+            system=SYSTEM,
+            messages=messages,
+            tools=TOOLS,
+            max_tokens=8000,
         )
         messages.append({"role": "assistant", "content": response.content})
+
         if response.stop_reason != "tool_use":
             return
+
         results = []
         for block in response.content:
-            if block.type == "tool_use":
-                handler = TOOL_HANDLERS.get(block.name)
-                try:
-                    output = handler(**block.input) if handler else f"Unknown tool: {block.name}"
-                except Exception as e:
-                    output = f"Error: {e}"
-                print(f"> {block.name}:")
-                print(str(output)[:200])
-                results.append({"type": "tool_result", "tool_use_id": block.id, "content": str(output)})
+            if block.type != "tool_use":
+                continue
+
+            handler = TOOL_HANDLERS.get(block.name)
+            try:
+                output = handler(**block.input) if handler else f"Unknown tool: {block.name}"
+            except Exception as exc:
+                output = f"Error: {exc}"
+
+            print(f"> {block.name}: {str(output)[:200]}")
+            results.append({
+                "type": "tool_result",
+                "tool_use_id": block.id,
+                "content": str(output),
+            })
+
         messages.append({"role": "user", "content": results})
 
 
@@ -217,11 +288,11 @@ def agent_loop(messages: list):
             break
         if query.strip().lower() in ("q", "exit", ""):
             break
+
         history.append({"role": "user", "content": query})
         agent_loop(history)
-        response_content = history[-1]["content"]
-        if isinstance(response_content, list):
-            for block in response_content:
-                if hasattr(block, "text"):
-                    print(block.text)
+
+        final_text = extract_text(history[-1]["content"])
+        if final_text:
+            print(final_text)
         print()
diff --git a/agents/s06_context_compact.py b/agents/s06_context_compact.py
index 0fde70efd..e75f13ccd 100644
--- a/agents/s06_context_compact.py
+++ b/agents/s06_context_compact.py
@@ -1,43 +1,24 @@
 #!/usr/bin/env python3
-# Harness: compression -- clean memory for infinite sessions.
+# Harness: compression -- keep the active context small enough to keep working.
 """
-s06_context_compact.py - Compact
-
-Three-layer compression pipeline so the agent can work forever:
-
-    Every turn:
-    +------------------+
-    | Tool call result |
-    +------------------+
-            |
-            v
-    [Layer 1: micro_compact]        (silent, every turn)
-      Replace non-read_file tool_result content older than last 3
-      with "[Previous: used {tool_name}]"
-            |
-            v
-    [Check: tokens > 50000?]
-       |               |
-       no              yes
-       |               |
-       v               v
-    continue    [Layer 2: auto_compact]
-                  Save full transcript to .transcripts/
-                  Ask LLM to summarize conversation.
-                  Replace all messages with [summary].
-                        |
-                        v
-                [Layer 3: compact tool]
-                  Model calls compact -> immediate summarization.
-                  Same as auto, triggered manually.
-
-Key insight: "The agent can forget strategically and keep working forever."
+s06_context_compact.py - Context Compact
+
+This teaching version keeps the compact model intentionally small:
+
+1. Large tool output is persisted to disk and replaced with a preview marker.
+2. Older tool results are micro-compacted into short placeholders.
+3. When the whole conversation gets too large, the agent summarizes it and
+   continues from that summary.
+
+The goal is not to model every production branch. The goal is to make the
+active-context idea explicit and teachable.
 """
 
 import json
 import os
 import subprocess
 import time
+from dataclasses import dataclass, field
 from pathlib import Path
 
 from anthropic import Anthropic
@@ -52,193 +33,332 @@
 client = Anthropic(base_url=os.getenv("ANTHROPIC_BASE_URL"))
 MODEL = os.environ["MODEL_ID"]
 
-SYSTEM = f"You are a coding agent at {WORKDIR}. Use tools to solve tasks."
+SYSTEM = (
+    f"You are a coding agent at {WORKDIR}. "
+    "Keep working step by step, and use compact if the conversation gets too long."
+)
 
-THRESHOLD = 50000
+CONTEXT_LIMIT = 50000
+KEEP_RECENT_TOOL_RESULTS = 3
+PERSIST_THRESHOLD = 30000
+PREVIEW_CHARS = 2000
 TRANSCRIPT_DIR = WORKDIR / ".transcripts"
-KEEP_RECENT = 3
-PRESERVE_RESULT_TOOLS = {"read_file"}
+TOOL_RESULTS_DIR = WORKDIR / ".task_outputs" / "tool-results"
+
+
+@dataclass
+class CompactState:
+    has_compacted: bool = False
+    last_summary: str = ""
+    recent_files: list[str] = field(default_factory=list)
+
+
+def estimate_context_size(messages: list) -> int:
+    return len(str(messages))
+
 
+def track_recent_file(state: CompactState, path: str) -> None:
+    if path in state.recent_files:
+        state.recent_files.remove(path)
+    state.recent_files.append(path)
+    if len(state.recent_files) > 5:
+        state.recent_files[:] = state.recent_files[-5:]
 
-def estimate_tokens(messages: list) -> int:
-    """Rough token count: ~4 chars per token."""
-    return len(str(messages)) // 4
+
+def safe_path(path_str: str) -> Path:
+    path = (WORKDIR / path_str).resolve()
+    if not path.is_relative_to(WORKDIR):
+        raise ValueError(f"Path escapes workspace: {path_str}")
+    return path
+
+
+def persist_large_output(tool_use_id: str, output: str) -> str:
+    if len(output) <= PERSIST_THRESHOLD:
+        return output
+
+    TOOL_RESULTS_DIR.mkdir(parents=True, exist_ok=True)
+    stored_path = TOOL_RESULTS_DIR / f"{tool_use_id}.txt"
+    if not stored_path.exists():
+        stored_path.write_text(output)
+
+    preview = output[:PREVIEW_CHARS]
+    rel_path = stored_path.relative_to(WORKDIR)
+    return (
+        "<persisted-output>\n"
+        f"Full output saved to: {rel_path}\n"
+        "Preview:\n"
+        f"{preview}\n"
+        "</persisted-output>"
+    )
+
+
+def collect_tool_result_blocks(messages: list) -> list[tuple[int, int, dict]]:
+    blocks = []
+    for message_index, message in enumerate(messages):
+        content = message.get("content")
+        if message.get("role") != "user" or not isinstance(content, list):
+            continue
+        for block_index, block in enumerate(content):
+            if isinstance(block, dict) and block.get("type") == "tool_result":
+                blocks.append((message_index, block_index, block))
+    return blocks
 
 
-# -- Layer 1: micro_compact - replace old tool results with placeholders --
 def micro_compact(messages: list) -> list:
-    # Collect (msg_index, part_index, tool_result_dict) for all tool_result entries
-    tool_results = []
-    for msg_idx, msg in enumerate(messages):
-        if msg["role"] == "user" and isinstance(msg.get("content"), list):
-            for part_idx, part in enumerate(msg["content"]):
-                if isinstance(part, dict) and part.get("type") == "tool_result":
-                    tool_results.append((msg_idx, part_idx, part))
-    if len(tool_results) <= KEEP_RECENT:
+    tool_results = collect_tool_result_blocks(messages)
+    if len(tool_results) <= KEEP_RECENT_TOOL_RESULTS:
         return messages
-    # Find tool_name for each result by matching tool_use_id in prior assistant messages
-    tool_name_map = {}
-    for msg in messages:
-        if msg["role"] == "assistant":
-            content = msg.get("content", [])
-            if isinstance(content, list):
-                for block in content:
-                    if hasattr(block, "type") and block.type == "tool_use":
-                        tool_name_map[block.id] = block.name
-    # Clear old results (keep last KEEP_RECENT). Preserve read_file outputs because
-    # they are reference material; compacting them forces the agent to re-read files.
-    to_clear = tool_results[:-KEEP_RECENT]
-    for _, _, result in to_clear:
-        if not isinstance(result.get("content"), str) or len(result["content"]) <= 100:
-            continue
-        tool_id = result.get("tool_use_id", "")
-        tool_name = tool_name_map.get(tool_id, "unknown")
-        if tool_name in PRESERVE_RESULT_TOOLS:
+
+    for _, _, block in tool_results[:-KEEP_RECENT_TOOL_RESULTS]:
+        content = block.get("content", "")
+        if not isinstance(content, str) or len(content) <= 120:
             continue
-        result["content"] = f"[Previous: used {tool_name}]"
+        block["content"] = "[Earlier tool result compacted. Re-run the tool if you need full detail.]"
     return messages
 
 
-# -- Layer 2: auto_compact - save transcript, summarize, replace messages --
-def auto_compact(messages: list) -> list:
-    # Save full transcript to disk
-    TRANSCRIPT_DIR.mkdir(exist_ok=True)
-    transcript_path = TRANSCRIPT_DIR / f"transcript_{int(time.time())}.jsonl"
-    with open(transcript_path, "w") as f:
-        for msg in messages:
-            f.write(json.dumps(msg, default=str) + "\n")
-    print(f"[transcript saved: {transcript_path}]")
-    # Ask LLM to summarize
-    conversation_text = json.dumps(messages, default=str)[-80000:]
+def write_transcript(messages: list) -> Path:
+    TRANSCRIPT_DIR.mkdir(parents=True, exist_ok=True)
+    path = TRANSCRIPT_DIR / f"transcript_{int(time.time())}.jsonl"
+    with path.open("w") as handle:
+        for message in messages:
+            handle.write(json.dumps(message, default=str) + "\n")
+    return path
+
+
+def summarize_history(messages: list) -> str:
+    conversation = json.dumps(messages, default=str)[:80000]
+    prompt = (
+        "Summarize this coding-agent conversation so work can continue.\n"
+        "Preserve:\n"
+        "1. The current goal\n"
+        "2. Important findings and decisions\n"
+        "3. Files read or changed\n"
+        "4. Remaining work\n"
+        "5. User constraints and preferences\n"
+        "Be compact but concrete.\n\n"
+        f"{conversation}"
+    )
     response = client.messages.create(
         model=MODEL,
-        messages=[{"role": "user", "content":
-            "Summarize this conversation for continuity. Include: "
-            "1) What was accomplished, 2) Current state, 3) Key decisions made. "
-            "Be concise but preserve critical details.\n\n" + conversation_text}],
+        messages=[{"role": "user", "content": prompt}],
         max_tokens=2000,
     )
-    summary = next((block.text for block in response.content if hasattr(block, "text")), "")
-    if not summary:
-        summary = "No summary generated."
-    # Replace all messages with compressed summary
-    return [
-        {"role": "user", "content": f"[Conversation compressed. Transcript: {transcript_path}]\n\n{summary}"},
-    ]
-
-
-# -- Tool implementations --
-def safe_path(p: str) -> Path:
-    path = (WORKDIR / p).resolve()
-    if not path.is_relative_to(WORKDIR):
-        raise ValueError(f"Path escapes workspace: {p}")
-    return path
+    return response.content[0].text.strip()
+
 
-def run_bash(command: str) -> str:
+def compact_history(messages: list, state: CompactState, focus: str | None = None) -> list:
+    transcript_path = write_transcript(messages)
+    print(f"[transcript saved: {transcript_path}]")
+
+    summary = summarize_history(messages)
+    if focus:
+        summary += f"\n\nFocus to preserve next: {focus}"
+    if state.recent_files:
+        recent_lines = "\n".join(f"- {path}" for path in state.recent_files)
+        summary += f"\n\nRecent files to reopen if needed:\n{recent_lines}"
+
+    state.has_compacted = True
+    state.last_summary = summary
+
+    return [{
+        "role": "user",
+        "content": (
+            "This conversation was compacted so the agent can continue working.\n\n"
+            f"{summary}"
+        ),
+    }]
+
+
+def run_bash(command: str, tool_use_id: str) -> str:
     dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
-    if any(d in command for d in dangerous):
+    if any(item in command for item in dangerous):
         return "Error: Dangerous command blocked"
     try:
-        r = subprocess.run(command, shell=True, cwd=WORKDIR,
-                           capture_output=True, text=True, timeout=120)
-        out = (r.stdout + r.stderr).strip()
-        return out[:50000] if out else "(no output)"
+        result = subprocess.run(
+            command,
+            shell=True,
+            cwd=WORKDIR,
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
     except subprocess.TimeoutExpired:
         return "Error: Timeout (120s)"
 
-def run_read(path: str, limit: int = None) -> str:
+    output = (result.stdout + result.stderr).strip() or "(no output)"
+    return persist_large_output(tool_use_id, output)
+
+
+def run_read(path: str, tool_use_id: str, state: CompactState, limit: int | None = None) -> str:
     try:
+        track_recent_file(state, path)
         lines = safe_path(path).read_text().splitlines()
         if limit and limit < len(lines):
-            lines = lines[:limit] + [f"... ({len(lines) - limit} more)"]
-        return "\n".join(lines)[:50000]
-    except Exception as e:
-        return f"Error: {e}"
+            lines = lines[:limit] + [f"... ({len(lines) - limit} more lines)"]
+        output = "\n".join(lines)
+        return persist_large_output(tool_use_id, output)
+    except Exception as exc:
+        return f"Error: {exc}"
+
 
 def run_write(path: str, content: str) -> str:
     try:
-        fp = safe_path(path)
-        fp.parent.mkdir(parents=True, exist_ok=True)
-        fp.write_text(content)
-        return f"Wrote {len(content)} bytes"
-    except Exception as e:
-        return f"Error: {e}"
+        file_path = safe_path(path)
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_path.write_text(content)
+        return f"Wrote {len(content)} bytes to {path}"
+    except Exception as exc:
+        return f"Error: {exc}"
+
 
 def run_edit(path: str, old_text: str, new_text: str) -> str:
     try:
-        fp = safe_path(path)
-        content = fp.read_text()
+        file_path = safe_path(path)
+        content = file_path.read_text()
         if old_text not in content:
             return f"Error: Text not found in {path}"
-        fp.write_text(content.replace(old_text, new_text, 1))
+        file_path.write_text(content.replace(old_text, new_text, 1))
         return f"Edited {path}"
-    except Exception as e:
-        return f"Error: {e}"
+    except Exception as exc:
+        return f"Error: {exc}"
 
 
-TOOL_HANDLERS = {
-    "bash":       lambda **kw: run_bash(kw["command"]),
-    "read_file":  lambda **kw: run_read(kw["path"], kw.get("limit")),
-    "write_file": lambda **kw: run_write(kw["path"], kw["content"]),
-    "edit_file":  lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
-    "compact":    lambda **kw: "Manual compression requested.",
-}
-
 TOOLS = [
-    {"name": "bash", "description": "Run a shell command.",
-     "input_schema": {"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]}},
-    {"name": "read_file", "description": "Read file contents.",
-     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "limit": {"type": "integer"}}, "required": ["path"]}},
-    {"name": "write_file", "description": "Write content to file.",
-     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "content": {"type": "string"}}, "required": ["path", "content"]}},
-    {"name": "edit_file", "description": "Replace exact text in file.",
-     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "old_text": {"type": "string"}, "new_text": {"type": "string"}}, "required": ["path", "old_text", "new_text"]}},
-    {"name": "compact", "description": "Trigger manual conversation compression.",
-     "input_schema": {"type": "object", "properties": {"focus": {"type": "string", "description": "What to preserve in the summary"}}}},
+    {
+        "name": "bash",
+        "description": "Run a shell command.",
+        "input_schema": {
+            "type": "object",
+            "properties": {"command": {"type": "string"}},
+            "required": ["command"],
+        },
+    },
+    {
+        "name": "read_file",
+        "description": "Read file contents.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string"},
+                "limit": {"type": "integer"},
+            },
+            "required": ["path"],
+        },
+    },
+    {
+        "name": "write_file",
+        "description": "Write content to a file.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string"},
+                "content": {"type": "string"},
+            },
+            "required": ["path", "content"],
+        },
+    },
+    {
+        "name": "edit_file",
+        "description": "Replace exact text in a file once.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string"},
+                "old_text": {"type": "string"},
+                "new_text": {"type": "string"},
+            },
+            "required": ["path", "old_text", "new_text"],
+        },
+    },
+    {
+        "name": "compact",
+        "description": "Summarize earlier conversation so work can continue in a smaller context.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "focus": {"type": "string"},
+            },
+        },
+    },
 ]
 
 
-def agent_loop(messages: list):
+def extract_text(content) -> str:
+    if not isinstance(content, list):
+        return ""
+    texts = []
+    for block in content:
+        text = getattr(block, "text", None)
+        if text:
+            texts.append(text)
+    return "\n".join(texts).strip()
+
+
+def execute_tool(block, state: CompactState) -> str:
+    if block.name == "bash":
+        return run_bash(block.input["command"], block.id)
+    if block.name == "read_file":
+        return run_read(block.input["path"], block.id, state, block.input.get("limit"))
+    if block.name == "write_file":
+        return run_write(block.input["path"], block.input["content"])
+    if block.name == "edit_file":
+        return run_edit(block.input["path"], block.input["old_text"], block.input["new_text"])
+    if block.name == "compact":
+        return "Compacting conversation..."
+    return f"Unknown tool: {block.name}"
+
+
+def agent_loop(messages: list, state: CompactState) -> None:
     while True:
-        # Layer 1: micro_compact before each LLM call
-        micro_compact(messages)
-        # Layer 2: auto_compact if token estimate exceeds threshold
-        if estimate_tokens(messages) > THRESHOLD:
-            print("[auto_compact triggered]")
-            messages[:] = auto_compact(messages)
+        messages[:] = micro_compact(messages)
+
+        if estimate_context_size(messages) > CONTEXT_LIMIT:
+            print("[auto compact]")
+            messages[:] = compact_history(messages, state)
+
         response = client.messages.create(
-            model=MODEL, system=SYSTEM, messages=messages,
-            tools=TOOLS, max_tokens=8000,
+            model=MODEL,
+            system=SYSTEM,
+            messages=messages,
+            tools=TOOLS,
+            max_tokens=8000,
         )
         messages.append({"role": "assistant", "content": response.content})
+
         if response.stop_reason != "tool_use":
             return
+
         results = []
         manual_compact = False
+        compact_focus = None
         for block in response.content:
-            if block.type == "tool_use":
-                if block.name == "compact":
-                    manual_compact = True
-                    output = "Compressing..."
-                else:
-                    handler = TOOL_HANDLERS.get(block.name)
-                    try:
-                        output = handler(**block.input) if handler else f"Unknown tool: {block.name}"
-                    except Exception as e:
-                        output = f"Error: {e}"
-                print(f"> {block.name}:")
-                print(str(output)[:200])
-                results.append({"type": "tool_result", "tool_use_id": block.id, "content": str(output)})
+            if block.type != "tool_use":
+                continue
+
+            output = execute_tool(block, state)
+            if block.name == "compact":
+                manual_compact = True
+                compact_focus = (block.input or {}).get("focus")
+
+            print(f"> {block.name}: {str(output)[:200]}")
+            results.append({
+                "type": "tool_result",
+                "tool_use_id": block.id,
+                "content": str(output),
+            })
+
         messages.append({"role": "user", "content": results})
-        # Layer 3: manual compact triggered by the compact tool
+
         if manual_compact:
             print("[manual compact]")
-            messages[:] = auto_compact(messages)
-            return
+            messages[:] = compact_history(messages, state, focus=compact_focus)
 
 
 if __name__ == "__main__":
     history = []
+    compact_state = CompactState()
+
     while True:
         try:
             query = input("\033[36ms06 >> \033[0m")
@@ -246,11 +366,11 @@ def agent_loop(messages: list):
             break
         if query.strip().lower() in ("q", "exit", ""):
             break
+
         history.append({"role": "user", "content": query})
-        agent_loop(history)
-        response_content = history[-1]["content"]
-        if isinstance(response_content, list):
-            for block in response_content:
-                if hasattr(block, "text"):
-                    print(block.text)
+        agent_loop(history, compact_state)
+
+        final_text = extract_text(history[-1]["content"])
+        if final_text:
+            print(final_text)
         print()
diff --git a/agents/s07_permission_system.py b/agents/s07_permission_system.py
new file mode 100644
index 000000000..747b904ee
--- /dev/null
+++ b/agents/s07_permission_system.py
@@ -0,0 +1,419 @@
+#!/usr/bin/env python3
+# Harness: safety -- the pipeline between intent and execution.
+"""
+s07_permission_system.py - Permission System
+
+Every tool call passes through a permission pipeline before execution.
+
+Teaching pipeline:
+  1. deny rules
+  2. mode check
+  3. allow rules
+  4. ask user
+
+This version intentionally teaches three modes first:
+  - default
+  - plan
+  - auto
+
+That is enough to build a real, understandable permission system without
+burying readers under every advanced policy branch on day one.
+
+Key insight: "Safety is a pipeline, not a boolean."
+"""
+
+import json
+import os
+import re
+import subprocess
+from fnmatch import fnmatch
+from pathlib import Path
+
+from anthropic import Anthropic
+from dotenv import load_dotenv
+
+load_dotenv(override=True)
+
+if os.getenv("ANTHROPIC_BASE_URL"):
+    os.environ.pop("ANTHROPIC_AUTH_TOKEN", None)
+
+WORKDIR = Path.cwd()
+client = Anthropic(base_url=os.getenv("ANTHROPIC_BASE_URL"))
+MODEL = os.environ["MODEL_ID"]
+
+# -- Permission modes --
+# Teaching version starts with three clear modes first.
+MODES = ("default", "plan", "auto")
+
+READ_ONLY_TOOLS = {"read_file", "bash_readonly"}
+
+# Tools that modify state
+WRITE_TOOLS = {"write_file", "edit_file", "bash"}
+
+
+# -- Bash security validation --
+class BashSecurityValidator:
+    """
+    Validate bash commands for obviously dangerous patterns.
+
+    The teaching version deliberately keeps this small and easy to read.
+    First catch a few high-risk patterns, then let the permission pipeline
+    decide whether to deny or ask the user.
+    """
+
+    VALIDATORS = [
+        ("shell_metachar", r"[;&|`$]"),       # shell metacharacters
+        ("sudo", r"\bsudo\b"),                 # privilege escalation
+        ("rm_rf", r"\brm\s+(-[a-zA-Z]*)?r"),  # recursive delete
+        ("cmd_substitution", r"\$\("),          # command substitution
+        ("ifs_injection", r"\bIFS\s*="),        # IFS manipulation
+    ]
+
+    def validate(self, command: str) -> list:
+        """
+        Check a bash command against all validators.
+
+        Returns list of (validator_name, matched_pattern) tuples for failures.
+        An empty list means the command passed all validators.
+        """
+        failures = []
+        for name, pattern in self.VALIDATORS:
+            if re.search(pattern, command):
+                failures.append((name, pattern))
+        return failures
+
+    def is_safe(self, command: str) -> bool:
+        """Convenience: returns True only if no validators triggered."""
+        return len(self.validate(command)) == 0
+
+    def describe_failures(self, command: str) -> str:
+        """Human-readable summary of validation failures."""
+        failures = self.validate(command)
+        if not failures:
+            return "No issues detected"
+        parts = [f"{name} (pattern: {pattern})" for name, pattern in failures]
+        return "Security flags: " + ", ".join(parts)
+
+
+# -- Workspace trust --
+def is_workspace_trusted(workspace: Path = None) -> bool:
+    """
+    Check if a workspace has been explicitly marked as trusted.
+
+    The teaching version uses a simple marker file. A more complete system
+    can layer richer trust flows on top of the same idea.
+    """
+    ws = workspace or WORKDIR
+    trust_marker = ws / ".claude" / ".claude_trusted"
+    return trust_marker.exists()
+
+
+# Singleton validator instance used by the permission pipeline
+bash_validator = BashSecurityValidator()
+
+
+# -- Permission rules --
+# Rules are checked in order: first match wins.
+# Format: {"tool": "<tool_name_or_*>", "path": "<glob_or_*>", "behavior": "allow|deny|ask"}
+DEFAULT_RULES = [
+    # Always deny dangerous patterns
+    {"tool": "bash", "content": "rm -rf /", "behavior": "deny"},
+    {"tool": "bash", "content": "sudo *", "behavior": "deny"},
+    # Allow reading anything
+    {"tool": "read_file", "path": "*", "behavior": "allow"},
+]
+
+
+class PermissionManager:
+    """
+    Manages permission decisions for tool calls.
+
+    Pipeline: deny_rules -> mode_check -> allow_rules -> ask_user
+
+    The teaching version keeps the decision path short on purpose so readers
+    can implement it themselves before adding more advanced policy layers.
+    """
+
+    def __init__(self, mode: str = "default", rules: list = None):
+        if mode not in MODES:
+            raise ValueError(f"Unknown mode: {mode}. Choose from {MODES}")
+        self.mode = mode
+        self.rules = rules or list(DEFAULT_RULES)
+        # Simple denial tracking helps surface when the agent is repeatedly
+        # asking for actions the system will not allow.
+        self.consecutive_denials = 0
+        self.max_consecutive_denials = 3
+
+    def check(self, tool_name: str, tool_input: dict) -> dict:
+        """
+        Returns: {"behavior": "allow"|"deny"|"ask", "reason": str}
+        """
+        # Step 0: Bash security validation (before deny rules)
+        # Teaching version checks early for clarity.
+        if tool_name == "bash":
+            command = tool_input.get("command", "")
+            failures = bash_validator.validate(command)
+            if failures:
+                # Severe patterns (sudo, rm_rf) get immediate deny
+                severe = {"sudo", "rm_rf"}
+                severe_hits = [f for f in failures if f[0] in severe]
+                if severe_hits:
+                    desc = bash_validator.describe_failures(command)
+                    return {"behavior": "deny",
+                            "reason": f"Bash validator: {desc}"}
+                # Other patterns escalate to ask (user can still approve)
+                desc = bash_validator.describe_failures(command)
+                return {"behavior": "ask",
+                        "reason": f"Bash validator flagged: {desc}"}
+
+        # Step 1: Deny rules (bypass-immune, checked first always)
+        for rule in self.rules:
+            if rule["behavior"] != "deny":
+                continue
+            if self._matches(rule, tool_name, tool_input):
+                return {"behavior": "deny",
+                        "reason": f"Blocked by deny rule: {rule}"}
+
+        # Step 2: Mode-based decisions
+        if self.mode == "plan":
+            # Plan mode: deny all write operations, allow reads
+            if tool_name in WRITE_TOOLS:
+                return {"behavior": "deny",
+                        "reason": "Plan mode: write operations are blocked"}
+            return {"behavior": "allow", "reason": "Plan mode: read-only allowed"}
+
+        if self.mode == "auto":
+            # Auto mode: auto-allow read-only tools, ask for writes
+            if tool_name in READ_ONLY_TOOLS or tool_name == "read_file":
+                return {"behavior": "allow",
+                        "reason": "Auto mode: read-only tool auto-approved"}
+            # Teaching: fall through to allow rules, then ask
+            pass
+
+        # Step 3: Allow rules
+        for rule in self.rules:
+            if rule["behavior"] != "allow":
+                continue
+            if self._matches(rule, tool_name, tool_input):
+                self.consecutive_denials = 0
+                return {"behavior": "allow",
+                        "reason": f"Matched allow rule: {rule}"}
+
+        # Step 4: Ask user (default behavior for unmatched tools)
+        return {"behavior": "ask",
+                "reason": f"No rule matched for {tool_name}, asking user"}
+
+    def ask_user(self, tool_name: str, tool_input: dict) -> bool:
+        """Interactive approval prompt. Returns True if approved."""
+        preview = json.dumps(tool_input, ensure_ascii=False)[:200]
+        print(f"\n  [Permission] {tool_name}: {preview}")
+        try:
+            answer = input("  Allow? (y/n/always): ").strip().lower()
+        except (EOFError, KeyboardInterrupt):
+            return False
+
+        if answer == "always":
+            # Add permanent allow rule for this tool
+            self.rules.append({"tool": tool_name, "path": "*", "behavior": "allow"})
+            self.consecutive_denials = 0
+            return True
+        if answer in ("y", "yes"):
+            self.consecutive_denials = 0
+            return True
+
+        # Track denials for circuit breaker
+        self.consecutive_denials += 1
+        if self.consecutive_denials >= self.max_consecutive_denials:
+            print(f"  [{self.consecutive_denials} consecutive denials -- "
+                  "consider switching to plan mode]")
+        return False
+
+    def _matches(self, rule: dict, tool_name: str, tool_input: dict) -> bool:
+        """Check if a rule matches the tool call."""
+        # Tool name match
+        if rule.get("tool") and rule["tool"] != "*":
+            if rule["tool"] != tool_name:
+                return False
+        # Path pattern match
+        if "path" in rule and rule["path"] != "*":
+            path = tool_input.get("path", "")
+            if not fnmatch(path, rule["path"]):
+                return False
+        # Content pattern match (for bash commands)
+        if "content" in rule:
+            command = tool_input.get("command", "")
+            if not fnmatch(command, rule["content"]):
+                return False
+        return True
+
+
+# -- Tool implementations --
+def safe_path(p: str) -> Path:
+    path = (WORKDIR / p).resolve()
+    if not path.is_relative_to(WORKDIR):
+        raise ValueError(f"Path escapes workspace: {p}")
+    return path
+
+
+def run_bash(command: str) -> str:
+    try:
+        r = subprocess.run(command, shell=True, cwd=WORKDIR,
+                           capture_output=True, text=True, timeout=120)
+        out = (r.stdout + r.stderr).strip()
+        return out[:50000] if out else "(no output)"
+    except subprocess.TimeoutExpired:
+        return "Error: Timeout (120s)"
+
+
+def run_read(path: str, limit: int = None) -> str:
+    try:
+        lines = safe_path(path).read_text().splitlines()
+        if limit and limit < len(lines):
+            lines = lines[:limit] + [f"... ({len(lines) - limit} more)"]
+        return "\n".join(lines)[:50000]
+    except Exception as e:
+        return f"Error: {e}"
+
+
+def run_write(path: str, content: str) -> str:
+    try:
+        fp = safe_path(path)
+        fp.parent.mkdir(parents=True, exist_ok=True)
+        fp.write_text(content)
+        return f"Wrote {len(content)} bytes"
+    except Exception as e:
+        return f"Error: {e}"
+
+
+def run_edit(path: str, old_text: str, new_text: str) -> str:
+    try:
+        fp = safe_path(path)
+        content = fp.read_text()
+        if old_text not in content:
+            return f"Error: Text not found in {path}"
+        fp.write_text(content.replace(old_text, new_text, 1))
+        return f"Edited {path}"
+    except Exception as e:
+        return f"Error: {e}"
+
+
+TOOL_HANDLERS = {
+    "bash":       lambda **kw: run_bash(kw["command"]),
+    "read_file":  lambda **kw: run_read(kw["path"], kw.get("limit")),
+    "write_file": lambda **kw: run_write(kw["path"], kw["content"]),
+    "edit_file":  lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
+}
+
+TOOLS = [
+    {"name": "bash", "description": "Run a shell command.",
+     "input_schema": {"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]}},
+    {"name": "read_file", "description": "Read file contents.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "limit": {"type": "integer"}}, "required": ["path"]}},
+    {"name": "write_file", "description": "Write content to file.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "content": {"type": "string"}}, "required": ["path", "content"]}},
+    {"name": "edit_file", "description": "Replace exact text in file.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "old_text": {"type": "string"}, "new_text": {"type": "string"}}, "required": ["path", "old_text", "new_text"]}},
+]
+
+SYSTEM = f"""You are a coding agent at {WORKDIR}. Use tools to solve tasks.
+The user controls permissions. Some tool calls may be denied."""
+
+
+def agent_loop(messages: list, perms: PermissionManager):
+    """
+    The permission-aware agent loop.
+
+    For each tool call:
+      1. LLM requests tool use
+      2. Permission pipeline checks: deny_rules -> mode -> allow_rules -> ask
+      3. If allowed: execute tool, return result
+      4. If denied: return rejection message to LLM
+    """
+    while True:
+        response = client.messages.create(
+            model=MODEL, system=SYSTEM, messages=messages,
+            tools=TOOLS, max_tokens=8000,
+        )
+        messages.append({"role": "assistant", "content": response.content})
+
+        if response.stop_reason != "tool_use":
+            return
+
+        results = []
+        for block in response.content:
+            if block.type != "tool_use":
+                continue
+
+            # -- Permission check --
+            decision = perms.check(block.name, block.input or {})
+
+            if decision["behavior"] == "deny":
+                output = f"Permission denied: {decision['reason']}"
+                print(f"  [DENIED] {block.name}: {decision['reason']}")
+
+            elif decision["behavior"] == "ask":
+                if perms.ask_user(block.name, block.input or {}):
+                    handler = TOOL_HANDLERS.get(block.name)
+                    output = handler(**(block.input or {})) if handler else f"Unknown: {block.name}"
+                    print(f"> {block.name}: {str(output)[:200]}")
+                else:
+                    output = f"Permission denied by user for {block.name}"
+                    print(f"  [USER DENIED] {block.name}")
+
+            else:  # allow
+                handler = TOOL_HANDLERS.get(block.name)
+                output = handler(**(block.input or {})) if handler else f"Unknown: {block.name}"
+                print(f"> {block.name}: {str(output)[:200]}")
+
+            results.append({
+                "type": "tool_result",
+                "tool_use_id": block.id,
+                "content": str(output),
+            })
+
+        messages.append({"role": "user", "content": results})
+
+
+if __name__ == "__main__":
+    # Choose permission mode at startup
+    print("Permission modes: default, plan, auto")
+    mode_input = input("Mode (default): ").strip().lower() or "default"
+    if mode_input not in MODES:
+        mode_input = "default"
+
+    perms = PermissionManager(mode=mode_input)
+    print(f"[Permission mode: {mode_input}]")
+
+    history = []
+    while True:
+        try:
+            query = input("\033[36ms07 >> \033[0m")
+        except (EOFError, KeyboardInterrupt):
+            break
+        if query.strip().lower() in ("q", "exit", ""):
+            break
+
+        # /mode command to switch modes at runtime
+        if query.startswith("/mode"):
+            parts = query.split()
+            if len(parts) == 2 and parts[1] in MODES:
+                perms.mode = parts[1]
+                print(f"[Switched to {parts[1]} mode]")
+            else:
+                print(f"Usage: /mode <{'|'.join(MODES)}>")
+            continue
+
+        # /rules command to show current rules
+        if query.strip() == "/rules":
+            for i, rule in enumerate(perms.rules):
+                print(f"  {i}: {rule}")
+            continue
+
+        history.append({"role": "user", "content": query})
+        agent_loop(history, perms)
+        response_content = history[-1]["content"]
+        if isinstance(response_content, list):
+            for block in response_content:
+                if hasattr(block, "text"):
+                    print(block.text)
+        print()
diff --git a/agents/s08_hook_system.py b/agents/s08_hook_system.py
new file mode 100644
index 000000000..f689989bf
--- /dev/null
+++ b/agents/s08_hook_system.py
@@ -0,0 +1,340 @@
+#!/usr/bin/env python3
+# Harness: extensibility -- injecting behavior without touching the loop.
+"""
+s08_hook_system.py - Hook System
+
+Hooks are extension points around the main loop.
+They let readers add behavior without rewriting the loop itself.
+
+Teaching version:
+  - SessionStart
+  - PreToolUse
+  - PostToolUse
+
+Teaching exit-code contract:
+  - 0 -> continue
+  - 1 -> block
+  - 2 -> inject a message
+
+This is intentionally simpler than a production system. The goal here is to
+teach the extension pattern clearly before introducing event-specific edge
+cases.
+
+Key insight: "Extend the agent without touching the loop."
+"""
+
+import json
+import os
+import subprocess
+from pathlib import Path
+
+from anthropic import Anthropic
+from dotenv import load_dotenv
+
+load_dotenv(override=True)
+
+if os.getenv("ANTHROPIC_BASE_URL"):
+    os.environ.pop("ANTHROPIC_AUTH_TOKEN", None)
+
+WORKDIR = Path.cwd()
+client = Anthropic(base_url=os.getenv("ANTHROPIC_BASE_URL"))
+MODEL = os.environ["MODEL_ID"]
+
+# The teaching version keeps only the three clearest events. More complete
+# systems can grow the event surface later.
+
+HOOK_EVENTS = ("PreToolUse", "PostToolUse", "SessionStart")
+HOOK_TIMEOUT = 30  # seconds
+# Real CC timeouts:
+#   TOOL_HOOK_EXECUTION_TIMEOUT_MS = 600000 (10 minutes for tool hooks)
+#   SESSION_END_HOOK_TIMEOUT_MS = 1500 (1.5 seconds for SessionEnd hooks)
+
+# Workspace trust marker. Hooks only run if this file exists (or SDK mode).
+TRUST_MARKER = WORKDIR / ".claude" / ".claude_trusted"
+
+
+class HookManager:
+    """
+    Load and execute hooks from .hooks.json configuration.
+
+    The hook manager does three simple jobs:
+    - load hook definitions
+    - run matching commands for an event
+    - aggregate block / message results for the caller
+    """
+
+    def __init__(self, config_path: Path = None, sdk_mode: bool = False):
+        self.hooks = {"PreToolUse": [], "PostToolUse": [], "SessionStart": []}
+        self._sdk_mode = sdk_mode
+        config_path = config_path or (WORKDIR / ".hooks.json")
+        if config_path.exists():
+            try:
+                config = json.loads(config_path.read_text())
+                for event in HOOK_EVENTS:
+                    self.hooks[event] = config.get("hooks", {}).get(event, [])
+                print(f"[Hooks loaded from {config_path}]")
+            except Exception as e:
+                print(f"[Hook config error: {e}]")
+
+    def _check_workspace_trust(self) -> bool:
+        """
+        Check whether the current workspace is trusted.
+
+        The teaching version uses a simple trust marker file.
+        In SDK mode, trust is treated as implicit.
+        """
+        if self._sdk_mode:
+            return True
+        return TRUST_MARKER.exists()
+
+    def run_hooks(self, event: str, context: dict = None) -> dict:
+        """
+        Execute all hooks for an event.
+
+        Returns: {"blocked": bool, "messages": list[str]}
+          - blocked: True if any hook returned exit code 1
+          - messages: stderr content from exit-code-2 hooks (to inject)
+        """
+        result = {"blocked": False, "messages": []}
+
+        # Trust gate: refuse to run hooks in untrusted workspaces
+        if not self._check_workspace_trust():
+            return result
+
+        hooks = self.hooks.get(event, [])
+
+        for hook_def in hooks:
+            # Check matcher (tool name filter for PreToolUse/PostToolUse)
+            matcher = hook_def.get("matcher")
+            if matcher and context:
+                tool_name = context.get("tool_name", "")
+                if matcher != "*" and matcher != tool_name:
+                    continue
+
+            command = hook_def.get("command", "")
+            if not command:
+                continue
+
+            # Build environment with hook context
+            env = dict(os.environ)
+            if context:
+                env["HOOK_EVENT"] = event
+                env["HOOK_TOOL_NAME"] = context.get("tool_name", "")
+                env["HOOK_TOOL_INPUT"] = json.dumps(
+                    context.get("tool_input", {}), ensure_ascii=False)[:10000]
+                if "tool_output" in context:
+                    env["HOOK_TOOL_OUTPUT"] = str(
+                        context["tool_output"])[:10000]
+
+            try:
+                r = subprocess.run(
+                    command, shell=True, cwd=WORKDIR, env=env,
+                    capture_output=True, text=True, timeout=HOOK_TIMEOUT,
+                )
+
+                if r.returncode == 0:
+                    # Continue silently
+                    if r.stdout.strip():
+                        print(f"  [hook:{event}] {r.stdout.strip()[:100]}")
+
+                    # Optional structured stdout: small extension point that
+                    # keeps the teaching contract simple.
+                    try:
+                        hook_output = json.loads(r.stdout)
+                        if "updatedInput" in hook_output and context:
+                            context["tool_input"] = hook_output["updatedInput"]
+                        if "additionalContext" in hook_output:
+                            result["messages"].append(
+                                hook_output["additionalContext"])
+                        if "permissionDecision" in hook_output:
+                            result["permission_override"] = (
+                                hook_output["permissionDecision"])
+                    except (json.JSONDecodeError, TypeError):
+                        pass  # stdout was not JSON -- normal for simple hooks
+
+                elif r.returncode == 1:
+                    # Block execution
+                    result["blocked"] = True
+                    reason = r.stderr.strip() or "Blocked by hook"
+                    result["block_reason"] = reason
+                    print(f"  [hook:{event}] BLOCKED: {reason[:200]}")
+
+                elif r.returncode == 2:
+                    # Inject message
+                    msg = r.stderr.strip()
+                    if msg:
+                        result["messages"].append(msg)
+                        print(f"  [hook:{event}] INJECT: {msg[:200]}")
+
+            except subprocess.TimeoutExpired:
+                print(f"  [hook:{event}] Timeout ({HOOK_TIMEOUT}s)")
+            except Exception as e:
+                print(f"  [hook:{event}] Error: {e}")
+
+        return result
+
+
+# -- Tool implementations (same as s02) --
+def safe_path(p: str) -> Path:
+    path = (WORKDIR / p).resolve()
+    if not path.is_relative_to(WORKDIR):
+        raise ValueError(f"Path escapes workspace: {p}")
+    return path
+
+
+def run_bash(command: str) -> str:
+    dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
+    if any(d in command for d in dangerous):
+        return "Error: Dangerous command blocked"
+    try:
+        r = subprocess.run(command, shell=True, cwd=WORKDIR,
+                           capture_output=True, text=True, timeout=120)
+        out = (r.stdout + r.stderr).strip()
+        return out[:50000] if out else "(no output)"
+    except subprocess.TimeoutExpired:
+        return "Error: Timeout (120s)"
+
+
+def run_read(path: str, limit: int = None) -> str:
+    try:
+        lines = safe_path(path).read_text().splitlines()
+        if limit and limit < len(lines):
+            lines = lines[:limit] + [f"... ({len(lines) - limit} more)"]
+        return "\n".join(lines)[:50000]
+    except Exception as e:
+        return f"Error: {e}"
+
+
+def run_write(path: str, content: str) -> str:
+    try:
+        fp = safe_path(path)
+        fp.parent.mkdir(parents=True, exist_ok=True)
+        fp.write_text(content)
+        return f"Wrote {len(content)} bytes"
+    except Exception as e:
+        return f"Error: {e}"
+
+
+def run_edit(path: str, old_text: str, new_text: str) -> str:
+    try:
+        fp = safe_path(path)
+        content = fp.read_text()
+        if old_text not in content:
+            return f"Error: Text not found in {path}"
+        fp.write_text(content.replace(old_text, new_text, 1))
+        return f"Edited {path}"
+    except Exception as e:
+        return f"Error: {e}"
+
+
+TOOL_HANDLERS = {
+    "bash":       lambda **kw: run_bash(kw["command"]),
+    "read_file":  lambda **kw: run_read(kw["path"], kw.get("limit")),
+    "write_file": lambda **kw: run_write(kw["path"], kw["content"]),
+    "edit_file":  lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
+}
+
+TOOLS = [
+    {"name": "bash", "description": "Run a shell command.",
+     "input_schema": {"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]}},
+    {"name": "read_file", "description": "Read file contents.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "limit": {"type": "integer"}}, "required": ["path"]}},
+    {"name": "write_file", "description": "Write content to file.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "content": {"type": "string"}}, "required": ["path", "content"]}},
+    {"name": "edit_file", "description": "Replace exact text in file.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "old_text": {"type": "string"}, "new_text": {"type": "string"}}, "required": ["path", "old_text", "new_text"]}},
+]
+
+SYSTEM = f"You are a coding agent at {WORKDIR}. Use tools to solve tasks."
+
+
+def agent_loop(messages: list, hooks: HookManager):
+    """
+    The hook-aware agent loop.
+
+    The teaching version keeps only the clearest integration points:
+    SessionStart, PreToolUse, execute tool, PostToolUse.
+    """
+    while True:
+        response = client.messages.create(
+            model=MODEL, system=SYSTEM, messages=messages,
+            tools=TOOLS, max_tokens=8000,
+        )
+        messages.append({"role": "assistant", "content": response.content})
+
+        if response.stop_reason != "tool_use":
+            return
+
+        results = []
+        for block in response.content:
+            if block.type != "tool_use":
+                continue
+
+            tool_input = dict(block.input or {})
+            ctx = {"tool_name": block.name, "tool_input": tool_input}
+
+            # -- PreToolUse hooks --
+            pre_result = hooks.run_hooks("PreToolUse", ctx)
+
+            # Inject hook messages into results
+            for msg in pre_result.get("messages", []):
+                results.append({
+                    "type": "tool_result", "tool_use_id": block.id,
+                    "content": f"[Hook message]: {msg}",
+                })
+
+            if pre_result.get("blocked"):
+                reason = pre_result.get("block_reason", "Blocked by hook")
+                output = f"Tool blocked by PreToolUse hook: {reason}"
+                results.append({
+                    "type": "tool_result", "tool_use_id": block.id,
+                    "content": output,
+                })
+                continue
+
+            # -- Execute tool --
+            handler = TOOL_HANDLERS.get(block.name)
+            try:
+                output = handler(**tool_input) if handler else f"Unknown: {block.name}"
+            except Exception as e:
+                output = f"Error: {e}"
+            print(f"> {block.name}: {str(output)[:200]}")
+
+            # -- PostToolUse hooks --
+            ctx["tool_output"] = output
+            post_result = hooks.run_hooks("PostToolUse", ctx)
+
+            # Inject post-hook messages
+            for msg in post_result.get("messages", []):
+                output += f"\n[Hook note]: {msg}"
+
+            results.append({
+                "type": "tool_result", "tool_use_id": block.id,
+                "content": str(output),
+            })
+
+        messages.append({"role": "user", "content": results})
+
+
+if __name__ == "__main__":
+    hooks = HookManager()
+
+    # Fire SessionStart hooks
+    hooks.run_hooks("SessionStart", {"tool_name": "", "tool_input": {}})
+
+    history = []
+    while True:
+        try:
+            query = input("\033[36ms08 >> \033[0m")
+        except (EOFError, KeyboardInterrupt):
+            break
+        if query.strip().lower() in ("q", "exit", ""):
+            break
+        history.append({"role": "user", "content": query})
+        agent_loop(history, hooks)
+        response_content = history[-1]["content"]
+        if isinstance(response_content, list):
+            for block in response_content:
+                if hasattr(block, "text"):
+                    print(block.text)
+        print()
diff --git a/agents/s09_memory_system.py b/agents/s09_memory_system.py
new file mode 100644
index 000000000..32dd0b7b5
--- /dev/null
+++ b/agents/s09_memory_system.py
@@ -0,0 +1,534 @@
+#!/usr/bin/env python3
+# Harness: persistence -- remembering across the session boundary.
+"""
+s09_memory_system.py - Memory System
+
+This teaching version focuses on one core idea:
+some information should survive the current conversation, but not everything
+belongs in memory.
+
+Use memory for:
+  - user preferences
+  - repeated user feedback
+  - project facts that are NOT obvious from the current code
+  - pointers to external resources
+
+Do NOT use memory for:
+  - code structure that can be re-read from the repo
+  - temporary task state
+  - secrets
+
+Storage layout:
+  .memory/
+    MEMORY.md
+    prefer_tabs.md
+    review_style.md
+    incident_board.md
+
+Each memory is a small Markdown file with frontmatter.
+The agent can save a memory through save_memory(), and the memory index
+is rebuilt after each write.
+
+An optional "Dream" pass can later consolidate, deduplicate, and prune
+stored memories. It is useful, but it is not the first thing readers need
+to understand.
+
+Key insight: "Memory only stores cross-session information that is still
+worth recalling later and is not easy to re-derive from the current repo."
+"""
+
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+
+from anthropic import Anthropic
+from dotenv import load_dotenv
+
+load_dotenv(override=True)
+
+if os.getenv("ANTHROPIC_BASE_URL"):
+    os.environ.pop("ANTHROPIC_AUTH_TOKEN", None)
+
+WORKDIR = Path.cwd()
+client = Anthropic(base_url=os.getenv("ANTHROPIC_BASE_URL"))
+MODEL = os.environ["MODEL_ID"]
+
+MEMORY_DIR = WORKDIR / ".memory"
+MEMORY_INDEX = MEMORY_DIR / "MEMORY.md"
+MEMORY_TYPES = ("user", "feedback", "project", "reference")
+MAX_INDEX_LINES = 200
+
+
+class MemoryManager:
+    """
+    Load, build, and save persistent memories across sessions.
+
+    The teaching version keeps memory explicit:
+    one Markdown file per memory, plus one compact index file.
+    """
+
+    def __init__(self, memory_dir: Path = None):
+        self.memory_dir = memory_dir or MEMORY_DIR
+        self.memories = {}  # name -> {description, type, content}
+
+    def load_all(self):
+        """Load MEMORY.md index and all individual memory files."""
+        self.memories = {}
+        if not self.memory_dir.exists():
+            return
+
+        # Scan all .md files except MEMORY.md
+        for md_file in sorted(self.memory_dir.glob("*.md")):
+            if md_file.name == "MEMORY.md":
+                continue
+            parsed = self._parse_frontmatter(md_file.read_text())
+            if parsed:
+                name = parsed.get("name", md_file.stem)
+                self.memories[name] = {
+                    "description": parsed.get("description", ""),
+                    "type": parsed.get("type", "project"),
+                    "content": parsed.get("content", ""),
+                    "file": md_file.name,
+                }
+
+        count = len(self.memories)
+        if count > 0:
+            print(f"[Memory loaded: {count} memories from {self.memory_dir}]")
+
+    def load_memory_prompt(self) -> str:
+        """Build a memory section for injection into the system prompt."""
+        if not self.memories:
+            return ""
+
+        sections = []
+        sections.append("# Memories (persistent across sessions)")
+        sections.append("")
+
+        # Group by type for readability
+        for mem_type in MEMORY_TYPES:
+            typed = {k: v for k, v in self.memories.items() if v["type"] == mem_type}
+            if not typed:
+                continue
+            sections.append(f"## [{mem_type}]")
+            for name, mem in typed.items():
+                sections.append(f"### {name}: {mem['description']}")
+                if mem["content"].strip():
+                    sections.append(mem["content"].strip())
+                sections.append("")
+
+        return "\n".join(sections)
+
+    def save_memory(self, name: str, description: str, mem_type: str, content: str) -> str:
+        """
+        Save a memory to disk and update the index.
+
+        Returns a status message.
+        """
+        if mem_type not in MEMORY_TYPES:
+            return f"Error: type must be one of {MEMORY_TYPES}"
+
+        # Sanitize name for filename
+        safe_name = re.sub(r"[^a-zA-Z0-9_-]", "_", name.lower())
+        if not safe_name:
+            return "Error: invalid memory name"
+
+        self.memory_dir.mkdir(parents=True, exist_ok=True)
+
+        # Write individual memory file with frontmatter
+        frontmatter = (
+            f"---\n"
+            f"name: {name}\n"
+            f"description: {description}\n"
+            f"type: {mem_type}\n"
+            f"---\n"
+            f"{content}\n"
+        )
+        file_name = f"{safe_name}.md"
+        file_path = self.memory_dir / file_name
+        file_path.write_text(frontmatter)
+
+        # Update in-memory store
+        self.memories[name] = {
+            "description": description,
+            "type": mem_type,
+            "content": content,
+            "file": file_name,
+        }
+
+        # Rebuild MEMORY.md index
+        self._rebuild_index()
+
+        return f"Saved memory '{name}' [{mem_type}] to {file_path.relative_to(WORKDIR)}"
+
+    def _rebuild_index(self):
+        """Rebuild MEMORY.md from current in-memory state, capped at 200 lines."""
+        lines = ["# Memory Index", ""]
+        for name, mem in self.memories.items():
+            lines.append(f"- {name}: {mem['description']} [{mem['type']}]")
+            if len(lines) >= MAX_INDEX_LINES:
+                lines.append(f"... (truncated at {MAX_INDEX_LINES} lines)")
+                break
+        self.memory_dir.mkdir(parents=True, exist_ok=True)
+        MEMORY_INDEX.write_text("\n".join(lines) + "\n")
+
+    def _parse_frontmatter(self, text: str) -> dict | None:
+        """Parse --- delimited frontmatter + body content."""
+        match = re.match(r"^---\s*\n(.*?)\n---\s*\n(.*)", text, re.DOTALL)
+        if not match:
+            return None
+        header, body = match.group(1), match.group(2)
+        result = {"content": body.strip()}
+        for line in header.splitlines():
+            if ":" in line:
+                key, _, value = line.partition(":")
+                result[key.strip()] = value.strip()
+        return result
+
+
+class DreamConsolidator:
+    """
+    Auto-consolidation of memories between sessions ("Dream").
+
+    This is an optional later-stage feature. Its job is to prevent the memory
+    store from growing into a noisy pile by merging, deduplicating, and
+    pruning entries over time.
+    """
+
+    COOLDOWN_SECONDS = 86400       # 24 hours between consolidations
+    SCAN_THROTTLE_SECONDS = 600    # 10 minutes between scan attempts
+    MIN_SESSION_COUNT = 5          # need enough data to consolidate
+    LOCK_STALE_SECONDS = 3600      # PID lock considered stale after 1 hour
+
+    PHASES = [
+        "Orient: scan MEMORY.md index for structure and categories",
+        "Gather: read individual memory files for full content",
+        "Consolidate: merge related memories, remove stale entries",
+        "Prune: enforce 200-line limit on MEMORY.md index",
+    ]
+
+    def __init__(self, memory_dir: Path = None):
+        self.memory_dir = memory_dir or MEMORY_DIR
+        self.lock_file = self.memory_dir / ".dream_lock"
+        self.enabled = True
+        self.mode = "default"
+        self.last_consolidation_time = 0.0
+        self.last_scan_time = 0.0
+        self.session_count = 0
+
+    def should_consolidate(self) -> tuple[bool, str]:
+        """
+        Check 7 gates in sequence. All must pass.
+        Returns (can_run, reason) where reason explains the first failed gate.
+        """
+        import time
+
+        now = time.time()
+
+        # Gate 1: enabled flag
+        if not self.enabled:
+            return False, "Gate 1: consolidation is disabled"
+
+        # Gate 2: memory directory exists and has memory files
+        if not self.memory_dir.exists():
+            return False, "Gate 2: memory directory does not exist"
+        memory_files = list(self.memory_dir.glob("*.md"))
+        # Exclude MEMORY.md itself from the count
+        memory_files = [f for f in memory_files if f.name != "MEMORY.md"]
+        if not memory_files:
+            return False, "Gate 2: no memory files found"
+
+        # Gate 3: not in plan mode (only consolidate in active modes)
+        if self.mode == "plan":
+            return False, "Gate 3: plan mode does not allow consolidation"
+
+        # Gate 4: 24-hour cooldown since last consolidation
+        time_since_last = now - self.last_consolidation_time
+        if time_since_last < self.COOLDOWN_SECONDS:
+            remaining = int(self.COOLDOWN_SECONDS - time_since_last)
+            return False, f"Gate 4: cooldown active, {remaining}s remaining"
+
+        # Gate 5: 10-minute throttle since last scan attempt
+        time_since_scan = now - self.last_scan_time
+        if time_since_scan < self.SCAN_THROTTLE_SECONDS:
+            remaining = int(self.SCAN_THROTTLE_SECONDS - time_since_scan)
+            return False, f"Gate 5: scan throttle active, {remaining}s remaining"
+
+        # Gate 6: need at least 5 sessions worth of data
+        if self.session_count < self.MIN_SESSION_COUNT:
+            return False, f"Gate 6: only {self.session_count} sessions, need {self.MIN_SESSION_COUNT}"
+
+        # Gate 7: no active lock file (check PID staleness)
+        if not self._acquire_lock():
+            return False, "Gate 7: lock held by another process"
+
+        return True, "All 7 gates passed"
+
+    def consolidate(self) -> list[str]:
+        """
+        Run the 4-phase consolidation process.
+
+        The teaching version returns phase descriptions to make the flow
+        visible without requiring an extra LLM pass here.
+        """
+        import time
+
+        can_run, reason = self.should_consolidate()
+        if not can_run:
+            print(f"[Dream] Cannot consolidate: {reason}")
+            return []
+
+        print("[Dream] Starting consolidation...")
+        self.last_scan_time = time.time()
+
+        completed_phases = []
+        for i, phase in enumerate(self.PHASES, 1):
+            print(f"[Dream] Phase {i}/4: {phase}")
+            completed_phases.append(phase)
+
+        self.last_consolidation_time = time.time()
+        self._release_lock()
+        print(f"[Dream] Consolidation complete: {len(completed_phases)} phases executed")
+        return completed_phases
+
+    def _acquire_lock(self) -> bool:
+        """
+        Acquire a PID-based lock file. Returns False if locked by another
+        live process. Stale locks (older than LOCK_STALE_SECONDS) are removed.
+        """
+        import time
+
+        if self.lock_file.exists():
+            try:
+                lock_data = self.lock_file.read_text().strip()
+                pid_str, timestamp_str = lock_data.split(":", 1)
+                pid = int(pid_str)
+                lock_time = float(timestamp_str)
+
+                # Check if lock is stale
+                if (time.time() - lock_time) > self.LOCK_STALE_SECONDS:
+                    print(f"[Dream] Removing stale lock from PID {pid}")
+                    self.lock_file.unlink()
+                else:
+                    # Check if owning process is still alive
+                    try:
+                        os.kill(pid, 0)
+                        return False  # process alive, lock is valid
+                    except OSError:
+                        print(f"[Dream] Removing lock from dead PID {pid}")
+                        self.lock_file.unlink()
+            except (ValueError, OSError):
+                # Corrupted lock file, remove it
+                self.lock_file.unlink(missing_ok=True)
+
+        # Write new lock
+        try:
+            self.memory_dir.mkdir(parents=True, exist_ok=True)
+            self.lock_file.write_text(f"{os.getpid()}:{time.time()}")
+            return True
+        except OSError:
+            return False
+
+    def _release_lock(self):
+        """Release the lock file if we own it."""
+        try:
+            if self.lock_file.exists():
+                lock_data = self.lock_file.read_text().strip()
+                pid_str = lock_data.split(":")[0]
+                if int(pid_str) == os.getpid():
+                    self.lock_file.unlink()
+        except (ValueError, OSError):
+            pass
+
+
+# -- Tool implementations --
+def safe_path(p: str) -> Path:
+    path = (WORKDIR / p).resolve()
+    if not path.is_relative_to(WORKDIR):
+        raise ValueError(f"Path escapes workspace: {p}")
+    return path
+
+
+def run_bash(command: str) -> str:
+    dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
+    if any(d in command for d in dangerous):
+        return "Error: Dangerous command blocked"
+    try:
+        r = subprocess.run(command, shell=True, cwd=WORKDIR,
+                           capture_output=True, text=True, timeout=120)
+        out = (r.stdout + r.stderr).strip()
+        return out[:50000] if out else "(no output)"
+    except subprocess.TimeoutExpired:
+        return "Error: Timeout (120s)"
+
+
+def run_read(path: str, limit: int = None) -> str:
+    try:
+        lines = safe_path(path).read_text().splitlines()
+        if limit and limit < len(lines):
+            lines = lines[:limit] + [f"... ({len(lines) - limit} more)"]
+        return "\n".join(lines)[:50000]
+    except Exception as e:
+        return f"Error: {e}"
+
+
+def run_write(path: str, content: str) -> str:
+    try:
+        fp = safe_path(path)
+        fp.parent.mkdir(parents=True, exist_ok=True)
+        fp.write_text(content)
+        return f"Wrote {len(content)} bytes"
+    except Exception as e:
+        return f"Error: {e}"
+
+
+def run_edit(path: str, old_text: str, new_text: str) -> str:
+    try:
+        fp = safe_path(path)
+        content = fp.read_text()
+        if old_text not in content:
+            return f"Error: Text not found in {path}"
+        fp.write_text(content.replace(old_text, new_text, 1))
+        return f"Edited {path}"
+    except Exception as e:
+        return f"Error: {e}"
+
+
+# Global memory manager
+memory_mgr = MemoryManager()
+
+
+def run_save_memory(name: str, description: str, mem_type: str, content: str) -> str:
+    return memory_mgr.save_memory(name, description, mem_type, content)
+
+
+TOOL_HANDLERS = {
+    "bash":         lambda **kw: run_bash(kw["command"]),
+    "read_file":    lambda **kw: run_read(kw["path"], kw.get("limit")),
+    "write_file":   lambda **kw: run_write(kw["path"], kw["content"]),
+    "edit_file":    lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
+    "save_memory":  lambda **kw: run_save_memory(kw["name"], kw["description"], kw["type"], kw["content"]),
+}
+
+TOOLS = [
+    {"name": "bash", "description": "Run a shell command.",
+     "input_schema": {"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]}},
+    {"name": "read_file", "description": "Read file contents.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "limit": {"type": "integer"}}, "required": ["path"]}},
+    {"name": "write_file", "description": "Write content to file.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "content": {"type": "string"}}, "required": ["path", "content"]}},
+    {"name": "edit_file", "description": "Replace exact text in file.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "old_text": {"type": "string"}, "new_text": {"type": "string"}}, "required": ["path", "old_text", "new_text"]}},
+    {"name": "save_memory", "description": "Save a persistent memory that survives across sessions.",
+     "input_schema": {"type": "object", "properties": {
+         "name": {"type": "string", "description": "Short identifier (e.g. prefer_tabs, db_schema)"},
+         "description": {"type": "string", "description": "One-line summary of what this memory captures"},
+         "type": {"type": "string", "enum": ["user", "feedback", "project", "reference"],
+                  "description": "user=preferences, feedback=corrections, project=non-obvious project conventions or decision reasons, reference=external resource pointers"},
+         "content": {"type": "string", "description": "Full memory content (multi-line OK)"},
+     }, "required": ["name", "description", "type", "content"]}},
+]
+
+MEMORY_GUIDANCE = """
+When to save memories:
+- User states a preference ("I like tabs", "always use pytest") -> type: user
+- User corrects you ("don't do X", "that was wrong because...") -> type: feedback
+- You learn a project fact that is not easy to infer from current code alone
+  (for example: a rule exists because of compliance, or a legacy module must
+  stay untouched for business reasons) -> type: project
+- You learn where an external resource lives (ticket board, dashboard, docs URL)
+  -> type: reference
+
+When NOT to save:
+- Anything easily derivable from code (function signatures, file structure, directory layout)
+- Temporary task state (current branch, open PR numbers, current TODOs)
+- Secrets or credentials (API keys, passwords)
+"""
+
+
+def build_system_prompt() -> str:
+    """Assemble system prompt with memory content included."""
+    parts = [f"You are a coding agent at {WORKDIR}. Use tools to solve tasks."]
+
+    # Inject memory content if available
+    memory_section = memory_mgr.load_memory_prompt()
+    if memory_section:
+        parts.append(memory_section)
+
+    parts.append(MEMORY_GUIDANCE)
+    return "\n\n".join(parts)
+
+
+def agent_loop(messages: list):
+    """
+    Agent loop with memory-aware system prompt.
+
+    The system prompt is rebuilt each call so newly saved memories
+    are visible in the next LLM turn within the same session.
+    """
+    while True:
+        system = build_system_prompt()
+        response = client.messages.create(
+            model=MODEL, system=system, messages=messages,
+            tools=TOOLS, max_tokens=8000,
+        )
+        messages.append({"role": "assistant", "content": response.content})
+
+        if response.stop_reason != "tool_use":
+            return
+
+        results = []
+        for block in response.content:
+            if block.type != "tool_use":
+                continue
+            handler = TOOL_HANDLERS.get(block.name)
+            try:
+                output = handler(**(block.input or {})) if handler else f"Unknown: {block.name}"
+            except Exception as e:
+                output = f"Error: {e}"
+            print(f"> {block.name}: {str(output)[:200]}")
+            results.append({
+                "type": "tool_result",
+                "tool_use_id": block.id,
+                "content": str(output),
+            })
+
+        messages.append({"role": "user", "content": results})
+
+
+if __name__ == "__main__":
+    # Load existing memories at session start
+    memory_mgr.load_all()
+    mem_count = len(memory_mgr.memories)
+    if mem_count:
+        print(f"[{mem_count} memories loaded into context]")
+    else:
+        print("[No existing memories. The agent can create them with save_memory.]")
+
+    history = []
+    while True:
+        try:
+            query = input("\033[36ms09 >> \033[0m")
+        except (EOFError, KeyboardInterrupt):
+            break
+        if query.strip().lower() in ("q", "exit", ""):
+            break
+
+        # /memories command to list current memories
+        if query.strip() == "/memories":
+            if memory_mgr.memories:
+                for name, mem in memory_mgr.memories.items():
+                    print(f"  [{mem['type']}] {name}: {mem['description']}")
+            else:
+                print("  (no memories)")
+            continue
+
+        history.append({"role": "user", "content": query})
+        agent_loop(history)
+        response_content = history[-1]["content"]
+        if isinstance(response_content, list):
+            for block in response_content:
+                if hasattr(block, "text"):
+                    print(block.text)
+        print()
diff --git a/agents/s10_system_prompt.py b/agents/s10_system_prompt.py
new file mode 100644
index 000000000..617fd4439
--- /dev/null
+++ b/agents/s10_system_prompt.py
@@ -0,0 +1,389 @@
+#!/usr/bin/env python3
+# Harness: assembly -- the system prompt is a pipeline, not a string.
+"""
+s10_system_prompt.py - System Prompt Construction
+
+This chapter teaches one core idea:
+the system prompt should be assembled from clear sections, not written as one
+giant hardcoded blob.
+
+Teaching pipeline:
+  1. core instructions
+  2. tool listing
+  3. skill metadata
+  4. memory section
+  5. CLAUDE.md chain
+  6. dynamic context
+
+The builder keeps stable information separate from information that changes
+often. A simple DYNAMIC_BOUNDARY marker makes that split visible.
+
+Per-turn reminders are even more dynamic. They are better injected as a
+separate user-role system reminder than mixed blindly into the stable prompt.
+
+Key insight: "Prompt construction is a pipeline with boundaries, not one
+big string."
+"""
+
+import datetime
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+
+from anthropic import Anthropic
+from dotenv import load_dotenv
+
+load_dotenv(override=True)
+
+if os.getenv("ANTHROPIC_BASE_URL"):
+    os.environ.pop("ANTHROPIC_AUTH_TOKEN", None)
+
+WORKDIR = Path.cwd()
+client = Anthropic(base_url=os.getenv("ANTHROPIC_BASE_URL"))
+MODEL = os.environ["MODEL_ID"]
+
+DYNAMIC_BOUNDARY = "=== DYNAMIC_BOUNDARY ==="
+
+
+class SystemPromptBuilder:
+    """
+    Assemble the system prompt from independent sections.
+
+    The teaching goal here is clarity:
+    each section has one source and one responsibility.
+
+    That makes the prompt easier to reason about, easier to test, and easier
+    to evolve as the agent grows new capabilities.
+    """
+
+    def __init__(self, workdir: Path = None, tools: list = None):
+        self.workdir = workdir or WORKDIR
+        self.tools = tools or []
+        self.skills_dir = self.workdir / "skills"
+        self.memory_dir = self.workdir / ".memory"
+
+    # -- Section 1: Core instructions --
+    def _build_core(self) -> str:
+        return (
+            f"You are a coding agent operating in {self.workdir}.\n"
+            "Use the provided tools to explore, read, write, and edit files.\n"
+            "Always verify before assuming. Prefer reading files over guessing."
+        )
+
+    # -- Section 2: Tool listings --
+    def _build_tool_listing(self) -> str:
+        if not self.tools:
+            return ""
+        lines = ["# Available tools"]
+        for tool in self.tools:
+            props = tool.get("input_schema", {}).get("properties", {})
+            params = ", ".join(props.keys())
+            lines.append(f"- {tool['name']}({params}): {tool['description']}")
+        return "\n".join(lines)
+
+    # -- Section 3: Skill metadata (layer 1 from s05 concept) --
+    def _build_skill_listing(self) -> str:
+        if not self.skills_dir.exists():
+            return ""
+        skills = []
+        for skill_dir in sorted(self.skills_dir.iterdir()):
+            skill_md = skill_dir / "SKILL.md"
+            if not skill_md.exists():
+                continue
+            text = skill_md.read_text()
+            # Parse frontmatter for name + description
+            match = re.match(r"^---\s*\n(.*?)\n---", text, re.DOTALL)
+            if not match:
+                continue
+            meta = {}
+            for line in match.group(1).splitlines():
+                if ":" in line:
+                    k, _, v = line.partition(":")
+                    meta[k.strip()] = v.strip()
+            name = meta.get("name", skill_dir.name)
+            desc = meta.get("description", "")
+            skills.append(f"- {name}: {desc}")
+        if not skills:
+            return ""
+        return "# Available skills\n" + "\n".join(skills)
+
+    # -- Section 4: Memory content --
+    def _build_memory_section(self) -> str:
+        if not self.memory_dir.exists():
+            return ""
+        memories = []
+        for md_file in sorted(self.memory_dir.glob("*.md")):
+            if md_file.name == "MEMORY.md":
+                continue
+            text = md_file.read_text()
+            match = re.match(r"^---\s*\n(.*?)\n---\s*\n(.*)", text, re.DOTALL)
+            if not match:
+                continue
+            header, body = match.group(1), match.group(2).strip()
+            meta = {}
+            for line in header.splitlines():
+                if ":" in line:
+                    k, _, v = line.partition(":")
+                    meta[k.strip()] = v.strip()
+            name = meta.get("name", md_file.stem)
+            mem_type = meta.get("type", "project")
+            desc = meta.get("description", "")
+            memories.append(f"[{mem_type}] {name}: {desc}\n{body}")
+        if not memories:
+            return ""
+        return "# Memories (persistent)\n\n" + "\n\n".join(memories)
+
+    # -- Section 5: CLAUDE.md chain --
+    def _build_claude_md(self) -> str:
+        """
+        Load CLAUDE.md files in priority order (all are included):
+        1. ~/.claude/CLAUDE.md (user-global instructions)
+        2. <project-root>/CLAUDE.md (project instructions)
+        3. <current-subdir>/CLAUDE.md (directory-specific instructions)
+        """
+        sources = []
+
+        # User-global
+        user_claude = Path.home() / ".claude" / "CLAUDE.md"
+        if user_claude.exists():
+            sources.append(("user global (~/.claude/CLAUDE.md)", user_claude.read_text()))
+
+        # Project root
+        project_claude = self.workdir / "CLAUDE.md"
+        if project_claude.exists():
+            sources.append(("project root (CLAUDE.md)", project_claude.read_text()))
+
+        # Subdirectory -- in real CC, this walks from cwd up to project root
+        # Teaching: check cwd if different from workdir
+        cwd = Path.cwd()
+        if cwd != self.workdir:
+            subdir_claude = cwd / "CLAUDE.md"
+            if subdir_claude.exists():
+                sources.append((f"subdir ({cwd.name}/CLAUDE.md)", subdir_claude.read_text()))
+
+        if not sources:
+            return ""
+        parts = ["# CLAUDE.md instructions"]
+        for label, content in sources:
+            parts.append(f"## From {label}")
+            parts.append(content.strip())
+        return "\n\n".join(parts)
+
+    # -- Section 6: Dynamic context --
+    def _build_dynamic_context(self) -> str:
+        lines = [
+            f"Current date: {datetime.date.today().isoformat()}",
+            f"Working directory: {self.workdir}",
+            f"Model: {MODEL}",
+            f"Platform: {os.uname().sysname}",
+        ]
+        return "# Dynamic context\n" + "\n".join(lines)
+
+    # -- Assemble all sections --
+    def build(self) -> str:
+        """
+        Assemble the full system prompt from all sections.
+
+        Static sections (1-5) are separated from dynamic (6) by
+        the DYNAMIC_BOUNDARY marker. In real CC, the static prefix
+        is cached across turns to save prompt tokens.
+        """
+        sections = []
+
+        core = self._build_core()
+        if core:
+            sections.append(core)
+
+        tools = self._build_tool_listing()
+        if tools:
+            sections.append(tools)
+
+        skills = self._build_skill_listing()
+        if skills:
+            sections.append(skills)
+
+        memory = self._build_memory_section()
+        if memory:
+            sections.append(memory)
+
+        claude_md = self._build_claude_md()
+        if claude_md:
+            sections.append(claude_md)
+
+        # Static/dynamic boundary
+        sections.append(DYNAMIC_BOUNDARY)
+
+        dynamic = self._build_dynamic_context()
+        if dynamic:
+            sections.append(dynamic)
+
+        return "\n\n".join(sections)
+
+
+def build_system_reminder(extra: str = None) -> dict:
+    """
+    Build a system-reminder user message for per-turn dynamic content.
+
+    The teaching version keeps reminders outside the stable system prompt so
+    short-lived context does not get mixed into the long-lived instructions.
+    """
+    parts = []
+    if extra:
+        parts.append(extra)
+    if not parts:
+        return None
+    content = "<system-reminder>\n" + "\n".join(parts) + "\n</system-reminder>"
+    return {"role": "user", "content": content}
+
+
+# -- Tool implementations --
+def safe_path(p: str) -> Path:
+    path = (WORKDIR / p).resolve()
+    if not path.is_relative_to(WORKDIR):
+        raise ValueError(f"Path escapes workspace: {p}")
+    return path
+
+
+def run_bash(command: str) -> str:
+    dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
+    if any(d in command for d in dangerous):
+        return "Error: Dangerous command blocked"
+    try:
+        r = subprocess.run(command, shell=True, cwd=WORKDIR,
+                           capture_output=True, text=True, timeout=120)
+        out = (r.stdout + r.stderr).strip()
+        return out[:50000] if out else "(no output)"
+    except subprocess.TimeoutExpired:
+        return "Error: Timeout (120s)"
+
+
+def run_read(path: str, limit: int = None) -> str:
+    try:
+        lines = safe_path(path).read_text().splitlines()
+        if limit and limit < len(lines):
+            lines = lines[:limit] + [f"... ({len(lines) - limit} more)"]
+        return "\n".join(lines)[:50000]
+    except Exception as e:
+        return f"Error: {e}"
+
+
+def run_write(path: str, content: str) -> str:
+    try:
+        fp = safe_path(path)
+        fp.parent.mkdir(parents=True, exist_ok=True)
+        fp.write_text(content)
+        return f"Wrote {len(content)} bytes"
+    except Exception as e:
+        return f"Error: {e}"
+
+
+def run_edit(path: str, old_text: str, new_text: str) -> str:
+    try:
+        fp = safe_path(path)
+        content = fp.read_text()
+        if old_text not in content:
+            return f"Error: Text not found in {path}"
+        fp.write_text(content.replace(old_text, new_text, 1))
+        return f"Edited {path}"
+    except Exception as e:
+        return f"Error: {e}"
+
+
+TOOL_HANDLERS = {
+    "bash":       lambda **kw: run_bash(kw["command"]),
+    "read_file":  lambda **kw: run_read(kw["path"], kw.get("limit")),
+    "write_file": lambda **kw: run_write(kw["path"], kw["content"]),
+    "edit_file":  lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
+}
+
+TOOLS = [
+    {"name": "bash", "description": "Run a shell command.",
+     "input_schema": {"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]}},
+    {"name": "read_file", "description": "Read file contents.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "limit": {"type": "integer"}}, "required": ["path"]}},
+    {"name": "write_file", "description": "Write content to file.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "content": {"type": "string"}}, "required": ["path", "content"]}},
+    {"name": "edit_file", "description": "Replace exact text in file.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "old_text": {"type": "string"}, "new_text": {"type": "string"}}, "required": ["path", "old_text", "new_text"]}},
+]
+
+# Global prompt builder
+prompt_builder = SystemPromptBuilder(workdir=WORKDIR, tools=TOOLS)
+
+
+def agent_loop(messages: list):
+    """
+    Agent loop with assembled system prompt.
+
+    The system prompt is rebuilt each iteration. In real CC, the static
+    prefix is cached and only the dynamic suffix changes per turn.
+    """
+    while True:
+        system = prompt_builder.build()
+        response = client.messages.create(
+            model=MODEL, system=system, messages=messages,
+            tools=TOOLS, max_tokens=8000,
+        )
+        messages.append({"role": "assistant", "content": response.content})
+
+        if response.stop_reason != "tool_use":
+            return
+
+        results = []
+        for block in response.content:
+            if block.type != "tool_use":
+                continue
+            handler = TOOL_HANDLERS.get(block.name)
+            try:
+                output = handler(**(block.input or {})) if handler else f"Unknown: {block.name}"
+            except Exception as e:
+                output = f"Error: {e}"
+            print(f"> {block.name}: {str(output)[:200]}")
+            results.append({
+                "type": "tool_result",
+                "tool_use_id": block.id,
+                "content": str(output),
+            })
+
+        messages.append({"role": "user", "content": results})
+
+
+if __name__ == "__main__":
+    # Show the assembled prompt at startup for educational purposes
+    full_prompt = prompt_builder.build()
+    section_count = full_prompt.count("\n# ")
+    print(f"[System prompt assembled: {len(full_prompt)} chars, ~{section_count} sections]")
+
+    # /prompt command shows the full assembled prompt
+    history = []
+    while True:
+        try:
+            query = input("\033[36ms10 >> \033[0m")
+        except (EOFError, KeyboardInterrupt):
+            break
+        if query.strip().lower() in ("q", "exit", ""):
+            break
+
+        if query.strip() == "/prompt":
+            print("--- System Prompt ---")
+            print(prompt_builder.build())
+            print("--- End ---")
+            continue
+
+        if query.strip() == "/sections":
+            prompt = prompt_builder.build()
+            for line in prompt.splitlines():
+                if line.startswith("# ") or line == DYNAMIC_BOUNDARY:
+                    print(f"  {line}")
+            continue
+
+        history.append({"role": "user", "content": query})
+        agent_loop(history)
+        response_content = history[-1]["content"]
+        if isinstance(response_content, list):
+            for block in response_content:
+                if hasattr(block, "text"):
+                    print(block.text)
+        print()
diff --git a/agents/s11_error_recovery.py b/agents/s11_error_recovery.py
new file mode 100644
index 000000000..652954052
--- /dev/null
+++ b/agents/s11_error_recovery.py
@@ -0,0 +1,315 @@
+#!/usr/bin/env python3
+# Harness: resilience -- a robust agent recovers instead of crashing.
+"""
+s11_error_recovery.py - Error Recovery
+
+Teaching demo of three recovery paths:
+
+- continue when output is truncated
+- compact when context grows too large
+- back off when transport errors are temporary
+
+    LLM response
+         |
+         v
+    [Check stop_reason]
+         |
+         +-- "max_tokens" ----> [Strategy 1: max_output_tokens recovery]
+         |                       Inject continuation message:
+         |                       "Output limit hit. Continue directly."
+         |                       Retry up to MAX_RECOVERY_ATTEMPTS (3).
+         |                       Counter: max_output_recovery_count
+         |
+         +-- API error -------> [Check error type]
+         |                       |
+         |                       +-- prompt_too_long --> [Strategy 2: compact + retry]
+         |                       |   Trigger auto_compact (LLM summary).
+         |                       |   Replace history with summary.
+         |                       |   Retry the turn.
+         |                       |
+         |                       +-- connection/rate --> [Strategy 3: backoff retry]
+         |                           Exponential backoff: base * 2^attempt + jitter
+         |                           Up to 3 retries.
+         |
+         +-- "end_turn" -----> [Normal exit]
+
+    Recovery priority (first match wins):
+    1. max_tokens -> inject continuation, retry
+    2. prompt_too_long -> compact, retry
+    3. connection error -> backoff, retry
+    4. all retries exhausted -> fail gracefully
+"""
+
+import json
+import os
+import random
+import subprocess
+import time
+from pathlib import Path
+
+from anthropic import Anthropic, APIError
+from dotenv import load_dotenv
+
+load_dotenv(override=True)
+
+if os.getenv("ANTHROPIC_BASE_URL"):
+    os.environ.pop("ANTHROPIC_AUTH_TOKEN", None)
+
+WORKDIR = Path.cwd()
+client = Anthropic(base_url=os.getenv("ANTHROPIC_BASE_URL"))
+MODEL = os.environ["MODEL_ID"]
+
+# Recovery constants
+MAX_RECOVERY_ATTEMPTS = 3
+BACKOFF_BASE_DELAY = 1.0  # seconds
+BACKOFF_MAX_DELAY = 30.0  # seconds
+TOKEN_THRESHOLD = 50000   # chars / 4 ~ tokens for compact trigger
+
+CONTINUATION_MESSAGE = (
+    "Output limit hit. Continue directly from where you stopped -- "
+    "no recap, no repetition. Pick up mid-sentence if needed."
+)
+
+
+def estimate_tokens(messages: list) -> int:
+    """Rough token estimate: ~4 chars per token."""
+    return len(json.dumps(messages, default=str)) // 4
+
+
+def auto_compact(messages: list) -> list:
+    """
+    Compress conversation history into a short continuation summary.
+    """
+    conversation_text = json.dumps(messages, default=str)[:80000]
+    prompt = (
+        "Summarize this conversation for continuity. Include:\n"
+        "1) Task overview and success criteria\n"
+        "2) Current state: completed work, files touched\n"
+        "3) Key decisions and failed approaches\n"
+        "4) Remaining next steps\n"
+        "Be concise but preserve critical details.\n\n"
+        + conversation_text
+    )
+    try:
+        response = client.messages.create(
+            model=MODEL,
+            messages=[{"role": "user", "content": prompt}],
+            max_tokens=4000,
+        )
+        summary = response.content[0].text
+    except Exception as e:
+        summary = f"(compact failed: {e}). Previous context lost."
+
+    continuation = (
+        "This session continues from a previous conversation that was compacted. "
+        f"Summary of prior context:\n\n{summary}\n\n"
+        "Continue from where we left off without re-asking the user."
+    )
+    return [{"role": "user", "content": continuation}]
+
+
+def backoff_delay(attempt: int) -> float:
+    """Exponential backoff with jitter: base * 2^attempt + random(0, 1)."""
+    delay = min(BACKOFF_BASE_DELAY * (2 ** attempt), BACKOFF_MAX_DELAY)
+    jitter = random.uniform(0, 1)
+    return delay + jitter
+
+
+# -- Tool implementations --
+def safe_path(p: str) -> Path:
+    path = (WORKDIR / p).resolve()
+    if not path.is_relative_to(WORKDIR):
+        raise ValueError(f"Path escapes workspace: {p}")
+    return path
+
+
+def run_bash(command: str) -> str:
+    dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
+    if any(d in command for d in dangerous):
+        return "Error: Dangerous command blocked"
+    try:
+        r = subprocess.run(command, shell=True, cwd=WORKDIR,
+                           capture_output=True, text=True, timeout=120)
+        out = (r.stdout + r.stderr).strip()
+        return out[:50000] if out else "(no output)"
+    except subprocess.TimeoutExpired:
+        return "Error: Timeout (120s)"
+
+
+def run_read(path: str, limit: int = None) -> str:
+    try:
+        lines = safe_path(path).read_text().splitlines()
+        if limit and limit < len(lines):
+            lines = lines[:limit] + [f"... ({len(lines) - limit} more)"]
+        return "\n".join(lines)[:50000]
+    except Exception as e:
+        return f"Error: {e}"
+
+
+def run_write(path: str, content: str) -> str:
+    try:
+        fp = safe_path(path)
+        fp.parent.mkdir(parents=True, exist_ok=True)
+        fp.write_text(content)
+        return f"Wrote {len(content)} bytes"
+    except Exception as e:
+        return f"Error: {e}"
+
+
+def run_edit(path: str, old_text: str, new_text: str) -> str:
+    try:
+        fp = safe_path(path)
+        content = fp.read_text()
+        if old_text not in content:
+            return f"Error: Text not found in {path}"
+        fp.write_text(content.replace(old_text, new_text, 1))
+        return f"Edited {path}"
+    except Exception as e:
+        return f"Error: {e}"
+
+
+TOOL_HANDLERS = {
+    "bash":       lambda **kw: run_bash(kw["command"]),
+    "read_file":  lambda **kw: run_read(kw["path"], kw.get("limit")),
+    "write_file": lambda **kw: run_write(kw["path"], kw["content"]),
+    "edit_file":  lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
+}
+
+TOOLS = [
+    {"name": "bash", "description": "Run a shell command.",
+     "input_schema": {"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]}},
+    {"name": "read_file", "description": "Read file contents.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "limit": {"type": "integer"}}, "required": ["path"]}},
+    {"name": "write_file", "description": "Write content to file.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "content": {"type": "string"}}, "required": ["path", "content"]}},
+    {"name": "edit_file", "description": "Replace exact text in file.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "old_text": {"type": "string"}, "new_text": {"type": "string"}}, "required": ["path", "old_text", "new_text"]}},
+]
+
+SYSTEM = f"You are a coding agent at {WORKDIR}. Use tools to solve tasks."
+
+
+def agent_loop(messages: list):
+    """
+    Error-recovering agent loop with three paths:
+
+    1. continue after max_tokens
+    2. compact after prompt-too-long
+    3. back off after transient transport failure
+    """
+    max_output_recovery_count = 0
+
+    while True:
+        # -- Attempt the API call with connection retry --
+        response = None
+        for attempt in range(MAX_RECOVERY_ATTEMPTS + 1):
+            try:
+                response = client.messages.create(
+                    model=MODEL, system=SYSTEM, messages=messages,
+                    tools=TOOLS, max_tokens=8000,
+                )
+                break  # success
+
+            except APIError as e:
+                error_body = str(e).lower()
+
+                # Strategy 2: prompt_too_long -> compact and retry
+                if "overlong_prompt" in error_body or ("prompt" in error_body and "long" in error_body):
+                    print(f"[Recovery] Prompt too long. Compacting... (attempt {attempt + 1})")
+                    messages[:] = auto_compact(messages)
+                    continue
+
+                # Strategy 3: connection/rate errors -> backoff
+                if attempt < MAX_RECOVERY_ATTEMPTS:
+                    delay = backoff_delay(attempt)
+                    print(f"[Recovery] API error: {e}. "
+                          f"Retrying in {delay:.1f}s (attempt {attempt + 1}/{MAX_RECOVERY_ATTEMPTS})")
+                    time.sleep(delay)
+                    continue
+
+                # All retries exhausted
+                print(f"[Error] API call failed after {MAX_RECOVERY_ATTEMPTS} retries: {e}")
+                return
+
+            except (ConnectionError, TimeoutError, OSError) as e:
+                # Strategy 3: network-level errors -> backoff
+                if attempt < MAX_RECOVERY_ATTEMPTS:
+                    delay = backoff_delay(attempt)
+                    print(f"[Recovery] Connection error: {e}. "
+                          f"Retrying in {delay:.1f}s (attempt {attempt + 1}/{MAX_RECOVERY_ATTEMPTS})")
+                    time.sleep(delay)
+                    continue
+
+                print(f"[Error] Connection failed after {MAX_RECOVERY_ATTEMPTS} retries: {e}")
+                return
+
+        if response is None:
+            print("[Error] No response received.")
+            return
+
+        messages.append({"role": "assistant", "content": response.content})
+
+        # -- Strategy 1: max_tokens recovery --
+        if response.stop_reason == "max_tokens":
+            max_output_recovery_count += 1
+            if max_output_recovery_count <= MAX_RECOVERY_ATTEMPTS:
+                print(f"[Recovery] max_tokens hit "
+                      f"({max_output_recovery_count}/{MAX_RECOVERY_ATTEMPTS}). "
+                      "Injecting continuation...")
+                messages.append({"role": "user", "content": CONTINUATION_MESSAGE})
+                continue  # retry the loop
+            else:
+                print(f"[Error] max_tokens recovery exhausted "
+                      f"({MAX_RECOVERY_ATTEMPTS} attempts). Stopping.")
+                return
+
+        # Reset max_tokens counter on successful non-max_tokens response
+        max_output_recovery_count = 0
+
+        # -- Normal end_turn: no tool use requested --
+        if response.stop_reason != "tool_use":
+            return
+
+        # -- Process tool calls --
+        results = []
+        for block in response.content:
+            if block.type != "tool_use":
+                continue
+            handler = TOOL_HANDLERS.get(block.name)
+            try:
+                output = handler(**(block.input or {})) if handler else f"Unknown: {block.name}"
+            except Exception as e:
+                output = f"Error: {e}"
+            print(f"> {block.name}: {str(output)[:200]}")
+            results.append({
+                "type": "tool_result",
+                "tool_use_id": block.id,
+                "content": str(output),
+            })
+
+        messages.append({"role": "user", "content": results})
+
+        # Check if we should auto-compact (proactive, not just reactive)
+        if estimate_tokens(messages) > TOKEN_THRESHOLD:
+            print("[Recovery] Token estimate exceeds threshold. Auto-compacting...")
+            messages[:] = auto_compact(messages)
+
+
+if __name__ == "__main__":
+    print("[Error recovery enabled: max_tokens / prompt_too_long / connection backoff]")
+    history = []
+    while True:
+        try:
+            query = input("\033[36ms11 >> \033[0m")
+        except (EOFError, KeyboardInterrupt):
+            break
+        if query.strip().lower() in ("q", "exit", ""):
+            break
+        history.append({"role": "user", "content": query})
+        agent_loop(history)
+        response_content = history[-1]["content"]
+        if isinstance(response_content, list):
+            for block in response_content:
+                if hasattr(block, "text"):
+                    print(block.text)
+        print()
diff --git a/agents/s07_task_system.py b/agents/s12_task_system.py
similarity index 74%
rename from agents/s07_task_system.py
rename to agents/s12_task_system.py
index cf72783e4..f4e79f805 100644
--- a/agents/s07_task_system.py
+++ b/agents/s12_task_system.py
@@ -1,15 +1,18 @@
 #!/usr/bin/env python3
 # Harness: persistent tasks -- goals that outlive any single conversation.
 """
-s07_task_system.py - Tasks
+s12_task_system.py - Tasks
 
 Tasks persist as JSON files in .tasks/ so they survive context compression.
-Each task has a dependency graph (blockedBy).
+Each task carries a small dependency graph:
+
+- blockedBy: what must finish first
+- blocks: what this task unlocks later
 
     .tasks/
       task_1.json  {"id":1, "subject":"...", "status":"completed", ...}
       task_2.json  {"id":2, "blockedBy":[1], "status":"pending", ...}
-      task_3.json  {"id":3, "blockedBy":[2], ...}
+      task_3.json  {"id":3, "blockedBy":[2], "blocks":[], ...}
 
     Dependency resolution:
     +----------+     +----------+     +----------+
@@ -19,7 +22,22 @@
          |                ^
          +--- completing task 1 removes it from task 2's blockedBy
 
-Key insight: "State that survives compression -- because it's outside the conversation."
+Key idea: task state survives compression because it lives on disk, not only
+inside the conversation.
+These are durable work-graph tasks, not transient runtime execution slots.
+
+Read this file in this order:
+1. TaskManager: what a TaskRecord looks like on disk.
+2. TOOL_HANDLERS / TOOLS: how task operations enter the same loop as normal tools.
+3. agent_loop: how persistent work state is exposed back to the model.
+
+Most common confusion:
+- a task record is a durable work item
+- it is not a thread, background slot, or worker process
+
+Teaching boundary:
+this chapter teaches the durable work graph first.
+Runtime execution slots and schedulers arrive later.
 """
 
 import json
@@ -43,8 +61,13 @@
 SYSTEM = f"You are a coding agent at {WORKDIR}. Use task tools to plan and track work."
 
 
-# -- TaskManager: CRUD with dependency graph, persisted as JSON files --
+# -- TaskManager: CRUD for a persistent task graph --
 class TaskManager:
+    """Persistent TaskRecord store.
+
+    Think "work graph on disk", not "currently running worker".
+    """
+
     def __init__(self, tasks_dir: Path):
         self.dir = tasks_dir
         self.dir.mkdir(exist_ok=True)
@@ -62,35 +85,47 @@ def _load(self, task_id: int) -> dict:
 
     def _save(self, task: dict):
         path = self.dir / f"task_{task['id']}.json"
-        path.write_text(json.dumps(task, indent=2, ensure_ascii=False))
+        path.write_text(json.dumps(task, indent=2))
 
     def create(self, subject: str, description: str = "") -> str:
         task = {
             "id": self._next_id, "subject": subject, "description": description,
-            "status": "pending", "blockedBy": [], "owner": "",
+            "status": "pending", "blockedBy": [], "blocks": [], "owner": "",
         }
         self._save(task)
         self._next_id += 1
-        return json.dumps(task, indent=2, ensure_ascii=False)
+        return json.dumps(task, indent=2)
 
     def get(self, task_id: int) -> str:
-        return json.dumps(self._load(task_id), indent=2, ensure_ascii=False)
+        return json.dumps(self._load(task_id), indent=2)
 
-    def update(self, task_id: int, status: str = None,
-               add_blocked_by: list = None, remove_blocked_by: list = None) -> str:
+    def update(self, task_id: int, status: str = None, owner: str = None,
+               add_blocked_by: list = None, add_blocks: list = None) -> str:
         task = self._load(task_id)
+        if owner is not None:
+            task["owner"] = owner
         if status:
-            if status not in ("pending", "in_progress", "completed"):
+            if status not in ("pending", "in_progress", "completed", "deleted"):
                 raise ValueError(f"Invalid status: {status}")
             task["status"] = status
+            # When a task is completed, remove it from all other tasks' blockedBy
             if status == "completed":
                 self._clear_dependency(task_id)
         if add_blocked_by:
             task["blockedBy"] = list(set(task["blockedBy"] + add_blocked_by))
-        if remove_blocked_by:
-            task["blockedBy"] = [x for x in task["blockedBy"] if x not in remove_blocked_by]
+        if add_blocks:
+            task["blocks"] = list(set(task["blocks"] + add_blocks))
+            # Bidirectional: also update the blocked tasks' blockedBy lists
+            for blocked_id in add_blocks:
+                try:
+                    blocked = self._load(blocked_id)
+                    if task_id not in blocked["blockedBy"]:
+                        blocked["blockedBy"].append(task_id)
+                        self._save(blocked)
+                except ValueError:
+                    pass
         self._save(task)
-        return json.dumps(task, indent=2, ensure_ascii=False)
+        return json.dumps(task, indent=2)
 
     def _clear_dependency(self, completed_id: int):
         """Remove completed_id from all other tasks' blockedBy lists."""
@@ -102,19 +137,16 @@ def _clear_dependency(self, completed_id: int):
 
     def list_all(self) -> str:
         tasks = []
-        files = sorted(
-            self.dir.glob("task_*.json"),
-            key=lambda f: int(f.stem.split("_")[1])
-        )
-        for f in files:
+        for f in sorted(self.dir.glob("task_*.json")):
             tasks.append(json.loads(f.read_text()))
         if not tasks:
             return "No tasks."
         lines = []
         for t in tasks:
-            marker = {"pending": "[ ]", "in_progress": "[>]", "completed": "[x]"}.get(t["status"], "[?]")
+            marker = {"pending": "[ ]", "in_progress": "[>]", "completed": "[x]", "deleted": "[-]"}.get(t["status"], "[?]")
             blocked = f" (blocked by: {t['blockedBy']})" if t.get("blockedBy") else ""
-            lines.append(f"{marker} #{t['id']}: {t['subject']}{blocked}")
+            owner = f" owner={t['owner']}" if t.get("owner") else ""
+            lines.append(f"{marker} #{t['id']}: {t['subject']}{owner}{blocked}")
         return "\n".join(lines)
 
 
@@ -176,7 +208,7 @@ def run_edit(path: str, old_text: str, new_text: str) -> str:
     "write_file":  lambda **kw: run_write(kw["path"], kw["content"]),
     "edit_file":   lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
     "task_create": lambda **kw: TASKS.create(kw["subject"], kw.get("description", "")),
-    "task_update": lambda **kw: TASKS.update(kw["task_id"], kw.get("status"), kw.get("addBlockedBy"), kw.get("removeBlockedBy")),
+    "task_update": lambda **kw: TASKS.update(kw["task_id"], kw.get("status"), kw.get("owner"), kw.get("addBlockedBy"), kw.get("addBlocks")),
     "task_list":   lambda **kw: TASKS.list_all(),
     "task_get":    lambda **kw: TASKS.get(kw["task_id"]),
 }
@@ -192,8 +224,8 @@ def run_edit(path: str, old_text: str, new_text: str) -> str:
      "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "old_text": {"type": "string"}, "new_text": {"type": "string"}}, "required": ["path", "old_text", "new_text"]}},
     {"name": "task_create", "description": "Create a new task.",
      "input_schema": {"type": "object", "properties": {"subject": {"type": "string"}, "description": {"type": "string"}}, "required": ["subject"]}},
-    {"name": "task_update", "description": "Update a task's status or dependencies.",
-     "input_schema": {"type": "object", "properties": {"task_id": {"type": "integer"}, "status": {"type": "string", "enum": ["pending", "in_progress", "completed"]}, "addBlockedBy": {"type": "array", "items": {"type": "integer"}}, "removeBlockedBy": {"type": "array", "items": {"type": "integer"}}}, "required": ["task_id"]}},
+    {"name": "task_update", "description": "Update a task's status, owner, or dependencies.",
+     "input_schema": {"type": "object", "properties": {"task_id": {"type": "integer"}, "status": {"type": "string", "enum": ["pending", "in_progress", "completed", "deleted"]}, "owner": {"type": "string", "description": "Set when a teammate claims the task"}, "addBlockedBy": {"type": "array", "items": {"type": "integer"}}, "addBlocks": {"type": "array", "items": {"type": "integer"}}}, "required": ["task_id"]}},
     {"name": "task_list", "description": "List all tasks with status summary.",
      "input_schema": {"type": "object", "properties": {}}},
     {"name": "task_get", "description": "Get full details of a task by ID.",
@@ -218,8 +250,7 @@ def agent_loop(messages: list):
                     output = handler(**block.input) if handler else f"Unknown tool: {block.name}"
                 except Exception as e:
                     output = f"Error: {e}"
-                print(f"> {block.name}:")
-                print(str(output)[:200])
+                print(f"> {block.name}: {str(output)[:200]}")
                 results.append({"type": "tool_result", "tool_use_id": block.id, "content": str(output)})
         messages.append({"role": "user", "content": results})
 
@@ -228,7 +259,7 @@ def agent_loop(messages: list):
     history = []
     while True:
         try:
-            query = input("\033[36ms07 >> \033[0m")
+            query = input("\033[36ms12 >> \033[0m")
         except (EOFError, KeyboardInterrupt):
             break
         if query.strip().lower() in ("q", "exit", ""):
diff --git a/agents/s08_background_tasks.py b/agents/s13_background_tasks.py
similarity index 63%
rename from agents/s08_background_tasks.py
rename to agents/s13_background_tasks.py
index 390a77780..ea19e6dc2 100644
--- a/agents/s08_background_tasks.py
+++ b/agents/s13_background_tasks.py
@@ -1,10 +1,10 @@
 #!/usr/bin/env python3
 # Harness: background execution -- the model thinks while the harness waits.
 """
-s08_background_tasks.py - Background Tasks
+s13_background_tasks.py - Background Tasks
 
-Run commands in background threads. A notification queue is drained
-before each LLM call to deliver results.
+Run slow commands in background threads. Before each LLM call, the loop
+drains a notification queue and hands finished results back to the model.
 
     Main thread                Background thread
     +-----------------+        +-----------------+
@@ -18,16 +18,19 @@
     Agent ----[spawn A]----[spawn B]----[other work]----
                  |              |
                  v              v
-              [A runs]      [B runs]        (parallel)
+              [A runs]      [B runs]
                  |              |
                  +-- notification queue --> [results injected]
 
-Key insight: "Fire and forget -- the agent doesn't block while the command runs."
+Background tasks here are runtime execution slots, not the durable task-board
+records introduced in s12.
 """
 
 import os
+import json
 import subprocess
 import threading
+import time
 import uuid
 from pathlib import Path
 
@@ -40,28 +43,94 @@
     os.environ.pop("ANTHROPIC_AUTH_TOKEN", None)
 
 WORKDIR = Path.cwd()
+RUNTIME_DIR = WORKDIR / ".runtime-tasks"
+RUNTIME_DIR.mkdir(exist_ok=True)
 client = Anthropic(base_url=os.getenv("ANTHROPIC_BASE_URL"))
 MODEL = os.environ["MODEL_ID"]
 
 SYSTEM = f"You are a coding agent at {WORKDIR}. Use background_run for long-running commands."
 
+STALL_THRESHOLD_S = 45  # seconds before a task is considered stalled
+
+
+class NotificationQueue:
+    """
+    Priority-based notification queue with same-key folding.
+
+    Folding means a newer message can replace an older message with the
+    same key, so the context is not flooded with stale updates.
+    """
+
+    PRIORITIES = {"immediate": 0, "high": 1, "medium": 2, "low": 3}
+
+    def __init__(self):
+        self._queue = []  # list of (priority, key, message)
+        self._lock = threading.Lock()
+
+    def push(self, message: str, priority: str = "medium", key: str = None):
+        """Add a message to the queue, folding if key matches an existing entry."""
+        with self._lock:
+            if key:
+                # Fold: replace existing message with same key
+                self._queue = [(p, k, m) for p, k, m in self._queue if k != key]
+            self._queue.append((self.PRIORITIES.get(priority, 2), key, message))
+            self._queue.sort(key=lambda x: x[0])
+
+    def drain(self) -> list[str]:
+        """Return all pending messages in priority order and clear the queue."""
+        with self._lock:
+            messages = [m for _, _, m in self._queue]
+            self._queue.clear()
+            return messages
+
 
 # -- BackgroundManager: threaded execution + notification queue --
 class BackgroundManager:
     def __init__(self):
-        self.tasks = {}  # task_id -> {status, result, command}
+        self.dir = RUNTIME_DIR
+        self.tasks = {}  # task_id -> {status, result, command, started_at}
         self._notification_queue = []  # completed task results
         self._lock = threading.Lock()
 
+    def _record_path(self, task_id: str) -> Path:
+        return self.dir / f"{task_id}.json"
+
+    def _output_path(self, task_id: str) -> Path:
+        return self.dir / f"{task_id}.log"
+
+    def _persist_task(self, task_id: str):
+        record = dict(self.tasks[task_id])
+        self._record_path(task_id).write_text(
+            json.dumps(record, indent=2, ensure_ascii=False)
+        )
+
+    def _preview(self, output: str, limit: int = 500) -> str:
+        compact = " ".join((output or "(no output)").split())
+        return compact[:limit]
+
     def run(self, command: str) -> str:
         """Start a background thread, return task_id immediately."""
         task_id = str(uuid.uuid4())[:8]
-        self.tasks[task_id] = {"status": "running", "result": None, "command": command}
+        output_file = self._output_path(task_id)
+        self.tasks[task_id] = {
+            "id": task_id,
+            "status": "running",
+            "result": None,
+            "command": command,
+            "started_at": time.time(),
+            "finished_at": None,
+            "result_preview": "",
+            "output_file": str(output_file.relative_to(WORKDIR)),
+        }
+        self._persist_task(task_id)
         thread = threading.Thread(
             target=self._execute, args=(task_id, command), daemon=True
         )
         thread.start()
-        return f"Background task {task_id} started: {command[:80]}"
+        return (
+            f"Background task {task_id} started: {command[:80]} "
+            f"(output_file={output_file.relative_to(WORKDIR)})"
+        )
 
     def _execute(self, task_id: str, command: str):
         """Thread target: run subprocess, capture output, push to queue."""
@@ -78,14 +147,22 @@ def _execute(self, task_id: str, command: str):
         except Exception as e:
             output = f"Error: {e}"
             status = "error"
+        final_output = output or "(no output)"
+        preview = self._preview(final_output)
+        output_path = self._output_path(task_id)
+        output_path.write_text(final_output)
         self.tasks[task_id]["status"] = status
-        self.tasks[task_id]["result"] = output or "(no output)"
+        self.tasks[task_id]["result"] = final_output
+        self.tasks[task_id]["finished_at"] = time.time()
+        self.tasks[task_id]["result_preview"] = preview
+        self._persist_task(task_id)
         with self._lock:
             self._notification_queue.append({
                 "task_id": task_id,
                 "status": status,
                 "command": command[:80],
-                "result": (output or "(no output)")[:500],
+                "preview": preview,
+                "output_file": str(output_path.relative_to(WORKDIR)),
             })
 
     def check(self, task_id: str = None) -> str:
@@ -94,10 +171,20 @@ def check(self, task_id: str = None) -> str:
             t = self.tasks.get(task_id)
             if not t:
                 return f"Error: Unknown task {task_id}"
-            return f"[{t['status']}] {t['command'][:60]}\n{t.get('result') or '(running)'}"
+            visible = {
+                "id": t["id"],
+                "status": t["status"],
+                "command": t["command"],
+                "result_preview": t.get("result_preview", ""),
+                "output_file": t.get("output_file", ""),
+            }
+            return json.dumps(visible, indent=2, ensure_ascii=False)
         lines = []
         for tid, t in self.tasks.items():
-            lines.append(f"{tid}: [{t['status']}] {t['command'][:60]}")
+            lines.append(
+                f"{tid}: [{t['status']}] {t['command'][:60]} "
+                f"-> {t.get('result_preview') or '(running)'}"
+            )
         return "\n".join(lines) if lines else "No background tasks."
 
     def drain_notifications(self) -> list:
@@ -107,6 +194,20 @@ def drain_notifications(self) -> list:
             self._notification_queue.clear()
         return notifs
 
+    def detect_stalled(self) -> list[str]:
+        """
+        Return task IDs that have been running longer than STALL_THRESHOLD_S.
+        """
+        now = time.time()
+        stalled = []
+        for task_id, info in self.tasks.items():
+            if info["status"] != "running":
+                continue
+            elapsed = now - info.get("started_at", now)
+            if elapsed > STALL_THRESHOLD_S:
+                stalled.append(task_id)
+        return stalled
+
 
 BG = BackgroundManager()
 
@@ -187,11 +288,14 @@ def run_edit(path: str, old_text: str, new_text: str) -> str:
 
 def agent_loop(messages: list):
     while True:
-        # Drain background notifications and inject as system message before LLM call
+        # Drain background notifications and inject as a synthetic user/assistant
+        # transcript pair before the next model call (teaching demo behavior).
         notifs = BG.drain_notifications()
         if notifs and messages:
             notif_text = "\n".join(
-                f"[bg:{n['task_id']}] {n['status']}: {n['result']}" for n in notifs
+                f"[bg:{n['task_id']}] {n['status']}: {n['preview']} "
+                f"(output_file={n['output_file']})"
+                for n in notifs
             )
             messages.append({"role": "user", "content": f"<background-results>\n{notif_text}\n</background-results>"})
         response = client.messages.create(
@@ -219,7 +323,7 @@ def agent_loop(messages: list):
     history = []
     while True:
         try:
-            query = input("\033[36ms08 >> \033[0m")
+            query = input("\033[36ms13 >> \033[0m")
         except (EOFError, KeyboardInterrupt):
             break
         if query.strip().lower() in ("q", "exit", ""):
diff --git a/agents/s14_cron_scheduler.py b/agents/s14_cron_scheduler.py
new file mode 100644
index 000000000..57910cc12
--- /dev/null
+++ b/agents/s14_cron_scheduler.py
@@ -0,0 +1,564 @@
+#!/usr/bin/env python3
+# Harness: time -- the agent schedules its own future work.
+"""
+s14_cron_scheduler.py - Cron / Scheduled Tasks
+
+The agent can schedule prompts for future execution using standard cron
+expressions. When a schedule matches the current time, it pushes a
+notification back into the main conversation loop.
+
+    Cron expression: 5 fields
+    +-------+-------+-------+-------+-------+
+    | min   | hour  | dom   | month | dow   |
+    | 0-59  | 0-23  | 1-31  | 1-12  | 0-6   |
+    +-------+-------+-------+-------+-------+
+    Examples:
+      "*/5 * * * *"   -> every 5 minutes
+      "0 9 * * 1"     -> Monday 9:00 AM
+      "30 14 * * *"   -> daily 2:30 PM
+
+    Two persistence modes:
+    +--------------------+-------------------------------+
+    | session-only       | In-memory list, lost on exit  |
+    | durable            | .claude/scheduled_tasks.json  |
+    +--------------------+-------------------------------+
+
+    Two trigger modes:
+    +--------------------+-------------------------------+
+    | recurring          | Repeats until deleted or      |
+    |                    | 7-day auto-expiry             |
+    | one-shot           | Fires once, then auto-deleted |
+    +--------------------+-------------------------------+
+
+    Jitter: recurring tasks can avoid exact minute boundaries.
+
+    Architecture:
+    +-------------------------------+
+    |  Background thread            |
+    |  (checks every 1 second)      |
+    |                               |
+    |  for each task:               |
+    |    if cron_matches(now):      |
+    |      enqueue notification     |
+    +-------------------------------+
+              |
+              v
+    [notification_queue]
+              |
+         (drained at top of agent_loop)
+              |
+              v
+    [injected as user messages before LLM call]
+
+Key idea: scheduling remembers future work, then hands it back to the
+same main loop when the time arrives.
+"""
+
+import json
+import os
+import subprocess
+import threading
+import time
+import uuid
+from datetime import datetime, timedelta
+from pathlib import Path
+from queue import Queue, Empty
+
+from anthropic import Anthropic
+from dotenv import load_dotenv
+
+load_dotenv(override=True)
+
+if os.getenv("ANTHROPIC_BASE_URL"):
+    os.environ.pop("ANTHROPIC_AUTH_TOKEN", None)
+
+WORKDIR = Path.cwd()
+client = Anthropic(base_url=os.getenv("ANTHROPIC_BASE_URL"))
+MODEL = os.environ["MODEL_ID"]
+
+SCHEDULED_TASKS_FILE = WORKDIR / ".claude" / "scheduled_tasks.json"
+CRON_LOCK_FILE = WORKDIR / ".claude" / "cron.lock"
+AUTO_EXPIRY_DAYS = 7
+JITTER_MINUTES = [0, 30]  # avoid these exact minutes for recurring tasks
+JITTER_OFFSET_MAX = 4     # offset range in minutes
+# Teaching version: use a simple 1-4 minute offset when needed.
+
+
+class CronLock:
+    """
+    PID-file-based lock to prevent multiple sessions from firing the same cron job.
+    """
+
+    def __init__(self, lock_path: Path = None):
+        self._lock_path = lock_path or CRON_LOCK_FILE
+
+    def acquire(self) -> bool:
+        """
+        Try to acquire the cron lock. Returns True on success.
+
+        If a lock file exists, check whether the PID inside is still alive.
+        If the process is dead the lock is stale and we can take over.
+        """
+        if self._lock_path.exists():
+            try:
+                stored_pid = int(self._lock_path.read_text().strip())
+                # PID liveness probe: send signal 0 (no-op) to check existence
+                os.kill(stored_pid, 0)
+                # Process is alive -- lock is held by another session
+                return False
+            except (ValueError, ProcessLookupError, PermissionError, OSError):
+                # Stale lock (process dead or PID unparseable) -- remove it
+                pass
+        self._lock_path.parent.mkdir(parents=True, exist_ok=True)
+        self._lock_path.write_text(str(os.getpid()))
+        return True
+
+    def release(self):
+        """Remove the lock file if it belongs to this process."""
+        try:
+            if self._lock_path.exists():
+                stored_pid = int(self._lock_path.read_text().strip())
+                if stored_pid == os.getpid():
+                    self._lock_path.unlink()
+        except (ValueError, OSError):
+            pass
+
+
+def cron_matches(expr: str, dt: datetime) -> bool:
+    """
+    Check if a 5-field cron expression matches a given datetime.
+
+    Fields: minute hour day-of-month month day-of-week
+    Supports: * (any), */N (every N), N (exact), N-M (range), N,M (list)
+
+    No external dependencies -- simple manual matching.
+    """
+    fields = expr.strip().split()
+    if len(fields) != 5:
+        return False
+
+    values = [dt.minute, dt.hour, dt.day, dt.month, dt.weekday()]
+    # Python weekday: 0=Monday; cron: 0=Sunday. Convert.
+    cron_dow = (dt.weekday() + 1) % 7
+    values[4] = cron_dow
+    ranges = [(0, 59), (0, 23), (1, 31), (1, 12), (0, 6)]
+
+    for field, value, (lo, hi) in zip(fields, values, ranges):
+        if not _field_matches(field, value, lo, hi):
+            return False
+    return True
+
+
+def _field_matches(field: str, value: int, lo: int, hi: int) -> bool:
+    """Match a single cron field against a value."""
+    if field == "*":
+        return True
+
+    for part in field.split(","):
+        # Handle step: */N or N-M/S
+        step = 1
+        if "/" in part:
+            part, step_str = part.split("/", 1)
+            step = int(step_str)
+
+        if part == "*":
+            # */N -- check if value is on the step grid
+            if (value - lo) % step == 0:
+                return True
+        elif "-" in part:
+            # Range: N-M
+            start, end = part.split("-", 1)
+            start, end = int(start), int(end)
+            if start <= value <= end and (value - start) % step == 0:
+                return True
+        else:
+            # Exact value
+            if int(part) == value:
+                return True
+
+    return False
+
+
+class CronScheduler:
+    """
+    Manage scheduled tasks with background checking.
+
+    Teaching version keeps only the core pieces: schedule records, a
+    minute checker, optional persistence, and a notification queue.
+    """
+
+    def __init__(self):
+        self.tasks = []        # list of task dicts
+        self.queue = Queue()   # notification queue
+        self._stop_event = threading.Event()
+        self._thread = None
+        self._last_check_minute = -1  # avoid double-firing within same minute
+
+    def start(self):
+        """Load durable tasks and start the background check thread."""
+        self._load_durable()
+        self._thread = threading.Thread(target=self._check_loop, daemon=True)
+        self._thread.start()
+        count = len(self.tasks)
+        if count:
+            print(f"[Cron] Loaded {count} scheduled tasks")
+
+    def stop(self):
+        """Stop the background thread."""
+        self._stop_event.set()
+        if self._thread:
+            self._thread.join(timeout=2)
+
+    def create(self, cron_expr: str, prompt: str,
+               recurring: bool = True, durable: bool = False) -> str:
+        """Create a new scheduled task. Returns the task ID."""
+        task_id = str(uuid.uuid4())[:8]
+        now = time.time()
+
+        task = {
+            "id": task_id,
+            "cron": cron_expr,
+            "prompt": prompt,
+            "recurring": recurring,
+            "durable": durable,
+            "createdAt": now,
+        }
+
+        # Jitter for recurring tasks: if the cron fires on :00 or :30,
+        # note it so we can offset the check slightly
+        if recurring:
+            task["jitter_offset"] = self._compute_jitter(cron_expr)
+
+        self.tasks.append(task)
+        if durable:
+            self._save_durable()
+
+        mode = "recurring" if recurring else "one-shot"
+        store = "durable" if durable else "session-only"
+        return f"Created task {task_id} ({mode}, {store}): cron={cron_expr}"
+
+    def delete(self, task_id: str) -> str:
+        """Delete a scheduled task by ID."""
+        before = len(self.tasks)
+        self.tasks = [t for t in self.tasks if t["id"] != task_id]
+        if len(self.tasks) < before:
+            self._save_durable()
+            return f"Deleted task {task_id}"
+        return f"Task {task_id} not found"
+
+    def list_tasks(self) -> str:
+        """List all scheduled tasks."""
+        if not self.tasks:
+            return "No scheduled tasks."
+        lines = []
+        for t in self.tasks:
+            mode = "recurring" if t["recurring"] else "one-shot"
+            store = "durable" if t["durable"] else "session"
+            age_hours = (time.time() - t["createdAt"]) / 3600
+            lines.append(
+                f"  {t['id']}  {t['cron']}  [{mode}/{store}] "
+                f"({age_hours:.1f}h old): {t['prompt'][:60]}"
+            )
+        return "\n".join(lines)
+
+    def drain_notifications(self) -> list[str]:
+        """Drain all pending notifications from the queue."""
+        notifications = []
+        while True:
+            try:
+                notifications.append(self.queue.get_nowait())
+            except Empty:
+                break
+        return notifications
+
+    def _compute_jitter(self, cron_expr: str) -> int:
+        """If cron targets :00 or :30, return a small offset (1-4 minutes)."""
+        fields = cron_expr.strip().split()
+        if len(fields) < 1:
+            return 0
+        minute_field = fields[0]
+        try:
+            minute_val = int(minute_field)
+            if minute_val in JITTER_MINUTES:
+                # Deterministic jitter based on the expression hash
+                return (hash(cron_expr) % JITTER_OFFSET_MAX) + 1
+        except ValueError:
+            pass
+        return 0
+
+    def _check_loop(self):
+        """Background thread: check every second if any task is due."""
+        while not self._stop_event.is_set():
+            now = datetime.now()
+            current_minute = now.hour * 60 + now.minute
+
+            # Only check once per minute to avoid double-firing
+            if current_minute != self._last_check_minute:
+                self._last_check_minute = current_minute
+                self._check_tasks(now)
+
+            self._stop_event.wait(timeout=1)
+
+    def _check_tasks(self, now: datetime):
+        """Check all tasks against current time, fire matches."""
+        expired = []
+        fired_oneshots = []
+
+        for task in self.tasks:
+            # Auto-expiry: recurring tasks older than 7 days
+            age_days = (time.time() - task["createdAt"]) / 86400
+            if task["recurring"] and age_days > AUTO_EXPIRY_DAYS:
+                expired.append(task["id"])
+                continue
+
+            # Apply jitter offset for the match check
+            check_time = now
+            jitter = task.get("jitter_offset", 0)
+            if jitter:
+                check_time = now - timedelta(minutes=jitter)
+
+            if cron_matches(task["cron"], check_time):
+                notification = (
+                    f"[Scheduled task {task['id']}]: {task['prompt']}"
+                )
+                self.queue.put(notification)
+                task["last_fired"] = time.time()
+                print(f"[Cron] Fired: {task['id']}")
+
+                if not task["recurring"]:
+                    fired_oneshots.append(task["id"])
+
+        # Clean up expired and one-shot tasks
+        if expired or fired_oneshots:
+            remove_ids = set(expired) | set(fired_oneshots)
+            self.tasks = [t for t in self.tasks if t["id"] not in remove_ids]
+            for tid in expired:
+                print(f"[Cron] Auto-expired: {tid} (older than {AUTO_EXPIRY_DAYS} days)")
+            for tid in fired_oneshots:
+                print(f"[Cron] One-shot completed and removed: {tid}")
+            self._save_durable()
+
+    def _load_durable(self):
+        """Load durable tasks from .claude/scheduled_tasks.json."""
+        if not SCHEDULED_TASKS_FILE.exists():
+            return
+        try:
+            data = json.loads(SCHEDULED_TASKS_FILE.read_text())
+            # Only load durable tasks
+            self.tasks = [t for t in data if t.get("durable")]
+        except Exception as e:
+            print(f"[Cron] Error loading tasks: {e}")
+
+    def detect_missed_tasks(self) -> list[dict]:
+        """
+        On startup, check each durable task's last_fired time.
+
+        If a task should have fired while the session was closed (i.e.
+        the gap between last_fired and now contains at least one cron match),
+        flag it as missed. The caller can then let the user decide whether
+        to run or discard each missed task.
+
+        """
+        now = datetime.now()
+        missed = []
+        for task in self.tasks:
+            last_fired = task.get("last_fired")
+            if last_fired is None:
+                continue
+            last_dt = datetime.fromtimestamp(last_fired)
+            # Walk forward minute-by-minute from last_fired to now (cap at 24h)
+            check = last_dt + timedelta(minutes=1)
+            cap = min(now, last_dt + timedelta(hours=24))
+            while check <= cap:
+                if cron_matches(task["cron"], check):
+                    missed.append({
+                        "id": task["id"],
+                        "cron": task["cron"],
+                        "prompt": task["prompt"],
+                        "missed_at": check.isoformat(),
+                    })
+                    break  # one miss is enough to flag it
+                check += timedelta(minutes=1)
+        return missed
+
+    def _save_durable(self):
+        """Save durable tasks to disk."""
+        durable = [t for t in self.tasks if t.get("durable")]
+        SCHEDULED_TASKS_FILE.parent.mkdir(parents=True, exist_ok=True)
+        SCHEDULED_TASKS_FILE.write_text(
+            json.dumps(durable, indent=2) + "\n"
+        )
+
+
+# Global scheduler
+scheduler = CronScheduler()
+
+
+# -- Tool implementations --
+def safe_path(p: str) -> Path:
+    path = (WORKDIR / p).resolve()
+    if not path.is_relative_to(WORKDIR):
+        raise ValueError(f"Path escapes workspace: {p}")
+    return path
+
+
+def run_bash(command: str) -> str:
+    dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
+    if any(d in command for d in dangerous):
+        return "Error: Dangerous command blocked"
+    try:
+        r = subprocess.run(command, shell=True, cwd=WORKDIR,
+                           capture_output=True, text=True, timeout=120)
+        out = (r.stdout + r.stderr).strip()
+        return out[:50000] if out else "(no output)"
+    except subprocess.TimeoutExpired:
+        return "Error: Timeout (120s)"
+
+
+def run_read(path: str, limit: int = None) -> str:
+    try:
+        lines = safe_path(path).read_text().splitlines()
+        if limit and limit < len(lines):
+            lines = lines[:limit] + [f"... ({len(lines) - limit} more)"]
+        return "\n".join(lines)[:50000]
+    except Exception as e:
+        return f"Error: {e}"
+
+
+def run_write(path: str, content: str) -> str:
+    try:
+        fp = safe_path(path)
+        fp.parent.mkdir(parents=True, exist_ok=True)
+        fp.write_text(content)
+        return f"Wrote {len(content)} bytes"
+    except Exception as e:
+        return f"Error: {e}"
+
+
+def run_edit(path: str, old_text: str, new_text: str) -> str:
+    try:
+        fp = safe_path(path)
+        content = fp.read_text()
+        if old_text not in content:
+            return f"Error: Text not found in {path}"
+        fp.write_text(content.replace(old_text, new_text, 1))
+        return f"Edited {path}"
+    except Exception as e:
+        return f"Error: {e}"
+
+
+TOOL_HANDLERS = {
+    "bash":        lambda **kw: run_bash(kw["command"]),
+    "read_file":   lambda **kw: run_read(kw["path"], kw.get("limit")),
+    "write_file":  lambda **kw: run_write(kw["path"], kw["content"]),
+    "edit_file":   lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
+    "cron_create": lambda **kw: scheduler.create(
+        kw["cron"], kw["prompt"], kw.get("recurring", True), kw.get("durable", False)),
+    "cron_delete": lambda **kw: scheduler.delete(kw["id"]),
+    "cron_list":   lambda **kw: scheduler.list_tasks(),
+}
+
+TOOLS = [
+    {"name": "bash", "description": "Run a shell command.",
+     "input_schema": {"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]}},
+    {"name": "read_file", "description": "Read file contents.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "limit": {"type": "integer"}}, "required": ["path"]}},
+    {"name": "write_file", "description": "Write content to file.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "content": {"type": "string"}}, "required": ["path", "content"]}},
+    {"name": "edit_file", "description": "Replace exact text in file.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "old_text": {"type": "string"}, "new_text": {"type": "string"}}, "required": ["path", "old_text", "new_text"]}},
+    {"name": "cron_create", "description": "Schedule a recurring or one-shot task with a cron expression.",
+     "input_schema": {"type": "object", "properties": {
+         "cron": {"type": "string", "description": "5-field cron expression: 'min hour dom month dow'"},
+         "prompt": {"type": "string", "description": "The prompt to inject when the task fires"},
+         "recurring": {"type": "boolean", "description": "true=repeat, false=fire once then delete. Default true."},
+         "durable": {"type": "boolean", "description": "true=persist to disk, false=session-only. Default false."},
+     }, "required": ["cron", "prompt"]}},
+    {"name": "cron_delete", "description": "Delete a scheduled task by ID.",
+     "input_schema": {"type": "object", "properties": {
+         "id": {"type": "string", "description": "Task ID to delete"},
+     }, "required": ["id"]}},
+    {"name": "cron_list", "description": "List all scheduled tasks.",
+     "input_schema": {"type": "object", "properties": {}}},
+]
+
+SYSTEM = f"You are a coding agent at {WORKDIR}. Use tools to solve tasks.\n\nYou can schedule future work with cron_create. Tasks fire automatically and their prompts are injected into the conversation."
+
+
+def agent_loop(messages: list):
+    """
+    Cron-aware agent loop.
+
+    Before each LLM call, drain the notification queue and inject any
+    fired task prompts as user messages. This is how the agent "wakes up"
+    to handle scheduled work.
+    """
+    while True:
+        # Drain scheduled task notifications
+        notifications = scheduler.drain_notifications()
+        for note in notifications:
+            print(f"[Cron notification] {note[:100]}")
+            messages.append({"role": "user", "content": note})
+
+        response = client.messages.create(
+            model=MODEL, system=SYSTEM, messages=messages,
+            tools=TOOLS, max_tokens=8000,
+        )
+        messages.append({"role": "assistant", "content": response.content})
+
+        if response.stop_reason != "tool_use":
+            return
+
+        results = []
+        for block in response.content:
+            if block.type != "tool_use":
+                continue
+            handler = TOOL_HANDLERS.get(block.name)
+            try:
+                output = handler(**(block.input or {})) if handler else f"Unknown: {block.name}"
+            except Exception as e:
+                output = f"Error: {e}"
+            print(f"> {block.name}: {str(output)[:200]}")
+            results.append({
+                "type": "tool_result",
+                "tool_use_id": block.id,
+                "content": str(output),
+            })
+
+        messages.append({"role": "user", "content": results})
+
+
+if __name__ == "__main__":
+    scheduler.start()
+    print("[Cron scheduler running. Background checks every second.]")
+    print("[Commands: /cron to list tasks, /test to fire a test notification]")
+
+    history = []
+    while True:
+        try:
+            query = input("\033[36ms14 >> \033[0m")
+        except (EOFError, KeyboardInterrupt):
+            scheduler.stop()
+            break
+        if query.strip().lower() in ("q", "exit", ""):
+            scheduler.stop()
+            break
+
+        if query.strip() == "/cron":
+            print(scheduler.list_tasks())
+            continue
+
+        if query.strip() == "/test":
+            # Manually enqueue a test notification for demonstration
+            scheduler.queue.put("[Scheduled task test-0000]: This is a test notification.")
+            print("[Test notification enqueued. It will be injected on your next message.]")
+            continue
+
+        history.append({"role": "user", "content": query})
+        agent_loop(history)
+        response_content = history[-1]["content"]
+        if isinstance(response_content, list):
+            for block in response_content:
+                if hasattr(block, "text"):
+                    print(block.text)
+        print()
diff --git a/agents/s09_agent_teams.py b/agents/s15_agent_teams.py
similarity index 94%
rename from agents/s09_agent_teams.py
rename to agents/s15_agent_teams.py
index 90f6760df..8ec640baa 100644
--- a/agents/s09_agent_teams.py
+++ b/agents/s15_agent_teams.py
@@ -1,13 +1,14 @@
 #!/usr/bin/env python3
 # Harness: team mailboxes -- multiple models, coordinated through files.
 """
-s09_agent_teams.py - Agent Teams
+s15_agent_teams.py - Agent Teams
 
 Persistent named agents with file-based JSONL inboxes. Each teammate runs
-its own agent loop in a separate thread. Communication via append-only inboxes.
+its own agent loop in a separate thread. Communication happens through
+append-only inbox files.
 
     Subagent (s04):  spawn -> execute -> return summary -> destroyed
-    Teammate (s09):  spawn -> work -> idle -> work -> ... -> shutdown
+    Teammate (s15):  spawn -> work -> idle -> work -> ... -> shutdown
 
     .team/config.json                   .team/inbox/
     +----------------------------+      +------------------+
@@ -31,16 +32,20 @@
     | status -> idle   |      |                  |
     +------------------+      +------------------+
 
-    5 message types (all declared, not all handled here):
-    +-------------------------+-----------------------------------+
-    | message                 | Normal text message               |
-    | broadcast               | Sent to all teammates             |
-    | shutdown_request        | Request graceful shutdown (s10)   |
-    | shutdown_response       | Approve/reject shutdown (s10)     |
-    | plan_approval_response  | Approve/reject plan (s10)         |
-    +-------------------------+-----------------------------------+
+Key idea: teammates have names, inboxes, and independent loops.
 
-Key insight: "Teammates that can talk to each other."
+Read this file in this order:
+1. MessageBus: how messages are queued and drained.
+2. TeammateManager: what persistent teammate state looks like.
+3. _teammate_loop / TOOL_HANDLERS: how each named teammate keeps re-entering the same tool loop.
+
+Most common confusion:
+- a teammate is not a one-shot subagent
+- an inbox message is not yet a full protocol request
+
+Teaching boundary:
+this file teaches persistent named workers plus mailboxes.
+Approval protocols and autonomous policies are added in later chapters.
 """
 
 import json
@@ -70,6 +75,7 @@
     "broadcast",
     "shutdown_request",
     "shutdown_response",
+    "plan_approval",
     "plan_approval_response",
 }
 
@@ -122,6 +128,8 @@ def broadcast(self, sender: str, content: str, teammates: list) -> str:
 
 # -- TeammateManager: persistent named agents with config.json --
 class TeammateManager:
+    """Persistent teammate registry plus worker-loop launcher."""
+
     def __init__(self, team_dir: Path):
         self.dir = team_dir
         self.dir.mkdir(exist_ok=True)
@@ -382,7 +390,7 @@ def agent_loop(messages: list):
     history = []
     while True:
         try:
-            query = input("\033[36ms09 >> \033[0m")
+            query = input("\033[36ms15 >> \033[0m")
         except (EOFError, KeyboardInterrupt):
             break
         if query.strip().lower() in ("q", "exit", ""):
diff --git a/agents/s10_team_protocols.py b/agents/s16_team_protocols.py
similarity index 83%
rename from agents/s10_team_protocols.py
rename to agents/s16_team_protocols.py
index d5475359c..384b086ce 100644
--- a/agents/s10_team_protocols.py
+++ b/agents/s16_team_protocols.py
@@ -1,10 +1,10 @@
 #!/usr/bin/env python3
 # Harness: protocols -- structured handshakes between models.
 """
-s10_team_protocols.py - Team Protocols
+s16_team_protocols.py - Team Protocols
 
 Shutdown protocol and plan approval protocol, both using the same
-request_id correlation pattern. Builds on s09's team messaging.
+request_id correlation pattern. Builds on s15's mailbox-based team messaging.
 
     Shutdown FSM: pending -> approved | rejected
 
@@ -37,14 +37,28 @@
                                      +---------------------+
                                              |
     +---------------------+          +-------v-------------+
-    | plan_approval_resp   | <------- | plan_approval       |
+    | plan_approval_response| <------ | plan_approval       |
     | {approve: true}      |          | review: {req_id,    |
     +---------------------+          |   approve: true}     |
                                      +---------------------+
 
-    Trackers: {request_id: {"target|from": name, "status": "pending|..."}}
+    Request store: .team/requests/{request_id}.json
 
-Key insight: "Same request_id correlation pattern, two domains."
+Key idea: one request/response shape can support multiple kinds of team workflow.
+Protocol requests are structured workflow objects, not normal free-form chat.
+
+Read this file in this order:
+1. MessageBus: how protocol envelopes still travel through the same inbox surface.
+2. Request files under .team/requests: how a request keeps durable status after the message is sent.
+3. Protocol handlers: how shutdown and plan approval reuse the same correlation pattern.
+
+Most common confusion:
+- a protocol request is not a normal teammate chat message
+- a request record is not a task record
+
+Teaching boundary:
+this file teaches durable handshakes first.
+Autonomous claiming, task selection, and worktree assignment stay in later chapters.
 """
 
 import json
@@ -67,6 +81,7 @@
 MODEL = os.environ["MODEL_ID"]
 TEAM_DIR = WORKDIR / ".team"
 INBOX_DIR = TEAM_DIR / "inbox"
+REQUESTS_DIR = TEAM_DIR / "requests"
 
 SYSTEM = f"You are a team lead at {WORKDIR}. Manage teammates with shutdown and plan approval protocols."
 
@@ -75,15 +90,10 @@
     "broadcast",
     "shutdown_request",
     "shutdown_response",
+    "plan_approval",
     "plan_approval_response",
 }
 
-# -- Request trackers: correlate by request_id --
-shutdown_requests = {}
-plan_requests = {}
-_tracker_lock = threading.Lock()
-
-
 # -- MessageBus: JSONL inbox per teammate --
 class MessageBus:
     def __init__(self, inbox_dir: Path):
@@ -130,6 +140,48 @@ def broadcast(self, sender: str, content: str, teammates: list) -> str:
 BUS = MessageBus(INBOX_DIR)
 
 
+class RequestStore:
+    """
+    Durable request records for protocol workflows.
+
+    Protocol state should survive long enough to inspect, resume, or reconcile.
+    This store keeps one JSON file per request_id under .team/requests/.
+    """
+
+    def __init__(self, base_dir: Path):
+        self.dir = base_dir
+        self.dir.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.Lock()
+
+    def _path(self, request_id: str) -> Path:
+        return self.dir / f"{request_id}.json"
+
+    def create(self, record: dict) -> dict:
+        request_id = record["request_id"]
+        with self._lock:
+            self._path(request_id).write_text(json.dumps(record, indent=2))
+        return record
+
+    def get(self, request_id: str) -> dict | None:
+        path = self._path(request_id)
+        if not path.exists():
+            return None
+        return json.loads(path.read_text())
+
+    def update(self, request_id: str, **changes) -> dict | None:
+        with self._lock:
+            record = self.get(request_id)
+            if not record:
+                return None
+            record.update(changes)
+            record["updated_at"] = time.time()
+            self._path(request_id).write_text(json.dumps(record, indent=2))
+        return record
+
+
+REQUEST_STORE = RequestStore(REQUESTS_DIR)
+
+
 # -- TeammateManager with shutdown + plan approval --
 class TeammateManager:
     def __init__(self, team_dir: Path):
@@ -236,9 +288,15 @@ def _exec(self, sender: str, tool_name: str, args: dict) -> str:
         if tool_name == "shutdown_response":
             req_id = args["request_id"]
             approve = args["approve"]
-            with _tracker_lock:
-                if req_id in shutdown_requests:
-                    shutdown_requests[req_id]["status"] = "approved" if approve else "rejected"
+            updated = REQUEST_STORE.update(
+                req_id,
+                status="approved" if approve else "rejected",
+                resolved_by=sender,
+                resolved_at=time.time(),
+                response={"approve": approve, "reason": args.get("reason", "")},
+            )
+            if not updated:
+                return f"Error: Unknown shutdown request {req_id}"
             BUS.send(
                 sender, "lead", args.get("reason", ""),
                 "shutdown_response", {"request_id": req_id, "approve": approve},
@@ -247,10 +305,18 @@ def _exec(self, sender: str, tool_name: str, args: dict) -> str:
         if tool_name == "plan_approval":
             plan_text = args.get("plan", "")
             req_id = str(uuid.uuid4())[:8]
-            with _tracker_lock:
-                plan_requests[req_id] = {"from": sender, "plan": plan_text, "status": "pending"}
+            REQUEST_STORE.create({
+                "request_id": req_id,
+                "kind": "plan_approval",
+                "from": sender,
+                "to": "lead",
+                "status": "pending",
+                "plan": plan_text,
+                "created_at": time.time(),
+                "updated_at": time.time(),
+            })
             BUS.send(
-                sender, "lead", plan_text, "plan_approval_response",
+                sender, "lead", plan_text, "plan_approval",
                 {"request_id": req_id, "plan": plan_text},
             )
             return f"Plan submitted (request_id={req_id}). Waiting for lead approval."
@@ -350,8 +416,15 @@ def _run_edit(path: str, old_text: str, new_text: str) -> str:
 # -- Lead-specific protocol handlers --
 def handle_shutdown_request(teammate: str) -> str:
     req_id = str(uuid.uuid4())[:8]
-    with _tracker_lock:
-        shutdown_requests[req_id] = {"target": teammate, "status": "pending"}
+    REQUEST_STORE.create({
+        "request_id": req_id,
+        "kind": "shutdown",
+        "from": "lead",
+        "to": teammate,
+        "status": "pending",
+        "created_at": time.time(),
+        "updated_at": time.time(),
+    })
     BUS.send(
         "lead", teammate, "Please shut down gracefully.",
         "shutdown_request", {"request_id": req_id},
@@ -360,22 +433,25 @@ def handle_shutdown_request(teammate: str) -> str:
 
 
 def handle_plan_review(request_id: str, approve: bool, feedback: str = "") -> str:
-    with _tracker_lock:
-        req = plan_requests.get(request_id)
+    req = REQUEST_STORE.get(request_id)
     if not req:
         return f"Error: Unknown plan request_id '{request_id}'"
-    with _tracker_lock:
-        req["status"] = "approved" if approve else "rejected"
+    REQUEST_STORE.update(
+        request_id,
+        status="approved" if approve else "rejected",
+        reviewed_by="lead",
+        resolved_at=time.time(),
+        feedback=feedback,
+    )
     BUS.send(
         "lead", req["from"], feedback, "plan_approval_response",
         {"request_id": request_id, "approve": approve, "feedback": feedback},
     )
-    return f"Plan {req['status']} for '{req['from']}'"
+    return f"Plan {'approved' if approve else 'rejected'} for '{req['from']}'"
 
 
 def _check_shutdown_status(request_id: str) -> str:
-    with _tracker_lock:
-        return json.dumps(shutdown_requests.get(request_id, {"error": "not found"}))
+    return json.dumps(REQUEST_STORE.get(request_id) or {"error": "not found"})
 
 
 # -- Lead tool dispatch (12 tools) --
@@ -463,7 +539,7 @@ def agent_loop(messages: list):
     history = []
     while True:
         try:
-            query = input("\033[36ms10 >> \033[0m")
+            query = input("\033[36ms16 >> \033[0m")
         except (EOFError, KeyboardInterrupt):
             break
         if query.strip().lower() in ("q", "exit", ""):
diff --git a/agents/s11_autonomous_agents.py b/agents/s17_autonomous_agents.py
similarity index 79%
rename from agents/s11_autonomous_agents.py
rename to agents/s17_autonomous_agents.py
index 3aec416b8..272bc336d 100644
--- a/agents/s11_autonomous_agents.py
+++ b/agents/s17_autonomous_agents.py
@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
 # Harness: autonomy -- models that find work without being told.
 """
-s11_autonomous_agents.py - Autonomous Agents
+s17_autonomous_agents.py - Autonomous Agents
 
 Idle cycle with task board polling, auto-claiming unclaimed tasks, and
-identity re-injection after context compression. Builds on s10's protocols.
+identity re-injection after context compression. Builds on task boards,
+team mailboxes, and protocol support from earlier chapters.
 
     Teammate lifecycle:
     +-------+
@@ -32,7 +33,10 @@
     messages = [identity_block, ...remaining...]
     "You are 'coder', role: backend, team: my-team"
 
-Key insight: "The agent finds work itself."
+Key idea: an idle teammate can safely claim ready work instead of waiting
+for every assignment from the lead.
+A teammate here is a long-lived worker, not a one-shot subagent that only
+returns a single summary.
 """
 
 import json
@@ -56,6 +60,8 @@
 TEAM_DIR = WORKDIR / ".team"
 INBOX_DIR = TEAM_DIR / "inbox"
 TASKS_DIR = WORKDIR / ".tasks"
+REQUESTS_DIR = TEAM_DIR / "requests"
+CLAIM_EVENTS_PATH = TASKS_DIR / "claim_events.jsonl"
 
 POLL_INTERVAL = 5
 IDLE_TIMEOUT = 60
@@ -67,13 +73,10 @@
     "broadcast",
     "shutdown_request",
     "shutdown_response",
+    "plan_approval",
     "plan_approval_response",
 }
 
-# -- Request trackers --
-shutdown_requests = {}
-plan_requests = {}
-_tracker_lock = threading.Lock()
 _claim_lock = threading.Lock()
 
 
@@ -123,37 +126,108 @@ def broadcast(self, sender: str, content: str, teammates: list) -> str:
 BUS = MessageBus(INBOX_DIR)
 
 
+class RequestStore:
+    """
+    Durable protocol request records.
+
+    s17 should not regress from s16 back to in-memory trackers. These request
+    files let autonomous teammates inspect or resume protocol state later.
+    """
+
+    def __init__(self, base_dir: Path):
+        self.dir = base_dir
+        self.dir.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.Lock()
+
+    def _path(self, request_id: str) -> Path:
+        return self.dir / f"{request_id}.json"
+
+    def create(self, record: dict) -> dict:
+        request_id = record["request_id"]
+        with self._lock:
+            self._path(request_id).write_text(json.dumps(record, indent=2))
+        return record
+
+    def get(self, request_id: str) -> dict | None:
+        path = self._path(request_id)
+        if not path.exists():
+            return None
+        return json.loads(path.read_text())
+
+    def update(self, request_id: str, **changes) -> dict | None:
+        with self._lock:
+            record = self.get(request_id)
+            if not record:
+                return None
+            record.update(changes)
+            record["updated_at"] = time.time()
+            self._path(request_id).write_text(json.dumps(record, indent=2))
+        return record
+
+
+REQUEST_STORE = RequestStore(REQUESTS_DIR)
+
+
 # -- Task board scanning --
-def scan_unclaimed_tasks() -> list:
+def _append_claim_event(payload: dict):
+    TASKS_DIR.mkdir(parents=True, exist_ok=True)
+    with CLAIM_EVENTS_PATH.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(payload) + "\n")
+
+
+def _task_allows_role(task: dict, role: str | None) -> bool:
+    required_role = task.get("claim_role") or task.get("required_role") or ""
+    if not required_role:
+        return True
+    return bool(role) and role == required_role
+
+
+def is_claimable_task(task: dict, role: str | None = None) -> bool:
+    return (
+        task.get("status") == "pending"
+        and not task.get("owner")
+        and not task.get("blockedBy")
+        and _task_allows_role(task, role)
+    )
+
+
+def scan_unclaimed_tasks(role: str | None = None) -> list:
     TASKS_DIR.mkdir(exist_ok=True)
     unclaimed = []
     for f in sorted(TASKS_DIR.glob("task_*.json")):
         task = json.loads(f.read_text())
-        if (task.get("status") == "pending"
-                and not task.get("owner")
-                and not task.get("blockedBy")):
+        if is_claimable_task(task, role):
             unclaimed.append(task)
     return unclaimed
 
 
-def claim_task(task_id: int, owner: str) -> str:
+def claim_task(
+    task_id: int,
+    owner: str,
+    role: str | None = None,
+    source: str = "manual",
+) -> str:
     with _claim_lock:
         path = TASKS_DIR / f"task_{task_id}.json"
         if not path.exists():
             return f"Error: Task {task_id} not found"
         task = json.loads(path.read_text())
-        if task.get("owner"):
-            existing_owner = task.get("owner") or "someone else"
-            return f"Error: Task {task_id} has already been claimed by {existing_owner}"
-        if task.get("status") != "pending":
-            status = task.get("status")
-            return f"Error: Task {task_id} cannot be claimed because its status is '{status}'"
-        if task.get("blockedBy"):
-            return f"Error: Task {task_id} is blocked by other task(s) and cannot be claimed yet"
+        if not is_claimable_task(task, role):
+            return f"Error: Task {task_id} is not claimable for role={role or '(any)'}"
         task["owner"] = owner
         task["status"] = "in_progress"
+        task["claimed_at"] = time.time()
+        task["claim_source"] = source
         path.write_text(json.dumps(task, indent=2))
-    return f"Claimed task #{task_id} for {owner}"
+    _append_claim_event({
+        "event": "task.claimed",
+        "task_id": task_id,
+        "owner": owner,
+        "role": role,
+        "source": source,
+        "ts": time.time(),
+    })
+    return f"Claimed task #{task_id} for {owner} via {source}"
 
 
 # -- Identity re-injection after compression --
@@ -164,6 +238,13 @@ def make_identity_block(name: str, role: str, team_name: str) -> dict:
     }
 
 
+def ensure_identity_context(messages: list, name: str, role: str, team_name: str):
+    if messages and "<identity>" in str(messages[0].get("content", "")):
+        return
+    messages.insert(0, make_identity_block(name, role, team_name))
+    messages.insert(1, {"role": "assistant", "content": f"I am {name}. Continuing."})
+
+
 # -- Autonomous TeammateManager --
 class TeammateManager:
     def __init__(self, team_dir: Path):
@@ -272,6 +353,7 @@ def _loop(self, name: str, role: str, prompt: str):
                 time.sleep(POLL_INTERVAL)
                 inbox = BUS.read_inbox(name)
                 if inbox:
+                    ensure_identity_context(messages, name, role, team_name)
                     for msg in inbox:
                         if msg.get("type") == "shutdown_request":
                             self._set_status(name, "shutdown")
@@ -279,21 +361,21 @@ def _loop(self, name: str, role: str, prompt: str):
                         messages.append({"role": "user", "content": json.dumps(msg)})
                     resume = True
                     break
-                unclaimed = scan_unclaimed_tasks()
+                unclaimed = scan_unclaimed_tasks(role)
                 if unclaimed:
                     task = unclaimed[0]
-                    result = claim_task(task["id"], name)
-                    if result.startswith("Error:"):
+                    claim_result = claim_task(
+                        task["id"], name, role=role, source="auto"
+                    )
+                    if claim_result.startswith("Error:"):
                         continue
                     task_prompt = (
                         f"<auto-claimed>Task #{task['id']}: {task['subject']}\n"
                         f"{task.get('description', '')}</auto-claimed>"
                     )
-                    if len(messages) <= 3:
-                        messages.insert(0, make_identity_block(name, role, team_name))
-                        messages.insert(1, {"role": "assistant", "content": f"I am {name}. Continuing."})
+                    ensure_identity_context(messages, name, role, team_name)
                     messages.append({"role": "user", "content": task_prompt})
-                    messages.append({"role": "assistant", "content": f"Claimed task #{task['id']}. Working on it."})
+                    messages.append({"role": "assistant", "content": f"{claim_result}. Working on it."})
                     resume = True
                     break
 
@@ -318,9 +400,15 @@ def _exec(self, sender: str, tool_name: str, args: dict) -> str:
             return json.dumps(BUS.read_inbox(sender), indent=2)
         if tool_name == "shutdown_response":
             req_id = args["request_id"]
-            with _tracker_lock:
-                if req_id in shutdown_requests:
-                    shutdown_requests[req_id]["status"] = "approved" if args["approve"] else "rejected"
+            updated = REQUEST_STORE.update(
+                req_id,
+                status="approved" if args["approve"] else "rejected",
+                resolved_by=sender,
+                resolved_at=time.time(),
+                response={"approve": args["approve"], "reason": args.get("reason", "")},
+            )
+            if not updated:
+                return f"Error: Unknown shutdown request {req_id}"
             BUS.send(
                 sender, "lead", args.get("reason", ""),
                 "shutdown_response", {"request_id": req_id, "approve": args["approve"]},
@@ -329,15 +417,28 @@ def _exec(self, sender: str, tool_name: str, args: dict) -> str:
         if tool_name == "plan_approval":
             plan_text = args.get("plan", "")
             req_id = str(uuid.uuid4())[:8]
-            with _tracker_lock:
-                plan_requests[req_id] = {"from": sender, "plan": plan_text, "status": "pending"}
+            REQUEST_STORE.create({
+                "request_id": req_id,
+                "kind": "plan_approval",
+                "from": sender,
+                "to": "lead",
+                "status": "pending",
+                "plan": plan_text,
+                "created_at": time.time(),
+                "updated_at": time.time(),
+            })
             BUS.send(
-                sender, "lead", plan_text, "plan_approval_response",
+                sender, "lead", plan_text, "plan_approval",
                 {"request_id": req_id, "plan": plan_text},
             )
             return f"Plan submitted (request_id={req_id}). Waiting for approval."
         if tool_name == "claim_task":
-            return claim_task(args["task_id"], sender)
+            return claim_task(
+                args["task_id"],
+                sender,
+                role=self._find_member(sender).get("role") if self._find_member(sender) else None,
+                source="manual",
+            )
         return f"Unknown tool: {tool_name}"
 
     def _teammate_tools(self) -> list:
@@ -438,8 +539,15 @@ def _run_edit(path: str, old_text: str, new_text: str) -> str:
 # -- Lead-specific protocol handlers --
 def handle_shutdown_request(teammate: str) -> str:
     req_id = str(uuid.uuid4())[:8]
-    with _tracker_lock:
-        shutdown_requests[req_id] = {"target": teammate, "status": "pending"}
+    REQUEST_STORE.create({
+        "request_id": req_id,
+        "kind": "shutdown",
+        "from": "lead",
+        "to": teammate,
+        "status": "pending",
+        "created_at": time.time(),
+        "updated_at": time.time(),
+    })
     BUS.send(
         "lead", teammate, "Please shut down gracefully.",
         "shutdown_request", {"request_id": req_id},
@@ -448,22 +556,25 @@ def handle_shutdown_request(teammate: str) -> str:
 
 
 def handle_plan_review(request_id: str, approve: bool, feedback: str = "") -> str:
-    with _tracker_lock:
-        req = plan_requests.get(request_id)
+    req = REQUEST_STORE.get(request_id)
     if not req:
         return f"Error: Unknown plan request_id '{request_id}'"
-    with _tracker_lock:
-        req["status"] = "approved" if approve else "rejected"
+    REQUEST_STORE.update(
+        request_id,
+        status="approved" if approve else "rejected",
+        reviewed_by="lead",
+        resolved_at=time.time(),
+        feedback=feedback,
+    )
     BUS.send(
         "lead", req["from"], feedback, "plan_approval_response",
         {"request_id": request_id, "approve": approve, "feedback": feedback},
     )
-    return f"Plan {req['status']} for '{req['from']}'"
+    return f"Plan {'approved' if approve else 'rejected'} for '{req['from']}'"
 
 
 def _check_shutdown_status(request_id: str) -> str:
-    with _tracker_lock:
-        return json.dumps(shutdown_requests.get(request_id, {"error": "not found"}))
+    return json.dumps(REQUEST_STORE.get(request_id) or {"error": "not found"})
 
 
 # -- Lead tool dispatch (14 tools) --
@@ -525,6 +636,10 @@ def agent_loop(messages: list):
                 "role": "user",
                 "content": f"<inbox>{json.dumps(inbox, indent=2)}</inbox>",
             })
+            messages.append({
+                "role": "assistant",
+                "content": "Noted inbox messages.",
+            })
         response = client.messages.create(
             model=MODEL,
             system=SYSTEM,
@@ -543,8 +658,7 @@ def agent_loop(messages: list):
                     output = handler(**block.input) if handler else f"Unknown tool: {block.name}"
                 except Exception as e:
                     output = f"Error: {e}"
-                print(f"> {block.name}:")
-                print(str(output)[:200])
+                print(f"> {block.name}: {str(output)[:200]}")
                 results.append({
                     "type": "tool_result",
                     "tool_use_id": block.id,
@@ -557,7 +671,7 @@ def agent_loop(messages: list):
     history = []
     while True:
         try:
-            query = input("\033[36ms11 >> \033[0m")
+            query = input("\033[36ms17 >> \033[0m")
         except (EOFError, KeyboardInterrupt):
             break
         if query.strip().lower() in ("q", "exit", ""):
diff --git a/agents/s12_worktree_task_isolation.py b/agents/s18_worktree_task_isolation.py
similarity index 51%
rename from agents/s12_worktree_task_isolation.py
rename to agents/s18_worktree_task_isolation.py
index 09f905253..deac23bf7 100644
--- a/agents/s12_worktree_task_isolation.py
+++ b/agents/s18_worktree_task_isolation.py
@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 # Harness: directory isolation -- parallel execution lanes that never collide.
 """
-s12_worktree_task_isolation.py - Worktree + Task Isolation
+s18_worktree_task_isolation.py - Worktree + Task Isolation
 
 Directory-level isolation for parallel task execution.
 Tasks are the control plane and worktrees are the execution plane.
@@ -28,6 +28,19 @@
       }
 
 Key insight: "Isolate by directory, coordinate by task ID."
+
+Read this file in this order:
+1. EventBus: how worktree lifecycle stays observable.
+2. TaskManager: how a task binds to an execution lane without becoming the lane itself.
+3. Worktree registry / closeout helpers: how directory state is created, tracked, and cleaned up.
+
+Most common confusion:
+- a worktree is not the task itself
+- a worktree record is not just a path string
+
+Teaching boundary:
+this file teaches isolated execution lanes first.
+Cross-machine execution, merge automation, and enterprise policy glue are intentionally out of scope.
 """
 
 import json
@@ -51,19 +64,13 @@
 
 
 def detect_repo_root(cwd: Path) -> Path | None:
-    """Return git repo root if cwd is inside a repo, else None."""
     try:
         r = subprocess.run(
             ["git", "rev-parse", "--show-toplevel"],
-            cwd=cwd,
-            capture_output=True,
-            text=True,
-            timeout=10,
+            cwd=cwd, capture_output=True, text=True, timeout=10,
         )
-        if r.returncode != 0:
-            return None
         root = Path(r.stdout.strip())
-        return root if root.exists() else None
+        return root if r.returncode == 0 and root.exists() else None
     except Exception:
         return None
 
@@ -74,8 +81,7 @@ def detect_repo_root(cwd: Path) -> Path | None:
     f"You are a coding agent at {WORKDIR}. "
     "Use task + worktree tools for multi-task work. "
     "For parallel or risky changes: create tasks, allocate worktree lanes, "
-    "run commands in those lanes, then choose keep/remove for closeout. "
-    "Use worktree_events when you need lifecycle visibility."
+    "run commands in those lanes, then choose keep/remove for closeout."
 )
 
 
@@ -87,30 +93,23 @@ def __init__(self, event_log_path: Path):
         if not self.path.exists():
             self.path.write_text("")
 
-    def emit(
-        self,
-        event: str,
-        task: dict | None = None,
-        worktree: dict | None = None,
-        error: str | None = None,
-    ):
-        payload = {
-            "event": event,
-            "ts": time.time(),
-            "task": task or {},
-            "worktree": worktree or {},
-        }
+    def emit(self, event: str, task_id=None, wt_name=None, error=None, **extra):
+        payload = {"event": event, "ts": time.time()}
+        if task_id is not None:
+            payload["task_id"] = task_id
+        if wt_name:
+            payload["worktree"] = wt_name
         if error:
             payload["error"] = error
+        payload.update(extra)
         with self.path.open("a", encoding="utf-8") as f:
             f.write(json.dumps(payload) + "\n")
 
     def list_recent(self, limit: int = 20) -> str:
         n = max(1, min(int(limit or 20), 200))
         lines = self.path.read_text(encoding="utf-8").splitlines()
-        recent = lines[-n:]
         items = []
-        for line in recent:
+        for line in lines[-n:]:
             try:
                 items.append(json.loads(line))
             except Exception:
@@ -148,15 +147,11 @@ def _save(self, task: dict):
 
     def create(self, subject: str, description: str = "") -> str:
         task = {
-            "id": self._next_id,
-            "subject": subject,
-            "description": description,
-            "status": "pending",
-            "owner": "",
-            "worktree": "",
-            "blockedBy": [],
-            "created_at": time.time(),
-            "updated_at": time.time(),
+            "id": self._next_id, "subject": subject, "description": description,
+            "status": "pending", "owner": "", "worktree": "",
+            "worktree_state": "unbound", "last_worktree": "",
+            "closeout": None, "blockedBy": [],
+            "created_at": time.time(), "updated_at": time.time(),
         }
         self._save(task)
         self._next_id += 1
@@ -171,7 +166,7 @@ def exists(self, task_id: int) -> bool:
     def update(self, task_id: int, status: str = None, owner: str = None) -> str:
         task = self._load(task_id)
         if status:
-            if status not in ("pending", "in_progress", "completed"):
+            if status not in ("pending", "in_progress", "completed", "deleted"):
                 raise ValueError(f"Invalid status: {status}")
             task["status"] = status
         if owner is not None:
@@ -183,6 +178,8 @@ def update(self, task_id: int, status: str = None, owner: str = None) -> str:
     def bind_worktree(self, task_id: int, worktree: str, owner: str = "") -> str:
         task = self._load(task_id)
         task["worktree"] = worktree
+        task["last_worktree"] = worktree
+        task["worktree_state"] = "active"
         if owner:
             task["owner"] = owner
         if task["status"] == "pending":
@@ -194,6 +191,21 @@ def bind_worktree(self, task_id: int, worktree: str, owner: str = "") -> str:
     def unbind_worktree(self, task_id: int) -> str:
         task = self._load(task_id)
         task["worktree"] = ""
+        task["worktree_state"] = "unbound"
+        task["updated_at"] = time.time()
+        self._save(task)
+        return json.dumps(task, indent=2)
+
+    def record_closeout(self, task_id: int, action: str, reason: str = "", keep_binding: bool = False) -> str:
+        task = self._load(task_id)
+        task["closeout"] = {
+            "action": action,
+            "reason": reason,
+            "at": time.time(),
+        }
+        task["worktree_state"] = action
+        if not keep_binding:
+            task["worktree"] = ""
         task["updated_at"] = time.time()
         self._save(task)
         return json.dumps(task, indent=2)
@@ -206,11 +218,7 @@ def list_all(self) -> str:
             return "No tasks."
         lines = []
         for t in tasks:
-            marker = {
-                "pending": "[ ]",
-                "in_progress": "[>]",
-                "completed": "[x]",
-            }.get(t["status"], "[?]")
+            marker = {"pending": "[ ]", "in_progress": "[>]", "completed": "[x]", "deleted": "[-]"}.get(t["status"], "[?]")
             owner = f" owner={t['owner']}" if t.get("owner") else ""
             wt = f" wt={t['worktree']}" if t.get("worktree") else ""
             lines.append(f"{marker} #{t['id']}: {t['subject']}{owner}{wt}")
@@ -221,7 +229,7 @@ def list_all(self) -> str:
 EVENTS = EventBus(REPO_ROOT / ".worktrees" / "events.jsonl")
 
 
-# -- WorktreeManager: create/list/run/remove git worktrees + lifecycle index --
+# -- WorktreeManager: create/list/run/remove git worktrees --
 class WorktreeManager:
     def __init__(self, repo_root: Path, tasks: TaskManager, events: EventBus):
         self.repo_root = repo_root
@@ -232,16 +240,13 @@ def __init__(self, repo_root: Path, tasks: TaskManager, events: EventBus):
         self.index_path = self.dir / "index.json"
         if not self.index_path.exists():
             self.index_path.write_text(json.dumps({"worktrees": []}, indent=2))
-        self.git_available = self._is_git_repo()
+        self.git_available = self._check_git()
 
-    def _is_git_repo(self) -> bool:
+    def _check_git(self) -> bool:
         try:
             r = subprocess.run(
                 ["git", "rev-parse", "--is-inside-work-tree"],
-                cwd=self.repo_root,
-                capture_output=True,
-                text=True,
-                timeout=10,
+                cwd=self.repo_root, capture_output=True, text=True, timeout=10,
             )
             return r.returncode == 0
         except Exception:
@@ -249,17 +254,13 @@ def _is_git_repo(self) -> bool:
 
     def _run_git(self, args: list[str]) -> str:
         if not self.git_available:
-            raise RuntimeError("Not in a git repository. worktree tools require git.")
+            raise RuntimeError("Not in a git repository.")
         r = subprocess.run(
-            ["git", *args],
-            cwd=self.repo_root,
-            capture_output=True,
-            text=True,
-            timeout=120,
+            ["git", *args], cwd=self.repo_root,
+            capture_output=True, text=True, timeout=120,
         )
         if r.returncode != 0:
-            msg = (r.stdout + r.stderr).strip()
-            raise RuntimeError(msg or f"git {' '.join(args)} failed")
+            raise RuntimeError((r.stdout + r.stderr).strip() or f"git {' '.join(args)} failed")
         return (r.stdout + r.stderr).strip() or "(no output)"
 
     def _load_index(self) -> dict:
@@ -269,83 +270,63 @@ def _save_index(self, data: dict):
         self.index_path.write_text(json.dumps(data, indent=2))
 
     def _find(self, name: str) -> dict | None:
-        idx = self._load_index()
-        for wt in idx.get("worktrees", []):
+        for wt in self._load_index().get("worktrees", []):
             if wt.get("name") == name:
                 return wt
         return None
 
+    def _update_entry(self, name: str, **changes) -> dict:
+        idx = self._load_index()
+        updated = None
+        for item in idx.get("worktrees", []):
+            if item.get("name") == name:
+                item.update(changes)
+                updated = item
+                break
+        self._save_index(idx)
+        if not updated:
+            raise ValueError(f"Worktree '{name}' not found in index")
+        return updated
+
     def _validate_name(self, name: str):
         if not re.fullmatch(r"[A-Za-z0-9._-]{1,40}", name or ""):
-            raise ValueError(
-                "Invalid worktree name. Use 1-40 chars: letters, numbers, ., _, -"
-            )
+            raise ValueError("Invalid worktree name. Use 1-40 chars: letters, digits, ., _, -")
 
     def create(self, name: str, task_id: int = None, base_ref: str = "HEAD") -> str:
         self._validate_name(name)
         if self._find(name):
-            raise ValueError(f"Worktree '{name}' already exists in index")
+            raise ValueError(f"Worktree '{name}' already exists")
         if task_id is not None and not self.tasks.exists(task_id):
             raise ValueError(f"Task {task_id} not found")
 
         path = self.dir / name
         branch = f"wt/{name}"
-        self.events.emit(
-            "worktree.create.before",
-            task={"id": task_id} if task_id is not None else {},
-            worktree={"name": name, "base_ref": base_ref},
-        )
+        self.events.emit("worktree.create.before", task_id=task_id, wt_name=name)
         try:
             self._run_git(["worktree", "add", "-b", branch, str(path), base_ref])
-
             entry = {
-                "name": name,
-                "path": str(path),
-                "branch": branch,
-                "task_id": task_id,
-                "status": "active",
-                "created_at": time.time(),
+                "name": name, "path": str(path), "branch": branch,
+                "task_id": task_id, "status": "active", "created_at": time.time(),
             }
-
             idx = self._load_index()
             idx["worktrees"].append(entry)
             self._save_index(idx)
-
             if task_id is not None:
                 self.tasks.bind_worktree(task_id, name)
-
-            self.events.emit(
-                "worktree.create.after",
-                task={"id": task_id} if task_id is not None else {},
-                worktree={
-                    "name": name,
-                    "path": str(path),
-                    "branch": branch,
-                    "status": "active",
-                },
-            )
+            self.events.emit("worktree.create.after", task_id=task_id, wt_name=name)
             return json.dumps(entry, indent=2)
         except Exception as e:
-            self.events.emit(
-                "worktree.create.failed",
-                task={"id": task_id} if task_id is not None else {},
-                worktree={"name": name, "base_ref": base_ref},
-                error=str(e),
-            )
+            self.events.emit("worktree.create.failed", task_id=task_id, wt_name=name, error=str(e))
             raise
 
     def list_all(self) -> str:
-        idx = self._load_index()
-        wts = idx.get("worktrees", [])
+        wts = self._load_index().get("worktrees", [])
         if not wts:
             return "No worktrees in index."
         lines = []
         for wt in wts:
             suffix = f" task={wt['task_id']}" if wt.get("task_id") else ""
-            lines.append(
-                f"[{wt.get('status', 'unknown')}] {wt['name']} -> "
-                f"{wt['path']} ({wt.get('branch', '-')}){suffix}"
-            )
+            lines.append(f"[{wt.get('status', '?')}] {wt['name']} -> {wt['path']} ({wt.get('branch', '-')}){suffix}")
         return "\n".join(lines)
 
     def status(self, name: str) -> str:
@@ -357,150 +338,162 @@ def status(self, name: str) -> str:
             return f"Error: Worktree path missing: {path}"
         r = subprocess.run(
             ["git", "status", "--short", "--branch"],
-            cwd=path,
-            capture_output=True,
-            text=True,
-            timeout=60,
+            cwd=path, capture_output=True, text=True, timeout=60,
         )
-        text = (r.stdout + r.stderr).strip()
-        return text or "Clean worktree"
+        return (r.stdout + r.stderr).strip() or "Clean worktree"
+
+    def enter(self, name: str) -> str:
+        wt = self._find(name)
+        if not wt:
+            return f"Error: Unknown worktree '{name}'"
+        path = Path(wt["path"])
+        if not path.exists():
+            return f"Error: Worktree path missing: {path}"
+        updated = self._update_entry(name, last_entered_at=time.time())
+        self.events.emit("worktree.enter", task_id=wt.get("task_id"), wt_name=name, path=str(path))
+        return json.dumps(updated, indent=2)
 
     def run(self, name: str, command: str) -> str:
         dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
         if any(d in command for d in dangerous):
             return "Error: Dangerous command blocked"
-
         wt = self._find(name)
         if not wt:
             return f"Error: Unknown worktree '{name}'"
         path = Path(wt["path"])
         if not path.exists():
             return f"Error: Worktree path missing: {path}"
-
         try:
-            r = subprocess.run(
-                command,
-                shell=True,
-                cwd=path,
-                capture_output=True,
-                text=True,
-                timeout=300,
+            self._update_entry(
+                name,
+                last_entered_at=time.time(),
+                last_command_at=time.time(),
+                last_command_preview=command[:120],
             )
+            self.events.emit("worktree.run.before", task_id=wt.get("task_id"), wt_name=name, command=command[:120])
+            r = subprocess.run(command, shell=True, cwd=path,
+                               capture_output=True, text=True, timeout=300)
             out = (r.stdout + r.stderr).strip()
+            self.events.emit("worktree.run.after", task_id=wt.get("task_id"), wt_name=name)
             return out[:50000] if out else "(no output)"
         except subprocess.TimeoutExpired:
+            self.events.emit("worktree.run.timeout", task_id=wt.get("task_id"), wt_name=name)
             return "Error: Timeout (300s)"
 
-    def remove(self, name: str, force: bool = False, complete_task: bool = False) -> str:
+    def remove(
+        self,
+        name: str,
+        force: bool = False,
+        complete_task: bool = False,
+        reason: str = "",
+    ) -> str:
         wt = self._find(name)
         if not wt:
             return f"Error: Unknown worktree '{name}'"
-
-        self.events.emit(
-            "worktree.remove.before",
-            task={"id": wt.get("task_id")} if wt.get("task_id") is not None else {},
-            worktree={"name": name, "path": wt.get("path")},
-        )
+        task_id = wt.get("task_id")
+        self.events.emit("worktree.remove.before", task_id=task_id, wt_name=name)
         try:
             args = ["worktree", "remove"]
             if force:
                 args.append("--force")
             args.append(wt["path"])
             self._run_git(args)
-
-            if complete_task and wt.get("task_id") is not None:
-                task_id = wt["task_id"]
-                before = json.loads(self.tasks.get(task_id))
+            if complete_task and task_id is not None:
                 self.tasks.update(task_id, status="completed")
-                self.tasks.unbind_worktree(task_id)
-                self.events.emit(
-                    "task.completed",
-                    task={
-                        "id": task_id,
-                        "subject": before.get("subject", ""),
-                        "status": "completed",
-                    },
-                    worktree={"name": name},
-                )
-
-            idx = self._load_index()
-            for item in idx.get("worktrees", []):
-                if item.get("name") == name:
-                    item["status"] = "removed"
-                    item["removed_at"] = time.time()
-            self._save_index(idx)
-
-            self.events.emit(
-                "worktree.remove.after",
-                task={"id": wt.get("task_id")} if wt.get("task_id") is not None else {},
-                worktree={"name": name, "path": wt.get("path"), "status": "removed"},
+                self.events.emit("task.completed", task_id=task_id, wt_name=name)
+            if task_id is not None:
+                self.tasks.record_closeout(task_id, "removed", reason, keep_binding=False)
+            self._update_entry(
+                name,
+                status="removed",
+                removed_at=time.time(),
+                closeout={"action": "remove", "reason": reason, "at": time.time()},
             )
+            self.events.emit("worktree.remove.after", task_id=task_id, wt_name=name)
             return f"Removed worktree '{name}'"
         except Exception as e:
-            self.events.emit(
-                "worktree.remove.failed",
-                task={"id": wt.get("task_id")} if wt.get("task_id") is not None else {},
-                worktree={"name": name, "path": wt.get("path")},
-                error=str(e),
-            )
+            self.events.emit("worktree.remove.failed", task_id=task_id, wt_name=name, error=str(e))
             raise
 
     def keep(self, name: str) -> str:
         wt = self._find(name)
         if not wt:
             return f"Error: Unknown worktree '{name}'"
-
-        idx = self._load_index()
-        kept = None
-        for item in idx.get("worktrees", []):
-            if item.get("name") == name:
-                item["status"] = "kept"
-                item["kept_at"] = time.time()
-                kept = item
-        self._save_index(idx)
-
-        self.events.emit(
-            "worktree.keep",
-            task={"id": wt.get("task_id")} if wt.get("task_id") is not None else {},
-            worktree={
-                "name": name,
-                "path": wt.get("path"),
-                "status": "kept",
-            },
+        if wt.get("task_id") is not None:
+            self.tasks.record_closeout(wt["task_id"], "kept", "", keep_binding=True)
+        self._update_entry(
+            name,
+            status="kept",
+            kept_at=time.time(),
+            closeout={"action": "keep", "reason": "", "at": time.time()},
         )
-        return json.dumps(kept, indent=2) if kept else f"Error: Unknown worktree '{name}'"
+        self.events.emit("worktree.keep", task_id=wt.get("task_id"), wt_name=name)
+        return json.dumps(self._find(name), indent=2)
+
+    def closeout(
+        self,
+        name: str,
+        action: str,
+        reason: str = "",
+        force: bool = False,
+        complete_task: bool = False,
+    ) -> str:
+        if action == "keep":
+            wt = self._find(name)
+            if not wt:
+                return f"Error: Unknown worktree '{name}'"
+            if wt.get("task_id") is not None:
+                self.tasks.record_closeout(
+                    wt["task_id"], "kept", reason, keep_binding=True
+                )
+                if complete_task:
+                    self.tasks.update(wt["task_id"], status="completed")
+            self._update_entry(
+                name,
+                status="kept",
+                kept_at=time.time(),
+                closeout={"action": "keep", "reason": reason, "at": time.time()},
+            )
+            self.events.emit(
+                "worktree.closeout.keep",
+                task_id=wt.get("task_id"),
+                wt_name=name,
+                reason=reason,
+            )
+            return json.dumps(self._find(name), indent=2)
+        if action == "remove":
+            self.events.emit("worktree.closeout.remove", wt_name=name, reason=reason)
+            return self.remove(
+                name,
+                force=force,
+                complete_task=complete_task,
+                reason=reason,
+            )
+        raise ValueError("action must be 'keep' or 'remove'")
 
 
 WORKTREES = WorktreeManager(REPO_ROOT, TASKS, EVENTS)
 
 
-# -- Base tools (kept minimal, same style as previous sessions) --
+# -- Base tools (same as previous sessions, kept minimal) --
 def safe_path(p: str) -> Path:
     path = (WORKDIR / p).resolve()
     if not path.is_relative_to(WORKDIR):
         raise ValueError(f"Path escapes workspace: {p}")
     return path
 
-
 def run_bash(command: str) -> str:
     dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
     if any(d in command for d in dangerous):
         return "Error: Dangerous command blocked"
     try:
-        r = subprocess.run(
-            command,
-            shell=True,
-            cwd=WORKDIR,
-            capture_output=True,
-            text=True,
-            timeout=120,
-        )
+        r = subprocess.run(command, shell=True, cwd=WORKDIR,
+                           capture_output=True, text=True, timeout=120)
         out = (r.stdout + r.stderr).strip()
         return out[:50000] if out else "(no output)"
     except subprocess.TimeoutExpired:
         return "Error: Timeout (120s)"
 
-
 def run_read(path: str, limit: int = None) -> str:
     try:
         lines = safe_path(path).read_text().splitlines()
@@ -510,7 +503,6 @@ def run_read(path: str, limit: int = None) -> str:
     except Exception as e:
         return f"Error: {e}"
 
-
 def run_write(path: str, content: str) -> str:
     try:
         fp = safe_path(path)
@@ -520,7 +512,6 @@ def run_write(path: str, content: str) -> str:
     except Exception as e:
         return f"Error: {e}"
 
-
 def run_edit(path: str, old_text: str, new_text: str) -> str:
     try:
         fp = safe_path(path)
@@ -545,200 +536,76 @@ def run_edit(path: str, old_text: str, new_text: str) -> str:
     "task_bind_worktree": lambda **kw: TASKS.bind_worktree(kw["task_id"], kw["worktree"], kw.get("owner", "")),
     "worktree_create": lambda **kw: WORKTREES.create(kw["name"], kw.get("task_id"), kw.get("base_ref", "HEAD")),
     "worktree_list": lambda **kw: WORKTREES.list_all(),
+    "worktree_enter": lambda **kw: WORKTREES.enter(kw["name"]),
     "worktree_status": lambda **kw: WORKTREES.status(kw["name"]),
     "worktree_run": lambda **kw: WORKTREES.run(kw["name"], kw["command"]),
+    "worktree_closeout": lambda **kw: WORKTREES.closeout(
+        kw["name"],
+        kw["action"],
+        kw.get("reason", ""),
+        kw.get("force", False),
+        kw.get("complete_task", False),
+    ),
     "worktree_keep": lambda **kw: WORKTREES.keep(kw["name"]),
-    "worktree_remove": lambda **kw: WORKTREES.remove(kw["name"], kw.get("force", False), kw.get("complete_task", False)),
+    "worktree_remove": lambda **kw: WORKTREES.remove(
+        kw["name"],
+        kw.get("force", False),
+        kw.get("complete_task", False),
+        kw.get("reason", ""),
+    ),
     "worktree_events": lambda **kw: EVENTS.list_recent(kw.get("limit", 20)),
 }
 
+# Compact tool definitions -- same schema, less vertical space
 TOOLS = [
-    {
-        "name": "bash",
-        "description": "Run a shell command in the current workspace (blocking).",
-        "input_schema": {
-            "type": "object",
-            "properties": {"command": {"type": "string"}},
-            "required": ["command"],
-        },
-    },
-    {
-        "name": "read_file",
-        "description": "Read file contents.",
-        "input_schema": {
-            "type": "object",
-            "properties": {
-                "path": {"type": "string"},
-                "limit": {"type": "integer"},
-            },
-            "required": ["path"],
-        },
-    },
-    {
-        "name": "write_file",
-        "description": "Write content to file.",
-        "input_schema": {
-            "type": "object",
-            "properties": {
-                "path": {"type": "string"},
-                "content": {"type": "string"},
-            },
-            "required": ["path", "content"],
-        },
-    },
-    {
-        "name": "edit_file",
-        "description": "Replace exact text in file.",
-        "input_schema": {
-            "type": "object",
-            "properties": {
-                "path": {"type": "string"},
-                "old_text": {"type": "string"},
-                "new_text": {"type": "string"},
-            },
-            "required": ["path", "old_text", "new_text"],
-        },
-    },
-    {
-        "name": "task_create",
-        "description": "Create a new task on the shared task board.",
-        "input_schema": {
-            "type": "object",
-            "properties": {
-                "subject": {"type": "string"},
-                "description": {"type": "string"},
-            },
-            "required": ["subject"],
-        },
-    },
-    {
-        "name": "task_list",
-        "description": "List all tasks with status, owner, and worktree binding.",
-        "input_schema": {"type": "object", "properties": {}},
-    },
-    {
-        "name": "task_get",
-        "description": "Get task details by ID.",
-        "input_schema": {
-            "type": "object",
-            "properties": {"task_id": {"type": "integer"}},
-            "required": ["task_id"],
-        },
-    },
-    {
-        "name": "task_update",
-        "description": "Update task status or owner.",
-        "input_schema": {
-            "type": "object",
-            "properties": {
-                "task_id": {"type": "integer"},
-                "status": {
-                    "type": "string",
-                    "enum": ["pending", "in_progress", "completed"],
-                },
-                "owner": {"type": "string"},
-            },
-            "required": ["task_id"],
-        },
-    },
-    {
-        "name": "task_bind_worktree",
-        "description": "Bind a task to a worktree name.",
-        "input_schema": {
-            "type": "object",
-            "properties": {
-                "task_id": {"type": "integer"},
-                "worktree": {"type": "string"},
-                "owner": {"type": "string"},
-            },
-            "required": ["task_id", "worktree"],
-        },
-    },
-    {
-        "name": "worktree_create",
-        "description": "Create a git worktree and optionally bind it to a task.",
-        "input_schema": {
-            "type": "object",
-            "properties": {
-                "name": {"type": "string"},
-                "task_id": {"type": "integer"},
-                "base_ref": {"type": "string"},
-            },
-            "required": ["name"],
-        },
-    },
-    {
-        "name": "worktree_list",
-        "description": "List worktrees tracked in .worktrees/index.json.",
-        "input_schema": {"type": "object", "properties": {}},
-    },
-    {
-        "name": "worktree_status",
-        "description": "Show git status for one worktree.",
-        "input_schema": {
-            "type": "object",
-            "properties": {"name": {"type": "string"}},
-            "required": ["name"],
-        },
-    },
-    {
-        "name": "worktree_run",
-        "description": "Run a shell command in a named worktree directory.",
-        "input_schema": {
-            "type": "object",
-            "properties": {
-                "name": {"type": "string"},
-                "command": {"type": "string"},
-            },
-            "required": ["name", "command"],
-        },
-    },
-    {
-        "name": "worktree_remove",
-        "description": "Remove a worktree and optionally mark its bound task completed.",
-        "input_schema": {
-            "type": "object",
-            "properties": {
-                "name": {"type": "string"},
-                "force": {"type": "boolean"},
-                "complete_task": {"type": "boolean"},
-            },
-            "required": ["name"],
-        },
-    },
-    {
-        "name": "worktree_keep",
-        "description": "Mark a worktree as kept in lifecycle state without removing it.",
-        "input_schema": {
-            "type": "object",
-            "properties": {"name": {"type": "string"}},
-            "required": ["name"],
-        },
-    },
-    {
-        "name": "worktree_events",
-        "description": "List recent worktree/task lifecycle events from .worktrees/events.jsonl.",
-        "input_schema": {
-            "type": "object",
-            "properties": {"limit": {"type": "integer"}},
-        },
-    },
+    {"name": "bash", "description": "Run a shell command in the current workspace.",
+     "input_schema": {"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]}},
+    {"name": "read_file", "description": "Read file contents.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "limit": {"type": "integer"}}, "required": ["path"]}},
+    {"name": "write_file", "description": "Write content to file.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "content": {"type": "string"}}, "required": ["path", "content"]}},
+    {"name": "edit_file", "description": "Replace exact text in file.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "old_text": {"type": "string"}, "new_text": {"type": "string"}}, "required": ["path", "old_text", "new_text"]}},
+    {"name": "task_create", "description": "Create a new task on the shared task board.",
+     "input_schema": {"type": "object", "properties": {"subject": {"type": "string"}, "description": {"type": "string"}}, "required": ["subject"]}},
+    {"name": "task_list", "description": "List all tasks with status, owner, and worktree binding.",
+     "input_schema": {"type": "object", "properties": {}}},
+    {"name": "task_get", "description": "Get task details by ID.",
+     "input_schema": {"type": "object", "properties": {"task_id": {"type": "integer"}}, "required": ["task_id"]}},
+    {"name": "task_update", "description": "Update task status or owner.",
+     "input_schema": {"type": "object", "properties": {"task_id": {"type": "integer"}, "status": {"type": "string", "enum": ["pending", "in_progress", "completed", "deleted"]}, "owner": {"type": "string"}}, "required": ["task_id"]}},
+    {"name": "task_bind_worktree", "description": "Bind a task to a worktree name.",
+     "input_schema": {"type": "object", "properties": {"task_id": {"type": "integer"}, "worktree": {"type": "string"}, "owner": {"type": "string"}}, "required": ["task_id", "worktree"]}},
+    {"name": "worktree_create", "description": "Create a git worktree and optionally bind it to a task.",
+     "input_schema": {"type": "object", "properties": {"name": {"type": "string"}, "task_id": {"type": "integer"}, "base_ref": {"type": "string"}}, "required": ["name"]}},
+    {"name": "worktree_list", "description": "List worktrees tracked in .worktrees/index.json.",
+     "input_schema": {"type": "object", "properties": {}}},
+    {"name": "worktree_enter", "description": "Enter or reopen a worktree lane before working in it.",
+     "input_schema": {"type": "object", "properties": {"name": {"type": "string"}}, "required": ["name"]}},
+    {"name": "worktree_status", "description": "Show git status for one worktree.",
+     "input_schema": {"type": "object", "properties": {"name": {"type": "string"}}, "required": ["name"]}},
+    {"name": "worktree_run", "description": "Run a shell command in a named worktree directory.",
+     "input_schema": {"type": "object", "properties": {"name": {"type": "string"}, "command": {"type": "string"}}, "required": ["name", "command"]}},
+    {"name": "worktree_closeout", "description": "Close out a lane by keeping it for follow-up or removing it.",
+     "input_schema": {"type": "object", "properties": {"name": {"type": "string"}, "action": {"type": "string", "enum": ["keep", "remove"]}, "reason": {"type": "string"}, "force": {"type": "boolean"}, "complete_task": {"type": "boolean"}}, "required": ["name", "action"]}},
+    {"name": "worktree_remove", "description": "Remove a worktree and optionally mark its bound task completed.",
+     "input_schema": {"type": "object", "properties": {"name": {"type": "string"}, "force": {"type": "boolean"}, "complete_task": {"type": "boolean"}, "reason": {"type": "string"}}, "required": ["name"]}},
+    {"name": "worktree_keep", "description": "Mark a worktree as kept without removing it.",
+     "input_schema": {"type": "object", "properties": {"name": {"type": "string"}}, "required": ["name"]}},
+    {"name": "worktree_events", "description": "List recent lifecycle events.",
+     "input_schema": {"type": "object", "properties": {"limit": {"type": "integer"}}}},
 ]
 
 
 def agent_loop(messages: list):
     while True:
         response = client.messages.create(
-            model=MODEL,
-            system=SYSTEM,
-            messages=messages,
-            tools=TOOLS,
-            max_tokens=8000,
+            model=MODEL, system=SYSTEM, messages=messages,
+            tools=TOOLS, max_tokens=8000,
         )
         messages.append({"role": "assistant", "content": response.content})
         if response.stop_reason != "tool_use":
             return
-
         results = []
         for block in response.content:
             if block.type == "tool_use":
@@ -747,27 +614,20 @@ def agent_loop(messages: list):
                     output = handler(**block.input) if handler else f"Unknown tool: {block.name}"
                 except Exception as e:
                     output = f"Error: {e}"
-                print(f"> {block.name}:")
-                print(str(output)[:200])
-                results.append(
-                    {
-                        "type": "tool_result",
-                        "tool_use_id": block.id,
-                        "content": str(output),
-                    }
-                )
+                print(f"> {block.name}: {str(output)[:200]}")
+                results.append({"type": "tool_result", "tool_use_id": block.id, "content": str(output)})
         messages.append({"role": "user", "content": results})
 
 
 if __name__ == "__main__":
-    print(f"Repo root for s12: {REPO_ROOT}")
+    print(f"Repo root for s18: {REPO_ROOT}")
     if not WORKTREES.git_available:
         print("Note: Not in a git repo. worktree_* tools will return errors.")
 
     history = []
     while True:
         try:
-            query = input("\033[36ms12 >> \033[0m")
+            query = input("\033[36ms18 >> \033[0m")
         except (EOFError, KeyboardInterrupt):
             break
         if query.strip().lower() in ("q", "exit", ""):
diff --git a/agents/s19_mcp_plugin.py b/agents/s19_mcp_plugin.py
new file mode 100644
index 000000000..d7dd0f953
--- /dev/null
+++ b/agents/s19_mcp_plugin.py
@@ -0,0 +1,567 @@
+#!/usr/bin/env python3
+# Harness: integration -- tools aren't just in your code.
+"""
+s19_mcp_plugin.py - MCP & Plugin System
+
+This teaching chapter focuses on the smallest useful idea:
+external processes can expose tools, and your agent can treat them like
+normal tools after a small amount of normalization.
+
+Minimal path:
+  1. start an MCP server process
+  2. ask it which tools it has
+  3. prefix and register those tools
+  4. route matching calls to that server
+
+Plugins add one more layer: discovery. A tiny manifest tells the agent which
+external server to start.
+
+Key insight: "External tools should enter the same tool pipeline, not form a
+completely separate world." In practice that means shared permission checks
+and normalized tool_result payloads.
+
+Read this file in this order:
+1. CapabilityPermissionGate: external tools still go through the same control gate.
+2. MCPClient: how one server connection exposes tool specs and tool calls.
+3. PluginLoader: how manifests declare external servers.
+4. MCPToolRouter / build_tool_pool: how native and external tools merge into one pool.
+
+Most common confusion:
+- a plugin manifest is not an MCP server
+- an MCP server is not a single MCP tool
+- external capability does not bypass the native permission path
+
+Teaching boundary:
+this file teaches the smallest useful stdio MCP path.
+Marketplace details, auth flows, reconnect logic, and non-tool capability layers
+are intentionally left to bridge docs and later extensions.
+"""
+
+import json
+import os
+import subprocess
+import threading
+from pathlib import Path
+
+from anthropic import Anthropic
+from dotenv import load_dotenv
+
+load_dotenv(override=True)
+
+if os.getenv("ANTHROPIC_BASE_URL"):
+    os.environ.pop("ANTHROPIC_AUTH_TOKEN", None)
+
+WORKDIR = Path.cwd()
+client = Anthropic(base_url=os.getenv("ANTHROPIC_BASE_URL"))
+MODEL = os.environ["MODEL_ID"]
+PERMISSION_MODES = ("default", "auto")
+
+
+class CapabilityPermissionGate:
+    """
+    Shared permission gate for native tools and external capabilities.
+
+    The teaching goal is simple: MCP does not bypass the control plane.
+    Native tools and MCP tools both become normalized capability intents first,
+    then pass through the same allow / ask policy.
+    """
+
+    READ_PREFIXES = ("read", "list", "get", "show", "search", "query", "inspect")
+    HIGH_RISK_PREFIXES = ("delete", "remove", "drop", "shutdown")
+
+    def __init__(self, mode: str = "default"):
+        self.mode = mode if mode in PERMISSION_MODES else "default"
+
+    def normalize(self, tool_name: str, tool_input: dict) -> dict:
+        if tool_name.startswith("mcp__"):
+            _, server_name, actual_tool = tool_name.split("__", 2)
+            source = "mcp"
+        else:
+            server_name = None
+            actual_tool = tool_name
+            source = "native"
+
+        lowered = actual_tool.lower()
+        if actual_tool == "read_file" or lowered.startswith(self.READ_PREFIXES):
+            risk = "read"
+        elif actual_tool == "bash":
+            command = tool_input.get("command", "")
+            risk = "high" if any(
+                token in command for token in ("rm -rf", "sudo", "shutdown", "reboot")
+            ) else "write"
+        elif lowered.startswith(self.HIGH_RISK_PREFIXES):
+            risk = "high"
+        else:
+            risk = "write"
+
+        return {
+            "source": source,
+            "server": server_name,
+            "tool": actual_tool,
+            "risk": risk,
+        }
+
+    def check(self, tool_name: str, tool_input: dict) -> dict:
+        intent = self.normalize(tool_name, tool_input)
+
+        if intent["risk"] == "read":
+            return {"behavior": "allow", "reason": "Read capability", "intent": intent}
+
+        if self.mode == "auto" and intent["risk"] != "high":
+            return {
+                "behavior": "allow",
+                "reason": "Auto mode for non-high-risk capability",
+                "intent": intent,
+            }
+
+        if intent["risk"] == "high":
+            return {
+                "behavior": "ask",
+                "reason": "High-risk capability requires confirmation",
+                "intent": intent,
+            }
+
+        return {
+            "behavior": "ask",
+            "reason": "State-changing capability requires confirmation",
+            "intent": intent,
+        }
+
+    def ask_user(self, intent: dict, tool_input: dict) -> bool:
+        preview = json.dumps(tool_input, ensure_ascii=False)[:200]
+        source = (
+            f"{intent['source']}:{intent['server']}/{intent['tool']}"
+            if intent.get("server")
+            else f"{intent['source']}:{intent['tool']}"
+        )
+        print(f"\n  [Permission] {source} risk={intent['risk']}: {preview}")
+        try:
+            answer = input("  Allow? (y/n): ").strip().lower()
+        except (EOFError, KeyboardInterrupt):
+            return False
+        return answer in ("y", "yes")
+
+
+permission_gate = CapabilityPermissionGate()
+
+
+class MCPClient:
+    """
+    Minimal MCP client over stdio.
+
+    This is enough to teach the core architecture without dragging readers
+    through every transport, auth flow, or marketplace detail up front.
+    """
+
+    def __init__(self, server_name: str, command: str, args: list = None, env: dict = None):
+        self.server_name = server_name
+        self.command = command
+        self.args = args or []
+        self.env = {**os.environ, **(env or {})}
+        self.process = None
+        self._request_id = 0
+        self._tools = []  # cached tool list
+
+    def connect(self):
+        """Start the MCP server process."""
+        try:
+            self.process = subprocess.Popen(
+                [self.command] + self.args,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                env=self.env,
+                text=True,
+            )
+            # Send initialize request
+            self._send({"method": "initialize", "params": {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {},
+                "clientInfo": {"name": "teaching-agent", "version": "1.0"},
+            }})
+            response = self._recv()
+            if response and "result" in response:
+                # Send initialized notification
+                self._send({"method": "notifications/initialized"})
+                return True
+        except FileNotFoundError:
+            print(f"[MCP] Server command not found: {self.command}")
+        except Exception as e:
+            print(f"[MCP] Connection failed: {e}")
+        return False
+
+    def list_tools(self) -> list:
+        """Fetch available tools from the server."""
+        self._send({"method": "tools/list", "params": {}})
+        response = self._recv()
+        if response and "result" in response:
+            self._tools = response["result"].get("tools", [])
+        return self._tools
+
+    def call_tool(self, tool_name: str, arguments: dict) -> str:
+        """Execute a tool on the server."""
+        self._send({"method": "tools/call", "params": {
+            "name": tool_name,
+            "arguments": arguments,
+        }})
+        response = self._recv()
+        if response and "result" in response:
+            content = response["result"].get("content", [])
+            return "\n".join(c.get("text", str(c)) for c in content)
+        if response and "error" in response:
+            return f"MCP Error: {response['error'].get('message', 'unknown')}"
+        return "MCP Error: no response"
+
+    def get_agent_tools(self) -> list:
+        """
+        Convert MCP tools to agent tool format.
+
+        Teaching version uses the same simple prefix idea:
+        mcp__{server_name}__{tool_name}
+        """
+        agent_tools = []
+        for tool in self._tools:
+            prefixed_name = f"mcp__{self.server_name}__{tool['name']}"
+            agent_tools.append({
+                "name": prefixed_name,
+                "description": tool.get("description", ""),
+                "input_schema": tool.get("inputSchema", {"type": "object", "properties": {}}),
+                "_mcp_server": self.server_name,
+                "_mcp_tool": tool["name"],
+            })
+        return agent_tools
+
+    def disconnect(self):
+        """Shut down the server process."""
+        if self.process:
+            try:
+                self._send({"method": "shutdown"})
+                self.process.terminate()
+                self.process.wait(timeout=5)
+            except Exception:
+                self.process.kill()
+            self.process = None
+
+    def _send(self, message: dict):
+        if not self.process or self.process.poll() is not None:
+            return
+        self._request_id += 1
+        envelope = {"jsonrpc": "2.0", "id": self._request_id, **message}
+        line = json.dumps(envelope) + "\n"
+        try:
+            self.process.stdin.write(line)
+            self.process.stdin.flush()
+        except (BrokenPipeError, OSError):
+            pass
+
+    def _recv(self) -> dict | None:
+        if not self.process or self.process.poll() is not None:
+            return None
+        try:
+            line = self.process.stdout.readline()
+            if line:
+                return json.loads(line)
+        except (json.JSONDecodeError, OSError):
+            pass
+        return None
+
+
+class PluginLoader:
+    """
+    Load plugins from .claude-plugin/ directories.
+
+    Teaching version implements the smallest useful plugin flow:
+    read a manifest, discover MCP server configs, and register them.
+    """
+
+    def __init__(self, search_dirs: list = None):
+        self.search_dirs = search_dirs or [WORKDIR]
+        self.plugins = {}  # name -> manifest
+
+    def scan(self) -> list:
+        """Scan directories for .claude-plugin/plugin.json manifests."""
+        found = []
+        for search_dir in self.search_dirs:
+            plugin_dir = Path(search_dir) / ".claude-plugin"
+            manifest_path = plugin_dir / "plugin.json"
+            if manifest_path.exists():
+                try:
+                    manifest = json.loads(manifest_path.read_text())
+                    name = manifest.get("name", plugin_dir.parent.name)
+                    self.plugins[name] = manifest
+                    found.append(name)
+                except (json.JSONDecodeError, OSError) as e:
+                    print(f"[Plugin] Failed to load {manifest_path}: {e}")
+        return found
+
+    def get_mcp_servers(self) -> dict:
+        """
+        Extract MCP server configs from loaded plugins.
+        Returns {server_name: {command, args, env}}.
+        """
+        servers = {}
+        for plugin_name, manifest in self.plugins.items():
+            for server_name, config in manifest.get("mcpServers", {}).items():
+                servers[f"{plugin_name}__{server_name}"] = config
+        return servers
+
+
+class MCPToolRouter:
+    """
+    Routes tool calls to the correct MCP server.
+
+    MCP tools are prefixed mcp__{server}__{tool} and live alongside
+    native tools in the same tool pool. The router strips the prefix
+    and dispatches to the right MCPClient.
+    """
+
+    def __init__(self):
+        self.clients = {}  # server_name -> MCPClient
+
+    def register_client(self, client: MCPClient):
+        self.clients[client.server_name] = client
+
+    def is_mcp_tool(self, tool_name: str) -> bool:
+        return tool_name.startswith("mcp__")
+
+    def call(self, tool_name: str, arguments: dict) -> str:
+        """Route an MCP tool call to the correct server."""
+        parts = tool_name.split("__", 2)
+        if len(parts) != 3:
+            return f"Error: Invalid MCP tool name: {tool_name}"
+        _, server_name, actual_tool = parts
+        client = self.clients.get(server_name)
+        if not client:
+            return f"Error: MCP server not found: {server_name}"
+        return client.call_tool(actual_tool, arguments)
+
+    def get_all_tools(self) -> list:
+        """Collect tools from all connected MCP servers."""
+        tools = []
+        for client in self.clients.values():
+            tools.extend(client.get_agent_tools())
+        return tools
+
+
+# -- Native tool implementations (same as s02) --
+def safe_path(p: str) -> Path:
+    path = (WORKDIR / p).resolve()
+    if not path.is_relative_to(WORKDIR):
+        raise ValueError(f"Path escapes workspace: {p}")
+    return path
+
+def run_bash(command: str) -> str:
+    dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
+    if any(d in command for d in dangerous):
+        return "Error: Dangerous command blocked"
+    try:
+        r = subprocess.run(command, shell=True, cwd=WORKDIR,
+                           capture_output=True, text=True, timeout=120)
+        out = (r.stdout + r.stderr).strip()
+        return out[:50000] if out else "(no output)"
+    except subprocess.TimeoutExpired:
+        return "Error: Timeout (120s)"
+
+def run_read(path: str) -> str:
+    try:
+        return safe_path(path).read_text()[:50000]
+    except Exception as e:
+        return f"Error: {e}"
+
+def run_write(path: str, content: str) -> str:
+    try:
+        fp = safe_path(path)
+        fp.parent.mkdir(parents=True, exist_ok=True)
+        fp.write_text(content)
+        return f"Wrote {len(content)} bytes"
+    except Exception as e:
+        return f"Error: {e}"
+
+def run_edit(path: str, old_text: str, new_text: str) -> str:
+    try:
+        fp = safe_path(path)
+        content = fp.read_text()
+        if old_text not in content:
+            return f"Error: Text not found in {path}"
+        fp.write_text(content.replace(old_text, new_text, 1))
+        return f"Edited {path}"
+    except Exception as e:
+        return f"Error: {e}"
+
+
+NATIVE_HANDLERS = {
+    "bash":       lambda **kw: run_bash(kw["command"]),
+    "read_file":  lambda **kw: run_read(kw["path"]),
+    "write_file": lambda **kw: run_write(kw["path"], kw["content"]),
+    "edit_file":  lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
+}
+
+NATIVE_TOOLS = [
+    {"name": "bash", "description": "Run a shell command.",
+     "input_schema": {"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]}},
+    {"name": "read_file", "description": "Read file contents.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}}, "required": ["path"]}},
+    {"name": "write_file", "description": "Write content to file.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "content": {"type": "string"}}, "required": ["path", "content"]}},
+    {"name": "edit_file", "description": "Replace exact text in file.",
+     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "old_text": {"type": "string"}, "new_text": {"type": "string"}}, "required": ["path", "old_text", "new_text"]}},
+]
+
+
+# -- MCP Tool Router (global) --
+mcp_router = MCPToolRouter()
+plugin_loader = PluginLoader()
+
+
+def build_tool_pool() -> list:
+    """
+    Assemble the complete tool pool: native + MCP tools.
+
+    Native tools take precedence on name conflicts so the local core remains
+    predictable even after external tools are added.
+    """
+    all_tools = list(NATIVE_TOOLS)
+    mcp_tools = mcp_router.get_all_tools()
+
+    native_names = {t["name"] for t in all_tools}
+    for tool in mcp_tools:
+        if tool["name"] not in native_names:
+            all_tools.append(tool)
+
+    return all_tools
+
+
+def handle_tool_call(tool_name: str, tool_input: dict) -> str:
+    """Dispatch to native handler or MCP router."""
+    if mcp_router.is_mcp_tool(tool_name):
+        return mcp_router.call(tool_name, tool_input)
+    handler = NATIVE_HANDLERS.get(tool_name)
+    if handler:
+        return handler(**tool_input)
+    return f"Unknown tool: {tool_name}"
+
+
+def normalize_tool_result(tool_name: str, output: str, intent: dict | None = None) -> str:
+    intent = intent or permission_gate.normalize(tool_name, {})
+    status = "error" if "Error:" in output or "MCP Error:" in output else "ok"
+    payload = {
+        "source": intent["source"],
+        "server": intent.get("server"),
+        "tool": intent["tool"],
+        "risk": intent["risk"],
+        "status": status,
+        "preview": output[:500],
+    }
+    return json.dumps(payload, indent=2, ensure_ascii=False)
+
+
+def agent_loop(messages: list):
+    """Agent loop with unified native + MCP tool pool."""
+    tools = build_tool_pool()
+
+    while True:
+        system = (
+            f"You are a coding agent at {WORKDIR}. Use tools to solve tasks.\n"
+            "You have both native tools and MCP tools available.\n"
+            "MCP tools are prefixed with mcp__{server}__{tool}.\n"
+            "All capabilities pass through the same permission gate before execution."
+        )
+        response = client.messages.create(
+            model=MODEL, system=system, messages=messages,
+            tools=tools, max_tokens=8000,
+        )
+        messages.append({"role": "assistant", "content": response.content})
+
+        if response.stop_reason != "tool_use":
+            return
+
+        results = []
+        for block in response.content:
+            if block.type != "tool_use":
+                continue
+            decision = permission_gate.check(block.name, block.input or {})
+            try:
+                if decision["behavior"] == "deny":
+                    output = f"Permission denied: {decision['reason']}"
+                elif decision["behavior"] == "ask" and not permission_gate.ask_user(
+                    decision["intent"], block.input or {}
+                ):
+                    output = f"Permission denied by user: {decision['reason']}"
+                else:
+                    output = handle_tool_call(block.name, block.input or {})
+            except Exception as e:
+                output = f"Error: {e}"
+            print(f"> {block.name}: {str(output)[:200]}")
+            results.append({
+                "type": "tool_result",
+                "tool_use_id": block.id,
+                "content": normalize_tool_result(
+                    block.name,
+                    str(output),
+                    decision.get("intent"),
+                ),
+            })
+
+        messages.append({"role": "user", "content": results})
+
+
+# Further upgrades you can add later:
+# - more transports
+# - auth / approval flows
+# - server reconnect and lifecycle management
+# - filtering external tools before they reach the model
+# - richer plugin installation and update handling
+
+
+if __name__ == "__main__":
+    # Scan for plugins
+    found = plugin_loader.scan()
+    if found:
+        print(f"[Plugins loaded: {', '.join(found)}]")
+        for server_name, config in plugin_loader.get_mcp_servers().items():
+            mcp_client = MCPClient(server_name, config.get("command", ""), config.get("args", []))
+            if mcp_client.connect():
+                mcp_client.list_tools()
+                mcp_router.register_client(mcp_client)
+                print(f"[MCP] Connected to {server_name}")
+
+    tool_count = len(build_tool_pool())
+    mcp_count = len(mcp_router.get_all_tools())
+    print(f"[Tool pool: {tool_count} tools ({mcp_count} from MCP)]")
+
+    history = []
+    while True:
+        try:
+            query = input("\033[36ms19 >> \033[0m")
+        except (EOFError, KeyboardInterrupt):
+            break
+        if query.strip().lower() in ("q", "exit", ""):
+            break
+
+        if query.strip() == "/tools":
+            for tool in build_tool_pool():
+                prefix = "[MCP] " if tool["name"].startswith("mcp__") else "       "
+                print(f"  {prefix}{tool['name']}: {tool.get('description', '')[:60]}")
+            continue
+
+        if query.strip() == "/mcp":
+            if mcp_router.clients:
+                for name, c in mcp_router.clients.items():
+                    tools = c.get_agent_tools()
+                    print(f"  {name}: {len(tools)} tools")
+            else:
+                print("  (no MCP servers connected)")
+            continue
+
+        history.append({"role": "user", "content": query})
+        agent_loop(history)
+        response_content = history[-1]["content"]
+        if isinstance(response_content, list):
+            for block in response_content:
+                if hasattr(block, "text"):
+                    print(block.text)
+        print()
+
+    # Cleanup MCP connections
+    for c in mcp_router.clients.values():
+        c.disconnect()
diff --git a/agents/s_full.py b/agents/s_full.py
index e2f887b5c..bd09faed0 100644
--- a/agents/s_full.py
+++ b/agents/s_full.py
@@ -1,39 +1,36 @@
 #!/usr/bin/env python3
 # Harness: all mechanisms combined -- the complete cockpit for the model.
 """
-s_full.py - Full Reference Agent
-
-Capstone implementation combining every mechanism from s01-s11.
-Session s12 (task-aware worktree isolation) is taught separately.
-NOT a teaching session -- this is the "put it all together" reference.
-
-    +------------------------------------------------------------------+
-    |                        FULL AGENT                                 |
-    |                                                                   |
-    |  System prompt (s05 skills, task-first + optional todo nag)      |
-    |                                                                   |
-    |  Before each LLM call:                                            |
-    |  +--------------------+  +------------------+  +--------------+  |
-    |  | Microcompact (s06) |  | Drain bg (s08)   |  | Check inbox  |  |
-    |  | Auto-compact (s06) |  | notifications    |  | (s09)        |  |
-    |  +--------------------+  +------------------+  +--------------+  |
-    |                                                                   |
-    |  Tool dispatch (s02 pattern):                                     |
-    |  +--------+----------+----------+---------+-----------+          |
-    |  | bash   | read     | write    | edit    | TodoWrite |          |
-    |  | task   | load_sk  | compress | bg_run  | bg_check  |          |
-    |  | t_crt  | t_get    | t_upd    | t_list  | spawn_tm  |          |
-    |  | list_tm| send_msg | rd_inbox | bcast   | shutdown  |          |
-    |  | plan   | idle     | claim    |         |           |          |
-    |  +--------+----------+----------+---------+-----------+          |
-    |                                                                   |
-    |  Subagent (s04):  spawn -> work -> return summary                 |
-    |  Teammate (s09):  spawn -> work -> idle -> auto-claim (s11)      |
-    |  Shutdown (s10):  request_id handshake                            |
-    |  Plan gate (s10): submit -> approve/reject                        |
-    +------------------------------------------------------------------+
-
-    REPL commands: /compact /tasks /team /inbox
+s_full.py - Capstone Teaching Agent
+
+Capstone file that combines the core local mechanisms taught across
+`s01-s18` into one runnable agent.
+
+`s19` (MCP / plugin integration) is still taught as a separate chapter,
+because external tool connectivity is easier to understand after the local
+core is already stable.
+
+Chapter -> Class/Function mapping:
+  s01 Agent Loop     -> agent_loop()
+  s02 Tool Dispatch  -> TOOL_HANDLERS, normalize_messages()
+  s03 TodoWrite      -> TodoManager
+  s04 Subagent       -> run_subagent()
+  s05 Skill Loading  -> SkillLoader
+  s06 Context Compact-> maybe_persist_output(), micro_compact(), auto_compact()
+  s07 Permissions    -> PermissionManager
+  s08 Hooks          -> HookManager
+  s09 Memory         -> MemoryManager
+  s10 System Prompt  -> build_system_prompt()
+  s11 Error Recovery -> recovery logic inside agent_loop()
+  s12 Task System    -> TaskManager
+  s13 Background     -> BackgroundManager
+  s14 Cron Scheduler -> CronScheduler
+  s15 Agent Teams    -> TeammateManager, MessageBus
+  s16 Team Protocols -> shutdown_requests, plan_requests dicts
+  s17 Autonomous     -> _idle_poll(), scan_unclaimed_tasks()
+  s18 Worktree       -> WorktreeManager
+
+REPL commands: /compact /tasks /team /inbox
 """
 
 import json
@@ -66,10 +63,69 @@
 POLL_INTERVAL = 5
 IDLE_TIMEOUT = 60
 
+# Persisted-output: large tool outputs written to disk, replaced with preview marker
+TASK_OUTPUT_DIR = WORKDIR / ".task_outputs"
+TOOL_RESULTS_DIR = TASK_OUTPUT_DIR / "tool-results"
+PERSIST_OUTPUT_TRIGGER_CHARS_DEFAULT = 50000
+PERSIST_OUTPUT_TRIGGER_CHARS_BASH = 30000
+CONTEXT_TRUNCATE_CHARS = 50000
+PERSISTED_OPEN = "<persisted-output>"
+PERSISTED_CLOSE = "</persisted-output>"
+PERSISTED_PREVIEW_CHARS = 2000
+KEEP_RECENT = 3
+PRESERVE_RESULT_TOOLS = {"read_file"}
+
 VALID_MSG_TYPES = {"message", "broadcast", "shutdown_request",
                    "shutdown_response", "plan_approval_response"}
 
 
+# === SECTION: persisted_output (s06) ===
+def _persist_tool_result(tool_use_id: str, content: str) -> Path:
+    TOOL_RESULTS_DIR.mkdir(parents=True, exist_ok=True)
+    safe_id = re.sub(r"[^a-zA-Z0-9_.-]", "_", tool_use_id or "unknown")
+    path = TOOL_RESULTS_DIR / f"{safe_id}.txt"
+    if not path.exists():
+        path.write_text(content)
+    return path.relative_to(WORKDIR)
+
+def _format_size(size: int) -> str:
+    if size < 1024:
+        return f"{size}B"
+    if size < 1024 * 1024:
+        return f"{size / 1024:.1f}KB"
+    return f"{size / (1024 * 1024):.1f}MB"
+
+def _preview_slice(text: str, limit: int) -> tuple[str, bool]:
+    if len(text) <= limit:
+        return text, False
+    idx = text[:limit].rfind("\n")
+    cut = idx if idx > (limit * 0.5) else limit
+    return text[:cut], True
+
+def _build_persisted_marker(stored_path: Path, content: str) -> str:
+    preview, has_more = _preview_slice(content, PERSISTED_PREVIEW_CHARS)
+    marker = (
+        f"{PERSISTED_OPEN}\n"
+        f"Output too large ({_format_size(len(content))}). "
+        f"Full output saved to: {stored_path}\n\n"
+        f"Preview (first {_format_size(PERSISTED_PREVIEW_CHARS)}):\n"
+        f"{preview}"
+    )
+    if has_more:
+        marker += "\n..."
+    marker += f"\n{PERSISTED_CLOSE}"
+    return marker
+
+def maybe_persist_output(tool_use_id: str, output: str, trigger_chars: int = None) -> str:
+    if not isinstance(output, str):
+        return str(output)
+    trigger = PERSIST_OUTPUT_TRIGGER_CHARS_DEFAULT if trigger_chars is None else int(trigger_chars)
+    if len(output) <= trigger:
+        return output
+    stored_path = _persist_tool_result(tool_use_id, output)
+    return _build_persisted_marker(stored_path, output)
+
+
 # === SECTION: base_tools ===
 def safe_path(p: str) -> Path:
     path = (WORKDIR / p).resolve()
@@ -77,7 +133,7 @@ def safe_path(p: str) -> Path:
         raise ValueError(f"Path escapes workspace: {p}")
     return path
 
-def run_bash(command: str) -> str:
+def run_bash(command: str, tool_use_id: str = "") -> str:
     dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
     if any(d in command for d in dangerous):
         return "Error: Dangerous command blocked"
@@ -85,16 +141,21 @@ def run_bash(command: str) -> str:
         r = subprocess.run(command, shell=True, cwd=WORKDIR,
                            capture_output=True, text=True, timeout=120)
         out = (r.stdout + r.stderr).strip()
-        return out[:50000] if out else "(no output)"
+        if not out:
+            return "(no output)"
+        out = maybe_persist_output(tool_use_id, out, trigger_chars=PERSIST_OUTPUT_TRIGGER_CHARS_BASH)
+        return out[:CONTEXT_TRUNCATE_CHARS] if isinstance(out, str) else str(out)[:CONTEXT_TRUNCATE_CHARS]
     except subprocess.TimeoutExpired:
         return "Error: Timeout (120s)"
 
-def run_read(path: str, limit: int = None) -> str:
+def run_read(path: str, tool_use_id: str = "", limit: int = None) -> str:
     try:
         lines = safe_path(path).read_text().splitlines()
         if limit and limit < len(lines):
             lines = lines[:limit] + [f"... ({len(lines) - limit} more)"]
-        return "\n".join(lines)[:50000]
+        out = "\n".join(lines)
+        out = maybe_persist_output(tool_use_id, out)
+        return out[:CONTEXT_TRUNCATE_CHARS] if isinstance(out, str) else str(out)[:CONTEXT_TRUNCATE_CHARS]
     except Exception as e:
         return f"Error: {e}"
 
@@ -228,33 +289,64 @@ def estimate_tokens(messages: list) -> int:
     return len(json.dumps(messages, default=str)) // 4
 
 def microcompact(messages: list):
-    indices = []
-    for i, msg in enumerate(messages):
+    tool_results = []
+    for msg in messages:
         if msg["role"] == "user" and isinstance(msg.get("content"), list):
             for part in msg["content"]:
                 if isinstance(part, dict) and part.get("type") == "tool_result":
-                    indices.append(part)
-    if len(indices) <= 3:
+                    tool_results.append(part)
+    if len(tool_results) <= KEEP_RECENT:
         return
-    for part in indices[:-3]:
-        if isinstance(part.get("content"), str) and len(part["content"]) > 100:
-            part["content"] = "[cleared]"
+    tool_name_map = {}
+    for msg in messages:
+        if msg["role"] == "assistant":
+            content = msg.get("content", [])
+            if isinstance(content, list):
+                for block in content:
+                    if hasattr(block, "type") and block.type == "tool_use":
+                        tool_name_map[block.id] = block.name
+    for part in tool_results[:-KEEP_RECENT]:
+        if not isinstance(part.get("content"), str) or len(part["content"]) <= 100:
+            continue
+        tool_id = part.get("tool_use_id", "")
+        tool_name = tool_name_map.get(tool_id, "unknown")
+        if tool_name in PRESERVE_RESULT_TOOLS:
+            continue
+        part["content"] = f"[Previous: used {tool_name}]"
 
-def auto_compact(messages: list) -> list:
+def auto_compact(messages: list, focus: str = None) -> list:
     TRANSCRIPT_DIR.mkdir(exist_ok=True)
     path = TRANSCRIPT_DIR / f"transcript_{int(time.time())}.jsonl"
     with open(path, "w") as f:
         for msg in messages:
             f.write(json.dumps(msg, default=str) + "\n")
-    conv_text = json.dumps(messages, default=str)[-80000:]
+    conv_text = json.dumps(messages, default=str)[:80000]
+    prompt = (
+        "Summarize this conversation for continuity. Structure your summary:\n"
+        "1) Task overview: core request, success criteria, constraints\n"
+        "2) Current state: completed work, files touched, artifacts created\n"
+        "3) Key decisions and discoveries: constraints, errors, failed approaches\n"
+        "4) Next steps: remaining actions, blockers, priority order\n"
+        "5) Context to preserve: user preferences, domain details, commitments\n"
+        "Be concise but preserve critical details.\n"
+    )
+    if focus:
+        prompt += f"\nPay special attention to: {focus}\n"
     resp = client.messages.create(
         model=MODEL,
-        messages=[{"role": "user", "content": f"Summarize for continuity:\n{conv_text}"}],
-        max_tokens=2000,
+        messages=[{"role": "user", "content": prompt + "\n" + conv_text}],
+        max_tokens=4000,
     )
     summary = resp.content[0].text
+    continuation = (
+        "This session is being continued from a previous conversation that ran out "
+        "of context. The summary below covers the earlier portion of the conversation.\n\n"
+        f"{summary}\n\n"
+        "Please continue the conversation from where we left it off without asking "
+        "the user any further questions."
+    )
     return [
-        {"role": "user", "content": f"[Compressed. Transcript: {path}]\n{summary}"},
+        {"role": "user", "content": continuation},
     ]
 
 
@@ -277,7 +369,7 @@ def _save(self, task: dict):
 
     def create(self, subject: str, description: str = "") -> str:
         task = {"id": self._next_id(), "subject": subject, "description": description,
-                "status": "pending", "owner": None, "blockedBy": []}
+                "status": "pending", "owner": None, "blockedBy": [], "blocks": []}
         self._save(task)
         return json.dumps(task, indent=2)
 
@@ -285,7 +377,7 @@ def get(self, tid: int) -> str:
         return json.dumps(self._load(tid), indent=2)
 
     def update(self, tid: int, status: str = None,
-               add_blocked_by: list = None, remove_blocked_by: list = None) -> str:
+               add_blocked_by: list = None, add_blocks: list = None) -> str:
         task = self._load(tid)
         if status:
             task["status"] = status
@@ -300,8 +392,8 @@ def update(self, tid: int, status: str = None,
                 return f"Task {tid} deleted"
         if add_blocked_by:
             task["blockedBy"] = list(set(task["blockedBy"] + add_blocked_by))
-        if remove_blocked_by:
-            task["blockedBy"] = [x for x in task["blockedBy"] if x not in remove_blocked_by]
+        if add_blocks:
+            task["blocks"] = list(set(task["blocks"] + add_blocks))
         self._save(task)
         return json.dumps(task, indent=2)
 
@@ -350,7 +442,12 @@ def _exec(self, tid: str, command: str, timeout: int):
     def check(self, tid: str = None) -> str:
         if tid:
             t = self.tasks.get(tid)
-            return f"[{t['status']}] {t.get('result') or '(running)'}" if t else f"Unknown: {tid}"
+            if not t:
+                return f"Unknown: {tid}"
+            result = t.get("result")
+            if result is None:
+                result = "(running)"
+            return f"[{t['status']}] {result}"
         return "\n".join(f"{k}: [{v['status']}] {v['command'][:60]}" for k, v in self.tasks.items()) or "No bg tasks."
 
     def drain(self) -> list:
@@ -575,8 +672,8 @@ def handle_plan_review(request_id: str, approve: bool, feedback: str = "") -> st
 
 # === SECTION: tool_dispatch (s02) ===
 TOOL_HANDLERS = {
-    "bash":             lambda **kw: run_bash(kw["command"]),
-    "read_file":        lambda **kw: run_read(kw["path"], kw.get("limit")),
+    "bash":             lambda **kw: run_bash(kw["command"], kw.get("tool_use_id", "")),
+    "read_file":        lambda **kw: run_read(kw["path"], kw.get("tool_use_id", ""), kw.get("limit")),
     "write_file":       lambda **kw: run_write(kw["path"], kw["content"]),
     "edit_file":        lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
     "TodoWrite":        lambda **kw: TODO.update(kw["items"]),
@@ -587,7 +684,7 @@ def handle_plan_review(request_id: str, approve: bool, feedback: str = "") -> st
     "check_background": lambda **kw: BG.check(kw.get("task_id")),
     "task_create":      lambda **kw: TASK_MGR.create(kw["subject"], kw.get("description", "")),
     "task_get":         lambda **kw: TASK_MGR.get(kw["task_id"]),
-    "task_update":      lambda **kw: TASK_MGR.update(kw["task_id"], kw.get("status"), kw.get("add_blocked_by"), kw.get("remove_blocked_by")),
+    "task_update":      lambda **kw: TASK_MGR.update(kw["task_id"], kw.get("status"), kw.get("add_blocked_by"), kw.get("add_blocks")),
     "task_list":        lambda **kw: TASK_MGR.list_all(),
     "spawn_teammate":   lambda **kw: TEAM.spawn(kw["name"], kw["role"], kw["prompt"]),
     "list_teammates":   lambda **kw: TEAM.list_all(),
@@ -626,7 +723,7 @@ def handle_plan_review(request_id: str, approve: bool, feedback: str = "") -> st
     {"name": "task_get", "description": "Get task details by ID.",
      "input_schema": {"type": "object", "properties": {"task_id": {"type": "integer"}}, "required": ["task_id"]}},
     {"name": "task_update", "description": "Update task status or dependencies.",
-     "input_schema": {"type": "object", "properties": {"task_id": {"type": "integer"}, "status": {"type": "string", "enum": ["pending", "in_progress", "completed", "deleted"]}, "add_blocked_by": {"type": "array", "items": {"type": "integer"}}, "remove_blocked_by": {"type": "array", "items": {"type": "integer"}}}, "required": ["task_id"]}},
+     "input_schema": {"type": "object", "properties": {"task_id": {"type": "integer"}, "status": {"type": "string", "enum": ["pending", "in_progress", "completed", "deleted"]}, "add_blocked_by": {"type": "array", "items": {"type": "integer"}}, "add_blocks": {"type": "array", "items": {"type": "integer"}}}, "required": ["task_id"]}},
     {"name": "task_list", "description": "List all tasks.",
      "input_schema": {"type": "object", "properties": {}}},
     {"name": "spawn_teammate", "description": "Spawn a persistent autonomous teammate.",
@@ -664,10 +761,12 @@ def agent_loop(messages: list):
         if notifs:
             txt = "\n".join(f"[bg:{n['task_id']}] {n['status']}: {n['result']}" for n in notifs)
             messages.append({"role": "user", "content": f"<background-results>\n{txt}\n</background-results>"})
+            messages.append({"role": "assistant", "content": "Noted background results."})
         # s10: check lead inbox
         inbox = BUS.read_inbox("lead")
         if inbox:
             messages.append({"role": "user", "content": f"<inbox>{json.dumps(inbox, indent=2)}</inbox>"})
+            messages.append({"role": "assistant", "content": "Noted inbox messages."})
         # LLM call
         response = client.messages.create(
             model=MODEL, system=SYSTEM, messages=messages,
@@ -680,30 +779,32 @@ def agent_loop(messages: list):
         results = []
         used_todo = False
         manual_compress = False
+        compact_focus = None
         for block in response.content:
             if block.type == "tool_use":
                 if block.name == "compress":
                     manual_compress = True
+                    compact_focus = (block.input or {}).get("focus")
                 handler = TOOL_HANDLERS.get(block.name)
                 try:
-                    output = handler(**block.input) if handler else f"Unknown tool: {block.name}"
+                    tool_input = dict(block.input or {})
+                    tool_input["tool_use_id"] = block.id
+                    output = handler(**tool_input) if handler else f"Unknown tool: {block.name}"
                 except Exception as e:
                     output = f"Error: {e}"
-                print(f"> {block.name}:")
-                print(str(output)[:200])
+                print(f"> {block.name}: {str(output)[:200]}")
                 results.append({"type": "tool_result", "tool_use_id": block.id, "content": str(output)})
                 if block.name == "TodoWrite":
                     used_todo = True
         # s03: nag reminder (only when todo workflow is active)
         rounds_without_todo = 0 if used_todo else rounds_without_todo + 1
         if TODO.has_open_items() and rounds_without_todo >= 3:
-            results.append({"type": "text", "text": "<reminder>Update your todos.</reminder>"})
+            results.insert(0, {"type": "text", "text": "<reminder>Update your todos.</reminder>"})
         messages.append({"role": "user", "content": results})
         # s06: manual compress
         if manual_compress:
             print("[manual compact]")
-            messages[:] = auto_compact(messages)
-            return
+            messages[:] = auto_compact(messages, focus=compact_focus)
 
 
 # === SECTION: repl ===
@@ -732,9 +833,4 @@ def agent_loop(messages: list):
             continue
         history.append({"role": "user", "content": query})
         agent_loop(history)
-        response_content = history[-1]["content"]
-        if isinstance(response_content, list):
-            for block in response_content:
-                if hasattr(block, "text"):
-                    print(block.text)
         print()
diff --git a/agents_deepagents/README.md b/agents_deepagents/README.md
new file mode 100644
index 000000000..a4b58108d
--- /dev/null
+++ b/agents_deepagents/README.md
@@ -0,0 +1,115 @@
+# LangChain-Native Deep Agents s01-s06 Teaching Track
+
+This directory is the parallel LangChain/Deep Agents track for the first
+milestone of the course. The original `agents/*.py` files remain the
+hand-written Anthropic SDK baseline; these files preserve the original
+chapters' meaningful behavior while letting each `sNN` file use the most
+natural LangChain-native implementation for that lesson.
+
+The web UI does not surface this directory yet. Read and run these files from
+the terminal.
+
+## Migration Policy
+
+- Preserve original project functionality before preserving tutorial-internal
+  mechanism boundaries.
+- Prefer natural LangChain / Deep Agents primitives over line-by-line tutorial
+  fidelity.
+- Keep the `sNN` chapter shell only while it remains a useful navigation aid.
+- If a chapter intentionally drops nonessential behavior, document that drop
+  explicitly instead of silently shrinking the feature.
+
+## Environment
+
+Configure the Deep Agents track with OpenAI-style variables:
+
+```sh
+OPENAI_API_KEY=sk-...
+OPENAI_MODEL=gpt-4.1-mini        # optional; defaults to gpt-4.1-mini
+OPENAI_BASE_URL=https://...      # optional OpenAI-compatible endpoint
+```
+
+`OPENAI_MODEL` is preferred for this track. `MODEL_ID` is accepted only as a
+compatibility fallback if you already use the original `.env` file.
+
+## Current Anchors
+
+- `s02` is the current **state-light** example: a thin tool-use wrapper with
+  normalized input and middleware, but no custom tool-use state object.
+- `s03` is the current **naturally stateful** example: planning lives in
+  explicit LangChain state (`PlanningState`) and is updated through
+  `Command(update=...)` plus middleware. Its display path now uses a tiny
+  renderer-first seam while preserving the terminal output and avoiding
+  browser/API/event-bus scope.
+- `s06` is the current **context-compression** example: canonical history stays
+  in explicit state while a smaller model-facing projection walks through a
+  cc-haha-inspired six-stage pipeline.
+- After review, the current `s01-s06` file names still describe the dominant
+  behavior of each chapter well enough to keep the chapter shell useful.
+
+## Chapter Map
+
+| Original baseline | Current track | Dominant LangChain-native shape | Behavior preserved |
+|---|---|---|---|
+| `agents/s01_agent_loop.py` | `agents_deepagents/s01_agent_loop.py` | Minimal `create_agent_runtime(...)` loop with no future capabilities exposed early | Minimal loop + turn-by-turn interaction |
+| `agents/s02_tool_use.py` | `agents_deepagents/s02_tool_use.py` | Thin invoke wrapper plus `ToolUseMiddleware`; no custom tool state | File/tool growth without rewriting the loop |
+| `agents/s03_todo_write.py` | `agents_deepagents/s03_todo_write.py` | Tutorial-shaped planning state (`items`, `rounds_since_update`) plus middleware-driven `write_plan` updates and direct terminal rendering helpers | Visible session planning state |
+| `agents/s04_subagent.py` | `agents_deepagents/s04_subagent.py` | Deep Agents `SubAgentMiddleware` maps original `run_subagent(prompt)` to `task(description, subagent_type)` with fresh child message context and summary-only return | Subagents as context isolation |
+| `agents/s05_skill_loading.py` | `agents_deepagents/s05_skill_loading.py` | Deep Agents `SkillsMiddleware` advertises skill metadata; `read_file` loads `SKILL.md` only on demand | Discover light, load deep |
+| `agents/s06_context_compact.py` | `agents_deepagents/s06_context_compact.py` | Typed state plus six explicit compression stages: tool-result budget, snip projection, microcompact, context collapse, auto compact, and reactive overflow recovery | Honest cc-haha-inspired context compression pipeline |
+
+## s06 Evidence / Inference Map
+
+`s06_context_compact.py` exposes these same classifications in code so tests can
+verify the README disclosure stays aligned.
+
+### Source-backed stages
+
+- `apply_tool_result_budget`
+- `microcompact_messages`
+- `auto_compact_if_needed`
+- `reactive_compact_on_overflow`
+
+### Inferred teaching equivalents
+
+- `snip_projection`
+- `context_collapse`
+
+### Intentional simplifications
+
+- Character counts stand in for exact tokenizer budgets.
+- Persisted tool outputs are stored as plain text files instead of provider
+  cache edits.
+- Snip projection and context collapse are honest teaching equivalents because
+  the public cc-haha tree does not expose those internals in full.
+- Auto compact omits session-memory extraction, telemetry, and
+  prompt-cache-sharing details.
+
+## CC Alignment Progress Docs
+
+Each implemented `sNN` chapter should have a matching progress document under
+[`cc_alignment/`](./cc_alignment/) that lists what is aligned with CC/cc-haha,
+what is only a teaching equivalent, what is intentionally not copied, and what
+should be considered next.
+
+Current s06 details: [`cc_alignment/s06-context-compact.md`](./cc_alignment/s06-context-compact.md).
+
+## Disclosure Status
+
+This README currently records no intentional nonessential drops for `s01-s06`.
+If a later chapter needs to omit nonessential behavior, record that fact in the
+chapter report or this README instead of implying full parity by default.
+
+## Run
+
+```sh
+python agents_deepagents/s01_agent_loop.py
+python agents_deepagents/s02_tool_use.py
+python agents_deepagents/s03_todo_write.py
+python agents_deepagents/s04_subagent.py
+python agents_deepagents/s05_skill_loading.py
+python agents_deepagents/s06_context_compact.py
+```
+
+Automated tests compile the files and import pure helpers only; they do not use
+`OPENAI_API_KEY` and do not make network calls.
diff --git a/agents_deepagents/__init__.py b/agents_deepagents/__init__.py
new file mode 100644
index 000000000..4260dfd3b
--- /dev/null
+++ b/agents_deepagents/__init__.py
@@ -0,0 +1,6 @@
+"""Parallel Deep Agents teaching track for s01-s06.
+
+The original ``agents/`` scripts stay as the hand-written Anthropic SDK
+baseline. Files in this package show the first six lessons through a staged
+Deep Agents track.
+"""
diff --git a/agents_deepagents/_common.py b/agents_deepagents/_common.py
new file mode 100644
index 000000000..c4ce6f3e5
--- /dev/null
+++ b/agents_deepagents/_common.py
@@ -0,0 +1,170 @@
+"""Small shared helpers for the Deep Agents teaching track.
+
+The chapter files stay runnable and readable, while this module keeps
+repeated OpenAI-compatible model configuration and safe filesystem helpers in
+one place. It intentionally does not instantiate a Deep Agents model at import
+time, so tests can import pure helpers without an API key or network access.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+from typing import Any, Iterable
+
+from dotenv import load_dotenv
+
+load_dotenv(override=True)
+
+WORKDIR = Path.cwd()
+DEFAULT_OPENAI_MODEL = "gpt-4.1-mini"
+OUTPUT_LIMIT = 50_000
+DANGEROUS_COMMANDS = ("rm -rf /", "sudo", "shutdown", "reboot", "> /dev/")
+
+
+def resolve_openai_model() -> str:
+    """Return the model name for the OpenAI-interface Deep Agents track.
+
+    `OPENAI_MODEL` is the canonical variable for this track.  `MODEL_ID` is
+    only treated as a compatibility fallback when it does not look like the
+    existing Anthropic default from `.env.example`; this avoids accidentally
+    driving the OpenAI interface with `claude-*` names.
+    """
+
+    openai_model = os.getenv("OPENAI_MODEL", "").strip()
+    if openai_model:
+        return openai_model
+
+    legacy_model = os.getenv("MODEL_ID", "").strip()
+    if legacy_model and not legacy_model.lower().startswith("claude"):
+        return legacy_model
+
+    return DEFAULT_OPENAI_MODEL
+
+
+def require_openai_api_key() -> None:
+    """Fail with a teaching-oriented message before a live model call."""
+
+    if not os.getenv("OPENAI_API_KEY"):
+        raise RuntimeError(
+            "Set OPENAI_API_KEY before running the Deep Agents demos. "
+            "OPENAI_BASE_URL is optional for OpenAI-compatible endpoints."
+        )
+
+
+def build_openai_chat_model(*, temperature: float = 0.0, timeout: int = 60):
+    """Build ChatOpenAI lazily so imports/tests do not require credentials."""
+
+    require_openai_api_key()
+    from langchain_openai import ChatOpenAI
+
+    kwargs: dict[str, Any] = {
+        "model": resolve_openai_model(),
+        "temperature": temperature,
+        "timeout": timeout,
+    }
+    base_url = os.getenv("OPENAI_BASE_URL", "").strip()
+    if base_url:
+        kwargs["base_url"] = base_url
+    return ChatOpenAI(**kwargs)
+
+
+def safe_path(path_str: str) -> Path:
+    """Resolve a workspace-local path and reject traversal outside WORKDIR."""
+
+    path = (WORKDIR / path_str).resolve()
+    if not path.is_relative_to(WORKDIR):
+        raise ValueError(f"Path escapes workspace: {path_str}")
+    return path
+
+
+def run_bash(command: str) -> str:
+    """Run a bounded shell command in the teaching workspace."""
+
+    if any(item in command for item in DANGEROUS_COMMANDS):
+        return "Error: Dangerous command blocked"
+    try:
+        result = subprocess.run(
+            command,
+            shell=True,
+            cwd=WORKDIR,
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+    except subprocess.TimeoutExpired:
+        return "Error: Timeout (120s)"
+    except (FileNotFoundError, OSError) as exc:
+        return f"Error: {exc}"
+
+    output = (result.stdout + result.stderr).strip()
+    return output[:OUTPUT_LIMIT] if output else "(no output)"
+
+
+def read_file(path: str, limit: int | None = None) -> str:
+    try:
+        lines = safe_path(path).read_text().splitlines()
+        if limit and limit < len(lines):
+            lines = lines[:limit] + [f"... ({len(lines) - limit} more lines)"]
+        return "\n".join(lines)[:OUTPUT_LIMIT]
+    except Exception as exc:
+        return f"Error: {exc}"
+
+
+def write_file(path: str, content: str) -> str:
+    try:
+        file_path = safe_path(path)
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_path.write_text(content)
+        return f"Wrote {len(content)} bytes to {path}"
+    except Exception as exc:
+        return f"Error: {exc}"
+
+
+def edit_file(path: str, old_text: str, new_text: str) -> str:
+    try:
+        file_path = safe_path(path)
+        content = file_path.read_text()
+        if old_text not in content:
+            return f"Error: Text not found in {path}"
+        file_path.write_text(content.replace(old_text, new_text, 1))
+        return f"Edited {path}"
+    except Exception as exc:
+        return f"Error: {exc}"
+
+
+def message_text(message: Any) -> str:
+    """Extract printable text from Deep Agents BaseMessage or dict content."""
+
+    content = getattr(message, "content", None)
+    if content is None and isinstance(message, dict):
+        content = message.get("content")
+    if isinstance(content, str):
+        return content.strip()
+    if isinstance(content, list):
+        parts: list[str] = []
+        for block in content:
+            if isinstance(block, str):
+                parts.append(block)
+            elif isinstance(block, dict):
+                text = block.get("text") or block.get("content")
+                if text:
+                    parts.append(str(text))
+            else:
+                text = (
+                    getattr(block, "text", None)
+                    or getattr(block, "content", None)
+                )
+                if text:
+                    parts.append(str(text))
+        return "\n".join(parts).strip()
+    return ""
+
+
+def latest_text(messages: Iterable[Any]) -> str:
+    for message in reversed(list(messages)):
+        text = message_text(message)
+        if text:
+            return text
+    return ""
diff --git a/agents_deepagents/_deepagents_gating.py b/agents_deepagents/_deepagents_gating.py
new file mode 100644
index 000000000..a04c2221a
--- /dev/null
+++ b/agents_deepagents/_deepagents_gating.py
@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+"""Deep Agents staging spike for the s01-s06 teaching track.
+
+`deepagents.create_deep_agent()` eagerly installs planning, filesystem,
+subagent, and summarization middleware. That default stack is convenient for a
+fully-loaded coding harness, but it is too permissive for this repository's
+chapter-by-chapter tutorial: `s01` must not expose planning yet, and `s03`
+must still block subagents.
+
+This module proves the gating requirement is technically viable by
+composing the Deep Agents middleware stack directly with
+`langchain.agents.create_agent()`. Each stage only receives the
+middleware that should be visible at that chapter.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, Sequence
+
+from deepagents.backends import StateBackend
+from deepagents.middleware.filesystem import FilesystemMiddleware
+from deepagents.middleware.patch_tool_calls import PatchToolCallsMiddleware
+from deepagents.middleware.skills import SkillsMiddleware
+from deepagents.middleware.subagents import (
+    CompiledSubAgent,
+    SubAgent,
+    SubAgentMiddleware,
+)
+from deepagents.middleware.summarization import (
+    create_summarization_middleware,
+    create_summarization_tool_middleware,
+)
+from langchain.agents import create_agent
+from langchain.agents.middleware import TodoListMiddleware
+from langchain.agents.middleware.types import AgentMiddleware
+from langchain.chat_models import init_chat_model
+from langchain_core.language_models.chat_models import BaseChatModel
+
+StageName = Literal[
+    "s01",
+    "s02",
+    "s03",
+    "s04",
+    "s05",
+    "s06",
+    "s07",
+    "s08",
+    "s09",
+    "s10",
+    "s11",
+]
+
+
+@dataclass(frozen=True)
+class StageCapabilities:
+    planning: bool = False
+    subagents: bool = False
+    skills: bool = False
+    compaction: bool = False
+
+
+STAGE_CAPABILITIES: dict[StageName, StageCapabilities] = {
+    "s01": StageCapabilities(),
+    "s02": StageCapabilities(),
+    "s03": StageCapabilities(planning=True),
+    "s04": StageCapabilities(planning=True, subagents=True),
+    "s05": StageCapabilities(planning=True, subagents=True, skills=True),
+    "s06": StageCapabilities(
+        planning=True,
+        subagents=True,
+        skills=True,
+        compaction=True,
+    ),
+    "s07": StageCapabilities(),
+    "s08": StageCapabilities(),
+    "s09": StageCapabilities(),
+    "s10": StageCapabilities(),
+    "s11": StageCapabilities(),
+}
+
+SubagentSpec = SubAgent | CompiledSubAgent
+
+
+def capabilities_for_stage(stage: StageName) -> StageCapabilities:
+    try:
+        return STAGE_CAPABILITIES[stage]
+    except KeyError as exc:  # pragma: no cover - defensive guard
+        expected = ", ".join(STAGE_CAPABILITIES)
+        raise ValueError(
+            f"Unsupported stage '{stage}'. Expected one of: {expected}"
+        ) from exc
+
+
+def _resolve_model(model: str | BaseChatModel) -> BaseChatModel:
+    return init_chat_model(model) if isinstance(model, str) else model
+
+
+def _validate_stage_inputs(
+    stage: StageName,
+    capabilities: StageCapabilities,
+    *,
+    subagents: Sequence[SubagentSpec] | None,
+    skill_sources: Sequence[str] | None,
+) -> None:
+    if capabilities.subagents and not subagents:
+        raise ValueError(f"{stage} requires at least one configured subagent")
+    if capabilities.skills and not skill_sources:
+        raise ValueError(
+            f"{stage} requires at least one configured skill source"
+        )
+
+
+def build_stage_middleware(
+    stage: StageName,
+    *,
+    model: str | BaseChatModel,
+    backend: Any = StateBackend,
+    subagents: Sequence[SubagentSpec] | None = None,
+    skill_sources: Sequence[str] | None = None,
+    extra_middleware: Sequence[AgentMiddleware[Any, Any]] = (),
+) -> list[AgentMiddleware[Any, Any]]:
+    """Build the middleware stack for a staged Deep Agents chapter."""
+
+    capabilities = capabilities_for_stage(stage)
+    _validate_stage_inputs(
+        stage,
+        capabilities,
+        subagents=subagents,
+        skill_sources=skill_sources,
+    )
+
+    resolved_model = (
+        _resolve_model(model) if capabilities.compaction else model
+    )
+
+    middleware: list[AgentMiddleware[Any, Any]] = []
+    if capabilities.planning:
+        middleware.append(TodoListMiddleware())
+    if capabilities.skills and skill_sources:
+        middleware.append(
+            SkillsMiddleware(
+                backend=backend,
+                sources=list(skill_sources),
+            )
+        )
+
+    middleware.append(FilesystemMiddleware(backend=backend))
+
+    if capabilities.subagents and subagents:
+        middleware.append(
+            SubAgentMiddleware(
+                backend=backend,
+                subagents=list(subagents),
+            )
+        )
+    if capabilities.compaction:
+        middleware.append(
+            create_summarization_tool_middleware(
+                resolved_model,
+                backend,
+            )
+        )
+        middleware.append(
+            create_summarization_middleware(resolved_model, backend)
+        )
+
+    middleware.append(PatchToolCallsMiddleware())
+    middleware.extend(extra_middleware)
+    return middleware
+
+
+def build_stage_agent(
+    stage: StageName,
+    *,
+    model: str | BaseChatModel,
+    tools: Sequence[Any] | None = None,
+    backend: Any = StateBackend,
+    system_prompt: str | None = None,
+    subagents: Sequence[SubagentSpec] | None = None,
+    skill_sources: Sequence[str] | None = None,
+    extra_middleware: Sequence[AgentMiddleware[Any, Any]] = (),
+):
+    """Create a stage-gated agent using Deep Agents middleware primitives."""
+
+    capabilities = capabilities_for_stage(stage)
+    resolved_model = (
+        _resolve_model(model) if capabilities.compaction else model
+    )
+
+    return create_agent(
+        resolved_model,
+        tools=list(tools or []),
+        system_prompt=system_prompt,
+        middleware=build_stage_middleware(
+            stage,
+            model=resolved_model,
+            backend=backend,
+            subagents=subagents,
+            skill_sources=skill_sources,
+            extra_middleware=extra_middleware,
+        ),
+    )
diff --git a/agents_deepagents/cc_alignment/README.md b/agents_deepagents/cc_alignment/README.md
new file mode 100644
index 000000000..aa3d96361
--- /dev/null
+++ b/agents_deepagents/cc_alignment/README.md
@@ -0,0 +1,51 @@
+# CC Alignment Progress Documents
+
+Every implemented `agents_deepagents/sNN_*.py` chapter must have a matching CC
+alignment progress document in this directory.
+
+## Project rule
+
+For each `sNN` chapter, maintain one document named:
+
+```text
+agents_deepagents/cc_alignment/sNN-<topic>.md
+```
+
+The document must explicitly list:
+
+1. **Chapter scope** — what this `sNN` is responsible for in the LangChain / Deep Agents track.
+2. **CC / cc-haha reference points** — source files, docs, or observed behavior used as the alignment target.
+3. **Aligned** — behavior or structure we intentionally match.
+4. **Partially aligned / teaching equivalent** — behavior we model in a smaller LangChain-native way.
+5. **Not aligned / intentionally not copied** — production details we do not implement yet, with reasons.
+6. **Tests / evidence** — deterministic verification proving the current state.
+7. **Next alignment candidates** — what should be considered in a later product-stage or chapter pass.
+
+If a chapter has no meaningful CC equivalent yet, the document should still exist
+and say so explicitly rather than leaving alignment status implicit.
+
+## Current documents
+
+| Chapter | Document | Status |
+|---|---|---|
+| s06 Context Compact | [`s06-context-compact.md`](./s06-context-compact.md) | Teaching-level structural parity with explicit production gaps |
+
+## Template
+
+```md
+# sNN: <Title> — CC Alignment Progress
+
+## Scope
+
+## CC reference points
+
+## Aligned
+
+## Partially aligned / teaching equivalent
+
+## Not aligned / intentionally not copied
+
+## Tests / evidence
+
+## Next alignment candidates
+```
diff --git a/agents_deepagents/cc_alignment/s06-context-compact.md b/agents_deepagents/cc_alignment/s06-context-compact.md
new file mode 100644
index 000000000..14ee463e0
--- /dev/null
+++ b/agents_deepagents/cc_alignment/s06-context-compact.md
@@ -0,0 +1,355 @@
+# s06：Context Compact — CC 对齐进度
+
+## 范围
+
+`s06_context_compact.py` 是教程轨道里的上下文压缩章节。它负责在保留足够的
+canonical history（规范历史记录）和恢复元数据的同时，缩小模型每轮真正看到的
+active context（活跃上下文）。
+
+当前实现是一个 **受 cc-haha 启发的 LangChain 教学版压缩流水线**，不是 Claude
+Code 生产级 compact runtime 的完整克隆。
+
+## CC 参考点
+
+主要参考：`NanmiCoder/cc-haha` commit
+`5fa3247f9fa3ddde462185218f7e73b2dccfc956`。
+
+本章使用到的公开源码参考点：
+
+- `src/query.ts` — 模型调用前的压缩顺序：
+  `applyToolResultBudget -> snipCompactIfNeeded -> microcompactMessages -> contextCollapse.applyCollapsesIfNeeded -> autoCompactIfNeeded`。
+- `src/utils/toolResultStorage.ts` — 大型 tool result 持久化、`<persisted-output>` 标记、单轮 message 预算、replacement decision。
+- `src/services/compact/microCompact.ts` — 可压缩工具集合、旧结果清理、time-based / cached microcompact 概念，以及 microcompact boundary。
+- `src/services/compact/autoCompact.ts` — 阈值计算、summary 预算、auto compact 触发、失败 circuit breaker。
+- `src/services/compact/compact.ts` 与 `src/commands/compact/compact.ts` — 手动 compact、summary prompt、compact boundary、prompt-too-long retry、compact 后 hook / attachment 恢复。
+- cc-haha 文档把高层压缩策略描述为四层：**snip**、**micro**、**context collapse**、**auto compact**。
+
+公开源码限制：
+
+- `snipCompact` 与 `contextCollapse` 在公开 tree 中是 feature-gated 引用；本次能看到集成点和行为目标，但看不到完整内部实现。因此本章里的 `snip_projection` 与 `context_collapse` 是教学等价实现，不声称逐行复刻。
+
+## 已对齐
+
+这些部分有意对齐 CC / cc-haha 公开可见的结构或行为。
+
+### 1. 压缩阶段顺序是显式的
+
+当前 s06 暴露同样的教学顺序：
+
+```python
+PIPELINE_STAGE_ORDER = (
+    "apply_tool_result_budget",
+    "snip_projection",
+    "microcompact_messages",
+    "context_collapse",
+    "auto_compact_if_needed",
+    "reactive_compact_on_overflow",
+)
+```
+
+这对齐了 cc-haha 的核心思想：压缩不是一次“神奇总结”，而是模型调用前的一组分阶段 context preparation pipeline。
+
+### 2. 大型 tool output 不直接污染 active context
+
+当前 s06 实现：
+
+```python
+apply_tool_result_budget()
+```
+
+已对齐行为：
+
+- 超预算的 tool output 会被持久化到 active context 之外；
+- 模型可见内容变成 `<persisted-output>` preview marker；
+- replacement decision 按 tool call id 记录；
+- 重复 pipeline pass 会复用之前的 replacement decision。
+
+这对齐 cc-haha 的大型输出持久化与单轮 message budget 策略；区别是我们使用小型本地教学存储路径，而不是生产级 session storage infrastructure。
+
+### 3. 旧 tool result 可以 microcompact
+
+当前 s06 实现：
+
+```python
+microcompact_messages()
+```
+
+已对齐行为：
+
+- 只处理 compactable tools；
+- 保留最近的 tool results；
+- 更旧的 tool results 被替换成 placeholder；
+- microcompact boundary 记录发生了什么。
+
+这对齐 cc-haha microcompact 的核心目标：避免旧工具输出持续占用模型上下文。
+
+### 4. Auto compact 由阈值触发
+
+当前 s06 实现：
+
+```python
+auto_compact_if_needed()
+```
+
+已对齐行为：
+
+- 估算 model-facing context size；
+- 超过阈值后 compact；
+- 生成 summary；
+- 保留 recent context；
+- 记录 compact boundary。
+
+这对齐 cc-haha auto compact 的目的。测试中使用 deterministic summarizer 代替 live model call。
+
+### 5. Overflow recovery 先尝试 collapse，再 full compact
+
+当前 s06 实现：
+
+```python
+reactive_compact_on_overflow()
+```
+
+已对齐行为：
+
+```text
+prompt/context overflow
+  -> 先尝试 drain staged collapse
+  -> 如果仍然太大，再 reactive full compact
+```
+
+这对齐 cc-haha prompt-too-long recovery 的恢复形状：优先 drain staged collapse，再 fallback 到 reactive compact。
+
+### 6. 压缩状态保留可恢复元数据
+
+当前 s06 使用 typed state：
+
+- `ContextCompressionState`
+- `ContextMessage`
+- `PersistedOutput`
+- `CompactBoundary`
+- summaries
+- transitions
+
+这对齐 CC 的重要原则：压缩不能只是静默删除历史，而要留下可恢复、可解释的元数据。
+
+## 部分对齐 / 教学等价
+
+### 1. Snip projection
+
+当前 s06 实现：
+
+```python
+snip_projection()
+```
+
+它建模的是：
+
+- canonical history 保留在 `state.messages`；
+- `state.model_messages` 变成更小的 model-facing view；
+- snip boundary 记录这次 projection。
+
+为什么只是部分对齐：
+
+- 公开 cc-haha 源码能看到 snip 的集成点，但看不到完整 `snipCompact` 实现；
+- 我们的版本是根据可见目标做出的 LangChain-native 教学等价实现。
+
+### 2. Context collapse
+
+当前 s06 实现：
+
+```python
+context_collapse()
+```
+
+它建模的是：
+
+- 先总结更旧的 groups；
+- 保留最近 groups 的原文；
+- 保留 summary metadata；
+- recovery 可以在 reactive compact 前 drain staged collapse。
+
+为什么只是部分对齐：
+
+- 公开 cc-haha 源码能看到 `contextCollapse.applyCollapsesIfNeeded()` 与 `recoverFromOverflow()` 集成点，但看不到完整内部实现；
+- 我们的版本是 staged-summary 教学等价实现。
+
+### 3. LangChain-native message/state 边界
+
+当前 s06 使用 typed Python dataclasses 和小型 `build_agent()` surface。它比 cc-haha TypeScript runtime 小很多，但保留了最重要的 LangChain 侧边界：
+
+```text
+canonical history != model-facing projection
+```
+
+## 未对齐 / 有意不复制
+
+以下是 s06 当前没有实现的生产级 CC 细节。
+
+### 1. 真实 provider cache edits
+
+未复制：
+
+- Anthropic cache edit APIs；
+- `cache_deleted_input_tokens` accounting；
+- prompt-cache-preserving delete operations。
+
+原因：
+
+- provider cache edits 属于生产/runtime 基础设施；
+- 本章只需要教学核心行为：旧 tool result 可以变轻，同时保留可恢复性。
+
+### 2. 完整 `snipCompact` 内部算法
+
+未复制：
+
+- 精确 snip algorithm；
+- hidden feature-gated implementation details。
+
+原因：
+
+- 公开 cc-haha 源码中没有完整实现；
+- 当前使用诚实的教学等价实现。
+
+### 3. 完整 `contextCollapse` 内部算法
+
+未复制：
+
+- 精确 collapse store；
+- 完整 staged collapse commit log；
+- 生产级 collapse projection rules。
+
+原因：
+
+- 公开 cc-haha 源码中没有完整实现；
+- 当前实现的是可观察行为等价。
+
+### 4. Session memory compaction
+
+未复制：
+
+- session memory extraction；
+- `lastSummarizedMessageId`；
+- memory file truncation；
+- resumed-session compact path。
+
+原因：
+
+- 这属于后续 memory / product-runtime stage，不应该提前塞进 s06 教学版。
+
+### 5. Pre/Post compact hooks
+
+未复制：
+
+- PreCompact hooks；
+- PostCompact hooks；
+- SessionStart hook replay；
+- hook-provided summary instructions。
+
+原因：
+
+- hooks 是独立子系统；在 hook 章节/阶段前，不应提前拉进 s06。
+
+### 6. Prompt-cache-sharing fork
+
+未复制：
+
+- forked compact agent；
+- prompt-cache-sharing parameters；
+- streaming fallback retry loop。
+
+原因：
+
+- 这是生产优化，不是 deterministic teaching version 的必要条件。
+
+### 7. GrowthBook / telemetry / feature flags
+
+未复制：
+
+- remote config；
+- analytics events；
+- experiment gates；
+- circuit-break telemetry。
+
+原因：
+
+- 本地教学轨道不需要这些生产运营设施。
+
+### 8. 完整 token accounting 与 media recovery
+
+未复制：
+
+- 精确 tokenizer budgets；
+- image / document token handling；
+- media-size recovery；
+- model-specific context window logic。
+
+原因：
+
+- s06 使用 deterministic character-count budgets，使测试保持 no-network 且稳定。
+
+### 9. 完整 UI / transcript restore 系统
+
+未复制：
+
+- compact boundary UI components；
+- transcript segment storage；
+- recent file restore attachments；
+- plan / skills / background-agent rehydration attachments。
+
+原因：
+
+- 这些属于 product UI / runtime persistence 关注点。s06 只记录 compact boundaries、persisted outputs、summaries、transitions 作为教学底座。
+
+## 测试 / 证据
+
+当前 deterministic verification：
+
+```sh
+PYTHON_DOTENV_DISABLED=1 python -m pytest \
+  tests/test_s06_context_compact_baseline.py \
+  tests/test_deepagents_track_smoke.py \
+  tests/test_stage_track_capability_contract.py -q
+```
+
+期望结果：
+
+```text
+23 passed
+```
+
+完成时也使用过这些检查：
+
+```sh
+PYTHON_DOTENV_DISABLED=1 python -m py_compile agents_deepagents/*.py
+git diff --check
+git diff --name-only -- coding-deepgent
+```
+
+s06 baseline tests 断言：
+
+- source-backed / inferred / simplification metadata 存在；
+- oversized tool output 会被持久化并替换成 marker；
+- replacement decisions 会被复用；
+- snip projection 会缩小 model-facing context，同时保留 canonical history；
+- microcompact 会保留最近 tool results 并清理更旧结果；
+- context collapse 会总结 older groups 并保留 recent groups；
+- auto compact 会生成 summary + recent context；
+- reactive compact 会记录 collapse-before-reactive transition order；
+- s06 是 stage gating 中第一个暴露 `compact` capability 的章节。
+
+## 下一步对齐候选
+
+未来不要随意往 s06 增加细节。最有价值的下一步，是把 context compression 接到其他 runtime state。
+
+1. **TodoWrite preservation**
+   - product compact 应该保留当前 `todos`、active todo、最近 completed/pending context。
+2. **Subagent boundaries**
+   - 决定 child agent 是继承 parent compression state，还是拥有自己的 isolated context。
+3. **Skill state**
+   - compact 时保留 invoked skill metadata / content。
+4. **Session memory**
+   - 只有 memory chapter / product stage 进入范围后，再加入真实 memory extraction / resumed-session compact。
+5. **Hooks**
+   - 只有 hook system 进入范围后，再加入 PreCompact / PostCompact 行为。
+6. **Product migration**
+   - 如果要迁入 `coding-deepgent/`，必须另写 product-stage plan；不要把教程模块直接复制成 production runtime。
diff --git a/agents_deepagents/common.py b/agents_deepagents/common.py
new file mode 100644
index 000000000..a4f8ecf90
--- /dev/null
+++ b/agents_deepagents/common.py
@@ -0,0 +1,270 @@
+#!/usr/bin/env python3
+"""Shared helpers for the Deep Agents s01-s06 teaching track.
+
+This module intentionally stays tiny.  The chapter files should still be read
+as the teaching surface; the shared code only avoids repeating the same safe
+file tools and OpenAI-compatible model setup in every script.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+from typing import Any, Iterable
+
+from langchain.tools import tool
+
+try:
+    from dotenv import load_dotenv
+except ImportError:
+    load_dotenv = None
+
+if load_dotenv is not None:
+    load_dotenv(override=True)
+
+WORKDIR = Path.cwd()
+DEFAULT_OPENAI_MODEL = "gpt-4.1-mini"
+OUTPUT_LIMIT = 50_000
+DANGEROUS_COMMANDS = ("rm -rf /", "sudo", "shutdown", "reboot", "> /dev/")
+
+
+def deepagents_model_name() -> str:
+    """Return the model name for the Deep Agents track.
+
+    ``OPENAI_MODEL`` is the explicit Deep Agents-track variable.  ``MODEL_ID``
+    is accepted only as a compatibility fallback when it does not look like an
+    Anthropic model from the original ``agents/`` track.
+    """
+
+    openai_model = os.getenv("OPENAI_MODEL", "").strip()
+    if openai_model:
+        return openai_model
+
+    legacy_model = os.getenv("MODEL_ID", "").strip()
+    if legacy_model and not legacy_model.lower().startswith("claude"):
+        return legacy_model
+
+    return DEFAULT_OPENAI_MODEL
+
+
+# Backward-compatible alias while the track rename propagates through tests and
+# external notes.
+langchain_model_name = deepagents_model_name
+
+
+def build_openai_model(*, temperature: float = 0.0, timeout: int = 60):
+    """Build a ChatOpenAI model lazily.
+
+    Importing chapter modules should never require credentials.  The API key is
+    checked only when a demo is actually run.
+    """
+
+    if not os.getenv("OPENAI_API_KEY"):
+        raise RuntimeError(
+            "OPENAI_API_KEY is required to run the Deep Agents examples. "
+            "Set OPENAI_MODEL to choose a model and OPENAI_BASE_URL for an "
+            "OpenAI-compatible endpoint."
+        )
+
+    from langchain_openai import ChatOpenAI
+
+    kwargs: dict[str, Any] = {
+        "model": deepagents_model_name(),
+        "temperature": temperature,
+        "timeout": timeout,
+    }
+    base_url = os.getenv("OPENAI_BASE_URL")
+    if base_url:
+        kwargs["base_url"] = base_url
+    return ChatOpenAI(**kwargs)
+
+
+def create_agent_runtime(system_prompt: str, tools: Iterable[Any]):
+    """Create the stage-track agent with the current OpenAI-style model."""
+
+    from langchain.agents import create_agent
+
+    return create_agent(
+        model=build_openai_model(),
+        tools=list(tools),
+        system_prompt=system_prompt,
+    )
+
+
+def safe_path(path_str: str) -> Path:
+    """Resolve a path inside the current workspace, rejecting escapes."""
+
+    path = (WORKDIR / path_str).resolve()
+    if not path.is_relative_to(WORKDIR):
+        raise ValueError(f"Path escapes workspace: {path_str}")
+    return path
+
+
+def _bash_impl(command: str) -> str:
+    """Implementation helper for the bash tool."""
+
+    if any(item in command for item in DANGEROUS_COMMANDS):
+        return "Error: Dangerous command blocked"
+    try:
+        result = subprocess.run(
+            command,
+            shell=True,
+            cwd=WORKDIR,
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+    except subprocess.TimeoutExpired:
+        return "Error: Timeout (120s)"
+    except (FileNotFoundError, OSError) as exc:
+        return f"Error: {exc}"
+
+    output = (result.stdout + result.stderr).strip()
+    return output[:OUTPUT_LIMIT] if output else "(no output)"
+
+
+def read_file_content(path: str, limit: int | None = None) -> str:
+    """Read a workspace file, optionally limiting returned lines."""
+
+    try:
+        lines = safe_path(path).read_text(encoding="utf-8").splitlines()
+        if limit and limit < len(lines):
+            lines = lines[:limit] + [f"... ({len(lines) - limit} more lines)"]
+        return "\n".join(lines)[:OUTPUT_LIMIT]
+    except Exception as exc:  # teaching tool: report errors as tool output
+        return f"Error: {exc}"
+
+
+def _write_file_impl(path: str, content: str) -> str:
+    """Implementation helper for the write_file tool."""
+
+    try:
+        file_path = safe_path(path)
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_path.write_text(content, encoding="utf-8")
+        return f"Wrote {len(content)} bytes to {path}"
+    except Exception as exc:
+        return f"Error: {exc}"
+
+
+def _edit_file_impl(path: str, old_text: str, new_text: str) -> str:
+    """Implementation helper for the edit_file tool."""
+
+    try:
+        file_path = safe_path(path)
+        content = file_path.read_text(encoding="utf-8")
+        if old_text not in content:
+            return f"Error: Text not found in {path}"
+        file_path.write_text(
+            content.replace(old_text, new_text, 1),
+            encoding="utf-8",
+        )
+        return f"Edited {path}"
+    except Exception as exc:
+        return f"Error: {exc}"
+
+
+@tool("bash")
+def bash(command: str) -> str:
+    """Run a shell command in the current workspace."""
+
+    return _bash_impl(command)
+
+
+@tool("read_file")
+def read_file(path: str, limit: int | None = None) -> str:
+    """Read a workspace file, optionally limiting returned lines."""
+
+    return read_file_content(path, limit)
+
+
+@tool("write_file")
+def write_file(path: str, content: str) -> str:
+    """Write content to a workspace file."""
+
+    return _write_file_impl(path, content)
+
+
+@tool("edit_file")
+def edit_file(path: str, old_text: str, new_text: str) -> str:
+    """Replace one exact text fragment in a workspace file."""
+
+    return _edit_file_impl(path, old_text, new_text)
+
+
+def _message_content(message: Any) -> Any:
+    if isinstance(message, dict):
+        return message.get("content", "")
+    return getattr(message, "content", "")
+
+
+def extract_text(content: Any) -> str:
+    """Extract readable text from Deep Agents or dict message content."""
+
+    if content is None:
+        return ""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        texts: list[str] = []
+        for block in content:
+            if isinstance(block, dict):
+                if (
+                    block.get("type") in {"text", "output_text"}
+                    and block.get("text")
+                ):
+                    texts.append(str(block["text"]))
+                elif block.get("content"):
+                    texts.append(str(block["content"]))
+                continue
+            text = getattr(block, "text", None)
+            if text:
+                texts.append(str(text))
+        return "\n".join(texts).strip()
+
+    text_attr = getattr(content, "text", None)
+    if isinstance(text_attr, str):
+        return text_attr.strip()
+    if callable(text_attr):
+        try:
+            return str(text_attr()).strip()
+        except TypeError:
+            pass
+    return str(content).strip()
+
+
+def latest_assistant_text(result: Any) -> str:
+    """Return the final assistant text from an agent/model result."""
+
+    if isinstance(result, dict):
+        messages = result.get("messages") or []
+        for message in reversed(messages):
+            role = (
+                message.get("role")
+                if isinstance(message, dict)
+                else getattr(message, "type", "")
+            )
+            if role in {"assistant", "ai"}:
+                text = extract_text(_message_content(message))
+                if text:
+                    return text
+        if messages:
+            return extract_text(_message_content(messages[-1]))
+    return extract_text(_message_content(result))
+
+
+def invoke_and_append(agent: Any, messages: list[dict[str, Any]]) -> str:
+    """Invoke a Deep Agents agent and append only the final answer to history.
+
+    Deep Agents owns the internal model -> tool -> tool-result loop. For the
+    next CLI turn we keep a compact teaching history: the user's prompt plus
+    the final assistant answer, while the original ``agents/`` files remain
+    the place to inspect every raw provider block.
+    """
+
+    result = agent.invoke({"messages": messages})
+    final_text = latest_assistant_text(result)
+    if final_text:
+        messages.append({"role": "assistant", "content": final_text})
+    return final_text
diff --git a/agents_deepagents/s01_agent_loop.py b/agents_deepagents/s01_agent_loop.py
new file mode 100644
index 000000000..080c6aeaa
--- /dev/null
+++ b/agents_deepagents/s01_agent_loop.py
@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+# Deep Agents track: the framework-owned loop -- model, tool, result, repeat.
+"""
+s01_agent_loop.py - The Agent Loop with Deep Agents
+
+The original ``agents/s01_agent_loop.py`` hand-writes every provider turn. This
+parallel version uses the same ``create_agent`` loop that underpins the staged
+Deep Agents track. The important comparison: the track runtime now owns the
+repeated model -> tool -> tool-result loop, while this
+harness still owns the user history, workspace tool, and CLI boundary.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+try:
+    from .common import WORKDIR, bash, create_agent_runtime, extract_text, invoke_and_append
+except ImportError:  # direct script execution: python agents_deepagents/s01_agent_loop.py
+    from common import WORKDIR, bash, create_agent_runtime, extract_text, invoke_and_append
+
+SYSTEM = (
+    f"You are a coding agent at {WORKDIR}. "
+    "Use bash to inspect and change the workspace. Act first, then report clearly."
+)
+TOOLS = [bash]
+
+
+@dataclass
+class LoopState:
+    # The visible harness state is still small: history and why the harness continues.
+    messages: list[dict[str, Any]] = field(default_factory=list)
+    turn_count: int = 1
+    transition_reason: str | None = None
+
+
+def build_agent():
+    """Create the stage-track agent that owns the inner model/tool loop."""
+
+    return create_agent_runtime(SYSTEM, TOOLS)
+
+
+def agent_loop(state: LoopState) -> str:
+    final_text = invoke_and_append(build_agent(), state.messages)
+    state.turn_count += 1
+    state.transition_reason = "langchain_agent_completed"
+    return final_text
+
+
+if __name__ == "__main__":
+    history: list[dict[str, Any]] = []
+    while True:
+        try:
+            query = input("\033[36ms01-lc >> \033[0m")
+        except (EOFError, KeyboardInterrupt):
+            break
+        if query.strip().lower() in ("q", "exit", ""):
+            break
+
+        history.append({"role": "user", "content": query})
+        state = LoopState(messages=history)
+        try:
+            final = agent_loop(state)
+        except RuntimeError as exc:
+            print(f"Error: {exc}")
+            continue
+        print(extract_text(final) or "(no response)")
+        print()
diff --git a/agents_deepagents/s02_tool_use.py b/agents_deepagents/s02_tool_use.py
new file mode 100644
index 000000000..837144fe9
--- /dev/null
+++ b/agents_deepagents/s02_tool_use.py
@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+# Deep Agents track: tool dispatch -- expanding what the agent can reach.
+"""
+s02_tool_use.py - Tool dispatch with Deep Agents
+
+The original chapter adds read/write/edit tools without changing the visible
+harness. This stage keeps the same lesson: the runtime owns the inner
+model -> tool -> result loop, while the chapter wrapper stays thin and the tool
+surface is unchanged.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from langchain.agents import create_agent
+from langchain.agents.middleware import AgentMiddleware, ModelRequest, ModelResponse
+from langchain.messages import SystemMessage
+
+try:
+    from .common import (
+        WORKDIR,
+        bash,
+        build_openai_model,
+        edit_file,
+        extract_text,
+        latest_assistant_text,
+        read_file,
+        write_file,
+    )
+except ImportError:
+    from common import (
+        WORKDIR,
+        bash,
+        build_openai_model,
+        edit_file,
+        extract_text,
+        latest_assistant_text,
+        read_file,
+        write_file,
+    )
+
+SYSTEM = f"You are a coding agent at {WORKDIR}. Use tools to solve tasks. Act, don't explain."
+
+# Read-only tools can safely run in parallel; mutating tools must be serialized.
+CONCURRENCY_SAFE = {"read_file"}
+CONCURRENCY_UNSAFE = {"write_file", "edit_file"}
+TOOLS = [bash, read_file, write_file, edit_file]
+
+
+class ToolUseMiddleware(AgentMiddleware):
+    """Keep the s02 lesson explicit without adding chapter-specific state."""
+
+    def wrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], ModelResponse],
+    ) -> ModelResponse:
+        new_content = list(request.system_message.content_blocks) + [
+            {
+                "type": "text",
+                "text": (
+                    "Stage s02: the runtime owns the repeated model-tool loop. "
+                    "This chapter only expands the available tool surface. "
+                    f"Visible merged history count: {len(request.messages)}."
+                ),
+            }
+        ]
+        return handler(
+            request.override(system_message=SystemMessage(content=new_content))
+        )
+
+
+def normalize_messages(messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Keep only provider-facing message fields and merge consecutive roles."""
+
+    cleaned: list[dict[str, Any]] = []
+    for message in messages:
+        role = message.get("role", "user")
+        content = message.get("content", "")
+        cleaned.append({"role": role, "content": content})
+
+    if not cleaned:
+        return cleaned
+
+    merged = [cleaned[0]]
+    for message in cleaned[1:]:
+        if message["role"] == merged[-1]["role"]:
+            merged[-1]["content"] = f"{merged[-1]['content']}\n\n{message['content']}"
+        else:
+            merged.append(message)
+    return merged
+
+
+def build_agent():
+    return create_agent(
+        model=build_openai_model(),
+        tools=TOOLS,
+        system_prompt=SYSTEM,
+        middleware=[ToolUseMiddleware()],
+    )
+
+
+def agent_loop(messages: list[dict[str, Any]]) -> str:
+    normalized = normalize_messages(messages)
+    result = build_agent().invoke({"messages": normalized})
+    final_text = latest_assistant_text(result)
+    if final_text:
+        messages.append({"role": "assistant", "content": final_text})
+    return final_text
+
+
+if __name__ == "__main__":
+    history: list[dict[str, Any]] = []
+    while True:
+        try:
+            query = input("\033[36ms02-lc >> \033[0m")
+        except (EOFError, KeyboardInterrupt):
+            break
+        if query.strip().lower() in ("q", "exit", ""):
+            break
+
+        history.append({"role": "user", "content": query})
+        try:
+            final = agent_loop(history)
+        except RuntimeError as exc:
+            print(f"Error: {exc}")
+            continue
+        print(extract_text(final) or "(no response)")
+        print()
diff --git a/agents_deepagents/s03_todo_write.py b/agents_deepagents/s03_todo_write.py
new file mode 100644
index 000000000..3ba0e753b
--- /dev/null
+++ b/agents_deepagents/s03_todo_write.py
@@ -0,0 +1,463 @@
+#!/usr/bin/env python3
+# Deep Agents track: planning -- keep session plan state outside the model's head.
+"""
+s03_todo_write.py - Session Planning with Deep Agents tools
+
+This is the first chapter where custom state becomes natural. The session plan
+belongs in explicit runtime state, not in the model's hidden chain-of-thought.
+Middleware renders that state back into the prompt, and the write_plan tool updates it
+through LangChain state updates.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Annotated, Any, Literal
+
+from langchain.agents import AgentState, create_agent
+from langchain.agents.middleware import AgentMiddleware, ModelRequest, ModelResponse
+from langchain.messages import AIMessage, SystemMessage, ToolMessage
+from langchain.tools.tool_node import ToolCallRequest
+from langchain.tools import InjectedToolCallId, tool
+from langgraph.types import Command
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+from typing_extensions import NotRequired, TypedDict
+
+try:
+    from .common import (
+        WORKDIR,
+        bash,
+        build_openai_model,
+        edit_file,
+        extract_text,
+        latest_assistant_text,
+        read_file,
+        write_file,
+    )
+except ImportError:
+    from common import (
+        WORKDIR,
+        bash,
+        build_openai_model,
+        edit_file,
+        extract_text,
+        latest_assistant_text,
+        read_file,
+        write_file,
+    )
+
+PLAN_REMINDER_INTERVAL = 3
+SYSTEM = f"""You are a coding agent at {WORKDIR}.
+Use the write_plan tool for complex multi-step work when explicit progress tracking is helpful.
+Skip the write_plan tool for simple, trivial, or purely conversational requests that can be completed directly.
+When a task genuinely needs a plan, call write_plan before other tools and write the full current plan.
+Each plan item must include non-empty content; use pending, in_progress, or completed status.
+Keep exactly one step in_progress while unfinished work remains.
+Mark steps completed as soon as they are actually done; if blocked, leave the current step in_progress or rewrite the plan.
+Revise the plan list as new information appears, remove stale steps, and add newly discovered necessary steps.
+Never call write_plan multiple times in parallel within the same response.
+Refresh the plan as work advances. Prefer tools over prose."""
+
+# 项目约束（给维护者读）：
+# - write_plan 是 LangChain tool calling 的结构化工具入参，不是最终回答 JSON。
+# - 工具入参必须通过 Pydantic args_schema 暴露 required / enum / extra-forbid
+#   约束；不要退回 list[dict[str, Any]] 让模型自由填对象。
+# - 不在 Python 侧兜底猜 task/step/done/doing 等别名；错 JSON 应由 schema 暴露。
+# - 如果以后新增 write_plan JSON 字段，先改 PlanItemInput / WritePlanInput 和测试。
+# - with_structured_output()/response_format 只用于最终结构化回答，不用于这种
+#   需要写入 LangGraph state 的工具参数。
+# - 当前 write_plan 工具只需要 `items` 和 `tool_call_id`，不读取 runtime.state/context/store。
+# - 按 LangChain 官方 planning/todo middleware 风格，用 InjectedToolCallId 注入当前调用 id。
+# - 为了同时保留显式 args_schema 和隐藏注入字段，WritePlanInput 内部包含
+#   `tool_call_id: Annotated[str | None, InjectedToolCallId] = None`；
+#   它不会出现在模型可见的 tool_call_schema 中，但工具执行时会被注入。
+
+
+class PlanItemState(TypedDict):
+    """运行时保存的单条计划状态。
+
+    这是 agent state 里的内部格式，渲染器和 middleware 都读取这个结构。
+    它和 PlanItemInput 字段保持一致，但它是普通 dict，方便写入
+    LangGraph state。
+    """
+
+    content: str
+    status: Literal["pending", "in_progress", "completed"]
+    activeForm: NotRequired[str]
+
+
+class PlanningState(AgentState):
+    """s03 给 LangChain agent 增加的自定义短期状态。
+
+    AgentState 已经包含 messages；这里额外保存：
+    - items: 当前会话计划。
+    - rounds_since_update: 计划多久没被 write_plan 工具刷新，用于触发提醒。
+    """
+
+    items: NotRequired[list[PlanItemState]]
+    rounds_since_update: NotRequired[int]
+
+
+# 注意：
+# PlanItemInput / WritePlanInput 是 args_schema 的一部分，Pydantic class docstring
+# 可能进入模型可见的 JSON schema description。
+# 所以这里不给这两个 schema class 写面向维护者的长 docstring；人类说明放在
+# 上方注释里，模型说明放在 Field(description=...) 和 tool(description=...)。
+class PlanItemInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    content: str = Field(
+        ...,
+        min_length=1,
+        description="Non-empty description of this plan step.",
+    )
+    status: Literal["pending", "in_progress", "completed"] = Field(
+        ...,
+        description="Current step status. Exactly one item should be in_progress.",
+    )
+    activeForm: str | None = Field(
+        default=None,
+        description="Short gerund phrase shown only for the in_progress step.",
+    )
+
+    @field_validator("content")
+    @classmethod
+    def _content_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("content required")
+        return value
+
+    @field_validator("activeForm")
+    @classmethod
+    def _active_form_must_not_be_blank(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        value = value.strip()
+        return value or None
+
+
+class WritePlanInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    items: list[PlanItemInput] = Field(
+        ...,
+        min_length=1,
+        max_length=12,
+        description=(
+            "Complete current plan. Every item must have content and status; "
+            "use pending, in_progress, or completed."
+        ),
+    )
+    tool_call_id: Annotated[str | None, InjectedToolCallId] = None
+
+
+def normalize_plan_items(
+    items: list[PlanItemInput | dict[str, Any]],
+) -> list[PlanItemState]:
+    """把 write_plan 工具入参转换成 LangGraph state 可保存的普通 dict。
+
+    这一步做三件事：
+    1. `WritePlanInput(items=items)` 触发 Pydantic 校验，确保 JSON 结构符合
+       LangChain tool schema。
+    2. 将 Pydantic 对象转成 PlanItemState 普通 dict，方便写入 state 和渲染。
+    3. 额外检查最多只能有一个 in_progress，避免模型同时标记多个当前步骤。
+    """
+
+    validated = WritePlanInput(items=items)
+
+    normalized: list[PlanItemState] = []
+    in_progress_count = 0
+    for item_input in validated.items:
+        if item_input.status == "in_progress":
+            in_progress_count += 1
+
+        item: PlanItemState = {
+            "content": item_input.content,
+            "status": item_input.status,
+        }
+        if item_input.activeForm:
+            item["activeForm"] = item_input.activeForm
+        normalized.append(item)
+
+    if in_progress_count > 1:
+        raise ValueError("Only one plan item can be in_progress")
+
+    return normalized
+
+
+def render_plan_items(items: list[PlanItemState]) -> str:
+    """把当前计划渲染成终端可读文本。"""
+
+    if not items:
+        return "No session plan yet."
+
+    lines: list[str] = []
+    for item in items:
+        marker = {"pending": "[ ]", "in_progress": "[>]", "completed": "[x]"}[
+            item["status"]
+        ]
+        line = f"{marker} {item['content']}"
+        active_form = item.get("activeForm", "")
+        if item["status"] == "in_progress" and active_form:
+            line += f" ({active_form})"
+        lines.append(line)
+
+    completed = sum(1 for item in items if item["status"] == "completed")
+    lines.append(f"\n({completed}/{len(items)} completed)")
+    return "\n".join(lines)
+
+
+def reminder_text(
+    items: list[PlanItemState],
+    rounds_since_update: int,
+) -> str | None:
+    """当计划连续多轮未更新时，生成注入给模型的提醒文本。"""
+
+    if not items:
+        return None
+    if rounds_since_update < PLAN_REMINDER_INTERVAL:
+        return None
+    return "<reminder>Refresh your current plan before continuing.</reminder>"
+
+
+def _write_plan_command(
+    items: list[PlanItemInput],
+    tool_call_id: str | None = None,
+) -> Command:
+    """write_plan 工具实现：把模型给出的计划写回 LangGraph state。
+
+    返回 Command(update=...) 是 LangGraph/LangChain 的状态更新方式：
+    - items 写入当前会话计划；
+    - rounds_since_update 重置为 0；
+    - ToolMessage 把渲染后的计划作为工具结果返回给模型。
+
+    这里不再依赖 ToolRuntime，因为这个工具并不读取 runtime 的其他内容；
+    它只需要当前这次 tool call 的 id，用于构造 ToolMessage。
+    """
+
+    if tool_call_id is None:
+        raise ValueError("tool_call_id is required for write_plan tool execution")
+
+    normalized = normalize_plan_items(items)
+    rendered = render_plan_items(normalized)
+    return Command(
+        update={
+            "items": normalized,
+            "rounds_since_update": 0,
+            "messages": [
+                ToolMessage(content=rendered, tool_call_id=tool_call_id)
+            ],
+        }
+    )
+
+
+@tool(
+    "write_plan",
+    args_schema=WritePlanInput,
+    description=(
+        "Create or replace the visible session plan for complex multi-step work. "
+        "Use it when a task needs explicit planning, progress tracking, or later "
+        "revision; skip it for simple one-step or purely conversational requests. "
+        "Input must be the full current plan as JSON items[]. Each item requires "
+        "content and status (pending, in_progress, or completed), and exactly one "
+        "item should stay in_progress while work remains."
+    ),
+)
+def write_plan(
+    items: list[PlanItemInput],
+    tool_call_id: str | None = None,
+) -> Command:
+    """Create or replace the visible session plan for complex multi-step work."""
+
+    return _write_plan_command(items, tool_call_id)
+
+
+write_plan_tool = write_plan
+
+TOOLS = [bash, read_file, write_file, edit_file, write_plan]
+
+
+class PlanContextMiddleware(AgentMiddleware[PlanningState]):
+    """把计划状态接回每一轮模型调用。
+
+    write_plan 工具负责“写计划”；middleware 负责“读计划并注入 prompt”。
+    这样模型下一轮会看到 Current session plan，而不是只把计划藏在 Python state。
+    """
+
+    state_schema = PlanningState
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._updated_this_turn = False
+
+    def before_agent(self, state: PlanningState, runtime) -> dict[str, Any] | None:
+        """每次 agent invocation 开始时补齐 s03 自定义 state 默认值。"""
+
+        self._updated_this_turn = False
+        return {
+            key: value
+            for key, value in (("items", []), ("rounds_since_update", 0))
+            if key not in state
+        } or None
+
+    def wrap_tool_call(self, request: ToolCallRequest, handler: Callable):
+        """包住工具调用，用来记录本轮是否调用过 write_plan。"""
+
+        if request.tool_call["name"] == "write_plan":
+            self._updated_this_turn = True
+        return handler(request)
+
+    def wrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], ModelResponse],
+    ) -> ModelResponse:
+        """每次模型调用前，把当前计划追加到 system message。
+
+        request.system_message.content_blocks 是 LangChain 官方的消息块接口。
+        这里追加 text block，让模型在下一次思考时看到最新计划和过期提醒。
+        """
+
+        items = request.state.get("items", [])
+        rounds_since_update = request.state.get("rounds_since_update", 0)
+        extra_blocks: list[dict[str, str]] = []
+
+        if items:
+            extra_blocks.append(
+                {
+                    "type": "text",
+                    "text": "Current session plan:\n" + render_plan_items(items),
+                }
+            )
+            reminder = reminder_text(items, rounds_since_update)
+            if reminder:
+                extra_blocks.append({"type": "text", "text": reminder})
+
+        if not extra_blocks:
+            return handler(request)
+
+        return handler(
+            request.override(
+                system_message=SystemMessage(
+                    content=[*request.system_message.content_blocks, *extra_blocks]
+                )
+            )
+        )
+
+    def after_model(self, state: PlanningState, runtime) -> dict[str, Any] | None:
+        """拒绝同一轮里并行多次调用 write_plan。
+
+        write_plan 会整体替换当前计划，所以一条 AIMessage 里如果同时出现多个 write_plan
+        tool call，会产生“哪个计划才算最终版本”的歧义。这里沿用 LangChain
+        官方 planning/todo middleware 的思路，在工具真正执行前直接返回错误 ToolMessage。
+        """
+
+        messages = state.get("messages", [])
+        if not messages:
+            return None
+
+        last_ai_message = next(
+            (message for message in reversed(messages) if isinstance(message, AIMessage)),
+            None,
+        )
+        if last_ai_message is None or not last_ai_message.tool_calls:
+            return None
+
+        write_plan_calls = [call for call in last_ai_message.tool_calls if call["name"] == "write_plan"]
+        if len(write_plan_calls) <= 1:
+            return None
+
+        return {
+            "messages": [
+                ToolMessage(
+                    content=(
+                        "Error: The `write_plan` tool should never be called multiple times in "
+                        "parallel. Call it once per model response so the session plan has "
+                        "one unambiguous replacement."
+                    ),
+                    tool_call_id=call["id"],
+                    status="error",
+                )
+                for call in write_plan_calls
+            ]
+        }
+
+    def after_agent(self, state: PlanningState, runtime) -> dict[str, Any] | None:
+        """本轮结束后维护 stale counter。
+
+        如果本轮调用过 write_plan，计划刚刷新，不增加计数；否则只要已有计划，
+        rounds_since_update 就加一，后续达到阈值会触发 reminder_text。
+        """
+
+        if self._updated_this_turn:
+            return None
+        if state.get("items"):
+            return {"rounds_since_update": state.get("rounds_since_update", 0) + 1}
+        return None
+
+
+SESSION_STATE: dict[str, Any] = {
+    "items": [],
+    "rounds_since_update": 0,
+}
+
+
+def build_agent():
+    """创建 s03 agent，并注册带 args_schema 的 write_plan_tool。"""
+
+    return create_agent(
+        model=build_openai_model(),
+        tools=TOOLS,
+        system_prompt=SYSTEM,
+        middleware=[PlanContextMiddleware()],
+    )
+
+
+def agent_loop(messages: list[dict[str, Any]]) -> str:
+    """推进一轮对话，并把 LangGraph 返回的计划状态同步回 SESSION_STATE。"""
+
+    result = build_agent().invoke({"messages": list(messages), **SESSION_STATE})
+    SESSION_STATE.update(
+        {
+            "items": result.get("items", []),
+            "rounds_since_update": result.get("rounds_since_update", 0),
+        }
+    )
+    final_text = latest_assistant_text(result)
+    if final_text:
+        messages.append({"role": "assistant", "content": final_text})
+    return final_text
+
+
+def current_plan_text() -> str | None:
+    """给 CLI 使用：如果当前已有计划，就返回可打印的终端计划文本。"""
+
+    items = SESSION_STATE.get("items") or []
+    if not items:
+        return None
+    return render_plan_items(items)
+
+
+if __name__ == "__main__":
+    history: list[dict[str, Any]] = []
+    while True:
+        try:
+            query = input("\033[36ms03-lc >> \033[0m")
+        except (EOFError, KeyboardInterrupt):
+            break
+        if query.strip().lower() in ("q", "exit", ""):
+            break
+
+        history.append({"role": "user", "content": query})
+        try:
+            final = agent_loop(history)
+        except RuntimeError as exc:
+            print(f"Error: {exc}")
+            continue
+        print(extract_text(final) or "(no response)")
+        plan_text = current_plan_text()
+        if plan_text:
+            print("\nCurrent session plan:")
+            print(plan_text)
+        print()
diff --git a/agents_deepagents/s04_subagent.py b/agents_deepagents/s04_subagent.py
new file mode 100644
index 000000000..8faf69b71
--- /dev/null
+++ b/agents_deepagents/s04_subagent.py
@@ -0,0 +1,282 @@
+#!/usr/bin/env python3
+# Deep Agents track: context isolation -- a child agent gets fresh messages.
+"""
+s04_subagent.py - Subagents with Deep Agents
+
+This chapter keeps the original lesson -- delegate a context-heavy side task and
+return only a short summary -- but now uses Deep Agents' native task/subagent
+middleware instead of a handwritten nested agent loop.
+
+Mapping bridge from the original tutorial:
+- original `run_subagent(prompt)` -> Deep Agents `task(description, subagent_type)`
+- original local `sub_messages = [...]` -> middleware-managed fresh message context
+- original summary string -> child final message returned as the parent `ToolMessage`
+
+This file intentionally does not define `task`, `run_subagent`, `PARENT_TOOLS`,
+or `CHILD_TOOLS`; `SubAgentMiddleware` injects `task`, and the `SubAgent` spec
+controls the child's non-recursive tool surface.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from typing_extensions import TypedDict
+
+from deepagents.backends import StateBackend
+from deepagents.middleware.subagents import SubAgent, SubAgentMiddleware
+from langchain.agents import create_agent
+from langchain_core.language_models.chat_models import BaseChatModel
+
+try:
+    from .common import (
+        WORKDIR,
+        bash,
+        build_openai_model,
+        edit_file,
+        extract_text,
+        latest_assistant_text,
+        read_file,
+        write_file,
+    )
+except ImportError:
+    from common import (
+        WORKDIR,
+        bash,
+        build_openai_model,
+        edit_file,
+        extract_text,
+        latest_assistant_text,
+        read_file,
+        write_file,
+    )
+
+SYSTEM = (
+    f"You are a coding agent at {WORKDIR}. "
+    "Use the task tool when a subtask needs fresh context or would otherwise "
+    "bloat the main thread."
+)
+SUBAGENT_SYSTEM = (
+    f"You are a coding subagent at {WORKDIR}. "
+    "Complete the delegated task autonomously, then return a concise summary "
+    "of what you found or changed."
+)
+SUBAGENT_TYPE = "general-purpose"
+SUBAGENT_DESCRIPTION = (
+    "Fresh-context coding subagent for isolated exploration, editing, and "
+    "verification tasks. Return only a short summary to the parent agent."
+)
+
+# Base tools shared by the parent and explicitly granted to the child.
+# `task` is injected only into the parent by SubAgentMiddleware; leaving it out
+# here preserves the original s04 no-recursive-spawn child tool boundary.
+TOOLS = [bash, read_file, write_file, edit_file]
+
+
+class TaskActivity(TypedDict):
+    description: str
+    subagent_type: str
+    summary: str
+
+
+def _task_calls_from_message(message: Any) -> list[tuple[str, str, str]]:
+    """Return task-call metadata from one AI message.
+
+    This keeps the extractor focused on task semantics instead of repeatedly
+    branching over generic message attributes.
+    """
+
+    message_type = (
+        str(message.get("type") or message.get("role") or "")
+        if isinstance(message, dict)
+        else str(getattr(message, "type", ""))
+    )
+    if message_type != "ai":
+        return []
+
+    tool_calls = (
+        list(message.get("tool_calls") or [])
+        if isinstance(message, dict)
+        else list(getattr(message, "tool_calls", []) or [])
+    )
+    events: list[tuple[str, str, str]] = []
+    for tool_call in tool_calls:
+        if tool_call.get("name") != "task":
+            continue
+        args = tool_call.get("args") or {}
+        events.append(
+            (
+                str(tool_call.get("id") or ""),
+                str(args.get("description") or "").strip(),
+                str(args.get("subagent_type") or "").strip(),
+            )
+        )
+    return events
+
+
+def _task_result_from_message(message: Any) -> tuple[str, str] | None:
+    """Return the task tool-call id plus rendered summary from one tool message."""
+
+    message_type = (
+        str(message.get("type") or message.get("role") or "")
+        if isinstance(message, dict)
+        else str(getattr(message, "type", ""))
+    )
+    if message_type != "tool":
+        return None
+
+    tool_name = (
+        str(message.get("name") or "")
+        if isinstance(message, dict)
+        else str(getattr(message, "name", ""))
+    )
+    if tool_name != "task":
+        return None
+
+    tool_call_id = (
+        str(message.get("tool_call_id") or message.get("id") or "")
+        if isinstance(message, dict)
+        else str(getattr(message, "tool_call_id", "") or getattr(message, "id", ""))
+    )
+    content = message.get("content", "") if isinstance(message, dict) else getattr(message, "content", "")
+    return tool_call_id, extract_text(content)
+
+
+def extract_task_activity(result: dict[str, Any]) -> list[TaskActivity]:
+    """Extract task/subagent events as structured data.
+
+    This keeps UI concerns out of agent execution. The CLI can render these
+    events for terminal visibility now, and future frontends can present the
+    same structured activity differently without changing agent logic.
+    """
+
+    messages = result.get("messages") or []
+    pending_calls: dict[str, dict[str, str]] = {}
+    events: list[TaskActivity] = []
+
+    for message in messages:
+        task_calls = _task_calls_from_message(message)
+        if task_calls:
+            for tool_call_id, description, subagent_type in task_calls:
+                pending_calls[tool_call_id] = {
+                    "description": description,
+                    "subagent_type": subagent_type,
+                }
+            continue
+
+        task_result = _task_result_from_message(message)
+        if task_result is None:
+            continue
+
+        tool_call_id, summary = task_result
+        event_data = pending_calls.get(tool_call_id, {})
+        events.append(
+            {
+                "description": event_data.get("description", ""),
+                "subagent_type": event_data.get("subagent_type", ""),
+                "summary": summary,
+            }
+        )
+
+    return events
+
+
+def render_task_activity(events: list[TaskActivity]) -> list[str]:
+    """Render structured task activity for the terminal UI.
+
+    The terminal is only one presentation layer over task activity. Future UIs
+    can reuse ``extract_task_activity`` and replace this renderer.
+    """
+
+    lines: list[str] = []
+    for event in events:
+        subtype = f" ({event['subagent_type']})" if event["subagent_type"] else ""
+        description = event["description"] or "delegated subtask"
+        summary = event["summary"] or "(no summary)"
+        lines.append(f"> task{subtype}: {description}")
+        lines.append(f"  {summary}")
+    return lines
+
+
+def build_subagents(
+    model: BaseChatModel,
+) -> list[SubAgent]:
+    """Return the stage's available subagent specs.
+
+    The spec is the Deep Agents replacement for the original CHILD_TOOLS and
+    SUBAGENT_SYSTEM bundle. The child receives these tools and a fresh message
+    context internally; this is message-context isolation, not total process or
+    arbitrary runtime-state isolation.
+    """
+
+    return [
+        {
+            "name": SUBAGENT_TYPE,
+            "description": SUBAGENT_DESCRIPTION,
+            "system_prompt": SUBAGENT_SYSTEM,
+            "model": model,
+            "tools": TOOLS,
+        }
+    ]
+
+
+def build_agent(
+    *,
+    model: BaseChatModel | None = None,
+    subagent_model: BaseChatModel | None = None,
+):
+    """Build the parent agent with Deep Agents' native task tool.
+
+    SubAgentMiddleware maps the original parent `task(prompt)` idea to the
+    framework-managed `task(description, subagent_type)` tool and returns the
+    child final message as a parent-visible ToolMessage.
+    """
+
+    main_model = model or build_openai_model()
+    child_model = subagent_model or main_model
+    return create_agent(
+        model=main_model,
+        tools=TOOLS,
+        system_prompt=SYSTEM,
+        middleware=[
+            SubAgentMiddleware(
+                backend=StateBackend,
+                subagents=build_subagents(child_model),
+            )
+        ],
+    )
+
+
+def run_turn(messages: list[dict[str, Any]]) -> tuple[str, list[TaskActivity]]:
+    result = build_agent().invoke({"messages": messages})
+    final_text = latest_assistant_text(result)
+    if final_text:
+        messages.append({"role": "assistant", "content": final_text})
+    return final_text, extract_task_activity(result)
+
+
+def agent_loop(messages: list[dict[str, Any]]) -> str:
+    final_text, _ = run_turn(messages)
+    return final_text
+
+
+if __name__ == "__main__":
+    history: list[dict[str, Any]] = []
+    while True:
+        try:
+            query = input("\033[36ms04-lc >> \033[0m")
+        except (EOFError, KeyboardInterrupt):
+            break
+        if query.strip().lower() in ("q", "exit", ""):
+            break
+
+        history.append({"role": "user", "content": query})
+        try:
+            final, events = run_turn(history)
+        except RuntimeError as exc:
+            print(f"Error: {exc}")
+            continue
+        for line in render_task_activity(events):
+            print(line)
+        print(extract_text(final) or "(no response)")
+        print()
diff --git a/agents_deepagents/s05_skill_loading.py b/agents_deepagents/s05_skill_loading.py
new file mode 100644
index 000000000..e0330a75e
--- /dev/null
+++ b/agents_deepagents/s05_skill_loading.py
@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+# Deep Agents track: on-demand knowledge -- discover light, load deep.
+"""
+s05_skill_loading.py - Skills with Deep Agents
+
+The original chapter teaches progressive disclosure: keep a cheap skill catalog
+visible, then read the full skill instructions only when they are relevant.
+This version keeps that behavior but uses Deep Agents' native skills middleware
+instead of a custom ``load_skill`` tool.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain.tools import tool
+
+from deepagents.backends.filesystem import FilesystemBackend
+from deepagents.middleware.skills import SkillsMiddleware
+from langchain.agents import create_agent
+from langchain_core.language_models.chat_models import BaseChatModel
+
+try:
+    from .common import (
+        WORKDIR,
+        bash,
+        build_openai_model,
+        edit_file,
+        extract_text,
+        invoke_and_append,
+        read_file_content,
+        write_file,
+    )
+except ImportError:
+    from common import (
+        WORKDIR,
+        bash,
+        build_openai_model,
+        edit_file,
+        extract_text,
+        invoke_and_append,
+        read_file_content,
+        write_file,
+    )
+
+SKILL_SOURCE = "/skills"
+SYSTEM = f"""You are a coding agent at {WORKDIR}.
+Use the skills catalog when a task needs specialized instructions.
+When a skill looks relevant, read its SKILL.md path before following it."""
+
+
+def normalize_skill_path(path: str) -> str:
+    """Map Deep Agents' virtual skill paths onto the local workspace."""
+
+    if path.startswith("/skills/"):
+        return path[1:]
+    return path
+
+
+@tool("read_file")
+def read_file(path: str, limit: int | None = None) -> str:
+    """Read normal workspace files and SkillsMiddleware virtual skill paths."""
+
+    return read_file_content(normalize_skill_path(path), limit)
+
+
+TOOLS = [bash, read_file, write_file, edit_file]
+
+
+def build_agent(
+    *,
+    model: BaseChatModel | None = None,
+    backend: FilesystemBackend | None = None,
+    skill_sources: list[str] | None = None,
+):
+    """Build the agent with Deep Agents' skills middleware."""
+
+    return create_agent(
+        model=model or build_openai_model(),
+        tools=TOOLS,
+        system_prompt=SYSTEM,
+        middleware=[
+            SkillsMiddleware(
+                backend=backend
+                or FilesystemBackend(root_dir=WORKDIR, virtual_mode=True),
+                sources=skill_sources or [SKILL_SOURCE],
+            )
+        ],
+    )
+
+
+def agent_loop(messages: list[dict[str, Any]]) -> str:
+    return invoke_and_append(build_agent(), messages)
+
+
+if __name__ == "__main__":
+    history: list[dict[str, Any]] = []
+    while True:
+        try:
+            query = input("\033[36ms05-lc >> \033[0m")
+        except (EOFError, KeyboardInterrupt):
+            break
+        if query.strip().lower() in ("q", "exit", ""):
+            break
+
+        history.append({"role": "user", "content": query})
+        try:
+            final = agent_loop(history)
+        except RuntimeError as exc:
+            print(f"Error: {exc}")
+            continue
+        print(extract_text(final) or "(no response)")
+        print()
diff --git a/agents_deepagents/s06_context_compact.py b/agents_deepagents/s06_context_compact.py
new file mode 100644
index 000000000..a346f250d
--- /dev/null
+++ b/agents_deepagents/s06_context_compact.py
@@ -0,0 +1,800 @@
+#!/usr/bin/env python3
+# Deep Agents track: context compression -- keep canonical history, shrink model-facing context.
+"""
+s06_context_compact.py - cc-haha-inspired context compression with LangChain concepts.
+
+This chapter teaches a six-stage pipeline modeled on the public Claude Code /
+cc-haha compression flow:
+
+1. apply_tool_result_budget
+2. snip_projection
+3. microcompact_messages
+4. context_collapse
+5. auto_compact_if_needed
+6. reactive_compact_on_overflow
+
+The implementation is intentionally tutorial-sized. It preserves canonical
+history in explicit state, produces a smaller model-facing projection, and uses
+injected deterministic summarizers for tests instead of live API calls.
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Literal, Sequence
+
+from langchain.agents import create_agent
+from langchain.tools import tool
+from langchain_core.language_models.chat_models import BaseChatModel
+from pydantic import BaseModel, ConfigDict, Field
+
+try:
+    from .common import (
+        WORKDIR,
+        bash,
+        build_openai_model,
+        edit_file,
+        invoke_and_append,
+        read_file,
+        write_file,
+    )
+except ImportError:
+    from common import (
+        WORKDIR,
+        bash,
+        build_openai_model,
+        edit_file,
+        invoke_and_append,
+        read_file,
+        write_file,
+    )
+
+MessageRole = Literal["system", "user", "assistant", "tool"]
+Summarizer = Callable[[Sequence["ContextMessage"]], str]
+
+PIPELINE_STAGE_ORDER = (
+    "apply_tool_result_budget",
+    "snip_projection",
+    "microcompact_messages",
+    "context_collapse",
+    "auto_compact_if_needed",
+    "reactive_compact_on_overflow",
+)
+SOURCE_BACKED_STAGES = (
+    "apply_tool_result_budget",
+    "microcompact_messages",
+    "auto_compact_if_needed",
+    "reactive_compact_on_overflow",
+)
+INFERRED_STAGES = (
+    "snip_projection",
+    "context_collapse",
+)
+INTENTIONAL_SIMPLIFICATIONS = (
+    "Character counts stand in for exact tokenizer budgets.",
+    "Persisted tool outputs are stored as plain text files instead of provider cache edits.",
+    "Snip projection and context collapse are honest teaching equivalents because the public cc-haha tree does not expose those internals in full.",
+    "Auto compact omits session-memory extraction, telemetry, and prompt-cache-sharing details.",
+)
+
+SYSTEM = f"""You are a coding agent at {WORKDIR}.
+Keep canonical history intact, but keep the model-facing context lean.
+If tool output grows too large, remember the teaching pipeline:
+persist oversized results, snip the projection, microcompact stale tool
+results, collapse old rounds, compact when thresholds are exceeded, and recover
+reactively if an overflow still happens.
+Use the compact tool when you need a manual reset point."""
+
+DEFAULT_TOOL_RESULT_THRESHOLD = 2_000
+DEFAULT_PER_MESSAGE_TOOL_BUDGET = 3_200
+DEFAULT_PREVIEW_CHARS = 240
+DEFAULT_SNIP_KEEP_LAST = 6
+DEFAULT_MICROCOMPACT_KEEP_RECENT = 2
+DEFAULT_CONTEXT_COLLAPSE_THRESHOLD = 2_800
+DEFAULT_CONTEXT_COLLAPSE_KEEP_RECENT_GROUPS = 1
+DEFAULT_AUTO_COMPACT_THRESHOLD = 1_900
+DEFAULT_AUTO_COMPACT_KEEP_RECENT = 4
+DEFAULT_SUMMARY_BUDGET = 600
+DEFAULT_REACTIVE_DRAIN_BUDGET = 220
+PERSISTED_OUTPUT_DIR = WORKDIR / ".task_outputs" / "tool-results"
+COMPACTABLE_TOOLS = {
+    "bash",
+    "read_file",
+    "grep",
+    "glob",
+    "search",
+    "write_file",
+    "edit_file",
+}
+MICROCOMPACT_PLACEHOLDER = (
+    "[microcompacted tool result; rerun the tool if you need full detail.]"
+)
+
+
+@dataclass
+class ContextMessage:
+    id: str
+    role: MessageRole
+    content: str
+    name: str | None = None
+    tool_call_id: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class PersistedOutput:
+    tool_call_id: str
+    path: str
+    preview: str
+    original_size: int
+
+
+@dataclass
+class CompactBoundary:
+    kind: str
+    reason: str
+    source_message_ids: tuple[str, ...] = ()
+    size_saved: int = 0
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class CollapsePlan:
+    summary_message: ContextMessage
+    source_message_ids: tuple[str, ...]
+    recent_message_ids: tuple[str, ...]
+
+
+@dataclass
+class ContextCompressionState:
+    messages: list[ContextMessage]
+    model_messages: list[ContextMessage] | None = None
+    persisted_outputs: dict[str, PersistedOutput] = field(default_factory=dict)
+    replacement_decisions: dict[str, str] = field(default_factory=dict)
+    compact_boundaries: list[CompactBoundary] = field(default_factory=list)
+    summaries: list[str] = field(default_factory=list)
+    transitions: list[str] = field(default_factory=list)
+    staged_collapse: CollapsePlan | None = None
+
+    def __post_init__(self) -> None:
+        if self.model_messages is None:
+            self.model_messages = deepcopy(self.messages)
+
+
+class PromptTooLongError(RuntimeError):
+    """Synthetic overflow sentinel for deterministic tests and demos."""
+
+
+class CompactInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    focus: str | None = Field(
+        default=None,
+        description=(
+            "Optional short note about what the next compact summary must keep"
+        ),
+    )
+
+
+def clone_state(state: ContextCompressionState) -> ContextCompressionState:
+    return deepcopy(state)
+
+
+def estimate_context_size(messages: Sequence[ContextMessage]) -> int:
+    return sum(len(message.role) + len(message.content) for message in messages)
+
+
+def tool_name(message: ContextMessage) -> str:
+    if message.name:
+        return message.name
+    metadata_name = str(message.metadata.get("tool_name") or "").strip()
+    return metadata_name or "tool"
+
+
+def is_tool_result_message(message: ContextMessage) -> bool:
+    return message.role == "tool" and bool(message.tool_call_id or message.name)
+
+
+def is_persisted_marker(content: str) -> bool:
+    return content.startswith("<persisted-output>")
+
+
+def trim_text(text: str, limit: int) -> str:
+    stripped = text.strip()
+    if len(stripped) <= limit:
+        return stripped
+    return stripped[: max(0, limit - 17)].rstrip() + "... [truncated]"
+
+
+def relative_display_path(path: Path) -> str:
+    try:
+        return str(path.relative_to(WORKDIR))
+    except ValueError:
+        return str(path)
+
+
+def persisted_output_marker(persisted: PersistedOutput) -> str:
+    return (
+        "<persisted-output>\n"
+        f"tool_call_id: {persisted.tool_call_id}\n"
+        f"path: {persisted.path}\n"
+        "preview:\n"
+        f"{persisted.preview}\n"
+        "</persisted-output>"
+    )
+
+
+def deterministic_summarizer(messages: Sequence[ContextMessage]) -> str:
+    if not messages:
+        return "No earlier context to preserve."
+
+    lines: list[str] = []
+    for message in messages[:6]:
+        label = message.role
+        if is_tool_result_message(message):
+            label = f"tool:{tool_name(message)}"
+        preview = trim_text(message.content.replace("\n", " "), 80)
+        lines.append(f"- {label}: {preview}")
+
+    if len(messages) > 6:
+        lines.append(f"- ... {len(messages) - 6} more messages elided")
+    return "Compressed carry-forward summary:\n" + "\n".join(lines)
+
+
+def normalize_history(messages: Sequence[dict[str, Any] | ContextMessage]) -> list[ContextMessage]:
+    normalized: list[ContextMessage] = []
+    for index, raw in enumerate(messages, start=1):
+        if isinstance(raw, ContextMessage):
+            normalized.append(deepcopy(raw))
+            continue
+
+        content = raw.get("content", "")
+        if isinstance(content, list):
+            content = "\n".join(
+                str(block.get("text") or block.get("content") or "")
+                for block in content
+                if isinstance(block, dict)
+            ).strip()
+        normalized.append(
+            ContextMessage(
+                id=str(raw.get("id") or f"m{index}"),
+                role=raw.get("role", "user"),
+                content=str(content),
+                name=raw.get("name"),
+                tool_call_id=raw.get("tool_call_id"),
+                metadata={
+                    key: value
+                    for key, value in raw.items()
+                    if key
+                    not in {"id", "role", "content", "name", "tool_call_id"}
+                },
+            )
+        )
+    return normalized
+
+
+def state_from_history(
+    messages: Sequence[dict[str, Any] | ContextMessage],
+) -> ContextCompressionState:
+    return ContextCompressionState(messages=normalize_history(messages))
+
+
+def _persist_tool_result(
+    state: ContextCompressionState,
+    message: ContextMessage,
+    *,
+    storage_dir: Path,
+    preview_chars: int,
+) -> tuple[PersistedOutput, int]:
+    tool_call_id = message.tool_call_id or message.id
+    persisted = state.persisted_outputs.get(tool_call_id)
+    if persisted is None:
+        storage_dir.mkdir(parents=True, exist_ok=True)
+        output_path = storage_dir / f"{tool_call_id}.txt"
+        if not output_path.exists():
+            output_path.write_text(message.content, encoding="utf-8")
+        persisted = PersistedOutput(
+            tool_call_id=tool_call_id,
+            path=relative_display_path(output_path),
+            preview=trim_text(message.content, preview_chars),
+            original_size=len(message.content),
+        )
+        state.persisted_outputs[tool_call_id] = persisted
+
+    replacement = persisted_output_marker(persisted)
+    size_saved = max(0, len(message.content) - len(replacement))
+    message.content = replacement
+    state.replacement_decisions[tool_call_id] = persisted.path
+    return persisted, size_saved
+
+
+def _tool_message_groups(
+    messages: Sequence[ContextMessage],
+) -> dict[str, list[ContextMessage]]:
+    groups: dict[str, list[ContextMessage]] = {}
+    for index, message in enumerate(messages):
+        if not is_tool_result_message(message):
+            continue
+        group_id = (
+            str(message.metadata.get("group_id") or "").strip()
+            or str(message.metadata.get("round_id") or "").strip()
+            or f"tool-group-{index}"
+        )
+        groups.setdefault(group_id, []).append(message)
+    return groups
+
+
+def _record_boundary(
+    state: ContextCompressionState,
+    *,
+    kind: str,
+    reason: str,
+    source_messages: Sequence[ContextMessage],
+    size_saved: int,
+    details: dict[str, Any] | None = None,
+) -> None:
+    state.compact_boundaries.append(
+        CompactBoundary(
+            kind=kind,
+            reason=reason,
+            source_message_ids=tuple(message.id for message in source_messages),
+            size_saved=size_saved,
+            details=details or {},
+        )
+    )
+
+
+def apply_tool_result_budget(
+    state: ContextCompressionState,
+    *,
+    storage_dir: Path = PERSISTED_OUTPUT_DIR,
+    per_tool_threshold: int = DEFAULT_TOOL_RESULT_THRESHOLD,
+    per_message_budget: int = DEFAULT_PER_MESSAGE_TOOL_BUDGET,
+    preview_chars: int = DEFAULT_PREVIEW_CHARS,
+) -> ContextCompressionState:
+    next_state = clone_state(state)
+    next_state.transitions.append("apply_tool_result_budget")
+
+    replaced_messages: list[ContextMessage] = []
+    total_saved = 0
+
+    for message in next_state.model_messages:
+        if not is_tool_result_message(message):
+            continue
+        tool_call_id = message.tool_call_id or message.id
+        if tool_call_id in next_state.replacement_decisions:
+            _, saved = _persist_tool_result(
+                next_state,
+                message,
+                storage_dir=storage_dir,
+                preview_chars=preview_chars,
+            )
+            replaced_messages.append(message)
+            total_saved += saved
+            continue
+        if len(message.content) > per_tool_threshold:
+            _, saved = _persist_tool_result(
+                next_state,
+                message,
+                storage_dir=storage_dir,
+                preview_chars=preview_chars,
+            )
+            replaced_messages.append(message)
+            total_saved += saved
+
+    for group_id, tool_messages in _tool_message_groups(next_state.model_messages).items():
+        remaining_budget = sum(len(message.content) for message in tool_messages)
+        fresh_messages = [
+            message
+            for message in tool_messages
+            if (message.tool_call_id or message.id)
+            not in next_state.replacement_decisions
+        ]
+        while remaining_budget > per_message_budget and fresh_messages:
+            candidate = max(fresh_messages, key=lambda message: len(message.content))
+            _, saved = _persist_tool_result(
+                next_state,
+                candidate,
+                storage_dir=storage_dir,
+                preview_chars=preview_chars,
+            )
+            replaced_messages.append(candidate)
+            total_saved += saved
+            remaining_budget = sum(len(message.content) for message in tool_messages)
+            fresh_messages = [
+                message
+                for message in tool_messages
+                if (message.tool_call_id or message.id)
+                not in next_state.replacement_decisions
+            ]
+        if group_id and tool_messages:
+            tool_messages[-1].metadata["budget_group"] = group_id
+
+    if replaced_messages:
+        _record_boundary(
+            next_state,
+            kind="tool_result_budget",
+            reason=(
+                "Persist oversized tool outputs and freeze replacement decisions "
+                "by tool_call_id."
+            ),
+            source_messages=replaced_messages,
+            size_saved=total_saved,
+            details={
+                "replacement_decisions": dict(next_state.replacement_decisions),
+            },
+        )
+    return next_state
+
+
+def snip_projection(
+    state: ContextCompressionState,
+    *,
+    keep_last: int = DEFAULT_SNIP_KEEP_LAST,
+) -> ContextCompressionState:
+    next_state = clone_state(state)
+    next_state.transitions.append("snip_projection")
+
+    if len(next_state.model_messages) <= keep_last:
+        return next_state
+
+    omitted = next_state.model_messages[:-keep_last]
+    kept = next_state.model_messages[-keep_last:]
+    snip_message = ContextMessage(
+        id=f"snip-{len(next_state.compact_boundaries) + 1}",
+        role="system",
+        content=(
+            f"[snip] {len(omitted)} older messages hidden from the active "
+            "projection; canonical history still lives in state.messages."
+        ),
+        metadata={"stage": "snip"},
+    )
+    next_state.model_messages = [snip_message, *kept]
+    _record_boundary(
+        next_state,
+        kind="snip",
+        reason="Projection-only trim of older context.",
+        source_messages=omitted,
+        size_saved=max(0, estimate_context_size(omitted) - len(snip_message.content)),
+        details={"kept_recent": keep_last},
+    )
+    return next_state
+
+
+def microcompact_messages(
+    state: ContextCompressionState,
+    *,
+    keep_recent: int = DEFAULT_MICROCOMPACT_KEEP_RECENT,
+    compactable_tools: set[str] | None = None,
+) -> ContextCompressionState:
+    next_state = clone_state(state)
+    next_state.transitions.append("microcompact_messages")
+
+    compactable_tools = compactable_tools or COMPACTABLE_TOOLS
+    compactable = [
+        message
+        for message in next_state.model_messages
+        if is_tool_result_message(message) and tool_name(message) in compactable_tools
+    ]
+    if len(compactable) <= keep_recent:
+        return next_state
+
+    cleared_messages = compactable[:-keep_recent]
+    size_saved = 0
+    cleared_ids: list[str] = []
+    for message in cleared_messages:
+        if is_persisted_marker(message.content) or message.content == MICROCOMPACT_PLACEHOLDER:
+            continue
+        size_saved += max(0, len(message.content) - len(MICROCOMPACT_PLACEHOLDER))
+        message.content = MICROCOMPACT_PLACEHOLDER
+        cleared_ids.append(message.tool_call_id or message.id)
+
+    if cleared_ids:
+        _record_boundary(
+            next_state,
+            kind="microcompact",
+            reason="Clear older compactable tool results while keeping recent ones intact.",
+            source_messages=cleared_messages,
+            size_saved=size_saved,
+            details={"cleared_tool_call_ids": cleared_ids, "kept_recent": keep_recent},
+        )
+    return next_state
+
+
+def group_api_rounds(
+    messages: Sequence[ContextMessage],
+) -> list[list[ContextMessage]]:
+    groups: list[list[ContextMessage]] = []
+    current_group: list[ContextMessage] = []
+    for message in messages:
+        if message.role == "user" and current_group:
+            groups.append(current_group)
+            current_group = []
+        current_group.append(message)
+    if current_group:
+        groups.append(current_group)
+    return groups
+
+
+def context_collapse(
+    state: ContextCompressionState,
+    summarizer: Summarizer = deterministic_summarizer,
+    *,
+    collapse_threshold: int = DEFAULT_CONTEXT_COLLAPSE_THRESHOLD,
+    keep_recent_groups: int = DEFAULT_CONTEXT_COLLAPSE_KEEP_RECENT_GROUPS,
+) -> ContextCompressionState:
+    next_state = clone_state(state)
+    next_state.transitions.append("context_collapse")
+
+    if estimate_context_size(next_state.model_messages) <= collapse_threshold:
+        return next_state
+
+    groups = group_api_rounds(next_state.model_messages)
+    if len(groups) <= keep_recent_groups:
+        return next_state
+
+    collapsed_groups = groups[:-keep_recent_groups]
+    recent_groups = groups[-keep_recent_groups:]
+    collapsed_messages = [message for group in collapsed_groups for message in group]
+    recent_messages = [message for group in recent_groups for message in group]
+    summary = summarizer(collapsed_messages).strip() or "Earlier context summarized."
+    summary_message = ContextMessage(
+        id=f"context-collapse-{len(next_state.summaries) + 1}",
+        role="system",
+        content=f"[context-collapse]\n{summary}",
+        metadata={"stage": "context_collapse", "inferred": True},
+    )
+    next_state.model_messages = [summary_message, *recent_messages]
+    next_state.summaries.append(summary)
+    next_state.staged_collapse = CollapsePlan(
+        summary_message=deepcopy(summary_message),
+        source_message_ids=tuple(message.id for message in collapsed_messages),
+        recent_message_ids=tuple(message.id for message in recent_messages),
+    )
+    _record_boundary(
+        next_state,
+        kind="context_collapse",
+        reason="Summarize older API-round groups while keeping recent groups verbatim.",
+        source_messages=collapsed_messages,
+        size_saved=max(
+            0,
+            estimate_context_size(collapsed_messages) - len(summary_message.content),
+        ),
+        details={"keep_recent_groups": keep_recent_groups},
+    )
+    return next_state
+
+
+def _build_summary_message(
+    *,
+    stage: str,
+    summary: str,
+    index: int,
+) -> ContextMessage:
+    return ContextMessage(
+        id=f"{stage}-{index}",
+        role="system",
+        content=f"[{stage}]\n{summary}",
+        metadata={"stage": stage},
+    )
+
+
+def auto_compact_if_needed(
+    state: ContextCompressionState,
+    summarizer: Summarizer = deterministic_summarizer,
+    *,
+    threshold: int = DEFAULT_AUTO_COMPACT_THRESHOLD,
+    keep_recent: int = DEFAULT_AUTO_COMPACT_KEEP_RECENT,
+    summary_budget: int = DEFAULT_SUMMARY_BUDGET,
+    focus: str | None = None,
+    force: bool = False,
+    boundary_kind: str = "auto_compact",
+    transition_name: str | None = "auto_compact",
+) -> ContextCompressionState:
+    next_state = clone_state(state)
+    if transition_name:
+        next_state.transitions.append(transition_name)
+
+    if not force and estimate_context_size(next_state.model_messages) <= threshold:
+        return next_state
+
+    if keep_recent and len(next_state.model_messages) > keep_recent:
+        summary_source = next_state.model_messages[:-keep_recent]
+        recent_messages = next_state.model_messages[-keep_recent:]
+    else:
+        summary_source = list(next_state.model_messages)
+        recent_messages = []
+
+    summary = summarizer(summary_source).strip() or "Conversation compacted."
+    if focus:
+        summary = f"{summary}\nFocus next: {focus.strip()}"
+    summary = trim_text(summary, summary_budget)
+    summary_message = _build_summary_message(
+        stage=boundary_kind.replace("_", "-"),
+        summary=summary,
+        index=len(next_state.summaries) + 1,
+    )
+    next_state.model_messages = [summary_message, *recent_messages]
+    next_state.summaries.append(summary)
+    next_state.staged_collapse = None
+    _record_boundary(
+        next_state,
+        kind=boundary_kind,
+        reason="Reset active context to a summary plus recent messages.",
+        source_messages=summary_source,
+        size_saved=max(
+            0,
+            estimate_context_size(summary_source) - len(summary_message.content),
+        ),
+        details={"keep_recent": keep_recent},
+    )
+    return next_state
+
+
+def compact_conversation(
+    state: ContextCompressionState,
+    summarizer: Summarizer = deterministic_summarizer,
+    *,
+    focus: str | None = None,
+    keep_recent: int = DEFAULT_AUTO_COMPACT_KEEP_RECENT,
+) -> ContextCompressionState:
+    return auto_compact_if_needed(
+        state,
+        summarizer,
+        threshold=0,
+        keep_recent=keep_recent,
+        focus=focus,
+        force=True,
+    )
+
+
+manual_compact = compact_conversation
+
+
+def reactive_compact_on_overflow(
+    state: ContextCompressionState,
+    error: Exception | str | None,
+    summarizer: Summarizer = deterministic_summarizer,
+    *,
+    threshold: int = DEFAULT_AUTO_COMPACT_THRESHOLD,
+    keep_recent: int = DEFAULT_AUTO_COMPACT_KEEP_RECENT,
+    drain_summary_budget: int = DEFAULT_REACTIVE_DRAIN_BUDGET,
+) -> ContextCompressionState:
+    next_state = clone_state(state)
+    next_state.transitions.append("collapse_drain_retry")
+
+    if next_state.staged_collapse is not None:
+        drained_summary = trim_text(
+            next_state.staged_collapse.summary_message.content,
+            drain_summary_budget,
+        )
+        recent_ids = set(next_state.staged_collapse.recent_message_ids)
+        recent_messages = [
+            message
+            for message in next_state.model_messages
+            if message.id in recent_ids
+        ]
+        next_state.model_messages = [
+            ContextMessage(
+                id=f"collapse-drain-{len(next_state.summaries) + 1}",
+                role="system",
+                content=drained_summary,
+                metadata={"stage": "collapse_drain_retry"},
+            ),
+            *recent_messages,
+        ]
+
+    if estimate_context_size(next_state.model_messages) <= threshold:
+        return next_state
+
+    next_state.transitions.append("reactive_compact_retry")
+    focus = None
+    if error:
+        focus = f"Recover after overflow: {error}"
+    return auto_compact_if_needed(
+        next_state,
+        summarizer,
+        threshold=threshold,
+        keep_recent=keep_recent,
+        focus=focus,
+        force=True,
+        boundary_kind="reactive_compact",
+        transition_name=None,
+    )
+
+
+def run_compression_pipeline(
+    state: ContextCompressionState,
+    summarizer: Summarizer = deterministic_summarizer,
+    *,
+    storage_dir: Path = PERSISTED_OUTPUT_DIR,
+    per_tool_threshold: int = DEFAULT_TOOL_RESULT_THRESHOLD,
+    per_message_budget: int = DEFAULT_PER_MESSAGE_TOOL_BUDGET,
+    snip_keep_last: int = DEFAULT_SNIP_KEEP_LAST,
+    micro_keep_recent: int = DEFAULT_MICROCOMPACT_KEEP_RECENT,
+    collapse_threshold: int = DEFAULT_CONTEXT_COLLAPSE_THRESHOLD,
+    collapse_keep_recent_groups: int = DEFAULT_CONTEXT_COLLAPSE_KEEP_RECENT_GROUPS,
+    auto_threshold: int = DEFAULT_AUTO_COMPACT_THRESHOLD,
+    auto_keep_recent: int = DEFAULT_AUTO_COMPACT_KEEP_RECENT,
+) -> ContextCompressionState:
+    compacted = apply_tool_result_budget(
+        state,
+        storage_dir=storage_dir,
+        per_tool_threshold=per_tool_threshold,
+        per_message_budget=per_message_budget,
+    )
+    compacted = snip_projection(compacted, keep_last=snip_keep_last)
+    compacted = microcompact_messages(compacted, keep_recent=micro_keep_recent)
+    compacted = context_collapse(
+        compacted,
+        summarizer,
+        collapse_threshold=collapse_threshold,
+        keep_recent_groups=collapse_keep_recent_groups,
+    )
+    return auto_compact_if_needed(
+        compacted,
+        summarizer,
+        threshold=auto_threshold,
+        keep_recent=auto_keep_recent,
+    )
+
+
+@tool(
+    "compact",
+    args_schema=CompactInput,
+    description=(
+        "Manual teaching wrapper for conversation compaction. Use it when the "
+        "thread is bloated and you want a short carry-forward summary of goals, "
+        "decisions, files, and next steps before continuing."
+    ),
+)
+def compact(focus: str | None = None) -> str:
+    """Expose the stage's manual compact capability to the model."""
+
+    summary = (
+        "Manual compaction in this chapter means carrying forward the current "
+        "goal, important decisions, touched files, and next steps while "
+        "dropping bulky detail from the active context."
+    )
+    if focus:
+        return f"{summary}\nFocus next: {focus.strip()}"
+    return summary
+
+
+TOOLS = [bash, read_file, write_file, edit_file, compact]
+
+
+def build_agent(*, model: BaseChatModel | None = None):
+    """Create the s06 demo agent without requiring credentials on import."""
+
+    return create_agent(
+        model=model or build_openai_model(),
+        tools=TOOLS,
+        system_prompt=SYSTEM,
+    )
+
+
+def agent_loop(messages: list[dict[str, Any]]) -> str:
+    return invoke_and_append(build_agent(), messages)
+
+
+if __name__ == "__main__":
+    history: list[dict[str, Any]] = []
+    while True:
+        try:
+            query = input("\033[36ms06-da >> \033[0m")
+        except (EOFError, KeyboardInterrupt):
+            break
+        if query.strip().lower() in ("q", "exit", ""):
+            break
+
+        history.append({"role": "user", "content": query})
+        try:
+            final = agent_loop(history)
+        except RuntimeError as exc:
+            print(f"Error: {exc}")
+            continue
+        print(final)
+        print()
diff --git a/coding-deepgent/.env.example b/coding-deepgent/.env.example
new file mode 100644
index 000000000..e53485120
--- /dev/null
+++ b/coding-deepgent/.env.example
@@ -0,0 +1,3 @@
+OPENAI_API_KEY=sk-...
+OPENAI_MODEL=gpt-4.1-mini
+# OPENAI_BASE_URL=https://your-compatible-endpoint.example/v1
diff --git a/coding-deepgent/.flake8 b/coding-deepgent/.flake8
new file mode 100644
index 000000000..6deafc261
--- /dev/null
+++ b/coding-deepgent/.flake8
@@ -0,0 +1,2 @@
+[flake8]
+max-line-length = 120
diff --git a/coding-deepgent/PROJECT_PROGRESS.md b/coding-deepgent/PROJECT_PROGRESS.md
new file mode 100644
index 000000000..a085b626e
--- /dev/null
+++ b/coding-deepgent/PROJECT_PROGRESS.md
@@ -0,0 +1,84 @@
+# coding-deepgent progress
+
+## Current product stage
+
+- `current_product_stage`: `stage-11-mcp-plugin-real-loading`
+- `compatibility_anchor`: `mcp-plugin-real-loading`
+- `architecture_reshape_status`: `s1-skeleton-complete`
+- Status: MCP/plugin real loading implemented as one cumulative LangChain cc product surface
+- Last updated: 2026-04-14
+
+## Project-wide architecture reshape (S1 skeleton)
+
+The facility stages remain at Stage 11, but the product skeleton has been reshaped to reduce central-file pressure and low-value public glue:
+
+- `app.py` is now a thin entrypoint over `bootstrap.py` and `agent_loop_service.py`
+- `cli.py` is now a thin Typer shell over `cli_service.py`
+- startup validation is explicit instead of piggybacking on agent creation side effects
+- filesystem execution and discovery now follow a runtime-owned service path
+- session recording/loading now centers on `sessions/service.py`
+- low-value facades and global mutable public surfaces were deleted instead of preserved
+
+This reshape is the new baseline for the next cc-core upgrades.
+
+## Upgrade gate
+
+Advance by explicit product-stage plan approval, not tutorial chapter completion.
+
+## Stage roadmap
+
+1. Stage 1: TodoWrite / todos / activeForm product contract
+2. Stage 2: architecture gate for filesystem/tool-system/session seams
+3. Stage 3: professional domain runtime foundation with typed settings, DI composition, Typer/Rich CLI, runtime context, sessions, filesystem/tool_system, and local events
+4. Stage 4: control-plane foundation (permissions, hooks, structured prompt/context)
+5. Stage 5: memory/context/compact foundation
+6. Stage 6: skills/subagents/durable task graph
+7. Stage 7: local MCP/plugin extension foundation
+8. Stage 8: recovery/evidence/runtime-continuation foundation
+9. Stage 9: permission/trust-boundary hardening
+10. Stage 10: hooks/lifecycle expansion
+11. Stage 11: MCP/plugin real loading
+
+## Abstraction checkpoint
+
+Before implementing the next stage, re-evaluate whether the current domain packages and containers still preserve the boundary rules in `.trellis/plans/prd-coding-deepgent-runtime-foundation.md`.
+
+## Renderer boundary note
+
+The current product has a dependency-free planning renderer seam for terminal plan/reminder output. This is a behavior-preserving boundary, not a browser/API/event-bus implementation.
+
+## Stage 4 control-plane foundation
+
+Stage 4 adds deterministic permission/safety decisions, local lifecycle hooks, and structured prompt/context assembly as LangChain-native seams over the existing `create_agent` runtime. Interactive UI approval, auto classifiers, memory, durable tasks, subagents, and MCP/plugin loading remain future stages.
+
+## Stage 5 memory/context/compact foundation
+
+Stage 5 adds a store-backed long-term memory foundation seam, the model-visible `save_memory` tool, bounded memory context injection, and deterministic tool-result budget helpers. Message-history projection/pruning, LLM autocompact, session-memory side-agent writing, subagents, durable tasks, and MCP/plugin memory sync remain future work.
+
+## Stage 6 skills/subagents/task graph
+
+Stage 6 adds local skill loading, a store-backed durable task graph, and a minimal synchronous/stateless `run_subagent` tool. Background agents, SendMessage/mailbox, worktrees, remote/team runtime, sidechain resume, forked skill execution, extension distribution, and custom query loops remain future work.
+
+## Stage 7 MCP/plugin extension foundation
+
+Stage 7 adds local-only extension seams: MCP tool descriptors can become agent-bindable `ToolCapability` entries, MCP resources remain separate metadata/read surfaces, and strict local `plugin.json` manifests declare local tools, skills, and resources without executing plugin code. Connection management, installer/update flows, remote trust, background daemons, and runtime replacement remain deferred.
+
+
+## Stage 8 recovery/evidence/runtime-continuation foundation
+
+Stage 8 adds session-scoped evidence records, loaded-session evidence, a deterministic recovery brief, and default CLI session-store wiring for listing and resuming recorded sessions. It preserves LangChain `create_agent`/LangGraph `thread_id` runtime boundaries and defers checkpoint browsers, task-level evidence stores, mailbox/background resume, and new persistence dependencies.
+
+
+## Stage 9 permission/trust-boundary hardening
+
+Stage 9 hardens the existing permission runtime with typed settings-backed rules, explicit trusted extra workspace directories, and builtin/extension capability trust metadata. It stays deterministic and local-only: no HITL UI, no remote trust flow, no marketplace/install/update behavior, and no runtime replacement.
+
+
+## Stage 10 hooks/lifecycle expansion
+
+Stage 10 wires the local sync hook registry into real runtime boundaries: `SessionStart` and `UserPromptSubmit` run from the app invocation path, while `PreToolUse`, `PostToolUse`, and `PermissionDenied` run from tool middleware. Hooks remain deterministic and local-only: no async/plugin/HTTP/remote hook platform and no model-visible prompt mutation from hook context.
+
+
+## Stage 11 MCP/plugin real loading
+
+Stage 11 adds typed root `.mcp.json` loading, an optional official adapter-backed MCP tool loading seam, and plugin declaration validation against known local capabilities/skills. It still defers dependency installation, marketplace/install/update, remote trust/auth UX, and runtime replacement.
diff --git a/coding-deepgent/README.md b/coding-deepgent/README.md
new file mode 100644
index 000000000..3d74e6c46
--- /dev/null
+++ b/coding-deepgent/README.md
@@ -0,0 +1,76 @@
+# coding-deepgent
+
+Independent cumulative LangChain cc product surface.
+
+## Current product stage
+
+- `current_product_stage`: `stage-11-mcp-plugin-real-loading`
+- `compatibility_anchor`: `mcp-plugin-real-loading`
+- `architecture_reshape_status`: `s1-skeleton-complete`
+- Upgrade policy: advance by explicit product-stage plan approval, not tutorial chapter completion.
+
+## Current architecture
+
+- LangChain remains the runtime boundary: `RuntimeState`, `RuntimeContext`, `context=`, and LangGraph `thread_id` config own runtime invocation.
+- Dependency-injector containers compose settings, runtime seams, domain tools, middleware, session storage, and agent creation; domain packages do not import containers.
+- The public planning contract remains cc-aligned `TodoWrite(todos=[...])` with required `activeForm` on every todo item.
+- The current product has explicit domains for runtime, permissions, hooks, prompt/context, memory, compact helpers, local skills, durable tasks, bounded subagents, local MCP tool registration, and local plugin manifests without replacing LangChain's agent runtime.
+
+## Architecture reshape status
+
+Project-wide S1 skeleton reshape is complete:
+
+- bootstrap / agent-loop / CLI orchestration moved into dedicated services
+- startup validation is explicit
+- filesystem execution is runtime-owned instead of settings-driven by default
+- session defaults now have one owner (`runtime.default_runtime_state`)
+- low-value facades and global mutable public state were removed rather than kept for compatibility
+
+## CLI surface
+
+The stage-3 runtime-foundation CLI keeps the legacy `--prompt` path while adding grouped commands:
+
+- `coding-deepgent --prompt "..."` — run one prompt and exit
+- `coding-deepgent run "..."` — explicit one-shot command
+- `coding-deepgent config show` — render the resolved local configuration without exposing secrets
+- `coding-deepgent sessions list` — render the current session index view
+- `coding-deepgent sessions resume <session-id> --prompt "..."` — continue a recorded session when a session provider is wired
+- `coding-deepgent doctor` — verify CLI/rendering/logging dependencies locally
+
+Rich table renderers live in `coding_deepgent.renderers.text`, and local structured logging setup lives in `coding_deepgent.logging_config`.
+
+## Stage 4 control-plane foundation
+
+Stage 4 adds deterministic permission/safety decisions, local lifecycle hooks, and structured prompt/context assembly as LangChain-native seams over the existing `create_agent` runtime. Interactive UI approval, auto classifiers, memory, durable tasks, subagents, and MCP/plugin loading remain future stages.
+
+## Stage 5 memory/context/compact foundation
+
+Stage 5 adds a store-backed long-term memory foundation seam, the model-visible `save_memory` tool, bounded memory context injection, and deterministic tool-result budget helpers. Message-history projection/pruning, LLM autocompact, session-memory side-agent writing, subagents, durable tasks, and MCP/plugin memory sync remain future work.
+
+## Stage 6 skills/subagents/task graph
+
+Stage 6 adds local skill loading, a store-backed durable task graph, and a minimal synchronous/stateless `run_subagent` tool. Background agents, SendMessage/mailbox, worktrees, remote/team runtime, sidechain resume, forked skill execution, extension distribution, and custom query loops remain future work.
+
+## Stage 7 MCP/plugin extension foundation
+
+Stage 7 adds a local MCP adapter seam that converts already-discovered MCP tools into agent-bindable `ToolCapability` entries while keeping MCP resources in a separate read-surface registry. It also adds a strict local `plugin.json` manifest loader/registry for metadata-only declarations of local tools, skills, and resources. Stage 7 intentionally does not add a connection manager, installer/update flow, remote trust workflow, background daemon, or runtime replacement.
+
+
+## Stage 8 recovery/evidence/runtime-continuation foundation
+
+Stage 8 adds a minimal recovery facility before deeper cc-core upgrades: session JSONL transcripts can carry factual evidence records, loaded sessions expose evidence alongside history/state, `sessions resume` can render a recovery brief, and the default CLI runtime uses the real local session store for list/resume. Full checkpoint browsing, task-level evidence stores, mailbox/background resume, and additional persistence dependencies remain future work.
+
+
+## Stage 9 permission/trust-boundary hardening
+
+Stage 9 extends the middleware-based permission runtime with typed settings-backed rules, explicitly trusted extra workspace directories, and capability trust metadata that distinguishes builtin tools from extension-provided tools. This stage intentionally defers interactive approval UX, remote trust, and marketplace/install flows.
+
+
+## Stage 10 hooks/lifecycle expansion
+
+Stage 10 upgrades hooks from a passive registry to a real local lifecycle seam. The runtime context now carries a hook registry, `app.agent_loop()` dispatches `SessionStart` / `UserPromptSubmit`, and `ToolGuardMiddleware` dispatches `PreToolUse`, `PostToolUse`, and `PermissionDenied`. Async hooks, plugin hooks, remote hooks, and model-visible hook context remain deferred.
+
+
+## Stage 11 MCP/plugin real loading
+
+Stage 11 upgrades the Stage 7 foundation into real loading: a root `.mcp.json` file can be parsed strictly, official `langchain-mcp-adapters` loading is used when available, MCP tool capabilities flow into the agent tool list, and local plugin declarations are validated against known local capabilities and skills. Dependency installation, marketplace/install/update flows, remote trust/auth UX, and runtime replacement remain deferred.
diff --git a/coding-deepgent/docs/cc-alignment-roadmap.md b/coding-deepgent/docs/cc-alignment-roadmap.md
new file mode 100644
index 000000000..716aadfa0
--- /dev/null
+++ b/coding-deepgent/docs/cc-alignment-roadmap.md
@@ -0,0 +1,148 @@
+# coding-deepgent cc alignment roadmap
+
+## Scope
+
+`coding-deepgent` is the product-track LangChain/LangGraph implementation of selected Claude Code / cc-haha runtime ideas. This document records product-local alignment decisions for Stage 4 and later.
+
+## Expected effect
+
+Aligning Stage 4 should improve safety, maintainability, context quality, and testability. The local runtime effect is: tools run behind one deterministic permission decision layer, lifecycle hooks exist as a future extension seam, and prompt/context assembly becomes structured without replacing LangChain's `create_agent` runtime.
+
+## Evidence policy
+
+- Secondary target map: `lintsinghua/claude-code-book` / local `/root/claude-code-haha/docs/must-read/*`.
+- Primary implementation evidence: local `NanmiCoder/cc-haha` checkout at `/root/claude-code-haha`, commit `d166eb8`.
+- Local implementation must stay LangChain-first: `create_agent`, `AgentMiddleware`, strict Pydantic tools, `Command(update=...)`, state/context schemas, checkpointer/store before custom runtime.
+
+## Alignment matrix
+
+- `/root/claude-code-haha/src/types/permissions.ts:PermissionMode` -> external five-mode union (`default`, `plan`, `acceptEdits`, `bypassPermissions`, `dontAsk`) in `coding_deepgent.permissions.modes` -> align -> implement now; defer `auto` and `bubble`.
+- `/root/claude-code-haha/src/utils/permissions/permissions.ts:ask/dontAsk branches` -> Stage 4 `ask` becomes deterministic non-executing `ToolMessage` + runtime event, and `dontAsk` converts the same path into explicit denial -> partial -> no UI/human-interrupt approval yet.
+- `/root/claude-code-haha/src/Tool.ts:Tool.checkPermissions` and `ToolPermissionContext` -> `ToolGuardMiddleware` delegates to a product-local `PermissionManager` before handler execution -> align -> use LangChain `AgentMiddleware`, not a custom tool executor.
+- `/root/claude-code-haha/src/utils/queryContext.ts:fetchSystemPromptParts` -> `PromptContext` exposes default system prompt parts, user context, and system context -> align -> keep builder small and compatible with `create_agent`.
+- `/root/claude-code-haha/src/types/hooks.ts:HookEvent` and hook JSON output schemas -> local sync hook registry with strict `HookPayload` / `HookResult` schemas for selected lifecycle events -> partial -> no HTTP/prompt/agent hooks yet.
+- `/root/claude-code-haha/src/query.ts:tool budget/snip/microcompact/context collapse/autocompact sequence` -> later `compact/` seam after prompt/context foundation -> defer -> Stage 5 candidate.
+- `/root/claude-code-haha/src/utils/tasks.ts` and `src/tools/Task*Tool/*` -> future store-backed task domain separate from TodoWrite -> defer -> Stage 6 candidate.
+- `/root/claude-code-haha/src/components/permissions/*` -> no local UI parity target -> do-not-copy -> Rich CLI only unless explicitly requested.
+
+## Stage 5 memory/context rows
+
+- `/root/claude-code-haha/src/memdir/memoryTypes.ts` -> `MemoryRecord` / `SaveMemoryInput` as strict Pydantic schemas -> partial -> store-backed foundation only.
+- `/root/claude-code-haha/src/memdir/findRelevantMemories.ts` -> deterministic `recall_memories()` helper with bounded result count -> partial -> no embedding/vector recall yet.
+- `/root/claude-code-haha/src/utils/queryContext.ts:fetchSystemPromptParts` -> prompt builder accepts rendered memory context as a distinct prompt section -> align -> use existing `create_agent` prompt path.
+- `/root/claude-code-haha/src/query.ts:applyToolResultBudget` -> deterministic `apply_tool_result_budget()` helper for oversized tool-result strings -> partial -> no message-history projection/pruning in Stage 5.
+
+## Stage 6 skills/tasks/subagents rows
+
+- `/root/claude-code-haha/src/tools/SkillTool/SkillTool.ts` -> local `load_skill` tool loads one `SKILL.md` by explicit name -> partial -> no plugin/MCP/remote skills.
+- `/root/claude-code-haha/src/utils/tasks.ts` and `/root/claude-code-haha/src/tools/Task*Tool/*` -> store-backed `task_create/get/list/update` with strict transitions -> partial -> no coordinator/team runtime yet.
+- `/root/claude-code-haha/src/tools/AgentTool/AgentTool.tsx` -> minimal synchronous/stateless `run_subagent` tool with exact child-tool allowlist -> partial -> no background/worktree/mailbox/resume.
+- `/root/claude-code-haha/src/tools/SendMessageTool/*` -> mailbox/send-message semantics -> defer -> requires later multi-agent runtime.
+
+## Prior completed candidates
+
+1. Stage 5: memory + context budget + compact seam.
+2. Stage 6: skills + subagents + durable task graph.
+3. Stage 7: local MCP/plugin extension foundation.
+
+## Stage 7 MCP/plugin extension rows
+
+## Expected effect
+
+Aligning Stage 7 should improve product extensibility, capability registration, and future ecosystem readiness. The local runtime effect is: already-discovered MCP tools can be carried into the LangChain agent tool list through typed `ToolCapability` entries, MCP resources stay as separate read-surface metadata, and local plugin manifests can declare bounded local capabilities without executing plugin code or replacing the runtime.
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| MCP tool provenance | `/root/claude-code-haha/src/services/mcp/types.ts` models connected servers, serialized tools, resources, and scoped config metadata | keep extension tool origin visible and deterministic | `coding_deepgent.mcp.MCPSourceMetadata` + `MCPToolDescriptor` | partial | Convert already-discovered local descriptors only; no connection manager |
+| MCP resources | `/root/claude-code-haha/src/services/mcp/utils.ts:filterResourcesByServer` keeps resources separate from tools | prevent read surfaces becoming executable capabilities | `MCPResourceRegistry` | align | Store resources outside `CapabilityRegistry` |
+| MCP connection/config breadth | `/root/claude-code-haha/src/services/mcp/config.ts` and `MCPConnectionManager.tsx` cover config merging, auth, and multiple transports | avoid premature protocol/platform creep | none in Stage 7 | defer | Official LangChain adapters remain future connection seam |
+| Plugin manifest loading | `/root/claude-code-haha/src/utils/plugins/pluginLoader.ts` loads plugin metadata/components from filesystem/cache sources | local extension declarations become deterministic and inspectable | `coding_deepgent.plugins.loader` + `PluginRegistry` | partial | Strict local `plugin.json` metadata only |
+| Plugin MCP/platform fields | `/root/claude-code-haha/src/utils/plugins/schemas.ts` allows rich commands/skills/hooks/MCP/LSP/platform fields | protect current runtime from silent mutation | `PluginManifest(extra="forbid")` | do-not-copy now | Only `name`, `description`, `version`, `skills`, `tools`, `resources` |
+| Skill extension bridge | `/root/claude-code-haha/src/tools/SkillTool/*` and plugin skill loading normalize multiple skill sources | preserve future skill packaging path | manifest `skills: tuple[str, ...]` | partial | Declare local identifiers only; no forked/remote/plugin skill execution |
+| Hook/platform integration | `/root/claude-code-haha/src/utils/hooks/*` provides a programmable extension layer | useful later, but unsafe to merge with manifest foundation now | existing Stage 4 hook registry | defer | Plugins cannot declare hook/runtime settings in Stage 7 |
+
+### Stage 7 references
+
+- cc-haha source evidence: `/root/claude-code-haha/src/services/mcp/types.ts`, `/root/claude-code-haha/src/services/mcp/config.ts`, `/root/claude-code-haha/src/services/mcp/utils.ts`, `/root/claude-code-haha/src/utils/plugins/schemas.ts`, `/root/claude-code-haha/src/utils/plugins/pluginLoader.ts`, `/root/claude-code-haha/src/utils/plugins/mcpPluginIntegration.ts`, `/root/claude-code-haha/src/tools/SkillTool/constants.ts`, `/root/claude-code-haha/src/tools/SkillTool/prompt.ts`, `/root/claude-code-haha/docs/must-read/06-extension-platform.md`.
+- LangChain reference: official LangChain MCP docs describe `langchain-mcp-adapters`, `MultiServerMCPClient.get_tools()`, stateless default sessions, and a separate resource-loading path via `get_resources()` / resource blobs.
+
+## Updated next candidates
+
+1. Stage 7.x: richer MCP config loading only if it can use official LangChain adapter seams without new runtime loops.
+2. Stage 8: recovery/checkpoint UX, task continuation, or multi-agent coordination once extension surfaces remain stable.
+
+
+## Stage 8 recovery/evidence/runtime-continuation rows
+
+## Expected effect
+
+Aligning Stage 8 should improve long-task continuity and verification readiness. The local runtime effect is: a recorded session can be resumed with history, latest runtime state, and recent evidence visible as a recovery brief, while later Task, Memory, and Subagent upgrades can attach to the same recovery/evidence seam.
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Transcript recovery | `/root/claude-code-haha/docs/must-read/02-agent-runtime.md` describes transcript + metadata as resume prerequisites | resumed sessions expose enough execution context to continue | `JsonlSessionStore` history/state/evidence loading | partial | Add session evidence records; defer full metadata runtime |
+| Task/runtime continuation | `/root/claude-code-haha/docs/must-read/04-task-workflow.md` describes stop/resume/poll around task runtime | future task/subagent work can link evidence to continuation | session-scoped evidence first | defer/partial | Defer task-level evidence store until task-core upgrade |
+| LangChain runtime | official LangChain docs describe `create_agent`, runtime context/store, and thread IDs | continuation stays on LangGraph runtime seams | `RuntimeInvocation`, session `thread_id`, CLI resume | align | Preserve runtime boundary; no custom query loop |
+| Evidence ledger | cc-haha session/task analysis keeps transcripts and execution facts separate from UI | tests and runtime facts become recoverable context | `SessionEvidence` + `RecoveryBrief` | partial | No model-visible evidence tool in Stage 8 |
+
+## Updated next candidates after Stage 8
+
+1. Facility B: Permission / trust boundary hardening.
+2. Facility C: Hooks / lifecycle expansion.
+3. Facility D: MCP / plugin real loading via official adapter seams.
+4. Then resume the nine cc-core primary system upgrades.
+
+
+## Stage 9 permission/trust-boundary rows
+
+## Expected effect
+
+Aligning Stage 9 should improve deterministic safety before later Skill, Task, Session, and MCP/plugin upgrades. The local runtime effect is: permission rules become typed local settings, trusted extra directories can be granted without global path weakening, and extension capabilities carry trust metadata so policy can treat them more conservatively than builtin tools.
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Permission layering | `/root/claude-code-haha/docs/must-read/05-permission-security.md` shows mode/rules/filesystem/strategy layers | preserve one permission runtime around all tools | `PermissionManager` + `ToolGuardMiddleware` | align | Harden existing path rather than redesign |
+| Rule sources and directories | cc-haha permission types/settings track rule origins and additional directories | allow explicit trusted scope without broadening workspace safety | typed settings-backed rules + `trusted_workdirs` | partial | local-only settings first |
+| Extension trust | later MCP/plugin tools expand execution surface | distinguish builtin vs extension trust at policy time | `ToolCapability(source, trusted)` | partial | deterministic conservative trust only |
+
+## Updated next candidates after Stage 9
+
+1. Facility C: Hooks / lifecycle expansion.
+2. Facility D: MCP / plugin real loading via official adapter seams.
+3. Then resume the nine cc-core primary system upgrades.
+
+
+## Stage 10 hooks/lifecycle rows
+
+## Expected effect
+
+Aligning Stage 10 should improve lifecycle extensibility before deeper Memory, Task, Session, and Skill upgrades. The local runtime effect is: deterministic local hooks can now observe and, where safe, block key lifecycle moments at the app and tool boundaries without replacing the LangChain runtime.
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Hook event/result schema | `/root/claude-code-haha/src/types/hooks.ts` validates hook outputs and event-specific payloads | keep typed local hook contracts | `HookPayload`, `HookResult`, `HookDispatchOutcome` | align | local sync schema only |
+| Hook runtime integration | cc-haha docs describe hooks as a programmable middleware layer, not an afterthought | lifecycle extension seam lives at real runtime boundaries | `app.agent_loop()` + `ToolGuardMiddleware` | partial | local sync + deterministic block only |
+| Hook platform breadth | cc-haha supports session/frontmatter/skill/HTTP/async hooks | avoid platform creep before the local seam proves useful | defer broader hook surfaces | defer | async/plugin/remote hooks remain later work |
+
+## Updated next candidates after Stage 10
+
+1. Facility D: MCP / plugin real loading via official adapter seams.
+2. Then resume the nine cc-core primary system upgrades with facilities A/B/C in place.
+
+
+## Stage 11 MCP/plugin real loading rows
+
+## Expected effect
+
+Aligning Stage 11 should turn the local MCP/plugin foundation into a usable local loading seam. The local runtime effect is: root `.mcp.json` config becomes a strict project config surface, official adapter-backed MCP tool loading can contribute capabilities when available, and plugin declarations are validated against known local capabilities/skills without opening platform or trust-scope creep.
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| `.mcp.json` config | Deep Agents / Claude-compatible docs use root `.mcp.json` as MCP config surface | familiar local config surface | typed root `.mcp.json` loader | partial | root-only in this stage |
+| Official MCP loading | LangChain docs use `MultiServerMCPClient(...).get_tools()` | real tools flow through official adapter seam | optional adapter-backed loader | align | adapter required but not auto-installed |
+| Plugin declaration validation | Stage 7 local plugin manifests declare local tools/skills/resources | plugins can safely reference known capabilities without runtime control | validated plugin registry | partial | validation-only, no runtime replacement |
+
+## Updated next candidates after Stage 11
+
+1. Resume the nine cc-core primary system upgrades with facilities A/B/C/D in place.
+2. Revisit dependency installation for first-class MCP support only if the user explicitly asks.
diff --git a/coding-deepgent/docs/review-checklist.md b/coding-deepgent/docs/review-checklist.md
new file mode 100644
index 000000000..29bb31ed8
--- /dev/null
+++ b/coding-deepgent/docs/review-checklist.md
@@ -0,0 +1,54 @@
+# s03 Review Checklist
+
+Use this checklist when reviewing or integrating `coding-deepgent/` changes.
+
+## 1. Independence from `agents_deepagents`
+
+- [ ] No runtime imports from `agents_deepagents`
+- [ ] No test imports from `agents_deepagents`
+- [ ] No project-local helper script depends on `agents_deepagents`
+- [ ] Behavioral parity is documented as reference knowledge, not shared code
+
+## 2. Cumulative app shape
+
+- [ ] The directory reads as one standalone project/package
+- [ ] The public surface is one integrated `s03` app/CLI
+- [ ] The implementation does not expose stage-mirror entrypoints as the main
+      interface
+- [ ] The current app includes `s01` loop behavior, `s02` tool growth, and
+      `s03` planning behavior together
+
+## 3. Responsibility boundaries
+
+- [ ] `config` owns environment/config loading
+- [ ] `state` owns runtime state definitions
+- [ ] `tools/filesystem` owns workspace tool behavior
+- [ ] `tools/planning` owns planning-tool updates
+- [ ] `middleware/planning` owns prompt/state mediation
+- [ ] `app` owns agent wiring
+- [ ] `cli` owns the command-line boundary
+- [ ] `tests` verify the project locally instead of reaching outward
+
+## 4. Planning-state quality guardrails
+
+- [ ] Planning state is explicit, reviewable, and bounded
+- [ ] The plan keeps at most one `in_progress` item
+- [ ] Planning updates happen through the intended tool/update path
+- [ ] Reminder or rendering behavior stays in middleware, not scattered across
+      unrelated modules
+
+## 5. Documentation + milestone consistency
+
+- [ ] `README.md` says the project is cumulative through `s03`
+- [ ] `PROJECT_PROGRESS.md` records the same milestone and upgrade gate
+- [ ] Docs explain that later upgrades are user-confirmed, not automatic
+- [ ] Docs clearly state that `agents_deepagents/` is reference-only
+
+## 6. Verification handoff
+
+The implementation/test lanes should be able to show evidence for:
+
+- [ ] standalone import/build health
+- [ ] focused tests for tools, app wiring, and planning behavior
+- [ ] absence of forbidden `agents_deepagents` dependencies
+- [ ] one integrated `s03` entrypoint instead of parallel public stages
diff --git a/coding-deepgent/docs/session-foundation-cc-alignment.md b/coding-deepgent/docs/session-foundation-cc-alignment.md
new file mode 100644
index 000000000..692fa2df4
--- /dev/null
+++ b/coding-deepgent/docs/session-foundation-cc-alignment.md
@@ -0,0 +1,41 @@
+# Session foundation cc-haha alignment note
+
+## Expected effect
+
+Aligning this behavior should improve reliability and product parity. The local
+effect is a small, testable session substrate: transcript records, same-workdir
+listing, resume-ready state snapshots, and a direct LangGraph `thread_id`
+mapping without pulling in cc-haha's broader resume UI or sidechain runtime.
+
+## Reference points inspected
+
+- `/root/claude-code-haha/src/types/logs.ts`
+- `/root/claude-code-haha/src/utils/sessionStorage.ts`
+- `/root/claude-code-haha/src/commands/resume/resume.tsx`
+- `/root/claude-code-haha/src/tools/AgentTool/resumeAgent.ts`
+- `/root/claude-code-haha/src/services/SessionMemory/sessionMemory.ts`
+
+## Alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Transcript identity | Serialized messages carry `cwd`, `sessionId`, `timestamp`, `version` | Stable local transcript records and deterministic lookup | `coding_deepgent.sessions.records` / `store_jsonl` | align | Keep the core identity fields in JSONL records |
+| Same-workdir resume filter | Resume starts from same-repo/session-filtered logs | Avoid cross-workdir leakage in product resume/listing | `JsonlSessionStore.list_sessions()` | align | Filter by resolved workdir and ignore unrelated transcripts |
+| LangGraph thread binding | Resume path depends on stable session identity | Future runtime wiring can map session id to `thread_id` directly | `coding_deepgent.sessions.langgraph` | partial | Provide the mapping helper now; full runtime injection is separate work |
+| State restore | cc-haha resume reconstructs richer runtime state from logs | Product resume keeps TodoWrite state instead of replaying messages only | `state_snapshot` handling in `store_jsonl` / `resume` | align | Last valid same-session snapshot wins; missing snapshots fall back to default state |
+| Lite/full logs, sidechains, cross-project flows | cc-haha supports richer resume UX and storage variants | Avoid speculative complexity before product runtime and CLI slices land | not implemented in this task | defer | Keep the domain transcript/resume-only for now |
+| SessionMemory and subagent resume | cc-haha layers later memory/subagent behavior on top of session logs | Preserve boundaries so sessions do not become memory/task/subagent storage | not implemented in this task | defer | Revisit only after those product stages exist |
+
+## What aligned now
+
+- Versioned JSONL `message` and `state_snapshot` records.
+- Same-workdir session lookup.
+- Resume-ready state restoration helper.
+- Session id to LangGraph `thread_id` mapping helper.
+
+## Intentionally not copied yet
+
+- Cross-project resume flows.
+- Lite/full transcript variants.
+- Sidechain/subagent transcript grouping.
+- SessionMemory extraction and richer resume reconstruction.
diff --git a/coding-deepgent/project_status.json b/coding-deepgent/project_status.json
new file mode 100644
index 000000000..3f1079b33
--- /dev/null
+++ b/coding-deepgent/project_status.json
@@ -0,0 +1,12 @@
+{
+  "project": "coding-deepgent",
+  "current_product_stage": "stage-11-mcp-plugin-real-loading",
+  "compatibility_anchor": "mcp-plugin-real-loading",
+  "architecture_reshape_status": "s1-skeleton-complete",
+  "shape": "staged_langchain_cc_product",
+  "public_shape": "single cumulative app",
+  "upgrade_policy": "Advance by explicit product-stage plan approval, not tutorial chapter completion.",
+  "public_entrypoints": [
+    "coding-deepgent"
+  ]
+}
diff --git a/coding-deepgent/pyproject.toml b/coding-deepgent/pyproject.toml
new file mode 100644
index 000000000..e9087092d
--- /dev/null
+++ b/coding-deepgent/pyproject.toml
@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "coding-deepgent"
+version = "0.1.0"
+description = "Staged LangChain cc product surface"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "dependency-injector>=4.48.0",
+  "langchain>=1.0.0",
+  "langchain-openai>=1.0.0",
+  "pydantic-settings>=2.8.0",
+  "python-dotenv>=1.0.0",
+  "pyyaml>=6.0",
+  "rich>=13.9.0",
+  "structlog>=24.4.0",
+  "typer>=0.16.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "mypy>=1.11.0",
+  "pytest>=8.0.0",
+  "ruff>=0.6.0",
+]
+
+[project.scripts]
+coding-deepgent = "coding_deepgent.cli:cli"
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]
diff --git a/coding-deepgent/src/coding_deepgent/__init__.py b/coding-deepgent/src/coding_deepgent/__init__.py
new file mode 100644
index 000000000..92c739db5
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/__init__.py
@@ -0,0 +1,5 @@
+"""coding-deepgent public package surface."""
+
+from .app import agent_loop, build_agent
+
+__all__ = ["agent_loop", "build_agent"]
diff --git a/coding-deepgent/src/coding_deepgent/__main__.py b/coding-deepgent/src/coding_deepgent/__main__.py
new file mode 100644
index 000000000..2834f1ec3
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/__main__.py
@@ -0,0 +1,3 @@
+from coding_deepgent.cli import cli
+
+raise SystemExit(cli())
diff --git a/coding-deepgent/src/coding_deepgent/agent_loop_service.py b/coding-deepgent/src/coding_deepgent/agent_loop_service.py
new file mode 100644
index 000000000..ac9acdcf9
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/agent_loop_service.py
@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from collections.abc import Callable, MutableMapping
+from typing import Any
+
+from coding_deepgent.agent_runtime_service import (
+    invoke_agent,
+    resolve_compiled_agent,
+    session_payload,
+    update_session_state,
+)
+from coding_deepgent.containers import AppContainer
+from coding_deepgent.hooks.dispatcher import dispatch_runtime_hook
+from coding_deepgent.rendering import latest_assistant_text, normalize_messages
+from coding_deepgent.runtime import RuntimeInvocation
+from coding_deepgent.sessions.records import SessionContext
+
+
+def is_new_session(
+    normalized_messages: list[dict[str, Any]],
+    session_state: MutableMapping[str, Any],
+) -> bool:
+    return (
+        len(normalized_messages) == 1
+        and not session_state.get("todos")
+        and session_state.get("rounds_since_update", 0) == 0
+    )
+
+
+def run_agent_loop(
+    *,
+    messages: list[dict[str, Any]],
+    session_state: MutableMapping[str, Any],
+    session_id: str | None,
+    container: AppContainer | None,
+    build_container: Callable[[], AppContainer],
+    build_agent: Callable[..., Any],
+    build_runtime_invocation: Callable[..., RuntimeInvocation],
+    session_context: SessionContext | None = None,
+) -> str:
+    active_container = container or build_container()
+    normalized = normalize_messages(messages)
+    invocation = build_runtime_invocation(
+        container=active_container,
+        session_id=session_id,
+        session_context=session_context,
+    )
+
+    if is_new_session(normalized, session_state):
+        dispatch_runtime_hook(
+            invocation,
+            event="SessionStart",
+            data={
+                "session_id": invocation.context.session_id,
+                "entrypoint": invocation.context.entrypoint,
+                "workdir": str(invocation.context.workdir),
+            },
+        )
+
+    prompt_submit = dispatch_runtime_hook(
+        invocation,
+        event="UserPromptSubmit",
+        data={
+            "session_id": invocation.context.session_id,
+            "message_count": len(normalized),
+            "latest_user_message": normalized[-1]["content"] if normalized else "",
+        },
+    )
+    if prompt_submit.blocked:
+        final_text = prompt_submit.reason or "UserPromptSubmit hook blocked execution."
+        messages.append({"role": "assistant", "content": final_text})
+        return final_text
+
+    result = invoke_agent(
+        resolve_compiled_agent(active_container, build_agent),
+        {"messages": normalized, **session_payload(session_state)},
+        invocation,
+    )
+    update_session_state(session_state, result)
+    final_text = latest_assistant_text(result)
+    if final_text:
+        messages.append({"role": "assistant", "content": final_text})
+    return final_text
diff --git a/coding-deepgent/src/coding_deepgent/agent_runtime_service.py b/coding-deepgent/src/coding_deepgent/agent_runtime_service.py
new file mode 100644
index 000000000..977c37976
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/agent_runtime_service.py
@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from collections.abc import Callable, MutableMapping
+from inspect import Parameter, signature
+from typing import Any
+
+from coding_deepgent.containers import AppContainer
+from coding_deepgent.runtime import RuntimeInvocation
+
+
+def supports_keyword_argument(callback: Callable[..., Any], keyword: str) -> bool:
+    try:
+        parameters = signature(callback).parameters.values()
+    except (TypeError, ValueError):
+        return True
+
+    return any(
+        parameter.kind == Parameter.VAR_KEYWORD or parameter.name == keyword
+        for parameter in parameters
+    )
+
+
+def resolve_compiled_agent(active_container: AppContainer, build_agent: Callable[..., Any]):
+    if supports_keyword_argument(build_agent, "container"):
+        return build_agent(container=active_container)
+    return build_agent()
+
+
+def invoke_agent(
+    compiled_agent: Any,
+    payload: dict[str, Any],
+    invocation: RuntimeInvocation,
+) -> dict[str, Any]:
+    invoke = compiled_agent.invoke
+    if supports_keyword_argument(invoke, "context") or supports_keyword_argument(
+        invoke, "config"
+    ):
+        return invoke(payload, context=invocation.context, config=invocation.config)
+    return invoke(payload)
+
+
+def session_payload(session_state: MutableMapping[str, Any]) -> dict[str, Any]:
+    return {
+        "todos": session_state.get("todos", []),
+        "rounds_since_update": session_state.get("rounds_since_update", 0),
+    }
+
+
+def update_session_state(
+    session_state: MutableMapping[str, Any],
+    result: dict[str, Any],
+) -> None:
+    session_state.update(
+        {
+            "todos": result.get("todos", []),
+            "rounds_since_update": result.get("rounds_since_update", 0),
+        }
+    )
diff --git a/coding-deepgent/src/coding_deepgent/agent_service.py b/coding-deepgent/src/coding_deepgent/agent_service.py
new file mode 100644
index 000000000..a9dd63405
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/agent_service.py
@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, Callable
+
+from coding_deepgent.prompting import build_prompt_context
+from coding_deepgent.settings import Settings
+from coding_deepgent.startup import StartupContractStatus
+
+
+def build_system_prompt(settings: Settings) -> str:
+    return build_prompt_context(
+        workdir=settings.workdir,
+        agent_name=settings.agent_name,
+        session_id="default",
+        entrypoint=settings.entrypoint,
+        custom_system_prompt=settings.custom_system_prompt,
+        append_system_prompt=settings.append_system_prompt,
+    ).system_prompt
+
+
+def singleton_list(item: object) -> list[object]:
+    return [item]
+
+
+def combine_middleware(*groups: Sequence[object]) -> list[object]:
+    combined: list[object] = []
+    for group in groups:
+        combined.extend(group)
+    return combined
+
+
+def create_compiled_agent(
+    create_agent_factory: Callable[..., Any],
+    *,
+    model: Any,
+    tools: Sequence[object],
+    system_prompt: str,
+    middleware: Sequence[object],
+    state_schema: type[Any],
+    context_schema: type[Any],
+    checkpointer: Any,
+    store: Any,
+) -> Any:
+    return create_agent_factory(
+        model=model,
+        tools=list(tools),
+        system_prompt=system_prompt,
+        middleware=list(middleware),
+        state_schema=state_schema,
+        context_schema=context_schema,
+        checkpointer=checkpointer,
+        store=store,
+        name="coding-deepgent",
+    )
+
+
+def create_compiled_agent_after_startup_validation(
+    *,
+    startup_contract: StartupContractStatus,
+    create_agent_factory: Callable[..., Any],
+    model: Any,
+    tools: Sequence[object],
+    system_prompt: str,
+    middleware: Sequence[object],
+    state_schema: type[Any],
+    context_schema: type[Any],
+    checkpointer: Any,
+    store: Any,
+) -> Any:
+    del startup_contract
+    return create_compiled_agent(
+        create_agent_factory,
+        model=model,
+        tools=tools,
+        system_prompt=system_prompt,
+        middleware=middleware,
+        state_schema=state_schema,
+        context_schema=context_schema,
+        checkpointer=checkpointer,
+        store=store,
+    )
diff --git a/coding-deepgent/src/coding_deepgent/app.py b/coding-deepgent/src/coding_deepgent/app.py
new file mode 100644
index 000000000..68dff5fc3
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/app.py
@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from collections.abc import MutableMapping
+from typing import Any
+
+from langchain.agents import create_agent
+
+from coding_deepgent import agent_loop_service
+from coding_deepgent import bootstrap
+from coding_deepgent.containers import AppContainer
+from coding_deepgent.settings import build_openai_model, load_settings
+from coding_deepgent.runtime import RuntimeInvocation, default_runtime_state
+from coding_deepgent.sessions.records import SessionContext
+
+
+def build_container() -> AppContainer:
+    container = bootstrap.build_container(
+        settings_loader=load_settings,
+        model_factory=build_openai_model,
+        create_agent_factory=create_agent,
+    )
+    bootstrap.validate_container_startup(container=container)
+    return container
+
+
+def build_agent(*, container: AppContainer | None = None):
+    active_container = container or build_container()
+    return bootstrap.build_agent(container=active_container)
+
+
+def build_runtime_invocation(
+    *,
+    container: AppContainer | None = None,
+    session_id: str | None = None,
+    session_context: SessionContext | None = None,
+) -> RuntimeInvocation:
+    active_container = container or build_container()
+    return bootstrap.build_runtime_invocation(
+        container=active_container,
+        session_id=session_id,
+        session_context=session_context,
+    )
+
+
+def agent_loop(
+    messages: list[dict[str, Any]],
+    *,
+    container: AppContainer | None = None,
+    session_state: MutableMapping[str, Any] | None = None,
+    session_id: str | None = None,
+    session_context: SessionContext | None = None,
+) -> str:
+    active_session_state = (
+        session_state if session_state is not None else default_runtime_state()
+    )
+    return agent_loop_service.run_agent_loop(
+        messages=messages,
+        session_state=active_session_state,
+        session_id=session_id,
+        container=container,
+        build_container=build_container,
+        build_agent=build_agent,
+        build_runtime_invocation=build_runtime_invocation,
+        session_context=session_context,
+    )
diff --git a/coding-deepgent/src/coding_deepgent/bootstrap.py b/coding-deepgent/src/coding_deepgent/bootstrap.py
new file mode 100644
index 000000000..e6f0c0c2e
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/bootstrap.py
@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from dependency_injector import providers
+
+from coding_deepgent.containers import AppContainer
+from coding_deepgent.sessions.records import SessionContext
+
+
+def build_container(
+    *,
+    settings_loader: Callable[[], Any],
+    model_factory: Callable[..., Any],
+    create_agent_factory: Any,
+) -> AppContainer:
+    container = AppContainer(
+        settings=providers.Singleton(settings_loader),
+        model=providers.Factory(model_factory),
+        create_agent_factory=providers.Object(create_agent_factory),
+    )
+    container.check_dependencies()
+    return container
+
+
+def validate_container_startup(*, container: AppContainer) -> Any:
+    return container.startup_contract()
+
+
+def build_agent(*, container: AppContainer) -> Any:
+    return container.agent()
+
+
+def build_runtime_invocation(
+    *,
+    container: AppContainer,
+    session_id: str | None = None,
+    session_context: SessionContext | None = None,
+):
+    return container.runtime.invocation(
+        session_id=session_id,
+        session_context=session_context,
+    )
diff --git a/coding-deepgent/src/coding_deepgent/cli.py b/coding-deepgent/src/coding_deepgent/cli.py
new file mode 100644
index 000000000..73448f48f
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/cli.py
@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+import typer
+from click.exceptions import ClickException
+from typer.main import get_command
+
+from coding_deepgent import cli_service
+from coding_deepgent.app import agent_loop
+from coding_deepgent.logging_config import configure_logging
+from coding_deepgent.renderers.text import (
+    render_config_table,
+    render_doctor_table,
+    render_session_table,
+)
+from coding_deepgent.rendering import extract_text
+from coding_deepgent.settings import build_openai_model
+
+app = typer.Typer(
+    add_completion=False,
+    help="Run the coding-deepgent LangChain cc product agent.",
+    no_args_is_help=True,
+)
+config_app = typer.Typer(help="Inspect resolved configuration.")
+sessions_app = typer.Typer(help="Inspect or resume recorded sessions.")
+app.add_typer(config_app, name="config")
+app.add_typer(sessions_app, name="sessions")
+
+
+def build_cli_runtime() -> cli_service.CliRuntime:
+    return cli_service.build_cli_runtime(agent_loop)
+
+
+def run_once(
+    prompt: str,
+    history: list[dict[str, object]] | None = None,
+    session_state: dict[str, object] | None = None,
+    session_id: str | None = None,
+) -> str:
+    return cli_service.run_once(
+        prompt=prompt,
+        run_agent=agent_loop,
+        history=history,
+        session_state=session_state,
+        session_id=session_id,
+        settings=build_cli_runtime().settings_loader(),
+    )
+
+
+def _emit_text(text: str) -> None:
+    typer.echo(text or "(no response)")
+
+
+def _run_prompt(
+    prompt: str,
+    *,
+    history: list[dict[str, Any]] | None = None,
+    session_state: dict[str, object] | None = None,
+    session_id: str | None = None,
+) -> None:
+    runtime = build_cli_runtime()
+    try:
+        result = runtime.run_prompt(prompt, history, session_state, session_id)
+    except RuntimeError as exc:  # pragma: no cover
+        raise ClickException(str(exc)) from exc
+    _emit_text(extract_text(result))
+
+
+@app.callback(invoke_without_command=True)
+def root(
+    prompt: str | None = typer.Option(
+        None, "--prompt", help="Run one prompt and exit."
+    ),
+) -> None:
+    if prompt is not None:
+        _run_prompt(prompt)
+        raise typer.Exit()
+
+
+@app.command("run")
+def run_command(
+    prompt: str = typer.Argument(..., help="Prompt to send to the agent."),
+) -> None:
+    _run_prompt(prompt)
+
+
+@config_app.command("show")
+def config_show() -> None:
+    runtime = build_cli_runtime()
+    typer.echo(render_config_table(cli_service.config_rows(runtime.settings_loader())))
+
+
+@sessions_app.command("list")
+def sessions_list() -> None:
+    runtime = build_cli_runtime()
+    sessions = [
+        {
+            "session_id": session.session_id,
+            "updated_at": session.updated_at,
+            "message_count": session.message_count,
+            "workdir": session.workdir,
+        }
+        for session in runtime.list_sessions()
+    ]
+    typer.echo(render_session_table(sessions))
+
+
+@sessions_app.command("resume")
+def sessions_resume(
+    session_id: str = typer.Argument(..., help="Session identifier to resume."),
+    prompt: str | None = typer.Option(
+        None, "--prompt", help="Optional prompt to continue the session."
+    ),
+    compact_summary: str | None = typer.Option(
+        None,
+        "--compact-summary",
+        help="Optional manual compact summary to use for continuation history.",
+    ),
+    generate_compact_summary: bool = typer.Option(
+        False,
+        "--generate-compact-summary",
+        help="Generate a manual compact summary for continuation history.",
+    ),
+    compact_instructions: str | None = typer.Option(
+        None,
+        "--compact-instructions",
+        help="Optional additional instructions for generated compact summary.",
+    ),
+    compact_keep_last: int = typer.Option(
+        4,
+        "--compact-keep-last",
+        min=0,
+        help="Number of recent messages to preserve after manual compaction.",
+    ),
+) -> None:
+    runtime = build_cli_runtime()
+    try:
+        loaded = runtime.load_session(session_id)
+    except KeyError as exc:
+        raise ClickException(str(exc)) from exc
+
+    if prompt is None:
+        if (
+            compact_summary is not None
+            or generate_compact_summary
+            or compact_instructions is not None
+        ):
+            raise ClickException("compact options require --prompt.")
+        typer.echo(cli_service.recovery_brief_text(loaded))
+        typer.echo("Re-run with --prompt to continue.")
+        raise typer.Exit()
+    if compact_summary is not None and generate_compact_summary:
+        raise ClickException(
+            "--compact-summary and --generate-compact-summary are mutually exclusive."
+        )
+    if compact_instructions is not None and not generate_compact_summary:
+        raise ClickException("--compact-instructions requires --generate-compact-summary.")
+
+    try:
+        if generate_compact_summary:
+            history = cli_service.generated_compacted_continuation_history(
+                loaded,
+                summarizer=build_openai_model(runtime.settings_loader()),
+                keep_last=compact_keep_last,
+                custom_instructions=compact_instructions,
+            )
+        elif compact_summary is not None:
+            history = cli_service.compacted_continuation_history(
+                loaded,
+                summary=compact_summary,
+                keep_last=compact_keep_last,
+            )
+        else:
+            history = cli_service.selected_continuation_history(loaded)
+    except (RuntimeError, ValueError) as exc:
+        raise ClickException(str(exc)) from exc
+
+    _run_prompt(
+        prompt,
+        history=history,
+        session_state=loaded.state,
+        session_id=loaded.summary.session_id,
+    )
+
+
+@app.command("doctor")
+def doctor() -> None:
+    configure_logging()
+    runtime = build_cli_runtime()
+    checks = [
+        {"name": check.name, "status": check.status, "detail": check.detail}
+        for check in runtime.doctor_checks()
+    ]
+    typer.echo(render_doctor_table(checks))
+
+
+def main(argv: list[str] | None = None) -> int:
+    command = get_command(app)
+    try:
+        command.main(
+            args=argv or [], prog_name="coding-deepgent", standalone_mode=False
+        )
+    except ClickException as exc:
+        exc.show()
+        return exc.exit_code
+    except SystemExit as exc:
+        if isinstance(exc.code, int):
+            return exc.code
+        return 0
+    return 0
+
+
+def cli(argv: list[str] | None = None) -> int:
+    return main(sys.argv[1:] if argv is None else argv)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()
diff --git a/coding-deepgent/src/coding_deepgent/cli_service.py b/coding-deepgent/src/coding_deepgent/cli_service.py
new file mode 100644
index 000000000..622ae02ce
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/cli_service.py
@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import importlib.util
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Sequence
+
+from coding_deepgent.compact import (
+    compact_messages_with_summary,
+    generate_compact_summary,
+)
+from coding_deepgent.logging_config import safe_environment_snapshot
+from coding_deepgent.settings import Settings, load_settings
+from coding_deepgent.sessions import (
+    LoadedSession,
+    SessionLoadError,
+    build_recovery_brief,
+    build_resume_context_message,
+    render_recovery_brief,
+)
+from coding_deepgent.sessions.service import (
+    list_recorded_sessions,
+    load_recorded_session,
+    run_prompt_with_recording,
+)
+
+
+@dataclass(frozen=True)
+class SessionSummaryView:
+    session_id: str
+    updated_at: str
+    message_count: int
+    workdir: str
+
+
+@dataclass(frozen=True)
+class DoctorCheck:
+    name: str
+    status: str
+    detail: str
+
+
+@dataclass(frozen=True)
+class CliRuntime:
+    settings_loader: Callable[[], Settings]
+    list_sessions: Callable[[], Sequence[SessionSummaryView]]
+    load_session: Callable[[str], LoadedSession]
+    run_prompt: Callable[
+        [str, list[dict[str, Any]] | None, dict[str, Any] | None, str | None], str
+    ]
+    doctor_checks: Callable[[], Sequence[DoctorCheck]]
+
+
+def default_session_dir(settings: Settings) -> Path:
+    configured = os.getenv("CODING_DEEPGENT_SESSION_DIR")
+    if configured:
+        return Path(configured).expanduser().resolve()
+    return settings.session_dir
+
+
+def dependency_status(module_name: str) -> str:
+    return "installed" if importlib.util.find_spec(module_name) else "missing"
+
+
+def doctor_checks(settings: Settings) -> Sequence[DoctorCheck]:
+    safe_env = safe_environment_snapshot(os.environ)
+    return [
+        DoctorCheck(
+            "openai_api_key",
+            safe_env["OPENAI_API_KEY"],
+            "Required only for live run commands.",
+        ),
+        DoctorCheck("model_name", "resolved", settings.model_name),
+        DoctorCheck("workdir", "ready", str(settings.workdir)),
+        DoctorCheck("session_dir", "ready", str(default_session_dir(settings))),
+        DoctorCheck("typer", dependency_status("typer"), "CLI command surface."),
+        DoctorCheck("rich", dependency_status("rich"), "Terminal rendering dependency."),
+        DoctorCheck(
+            "structlog",
+            dependency_status("structlog"),
+            "Structured local logging dependency.",
+        ),
+    ]
+
+
+def recorded_sessions(settings: Settings) -> Sequence[SessionSummaryView]:
+    return [
+        SessionSummaryView(
+            session_id=summary.session_id,
+            updated_at=summary.updated_at or "unknown",
+            message_count=summary.message_count,
+            workdir=str(summary.workdir),
+        )
+        for summary in list_recorded_sessions(settings)
+    ]
+
+
+def load_session(settings: Settings, session_id: str) -> LoadedSession:
+    try:
+        return load_recorded_session(settings, session_id)
+    except SessionLoadError as exc:
+        raise KeyError(str(exc)) from exc
+
+
+def run_once(
+    *,
+    settings: Settings,
+    prompt: str,
+    run_agent: Callable[..., str],
+    history: list[dict[str, Any]] | None = None,
+    session_state: dict[str, Any] | None = None,
+    session_id: str | None = None,
+) -> str:
+    return run_prompt_with_recording(
+        settings=settings,
+        prompt=prompt,
+        run_agent=run_agent,
+        history=history,
+        session_state=session_state,
+        session_id=session_id,
+    )
+
+
+def recovery_brief_text(loaded: LoadedSession) -> str:
+    return render_recovery_brief(build_recovery_brief(loaded))
+
+
+def continuation_history(loaded: LoadedSession) -> list[dict[str, Any]]:
+    return [
+        build_resume_context_message(loaded),
+        *(dict(message) for message in loaded.history),
+    ]
+
+
+def selected_continuation_history(loaded: LoadedSession) -> list[dict[str, Any]]:
+    return [
+        build_resume_context_message(loaded),
+        *[dict(message) for message in loaded.compacted_history],
+    ]
+
+
+def compacted_continuation_history(
+    loaded: LoadedSession,
+    *,
+    summary: str,
+    keep_last: int = 4,
+) -> list[dict[str, Any]]:
+    artifact = compact_messages_with_summary(
+        [dict(message) for message in loaded.history],
+        summary=summary,
+        keep_last=keep_last,
+    )
+    return [
+        build_resume_context_message(loaded),
+        *artifact.messages,
+    ]
+
+
+def generated_compacted_continuation_history(
+    loaded: LoadedSession,
+    *,
+    summarizer: Any,
+    keep_last: int = 4,
+    custom_instructions: str | None = None,
+) -> list[dict[str, Any]]:
+    summary = generate_compact_summary(
+        [dict(message) for message in loaded.history],
+        summarizer,
+        custom_instructions=custom_instructions,
+    )
+    return compacted_continuation_history(
+        loaded,
+        summary=summary,
+        keep_last=keep_last,
+    )
+
+
+def config_rows(settings: Settings) -> list[tuple[str, str]]:
+    safe_env = safe_environment_snapshot(os.environ)
+    return [
+        ("workdir", str(settings.workdir)),
+        ("model_name", settings.model_name),
+        ("openai_base_url", safe_env["OPENAI_BASE_URL"]),
+        ("openai_api_key", safe_env["OPENAI_API_KEY"]),
+        ("session_dir", str(default_session_dir(settings))),
+    ]
+
+
+def build_cli_runtime(
+    run_agent: Callable[..., str],
+    *,
+    settings_loader: Callable[[], Settings] | None = None,
+) -> CliRuntime:
+    active_settings_loader = settings_loader or load_settings
+    return CliRuntime(
+        settings_loader=active_settings_loader,
+        list_sessions=lambda: recorded_sessions(active_settings_loader()),
+        load_session=lambda session_id: load_session(
+            active_settings_loader(), session_id
+        ),
+        run_prompt=lambda prompt, history, session_state, session_id: run_once(
+            settings=active_settings_loader(),
+            prompt=prompt,
+            run_agent=run_agent,
+            history=history,
+            session_state=session_state,
+            session_id=session_id,
+        ),
+        doctor_checks=lambda: doctor_checks(active_settings_loader()),
+    )
diff --git a/coding-deepgent/src/coding_deepgent/compact/__init__.py b/coding-deepgent/src/coding_deepgent/compact/__init__.py
new file mode 100644
index 000000000..210653bde
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/compact/__init__.py
@@ -0,0 +1,39 @@
+from .budget import BudgetedText, TRUNCATION_MARKER, apply_tool_result_budget
+from .artifacts import (
+    COMPACT_BOUNDARY_PREFIX,
+    COMPACT_METADATA_KEY,
+    COMPACT_SUMMARY_PREFIX,
+    CompactArtifact,
+    compact_metadata,
+    compact_messages_with_summary,
+    compact_record_from_messages,
+    format_compact_summary,
+    is_compact_artifact_message,
+)
+from .projection import project_messages
+from .summarizer import (
+    COMPACT_SUMMARY_PROMPT,
+    build_compact_summary_prompt,
+    build_compact_summary_request,
+    generate_compact_summary,
+)
+
+__all__ = [
+    "BudgetedText",
+    "COMPACT_BOUNDARY_PREFIX",
+    "COMPACT_METADATA_KEY",
+    "COMPACT_SUMMARY_PREFIX",
+    "COMPACT_SUMMARY_PROMPT",
+    "CompactArtifact",
+    "TRUNCATION_MARKER",
+    "apply_tool_result_budget",
+    "build_compact_summary_prompt",
+    "build_compact_summary_request",
+    "compact_metadata",
+    "compact_messages_with_summary",
+    "compact_record_from_messages",
+    "format_compact_summary",
+    "generate_compact_summary",
+    "is_compact_artifact_message",
+    "project_messages",
+]
diff --git a/coding-deepgent/src/coding_deepgent/compact/artifacts.py b/coding-deepgent/src/coding_deepgent/compact/artifacts.py
new file mode 100644
index 000000000..3fc2c544a
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/compact/artifacts.py
@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+import re
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import Any, Literal
+
+COMPACT_BOUNDARY_PREFIX = "coding-deepgent compact boundary"
+COMPACT_SUMMARY_PREFIX = (
+    "This session is being continued from a compacted conversation."
+)
+COMPACT_METADATA_KEY = "coding_deepgent_compact"
+
+
+@dataclass(frozen=True, slots=True)
+class CompactArtifact:
+    trigger: Literal["manual"]
+    summary: str
+    original_message_count: int
+    summarized_message_count: int
+    kept_message_count: int
+    messages: list[dict[str, Any]]
+
+
+def compact_messages_with_summary(
+    messages: list[dict[str, Any]],
+    *,
+    summary: str,
+    keep_last: int = 4,
+) -> CompactArtifact:
+    if not messages:
+        raise ValueError("messages are required for compaction")
+    if keep_last < 0:
+        raise ValueError("keep_last must be non-negative")
+
+    formatted_summary = format_compact_summary(summary)
+    if not formatted_summary:
+        raise ValueError("summary is required for compaction")
+
+    clean_messages = [
+        deepcopy(message)
+        for message in messages
+        if not is_compact_artifact_message(message)
+    ]
+    keep_start = _adjust_keep_start_for_tool_pairs(
+        clean_messages, max(0, len(clean_messages) - keep_last)
+    )
+    kept_messages = clean_messages[keep_start:]
+    artifact_messages = [
+        build_compact_boundary_message(
+            trigger="manual",
+            original_message_count=len(clean_messages),
+            summarized_message_count=keep_start,
+            kept_message_count=len(kept_messages),
+        ),
+        build_compact_summary_message(formatted_summary),
+        *kept_messages,
+    ]
+    return CompactArtifact(
+        trigger="manual",
+        summary=formatted_summary,
+        original_message_count=len(clean_messages),
+        summarized_message_count=keep_start,
+        kept_message_count=len(kept_messages),
+        messages=artifact_messages,
+    )
+
+
+def build_compact_boundary_message(
+    *,
+    trigger: Literal["manual"],
+    original_message_count: int,
+    summarized_message_count: int,
+    kept_message_count: int,
+) -> dict[str, Any]:
+    return {
+        "role": "system",
+        "metadata": {
+            COMPACT_METADATA_KEY: {
+                "kind": "boundary",
+                "trigger": trigger,
+                "original_message_count": original_message_count,
+                "summarized_message_count": summarized_message_count,
+                "kept_message_count": kept_message_count,
+            }
+        },
+        "content": [
+            {
+                "type": "text",
+                "text": (
+                    f"{COMPACT_BOUNDARY_PREFIX}: trigger={trigger}; "
+                    f"original_messages={original_message_count}; "
+                    f"summarized_messages={summarized_message_count}; "
+                    f"kept_messages={kept_message_count}"
+                ),
+            }
+        ],
+    }
+
+
+def build_compact_summary_message(summary: str) -> dict[str, Any]:
+    return {
+        "role": "user",
+        "metadata": {
+            COMPACT_METADATA_KEY: {
+                "kind": "summary",
+                "summary": summary,
+            }
+        },
+        "content": [
+            {
+                "type": "text",
+                "text": f"{COMPACT_SUMMARY_PREFIX}\n\nSummary:\n{summary}",
+            }
+        ],
+    }
+
+
+def format_compact_summary(summary: str) -> str:
+    formatted = re.sub(r"<analysis>[\s\S]*?</analysis>", "", summary).strip()
+    summary_match = re.search(r"<summary>([\s\S]*?)</summary>", formatted)
+    if summary_match:
+        formatted = summary_match.group(1) or ""
+    return re.sub(r"\n\n+", "\n\n", formatted).strip()
+
+
+def is_compact_artifact_message(message: dict[str, Any]) -> bool:
+    if compact_metadata(message) is not None:
+        return True
+    text = _message_text(message)
+    return text.startswith(COMPACT_BOUNDARY_PREFIX) or text.startswith(
+        COMPACT_SUMMARY_PREFIX
+    )
+
+
+def compact_metadata(message: dict[str, Any]) -> dict[str, Any] | None:
+    metadata = message.get("metadata")
+    if not isinstance(metadata, dict):
+        return None
+    compact = metadata.get(COMPACT_METADATA_KEY)
+    return compact if isinstance(compact, dict) else None
+
+
+def compact_record_from_messages(messages: list[dict[str, Any]]) -> dict[str, Any] | None:
+    boundary: dict[str, Any] | None = None
+    summary: dict[str, Any] | None = None
+    for message in messages:
+        metadata = compact_metadata(message)
+        if metadata is None:
+            continue
+        if metadata.get("kind") == "boundary":
+            boundary = metadata
+            summary = None
+        elif metadata.get("kind") == "summary" and boundary is not None:
+            summary = metadata
+
+    if boundary is None or summary is None:
+        return None
+    summary_text = summary.get("summary")
+    if not isinstance(summary_text, str) or not summary_text.strip():
+        return None
+    return {
+        "trigger": str(boundary.get("trigger", "manual")),
+        "summary": summary_text.strip(),
+        "original_message_count": _int_field(boundary, "original_message_count"),
+        "summarized_message_count": _int_field(boundary, "summarized_message_count"),
+        "kept_message_count": _int_field(boundary, "kept_message_count"),
+    }
+
+
+def _adjust_keep_start_for_tool_pairs(
+    messages: list[dict[str, Any]],
+    start_index: int,
+) -> int:
+    if start_index <= 0 or start_index >= len(messages):
+        return start_index
+
+    needed_tool_uses = _tool_result_ids(messages[start_index:])
+    if not needed_tool_uses:
+        return start_index
+
+    kept_tool_uses = _tool_use_ids(messages[start_index:])
+    missing_tool_uses = needed_tool_uses - kept_tool_uses
+    adjusted = start_index
+    for index in range(start_index - 1, -1, -1):
+        message_tool_uses = _tool_use_ids([messages[index]])
+        if missing_tool_uses & message_tool_uses:
+            adjusted = index
+            missing_tool_uses -= message_tool_uses
+        if not missing_tool_uses:
+            break
+    return adjusted
+
+
+def _int_field(metadata: dict[str, Any], key: str) -> int:
+    value = metadata.get(key)
+    return value if isinstance(value, int) else 0
+
+
+def _tool_result_ids(messages: list[dict[str, Any]]) -> set[str]:
+    ids: set[str] = set()
+    for message in messages:
+        content = message.get("content")
+        if not isinstance(content, list):
+            continue
+        for block in content:
+            if isinstance(block, dict) and block.get("type") == "tool_result":
+                tool_use_id = block.get("tool_use_id")
+                if isinstance(tool_use_id, str) and tool_use_id:
+                    ids.add(tool_use_id)
+    return ids
+
+
+def _tool_use_ids(messages: list[dict[str, Any]]) -> set[str]:
+    ids: set[str] = set()
+    for message in messages:
+        content = message.get("content")
+        if not isinstance(content, list):
+            continue
+        for block in content:
+            if isinstance(block, dict) and block.get("type") == "tool_use":
+                tool_use_id = block.get("id")
+                if isinstance(tool_use_id, str) and tool_use_id:
+                    ids.add(tool_use_id)
+    return ids
+
+
+def _message_text(message: dict[str, Any]) -> str:
+    content = message.get("content", "")
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = [
+            str(block.get("text", ""))
+            for block in content
+            if isinstance(block, dict) and block.get("type") in {"text", "output_text"}
+        ]
+        return "\n".join(part for part in parts if part)
+    return str(content)
diff --git a/coding-deepgent/src/coding_deepgent/compact/budget.py b/coding-deepgent/src/coding_deepgent/compact/budget.py
new file mode 100644
index 000000000..7b6c10275
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/compact/budget.py
@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+TRUNCATION_MARKER = "\n...[tool result truncated by coding-deepgent budget]"
+
+
+@dataclass(frozen=True, slots=True)
+class BudgetedText:
+    text: str
+    original_length: int
+    truncated: bool
+    omitted_chars: int = 0
+
+
+def apply_tool_result_budget(text: str, *, max_chars: int) -> BudgetedText:
+    if max_chars < len(TRUNCATION_MARKER) + 1:
+        raise ValueError("max_chars must leave room for truncation marker")
+    original_length = len(text)
+    if original_length <= max_chars:
+        return BudgetedText(text=text, original_length=original_length, truncated=False)
+    keep = max_chars - len(TRUNCATION_MARKER)
+    return BudgetedText(
+        text=text[:keep] + TRUNCATION_MARKER,
+        original_length=original_length,
+        truncated=True,
+        omitted_chars=original_length - keep,
+    )
diff --git a/coding-deepgent/src/coding_deepgent/compact/projection.py b/coding-deepgent/src/coding_deepgent/compact/projection.py
new file mode 100644
index 000000000..dccaf52c5
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/compact/projection.py
@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+from coding_deepgent.compact.budget import apply_tool_result_budget
+
+
+def project_messages(
+    messages: list[dict[str, Any]],
+    *,
+    max_chars_per_message: int | None = None,
+) -> list[dict[str, Any]]:
+    projected: list[dict[str, Any]] = []
+
+    for message in messages:
+        normalized = _normalize_message(
+            message, max_chars_per_message=max_chars_per_message
+        )
+        if projected and _can_merge_text_messages(projected[-1], normalized):
+            merged = f"{projected[-1]['content']}\n\n{normalized['content']}"
+            projected[-1]["content"] = _project_content(
+                merged, max_chars_per_message=max_chars_per_message
+            )
+            continue
+        projected.append(normalized)
+
+    return projected
+
+
+def _normalize_message(
+    message: dict[str, Any],
+    *,
+    max_chars_per_message: int | None,
+) -> dict[str, Any]:
+    normalized = deepcopy(message)
+    normalized["role"] = message.get("role", "user")
+    normalized["content"] = _project_content(
+        message.get("content", ""), max_chars_per_message=max_chars_per_message
+    )
+    return normalized
+
+
+def _project_content(content: Any, *, max_chars_per_message: int | None) -> Any:
+    if isinstance(content, str) and max_chars_per_message is not None:
+        return apply_tool_result_budget(content, max_chars=max_chars_per_message).text
+    return content
+
+
+def _can_merge_text_messages(left: dict[str, Any], right: dict[str, Any]) -> bool:
+    if left.get("role") != right.get("role"):
+        return False
+    if not isinstance(left.get("content"), str) or not isinstance(
+        right.get("content"), str
+    ):
+        return False
+    if set(left.keys()) != {"role", "content"}:
+        return False
+    if set(right.keys()) != {"role", "content"}:
+        return False
+    return True
diff --git a/coding-deepgent/src/coding_deepgent/compact/summarizer.py b/coding-deepgent/src/coding_deepgent/compact/summarizer.py
new file mode 100644
index 000000000..1361c7ec5
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/compact/summarizer.py
@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from copy import deepcopy
+from typing import Any, Protocol
+
+from coding_deepgent.compact.artifacts import format_compact_summary
+
+COMPACT_SUMMARY_PROMPT = """Create a detailed compact summary of the conversation above.
+
+Respond with text only. Do not call tools.
+Use this shape:
+
+<analysis>
+Brief private checklist to ensure the summary is complete.
+</analysis>
+
+<summary>
+Include the user's intent, decisions made, files or code touched, errors and fixes, current work, and the next continuation step if one is known.
+</summary>
+"""
+
+
+class CompactSummarizer(Protocol):
+    def invoke(self, messages: list[dict[str, Any]]) -> Any: ...
+
+
+def build_compact_summary_prompt(custom_instructions: str | None = None) -> str:
+    if custom_instructions and custom_instructions.strip():
+        return (
+            f"{COMPACT_SUMMARY_PROMPT}\n\n"
+            f"Additional instructions:\n{custom_instructions.strip()}"
+        )
+    return COMPACT_SUMMARY_PROMPT
+
+
+def build_compact_summary_request(
+    messages: list[dict[str, Any]],
+    *,
+    custom_instructions: str | None = None,
+) -> list[dict[str, Any]]:
+    return [
+        *deepcopy(messages),
+        {
+            "role": "user",
+            "content": [
+                {
+                    "type": "text",
+                    "text": build_compact_summary_prompt(custom_instructions),
+                }
+            ],
+        },
+    ]
+
+
+def generate_compact_summary(
+    messages: list[dict[str, Any]],
+    summarizer: CompactSummarizer | Callable[[list[dict[str, Any]]], Any],
+    *,
+    custom_instructions: str | None = None,
+) -> str:
+    request = build_compact_summary_request(
+        messages,
+        custom_instructions=custom_instructions,
+    )
+    response = (
+        summarizer(request)
+        if callable(summarizer) and not hasattr(summarizer, "invoke")
+        else summarizer.invoke(request)  # type: ignore[union-attr]
+    )
+    summary = format_compact_summary(_extract_text(response))
+    if not summary:
+        raise ValueError("compact summarizer returned an empty summary")
+    return summary
+
+
+def _extract_text(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value.strip()
+    if isinstance(value, dict):
+        if "content" in value:
+            return _extract_text(value["content"])
+        if "messages" in value and isinstance(value["messages"], list):
+            for message in reversed(value["messages"]):
+                message_text = _extract_text(message)
+                if message_text:
+                    return message_text
+            return ""
+    if isinstance(value, list):
+        parts: list[str] = []
+        for item in value:
+            if isinstance(item, dict):
+                if item.get("type") in {"text", "output_text"} and item.get("text"):
+                    parts.append(str(item["text"]))
+                elif item.get("content"):
+                    parts.append(_extract_text(item["content"]))
+                continue
+            item_text = getattr(item, "text", None)
+            if isinstance(item_text, str):
+                parts.append(item_text)
+        return "\n".join(part for part in parts if part).strip()
+
+    content = getattr(value, "content", None)
+    if content is not None:
+        return _extract_text(content)
+    return str(value).strip()
diff --git a/coding-deepgent/src/coding_deepgent/containers/__init__.py b/coding-deepgent/src/coding_deepgent/containers/__init__.py
new file mode 100644
index 000000000..0b784c6ae
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/containers/__init__.py
@@ -0,0 +1,15 @@
+from .app import AppContainer
+from .filesystem import FilesystemContainer
+from .runtime import RuntimeContainer
+from .sessions import SessionsContainer
+from .todo import TodoContainer
+from .tool_system import ToolSystemContainer
+
+__all__ = [
+    "AppContainer",
+    "FilesystemContainer",
+    "RuntimeContainer",
+    "SessionsContainer",
+    "TodoContainer",
+    "ToolSystemContainer",
+]
diff --git a/coding-deepgent/src/coding_deepgent/containers/app.py b/coding-deepgent/src/coding_deepgent/containers/app.py
new file mode 100644
index 000000000..ddd7ac5aa
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/containers/app.py
@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from typing import Any
+
+from dependency_injector import containers, providers
+from langchain.agents import create_agent as langchain_create_agent
+
+from coding_deepgent import agent_service
+from coding_deepgent import extensions_service
+from coding_deepgent.memory import MemoryContextMiddleware
+from coding_deepgent.settings import build_openai_model, load_settings
+from coding_deepgent.startup import require_startup_contract, validate_startup_contract
+
+from .filesystem import FilesystemContainer
+from .runtime import RuntimeContainer
+from .sessions import SessionsContainer
+from .todo import TodoContainer
+from .tool_system import ToolSystemContainer
+
+class AppContainer(containers.DeclarativeContainer):
+    settings: Any = providers.Dependency(default=providers.Singleton(load_settings))
+    model: Any = providers.Dependency(default=providers.Factory(build_openai_model))
+    create_agent_factory: Any = providers.Dependency(
+        default=providers.Object(langchain_create_agent)
+    )
+    extension_capabilities: Any = providers.Dependency(default=providers.Object([]))
+
+    runtime: Any = providers.Container(RuntimeContainer, settings=settings)
+    todo: Any = providers.Container(TodoContainer)
+    filesystem: Any = providers.Container(FilesystemContainer)
+    sessions: Any = providers.Container(SessionsContainer)
+    mcp_runtime_load_result: Any = providers.Callable(
+        extensions_service.mcp_runtime_load_result,
+        settings,
+    )
+    mcp_capabilities: Any = providers.Callable(
+        extensions_service.mcp_capabilities,
+        mcp_runtime_load_result,
+    )
+    all_extension_capabilities: Any = providers.Callable(
+        extensions_service.combine_extension_capabilities,
+        extension_capabilities,
+        mcp_capabilities,
+    )
+    tool_system: Any = providers.Container(
+        ToolSystemContainer,
+        filesystem_tools=filesystem.tools,
+        todo_tools=todo.tools,
+        extension_capabilities=all_extension_capabilities,
+        permission_mode=settings.provided.permission_mode,
+        permission_allow_rules=settings.provided.permission_allow_rules,
+        permission_ask_rules=settings.provided.permission_ask_rules,
+        permission_deny_rules=settings.provided.permission_deny_rules,
+        workdir=settings.provided.workdir,
+        trusted_workdirs=settings.provided.trusted_workdirs,
+        event_sink=runtime.event_sink,
+    )
+
+    plugin_registry: Any = providers.Callable(extensions_service.plugin_registry, settings)
+    validated_plugin_registry: Any = providers.Callable(
+        extensions_service.validate_plugin_registry,
+        plugin_registry,
+        settings,
+        tool_system.capability_registry,
+    )
+    startup_contract: Any = providers.Callable(
+        validate_startup_contract,
+        validated_plugin_registry=validated_plugin_registry,
+        mcp_runtime_load_result=mcp_runtime_load_result,
+    )
+    validated_startup_contract: Any = providers.Callable(
+        require_startup_contract,
+        startup_contract,
+    )
+    system_prompt: Any = providers.Callable(agent_service.build_system_prompt, settings)
+    memory_middleware: Any = providers.Factory(MemoryContextMiddleware)
+    memory_middleware_list: Any = providers.Callable(
+        agent_service.singleton_list, memory_middleware
+    )
+    middleware: Any = providers.Callable(
+        agent_service.combine_middleware,
+        todo.middleware_list,
+        memory_middleware_list,
+        tool_system.middleware_list,
+    )
+    agent: Any = providers.Factory(
+        agent_service.create_compiled_agent_after_startup_validation,
+        startup_contract=validated_startup_contract,
+        create_agent_factory=create_agent_factory,
+        model=model,
+        tools=tool_system.tools,
+        system_prompt=system_prompt,
+        middleware=middleware,
+        state_schema=runtime.state_schema,
+        context_schema=runtime.context_schema,
+        checkpointer=runtime.checkpointer,
+        store=runtime.store,
+    )
+
+    capability_registry: Any = tool_system.capability_registry
+    session_store: Any = sessions.session_store
diff --git a/coding-deepgent/src/coding_deepgent/containers/filesystem.py b/coding-deepgent/src/coding_deepgent/containers/filesystem.py
new file mode 100644
index 000000000..0612f2f32
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/containers/filesystem.py
@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from dependency_injector import containers, providers
+
+from coding_deepgent.filesystem import bash, edit_file, read_file, write_file
+
+
+def _tool_list(*tools: object) -> list[object]:
+    return list(tools)
+
+
+class FilesystemContainer(containers.DeclarativeContainer):
+    bash = providers.Object(bash)
+    read_file = providers.Object(read_file)
+    write_file = providers.Object(write_file)
+    edit_file = providers.Object(edit_file)
+    tools = providers.Callable(_tool_list, bash, read_file, write_file, edit_file)
diff --git a/coding-deepgent/src/coding_deepgent/containers/runtime.py b/coding-deepgent/src/coding_deepgent/containers/runtime.py
new file mode 100644
index 000000000..e4798af3d
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/containers/runtime.py
@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import Any
+
+from dependency_injector import containers, providers
+
+from coding_deepgent.hooks import LocalHookRegistry
+from coding_deepgent.runtime import (
+    InMemoryEventSink,
+    PlanningState,
+    RuntimeContext,
+    build_runtime_context,
+    build_runtime_invocation,
+    default_runtime_state,
+    select_checkpointer,
+    select_store,
+)
+
+
+class RuntimeContainer(containers.DeclarativeContainer):
+    settings: Any = providers.Dependency()
+
+    event_sink: Any = providers.Singleton(InMemoryEventSink)
+    hook_registry: Any = providers.Singleton(LocalHookRegistry)
+    state_schema: Any = providers.Object(PlanningState)
+    context_schema: Any = providers.Object(RuntimeContext)
+    default_state: Any = providers.Callable(default_runtime_state)
+    context: Any = providers.Factory(
+        build_runtime_context,
+        settings=settings,
+        event_sink=event_sink,
+        hook_registry=hook_registry,
+    )
+    invocation: Any = providers.Factory(
+        build_runtime_invocation,
+        settings=settings,
+        event_sink=event_sink,
+        hook_registry=hook_registry,
+    )
+    checkpointer: Any = providers.Singleton(
+        select_checkpointer,
+        backend=settings.provided.checkpointer_backend,
+    )
+    store: Any = providers.Singleton(
+        select_store,
+        backend=settings.provided.store_backend,
+    )
diff --git a/coding-deepgent/src/coding_deepgent/containers/sessions.py b/coding-deepgent/src/coding_deepgent/containers/sessions.py
new file mode 100644
index 000000000..a4c95b87d
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/containers/sessions.py
@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from typing import Any
+
+from dependency_injector import containers, providers
+
+
+class SessionsContainer(containers.DeclarativeContainer):
+    session_store: Any = providers.Singleton(dict)
diff --git a/coding-deepgent/src/coding_deepgent/containers/todo.py b/coding-deepgent/src/coding_deepgent/containers/todo.py
new file mode 100644
index 000000000..e12557d0c
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/containers/todo.py
@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from dependency_injector import containers, providers
+
+from coding_deepgent.middleware import PlanContextMiddleware
+from coding_deepgent.todo.tools import todo_write
+
+
+def _singleton_list(item: object) -> list[object]:
+    return [item]
+
+
+class TodoContainer(containers.DeclarativeContainer):
+    tool = providers.Object(todo_write)
+    tools = providers.Callable(_singleton_list, tool)
+    middleware = providers.Factory(PlanContextMiddleware)
+    middleware_list = providers.Callable(_singleton_list, middleware)
diff --git a/coding-deepgent/src/coding_deepgent/containers/tool_system.py b/coding-deepgent/src/coding_deepgent/containers/tool_system.py
new file mode 100644
index 000000000..e7a4a745b
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/containers/tool_system.py
@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from dependency_injector import containers, providers
+
+from coding_deepgent.filesystem import glob_search, grep_search
+from coding_deepgent.memory import save_memory
+from coding_deepgent.permissions import PermissionManager
+from coding_deepgent.permissions.rules import PermissionRuleSpec, expand_rule_specs
+from coding_deepgent.skills import load_skill
+from coding_deepgent.subagents import run_subagent
+from coding_deepgent.tasks import (
+    plan_get,
+    plan_save,
+    task_create,
+    task_get,
+    task_list,
+    task_update,
+)
+from coding_deepgent.tool_system import (
+    ToolCapability,
+    ToolGuardMiddleware,
+    ToolPolicy,
+    build_builtin_capabilities,
+    build_capability_registry,
+)
+
+
+def _combine_tools(*groups: Sequence[object]) -> list[object]:
+    combined: list[object] = []
+    for group in groups:
+        combined.extend(group)
+    return combined
+
+
+def _tools_from_capabilities(capabilities: Sequence[ToolCapability]) -> list[object]:
+    return [capability.tool for capability in capabilities]
+
+
+def _singleton_list(item: object) -> list[object]:
+    return [item]
+
+
+def _permission_rules(
+    allow_rules: Sequence[PermissionRuleSpec],
+    ask_rules: Sequence[PermissionRuleSpec],
+    deny_rules: Sequence[PermissionRuleSpec],
+):
+    return expand_rule_specs(
+        allow_rules=allow_rules,
+        ask_rules=ask_rules,
+        deny_rules=deny_rules,
+    )
+
+
+class ToolSystemContainer(containers.DeclarativeContainer):
+    filesystem_tools: Any = providers.Dependency(default=providers.Object([]))
+    todo_tools: Any = providers.Dependency(default=providers.Object([]))
+    memory_tools: Any = providers.Dependency(default=providers.Object([save_memory]))
+    skill_tools: Any = providers.Dependency(default=providers.Object([load_skill]))
+    task_tools: Any = providers.Dependency(
+        default=providers.Object(
+            [task_create, task_get, task_list, task_update, plan_save, plan_get]
+        )
+    )
+    subagent_tools: Any = providers.Dependency(default=providers.Object([run_subagent]))
+    extension_capabilities: Any = providers.Dependency(default=providers.Object([]))
+    permission_mode: Any = providers.Dependency(default=providers.Object("default"))
+    permission_allow_rules: Any = providers.Dependency(default=providers.Object(()))
+    permission_ask_rules: Any = providers.Dependency(default=providers.Object(()))
+    permission_deny_rules: Any = providers.Dependency(default=providers.Object(()))
+    workdir: Any = providers.Dependency(default=providers.Object(None))
+    trusted_workdirs: Any = providers.Dependency(default=providers.Object(()))
+    event_sink: Any = providers.Dependency(default=providers.Object(None))
+    extension_tools: Any = providers.Callable(
+        _tools_from_capabilities,
+        extension_capabilities,
+    )
+    permission_rules: Any = providers.Callable(
+        _permission_rules,
+        permission_allow_rules,
+        permission_ask_rules,
+        permission_deny_rules,
+    )
+
+    base_tools: Any = providers.Callable(
+        _combine_tools,
+        filesystem_tools,
+        todo_tools,
+        memory_tools,
+        skill_tools,
+        task_tools,
+        subagent_tools,
+    )
+    builtin_capabilities: Any = providers.Callable(
+        build_builtin_capabilities,
+        filesystem_tools=filesystem_tools,
+        discovery_tools=providers.Object((glob_search, grep_search)),
+        todo_tools=todo_tools,
+        memory_tools=memory_tools,
+        skill_tools=skill_tools,
+        task_tools=task_tools,
+        subagent_tools=subagent_tools,
+    )
+    capability_registry: Any = providers.Callable(
+        build_capability_registry,
+        builtin_capabilities=builtin_capabilities,
+        extension_capabilities=extension_capabilities,
+    )
+    tools: Any = providers.Callable(
+        lambda registry: registry.main_tools(),
+        capability_registry,
+    )
+    permission_manager: Any = providers.Factory(
+        PermissionManager,
+        mode=permission_mode,
+        rules=permission_rules,
+        workdir=workdir,
+        trusted_workdirs=trusted_workdirs,
+    )
+    policy: Any = providers.Factory(
+        ToolPolicy,
+        registry=capability_registry,
+        permission_manager=permission_manager,
+    )
+    middleware: Any = providers.Factory(
+        ToolGuardMiddleware,
+        registry=capability_registry,
+        policy=policy,
+        event_sink=event_sink,
+    )
+    middleware_list: Any = providers.Callable(_singleton_list, middleware)
diff --git a/coding-deepgent/src/coding_deepgent/context_payloads.py b/coding-deepgent/src/coding_deepgent/context_payloads.py
new file mode 100644
index 000000000..340d48020
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/context_payloads.py
@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Literal
+
+TRUNCATION_MARKER = "\n...[context payload truncated by coding-deepgent budget]"
+DEFAULT_MAX_CHARS = 4000
+
+ContextPayloadKind = Literal["memory", "todo", "todo_reminder"]
+RenderableContextBlock = str | dict[str, object]
+
+
+@dataclass(frozen=True, slots=True)
+class ContextPayload:
+    kind: ContextPayloadKind
+    text: str
+    source: str
+    priority: int = 100
+
+    def normalized(self) -> "ContextPayload":
+        return ContextPayload(
+            kind=self.kind,
+            text=self.text.strip(),
+            source=self.source.strip(),
+            priority=self.priority,
+        )
+
+
+def _truncate_text(text: str, *, max_chars: int) -> str:
+    if max_chars < len(TRUNCATION_MARKER) + 1:
+        raise ValueError("max_chars must leave room for the truncation marker")
+    if len(text) <= max_chars:
+        return text
+    keep = max_chars - len(TRUNCATION_MARKER)
+    return text[:keep] + TRUNCATION_MARKER
+
+
+def render_context_payloads(
+    payloads: list[ContextPayload],
+    *,
+    max_chars: int = DEFAULT_MAX_CHARS,
+) -> list[dict[str, object]]:
+    if not payloads:
+        return []
+
+    deduped: dict[tuple[str, str, str], ContextPayload] = {}
+    for payload in payloads:
+        normalized = payload.normalized()
+        if not normalized.text or not normalized.source:
+            continue
+        key = (normalized.kind, normalized.source, normalized.text)
+        previous = deduped.get(key)
+        if previous is None or normalized.priority < previous.priority:
+            deduped[key] = normalized
+
+    ordered = sorted(
+        deduped.values(),
+        key=lambda item: (item.priority, item.kind, item.source, item.text),
+    )
+
+    rendered: list[dict[str, object]] = []
+    remaining = max_chars
+    for payload in ordered:
+        if remaining <= 0:
+            break
+        text = _truncate_text(payload.text, max_chars=remaining)
+        rendered.append({"type": "text", "text": text})
+        remaining -= len(text)
+
+    return rendered
+
+
+def merge_system_message_content(
+    current_blocks: Sequence[object],
+    payloads: list[ContextPayload],
+    *,
+    max_chars: int = DEFAULT_MAX_CHARS,
+) -> list[RenderableContextBlock]:
+    rendered_payloads = render_context_payloads(payloads, max_chars=max_chars)
+    if not rendered_payloads:
+        return _normalize_existing_blocks(current_blocks)
+    return [*_normalize_existing_blocks(current_blocks), *rendered_payloads]
+
+
+def _normalize_existing_blocks(
+    current_blocks: Sequence[object],
+) -> list[RenderableContextBlock]:
+    normalized: list[RenderableContextBlock] = []
+    for block in current_blocks:
+        if isinstance(block, str):
+            normalized.append(block)
+        elif isinstance(block, dict):
+            normalized.append(block)
+    return normalized
diff --git a/coding-deepgent/src/coding_deepgent/extensions_service.py b/coding-deepgent/src/coding_deepgent/extensions_service.py
new file mode 100644
index 000000000..dbae52192
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/extensions_service.py
@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from coding_deepgent.mcp import MCPRuntimeLoadResult, load_mcp_runtime_extensions
+from coding_deepgent.plugins import PluginRegistry, discover_local_plugins
+from coding_deepgent.skills import discover_local_skills
+from coding_deepgent.settings import Settings
+
+
+def plugin_registry(settings: Settings) -> PluginRegistry:
+    return PluginRegistry(
+        discover_local_plugins(
+            workdir=settings.workdir,
+            plugin_dir=settings.plugin_dir,
+        )
+    )
+
+
+def mcp_runtime_load_result(settings: Settings) -> MCPRuntimeLoadResult:
+    return load_mcp_runtime_extensions(workdir=settings.workdir)
+
+
+def mcp_capabilities(result: MCPRuntimeLoadResult) -> list[object]:
+    return list(result.capabilities)
+
+
+def combine_extension_capabilities(
+    manual_extension_capabilities: Sequence[object],
+    mcp_capabilities: Sequence[object],
+) -> list[object]:
+    return [*manual_extension_capabilities, *mcp_capabilities]
+
+
+def validate_plugin_registry(
+    plugin_registry: PluginRegistry,
+    settings: Settings,
+    capability_registry,
+) -> PluginRegistry:
+    declarable_names = getattr(capability_registry, "declarable_names", None)
+    known_tools = (
+        set(declarable_names())
+        if callable(declarable_names)
+        else set(capability_registry.names())
+    )
+    known_skills = {
+        skill.metadata.name
+        for skill in discover_local_skills(
+            workdir=settings.workdir,
+            skill_dir=settings.skill_dir,
+        )
+    }
+    plugin_registry.validate(
+        known_tools=known_tools,
+        known_skills=known_skills,
+    )
+    return plugin_registry
diff --git a/coding-deepgent/src/coding_deepgent/filesystem/__init__.py b/coding-deepgent/src/coding_deepgent/filesystem/__init__.py
new file mode 100644
index 000000000..f0554c203
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/filesystem/__init__.py
@@ -0,0 +1,33 @@
+from .discovery import glob_search, grep_search
+from .policy import DANGEROUS_COMMANDS, OUTPUT_LIMIT, safe_path
+from .service import (
+    FilesystemRuntime,
+    edit_workspace_file,
+    glob_workspace_paths,
+    grep_workspace_files,
+    read_workspace_file,
+    resolve_runtime,
+    run_bash,
+    write_workspace_file,
+)
+from .tools import bash, edit_file, read_file, write_file
+
+__all__ = [
+    "DANGEROUS_COMMANDS",
+    "FilesystemRuntime",
+    "OUTPUT_LIMIT",
+    "bash",
+    "edit_file",
+    "edit_workspace_file",
+    "glob_search",
+    "glob_workspace_paths",
+    "grep_search",
+    "grep_workspace_files",
+    "read_file",
+    "read_workspace_file",
+    "resolve_runtime",
+    "run_bash",
+    "safe_path",
+    "write_file",
+    "write_workspace_file",
+]
diff --git a/coding-deepgent/src/coding_deepgent/filesystem/discovery.py b/coding-deepgent/src/coding_deepgent/filesystem/discovery.py
new file mode 100644
index 000000000..b4f7f2eb8
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/filesystem/discovery.py
@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from langchain.tools import ToolRuntime, tool
+
+from .schemas import GlobInput, GrepInput
+from .service import glob_workspace_paths, grep_workspace_files, runtime_from_context
+
+
+@tool("glob", args_schema=GlobInput)
+def glob_search(pattern: str, runtime: ToolRuntime, limit: int = 200) -> str:
+    """List workspace paths that match a glob pattern."""
+
+    return glob_workspace_paths(runtime_from_context(runtime.context), pattern, limit=limit)
+
+
+@tool("grep", args_schema=GrepInput)
+def grep_search(
+    pattern: str,
+    runtime: ToolRuntime,
+    include: str = "**/*",
+    limit: int = 200,
+) -> str:
+    """Search workspace text files using a regular expression."""
+
+    return grep_workspace_files(
+        runtime_from_context(runtime.context),
+        pattern,
+        include=include,
+        limit=limit,
+    )
diff --git a/coding-deepgent/src/coding_deepgent/filesystem/policy.py b/coding-deepgent/src/coding_deepgent/filesystem/policy.py
new file mode 100644
index 000000000..c0863222c
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/filesystem/policy.py
@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Iterable
+
+OUTPUT_LIMIT = 50_000
+DANGEROUS_COMMANDS = ("rm -rf /", "sudo", "shutdown", "reboot", "> /dev/")
+
+
+@dataclass(frozen=True)
+class CommandPolicyDecision:
+    allowed: bool
+    reason: str
+    message: str
+
+
+@dataclass(frozen=True)
+class PathPolicyDecision:
+    allowed: bool
+    reason: str
+    message: str
+    path: Path | None = None
+
+
+@dataclass(frozen=True)
+class PatternPolicyDecision:
+    allowed: bool
+    reason: str
+    message: str
+
+
+def workspace_root(*, workdir: Path | None = None) -> Path:
+    if workdir is None:
+        raise ValueError("Filesystem policy requires an explicit workdir")
+    return workdir.expanduser().resolve()
+
+
+def trusted_roots(
+    *,
+    workdir: Path,
+    additional_workdirs: Iterable[Path] | None = None,
+) -> tuple[Path, ...]:
+    root = workspace_root(workdir=workdir)
+    extras_source = () if additional_workdirs is None else additional_workdirs
+    extras = tuple(path.expanduser().resolve() for path in extras_source)
+    return (root, *extras)
+
+
+def command_policy(command: str) -> CommandPolicyDecision:
+    if any(item in command for item in DANGEROUS_COMMANDS):
+        return CommandPolicyDecision(
+            allowed=False,
+            reason="dangerous_command",
+            message="Error: Dangerous command blocked",
+        )
+    return CommandPolicyDecision(allowed=True, reason="allowed", message="")
+
+
+def safe_path(
+    path_str: str,
+    *,
+    workdir: Path,
+    additional_workdirs: Iterable[Path] | None = None,
+) -> Path:
+    root = workspace_root(workdir=workdir)
+    raw_path = Path(path_str).expanduser()
+    path = raw_path.resolve() if raw_path.is_absolute() else (root / raw_path).resolve()
+    roots = trusted_roots(workdir=workdir, additional_workdirs=additional_workdirs)
+    if not any(path.is_relative_to(base) for base in roots):
+        raise ValueError(f"Path escapes workspace: {path_str}")
+    return path
+
+
+def path_policy(
+    path_str: str,
+    *,
+    workdir: Path,
+    additional_workdirs: Iterable[Path] | None = None,
+) -> PathPolicyDecision:
+    try:
+        path = safe_path(
+            path_str,
+            workdir=workdir,
+            additional_workdirs=additional_workdirs,
+        )
+    except ValueError as exc:
+        return PathPolicyDecision(
+            allowed=False,
+            reason="workspace_escape",
+            message=f"Error: {exc}",
+        )
+    return PathPolicyDecision(
+        allowed=True,
+        reason="allowed",
+        message="",
+        path=path,
+    )
+
+
+def pattern_policy(pattern: str) -> PatternPolicyDecision:
+    if pattern.startswith("/"):
+        return PatternPolicyDecision(
+            allowed=False,
+            reason="workspace_escape",
+            message="Error: Glob pattern must stay inside the workspace",
+        )
+
+    if ".." in PurePosixPath(pattern).parts:
+        return PatternPolicyDecision(
+            allowed=False,
+            reason="workspace_escape",
+            message="Error: Glob pattern must stay inside the workspace",
+        )
+
+    return PatternPolicyDecision(allowed=True, reason="allowed", message="")
diff --git a/coding-deepgent/src/coding_deepgent/filesystem/schemas.py b/coding-deepgent/src/coding_deepgent/filesystem/schemas.py
new file mode 100644
index 000000000..76e3ce26d
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/filesystem/schemas.py
@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class _StrictSchema(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+        json_schema_extra={"additionalProperties": False},
+    )
+
+
+class BashInput(_StrictSchema):
+    command: str = Field(
+        ..., min_length=1, description="Shell command to run inside the workspace."
+    )
+
+    @field_validator("command")
+    @classmethod
+    def _command_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("command is required")
+        return value
+
+
+class ReadFileInput(_StrictSchema):
+    path: str = Field(..., min_length=1, description="Workspace-relative path to read.")
+    limit: int | None = Field(
+        default=None,
+        ge=1,
+        le=10_000,
+        description="Optional maximum number of lines to return.",
+    )
+
+    @field_validator("path")
+    @classmethod
+    def _path_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("path is required")
+        return value
+
+
+class WriteFileInput(_StrictSchema):
+    path: str = Field(
+        ..., min_length=1, description="Workspace-relative path to write."
+    )
+    content: str = Field(..., description="Exact file content to write.")
+
+    @field_validator("path")
+    @classmethod
+    def _path_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("path is required")
+        return value
+
+
+class EditFileInput(_StrictSchema):
+    path: str = Field(..., min_length=1, description="Workspace-relative path to edit.")
+    old_text: str = Field(..., description="Exact text fragment to replace once.")
+    new_text: str = Field(
+        ..., description="Replacement text for the first matching fragment."
+    )
+
+    @field_validator("path")
+    @classmethod
+    def _path_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("path is required")
+        return value
+
+
+class GlobInput(_StrictSchema):
+    pattern: str = Field(
+        ..., min_length=1, description="Workspace-relative glob pattern to match."
+    )
+    limit: int = Field(
+        default=200, ge=1, le=2_000, description="Maximum number of matches to return."
+    )
+
+    @field_validator("pattern")
+    @classmethod
+    def _pattern_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("pattern is required")
+        return value
+
+
+class GrepInput(_StrictSchema):
+    pattern: str = Field(
+        ..., min_length=1, description="Regular expression to search for."
+    )
+    include: str = Field(
+        default="**/*", min_length=1, description="Glob for files to scan."
+    )
+    limit: int = Field(
+        default=200, ge=1, le=2_000, description="Maximum number of matches to return."
+    )
+
+    @field_validator("pattern", "include")
+    @classmethod
+    def _text_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("value is required")
+        return value
diff --git a/coding-deepgent/src/coding_deepgent/filesystem/service.py b/coding-deepgent/src/coding_deepgent/filesystem/service.py
new file mode 100644
index 000000000..8e471bacc
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/filesystem/service.py
@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+import re
+
+from coding_deepgent.filesystem.policy import (
+    OUTPUT_LIMIT,
+    command_policy,
+    pattern_policy,
+    safe_path,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class FilesystemRuntime:
+    workdir: Path
+    trusted_workdirs: tuple[Path, ...] = ()
+
+
+def resolve_runtime(
+    *,
+    workdir: Path,
+    trusted_workdirs: Iterable[Path] = (),
+) -> FilesystemRuntime:
+    return FilesystemRuntime(
+        workdir=workdir.expanduser().resolve(),
+        trusted_workdirs=tuple(path.expanduser().resolve() for path in trusted_workdirs),
+    )
+
+
+def runtime_from_context(context: object) -> FilesystemRuntime:
+    workdir = getattr(context, "workdir", None)
+    if workdir is None:
+        raise RuntimeError("Filesystem tools require runtime workdir")
+    trusted_workdirs = tuple(getattr(context, "trusted_workdirs", ()))
+    return resolve_runtime(
+        workdir=workdir,
+        trusted_workdirs=trusted_workdirs,
+    )
+
+
+def _safe_path(runtime: FilesystemRuntime, path: str) -> Path:
+    return safe_path(
+        path,
+        workdir=runtime.workdir,
+        additional_workdirs=runtime.trusted_workdirs,
+    )
+
+
+def run_bash(runtime: FilesystemRuntime, command: str) -> str:
+    decision = command_policy(command)
+    if not decision.allowed:
+        return decision.message
+
+    try:
+        result = subprocess.run(
+            command,
+            shell=True,
+            cwd=_safe_path(runtime, "."),
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+    except subprocess.TimeoutExpired:
+        return "Error: Timeout (120s)"
+    except (FileNotFoundError, OSError) as exc:
+        return f"Error: {exc}"
+
+    output = (result.stdout + result.stderr).strip()
+    return output[:OUTPUT_LIMIT] if output else "(no output)"
+
+
+def read_workspace_file(runtime: FilesystemRuntime, path: str, limit: int | None = None) -> str:
+    try:
+        lines = _safe_path(runtime, path).read_text(encoding="utf-8").splitlines()
+        if limit is not None and limit < len(lines):
+            remaining = len(lines) - limit
+            lines = lines[:limit] + [f"... ({remaining} more lines)"]
+        return "\n".join(lines)[:OUTPUT_LIMIT]
+    except Exception as exc:  # pragma: no cover
+        return f"Error: {exc}"
+
+
+def write_workspace_file(runtime: FilesystemRuntime, path: str, content: str) -> str:
+    try:
+        file_path = _safe_path(runtime, path)
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_path.write_text(content, encoding="utf-8")
+        return f"Wrote {len(content)} bytes to {path}"
+    except Exception as exc:  # pragma: no cover
+        return f"Error: {exc}"
+
+
+def edit_workspace_file(runtime: FilesystemRuntime, path: str, old_text: str, new_text: str) -> str:
+    try:
+        file_path = _safe_path(runtime, path)
+        content = file_path.read_text(encoding="utf-8")
+        if old_text not in content:
+            return f"Error: Text not found in {path}"
+        file_path.write_text(content.replace(old_text, new_text, 1), encoding="utf-8")
+        return f"Edited {path}"
+    except Exception as exc:  # pragma: no cover
+        return f"Error: {exc}"
+
+
+def glob_workspace_paths(
+    runtime: FilesystemRuntime,
+    pattern: str,
+    *,
+    limit: int = 200,
+) -> str:
+    decision = pattern_policy(pattern)
+    if not decision.allowed:
+        return decision.message
+
+    root = _safe_path(runtime, ".")
+    matches = sorted(
+        path for path in root.glob(pattern) if path.is_file() or path.is_dir()
+    )
+    rendered = [str(path.relative_to(root)) for path in matches[:limit]]
+    if len(matches) > limit:
+        rendered.append(f"... ({len(matches) - limit} more matches)")
+    return "\n".join(rendered)[:OUTPUT_LIMIT] if rendered else "(no matches)"
+
+
+def grep_workspace_files(
+    runtime: FilesystemRuntime,
+    pattern: str,
+    *,
+    include: str = "**/*",
+    limit: int = 200,
+) -> str:
+    include_decision = pattern_policy(include)
+    if not include_decision.allowed:
+        return include_decision.message
+
+    try:
+        regex = re.compile(pattern)
+    except re.error as exc:
+        return f"Error: Invalid regex: {exc}"
+
+    root = _safe_path(runtime, ".")
+    matches: list[str] = []
+    for path in sorted(root.glob(include)):
+        if not path.is_file():
+            continue
+        try:
+            lines = path.read_text(encoding="utf-8").splitlines()
+        except UnicodeDecodeError:
+            continue
+
+        for line_number, line in enumerate(lines, start=1):
+            if regex.search(line):
+                matches.append(f"{path.relative_to(root)}:{line_number}:{line}")
+                if len(matches) >= limit:
+                    return "\n".join(matches)[:OUTPUT_LIMIT]
+    return "\n".join(matches)[:OUTPUT_LIMIT] if matches else "(no matches)"
diff --git a/coding-deepgent/src/coding_deepgent/filesystem/tools.py b/coding-deepgent/src/coding_deepgent/filesystem/tools.py
new file mode 100644
index 000000000..2896b1ec3
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/filesystem/tools.py
@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from langchain.tools import ToolRuntime, tool
+
+from .service import (
+    edit_workspace_file,
+    read_workspace_file,
+    runtime_from_context,
+    run_bash,
+    write_workspace_file,
+)
+from .schemas import BashInput, EditFileInput, ReadFileInput, WriteFileInput
+
+
+@tool("bash", args_schema=BashInput)
+def bash(command: str, runtime: ToolRuntime) -> str:
+    """Run a shell command inside the current workspace."""
+
+    return run_bash(runtime_from_context(runtime.context), command)
+
+
+@tool("read_file", args_schema=ReadFileInput)
+def read_file(path: str, runtime: ToolRuntime, limit: int | None = None) -> str:
+    """Read a workspace file, optionally limiting returned lines."""
+
+    return read_workspace_file(runtime_from_context(runtime.context), path, limit)
+
+
+@tool("write_file", args_schema=WriteFileInput)
+def write_file(path: str, content: str, runtime: ToolRuntime) -> str:
+    """Write content to a workspace file."""
+
+    return write_workspace_file(runtime_from_context(runtime.context), path, content)
+
+
+@tool("edit_file", args_schema=EditFileInput)
+def edit_file(path: str, old_text: str, new_text: str, runtime: ToolRuntime) -> str:
+    """Replace one exact text fragment in a workspace file."""
+
+    return edit_workspace_file(
+        runtime_from_context(runtime.context),
+        path,
+        old_text,
+        new_text,
+    )
diff --git a/coding-deepgent/src/coding_deepgent/hooks/__init__.py b/coding-deepgent/src/coding_deepgent/hooks/__init__.py
new file mode 100644
index 000000000..b4e849039
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/hooks/__init__.py
@@ -0,0 +1,12 @@
+from .events import HookDecision, HookEventName, HookPayload, HookResult
+from .registry import HookCallback, HookDispatchOutcome, LocalHookRegistry
+
+__all__ = [
+    "HookCallback",
+    "HookDecision",
+    "HookDispatchOutcome",
+    "HookEventName",
+    "HookPayload",
+    "HookResult",
+    "LocalHookRegistry",
+]
diff --git a/coding-deepgent/src/coding_deepgent/hooks/dispatcher.py b/coding-deepgent/src/coding_deepgent/hooks/dispatcher.py
new file mode 100644
index 000000000..8d5642c28
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/hooks/dispatcher.py
@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from typing import Any
+
+from coding_deepgent.hooks.events import HookEventName, HookPayload
+from coding_deepgent.hooks.registry import HookDispatchOutcome, LocalHookRegistry
+from coding_deepgent.runtime.events import RuntimeEvent
+from coding_deepgent.runtime.invocation import RuntimeInvocation
+from coding_deepgent.sessions.evidence_events import append_runtime_event_evidence
+
+
+def emit_hook_runtime_event(
+    invocation: RuntimeInvocation,
+    *,
+    phase: str,
+    event: HookEventName,
+    blocked: bool = False,
+    reason: str | None = None,
+) -> None:
+    runtime_event = RuntimeEvent(
+        kind=phase,
+        message=f"Hook {phase} for {event}",
+        session_id=invocation.context.session_id,
+        metadata={
+            "source": "hooks",
+            "hook_event": event,
+            "blocked": blocked,
+            "reason": reason,
+        },
+    )
+    invocation.context.event_sink.emit(runtime_event)
+    append_runtime_event_evidence(context=invocation.context, event=runtime_event)
+
+
+def dispatch_runtime_hook(
+    invocation: RuntimeInvocation,
+    *,
+    event: HookEventName,
+    data: dict[str, object],
+) -> HookDispatchOutcome:
+    registry: LocalHookRegistry = invocation.context.hook_registry
+    if not registry.has_hooks(event):
+        return HookDispatchOutcome(results=(), blocked=False)
+    payload = HookPayload(event=event, data=data)
+    emit_hook_runtime_event(invocation, phase="hook_start", event=event)
+    outcome = registry.dispatch(payload)
+    emit_hook_runtime_event(
+        invocation,
+        phase="hook_blocked" if outcome.blocked else "hook_complete",
+        event=event,
+        blocked=outcome.blocked,
+        reason=outcome.reason,
+    )
+    return outcome
+
+
+def dispatch_context_hook(
+    *,
+    context: Any,
+    session_id: str,
+    event: HookEventName,
+    data: dict[str, object],
+) -> HookDispatchOutcome | None:
+    registry = getattr(context, "hook_registry", None)
+    sink = getattr(context, "event_sink", None)
+    if registry is None or sink is None or not registry.has_hooks(event):
+        return None
+    payload = HookPayload(event=event, data=data)
+    start_event = RuntimeEvent(
+        kind="hook_start",
+        message=f"Hook hook_start for {event}",
+        session_id=session_id,
+        metadata={"source": "hooks", "hook_event": event, "blocked": False},
+    )
+    sink.emit(start_event)
+    append_runtime_event_evidence(context=context, event=start_event)
+    outcome = registry.dispatch(payload)
+    terminal_event = RuntimeEvent(
+        kind="hook_blocked" if outcome.blocked else "hook_complete",
+        message=f"Hook {'hook_blocked' if outcome.blocked else 'hook_complete'} for {event}",
+        session_id=session_id,
+        metadata={
+            "source": "hooks",
+            "hook_event": event,
+            "blocked": outcome.blocked,
+            "reason": outcome.reason,
+        },
+    )
+    sink.emit(terminal_event)
+    append_runtime_event_evidence(context=context, event=terminal_event)
+    return outcome
diff --git a/coding-deepgent/src/coding_deepgent/hooks/events.py b/coding-deepgent/src/coding_deepgent/hooks/events.py
new file mode 100644
index 000000000..7ab4978b3
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/hooks/events.py
@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+HookEventName = Literal[
+    "SessionStart",
+    "UserPromptSubmit",
+    "PreToolUse",
+    "PostToolUse",
+    "PermissionDenied",
+]
+HookDecision = Literal["approve", "block"]
+
+
+class HookPayload(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    event: HookEventName
+    data: dict[str, object] = Field(default_factory=dict)
+
+
+class HookResult(BaseModel):
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    continue_: bool = Field(default=True, alias="continue")
+    decision: HookDecision | None = None
+    reason: str | None = None
+    additional_context: str | None = None
diff --git a/coding-deepgent/src/coding_deepgent/hooks/registry.py b/coding-deepgent/src/coding_deepgent/hooks/registry.py
new file mode 100644
index 000000000..4699a9106
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/hooks/registry.py
@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+from coding_deepgent.hooks.events import HookEventName, HookPayload, HookResult
+
+HookCallback = Callable[[HookPayload], HookResult]
+
+
+@dataclass(frozen=True, slots=True)
+class HookDispatchOutcome:
+    results: tuple[HookResult, ...]
+    blocked: bool
+    reason: str | None = None
+    additional_context: tuple[str, ...] = ()
+
+
+@dataclass(slots=True)
+class LocalHookRegistry:
+    """Small sync hook registry for deterministic local lifecycle hooks."""
+
+    _hooks: dict[HookEventName, list[HookCallback]] = field(default_factory=dict)
+
+    def register(self, event: HookEventName, callback: HookCallback) -> None:
+        self._hooks.setdefault(event, []).append(callback)
+
+    def run(self, payload: HookPayload) -> list[HookResult]:
+        return [callback(payload) for callback in self._hooks.get(payload.event, [])]
+
+    def dispatch(self, payload: HookPayload) -> HookDispatchOutcome:
+        results = tuple(self.run(payload))
+        blocked_result = next(
+            (
+                result
+                for result in results
+                if result.continue_ is False or result.decision == "block"
+            ),
+            None,
+        )
+        additional_context = tuple(
+            result.additional_context
+            for result in results
+            if result.additional_context is not None
+        )
+        return HookDispatchOutcome(
+            results=results,
+            blocked=blocked_result is not None,
+            reason=blocked_result.reason if blocked_result is not None else None,
+            additional_context=additional_context,
+        )
+
+    def has_hooks(self, event: HookEventName) -> bool:
+        return bool(self._hooks.get(event))
diff --git a/coding-deepgent/src/coding_deepgent/logging_config.py b/coding-deepgent/src/coding_deepgent/logging_config.py
new file mode 100644
index 000000000..4a0533f3d
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/logging_config.py
@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import logging as stdlib_logging
+from collections.abc import Mapping
+from typing import Any
+
+import structlog
+
+_REDACTED = "<redacted>"
+_SET = "<set>"
+_MISSING = "<missing>"
+
+_SECRET_FIELD_NAMES = {
+    "OPENAI_API_KEY",
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN",
+    "TOKEN",
+    "SECRET",
+    "PASSWORD",
+}
+
+
+def redact_value(name: str, value: str | None) -> str:
+    if not value:
+        return _MISSING
+    if any(secret_name in name.upper() for secret_name in _SECRET_FIELD_NAMES):
+        return _REDACTED
+    return value
+
+
+def presence_label(value: str | None) -> str:
+    return _SET if value else _MISSING
+
+
+def safe_environment_snapshot(env: Mapping[str, str | None]) -> dict[str, str]:
+    return {
+        "OPENAI_API_KEY": presence_label(env.get("OPENAI_API_KEY")),
+        "OPENAI_BASE_URL": env.get("OPENAI_BASE_URL") or "<default>",
+        "OPENAI_MODEL": env.get("OPENAI_MODEL") or env.get("MODEL_ID") or "<default>",
+    }
+
+
+def configure_logging(level: str = "INFO") -> Any:
+    resolved_level = getattr(stdlib_logging, level.upper(), stdlib_logging.INFO)
+    stdlib_logging.basicConfig(level=resolved_level, format="%(message)s", force=True)
+    structlog.reset_defaults()
+    structlog.configure(
+        processors=[
+            structlog.contextvars.merge_contextvars,
+            structlog.processors.add_log_level,
+            structlog.processors.TimeStamper(fmt="iso", utc=True),
+            structlog.processors.JSONRenderer(sort_keys=True),
+        ],
+        logger_factory=structlog.PrintLoggerFactory(),
+        wrapper_class=structlog.make_filtering_bound_logger(resolved_level),
+        cache_logger_on_first_use=True,
+    )
+    return structlog.get_logger("coding_deepgent")
diff --git a/coding-deepgent/src/coding_deepgent/mcp/__init__.py b/coding-deepgent/src/coding_deepgent/mcp/__init__.py
new file mode 100644
index 000000000..0a5f5adf9
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/mcp/__init__.py
@@ -0,0 +1,41 @@
+from .adapters import (
+    MCPResourceRegistry,
+    adapt_mcp_tool_descriptor,
+    adapt_mcp_tool_descriptors,
+    langchain_mcp_adapters_available,
+)
+from .loader import (
+    MCP_CONFIG_FILE_NAME,
+    MCPConfig,
+    MCPRuntimeLoadResult,
+    MCPServerConfig,
+    LoadedMCPConfig,
+    load_local_mcp_config,
+    load_mcp_runtime_extensions,
+    mcp_config_path,
+)
+from .schemas import (
+    MCPResourceDescriptor,
+    MCPSourceMetadata,
+    MCPToolDescriptor,
+    MCPToolHint,
+)
+
+__all__ = [
+    "MCP_CONFIG_FILE_NAME",
+    "MCPConfig",
+    "MCPRuntimeLoadResult",
+    "MCPResourceDescriptor",
+    "MCPResourceRegistry",
+    "MCPServerConfig",
+    "MCPSourceMetadata",
+    "MCPToolDescriptor",
+    "MCPToolHint",
+    "LoadedMCPConfig",
+    "adapt_mcp_tool_descriptor",
+    "adapt_mcp_tool_descriptors",
+    "langchain_mcp_adapters_available",
+    "load_local_mcp_config",
+    "load_mcp_runtime_extensions",
+    "mcp_config_path",
+]
diff --git a/coding-deepgent/src/coding_deepgent/mcp/adapters.py b/coding-deepgent/src/coding_deepgent/mcp/adapters.py
new file mode 100644
index 000000000..108061ffc
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/mcp/adapters.py
@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from importlib.util import find_spec
+from typing import Iterable
+
+from coding_deepgent.mcp.schemas import MCPResourceDescriptor, MCPToolDescriptor
+from coding_deepgent.tool_system import ToolCapability
+
+
+def langchain_mcp_adapters_available() -> bool:
+    """Return whether the official LangChain MCP adapter package is installed."""
+
+    return find_spec("langchain_mcp_adapters") is not None
+
+
+def adapt_mcp_tool_descriptor(descriptor: MCPToolDescriptor) -> ToolCapability:
+    """Convert one already-discovered MCP tool into a local capability entry."""
+
+    return ToolCapability(
+        name=descriptor.name,
+        tool=descriptor.tool,
+        domain="mcp",
+        read_only=descriptor.hints.read_only,
+        destructive=descriptor.hints.destructive,
+        concurrency_safe=descriptor.hints.read_only
+        and not descriptor.hints.destructive,
+        source=f"mcp:{descriptor.source.server_name}",
+        trusted=False,
+        family="mcp",
+        mutation=(
+            "read"
+            if descriptor.hints.read_only and not descriptor.hints.destructive
+            else "workspace_write"
+            if descriptor.hints.destructive
+            else "unknown"
+        ),
+        execution="plain_tool",
+        exposure="extension",
+        tags=(
+            "mcp",
+            f"server:{descriptor.source.server_name}",
+            f"transport:{descriptor.source.transport}",
+            *descriptor.tags,
+        ),
+    )
+
+
+def adapt_mcp_tool_descriptors(
+    descriptors: Iterable[MCPToolDescriptor],
+) -> tuple[ToolCapability, ...]:
+    """Convert descriptors in input order; duplicate names fail in the registry."""
+
+    return tuple(adapt_mcp_tool_descriptor(descriptor) for descriptor in descriptors)
+
+
+class MCPResourceRegistry:
+    """Separate read-surface registry for MCP resources.
+
+    Stage 7 keeps resources out of executable capability binding.
+    """
+
+    def __init__(self, resources: Iterable[MCPResourceDescriptor] = ()) -> None:
+        ordered = tuple(resources)
+        self._resources = ordered
+        self._by_uri = {resource.uri: resource for resource in ordered}
+        if len(self._by_uri) != len(ordered):
+            raise ValueError("MCP resource URIs must be unique")
+
+    def uris(self) -> list[str]:
+        return list(self._by_uri)
+
+    def get(self, uri: str) -> MCPResourceDescriptor | None:
+        return self._by_uri.get(uri)
+
+    def by_server(self, server_name: str) -> list[MCPResourceDescriptor]:
+        return [
+            resource
+            for resource in self._resources
+            if resource.source.server_name == server_name
+        ]
+
+    def all(self) -> tuple[MCPResourceDescriptor, ...]:
+        return self._resources
diff --git a/coding-deepgent/src/coding_deepgent/mcp/loader.py b/coding-deepgent/src/coding_deepgent/mcp/loader.py
new file mode 100644
index 000000000..ba3a63d1e
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/mcp/loader.py
@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import asyncio
+import importlib
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from coding_deepgent.mcp.adapters import (
+    MCPResourceRegistry,
+    adapt_mcp_tool_descriptors,
+    langchain_mcp_adapters_available,
+)
+from coding_deepgent.mcp.schemas import MCPSourceMetadata, MCPToolDescriptor
+from coding_deepgent.tool_system import ToolCapability
+
+MCP_CONFIG_FILE_NAME = ".mcp.json"
+
+
+class MCPServerConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    transport: str = Field(default="stdio", min_length=1)
+    command: str | None = None
+    args: tuple[str, ...] = ()
+    env: dict[str, str] = Field(default_factory=dict)
+    url: str | None = None
+    headers: dict[str, str] = Field(default_factory=dict)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_transport(cls, value: object) -> object:
+        if not isinstance(value, dict):
+            return value
+        data = dict(value)
+        if "transport" in data and "type" in data and data["transport"] != data["type"]:
+            raise ValueError("transport and type must match when both are provided")
+        if "transport" not in data and "type" in data:
+            data["transport"] = data.pop("type")
+        data.setdefault("transport", "stdio")
+        return data
+
+    @model_validator(mode="after")
+    def _validate_shape(self) -> "MCPServerConfig":
+        if self.transport == "stdio":
+            if self.command is None or not self.command.strip():
+                raise ValueError("stdio MCP server requires command")
+            if self.url is not None:
+                raise ValueError("stdio MCP server must not define url")
+            return self
+        if self.transport in {"http", "sse"}:
+            if self.url is None or not self.url.strip():
+                raise ValueError(f"{self.transport} MCP server requires url")
+            if self.command is not None:
+                raise ValueError(f"{self.transport} MCP server must not define command")
+            return self
+        raise ValueError(f"Unsupported MCP transport: {self.transport}")
+
+
+class MCPConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    mcpServers: dict[str, MCPServerConfig] = Field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class LoadedMCPConfig:
+    path: Path
+    config: MCPConfig
+
+
+@dataclass(frozen=True, slots=True)
+class MCPRuntimeLoadResult:
+    loaded_config: LoadedMCPConfig | None
+    capabilities: tuple[ToolCapability, ...]
+    resources: MCPResourceRegistry
+    adapter_available: bool
+    reason: str | None = None
+
+
+def mcp_config_path(workdir: Path) -> Path:
+    return workdir.resolve() / MCP_CONFIG_FILE_NAME
+
+
+def load_local_mcp_config(*, workdir: Path) -> LoadedMCPConfig | None:
+    path = mcp_config_path(workdir)
+    if not path.is_file():
+        return None
+    data = json.loads(path.read_text(encoding="utf-8"))
+    return LoadedMCPConfig(path=path, config=MCPConfig.model_validate(data))
+
+
+def _server_client_config(server: MCPServerConfig) -> dict[str, object]:
+    payload: dict[str, object] = {"transport": server.transport}
+    if server.command is not None:
+        payload["command"] = server.command
+    if server.args:
+        payload["args"] = list(server.args)
+    if server.env:
+        payload["env"] = dict(server.env)
+    if server.url is not None:
+        payload["url"] = server.url
+    if server.headers:
+        payload["headers"] = dict(server.headers)
+    return payload
+
+
+def _default_client_factory() -> Callable[[dict[str, Any]], Any] | None:
+    if not langchain_mcp_adapters_available():
+        return None
+    client_module = importlib.import_module("langchain_mcp_adapters.client")
+    client_cls = getattr(client_module, "MultiServerMCPClient")
+    return lambda config: client_cls(config)
+
+
+async def _load_server_tools(
+    server_name: str,
+    server: MCPServerConfig,
+    *,
+    client_factory: Callable[[dict[str, Any]], Any],
+) -> tuple[MCPToolDescriptor, ...]:
+    client = client_factory({server_name: _server_client_config(server)})
+    tools = await client.get_tools()
+    return tuple(
+        MCPToolDescriptor(
+            name=str(getattr(tool, "name", type(tool).__name__)),
+            tool=tool,
+            source=MCPSourceMetadata(
+                server_name=server_name, transport=server.transport
+            ),
+            description=str(getattr(tool, "description", "") or ""),
+        )
+        for tool in tools
+    )
+
+
+def load_mcp_runtime_extensions(
+    *,
+    workdir: Path,
+    client_factory: Callable[[dict[str, Any]], Any] | None = None,
+) -> MCPRuntimeLoadResult:
+    loaded_config = load_local_mcp_config(workdir=workdir)
+    if loaded_config is None:
+        return MCPRuntimeLoadResult(
+            loaded_config=None,
+            capabilities=(),
+            resources=MCPResourceRegistry(),
+            adapter_available=langchain_mcp_adapters_available(),
+            reason="no_mcp_config",
+        )
+
+    factory = client_factory or _default_client_factory()
+    if factory is None:
+        return MCPRuntimeLoadResult(
+            loaded_config=loaded_config,
+            capabilities=(),
+            resources=MCPResourceRegistry(),
+            adapter_available=False,
+            reason="langchain_mcp_adapters_unavailable",
+        )
+
+    descriptors: list[MCPToolDescriptor] = []
+    for server_name, server in loaded_config.config.mcpServers.items():
+        descriptors.extend(
+            asyncio.run(_load_server_tools(server_name, server, client_factory=factory))
+        )
+    return MCPRuntimeLoadResult(
+        loaded_config=loaded_config,
+        capabilities=adapt_mcp_tool_descriptors(descriptors),
+        resources=MCPResourceRegistry(),
+        adapter_available=True,
+    )
diff --git a/coding-deepgent/src/coding_deepgent/mcp/schemas.py b/coding-deepgent/src/coding_deepgent/mcp/schemas.py
new file mode 100644
index 000000000..a8663a7ce
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/mcp/schemas.py
@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class MCPSourceMetadata(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    server_name: str = Field(..., min_length=1)
+    transport: str = Field(default="local", min_length=1)
+
+    @field_validator("server_name", "transport")
+    @classmethod
+    def _text_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("value required")
+        return value
+
+
+class MCPToolHint(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    read_only: bool = False
+    destructive: bool = False
+
+
+class MCPResourceDescriptor(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    uri: str = Field(..., min_length=1)
+    name: str | None = Field(default=None, min_length=1)
+    description: str | None = Field(default=None, min_length=1)
+    mime_type: str | None = Field(default=None, min_length=1)
+    source: MCPSourceMetadata
+
+    @field_validator("uri")
+    @classmethod
+    def _uri_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("uri required")
+        return value
+
+
+@dataclass(frozen=True, slots=True)
+class MCPToolDescriptor:
+    name: str
+    tool: BaseTool
+    source: MCPSourceMetadata
+    description: str | None = None
+    hints: MCPToolHint = field(default_factory=MCPToolHint)
+    tags: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        name = self.name.strip()
+        if not name:
+            raise ValueError("tool name required")
+        object.__setattr__(self, "name", name)
+        if not self.description:
+            object.__setattr__(
+                self,
+                "description",
+                str(getattr(self.tool, "description", "") or ""),
+            )
diff --git a/coding-deepgent/src/coding_deepgent/memory/__init__.py b/coding-deepgent/src/coding_deepgent/memory/__init__.py
new file mode 100644
index 000000000..82cb0af36
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/memory/__init__.py
@@ -0,0 +1,27 @@
+from .middleware import MemoryContextMiddleware
+from .policy import MemoryQualityDecision, evaluate_memory_quality
+from .recall import recall_memories, render_memories
+from .schemas import MemoryNamespace, MemoryRecord, SaveMemoryInput
+from .store import (
+    MEMORY_ROOT_NAMESPACE,
+    list_memory_records,
+    memory_namespace,
+    save_memory_record,
+)
+from .tools import save_memory
+
+__all__ = [
+    "MEMORY_ROOT_NAMESPACE",
+    "MemoryContextMiddleware",
+    "MemoryQualityDecision",
+    "MemoryNamespace",
+    "MemoryRecord",
+    "SaveMemoryInput",
+    "evaluate_memory_quality",
+    "list_memory_records",
+    "memory_namespace",
+    "recall_memories",
+    "render_memories",
+    "save_memory",
+    "save_memory_record",
+]
diff --git a/coding-deepgent/src/coding_deepgent/memory/middleware.py b/coding-deepgent/src/coding_deepgent/memory/middleware.py
new file mode 100644
index 000000000..d466e8b94
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/memory/middleware.py
@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from langchain.agents.middleware import AgentMiddleware, ModelRequest, ModelResponse
+from langchain.messages import SystemMessage
+
+from coding_deepgent.context_payloads import (
+    ContextPayload,
+    merge_system_message_content,
+)
+from coding_deepgent.memory.recall import recall_memories, render_memories
+from coding_deepgent.memory.schemas import MemoryNamespace
+
+
+@dataclass(frozen=True, slots=True)
+class MemoryContextMiddleware(AgentMiddleware):
+    namespace: MemoryNamespace = "project"
+    limit: int = 5
+
+    def wrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], ModelResponse],
+    ) -> ModelResponse:
+        store = getattr(request.runtime, "store", None)
+        query = " ".join(
+            str(message.content)
+            for message in request.messages[-3:]
+            if hasattr(message, "content")
+        )
+        memories = recall_memories(
+            store, namespace=self.namespace, query=query, limit=self.limit
+        )
+        rendered = render_memories(memories)
+        if not rendered:
+            return handler(request)
+
+        current_blocks = (
+            request.system_message.content_blocks if request.system_message else []
+        )
+        payloads = [
+            ContextPayload(
+                kind="memory",
+                source=f"memory.{self.namespace}",
+                priority=200,
+                text=rendered,
+            )
+        ]
+        return handler(
+            request.override(
+                system_message=SystemMessage(
+                    content=merge_system_message_content(
+                        current_blocks, payloads
+                    )  # type: ignore[list-item]
+                )
+            )
+        )
diff --git a/coding-deepgent/src/coding_deepgent/memory/policy.py b/coding-deepgent/src/coding_deepgent/memory/policy.py
new file mode 100644
index 000000000..c52efff25
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/memory/policy.py
@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Literal
+
+from coding_deepgent.memory.schemas import MemoryRecord
+
+MemoryQualityCategory = Literal[
+    "accepted",
+    "duplicate",
+    "too_short",
+    "transient_state",
+]
+
+TRANSIENT_MEMORY_PHRASES = (
+    "active todo",
+    "completed task",
+    "current plan",
+    "current task",
+    "currently ",
+    "in progress",
+    "next step",
+    "next steps",
+    "pending task",
+    "right now",
+    "this session",
+    "todo:",
+    "todos:",
+    "working on",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class MemoryQualityDecision:
+    allowed: bool
+    category: MemoryQualityCategory
+    reason: str
+
+
+def normalize_memory_content(content: str) -> str:
+    return " ".join(content.casefold().split())
+
+
+def evaluate_memory_quality(
+    record: MemoryRecord,
+    *,
+    existing_records: Sequence[MemoryRecord] = (),
+) -> MemoryQualityDecision:
+    normalized = normalize_memory_content(record.content)
+    if len(normalized.split()) <= 1:
+        return MemoryQualityDecision(
+            allowed=False,
+            category="too_short",
+            reason="memory is too short to be reusable long-term knowledge",
+        )
+
+    if any(phrase in normalized for phrase in TRANSIENT_MEMORY_PHRASES):
+        return MemoryQualityDecision(
+            allowed=False,
+            category="transient_state",
+            reason="memory looks like transient task/session state",
+        )
+
+    for existing in existing_records:
+        if normalize_memory_content(existing.content) == normalized:
+            return MemoryQualityDecision(
+                allowed=False,
+                category="duplicate",
+                reason=f"duplicate memory already exists in {record.namespace}",
+            )
+
+    return MemoryQualityDecision(
+        allowed=True,
+        category="accepted",
+        reason="memory is durable reusable knowledge",
+    )
diff --git a/coding-deepgent/src/coding_deepgent/memory/recall.py b/coding-deepgent/src/coding_deepgent/memory/recall.py
new file mode 100644
index 000000000..4ebfe3c78
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/memory/recall.py
@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from coding_deepgent.memory.schemas import MemoryNamespace, MemoryRecord
+from coding_deepgent.memory.store import MemoryStore, list_memory_records
+
+
+def recall_memories(
+    store: MemoryStore | None,
+    *,
+    namespace: MemoryNamespace = "project",
+    query: str = "",
+    limit: int = 5,
+) -> list[MemoryRecord]:
+    if store is None:
+        return []
+
+    records = list_memory_records(store, namespace)
+    query_terms = {term.casefold() for term in query.split()}
+    if query_terms:
+        records = [
+            record
+            for record in records
+            if query_terms & set(record.content.casefold().split())
+        ]
+    return records[:limit]
+
+
+def render_memories(records: Sequence[MemoryRecord]) -> str | None:
+    if not records:
+        return None
+    lines = ["Relevant long-term memory:"]
+    lines.extend(f"- [{record.namespace}] {record.content}" for record in records)
+    return "\n".join(lines)
diff --git a/coding-deepgent/src/coding_deepgent/memory/schemas.py b/coding-deepgent/src/coding_deepgent/memory/schemas.py
new file mode 100644
index 000000000..b74167bea
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/memory/schemas.py
@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from langchain.tools import ToolRuntime
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+MemoryNamespace = Literal["project", "user", "local"]
+
+
+class MemoryRecord(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    content: str = Field(..., min_length=1, description="Reusable memory content.")
+    namespace: MemoryNamespace = Field(
+        default="project", description="Long-term memory namespace."
+    )
+    source: str = Field(default="agent", description="Source that saved this memory.")
+
+    @field_validator("content", "source")
+    @classmethod
+    def _text_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("value required")
+        return value
+
+
+class SaveMemoryInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    content: str = Field(
+        ...,
+        min_length=1,
+        description="Durable reusable knowledge or preference to store as long-term memory. Do not store current todos, transient plans, task status, recovery notes, or facts that are already present in the current conversation.",
+    )
+    namespace: MemoryNamespace = Field(
+        default="project",
+        description="Memory namespace. Use project for repository facts, user for durable user preferences, and local for machine-local notes.",
+    )
+    source: str = Field(
+        default="agent", description="Source label for this memory entry."
+    )
+    runtime: ToolRuntime
+
+    @field_validator("content", "source")
+    @classmethod
+    def _text_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("value required")
+        return value
diff --git a/coding-deepgent/src/coding_deepgent/memory/store.py b/coding-deepgent/src/coding_deepgent/memory/store.py
new file mode 100644
index 000000000..e7bef853f
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/memory/store.py
@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from hashlib import sha256
+from typing import Iterable, Protocol
+
+from coding_deepgent.memory.schemas import MemoryNamespace, MemoryRecord
+
+MEMORY_ROOT_NAMESPACE = "coding_deepgent_memory"
+
+
+class MemoryStore(Protocol):
+    def put(
+        self, namespace: tuple[str, ...], key: str, value: dict[str, object]
+    ) -> None: ...
+    def search(self, namespace: tuple[str, ...]) -> Iterable[object]: ...
+
+
+def memory_namespace(namespace: MemoryNamespace) -> tuple[str, ...]:
+    return (MEMORY_ROOT_NAMESPACE, namespace)
+
+
+def memory_key(record: MemoryRecord) -> str:
+    digest = sha256(f"{record.namespace}\0{record.content}".encode("utf-8")).hexdigest()
+    return digest[:16]
+
+
+def save_memory_record(store: MemoryStore, record: MemoryRecord) -> str:
+    key = memory_key(record)
+    store.put(memory_namespace(record.namespace), key, record.model_dump())
+    return key
+
+
+def list_memory_records(
+    store: MemoryStore, namespace: MemoryNamespace
+) -> list[MemoryRecord]:
+    records: list[MemoryRecord] = []
+    for item in store.search(memory_namespace(namespace)):
+        value = getattr(item, "value", item)
+        if isinstance(value, dict) and value:
+            records.append(MemoryRecord.model_validate(value))
+    return records
diff --git a/coding-deepgent/src/coding_deepgent/memory/tools.py b/coding-deepgent/src/coding_deepgent/memory/tools.py
new file mode 100644
index 000000000..f220ba69f
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/memory/tools.py
@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import cast
+
+from langchain.tools import ToolRuntime, tool
+
+from coding_deepgent.memory.schemas import (
+    MemoryNamespace,
+    MemoryRecord,
+    SaveMemoryInput,
+)
+from coding_deepgent.memory.policy import evaluate_memory_quality
+from coding_deepgent.memory.store import list_memory_records, save_memory_record
+
+
+@tool(
+    "save_memory",
+    args_schema=SaveMemoryInput,
+    description=(
+        "Save durable reusable knowledge or preferences as long-term memory. "
+        "Do not save transient todos, current plans, task status, recovery notes, "
+        "duplicates, or one-off observations."
+    ),
+)
+def save_memory(
+    content: str,
+    runtime: ToolRuntime,
+    namespace: str = "project",
+    source: str = "agent",
+) -> str:
+    """Save reusable long-term memory through the LangGraph store seam."""
+
+    validated = SaveMemoryInput(
+        content=content,
+        namespace=cast(MemoryNamespace, namespace),
+        source=source,
+        runtime=runtime,
+    )
+    store = runtime.store
+    if store is None:
+        return "Memory store is not configured; memory was not saved."
+    record = MemoryRecord(
+        content=validated.content,
+        namespace=validated.namespace,
+        source=validated.source,
+    )
+    quality = evaluate_memory_quality(
+        record,
+        existing_records=list_memory_records(store, validated.namespace),
+    )
+    if not quality.allowed:
+        return f"Memory not saved: {quality.reason}."
+
+    key = save_memory_record(store, record)
+    return f"Saved memory {key} in {validated.namespace}."
diff --git a/coding-deepgent/src/coding_deepgent/middleware/__init__.py b/coding-deepgent/src/coding_deepgent/middleware/__init__.py
new file mode 100644
index 000000000..5cb35e661
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/middleware/__init__.py
@@ -0,0 +1,3 @@
+from .planning import PlanContextMiddleware
+
+__all__ = ["PlanContextMiddleware"]
diff --git a/coding-deepgent/src/coding_deepgent/middleware/planning.py b/coding-deepgent/src/coding_deepgent/middleware/planning.py
new file mode 100644
index 000000000..56b965f63
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/middleware/planning.py
@@ -0,0 +1,3 @@
+from coding_deepgent.todo.middleware import TODO_WRITE_TOOL_NAME, PlanContextMiddleware
+
+__all__ = ["PlanContextMiddleware", "TODO_WRITE_TOOL_NAME"]
diff --git a/coding-deepgent/src/coding_deepgent/permission_specs.py b/coding-deepgent/src/coding_deepgent/permission_specs.py
new file mode 100644
index 000000000..2bf54db3f
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/permission_specs.py
@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class PermissionRuleSpec(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    tool_name: str = Field(..., min_length=1)
+    content: str | None = None
+    domain: str | None = None
+    capability_source: str | None = None
+    trusted: bool | None = None
+    rule_source: str = "settings"
+
+    @field_validator(
+        "tool_name",
+        "content",
+        "domain",
+        "capability_source",
+        "rule_source",
+    )
+    @classmethod
+    def _strip_text(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        stripped = value.strip()
+        if not stripped:
+            raise ValueError("value required")
+        return stripped
diff --git a/coding-deepgent/src/coding_deepgent/permissions/__init__.py b/coding-deepgent/src/coding_deepgent/permissions/__init__.py
new file mode 100644
index 000000000..4430d8fd5
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/permissions/__init__.py
@@ -0,0 +1,25 @@
+from coding_deepgent.permission_specs import PermissionRuleSpec
+
+from .manager import (
+    PermissionCode,
+    PermissionDecision,
+    PermissionManager,
+    ToolPermissionSubject,
+    is_read_only_bash,
+)
+from .modes import EXTERNAL_PERMISSION_MODES, PermissionBehavior, PermissionMode
+from .rules import PermissionRule, expand_rule_specs
+
+__all__ = [
+    "EXTERNAL_PERMISSION_MODES",
+    "PermissionBehavior",
+    "PermissionCode",
+    "PermissionDecision",
+    "PermissionManager",
+    "PermissionMode",
+    "PermissionRule",
+    "PermissionRuleSpec",
+    "ToolPermissionSubject",
+    "expand_rule_specs",
+    "is_read_only_bash",
+]
diff --git a/coding-deepgent/src/coding_deepgent/permissions/manager.py b/coding-deepgent/src/coding_deepgent/permissions/manager.py
new file mode 100644
index 000000000..11da5e47e
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/permissions/manager.py
@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+import shlex
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+from typing import Mapping, Sequence, cast
+
+from coding_deepgent.filesystem.policy import command_policy, path_policy
+from coding_deepgent.permissions.modes import PermissionBehavior, PermissionMode
+from coding_deepgent.permissions.rules import PermissionRule
+
+
+class PermissionCode(StrEnum):
+    ALLOWED = "allowed"
+    UNKNOWN_TOOL = "unknown_tool"
+    TOOL_DISABLED = "tool_disabled"
+    RULE_DENIED = "rule_denied"
+    RULE_ASK = "rule_ask"
+    RULE_ALLOWED = "rule_allowed"
+    PLAN_MODE_DENIED = "plan_mode_denied"
+    PERMISSION_REQUIRED = "permission_required"
+    DANGEROUS_COMMAND = "dangerous_command"
+    WORKSPACE_ESCAPE = "workspace_escape"
+    DONT_ASK_DENIED = "dont_ask_denied"
+
+
+@dataclass(frozen=True, slots=True)
+class PermissionDecision:
+    behavior: PermissionBehavior
+    code: PermissionCode
+    message: str = ""
+    metadata: Mapping[str, object] = field(default_factory=dict)
+
+    @property
+    def allowed(self) -> bool:
+        return self.behavior == "allow"
+
+
+@dataclass(frozen=True, slots=True)
+class ToolPermissionSubject:
+    name: str
+    read_only: bool
+    destructive: bool
+    enabled: bool = True
+    domain: str = "unknown"
+    source: str = "builtin"
+    trusted: bool = True
+
+
+READ_ONLY_BASH_COMMANDS = frozenset(
+    {"ls", "pwd", "cat", "grep", "head", "tail", "find", "rg"}
+)
+
+
+def is_read_only_bash(command: str) -> bool:
+    try:
+        words = shlex.split(command, posix=True)
+    except ValueError:
+        return False
+    if not words:
+        return False
+    if any(token in command for token in ("|", ">", "<", "&&", ";", "$(", "`")):
+        return False
+    return words[0] in READ_ONLY_BASH_COMMANDS
+
+
+class PermissionManager:
+    def __init__(
+        self,
+        *,
+        mode: PermissionMode = "default",
+        rules: Sequence[PermissionRule] = (),
+        workdir: Path | None = None,
+        trusted_workdirs: Sequence[Path] = (),
+    ) -> None:
+        self.mode = mode
+        self.rules = tuple(rules)
+        self.workdir = workdir.expanduser().resolve() if workdir is not None else None
+        self.trusted_workdirs = tuple(
+            path.expanduser().resolve() for path in trusted_workdirs
+        )
+
+    def evaluate(
+        self,
+        *,
+        tool_call: Mapping[str, object],
+        subject: ToolPermissionSubject | None,
+    ) -> PermissionDecision:
+        tool_name = str(tool_call.get("name", ""))
+        if subject is None:
+            return PermissionDecision(
+                behavior="deny",
+                code=PermissionCode.UNKNOWN_TOOL,
+                message=f"Error: Unknown tool `{tool_name}`",
+            )
+        if not subject.enabled:
+            return PermissionDecision(
+                behavior="deny",
+                code=PermissionCode.TOOL_DISABLED,
+                message=f"Error: Tool `{tool_name}` is disabled",
+            )
+
+        raw_args = tool_call.get("args", {})
+        args = raw_args if isinstance(raw_args, Mapping) else {}
+        hard_safety_decision = self._hard_safety_decision(tool_name, args)
+        if hard_safety_decision is not None:
+            return hard_safety_decision
+
+        rule_decision = self._rule_decision(tool_name, args, subject=subject)
+        if rule_decision is not None:
+            return self._apply_dont_ask(rule_decision)
+
+        decision = self._mode_decision(subject, tool_name, args)
+        return self._apply_dont_ask(decision)
+
+    def _hard_safety_decision(
+        self, tool_name: str, args: Mapping[str, object]
+    ) -> PermissionDecision | None:
+        if tool_name == "bash":
+            decision = command_policy(str(args.get("command", "")))
+            if not decision.allowed:
+                return PermissionDecision(
+                    behavior="deny",
+                    code=PermissionCode.DANGEROUS_COMMAND,
+                    message=decision.message,
+                )
+
+        path_arg = args.get("path")
+        if isinstance(path_arg, str):
+            if self.workdir is None:
+                return PermissionDecision(
+                    behavior="deny",
+                    code=PermissionCode.WORKSPACE_ESCAPE,
+                    message="Error: Path permissions require a configured workdir",
+                )
+            path_decision = path_policy(
+                path_arg,
+                workdir=self.workdir,
+                additional_workdirs=self.trusted_workdirs,
+            )
+            if not path_decision.allowed:
+                return PermissionDecision(
+                    behavior="deny",
+                    code=PermissionCode.WORKSPACE_ESCAPE,
+                    message=path_decision.message,
+                )
+        return None
+
+    def _rule_decision(
+        self,
+        tool_name: str,
+        args: Mapping[str, object],
+        *,
+        subject: ToolPermissionSubject,
+    ) -> PermissionDecision | None:
+        for behavior, code in (
+            ("deny", PermissionCode.RULE_DENIED),
+            ("ask", PermissionCode.RULE_ASK),
+            ("allow", PermissionCode.RULE_ALLOWED),
+        ):
+            rule = next(
+                (
+                    candidate
+                    for candidate in self.rules
+                    if candidate.behavior == behavior
+                    and candidate.matches(
+                        tool_name,
+                        args,
+                        domain=subject.domain,
+                        capability_source=subject.source,
+                        trusted=subject.trusted,
+                    )
+                ),
+                None,
+            )
+            if rule is not None:
+                return PermissionDecision(
+                    behavior=cast(PermissionBehavior, behavior),
+                    code=code,
+                    message=f"Permission {behavior} rule matched for `{tool_name}`",
+                    metadata={"rule_source": rule.source, "rule_content": rule.content},
+                )
+        return None
+
+    def _mode_decision(
+        self,
+        subject: ToolPermissionSubject,
+        tool_name: str,
+        args: Mapping[str, object],
+    ) -> PermissionDecision:
+        read_only = subject.read_only or (
+            tool_name == "bash" and is_read_only_bash(str(args.get("command", "")))
+        )
+        if not subject.trusted and subject.destructive and not read_only:
+            return PermissionDecision(
+                "ask",
+                PermissionCode.PERMISSION_REQUIRED,
+                f"Approval required before running untrusted extension `{tool_name}`",
+                metadata={
+                    "tool_name": tool_name,
+                    "tool_source": subject.source,
+                    "trusted": False,
+                },
+            )
+        if self.mode == "bypassPermissions":
+            return PermissionDecision("allow", PermissionCode.ALLOWED)
+
+        if self.mode == "acceptEdits":
+            return PermissionDecision("allow", PermissionCode.ALLOWED)
+        if self.mode == "plan":
+            if read_only or not subject.destructive:
+                return PermissionDecision("allow", PermissionCode.ALLOWED)
+            return PermissionDecision(
+                "deny",
+                PermissionCode.PLAN_MODE_DENIED,
+                f"Error: `{tool_name}` is not allowed in plan mode",
+            )
+
+        if read_only or not subject.destructive:
+            return PermissionDecision("allow", PermissionCode.ALLOWED)
+
+        return PermissionDecision(
+            "ask",
+            PermissionCode.PERMISSION_REQUIRED,
+            f"Approval required before running `{tool_name}`",
+            metadata={"tool_name": tool_name},
+        )
+
+    def _apply_dont_ask(self, decision: PermissionDecision) -> PermissionDecision:
+        if self.mode == "dontAsk" and decision.behavior == "ask":
+            return PermissionDecision(
+                "deny",
+                PermissionCode.DONT_ASK_DENIED,
+                f"Error: `{decision.metadata.get('tool_name', 'tool')}` would require approval, but dontAsk mode denies it"
+                if decision.metadata
+                else "Error: Approval would be required, but dontAsk mode denies it",
+                metadata=decision.metadata,
+            )
+        return decision
diff --git a/coding-deepgent/src/coding_deepgent/permissions/modes.py b/coding-deepgent/src/coding_deepgent/permissions/modes.py
new file mode 100644
index 000000000..93fa9903b
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/permissions/modes.py
@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import Literal
+
+PermissionMode = Literal[
+    "default", "plan", "acceptEdits", "bypassPermissions", "dontAsk"
+]
+PermissionBehavior = Literal["allow", "ask", "deny"]
+
+EXTERNAL_PERMISSION_MODES: tuple[PermissionMode, ...] = (
+    "default",
+    "plan",
+    "acceptEdits",
+    "bypassPermissions",
+    "dontAsk",
+)
diff --git a/coding-deepgent/src/coding_deepgent/permissions/rules.py b/coding-deepgent/src/coding_deepgent/permissions/rules.py
new file mode 100644
index 000000000..d0714b6dc
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/permissions/rules.py
@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Mapping, Sequence, cast
+
+from coding_deepgent.permission_specs import PermissionRuleSpec
+from coding_deepgent.permissions.modes import PermissionBehavior
+
+
+@dataclass(frozen=True, slots=True)
+class PermissionRule:
+    """A small explicit allow/deny/ask rule for local tool permission checks."""
+
+    tool_name: str
+    behavior: PermissionBehavior
+    content: str | None = None
+    match_domain: str | None = None
+    match_capability_source: str | None = None
+    match_trusted: bool | None = None
+    source: str = "local"
+
+    def matches(
+        self,
+        tool_name: str,
+        args: Mapping[str, object],
+        *,
+        domain: str | None = None,
+        capability_source: str | None = None,
+        trusted: bool | None = None,
+    ) -> bool:
+        if self.tool_name != tool_name:
+            return False
+        if self.match_domain is not None and self.match_domain != domain:
+            return False
+        if (
+            self.match_capability_source is not None
+            and self.match_capability_source != capability_source
+        ):
+            return False
+        if self.match_trusted is not None and self.match_trusted != trusted:
+            return False
+        if self.content is None:
+            return True
+        haystack = "\n".join(str(value) for value in args.values())
+        return self.content in haystack
+
+
+def expand_rule_specs(
+    *,
+    allow_rules: Sequence[PermissionRuleSpec] = (),
+    ask_rules: Sequence[PermissionRuleSpec] = (),
+    deny_rules: Sequence[PermissionRuleSpec] = (),
+) -> tuple[PermissionRule, ...]:
+    rules: list[PermissionRule] = []
+    for behavior, specs in (
+        ("allow", allow_rules),
+        ("ask", ask_rules),
+        ("deny", deny_rules),
+    ):
+        rules.extend(
+            PermissionRule(
+                tool_name=spec.tool_name,
+                behavior=cast(PermissionBehavior, behavior),
+                content=spec.content,
+                match_domain=spec.domain,
+                match_capability_source=spec.capability_source,
+                match_trusted=spec.trusted,
+                source=spec.rule_source,
+            )
+            for spec in specs
+        )
+    return tuple(rules)
diff --git a/coding-deepgent/src/coding_deepgent/plugins/__init__.py b/coding-deepgent/src/coding_deepgent/plugins/__init__.py
new file mode 100644
index 000000000..3fed1d45e
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/plugins/__init__.py
@@ -0,0 +1,26 @@
+from .loader import (
+    PLUGIN_FILE_NAME,
+    discover_local_plugins,
+    load_local_plugin,
+    parse_plugin_manifest,
+    plugin_root,
+)
+from .registry import (
+    PluginCapabilityDeclaration,
+    PluginRegistry,
+    ValidatedPluginDeclaration,
+)
+from .schemas import LoadedPluginManifest, PluginManifest
+
+__all__ = [
+    "LoadedPluginManifest",
+    "PLUGIN_FILE_NAME",
+    "PluginCapabilityDeclaration",
+    "PluginManifest",
+    "PluginRegistry",
+    "ValidatedPluginDeclaration",
+    "discover_local_plugins",
+    "load_local_plugin",
+    "parse_plugin_manifest",
+    "plugin_root",
+]
diff --git a/coding-deepgent/src/coding_deepgent/plugins/loader.py b/coding-deepgent/src/coding_deepgent/plugins/loader.py
new file mode 100644
index 000000000..11239c8af
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/plugins/loader.py
@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from coding_deepgent.plugins.schemas import LoadedPluginManifest, PluginManifest
+
+PLUGIN_FILE_NAME = "plugin.json"
+
+
+def plugin_root(workdir: Path, plugin_dir: Path) -> Path:
+    if plugin_dir.is_absolute():
+        return plugin_dir.resolve()
+    return (workdir / plugin_dir).resolve()
+
+
+def parse_plugin_manifest(path: Path) -> LoadedPluginManifest:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    manifest = PluginManifest.model_validate(data)
+    return LoadedPluginManifest(
+        manifest=manifest,
+        root=path.parent.resolve(),
+        path=path.resolve(),
+    )
+
+
+def load_local_plugin(
+    *, workdir: Path, plugin_dir: Path, name: str
+) -> LoadedPluginManifest:
+    root = plugin_root(workdir, plugin_dir)
+    path = root / name / PLUGIN_FILE_NAME
+    if not path.is_file():
+        raise FileNotFoundError(f"Local plugin not found: {name}")
+    loaded = parse_plugin_manifest(path)
+    if loaded.manifest.name != name:
+        raise ValueError(
+            f"Plugin name mismatch: requested {name}, found {loaded.manifest.name}"
+        )
+    return loaded
+
+
+def discover_local_plugins(
+    *, workdir: Path, plugin_dir: Path
+) -> tuple[LoadedPluginManifest, ...]:
+    root = plugin_root(workdir, plugin_dir)
+    if not root.exists():
+        return ()
+    if not root.is_dir():
+        raise NotADirectoryError(f"Plugin root is not a directory: {root}")
+
+    manifests: list[LoadedPluginManifest] = []
+    for entry in sorted(root.iterdir(), key=lambda candidate: candidate.name):
+        if not entry.is_dir():
+            continue
+        manifest_path = entry / PLUGIN_FILE_NAME
+        if manifest_path.is_file():
+            loaded = parse_plugin_manifest(manifest_path)
+            if loaded.manifest.name != entry.name:
+                raise ValueError(
+                    "Plugin directory and manifest name must match: "
+                    f"{entry.name} != {loaded.manifest.name}"
+                )
+            manifests.append(loaded)
+    return tuple(manifests)
diff --git a/coding-deepgent/src/coding_deepgent/plugins/registry.py b/coding-deepgent/src/coding_deepgent/plugins/registry.py
new file mode 100644
index 000000000..78bd11b4b
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/plugins/registry.py
@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable
+
+from coding_deepgent.plugins.schemas import LoadedPluginManifest
+
+
+@dataclass(frozen=True, slots=True)
+class PluginCapabilityDeclaration:
+    plugin_name: str
+    skills: tuple[str, ...]
+    tools: tuple[str, ...]
+    resources: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ValidatedPluginDeclaration(PluginCapabilityDeclaration):
+    pass
+
+
+class PluginRegistry:
+    def __init__(self, plugins: Iterable[LoadedPluginManifest] = ()) -> None:
+        ordered = tuple(plugins)
+        self._plugins = ordered
+        self._by_name = {plugin.manifest.name: plugin for plugin in ordered}
+        if len(self._by_name) != len(ordered):
+            raise ValueError("Plugin names must be unique")
+
+    def names(self) -> list[str]:
+        return list(self._by_name)
+
+    def get(self, name: str) -> LoadedPluginManifest | None:
+        return self._by_name.get(name)
+
+    def all(self) -> tuple[LoadedPluginManifest, ...]:
+        return self._plugins
+
+    def declarations(self) -> tuple[PluginCapabilityDeclaration, ...]:
+        return tuple(
+            PluginCapabilityDeclaration(
+                plugin_name=plugin.manifest.name,
+                skills=plugin.manifest.skills,
+                tools=plugin.manifest.tools,
+                resources=plugin.manifest.resources,
+            )
+            for plugin in self._plugins
+        )
+
+    def declared_tools(self) -> tuple[str, ...]:
+        return tuple(tool for item in self.declarations() for tool in item.tools)
+
+    def declared_skills(self) -> tuple[str, ...]:
+        return tuple(skill for item in self.declarations() for skill in item.skills)
+
+    def declared_resources(self) -> tuple[str, ...]:
+        return tuple(
+            resource for item in self.declarations() for resource in item.resources
+        )
+
+    def validate(
+        self,
+        *,
+        known_tools: set[str],
+        known_skills: set[str],
+        known_resources: set[str] | None = None,
+    ) -> tuple[ValidatedPluginDeclaration, ...]:
+        validated: list[ValidatedPluginDeclaration] = []
+        for item in self.declarations():
+            missing_tools = [tool for tool in item.tools if tool not in known_tools]
+            missing_skills = [
+                skill for skill in item.skills if skill not in known_skills
+            ]
+            missing_resources = (
+                [
+                    resource
+                    for resource in item.resources
+                    if resource not in known_resources
+                ]
+                if known_resources is not None
+                else []
+            )
+            if missing_tools or missing_skills or missing_resources:
+                raise ValueError(
+                    f"Plugin `{item.plugin_name}` declares unknown entries: "
+                    f"tools={missing_tools}, skills={missing_skills}, "
+                    f"resources={missing_resources}"
+                )
+            validated.append(
+                ValidatedPluginDeclaration(
+                    plugin_name=item.plugin_name,
+                    skills=item.skills,
+                    tools=item.tools,
+                    resources=item.resources,
+                )
+            )
+        return tuple(validated)
diff --git a/coding-deepgent/src/coding_deepgent/plugins/schemas.py b/coding-deepgent/src/coding_deepgent/plugins/schemas.py
new file mode 100644
index 000000000..7f45fa559
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/plugins/schemas.py
@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import re
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+_IDENTIFIER = re.compile(r"^[A-Za-z_][A-Za-z0-9_:-]*$")
+
+
+class PluginManifest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(..., min_length=1)
+    description: str = Field(..., min_length=1)
+    version: str = Field(..., min_length=1)
+    skills: tuple[str, ...] = ()
+    tools: tuple[str, ...] = ()
+    resources: tuple[str, ...] = ()
+
+    @field_validator("name", "description", "version")
+    @classmethod
+    def _text_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("value required")
+        return value
+
+    @field_validator("name")
+    @classmethod
+    def _name_must_be_identifier(cls, value: str) -> str:
+        if not _IDENTIFIER.fullmatch(value):
+            raise ValueError("name must be a local identifier")
+        return value
+
+    @field_validator("skills", "tools", "resources")
+    @classmethod
+    def _entries_must_be_identifiers(cls, values: tuple[str, ...]) -> tuple[str, ...]:
+        cleaned: list[str] = []
+        for value in values:
+            item = value.strip()
+            if not item:
+                raise ValueError("empty identifier")
+            if not _IDENTIFIER.fullmatch(item):
+                raise ValueError("values must be local identifiers")
+            cleaned.append(item)
+        if len(set(cleaned)) != len(cleaned):
+            raise ValueError("duplicate identifiers are not allowed")
+        return tuple(cleaned)
+
+
+@dataclass(frozen=True, slots=True)
+class LoadedPluginManifest:
+    manifest: PluginManifest
+    root: Path
+    path: Path
diff --git a/coding-deepgent/src/coding_deepgent/prompting/__init__.py b/coding-deepgent/src/coding_deepgent/prompting/__init__.py
new file mode 100644
index 000000000..c3ea86af8
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/prompting/__init__.py
@@ -0,0 +1,3 @@
+from .builder import PromptContext, build_default_system_prompt, build_prompt_context
+
+__all__ = ["PromptContext", "build_default_system_prompt", "build_prompt_context"]
diff --git a/coding-deepgent/src/coding_deepgent/prompting/builder.py b/coding-deepgent/src/coding_deepgent/prompting/builder.py
new file mode 100644
index 000000000..aec5a3f68
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/prompting/builder.py
@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Mapping, Sequence
+
+from coding_deepgent.memory import MemoryRecord, render_memories
+
+
+@dataclass(frozen=True, slots=True)
+class PromptContext:
+    default_system_prompt: tuple[str, ...]
+    user_context: Mapping[str, str] = field(default_factory=dict)
+    system_context: Mapping[str, str] = field(default_factory=dict)
+    append_system_prompt: str | None = None
+    memory_context: str | None = None
+
+    @property
+    def system_prompt_parts(self) -> tuple[str, ...]:
+        parts = [*self.default_system_prompt]
+        if self.memory_context:
+            parts.append(self.memory_context)
+        if self.append_system_prompt:
+            parts.append(self.append_system_prompt)
+        return tuple(parts)
+
+    @property
+    def system_prompt(self) -> str:
+        return "\n\n".join(self.system_prompt_parts)
+
+
+def build_default_system_prompt(*, workdir: Path, agent_name: str) -> tuple[str, ...]:
+    return (
+        f"You are {agent_name}, an independent cumulative LangChain cc product agent.",
+        f"Current workspace: {workdir}.",
+        (
+            "Use TodoWrite when explicit progress tracking helps on multi-step work; "
+            "preserve exactly one in-progress todo and include activeForm for every todo."
+        ),
+        "Prefer LangChain-native tools and state updates over prose when an action is needed.",
+    )
+
+
+def build_prompt_context(
+    *,
+    workdir: Path,
+    agent_name: str,
+    session_id: str,
+    entrypoint: str,
+    custom_system_prompt: str | None = None,
+    append_system_prompt: str | None = None,
+    memories: Sequence[MemoryRecord] = (),
+) -> PromptContext:
+    default_prompt = (
+        (custom_system_prompt,)
+        if custom_system_prompt
+        else build_default_system_prompt(workdir=workdir, agent_name=agent_name)
+    )
+    return PromptContext(
+        default_system_prompt=default_prompt,
+        user_context={"session_id": session_id},
+        system_context={
+            "workdir": str(workdir),
+            "entrypoint": entrypoint,
+            "agent_name": agent_name,
+        },
+        append_system_prompt=append_system_prompt,
+        memory_context=render_memories(memories),
+    )
diff --git a/coding-deepgent/src/coding_deepgent/renderers/__init__.py b/coding-deepgent/src/coding_deepgent/renderers/__init__.py
new file mode 100644
index 000000000..8d9773297
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/renderers/__init__.py
@@ -0,0 +1,17 @@
+from .planning import (
+    DEFAULT_PLAN_RENDERER,
+    PLAN_REMINDER_INTERVAL,
+    PlanRenderer,
+    TerminalPlanRenderer,
+    reminder_text,
+    render_plan_items,
+)
+
+__all__ = [
+    "DEFAULT_PLAN_RENDERER",
+    "PLAN_REMINDER_INTERVAL",
+    "PlanRenderer",
+    "TerminalPlanRenderer",
+    "reminder_text",
+    "render_plan_items",
+]
diff --git a/coding-deepgent/src/coding_deepgent/renderers/planning.py b/coding-deepgent/src/coding_deepgent/renderers/planning.py
new file mode 100644
index 000000000..682313e75
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/renderers/planning.py
@@ -0,0 +1,17 @@
+from coding_deepgent.todo.renderers import (
+    DEFAULT_PLAN_RENDERER,
+    PLAN_REMINDER_INTERVAL,
+    PlanRenderer,
+    TerminalPlanRenderer,
+    reminder_text,
+    render_plan_items,
+)
+
+__all__ = [
+    "DEFAULT_PLAN_RENDERER",
+    "PLAN_REMINDER_INTERVAL",
+    "PlanRenderer",
+    "TerminalPlanRenderer",
+    "reminder_text",
+    "render_plan_items",
+]
diff --git a/coding-deepgent/src/coding_deepgent/renderers/text.py b/coding-deepgent/src/coding_deepgent/renderers/text.py
new file mode 100644
index 000000000..54f743401
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/renderers/text.py
@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from io import StringIO
+from typing import Any
+
+from rich import box
+from rich.console import Console
+from rich.table import Table
+
+_RENDER_WIDTH = 140
+
+
+def _render_table(table: Table) -> str:
+    stream = StringIO()
+    console = Console(
+        file=stream,
+        color_system=None,
+        force_terminal=False,
+        record=True,
+        width=_RENDER_WIDTH,
+    )
+    console.print(table)
+    return console.export_text(styles=False).rstrip()
+
+
+def render_config_table(rows: Sequence[tuple[str, str]]) -> str:
+    table = Table(title="Configuration", box=box.SIMPLE_HEAVY, show_header=False)
+    table.add_column("Key", style="cyan", no_wrap=True)
+    table.add_column("Value", style="white")
+    for key, value in rows:
+        table.add_row(key, value)
+    return _render_table(table)
+
+
+def render_session_table(sessions: Sequence[Mapping[str, Any]]) -> str:
+    if not sessions:
+        return "No sessions recorded yet."
+
+    table = Table(title="Sessions", box=box.SIMPLE_HEAVY)
+    table.add_column("Session", style="cyan", no_wrap=True)
+    table.add_column("Updated", no_wrap=True)
+    table.add_column("Messages", justify="right", no_wrap=True)
+    table.add_column("Workdir")
+    for session in sessions:
+        table.add_row(
+            str(session.get("session_id", "unknown")),
+            str(session.get("updated_at", "-")),
+            str(session.get("message_count", 0)),
+            str(session.get("workdir", "-")),
+        )
+    return _render_table(table)
+
+
+def render_doctor_table(checks: Sequence[Mapping[str, Any]]) -> str:
+    table = Table(title="Doctor", box=box.SIMPLE_HEAVY)
+    table.add_column("Check", style="cyan", no_wrap=True, overflow="fold")
+    table.add_column("Status", no_wrap=True, overflow="fold")
+    table.add_column("Detail", overflow="fold")
+    for check in checks:
+        table.add_row(
+            str(check.get("name", "unknown")),
+            str(check.get("status", "unknown")),
+            str(check.get("detail", "")),
+        )
+    return _render_table(table)
diff --git a/coding-deepgent/src/coding_deepgent/rendering.py b/coding-deepgent/src/coding_deepgent/rendering.py
new file mode 100644
index 000000000..a1f340713
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/rendering.py
@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from typing import Any
+
+from coding_deepgent.compact import project_messages
+
+
+def _message_content(message: Any) -> Any:
+    if isinstance(message, dict):
+        return message.get("content", "")
+    return getattr(message, "content", "")
+
+
+def extract_text(content: Any) -> str:
+    if content is None:
+        return ""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        texts: list[str] = []
+        for block in content:
+            if isinstance(block, dict):
+                if block.get("type") in {"text", "output_text"} and block.get("text"):
+                    texts.append(str(block["text"]))
+                elif block.get("content"):
+                    texts.append(str(block["content"]))
+                continue
+            text = getattr(block, "text", None)
+            if text:
+                texts.append(str(text))
+        return "\n".join(texts).strip()
+
+    text_attr = getattr(content, "text", None)
+    if isinstance(text_attr, str):
+        return text_attr.strip()
+    if callable(text_attr):
+        try:
+            return str(text_attr()).strip()
+        except TypeError:
+            pass
+    return str(content).strip()
+
+
+def latest_assistant_text(result: Any) -> str:
+    if isinstance(result, dict):
+        messages = result.get("messages") or []
+        for message in reversed(messages):
+            role = (
+                message.get("role")
+                if isinstance(message, dict)
+                else getattr(message, "type", "")
+            )
+            if role in {"assistant", "ai"}:
+                text = extract_text(_message_content(message))
+                if text:
+                    return text
+        if messages:
+            return extract_text(_message_content(messages[-1]))
+    return extract_text(_message_content(result))
+
+
+def normalize_messages(messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return project_messages(messages)
diff --git a/coding-deepgent/src/coding_deepgent/runtime/__init__.py b/coding-deepgent/src/coding_deepgent/runtime/__init__.py
new file mode 100644
index 000000000..5f7542a2c
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/runtime/__init__.py
@@ -0,0 +1,32 @@
+from .checkpointing import select_checkpointer, select_store
+from .context import RuntimeContext
+from .events import InMemoryEventSink, NullEventSink, RuntimeEvent, RuntimeEventSink
+from .invocation import (
+    DEFAULT_SESSION_ID,
+    RuntimeInvocation,
+    build_runnable_config,
+    build_runtime_context,
+    build_runtime_invocation,
+    resolve_session_id,
+)
+from .state import PlanningState, RuntimeState, RuntimeTodoState, default_runtime_state
+
+__all__ = [
+    "DEFAULT_SESSION_ID",
+    "InMemoryEventSink",
+    "NullEventSink",
+    "PlanningState",
+    "RuntimeContext",
+    "RuntimeEvent",
+    "RuntimeEventSink",
+    "RuntimeInvocation",
+    "RuntimeState",
+    "RuntimeTodoState",
+    "build_runnable_config",
+    "build_runtime_context",
+    "build_runtime_invocation",
+    "default_runtime_state",
+    "resolve_session_id",
+    "select_checkpointer",
+    "select_store",
+]
diff --git a/coding-deepgent/src/coding_deepgent/runtime/checkpointing.py b/coding-deepgent/src/coding_deepgent/runtime/checkpointing.py
new file mode 100644
index 000000000..666b023bf
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/runtime/checkpointing.py
@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from langgraph.checkpoint.memory import InMemorySaver
+from langgraph.store.memory import InMemoryStore
+
+CheckpointerBackend = Literal["none", "memory"]
+StoreBackend = Literal["none", "memory"]
+
+
+def select_checkpointer(backend: CheckpointerBackend):
+    if backend == "none":
+        return None
+    if backend == "memory":
+        return InMemorySaver()
+    raise ValueError(f"Unsupported checkpointer backend: {backend}")
+
+
+def select_store(backend: StoreBackend):
+    if backend == "none":
+        return None
+    if backend == "memory":
+        return InMemoryStore()
+    raise ValueError(f"Unsupported store backend: {backend}")
diff --git a/coding-deepgent/src/coding_deepgent/runtime/context.py b/coding-deepgent/src/coding_deepgent/runtime/context.py
new file mode 100644
index 000000000..1267f86d2
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/runtime/context.py
@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from coding_deepgent.hooks.registry import LocalHookRegistry
+from coding_deepgent.runtime.events import RuntimeEventSink
+
+if TYPE_CHECKING:
+    from coding_deepgent.sessions.records import SessionContext
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeContext:
+    session_id: str
+    workdir: Path
+    trusted_workdirs: tuple[Path, ...]
+    entrypoint: str
+    agent_name: str
+    skill_dir: Path
+    event_sink: RuntimeEventSink
+    hook_registry: LocalHookRegistry = field(default_factory=LocalHookRegistry)
+    session_context: SessionContext | None = None
diff --git a/coding-deepgent/src/coding_deepgent/runtime/events.py b/coding-deepgent/src/coding_deepgent/runtime/events.py
new file mode 100644
index 000000000..32a3920a0
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/runtime/events.py
@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Mapping, Protocol
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeEvent:
+    kind: str
+    message: str
+    session_id: str
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+class RuntimeEventSink(Protocol):
+    def emit(self, event: RuntimeEvent) -> None: ...
+
+
+class NullEventSink:
+    def emit(self, event: RuntimeEvent) -> None:
+        del event
+
+
+class InMemoryEventSink:
+    def __init__(self) -> None:
+        self._events: list[RuntimeEvent] = []
+
+    def emit(self, event: RuntimeEvent) -> None:
+        self._events.append(event)
+
+    def snapshot(self) -> tuple[RuntimeEvent, ...]:
+        return tuple(self._events)
diff --git a/coding-deepgent/src/coding_deepgent/runtime/invocation.py b/coding-deepgent/src/coding_deepgent/runtime/invocation.py
new file mode 100644
index 000000000..e90734d1c
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/runtime/invocation.py
@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from coding_deepgent.hooks.registry import LocalHookRegistry
+from coding_deepgent.runtime.context import RuntimeContext
+from coding_deepgent.runtime.events import RuntimeEventSink
+from coding_deepgent.settings import Settings
+
+if TYPE_CHECKING:
+    from coding_deepgent.sessions.records import SessionContext
+
+DEFAULT_SESSION_ID = "default"
+
+
+def resolve_session_id(session_id: str | None = None) -> str:
+    resolved = (session_id or DEFAULT_SESSION_ID).strip()
+    return resolved or DEFAULT_SESSION_ID
+
+
+def build_runnable_config(
+    *, session_id: str | None = None
+) -> dict[str, dict[str, str]]:
+    resolved_session_id = resolve_session_id(session_id)
+    return {"configurable": {"thread_id": resolved_session_id}}
+
+
+def build_runtime_context(
+    settings: Settings,
+    event_sink: RuntimeEventSink,
+    hook_registry: LocalHookRegistry,
+    *,
+    session_id: str | None = None,
+    entrypoint: str | None = None,
+    agent_name: str | None = None,
+    session_context: SessionContext | None = None,
+) -> RuntimeContext:
+    resolved_session_id = resolve_session_id(session_id)
+    return RuntimeContext(
+        session_id=resolved_session_id,
+        workdir=settings.workdir,
+        trusted_workdirs=settings.trusted_workdirs,
+        entrypoint=entrypoint or settings.entrypoint,
+        agent_name=agent_name or settings.agent_name,
+        skill_dir=settings.skill_dir,
+        event_sink=event_sink,
+        hook_registry=hook_registry,
+        session_context=session_context,
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeInvocation:
+    context: RuntimeContext
+    config: dict[str, dict[str, str]]
+
+    @property
+    def thread_id(self) -> str:
+        return self.config["configurable"]["thread_id"]
+
+
+def build_runtime_invocation(
+    settings: Settings,
+    event_sink: RuntimeEventSink,
+    hook_registry: LocalHookRegistry,
+    *,
+    session_id: str | None = None,
+    entrypoint: str | None = None,
+    agent_name: str | None = None,
+    session_context: SessionContext | None = None,
+) -> RuntimeInvocation:
+    resolved_session_id = resolve_session_id(session_id)
+    return RuntimeInvocation(
+        context=build_runtime_context(
+            settings,
+            event_sink,
+            hook_registry,
+            session_id=resolved_session_id,
+            entrypoint=entrypoint,
+            agent_name=agent_name,
+            session_context=session_context,
+        ),
+        config=build_runnable_config(session_id=resolved_session_id),
+    )
diff --git a/coding-deepgent/src/coding_deepgent/runtime/state.py b/coding-deepgent/src/coding_deepgent/runtime/state.py
new file mode 100644
index 000000000..63ea96052
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/runtime/state.py
@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from langchain.agents import AgentState
+from typing_extensions import NotRequired, TypedDict
+
+
+class RuntimeTodoState(TypedDict):
+    content: str
+    status: Literal["pending", "in_progress", "completed"]
+    activeForm: str
+
+
+class RuntimeState(AgentState):
+    todos: NotRequired[list[RuntimeTodoState]]
+    rounds_since_update: NotRequired[int]
+
+
+PlanningState = RuntimeState
+
+
+def default_runtime_state() -> dict[str, Any]:
+    return {
+        "todos": [],
+        "rounds_since_update": 0,
+    }
diff --git a/coding-deepgent/src/coding_deepgent/sessions/__init__.py b/coding-deepgent/src/coding_deepgent/sessions/__init__.py
new file mode 100644
index 000000000..485187273
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/__init__.py
@@ -0,0 +1,58 @@
+from .langgraph import thread_config_for_session, thread_id_for_session
+from .ports import SessionStore
+from .records import (
+    COMPACT_RECORD_TYPE,
+    CompactedHistorySource,
+    EVIDENCE_RECORD_TYPE,
+    LoadedSession,
+    SessionCompact,
+    SessionContext,
+    SessionEvidence,
+    SessionLoadError,
+    SessionSummary,
+    iso_timestamp_now,
+)
+from .resume import (
+    RecoveryBrief,
+    apply_resume_state,
+    build_recovery_brief,
+    build_resume_context_message,
+    render_recovery_brief,
+    resume_session,
+)
+from .service import (
+    list_recorded_sessions,
+    load_recorded_session,
+    recorded_session_store,
+    run_prompt_with_recording,
+)
+from .store_jsonl import (
+    JsonlSessionStore,
+)
+
+__all__ = [
+    "LoadedSession",
+    "COMPACT_RECORD_TYPE",
+    "CompactedHistorySource",
+    "EVIDENCE_RECORD_TYPE",
+    "RecoveryBrief",
+    "SessionContext",
+    "SessionCompact",
+    "SessionEvidence",
+    "SessionLoadError",
+    "SessionStore",
+    "SessionSummary",
+    "JsonlSessionStore",
+    "apply_resume_state",
+    "build_recovery_brief",
+    "build_resume_context_message",
+    "iso_timestamp_now",
+    "list_recorded_sessions",
+    "load_recorded_session",
+    "recorded_session_store",
+    "render_recovery_brief",
+    "run_prompt_with_recording",
+    "resume_session",
+    "thread_config_for_session",
+    "thread_id_for_session",
+]
diff --git a/coding-deepgent/src/coding_deepgent/sessions/evidence_events.py b/coding-deepgent/src/coding_deepgent/sessions/evidence_events.py
new file mode 100644
index 000000000..567189be8
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/evidence_events.py
@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from coding_deepgent.runtime.events import RuntimeEvent
+from coding_deepgent.sessions.records import SessionContext
+from coding_deepgent.sessions.store_jsonl import JsonlSessionStore
+
+RUNTIME_EVIDENCE_KINDS = frozenset({"hook_blocked", "permission_denied"})
+
+
+def append_runtime_event_evidence(
+    *,
+    context: object,
+    event: RuntimeEvent,
+) -> bool:
+    if event.kind not in RUNTIME_EVIDENCE_KINDS:
+        return False
+    session_context = getattr(context, "session_context", None)
+    if not isinstance(session_context, SessionContext):
+        return False
+
+    metadata = _safe_metadata(event)
+    JsonlSessionStore(session_context.store_dir).append_evidence(
+        session_context,
+        kind="runtime_event",
+        summary=_summary(event, metadata),
+        status=_status(event),
+        subject=_subject(metadata),
+        metadata=metadata,
+    )
+    return True
+
+
+def _safe_metadata(event: RuntimeEvent) -> dict[str, object]:
+    source = event.metadata.get("source")
+    metadata: dict[str, object] = {
+        "event_kind": event.kind,
+        "source": source if isinstance(source, str) else "runtime",
+    }
+    for key in ("hook_event", "tool", "policy_code", "permission_behavior"):
+        value = event.metadata.get(key)
+        if isinstance(value, str) and value:
+            metadata[key] = value
+    blocked = event.metadata.get("blocked")
+    if isinstance(blocked, bool):
+        metadata["blocked"] = blocked
+    return metadata
+
+
+def _summary(event: RuntimeEvent, metadata: dict[str, object]) -> str:
+    if event.kind == "hook_blocked":
+        hook_event = metadata.get("hook_event", "unknown")
+        return f"Hook {hook_event} blocked execution."
+    if event.kind == "permission_denied":
+        tool = metadata.get("tool", "unknown")
+        policy_code = metadata.get("policy_code", "permission_denied")
+        return f"Tool {tool} denied by {policy_code}."
+    return event.message
+
+
+def _status(event: RuntimeEvent) -> str:
+    if event.kind == "hook_blocked":
+        return "blocked"
+    if event.kind == "permission_denied":
+        return "denied"
+    return "recorded"
+
+
+def _subject(metadata: dict[str, object]) -> str | None:
+    for key in ("tool", "hook_event"):
+        value = metadata.get(key)
+        if isinstance(value, str) and value:
+            return value
+    return None
diff --git a/coding-deepgent/src/coding_deepgent/sessions/langgraph.py b/coding-deepgent/src/coding_deepgent/sessions/langgraph.py
new file mode 100644
index 000000000..7674e4c86
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/langgraph.py
@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+
+def thread_id_for_session(session_id: str) -> str:
+    return session_id
+
+
+def thread_config_for_session(session_id: str) -> dict[str, dict[str, str]]:
+    return {"configurable": {"thread_id": thread_id_for_session(session_id)}}
diff --git a/coding-deepgent/src/coding_deepgent/sessions/ports.py b/coding-deepgent/src/coding_deepgent/sessions/ports.py
new file mode 100644
index 000000000..fe80aafb7
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/ports.py
@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, Protocol
+
+from .records import LoadedSession, SessionContext, SessionSummary
+
+
+class SessionStore(Protocol):
+    def create_session(
+        self,
+        *,
+        workdir: Path,
+        session_id: str | None = None,
+        entrypoint: str | None = None,
+    ) -> SessionContext: ...
+
+    def append_message(
+        self,
+        context: SessionContext,
+        *,
+        role: str,
+        content: str,
+        message_index: int | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> Path: ...
+
+    def append_state_snapshot(
+        self,
+        context: SessionContext,
+        *,
+        state: dict[str, Any],
+    ) -> Path: ...
+
+    def append_compact(
+        self,
+        context: SessionContext,
+        *,
+        trigger: str,
+        summary: str,
+        original_message_count: int,
+        summarized_message_count: int,
+        kept_message_count: int,
+        metadata: dict[str, Any] | None = None,
+    ) -> Path: ...
+
+    def load_session(
+        self,
+        *,
+        session_id: str,
+        workdir: Path,
+        default_state_factory: Callable[[], dict[str, Any]] | None = None,
+    ) -> LoadedSession: ...
+
+    def list_sessions(self, *, workdir: Path) -> list[SessionSummary]: ...
diff --git a/coding-deepgent/src/coding_deepgent/sessions/records.py b/coding-deepgent/src/coding_deepgent/sessions/records.py
new file mode 100644
index 000000000..ed470e36c
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/records.py
@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Literal
+
+SESSION_RECORD_VERSION = 1
+MESSAGE_RECORD_TYPE = "message"
+STATE_SNAPSHOT_RECORD_TYPE = "state_snapshot"
+EVIDENCE_RECORD_TYPE = "evidence"
+COMPACT_RECORD_TYPE = "compact"
+
+
+def iso_timestamp_now() -> str:
+    return datetime.now(UTC).isoformat().replace("+00:00", "Z")
+
+
+@dataclass(frozen=True, slots=True)
+class SessionContext:
+    session_id: str
+    workdir: Path
+    store_dir: Path
+    transcript_path: Path
+    entrypoint: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class SessionSummary:
+    session_id: str
+    workdir: Path
+    transcript_path: Path
+    created_at: str | None
+    updated_at: str | None
+    first_prompt: str | None
+    message_count: int
+    evidence_count: int = 0
+    compact_count: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class SessionEvidence:
+    kind: str
+    summary: str
+    status: str
+    created_at: str
+    subject: str | None = None
+    metadata: dict[str, Any] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class SessionCompact:
+    trigger: str
+    summary: str
+    created_at: str
+    original_message_count: int
+    summarized_message_count: int
+    kept_message_count: int
+    metadata: dict[str, Any] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class CompactedHistorySource:
+    mode: Literal["raw", "compact"]
+    reason: str
+    compact_index: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class LoadedSession:
+    context: SessionContext
+    history: list[dict[str, str]]
+    compacted_history: list[dict[str, Any]]
+    compacted_history_source: CompactedHistorySource
+    state: dict[str, Any]
+    evidence: list[SessionEvidence]
+    compacts: list[SessionCompact]
+    summary: SessionSummary
+
+
+class SessionLoadError(RuntimeError):
+    """Raised when a targeted session cannot be resumed from valid transcript records."""
+
+
+def make_message_record(
+    context: SessionContext,
+    *,
+    role: str,
+    content: str,
+    message_index: int | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    record: dict[str, Any] = {
+        "record_type": MESSAGE_RECORD_TYPE,
+        "version": SESSION_RECORD_VERSION,
+        "session_id": context.session_id,
+        "timestamp": iso_timestamp_now(),
+        "cwd": str(context.workdir),
+        "role": role,
+        "content": content,
+    }
+    if context.entrypoint:
+        record["entrypoint"] = context.entrypoint
+    if message_index is not None:
+        record["message_index"] = message_index
+    if metadata:
+        record["metadata"] = metadata
+    return record
+
+
+def make_state_snapshot_record(
+    context: SessionContext,
+    *,
+    state: dict[str, Any],
+) -> dict[str, Any]:
+    return {
+        "record_type": STATE_SNAPSHOT_RECORD_TYPE,
+        "version": SESSION_RECORD_VERSION,
+        "session_id": context.session_id,
+        "timestamp": iso_timestamp_now(),
+        "cwd": str(context.workdir),
+        "state": state,
+    }
+
+
+def make_evidence_record(
+    context: SessionContext,
+    *,
+    kind: str,
+    summary: str,
+    status: str = "recorded",
+    subject: str | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    record: dict[str, Any] = {
+        "record_type": EVIDENCE_RECORD_TYPE,
+        "version": SESSION_RECORD_VERSION,
+        "session_id": context.session_id,
+        "timestamp": iso_timestamp_now(),
+        "cwd": str(context.workdir),
+        "kind": kind.strip(),
+        "summary": summary.strip(),
+        "status": status.strip(),
+    }
+    if subject:
+        record["subject"] = subject.strip()
+    if metadata:
+        record["metadata"] = metadata
+    return record
+
+
+def make_compact_record(
+    context: SessionContext,
+    *,
+    trigger: str,
+    summary: str,
+    original_message_count: int,
+    summarized_message_count: int,
+    kept_message_count: int,
+    metadata: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    record: dict[str, Any] = {
+        "record_type": COMPACT_RECORD_TYPE,
+        "version": SESSION_RECORD_VERSION,
+        "session_id": context.session_id,
+        "timestamp": iso_timestamp_now(),
+        "cwd": str(context.workdir),
+        "trigger": trigger.strip(),
+        "summary": summary.strip(),
+        "original_message_count": original_message_count,
+        "summarized_message_count": summarized_message_count,
+        "kept_message_count": kept_message_count,
+    }
+    if context.entrypoint:
+        record["entrypoint"] = context.entrypoint
+    if metadata:
+        record["metadata"] = metadata
+    return record
diff --git a/coding-deepgent/src/coding_deepgent/sessions/resume.py b/coding-deepgent/src/coding_deepgent/sessions/resume.py
new file mode 100644
index 000000000..e7b2c4b10
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/resume.py
@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from collections.abc import Callable, MutableMapping
+from dataclasses import dataclass
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+
+from .ports import SessionStore
+from .records import LoadedSession, SessionCompact, SessionEvidence
+
+RESUME_CONTEXT_MESSAGE_PREFIX = (
+    "Resumed session context. Use this brief as continuation context, not as a new user request."
+)
+
+
+@dataclass(frozen=True, slots=True)
+class RecoveryBrief:
+    session_id: str
+    updated_at: str | None
+    message_count: int
+    active_todos: tuple[str, ...]
+    recent_evidence: tuple[SessionEvidence, ...]
+    recent_compacts: tuple[SessionCompact, ...]
+
+
+def apply_resume_state(
+    runtime_state: MutableMapping[str, Any],
+    loaded_session: LoadedSession,
+) -> None:
+    runtime_state.clear()
+    runtime_state.update(deepcopy(loaded_session.state))
+
+
+def resume_session(
+    store: SessionStore,
+    *,
+    session_id: str,
+    workdir: Path,
+    runtime_state: MutableMapping[str, Any],
+    default_state_factory: Callable[[], dict[str, Any]] | None = None,
+) -> LoadedSession:
+    loaded_session = store.load_session(
+        session_id=session_id,
+        workdir=workdir,
+        default_state_factory=default_state_factory,
+    )
+    apply_resume_state(runtime_state, loaded_session)
+    return loaded_session
+
+
+def build_recovery_brief(
+    loaded_session: LoadedSession,
+    *,
+    evidence_limit: int = 5,
+    compact_limit: int = 3,
+) -> RecoveryBrief:
+    active_todos = tuple(
+        str(item.get("content", "")).strip()
+        for item in loaded_session.state.get("todos", [])
+        if isinstance(item, dict)
+        and item.get("status") in {"pending", "in_progress"}
+        and str(item.get("content", "")).strip()
+    )
+    return RecoveryBrief(
+        session_id=loaded_session.summary.session_id,
+        updated_at=loaded_session.summary.updated_at,
+        message_count=loaded_session.summary.message_count,
+        active_todos=active_todos,
+        recent_evidence=tuple(loaded_session.evidence[-evidence_limit:]),
+        recent_compacts=tuple(loaded_session.compacts[-compact_limit:]),
+    )
+
+
+def render_recovery_brief(brief: RecoveryBrief) -> str:
+    lines = [
+        f"Session: {brief.session_id}",
+        f"Messages: {brief.message_count}",
+        f"Updated: {brief.updated_at or 'unknown'}",
+        "Active todos:",
+    ]
+    lines.extend(f"- {todo}" for todo in brief.active_todos)
+    if not brief.active_todos:
+        lines.append("- none")
+
+    lines.append("Recent evidence:")
+    lines.extend(_render_evidence(item) for item in brief.recent_evidence)
+    if not brief.recent_evidence:
+        lines.append("- none")
+    lines.append("Recent compacts:")
+    lines.extend(
+        f"- [{item.trigger}] {item.summary}"
+        for item in brief.recent_compacts
+    )
+    if not brief.recent_compacts:
+        lines.append("- none")
+    return "\n".join(lines)
+
+
+def _render_evidence(item: SessionEvidence) -> str:
+    return f"- [{item.status}] {item.kind}: {item.summary}{_evidence_provenance(item)}"
+
+
+def _evidence_provenance(item: SessionEvidence) -> str:
+    if item.kind != "verification":
+        return ""
+
+    metadata = item.metadata or {}
+    parts: list[str] = []
+    plan_id = metadata.get("plan_id")
+    verdict = metadata.get("verdict")
+    if isinstance(plan_id, str) and plan_id.strip():
+        parts.append(f"plan={plan_id.strip()}")
+    elif item.subject:
+        parts.append(f"subject={item.subject}")
+    if isinstance(verdict, str) and verdict.strip():
+        parts.append(f"verdict={verdict.strip()}")
+    if not parts:
+        return ""
+    return f" ({'; '.join(parts)})"
+
+
+def build_resume_context_message(loaded_session: LoadedSession) -> dict[str, str]:
+    return {
+        "role": "system",
+        "content": (
+            f"{RESUME_CONTEXT_MESSAGE_PREFIX}\n\n"
+            f"{render_recovery_brief(build_recovery_brief(loaded_session))}"
+        ),
+    }
+
+
+def is_resume_context_message(message: dict[str, Any]) -> bool:
+    return message.get("role") == "system" and str(
+        message.get("content", "")
+    ).startswith(RESUME_CONTEXT_MESSAGE_PREFIX)
diff --git a/coding-deepgent/src/coding_deepgent/sessions/service.py b/coding-deepgent/src/coding_deepgent/sessions/service.py
new file mode 100644
index 000000000..0ae890c95
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/service.py
@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from inspect import Parameter, signature
+from typing import Any
+
+from coding_deepgent.compact import (
+    compact_record_from_messages,
+    is_compact_artifact_message,
+)
+from coding_deepgent.runtime import default_runtime_state
+from coding_deepgent.settings import Settings
+from coding_deepgent.sessions.records import LoadedSession, SessionSummary
+from coding_deepgent.sessions.resume import is_resume_context_message
+from coding_deepgent.sessions.store_jsonl import JsonlSessionStore
+
+
+def recorded_session_store(settings: Settings) -> JsonlSessionStore:
+    return JsonlSessionStore(settings.session_dir)
+
+
+def list_recorded_sessions(settings: Settings) -> Sequence[SessionSummary]:
+    return recorded_session_store(settings).list_sessions(workdir=settings.workdir)
+
+
+def load_recorded_session(settings: Settings, session_id: str) -> LoadedSession:
+    return recorded_session_store(settings).load_session(
+        session_id=session_id,
+        workdir=settings.workdir,
+    )
+
+
+def _recorded_message_count(history: Sequence[dict[str, Any]]) -> int:
+    compact_record = compact_record_from_messages(list(history))
+    if compact_record is not None:
+        return int(compact_record["original_message_count"])
+    return sum(
+        1
+        for message in history
+        if not is_resume_context_message(message)
+        and not is_compact_artifact_message(message)
+    )
+
+
+def _supports_keyword_argument(callback: Callable[..., Any], keyword: str) -> bool:
+    try:
+        parameters = signature(callback).parameters.values()
+    except (TypeError, ValueError):
+        return True
+
+    return any(
+        parameter.kind == Parameter.VAR_KEYWORD or parameter.name == keyword
+        for parameter in parameters
+    )
+
+
+def run_prompt_with_recording(
+    *,
+    settings: Settings,
+    prompt: str,
+    run_agent: Callable[..., str],
+    history: list[dict[str, Any]] | None = None,
+    session_state: dict[str, Any] | None = None,
+    session_id: str | None = None,
+) -> str:
+    store = recorded_session_store(settings)
+    context = None
+    active_session_id = session_id
+    active_state = session_state if session_state is not None else default_runtime_state()
+    transcript = history if history is not None else []
+    recorded_message_count = _recorded_message_count(transcript)
+
+    if session_id is not None:
+        context = store.create_session(
+            workdir=settings.workdir,
+            session_id=session_id,
+            entrypoint=settings.entrypoint,
+        )
+    elif history is None:
+        context = store.create_session(
+            workdir=settings.workdir,
+            session_id=session_id,
+            entrypoint=settings.entrypoint,
+        )
+        active_session_id = context.session_id
+
+    if context is not None:
+        compact_record = compact_record_from_messages(transcript)
+        if compact_record is not None:
+            store.append_compact(context, **compact_record)
+        store.append_message(
+            context,
+            role="user",
+            content=prompt,
+            message_index=recorded_message_count,
+        )
+
+    transcript.append({"role": "user", "content": prompt})
+    run_agent_kwargs: dict[str, Any] = {
+        "session_state": active_state,
+        "session_id": active_session_id,
+    }
+    if context is not None and _supports_keyword_argument(
+        run_agent, "session_context"
+    ):
+        run_agent_kwargs["session_context"] = context
+    result = run_agent(transcript, **run_agent_kwargs)
+
+    if context is not None:
+        store.append_message(
+            context,
+            role="assistant",
+            content=result,
+            message_index=recorded_message_count + 1,
+        )
+        store.append_state_snapshot(context, state=active_state)
+        store.append_evidence(
+            context,
+            kind="runtime",
+            summary="Prompt completed through coding-deepgent CLI continuation path."
+            if history is not None
+            else "Prompt completed through coding-deepgent CLI run path.",
+            status="completed",
+            subject="cli.run_once.resume" if history is not None else "cli.run_once",
+        )
+
+    return result
diff --git a/coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py b/coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py
new file mode 100644
index 000000000..a7e3aeb71
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py
@@ -0,0 +1,414 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import uuid
+from collections.abc import Callable
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+
+from coding_deepgent.compact import compact_messages_with_summary
+from coding_deepgent.runtime import default_runtime_state
+
+from .records import (
+    COMPACT_RECORD_TYPE,
+    EVIDENCE_RECORD_TYPE,
+    LoadedSession,
+    MESSAGE_RECORD_TYPE,
+    SESSION_RECORD_VERSION,
+    STATE_SNAPSHOT_RECORD_TYPE,
+    CompactedHistorySource,
+    SessionContext,
+    SessionCompact,
+    SessionEvidence,
+    SessionLoadError,
+    SessionSummary,
+    make_compact_record,
+    make_evidence_record,
+    make_message_record,
+    make_state_snapshot_record,
+)
+
+
+class JsonlSessionStore:
+    def __init__(self, base_dir: Path | None = None) -> None:
+        self.base_dir = (
+            base_dir or Path.home() / ".coding-deepgent" / "sessions"
+        ).expanduser()
+
+    def create_session(
+        self,
+        *,
+        workdir: Path,
+        session_id: str | None = None,
+        entrypoint: str | None = None,
+    ) -> SessionContext:
+        context = self._context_for(
+            workdir=workdir,
+            session_id=session_id or str(uuid.uuid4()),
+            entrypoint=entrypoint,
+        )
+        context.transcript_path.parent.mkdir(parents=True, exist_ok=True)
+        context.transcript_path.touch(exist_ok=True)
+        return context
+
+    def transcript_path_for(self, *, session_id: str, workdir: Path) -> Path:
+        normalized_workdir = workdir.expanduser().resolve()
+        return self.workspace_dir_for(normalized_workdir) / f"{session_id}.jsonl"
+
+    def workspace_dir_for(self, workdir: Path) -> Path:
+        normalized_workdir = workdir.expanduser().resolve()
+        digest = hashlib.sha1(str(normalized_workdir).encode("utf-8")).hexdigest()[:16]
+        return self.base_dir / digest
+
+    def append_message(
+        self,
+        context: SessionContext,
+        *,
+        role: str,
+        content: str,
+        message_index: int | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> Path:
+        record = make_message_record(
+            context,
+            role=role,
+            content=content,
+            message_index=message_index,
+            metadata=metadata,
+        )
+        self._append_record(context.transcript_path, record)
+        return context.transcript_path
+
+    def append_state_snapshot(
+        self,
+        context: SessionContext,
+        *,
+        state: dict[str, Any],
+    ) -> Path:
+        serializable_state = json.loads(json.dumps(state))
+        record = make_state_snapshot_record(context, state=serializable_state)
+        self._append_record(context.transcript_path, record)
+        return context.transcript_path
+
+    def append_evidence(
+        self,
+        context: SessionContext,
+        *,
+        kind: str,
+        summary: str,
+        status: str = "recorded",
+        subject: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> Path:
+        serializable_metadata = (
+            json.loads(json.dumps(metadata)) if metadata is not None else None
+        )
+        record = make_evidence_record(
+            context,
+            kind=kind,
+            summary=summary,
+            status=status,
+            subject=subject,
+            metadata=serializable_metadata,
+        )
+        self._append_record(context.transcript_path, record)
+        return context.transcript_path
+
+    def append_compact(
+        self,
+        context: SessionContext,
+        *,
+        trigger: str,
+        summary: str,
+        original_message_count: int,
+        summarized_message_count: int,
+        kept_message_count: int,
+        metadata: dict[str, Any] | None = None,
+    ) -> Path:
+        serializable_metadata = (
+            json.loads(json.dumps(metadata)) if metadata is not None else None
+        )
+        record = make_compact_record(
+            context,
+            trigger=trigger,
+            summary=summary,
+            original_message_count=original_message_count,
+            summarized_message_count=summarized_message_count,
+            kept_message_count=kept_message_count,
+            metadata=serializable_metadata,
+        )
+        self._append_record(context.transcript_path, record)
+        return context.transcript_path
+
+    def load_session(
+        self,
+        *,
+        session_id: str,
+        workdir: Path,
+        default_state_factory: Callable[[], dict[str, Any]] | None = None,
+    ) -> LoadedSession:
+        normalized_workdir = workdir.expanduser().resolve()
+        context = self._context_for(workdir=normalized_workdir, session_id=session_id)
+        history: list[dict[str, str]] = []
+        last_valid_state: dict[str, Any] | None = None
+        created_at: str | None = None
+        updated_at: str | None = None
+        first_prompt: str | None = None
+        evidence: list[SessionEvidence] = []
+        compacts: list[SessionCompact] = []
+
+        for record in self._iter_valid_records(context.transcript_path):
+            if record.get("session_id") != session_id:
+                continue
+            if record.get("cwd") != str(normalized_workdir):
+                continue
+
+            timestamp = record.get("timestamp")
+            if isinstance(timestamp, str):
+                created_at = created_at or timestamp
+                updated_at = timestamp
+
+            record_type = record.get("record_type")
+            if record_type == MESSAGE_RECORD_TYPE:
+                role = record.get("role")
+                content = record.get("content")
+                if not isinstance(role, str) or not isinstance(content, str):
+                    continue
+                history.append({"role": role, "content": content})
+                if first_prompt is None and role == "user":
+                    first_prompt = content
+            elif record_type == STATE_SNAPSHOT_RECORD_TYPE:
+                state = self._coerce_state_snapshot(record.get("state"))
+                if state is not None:
+                    last_valid_state = state
+            elif record_type == EVIDENCE_RECORD_TYPE:
+                evidence_item = self._coerce_evidence(record)
+                if evidence_item is not None:
+                    evidence.append(evidence_item)
+            elif record_type == COMPACT_RECORD_TYPE:
+                compact_item = self._coerce_compact(record)
+                if compact_item is not None:
+                    compacts.append(compact_item)
+
+        if not history:
+            raise SessionLoadError(
+                f"No valid session messages found for session {session_id}"
+            )
+
+        summary = SessionSummary(
+            session_id=session_id,
+            workdir=normalized_workdir,
+            transcript_path=context.transcript_path,
+            created_at=created_at,
+            updated_at=updated_at,
+            first_prompt=first_prompt,
+            message_count=len(history),
+            evidence_count=len(evidence),
+            compact_count=len(compacts),
+        )
+        state_factory = default_state_factory or default_runtime_state
+        state = deepcopy(
+            last_valid_state if last_valid_state is not None else state_factory()
+        )
+        compacted_history, compacted_history_source = self._build_compacted_history(
+            history, compacts
+        )
+        return LoadedSession(
+            context=context,
+            history=history,
+            compacted_history=compacted_history,
+            compacted_history_source=compacted_history_source,
+            state=state,
+            evidence=evidence,
+            compacts=compacts,
+            summary=summary,
+        )
+
+    def list_sessions(self, *, workdir: Path) -> list[SessionSummary]:
+        normalized_workdir = workdir.expanduser().resolve()
+        workspace_dir = self.workspace_dir_for(normalized_workdir)
+        if not workspace_dir.exists():
+            return []
+
+        summaries: list[SessionSummary] = []
+        for transcript_path in sorted(workspace_dir.glob("*.jsonl")):
+            session_id = transcript_path.stem
+            try:
+                loaded = self.load_session(
+                    session_id=session_id, workdir=normalized_workdir
+                )
+            except SessionLoadError:
+                continue
+            summaries.append(loaded.summary)
+
+        return sorted(
+            summaries,
+            key=lambda summary: summary.updated_at or "",
+            reverse=True,
+        )
+
+    def _append_record(self, transcript_path: Path, record: dict[str, Any]) -> None:
+        transcript_path.parent.mkdir(parents=True, exist_ok=True)
+        with transcript_path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(record, ensure_ascii=False, sort_keys=True))
+            handle.write("\n")
+
+    def _context_for(
+        self,
+        *,
+        workdir: Path,
+        session_id: str,
+        entrypoint: str | None = None,
+    ) -> SessionContext:
+        normalized_workdir = workdir.expanduser().resolve()
+        return SessionContext(
+            session_id=session_id,
+            workdir=normalized_workdir,
+            store_dir=self.base_dir,
+            transcript_path=self.transcript_path_for(
+                session_id=session_id,
+                workdir=normalized_workdir,
+            ),
+            entrypoint=entrypoint,
+        )
+
+    def _iter_valid_records(self, transcript_path: Path) -> list[dict[str, Any]]:
+        if not transcript_path.exists():
+            return []
+
+        records: list[dict[str, Any]] = []
+        with transcript_path.open(encoding="utf-8") as handle:
+            for raw_line in handle:
+                line = raw_line.strip()
+                if not line:
+                    continue
+                try:
+                    record = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if not isinstance(record, dict):
+                    continue
+                if record.get("version") != SESSION_RECORD_VERSION:
+                    continue
+                if not isinstance(record.get("timestamp"), str):
+                    continue
+                records.append(record)
+        return records
+
+    def _coerce_state_snapshot(self, state: Any) -> dict[str, Any] | None:
+        if not isinstance(state, dict):
+            return None
+
+        todos = state.get("todos")
+        rounds_since_update = state.get("rounds_since_update")
+        if not isinstance(todos, list):
+            return None
+        if not isinstance(rounds_since_update, int):
+            return None
+
+        return {
+            "todos": deepcopy(todos),
+            "rounds_since_update": rounds_since_update,
+        }
+
+    def _coerce_evidence(self, record: dict[str, Any]) -> SessionEvidence | None:
+        kind = record.get("kind")
+        summary = record.get("summary")
+        status = record.get("status")
+        created_at = record.get("timestamp")
+        subject = record.get("subject")
+        metadata = record.get("metadata")
+        if not isinstance(kind, str) or not kind.strip():
+            return None
+        if not isinstance(summary, str) or not summary.strip():
+            return None
+        if not isinstance(status, str) or not status.strip():
+            return None
+        if not isinstance(created_at, str) or not created_at.strip():
+            return None
+        if subject is not None and not isinstance(subject, str):
+            return None
+        if metadata is not None and not isinstance(metadata, dict):
+            return None
+        return SessionEvidence(
+            kind=kind.strip(),
+            summary=summary.strip(),
+            status=status.strip(),
+            created_at=created_at,
+            subject=subject.strip() if isinstance(subject, str) and subject else None,
+            metadata=deepcopy(metadata) if isinstance(metadata, dict) else None,
+        )
+
+    def _coerce_compact(self, record: dict[str, Any]) -> SessionCompact | None:
+        trigger = record.get("trigger")
+        summary = record.get("summary")
+        created_at = record.get("timestamp")
+        original_message_count = record.get("original_message_count")
+        summarized_message_count = record.get("summarized_message_count")
+        kept_message_count = record.get("kept_message_count")
+        metadata = record.get("metadata")
+        if not isinstance(trigger, str) or not trigger.strip():
+            return None
+        if not isinstance(summary, str) or not summary.strip():
+            return None
+        if not isinstance(created_at, str) or not created_at.strip():
+            return None
+        if not isinstance(original_message_count, int) or original_message_count < 0:
+            return None
+        if not isinstance(summarized_message_count, int) or summarized_message_count < 0:
+            return None
+        if not isinstance(kept_message_count, int) or kept_message_count < 0:
+            return None
+        if metadata is not None and not isinstance(metadata, dict):
+            return None
+        return SessionCompact(
+            trigger=trigger.strip(),
+            summary=summary.strip(),
+            created_at=created_at,
+            original_message_count=original_message_count,
+            summarized_message_count=summarized_message_count,
+            kept_message_count=kept_message_count,
+            metadata=deepcopy(metadata) if isinstance(metadata, dict) else None,
+        )
+
+    def _build_compacted_history(
+        self,
+        history: list[dict[str, str]],
+        compacts: list[SessionCompact],
+    ) -> tuple[list[dict[str, Any]], CompactedHistorySource]:
+        raw_history = [dict(message) for message in history]
+        if not compacts:
+            return raw_history, CompactedHistorySource(
+                mode="raw", reason="no_compacts"
+            )
+
+        for index in range(len(compacts) - 1, -1, -1):
+            compact = compacts[index]
+            compacted = self._build_history_for_compact(raw_history, compact)
+            if compacted is not None:
+                return compacted, CompactedHistorySource(
+                    mode="compact",
+                    reason="latest_valid_compact",
+                    compact_index=index,
+                )
+        return raw_history, CompactedHistorySource(
+            mode="raw", reason="no_valid_compact"
+        )
+
+    def _build_history_for_compact(
+        self,
+        raw_history: list[dict[str, Any]],
+        compact: SessionCompact,
+    ) -> list[dict[str, Any]] | None:
+        keep_from = compact.original_message_count - compact.kept_message_count
+        keep_from = min(len(raw_history), max(0, keep_from))
+        preserved_tail = [dict(message) for message in raw_history[keep_from:]]
+        if not preserved_tail:
+            return None
+        return compact_messages_with_summary(
+            preserved_tail,
+            summary=compact.summary,
+            keep_last=len(preserved_tail),
+        ).messages
diff --git a/coding-deepgent/src/coding_deepgent/settings.py b/coding-deepgent/src/coding_deepgent/settings.py
new file mode 100644
index 000000000..ad3ffd434
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/settings.py
@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import Field, SecretStr, field_validator, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from coding_deepgent.permission_specs import PermissionRuleSpec
+
+PACKAGE_ROOT = Path(__file__).resolve().parent
+PROJECT_ROOT = PACKAGE_ROOT.parent.parent
+DEFAULT_OPENAI_MODEL = "gpt-4.1-mini"
+STATUS_FILE = PROJECT_ROOT / "project_status.json"
+
+CheckpointerBackend = Literal["none", "memory"]
+StoreBackend = Literal["none", "memory"]
+PermissionMode = Literal[
+    "default", "plan", "acceptEdits", "bypassPermissions", "dontAsk"
+]
+
+
+def resolve_workdir() -> Path:
+    configured = os.getenv("CODING_DEEPGENT_WORKDIR", "").strip()
+    if configured:
+        return Path(configured).expanduser().resolve()
+    return Path.cwd().resolve()
+
+
+def deepgent_model_name() -> str:
+    openai_model = os.getenv("OPENAI_MODEL", "").strip()
+    if openai_model:
+        return openai_model
+
+    legacy_model = os.getenv("MODEL_ID", "").strip()
+    if legacy_model and not legacy_model.lower().startswith("claude"):
+        return legacy_model
+
+    return DEFAULT_OPENAI_MODEL
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="CODING_DEEPGENT_",
+        env_file=PROJECT_ROOT / ".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    workdir: Path = Field(default_factory=resolve_workdir)
+    session_dir: Path = Field(default=Path(".coding-deepgent/sessions"))
+    skill_dir: Path = Field(default=Path("skills"))
+    plugin_dir: Path = Field(default=Path("plugins"))
+    model_name: str = Field(default_factory=deepgent_model_name)
+    openai_api_key: SecretStr | None = Field(default=None, alias="OPENAI_API_KEY")
+    openai_base_url: str | None = Field(default=None, alias="OPENAI_BASE_URL")
+    checkpointer_backend: CheckpointerBackend = "none"
+    store_backend: StoreBackend = "none"
+    permission_mode: PermissionMode = "default"
+    permission_allow_rules: tuple[PermissionRuleSpec, ...] = ()
+    permission_ask_rules: tuple[PermissionRuleSpec, ...] = ()
+    permission_deny_rules: tuple[PermissionRuleSpec, ...] = ()
+    trusted_workdirs: tuple[Path, ...] = ()
+    custom_system_prompt: str | None = None
+    append_system_prompt: str | None = None
+    agent_name: str = "coding-deepgent"
+    entrypoint: str = "coding-deepgent"
+    model_timeout_seconds: int = Field(default=60, ge=1, le=600)
+
+    @field_validator("workdir", mode="before")
+    @classmethod
+    def _resolve_workdir_value(cls, value: Any) -> Path:
+        if value in (None, ""):
+            return resolve_workdir()
+        return Path(value).expanduser().resolve()
+
+    @field_validator("model_name", mode="before")
+    @classmethod
+    def _resolve_model_name_value(cls, value: Any) -> str:
+        resolved = str(value or "").strip()
+        if not resolved:
+            return deepgent_model_name()
+        if resolved.lower().startswith("claude"):
+            return DEFAULT_OPENAI_MODEL
+        return resolved
+
+    @model_validator(mode="after")
+    def _normalize_paths(self) -> "Settings":
+        if not self.session_dir.is_absolute():
+            self.session_dir = (self.workdir / self.session_dir).resolve()
+        else:
+            self.session_dir = self.session_dir.expanduser().resolve()
+
+        if not self.skill_dir.is_absolute():
+            self.skill_dir = (self.workdir / self.skill_dir).resolve()
+        else:
+            self.skill_dir = self.skill_dir.expanduser().resolve()
+
+        if not self.plugin_dir.is_absolute():
+            self.plugin_dir = (self.workdir / self.plugin_dir).resolve()
+        else:
+            self.plugin_dir = self.plugin_dir.expanduser().resolve()
+
+        normalized_trusted_workdirs: list[Path] = []
+        for path in self.trusted_workdirs:
+            if path.is_absolute():
+                normalized = path.expanduser().resolve()
+            else:
+                normalized = (self.workdir / path).resolve()
+            if normalized not in normalized_trusted_workdirs:
+                normalized_trusted_workdirs.append(normalized)
+        self.trusted_workdirs = tuple(normalized_trusted_workdirs)
+        return self
+
+
+def load_settings() -> Settings:
+    return Settings()
+
+
+def build_openai_model(
+    settings: Settings | None = None,
+    *,
+    temperature: float = 0.0,
+    timeout: int | None = None,
+):
+    active_settings = settings or load_settings()
+    if active_settings.openai_api_key is None:
+        raise RuntimeError(
+            "OPENAI_API_KEY is required to run coding-deepgent. "
+            "Set OPENAI_MODEL to choose a model and OPENAI_BASE_URL for an OpenAI-compatible endpoint."
+        )
+
+    from langchain_openai import ChatOpenAI
+
+    kwargs: dict[str, Any] = {
+        "model": active_settings.model_name,
+        "temperature": temperature,
+        "timeout": timeout or active_settings.model_timeout_seconds,
+        "api_key": active_settings.openai_api_key.get_secret_value(),
+    }
+    if active_settings.openai_base_url:
+        kwargs["base_url"] = active_settings.openai_base_url
+    return ChatOpenAI(**kwargs)
diff --git a/coding-deepgent/src/coding_deepgent/skills/__init__.py b/coding-deepgent/src/coding_deepgent/skills/__init__.py
new file mode 100644
index 000000000..662d12744
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/skills/__init__.py
@@ -0,0 +1,21 @@
+from .loader import (
+    SKILL_FILE_NAME,
+    discover_local_skills,
+    load_local_skill,
+    parse_skill_markdown,
+    skill_root,
+)
+from .schemas import LoadedSkill, LoadSkillInput, SkillMetadata
+from .tools import load_skill
+
+__all__ = [
+    "LoadedSkill",
+    "LoadSkillInput",
+    "SKILL_FILE_NAME",
+    "SkillMetadata",
+    "discover_local_skills",
+    "load_local_skill",
+    "load_skill",
+    "parse_skill_markdown",
+    "skill_root",
+]
diff --git a/coding-deepgent/src/coding_deepgent/skills/loader.py b/coding-deepgent/src/coding_deepgent/skills/loader.py
new file mode 100644
index 000000000..5f5b59dc7
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/skills/loader.py
@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from coding_deepgent.skills.schemas import LoadedSkill, SkillMetadata
+
+SKILL_FILE_NAME = "SKILL.md"
+
+
+def parse_skill_markdown(path: Path) -> LoadedSkill:
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---\n"):
+        raise ValueError(f"Skill file missing frontmatter: {path}")
+    _, frontmatter, body = text.split("---", 2)
+    metadata: dict[str, str] = {}
+    for line in frontmatter.splitlines():
+        if not line.strip():
+            continue
+        key, sep, value = line.partition(":")
+        if not sep:
+            raise ValueError(f"Invalid frontmatter line in {path}: {line}")
+        metadata[key.strip()] = value.strip().strip('"')
+    return LoadedSkill(
+        metadata=SkillMetadata.model_validate(metadata),
+        body=body.strip(),
+        path=path,
+    )
+
+
+def skill_root(workdir: Path, skill_dir: Path) -> Path:
+    if skill_dir.is_absolute():
+        return skill_dir.resolve()
+    return (workdir / skill_dir).resolve()
+
+
+def load_local_skill(*, workdir: Path, skill_dir: Path, name: str) -> LoadedSkill:
+    root = skill_root(workdir, skill_dir)
+    path = root / name / SKILL_FILE_NAME
+    if not path.is_file():
+        raise FileNotFoundError(f"Local skill not found: {name}")
+    loaded = parse_skill_markdown(path)
+    if loaded.metadata.name != name:
+        raise ValueError(
+            f"Skill name mismatch: requested {name}, found {loaded.metadata.name}"
+        )
+    return loaded
+
+
+def discover_local_skills(
+    *,
+    workdir: Path,
+    skill_dir: Path,
+) -> tuple[LoadedSkill, ...]:
+    root = skill_root(workdir, skill_dir)
+    if not root.exists():
+        return ()
+    if not root.is_dir():
+        raise NotADirectoryError(f"Skill root is not a directory: {root}")
+
+    skills: list[LoadedSkill] = []
+    for entry in sorted(root.iterdir(), key=lambda candidate: candidate.name):
+        if not entry.is_dir():
+            continue
+        path = entry / SKILL_FILE_NAME
+        if not path.is_file():
+            continue
+        try:
+            loaded = parse_skill_markdown(path)
+        except ValueError:
+            continue
+        if loaded.metadata.name != entry.name:
+            raise ValueError(
+                f"Skill directory and metadata name must match: {entry.name} != {loaded.metadata.name}"
+            )
+        skills.append(loaded)
+    return tuple(skills)
diff --git a/coding-deepgent/src/coding_deepgent/skills/schemas.py b/coding-deepgent/src/coding_deepgent/skills/schemas.py
new file mode 100644
index 000000000..a6010fbb3
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/skills/schemas.py
@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from langchain.tools import ToolRuntime
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class SkillMetadata(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(..., min_length=1)
+    description: str = Field(..., min_length=1)
+
+    @field_validator("name", "description")
+    @classmethod
+    def _text_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("value required")
+        return value
+
+
+@dataclass(frozen=True, slots=True)
+class LoadedSkill:
+    metadata: SkillMetadata
+    body: str
+    path: Path
+
+    def render(self, *, max_chars: int = 4000) -> str:
+        body = (
+            self.body
+            if len(self.body) <= max_chars
+            else self.body[:max_chars] + "\n...[skill truncated]"
+        )
+        return f"# Skill: {self.metadata.name}\n\n{self.metadata.description}\n\n{body}"
+
+
+class LoadSkillInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    name: str = Field(..., min_length=1, description="Local skill name to load.")
+    runtime: ToolRuntime
+
+    @field_validator("name")
+    @classmethod
+    def _name_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("name required")
+        return value
diff --git a/coding-deepgent/src/coding_deepgent/skills/tools.py b/coding-deepgent/src/coding_deepgent/skills/tools.py
new file mode 100644
index 000000000..a41c37439
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/skills/tools.py
@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from langchain.tools import ToolRuntime, tool
+
+from coding_deepgent.skills.loader import load_local_skill
+from coding_deepgent.skills.schemas import LoadSkillInput
+
+
+@tool(
+    "load_skill",
+    args_schema=LoadSkillInput,
+    description="Load a local coding-deepgent skill by name. Does not load extension, MCP, remote, or distributed skills.",
+)
+def load_skill(name: str, runtime: ToolRuntime) -> str:
+    """Load one local skill body after explicit model request."""
+
+    context = runtime.context
+    workdir = Path(getattr(context, "workdir", Path.cwd()))
+    skill_dir = Path(getattr(context, "skill_dir", "skills"))
+    return load_local_skill(workdir=workdir, skill_dir=skill_dir, name=name).render()
diff --git a/coding-deepgent/src/coding_deepgent/startup.py b/coding-deepgent/src/coding_deepgent/startup.py
new file mode 100644
index 000000000..b7ff76cbe
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/startup.py
@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from coding_deepgent.mcp.loader import MCPRuntimeLoadResult
+from coding_deepgent.plugins import PluginRegistry
+
+
+@dataclass(frozen=True, slots=True)
+class StartupContractStatus:
+    plugin_count: int
+    mcp_config_loaded: bool
+    mcp_adapter_available: bool
+
+
+def validate_startup_contract(
+    *,
+    validated_plugin_registry: PluginRegistry,
+    mcp_runtime_load_result: MCPRuntimeLoadResult,
+) -> StartupContractStatus:
+    return StartupContractStatus(
+        plugin_count=len(validated_plugin_registry.names()),
+        mcp_config_loaded=mcp_runtime_load_result.loaded_config is not None,
+        mcp_adapter_available=mcp_runtime_load_result.adapter_available,
+    )
+
+
+def require_startup_contract(
+    startup_contract: StartupContractStatus,
+) -> StartupContractStatus:
+    return startup_contract
diff --git a/coding-deepgent/src/coding_deepgent/subagents/__init__.py b/coding-deepgent/src/coding_deepgent/subagents/__init__.py
new file mode 100644
index 000000000..03dee5eb1
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/subagents/__init__.py
@@ -0,0 +1,23 @@
+from .schemas import RunSubagentInput, SubagentType, VerifierSubagentResult
+from .tools import (
+    DEFAULT_CHILD_TOOLS,
+    FORBIDDEN_CHILD_TOOLS,
+    VERIFIER_EXTRA_TOOLS,
+    SubagentResult,
+    child_tool_allowlist,
+    run_subagent,
+    run_subagent_task,
+)
+
+__all__ = [
+    "DEFAULT_CHILD_TOOLS",
+    "FORBIDDEN_CHILD_TOOLS",
+    "RunSubagentInput",
+    "SubagentResult",
+    "SubagentType",
+    "VerifierSubagentResult",
+    "VERIFIER_EXTRA_TOOLS",
+    "child_tool_allowlist",
+    "run_subagent",
+    "run_subagent_task",
+]
diff --git a/coding-deepgent/src/coding_deepgent/subagents/schemas.py b/coding-deepgent/src/coding_deepgent/subagents/schemas.py
new file mode 100644
index 000000000..8c6a9054f
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/subagents/schemas.py
@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from langchain.tools import ToolRuntime
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+SubagentType = Literal["general", "verifier"]
+
+
+class RunSubagentInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    task: str = Field(
+        ...,
+        min_length=1,
+        description="Single task for a synchronous stateless subagent.",
+    )
+    runtime: ToolRuntime
+    agent_type: SubagentType = Field(
+        default="general", description="Bounded local subagent type."
+    )
+    plan_id: str | None = Field(
+        default=None,
+        min_length=1,
+        description="Durable plan artifact id. Required for verifier subagents.",
+    )
+    max_turns: int = Field(
+        default=1,
+        ge=1,
+        le=1,
+        description="Stage 6-min supports exactly one synchronous turn.",
+    )
+
+    @field_validator("task")
+    @classmethod
+    def _task_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("task required")
+        return value
+
+    @model_validator(mode="after")
+    def _verifier_requires_plan(self) -> "RunSubagentInput":
+        if self.agent_type == "verifier" and self.plan_id is None:
+            raise ValueError("verifier subagents require plan_id")
+        return self
+
+
+class VerifierSubagentResult(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    agent_type: Literal["verifier"] = "verifier"
+    plan_id: str = Field(..., min_length=1)
+    plan_title: str = Field(..., min_length=1)
+    verification: str = Field(..., min_length=1)
+    task_ids: list[str] = Field(default_factory=list)
+    tool_allowlist: list[str] = Field(default_factory=list)
+    content: str = Field(..., min_length=1)
diff --git a/coding-deepgent/src/coding_deepgent/subagents/tools.py b/coding-deepgent/src/coding_deepgent/subagents/tools.py
new file mode 100644
index 000000000..e9d7bcd2e
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/subagents/tools.py
@@ -0,0 +1,398 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, replace
+from typing import Any, cast
+
+from langchain.agents import create_agent
+from langchain.tools import ToolRuntime, tool
+from langchain_core.tools import BaseTool
+
+from coding_deepgent.filesystem import glob_search, grep_search, read_file
+from coding_deepgent.rendering import latest_assistant_text
+from coding_deepgent.runtime import RuntimeContext, RuntimeInvocation
+from coding_deepgent.sessions.records import SessionContext
+from coding_deepgent.sessions.store_jsonl import JsonlSessionStore
+from coding_deepgent.settings import build_openai_model
+from coding_deepgent.subagents.schemas import (
+    RunSubagentInput,
+    SubagentType,
+    VerifierSubagentResult,
+)
+from coding_deepgent.tasks import plan_get, task_get, task_list
+from coding_deepgent.tasks.store import get_plan
+from coding_deepgent.tool_system import ToolCapability, ToolGuardMiddleware, build_capability_registry
+
+DEFAULT_CHILD_TOOLS = ("read_file", "glob", "grep")
+VERIFIER_EXTRA_TOOLS = ("task_get", "task_list", "plan_get")
+FORBIDDEN_CHILD_TOOLS = (
+    "bash",
+    "write_file",
+    "edit_file",
+    "TodoWrite",
+    "save_memory",
+    "task_create",
+    "task_update",
+    "plan_save",
+    "load_skill",
+    "run_subagent",
+)
+CHILD_TOOL_OBJECTS: dict[str, BaseTool] = {
+    "read_file": read_file,
+    "glob": glob_search,
+    "grep": grep_search,
+    "task_get": task_get,
+    "task_list": task_list,
+    "plan_get": plan_get,
+}
+VERDICT_PATTERN = re.compile(
+    r"^\s*VERDICT:\s*(PASS|FAIL|PARTIAL)\s*$",
+    flags=re.IGNORECASE | re.MULTILINE,
+)
+VERDICT_STATUS = {
+    "PASS": "passed",
+    "FAIL": "failed",
+    "PARTIAL": "partial",
+}
+
+
+def _child_tool_capability(name: str) -> ToolCapability:
+    tool_object = CHILD_TOOL_OBJECTS[name]
+    if name in {"task_get", "task_list", "plan_get"}:
+        return ToolCapability(
+            name=name,
+            tool=tool_object,
+            domain="task",
+            read_only=True,
+            destructive=False,
+            concurrency_safe=True,
+            family="task",
+            mutation="read",
+            execution="plain_tool",
+            tags=("read", "durable_store"),
+        )
+    return ToolCapability(
+        name=name,
+        tool=tool_object,
+        domain="filesystem",
+        read_only=True,
+        destructive=False,
+        concurrency_safe=True,
+        family="filesystem",
+        mutation="read",
+        execution="plain_tool",
+        exposure="child_only",
+        tags=("read", "workspace"),
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class SubagentResult:
+    content: str
+    agent_type: SubagentType
+    tool_allowlist: tuple[str, ...]
+    plan_id: str | None = None
+    plan_title: str | None = None
+    verification: str | None = None
+    task_ids: tuple[str, ...] = ()
+
+
+ChildAgentFactory = Callable[[SubagentType, Sequence[str]], Callable[[str], str]]
+
+
+def child_tool_allowlist(agent_type: SubagentType) -> tuple[str, ...]:
+    if agent_type == "verifier":
+        return (*DEFAULT_CHILD_TOOLS, *VERIFIER_EXTRA_TOOLS)
+    return DEFAULT_CHILD_TOOLS
+
+
+def _verifier_task_prompt(
+    *,
+    task: str,
+    plan_id: str,
+    plan_title: str,
+    content: str,
+    verification: str,
+    task_ids: Sequence[str],
+) -> str:
+    task_refs = ", ".join(task_ids) if task_ids else "(none)"
+    return "\n".join(
+        [
+            "Verifier task:",
+            task,
+            "",
+            f"Plan ID: {plan_id}",
+            f"Plan title: {plan_title}",
+            f"Verification criteria: {verification}",
+            f"Referenced task IDs: {task_refs}",
+            "",
+            "Plan content:",
+            content,
+        ]
+    )
+
+
+def _verifier_system_prompt(*, tool_allowlist: Sequence[str], context: RuntimeContext) -> str:
+    allowed_tools = ", ".join(tool_allowlist)
+    return "\n\n".join(
+        [
+            (
+                "You are a verification specialist. Your role is to verify the "
+                "implementation against the plan and try to find breakage, not to "
+                "confirm success quickly."
+            ),
+            (
+                "You are strictly read-only. Do not modify files, tasks, plans, "
+                "memory, or invoke nested subagents."
+            ),
+            (
+                "Use only the available tools when they materially improve the "
+                "verification result. Cite concrete evidence from commands or tool "
+                "reads in your final answer."
+            ),
+            f"Workspace: {context.workdir}",
+            f"Allowed tools: {allowed_tools}",
+            (
+                "End with a final line exactly `VERDICT: PASS`, `VERDICT: FAIL`, "
+                "or `VERDICT: PARTIAL`."
+            ),
+        ]
+    )
+
+
+def _verifier_runtime_invocation(
+    *,
+    runtime: ToolRuntime,
+    plan_id: str,
+) -> RuntimeInvocation:
+    context = getattr(runtime, "context", None)
+    if not isinstance(context, RuntimeContext):
+        raise RuntimeError("Verifier subagent requires runtime context")
+    parent_config = getattr(runtime, "config", None)
+    parent_thread_id = context.session_id
+    if isinstance(parent_config, dict):
+        configurable = parent_config.get("configurable", {})
+        if isinstance(configurable, dict):
+            parent_thread_id = str(configurable.get("thread_id", parent_thread_id))
+    return RuntimeInvocation(
+        context=replace(
+            context,
+            agent_name=f"{context.agent_name}-verifier",
+            entrypoint="run_subagent:verifier",
+        ),
+        config={"configurable": {"thread_id": f"{parent_thread_id}:verifier:{plan_id}"}},
+    )
+
+
+def _verifier_tools(tool_allowlist: Sequence[str]) -> list[BaseTool]:
+    return [CHILD_TOOL_OBJECTS[name] for name in tool_allowlist]
+
+
+def _verifier_middleware(tool_allowlist: Sequence[str]) -> list[ToolGuardMiddleware]:
+    registry = build_capability_registry(
+        builtin_capabilities=tuple(
+            _child_tool_capability(name) for name in tool_allowlist
+        ),
+        extension_capabilities=(),
+    )
+    return [ToolGuardMiddleware(registry=registry)]
+
+
+def _execute_verifier_subagent(
+    *,
+    task: str,
+    runtime: ToolRuntime,
+    plan_id: str,
+    tool_allowlist: Sequence[str],
+) -> str:
+    from coding_deepgent.agent_runtime_service import invoke_agent
+
+    invocation = _verifier_runtime_invocation(runtime=runtime, plan_id=plan_id)
+    agent = cast(
+        Any,
+        create_agent,
+    )(
+        model=build_openai_model(),
+        tools=_verifier_tools(tool_allowlist),
+        system_prompt=_verifier_system_prompt(
+            tool_allowlist=tool_allowlist,
+            context=invocation.context,
+        ),
+        middleware=_verifier_middleware(tool_allowlist),
+        context_schema=RuntimeContext,
+        store=runtime.store,
+        name=invocation.context.agent_name,
+    )
+    result = invoke_agent(
+        agent,
+        {"messages": [{"role": "user", "content": task}]},
+        invocation,
+    )
+    content = latest_assistant_text(result).strip()
+    if not content:
+        raise RuntimeError("Verifier subagent returned no assistant content")
+    return content
+
+
+def verifier_verdict(content: str) -> str | None:
+    match = VERDICT_PATTERN.search(content)
+    if match is None:
+        return None
+    return match.group(1).upper()
+
+
+def verifier_evidence_summary(content: str, *, verdict: str) -> str:
+    lines = [
+        line.strip()
+        for line in content.splitlines()
+        if line.strip() and not VERDICT_PATTERN.match(line)
+    ]
+    summary = lines[0] if lines else f"Verifier verdict: {verdict}"
+    if len(summary) <= 240:
+        return summary
+    return f"{summary[:237].rstrip()}..."
+
+
+def record_verifier_evidence(
+    *,
+    result: SubagentResult,
+    runtime: ToolRuntime,
+) -> bool:
+    if result.agent_type != "verifier":
+        return False
+    verdict = verifier_verdict(result.content)
+    if verdict is None:
+        return False
+    context = getattr(runtime, "context", None)
+    session_context = getattr(context, "session_context", None)
+    if not isinstance(session_context, SessionContext):
+        return False
+    parent_thread_id = _runtime_thread_id(runtime)
+    child_thread_id = (
+        f"{parent_thread_id}:verifier:{result.plan_id}"
+        if result.plan_id
+        else f"{parent_thread_id}:verifier"
+    )
+    verifier_agent_name = _runtime_agent_name(runtime)
+
+    JsonlSessionStore(session_context.store_dir).append_evidence(
+        session_context,
+        kind="verification",
+        summary=verifier_evidence_summary(result.content, verdict=verdict),
+        status=VERDICT_STATUS[verdict],
+        subject=result.plan_id,
+        metadata={
+            "plan_id": result.plan_id or "",
+            "plan_title": result.plan_title or "",
+            "verdict": verdict,
+            "parent_session_id": session_context.session_id,
+            "parent_thread_id": parent_thread_id,
+            "child_thread_id": child_thread_id,
+            "verifier_agent_name": verifier_agent_name,
+            "task_ids": list(result.task_ids),
+            "tool_allowlist": list(result.tool_allowlist),
+        },
+    )
+    return True
+
+
+def _runtime_thread_id(runtime: ToolRuntime) -> str:
+    context = getattr(runtime, "context", None)
+    fallback = str(getattr(context, "session_id", "unknown"))
+    config = getattr(runtime, "config", None)
+    if not isinstance(config, dict):
+        return fallback
+    configurable = config.get("configurable")
+    if not isinstance(configurable, dict):
+        return fallback
+    return str(configurable.get("thread_id", fallback))
+
+
+def _runtime_agent_name(runtime: ToolRuntime) -> str:
+    context = getattr(runtime, "context", None)
+    parent_agent_name = str(getattr(context, "agent_name", "coding-deepgent"))
+    return f"{parent_agent_name}-verifier"
+
+
+def run_subagent_task(
+    *,
+    task: str,
+    agent_type: SubagentType = "general",
+    runtime: ToolRuntime | None = None,
+    plan_id: str | None = None,
+    child_agent_factory: ChildAgentFactory | None = None,
+) -> SubagentResult:
+    allowlist = child_tool_allowlist(agent_type)
+    if agent_type == "verifier":
+        if runtime is None or runtime.store is None:
+            raise RuntimeError("Verifier subagent requires task store")
+        if plan_id is None:
+            raise ValueError("Verifier subagent requires plan_id")
+        plan = get_plan(runtime.store, plan_id)
+        verifier_task = _verifier_task_prompt(
+            task=task,
+            plan_id=plan.id,
+            plan_title=plan.title,
+            content=plan.content,
+            verification=plan.verification,
+            task_ids=plan.task_ids,
+        )
+        if child_agent_factory is None:
+            content = _execute_verifier_subagent(
+                task=verifier_task,
+                runtime=runtime,
+                plan_id=plan.id,
+                tool_allowlist=allowlist,
+            )
+        else:
+            content = child_agent_factory(agent_type, allowlist)(verifier_task)
+        return SubagentResult(
+            content=content,
+            agent_type=agent_type,
+            tool_allowlist=allowlist,
+            plan_id=plan.id,
+            plan_title=plan.title,
+            verification=plan.verification,
+            task_ids=tuple(plan.task_ids),
+        )
+    if child_agent_factory is None:
+        content = f"Subagent {agent_type} accepted task synchronously: {task}"
+    else:
+        content = child_agent_factory(agent_type, allowlist)(task)
+    return SubagentResult(
+        content=content, agent_type=agent_type, tool_allowlist=allowlist
+    )
+
+
+@tool(
+    "run_subagent",
+    args_schema=RunSubagentInput,
+    description="Run a minimal synchronous stateless local subagent with a fixed child-tool allowlist.",
+)
+def run_subagent(
+    task: str,
+    runtime: ToolRuntime,
+    agent_type: SubagentType = "general",
+    plan_id: str | None = None,
+    max_turns: int = 1,
+) -> str:
+    """Run one bounded synchronous subagent task."""
+    del max_turns
+    result = run_subagent_task(
+        task=task,
+        runtime=runtime,
+        agent_type=agent_type,
+        plan_id=plan_id,
+    )
+    if agent_type == "verifier":
+        record_verifier_evidence(result=result, runtime=runtime)
+        return VerifierSubagentResult(
+            plan_id=result.plan_id or "",
+            plan_title=result.plan_title or "",
+            verification=result.verification or "",
+            task_ids=list(result.task_ids),
+            tool_allowlist=list(result.tool_allowlist),
+            content=result.content,
+        ).model_dump_json()
+    return result.content
diff --git a/coding-deepgent/src/coding_deepgent/tasks/__init__.py b/coding-deepgent/src/coding_deepgent/tasks/__init__.py
new file mode 100644
index 000000000..2c870da83
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/tasks/__init__.py
@@ -0,0 +1,58 @@
+from .schemas import (
+    PlanArtifact,
+    PlanGetInput,
+    PlanSaveInput,
+    TaskCreateInput,
+    TaskGetInput,
+    TaskListInput,
+    TaskRecord,
+    TaskStatus,
+    TaskUpdateInput,
+)
+from .store import (
+    TASK_ROOT_NAMESPACE,
+    PLAN_ROOT_NAMESPACE,
+    create_plan,
+    create_task,
+    get_plan,
+    get_task,
+    is_task_ready,
+    list_tasks,
+    plan_namespace,
+    task_namespace,
+    task_graph_needs_verification,
+    update_task,
+    validate_task_graph,
+)
+from .tools import plan_get, plan_save, task_create, task_get, task_list, task_update
+
+__all__ = [
+    "PlanArtifact",
+    "PlanGetInput",
+    "PlanSaveInput",
+    "PLAN_ROOT_NAMESPACE",
+    "TASK_ROOT_NAMESPACE",
+    "TaskCreateInput",
+    "TaskGetInput",
+    "TaskListInput",
+    "TaskRecord",
+    "TaskStatus",
+    "TaskUpdateInput",
+    "create_plan",
+    "create_task",
+    "get_plan",
+    "get_task",
+    "is_task_ready",
+    "list_tasks",
+    "plan_get",
+    "plan_namespace",
+    "plan_save",
+    "task_create",
+    "task_get",
+    "task_list",
+    "task_namespace",
+    "task_graph_needs_verification",
+    "task_update",
+    "update_task",
+    "validate_task_graph",
+]
diff --git a/coding-deepgent/src/coding_deepgent/tasks/schemas.py b/coding-deepgent/src/coding_deepgent/tasks/schemas.py
new file mode 100644
index 000000000..546538c87
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/tasks/schemas.py
@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from langchain.tools import ToolRuntime
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+TaskStatus = Literal["pending", "in_progress", "blocked", "completed", "cancelled"]
+TERMINAL_TASK_STATUSES: frozenset[TaskStatus] = frozenset({"completed", "cancelled"})
+ALLOWED_TRANSITIONS: dict[TaskStatus, frozenset[TaskStatus]] = {
+    "pending": frozenset({"in_progress", "blocked", "cancelled"}),
+    "in_progress": frozenset({"blocked", "completed", "cancelled"}),
+    "blocked": frozenset({"pending", "in_progress", "cancelled"}),
+    "completed": frozenset(),
+    "cancelled": frozenset(),
+}
+
+
+class TaskRecord(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    title: str = Field(..., min_length=1)
+    description: str = ""
+    status: TaskStatus = "pending"
+    depends_on: list[str] = Field(default_factory=list)
+    owner: str | None = None
+    metadata: dict[str, str] = Field(default_factory=dict)
+
+    @field_validator("id", "title", "description", mode="before")
+    @classmethod
+    def _strip_text(cls, value: str) -> str:
+        return str(value).strip()
+
+    @field_validator("title")
+    @classmethod
+    def _title_must_not_be_blank(cls, value: str) -> str:
+        if not value:
+            raise ValueError("title required")
+        return value
+
+
+class TaskCreateInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    title: str = Field(..., min_length=1)
+    description: str = ""
+    depends_on: list[str] = Field(default_factory=list)
+    owner: str | None = None
+    metadata: dict[str, str] = Field(default_factory=dict)
+    runtime: ToolRuntime
+
+
+class TaskGetInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    task_id: str = Field(..., min_length=1)
+    runtime: ToolRuntime
+
+
+class TaskListInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    include_terminal: bool = False
+    runtime: ToolRuntime
+
+
+class TaskUpdateInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    task_id: str = Field(..., min_length=1)
+    status: TaskStatus | None = None
+    depends_on: list[str] | None = None
+    owner: str | None = None
+    metadata: dict[str, str] | None = None
+    runtime: ToolRuntime
+
+    @model_validator(mode="after")
+    def _has_update(self) -> "TaskUpdateInput":
+        if (
+            self.status is None
+            and self.depends_on is None
+            and self.owner is None
+            and self.metadata is None
+        ):
+            raise ValueError("at least one update field is required")
+        return self
+
+
+class PlanArtifact(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    title: str = Field(..., min_length=1)
+    content: str = Field(..., min_length=1)
+    verification: str = Field(..., min_length=1)
+    task_ids: list[str] = Field(default_factory=list)
+    metadata: dict[str, str] = Field(default_factory=dict)
+
+    @field_validator("id", "title", "content", "verification", mode="before")
+    @classmethod
+    def _strip_plan_text(cls, value: str) -> str:
+        return str(value).strip()
+
+
+class PlanSaveInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    title: str = Field(..., min_length=1)
+    content: str = Field(..., min_length=1)
+    verification: str = Field(..., min_length=1)
+    task_ids: list[str] = Field(default_factory=list)
+    metadata: dict[str, str] = Field(default_factory=dict)
+    runtime: ToolRuntime
+
+
+class PlanGetInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    plan_id: str = Field(..., min_length=1)
+    runtime: ToolRuntime
diff --git a/coding-deepgent/src/coding_deepgent/tasks/store.py b/coding-deepgent/src/coding_deepgent/tasks/store.py
new file mode 100644
index 000000000..616bfe431
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/tasks/store.py
@@ -0,0 +1,255 @@
+from __future__ import annotations
+
+from hashlib import sha256
+from typing import Iterable, Protocol
+
+from coding_deepgent.tasks.schemas import (
+    ALLOWED_TRANSITIONS,
+    PlanArtifact,
+    TERMINAL_TASK_STATUSES,
+    TaskRecord,
+    TaskStatus,
+)
+
+TASK_ROOT_NAMESPACE = "coding_deepgent_tasks"
+PLAN_ROOT_NAMESPACE = "coding_deepgent_plans"
+
+
+class TaskStore(Protocol):
+    def put(
+        self, namespace: tuple[str, ...], key: str, value: dict[str, object]
+    ) -> None: ...
+    def get(self, namespace: tuple[str, ...], key: str) -> object | None: ...
+    def search(self, namespace: tuple[str, ...]) -> Iterable[object]: ...
+
+
+def task_namespace() -> tuple[str, ...]:
+    return (TASK_ROOT_NAMESPACE,)
+
+
+def plan_namespace() -> tuple[str, ...]:
+    return (PLAN_ROOT_NAMESPACE,)
+
+
+def task_id_for(title: str, existing_count: int = 0) -> str:
+    digest = sha256(f"{title}\0{existing_count}".encode("utf-8")).hexdigest()
+    return f"task-{digest[:10]}"
+
+
+def plan_id_for(title: str, existing_count: int = 0) -> str:
+    digest = sha256(f"plan\0{title}\0{existing_count}".encode("utf-8")).hexdigest()
+    return f"plan-{digest[:10]}"
+
+
+def _item_value(item: object) -> dict[str, object]:
+    value = getattr(item, "value", item)
+    return value if isinstance(value, dict) else {}
+
+
+def list_tasks(store: TaskStore, *, include_terminal: bool = False) -> list[TaskRecord]:
+    records = [
+        TaskRecord.model_validate(_item_value(item))
+        for item in store.search(task_namespace())
+    ]
+    if not include_terminal:
+        records = [
+            record for record in records if record.status not in TERMINAL_TASK_STATUSES
+        ]
+    return sorted(records, key=lambda record: record.id)
+
+
+def get_task(store: TaskStore, task_id: str) -> TaskRecord:
+    item = store.get(task_namespace(), task_id)
+    if item is None:
+        raise KeyError(f"Unknown task: {task_id}")
+    return TaskRecord.model_validate(_item_value(item))
+
+
+def save_task(store: TaskStore, record: TaskRecord) -> TaskRecord:
+    store.put(task_namespace(), record.id, record.model_dump())
+    return record
+
+
+def save_plan(store: TaskStore, record: PlanArtifact) -> PlanArtifact:
+    store.put(plan_namespace(), record.id, record.model_dump())
+    return record
+
+
+def get_plan(store: TaskStore, plan_id: str) -> PlanArtifact:
+    item = store.get(plan_namespace(), plan_id)
+    if item is None:
+        raise KeyError(f"Unknown plan: {plan_id}")
+    return PlanArtifact.model_validate(_item_value(item))
+
+
+def create_plan(
+    store: TaskStore,
+    *,
+    title: str,
+    content: str,
+    verification: str,
+    task_ids: list[str] | None = None,
+    metadata: dict[str, str] | None = None,
+) -> PlanArtifact:
+    active_task_ids = task_ids or []
+    _validate_dependencies_exist(store, active_task_ids)
+    existing_count = sum(1 for _ in store.search(plan_namespace()))
+    return save_plan(
+        store,
+        PlanArtifact(
+            id=plan_id_for(title, existing_count),
+            title=title,
+            content=content,
+            verification=verification,
+            task_ids=active_task_ids,
+            metadata=metadata or {},
+        ),
+    )
+
+
+def create_task(
+    store: TaskStore,
+    *,
+    title: str,
+    description: str = "",
+    depends_on: list[str] | None = None,
+    owner: str | None = None,
+    metadata: dict[str, str] | None = None,
+) -> TaskRecord:
+    active_depends_on = depends_on or []
+    _validate_dependencies_exist(store, active_depends_on)
+    existing_count = len(list_tasks(store, include_terminal=True))
+    record = TaskRecord(
+        id=task_id_for(title, existing_count),
+        title=title,
+        description=description,
+        depends_on=active_depends_on,
+        owner=owner,
+        metadata=metadata or {},
+    )
+    return save_task(store, record)
+
+
+def update_task(
+    store: TaskStore,
+    *,
+    task_id: str,
+    status: TaskStatus | None = None,
+    depends_on: list[str] | None = None,
+    owner: str | None = None,
+    metadata: dict[str, str] | None = None,
+) -> TaskRecord:
+    record = get_task(store, task_id)
+    updates: dict[str, object] = {}
+    merged_metadata = record.metadata
+    if metadata is not None:
+        merged_metadata = {**record.metadata, **metadata}
+    active_depends_on = depends_on if depends_on is not None else record.depends_on
+
+    if status is not None:
+        if status not in ALLOWED_TRANSITIONS[record.status]:
+            raise ValueError(f"Invalid task transition: {record.status} -> {status}")
+        if status == "blocked" and not active_depends_on and not merged_metadata.get(
+            "blocked_reason"
+        ):
+            raise ValueError("blocked tasks require a dependency or blocked_reason")
+        updates["status"] = status
+    if depends_on is not None:
+        _validate_task_dependencies(store, task_id=task_id, depends_on=depends_on)
+        updates["depends_on"] = depends_on
+    if owner is not None:
+        updates["owner"] = owner
+    if metadata is not None:
+        updates["metadata"] = merged_metadata
+    return save_task(store, record.model_copy(update=updates))
+
+
+def is_task_ready(store: TaskStore, record: TaskRecord) -> bool:
+    if record.status != "pending":
+        return False
+    return all(
+        get_task(store, dependency).status == "completed"
+        for dependency in record.depends_on
+    )
+
+
+def task_graph_needs_verification(store: TaskStore) -> bool:
+    records = list_tasks(store, include_terminal=True)
+    actionable = [
+        record for record in records if record.status != "cancelled"
+    ]
+    if len(actionable) < 3:
+        return False
+    if any(record.status != "completed" for record in actionable):
+        return False
+    return not any(_is_verification_task(record) for record in actionable)
+
+
+def validate_task_graph(store: TaskStore) -> None:
+    records = list_tasks(store, include_terminal=True)
+    ids = {record.id for record in records}
+    for record in records:
+        if record.id in record.depends_on:
+            raise ValueError(f"Task {record.id} cannot depend on itself")
+        missing = [task_id for task_id in record.depends_on if task_id not in ids]
+        if missing:
+            raise ValueError(f"Task {record.id} has unknown dependencies: {missing}")
+    _detect_dependency_cycle(records)
+
+
+def _validate_dependencies_exist(store: TaskStore, depends_on: list[str]) -> None:
+    known = {record.id for record in list_tasks(store, include_terminal=True)}
+    missing = [task_id for task_id in depends_on if task_id not in known]
+    if missing:
+        raise ValueError(f"Unknown task dependencies: {missing}")
+
+
+def _validate_task_dependencies(
+    store: TaskStore,
+    *,
+    task_id: str,
+    depends_on: list[str],
+) -> None:
+    if task_id in depends_on:
+        raise ValueError(f"Task {task_id} cannot depend on itself")
+    _validate_dependencies_exist(store, depends_on)
+    records = list_tasks(store, include_terminal=True)
+    updated_records = [
+        record.model_copy(update={"depends_on": depends_on})
+        if record.id == task_id
+        else record
+        for record in records
+    ]
+    _detect_dependency_cycle(updated_records)
+
+
+def _detect_dependency_cycle(records: list[TaskRecord]) -> None:
+    graph = {record.id: set(record.depends_on) for record in records}
+    visiting: set[str] = set()
+    visited: set[str] = set()
+
+    def visit(task_id: str) -> None:
+        if task_id in visited:
+            return
+        if task_id in visiting:
+            raise ValueError(f"Task dependency cycle detected at {task_id}")
+        visiting.add(task_id)
+        for dependency in graph.get(task_id, set()):
+            visit(dependency)
+        visiting.remove(task_id)
+        visited.add(task_id)
+
+    for task_id in graph:
+        visit(task_id)
+
+
+def _is_verification_task(record: TaskRecord) -> bool:
+    text = " ".join(
+        [
+            record.title,
+            record.description,
+            record.metadata.get("type", ""),
+            record.metadata.get("role", ""),
+        ]
+    ).casefold()
+    return "verif" in text
diff --git a/coding-deepgent/src/coding_deepgent/tasks/tools.py b/coding-deepgent/src/coding_deepgent/tasks/tools.py
new file mode 100644
index 000000000..1b8a17f56
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/tasks/tools.py
@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+from langchain.tools import ToolRuntime, tool
+
+from coding_deepgent.tasks.schemas import (
+    PlanGetInput,
+    PlanSaveInput,
+    TaskCreateInput,
+    TaskGetInput,
+    TaskListInput,
+    TaskRecord,
+    TaskStatus,
+    TaskUpdateInput,
+)
+from coding_deepgent.tasks.store import (
+    create_plan,
+    create_task,
+    get_plan,
+    get_task,
+    is_task_ready,
+    list_tasks,
+    task_graph_needs_verification,
+    update_task,
+)
+
+
+def _store(runtime: ToolRuntime):
+    if runtime.store is None:
+        raise RuntimeError("Task store is not configured")
+    return runtime.store
+
+
+def _render(record: TaskRecord) -> str:
+    return record.model_dump_json()
+
+
+def _render_plan(record) -> str:
+    return record.model_dump_json()
+
+
+def _render_list_record(runtime: ToolRuntime, record: TaskRecord) -> str:
+    ready = str(is_task_ready(_store(runtime), record)).lower()
+    return _render(
+        record.model_copy(update={"metadata": {**record.metadata, "ready": ready}})
+    )
+
+
+@tool(
+    "task_create",
+    args_schema=TaskCreateInput,
+    description="Create a durable coding-deepgent task. This is not TodoWrite state.",
+)
+def task_create(
+    title: str,
+    runtime: ToolRuntime,
+    description: str = "",
+    depends_on: list[str] | None = None,
+    owner: str | None = None,
+    metadata: dict[str, str] | None = None,
+) -> str:
+    """Create one durable task record."""
+    return _render(
+        create_task(
+            _store(runtime),
+            title=title,
+            description=description,
+            depends_on=depends_on,
+            owner=owner,
+            metadata=metadata,
+        )
+    )
+
+
+@tool("task_get", args_schema=TaskGetInput, description="Get one durable task by id.")
+def task_get(task_id: str, runtime: ToolRuntime) -> str:
+    """Get a durable task by id."""
+    return _render(get_task(_store(runtime), task_id))
+
+
+@tool(
+    "task_list",
+    args_schema=TaskListInput,
+    description="List durable coding-deepgent tasks in deterministic id order.",
+)
+def task_list(runtime: ToolRuntime, include_terminal: bool = False) -> str:
+    """List durable tasks."""
+    return (
+        "\n".join(
+            _render_list_record(runtime, record)
+            for record in list_tasks(_store(runtime), include_terminal=include_terminal)
+        )
+        or "No tasks."
+    )
+
+
+@tool(
+    "task_update",
+    args_schema=TaskUpdateInput,
+    description="Update durable task status, owner, or metadata with transition validation.",
+)
+def task_update(
+    task_id: str,
+    runtime: ToolRuntime,
+    status: TaskStatus | None = None,
+    depends_on: list[str] | None = None,
+    owner: str | None = None,
+    metadata: dict[str, str] | None = None,
+) -> str:
+    """Update one durable task."""
+    store = _store(runtime)
+    updated = update_task(
+        store,
+        task_id=task_id,
+        status=status,
+        depends_on=depends_on,
+        owner=owner,
+        metadata=metadata,
+    )
+    if status == "completed" and task_graph_needs_verification(store):
+        return _render(
+            updated.model_copy(
+                update={
+                    "metadata": {
+                        **updated.metadata,
+                        "verification_nudge": "true",
+                    }
+                }
+            )
+        )
+    return _render(updated)
+
+
+@tool(
+    "plan_save",
+    args_schema=PlanSaveInput,
+    description="Save an explicit durable implementation plan artifact with verification criteria.",
+)
+def plan_save(
+    title: str,
+    content: str,
+    verification: str,
+    runtime: ToolRuntime,
+    task_ids: list[str] | None = None,
+    metadata: dict[str, str] | None = None,
+) -> str:
+    """Save one durable plan artifact."""
+    return _render_plan(
+        create_plan(
+            _store(runtime),
+            title=title,
+            content=content,
+            verification=verification,
+            task_ids=task_ids,
+            metadata=metadata,
+        )
+    )
+
+
+@tool("plan_get", args_schema=PlanGetInput, description="Get one durable plan artifact.")
+def plan_get(plan_id: str, runtime: ToolRuntime) -> str:
+    """Get a durable plan artifact by id."""
+    return _render_plan(get_plan(_store(runtime), plan_id))
diff --git a/coding-deepgent/src/coding_deepgent/todo/__init__.py b/coding-deepgent/src/coding_deepgent/todo/__init__.py
new file mode 100644
index 000000000..96fc2f39e
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/todo/__init__.py
@@ -0,0 +1,33 @@
+from .middleware import PlanContextMiddleware, TODO_WRITE_TOOL_NAME
+from .renderers import (
+    DEFAULT_PLAN_RENDERER,
+    PLAN_REMINDER_INTERVAL,
+    PlanRenderer,
+    TerminalPlanRenderer,
+    reminder_text,
+    render_plan_items,
+)
+from .schemas import TodoItemInput, TodoWriteInput
+from .service import build_todo_update, normalize_todos
+from .state import PlanningState, TodoItemState, default_session_state
+from .tools import _todo_write_command, todo_write
+
+__all__ = [
+    "DEFAULT_PLAN_RENDERER",
+    "PLAN_REMINDER_INTERVAL",
+    "PlanContextMiddleware",
+    "PlanRenderer",
+    "PlanningState",
+    "TODO_WRITE_TOOL_NAME",
+    "TerminalPlanRenderer",
+    "TodoItemInput",
+    "TodoItemState",
+    "TodoWriteInput",
+    "_todo_write_command",
+    "build_todo_update",
+    "default_session_state",
+    "normalize_todos",
+    "reminder_text",
+    "render_plan_items",
+    "todo_write",
+]
diff --git a/coding-deepgent/src/coding_deepgent/todo/middleware.py b/coding-deepgent/src/coding_deepgent/todo/middleware.py
new file mode 100644
index 000000000..daa0e5ba6
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/todo/middleware.py
@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, cast
+
+from langchain.agents.middleware import AgentMiddleware, ModelRequest, ModelResponse
+from langchain.messages import AIMessage, SystemMessage, ToolMessage
+from langchain.tools.tool_node import ToolCallRequest
+
+from coding_deepgent.context_payloads import (
+    ContextPayload,
+    merge_system_message_content,
+)
+from coding_deepgent.todo.renderers import reminder_text, render_plan_items
+from coding_deepgent.todo.state import PlanningState, TodoItemState
+
+TODO_WRITE_TOOL_NAME = "TodoWrite"
+
+
+class PlanContextMiddleware(AgentMiddleware[PlanningState]):
+    """Render todo state into the prompt and track stale-todo rounds."""
+
+    state_schema = PlanningState
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._updated_this_turn = False
+
+    def before_agent(self, state: PlanningState, runtime) -> dict[str, Any] | None:
+        self._updated_this_turn = False
+        return {
+            key: value
+            for key, value in (("todos", []), ("rounds_since_update", 0))
+            if key not in state
+        } or None
+
+    def wrap_tool_call(self, request: ToolCallRequest, handler: Callable):
+        if request.tool_call["name"] == TODO_WRITE_TOOL_NAME:
+            self._updated_this_turn = True
+        return handler(request)
+
+    def wrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], ModelResponse],
+    ) -> ModelResponse:
+        todos = cast(list[TodoItemState], request.state.get("todos", []))
+        rounds_since_update = cast(int, request.state.get("rounds_since_update", 0))
+        payloads: list[ContextPayload] = []
+
+        if todos:
+            payloads.append(
+                ContextPayload(
+                    kind="todo",
+                    source="todo.current",
+                    priority=100,
+                    text="Current session todos:\n" + render_plan_items(todos),
+                )
+            )
+            reminder = reminder_text(todos, rounds_since_update)
+            if reminder:
+                payloads.append(
+                    ContextPayload(
+                        kind="todo_reminder",
+                        source="todo.reminder",
+                        priority=110,
+                        text=reminder,
+                    )
+                )
+
+        if not payloads:
+            return handler(request)
+
+        current_blocks = (
+            request.system_message.content_blocks
+            if request.system_message is not None
+            else []
+        )
+        return handler(
+            request.override(
+                system_message=SystemMessage(
+                    content=merge_system_message_content(
+                        current_blocks, payloads
+                    )  # type: ignore[list-item]
+                )
+            )
+        )
+
+    def after_model(self, state: PlanningState, runtime) -> dict[str, Any] | None:
+        messages = state.get("messages", [])
+        if not messages:
+            return None
+
+        last_ai_message = next(
+            (
+                message
+                for message in reversed(messages)
+                if isinstance(message, AIMessage)
+            ),
+            None,
+        )
+        if last_ai_message is None or not last_ai_message.tool_calls:
+            return None
+
+        todo_write_calls = [
+            call
+            for call in last_ai_message.tool_calls
+            if call["name"] == TODO_WRITE_TOOL_NAME
+        ]
+        if len(todo_write_calls) <= 1:
+            return None
+
+        return {
+            "messages": [
+                ToolMessage(
+                    content=(
+                        "Error: The `TodoWrite` tool should never be called multiple times in "
+                        "parallel. Call it once per model response so the session todos have "
+                        "one unambiguous replacement."
+                    ),
+                    tool_call_id=call["id"],
+                    status="error",
+                )
+                for call in todo_write_calls
+            ]
+        }
+
+    def after_agent(self, state: PlanningState, runtime) -> dict[str, Any] | None:
+        if self._updated_this_turn:
+            return None
+        if state.get("todos"):
+            return {"rounds_since_update": state.get("rounds_since_update", 0) + 1}
+        return None
diff --git a/coding-deepgent/src/coding_deepgent/todo/renderers.py b/coding-deepgent/src/coding_deepgent/todo/renderers.py
new file mode 100644
index 000000000..1355ab05f
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/todo/renderers.py
@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from coding_deepgent.todo.state import TodoItemState
+
+PLAN_REMINDER_INTERVAL = 3
+
+
+class PlanRenderer(Protocol):
+    """Render planning state for a display surface."""
+
+    def render_plan_items(self, items: list[TodoItemState]) -> str:
+        """Return display text for the current session plan."""
+        ...
+
+    def reminder_text(
+        self,
+        items: list[TodoItemState],
+        rounds_since_update: int,
+    ) -> str | None:
+        """Return reminder text when the current plan is stale."""
+        ...
+
+
+@dataclass(frozen=True)
+class TerminalPlanRenderer:
+    """Terminal-compatible renderer for the TodoWrite planning display."""
+
+    reminder_interval: int = PLAN_REMINDER_INTERVAL
+
+    def render_plan_items(self, items: list[TodoItemState]) -> str:
+        if not items:
+            return "No session plan yet."
+
+        lines: list[str] = []
+        for item in items:
+            marker = {"pending": "[ ]", "in_progress": "[>]", "completed": "[x]"}[
+                item["status"]
+            ]
+            line = f"{marker} {item['content']}"
+            active_form = item.get("activeForm", "")
+            if item["status"] == "in_progress" and active_form:
+                line += f" ({active_form})"
+            lines.append(line)
+
+        completed = sum(1 for item in items if item["status"] == "completed")
+        lines.append(f"\n({completed}/{len(items)} completed)")
+        return "\n".join(lines)
+
+    def reminder_text(
+        self,
+        items: list[TodoItemState],
+        rounds_since_update: int,
+    ) -> str | None:
+        if not items or rounds_since_update < self.reminder_interval:
+            return None
+        return "<reminder>Refresh your current plan before continuing.</reminder>"
+
+
+DEFAULT_PLAN_RENDERER = TerminalPlanRenderer()
+
+
+def render_plan_items(
+    items: list[TodoItemState],
+    renderer: PlanRenderer = DEFAULT_PLAN_RENDERER,
+) -> str:
+    """Compatibility wrapper for the default planning renderer."""
+
+    return renderer.render_plan_items(items)
+
+
+def reminder_text(
+    items: list[TodoItemState],
+    rounds_since_update: int,
+    renderer: PlanRenderer = DEFAULT_PLAN_RENDERER,
+) -> str | None:
+    """Compatibility wrapper for the default planning reminder."""
+
+    return renderer.reminder_text(items, rounds_since_update)
diff --git a/coding-deepgent/src/coding_deepgent/todo/schemas.py b/coding-deepgent/src/coding_deepgent/todo/schemas.py
new file mode 100644
index 000000000..c8be43755
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/todo/schemas.py
@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from langchain.tools import InjectedToolCallId
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class TodoItemInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    content: str = Field(
+        ...,
+        min_length=1,
+        description="Imperative description of this todo item.",
+    )
+    status: Literal["pending", "in_progress", "completed"] = Field(
+        ...,
+        description="Current todo status. Exactly one item should be in_progress.",
+    )
+    activeForm: str = Field(
+        ...,
+        min_length=1,
+        description="Present-continuous form shown while this todo is active.",
+    )
+
+    @field_validator("content", "activeForm")
+    @classmethod
+    def _text_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("value required")
+        return value
+
+
+class TodoWriteInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    todos: list[TodoItemInput] = Field(
+        ...,
+        min_length=1,
+        max_length=12,
+        description=(
+            "Complete current todo list. Every todo must have content, status, "
+            "and activeForm; use pending, in_progress, or completed."
+        ),
+    )
+    tool_call_id: Annotated[str | None, InjectedToolCallId] = None
diff --git a/coding-deepgent/src/coding_deepgent/todo/service.py b/coding-deepgent/src/coding_deepgent/todo/service.py
new file mode 100644
index 000000000..01409b208
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/todo/service.py
@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+from langchain.messages import ToolMessage
+from langgraph.types import Command
+
+from coding_deepgent.todo.renderers import render_plan_items
+from coding_deepgent.todo.schemas import TodoItemInput, TodoWriteInput
+from coding_deepgent.todo.state import TodoItemState
+
+
+def normalize_todos(
+    todos: Sequence[TodoItemInput | Mapping[str, object]],
+) -> list[TodoItemState]:
+    if len(todos) > 12:
+        raise ValueError("Keep the todo list short (max 12 todos)")
+
+    validated = TodoWriteInput.model_validate({"todos": list(todos)})
+
+    normalized: list[TodoItemState] = []
+    in_progress_count = 0
+    for todo_input in validated.todos:
+        if todo_input.status == "in_progress":
+            in_progress_count += 1
+
+        normalized.append(
+            {
+                "content": todo_input.content,
+                "status": todo_input.status,
+                "activeForm": todo_input.activeForm,
+            }
+        )
+
+    if in_progress_count > 1:
+        raise ValueError("Only one todo item can be in_progress")
+
+    return normalized
+
+
+def build_todo_update(
+    todos: Sequence[TodoItemInput | Mapping[str, object]],
+    *,
+    tool_call_id: str | None = None,
+) -> Command:
+    if tool_call_id is None:
+        raise ValueError("tool_call_id is required for TodoWrite tool execution")
+
+    normalized = normalize_todos(todos)
+    rendered = render_plan_items(normalized)
+    return Command(
+        update={
+            "todos": normalized,
+            "rounds_since_update": 0,
+            "messages": [ToolMessage(content=rendered, tool_call_id=tool_call_id)],
+        }
+    )
diff --git a/coding-deepgent/src/coding_deepgent/todo/state.py b/coding-deepgent/src/coding_deepgent/todo/state.py
new file mode 100644
index 000000000..3daeeab59
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/todo/state.py
@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from langchain.agents import AgentState
+from typing_extensions import NotRequired, TypedDict
+
+
+class TodoItemState(TypedDict):
+    content: str
+    status: Literal["pending", "in_progress", "completed"]
+    activeForm: str
+
+
+class PlanningState(AgentState):
+    todos: NotRequired[list[TodoItemState]]
+    rounds_since_update: NotRequired[int]
+
+
+def default_session_state() -> dict[str, Any]:
+    return {
+        "todos": [],
+        "rounds_since_update": 0,
+    }
diff --git a/coding-deepgent/src/coding_deepgent/todo/tools.py b/coding-deepgent/src/coding_deepgent/todo/tools.py
new file mode 100644
index 000000000..615535e8e
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/todo/tools.py
@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+from langchain.tools import tool
+from langgraph.types import Command
+
+from coding_deepgent.todo.renderers import (
+    PLAN_REMINDER_INTERVAL,
+    reminder_text,
+    render_plan_items,
+)
+from coding_deepgent.todo.schemas import TodoItemInput, TodoWriteInput
+from coding_deepgent.todo.service import build_todo_update
+
+__all__ = [
+    "PLAN_REMINDER_INTERVAL",
+    "_todo_write_command",
+    "reminder_text",
+    "render_plan_items",
+    "todo_write",
+]
+
+
+def _todo_write_command(
+    todos: Sequence[TodoItemInput | Mapping[str, object]],
+    tool_call_id: str | None = None,
+) -> Command:
+    """Implementation helper for the TodoWrite tool."""
+
+    return build_todo_update(todos, tool_call_id=tool_call_id)
+
+
+@tool(
+    "TodoWrite",
+    args_schema=TodoWriteInput,
+    description=(
+        "Create or replace the current session todo list for complex multi-step work. Use this proactively "
+        "when explicit progress tracking helps; skip it for simple one-step or "
+        "purely conversational requests. Input must be the full current todo list in "
+        "todos[]. Every todo requires content, status, and activeForm. Do not call "
+        "TodoWrite multiple times in parallel within the same response."
+    ),
+)
+def todo_write(
+    todos: list[TodoItemInput],
+    tool_call_id: str | None = None,
+) -> Command:
+    """Create or replace the current session todo list for complex multi-step work."""
+
+    return _todo_write_command(todos, tool_call_id)
diff --git a/coding-deepgent/src/coding_deepgent/tool_system/__init__.py b/coding-deepgent/src/coding_deepgent/tool_system/__init__.py
new file mode 100644
index 000000000..cd9bd920f
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/tool_system/__init__.py
@@ -0,0 +1,21 @@
+from .capabilities import (
+    CapabilityRegistry,
+    ToolCapability,
+    build_builtin_capabilities,
+    build_capability_registry,
+    build_default_registry,
+)
+from .middleware import ToolGuardMiddleware
+from .policy import ToolPolicy, ToolPolicyCode, ToolPolicyDecision
+
+__all__ = [
+    "CapabilityRegistry",
+    "ToolCapability",
+    "build_builtin_capabilities",
+    "build_capability_registry",
+    "ToolGuardMiddleware",
+    "ToolPolicy",
+    "ToolPolicyCode",
+    "ToolPolicyDecision",
+    "build_default_registry",
+]
diff --git a/coding-deepgent/src/coding_deepgent/tool_system/capabilities.py b/coding-deepgent/src/coding_deepgent/tool_system/capabilities.py
new file mode 100644
index 000000000..19698b370
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/tool_system/capabilities.py
@@ -0,0 +1,409 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Iterable
+
+from langchain_core.tools import BaseTool
+
+from coding_deepgent.filesystem import (
+    bash,
+    edit_file,
+    glob_search,
+    grep_search,
+    read_file,
+    write_file,
+)
+from coding_deepgent.todo.tools import todo_write
+
+
+@dataclass(frozen=True)
+class ToolCapability:
+    name: str
+    tool: BaseTool
+    domain: str
+    read_only: bool
+    destructive: bool
+    concurrency_safe: bool
+    enabled: bool = True
+    source: str = "builtin"
+    trusted: bool = True
+    family: str = "unknown"
+    mutation: str = "unknown"
+    execution: str = "plain_tool"
+    exposure: str = "main"
+    tags: tuple[str, ...] = field(default_factory=tuple)
+
+
+class CapabilityRegistry:
+    def __init__(self, capabilities: Iterable[ToolCapability]):
+        ordered = list(capabilities)
+        self._capabilities = {capability.name: capability for capability in ordered}
+        if len(self._capabilities) != len(ordered):
+            raise ValueError("Tool capability names must be unique")
+
+    def names(self) -> list[str]:
+        return list(self._capabilities)
+
+    def get(self, name: str) -> ToolCapability | None:
+        return self._capabilities.get(name)
+
+    def require(self, name: str) -> ToolCapability:
+        capability = self.get(name)
+        if capability is None:
+            raise KeyError(f"Unknown tool capability: {name}")
+        return capability
+
+    def tools(self, *, enabled_only: bool = True) -> list[BaseTool]:
+        capabilities = [
+            capability
+            for capability in self._capabilities.values()
+            if not enabled_only or capability.enabled
+        ]
+        return [capability.tool for capability in capabilities]
+
+    def names_for_exposure(
+        self,
+        *exposures: str,
+        enabled_only: bool = True,
+    ) -> list[str]:
+        return [
+            capability.name
+            for capability in self._capabilities.values()
+            if (not enabled_only or capability.enabled)
+            and capability.exposure in exposures
+        ]
+
+    def tools_for_exposure(
+        self,
+        *exposures: str,
+        enabled_only: bool = True,
+    ) -> list[BaseTool]:
+        return [
+            capability.tool
+            for capability in self._capabilities.values()
+            if (not enabled_only or capability.enabled)
+            and capability.exposure in exposures
+        ]
+
+    def main_tools(self) -> list[BaseTool]:
+        return self.tools_for_exposure("main", "extension")
+
+    def main_names(self) -> list[str]:
+        return self.names_for_exposure("main", "extension")
+
+    def child_names(self) -> list[str]:
+        return self.names_for_exposure("child_only")
+
+    def declarable_names(self) -> list[str]:
+        return self.names_for_exposure("main", "extension")
+
+    def metadata(self) -> dict[str, ToolCapability]:
+        return dict(self._capabilities)
+
+
+def build_default_registry(*, include_discovery: bool = False) -> CapabilityRegistry:
+    capabilities = list(
+        build_builtin_capabilities(
+            filesystem_tools=(
+                bash,
+                read_file,
+                write_file,
+                edit_file,
+            ),
+            discovery_tools=((glob_search, grep_search) if include_discovery else ()),
+            todo_tools=(todo_write,),
+            memory_tools=(),
+            skill_tools=(),
+            task_tools=(),
+            subagent_tools=(),
+        )
+    )
+    return build_capability_registry(
+        builtin_capabilities=capabilities,
+        extension_capabilities=(),
+    )
+
+
+def build_capability_registry(
+    *,
+    builtin_capabilities: Sequence[ToolCapability],
+    extension_capabilities: Sequence[ToolCapability],
+) -> CapabilityRegistry:
+    return CapabilityRegistry([*builtin_capabilities, *extension_capabilities])
+
+
+def build_builtin_capabilities(
+    *,
+    filesystem_tools: Sequence[BaseTool],
+    discovery_tools: Sequence[BaseTool] = (),
+    todo_tools: Sequence[BaseTool],
+    memory_tools: Sequence[BaseTool],
+    skill_tools: Sequence[BaseTool],
+    task_tools: Sequence[BaseTool],
+    subagent_tools: Sequence[BaseTool],
+) -> tuple[ToolCapability, ...]:
+    ordered_tools = [
+        *filesystem_tools,
+        *discovery_tools,
+        *todo_tools,
+        *memory_tools,
+        *skill_tools,
+        *task_tools,
+        *subagent_tools,
+    ]
+    tool_by_name: dict[str, BaseTool] = {}
+    for tool in ordered_tools:
+        name = getattr(tool, "name", type(tool).__name__)
+        if name in tool_by_name:
+            raise ValueError(f"Duplicate builtin tool name: {name}")
+        tool_by_name[name] = tool
+    capabilities: list[ToolCapability] = [
+        ToolCapability(
+            name="bash",
+            tool=tool_by_name["bash"],
+            domain="filesystem",
+            read_only=False,
+            destructive=True,
+            concurrency_safe=False,
+            family="filesystem",
+            mutation="workspace_write",
+            execution="plain_tool",
+            tags=("shell", "workspace"),
+        ),
+        ToolCapability(
+            name="read_file",
+            tool=tool_by_name["read_file"],
+            domain="filesystem",
+            read_only=True,
+            destructive=False,
+            concurrency_safe=True,
+            family="filesystem",
+            mutation="read",
+            execution="plain_tool",
+            tags=("read", "workspace"),
+        ),
+        ToolCapability(
+            name="write_file",
+            tool=tool_by_name["write_file"],
+            domain="filesystem",
+            read_only=False,
+            destructive=True,
+            concurrency_safe=False,
+            family="filesystem",
+            mutation="workspace_write",
+            execution="plain_tool",
+            tags=("write", "workspace"),
+        ),
+        ToolCapability(
+            name="edit_file",
+            tool=tool_by_name["edit_file"],
+            domain="filesystem",
+            read_only=False,
+            destructive=True,
+            concurrency_safe=False,
+            family="filesystem",
+            mutation="workspace_write",
+            execution="plain_tool",
+            tags=("edit", "workspace"),
+        ),
+        ToolCapability(
+            name="TodoWrite",
+            tool=tool_by_name["TodoWrite"],
+            domain="todo",
+            read_only=False,
+            destructive=False,
+            concurrency_safe=False,
+            family="todo",
+            mutation="state_update",
+            execution="command_update",
+            tags=("state", "planning"),
+        ),
+    ]
+    if "glob" in tool_by_name:
+        capabilities.append(
+            ToolCapability(
+                name="glob",
+                tool=tool_by_name["glob"],
+                domain="filesystem",
+                read_only=True,
+                destructive=False,
+                concurrency_safe=True,
+                family="filesystem",
+                mutation="read",
+                execution="plain_tool",
+                exposure="child_only",
+                tags=("discovery", "workspace"),
+            )
+        )
+    if "grep" in tool_by_name:
+        capabilities.append(
+            ToolCapability(
+                name="grep",
+                tool=tool_by_name["grep"],
+                domain="filesystem",
+                read_only=True,
+                destructive=False,
+                concurrency_safe=True,
+                family="filesystem",
+                mutation="read",
+                execution="plain_tool",
+                exposure="child_only",
+                tags=("discovery", "workspace"),
+            )
+        )
+    if "save_memory" in tool_by_name:
+        capabilities.append(
+            ToolCapability(
+                name="save_memory",
+                tool=tool_by_name["save_memory"],
+                domain="memory",
+                family="memory",
+                mutation="durable_store",
+                execution="plain_tool",
+                read_only=False,
+                destructive=False,
+                concurrency_safe=False,
+                source="builtin",
+                trusted=True,
+                exposure="main",
+                tags=("memory",),
+            )
+        )
+    if "load_skill" in tool_by_name:
+        capabilities.append(
+            ToolCapability(
+                name="load_skill",
+                tool=tool_by_name["load_skill"],
+                domain="skills",
+                family="skills",
+                mutation="capability_load",
+                execution="local_loader",
+                read_only=True,
+                destructive=False,
+                concurrency_safe=True,
+                source="builtin",
+                trusted=True,
+                exposure="main",
+                tags=("skill",),
+            )
+        )
+    if "task_create" in tool_by_name:
+        capabilities.extend(
+            [
+                ToolCapability(
+                    name="task_create",
+                    tool=tool_by_name["task_create"],
+                    domain="tasks",
+                    family="tasks",
+                    mutation="durable_store",
+                    execution="plain_tool",
+                    read_only=False,
+                    destructive=False,
+                    concurrency_safe=False,
+                    source="builtin",
+                    trusted=True,
+                    exposure="main",
+                    tags=("task",),
+                ),
+                ToolCapability(
+                    name="task_get",
+                    tool=tool_by_name["task_get"],
+                    domain="tasks",
+                    family="tasks",
+                    mutation="read",
+                    execution="plain_tool",
+                    read_only=True,
+                    destructive=False,
+                    concurrency_safe=True,
+                    source="builtin",
+                    trusted=True,
+                    exposure="main",
+                    tags=("task", "read"),
+                ),
+                ToolCapability(
+                    name="task_list",
+                    tool=tool_by_name["task_list"],
+                    domain="tasks",
+                    family="tasks",
+                    mutation="read",
+                    execution="plain_tool",
+                    read_only=True,
+                    destructive=False,
+                    concurrency_safe=True,
+                    source="builtin",
+                    trusted=True,
+                    exposure="main",
+                    tags=("task", "read"),
+                ),
+                ToolCapability(
+                    name="task_update",
+                    tool=tool_by_name["task_update"],
+                    domain="tasks",
+                    family="tasks",
+                    mutation="durable_store",
+                    execution="plain_tool",
+                    read_only=False,
+                    destructive=False,
+                    concurrency_safe=False,
+                    source="builtin",
+                    trusted=True,
+                    exposure="main",
+                    tags=("task",),
+                ),
+            ]
+        )
+    if "plan_save" in tool_by_name:
+        capabilities.extend(
+            [
+                ToolCapability(
+                    name="plan_save",
+                    tool=tool_by_name["plan_save"],
+                    domain="tasks",
+                    family="plan",
+                    mutation="durable_store",
+                    execution="plain_tool",
+                    read_only=False,
+                    destructive=False,
+                    concurrency_safe=False,
+                    source="builtin",
+                    trusted=True,
+                    exposure="main",
+                    tags=("plan", "workflow"),
+                ),
+                ToolCapability(
+                    name="plan_get",
+                    tool=tool_by_name["plan_get"],
+                    domain="tasks",
+                    family="plan",
+                    mutation="read",
+                    execution="plain_tool",
+                    read_only=True,
+                    destructive=False,
+                    concurrency_safe=True,
+                    source="builtin",
+                    trusted=True,
+                    exposure="main",
+                    tags=("plan", "read", "workflow"),
+                ),
+            ]
+        )
+    if "run_subagent" in tool_by_name:
+        capabilities.append(
+            ToolCapability(
+                name="run_subagent",
+                tool=tool_by_name["run_subagent"],
+                domain="subagents",
+                family="subagents",
+                mutation="orchestration",
+                execution="child_agent_bridge",
+                read_only=False,
+                destructive=False,
+                concurrency_safe=False,
+                source="builtin",
+                trusted=True,
+                exposure="main",
+                tags=("subagent",),
+            )
+        )
+    return tuple(capabilities)
diff --git a/coding-deepgent/src/coding_deepgent/tool_system/middleware.py b/coding-deepgent/src/coding_deepgent/tool_system/middleware.py
new file mode 100644
index 000000000..2e6162347
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/tool_system/middleware.py
@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from langchain.agents.middleware import AgentMiddleware
+from langchain.messages import ToolMessage
+from langchain.tools.tool_node import ToolCallRequest
+from langgraph.types import Command
+
+from coding_deepgent.hooks.dispatcher import dispatch_context_hook
+from coding_deepgent.hooks.events import HookEventName
+from coding_deepgent.runtime import RuntimeEvent
+from coding_deepgent.sessions.evidence_events import append_runtime_event_evidence
+
+from .capabilities import CapabilityRegistry
+from .policy import ToolPolicy, ToolPolicyCode, ToolPolicyDecision
+
+
+class ToolGuardMiddleware(AgentMiddleware):
+    """Apply shared tool policy before execution and emit local event evidence."""
+
+    def __init__(
+        self,
+        *,
+        registry: CapabilityRegistry,
+        policy: ToolPolicy | None = None,
+        event_sink: object | None = None,
+    ) -> None:
+        super().__init__()
+        self.registry = registry
+        self.policy = policy or ToolPolicy(registry=registry)
+        self.event_sink = event_sink
+
+    def wrap_tool_call(
+        self,
+        request: ToolCallRequest,
+        handler: Callable[[ToolCallRequest], ToolMessage | Command[Any]],
+    ) -> ToolMessage | Command[Any]:
+        decision = self.policy.evaluate(request.tool_call)
+        tool_call_id = request.tool_call.get("id")
+
+        if not decision.allowed:
+            phase = (
+                "permission_ask"
+                if decision.code == ToolPolicyCode.PERMISSION_REQUIRED
+                else "permission_denied"
+            )
+            self._emit(request=request, phase=phase, decision=decision)
+            self._dispatch_hook(
+                request=request,
+                event="PermissionDenied",
+                data={
+                    "tool": str(request.tool_call["name"]),
+                    "policy_code": decision.code.value,
+                    "message": decision.message,
+                },
+            )
+            return ToolMessage(
+                content=decision.message,
+                tool_call_id=str(tool_call_id or ""),
+                status="error",
+            )
+
+        hook_outcome = self._dispatch_hook(
+            request=request,
+            event="PreToolUse",
+            data={
+                "tool": str(request.tool_call["name"]),
+                "args": dict(request.tool_call.get("args", {})),
+            },
+        )
+        if hook_outcome is not None and hook_outcome.blocked:
+            return ToolMessage(
+                content=hook_outcome.reason or "PreToolUse hook blocked execution.",
+                tool_call_id=str(tool_call_id or ""),
+                status="error",
+            )
+
+        self._emit(request=request, phase="allowed", decision=decision)
+        result = handler(request)
+        self._emit(
+            request=request,
+            phase="completed",
+            decision=decision,
+            result=result,
+        )
+        self._dispatch_hook(
+            request=request,
+            event="PostToolUse",
+            data={
+                "tool": str(request.tool_call["name"]),
+                "args": dict(request.tool_call.get("args", {})),
+                "result_type": type(result).__name__,
+            },
+        )
+        return result
+
+    def _emit(
+        self,
+        *,
+        request: ToolCallRequest,
+        phase: str,
+        decision: ToolPolicyDecision,
+        result: ToolMessage | Command[Any] | None = None,
+    ) -> None:
+        sink = self.event_sink or _runtime_event_sink(request.runtime)
+        if sink is None:
+            return
+
+        event: dict[str, object] = {
+            "source": "tool_guard",
+            "phase": phase,
+            "tool": str(request.tool_call["name"]),
+            "tool_call_id": request.tool_call.get("id"),
+            "policy_code": decision.code.value,
+            "permission_behavior": decision.behavior,
+            "result_type": type(result).__name__ if result is not None else None,
+        }
+        runtime_event = _send_event(sink, event, session_id=_session_id(request.runtime))
+        if runtime_event is not None:
+            append_runtime_event_evidence(
+                context=getattr(request.runtime, "context", None),
+                event=runtime_event,
+            )
+
+    def _dispatch_hook(
+        self,
+        *,
+        request: ToolCallRequest,
+        event: HookEventName,
+        data: dict[str, object],
+    ):
+        return dispatch_context_hook(
+            context=getattr(request.runtime, "context", None),
+            session_id=_session_id(request.runtime),
+            event=event,
+            data=data,
+        )
+
+
+def _runtime_event_sink(runtime: object) -> object | None:
+    context = getattr(runtime, "context", None)
+    if context is None:
+        return None
+
+    if isinstance(context, dict):
+        return context.get("event_sink")
+
+    return getattr(context, "event_sink", None)
+
+
+def _session_id(runtime: object) -> str:
+    context = getattr(runtime, "context", None)
+    if isinstance(context, dict):
+        return str(context.get("session_id", "unknown"))
+    return str(getattr(context, "session_id", "unknown"))
+
+
+def _send_event(
+    sink: object, event: dict[str, object], *, session_id: str
+) -> RuntimeEvent | None:
+    emit = getattr(sink, "emit", None)
+    if callable(emit):
+        runtime_event = RuntimeEvent(
+            kind=str(event["phase"]),
+            message=f"Tool guard {event['phase']} for {event['tool']}",
+            session_id=session_id,
+            metadata=event,
+        )
+        emit(runtime_event)
+        return runtime_event
+
+    if callable(sink):
+        sink(event)
+        return None
+
+    for method_name in ("record", "append"):
+        method = getattr(sink, method_name, None)
+        if callable(method):
+            method(event)
+            return None
+    return None
diff --git a/coding-deepgent/src/coding_deepgent/tool_system/policy.py b/coding-deepgent/src/coding_deepgent/tool_system/policy.py
new file mode 100644
index 000000000..229979e20
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/tool_system/policy.py
@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Mapping
+
+from coding_deepgent.permissions import (
+    PermissionCode,
+    PermissionManager,
+    ToolPermissionSubject,
+)
+
+from .capabilities import CapabilityRegistry
+
+
+class ToolPolicyCode(StrEnum):
+    ALLOWED = "allowed"
+    UNKNOWN_TOOL = "unknown_tool"
+    TOOL_DISABLED = "tool_disabled"
+    PERMISSION_REQUIRED = "permission_required"
+    PERMISSION_DENIED = "permission_denied"
+    DANGEROUS_COMMAND = "dangerous_command"
+    WORKSPACE_ESCAPE = "workspace_escape"
+
+
+_PERMISSION_CODE_MAP = {
+    PermissionCode.ALLOWED: ToolPolicyCode.ALLOWED,
+    PermissionCode.UNKNOWN_TOOL: ToolPolicyCode.UNKNOWN_TOOL,
+    PermissionCode.TOOL_DISABLED: ToolPolicyCode.TOOL_DISABLED,
+    PermissionCode.PERMISSION_REQUIRED: ToolPolicyCode.PERMISSION_REQUIRED,
+    PermissionCode.RULE_ASK: ToolPolicyCode.PERMISSION_REQUIRED,
+    PermissionCode.RULE_DENIED: ToolPolicyCode.PERMISSION_DENIED,
+    PermissionCode.PLAN_MODE_DENIED: ToolPolicyCode.PERMISSION_DENIED,
+    PermissionCode.DONT_ASK_DENIED: ToolPolicyCode.PERMISSION_DENIED,
+    PermissionCode.DANGEROUS_COMMAND: ToolPolicyCode.DANGEROUS_COMMAND,
+    PermissionCode.WORKSPACE_ESCAPE: ToolPolicyCode.WORKSPACE_ESCAPE,
+    PermissionCode.RULE_ALLOWED: ToolPolicyCode.ALLOWED,
+}
+
+
+@dataclass(frozen=True)
+class ToolPolicyDecision:
+    allowed: bool
+    code: ToolPolicyCode
+    message: str = ""
+    behavior: str = "allow"
+
+
+class ToolPolicy:
+    def __init__(
+        self,
+        *,
+        registry: CapabilityRegistry,
+        permission_manager: PermissionManager | None = None,
+    ) -> None:
+        self.registry = registry
+        self.permission_manager = permission_manager or PermissionManager()
+
+    def evaluate(self, tool_call: Mapping[str, object]) -> ToolPolicyDecision:
+        tool_name = str(tool_call.get("name", ""))
+        capability = self.registry.get(tool_name)
+        subject = (
+            ToolPermissionSubject(
+                name=capability.name,
+                read_only=capability.read_only,
+                destructive=capability.destructive,
+                enabled=capability.enabled,
+                domain=capability.domain,
+                source=capability.source,
+                trusted=capability.trusted,
+            )
+            if capability is not None
+            else None
+        )
+        decision = self.permission_manager.evaluate(
+            tool_call=tool_call, subject=subject
+        )
+        return ToolPolicyDecision(
+            allowed=decision.allowed,
+            code=_PERMISSION_CODE_MAP.get(
+                decision.code, ToolPolicyCode.PERMISSION_DENIED
+            ),
+            message=decision.message,
+            behavior=decision.behavior,
+        )
diff --git a/coding-deepgent/tests/conftest.py b/coding-deepgent/tests/conftest.py
new file mode 100644
index 000000000..1ccd61e3d
--- /dev/null
+++ b/coding-deepgent/tests/conftest.py
@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import os
+import socket
+import sys
+from pathlib import Path
+from typing import Any
+
+PROVIDER_ENV_VARS = (
+    "ANTHROPIC_AUTH_TOKEN",
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_BASE_URL",
+    "OPENAI_API_KEY",
+    "OPENAI_BASE_URL",
+)
+NETWORK_BLOCK_MESSAGE = (
+    "Network access is disabled during automated tests. "
+    "Stub the provider client instead of making live calls."
+)
+ORIGINAL_SOCKET_FUNCS: dict[str, Any] = {}
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+SRC_ROOT = PROJECT_ROOT / "src"
+
+if str(SRC_ROOT) not in sys.path:
+    sys.path.insert(0, str(SRC_ROOT))
+
+
+def _block_network(*args: Any, **kwargs: Any) -> None:
+    raise AssertionError(NETWORK_BLOCK_MESSAGE)
+
+
+def _block_socket_connect(self: socket.socket, *args: Any, **kwargs: Any) -> None:
+    raise AssertionError(NETWORK_BLOCK_MESSAGE)
+
+
+def pytest_configure(config: Any) -> None:
+    del config
+
+    for env_name in PROVIDER_ENV_VARS:
+        os.environ.pop(env_name, None)
+
+    ORIGINAL_SOCKET_FUNCS["create_connection"] = socket.create_connection
+    ORIGINAL_SOCKET_FUNCS["getaddrinfo"] = socket.getaddrinfo
+    ORIGINAL_SOCKET_FUNCS["connect"] = socket.socket.connect
+    ORIGINAL_SOCKET_FUNCS["connect_ex"] = socket.socket.connect_ex
+
+    socket.create_connection = _block_network  # type: ignore[assignment]
+    socket.getaddrinfo = _block_network  # type: ignore[assignment]
+    socket.socket.connect = _block_socket_connect  # type: ignore[assignment, method-assign]
+    socket.socket.connect_ex = _block_socket_connect  # type: ignore[assignment, method-assign]
+
+
+def pytest_unconfigure(config: Any) -> None:
+    del config
+
+    create_connection = ORIGINAL_SOCKET_FUNCS.get("create_connection")
+    getaddrinfo = ORIGINAL_SOCKET_FUNCS.get("getaddrinfo")
+    connect = ORIGINAL_SOCKET_FUNCS.get("connect")
+    connect_ex = ORIGINAL_SOCKET_FUNCS.get("connect_ex")
+
+    if create_connection is not None:
+        socket.create_connection = create_connection  # type: ignore[assignment]
+    if getaddrinfo is not None:
+        socket.getaddrinfo = getaddrinfo  # type: ignore[assignment]
+    if connect is not None:
+        socket.socket.connect = connect  # type: ignore[method-assign]
+    if connect_ex is not None:
+        socket.socket.connect_ex = connect_ex  # type: ignore[method-assign]
diff --git a/coding-deepgent/tests/test_app.py b/coding-deepgent/tests/test_app.py
new file mode 100644
index 000000000..e239f6fe9
--- /dev/null
+++ b/coding-deepgent/tests/test_app.py
@@ -0,0 +1,411 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Iterable, Sequence, cast
+
+from dependency_injector import providers
+from langchain_core.language_models.fake_chat_models import FakeMessagesListChatModel
+from langchain_core.messages import AIMessage
+from pydantic import PrivateAttr
+
+from coding_deepgent import app
+from coding_deepgent.containers import AppContainer
+from coding_deepgent.hooks import HookPayload, HookResult, LocalHookRegistry
+from coding_deepgent.memory import MemoryContextMiddleware
+from coding_deepgent.middleware import PlanContextMiddleware
+from coding_deepgent.runtime import (
+    InMemoryEventSink,
+    RuntimeContext,
+    RuntimeInvocation,
+    RuntimeState,
+)
+from coding_deepgent.sessions import SessionContext
+from coding_deepgent.settings import Settings
+from coding_deepgent.tool_system import ToolGuardMiddleware
+
+EXPECTED_TOOL_NAMES = [
+    "bash",
+    "read_file",
+    "write_file",
+    "edit_file",
+    "TodoWrite",
+    "save_memory",
+    "load_skill",
+    "task_create",
+    "task_get",
+    "task_list",
+    "task_update",
+    "plan_save",
+    "plan_get",
+    "run_subagent",
+]
+
+
+class RecordingFakeModel(FakeMessagesListChatModel):
+    _bound_tool_names: list[str] = PrivateAttr(default_factory=list)
+
+    def bind_tools(self, tools, *, tool_choice=None, **kwargs):
+        del tool_choice, kwargs
+        self._bound_tool_names = [
+            getattr(tool, "name", type(tool).__name__) for tool in tools
+        ]
+        return self
+
+
+class FakeAgent:
+    def __init__(self) -> None:
+        self.payloads: list[dict[str, Any]] = []
+
+    def invoke(self, payload: dict[str, Any]) -> dict[str, Any]:
+        self.payloads.append(payload)
+        return {
+            "messages": [
+                *payload["messages"],
+                {"role": "assistant", "content": "planned"},
+            ],
+            "todos": [
+                {
+                    "content": "Ship it",
+                    "status": "in_progress",
+                    "activeForm": "Shipping",
+                }
+            ],
+            "rounds_since_update": 0,
+        }
+
+
+def test_build_agent_binds_todowrite_product_tools(monkeypatch) -> None:
+    captured: dict[str, object] = {}
+
+    def fake_create_agent(**kwargs):
+        captured.update(kwargs)
+        return object()
+
+    monkeypatch.setattr(app, "build_openai_model", lambda: object())
+    monkeypatch.setattr(app, "create_agent", fake_create_agent)
+
+    agent = app.build_agent()
+
+    assert agent is not None
+    assert captured["state_schema"] is RuntimeState
+    middleware = cast(Sequence[object], captured["middleware"])
+    assert len(middleware) == 3
+    assert isinstance(middleware[0], PlanContextMiddleware)
+    assert isinstance(middleware[1], MemoryContextMiddleware)
+    assert isinstance(middleware[2], ToolGuardMiddleware)
+    tool_names = [
+        getattr(tool, "name", getattr(tool, "__name__", ""))
+        for tool in cast(Iterable[object], captured["tools"])
+    ]
+    assert tool_names == EXPECTED_TOOL_NAMES
+    system_prompt = str(captured["system_prompt"])
+    assert "explicit progress tracking helps on multi-step work" in system_prompt
+    assert "activeForm for every todo" in system_prompt
+    assert "write_plan" not in system_prompt
+
+
+def test_agent_loop_roundtrips_todo_state(monkeypatch) -> None:
+    fake = FakeAgent()
+    monkeypatch.setattr(app, "build_agent", lambda: fake)
+    session_state = {
+        "todos": [
+            {
+                "content": "Inspect",
+                "status": "completed",
+                "activeForm": "Inspecting",
+            }
+        ],
+        "rounds_since_update": 2,
+    }
+
+    history = [
+        {"role": "user", "content": "hello"},
+        {"role": "user", "content": "continue"},
+    ]
+
+    assert app.agent_loop(history, session_state=session_state) == "planned"
+    assert fake.payloads[0]["messages"] == [
+        {"role": "user", "content": "hello\n\ncontinue"}
+    ]
+    assert fake.payloads[0]["rounds_since_update"] == 2
+    assert fake.payloads[0]["todos"] == [
+        {"content": "Inspect", "status": "completed", "activeForm": "Inspecting"}
+    ]
+    assert history[-1] == {"role": "assistant", "content": "planned"}
+    assert session_state["todos"] == [
+        {"content": "Ship it", "status": "in_progress", "activeForm": "Shipping"}
+    ]
+
+
+def test_build_runtime_invocation_carries_session_context(tmp_path: Path) -> None:
+    session_context = SessionContext(
+        session_id="session-1",
+        workdir=tmp_path,
+        store_dir=tmp_path / "sessions",
+        transcript_path=tmp_path / "sessions" / "session-1.jsonl",
+        entrypoint="test",
+    )
+    container = AppContainer(
+        settings=providers.Object(Settings(workdir=tmp_path)),
+        model=providers.Object(object()),
+        create_agent_factory=providers.Object(lambda **kwargs: object()),
+    )
+
+    invocation = app.build_runtime_invocation(
+        container=container,
+        session_id="session-1",
+        session_context=session_context,
+    )
+
+    assert invocation.context.session_context is session_context
+    assert invocation.thread_id == "session-1"
+
+
+def test_agent_loop_threads_session_context_to_runtime_invocation(monkeypatch) -> None:
+    session_context = SessionContext(
+        session_id="session-1",
+        workdir=Path.cwd(),
+        store_dir=Path.cwd() / "sessions",
+        transcript_path=Path.cwd() / "sessions" / "session-1.jsonl",
+        entrypoint="test",
+    )
+    captured: dict[str, object] = {}
+    invocation = RuntimeInvocation(
+        context=RuntimeContext(
+            session_id="session-1",
+            workdir=Path.cwd(),
+            trusted_workdirs=(),
+            entrypoint="test",
+            agent_name="test-agent",
+            skill_dir=Path.cwd() / "skills",
+            event_sink=InMemoryEventSink(),
+            hook_registry=LocalHookRegistry(),
+            session_context=session_context,
+        ),
+        config={"configurable": {"thread_id": "session-1"}},
+    )
+
+    def build_runtime_invocation(**kwargs):
+        captured.update(kwargs)
+        return invocation
+
+    monkeypatch.setattr(app, "build_runtime_invocation", build_runtime_invocation)
+    monkeypatch.setattr(app, "build_agent", lambda **_: FakeAgent())
+
+    history = [{"role": "user", "content": "hello"}]
+    assert (
+        app.agent_loop(
+            history,
+            session_state={"todos": [], "rounds_since_update": 0},
+            session_id="session-1",
+            session_context=session_context,
+        )
+        == "planned"
+    )
+
+    assert captured["session_context"] is session_context
+
+
+def test_free_agent_path_executes_todowrite_without_runtime_injection_error(
+    monkeypatch,
+) -> None:
+    model = RecordingFakeModel(
+        responses=[
+            AIMessage(
+                content="",
+                tool_calls=[
+                    {
+                        "name": "TodoWrite",
+                        "args": {
+                            "todos": [
+                                {
+                                    "content": "Inspect repo",
+                                    "status": "in_progress",
+                                    "activeForm": "Inspecting",
+                                },
+                                {
+                                    "content": "Summarize findings",
+                                    "status": "pending",
+                                    "activeForm": "Summarizing",
+                                },
+                            ]
+                        },
+                        "id": "call_1",
+                        "type": "tool_call",
+                    }
+                ],
+            ),
+            AIMessage(content="planned"),
+        ]
+    )
+
+    monkeypatch.setattr(app, "build_openai_model", lambda: model)
+    session_state = {
+        "todos": [],
+        "rounds_since_update": 0,
+    }
+
+    history = [{"role": "user", "content": "plan this work"}]
+    assert app.agent_loop(history, session_state=session_state) == "planned"
+    assert model._bound_tool_names == EXPECTED_TOOL_NAMES
+    assert session_state["todos"] == [
+        {
+            "content": "Inspect repo",
+            "status": "in_progress",
+            "activeForm": "Inspecting",
+        },
+        {
+            "content": "Summarize findings",
+            "status": "pending",
+            "activeForm": "Summarizing",
+        },
+    ]
+
+
+def test_agent_loop_user_prompt_submit_hook_can_block_before_agent(monkeypatch) -> None:
+    registry = LocalHookRegistry()
+
+    def block_user_prompt(_payload: HookPayload) -> HookResult:
+        return HookResult.model_validate(
+            {"continue": False, "decision": "block", "reason": "hook blocked"}
+        )
+
+    registry.register("UserPromptSubmit", block_user_prompt)
+    sink = InMemoryEventSink()
+    invocation = RuntimeInvocation(
+        context=RuntimeContext(
+            session_id="session-1",
+            workdir=Path.cwd(),
+            trusted_workdirs=(),
+            entrypoint="test",
+            agent_name="test-agent",
+            skill_dir=Path.cwd() / "skills",
+            event_sink=sink,
+            hook_registry=registry,
+        ),
+        config={"configurable": {"thread_id": "session-1"}},
+    )
+    called: list[str] = []
+
+    monkeypatch.setattr(app, "build_runtime_invocation", lambda **_: invocation)
+
+    def build_blocked_agent(**_kwargs):
+        called.append("agent")
+        return FakeAgent()
+
+    monkeypatch.setattr(app, "build_agent", build_blocked_agent)
+
+    history = [{"role": "user", "content": "hello"}]
+    assert (
+        app.agent_loop(
+            history,
+            session_state={"todos": [], "rounds_since_update": 0},
+            session_id="session-1",
+        )
+        == "hook blocked"
+    )
+    assert called == []
+    assert history[-1] == {"role": "assistant", "content": "hook blocked"}
+    assert [event.kind for event in sink.snapshot()] == [
+        "hook_start",
+        "hook_blocked",
+    ]
+
+
+def test_agent_loop_session_start_hook_runs_on_new_session_only(monkeypatch) -> None:
+    registry = LocalHookRegistry()
+    seen: list[str] = []
+
+    def on_session_start(payload: HookPayload) -> HookResult:
+        seen.append(str(payload.data["session_id"]))
+        return HookResult()
+
+    registry.register("SessionStart", on_session_start)
+    sink = InMemoryEventSink()
+    invocation = RuntimeInvocation(
+        context=RuntimeContext(
+            session_id="session-1",
+            workdir=Path.cwd(),
+            trusted_workdirs=(),
+            entrypoint="test",
+            agent_name="test-agent",
+            skill_dir=Path.cwd() / "skills",
+            event_sink=sink,
+            hook_registry=registry,
+        ),
+        config={"configurable": {"thread_id": "session-1"}},
+    )
+
+    monkeypatch.setattr(app, "build_runtime_invocation", lambda **_: invocation)
+    monkeypatch.setattr(app, "build_agent", lambda **_: FakeAgent())
+
+    fresh_history = [{"role": "user", "content": "hello"}]
+    assert (
+        app.agent_loop(
+            fresh_history,
+            session_state={"todos": [], "rounds_since_update": 0},
+            session_id="session-1",
+        )
+        == "planned"
+    )
+    assert seen == ["session-1"]
+
+    seen.clear()
+    resumed_history = [
+        {
+            "role": "system",
+            "content": (
+                "Resumed session context. Use this brief as continuation context, "
+                "not as a new user request.\n\nSession: session-1"
+            ),
+        },
+        {"role": "user", "content": "hello"},
+        {"role": "assistant", "content": "planned"},
+        {"role": "user", "content": "continue"},
+    ]
+    assert (
+        app.agent_loop(
+            resumed_history,
+            session_state={"todos": [], "rounds_since_update": 1},
+            session_id="session-1",
+        )
+        == "planned"
+    )
+    assert seen == []
+
+
+def test_agent_loop_session_start_hook_is_observation_only(monkeypatch) -> None:
+    registry = LocalHookRegistry()
+    registry.register(
+        "SessionStart",
+        lambda _payload: HookResult.model_validate(
+            {"continue": False, "decision": "block", "reason": "ignored"}
+        ),
+    )
+    sink = InMemoryEventSink()
+    invocation = RuntimeInvocation(
+        context=RuntimeContext(
+            session_id="session-1",
+            workdir=Path.cwd(),
+            trusted_workdirs=(),
+            entrypoint="test",
+            agent_name="test-agent",
+            skill_dir=Path.cwd() / "skills",
+            event_sink=sink,
+            hook_registry=registry,
+        ),
+        config={"configurable": {"thread_id": "session-1"}},
+    )
+
+    monkeypatch.setattr(app, "build_runtime_invocation", lambda **_: invocation)
+    monkeypatch.setattr(app, "build_agent", lambda **_: FakeAgent())
+
+    history = [{"role": "user", "content": "hello"}]
+    assert (
+        app.agent_loop(
+            history,
+            session_state={"todos": [], "rounds_since_update": 0},
+            session_id="session-1",
+        )
+        == "planned"
+    )
diff --git a/coding-deepgent/tests/test_architecture_reshape.py b/coding-deepgent/tests/test_architecture_reshape.py
new file mode 100644
index 000000000..fe718ec96
--- /dev/null
+++ b/coding-deepgent/tests/test_architecture_reshape.py
@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SRC = ROOT / "src" / "coding_deepgent"
+
+
+def _text(path: str) -> str:
+    return (SRC / path).read_text(encoding="utf-8")
+
+
+def test_domain_and_service_modules_do_not_import_cli() -> None:
+    checked = [
+        *sorted((SRC / "filesystem").glob("*.py")),
+        *sorted((SRC / "hooks").glob("*.py")),
+        *sorted((SRC / "sessions").glob("*.py")),
+        *sorted((SRC / "mcp").glob("*.py")),
+        *sorted((SRC / "plugins").glob("*.py")),
+        *sorted((SRC / "permissions").glob("*.py")),
+        *sorted((SRC / "skills").glob("*.py")),
+        *sorted((SRC / "tasks").glob("*.py")),
+        *sorted((SRC / "todo").glob("*.py")),
+        SRC / "extensions_service.py",
+        SRC / "startup.py",
+    ]
+    offenders = [
+        str(path.relative_to(ROOT))
+        for path in checked
+        if "coding_deepgent.cli" in path.read_text(encoding="utf-8")
+    ]
+    assert offenders == []
+
+
+def test_app_uses_shared_agent_loop_service_and_not_direct_hook_or_runtime_logic() -> None:
+    text = _text("app.py")
+    public_surface_text = _text("__init__.py")
+
+    assert "from coding_deepgent import agent_loop_service" in text
+    assert "dispatch_runtime_hook" not in text
+    assert "normalize_messages" not in text
+    assert "latest_assistant_text" not in text
+    assert "agent_loop_service.run_agent_loop(" in text
+    assert "SESSION_STATE" not in text
+    assert "SESSION_STATE" not in public_surface_text
+
+
+def test_tool_middleware_uses_shared_hook_dispatcher() -> None:
+    text = _text("tool_system/middleware.py")
+
+    assert "dispatch_context_hook" in text
+    assert "HookPayload(" not in text
+    assert '"hook_start"' not in text
+
+
+def test_startup_contract_is_explicit() -> None:
+    bootstrap_text = _text("bootstrap.py")
+    app_text = _text("app.py")
+    startup_text = _text("startup.py")
+    container_text = _text("containers/app.py")
+    agent_service_text = _text("agent_service.py")
+    agent_provider_block = container_text.split("agent: Any = providers.Factory(", 1)[1]
+
+    assert "def validate_container_startup" in bootstrap_text
+    assert "validate_container_startup(container=container)" in app_text
+    assert "validate_startup_contract" in startup_text
+    assert "require_startup_contract" in startup_text
+    assert "create_compiled_agent_after_startup_validation" in agent_provider_block
+    assert "startup_contract=validated_startup_contract" in agent_provider_block
+    assert "validated_plugin_registry=validated_plugin_registry" not in agent_provider_block
+    assert "create_compiled_agent_after_startup_validation" in agent_service_text
+
+
+def test_filesystem_execution_primary_path_is_runtime_aware() -> None:
+    tools_text = _text("filesystem/tools.py")
+    discovery_text = _text("filesystem/discovery.py")
+    service_text = _text("filesystem/service.py")
+    policy_text = _text("filesystem/policy.py")
+
+    assert "ToolRuntime" in tools_text
+    assert "ToolRuntime" in discovery_text
+    assert "runtime_from_context(" in tools_text
+    assert "runtime_from_context(" in discovery_text
+    assert "safe_path(" not in tools_text
+    assert "safe_path(" not in discovery_text
+    assert "FilesystemRuntime" in service_text
+    assert "load_settings" not in policy_text
+    assert "Path.cwd()" not in policy_text
+
+
+def test_cli_module_stays_a_thin_entrypoint() -> None:
+    cli_text = _text("cli.py")
+
+    assert "CliRuntime =" not in cli_text
+    assert "SessionSummary =" not in cli_text
+    assert "DoctorCheck =" not in cli_text
diff --git a/coding-deepgent/tests/test_cli.py b/coding-deepgent/tests/test_cli.py
new file mode 100644
index 000000000..c912a0135
--- /dev/null
+++ b/coding-deepgent/tests/test_cli.py
@@ -0,0 +1,840 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from typer.testing import CliRunner
+
+from coding_deepgent import cli
+from coding_deepgent import cli_service
+from coding_deepgent.compact import COMPACT_BOUNDARY_PREFIX, COMPACT_SUMMARY_PREFIX
+from coding_deepgent.sessions import JsonlSessionStore
+from coding_deepgent.settings import Settings, load_settings
+
+runner = CliRunner()
+
+
+class FakeCompactSummarizer:
+    def __init__(self, response: str) -> None:
+        self.response = response
+        self.requests: list[list[dict[str, object]]] = []
+
+    def invoke(self, messages: list[dict[str, object]]) -> str:
+        self.requests.append(messages)
+        return self.response
+
+
+def _loaded_session(tmp_path: Path, session_id: str = "session-1"):
+    store = JsonlSessionStore(tmp_path / "sessions-store")
+    workdir = tmp_path / "workdir"
+    workdir.mkdir()
+    context = store.create_session(workdir=workdir, session_id=session_id)
+    store.append_message(context, role="assistant", content="existing")
+    store.append_state_snapshot(
+        context,
+        state={
+            "todos": [
+                {
+                    "content": "Continue work",
+                    "status": "in_progress",
+                    "activeForm": "Continuing",
+                }
+            ],
+            "rounds_since_update": 1,
+        },
+    )
+    store.append_evidence(
+        context,
+        kind="verification",
+        summary="pytest passed",
+        status="passed",
+    )
+    return store.load_session(session_id=session_id, workdir=workdir)
+
+
+def test_main_runs_one_integrated_prompt(monkeypatch, capsys) -> None:
+    captured: dict[str, object] = {}
+
+    def fake_run_once(
+        prompt: str,
+        history=None,
+        session_state=None,
+        session_id=None,
+    ) -> str:
+        captured["prompt"] = prompt
+        captured["history"] = history
+        captured["session_state"] = session_state
+        captured["session_id"] = session_id
+        return "done"
+
+    monkeypatch.setattr(cli, "run_once", fake_run_once)
+    monkeypatch.setattr(
+        cli,
+        "build_cli_runtime",
+        lambda: cli_service.CliRuntime(
+            settings_loader=load_settings,
+            list_sessions=lambda: [],
+            load_session=lambda session_id: _loaded_session(Path("/tmp"), session_id),
+            run_prompt=fake_run_once,
+            doctor_checks=lambda: [],
+        ),
+    )
+
+    assert cli.main(["--prompt", "continue"]) == 0
+    output = capsys.readouterr().out.strip()
+
+    assert captured == {
+        "prompt": "continue",
+        "history": None,
+        "session_state": None,
+        "session_id": None,
+    }
+    assert output == "done"
+
+
+def test_help_lists_runtime_foundation_commands() -> None:
+    result = runner.invoke(cli.app, ["--help"])
+
+    assert result.exit_code == 0
+    assert "run" in result.stdout
+    assert "sessions" in result.stdout
+    assert "config" in result.stdout
+    assert "doctor" in result.stdout
+
+
+def test_config_show_redacts_api_key(monkeypatch) -> None:
+    monkeypatch.setenv("OPENAI_API_KEY", "sk-super-secret")
+    monkeypatch.setenv("OPENAI_BASE_URL", "https://example.invalid/v1")
+
+    result = runner.invoke(cli.app, ["config", "show"])
+
+    assert result.exit_code == 0
+    assert "Configuration" in result.stdout
+    assert "openai_api_key" in result.stdout
+    assert "<set>" in result.stdout
+    assert "sk-super-secret" not in result.stdout
+    assert "https://example.invalid/v1" in result.stdout
+
+
+def _empty_history(session_id: str):
+    return _loaded_session(Path("/tmp/empty-history"), session_id)
+
+
+def _unused_run_prompt(
+    prompt: str, history=None, session_state=None, session_id=None
+) -> str:
+    del prompt, history, session_state, session_id
+    return "unused"
+
+
+def test_sessions_list_uses_runtime_provider(monkeypatch) -> None:
+    runtime = cli_service.CliRuntime(
+        settings_loader=lambda: Settings(
+            workdir=Path("/tmp/work"), model_name="gpt-test"
+        ),
+        list_sessions=lambda: [
+            cli_service.SessionSummaryView(
+                session_id="session-1",
+                updated_at="2026-04-13T00:00:00Z",
+                message_count=4,
+                workdir="/tmp/work",
+            )
+        ],
+        load_session=_empty_history,
+        run_prompt=_unused_run_prompt,
+        doctor_checks=lambda: [],
+    )
+    monkeypatch.setattr(cli, "build_cli_runtime", lambda: runtime)
+
+    result = runner.invoke(cli.app, ["sessions", "list"])
+
+    assert result.exit_code == 0
+    assert "session-1" in result.stdout
+    assert "2026-04-13T00:00:00Z" in result.stdout
+    assert "/tmp/work" in result.stdout
+
+
+def test_sessions_resume_uses_recovery_brief_continuation_history(
+    monkeypatch, tmp_path: Path
+) -> None:
+    captured: dict[str, object] = {}
+    loaded = _loaded_session(tmp_path)
+
+    def fake_run_prompt(
+        prompt: str,
+        history=None,
+        session_state=None,
+        session_id=None,
+    ) -> str:
+        captured["prompt"] = prompt
+        captured["history"] = history
+        captured["session_state"] = session_state
+        captured["session_id"] = session_id
+        return "resumed"
+
+    runtime = cli_service.CliRuntime(
+        settings_loader=load_settings,
+        list_sessions=lambda: [],
+        load_session=lambda session_id: loaded,
+        run_prompt=fake_run_prompt,
+        doctor_checks=lambda: [],
+    )
+    monkeypatch.setattr(cli, "build_cli_runtime", lambda: runtime)
+
+    result = runner.invoke(
+        cli.app, ["sessions", "resume", "session-1", "--prompt", "continue"]
+    )
+
+    assert result.exit_code == 0
+    assert captured == {
+        "prompt": "continue",
+        "history": [
+            {
+                "role": "system",
+                "content": (
+                    "Resumed session context. Use this brief as continuation "
+                    "context, not as a new user request.\n\n"
+                    "Session: session-1\n"
+                    "Messages: 1\n"
+                    "Updated: "
+                    f"{loaded.summary.updated_at}\n"
+                    "Active todos:\n"
+                    "- Continue work\n"
+                    "Recent evidence:\n"
+                    "- [passed] verification: pytest passed\n"
+                    "Recent compacts:\n"
+                    "- none"
+                ),
+            },
+            {"role": "assistant", "content": "existing"},
+        ],
+        "session_state": {
+            "todos": [
+                {
+                    "content": "Continue work",
+                    "status": "in_progress",
+                    "activeForm": "Continuing",
+                }
+            ],
+            "rounds_since_update": 1,
+        },
+        "session_id": "session-1",
+    }
+    assert "resumed" in result.stdout
+
+
+def test_sessions_resume_defaults_to_latest_compacted_continuation_when_available(
+    monkeypatch, tmp_path: Path
+) -> None:
+    captured: dict[str, object] = {}
+    store = JsonlSessionStore(tmp_path / "sessions-store")
+    workdir = tmp_path / "workdir"
+    workdir.mkdir()
+    context = store.create_session(workdir=workdir, session_id="session-1")
+    store.append_message(context, role="user", content="first", message_index=0)
+    store.append_message(context, role="assistant", content="done", message_index=1)
+    store.append_compact(
+        context,
+        trigger="manual",
+        summary="Earlier work was summarized.",
+        original_message_count=2,
+        summarized_message_count=1,
+        kept_message_count=1,
+    )
+    store.append_message(context, role="user", content="after compact", message_index=2)
+    store.append_message(
+        context, role="assistant", content="after compact answer", message_index=3
+    )
+    store.append_state_snapshot(
+        context,
+        state={"todos": [], "rounds_since_update": 0},
+    )
+    loaded = store.load_session(session_id="session-1", workdir=workdir)
+
+    def fake_run_prompt(
+        prompt: str,
+        history=None,
+        session_state=None,
+        session_id=None,
+    ) -> str:
+        captured["prompt"] = prompt
+        captured["history"] = history
+        captured["session_state"] = session_state
+        captured["session_id"] = session_id
+        return "resumed"
+
+    runtime = cli_service.CliRuntime(
+        settings_loader=load_settings,
+        list_sessions=lambda: [],
+        load_session=lambda session_id: loaded,
+        run_prompt=fake_run_prompt,
+        doctor_checks=lambda: [],
+    )
+    monkeypatch.setattr(cli, "build_cli_runtime", lambda: runtime)
+
+    result = runner.invoke(
+        cli.app, ["sessions", "resume", "session-1", "--prompt", "continue"]
+    )
+
+    assert result.exit_code == 0
+    history = captured["history"]
+    assert isinstance(history, list)
+    assert history[0]["role"] == "system"
+    assert "Resumed session context" in str(history[0]["content"])
+    assert history[1]["role"] == "system"
+    assert COMPACT_BOUNDARY_PREFIX in str(history[1]["content"])
+    assert history[2]["role"] == "user"
+    assert COMPACT_SUMMARY_PREFIX in str(history[2]["content"])
+    assert "Earlier work was summarized." in str(history[2]["content"])
+    assert history[3] == {"role": "assistant", "content": "done"}
+    assert history[4] == {"role": "user", "content": "after compact"}
+    assert history[5] == {"role": "assistant", "content": "after compact answer"}
+    assert captured["session_id"] == "session-1"
+    assert "resumed" in result.stdout
+
+
+def test_selected_continuation_history_uses_loaded_compacted_history(
+    tmp_path: Path,
+) -> None:
+    store = JsonlSessionStore(tmp_path / "sessions-store")
+    workdir = tmp_path / "workdir"
+    workdir.mkdir()
+    context = store.create_session(workdir=workdir, session_id="session-1")
+    store.append_message(context, role="user", content="first", message_index=0)
+    store.append_message(context, role="assistant", content="done", message_index=1)
+    store.append_compact(
+        context,
+        trigger="manual",
+        summary="Earlier work was summarized.",
+        original_message_count=2,
+        summarized_message_count=1,
+        kept_message_count=1,
+    )
+    store.append_message(context, role="user", content="after compact", message_index=2)
+    loaded = store.load_session(session_id="session-1", workdir=workdir)
+
+    history = cli_service.selected_continuation_history(loaded)
+
+    assert history[0]["role"] == "system"
+    assert history[1:] == loaded.compacted_history
+
+
+def test_selected_continuation_history_preserves_resume_compact_and_evidence_without_duplication(
+    tmp_path: Path,
+) -> None:
+    store = JsonlSessionStore(tmp_path / "sessions-store")
+    workdir = tmp_path / "workdir"
+    workdir.mkdir()
+    context = store.create_session(workdir=workdir, session_id="session-1")
+    store.append_message(context, role="user", content="existing", message_index=0)
+    store.append_evidence(
+        context,
+        kind="verification",
+        summary="pytest passed",
+        status="passed",
+        metadata={"plan_id": "plan-1", "verdict": "PASS"},
+    )
+    store.append_compact(
+        context,
+        trigger="manual",
+        summary="Earlier work was summarized.",
+        original_message_count=2,
+        summarized_message_count=1,
+        kept_message_count=1,
+    )
+    store.append_message(context, role="assistant", content="after compact", message_index=1)
+
+    loaded = store.load_session(session_id="session-1", workdir=workdir)
+    history = cli_service.selected_continuation_history(loaded)
+
+    assert history[0]["role"] == "system"
+    assert str(history[0]["content"]).count("Resumed session context.") == 1
+    assert "plan=plan-1" in str(history[0]["content"])
+    assert "verdict=PASS" in str(history[0]["content"])
+    assert history[1]["role"] == "system"
+    assert history[2]["role"] == "user"
+    assert "Earlier work was summarized." in str(history[2]["content"])
+    assert history[3] == {"role": "assistant", "content": "after compact"}
+    assert len(
+        [message for message in history if "Resumed session context." in str(message.get("content", ""))]
+    ) == 1
+
+
+def test_sessions_resume_can_use_manual_compact_summary(
+    monkeypatch, tmp_path: Path
+) -> None:
+    captured: dict[str, object] = {}
+    loaded = _loaded_session(tmp_path)
+
+    def fake_run_prompt(
+        prompt: str,
+        history=None,
+        session_state=None,
+        session_id=None,
+    ) -> str:
+        captured["prompt"] = prompt
+        captured["history"] = history
+        captured["session_state"] = session_state
+        captured["session_id"] = session_id
+        return "resumed"
+
+    runtime = cli_service.CliRuntime(
+        settings_loader=load_settings,
+        list_sessions=lambda: [],
+        load_session=lambda session_id: loaded,
+        run_prompt=fake_run_prompt,
+        doctor_checks=lambda: [],
+    )
+    monkeypatch.setattr(cli, "build_cli_runtime", lambda: runtime)
+
+    result = runner.invoke(
+        cli.app,
+        [
+            "sessions",
+            "resume",
+            "session-1",
+            "--prompt",
+            "continue",
+            "--compact-summary",
+            "<analysis>drop</analysis><summary>Earlier work is summarized.</summary>",
+            "--compact-keep-last",
+            "1",
+        ],
+    )
+
+    assert result.exit_code == 0
+    history = captured["history"]
+    assert isinstance(history, list)
+    assert history[0]["role"] == "system"
+    assert "Resumed session context" in str(history[0]["content"])
+    assert history[1]["role"] == "system"
+    assert COMPACT_BOUNDARY_PREFIX in str(history[1]["content"])
+    assert history[2]["role"] == "user"
+    assert COMPACT_SUMMARY_PREFIX in str(history[2]["content"])
+    assert "Earlier work is summarized." in str(history[2]["content"])
+    assert "<analysis>" not in str(history[2]["content"])
+    assert history[3] == {"role": "assistant", "content": "existing"}
+    assert captured["session_state"] == loaded.state
+    assert captured["session_id"] == "session-1"
+    assert "resumed" in result.stdout
+
+
+def test_sessions_resume_can_generate_manual_compact_summary(
+    monkeypatch, tmp_path: Path
+) -> None:
+    captured: dict[str, object] = {}
+    loaded = _loaded_session(tmp_path)
+    summarizer = FakeCompactSummarizer(
+        "<analysis>drop</analysis><summary>Generated compact summary.</summary>"
+    )
+
+    def fake_run_prompt(
+        prompt: str,
+        history=None,
+        session_state=None,
+        session_id=None,
+    ) -> str:
+        captured["prompt"] = prompt
+        captured["history"] = history
+        captured["session_state"] = session_state
+        captured["session_id"] = session_id
+        return "resumed"
+
+    runtime = cli_service.CliRuntime(
+        settings_loader=load_settings,
+        list_sessions=lambda: [],
+        load_session=lambda session_id: loaded,
+        run_prompt=fake_run_prompt,
+        doctor_checks=lambda: [],
+    )
+    monkeypatch.setattr(cli, "build_cli_runtime", lambda: runtime)
+    monkeypatch.setattr(cli, "build_openai_model", lambda _settings: summarizer)
+
+    result = runner.invoke(
+        cli.app,
+        [
+            "sessions",
+            "resume",
+            "session-1",
+            "--prompt",
+            "continue",
+            "--generate-compact-summary",
+            "--compact-instructions",
+            "Focus on code changes.",
+            "--compact-keep-last",
+            "1",
+        ],
+    )
+
+    assert result.exit_code == 0
+    assert len(summarizer.requests) == 1
+    assert summarizer.requests[0][0] == {"role": "assistant", "content": "existing"}
+    assert "Focus on code changes." in str(summarizer.requests[0][-1]["content"])
+    history = captured["history"]
+    assert isinstance(history, list)
+    assert "Resumed session context" in str(history[0]["content"])
+    assert COMPACT_BOUNDARY_PREFIX in str(history[1]["content"])
+    assert COMPACT_SUMMARY_PREFIX in str(history[2]["content"])
+    assert "Generated compact summary." in str(history[2]["content"])
+    assert captured["session_state"] == loaded.state
+    assert captured["session_id"] == "session-1"
+    assert "resumed" in result.stdout
+
+
+def test_sessions_resume_rejects_manual_and_generated_compact_together(
+    monkeypatch, tmp_path: Path
+) -> None:
+    loaded = _loaded_session(tmp_path)
+    called: list[str] = []
+
+    def run_prompt(
+        prompt: str, history=None, session_state=None, session_id=None
+    ) -> str:
+        del history, session_state, session_id
+        called.append(prompt)
+        return "unused"
+
+    runtime = cli_service.CliRuntime(
+        settings_loader=load_settings,
+        list_sessions=lambda: [],
+        load_session=lambda session_id: loaded,
+        run_prompt=run_prompt,
+        doctor_checks=lambda: [],
+    )
+    monkeypatch.setattr(cli, "build_cli_runtime", lambda: runtime)
+
+    result = runner.invoke(
+        cli.app,
+        [
+            "sessions",
+            "resume",
+            "session-1",
+            "--prompt",
+            "continue",
+            "--compact-summary",
+            "Manual summary.",
+            "--generate-compact-summary",
+        ],
+    )
+
+    assert result.exit_code != 0
+    assert called == []
+
+
+def test_sessions_resume_rejects_compact_options_without_prompt(
+    monkeypatch, tmp_path: Path
+) -> None:
+    loaded = _loaded_session(tmp_path)
+    called: list[str] = []
+
+    def run_prompt(
+        prompt: str, history=None, session_state=None, session_id=None
+    ) -> str:
+        del history, session_state, session_id
+        called.append(prompt)
+        return "unused"
+
+    runtime = cli_service.CliRuntime(
+        settings_loader=load_settings,
+        list_sessions=lambda: [],
+        load_session=lambda session_id: loaded,
+        run_prompt=run_prompt,
+        doctor_checks=lambda: [],
+    )
+    monkeypatch.setattr(cli, "build_cli_runtime", lambda: runtime)
+
+    result = runner.invoke(
+        cli.app,
+        [
+            "sessions",
+            "resume",
+            "session-1",
+            "--compact-instructions",
+            "Focus on code changes.",
+        ],
+    )
+
+    assert result.exit_code != 0
+    assert called == []
+
+
+def test_sessions_resume_rejects_compact_instructions_without_generation(
+    monkeypatch, tmp_path: Path
+) -> None:
+    loaded = _loaded_session(tmp_path)
+    called: list[str] = []
+
+    def run_prompt(
+        prompt: str, history=None, session_state=None, session_id=None
+    ) -> str:
+        del history, session_state, session_id
+        called.append(prompt)
+        return "unused"
+
+    runtime = cli_service.CliRuntime(
+        settings_loader=load_settings,
+        list_sessions=lambda: [],
+        load_session=lambda session_id: loaded,
+        run_prompt=run_prompt,
+        doctor_checks=lambda: [],
+    )
+    monkeypatch.setattr(cli, "build_cli_runtime", lambda: runtime)
+
+    result = runner.invoke(
+        cli.app,
+        [
+            "sessions",
+            "resume",
+            "session-1",
+            "--prompt",
+            "continue",
+            "--compact-instructions",
+            "Focus on code changes.",
+        ],
+    )
+
+    assert result.exit_code != 0
+    assert called == []
+
+
+def test_sessions_resume_without_prompt_shows_recovery_brief(
+    monkeypatch, tmp_path: Path
+) -> None:
+    store = JsonlSessionStore(tmp_path / "sessions-store")
+    workdir = tmp_path / "workdir"
+    workdir.mkdir()
+    context = store.create_session(workdir=workdir, session_id="session-brief")
+    store.append_message(context, role="user", content="start")
+    store.append_state_snapshot(
+        context,
+        state={
+            "todos": [
+                {
+                    "content": "Inspect repo",
+                    "status": "in_progress",
+                    "activeForm": "Inspecting",
+                }
+            ],
+            "rounds_since_update": 0,
+        },
+    )
+    store.append_evidence(
+        context,
+        kind="verification",
+        summary="pytest passed",
+        status="passed",
+    )
+    store.append_compact(
+        context,
+        trigger="manual",
+        summary="Earlier work was summarized.",
+        original_message_count=2,
+        summarized_message_count=1,
+        kept_message_count=1,
+    )
+    loaded = store.load_session(session_id="session-brief", workdir=workdir)
+
+    runtime = cli_service.CliRuntime(
+        settings_loader=load_settings,
+        list_sessions=lambda: [],
+        load_session=lambda session_id: loaded,
+        run_prompt=_unused_run_prompt,
+        doctor_checks=lambda: [],
+    )
+    monkeypatch.setattr(cli, "build_cli_runtime", lambda: runtime)
+
+    result = runner.invoke(cli.app, ["sessions", "resume", "session-brief"])
+
+    assert result.exit_code == 0
+    assert "Session: session-brief" in result.stdout
+    assert "Inspect repo" in result.stdout
+    assert "[passed] verification: pytest passed" in result.stdout
+    assert "[manual] Earlier work was summarized." in result.stdout
+
+
+def test_run_once_records_new_and_resumed_session_transcript(
+    monkeypatch, tmp_path: Path
+) -> None:
+    settings = Settings(
+        workdir=tmp_path,
+        session_dir=tmp_path / ".coding-deepgent" / "sessions",
+        model_name="gpt-test",
+    )
+
+    def fake_agent_loop(
+        messages: list[dict[str, object]],
+        *,
+        session_state=None,
+        session_id=None,
+        container=None,
+    ) -> str:
+        del session_id, container
+        if session_state is not None:
+            session_state["todos"] = [
+                {
+                    "content": "Resume task",
+                    "status": "in_progress",
+                    "activeForm": "Resuming",
+                }
+            ]
+            session_state["rounds_since_update"] = 0
+        messages.append({"role": "assistant", "content": "done"})
+        return "done"
+
+    monkeypatch.setattr(cli_service, "load_settings", lambda: settings)
+    monkeypatch.setattr(cli, "agent_loop", fake_agent_loop)
+
+    first = cli.run_once("first")
+    assert first == "done"
+
+    store = JsonlSessionStore(settings.session_dir)
+    [summary] = store.list_sessions(workdir=tmp_path)
+    loaded = store.load_session(session_id=summary.session_id, workdir=tmp_path)
+    assert loaded.history == [
+        {"role": "user", "content": "first"},
+        {"role": "assistant", "content": "done"},
+    ]
+    assert loaded.summary.evidence_count == 1
+
+    second = cli.run_once(
+        "second",
+        history=cli_service.continuation_history(loaded),
+        session_state=loaded.state,
+        session_id=loaded.summary.session_id,
+    )
+    assert second == "done"
+
+    resumed = store.load_session(session_id=summary.session_id, workdir=tmp_path)
+    raw_records = [
+        json.loads(line)
+        for line in (
+            store.transcript_path_for(session_id=summary.session_id, workdir=tmp_path)
+            .read_text(encoding="utf-8")
+            .splitlines()
+        )
+    ]
+    message_records = [
+        record for record in raw_records if record.get("record_type") == "message"
+    ]
+    assert resumed.history == [
+        {"role": "user", "content": "first"},
+        {"role": "assistant", "content": "done"},
+        {"role": "user", "content": "second"},
+        {"role": "assistant", "content": "done"},
+    ]
+    assert resumed.summary.evidence_count == 2
+    assert [record["message_index"] for record in message_records] == [0, 1, 2, 3]
+
+
+def test_run_once_passes_recording_session_context_to_agent(
+    monkeypatch, tmp_path: Path
+) -> None:
+    settings = Settings(
+        workdir=tmp_path,
+        session_dir=tmp_path / ".coding-deepgent" / "sessions",
+        model_name="gpt-test",
+    )
+    seen_contexts: list[object] = []
+
+    def fake_agent_loop(
+        messages: list[dict[str, object]],
+        *,
+        session_state=None,
+        session_id=None,
+        session_context=None,
+        container=None,
+    ) -> str:
+        del session_state, session_id, container
+        seen_contexts.append(session_context)
+        messages.append({"role": "assistant", "content": "done"})
+        return "done"
+
+    monkeypatch.setattr(cli_service, "load_settings", lambda: settings)
+    monkeypatch.setattr(cli, "agent_loop", fake_agent_loop)
+
+    assert cli.run_once("first") == "done"
+
+    assert len(seen_contexts) == 1
+    assert seen_contexts[0] is not None
+    assert getattr(seen_contexts[0], "session_id")
+    assert getattr(seen_contexts[0], "transcript_path").exists()
+
+
+def test_run_once_records_compact_metadata_without_message_index_skew(
+    monkeypatch, tmp_path: Path
+) -> None:
+    settings = Settings(
+        workdir=tmp_path,
+        session_dir=tmp_path / ".coding-deepgent" / "sessions",
+        model_name="gpt-test",
+    )
+
+    def fake_agent_loop(
+        messages: list[dict[str, object]],
+        *,
+        session_state=None,
+        session_id=None,
+        container=None,
+    ) -> str:
+        del session_state, session_id, container
+        messages.append({"role": "assistant", "content": "done"})
+        return "done"
+
+    monkeypatch.setattr(cli_service, "load_settings", lambda: settings)
+    monkeypatch.setattr(cli, "agent_loop", fake_agent_loop)
+
+    first = cli.run_once("first")
+    assert first == "done"
+    store = JsonlSessionStore(settings.session_dir)
+    [summary] = store.list_sessions(workdir=tmp_path)
+    loaded = store.load_session(session_id=summary.session_id, workdir=tmp_path)
+
+    second = cli.run_once(
+        "second",
+        history=cli_service.compacted_continuation_history(
+            loaded,
+            summary="<summary>Earlier work was summarized.</summary>",
+            keep_last=1,
+        ),
+        session_state=loaded.state,
+        session_id=loaded.summary.session_id,
+    )
+    assert second == "done"
+
+    resumed = store.load_session(session_id=summary.session_id, workdir=tmp_path)
+    raw_records = [
+        json.loads(line)
+        for line in (
+            store.transcript_path_for(session_id=summary.session_id, workdir=tmp_path)
+            .read_text(encoding="utf-8")
+            .splitlines()
+        )
+    ]
+    message_records = [
+        record for record in raw_records if record.get("record_type") == "message"
+    ]
+
+    assert resumed.history == [
+        {"role": "user", "content": "first"},
+        {"role": "assistant", "content": "done"},
+        {"role": "user", "content": "second"},
+        {"role": "assistant", "content": "done"},
+    ]
+    assert resumed.summary.compact_count == 1
+    assert resumed.compacts[0].summary == "Earlier work was summarized."
+    assert resumed.compacts[0].original_message_count == 2
+    assert resumed.compacts[0].summarized_message_count == 1
+    assert resumed.compacts[0].kept_message_count == 1
+    assert [record["message_index"] for record in message_records] == [0, 1, 2, 3]
+
+
+def test_doctor_reports_dependencies_without_secrets(monkeypatch) -> None:
+    monkeypatch.setenv("OPENAI_API_KEY", "sk-super-secret")
+
+    result = runner.invoke(cli.app, ["doctor"])
+
+    assert result.exit_code == 0
+    assert "Doctor" in result.stdout
+    assert "openai_api_key" in result.stdout
+    assert "<set>" in result.stdout
+    assert "sk-super-secret" not in result.stdout
diff --git a/coding-deepgent/tests/test_compact_artifacts.py b/coding-deepgent/tests/test_compact_artifacts.py
new file mode 100644
index 000000000..3a6c0c8fc
--- /dev/null
+++ b/coding-deepgent/tests/test_compact_artifacts.py
@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from copy import deepcopy
+
+import pytest
+
+from coding_deepgent.compact import (
+    COMPACT_BOUNDARY_PREFIX,
+    COMPACT_METADATA_KEY,
+    COMPACT_SUMMARY_PREFIX,
+    compact_messages_with_summary,
+    format_compact_summary,
+    project_messages,
+)
+
+
+def _text(message: dict[str, object]) -> str:
+    content = message["content"]
+    if isinstance(content, list):
+        return "\n".join(
+            str(block.get("text", ""))
+            for block in content
+            if isinstance(block, dict)
+        )
+    return str(content)
+
+
+def test_compact_messages_builds_boundary_summary_and_preserved_tail() -> None:
+    messages = [
+        {"role": "user", "content": "old request"},
+        {"role": "assistant", "content": "old answer"},
+        {"role": "user", "content": "recent request"},
+        {"role": "assistant", "content": "recent answer"},
+    ]
+
+    artifact = compact_messages_with_summary(
+        messages,
+        summary="Earlier work established the compact boundary.",
+        keep_last=2,
+    )
+
+    assert artifact.original_message_count == 4
+    assert artifact.summarized_message_count == 2
+    assert artifact.kept_message_count == 2
+    assert _text(artifact.messages[0]).startswith(COMPACT_BOUNDARY_PREFIX)
+    assert _text(artifact.messages[1]).startswith(COMPACT_SUMMARY_PREFIX)
+    assert artifact.messages[0]["metadata"][COMPACT_METADATA_KEY] == {
+        "kind": "boundary",
+        "trigger": "manual",
+        "original_message_count": 4,
+        "summarized_message_count": 2,
+        "kept_message_count": 2,
+    }
+    assert artifact.messages[1]["metadata"][COMPACT_METADATA_KEY] == {
+        "kind": "summary",
+        "summary": "Earlier work established the compact boundary.",
+    }
+    assert artifact.messages[2:] == messages[-2:]
+
+
+def test_compact_summary_strips_analysis_and_unwraps_summary() -> None:
+    assert (
+        format_compact_summary(
+            "<analysis>scratchpad</analysis>\n<summary>\nKeep this.\n</summary>"
+        )
+        == "Keep this."
+    )
+
+
+def test_compact_messages_does_not_mutate_input_messages() -> None:
+    messages = [
+        {"role": "user", "content": [{"type": "text", "text": "old"}]},
+        {"role": "assistant", "content": [{"type": "text", "text": "recent"}]},
+    ]
+    original = deepcopy(messages)
+
+    compact_messages_with_summary(messages, summary="Summary", keep_last=1)
+
+    assert messages == original
+
+
+def test_compact_artifact_survives_message_projection_without_user_merge() -> None:
+    artifact = compact_messages_with_summary(
+        [
+            {"role": "user", "content": "old"},
+            {"role": "user", "content": "recent"},
+        ],
+        summary="Summary",
+        keep_last=1,
+    )
+
+    assert project_messages(artifact.messages) == artifact.messages
+
+
+def test_compact_messages_expands_tail_to_preserve_tool_result_pair() -> None:
+    tool_use_message = {
+        "role": "assistant",
+        "content": [
+            {"type": "tool_use", "id": "call-1", "name": "bash", "input": {}}
+        ],
+    }
+    tool_result_message = {
+        "role": "user",
+        "content": [
+            {
+                "type": "tool_result",
+                "tool_use_id": "call-1",
+                "content": "ok",
+            }
+        ],
+    }
+    artifact = compact_messages_with_summary(
+        [
+            {"role": "user", "content": "old"},
+            tool_use_message,
+            tool_result_message,
+        ],
+        summary="Summary",
+        keep_last=1,
+    )
+
+    assert artifact.kept_message_count == 2
+    assert artifact.messages[-2:] == [tool_use_message, tool_result_message]
+
+
+def test_compact_messages_rejects_invalid_inputs() -> None:
+    with pytest.raises(ValueError, match="messages are required"):
+        compact_messages_with_summary([], summary="Summary")
+    with pytest.raises(ValueError, match="summary is required"):
+        compact_messages_with_summary([{"role": "user", "content": "x"}], summary=" ")
+    with pytest.raises(ValueError, match="keep_last"):
+        compact_messages_with_summary(
+            [{"role": "user", "content": "x"}], summary="Summary", keep_last=-1
+        )
diff --git a/coding-deepgent/tests/test_compact_budget.py b/coding-deepgent/tests/test_compact_budget.py
new file mode 100644
index 000000000..70b5ebe25
--- /dev/null
+++ b/coding-deepgent/tests/test_compact_budget.py
@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import pytest
+
+from coding_deepgent.compact import TRUNCATION_MARKER, apply_tool_result_budget
+
+
+def test_tool_result_budget_truncates_with_marker_and_metadata() -> None:
+    text = "abcdefghijklmnopqrstuvwxyz" * 3
+    result = apply_tool_result_budget(text, max_chars=len(TRUNCATION_MARKER) + 3)
+
+    assert result.truncated is True
+    assert result.text == "abc" + TRUNCATION_MARKER
+    assert result.original_length == len(text)
+    assert result.omitted_chars == len(text) - 3
+
+
+def test_tool_result_budget_leaves_small_text_unchanged_and_validates_limit() -> None:
+    result = apply_tool_result_budget("abc", max_chars=len(TRUNCATION_MARKER) + 1)
+
+    assert result.truncated is False
+    assert result.text == "abc"
+    assert result.omitted_chars == 0
+
+    with pytest.raises(ValueError):
+        apply_tool_result_budget("abc", max_chars=2)
diff --git a/coding-deepgent/tests/test_compact_summarizer.py b/coding-deepgent/tests/test_compact_summarizer.py
new file mode 100644
index 000000000..bb6392d82
--- /dev/null
+++ b/coding-deepgent/tests/test_compact_summarizer.py
@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from coding_deepgent.compact import (
+    build_compact_summary_prompt,
+    build_compact_summary_request,
+    generate_compact_summary,
+)
+
+
+class FakeSummarizer:
+    def __init__(self, response: Any) -> None:
+        self.response = response
+        self.requests: list[list[dict[str, Any]]] = []
+
+    def invoke(self, messages: list[dict[str, Any]]) -> Any:
+        self.requests.append(messages)
+        return self.response
+
+
+def test_build_compact_summary_request_appends_prompt_without_mutating_messages() -> None:
+    messages = [{"role": "user", "content": "hello"}]
+
+    request = build_compact_summary_request(
+        messages, custom_instructions="Focus on code changes."
+    )
+
+    assert messages == [{"role": "user", "content": "hello"}]
+    assert request[:-1] == messages
+    assert request[-1]["role"] == "user"
+    assert "Create a detailed compact summary" in str(request[-1]["content"])
+    assert "Focus on code changes." in str(request[-1]["content"])
+
+
+def test_generate_compact_summary_invokes_summarizer_and_formats_output() -> None:
+    summarizer = FakeSummarizer(
+        {
+            "content": [
+                {
+                    "type": "text",
+                    "text": (
+                        "<analysis>drop this</analysis>"
+                        "<summary>Keep the compact summary.</summary>"
+                    ),
+                }
+            ]
+        }
+    )
+
+    summary = generate_compact_summary(
+        [{"role": "user", "content": "old"}],
+        summarizer,
+    )
+
+    assert summary == "Keep the compact summary."
+    assert len(summarizer.requests) == 1
+    assert summarizer.requests[0][0] == {"role": "user", "content": "old"}
+
+
+def test_generate_compact_summary_supports_callable_summarizer() -> None:
+    seen: list[list[dict[str, Any]]] = []
+
+    def summarize(messages: list[dict[str, Any]]) -> str:
+        seen.append(messages)
+        return "<summary>Callable summary.</summary>"
+
+    assert (
+        generate_compact_summary([{"role": "user", "content": "old"}], summarize)
+        == "Callable summary."
+    )
+    assert seen
+
+
+def test_generate_compact_summary_rejects_empty_output() -> None:
+    with pytest.raises(ValueError, match="empty summary"):
+        generate_compact_summary(
+            [{"role": "user", "content": "old"}],
+            FakeSummarizer("<analysis>only scratchpad</analysis>"),
+        )
+
+
+def test_build_compact_summary_prompt_omits_blank_custom_instructions() -> None:
+    assert "Additional instructions" not in build_compact_summary_prompt(" ")
diff --git a/coding-deepgent/tests/test_config.py b/coding-deepgent/tests/test_config.py
new file mode 100644
index 000000000..abf450389
--- /dev/null
+++ b/coding-deepgent/tests/test_config.py
@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from coding_deepgent import settings as config
+
+
+def test_model_name_ignores_anthropic_model_id(monkeypatch) -> None:
+    monkeypatch.delenv("OPENAI_MODEL", raising=False)
+    monkeypatch.setenv("MODEL_ID", "claude-sonnet-4-6")
+
+    assert config.deepgent_model_name() == config.DEFAULT_OPENAI_MODEL
+
+    monkeypatch.setenv("MODEL_ID", "glm-5")
+
+    assert config.deepgent_model_name() == "glm-5"
+
+    monkeypatch.setenv("OPENAI_MODEL", "gpt-test-mini")
+
+    assert config.deepgent_model_name() == "gpt-test-mini"
diff --git a/coding-deepgent/tests/test_context_payloads.py b/coding-deepgent/tests/test_context_payloads.py
new file mode 100644
index 000000000..1aabc622d
--- /dev/null
+++ b/coding-deepgent/tests/test_context_payloads.py
@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from typing import cast
+
+from coding_deepgent.context_payloads import (
+    DEFAULT_MAX_CHARS,
+    TRUNCATION_MARKER,
+    ContextPayload,
+    merge_system_message_content,
+    render_context_payloads,
+)
+
+
+def test_render_context_payloads_is_deterministic_and_sorts_by_priority() -> None:
+    payloads = [
+        ContextPayload(kind="memory", text="Memory B", source="mem.b", priority=200),
+        ContextPayload(kind="todo", text="Todo A", source="todo.a", priority=100),
+        ContextPayload(
+            kind="todo_reminder",
+            text="Reminder C",
+            source="todo.reminder",
+            priority=110,
+        ),
+    ]
+
+    rendered = render_context_payloads(list(reversed(payloads)))
+
+    assert rendered == [
+        {"type": "text", "text": "Todo A"},
+        {"type": "text", "text": "Reminder C"},
+        {"type": "text", "text": "Memory B"},
+    ]
+
+
+def test_render_context_payloads_dedupes_same_kind_source_and_text() -> None:
+    rendered = render_context_payloads(
+        [
+            ContextPayload(kind="memory", text="Same", source="memory.project"),
+            ContextPayload(kind="memory", text="Same", source="memory.project"),
+            ContextPayload(kind="memory", text="Same", source="memory.other"),
+        ]
+    )
+
+    assert rendered == [
+        {"type": "text", "text": "Same"},
+        {"type": "text", "text": "Same"},
+    ]
+
+
+def test_render_context_payloads_bounds_output_with_truncation_marker() -> None:
+    text = "x" * (DEFAULT_MAX_CHARS + 100)
+    rendered = render_context_payloads(
+        [ContextPayload(kind="memory", text=text, source="memory.project")]
+    )
+    rendered_text = cast(str, rendered[0]["text"])
+
+    assert len(rendered) == 1
+    assert len(rendered_text) == DEFAULT_MAX_CHARS
+    assert rendered_text.endswith(TRUNCATION_MARKER)
+    assert "x" * 100 not in rendered_text[-100:]
+
+
+def test_merge_system_message_content_preserves_existing_blocks() -> None:
+    current = [{"type": "text", "text": "Base"}]
+    merged = merge_system_message_content(
+        current,
+        [ContextPayload(kind="todo", text="Current session todos:\n- one", source="todo.current")],
+    )
+
+    assert merged == [
+        {"type": "text", "text": "Base"},
+        {"type": "text", "text": "Current session todos:\n- one"},
+    ]
diff --git a/coding-deepgent/tests/test_contract.py b/coding-deepgent/tests/test_contract.py
new file mode 100644
index 000000000..d9c647ace
--- /dev/null
+++ b/coding-deepgent/tests/test_contract.py
@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import ast
+import json
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SRC = ROOT / "src" / "coding_deepgent"
+TESTS = ROOT / "tests"
+STAGE_1 = "stage-1-todowrite-foundation"
+STAGE_3 = "stage-3-professional-domain-runtime-foundation"
+STAGE_4 = "stage-4-control-plane-foundation"
+STAGE_5 = "stage-5-memory-context-compact-foundation"
+STAGE_6 = "stage-6-skills-subagents-task-graph"
+STAGE_7 = "stage-7-mcp-plugin-extension-foundation"
+STAGE_8 = "stage-8-recovery-evidence-runtime-continuation"
+STAGE_9 = "stage-9-permission-trust-boundary-hardening"
+STAGE_10 = "stage-10-hooks-lifecycle-expansion"
+STAGE_11 = "stage-11-mcp-plugin-real-loading"
+TUTORIAL_PACKAGE = "agents_" + "deepagents"
+
+
+def _python_files() -> list[Path]:
+    return sorted([*SRC.rglob("*.py"), *TESTS.rglob("*.py")])
+
+
+def _status() -> dict[str, object]:
+    return json.loads((ROOT / "project_status.json").read_text(encoding="utf-8"))
+
+
+def test_project_avoids_tutorial_track_imports() -> None:
+    offenders: list[str] = []
+
+    for path in _python_files():
+        tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    if alias.name.startswith(TUTORIAL_PACKAGE):
+                        offenders.append(f"{path}:{alias.name}")
+            elif isinstance(node, ast.ImportFrom):
+                module = node.module or ""
+                if module.startswith(TUTORIAL_PACKAGE):
+                    offenders.append(f"{path}:{module}")
+
+    assert offenders == []
+
+
+def test_product_status_uses_stage_language_not_chapter_gate() -> None:
+    status = _status()
+    stage = str(status["current_product_stage"])
+
+    assert stage in {
+        STAGE_1,
+        STAGE_3,
+        STAGE_4,
+        STAGE_5,
+        STAGE_6,
+        STAGE_7,
+        STAGE_8,
+        STAGE_9,
+        STAGE_10,
+        STAGE_11,
+    }
+    assert (
+        status["compatibility_anchor"]
+        == {
+            STAGE_1: "s03",
+            STAGE_3: "professional-domain-runtime-foundation",
+            STAGE_4: "control-plane-foundation",
+            STAGE_5: "memory-context-compact-foundation",
+            STAGE_6: "skills-subagents-task-graph",
+            STAGE_7: "mcp-plugin-extension-foundation",
+            STAGE_8: "recovery-evidence-runtime-continuation",
+            STAGE_9: "permission-trust-boundary-hardening",
+            STAGE_10: "hooks-lifecycle-expansion",
+            STAGE_11: "mcp-plugin-real-loading",
+        }[stage]
+    )
+    assert status["shape"] == "staged_langchain_cc_product"
+    upgrade_policy = str(status["upgrade_policy"])
+    assert "product-stage plan approval" in upgrade_policy
+    assert "chapter is complete" not in upgrade_policy
+
+
+def test_package_does_not_expose_stage_named_modules() -> None:
+    package_files = {path.name for path in SRC.glob("*.py")}
+
+    assert not any(name.startswith("s0") for name in package_files)
diff --git a/coding-deepgent/tests/test_hooks.py b/coding-deepgent/tests/test_hooks.py
new file mode 100644
index 000000000..ba54c8b05
--- /dev/null
+++ b/coding-deepgent/tests/test_hooks.py
@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from coding_deepgent.hooks import (
+    HookDispatchOutcome,
+    HookPayload,
+    HookResult,
+    LocalHookRegistry,
+)
+from coding_deepgent.hooks.dispatcher import dispatch_context_hook, dispatch_runtime_hook
+from coding_deepgent.runtime import InMemoryEventSink, RuntimeContext, RuntimeInvocation
+from coding_deepgent.sessions import JsonlSessionStore, build_recovery_brief, render_recovery_brief
+from pathlib import Path
+
+
+def test_local_hook_registry_runs_matching_hooks_in_order() -> None:
+    registry = LocalHookRegistry()
+    seen: list[str] = []
+
+    def first(payload: HookPayload) -> HookResult:
+        seen.append(f"first:{payload.event}")
+        return HookResult(reason="first")
+
+    def second(payload: HookPayload) -> HookResult:
+        seen.append(f"second:{payload.event}")
+        return HookResult.model_validate(
+            {"continue": False, "decision": "block", "reason": "second"}
+        )
+
+    registry.register("PreToolUse", first)
+    registry.register("PreToolUse", second)
+
+    results = registry.run(HookPayload(event="PreToolUse", data={"tool": "bash"}))
+
+    assert seen == ["first:PreToolUse", "second:PreToolUse"]
+    assert [result.reason for result in results] == ["first", "second"]
+    assert results[1].continue_ is False
+
+
+def test_local_hook_registry_dispatch_aggregates_block_and_context() -> None:
+    registry = LocalHookRegistry()
+
+    registry.register(
+        "UserPromptSubmit",
+        lambda _payload: HookResult(additional_context="ctx-1"),
+    )
+    registry.register(
+        "UserPromptSubmit",
+        lambda _payload: HookResult.model_validate(
+            {
+                "continue": False,
+                "decision": "block",
+                "reason": "blocked",
+                "additional_context": "ctx-2",
+            }
+        ),
+    )
+
+    outcome = registry.dispatch(
+        HookPayload(event="UserPromptSubmit", data={"message": "hello"})
+    )
+
+    assert isinstance(outcome, HookDispatchOutcome)
+    assert outcome.blocked is True
+    assert outcome.reason == "blocked"
+    assert outcome.additional_context == ("ctx-1", "ctx-2")
+
+
+def test_hook_result_schema_rejects_unknown_fields_and_decisions() -> None:
+    with pytest.raises(ValidationError):
+        HookResult.model_validate({"decision": "maybe"})
+    with pytest.raises(ValidationError):
+        HookResult.model_validate({"continue": True, "extra": "nope"})
+
+
+def test_hook_payload_rejects_unknown_events() -> None:
+    with pytest.raises(ValidationError):
+        HookPayload.model_validate({"event": "UnknownEvent", "data": {}})
+
+
+def test_runtime_hook_dispatch_emits_start_and_terminal_event_metadata() -> None:
+    registry = LocalHookRegistry()
+    registry.register(
+        "UserPromptSubmit",
+        lambda _payload: HookResult.model_validate(
+            {"continue": False, "decision": "block", "reason": "blocked"}
+        ),
+    )
+    sink = InMemoryEventSink()
+    invocation = RuntimeInvocation(
+        context=RuntimeContext(
+            session_id="session-1",
+            workdir=Path.cwd(),
+            trusted_workdirs=(),
+            entrypoint="test",
+            agent_name="test-agent",
+            skill_dir=Path.cwd() / "skills",
+            event_sink=sink,
+            hook_registry=registry,
+        ),
+        config={"configurable": {"thread_id": "session-1"}},
+    )
+
+    outcome = dispatch_runtime_hook(
+        invocation,
+        event="UserPromptSubmit",
+        data={"message": "hello"},
+    )
+    events = sink.snapshot()
+
+    assert outcome.blocked is True
+    assert [event.kind for event in events] == ["hook_start", "hook_blocked"]
+    assert events[0].metadata == {
+        "source": "hooks",
+        "hook_event": "UserPromptSubmit",
+        "blocked": False,
+        "reason": None,
+    }
+    assert events[1].metadata == {
+        "source": "hooks",
+        "hook_event": "UserPromptSubmit",
+        "blocked": True,
+        "reason": "blocked",
+    }
+
+
+def test_blocked_runtime_hook_appends_session_evidence(tmp_path: Path) -> None:
+    store = JsonlSessionStore(tmp_path / "sessions")
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+    session_context = store.create_session(workdir=workdir, session_id="session-1")
+    store.append_message(session_context, role="user", content="start")
+    registry = LocalHookRegistry()
+    registry.register(
+        "UserPromptSubmit",
+        lambda _payload: HookResult.model_validate(
+            {"continue": False, "decision": "block", "reason": "blocked"}
+        ),
+    )
+    invocation = RuntimeInvocation(
+        context=RuntimeContext(
+            session_id="session-1",
+            workdir=workdir,
+            trusted_workdirs=(),
+            entrypoint="test",
+            agent_name="test-agent",
+            skill_dir=workdir / "skills",
+            event_sink=InMemoryEventSink(),
+            hook_registry=registry,
+            session_context=session_context,
+        ),
+        config={"configurable": {"thread_id": "session-1"}},
+    )
+
+    dispatch_runtime_hook(
+        invocation,
+        event="UserPromptSubmit",
+        data={"message": "hello"},
+    )
+    loaded = store.load_session(session_id="session-1", workdir=workdir)
+    rendered = render_recovery_brief(build_recovery_brief(loaded))
+
+    assert loaded.summary.evidence_count == 1
+    assert loaded.evidence[0].kind == "runtime_event"
+    assert loaded.evidence[0].status == "blocked"
+    assert loaded.evidence[0].metadata == {
+        "event_kind": "hook_blocked",
+        "source": "hooks",
+        "hook_event": "UserPromptSubmit",
+        "blocked": True,
+    }
+    assert "[blocked] runtime_event: Hook UserPromptSubmit blocked execution." in rendered
+
+
+def test_context_hook_dispatch_emits_start_and_complete_event_metadata() -> None:
+    registry = LocalHookRegistry()
+    registry.register("PreToolUse", lambda _payload: HookResult(reason="ok"))
+    sink = InMemoryEventSink()
+    context = RuntimeContext(
+        session_id="session-1",
+        workdir=Path.cwd(),
+        trusted_workdirs=(),
+        entrypoint="test",
+        agent_name="test-agent",
+        skill_dir=Path.cwd() / "skills",
+        event_sink=sink,
+        hook_registry=registry,
+    )
+
+    outcome = dispatch_context_hook(
+        context=context,
+        session_id="session-1",
+        event="PreToolUse",
+        data={"tool": "read_file"},
+    )
+    events = sink.snapshot()
+
+    assert outcome is not None
+    assert outcome.blocked is False
+    assert [event.kind for event in events] == ["hook_start", "hook_complete"]
+    assert events[0].metadata == {
+        "source": "hooks",
+        "hook_event": "PreToolUse",
+        "blocked": False,
+    }
+    assert events[1].metadata == {
+        "source": "hooks",
+        "hook_event": "PreToolUse",
+        "blocked": False,
+        "reason": None,
+    }
diff --git a/coding-deepgent/tests/test_logging.py b/coding-deepgent/tests/test_logging.py
new file mode 100644
index 000000000..2dac51d0e
--- /dev/null
+++ b/coding-deepgent/tests/test_logging.py
@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from coding_deepgent.logging_config import (
+    configure_logging,
+    redact_value,
+    safe_environment_snapshot,
+)
+
+
+def test_safe_environment_snapshot_redacts_provider_secret() -> None:
+    snapshot = safe_environment_snapshot(
+        {
+            "OPENAI_API_KEY": "sk-secret",
+            "OPENAI_BASE_URL": "https://example.invalid/v1",
+            "OPENAI_MODEL": "gpt-test",
+        }
+    )
+
+    assert snapshot == {
+        "OPENAI_API_KEY": "<set>",
+        "OPENAI_BASE_URL": "https://example.invalid/v1",
+        "OPENAI_MODEL": "gpt-test",
+    }
+    assert "sk-secret" not in str(snapshot)
+
+
+def test_redact_value_masks_named_secret_fields() -> None:
+    assert redact_value("OPENAI_API_KEY", "sk-secret") == "<redacted>"
+    assert (
+        redact_value("OPENAI_BASE_URL", "https://example.invalid/v1")
+        == "https://example.invalid/v1"
+    )
+
+
+def test_configure_logging_initializes_structlog_without_services() -> None:
+    logger = configure_logging("DEBUG")
+
+    assert logger is not None
+    assert hasattr(logger, "bind")
diff --git a/coding-deepgent/tests/test_mcp.py b/coding-deepgent/tests/test_mcp.py
new file mode 100644
index 000000000..913a71cdf
--- /dev/null
+++ b/coding-deepgent/tests/test_mcp.py
@@ -0,0 +1,289 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Sequence, cast
+
+import pytest
+from dependency_injector import providers
+from langchain.tools import tool
+
+from coding_deepgent.containers import AppContainer
+from coding_deepgent.mcp import (
+    MCPConfig,
+    MCPResourceDescriptor,
+    MCPResourceRegistry,
+    MCPRuntimeLoadResult,
+    MCPServerConfig,
+    MCPSourceMetadata,
+    MCPToolDescriptor,
+    MCPToolHint,
+    adapt_mcp_tool_descriptor,
+    adapt_mcp_tool_descriptors,
+    langchain_mcp_adapters_available,
+    load_local_mcp_config,
+    load_mcp_runtime_extensions,
+    mcp_config_path,
+)
+from coding_deepgent.settings import Settings
+from coding_deepgent.tool_system import CapabilityRegistry
+
+
+@tool("mcp__docs__lookup", description="Lookup docs by query.")
+def docs_lookup(query: str) -> str:
+    """Lookup docs by query."""
+
+    return query
+
+
+def test_mcp_tool_descriptor_maps_to_capability_with_source_metadata() -> None:
+    descriptor = MCPToolDescriptor(
+        name="mcp__docs__lookup",
+        tool=docs_lookup,
+        source=MCPSourceMetadata(server_name="docs", transport="stdio"),
+        hints=MCPToolHint(read_only=True),
+    )
+
+    capability = adapt_mcp_tool_descriptor(descriptor)
+
+    assert capability.name == "mcp__docs__lookup"
+    assert capability.tool is docs_lookup
+    assert capability.domain == "mcp"
+    assert capability.read_only is True
+    assert capability.destructive is False
+    assert capability.concurrency_safe is True
+    assert capability.source == "mcp:docs"
+    assert capability.trusted is False
+    assert "server:docs" in capability.tags
+    assert "transport:stdio" in capability.tags
+
+
+def test_mcp_resources_stay_separate_from_executable_capabilities() -> None:
+    source = MCPSourceMetadata(server_name="docs", transport="stdio")
+    resource = MCPResourceDescriptor(
+        uri="file:///docs/guide.md",
+        name="guide",
+        description="Guide",
+        mime_type="text/markdown",
+        source=source,
+    )
+    registry = MCPResourceRegistry([resource])
+    capabilities = adapt_mcp_tool_descriptors(
+        [
+            MCPToolDescriptor(
+                name="mcp__docs__lookup",
+                tool=docs_lookup,
+                source=source,
+            )
+        ]
+    )
+
+    assert registry.uris() == ["file:///docs/guide.md"]
+    assert registry.by_server("docs") == [resource]
+    assert [capability.name for capability in capabilities] == ["mcp__docs__lookup"]
+    assert "file:///docs/guide.md" not in [
+        capability.name for capability in capabilities
+    ]
+
+    with pytest.raises(ValueError):
+        MCPResourceRegistry([resource, resource])
+
+
+def test_mcp_extension_capabilities_are_agent_bindable_without_replacing_runtime(
+    tmp_path,
+) -> None:
+    captured: dict[str, object] = {}
+
+    def fake_create_agent(**kwargs):
+        captured.update(kwargs)
+        return object()
+
+    capability = adapt_mcp_tool_descriptor(
+        MCPToolDescriptor(
+            name="mcp__docs__lookup",
+            tool=docs_lookup,
+            source=MCPSourceMetadata(server_name="docs", transport="stdio"),
+            hints=MCPToolHint(read_only=True),
+        )
+    )
+    settings = Settings(workdir=tmp_path)
+    container = AppContainer(
+        settings=providers.Object(settings),
+        model=providers.Object(object()),
+        create_agent_factory=providers.Object(fake_create_agent),
+        extension_capabilities=providers.Object([capability]),
+    )
+
+    assert container.agent() is not None
+    assert captured["name"] == "coding-deepgent"
+    tool_names = [
+        getattr(tool_item, "name", type(tool_item).__name__)
+        for tool_item in cast(Sequence[object], captured["tools"])
+    ]
+    assert tool_names[-1] == "mcp__docs__lookup"
+    assert "mcp__docs__lookup" in container.capability_registry().names()
+    assert isinstance(container.capability_registry(), CapabilityRegistry)
+
+
+def test_langchain_mcp_adapter_probe_is_optional_and_side_effect_free() -> None:
+    assert isinstance(langchain_mcp_adapters_available(), bool)
+
+
+def test_mcp_config_schema_and_loader_are_strict(tmp_path: Path) -> None:
+    path = mcp_config_path(tmp_path)
+    path.write_text(
+        json.dumps(
+            {
+                "mcpServers": {
+                    "docs": {
+                        "command": "python",
+                        "args": ["server.py"],
+                        "env": {"TOKEN": "x"},
+                    }
+                }
+            }
+        ),
+        encoding="utf-8",
+    )
+
+    loaded = load_local_mcp_config(workdir=tmp_path)
+
+    assert loaded is not None
+    assert loaded.path == path
+    assert isinstance(loaded.config, MCPConfig)
+    assert loaded.config.mcpServers["docs"].transport == "stdio"
+
+    with pytest.raises(Exception):
+        MCPServerConfig.model_validate({"transport": "stdio", "extra": True})
+
+
+def test_mcp_server_transport_alias_and_http_sse_contracts() -> None:
+    http = MCPServerConfig.model_validate(
+        {"type": "http", "url": "https://example.invalid/mcp"}
+    )
+    sse = MCPServerConfig.model_validate(
+        {"transport": "sse", "url": "https://example.invalid/events"}
+    )
+
+    assert http.transport == "http"
+    assert sse.transport == "sse"
+
+    with pytest.raises(ValueError, match="transport and type must match"):
+        MCPServerConfig.model_validate(
+            {"transport": "stdio", "type": "http", "command": "server"}
+        )
+    with pytest.raises(ValueError, match="http MCP server requires url"):
+        MCPServerConfig.model_validate({"transport": "http"})
+    with pytest.raises(ValueError, match="http MCP server must not define command"):
+        MCPServerConfig.model_validate(
+            {
+                "transport": "http",
+                "url": "https://example.invalid/mcp",
+                "command": "server",
+            }
+        )
+
+
+def test_mcp_runtime_load_fails_soft_without_adapter(
+    monkeypatch, tmp_path: Path
+) -> None:
+    mcp_config_path(tmp_path).write_text(
+        json.dumps(
+            {
+                "mcpServers": {
+                    "docs": {
+                        "command": "python",
+                        "args": ["server.py"],
+                    }
+                }
+            }
+        ),
+        encoding="utf-8",
+    )
+
+    monkeypatch.setattr(
+        "coding_deepgent.mcp.loader.langchain_mcp_adapters_available",
+        lambda: False,
+    )
+    result = load_mcp_runtime_extensions(workdir=tmp_path)
+
+    assert isinstance(result, MCPRuntimeLoadResult)
+    assert result.loaded_config is not None
+    assert result.capabilities == ()
+    assert result.reason == "langchain_mcp_adapters_unavailable"
+
+
+def test_mcp_runtime_load_uses_client_factory_when_available(tmp_path: Path) -> None:
+    mcp_config_path(tmp_path).write_text(
+        json.dumps(
+            {
+                "mcpServers": {
+                    "docs": {
+                        "command": "python",
+                        "args": ["server.py"],
+                    }
+                }
+            }
+        ),
+        encoding="utf-8",
+    )
+
+    class FakeClient:
+        def __init__(self, config):
+            self.config = config
+
+        async def get_tools(self):
+            return [docs_lookup]
+
+    result = load_mcp_runtime_extensions(
+        workdir=tmp_path,
+        client_factory=lambda config: FakeClient(config),
+    )
+
+    assert result.adapter_available is True
+    assert [capability.name for capability in result.capabilities] == [
+        "mcp__docs__lookup"
+    ]
+    assert result.resources.uris() == []
+
+
+def test_app_container_merges_loaded_mcp_capabilities(
+    monkeypatch, tmp_path: Path
+) -> None:
+    captured: dict[str, object] = {}
+
+    def fake_create_agent(**kwargs):
+        captured.update(kwargs)
+        return object()
+
+    capability = adapt_mcp_tool_descriptor(
+        MCPToolDescriptor(
+            name="mcp__docs__lookup",
+            tool=docs_lookup,
+            source=MCPSourceMetadata(server_name="docs", transport="stdio"),
+            hints=MCPToolHint(read_only=True),
+        )
+    )
+    settings = Settings(workdir=tmp_path)
+    container = AppContainer(
+        settings=providers.Object(settings),
+        model=providers.Object(object()),
+        create_agent_factory=providers.Object(fake_create_agent),
+    )
+    container.mcp_runtime_load_result.override(
+        providers.Object(
+            MCPRuntimeLoadResult(
+                loaded_config=None,
+                capabilities=(capability,),
+                resources=MCPResourceRegistry(),
+                adapter_available=True,
+            )
+        )
+    )
+
+    assert container.agent() is not None
+    tool_names = [
+        getattr(tool_item, "name", type(tool_item).__name__)
+        for tool_item in cast(Sequence[object], captured["tools"])
+    ]
+    assert "mcp__docs__lookup" in tool_names
diff --git a/coding-deepgent/tests/test_memory.py b/coding-deepgent/tests/test_memory.py
new file mode 100644
index 000000000..73c2620ef
--- /dev/null
+++ b/coding-deepgent/tests/test_memory.py
@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from typing import cast
+
+import pytest
+from langgraph.store.memory import InMemoryStore
+from pydantic import BaseModel, ValidationError
+
+from coding_deepgent.memory import (
+    MemoryRecord,
+    SaveMemoryInput,
+    evaluate_memory_quality,
+    list_memory_records,
+    recall_memories,
+    save_memory,
+    save_memory_record,
+)
+
+
+def test_save_memory_schema_is_strict_and_model_visible() -> None:
+    tool_call_schema = cast(type[BaseModel], save_memory.tool_call_schema)
+    schema = tool_call_schema.model_json_schema()
+
+    assert save_memory.name == "save_memory"
+    assert schema["required"] == ["content"]
+    assert "tool_call_id" not in schema["properties"]
+    assert "content" in schema["properties"]
+
+    with pytest.raises(ValidationError):
+        SaveMemoryInput.model_validate({"task": "do not alias"})
+    with pytest.raises(ValidationError):
+        SaveMemoryInput.model_validate({"content": "remember", "extra": "nope"})
+
+
+def test_memory_store_save_list_and_recall_are_deterministic() -> None:
+    store = InMemoryStore()
+    first = MemoryRecord(
+        content="Use LangChain store for long-term memory", namespace="project"
+    )
+    second = MemoryRecord(
+        content="Keep Todo separate from durable tasks", namespace="project"
+    )
+
+    first_key = save_memory_record(store, first)
+    second_key = save_memory_record(store, second)
+
+    assert first_key != second_key
+    assert [record.content for record in list_memory_records(store, "project")] == [
+        first.content,
+        second.content,
+    ]
+    assert [
+        record.content for record in recall_memories(store, query="LangChain", limit=2)
+    ] == [first.content]
+    assert [record.content for record in recall_memories(store, limit=1)] == [
+        first.content
+    ]
+    assert recall_memories(None) == []
+
+
+def test_memory_quality_policy_rejects_transient_and_duplicate_entries() -> None:
+    existing = [
+        MemoryRecord(
+            content="Prefer LangChain stores for cross-session memory",
+            namespace="project",
+        )
+    ]
+
+    duplicate = evaluate_memory_quality(
+        MemoryRecord(
+            content=" prefer   langchain stores for cross-session MEMORY ",
+            namespace="project",
+        ),
+        existing_records=existing,
+    )
+    transient = evaluate_memory_quality(
+        MemoryRecord(content="Currently working on Stage 12D", namespace="project")
+    )
+    durable = evaluate_memory_quality(
+        MemoryRecord(
+            content="Use LangChain stores for cross-session memory",
+            namespace="project",
+        ),
+        existing_records=existing,
+    )
+
+    assert duplicate.allowed is False
+    assert duplicate.category == "duplicate"
+    assert transient.allowed is False
+    assert transient.category == "transient_state"
+    assert durable.allowed is True
+    assert durable.category == "accepted"
+
+
+def test_memory_namespaces_are_isolated_for_recall_and_duplicates() -> None:
+    store = InMemoryStore()
+    project = MemoryRecord(
+        content="Prefer LangChain stores for memory", namespace="project"
+    )
+    user = MemoryRecord(
+        content="Prefer concise answers by default", namespace="user"
+    )
+    save_memory_record(store, project)
+    save_memory_record(store, user)
+
+    project_records = list_memory_records(store, "project")
+    user_records = list_memory_records(store, "user")
+    project_recall = recall_memories(store, namespace="project", query="LangChain")
+    user_recall = recall_memories(store, namespace="user", query="concise")
+
+    duplicate_in_same_namespace = evaluate_memory_quality(
+        MemoryRecord(
+            content=" prefer   langchain stores for MEMORY ", namespace="project"
+        ),
+        existing_records=project_records,
+    )
+    same_content_other_namespace = evaluate_memory_quality(
+        MemoryRecord(
+            content=" prefer   langchain stores for MEMORY ", namespace="user"
+        ),
+        existing_records=user_records,
+    )
+
+    assert [record.namespace for record in project_records] == ["project"]
+    assert [record.namespace for record in user_records] == ["user"]
+    assert [record.namespace for record in project_recall] == ["project"]
+    assert [record.namespace for record in user_recall] == ["user"]
+    assert duplicate_in_same_namespace.allowed is False
+    assert same_content_other_namespace.allowed is True
diff --git a/coding-deepgent/tests/test_memory_context.py b/coding-deepgent/tests/test_memory_context.py
new file mode 100644
index 000000000..c60feef38
--- /dev/null
+++ b/coding-deepgent/tests/test_memory_context.py
@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from coding_deepgent.memory import MemoryRecord
+from coding_deepgent.prompting import build_prompt_context
+
+
+def test_prompt_context_injects_recalled_memory_as_distinct_section() -> None:
+    context = build_prompt_context(
+        workdir=Path("/tmp/project"),
+        agent_name="coding-deepgent",
+        session_id="s1",
+        entrypoint="coding-deepgent",
+        memories=[
+            MemoryRecord(
+                content="Prefer LangChain stores for memory", namespace="project"
+            )
+        ],
+    )
+
+    assert (
+        context.memory_context
+        == "Relevant long-term memory:\n- [project] Prefer LangChain stores for memory"
+    )
+    assert context.memory_context in context.system_prompt
+    assert context.default_system_prompt[0].startswith("You are coding-deepgent")
diff --git a/coding-deepgent/tests/test_memory_integration.py b/coding-deepgent/tests/test_memory_integration.py
new file mode 100644
index 000000000..ac9bbd105
--- /dev/null
+++ b/coding-deepgent/tests/test_memory_integration.py
@@ -0,0 +1,271 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+from typing import Any, Sequence, cast
+
+from langchain.agents import create_agent
+from langchain.agents.middleware import ModelRequest
+from langchain.messages import HumanMessage, SystemMessage
+from langchain_core.messages import AIMessage
+from langchain_core.language_models.fake_chat_models import FakeMessagesListChatModel
+from pydantic import PrivateAttr
+from langgraph.store.memory import InMemoryStore
+
+from coding_deepgent.memory import (
+    MemoryContextMiddleware,
+    MemoryRecord,
+    memory_namespace,
+    save_memory,
+    save_memory_record,
+)
+from coding_deepgent.context_payloads import ContextPayload, merge_system_message_content
+from coding_deepgent.containers import AppContainer
+from coding_deepgent.settings import Settings
+from coding_deepgent.todo.middleware import PlanContextMiddleware
+
+
+class RecordingFakeModel(FakeMessagesListChatModel):
+    _bound_tool_names: list[str] = PrivateAttr(default_factory=list)
+
+    def bind_tools(self, tools, *, tool_choice=None, **kwargs):
+        del tool_choice, kwargs
+        self._bound_tool_names = [
+            getattr(tool, "name", type(tool).__name__) for tool in tools
+        ]
+        return self
+
+
+def test_save_memory_tool_writes_to_langgraph_store_via_create_agent_runtime() -> None:
+    store = InMemoryStore()
+    model = RecordingFakeModel(
+        responses=[
+            AIMessage(
+                content="",
+                tool_calls=[
+                    {
+                        "name": "save_memory",
+                        "args": {"content": "Remember LangChain stores"},
+                        "id": "mem1",
+                        "type": "tool_call",
+                    }
+                ],
+            ),
+            AIMessage(content="done"),
+        ]
+    )
+
+    agent = create_agent(model=model, tools=[save_memory], store=store)
+    result = agent.invoke({"messages": [{"role": "user", "content": "save"}]})
+
+    assert model._bound_tool_names == ["save_memory"]
+    assert any("Saved memory" in str(message.content) for message in result["messages"])
+    records = store.search(memory_namespace("project"))
+    assert [item.value["content"] for item in records] == ["Remember LangChain stores"]
+
+
+def test_save_memory_tool_rejects_transient_memory_via_create_agent_runtime() -> None:
+    store = InMemoryStore()
+    model = RecordingFakeModel(
+        responses=[
+            AIMessage(
+                content="",
+                tool_calls=[
+                    {
+                        "name": "save_memory",
+                        "args": {"content": "Currently working on Stage 12D"},
+                        "id": "mem1",
+                        "type": "tool_call",
+                    }
+                ],
+            ),
+            AIMessage(content="done"),
+        ]
+    )
+
+    agent = create_agent(model=model, tools=[save_memory], store=store)
+    result = agent.invoke({"messages": [{"role": "user", "content": "save"}]})
+
+    assert any(
+        "Memory not saved: memory looks like transient task/session state."
+        in str(message.content)
+        for message in result["messages"]
+    )
+    assert store.search(memory_namespace("project")) == []
+
+
+def test_memory_context_middleware_injects_store_backed_memory() -> None:
+    store = InMemoryStore()
+    save_memory_record(
+        store, MemoryRecord(content="Prefer LangChain stores for memory")
+    )
+    runtime = SimpleNamespace(store=store)
+    captured: dict[str, object] = {}
+
+    def handler(request: ModelRequest):
+        captured["system_message"] = request.system_message
+        return SimpleNamespace(result="ok")
+
+    middleware = MemoryContextMiddleware()
+    request = ModelRequest(
+        model=RecordingFakeModel(responses=[]),
+        messages=[HumanMessage(content="LangChain memory question")],
+        system_message=SystemMessage(content="Base"),
+        tool_choice=None,
+        tools=[],
+        response_format=None,
+        state={"messages": []},
+        runtime=runtime,  # type: ignore[arg-type]
+        model_settings={},
+    )
+
+    middleware.wrap_model_call(request, handler)
+
+    system_message = captured["system_message"]
+    assert isinstance(system_message, SystemMessage)
+    assert "Relevant long-term memory" in str(system_message.content)
+    assert "Prefer LangChain stores for memory" in str(system_message.content)
+
+
+def test_memory_context_payload_renderer_path_is_shared() -> None:
+    blocks = merge_system_message_content(
+        [{"type": "text", "text": "Base"}],
+        [
+            ContextPayload(
+                kind="memory",
+                text="Relevant long-term memory:\n- [project] Prefer LangChain stores for memory",
+                source="memory.project",
+                priority=200,
+            )
+        ],
+    )
+
+    assert blocks == [
+        {"type": "text", "text": "Base"},
+        {
+            "type": "text",
+            "text": "Relevant long-term memory:\n- [project] Prefer LangChain stores for memory",
+        },
+    ]
+
+
+def test_memory_context_middleware_respects_namespace_scope() -> None:
+    store = InMemoryStore()
+    save_memory_record(
+        store, MemoryRecord(content="Project memory", namespace="project")
+    )
+    save_memory_record(store, MemoryRecord(content="User memory", namespace="user"))
+    runtime = SimpleNamespace(store=store)
+    captured: dict[str, object] = {}
+
+    def handler(request: ModelRequest):
+        captured["system_message"] = request.system_message
+        return SimpleNamespace(result="ok")
+
+    middleware = MemoryContextMiddleware(namespace="user")
+    request = ModelRequest(
+        model=RecordingFakeModel(responses=[]),
+        messages=[HumanMessage(content="user memory question")],
+        system_message=SystemMessage(content="Base"),
+        tool_choice=None,
+        tools=[],
+        response_format=None,
+        state={"messages": []},
+        runtime=runtime,  # type: ignore[arg-type]
+        model_settings={},
+    )
+
+    middleware.wrap_model_call(request, handler)
+
+    system_message = captured["system_message"]
+    assert isinstance(system_message, SystemMessage)
+    text = str(system_message.content)
+    assert "User memory" in text
+    assert "Project memory" not in text
+
+
+def test_app_container_wires_memory_middleware_and_store() -> None:
+    captured: dict[str, object] = {}
+
+    def fake_create_agent(**kwargs):
+        captured.update(kwargs)
+        return object()
+
+    container = AppContainer(
+        settings=Settings(store_backend="memory"),
+        model=object,
+        create_agent_factory=fake_create_agent,
+    )
+
+    assert container.agent() is not None
+    middleware_names = [
+        type(item).__name__ for item in cast(Sequence[object], captured["middleware"])
+    ]
+    assert middleware_names == [
+        "PlanContextMiddleware",
+        "MemoryContextMiddleware",
+        "ToolGuardMiddleware",
+    ]
+    assert captured["store"] is not None
+
+
+def test_resume_todo_and_memory_context_compose_without_duplication() -> None:
+    store = InMemoryStore()
+    save_memory_record(
+        store, MemoryRecord(content="Continue the work by preferring LangChain stores for memory")
+    )
+    runtime = SimpleNamespace(store=store)
+    captured: dict[str, object] = {}
+
+    def final_handler(request: ModelRequest):
+        captured["messages"] = request.messages
+        captured["system_message"] = request.system_message
+        return SimpleNamespace(result="ok")
+
+    request = ModelRequest(
+        model=RecordingFakeModel(responses=[]),
+        messages=[
+            SystemMessage(content="Resumed session context. Use this brief as continuation context."),
+            HumanMessage(content="continue the work"),
+        ],
+        system_message=SystemMessage(content="Base"),
+        tool_choice=None,
+        tools=[],
+        response_format=None,
+        state=cast(
+            Any,
+            {
+                "messages": [],
+                "todos": [
+                    {
+                        "content": "Close Stage 22",
+                        "status": "in_progress",
+                        "activeForm": "Closing Stage 22",
+                    }
+                ],
+                "rounds_since_update": 1,
+            },
+        ),
+        runtime=runtime,  # type: ignore[arg-type]
+        model_settings={},
+    )
+
+    memory_middleware = MemoryContextMiddleware()
+    planning_middleware = PlanContextMiddleware()
+
+    planning_middleware.wrap_model_call(
+        request,
+        lambda planned_request: memory_middleware.wrap_model_call(
+            planned_request, final_handler
+        ),
+    )
+
+    system_message = captured["system_message"]
+    assert isinstance(system_message, SystemMessage)
+    text = str(system_message.content)
+    assert "Base" in text
+    assert "Current session todos:" in text
+    assert "Relevant long-term memory" in text
+    assert text.index("Current session todos:") < text.index("Relevant long-term memory")
+    assert text.count("Resumed session context.") == 0
+    messages = cast(Sequence[object], captured["messages"])
+    assert any("Resumed session context." in str(getattr(message, "content", "")) for message in messages)
diff --git a/coding-deepgent/tests/test_message_projection.py b/coding-deepgent/tests/test_message_projection.py
new file mode 100644
index 000000000..8ba4705df
--- /dev/null
+++ b/coding-deepgent/tests/test_message_projection.py
@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import Any
+
+from coding_deepgent.compact import TRUNCATION_MARKER, project_messages
+
+
+def test_project_messages_merges_only_plain_same_role_text_messages() -> None:
+    messages = [
+        {"role": "user", "content": "first"},
+        {"role": "user", "content": "second"},
+        {"role": "assistant", "content": "third"},
+    ]
+
+    assert project_messages(messages) == [
+        {"role": "user", "content": "first\n\nsecond"},
+        {"role": "assistant", "content": "third"},
+    ]
+
+
+def test_project_messages_preserves_structured_content_and_does_not_merge_it() -> None:
+    messages: list[dict[str, Any]] = [
+        {"role": "user", "content": "plain"},
+        {
+            "role": "user",
+            "content": [{"type": "tool_result", "tool_use_id": "call-1", "content": "ok"}],
+        },
+        {"role": "user", "content": "tail"},
+    ]
+
+    assert project_messages(messages) == messages
+
+
+def test_project_messages_preserves_extra_metadata_by_not_merging() -> None:
+    messages = [
+        {"role": "assistant", "content": "part 1", "id": "m1"},
+        {"role": "assistant", "content": "part 2"},
+    ]
+
+    assert project_messages(messages) == [
+        {"role": "assistant", "content": "part 1", "id": "m1"},
+        {"role": "assistant", "content": "part 2"},
+    ]
+
+
+def test_project_messages_can_apply_per_message_budget() -> None:
+    messages = [{"role": "user", "content": "x" * 120}]
+
+    projected = project_messages(messages, max_chars_per_message=len(TRUNCATION_MARKER) + 5)
+
+    assert projected == [
+        {"role": "user", "content": "xxxxx" + TRUNCATION_MARKER},
+    ]
diff --git a/coding-deepgent/tests/test_permissions.py b/coding-deepgent/tests/test_permissions.py
new file mode 100644
index 000000000..fa7edef4f
--- /dev/null
+++ b/coding-deepgent/tests/test_permissions.py
@@ -0,0 +1,302 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import cast
+
+import pytest
+from pydantic import ValidationError
+
+from coding_deepgent.permissions import (
+    PermissionManager,
+    PermissionMode,
+    PermissionRule,
+    PermissionRuleSpec,
+    ToolPermissionSubject,
+    expand_rule_specs,
+)
+from coding_deepgent.filesystem.policy import pattern_policy
+from coding_deepgent.tool_system import ToolPolicy, ToolPolicyCode, build_default_registry
+from coding_deepgent.settings import Settings
+
+READ = ToolPermissionSubject(
+    name="read_file",
+    read_only=True,
+    destructive=False,
+    domain="filesystem",
+    source="builtin",
+    trusted=True,
+)
+WRITE = ToolPermissionSubject(
+    name="write_file",
+    read_only=False,
+    destructive=True,
+    domain="filesystem",
+    source="builtin",
+    trusted=True,
+)
+BASH = ToolPermissionSubject(
+    name="bash",
+    read_only=False,
+    destructive=True,
+    domain="filesystem",
+    source="builtin",
+    trusted=True,
+)
+TODO = ToolPermissionSubject(
+    name="TodoWrite",
+    read_only=False,
+    destructive=False,
+    domain="todo",
+    source="builtin",
+    trusted=True,
+)
+UNTRUSTED_EXTENSION_WRITE = ToolPermissionSubject(
+    name="mcp__docs__write",
+    read_only=False,
+    destructive=True,
+    domain="mcp",
+    source="mcp:docs",
+    trusted=False,
+)
+READONLY_EXTENSION = ToolPermissionSubject(
+    name="mcp__docs__lookup",
+    read_only=True,
+    destructive=False,
+    domain="mcp",
+    source="mcp:docs",
+    trusted=False,
+)
+
+
+def decision(
+    mode: str,
+    subject: ToolPermissionSubject,
+    args: dict[str, object] | None = None,
+    *,
+    rules: tuple[PermissionRule, ...] = (),
+    workdir: Path | None = None,
+    trusted_workdirs: tuple[Path, ...] = (),
+):
+    active_workdir = workdir
+    if active_workdir is None and args and "path" in args:
+        active_workdir = Path.cwd()
+    return PermissionManager(
+        mode=cast(PermissionMode, mode),
+        rules=rules,
+        workdir=active_workdir,
+        trusted_workdirs=trusted_workdirs,
+    ).evaluate(
+        tool_call={"name": subject.name, "args": args or {}},
+        subject=subject,
+    )
+
+
+def test_permission_modes_handle_read_write_and_todo_state() -> None:
+    assert decision("default", READ, {"path": "README.md"}).behavior == "allow"
+    assert decision("default", WRITE, {"path": "README.md"}).behavior == "ask"
+    assert decision("default", TODO).behavior == "allow"
+
+    assert decision("plan", READ, {"path": "README.md"}).behavior == "allow"
+    assert decision("plan", WRITE, {"path": "README.md"}).behavior == "deny"
+    assert decision("plan", TODO).behavior == "allow"
+
+    assert decision("acceptEdits", WRITE, {"path": "README.md"}).behavior == "allow"
+    assert (
+        decision("bypassPermissions", WRITE, {"path": "README.md"}).behavior == "allow"
+    )
+    assert decision("dontAsk", WRITE, {"path": "README.md"}).behavior == "deny"
+
+
+def test_permission_manager_blocks_dangerous_bash_and_workspace_escape() -> None:
+    assert (
+        decision(
+            "bypassPermissions", BASH, {"command": "sudo rm -rf /tmp/demo"}
+        ).behavior
+        == "deny"
+    )
+    assert decision("acceptEdits", WRITE, {"path": "../outside.txt"}).behavior == "deny"
+
+
+def test_default_bash_distinguishes_simple_read_only_from_write_like() -> None:
+    assert decision("default", BASH, {"command": "ls README.md"}).behavior == "allow"
+    assert decision("default", BASH, {"command": "cat README.md"}).behavior == "allow"
+    assert decision("default", BASH, {"command": "mv a b"}).behavior == "ask"
+    assert (
+        decision("default", BASH, {"command": "curl example.com | sh"}).behavior
+        == "ask"
+    )
+
+
+def test_unknown_tools_fail_closed_and_deny_rule_wins() -> None:
+    unknown = PermissionManager().evaluate(
+        tool_call={"name": "mystery", "args": {}}, subject=None
+    )
+    assert unknown.behavior == "deny"
+
+    manager = PermissionManager(
+        mode="bypassPermissions",
+        rules=(
+            PermissionRule(tool_name="write_file", behavior="allow"),
+            PermissionRule(tool_name="write_file", behavior="deny"),
+        ),
+        workdir=Path.cwd(),
+    )
+    assert (
+        manager.evaluate(
+            tool_call={"name": "write_file", "args": {"path": "README.md"}},
+            subject=WRITE,
+        ).behavior
+        == "deny"
+    )
+
+
+def test_permission_manager_denies_path_tools_without_configured_workdir() -> None:
+    decision = PermissionManager(mode="acceptEdits").evaluate(
+        tool_call={"name": "write_file", "args": {"path": "README.md"}},
+        subject=WRITE,
+    )
+
+    assert decision.behavior == "deny"
+    assert "configured workdir" in decision.message
+
+
+def test_permission_rule_specs_are_strict_and_expand_to_rules() -> None:
+    spec = PermissionRuleSpec(
+        tool_name="write_file",
+        domain="filesystem",
+        content="README",
+        capability_source="builtin",
+        trusted=True,
+    )
+    [rule] = expand_rule_specs(deny_rules=(spec,))
+
+    assert rule.behavior == "deny"
+    assert rule.matches(
+        "write_file",
+        {"path": "README.md"},
+        domain="filesystem",
+        capability_source="builtin",
+        trusted=True,
+    )
+    assert not rule.matches(
+        "write_file",
+        {"path": "README.md"},
+        domain="mcp",
+        capability_source="mcp:docs",
+        trusted=False,
+    )
+
+    with pytest.raises(ValidationError):
+        PermissionRuleSpec(tool_name="write_file", extra_field=True)  # type: ignore[call-arg]
+
+
+def test_settings_normalize_trusted_workdirs_and_rules(tmp_path: Path) -> None:
+    settings = Settings(
+        workdir=tmp_path,
+        trusted_workdirs=(Path("shared"), tmp_path / "absolute-shared"),
+        permission_deny_rules=(
+            PermissionRuleSpec(tool_name="write_file", domain="filesystem"),
+        ),
+    )
+
+    assert settings.trusted_workdirs == (
+        (tmp_path / "shared").resolve(),
+        (tmp_path / "absolute-shared").resolve(),
+    )
+    assert settings.permission_deny_rules[0].tool_name == "write_file"
+
+
+def test_trusted_workdirs_allow_explicit_extra_root_only() -> None:
+    workdir = Path.cwd()
+    trusted_root = workdir.parent
+
+    assert (
+        decision(
+            "acceptEdits",
+            WRITE,
+            {"path": str(trusted_root / "shared.txt")},
+            workdir=workdir,
+            trusted_workdirs=(trusted_root,),
+        ).behavior
+        == "allow"
+    )
+    assert (
+        decision(
+            "acceptEdits",
+            WRITE,
+            {"path": "/tmp/elsewhere/outside.txt"},
+            workdir=workdir,
+            trusted_workdirs=(trusted_root,),
+        ).behavior
+        == "deny"
+    )
+
+
+def test_untrusted_extension_destructive_actions_require_approval_even_in_accept_modes() -> (
+    None
+):
+    assert (
+        decision(
+            "acceptEdits",
+            UNTRUSTED_EXTENSION_WRITE,
+            {"path": "README.md"},
+        ).behavior
+        == "ask"
+    )
+    assert (
+        decision(
+            "bypassPermissions",
+            UNTRUSTED_EXTENSION_WRITE,
+            {"path": "README.md"},
+        ).behavior
+        == "ask"
+    )
+    assert (
+        decision(
+            "dontAsk",
+            UNTRUSTED_EXTENSION_WRITE,
+            {"path": "README.md"},
+        ).behavior
+        == "deny"
+    )
+    assert (
+        decision(
+            "acceptEdits",
+            READONLY_EXTENSION,
+            {"query": "docs"},
+        ).behavior
+        == "allow"
+    )
+
+
+def test_tool_policy_maps_permission_codes_to_tool_policy_codes() -> None:
+    registry = build_default_registry()
+    policy = ToolPolicy(
+        registry=registry,
+        permission_manager=PermissionManager(mode="plan", workdir=Path.cwd()),
+    )
+
+    read_decision = policy.evaluate(
+        {"name": "read_file", "args": {"path": "README.md"}}
+    )
+    write_decision = policy.evaluate(
+        {"name": "write_file", "args": {"path": "README.md", "content": "x"}}
+    )
+    unknown_decision = policy.evaluate({"name": "no_such_tool", "args": {}})
+
+    assert read_decision.code == ToolPolicyCode.ALLOWED
+    assert write_decision.code == ToolPolicyCode.PERMISSION_DENIED
+    assert unknown_decision.code == ToolPolicyCode.UNKNOWN_TOOL
+
+
+def test_pattern_policy_rejects_absolute_and_parent_escaping_patterns() -> None:
+    absolute = pattern_policy("/tmp/**/*.py")
+    parent = pattern_policy("../outside/**/*.py")
+    nested_parent = pattern_policy("src/**/../secret.txt")
+    allowed = pattern_policy("src/**/*.py")
+
+    assert absolute.allowed is False
+    assert absolute.reason == "workspace_escape"
+    assert parent.allowed is False
+    assert nested_parent.allowed is False
+    assert allowed.allowed is True
diff --git a/coding-deepgent/tests/test_planning.py b/coding-deepgent/tests/test_planning.py
new file mode 100644
index 000000000..77998462f
--- /dev/null
+++ b/coding-deepgent/tests/test_planning.py
@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+from typing import cast
+
+from langchain_core.messages import AIMessage
+from langchain.messages import ToolMessage
+from pydantic import BaseModel, ValidationError
+import pytest
+from langgraph.types import Command
+
+from coding_deepgent.context_payloads import ContextPayload, merge_system_message_content
+from coding_deepgent.middleware.planning import PlanContextMiddleware
+from coding_deepgent.todo.state import PlanningState, TodoItemState
+from coding_deepgent.todo.renderers import reminder_text
+from coding_deepgent.todo.tools import (
+    _todo_write_command,
+    todo_write,
+)
+
+
+def test_todowrite_updates_custom_state_via_command() -> None:
+    command = _todo_write_command(
+        [
+            {
+                "content": "Inspect repo",
+                "status": "completed",
+                "activeForm": "Inspecting",
+            },
+            {
+                "content": "Implement change",
+                "status": "in_progress",
+                "activeForm": "Implementing",
+            },
+        ],
+        tool_call_id="call-1",
+    )
+
+    assert isinstance(command, Command)
+    command_update = command.update
+    assert command_update is not None
+    assert command_update["todos"] == [
+        {"content": "Inspect repo", "status": "completed", "activeForm": "Inspecting"},
+        {
+            "content": "Implement change",
+            "status": "in_progress",
+            "activeForm": "Implementing",
+        },
+    ]
+    assert command_update["rounds_since_update"] == 0
+    assert isinstance(command_update["messages"][0], ToolMessage)
+
+
+def test_todowrite_tool_call_schema_hides_injected_tool_call_id() -> None:
+    tool_call_schema = cast(type[BaseModel], todo_write.tool_call_schema)
+    schema = tool_call_schema.model_json_schema()
+    item_schema = schema["$defs"]["TodoItemInput"]
+
+    assert getattr(todo_write, "name", None) == "TodoWrite"
+    assert schema["required"] == ["todos"]
+    assert "items" not in schema["properties"]
+    assert "tool_call_id" not in schema["properties"]
+    assert item_schema["required"] == ["content", "status", "activeForm"]
+    assert item_schema["additionalProperties"] is False
+
+
+def test_todowrite_rejects_mismatched_json_without_fallback() -> None:
+    with pytest.raises(ValidationError):
+        _todo_write_command([{}], tool_call_id="call-1")
+
+    with pytest.raises(ValidationError):
+        _todo_write_command(
+            [{"task": "Inspect repo", "status": "done", "activeForm": "Inspecting"}],
+            tool_call_id="call-1",
+        )
+
+    with pytest.raises(ValueError, match="tool_call_id is required"):
+        _todo_write_command(
+            [
+                {
+                    "content": "Inspect repo",
+                    "status": "pending",
+                    "activeForm": "Inspecting",
+                }
+            ]
+        )
+
+
+def test_todowrite_requires_active_form_for_every_item() -> None:
+    with pytest.raises(ValidationError):
+        _todo_write_command(
+            [{"content": "Inspect repo", "status": "pending"}], tool_call_id="call-1"
+        )
+
+    with pytest.raises(ValidationError):
+        _todo_write_command(
+            [{"content": "Inspect repo", "status": "pending", "activeForm": "   "}],
+            tool_call_id="call-1",
+        )
+
+
+def test_plan_context_middleware_rejects_parallel_todowrite_calls() -> None:
+    middleware = PlanContextMiddleware()
+
+    state: PlanningState = {
+        "messages": [
+            AIMessage(
+                content="",
+                tool_calls=[
+                    {
+                        "name": "TodoWrite",
+                        "args": {
+                            "todos": [
+                                {
+                                    "content": "Inspect repo",
+                                    "status": "in_progress",
+                                    "activeForm": "Inspecting",
+                                }
+                            ]
+                        },
+                        "id": "call_1",
+                        "type": "tool_call",
+                    },
+                    {
+                        "name": "TodoWrite",
+                        "args": {
+                            "todos": [
+                                {
+                                    "content": "Summarize findings",
+                                    "status": "pending",
+                                    "activeForm": "Summarizing",
+                                }
+                            ]
+                        },
+                        "id": "call_2",
+                        "type": "tool_call",
+                    },
+                ],
+            )
+        ]
+    }
+
+    update = middleware.after_model(state, runtime=None)
+
+    assert update is not None
+    assert len(update["messages"]) == 2
+    assert all(isinstance(message, ToolMessage) for message in update["messages"])
+    assert all(
+        getattr(message, "status", None) == "error" for message in update["messages"]
+    )
+    assert (
+        "should never be called multiple times in parallel"
+        in update["messages"][0].content
+    )
+
+
+def test_plan_context_middleware_tracks_stale_rounds() -> None:
+    middleware = PlanContextMiddleware()
+
+    assert middleware.after_agent(
+        {
+            "messages": [],
+            "todos": [
+                {"content": "Keep going", "status": "pending", "activeForm": "Keeping"}
+            ],
+            "rounds_since_update": 2,
+        },
+        runtime=None,
+    ) == {"rounds_since_update": 3}
+
+    middleware._updated_this_turn = True
+    assert (
+        middleware.after_agent(
+            {
+                "messages": [],
+                "todos": [
+                    {
+                        "content": "Keep going",
+                        "status": "pending",
+                        "activeForm": "Keeping",
+                    }
+                ],
+                "rounds_since_update": 0,
+            },
+            runtime=None,
+        )
+        is None
+    )
+
+
+def test_plan_context_middleware_seeds_missing_defaults() -> None:
+    middleware = PlanContextMiddleware()
+
+    assert middleware.before_agent({"messages": []}, runtime=None) == {
+        "todos": [],
+        "rounds_since_update": 0,
+    }
+
+
+def test_reminder_text_triggers_only_for_stale_plans() -> None:
+    todos: list[TodoItemState] = [
+        {"content": "Keep going", "status": "pending", "activeForm": "Keeping"}
+    ]
+    assert reminder_text(todos, 2) is None
+    assert (
+        reminder_text(todos, 3)
+        == "<reminder>Refresh your current plan before continuing.</reminder>"
+    )
+
+
+def test_todo_context_payload_renderer_path_is_shared() -> None:
+    blocks = merge_system_message_content(
+        [{"type": "text", "text": "Base"}],
+        [
+            ContextPayload(
+                kind="todo",
+                text="Current session todos:\n[ ] Keep going",
+                source="todo.current",
+                priority=100,
+            ),
+            ContextPayload(
+                kind="todo_reminder",
+                text="<reminder>Refresh your current plan before continuing.</reminder>",
+                source="todo.reminder",
+                priority=110,
+            ),
+        ],
+    )
+
+    assert blocks == [
+        {"type": "text", "text": "Base"},
+        {"type": "text", "text": "Current session todos:\n[ ] Keep going"},
+        {
+            "type": "text",
+            "text": "<reminder>Refresh your current plan before continuing.</reminder>",
+        },
+    ]
diff --git a/coding-deepgent/tests/test_planning_renderer.py b/coding-deepgent/tests/test_planning_renderer.py
new file mode 100644
index 000000000..e0554c6e6
--- /dev/null
+++ b/coding-deepgent/tests/test_planning_renderer.py
@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from coding_deepgent.renderers.planning import (
+    TerminalPlanRenderer,
+    reminder_text,
+    render_plan_items,
+)
+from coding_deepgent.todo.state import TodoItemState
+
+
+def test_terminal_plan_renderer_golden_output() -> None:
+    items: list[TodoItemState] = [
+        {"content": "Inspect repo", "status": "completed", "activeForm": "Inspecting"},
+        {
+            "content": "Implement renderer seam",
+            "status": "in_progress",
+            "activeForm": "Implementing",
+        },
+        {"content": "Verify behavior", "status": "pending", "activeForm": "Verifying"},
+    ]
+
+    assert render_plan_items(items) == (
+        "[x] Inspect repo\n"
+        "[>] Implement renderer seam (Implementing)\n"
+        "[ ] Verify behavior\n"
+        "\n"
+        "(1/3 completed)"
+    )
+
+
+def test_terminal_plan_renderer_empty_plan_and_reminder_threshold() -> None:
+    renderer = TerminalPlanRenderer()
+    items: list[TodoItemState] = [
+        {"content": "Keep going", "status": "pending", "activeForm": "Keeping"}
+    ]
+
+    assert renderer.render_plan_items([]) == "No session plan yet."
+    assert reminder_text([], 99) is None
+    assert renderer.reminder_text(items, 2) is None
+    assert renderer.reminder_text(items, 3) == (
+        "<reminder>Refresh your current plan before continuing.</reminder>"
+    )
diff --git a/coding-deepgent/tests/test_plugins.py b/coding-deepgent/tests/test_plugins.py
new file mode 100644
index 000000000..53d4b422c
--- /dev/null
+++ b/coding-deepgent/tests/test_plugins.py
@@ -0,0 +1,265 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+from dependency_injector import providers
+from pydantic import ValidationError
+
+from coding_deepgent.containers import AppContainer
+from coding_deepgent.plugins import (
+    LoadedPluginManifest,
+    PluginManifest,
+    PluginRegistry,
+    ValidatedPluginDeclaration,
+    discover_local_plugins,
+    load_local_plugin,
+    parse_plugin_manifest,
+    plugin_root,
+)
+from coding_deepgent.settings import Settings
+
+
+def write_plugin(root: Path, name: str, payload: dict[str, object]) -> Path:
+    plugin_dir = root / name
+    plugin_dir.mkdir(parents=True)
+    path = plugin_dir / "plugin.json"
+    path.write_text(json.dumps(payload), encoding="utf-8")
+    return path
+
+
+def valid_manifest(name: str = "demo") -> dict[str, object]:
+    return {
+        "name": name,
+        "description": "Demo extension",
+        "version": "1.0.0",
+        "skills": ["demo:review"],
+        "tools": ["read_file"],
+        "resources": ["demo_notes"],
+    }
+
+
+def write_skill(root: Path, name: str = "demo:review") -> None:
+    skill_dir = root / name
+    skill_dir.mkdir(parents=True)
+    (skill_dir / "SKILL.md").write_text(
+        f"---\nname: {name}\ndescription: Demo skill\n---\n\nUse this skill carefully.",
+        encoding="utf-8",
+    )
+
+
+def test_plugin_manifest_schema_is_strict_and_metadata_only() -> None:
+    manifest = PluginManifest.model_validate(valid_manifest())
+
+    assert manifest.name == "demo"
+    assert manifest.skills == ("demo:review",)
+    assert manifest.tools == ("read_file",)
+    assert manifest.resources == ("demo_notes",)
+
+    with pytest.raises(ValidationError):
+        PluginManifest.model_validate({"name": "demo"})
+
+    with pytest.raises(ValidationError):
+        PluginManifest.model_validate({**valid_manifest(), "extra": True})
+
+    for blocked in ("permissionMode", "mcpServers", "hooks", "prompt globals"):
+        with pytest.raises(ValidationError):
+            PluginManifest.model_validate({**valid_manifest(), blocked: []})
+
+
+def test_plugin_manifest_values_are_explicit_local_identifiers() -> None:
+    for payload in (
+        {**valid_manifest(), "tools": ["../read_file"]},
+        {**valid_manifest(), "skills": ["pkg.module.skill"]},
+        {**valid_manifest(), "resources": ["https://example.invalid/r"]},
+        {**valid_manifest(), "tools": ["read_file", "read_file"]},
+    ):
+        with pytest.raises(ValidationError):
+            PluginManifest.model_validate(payload)
+
+
+def test_local_plugin_loader_is_deterministic_and_does_not_execute_code(
+    tmp_path: Path,
+) -> None:
+    root = tmp_path / "plugins"
+    write_plugin(root, "zeta", valid_manifest("zeta"))
+    alpha_path = write_plugin(root, "alpha", valid_manifest("alpha"))
+    (root / "alpha" / "explode.py").write_text(
+        "raise RuntimeError('must not run')",
+        encoding="utf-8",
+    )
+
+    assert plugin_root(tmp_path, Path("plugins")) == root.resolve()
+    assert parse_plugin_manifest(alpha_path).manifest.name == "alpha"
+    assert load_local_plugin(workdir=tmp_path, plugin_dir=Path("plugins"), name="alpha")
+    assert [
+        item.manifest.name
+        for item in discover_local_plugins(workdir=tmp_path, plugin_dir=Path("plugins"))
+    ] == ["alpha", "zeta"]
+
+    with pytest.raises(FileNotFoundError):
+        load_local_plugin(workdir=tmp_path, plugin_dir=Path("plugins"), name="missing")
+
+
+def test_plugin_registry_exposes_declarations_without_runtime_mutation(
+    tmp_path: Path,
+) -> None:
+    root = tmp_path / "plugins"
+    write_plugin(root, "alpha", valid_manifest("alpha"))
+    write_plugin(
+        root,
+        "beta",
+        {
+            **valid_manifest("beta"),
+            "tools": ["TodoWrite"],
+            "skills": [],
+            "resources": ["beta_resource"],
+        },
+    )
+
+    registry = PluginRegistry(
+        discover_local_plugins(workdir=tmp_path, plugin_dir=Path("plugins"))
+    )
+
+    assert registry.names() == ["alpha", "beta"]
+    assert registry.declared_tools() == ("read_file", "TodoWrite")
+    assert registry.declared_skills() == ("demo:review",)
+    assert registry.declared_resources() == ("demo_notes", "beta_resource")
+
+    validated = registry.validate(
+        known_tools={"read_file", "TodoWrite"},
+        known_skills={"demo:review"},
+    )
+    assert isinstance(validated[0], ValidatedPluginDeclaration)
+
+
+def test_plugin_registry_validation_fails_for_unknown_tool_or_skill(
+    tmp_path: Path,
+) -> None:
+    root = tmp_path / "plugins"
+    write_plugin(root, "alpha", valid_manifest("alpha"))
+    registry = PluginRegistry(
+        discover_local_plugins(workdir=tmp_path, plugin_dir=Path("plugins"))
+    )
+
+    with pytest.raises(ValueError, match="unknown entries"):
+        registry.validate(known_tools={"TodoWrite"}, known_skills=set())
+
+
+def test_plugin_registry_rejects_duplicate_plugin_names(tmp_path: Path) -> None:
+    first_path = write_plugin(tmp_path / "plugins-a", "demo", valid_manifest("demo"))
+    second_path = write_plugin(tmp_path / "plugins-b", "demo", valid_manifest("demo"))
+
+    with pytest.raises(ValueError, match="Plugin names must be unique"):
+        PluginRegistry(
+            [
+                LoadedPluginManifest(
+                    manifest=parse_plugin_manifest(first_path).manifest,
+                    root=first_path.parent,
+                    path=first_path,
+                ),
+                LoadedPluginManifest(
+                    manifest=parse_plugin_manifest(second_path).manifest,
+                    root=second_path.parent,
+                    path=second_path,
+                ),
+            ]
+        )
+
+
+def test_plugin_registry_resource_validation_requires_explicit_known_resources(
+    tmp_path: Path,
+) -> None:
+    root = tmp_path / "plugins"
+    write_plugin(root, "alpha", valid_manifest("alpha"))
+    registry = PluginRegistry(
+        discover_local_plugins(workdir=tmp_path, plugin_dir=Path("plugins"))
+    )
+
+    with pytest.raises(ValueError, match="unknown entries"):
+        registry.validate(
+            known_tools={"read_file"},
+            known_skills={"demo:review"},
+            known_resources=set(),
+        )
+
+    validated = registry.validate(
+        known_tools={"read_file"},
+        known_skills={"demo:review"},
+        known_resources={"demo_notes"},
+    )
+    assert validated[0].resources == ("demo_notes",)
+
+
+def test_settings_resolves_plugin_dir_under_workdir(tmp_path: Path) -> None:
+    settings = Settings(workdir=tmp_path, plugin_dir=Path("extensions"))
+
+    assert settings.plugin_dir == (tmp_path / "extensions").resolve()
+
+
+def test_app_container_validates_plugin_declarations_against_known_local_capabilities(
+    tmp_path: Path,
+) -> None:
+    write_skill(tmp_path / "skills")
+    write_plugin(tmp_path / "plugins", "demo", valid_manifest("demo"))
+
+    container = AppContainer(
+        settings=providers.Object(Settings(workdir=tmp_path)),
+        model=providers.Object(object()),
+        create_agent_factory=providers.Object(lambda **kwargs: object()),
+    )
+
+    validated = container.validated_plugin_registry()
+
+    assert validated.names() == ["demo"]
+
+
+def test_app_container_blocks_invalid_plugin_declarations_on_explicit_startup_validation(
+    tmp_path: Path,
+) -> None:
+    write_skill(tmp_path / "skills")
+    write_plugin(
+        tmp_path / "plugins",
+        "demo",
+        {
+            **valid_manifest("demo"),
+            "tools": ["no_such_tool"],
+            "resources": [],
+        },
+    )
+
+    container = AppContainer(
+        settings=providers.Object(Settings(workdir=tmp_path)),
+        model=providers.Object(object()),
+        create_agent_factory=providers.Object(lambda **kwargs: object()),
+    )
+
+    with pytest.raises(ValueError, match="unknown entries"):
+        container.startup_contract()
+    with pytest.raises(ValueError, match="unknown entries"):
+        container.agent()
+
+
+def test_child_only_tools_are_not_plugin_declarable(
+    tmp_path: Path,
+) -> None:
+    write_skill(tmp_path / "skills")
+    write_plugin(
+        tmp_path / "plugins",
+        "demo",
+        {
+            **valid_manifest("demo"),
+            "tools": ["glob"],
+            "resources": [],
+        },
+    )
+
+    container = AppContainer(
+        settings=providers.Object(Settings(workdir=tmp_path)),
+        model=providers.Object(object()),
+        create_agent_factory=providers.Object(lambda **kwargs: object()),
+    )
+
+    with pytest.raises(ValueError, match="unknown entries"):
+        container.startup_contract()
diff --git a/coding-deepgent/tests/test_prompting.py b/coding-deepgent/tests/test_prompting.py
new file mode 100644
index 000000000..37fb658d3
--- /dev/null
+++ b/coding-deepgent/tests/test_prompting.py
@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from coding_deepgent.agent_service import build_system_prompt
+from coding_deepgent.prompting import build_prompt_context
+from coding_deepgent.settings import Settings
+
+
+def test_prompt_context_splits_system_user_and_system_context() -> None:
+    context = build_prompt_context(
+        workdir=Path("/tmp/project"),
+        agent_name="coding-deepgent",
+        session_id="session-1",
+        entrypoint="coding-deepgent",
+    )
+
+    assert context.user_context == {"session_id": "session-1"}
+    assert context.system_context == {
+        "workdir": "/tmp/project",
+        "entrypoint": "coding-deepgent",
+        "agent_name": "coding-deepgent",
+    }
+    assert "coding-deepgent" in context.system_prompt
+    assert "write_file" not in context.system_prompt
+
+
+def test_prompt_context_supports_settings_backed_custom_and_append_prompt() -> None:
+    context = build_prompt_context(
+        workdir=Path("/tmp/project"),
+        agent_name="coding-deepgent",
+        session_id="session-1",
+        entrypoint="coding-deepgent",
+        custom_system_prompt="Custom base",
+        append_system_prompt="Appendix",
+    )
+
+    assert context.default_system_prompt == ("Custom base",)
+    assert context.system_prompt == "Custom base\n\nAppendix"
+
+
+def test_build_system_prompt_respects_settings_backed_layering() -> None:
+    settings = Settings(
+        workdir=Path("/tmp/project"),
+        custom_system_prompt="Custom base",
+        append_system_prompt="Appendix",
+        agent_name="coding-deepgent",
+        entrypoint="coding-deepgent",
+    )
+
+    assert build_system_prompt(settings) == "Custom base\n\nAppendix"
diff --git a/coding-deepgent/tests/test_renderers.py b/coding-deepgent/tests/test_renderers.py
new file mode 100644
index 000000000..28beb1c6a
--- /dev/null
+++ b/coding-deepgent/tests/test_renderers.py
@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from coding_deepgent.renderers.text import (
+    render_config_table,
+    render_doctor_table,
+    render_session_table,
+)
+
+
+def test_render_config_table_contains_key_value_rows() -> None:
+    output = render_config_table(
+        [
+            ("workdir", "/tmp/work"),
+            ("openai_api_key", "<set>"),
+        ]
+    )
+
+    assert "Configuration" in output
+    assert "workdir" in output
+    assert "/tmp/work" in output
+    assert "openai_api_key" in output
+    assert "<set>" in output
+
+
+def test_render_session_table_handles_empty_and_rows() -> None:
+    assert render_session_table([]) == "No sessions recorded yet."
+
+    output = render_session_table(
+        [
+            {
+                "session_id": "session-1",
+                "updated_at": "2026-04-13T00:00:00Z",
+                "message_count": 3,
+                "workdir": "/tmp/work",
+            }
+        ]
+    )
+
+    assert "Sessions" in output
+    assert "session-1" in output
+    assert "2026-04-13T00:00:00Z" in output
+    assert "/tmp/work" in output
+
+
+def test_render_doctor_table_lists_check_statuses() -> None:
+    output = render_doctor_table(
+        [
+            {"name": "typer", "status": "installed", "detail": "CLI command surface."},
+            {
+                "name": "openai_api_key",
+                "status": "<set>",
+                "detail": "Required for live calls.",
+            },
+        ]
+    )
+
+    assert "Doctor" in output
+    assert "typer" in output
+    assert "installed" in output
+    assert "openai_api_key" in output
+    assert "<set>" in output
diff --git a/coding-deepgent/tests/test_rendering.py b/coding-deepgent/tests/test_rendering.py
new file mode 100644
index 000000000..183caf064
--- /dev/null
+++ b/coding-deepgent/tests/test_rendering.py
@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from coding_deepgent.rendering import extract_text, normalize_messages
+
+
+def test_extract_text_reads_block_lists() -> None:
+    content = [
+        {"type": "text", "text": "alpha"},
+        {"type": "output_text", "text": "beta"},
+        {"type": "ignored", "content": "gamma"},
+    ]
+
+    assert extract_text(content) == "alpha\nbeta\ngamma"
+
+
+def test_normalize_messages_merges_visible_history() -> None:
+    messages = [
+        {"role": "user", "content": "first"},
+        {"role": "user", "content": "second"},
+        {"role": "assistant", "content": "third"},
+        {"role": "assistant", "content": "fourth"},
+    ]
+
+    assert normalize_messages(messages) == [
+        {"role": "user", "content": "first\n\nsecond"},
+        {"role": "assistant", "content": "third\n\nfourth"},
+    ]
+
+
+def test_normalize_messages_keeps_projection_contract_under_mixed_inputs() -> None:
+    messages: list[dict[str, object]] = [
+        {"role": "user", "content": "first"},
+        {"role": "user", "content": "second"},
+        {
+            "role": "assistant",
+            "content": [{"type": "text", "text": "structured"}],
+        },
+        {"role": "assistant", "content": "plain", "id": "m1"},
+        {"role": "assistant", "content": "x" * 120},
+    ]
+
+    normalized = normalize_messages(messages)
+
+    assert normalized[:2] == [
+        {"role": "user", "content": "first\n\nsecond"},
+        {"role": "assistant", "content": [{"type": "text", "text": "structured"}]},
+    ]
+    assert normalized[2] == {"role": "assistant", "content": "plain", "id": "m1"}
+    assert normalized[3] == {"role": "assistant", "content": "x" * 120}
diff --git a/coding-deepgent/tests/test_runtime_foundation_contract.py b/coding-deepgent/tests/test_runtime_foundation_contract.py
new file mode 100644
index 000000000..1067a822d
--- /dev/null
+++ b/coding-deepgent/tests/test_runtime_foundation_contract.py
@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import ast
+import json
+import re
+import tomllib
+from pathlib import Path
+from collections.abc import Mapping
+from typing import cast
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[1]
+SRC = ROOT / "src" / "coding_deepgent"
+README = ROOT / "README.md"
+PYPROJECT = ROOT / "pyproject.toml"
+STAGE_3 = "stage-3-professional-domain-runtime-foundation"
+STAGE_4 = "stage-4-control-plane-foundation"
+STAGE_5 = "stage-5-memory-context-compact-foundation"
+STAGE_6 = "stage-6-skills-subagents-task-graph"
+STAGE_7 = "stage-7-mcp-plugin-extension-foundation"
+STAGE_8 = "stage-8-recovery-evidence-runtime-continuation"
+STAGE_9 = "stage-9-permission-trust-boundary-hardening"
+STAGE_10 = "stage-10-hooks-lifecycle-expansion"
+STAGE_11 = "stage-11-mcp-plugin-real-loading"
+FUTURE_SESSION_DOMAINS = (
+    "tasks",
+    "subagents",
+)
+FUTURE_TOOL_SYSTEM_DOMAINS = (
+    "tasks",
+    "subagents",
+)
+FORBIDDEN_RUNTIME_DEPENDENCIES = {
+    "fastapi",
+    "plug" + "gy",
+    "open" + "telemetry",
+    "sqlalchemy",
+    "alembic",
+}
+
+
+def _status() -> dict[str, object]:
+    return json.loads((ROOT / "project_status.json").read_text(encoding="utf-8"))
+
+
+def _is_runtime_foundation_or_later() -> bool:
+    return _status()["current_product_stage"] in {
+        STAGE_3,
+        STAGE_4,
+        STAGE_5,
+        STAGE_6,
+        STAGE_7,
+        STAGE_8,
+        STAGE_9,
+        STAGE_10,
+        STAGE_11,
+    }
+
+
+def _require_runtime_foundation_or_later() -> None:
+    if not _is_runtime_foundation_or_later():
+        pytest.skip(
+            "runtime foundation contract activates only after "
+            "the stage marker is selected"
+        )
+
+
+def _pyproject() -> dict[str, object]:
+    with PYPROJECT.open("rb") as handle:
+        return tomllib.load(handle)
+
+
+def _dependency_names(group: str) -> set[str]:
+    project = cast(Mapping[str, object], _pyproject()["project"])
+    if group == "dependencies":
+        raw = project.get("dependencies", [])
+    else:
+        optional = cast(Mapping[str, object], project.get("optional-dependencies", {}))
+        raw = optional.get(group, [])
+    dependencies = cast(list[str], raw)
+    return {
+        re.split(r"[<>=!~;\[\s]", spec, maxsplit=1)[0].lower() for spec in dependencies
+    }
+
+
+def _module_name(path: Path) -> str:
+    return ".".join(("coding_deepgent", *path.relative_to(SRC).with_suffix("").parts))
+
+
+def _imported_modules(path: Path) -> set[str]:
+    tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+    imported: set[str] = set()
+    package_parts = _module_name(path).split(".")[:-1]
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            imported.update(alias.name for alias in node.names)
+        elif isinstance(node, ast.ImportFrom):
+            if node.level == 0:
+                module = node.module or ""
+            else:
+                trim = max(0, node.level - 1)
+                anchor = package_parts[: len(package_parts) - trim]
+                module = (
+                    ".".join([*anchor, *(node.module.split("."))])
+                    if node.module
+                    else ".".join(anchor)
+                )
+            if module:
+                imported.add(module)
+
+    return imported
+
+
+def _assert_no_import_prefix(paths: list[Path], prefixes: tuple[str, ...]) -> list[str]:
+    offenders: list[str] = []
+    for path in paths:
+        for module in _imported_modules(path):
+            if module.startswith(prefixes):
+                offenders.append(f"{path.relative_to(ROOT)} -> {module}")
+    return offenders
+
+
+def test_readme_stage_metadata_matches_project_status() -> None:
+    status = _status()
+    readme = README.read_text(encoding="utf-8")
+
+    assert str(status["current_product_stage"]) in readme
+    assert str(status["compatibility_anchor"]) in readme
+
+
+def test_runtime_foundation_dependency_contracts() -> None:
+    runtime_dependencies = _dependency_names("dependencies")
+    dev_dependencies = _dependency_names("dev")
+
+    if _is_runtime_foundation_or_later():
+        assert {
+            "dependency-injector",
+            "pydantic-settings",
+            "typer",
+            "rich",
+            "structlog",
+        } <= runtime_dependencies
+        assert {"ruff", "mypy"} <= dev_dependencies
+        assert runtime_dependencies.isdisjoint(FORBIDDEN_RUNTIME_DEPENDENCIES)
+        return
+
+    assert {"langchain", "langchain-openai", "python-dotenv"} <= runtime_dependencies
+    assert "pytest" in dev_dependencies
+
+
+def test_no_forbidden_runtime_foundation_mirror_modules_or_custom_tool_base() -> None:
+    forbidden_paths = (
+        SRC / "runtime" / "query.py",
+        SRC / ("tool_" + "executor.py"),
+        SRC / ("app_state_" + "store.py"),
+    )
+    missing = [path for path in forbidden_paths if path.exists()]
+    assert missing == []
+
+    offenders: list[str] = []
+    for path in SRC.rglob("*.py"):
+        tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ClassDef) and node.name == "Tool":
+                offenders.append(str(path.relative_to(ROOT)))
+
+    assert offenders == []
+
+
+def test_stage3_domain_packages_do_not_import_containers() -> None:
+    _require_runtime_foundation_or_later()
+
+    domain_paths = [
+        *sorted((SRC / "todo").rglob("*.py")),
+        *sorted((SRC / "filesystem").rglob("*.py")),
+        *sorted((SRC / "sessions").rglob("*.py")),
+        *sorted((SRC / "tool_system").rglob("*.py")),
+        *sorted((SRC / "permissions").rglob("*.py")),
+        *sorted((SRC / "hooks").rglob("*.py")),
+        *sorted((SRC / "prompting").rglob("*.py")),
+        *sorted((SRC / "memory").rglob("*.py")),
+        *sorted((SRC / "compact").rglob("*.py")),
+        *sorted((SRC / "skills").rglob("*.py")),
+        *sorted((SRC / "tasks").rglob("*.py")),
+        *sorted((SRC / "subagents").rglob("*.py")),
+        *sorted((SRC / "mcp").rglob("*.py")),
+        *sorted((SRC / "plugins").rglob("*.py")),
+    ]
+
+    offenders = _assert_no_import_prefix(domain_paths, ("coding_deepgent.containers",))
+    assert offenders == []
+
+
+def test_stage3_ui_imports_stay_out_of_domain_core_modules() -> None:
+    _require_runtime_foundation_or_later()
+
+    core_paths = [
+        path
+        for path in SRC.rglob("*.py")
+        if path.parent.name
+        in {
+            "todo",
+            "filesystem",
+            "sessions",
+            "tool_system",
+            "permissions",
+            "hooks",
+            "prompting",
+        }
+        and path.name in {"schemas.py", "state.py", "service.py"}
+    ]
+
+    offenders = _assert_no_import_prefix(core_paths, ("rich", "typer"))
+    assert offenders == []
+
+
+def test_stage3_future_domain_boundaries() -> None:
+    _require_runtime_foundation_or_later()
+
+    session_offenders = _assert_no_import_prefix(
+        sorted((SRC / "sessions").rglob("*.py")),
+        tuple(f"coding_deepgent.{domain}" for domain in FUTURE_SESSION_DOMAINS),
+    )
+    tool_system_offenders = _assert_no_import_prefix(
+        sorted((SRC / "tool_system").rglob("*.py")),
+        tuple(f"coding_deepgent.{domain}" for domain in FUTURE_TOOL_SYSTEM_DOMAINS),
+    )
+
+    assert session_offenders == []
+    assert tool_system_offenders == []
+
+
+def test_stage3_pydantic_settings_stays_centralized() -> None:
+    _require_runtime_foundation_or_later()
+
+    offenders = _assert_no_import_prefix(
+        [
+            path
+            for path in SRC.rglob("*.py")
+            if path.relative_to(SRC) != Path("settings.py")
+        ],
+        ("pydantic_settings",),
+    )
+    assert offenders == []
diff --git a/coding-deepgent/tests/test_sessions.py b/coding-deepgent/tests/test_sessions.py
new file mode 100644
index 000000000..243e40005
--- /dev/null
+++ b/coding-deepgent/tests/test_sessions.py
@@ -0,0 +1,661 @@
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from coding_deepgent.sessions import (
+    COMPACT_RECORD_TYPE,
+    EVIDENCE_RECORD_TYPE,
+    JsonlSessionStore,
+    SessionLoadError,
+    build_recovery_brief,
+    render_recovery_brief,
+    resume_session,
+    thread_config_for_session,
+)
+
+
+def test_jsonl_session_roundtrip_preserves_history_state_and_summary(tmp_path) -> None:
+    store = JsonlSessionStore(tmp_path / "sessions-store")
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+
+    context = store.create_session(workdir=workdir, entrypoint="cli")
+    store.append_message(context, role="user", content="plan this", message_index=0)
+    store.append_state_snapshot(context, state={"todos": [], "rounds_since_update": 0})
+    store.append_message(context, role="assistant", content="planned", message_index=1)
+    store.append_state_snapshot(
+        context,
+        state={
+            "todos": [
+                {
+                    "content": "Ship it",
+                    "status": "in_progress",
+                    "activeForm": "Shipping",
+                }
+            ],
+            "rounds_since_update": 0,
+        },
+    )
+
+    loaded = store.load_session(session_id=context.session_id, workdir=workdir)
+    raw_records = [
+        json.loads(line)
+        for line in context.transcript_path.read_text(encoding="utf-8").splitlines()
+    ]
+
+    assert context.transcript_path == store.transcript_path_for(
+        session_id=context.session_id,
+        workdir=workdir,
+    )
+    assert len(raw_records) == 4
+    assert raw_records[0]["record_type"] == "message"
+    assert raw_records[1]["record_type"] == "state_snapshot"
+    assert raw_records[0]["session_id"] == context.session_id
+    assert raw_records[0]["cwd"] == str(workdir.resolve())
+    assert loaded.history == [
+        {"role": "user", "content": "plan this"},
+        {"role": "assistant", "content": "planned"},
+    ]
+    assert loaded.compacted_history == loaded.history
+    assert loaded.compacted_history_source.mode == "raw"
+    assert loaded.compacted_history_source.reason == "no_compacts"
+    assert loaded.compacted_history_source.compact_index is None
+    assert loaded.state == {
+        "todos": [
+            {"content": "Ship it", "status": "in_progress", "activeForm": "Shipping"}
+        ],
+        "rounds_since_update": 0,
+    }
+    assert loaded.summary.session_id == context.session_id
+    assert loaded.summary.first_prompt == "plan this"
+    assert loaded.summary.message_count == 2
+    assert loaded.summary.evidence_count == 0
+    assert loaded.summary.created_at is not None
+    assert loaded.summary.updated_at is not None
+
+
+def test_list_sessions_filters_by_workdir(tmp_path) -> None:
+    store = JsonlSessionStore(tmp_path / "shared-sessions-store")
+    workdir_a = tmp_path / "repo-a"
+    workdir_b = tmp_path / "repo-b"
+    workdir_a.mkdir()
+    workdir_b.mkdir()
+
+    session_a = store.create_session(workdir=workdir_a)
+    store.append_message(session_a, role="user", content="alpha")
+    store.append_state_snapshot(
+        session_a, state={"todos": [], "rounds_since_update": 0}
+    )
+
+    session_b = store.create_session(workdir=workdir_b)
+    store.append_message(session_b, role="user", content="beta")
+    store.append_state_snapshot(
+        session_b, state={"todos": [], "rounds_since_update": 0}
+    )
+
+    listed = store.list_sessions(workdir=workdir_a)
+
+    assert [summary.session_id for summary in listed] == [session_a.session_id]
+    assert listed[0].first_prompt == "alpha"
+
+
+def test_load_session_ignores_corrupt_unknown_and_invalid_later_snapshots(
+    tmp_path,
+) -> None:
+    store = JsonlSessionStore(tmp_path / "sessions-store")
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+
+    context = store.create_session(workdir=workdir)
+    store.append_message(context, role="user", content="resume me")
+    store.append_state_snapshot(
+        context,
+        state={
+            "todos": [
+                {
+                    "content": "Inspect",
+                    "status": "in_progress",
+                    "activeForm": "Inspecting",
+                }
+            ],
+            "rounds_since_update": 3,
+        },
+    )
+
+    with context.transcript_path.open("a", encoding="utf-8") as handle:
+        handle.write("{not-json}\n")
+        handle.write(
+            json.dumps(
+                {
+                    "record_type": "future_record",
+                    "version": 1,
+                    "session_id": context.session_id,
+                    "timestamp": "2026-04-13T00:00:00Z",
+                    "cwd": str(workdir.resolve()),
+                }
+            )
+            + "\n"
+        )
+        handle.write(
+            json.dumps(
+                {
+                    "record_type": "state_snapshot",
+                    "version": 1,
+                    "session_id": "other-session",
+                    "timestamp": "2026-04-13T00:00:01Z",
+                    "cwd": str(workdir.resolve()),
+                    "state": {"todos": [], "rounds_since_update": 99},
+                }
+            )
+            + "\n"
+        )
+        handle.write(
+            json.dumps(
+                {
+                    "record_type": "state_snapshot",
+                    "version": 1,
+                    "session_id": context.session_id,
+                    "timestamp": "2026-04-13T00:00:02Z",
+                    "cwd": str(workdir.resolve()),
+                    "state": {"todos": "bad", "rounds_since_update": "bad"},
+                }
+            )
+            + "\n"
+        )
+
+    loaded = store.load_session(session_id=context.session_id, workdir=workdir)
+
+    assert loaded.history == [{"role": "user", "content": "resume me"}]
+    assert loaded.state == {
+        "todos": [
+            {"content": "Inspect", "status": "in_progress", "activeForm": "Inspecting"}
+        ],
+        "rounds_since_update": 3,
+    }
+
+
+def test_session_evidence_roundtrip_and_recovery_brief(tmp_path) -> None:
+    store = JsonlSessionStore(tmp_path / "sessions-store")
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+
+    context = store.create_session(workdir=workdir)
+    store.append_message(context, role="user", content="ship")
+    store.append_state_snapshot(
+        context,
+        state={
+            "todos": [
+                {
+                    "content": "Implement recovery",
+                    "status": "in_progress",
+                    "activeForm": "Implementing recovery",
+                },
+                {
+                    "content": "Already done",
+                    "status": "completed",
+                    "activeForm": "Completing",
+                },
+            ],
+            "rounds_since_update": 0,
+        },
+    )
+    store.append_evidence(
+        context,
+        kind="verification",
+        summary="targeted tests passed",
+        status="passed",
+        subject="pytest",
+        metadata={"command": "pytest tests/test_sessions.py"},
+    )
+
+    loaded = store.load_session(session_id=context.session_id, workdir=workdir)
+    raw_records = [
+        json.loads(line)
+        for line in context.transcript_path.read_text(encoding="utf-8").splitlines()
+    ]
+    brief = build_recovery_brief(loaded)
+    rendered = render_recovery_brief(brief)
+
+    assert raw_records[-1]["record_type"] == EVIDENCE_RECORD_TYPE
+    assert loaded.summary.evidence_count == 1
+    assert loaded.evidence[0].kind == "verification"
+    assert loaded.evidence[0].status == "passed"
+    assert loaded.evidence[0].summary == "targeted tests passed"
+    assert loaded.evidence[0].metadata == {"command": "pytest tests/test_sessions.py"}
+    assert brief.active_todos == ("Implement recovery",)
+    assert "Already done" not in rendered
+    assert "[passed] verification: targeted tests passed" in rendered
+
+
+def test_recovery_brief_renders_verification_provenance_only(tmp_path) -> None:
+    store = JsonlSessionStore(tmp_path / "sessions-store")
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+
+    context = store.create_session(workdir=workdir)
+    store.append_message(context, role="user", content="resume")
+    store.append_evidence(
+        context,
+        kind="runtime",
+        summary="Prompt completed.",
+        status="completed",
+        metadata={"internal": "hidden"},
+    )
+    store.append_evidence(
+        context,
+        kind="verification",
+        summary="Checked targeted tests.",
+        status="failed",
+        subject="plan-1",
+        metadata={"plan_id": "plan-1", "verdict": "FAIL", "ignored": "value"},
+    )
+
+    rendered = render_recovery_brief(
+        build_recovery_brief(store.load_session(session_id=context.session_id, workdir=workdir))
+    )
+
+    assert "- [completed] runtime: Prompt completed." in rendered
+    assert "internal=hidden" not in rendered
+    assert (
+        "- [failed] verification: Checked targeted tests. (plan=plan-1; verdict=FAIL)"
+        in rendered
+    )
+    assert "ignored=value" not in rendered
+
+
+def test_compact_record_roundtrip_does_not_enter_history(tmp_path) -> None:
+    store = JsonlSessionStore(tmp_path / "sessions-store")
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+
+    context = store.create_session(workdir=workdir, entrypoint="cli")
+    store.append_message(context, role="user", content="start", message_index=0)
+    store.append_compact(
+        context,
+        trigger="manual",
+        summary="Older work was summarized.",
+        original_message_count=2,
+        summarized_message_count=1,
+        kept_message_count=1,
+        metadata={"source": "test"},
+    )
+    store.append_message(context, role="assistant", content="continued", message_index=1)
+
+    loaded = store.load_session(session_id=context.session_id, workdir=workdir)
+    raw_records = [
+        json.loads(line)
+        for line in context.transcript_path.read_text(encoding="utf-8").splitlines()
+    ]
+
+    assert raw_records[1]["record_type"] == COMPACT_RECORD_TYPE
+    assert loaded.history == [
+        {"role": "user", "content": "start"},
+        {"role": "assistant", "content": "continued"},
+    ]
+    assert loaded.compacted_history[0]["role"] == "system"
+    assert loaded.compacted_history[1]["role"] == "user"
+    assert loaded.compacted_history[2] == {"role": "assistant", "content": "continued"}
+    assert loaded.compacted_history_source.mode == "compact"
+    assert loaded.compacted_history_source.reason == "latest_valid_compact"
+    assert loaded.compacted_history_source.compact_index == 0
+    assert loaded.summary.message_count == 2
+    assert loaded.summary.compact_count == 1
+    assert loaded.compacts[0].trigger == "manual"
+    assert loaded.compacts[0].summary == "Older work was summarized."
+    assert loaded.compacts[0].original_message_count == 2
+    assert loaded.compacts[0].summarized_message_count == 1
+    assert loaded.compacts[0].kept_message_count == 1
+    assert loaded.compacts[0].metadata == {"source": "test"}
+    brief = build_recovery_brief(loaded)
+    rendered = render_recovery_brief(brief)
+    assert brief.recent_compacts[0].summary == "Older work was summarized."
+    assert "[manual] Older work was summarized." in rendered
+
+
+def test_load_session_ignores_invalid_compact_records(tmp_path) -> None:
+    store = JsonlSessionStore(tmp_path / "sessions-store")
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+
+    context = store.create_session(workdir=workdir)
+    store.append_message(context, role="user", content="resume me")
+    with context.transcript_path.open("a", encoding="utf-8") as handle:
+        handle.write(
+            json.dumps(
+                {
+                    "record_type": "compact",
+                    "version": 1,
+                    "session_id": context.session_id,
+                    "timestamp": "2026-04-13T00:00:00Z",
+                    "cwd": str(workdir.resolve()),
+                    "trigger": "",
+                    "summary": "bad",
+                    "original_message_count": 1,
+                    "summarized_message_count": 1,
+                    "kept_message_count": 0,
+                }
+            )
+            + "\n"
+        )
+        handle.write(
+            json.dumps(
+                {
+                    "record_type": "compact",
+                    "version": 1,
+                    "session_id": "other",
+                    "timestamp": "2026-04-13T00:00:01Z",
+                    "cwd": str(workdir.resolve()),
+                    "trigger": "manual",
+                    "summary": "foreign",
+                    "original_message_count": 1,
+                    "summarized_message_count": 1,
+                    "kept_message_count": 0,
+                }
+            )
+            + "\n"
+        )
+
+    loaded = store.load_session(session_id=context.session_id, workdir=workdir)
+
+    assert loaded.compacts == []
+    assert loaded.summary.compact_count == 0
+
+
+def test_recovery_brief_limits_recent_compacts_in_original_order(tmp_path) -> None:
+    store = JsonlSessionStore(tmp_path / "sessions-store")
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+
+    context = store.create_session(workdir=workdir)
+    store.append_message(context, role="user", content="resume")
+    for index in range(5):
+        store.append_compact(
+            context,
+            trigger="manual",
+            summary=f"compact-{index}",
+            original_message_count=index + 1,
+            summarized_message_count=index,
+            kept_message_count=1,
+        )
+
+    loaded = store.load_session(session_id=context.session_id, workdir=workdir)
+    brief = build_recovery_brief(loaded, compact_limit=2)
+    rendered = render_recovery_brief(brief)
+
+    assert [item.summary for item in brief.recent_compacts] == [
+        "compact-3",
+        "compact-4",
+    ]
+    assert "[manual] compact-3" in rendered
+    assert "[manual] compact-4" in rendered
+
+
+def test_load_session_compacted_history_falls_back_to_raw_history_on_invalid_tail_range(
+    tmp_path,
+) -> None:
+    store = JsonlSessionStore(tmp_path / "sessions-store")
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+
+    context = store.create_session(workdir=workdir)
+    store.append_message(context, role="user", content="first")
+    store.append_message(context, role="assistant", content="second")
+    store.append_compact(
+        context,
+        trigger="manual",
+        summary="summary",
+        original_message_count=99,
+        summarized_message_count=98,
+        kept_message_count=1,
+    )
+
+    loaded = store.load_session(session_id=context.session_id, workdir=workdir)
+
+    assert loaded.history == [
+        {"role": "user", "content": "first"},
+        {"role": "assistant", "content": "second"},
+    ]
+    assert loaded.compacted_history == loaded.history
+    assert loaded.compacted_history_source.mode == "raw"
+    assert loaded.compacted_history_source.reason == "no_valid_compact"
+    assert loaded.compacted_history_source.compact_index is None
+
+
+def test_load_session_compacted_history_uses_latest_valid_compact_record(
+    tmp_path,
+) -> None:
+    store = JsonlSessionStore(tmp_path / "sessions-store")
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+
+    context = store.create_session(workdir=workdir)
+    store.append_message(context, role="user", content="first", message_index=0)
+    store.append_message(context, role="assistant", content="second", message_index=1)
+    store.append_compact(
+        context,
+        trigger="manual",
+        summary="valid compact",
+        original_message_count=2,
+        summarized_message_count=1,
+        kept_message_count=1,
+    )
+    store.append_compact(
+        context,
+        trigger="manual",
+        summary="invalid compact",
+        original_message_count=99,
+        summarized_message_count=98,
+        kept_message_count=1,
+    )
+
+    loaded = store.load_session(session_id=context.session_id, workdir=workdir)
+
+    assert loaded.compacted_history[0]["role"] == "system"
+    assert "valid compact" in str(loaded.compacted_history[1]["content"])
+    assert "invalid compact" not in str(loaded.compacted_history[1]["content"])
+    assert loaded.compacted_history_source.mode == "compact"
+    assert loaded.compacted_history_source.reason == "latest_valid_compact"
+    assert loaded.compacted_history_source.compact_index == 0
+
+
+def test_load_session_compacted_history_uses_newest_valid_compact_record(
+    tmp_path,
+) -> None:
+    store = JsonlSessionStore(tmp_path / "sessions-store")
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+
+    context = store.create_session(workdir=workdir)
+    store.append_message(context, role="user", content="first", message_index=0)
+    store.append_message(context, role="assistant", content="second", message_index=1)
+    store.append_message(context, role="user", content="third", message_index=2)
+    store.append_compact(
+        context,
+        trigger="manual",
+        summary="older compact",
+        original_message_count=3,
+        summarized_message_count=1,
+        kept_message_count=2,
+    )
+    store.append_compact(
+        context,
+        trigger="manual",
+        summary="newer compact",
+        original_message_count=3,
+        summarized_message_count=2,
+        kept_message_count=1,
+    )
+
+    loaded = store.load_session(session_id=context.session_id, workdir=workdir)
+
+    assert loaded.history == [
+        {"role": "user", "content": "first"},
+        {"role": "assistant", "content": "second"},
+        {"role": "user", "content": "third"},
+    ]
+    assert "newer compact" in str(loaded.compacted_history[1]["content"])
+    assert "older compact" not in str(loaded.compacted_history[1]["content"])
+    assert loaded.compacted_history[-1] == {"role": "user", "content": "third"}
+    assert loaded.compacted_history_source.mode == "compact"
+    assert loaded.compacted_history_source.compact_index == 1
+
+
+def test_recovery_brief_limits_recent_evidence_in_original_order(tmp_path) -> None:
+    store = JsonlSessionStore(tmp_path / "sessions-store")
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+
+    context = store.create_session(workdir=workdir)
+    store.append_message(context, role="user", content="resume")
+    store.append_state_snapshot(
+        context,
+        state={
+            "todos": [
+                {
+                    "content": "Keep context brief",
+                    "status": "pending",
+                    "activeForm": "Keeping context brief",
+                }
+            ],
+            "rounds_since_update": 0,
+        },
+    )
+    for index in range(7):
+        store.append_evidence(
+            context,
+            kind="verification",
+            summary=f"evidence-{index}",
+            status="passed",
+        )
+
+    loaded = store.load_session(session_id=context.session_id, workdir=workdir)
+    brief = build_recovery_brief(loaded, evidence_limit=3)
+
+    assert [item.summary for item in brief.recent_evidence] == [
+        "evidence-4",
+        "evidence-5",
+        "evidence-6",
+    ]
+    assert brief.active_todos == ("Keep context brief",)
+
+
+def test_load_session_ignores_invalid_evidence_records(tmp_path) -> None:
+    store = JsonlSessionStore(tmp_path / "sessions-store")
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+
+    context = store.create_session(workdir=workdir)
+    store.append_message(context, role="user", content="resume me")
+    with context.transcript_path.open("a", encoding="utf-8") as handle:
+        handle.write(
+            json.dumps(
+                {
+                    "record_type": "evidence",
+                    "version": 1,
+                    "session_id": context.session_id,
+                    "timestamp": "2026-04-13T00:00:00Z",
+                    "cwd": str(workdir.resolve()),
+                    "kind": "",
+                    "summary": "bad",
+                    "status": "passed",
+                }
+            )
+            + "\n"
+        )
+        handle.write(
+            json.dumps(
+                {
+                    "record_type": "evidence",
+                    "version": 1,
+                    "session_id": "other",
+                    "timestamp": "2026-04-13T00:00:01Z",
+                    "cwd": str(workdir.resolve()),
+                    "kind": "verification",
+                    "summary": "foreign",
+                    "status": "passed",
+                }
+            )
+            + "\n"
+        )
+
+    loaded = store.load_session(session_id=context.session_id, workdir=workdir)
+
+    assert loaded.evidence == []
+    assert loaded.summary.evidence_count == 0
+
+
+def test_load_session_requires_at_least_one_valid_message(tmp_path) -> None:
+    store = JsonlSessionStore(tmp_path / "sessions-store")
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+
+    context = store.create_session(workdir=workdir)
+    store.append_state_snapshot(context, state={"todos": [], "rounds_since_update": 0})
+
+    with pytest.raises(SessionLoadError, match="No valid session messages found"):
+        store.load_session(session_id=context.session_id, workdir=workdir)
+
+
+def test_load_session_without_snapshot_falls_back_to_default_state(tmp_path) -> None:
+    store = JsonlSessionStore(tmp_path / "sessions-store")
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+
+    context = store.create_session(workdir=workdir)
+    store.append_message(context, role="user", content="hello")
+
+    loaded = store.load_session(session_id=context.session_id, workdir=workdir)
+
+    assert loaded.history == [{"role": "user", "content": "hello"}]
+    assert loaded.state == {"todos": [], "rounds_since_update": 0}
+
+
+def test_resume_session_restores_runtime_state(tmp_path) -> None:
+    store = JsonlSessionStore(tmp_path / "sessions-store")
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+
+    context = store.create_session(workdir=workdir)
+    store.append_message(context, role="user", content="continue")
+    store.append_state_snapshot(
+        context,
+        state={
+            "todos": [
+                {"content": "Ship it", "status": "pending", "activeForm": "Shipping"}
+            ],
+            "rounds_since_update": 2,
+        },
+    )
+
+    runtime_state = {
+        "todos": [{"content": "Wrong", "status": "completed", "activeForm": "Wrong"}]
+    }
+    loaded = resume_session(
+        store,
+        session_id=context.session_id,
+        workdir=workdir,
+        runtime_state=runtime_state,
+    )
+
+    assert loaded.history == [{"role": "user", "content": "continue"}]
+    assert runtime_state == {
+        "todos": [
+            {"content": "Ship it", "status": "pending", "activeForm": "Shipping"}
+        ],
+        "rounds_since_update": 2,
+    }
+    runtime_state["todos"][0]["content"] = "Mutated"
+    assert loaded.state == {
+        "todos": [
+            {"content": "Ship it", "status": "pending", "activeForm": "Shipping"}
+        ],
+        "rounds_since_update": 2,
+    }
+
+
+def test_thread_config_uses_session_id_as_langgraph_thread_id() -> None:
+    assert thread_config_for_session("session-123") == {
+        "configurable": {"thread_id": "session-123"}
+    }
diff --git a/coding-deepgent/tests/test_skills.py b/coding-deepgent/tests/test_skills.py
new file mode 100644
index 000000000..98b4e77ac
--- /dev/null
+++ b/coding-deepgent/tests/test_skills.py
@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from typing import Any, cast
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+from pydantic import ValidationError
+
+from coding_deepgent.skills import LoadSkillInput, load_local_skill, load_skill
+from coding_deepgent.skills.loader import discover_local_skills, parse_skill_markdown
+
+
+def write_skill(root: Path, name: str = "demo") -> None:
+    path = root / name
+    path.mkdir(parents=True)
+    (path / "SKILL.md").write_text(
+        "---\nname: demo\ndescription: Demo skill\n---\n\nUse this skill carefully.",
+        encoding="utf-8",
+    )
+
+
+def test_local_skill_loader_reads_frontmatter_and_body(tmp_path: Path) -> None:
+    write_skill(tmp_path)
+
+    loaded = load_local_skill(workdir=tmp_path.parent, skill_dir=tmp_path, name="demo")
+
+    assert loaded.metadata.name == "demo"
+    assert loaded.metadata.description == "Demo skill"
+    assert "Use this skill" in loaded.body
+
+
+def test_load_skill_tool_is_strict_and_uses_runtime_context(tmp_path: Path) -> None:
+    write_skill(tmp_path)
+    runtime = SimpleNamespace(
+        context=SimpleNamespace(workdir=tmp_path.parent, skill_dir=tmp_path)
+    )
+
+    assert "# Skill: demo" in cast(Any, load_skill).func("demo", runtime)
+    assert load_skill.name == "load_skill"
+    assert (
+        "name"
+        in cast(Any, load_skill.tool_call_schema).model_json_schema()["properties"]
+    )
+
+    with pytest.raises(ValidationError):
+        LoadSkillInput.model_validate({"skill": "demo", "runtime": runtime})
+
+
+def test_skill_loader_rejects_malformed_or_mismatched_skills(tmp_path: Path) -> None:
+    malformed = tmp_path / "bad" / "SKILL.md"
+    malformed.parent.mkdir(parents=True)
+    malformed.write_text("no frontmatter", encoding="utf-8")
+    mismatch_root = tmp_path / "skills"
+    write_skill(mismatch_root, name="actual")
+    (mismatch_root / "actual" / "SKILL.md").write_text(
+        "---\nname: other\ndescription: Demo skill\n---\n\nBody.",
+        encoding="utf-8",
+    )
+
+    with pytest.raises(ValueError, match="missing frontmatter"):
+        parse_skill_markdown(malformed)
+    with pytest.raises(ValueError, match="Skill name mismatch"):
+        load_local_skill(workdir=tmp_path, skill_dir=mismatch_root, name="actual")
+    with pytest.raises(ValueError, match="directory and metadata name"):
+        discover_local_skills(workdir=tmp_path, skill_dir=mismatch_root)
+
+
+def test_loaded_skill_render_truncates_large_skill_body(tmp_path: Path) -> None:
+    write_skill(tmp_path)
+    loaded = load_local_skill(workdir=tmp_path.parent, skill_dir=tmp_path, name="demo")
+    long_skill = type(loaded)(
+        metadata=loaded.metadata,
+        body="x" * 20,
+        path=loaded.path,
+    )
+
+    rendered = long_skill.render(max_chars=5)
+
+    assert rendered.endswith("xxxxx\n...[skill truncated]")
diff --git a/coding-deepgent/tests/test_state.py b/coding-deepgent/tests/test_state.py
new file mode 100644
index 000000000..8e1e39148
--- /dev/null
+++ b/coding-deepgent/tests/test_state.py
@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import pytest
+
+from coding_deepgent.todo.service import normalize_todos
+from coding_deepgent.todo.state import default_session_state
+
+
+def test_default_session_state_matches_todowrite_contract() -> None:
+    assert default_session_state() == {
+        "todos": [],
+        "rounds_since_update": 0,
+    }
+
+
+def test_normalize_todos_rejects_multiple_in_progress_todos() -> None:
+    with pytest.raises(ValueError, match="Only one todo item can be in_progress"):
+        normalize_todos(
+            [
+                {
+                    "content": "Inspect repo",
+                    "status": "in_progress",
+                    "activeForm": "Inspecting",
+                },
+                {
+                    "content": "Implement change",
+                    "status": "in_progress",
+                    "activeForm": "Implementing",
+                },
+            ]
+        )
+
+
+def test_normalize_todos_rejects_empty_content() -> None:
+    with pytest.raises(ValueError, match="value required"):
+        normalize_todos(
+            [{"content": "   ", "status": "pending", "activeForm": "Waiting"}]
+        )
diff --git a/coding-deepgent/tests/test_structure.py b/coding-deepgent/tests/test_structure.py
new file mode 100644
index 000000000..fb453d51d
--- /dev/null
+++ b/coding-deepgent/tests/test_structure.py
@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+import ast
+import json
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+PACKAGE_ROOT = PROJECT_ROOT / "src" / "coding_deepgent"
+STAGE_1 = "stage-1-todowrite-foundation"
+STAGE_3 = "stage-3-professional-domain-runtime-foundation"
+STAGE_4 = "stage-4-control-plane-foundation"
+STAGE_5 = "stage-5-memory-context-compact-foundation"
+STAGE_6 = "stage-6-skills-subagents-task-graph"
+STAGE_7 = "stage-7-mcp-plugin-extension-foundation"
+STAGE_8 = "stage-8-recovery-evidence-runtime-continuation"
+STAGE_9 = "stage-9-permission-trust-boundary-hardening"
+STAGE_10 = "stage-10-hooks-lifecycle-expansion"
+STAGE_11 = "stage-11-mcp-plugin-real-loading"
+TUTORIAL_PACKAGE = "agents_" + "deepagents"
+
+
+def _python_files() -> list[Path]:
+    return sorted(PACKAGE_ROOT.rglob("*.py"))
+
+
+def _status() -> dict[str, object]:
+    return json.loads(
+        (PROJECT_ROOT / "project_status.json").read_text(encoding="utf-8")
+    )
+
+
+def test_project_contains_responsibility_modules() -> None:
+    stage = str(_status()["current_product_stage"])
+    expected = {
+        PROJECT_ROOT / "pyproject.toml",
+        PROJECT_ROOT / "project_status.json",
+    }
+
+    if stage == STAGE_1:
+        expected.update(
+            {
+                PACKAGE_ROOT / "config.py",
+                PACKAGE_ROOT / "state.py",
+                PACKAGE_ROOT / "app.py",
+                PACKAGE_ROOT / "cli.py",
+                PACKAGE_ROOT / "tools" / "filesystem.py",
+                PACKAGE_ROOT / "tools" / "planning.py",
+                PACKAGE_ROOT / "middleware" / "planning.py",
+            }
+        )
+    elif stage in {
+        STAGE_3,
+        STAGE_4,
+        STAGE_5,
+        STAGE_6,
+        STAGE_7,
+        STAGE_8,
+        STAGE_9,
+        STAGE_10,
+        STAGE_11,
+    }:
+        expected.update(
+            {
+                PACKAGE_ROOT / "app.py",
+                PACKAGE_ROOT / "cli.py",
+                PACKAGE_ROOT / "settings.py",
+                PACKAGE_ROOT / "containers" / "__init__.py",
+                PACKAGE_ROOT / "containers" / "app.py",
+                PACKAGE_ROOT / "containers" / "runtime.py",
+                PACKAGE_ROOT / "containers" / "tool_system.py",
+                PACKAGE_ROOT / "containers" / "filesystem.py",
+                PACKAGE_ROOT / "containers" / "todo.py",
+                PACKAGE_ROOT / "containers" / "sessions.py",
+                PACKAGE_ROOT / "runtime" / "__init__.py",
+                PACKAGE_ROOT / "runtime" / "context.py",
+                PACKAGE_ROOT / "runtime" / "state.py",
+                PACKAGE_ROOT / "tool_system" / "__init__.py",
+                PACKAGE_ROOT / "tool_system" / "capabilities.py",
+                PACKAGE_ROOT / "tool_system" / "policy.py",
+                PACKAGE_ROOT / "tool_system" / "middleware.py",
+                PACKAGE_ROOT / "filesystem" / "__init__.py",
+                PACKAGE_ROOT / "filesystem" / "schemas.py",
+                PACKAGE_ROOT / "filesystem" / "tools.py",
+                PACKAGE_ROOT / "todo" / "__init__.py",
+                PACKAGE_ROOT / "todo" / "schemas.py",
+                PACKAGE_ROOT / "todo" / "state.py",
+                PACKAGE_ROOT / "todo" / "tools.py",
+                PACKAGE_ROOT / "todo" / "middleware.py",
+                PACKAGE_ROOT / "todo" / "renderers.py",
+                PACKAGE_ROOT / "sessions" / "__init__.py",
+                PACKAGE_ROOT / "sessions" / "records.py",
+                PACKAGE_ROOT / "sessions" / "store_jsonl.py",
+                PACKAGE_ROOT / "sessions" / "resume.py",
+                PACKAGE_ROOT / "sessions" / "langgraph.py",
+                PACKAGE_ROOT / "permissions" / "__init__.py",
+                PACKAGE_ROOT / "permissions" / "manager.py",
+                PACKAGE_ROOT / "permissions" / "modes.py",
+                PACKAGE_ROOT / "permissions" / "rules.py",
+                PACKAGE_ROOT / "hooks" / "__init__.py",
+                PACKAGE_ROOT / "hooks" / "events.py",
+                PACKAGE_ROOT / "hooks" / "registry.py",
+                PACKAGE_ROOT / "prompting" / "__init__.py",
+                PACKAGE_ROOT / "prompting" / "builder.py",
+                PACKAGE_ROOT / "memory" / "__init__.py",
+                PACKAGE_ROOT / "memory" / "schemas.py",
+                PACKAGE_ROOT / "memory" / "store.py",
+                PACKAGE_ROOT / "memory" / "recall.py",
+                PACKAGE_ROOT / "memory" / "tools.py",
+                PACKAGE_ROOT / "compact" / "__init__.py",
+                PACKAGE_ROOT / "compact" / "budget.py",
+                PACKAGE_ROOT / "skills" / "__init__.py",
+                PACKAGE_ROOT / "skills" / "schemas.py",
+                PACKAGE_ROOT / "skills" / "loader.py",
+                PACKAGE_ROOT / "skills" / "tools.py",
+                PACKAGE_ROOT / "tasks" / "__init__.py",
+                PACKAGE_ROOT / "tasks" / "schemas.py",
+                PACKAGE_ROOT / "tasks" / "store.py",
+                PACKAGE_ROOT / "tasks" / "tools.py",
+                PACKAGE_ROOT / "subagents" / "__init__.py",
+                PACKAGE_ROOT / "subagents" / "schemas.py",
+                PACKAGE_ROOT / "subagents" / "tools.py",
+            }
+        )
+        if stage in {STAGE_3, STAGE_4, STAGE_5, STAGE_6, STAGE_7, STAGE_8, STAGE_9, STAGE_10}:
+            expected.update(
+                {
+                    PACKAGE_ROOT / "config.py",
+                    PACKAGE_ROOT / "state.py",
+                }
+            )
+        if stage in {STAGE_7, STAGE_8, STAGE_9, STAGE_10, STAGE_11}:
+            expected.update(
+                {
+                    PACKAGE_ROOT / "mcp" / "__init__.py",
+                    PACKAGE_ROOT / "mcp" / "schemas.py",
+                    PACKAGE_ROOT / "mcp" / "adapters.py",
+                    PACKAGE_ROOT / "plugins" / "__init__.py",
+                    PACKAGE_ROOT / "plugins" / "schemas.py",
+                    PACKAGE_ROOT / "plugins" / "loader.py",
+                    PACKAGE_ROOT / "plugins" / "registry.py",
+                }
+            )
+        if stage == STAGE_11:
+            expected.update(
+                {
+                    PACKAGE_ROOT / "bootstrap.py",
+                    PACKAGE_ROOT / "agent_runtime_service.py",
+                    PACKAGE_ROOT / "agent_loop_service.py",
+                    PACKAGE_ROOT / "cli_service.py",
+                    PACKAGE_ROOT / "extensions_service.py",
+                    PACKAGE_ROOT / "startup.py",
+                    PACKAGE_ROOT / "filesystem" / "service.py",
+                    PACKAGE_ROOT / "hooks" / "dispatcher.py",
+                    PACKAGE_ROOT / "sessions" / "service.py",
+                }
+            )
+    else:
+        raise AssertionError(f"unexpected product stage: {stage}")
+
+    missing = sorted(
+        str(path.relative_to(PROJECT_ROOT)) for path in expected if not path.exists()
+    )
+    assert not missing, f"missing expected project files: {missing}"
+
+
+def test_project_has_no_public_stage_modules() -> None:
+    staged_modules = sorted(path.name for path in PACKAGE_ROOT.glob("s[0-9][0-9]_*.py"))
+    assert staged_modules == []
+
+
+def test_project_status_declares_product_stage() -> None:
+    marker = _status()
+    stage = str(marker["current_product_stage"])
+
+    assert stage in {
+        STAGE_1,
+        STAGE_3,
+        STAGE_4,
+        STAGE_5,
+        STAGE_6,
+        STAGE_7,
+        STAGE_8,
+        STAGE_9,
+        STAGE_10,
+        STAGE_11,
+    }
+    assert (
+        marker["compatibility_anchor"]
+        == {
+            STAGE_1: "s03",
+            STAGE_3: "professional-domain-runtime-foundation",
+            STAGE_4: "control-plane-foundation",
+            STAGE_5: "memory-context-compact-foundation",
+            STAGE_6: "skills-subagents-task-graph",
+            STAGE_7: "mcp-plugin-extension-foundation",
+            STAGE_8: "recovery-evidence-runtime-continuation",
+            STAGE_9: "permission-trust-boundary-hardening",
+            STAGE_10: "hooks-lifecycle-expansion",
+            STAGE_11: "mcp-plugin-real-loading",
+        }[stage]
+    )
+    assert marker["shape"] == "staged_langchain_cc_product"
+    assert "product-stage plan approval" in str(marker["upgrade_policy"])
+    assert marker["public_entrypoints"] == ["coding-deepgent"]
+
+
+def test_source_tree_stays_independent_from_tutorial_track() -> None:
+    for path in _python_files():
+        tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                names = [alias.name for alias in node.names]
+                assert all(not name.startswith(TUTORIAL_PACKAGE) for name in names), (
+                    path
+                )
+            if isinstance(node, ast.ImportFrom):
+                module = node.module or ""
+                assert not module.startswith(TUTORIAL_PACKAGE), path
diff --git a/coding-deepgent/tests/test_subagents.py b/coding-deepgent/tests/test_subagents.py
new file mode 100644
index 000000000..8df8e5da3
--- /dev/null
+++ b/coding-deepgent/tests/test_subagents.py
@@ -0,0 +1,495 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, cast
+from types import SimpleNamespace
+
+import pytest
+from langgraph.store.memory import InMemoryStore
+from pydantic import ValidationError
+
+from coding_deepgent.hooks import LocalHookRegistry
+from coding_deepgent.runtime import InMemoryEventSink, RuntimeContext
+from coding_deepgent.sessions import JsonlSessionStore, build_recovery_brief, render_recovery_brief
+from coding_deepgent.subagents import tools as subagent_tools
+from coding_deepgent.subagents import (
+    DEFAULT_CHILD_TOOLS,
+    FORBIDDEN_CHILD_TOOLS,
+    RunSubagentInput,
+    VerifierSubagentResult,
+    child_tool_allowlist,
+    run_subagent,
+    run_subagent_task,
+)
+from coding_deepgent.tasks import create_plan, create_task
+
+
+def runtime_with_store(store: InMemoryStore) -> SimpleNamespace:
+    return SimpleNamespace(store=store)
+
+
+def runtime_with_context_and_store(store: InMemoryStore) -> SimpleNamespace:
+    return SimpleNamespace(
+        store=store,
+        context=RuntimeContext(
+            session_id="session-1",
+            workdir=Path.cwd(),
+            trusted_workdirs=(),
+            entrypoint="test",
+            agent_name="coding-deepgent",
+            skill_dir=Path.cwd() / "skills",
+            event_sink=InMemoryEventSink(),
+            hook_registry=LocalHookRegistry(),
+        ),
+        config={"configurable": {"thread_id": "session-1"}},
+    )
+
+
+def runtime_with_recorded_session(
+    store: InMemoryStore,
+    *,
+    session_store: JsonlSessionStore,
+    workdir: Path,
+) -> SimpleNamespace:
+    session_context = session_store.create_session(
+        workdir=workdir,
+        session_id="session-1",
+        entrypoint="test",
+    )
+    session_store.append_message(session_context, role="user", content="start")
+    return SimpleNamespace(
+        store=store,
+        context=RuntimeContext(
+            session_id="session-1",
+            workdir=workdir,
+            trusted_workdirs=(),
+            entrypoint="test",
+            agent_name="coding-deepgent",
+            skill_dir=workdir / "skills",
+            event_sink=InMemoryEventSink(),
+            hook_registry=LocalHookRegistry(),
+            session_context=session_context,
+        ),
+        config={"configurable": {"thread_id": "session-1"}},
+    )
+
+
+def test_subagent_allowlists_are_exact_and_exclude_mutating_tools() -> None:
+    assert child_tool_allowlist("general") == DEFAULT_CHILD_TOOLS
+    assert child_tool_allowlist("verifier") == (
+        *DEFAULT_CHILD_TOOLS,
+        "task_get",
+        "task_list",
+        "plan_get",
+    )
+    assert set(FORBIDDEN_CHILD_TOOLS).isdisjoint(child_tool_allowlist("verifier"))
+
+
+def test_run_subagent_task_uses_fake_factory_synchronously() -> None:
+    store = InMemoryStore()
+    runtime = runtime_with_store(store)
+    task = create_task(store, title="Implement feature")
+    plan = create_plan(
+        store,
+        title="Verification plan",
+        content="Inspect the feature output.",
+        verification="Run pytest tests/test_subagents.py",
+        task_ids=[task.id],
+    )
+    calls: list[tuple[str, tuple[str, ...], str]] = []
+
+    def factory(agent_type, tools):
+        def child(task: str) -> str:
+            calls.append((agent_type, tuple(tools), task))
+            return f"done:{task}"
+
+        return child
+
+    expected_task = "\n".join(
+        [
+            "Verifier task:",
+            "inspect",
+            "",
+            f"Plan ID: {plan.id}",
+            "Plan title: Verification plan",
+            "Verification criteria: Run pytest tests/test_subagents.py",
+            f"Referenced task IDs: {task.id}",
+            "",
+            "Plan content:",
+            "Inspect the feature output.",
+        ]
+    )
+
+    result = run_subagent_task(
+        task="inspect",
+        runtime=cast(Any, runtime),
+        agent_type="verifier",
+        plan_id=plan.id,
+        child_agent_factory=factory,
+    )
+
+    assert result.content == f"done:{expected_task}"
+    assert calls == [
+        (
+            "verifier",
+            ("read_file", "glob", "grep", "task_get", "task_list", "plan_get"),
+            expected_task,
+        )
+    ]
+
+
+def test_run_subagent_tool_schema_rejects_runtime_creep_fields() -> None:
+    runtime = SimpleNamespace()
+    assert "Subagent general accepted" in cast(Any, run_subagent).func(
+        "inspect", runtime
+    )
+    schema = cast(Any, run_subagent.tool_call_schema).model_json_schema()
+    assert set(schema["properties"]) == {"task", "agent_type", "plan_id", "max_turns"}
+
+    with pytest.raises(ValidationError):
+        RunSubagentInput.model_validate(
+            {"task": "x", "background": True, "runtime": runtime}
+        )
+
+
+def test_verifier_subagent_requires_plan_id() -> None:
+    runtime = runtime_with_store(InMemoryStore())
+
+    with pytest.raises(ValueError, match="plan_id"):
+        cast(Any, run_subagent).func(
+            "inspect",
+            runtime,
+            agent_type="verifier",
+        )
+
+
+def test_verifier_subagent_requires_task_store() -> None:
+    runtime = SimpleNamespace(store=None)
+
+    with pytest.raises(RuntimeError, match="task store"):
+        cast(Any, run_subagent).func(
+            "inspect",
+            runtime,
+            agent_type="verifier",
+            plan_id="plan-123",
+        )
+
+
+def test_verifier_subagent_rejects_unknown_plan() -> None:
+    runtime = runtime_with_store(InMemoryStore())
+
+    with pytest.raises(KeyError, match="Unknown plan"):
+        cast(Any, run_subagent).func(
+            "inspect",
+            runtime,
+            agent_type="verifier",
+            plan_id="plan-missing",
+        )
+
+
+def test_run_subagent_task_verifier_executes_real_child_agent(monkeypatch) -> None:
+    store = InMemoryStore()
+    runtime = runtime_with_context_and_store(store)
+    task = create_task(store, title="Implement feature")
+    plan = create_plan(
+        store,
+        title="Verification plan",
+        content="Run the targeted tests and inspect durable task state.",
+        verification="Run pytest tests/test_subagents.py",
+        task_ids=[task.id],
+    )
+    captured: dict[str, Any] = {}
+
+    class FakeChildAgent:
+        def invoke(self, payload: dict[str, Any], **kwargs: Any) -> dict[str, Any]:
+            captured["payload"] = payload
+            captured["invoke_kwargs"] = kwargs
+            return {"messages": [{"role": "assistant", "content": "VERDICT: PASS"}]}
+
+    def fake_create_agent(**kwargs: Any) -> FakeChildAgent:
+        captured["agent_kwargs"] = kwargs
+        return FakeChildAgent()
+
+    monkeypatch.setattr(subagent_tools, "create_agent", fake_create_agent)
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda: object())
+
+    result = run_subagent_task(
+        task="Verify the implementation",
+        runtime=cast(Any, runtime),
+        agent_type="verifier",
+        plan_id=plan.id,
+    )
+
+    assert result.content == "VERDICT: PASS"
+    assert [tool.name for tool in captured["agent_kwargs"]["tools"]] == [
+        "read_file",
+        "glob",
+        "grep",
+        "task_get",
+        "task_list",
+        "plan_get",
+    ]
+    assert "strictly read-only" in captured["agent_kwargs"]["system_prompt"]
+    assert captured["agent_kwargs"]["store"] is store
+    assert captured["agent_kwargs"]["name"] == "coding-deepgent-verifier"
+    assert len(captured["agent_kwargs"]["middleware"]) == 1
+    assert captured["payload"] == {
+        "messages": [
+            {
+                "role": "user",
+                "content": "\n".join(
+                    [
+                        "Verifier task:",
+                        "Verify the implementation",
+                        "",
+                        f"Plan ID: {plan.id}",
+                        "Plan title: Verification plan",
+                        "Verification criteria: Run pytest tests/test_subagents.py",
+                        f"Referenced task IDs: {task.id}",
+                        "",
+                        "Plan content:",
+                        "Run the targeted tests and inspect durable task state.",
+                    ]
+                ),
+            }
+        ]
+    }
+    assert captured["invoke_kwargs"]["context"].entrypoint == "run_subagent:verifier"
+    assert (
+        captured["invoke_kwargs"]["config"]["configurable"]["thread_id"]
+        == f"session-1:verifier:{plan.id}"
+    )
+
+
+def test_run_subagent_task_verifier_uses_durable_plan_payload() -> None:
+    store = InMemoryStore()
+    runtime = runtime_with_store(store)
+    task = create_task(store, title="Implement feature")
+    plan = create_plan(
+        store,
+        title="Verification plan",
+        content="Run the targeted tests and inspect durable task state.",
+        verification="Run pytest tests/test_subagents.py",
+        task_ids=[task.id],
+    )
+    calls: list[tuple[str, tuple[str, ...], str]] = []
+
+    def factory(agent_type, tools):
+        def child(rendered_task: str) -> str:
+            calls.append((agent_type, tuple(tools), rendered_task))
+            return "VERDICT: PASS"
+
+        return child
+
+    result = run_subagent_task(
+        task="Verify the implementation",
+        runtime=cast(Any, runtime),
+        agent_type="verifier",
+        plan_id=plan.id,
+        child_agent_factory=factory,
+    )
+
+    assert result.content == "VERDICT: PASS"
+    assert result.plan_id == plan.id
+    assert result.plan_title == "Verification plan"
+    assert result.verification == "Run pytest tests/test_subagents.py"
+    assert result.task_ids == (task.id,)
+    assert calls == [
+        (
+            "verifier",
+            ("read_file", "glob", "grep", "task_get", "task_list", "plan_get"),
+            "\n".join(
+                [
+                    "Verifier task:",
+                    "Verify the implementation",
+                    "",
+                    f"Plan ID: {plan.id}",
+                    "Plan title: Verification plan",
+                    "Verification criteria: Run pytest tests/test_subagents.py",
+                    f"Referenced task IDs: {task.id}",
+                    "",
+                    "Plan content:",
+                    "Run the targeted tests and inspect durable task state.",
+                ]
+            ),
+        )
+    ]
+
+
+def test_run_subagent_tool_returns_structured_verifier_result(monkeypatch) -> None:
+    store = InMemoryStore()
+    runtime = runtime_with_context_and_store(store)
+    task = create_task(store, title="Implement feature")
+    plan = create_plan(
+        store,
+        title="Verification plan",
+        content="Run the targeted tests and inspect durable task state.",
+        verification="Run pytest tests/test_subagents.py",
+        task_ids=[task.id],
+    )
+
+    monkeypatch.setattr(
+        subagent_tools,
+        "create_agent",
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [{"role": "assistant", "content": "VERDICT: PASS"}]
+            }
+        ),
+    )
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda: object())
+
+    output = cast(Any, run_subagent).func(
+        "Verify the implementation",
+        runtime,
+        agent_type="verifier",
+        plan_id=plan.id,
+    )
+    result = VerifierSubagentResult.model_validate_json(output)
+
+    assert result.agent_type == "verifier"
+    assert result.plan_id == plan.id
+    assert result.plan_title == "Verification plan"
+    assert result.verification == "Run pytest tests/test_subagents.py"
+    assert result.task_ids == [task.id]
+    assert result.tool_allowlist == [
+        "read_file",
+        "glob",
+        "grep",
+        "task_get",
+        "task_list",
+        "plan_get",
+    ]
+    assert result.content == "VERDICT: PASS"
+
+
+def test_verifier_verdict_helpers_map_status_and_summary() -> None:
+    assert subagent_tools.verifier_verdict("Checked output\nVERDICT: PASS") == "PASS"
+    assert subagent_tools.verifier_verdict("VERDICT: fail") == "FAIL"
+    assert subagent_tools.verifier_verdict("VERDICT: PARTIAL") == "PARTIAL"
+    assert subagent_tools.verifier_verdict("looks ok") is None
+    assert (
+        subagent_tools.verifier_evidence_summary(
+            "Checked targeted tests.\nVERDICT: PASS", verdict="PASS"
+        )
+        == "Checked targeted tests."
+    )
+    assert (
+        subagent_tools.verifier_evidence_summary("VERDICT: PASS", verdict="PASS")
+        == "Verifier verdict: PASS"
+    )
+
+
+def test_run_subagent_tool_persists_verifier_evidence_roundtrip(
+    monkeypatch, tmp_path: Path
+) -> None:
+    task_store = InMemoryStore()
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+    session_store = JsonlSessionStore(tmp_path / "sessions")
+    runtime = runtime_with_recorded_session(
+        task_store,
+        session_store=session_store,
+        workdir=workdir,
+    )
+    task = create_task(task_store, title="Implement feature")
+    plan = create_plan(
+        task_store,
+        title="Verification plan",
+        content="Run the targeted tests and inspect durable task state.",
+        verification="Run pytest coding-deepgent/tests/test_subagents.py",
+        task_ids=[task.id],
+    )
+
+    monkeypatch.setattr(
+        subagent_tools,
+        "create_agent",
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [
+                    {
+                        "role": "assistant",
+                        "content": "Checked targeted tests.\nVERDICT: FAIL",
+                    }
+                ]
+            }
+        ),
+    )
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda: object())
+
+    output = cast(Any, run_subagent).func(
+        "Verify the implementation",
+        runtime,
+        agent_type="verifier",
+        plan_id=plan.id,
+    )
+    result = VerifierSubagentResult.model_validate_json(output)
+    loaded = session_store.load_session(session_id="session-1", workdir=workdir)
+    rendered = render_recovery_brief(build_recovery_brief(loaded))
+
+    assert result.content == "Checked targeted tests.\nVERDICT: FAIL"
+    assert loaded.summary.evidence_count == 1
+    assert loaded.evidence[0].kind == "verification"
+    assert loaded.evidence[0].status == "failed"
+    assert loaded.evidence[0].summary == "Checked targeted tests."
+    assert loaded.evidence[0].subject == plan.id
+    assert loaded.evidence[0].metadata == {
+        "plan_id": plan.id,
+        "plan_title": "Verification plan",
+        "verdict": "FAIL",
+        "parent_session_id": "session-1",
+        "parent_thread_id": "session-1",
+        "child_thread_id": f"session-1:verifier:{plan.id}",
+        "verifier_agent_name": "coding-deepgent-verifier",
+        "task_ids": [task.id],
+        "tool_allowlist": [
+            "read_file",
+            "glob",
+            "grep",
+            "task_get",
+            "task_list",
+            "plan_get",
+        ],
+    }
+    assert "[failed] verification: Checked targeted tests." in rendered
+
+
+def test_run_subagent_tool_skips_verifier_evidence_without_recording_context(
+    monkeypatch,
+) -> None:
+    store = InMemoryStore()
+    runtime = runtime_with_context_and_store(store)
+    task = create_task(store, title="Implement feature")
+    plan = create_plan(
+        store,
+        title="Verification plan",
+        content="Run the targeted tests and inspect durable task state.",
+        verification="Run pytest coding-deepgent/tests/test_subagents.py",
+        task_ids=[task.id],
+    )
+
+    monkeypatch.setattr(
+        subagent_tools,
+        "create_agent",
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [
+                    {
+                        "role": "assistant",
+                        "content": "Checked targeted tests.\nVERDICT: PASS",
+                    }
+                ]
+            }
+        ),
+    )
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda: object())
+
+    output = cast(Any, run_subagent).func(
+        "Verify the implementation",
+        runtime,
+        agent_type="verifier",
+        plan_id=plan.id,
+    )
+    result = VerifierSubagentResult.model_validate_json(output)
+
+    assert result.content == "Checked targeted tests.\nVERDICT: PASS"
diff --git a/coding-deepgent/tests/test_tasks.py b/coding-deepgent/tests/test_tasks.py
new file mode 100644
index 000000000..1f3e006ea
--- /dev/null
+++ b/coding-deepgent/tests/test_tasks.py
@@ -0,0 +1,275 @@
+from __future__ import annotations
+
+from typing import Any, cast
+from types import SimpleNamespace
+
+import pytest
+from langgraph.store.memory import InMemoryStore
+from pydantic import ValidationError
+
+from coding_deepgent.tasks import (
+    PlanArtifact,
+    PlanSaveInput,
+    TaskCreateInput,
+    TaskRecord,
+    create_plan,
+    create_task,
+    get_plan,
+    get_task,
+    is_task_ready,
+    plan_get,
+    plan_save,
+    task_create,
+    task_get,
+    task_list,
+    task_namespace,
+    task_graph_needs_verification,
+    task_update,
+    update_task,
+    validate_task_graph,
+)
+
+
+def runtime_with_store(store: InMemoryStore) -> SimpleNamespace:
+    return SimpleNamespace(store=store)
+
+
+def test_task_store_transitions_dependencies_and_ready_rule() -> None:
+    store = InMemoryStore()
+    parent = create_task(store, title="Parent")
+    child = create_task(store, title="Child", depends_on=[parent.id])
+
+    assert is_task_ready(store, child) is False
+    assert (
+        update_task(store, task_id=parent.id, status="in_progress").status
+        == "in_progress"
+    )
+    assert (
+        update_task(store, task_id=parent.id, status="completed").status == "completed"
+    )
+    assert is_task_ready(store, get_task(store, child.id)) is True
+
+    with pytest.raises(ValueError):
+        update_task(store, task_id=parent.id, status="pending")
+
+
+def test_task_graph_rejects_missing_self_and_cycle_dependencies() -> None:
+    store = InMemoryStore()
+    parent = create_task(store, title="Parent")
+    child = create_task(store, title="Child", depends_on=[parent.id])
+
+    with pytest.raises(ValueError, match="Unknown task dependencies"):
+        create_task(store, title="Missing dependency", depends_on=["task-missing"])
+
+    with pytest.raises(ValueError, match="cannot depend on itself"):
+        update_task(store, task_id=child.id, depends_on=[child.id])
+
+    with pytest.raises(ValueError, match="cycle"):
+        update_task(store, task_id=parent.id, depends_on=[child.id])
+
+    store.put(
+        task_namespace(),
+        child.id,
+        child.model_copy(update={"depends_on": [child.id]}).model_dump(),
+    )
+    with pytest.raises(ValueError, match="cannot depend on itself"):
+        validate_task_graph(store)
+
+
+def test_task_update_requires_blocked_reason_or_dependency() -> None:
+    store = InMemoryStore()
+    task = create_task(store, title="Investigate failure")
+    blocker = create_task(store, title="Collect logs")
+
+    with pytest.raises(ValueError, match="blocked tasks require"):
+        update_task(store, task_id=task.id, status="blocked")
+
+    assert (
+        update_task(
+            store,
+            task_id=task.id,
+            status="blocked",
+            metadata={"blocked_reason": "Need logs"},
+        ).status
+        == "blocked"
+    )
+    other = create_task(store, title="Wait on dependency")
+    assert (
+        update_task(
+            store,
+            task_id=other.id,
+            status="blocked",
+            depends_on=[blocker.id],
+        ).depends_on
+        == [blocker.id]
+    )
+
+
+def test_task_graph_needs_verification_after_closing_three_tasks() -> None:
+    store = InMemoryStore()
+    first = create_task(store, title="Implement feature")
+    second = create_task(store, title="Update docs")
+    third = create_task(store, title="Run smoke")
+
+    assert task_graph_needs_verification(store) is False
+    for task in (first, second, third):
+        update_task(store, task_id=task.id, status="in_progress")
+        update_task(store, task_id=task.id, status="completed")
+
+    assert task_graph_needs_verification(store) is True
+
+
+def test_task_graph_with_verification_task_does_not_need_nudge() -> None:
+    store = InMemoryStore()
+    first = create_task(store, title="Implement feature")
+    second = create_task(store, title="Update docs")
+    verify = create_task(store, title="Verify implementation")
+
+    for task in (first, second, verify):
+        update_task(store, task_id=task.id, status="in_progress")
+        update_task(store, task_id=task.id, status="completed")
+
+    assert task_graph_needs_verification(store) is False
+
+
+def test_task_graph_recognizes_metadata_verification_and_ignores_cancelled() -> None:
+    store = InMemoryStore()
+    first = create_task(store, title="Implement feature")
+    second = create_task(store, title="Update docs")
+    cancelled = create_task(store, title="Cancelled side quest")
+    verify = create_task(store, title="Independent review", metadata={"role": "verification"})
+
+    for task in (first, second, verify):
+        update_task(store, task_id=task.id, status="in_progress")
+        update_task(store, task_id=task.id, status="completed")
+    update_task(store, task_id=cancelled.id, status="cancelled")
+
+    assert task_graph_needs_verification(store) is False
+
+
+def test_task_list_defaults_hide_terminal_and_include_terminal_restores_them() -> None:
+    store = InMemoryStore()
+    runtime = runtime_with_store(store)
+    active = create_task(store, title="Active task")
+    completed = create_task(store, title="Completed task")
+    cancelled = create_task(store, title="Cancelled task")
+    update_task(store, task_id=completed.id, status="in_progress")
+    update_task(store, task_id=completed.id, status="completed")
+    update_task(store, task_id=cancelled.id, status="cancelled")
+
+    default_output = cast(Any, task_list).func(runtime)
+    full_output = cast(Any, task_list).func(runtime, include_terminal=True)
+
+    assert active.id in default_output
+    assert completed.id not in default_output
+    assert cancelled.id not in default_output
+    assert active.id in full_output
+    assert completed.id in full_output
+    assert cancelled.id in full_output
+
+
+def test_task_tools_are_strict_and_do_not_mutate_todo_state() -> None:
+    store = InMemoryStore()
+    runtime = runtime_with_store(store)
+
+    created = cast(Any, task_create).func("Implement tests", runtime)
+    task_id = TaskRecord.model_validate_json(created).id
+
+    assert (
+        TaskRecord.model_validate_json(cast(Any, task_get).func(task_id, runtime)).title
+        == "Implement tests"
+    )
+    assert task_id in cast(Any, task_list).func(runtime)
+    assert '"ready":"true"' in cast(Any, task_list).func(runtime)
+    assert (
+        TaskRecord.model_validate_json(
+            cast(Any, task_update).func(
+                task_id, runtime, status="in_progress"
+            )
+        ).status
+        == "in_progress"
+    )
+    assert store.search(task_namespace())
+
+    with pytest.raises(ValidationError):
+        TaskCreateInput.model_validate({"content": "wrong", "runtime": runtime})
+
+
+def test_task_update_tool_marks_verification_nudge_in_output_metadata() -> None:
+    store = InMemoryStore()
+    runtime = runtime_with_store(store)
+    tasks = [
+        create_task(store, title="Implement feature"),
+        create_task(store, title="Update docs"),
+        create_task(store, title="Run smoke"),
+    ]
+    for task in tasks[:2]:
+        update_task(store, task_id=task.id, status="in_progress")
+        update_task(store, task_id=task.id, status="completed")
+    update_task(store, task_id=tasks[2].id, status="in_progress")
+
+    output = cast(Any, task_update).func(
+        tasks[2].id,
+        runtime,
+        status="completed",
+    )
+
+    assert (
+        TaskRecord.model_validate_json(output).metadata["verification_nudge"]
+        == "true"
+    )
+    assert get_task(store, tasks[2].id).metadata == {}
+
+
+def test_plan_artifact_roundtrip_requires_verification_and_known_tasks() -> None:
+    store = InMemoryStore()
+    task = create_task(store, title="Implement feature")
+
+    plan = create_plan(
+        store,
+        title="Implement feature plan",
+        content="Change tasks module.",
+        verification="Run pytest tests/test_tasks.py",
+        task_ids=[task.id],
+    )
+
+    assert get_plan(store, plan.id).verification == "Run pytest tests/test_tasks.py"
+    with pytest.raises(ValidationError):
+        PlanSaveInput.model_validate(
+            {
+                "title": "Plan",
+                "content": "No verification",
+                "verification": "",
+                "runtime": runtime_with_store(store),
+            }
+        )
+    with pytest.raises(ValueError, match="Unknown task dependencies"):
+        create_plan(
+            store,
+            title="Bad plan",
+            content="x",
+            verification="pytest",
+            task_ids=["task-missing"],
+        )
+
+
+def test_plan_tools_save_and_get_artifacts() -> None:
+    store = InMemoryStore()
+    runtime = runtime_with_store(store)
+    task = create_task(store, title="Implement feature")
+
+    saved = cast(Any, plan_save).func(
+        "Plan feature",
+        "Use existing task store.",
+        "Run pytest tests/test_tasks.py",
+        runtime,
+        task_ids=[task.id],
+    )
+    plan_id = PlanArtifact.model_validate_json(saved).id
+
+    assert (
+        PlanArtifact.model_validate_json(
+            cast(Any, plan_get).func(plan_id, runtime)
+        ).verification
+        == "Run pytest tests/test_tasks.py"
+    )
diff --git a/coding-deepgent/tests/test_todo_domain.py b/coding-deepgent/tests/test_todo_domain.py
new file mode 100644
index 000000000..ceddd164e
--- /dev/null
+++ b/coding-deepgent/tests/test_todo_domain.py
@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from coding_deepgent.middleware.planning import (
+    PlanContextMiddleware as CompatibilityMiddleware,
+)
+from coding_deepgent.renderers.planning import (
+    render_plan_items as compatibility_render_plan_items,
+)
+from coding_deepgent.todo import (
+    PlanContextMiddleware,
+    TerminalPlanRenderer,
+    render_plan_items,
+)
+from coding_deepgent.todo.service import normalize_todos
+
+ROOT = Path(__file__).resolve().parents[1]
+TODO_ROOT = ROOT / "src" / "coding_deepgent" / "todo"
+
+
+def test_todo_domain_package_exists_with_expected_modules() -> None:
+    expected = {
+        TODO_ROOT / "__init__.py",
+        TODO_ROOT / "middleware.py",
+        TODO_ROOT / "renderers.py",
+        TODO_ROOT / "schemas.py",
+        TODO_ROOT / "service.py",
+        TODO_ROOT / "state.py",
+        TODO_ROOT / "tools.py",
+    }
+
+    missing = sorted(
+        str(path.relative_to(ROOT)) for path in expected if not path.exists()
+    )
+    assert not missing, f"missing expected todo domain files: {missing}"
+
+
+def test_todo_domain_public_contract_matches_current_owning_modules() -> None:
+    assert CompatibilityMiddleware is PlanContextMiddleware
+    assert compatibility_render_plan_items is render_plan_items
+
+
+def test_todo_domain_renderer_output_stays_stable() -> None:
+    renderer = TerminalPlanRenderer()
+
+    assert renderer.render_plan_items(
+        [
+            {
+                "content": "Inspect repo",
+                "status": "completed",
+                "activeForm": "Inspecting",
+            },
+            {
+                "content": "Implement renderer seam",
+                "status": "in_progress",
+                "activeForm": "Implementing",
+            },
+            {
+                "content": "Verify behavior",
+                "status": "pending",
+                "activeForm": "Verifying",
+            },
+        ]
+    ) == (
+        "[x] Inspect repo\n"
+        "[>] Implement renderer seam (Implementing)\n"
+        "[ ] Verify behavior\n"
+        "\n"
+        "(1/3 completed)"
+    )
+
+
+def test_todo_domain_rejects_overlong_short_term_plan() -> None:
+    todos = [
+        {
+            "content": f"Task {index}",
+            "status": "pending",
+            "activeForm": f"Working {index}",
+        }
+        for index in range(13)
+    ]
+
+    try:
+        normalize_todos(todos)
+    except ValueError as exc:
+        assert "max 12 todos" in str(exc)
+    else:  # pragma: no cover
+        raise AssertionError("normalize_todos should reject more than 12 todos")
+
+
+def test_todo_domain_does_not_import_cross_domain_packages() -> None:
+    offenders: list[str] = []
+
+    for path in sorted(TODO_ROOT.glob("*.py")):
+        tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    if alias.name.startswith(
+                        (
+                            "coding_deepgent.containers",
+                            "coding_deepgent.filesystem",
+                            "coding_deepgent.sessions",
+                        )
+                    ):
+                        offenders.append(f"{path.name}:{alias.name}")
+            elif isinstance(node, ast.ImportFrom):
+                module = node.module or ""
+                if module.startswith(
+                    (
+                        "coding_deepgent.containers",
+                        "coding_deepgent.filesystem",
+                        "coding_deepgent.sessions",
+                    )
+                ):
+                    offenders.append(f"{path.name}:{module}")
+
+    assert offenders == []
diff --git a/coding-deepgent/tests/test_tool_system_middleware.py b/coding-deepgent/tests/test_tool_system_middleware.py
new file mode 100644
index 000000000..d8801ee5e
--- /dev/null
+++ b/coding-deepgent/tests/test_tool_system_middleware.py
@@ -0,0 +1,344 @@
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+
+from langchain.messages import ToolMessage
+from langgraph.types import Command
+
+from coding_deepgent.hooks import HookPayload, HookResult, LocalHookRegistry
+from coding_deepgent.memory import save_memory
+from coding_deepgent.permissions import PermissionManager
+from coding_deepgent.runtime import InMemoryEventSink, RuntimeContext
+from coding_deepgent.sessions import JsonlSessionStore, build_recovery_brief, render_recovery_brief
+from coding_deepgent.skills import load_skill
+from coding_deepgent.subagents import run_subagent
+from coding_deepgent.tasks import (
+    plan_get,
+    plan_save,
+    task_create,
+    task_get,
+    task_list,
+    task_update,
+)
+from coding_deepgent.tool_system import (
+    ToolCapability,
+    ToolGuardMiddleware,
+    ToolPolicy,
+    build_builtin_capabilities,
+    build_capability_registry,
+)
+from coding_deepgent.filesystem import bash, edit_file, glob_search, grep_search, read_file, write_file
+from coding_deepgent.todo.tools import todo_write
+
+
+def canonical_registry():
+    return build_capability_registry(
+        builtin_capabilities=build_builtin_capabilities(
+            filesystem_tools=(bash, read_file, write_file, edit_file),
+            discovery_tools=(glob_search, grep_search),
+            todo_tools=(todo_write,),
+            memory_tools=(save_memory,),
+            skill_tools=(load_skill,),
+            task_tools=(
+                task_create,
+                task_get,
+                task_list,
+                task_update,
+                plan_save,
+                plan_get,
+            ),
+            subagent_tools=(run_subagent,),
+        ),
+        extension_capabilities=(),
+    )
+
+
+def request(name: str, args: dict[str, object], sink: InMemoryEventSink | None = None):
+    hook_registry = LocalHookRegistry()
+    runtime = SimpleNamespace(
+        context=RuntimeContext(
+            session_id="session-1",
+            workdir=Path.cwd(),
+            trusted_workdirs=(),
+            entrypoint="test",
+            agent_name="test-agent",
+            skill_dir=Path.cwd() / "skills",
+            event_sink=sink or InMemoryEventSink(),
+            hook_registry=hook_registry,
+        )
+    )
+    return SimpleNamespace(
+        tool_call={"name": name, "args": args, "id": "call-1"}, runtime=runtime
+    )
+
+
+def request_with_session_context(
+    name: str,
+    args: dict[str, object],
+    *,
+    session_store: JsonlSessionStore,
+    workdir: Path,
+    sink: InMemoryEventSink | None = None,
+):
+    session_context = session_store.create_session(
+        workdir=workdir, session_id="session-1"
+    )
+    session_store.append_message(session_context, role="user", content="start")
+    hook_registry = LocalHookRegistry()
+    runtime = SimpleNamespace(
+        context=RuntimeContext(
+            session_id="session-1",
+            workdir=workdir,
+            trusted_workdirs=(),
+            entrypoint="test",
+            agent_name="test-agent",
+            skill_dir=workdir / "skills",
+            event_sink=sink or InMemoryEventSink(),
+            hook_registry=hook_registry,
+            session_context=session_context,
+        )
+    )
+    return SimpleNamespace(
+        tool_call={"name": name, "args": args, "id": "call-1"}, runtime=runtime
+    )
+
+
+def test_tool_guard_preserves_allowed_handler_return_values_and_events() -> None:
+    registry = canonical_registry()
+    sink = InMemoryEventSink()
+    middleware = ToolGuardMiddleware(registry=registry, event_sink=sink)
+    calls: list[str] = []
+
+    def handler(_request: Any) -> Command:
+        calls.append("called")
+        return Command(update={"todos": []})
+
+    result = middleware.wrap_tool_call(request("TodoWrite", {}, sink), handler)
+
+    assert isinstance(result, Command)
+    assert calls == ["called"]
+    assert [event.kind for event in sink.snapshot()] == ["allowed", "completed"]
+
+
+def test_tool_guard_blocks_ask_decisions_without_calling_handler() -> None:
+    registry = canonical_registry()
+    policy = ToolPolicy(
+        registry=registry,
+        permission_manager=PermissionManager(mode="default", workdir=Path.cwd()),
+    )
+    sink = InMemoryEventSink()
+    middleware = ToolGuardMiddleware(registry=registry, policy=policy, event_sink=sink)
+
+    result = middleware.wrap_tool_call(
+        request("write_file", {"path": "README.md", "content": "x"}, sink),
+        lambda _request: ToolMessage(content="should not run", tool_call_id="call-1"),
+    )
+
+    assert isinstance(result, ToolMessage)
+    assert result.status == "error"
+    assert "Approval required" in str(result.content)
+    events = sink.snapshot()
+    assert [event.kind for event in events] == ["permission_ask"]
+    assert events[0].metadata["policy_code"] == "permission_required"
+
+
+def test_tool_guard_denies_unknown_tools() -> None:
+    registry = canonical_registry()
+    sink = InMemoryEventSink()
+    middleware = ToolGuardMiddleware(registry=registry, event_sink=sink)
+
+    result = middleware.wrap_tool_call(
+        request("unknown", {}, sink),
+        lambda _request: ToolMessage(content="should not run", tool_call_id="call-1"),
+    )
+
+    assert isinstance(result, ToolMessage)
+    assert result.status == "error"
+    assert sink.snapshot()[0].metadata["policy_code"] == "unknown_tool"
+
+
+def test_tool_guard_emits_permission_denied_for_unknown_and_dont_ask() -> None:
+    registry = canonical_registry()
+    sink = InMemoryEventSink()
+    middleware = ToolGuardMiddleware(
+        registry=registry,
+        policy=ToolPolicy(
+            registry=registry,
+            permission_manager=PermissionManager(mode="dontAsk", workdir=Path.cwd()),
+        ),
+        event_sink=sink,
+    )
+
+    result = middleware.wrap_tool_call(
+        request("write_file", {"path": "README.md", "content": "x"}, sink),
+        lambda _request: ToolMessage(content="should not run", tool_call_id="call-1"),
+    )
+
+    assert isinstance(result, ToolMessage)
+    assert result.status == "error"
+    assert "dontAsk mode" in str(result.content)
+    assert sink.snapshot()[0].kind == "permission_denied"
+
+
+def test_tool_guard_permission_denied_appends_session_evidence(tmp_path: Path) -> None:
+    registry = canonical_registry()
+    sink = InMemoryEventSink()
+    session_store = JsonlSessionStore(tmp_path / "sessions")
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+    req = request_with_session_context(
+        "write_file",
+        {"path": "README.md", "content": "x"},
+        session_store=session_store,
+        workdir=workdir,
+        sink=sink,
+    )
+    middleware = ToolGuardMiddleware(
+        registry=registry,
+        policy=ToolPolicy(
+            registry=registry,
+            permission_manager=PermissionManager(mode="dontAsk", workdir=workdir),
+        ),
+        event_sink=sink,
+    )
+
+    result = middleware.wrap_tool_call(
+        req,
+        lambda _request: ToolMessage(content="should not run", tool_call_id="call-1"),
+    )
+    loaded = session_store.load_session(session_id="session-1", workdir=workdir)
+    rendered = render_recovery_brief(build_recovery_brief(loaded))
+
+    assert isinstance(result, ToolMessage)
+    assert result.status == "error"
+    assert loaded.summary.evidence_count == 1
+    assert loaded.evidence[0].kind == "runtime_event"
+    assert loaded.evidence[0].status == "denied"
+    assert loaded.evidence[0].metadata == {
+        "event_kind": "permission_denied",
+        "source": "tool_guard",
+        "tool": "write_file",
+        "policy_code": "permission_denied",
+        "permission_behavior": "deny",
+    }
+    assert "[denied] runtime_event: Tool write_file denied by permission_denied." in rendered
+
+
+def test_tool_guard_blocks_untrusted_extension_destructive_tools() -> None:
+    registry = canonical_registry()
+    sink = InMemoryEventSink()
+    extension_capability = ToolCapability(
+        name="mcp__docs__write",
+        tool=registry.require("write_file").tool,
+        domain="mcp",
+        read_only=False,
+        destructive=True,
+        concurrency_safe=False,
+        source="mcp:docs",
+        trusted=False,
+    )
+    extended_registry = type(registry)(
+        [*registry.metadata().values(), extension_capability]
+    )
+    policy = ToolPolicy(
+        registry=extended_registry,
+        permission_manager=PermissionManager(mode="acceptEdits", workdir=Path.cwd()),
+    )
+    middleware = ToolGuardMiddleware(
+        registry=extended_registry,
+        policy=policy,
+        event_sink=sink,
+    )
+
+    result = middleware.wrap_tool_call(
+        request("mcp__docs__write", {"path": "README.md", "content": "x"}, sink),
+        lambda _request: ToolMessage(content="should not run", tool_call_id="call-1"),
+    )
+
+    assert isinstance(result, ToolMessage)
+    assert result.status == "error"
+    assert "untrusted extension" in str(result.content)
+    assert sink.snapshot()[0].metadata["policy_code"] == "permission_required"
+
+
+def test_tool_guard_pre_tool_hook_can_block_handler_and_emits_hook_events() -> None:
+    registry = canonical_registry()
+    sink = InMemoryEventSink()
+    req = request("write_file", {"path": "README.md", "content": "x"}, sink)
+    req.runtime.context.hook_registry.register(
+        "PreToolUse",
+        lambda payload: HookResult.model_validate(
+            {
+                "continue": False,
+                "decision": "block",
+                "reason": f"blocked:{payload.data['tool']}",
+            }
+        ),
+    )
+    middleware = ToolGuardMiddleware(
+        registry=registry,
+        policy=ToolPolicy(
+            registry=registry,
+            permission_manager=PermissionManager(mode="acceptEdits", workdir=Path.cwd()),
+        ),
+        event_sink=sink,
+    )
+
+    result = middleware.wrap_tool_call(
+        req,
+        lambda _request: ToolMessage(content="should not run", tool_call_id="call-1"),
+    )
+
+    assert isinstance(result, ToolMessage)
+    assert "blocked:write_file" in str(result.content)
+    assert [event.kind for event in sink.snapshot()] == ["hook_start", "hook_blocked"]
+
+
+def test_tool_guard_post_tool_and_permission_denied_hooks_run() -> None:
+    registry = canonical_registry()
+    sink = InMemoryEventSink()
+    req = request("TodoWrite", {}, sink)
+    seen: list[str] = []
+
+    def on_post_tool_use(payload: HookPayload) -> HookResult:
+        seen.append(f"post:{payload.data['tool']}")
+        return HookResult()
+
+    req.runtime.context.hook_registry.register("PostToolUse", on_post_tool_use)
+    middleware = ToolGuardMiddleware(registry=registry, event_sink=sink)
+
+    result = middleware.wrap_tool_call(
+        req,
+        lambda _request: Command(update={"todos": []}),
+    )
+
+    assert isinstance(result, Command)
+    assert seen == ["post:TodoWrite"]
+    assert [event.kind for event in sink.snapshot()] == [
+        "allowed",
+        "completed",
+        "hook_start",
+        "hook_complete",
+    ]
+
+    deny_req = request("write_file", {"path": "README.md", "content": "x"}, sink)
+    deny_seen: list[str] = []
+
+    def on_permission_denied(payload: HookPayload) -> HookResult:
+        deny_seen.append(str(payload.data["tool"]))
+        return HookResult()
+
+    deny_req.runtime.context.hook_registry.register(
+        "PermissionDenied", on_permission_denied
+    )
+    deny_middleware = ToolGuardMiddleware(registry=registry, event_sink=sink)
+
+    deny_result = deny_middleware.wrap_tool_call(
+        deny_req,
+        lambda _request: ToolMessage(content="should not run", tool_call_id="call-1"),
+    )
+
+    assert isinstance(deny_result, ToolMessage)
+    assert deny_seen == ["write_file"]
diff --git a/coding-deepgent/tests/test_tool_system_registry.py b/coding-deepgent/tests/test_tool_system_registry.py
new file mode 100644
index 000000000..6b59f05fb
--- /dev/null
+++ b/coding-deepgent/tests/test_tool_system_registry.py
@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from dependency_injector import providers
+from langchain.tools import tool
+
+from coding_deepgent.containers import AppContainer
+from coding_deepgent.settings import Settings
+from coding_deepgent.tool_system import (
+    ToolCapability,
+    build_builtin_capabilities,
+    build_capability_registry,
+)
+
+
+EXPECTED_MAIN_TOOL_NAMES = [
+    "bash",
+    "read_file",
+    "write_file",
+    "edit_file",
+    "TodoWrite",
+    "save_memory",
+    "load_skill",
+    "task_create",
+    "task_get",
+    "task_list",
+    "task_update",
+    "plan_save",
+    "plan_get",
+    "run_subagent",
+]
+
+
+def _container(tmp_path: Path) -> AppContainer:
+    return AppContainer(
+        settings=providers.Object(Settings(workdir=tmp_path)),
+        model=providers.Object(object()),
+        create_agent_factory=providers.Object(lambda **kwargs: object()),
+    )
+
+
+def test_capability_inventory_exposes_child_only_and_main_projections(
+    tmp_path: Path,
+) -> None:
+    registry = _container(tmp_path).capability_registry()
+
+    assert "glob" in registry.names()
+    assert "grep" in registry.names()
+    assert registry.child_names() == ["glob", "grep"]
+    assert "glob" not in registry.main_names()
+    assert "grep" not in registry.main_names()
+    assert "glob" not in registry.declarable_names()
+    assert "grep" not in registry.declarable_names()
+    assert "save_memory" in registry.main_names()
+    assert "task_create" in registry.main_names()
+
+
+def test_main_projection_preserves_current_product_tool_surface(
+    tmp_path: Path,
+) -> None:
+    registry = _container(tmp_path).capability_registry()
+
+    tool_names = [
+        getattr(tool, "name", type(tool).__name__) for tool in registry.main_tools()
+    ]
+
+    assert tool_names == EXPECTED_MAIN_TOOL_NAMES
+
+
+@tool("duplicate_tool", description="First duplicate tool.")
+def duplicate_tool_first() -> str:
+    return "first"
+
+
+@tool("duplicate_tool", description="Second duplicate tool.")
+def duplicate_tool_second() -> str:
+    return "second"
+
+
+def test_build_builtin_capabilities_rejects_duplicate_tool_names() -> None:
+    with pytest.raises(ValueError, match="Duplicate builtin tool name: duplicate_tool"):
+        build_builtin_capabilities(
+            filesystem_tools=(duplicate_tool_first, duplicate_tool_second),
+            todo_tools=(),
+            memory_tools=(),
+            skill_tools=(),
+            task_tools=(),
+            subagent_tools=(),
+        )
+
+
+def test_capability_registry_enabled_and_extension_projections_are_explicit() -> None:
+    base_registry = _container(Path.cwd()).capability_registry()
+    extension_capability = ToolCapability(
+        name="mcp__docs__lookup",
+        tool=base_registry.require("read_file").tool,
+        domain="mcp",
+        read_only=True,
+        destructive=False,
+        concurrency_safe=True,
+        source="mcp:docs",
+        trusted=False,
+        exposure="extension",
+        tags=("read", "server:docs"),
+    )
+    disabled_capability = ToolCapability(
+        name="disabled_demo",
+        tool=base_registry.require("read_file").tool,
+        domain="demo",
+        read_only=True,
+        destructive=False,
+        concurrency_safe=True,
+        enabled=False,
+        exposure="main",
+    )
+    registry = build_capability_registry(
+        builtin_capabilities=tuple(base_registry.metadata().values()),
+        extension_capabilities=(extension_capability, disabled_capability),
+    )
+
+    assert "mcp__docs__lookup" in registry.main_names()
+    assert "mcp__docs__lookup" in registry.declarable_names()
+    assert "disabled_demo" not in registry.main_names()
+    assert "disabled_demo" not in registry.declarable_names()
+
+
+def test_app_container_threads_permission_settings_into_tool_system(tmp_path: Path) -> None:
+    trusted_root = (tmp_path / "shared").resolve()
+    trusted_root.mkdir(parents=True)
+    settings = Settings(
+        workdir=tmp_path,
+        permission_mode="plan",
+        trusted_workdirs=(trusted_root,),
+    )
+    container = AppContainer(
+        settings=providers.Object(settings),
+        model=providers.Object(object()),
+        create_agent_factory=providers.Object(lambda **kwargs: object()),
+    )
+
+    permission_manager = container.tool_system.permission_manager()
+
+    assert permission_manager.mode == "plan"
+    assert permission_manager.workdir == tmp_path.resolve()
+    assert permission_manager.trusted_workdirs == (trusted_root,)
diff --git a/coding-deepgent/tests/test_tools.py b/coding-deepgent/tests/test_tools.py
new file mode 100644
index 000000000..1baf89d43
--- /dev/null
+++ b/coding-deepgent/tests/test_tools.py
@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any, cast
+
+import pytest
+
+from coding_deepgent.filesystem import (
+    bash,
+    edit_file,
+    glob_search,
+    grep_search,
+    read_file,
+    safe_path,
+    write_file,
+)
+
+
+def runtime_for(*, workdir: Path, trusted_workdirs: tuple[Path, ...] = ()):
+    return SimpleNamespace(
+        context=SimpleNamespace(
+            workdir=workdir,
+            trusted_workdirs=trusted_workdirs,
+        )
+    )
+
+
+def test_safe_path_rejects_workspace_escape(tmp_path: Path) -> None:
+    with pytest.raises(ValueError):
+        safe_path("../escape.txt", workdir=tmp_path)
+
+
+def test_safe_path_requires_explicit_workdir() -> None:
+    with pytest.raises(TypeError):
+        safe_path("notes.txt")  # type: ignore[call-arg]
+
+
+def test_read_write_edit_roundtrip(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    monkeypatch.setenv("CODING_DEEPGENT_WORKDIR", str(tmp_path))
+    runtime = runtime_for(workdir=tmp_path)
+    write = cast(Any, write_file).func
+    read = cast(Any, read_file).func
+    edit = cast(Any, edit_file).func
+
+    assert (
+        write("notes.txt", "alpha\nbeta\n", runtime)
+        == "Wrote 11 bytes to notes.txt"
+    )
+    assert read("notes.txt", runtime) == "alpha\nbeta"
+    assert (
+        read("notes.txt", runtime, 1)
+        == "alpha\n... (1 more lines)"
+    )
+    assert (
+        edit("notes.txt", "beta", "gamma", runtime)
+        == "Edited notes.txt"
+    )
+    assert read("notes.txt", runtime) == "alpha\ngamma"
+
+
+def test_bash_blocks_dangerous_commands() -> None:
+    run = cast(Any, bash).func
+    assert (
+        run("rm -rf /", runtime_for(workdir=Path.cwd()))
+        == "Error: Dangerous command blocked"
+    )
+
+
+def test_tools_allow_explicit_trusted_extra_directories(
+    tmp_path: Path,
+) -> None:
+    trusted_dir = tmp_path.parent / "trusted-shared"
+    trusted_dir.mkdir()
+    trusted_file = trusted_dir / "shared.txt"
+
+    runtime = runtime_for(workdir=tmp_path, trusted_workdirs=(trusted_dir,))
+    write = cast(Any, write_file).func
+    read = cast(Any, read_file).func
+
+    assert (
+        write(str(trusted_file), "alpha", runtime)
+        == f"Wrote 5 bytes to {trusted_file}"
+    )
+    assert read(str(trusted_file), runtime) == "alpha"
+
+
+def test_discovery_tools_use_runtime_owned_roots(tmp_path: Path) -> None:
+    runtime = runtime_for(workdir=tmp_path)
+    (tmp_path / "notes.txt").write_text("alpha\nbeta\n", encoding="utf-8")
+    glob = cast(Any, glob_search).func
+    grep = cast(Any, grep_search).func
+
+    assert glob("*.txt", runtime) == "notes.txt"
+    assert grep("beta", runtime, "**/*.txt") == "notes.txt:2:beta"
diff --git a/docs/en/data-structures.md b/docs/en/data-structures.md
new file mode 100644
index 000000000..5e9300f98
--- /dev/null
+++ b/docs/en/data-structures.md
@@ -0,0 +1,167 @@
+# Core Data Structures
+
+> **Reference** -- Use this when you lose track of where state lives. Each record has one clear job.
+
+The 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.
+
+## Recommended Reading Together
+
+- [`glossary.md`](./glossary.md) for term meanings
+- [`entity-map.md`](./entity-map.md) for layer boundaries
+- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) for task vs runtime-slot separation
+- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md) for MCP beyond tools
+
+## Two Principles To Keep In Mind
+
+### Principle 1: separate content state from process-control state
+
+- `messages`, `tool_result`, and memory text are content state
+- `turn_count`, `transition`, and retry flags are process-control state
+
+### Principle 2: separate durable state from runtime-only state
+
+- tasks, memory, and schedules are usually durable
+- runtime slots, permission decisions, and live MCP connections are usually runtime state
+
+## Query And Conversation State
+
+### `Message`
+
+Stores conversation and tool round-trip history.
+
+### `NormalizedMessage`
+
+Stable message shape ready for the model API.
+
+### `QueryParams`
+
+External input used to start one query process.
+
+### `QueryState`
+
+Mutable state that changes across turns.
+
+### `TransitionReason`
+
+Explains why the next turn exists.
+
+### `CompactSummary`
+
+Compressed carry-forward summary when old context leaves the hot window.
+
+## Prompt And Input State
+
+### `SystemPromptBlock`
+
+One stable prompt fragment.
+
+### `PromptParts`
+
+Separated prompt fragments before final assembly.
+
+### `ReminderMessage`
+
+Temporary one-turn or one-mode injection.
+
+## Tool And Control-Plane State
+
+### `ToolSpec`
+
+What the model knows about one tool.
+
+### `ToolDispatchMap`
+
+Name-to-handler routing table.
+
+### `ToolUseContext`
+
+Shared execution environment visible to tools.
+
+### `ToolResultEnvelope`
+
+Normalized result returned into the main loop.
+
+### `PermissionRule`
+
+Policy that decides allow / deny / ask.
+
+### `PermissionDecision`
+
+Structured output of the permission gate.
+
+### `HookEvent`
+
+Normalized lifecycle event emitted around the loop.
+
+## Durable Work State
+
+### `TaskRecord`
+
+Durable work-graph node with goal, status, and dependency edges.
+
+### `ScheduleRecord`
+
+Rule describing when work should trigger.
+
+### `MemoryEntry`
+
+Cross-session fact worth keeping.
+
+## Runtime Execution State
+
+### `RuntimeTaskState`
+
+Live execution-slot record for background or long-running work.
+
+### `Notification`
+
+Small result bridge that carries runtime outcomes back into the main loop.
+
+### `RecoveryState`
+
+State used to continue coherently after failures.
+
+## Team And Platform State
+
+### `TeamMember`
+
+Persistent teammate identity.
+
+### `MessageEnvelope`
+
+Structured message between teammates.
+
+### `RequestRecord`
+
+Durable record for approvals, shutdowns, handoffs, or other protocol workflows.
+
+### `WorktreeRecord`
+
+Record for one isolated execution lane.
+
+### `MCPServerConfig`
+
+Configuration for one external capability provider.
+
+### `CapabilityRoute`
+
+Routing decision for native, plugin, or MCP-backed capability.
+
+## A Useful Quick Map
+
+| Record | Main Job | Usually Lives In |
+|---|---|---|
+| `Message` | conversation history | `messages[]` |
+| `QueryState` | turn-by-turn control | query engine |
+| `ToolUseContext` | tool execution environment | tool control plane |
+| `PermissionDecision` | execution gate outcome | permission layer |
+| `TaskRecord` | durable work goal | task board |
+| `RuntimeTaskState` | live execution slot | runtime manager |
+| `TeamMember` | persistent teammate | team config |
+| `RequestRecord` | protocol state | request tracker |
+| `WorktreeRecord` | isolated execution lane | worktree index |
+| `MCPServerConfig` | external capability config | settings / plugin config |
+
+## Key Takeaway
+
+**High-completion systems become much easier to understand when every important record has one clear job and one clear layer.**
diff --git a/docs/en/entity-map.md b/docs/en/entity-map.md
new file mode 100644
index 000000000..7409b8f7a
--- /dev/null
+++ b/docs/en/entity-map.md
@@ -0,0 +1,119 @@
+# Entity Map
+
+> **Reference** -- Use this when concepts start to blur together. It tells you which layer each thing belongs to.
+
+As 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.
+
+## How This Map Differs From Other Docs
+
+- this map answers: **which layer does this thing belong to?**
+- [`glossary.md`](./glossary.md) answers: **what does the word mean?**
+- [`data-structures.md`](./data-structures.md) answers: **what does the state shape look like?**
+
+## A Fast Layered Picture
+
+```text
+conversation layer
+  - message
+  - prompt block
+  - reminder
+
+action layer
+  - tool call
+  - tool result
+  - hook event
+
+work layer
+  - work-graph task
+  - runtime task
+  - protocol request
+
+execution layer
+  - subagent
+  - teammate
+  - worktree lane
+
+platform layer
+  - MCP server
+  - memory record
+  - capability router
+```
+
+## The Most Commonly Confused Pairs
+
+### `Message` vs `PromptBlock`
+
+| Entity | What It Is | What It Is Not |
+|---|---|---|
+| `Message` | conversational content in history | not a stable system rule |
+| `PromptBlock` | stable prompt instruction fragment | not one turn's latest event |
+
+### `Todo / Plan` vs `Task`
+
+| Entity | What It Is | What It Is Not |
+|---|---|---|
+| `todo / plan` | temporary session guidance | not a durable work graph |
+| `task` | durable work node | not one turn's local thought |
+
+### `Work-Graph Task` vs `RuntimeTaskState`
+
+| Entity | What It Is | What It Is Not |
+|---|---|---|
+| work-graph task | durable goal and dependency node | not the live executor |
+| runtime task | currently running execution slot | not the durable dependency node |
+
+### `Subagent` vs `Teammate`
+
+| Entity | What It Is | What It Is Not |
+|---|---|---|
+| subagent | one-shot delegated worker | not a long-lived team member |
+| teammate | persistent collaborator with identity and inbox | not a disposable summary tool |
+
+### `ProtocolRequest` vs normal message
+
+| Entity | What It Is | What It Is Not |
+|---|---|---|
+| normal message | free-form communication | not a traceable approval workflow |
+| protocol request | structured request with `request_id` | not casual chat text |
+
+### `Task` vs `Worktree`
+
+| Entity | What It Is | What It Is Not |
+|---|---|---|
+| task | what should be done | not a directory |
+| worktree | where isolated execution happens | not the goal itself |
+
+### `Memory` vs `CLAUDE.md`
+
+| Entity | What It Is | What It Is Not |
+|---|---|---|
+| memory | durable cross-session facts | not the project rule file |
+| `CLAUDE.md` | stable local rule / instruction surface | not user-specific long-term fact storage |
+
+### `MCPServer` vs `MCPTool`
+
+| Entity | What It Is | What It Is Not |
+|---|---|---|
+| MCP server | external capability provider | not one specific tool |
+| MCP tool | one exposed capability | not the whole connection surface |
+
+## Quick "What / Where" Table
+
+| Entity | Main Job | Typical Place |
+|---|---|---|
+| `Message` | visible conversation context | `messages[]` |
+| `PromptParts` | input assembly fragments | prompt builder |
+| `PermissionRule` | execution decision rules | settings / session state |
+| `HookEvent` | lifecycle extension point | hook system |
+| `MemoryEntry` | durable fact | memory store |
+| `TaskRecord` | work goal node | task board |
+| `RuntimeTaskState` | live execution slot | runtime manager |
+| `TeamMember` | persistent worker identity | team config |
+| `MessageEnvelope` | structured teammate message | inbox |
+| `RequestRecord` | protocol workflow state | request tracker |
+| `WorktreeRecord` | isolated execution lane | worktree index |
+| `MCPServerConfig` | external capability provider config | plugin / settings |
+
+## Key Takeaway
+
+**The more capable the system becomes, the more important clear entity boundaries become.**
diff --git a/docs/en/glossary.md b/docs/en/glossary.md
new file mode 100644
index 000000000..8abfc93f1
--- /dev/null
+++ b/docs/en/glossary.md
@@ -0,0 +1,141 @@
+# Glossary
+
+> **Reference** -- Bookmark this page. Come back whenever you hit an unfamiliar term.
+
+This 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.
+
+## Recommended Companion Docs
+
+- [`entity-map.md`](./entity-map.md) for layer boundaries
+- [`data-structures.md`](./data-structures.md) for record shapes
+- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) if you keep mixing up different kinds of "task"
+
+## Agent
+
+A model that can reason over input and call tools to complete work. (Think of it as the "brain" that decides what to do next.)
+
+## Harness
+
+The working environment prepared around the model -- everything the model needs but cannot provide for itself:
+
+- tools
+- filesystem
+- permissions
+- prompt assembly
+- memory
+- task runtime
+
+## Agent Loop
+
+The repeating core cycle that drives every agent session. Each iteration looks like this:
+
+1. send current input to the model
+2. inspect whether it answered or asked for tools
+3. execute tools if needed
+4. write results back
+5. continue or stop
+
+## Message / `messages[]`
+
+The visible conversation and tool-result history used as working context. (This is the rolling transcript the model sees on every turn.)
+
+## Tool
+
+An action the model may request, such as reading a file, writing a file, editing content, or running a shell command.
+
+## Tool Schema
+
+The description shown to the model:
+
+- name
+- purpose
+- input parameters
+- input types
+
+## Dispatch Map
+
+A routing table from tool names to handlers. (Like a phone switchboard: the name comes in, and the map connects it to the right function.)
+
+## Stop Reason
+
+Why the current model turn ended. Common values:
+
+- `end_turn`
+- `tool_use`
+- `max_tokens`
+
+## Context
+
+The total information currently visible to the model. (Everything inside the model's "window" on a given turn.)
+
+## Compaction
+
+The 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.)
+
+## Subagent
+
+A 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.)
+
+## Permission
+
+The decision layer that determines whether a requested action may execute.
+
+## Hook
+
+An 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.)
+
+## Memory
+
+Cross-session information worth keeping because it remains valuable later and is not cheap to re-derive.
+
+## System Prompt
+
+The stable system-level instruction surface that defines identity, rules, and long-lived constraints.
+
+## Query
+
+The full multi-turn process used to complete one user request. (One query may span many loop turns before the answer is ready.)
+
+## Transition Reason
+
+The reason the system continues into another turn.
+
+## Task
+
+A durable work goal node in the work graph. (Unlike a todo item that disappears when the session ends, a task persists.)
+
+## Runtime Task / Runtime Slot
+
+A live execution slot representing something currently running. (The task says "what should happen"; the runtime slot says "it is happening right now.")
+
+## Teammate
+
+A persistent collaborator inside a multi-agent system. (Unlike a subagent that is fire-and-forget, a teammate sticks around.)
+
+## Protocol Request
+
+A structured request with explicit identity, status, and tracking, usually backed by a `request_id`. (A formal envelope rather than a casual message.)
+
+## Worktree
+
+An 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.)
+
+## MCP
+
+Model 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.)
+
+## DAG
+
+Directed 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.
+
+## FSM / State Machine
+
+Finite 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.
+
+## Control Plane
+
+The 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.
+
+## Tokens
+
+The 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.
diff --git a/docs/en/s00-architecture-overview.md b/docs/en/s00-architecture-overview.md
new file mode 100644
index 000000000..ceb94acc1
--- /dev/null
+++ b/docs/en/s00-architecture-overview.md
@@ -0,0 +1,179 @@
+# s00: Architecture Overview
+
+Welcome 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.
+
+## The Big Picture
+
+The mainline of this repo is reasonable because it grows the system in four dependency-driven stages:
+
+1. build a real single-agent loop
+2. harden that loop with safety, memory, and recovery
+3. turn temporary session work into durable runtime work
+4. grow the single executor into a multi-agent platform with isolated lanes and external capability routing
+
+This order follows **mechanism dependencies**, not file order and not product glamour.
+
+If the learner does not already understand:
+
+`user input -> model -> tools -> write-back -> next turn`
+
+then permissions, hooks, memory, tasks, teams, worktrees, and MCP all become disconnected vocabulary.
+
+## What This Repo Is Trying To Reconstruct
+
+This repository is not trying to mirror a production codebase line by line.
+
+It is trying to reconstruct the parts that determine whether an agent system actually works:
+
+- what the main modules are
+- how those modules cooperate
+- what each module is responsible for
+- where the important state lives
+- how one request flows through the system
+
+That means the goal is:
+
+**high fidelity to the design backbone, not 1:1 fidelity to every outer implementation detail.**
+
+## Three Tips Before You Start
+
+### Tip 1: Learn the smallest correct version first
+
+For example, a subagent does not need every advanced capability on day one.
+
+The smallest correct version already teaches the core lesson:
+
+- the parent defines the subtask
+- the child gets a separate `messages[]`
+- the child returns a summary
+
+Only after that is stable should you add:
+
+- inherited context
+- separate permissions
+- background runtime
+- worktree isolation
+
+### Tip 2: New terms should be explained before they are used
+
+This repo uses terms such as:
+
+- state machine
+- dispatch map
+- dependency graph
+- worktree
+- protocol envelope
+- MCP
+
+If a term is unfamiliar, pause and check the reference docs rather than pushing forward blindly.
+
+Recommended companions:
+
+- [`glossary.md`](./glossary.md)
+- [`entity-map.md`](./entity-map.md)
+- [`data-structures.md`](./data-structures.md)
+- [`teaching-scope.md`](./teaching-scope.md)
+
+### Tip 3: Do not let peripheral complexity pretend to be core mechanism
+
+Good teaching does not try to include everything.
+
+It explains the important parts completely and keeps low-value complexity out of your way:
+
+- packaging and release flow
+- enterprise integration glue
+- telemetry
+- product-specific compatibility branches
+- file-name / line-number reverse-engineering trivia
+
+## Bridge Docs That Matter
+
+Treat these as cross-chapter maps:
+
+| Doc | What It Clarifies |
+|---|---|
+| [`s00d-chapter-order-rationale.md`](./s00d-chapter-order-rationale.md) (Deep Dive) | why the curriculum order is what it is |
+| [`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 |
+| [`s00a-query-control-plane.md`](./s00a-query-control-plane.md) (Deep Dive) | why a high-completion agent needs more than `messages[] + while True` |
+| [`s00b-one-request-lifecycle.md`](./s00b-one-request-lifecycle.md) (Deep Dive) | how one request moves through the full system |
+| [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md) (Deep Dive) | why tools become a control plane, not just a function table |
+| [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md) (Deep Dive) | why system prompt is only one input surface |
+| [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) (Deep Dive) | why durable tasks and live runtime slots must split |
+| [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md) (Deep Dive) | why MCP is more than a remote tool list |
+
+## The Four Learning Stages
+
+### Stage 1: Core Single-Agent (`s01-s06`)
+
+Goal: build a single agent that can actually do work.
+
+| Chapter | New Layer |
+|---|---|
+| `s01` | loop and write-back |
+| `s02` | tools and dispatch |
+| `s03` | session planning |
+| `s04` | delegated subtask isolation |
+| `s05` | skill discovery and loading |
+| `s06` | context compaction |
+
+### Stage 2: Hardening (`s07-s11`)
+
+Goal: make the loop safer, more stable, and easier to extend.
+
+| Chapter | New Layer |
+|---|---|
+| `s07` | permission gate |
+| `s08` | hooks and side effects |
+| `s09` | durable memory |
+| `s10` | prompt assembly |
+| `s11` | recovery and continuation |
+
+### Stage 3: Runtime Work (`s12-s14`)
+
+Goal: upgrade session work into durable, background, and scheduled runtime work.
+
+| Chapter | New Layer |
+|---|---|
+| `s12` | persistent task graph |
+| `s13` | runtime execution slots |
+| `s14` | time-based triggers |
+
+### Stage 4: Platform (`s15-s19`)
+
+Goal: grow from one executor into a larger platform.
+
+| Chapter | New Layer |
+|---|---|
+| `s15` | persistent teammates |
+| `s16` | structured team protocols |
+| `s17` | autonomous claiming and resuming |
+| `s18` | isolated execution lanes |
+| `s19` | external capability routing |
+
+## Quick Reference: What Each Chapter Adds
+
+| Chapter | Core Structure | What You Should Be Able To Build |
+|---|---|---|
+| `s01` | `LoopState`, `tool_result` write-back | a minimal working agent loop |
+| `s02` | `ToolSpec`, dispatch map | stable tool routing |
+| `s03` | `TodoItem`, `PlanState` | visible session planning |
+| `s04` | isolated child context | delegated subtasks without polluting the parent |
+| `s05` | `SkillRegistry` | cheap discovery and deep on-demand loading |
+| `s06` | compaction records | long sessions that stay usable |
+| `s07` | permission decisions | execution behind a gate |
+| `s08` | lifecycle events | extension without rewriting the loop |
+| `s09` | memory records | selective long-term memory |
+| `s10` | prompt parts | staged input assembly |
+| `s11` | continuation reasons | recovery branches that stay legible |
+| `s12` | `TaskRecord` | durable work graphs |
+| `s13` | `RuntimeTaskState` | background execution with later write-back |
+| `s14` | `ScheduleRecord` | time-triggered work |
+| `s15` | `TeamMember`, inboxes | persistent teammates |
+| `s16` | protocol envelopes | structured request / response coordination |
+| `s17` | claim policy | self-claim and self-resume |
+| `s18` | `WorktreeRecord` | isolated execution lanes |
+| `s19` | capability routing | unified native + plugin + MCP routing |
+
+## Key Takeaway
+
+**A good chapter order is not a list of features. It is a path where each mechanism grows naturally out of the last one.**
diff --git a/docs/en/s00a-query-control-plane.md b/docs/en/s00a-query-control-plane.md
new file mode 100644
index 000000000..29366128c
--- /dev/null
+++ b/docs/en/s00a-query-control-plane.md
@@ -0,0 +1,207 @@
+# s00a: Query Control Plane
+
+> **Deep Dive** -- Best read after completing Stage 1 (s01-s06). It explains why the simple loop needs a coordination layer as the system grows.
+
+### When to Read This
+
+After you've built the basic loop and tools, and before you start Stage 2's hardening chapters.
+
+---
+
+> This bridge document answers one foundational question:
+>
+> **Why is `messages[] + while True` not enough for a high-completion agent?**
+
+## Why This Document Exists
+
+`s01` correctly teaches the smallest working loop:
+
+```text
+user input
+  ->
+model response
+  ->
+if tool_use then execute
+  ->
+append result
+  ->
+continue
+```
+
+That is the right starting point.
+
+But 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:
+
+- current turn
+- continuation reason
+- recovery state
+- compaction state
+- budget changes
+- hook-driven continuation
+
+That layer is the **query control plane**.
+
+## Terms First
+
+### What is a query?
+
+Here, a query is not a database lookup.
+
+It means:
+
+> the full multi-turn process the system runs in order to finish one user request
+
+### What is a control plane?
+
+A control plane does not perform the business action itself.
+
+It coordinates:
+
+- when execution continues
+- why it continues
+- what state is patched before the next turn
+
+If 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.
+
+### What is a transition?
+
+A transition explains:
+
+> why the previous turn did not end and why the next turn exists
+
+Common reasons:
+
+- tool result write-back
+- truncated output recovery
+- retry after compaction
+- retry after transport failure
+
+## The Smallest Useful Mental Model
+
+Think of the query path in three layers:
+
+```text
+1. Input layer
+   - messages
+   - system prompt
+   - user/system context
+
+2. Control layer
+   - query state
+   - turn count
+   - transition reason
+   - recovery / compaction / budget flags
+
+3. Execution layer
+   - model call
+   - tool execution
+   - write-back
+```
+
+The control plane does not replace the loop.
+
+It makes the loop capable of handling more than one happy-path branch.
+
+## Why `messages[]` Alone Stops Being Enough
+
+At demo scale, many learners put everything into `messages[]`.
+
+That breaks down once the system needs to know:
+
+- whether reactive compaction already ran
+- how many continuation attempts happened
+- whether this turn is a retry or a normal write-back
+- whether a temporary output budget is active
+
+Those are not conversation contents.
+
+They are **process-control state**.
+
+## Core Structures
+
+### `QueryParams`
+
+External input passed into the query engine:
+
+```python
+params = {
+    "messages": [...],
+    "system_prompt": "...",
+    "tool_use_context": {...},
+    "max_output_tokens_override": None,
+    "max_turns": None,
+}
+```
+
+### `QueryState`
+
+Mutable state that changes across turns:
+
+```python
+state = {
+    "messages": [...],
+    "tool_use_context": {...},
+    "turn_count": 1,
+    "continuation_count": 0,
+    "has_attempted_compact": False,
+    "max_output_tokens_override": None,
+    "transition": None,
+}
+```
+
+### `TransitionReason`
+
+An explicit reason for continuing:
+
+```python
+TRANSITIONS = (
+    "tool_result_continuation",
+    "max_tokens_recovery",
+    "compact_retry",
+    "transport_retry",
+)
+```
+
+This is not ceremony. It makes logs, testing, debugging, and teaching much clearer.
+
+## Minimal Implementation Pattern
+
+### 1. Split entry params from live state
+
+```python
+def query(params):
+    state = {
+        "messages": params["messages"],
+        "tool_use_context": params["tool_use_context"],
+        "turn_count": 1,
+        "transition": None,
+    }
+```
+
+### 2. Let every continue-site patch state explicitly
+
+```python
+state["transition"] = "tool_result_continuation"
+state["turn_count"] += 1
+```
+
+### 3. Make the next turn enter with a reason
+
+The next loop iteration should know whether it exists because of:
+
+- normal write-back
+- retry
+- compaction
+- continuation after truncated output
+
+## What This Changes For You
+
+Once you see the query control plane clearly, later chapters stop feeling like random features.
+
+- `s06` compaction becomes a state patch, not a magic jump
+- `s11` recovery becomes structured continuation, not just `try/except`
+- `s17` autonomy becomes another controlled continuation path, not a separate mystery loop
+
+## Key Takeaway
+
+**A query is not just messages flowing through a loop. It is a controlled process with explicit continuation state.**
diff --git a/docs/en/s00b-one-request-lifecycle.md b/docs/en/s00b-one-request-lifecycle.md
new file mode 100644
index 000000000..77bb89f56
--- /dev/null
+++ b/docs/en/s00b-one-request-lifecycle.md
@@ -0,0 +1,226 @@
+# s00b: One Request Lifecycle
+
+> **Deep Dive** -- Best read after Stage 2 (s07-s11) when you want to see how all the pieces connect end-to-end.
+
+### When to Read This
+
+When you've learned several subsystems and want to see the full vertical flow of a single request.
+
+---
+
+> This bridge document connects the whole system into one continuous execution chain.
+>
+> It answers:
+>
+> **What really happens after one user message enters the system?**
+
+## Why This Document Exists
+
+When you read chapter by chapter, you can understand each mechanism in isolation:
+
+- `s01` loop
+- `s02` tools
+- `s07` permissions
+- `s09` memory
+- `s12-s19` tasks, teams, worktrees, MCP
+
+But implementation gets difficult when you cannot answer:
+
+- what comes first?
+- when do memory and prompt assembly happen?
+- where do permissions sit relative to tools?
+- when do tasks, runtime slots, teammates, worktrees, and MCP enter?
+
+This document gives you the vertical flow.
+
+## The Most Important Full Picture
+
+```text
+user request
+  |
+  v
+initialize query state
+  |
+  v
+assemble system prompt / messages / reminders
+  |
+  v
+call model
+  |
+  +-- normal answer --------------------------> finish request
+  |
+  +-- tool_use
+        |
+        v
+    tool router
+        |
+        +-- permission gate
+        +-- hooks
+        +-- native tool / MCP / agent / task / team
+        |
+        v
+    execution result
+        |
+        +-- may update task / runtime / memory / worktree state
+        |
+        v
+    write tool_result back to messages
+        |
+        v
+    patch query state
+        |
+        v
+    continue next turn
+```
+
+## Segment 1: A User Request Becomes Query State
+
+The system does not treat one user request as one API call.
+
+It first creates a query state for a process that may span many turns:
+
+```python
+query_state = {
+    "messages": [{"role": "user", "content": user_text}],
+    "turn_count": 1,
+    "transition": None,
+    "tool_use_context": {...},
+}
+```
+
+The key mental shift:
+
+**a request is a multi-turn runtime process, not a single model response.**
+
+Related reading:
+
+- [`s01-the-agent-loop.md`](./s01-the-agent-loop.md)
+- [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)
+
+## Segment 2: The Real Model Input Is Assembled
+
+The harness usually does not send raw `messages` directly.
+
+It assembles:
+
+- system prompt blocks
+- normalized messages
+- memory attachments
+- reminders
+- tool definitions
+
+So the actual payload is closer to:
+
+```text
+system prompt
++ normalized messages
++ tools
++ optional reminders and attachments
+```
+
+Related chapters:
+
+- `s09`
+- `s10`
+- [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md)
+
+## Segment 3: The Model Produces Either an Answer or an Action Intent
+
+There are two important output classes.
+
+### Normal answer
+
+The request may end here.
+
+### Action intent
+
+This usually means a tool call, for example:
+
+- `read_file(...)`
+- `bash(...)`
+- `task_create(...)`
+- `mcp__server__tool(...)`
+
+The system is no longer receiving only text.
+
+It is receiving an instruction that should affect the real world.
+
+## Segment 4: The Tool Control Plane Takes Over
+
+Once `tool_use` appears, the system enters the tool control plane (the layer that decides how a tool call gets routed, checked, and executed).
+
+It answers:
+
+1. which tool is this?
+2. where should it route?
+3. should it pass a permission gate?
+4. do hooks observe or modify the action?
+5. what shared runtime context can it access?
+
+Minimal picture:
+
+```text
+tool_use
+  |
+  v
+tool router
+  |
+  +-- native handler
+  +-- MCP client
+  +-- agent / team / task runtime
+```
+
+Related reading:
+
+- [`s02-tool-use.md`](./s02-tool-use.md)
+- [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md)
+
+## Segment 5: Execution May Update More Than Messages
+
+A tool result does not only return text.
+
+Execution may also update:
+
+- task board state
+- runtime task state
+- memory records
+- request records
+- worktree records
+
+That is why middle and late chapters are not optional side features. They become part of the request lifecycle.
+
+## Segment 6: Results Rejoin the Main Loop
+
+The crucial step is always the same:
+
+```text
+real execution result
+  ->
+tool_result or structured write-back
+  ->
+messages / query state updated
+  ->
+next turn
+```
+
+If the result never re-enters the loop, the model cannot reason over reality.
+
+## A Useful Compression
+
+When you get lost, compress the whole lifecycle into three layers:
+
+### Query loop
+
+Owns the multi-turn request process.
+
+### Tool control plane
+
+Owns routing, permissions, hooks, and execution context.
+
+### Platform state
+
+Owns durable records such as tasks, runtime slots, teammates, worktrees, and external capability configuration.
+
+## Key Takeaway
+
+**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.**
diff --git a/docs/en/s00c-query-transition-model.md b/docs/en/s00c-query-transition-model.md
new file mode 100644
index 000000000..c4316638f
--- /dev/null
+++ b/docs/en/s00c-query-transition-model.md
@@ -0,0 +1,268 @@
+# s00c: Query Transition Model
+
+> **Deep Dive** -- Best read alongside s11 (Error Recovery). It deepens the transition model introduced in s00a.
+
+### When to Read This
+
+When you're working on error recovery and want to understand why each continuation needs an explicit reason.
+
+---
+
+> This bridge note answers one narrow but important question:
+>
+> **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?**
+
+## Why This Note Exists
+
+The mainline already teaches:
+
+- `s01`: the smallest loop
+- `s06`: compaction and context control
+- `s11`: error recovery
+
+That sequence is correct.
+
+The problem is what you often carry in your head after reading those chapters separately:
+
+> "The loop continues because it continues."
+
+That is enough for a toy demo, but it breaks down quickly in a larger system.
+
+A query can continue for very different reasons:
+
+- a tool just finished and the model needs the result
+- the output hit a token limit and the model should continue
+- compaction changed the active context and the system should retry
+- the transport layer failed and backoff says "try again"
+- a stop hook said the turn should not fully end yet
+- a budget policy still allows the system to keep going
+
+If all of those collapse into one vague `continue`, three things get worse fast:
+
+- logs stop being readable
+- tests stop being precise
+- the teaching mental model becomes blurry
+
+## Terms First
+
+### What is a transition
+
+Here, a transition means:
+
+> the reason the previous turn became the next turn
+
+It is not the message content itself. It is the control-flow cause.
+
+### What is a continuation
+
+A continuation means:
+
+> this query is still alive and should keep advancing
+
+But continuation is not one thing. It is a family of reasons.
+
+### What is a query boundary
+
+A query boundary is the edge between one turn and the next.
+
+Whenever the system crosses that boundary, it should know:
+
+- why it is crossing
+- what state was changed before the crossing
+- how the next turn should interpret that change
+
+## The Minimum Mental Model
+
+Do not picture a query as a single straight line.
+
+A better mental model is:
+
+```text
+one query
+  = a chain of state transitions
+    with explicit continuation reasons
+```
+
+For example:
+
+```text
+user input
+  ->
+model emits tool_use
+  ->
+tool finishes
+  ->
+tool_result_continuation
+  ->
+model output is truncated
+  ->
+max_tokens_recovery
+  ->
+compaction happens
+  ->
+compact_retry
+  ->
+final completion
+```
+
+That is why the real lesson is not:
+
+> "the loop keeps spinning"
+
+The real lesson is:
+
+> "the system is advancing through typed transition reasons"
+
+## Core Records
+
+### 1. `transition` inside query state
+
+Even a teaching implementation should carry an explicit transition field:
+
+```python
+state = {
+    "messages": [...],
+    "turn_count": 3,
+    "continuation_count": 1,
+    "has_attempted_compact": False,
+    "transition": None,
+}
+```
+
+This field is not decoration.
+
+It tells you:
+
+- why this turn exists
+- how the log should explain it
+- what path a test should assert
+
+### 2. `TransitionReason`
+
+A minimal teaching set can look like this:
+
+```python
+TRANSITIONS = (
+    "tool_result_continuation",
+    "max_tokens_recovery",
+    "compact_retry",
+    "transport_retry",
+    "stop_hook_continuation",
+    "budget_continuation",
+)
+```
+
+These reasons are not equivalent:
+
+- `tool_result_continuation`
+  is normal loop progress
+- `max_tokens_recovery`
+  is continuation after truncated output
+- `compact_retry`
+  is continuation after context reshaping
+- `transport_retry`
+  is continuation after infrastructure failure
+- `stop_hook_continuation`
+  is continuation forced by external control logic
+- `budget_continuation`
+  is continuation allowed by policy and remaining budget
+
+### 3. Continuation budget
+
+High-completion systems do not just continue. They limit continuation.
+
+Typical fields look like:
+
+```python
+state = {
+    "max_output_tokens_recovery_count": 2,
+    "has_attempted_reactive_compact": True,
+}
+```
+
+The principle is:
+
+> continuation is a controlled resource, not an infinite escape hatch
+
+## Minimum Implementation Steps
+
+### Step 1: make every continue site explicit
+
+Many beginner loops still look like this:
+
+```python
+continue
+```
+
+Move one step forward:
+
+```python
+state["transition"] = "tool_result_continuation"
+continue
+```
+
+### Step 2: pair each continuation with its state patch
+
+```python
+if response.stop_reason == "tool_use":
+    state["messages"] = append_tool_results(...)
+    state["turn_count"] += 1
+    state["transition"] = "tool_result_continuation"
+    continue
+
+if response.stop_reason == "max_tokens":
+    state["messages"].append({
+        "role": "user",
+        "content": CONTINUE_MESSAGE,
+    })
+    state["max_output_tokens_recovery_count"] += 1
+    state["transition"] = "max_tokens_recovery"
+    continue
+```
+
+The important part is not "one more line of code."
+
+The important part is:
+
+> before every continuation, the system knows both the reason and the state mutation
+
+### Step 3: separate normal progress from recovery
+
+```python
+if should_retry_transport(error):
+    time.sleep(backoff(...))
+    state["transition"] = "transport_retry"
+    continue
+
+if should_recompact(error):
+    state["messages"] = compact_messages(state["messages"])
+    state["transition"] = "compact_retry"
+    continue
+```
+
+Once you do this, "continue" stops being a vague action and becomes a typed control transition.
+
+## What to Test
+
+Your teaching repo should make these assertions straightforward:
+
+- a tool result writes `tool_result_continuation`
+- a truncated model output writes `max_tokens_recovery`
+- compaction retry does not silently reuse the old reason
+- transport retry increments retry state and does not look like a normal turn
+
+If those paths are not easy to test, the model is probably still too implicit.
+
+## What Not to Over-Teach
+
+You do not need to bury yourself in vendor-specific transport details or every corner-case enum.
+
+For a teaching repo, the core lesson is narrower:
+
+> one query is a sequence of explicit transitions, and each transition should carry a reason, a state patch, and a budget rule
+
+That is the part you actually need if you want to rebuild a high-completion agent from zero.
+
+## Key Takeaway
+
+**Every continuation needs a typed reason. Without one, logs blur, tests weaken, and the mental model collapses into "the loop keeps spinning."**
diff --git a/docs/en/s00d-chapter-order-rationale.md b/docs/en/s00d-chapter-order-rationale.md
new file mode 100644
index 000000000..2c351a4c4
--- /dev/null
+++ b/docs/en/s00d-chapter-order-rationale.md
@@ -0,0 +1,292 @@
+# s00d: Chapter Order Rationale
+
+> **Deep Dive** -- Read this after completing Stage 1 (s01-s06) or whenever you wonder "why is the course ordered this way?"
+
+This 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?
+
+## Conclusion First
+
+The current `s01 -> s19` order is structurally sound.
+
+Its strength is not just breadth. Its strength is that it grows the system in the same order you should understand it:
+
+1. Build the smallest working agent loop.
+2. Add the control-plane and hardening layers around that loop.
+3. Upgrade session planning into durable work and runtime state.
+4. Only then expand into persistent teams, isolated execution lanes, and external capability buses.
+
+That is the right teaching order because it follows:
+
+**dependency order between mechanisms**
+
+not file order or product packaging order.
+
+## The Four Dependency Lines
+
+This curriculum is really organized by four dependency lines:
+
+1. `core loop dependency`
+2. `control-plane dependency`
+3. `work-state dependency`
+4. `platform-boundary dependency`
+
+In plain English:
+
+```text
+first make the agent run
+  -> then make it run safely
+  -> then make it run durably
+  -> then make it run as a platform
+```
+
+## The Real Shape of the Sequence
+
+```text
+s01-s06
+  build one working single-agent system
+
+s07-s11
+  harden and control that system
+
+s12-s14
+  turn temporary planning into durable work + runtime
+
+s15-s19
+  expand into teammates, protocols, autonomy, isolated lanes, and external capability
+```
+
+After each stage, you should be able to say:
+
+- after `s06`: "I can build one real single-agent harness"
+- after `s11`: "I can make that harness safer, steadier, and easier to extend"
+- after `s14`: "I can manage durable work, background execution, and time-triggered starts"
+- after `s19`: "I understand the platform boundary of a high-completion agent system"
+
+## Why The Early Chapters Must Stay In Their Current Order
+
+### `s01` must stay first
+
+Because it establishes:
+
+- the minimal entry point
+- the turn-by-turn loop
+- why tool results must flow back into the next model call
+
+Without this, everything later becomes disconnected feature talk.
+
+### `s02` must immediately follow `s01`
+
+Because an agent that cannot route intent into tools is still only talking, not acting.
+
+`s02` is where learners first see the harness become real:
+
+- model emits `tool_use`
+- the system dispatches to a handler
+- the tool executes
+- `tool_result` flows back into the loop
+
+### `s03` should stay before `s04`
+
+This is an important guardrail.
+
+You should first understand:
+
+- how the current agent organizes its own work
+
+before learning:
+
+- when to delegate work into a separate sub-context
+
+If `s04` comes too early, subagents become an escape hatch instead of a clear isolation mechanism.
+
+### `s05` should stay before `s06`
+
+These two chapters solve two halves of the same problem:
+
+- `s05`: prevent unnecessary knowledge from entering the context
+- `s06`: manage the context that still must remain active
+
+That order matters. A good system first avoids bloat, then compacts what is still necessary.
+
+## Why `s07-s11` Form One Hardening Block
+
+These chapters all answer the same larger question:
+
+**the loop already works, so how does it become stable, safe, and legible as a real system?**
+
+### `s07` should stay before `s08`
+
+Permission comes first because the system must first answer:
+
+- may this action happen at all
+- should it be denied
+- should it ask the user first
+
+Only after that should you teach hooks, which answer:
+
+- what extra behavior attaches around the loop
+
+So the correct teaching order is:
+
+**gate first, extend second**
+
+### `s09` should stay before `s10`
+
+This is another very important ordering decision.
+
+`s09` teaches:
+
+- what durable information exists
+- which facts deserve long-term storage
+
+`s10` teaches:
+
+- how multiple information sources are assembled into model input
+
+That means:
+
+- memory defines one content source
+- prompt assembly explains how all content sources are combined
+
+If you reverse them, prompt construction starts to feel arbitrary and mysterious.
+
+### `s11` is the right closing chapter for this block
+
+Error recovery is not an isolated feature.
+
+It is where the system finally needs to explain:
+
+- why it is continuing
+- why it is retrying
+- why it is stopping
+
+That only becomes legible after the input path, tool path, state path, and control path already exist.
+
+## Why `s12-s14` Must Stay Goal -> Runtime -> Schedule
+
+This is the easiest part of the curriculum to teach badly if the order is wrong.
+
+### `s12` must stay before `s13`
+
+`s12` teaches:
+
+- what work exists
+- dependency relations between work nodes
+- when downstream work unlocks
+
+`s13` teaches:
+
+- what live execution is currently running
+- where background results go
+- how runtime state writes back
+
+That is the crucial distinction:
+
+- `task` is the durable work goal
+- `runtime task` is the live execution slot
+
+If `s13` comes first, you will almost certainly collapse those two into one concept.
+
+### `s14` must stay after `s13`
+
+Cron does not add another kind of task.
+
+It adds a new start condition:
+
+**time becomes one more way to launch work into the runtime**
+
+So the right order is:
+
+`durable task graph -> runtime slot -> schedule trigger`
+
+## Why `s15-s19` Should Stay Team -> Protocol -> Autonomy -> Worktree -> Capability Bus
+
+### `s15` defines who persists in the system
+
+Before protocols or autonomy make sense, the system needs durable actors:
+
+- who teammates are
+- what identity they carry
+- how they persist across work
+
+### `s16` then defines how those actors coordinate
+
+Protocols should not come before actors.
+
+Protocols exist to structure:
+
+- who requests
+- who approves
+- who responds
+- how requests remain traceable
+
+### `s17` only makes sense after both
+
+Autonomy is easy to teach vaguely.
+
+But in a real system it only becomes clear after:
+
+- persistent teammates exist
+- structured coordination already exists
+
+Otherwise "autonomous claiming" sounds like magic instead of the bounded mechanism it really is.
+
+### `s18` should stay before `s19`
+
+Worktree isolation is a local execution-boundary problem:
+
+- where parallel work actually runs
+- how one work lane stays isolated from another
+
+That should become clear before moving outward into:
+
+- plugins
+- MCP servers
+- external capability routing
+
+Otherwise you risk over-focusing on external capability and under-learning the local platform boundary.
+
+### `s19` is correctly last
+
+It is the outer platform boundary.
+
+It only becomes clean once you already understand:
+
+- local actors
+- local work lanes
+- local durable work
+- local runtime execution
+- then external capability providers
+
+## Five Reorders That Would Make The Course Worse
+
+1. Moving `s04` before `s03`
+   This teaches delegation before local planning.
+
+2. Moving `s10` before `s09`
+   This teaches prompt assembly before the learner understands one of its core inputs.
+
+3. Moving `s13` before `s12`
+   This collapses durable goals and live runtime slots into one confused idea.
+
+4. Moving `s17` before `s15` or `s16`
+   This turns autonomy into vague polling magic.
+
+5. Moving `s19` before `s18`
+   This makes the external platform look more important than the local execution boundary.
+
+## A Good Maintainer Check Before Reordering
+
+Before moving chapters around, ask:
+
+1. Does the learner already understand the prerequisite concept?
+2. Will this reorder blur two concepts that should stay separate?
+3. Is this chapter mainly about goals, runtime state, actors, or capability boundaries?
+4. If I move it earlier, will the reader still be able to build the minimal correct version?
+5. Am I optimizing for understanding, or merely copying source-file order?
+
+If the honest answer to the last question is "source-file order", the reorder is probably a mistake.
+
+## Key Takeaway
+
+**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.**
diff --git a/docs/en/s00e-reference-module-map.md b/docs/en/s00e-reference-module-map.md
new file mode 100644
index 000000000..0b548f50b
--- /dev/null
+++ b/docs/en/s00e-reference-module-map.md
@@ -0,0 +1,214 @@
+# s00e: Reference Module Map
+
+> **Deep Dive** -- Read this when you want to verify how the teaching chapters map to the real production codebase.
+
+This 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?
+
+## Verdict First
+
+Yes.
+
+The 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.
+
+The reason is simple:
+
+- the reference repo contains many surface-level directories
+- but the real design weight is concentrated in a smaller set of control, state, task, team, worktree, and capability modules
+- those modules line up with the current four-stage teaching path
+
+So the right move is **not** to flatten the teaching repo into source-tree order.
+
+The right move is:
+
+- keep the current dependency-driven order
+- make the mapping to the reference repo explicit
+- keep removing low-value product detail from the mainline
+
+## How This Comparison Was Done
+
+The comparison was based on the reference repo's higher-signal clusters, especially modules around:
+
+- `Tool.ts`
+- `state/AppStateStore.ts`
+- `coordinator/coordinatorMode.ts`
+- `memdir/*`
+- `services/SessionMemory/*`
+- `services/toolUseSummary/*`
+- `constants/prompts.ts`
+- `tasks/*`
+- `tools/TodoWriteTool/*`
+- `tools/AgentTool/*`
+- `tools/ScheduleCronTool/*`
+- `tools/EnterWorktreeTool/*`
+- `tools/ExitWorktreeTool/*`
+- `tools/MCPTool/*`
+- `services/mcp/*`
+- `plugins/*`
+- `hooks/toolPermission/*`
+
+This is enough to judge the backbone without dragging you through every product-facing command, compatibility branch, or UI detail.
+
+## The Real Mapping
+
+| Reference repo cluster | Typical examples | Teaching chapter(s) | Why this placement is right |
+|---|---|---|---|
+| 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. |
+| 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. |
+| Session planning | `TodoWriteTool` | `s03` | Session planning is a small but central layer. It belongs early, before durable tasks. |
+| 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. |
+| 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. |
+| 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. |
+| 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. |
+| 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. |
+| 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. |
+| 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. |
+| 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. |
+| Durable work graph | task records, task board concepts, dependency unlocks | `s12` | The teaching repo correctly separates durable work goals from temporary session planning. |
+| 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`. |
+| Scheduled triggers | `ScheduleCronTool/*`, `useScheduledTasks` | `s14` | Scheduling appears after runtime work exists, which is exactly the correct dependency order. |
+| Persistent teammates | `InProcessTeammateTask`, team tools, agent registries | `s15` | The source clearly grows from one-shot subagents into durable actors. Teaching teammates later is correct. |
+| 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. |
+| 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. |
+| 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. |
+| 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. |
+
+## The Most Important Validation Points
+
+The reference repo strongly confirms five teaching choices.
+
+### 1. `s03` should stay before `s12`
+
+The source contains both:
+
+- small session planning
+- larger durable task/runtime machinery
+
+Those are not the same thing.
+
+The teaching repo is correct to teach:
+
+`session planning first -> durable tasks later`
+
+### 2. `s09` should stay before `s10`
+
+The source builds the model input from multiple sources, including memory.
+
+That means:
+
+- memory is one input source
+- prompt assembly is the pipeline that combines sources
+
+So memory should be explained before prompt assembly.
+
+### 3. `s12` must stay before `s13`
+
+The runtime-task union in the reference repo is one of the strongest pieces of evidence in the whole comparison.
+
+It shows that:
+
+- durable work definitions
+- live running executions
+
+must stay conceptually separate.
+
+If `s13` came first, you would almost certainly merge those two layers.
+
+### 4. `s15 -> s16 -> s17` is the right order
+
+The source has:
+
+- durable actors
+- structured coordination
+- autonomous resume / claiming behavior
+
+Autonomy depends on the first two. So the current order is correct.
+
+### 5. `s18` should stay before `s19`
+
+The reference repo treats worktree isolation as a local execution-boundary mechanism.
+
+That should be understood before you are asked to reason about:
+
+- external capability providers
+- MCP servers
+- plugin-installed surfaces
+
+Otherwise external capability looks more central than it really is.
+
+## What This Teaching Repo Should Still Avoid Copying
+
+The reference repo contains many things that are real, but should still not dominate the teaching mainline:
+
+- CLI command surface area
+- UI rendering details
+- telemetry and analytics branches
+- product integration glue
+- remote and enterprise wiring
+- platform-specific compatibility code
+- line-by-line naming trivia
+
+These are valid implementation details.
+
+They are not the right center of a 0-to-1 teaching path.
+
+## Where The Teaching Repo Must Be Extra Careful
+
+The mapping also reveals several places where things can easily drift into confusion.
+
+### 1. Do not merge subagents and teammates into one vague concept
+
+The reference repo's `AgentTool` spans:
+
+- one-shot delegation
+- async/background workers
+- teammate-like persistent workers
+- worktree-isolated workers
+
+That is exactly why the teaching repo should split the story across:
+
+- `s04`
+- `s15`
+- `s17`
+- `s18`
+
+### 2. Do not teach worktree as "just a git trick"
+
+The source shows closeout, resume, cleanup, and isolation state around worktrees.
+
+So `s18` should keep teaching:
+
+- lane identity
+- task binding
+- keep/remove closeout
+- resume and cleanup concerns
+
+not just `git worktree add`.
+
+### 3. Do not reduce MCP to "remote tools"
+
+The source includes:
+
+- tools
+- resources
+- prompts
+- elicitation / connection state
+- plugin mediation
+
+So `s19` should keep a tools-first teaching path, but still explain the wider capability-bus boundary.
+
+## Final Judgment
+
+Compared against the high-signal module clusters in the reference repo, the current chapter order is sound.
+
+The biggest remaining quality gains do **not** come from another major reorder.
+
+They come from:
+
+- cleaner bridge docs
+- stronger entity-boundary explanations
+- tighter multilingual consistency
+- web pages that expose the same learning map clearly
+
+## Key Takeaway
+
+**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.**
diff --git a/docs/en/s00f-code-reading-order.md b/docs/en/s00f-code-reading-order.md
new file mode 100644
index 000000000..4356bb262
--- /dev/null
+++ b/docs/en/s00f-code-reading-order.md
@@ -0,0 +1,156 @@
+# s00f: Code Reading Order
+
+> **Deep Dive** -- Read this when you're about to open the Python agent files and want a strategy for reading them.
+
+This 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?
+
+## Conclusion First
+
+Do not read the code like this:
+
+- do not start with the longest file
+- do not jump straight into the most "advanced" chapter
+- do not open `web/` first and then guess the mainline
+- do not treat all `agents/*.py` files like one flat source pool
+
+The stable rule is simple:
+
+**read the code in the same order as the curriculum.**
+
+Inside each chapter file, keep the same reading order:
+
+1. state structures
+2. tool definitions or registries
+3. the function that advances one turn
+4. the CLI entry last
+
+## Why This Page Exists
+
+You 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.
+
+Typical mistakes:
+
+- staring at the bottom half of a long file first
+- reading a pile of `run_*` helpers before knowing where they connect
+- jumping into late platform chapters and treating early chapters as "too simple"
+- collapsing `task`, `runtime task`, `teammate`, and `worktree` back into one vague idea
+
+## Use The Same Reading Template For Every Agent File
+
+For any `agents/sXX_*.py`, read in this order:
+
+### 1. File header
+
+Answer two questions before anything else:
+
+- what is this chapter teaching
+- what is it intentionally not teaching yet
+
+### 2. State structures or manager classes
+
+Look for things like:
+
+- `LoopState`
+- `PlanningState`
+- `CompactState`
+- `TaskManager`
+- `BackgroundManager`
+- `TeammateManager`
+- `WorktreeManager`
+
+### 3. Tool list or registry
+
+Look for:
+
+- `TOOLS`
+- `TOOL_HANDLERS`
+- `build_tool_pool()`
+- the important `run_*` entrypoints
+
+### 4. The turn-advancing function
+
+Usually this is one of:
+
+- `run_one_turn(...)`
+- `agent_loop(...)`
+- a chapter-specific `handle_*`
+
+### 5. CLI entry last
+
+`if __name__ == "__main__"` matters, but it should not be the first thing you study.
+
+## Stage 1: `s01-s06`
+
+This stage is the single-agent backbone taking shape.
+
+| Chapter | File | Read First | Then Read | Confirm Before Moving On |
+|---|---|---|---|---|
+| `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` |
+| `s02` | `agents/s02_tool_use.py` | `safe_path()` | tool handlers -> `TOOL_HANDLERS` -> `agent_loop()` | You understand how tools grow without rewriting the loop |
+| `s03` | `agents/s03_todo_write.py` | planning state types | todo handler path -> reminder injection -> `agent_loop()` | You understand visible session planning state |
+| `s04` | `agents/s04_subagent.py` | `AgentTemplate` | `run_subagent()` -> parent `agent_loop()` | You understand that subagents are mainly context isolation |
+| `s05` | `agents/s05_skill_loading.py` | skill registry types | registry methods -> `agent_loop()` | You understand discover light, load deep |
+| `s06` | `agents/s06_context_compact.py` | `CompactState` | persist / micro compact / history compact -> `agent_loop()` | You understand that compaction relocates detail instead of deleting continuity |
+
+### Deep Agents track for Stage 1
+
+After reading the hand-written `agents/s01-s06` baseline, you can open
+`agents_deepagents/s01_agent_loop.py` through
+`agents_deepagents/s11_error_recovery.py` as the staged Deep Agents track. It
+keeps the original files unchanged, uses OpenAI-style `OPENAI_API_KEY` /
+`OPENAI_MODEL` configuration, and shows how the stage track evolves chapter by
+chapter without exposing later capabilities too early. The web UI does not
+surface this track yet.
+
+## Stage 2: `s07-s11`
+
+### Deep Agents track for Stage 2
+
+After the stage-1 Deep Agents files, continue with `agents_deepagents/s07_permission_system.py` through `agents_deepagents/s11_error_recovery.py`. This Stage-2 slice keeps the original chapter order while layering permissions, hooks, memory, prompt assembly, and recovery on top of the same staged Deep Agents harness.
+
+This stage hardens the control plane around a working single agent.
+
+| Chapter | File | Read First | Then Read | Confirm Before Moving On |
+|---|---|---|---|---|
+| `s07` | `agents/s07_permission_system.py` | validator / manager | permission path -> `run_bash()` -> `agent_loop()` | You understand gate before execute |
+| `s08` | `agents/s08_hook_system.py` | `HookManager` | hook registration and dispatch -> `agent_loop()` | You understand fixed extension points |
+| `s09` | `agents/s09_memory_system.py` | memory managers | save path -> prompt build -> `agent_loop()` | You understand memory as a long-term information layer |
+| `s10` | `agents/s10_system_prompt.py` | `SystemPromptBuilder` | reminder builder -> `agent_loop()` | You understand input assembly as a pipeline |
+| `s11` | `agents/s11_error_recovery.py` | compact / backoff helpers | recovery branches -> `agent_loop()` | You understand continuation after failure |
+
+## Stage 3: `s12-s14`
+
+This stage turns the harness into a work runtime.
+
+| Chapter | File | Read First | Then Read | Confirm Before Moving On |
+|---|---|---|---|---|
+| `s12` | `agents/s12_task_system.py` | `TaskManager` | task create / dependency / unlock -> `agent_loop()` | You understand durable work goals |
+| `s13` | `agents/s13_background_tasks.py` | `NotificationQueue` / `BackgroundManager` | background registration -> notification drain -> `agent_loop()` | You understand runtime slots |
+| `s14` | `agents/s14_cron_scheduler.py` | `CronLock` / `CronScheduler` | cron match -> trigger -> `agent_loop()` | You understand future start conditions |
+
+## Stage 4: `s15-s19`
+
+This stage is about platform boundaries.
+
+| Chapter | File | Read First | Then Read | Confirm Before Moving On |
+|---|---|---|---|---|
+| `s15` | `agents/s15_agent_teams.py` | `MessageBus` / `TeammateManager` | roster / inbox / loop -> `agent_loop()` | You understand persistent teammates |
+| `s16` | `agents/s16_team_protocols.py` | `RequestStore` / `TeammateManager` | request handlers -> `agent_loop()` | You understand request-response plus `request_id` |
+| `s17` | `agents/s17_autonomous_agents.py` | claim and identity helpers | claim path -> resume path -> `agent_loop()` | You understand idle check -> safe claim -> resume work |
+| `s18` | `agents/s18_worktree_task_isolation.py` | `TaskManager` / `WorktreeManager` / `EventBus` | worktree lifecycle -> `agent_loop()` | You understand goals versus execution lanes |
+| `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 |
+
+## Best Doc + Code Loop
+
+For each chapter:
+
+1. read the chapter prose
+2. read the bridge note for that chapter
+3. open the matching `agents/sXX_*.py`
+4. follow the order: state -> tools -> turn driver -> CLI entry
+5. run the demo once
+6. rewrite the smallest version from scratch
+
+## Key Takeaway
+
+**Code reading order must obey teaching order: read boundaries first, then state, then the path that advances the loop.**
diff --git a/docs/en/s01-the-agent-loop.md b/docs/en/s01-the-agent-loop.md
index 405646869..67b3700dc 100644
--- a/docs/en/s01-the-agent-loop.md
+++ b/docs/en/s01-the-agent-loop.md
@@ -1,16 +1,24 @@
 # s01: The Agent Loop
 
-`[ s01 ] s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
+`[ s01 ] > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
 
-> *"One loop & Bash is all you need"* -- one tool + one loop = an agent.
->
-> **Harness layer**: The loop -- the model's first connection to the real world.
+## What You'll Learn
 
-## Problem
+- How the core agent loop works: send messages, run tools, feed results back
+- Why the "write-back" step is the single most important idea in agent design
+- How to build a working agent in under 30 lines of Python
 
-A language model can reason about code, but it can't *touch* the real world -- can't read files, run tests, or check errors. Without a loop, every tool call requires you to manually copy-paste results back. You become the loop.
+Imagine 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.
 
-## Solution
+## The Problem
+
+Without 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.
+
+The solution is simple: let the code do the looping.
+
+## The Solution
+
+Here's the entire system in one picture:
 
 ```
 +--------+      +-------+      +---------+
@@ -20,20 +28,20 @@ A language model can reason about code, but it can't *touch* the real world -- c
                     ^                |
                     |   tool_result  |
                     +----------------+
-                    (loop until stop_reason != "tool_use")
+                    (loop until the model stops calling tools)
 ```
 
-One exit condition controls the entire flow. The loop runs until the model stops calling tools.
+The 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.
 
 ## How It Works
 
-1. User prompt becomes the first message.
+**Step 1.** The user's prompt becomes the first message.
 
 ```python
 messages.append({"role": "user", "content": query})
 ```
 
-2. Send messages + tool definitions to the LLM.
+**Step 2.** Send the conversation to the model, along with tool definitions.
 
 ```python
 response = client.messages.create(
@@ -42,15 +50,17 @@ response = client.messages.create(
 )
 ```
 
-3. Append the assistant response. Check `stop_reason` -- if the model didn't call a tool, we're done.
+**Step 3.** Add the model's response to the conversation. Then check: did it call a tool, or is it done?
 
 ```python
 messages.append({"role": "assistant", "content": response.content})
+
+# If the model didn't call a tool, the task is finished
 if response.stop_reason != "tool_use":
     return
 ```
 
-4. Execute each tool call, collect results, append as a user message. Loop back to step 2.
+**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.
 
 ```python
 results = []
@@ -59,13 +69,14 @@ for block in response.content:
         output = run_bash(block.input["command"])
         results.append({
             "type": "tool_result",
-            "tool_use_id": block.id,
+            "tool_use_id": block.id,  # links result to the tool call
             "content": output,
         })
+# This is the "write-back" -- the model can now see the real-world result
 messages.append({"role": "user", "content": results})
 ```
 
-Assembled into one function:
+Put it all together, and the entire agent fits in one function:
 
 ```python
 def agent_loop(query):
@@ -78,7 +89,7 @@ def agent_loop(query):
         messages.append({"role": "assistant", "content": response.content})
 
         if response.stop_reason != "tool_use":
-            return
+            return  # model is done
 
         results = []
         for block in response.content:
@@ -92,7 +103,9 @@ def agent_loop(query):
         messages.append({"role": "user", "content": results})
 ```
 
-That's the entire agent in under 30 lines. Everything else in this course layers on top -- without changing the loop.
+That's the entire agent in under 30 lines. Everything else in this course layers on top of this loop -- without changing its core shape.
+
+> **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.
 
 ## What Changed
 
@@ -114,3 +127,19 @@ python agents/s01_agent_loop.py
 2. `List all Python files in this directory`
 3. `What is the current git branch?`
 4. `Create a directory called test_output and write 3 files in it`
+
+## What You've Mastered
+
+At this point, you can:
+
+- Build a working agent loop from scratch
+- Explain why tool results must flow back into the conversation (the "write-back")
+- Redraw the loop from memory: messages -> model -> tool execution -> write-back -> next turn
+
+## What's Next
+
+Right 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.
+
+## Key Takeaway
+
+> 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.
diff --git a/docs/en/s02-tool-use.md b/docs/en/s02-tool-use.md
index 279774b82..2e4b76ec1 100644
--- a/docs/en/s02-tool-use.md
+++ b/docs/en/s02-tool-use.md
@@ -1,18 +1,22 @@
 # s02: Tool Use
 
-`s01 > [ s02 ] s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
+`s01 > [ s02 ] > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
 
-> *"Adding a tool means adding one handler"* -- the loop stays the same; new tools register into the dispatch map.
->
-> **Harness layer**: Tool dispatch -- expanding what the model can reach.
+## What You'll Learn
 
-## Problem
+- How to build a dispatch map (a routing table that maps tool names to handler functions)
+- How path sandboxing prevents the model from escaping its workspace
+- How to add new tools without touching the agent loop
 
-With only `bash`, the agent shells out for everything. `cat` truncates unpredictably, `sed` fails on special characters, and every bash call is an unconstrained security surface. Dedicated tools like `read_file` and `write_file` let you enforce path sandboxing at the tool level.
+If 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.
 
-The key insight: adding tools does not require changing the loop.
+## The Problem
 
-## Solution
+With 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?
+
+## The Solution
+
+The 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.
 
 ```
 +--------+      +-------+      +------------------+
@@ -31,7 +35,7 @@ One lookup replaces any if/elif chain.
 
 ## How It Works
 
-1. Each tool gets a handler function. Path sandboxing prevents workspace escape.
+**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.
 
 ```python
 def safe_path(p: str) -> Path:
@@ -45,10 +49,10 @@ def run_read(path: str, limit: int = None) -> str:
     lines = text.splitlines()
     if limit and limit < len(lines):
         lines = lines[:limit]
-    return "\n".join(lines)[:50000]
+    return "\n".join(lines)[:50000]  # hard cap to avoid blowing up the context
 ```
 
-2. The dispatch map links tool names to handlers.
+**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.
 
 ```python
 TOOL_HANDLERS = {
@@ -60,7 +64,7 @@ TOOL_HANDLERS = {
 }
 ```
 
-3. In the loop, look up the handler by name. The loop body itself is unchanged from s01.
+**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.
 
 ```python
 for block in response.content:
@@ -97,3 +101,21 @@ python agents/s02_tool_use.py
 2. `Create a file called greet.py with a greet(name) function`
 3. `Edit greet.py to add a docstring to the function`
 4. `Read greet.py to verify the edit worked`
+
+## What You've Mastered
+
+At this point, you can:
+
+- Wire any new tool into the agent by adding one handler and one schema entry -- without touching the loop.
+- Enforce path sandboxing so the model cannot read or write outside its workspace.
+- Explain why a dispatch map scales better than an if/elif chain.
+
+Keep 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.
+
+## What's Next
+
+Your 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.
+
+## Key Takeaway
+
+> The loop should not care how a tool works internally. It only needs a reliable route from tool name to handler.
diff --git a/docs/en/s02a-tool-control-plane.md b/docs/en/s02a-tool-control-plane.md
new file mode 100644
index 000000000..e5108226b
--- /dev/null
+++ b/docs/en/s02a-tool-control-plane.md
@@ -0,0 +1,214 @@
+# s02a: Tool Control Plane
+
+> **Deep Dive** -- Best read after s02 and before s07. It shows why tools become more than a simple lookup table.
+
+### When to Read This
+
+After you understand basic tool dispatch and before you add permissions.
+
+---
+
+> This bridge document answers another key question:
+>
+> **Why is a tool system more than a `tool_name -> handler` table?**
+
+## Why This Document Exists
+
+`s02` correctly teaches tool registration and dispatch first.
+
+That is the right teaching move because you should first understand how the model turns intent into action.
+
+But later the tool layer starts carrying much more responsibility:
+
+- permission checks
+- MCP routing
+- notifications
+- shared runtime state
+- message access
+- app state
+- capability-specific restrictions
+
+At that point, the tool layer is no longer just a function table.
+
+It becomes a control plane (the coordination layer that decides *how* each tool call gets routed and executed, rather than performing the tool work itself).
+
+## Terms First
+
+### Tool control plane
+
+The part of the system that decides **how** a tool call executes:
+
+- where it runs
+- whether it is allowed
+- what state it can access
+- whether it is native or external
+
+### Execution context
+
+The runtime environment visible to the tool:
+
+- current working directory
+- current permission mode
+- current messages
+- available MCP clients
+- app state and notification channels
+
+### Capability source
+
+Not every tool comes from the same place. Common sources:
+
+- native local tools
+- MCP tools
+- agent/team/task/worktree platform tools
+
+## The Smallest Useful Mental Model
+
+Think of the tool system as four layers:
+
+```text
+1. ToolSpec
+   what the model sees
+
+2. Tool Router
+   where the request gets sent
+
+3. ToolUseContext
+   what environment the tool can access
+
+4. Tool Result Envelope
+   how the output returns to the main loop
+```
+
+The biggest step up is layer 3:
+
+**high-completion systems are defined less by the dispatch table and more by the shared execution context.**
+
+## Core Structures
+
+### `ToolSpec`
+
+```python
+tool = {
+    "name": "read_file",
+    "description": "Read file contents.",
+    "input_schema": {...},
+}
+```
+
+### `ToolDispatchMap`
+
+```python
+handlers = {
+    "read_file": read_file,
+    "write_file": write_file,
+    "bash": run_bash,
+}
+```
+
+Necessary, but not sufficient.
+
+### `ToolUseContext`
+
+```python
+tool_use_context = {
+    "tools": handlers,
+    "permission_context": {...},
+    "mcp_clients": {},
+    "messages": [...],
+    "app_state": {...},
+    "notifications": [],
+    "cwd": "...",
+}
+```
+
+The key point:
+
+Tools stop receiving only input parameters.
+They start receiving a shared runtime environment.
+
+### `ToolResultEnvelope`
+
+```python
+result = {
+    "ok": True,
+    "content": "...",
+    "is_error": False,
+    "attachments": [],
+}
+```
+
+This makes it easier to support:
+
+- plain text output
+- structured output
+- error output
+- attachment-like results
+
+## Why `ToolUseContext` Eventually Becomes Necessary
+
+Compare two systems.
+
+### System A: dispatch map only
+
+```python
+output = handlers[tool_name](**tool_input)
+```
+
+Fine for a demo.
+
+### System B: dispatch map plus execution context
+
+```python
+output = handlers[tool_name](tool_input, tool_use_context)
+```
+
+Closer to a real platform.
+
+Why?
+
+Because now:
+
+- `bash` needs permissions
+- `mcp__...` needs a client
+- `agent` tools need execution environment setup
+- `task_output` may need file writes plus notification write-back
+
+## Minimal Implementation Path
+
+### 1. Keep `ToolSpec` and handlers
+
+Do not throw away the simple model.
+
+### 2. Introduce one shared context object
+
+```python
+class ToolUseContext:
+    def __init__(self):
+        self.handlers = {}
+        self.permission_context = {}
+        self.mcp_clients = {}
+        self.messages = []
+        self.app_state = {}
+        self.notifications = []
+```
+
+### 3. Let all handlers receive the context
+
+```python
+def run_tool(tool_name: str, tool_input: dict, ctx: ToolUseContext):
+    handler = ctx.handlers[tool_name]
+    return handler(tool_input, ctx)
+```
+
+### 4. Route by capability source
+
+```python
+def route_tool(tool_name: str, tool_input: dict, ctx: ToolUseContext):
+    if tool_name.startswith("mcp__"):
+        return run_mcp_tool(tool_name, tool_input, ctx)
+    return run_native_tool(tool_name, tool_input, ctx)
+```
+
+## Key Takeaway
+
+**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.**
diff --git a/docs/en/s02b-tool-execution-runtime.md b/docs/en/s02b-tool-execution-runtime.md
new file mode 100644
index 000000000..aa43438d9
--- /dev/null
+++ b/docs/en/s02b-tool-execution-runtime.md
@@ -0,0 +1,287 @@
+# s02b: Tool Execution Runtime
+
+> **Deep Dive** -- Best read after s02, when you want to understand concurrent tool execution.
+
+### When to Read This
+
+When you start wondering how multiple tool calls in one turn get executed safely.
+
+---
+
+> This bridge note is not about how tools are registered.
+>
+> It is about a deeper question:
+>
+> **When the model emits multiple tool calls, what rules decide concurrency, progress updates, result ordering, and context merging?**
+
+## Why This Note Exists
+
+`s02` correctly teaches:
+
+- tool schema
+- dispatch map
+- `tool_result` flowing back into the loop
+
+That is the right starting point.
+
+But once the system grows, the hard questions move one layer deeper:
+
+- which tools can run in parallel
+- which tools should stay serial
+- whether long-running tools should emit progress first
+- whether concurrent results should write back in completion order or original order
+- whether tool execution mutates shared context
+- how concurrent mutations should merge safely
+
+Those questions are not about registration anymore.
+
+They 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.
+
+## Terms First
+
+### What "tool execution runtime" means here
+
+This is not the programming language runtime.
+
+Here it means:
+
+> the rules the system uses once tool calls actually start executing
+
+Those rules include scheduling, tracking, yielding progress, and merging results.
+
+### What "concurrency safe" means
+
+A tool is concurrency safe when:
+
+> it can run alongside similar work without corrupting shared state
+
+Typical read-only tools are often safe:
+
+- `read_file`
+- some search tools
+- query-only MCP tools
+
+Many write tools are not:
+
+- `write_file`
+- `edit_file`
+- tools that modify shared application state
+
+### What a progress message is
+
+A progress message means:
+
+> the tool is not done yet, but the system already surfaces what it is doing
+
+This keeps the user informed during long-running operations rather than leaving them staring at silence.
+
+### What a context modifier is
+
+Some tools do more than return text.
+
+They also modify shared runtime context, for example:
+
+- update a notification queue
+- record active tools
+- mutate app state
+
+That shared-state mutation is called a context modifier.
+
+## The Minimum Mental Model
+
+Do not flatten tool execution into:
+
+```text
+tool_use -> handler -> result
+```
+
+A better mental model is:
+
+```text
+tool_use blocks
+  ->
+partition by concurrency safety
+  ->
+choose concurrent or serial execution
+  ->
+emit progress if needed
+  ->
+write results back in stable order
+  ->
+merge queued context modifiers
+```
+
+Two upgrades matter most:
+
+- concurrency is not "all tools run together"
+- shared context should not be mutated in random completion order
+
+## Core Records
+
+### 1. `ToolExecutionBatch`
+
+A minimal teaching batch can look like:
+
+```python
+batch = {
+    "is_concurrency_safe": True,
+    "blocks": [tool_use_1, tool_use_2, tool_use_3],
+}
+```
+
+The point is simple:
+
+- tools are not always handled one by one
+- the runtime groups them into execution batches first
+
+### 2. `TrackedTool`
+
+If you want a higher-completion execution layer, track each tool explicitly:
+
+```python
+tracked_tool = {
+    "id": "toolu_01",
+    "name": "read_file",
+    "status": "queued",   # queued / executing / completed / yielded
+    "is_concurrency_safe": True,
+    "pending_progress": [],
+    "results": [],
+    "context_modifiers": [],
+}
+```
+
+This makes the runtime able to answer:
+
+- what is still waiting
+- what is already running
+- what has completed
+- what has already yielded progress
+
+### 3. `MessageUpdate`
+
+Tool execution may produce more than one final result.
+
+A minimal update can be treated as:
+
+```python
+update = {
+    "message": maybe_message,
+    "new_context": current_context,
+}
+```
+
+In a larger runtime, updates usually split into two channels:
+
+- messages that should surface upstream immediately
+- context changes that should stay internal until merge time
+
+### 4. Queued context modifiers
+
+This is easy to skip, but it is one of the most important ideas.
+
+In a concurrent batch, the safer strategy is not:
+
+> "whichever tool finishes first mutates shared context first"
+
+The safer strategy is:
+
+> queue context modifiers first, then merge them later in the original tool order
+
+For example:
+
+```python
+queued_context_modifiers = {
+    "toolu_01": [modify_ctx_a],
+    "toolu_02": [modify_ctx_b],
+}
+```
+
+## Minimum Implementation Steps
+
+### Step 1: classify concurrency safety
+
+```python
+def is_concurrency_safe(tool_name: str, tool_input: dict) -> bool:
+    return tool_name in {"read_file", "search_files"}
+```
+
+### Step 2: partition before execution
+
+```python
+batches = partition_tool_calls(tool_uses)
+
+for batch in batches:
+    if batch["is_concurrency_safe"]:
+        run_concurrently(batch["blocks"])
+    else:
+        run_serially(batch["blocks"])
+```
+
+### Step 3: let concurrent batches emit progress
+
+```python
+for update in run_concurrently(...):
+    if update.get("message"):
+        yield update["message"]
+```
+
+### Step 4: merge context in stable order
+
+```python
+queued_modifiers = {}
+
+for update in concurrent_updates:
+    if update.get("context_modifier"):
+        queued_modifiers[update["tool_id"]].append(update["context_modifier"])
+
+for tool in original_batch_order:
+    for modifier in queued_modifiers.get(tool["id"], []):
+        context = modifier(context)
+```
+
+This is one of the places where a teaching repo can still stay simple while remaining honest about the real system shape.
+
+## The Picture You Should Hold
+
+```text
+tool_use blocks
+  |
+  v
+partition by concurrency safety
+  |
+  +-- safe batch ----------> concurrent execution
+  |                            |
+  |                            +-- progress updates
+  |                            +-- final results
+  |                            +-- queued context modifiers
+  |
+  +-- exclusive batch -----> serial execution
+                               |
+                               +-- direct result
+                               +-- direct context update
+```
+
+## Why This Matters More Than the Dispatch Map
+
+In a tiny demo:
+
+```python
+handlers[tool_name](tool_input)
+```
+
+is enough.
+
+But in a higher-completion agent, the hard part is no longer calling the right handler.
+
+The hard part is:
+
+- scheduling multiple tools safely
+- keeping progress visible
+- making result ordering stable
+- preventing shared context from becoming nondeterministic
+
+That is why tool execution runtime deserves its own deep dive.
+
+## Key Takeaway
+
+**Once the model emits multiple tool calls per turn, the hard problem shifts from dispatch to safe concurrent execution with stable result ordering.**
diff --git a/docs/en/s03-todo-write.md b/docs/en/s03-todo-write.md
index e44611475..5b6beba07 100644
--- a/docs/en/s03-todo-write.md
+++ b/docs/en/s03-todo-write.md
@@ -1,16 +1,22 @@
 # s03: TodoWrite
 
-`s01 > s02 > [ s03 ] s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
+`s01 > s02 > [ s03 ] > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
 
-> *"An agent without a plan drifts"* -- list the steps first, then execute.
->
-> **Harness layer**: Planning -- keeping the model on course without scripting the route.
+## What You'll Learn
 
-## Problem
+- How session planning keeps the model on track during multi-step tasks
+- How a structured todo list with status tracking replaces fragile free-form plans
+- How gentle reminders (nag injection) pull the model back when it drifts
 
-On multi-step tasks, the model loses track. It repeats work, skips steps, or wanders off. Long conversations make this worse -- the system prompt fades as tool results fill the context. A 10-step refactoring might complete steps 1-3, then the model starts improvising because it forgot steps 4-10.
+Have 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.
 
-## Solution
+## The Problem
+
+On 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.
+
+## The Solution
+
+Give the model a `todo` tool that maintains a structured checklist. Then inject gentle reminders when the model goes too long without updating its plan.
 
 ```
 +--------+      +-------+      +---------+
@@ -34,7 +40,7 @@ On multi-step tasks, the model loses track. It repeats work, skips steps, or wan
 
 ## How It Works
 
-1. TodoManager stores items with statuses. Only one item can be `in_progress` at a time.
+**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.
 
 ```python
 class TodoManager:
@@ -49,10 +55,10 @@ class TodoManager:
         if in_progress_count > 1:
             raise ValueError("Only one task can be in_progress")
         self.items = validated
-        return self.render()
+        return self.render()  # returns the checklist as formatted text
 ```
 
-2. The `todo` tool goes into the dispatch map like any other tool.
+**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.
 
 ```python
 TOOL_HANDLERS = {
@@ -61,19 +67,18 @@ TOOL_HANDLERS = {
 }
 ```
 
-3. A nag reminder injects a nudge if the model goes 3+ rounds without calling `todo`.
+**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.
 
 ```python
-if rounds_since_todo >= 3 and messages:
-    last = messages[-1]
-    if last["role"] == "user" and isinstance(last.get("content"), list):
-        last["content"].insert(0, {
-            "type": "text",
-            "text": "<reminder>Update your todos.</reminder>",
-        })
+if rounds_since_todo >= 3:
+    results.insert(0, {
+        "type": "text",
+        "text": "<reminder>Update your todos.</reminder>",
+    })
+messages.append({"role": "user", "content": results})
 ```
 
-The "one in_progress at a time" constraint forces sequential focus. The nag reminder creates accountability.
+The "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.
 
 ## What Changed From s02
 
@@ -94,3 +99,24 @@ python agents/s03_todo_write.py
 1. `Refactor the file hello.py: add type hints, docstrings, and a main guard`
 2. `Create a Python package with __init__.py, utils.py, and tests/test_utils.py`
 3. `Review all Python files and fix any style issues`
+
+Watch 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.
+
+## What You've Mastered
+
+At this point, you can:
+
+- Add session planning to any agent by dropping a `todo` tool into the dispatch map.
+- Enforce sequential focus with the "one in_progress at a time" constraint.
+- Use nag injection to pull the model back on track when it drifts.
+- Explain why structured state beats free-form prose for multi-step plans.
+
+Keep 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.
+
+## What's Next
+
+Your 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.
+
+## Key Takeaway
+
+> Once the plan lives in structured state instead of free-form prose, the agent drifts much less.
diff --git a/docs/en/s04-subagent.md b/docs/en/s04-subagent.md
index 8a6ff2a6e..37ba0adf4 100644
--- a/docs/en/s04-subagent.md
+++ b/docs/en/s04-subagent.md
@@ -1,16 +1,22 @@
 # s04: Subagents
 
-`s01 > s02 > s03 > [ s04 ] s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
+`s01 > s02 > s03 > [ s04 ] > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
 
-> *"Break big tasks down; each subtask gets a clean context"* -- subagents use independent messages[], keeping the main conversation clean.
->
-> **Harness layer**: Context isolation -- protecting the model's clarity of thought.
+## What You'll Learn
+- Why exploring a side question can pollute the parent agent's context
+- How a subagent gets a fresh, empty message history
+- How only a short summary travels back to the parent
+- Why the child's full message history is discarded after use
 
-## Problem
+Imagine 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.
 
-As the agent works, its messages array grows. Every file read, every bash output stays in context permanently. "What testing framework does this project use?" might require reading 5 files, but the parent only needs the answer: "pytest."
+## The Problem
 
-## Solution
+As 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.
+
+## The Solution
+
+The 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.
 
 ```
 Parent agent                     Subagent
@@ -28,7 +34,7 @@ Parent context stays clean. Subagent context is discarded.
 
 ## How It Works
 
-1. The parent gets a `task` tool. The child gets all base tools except `task` (no recursive spawning).
+**Step 1.** The parent gets a `task` tool that the child does not. This prevents recursive spawning -- a child cannot create its own children.
 
 ```python
 PARENT_TOOLS = CHILD_TOOLS + [
@@ -42,7 +48,7 @@ PARENT_TOOLS = CHILD_TOOLS + [
 ]
 ```
 
-2. The subagent starts with `messages=[]` and runs its own loop. Only the final text returns to the parent.
+**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`.
 
 ```python
 def run_subagent(prompt: str) -> str:
@@ -66,12 +72,13 @@ def run_subagent(prompt: str) -> str:
                     "tool_use_id": block.id,
                     "content": str(output)[:50000]})
         sub_messages.append({"role": "user", "content": results})
+    # Extract only the final text -- everything else is thrown away
     return "".join(
         b.text for b in response.content if hasattr(b, "text")
     ) or "(no summary)"
 ```
 
-The child's entire message history (possibly 30+ tool calls) is discarded. The parent receives a one-paragraph summary as a normal `tool_result`.
+The 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.
 
 ## What Changed From s03
 
@@ -92,3 +99,22 @@ python agents/s04_subagent.py
 1. `Use a subtask to find what testing framework this project uses`
 2. `Delegate: read all .py files and summarize what each one does`
 3. `Use a task to create a new module, then verify it from here`
+
+## What You've Mastered
+
+At this point, you can:
+
+- Explain why a subagent is primarily a **context boundary**, not a process trick
+- Spawn a one-shot child agent with a fresh `messages=[]`
+- Return only a summary to the parent, discarding all intermediate exploration
+- Decide which tools the child should and should not have access to
+
+You 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.
+
+## What's Next
+
+So 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.
+
+## Key Takeaway
+
+> A subagent is a disposable scratch pad: fresh context in, short summary out, everything else discarded.
diff --git a/docs/en/s05-skill-loading.md b/docs/en/s05-skill-loading.md
index 0cf193850..96bcbacf1 100644
--- a/docs/en/s05-skill-loading.md
+++ b/docs/en/s05-skill-loading.md
@@ -1,16 +1,22 @@
 # s05: Skills
 
-`s01 > s02 > s03 > s04 > [ s05 ] s06 | s07 > s08 > s09 > s10 > s11 > s12`
+`s01 > s02 > s03 > s04 > [ s05 ] > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
 
-> *"Load knowledge when you need it, not upfront"* -- inject via tool_result, not the system prompt.
->
-> **Harness layer**: On-demand knowledge -- domain expertise, loaded when the model asks.
+## What You'll Learn
+- Why stuffing all domain knowledge into the system prompt wastes tokens
+- The two-layer loading pattern: cheap names up front, expensive bodies on demand
+- How frontmatter (YAML metadata at the top of a file) gives each skill a name and description
+- How the model decides for itself which skill to load and when
 
-## Problem
+You 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.
 
-You want the agent to follow domain-specific workflows: git conventions, testing patterns, code review checklists. Putting everything in the system prompt wastes tokens on unused skills. 10 skills at 2000 tokens each = 20,000 tokens, most of which are irrelevant to any given task.
+## The Problem
 
-## Solution
+You 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.
+
+## The Solution
+
+Split 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.
 
 ```
 System prompt (Layer 1 -- always present):
@@ -31,11 +37,9 @@ When model calls load_skill("git"):
 +--------------------------------------+
 ```
 
-Layer 1: skill *names* in system prompt (cheap). Layer 2: full *body* via tool_result (on demand).
-
 ## How It Works
 
-1. Each skill is a directory containing a `SKILL.md` with YAML frontmatter.
+**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.
 
 ```
 skills/
@@ -45,7 +49,7 @@ skills/
     SKILL.md       # ---\n name: code-review\n description: Review code\n ---\n ...
 ```
 
-2. SkillLoader scans for `SKILL.md` files, uses the directory name as the skill identifier.
+**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.
 
 ```python
 class SkillLoader:
@@ -54,10 +58,12 @@ class SkillLoader:
         for f in sorted(skills_dir.rglob("SKILL.md")):
             text = f.read_text()
             meta, body = self._parse_frontmatter(text)
+            # Use the frontmatter name, or fall back to the directory name
             name = meta.get("name", f.parent.name)
             self.skills[name] = {"meta": meta, "body": body}
 
     def get_descriptions(self) -> str:
+        """Layer 1: cheap one-liners for the system prompt."""
         lines = []
         for name, skill in self.skills.items():
             desc = skill["meta"].get("description", "")
@@ -65,13 +71,14 @@ class SkillLoader:
         return "\n".join(lines)
 
     def get_content(self, name: str) -> str:
+        """Layer 2: full body, returned as a tool_result."""
         skill = self.skills.get(name)
         if not skill:
             return f"Error: Unknown skill '{name}'."
         return f"<skill name=\"{name}\">\n{skill['body']}\n</skill>"
 ```
 
-3. Layer 1 goes into the system prompt. Layer 2 is just another tool handler.
+**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.
 
 ```python
 SYSTEM = f"""You are a coding agent at {WORKDIR}.
@@ -84,7 +91,7 @@ TOOL_HANDLERS = {
 }
 ```
 
-The model learns what skills exist (cheap) and loads them when relevant (expensive).
+The 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.
 
 ## What Changed From s04
 
@@ -106,3 +113,22 @@ python agents/s05_skill_loading.py
 2. `Load the agent-builder skill and follow its instructions`
 3. `I need to do a code review -- load the relevant skill first`
 4. `Build an MCP server using the mcp-builder skill`
+
+## What You've Mastered
+
+At this point, you can:
+
+- Explain why "list first, load later" beats stuffing everything into the system prompt
+- Write a `SKILL.md` with YAML frontmatter that a `SkillLoader` can discover
+- Wire up two-layer loading: cheap descriptions in the system prompt, full bodies via `tool_result`
+- Let the model decide for itself when domain knowledge is worth loading
+
+You 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.
+
+## What's Next
+
+You 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.
+
+## Key Takeaway
+
+> Advertise skill names cheaply in the system prompt; load the full body through a tool call only when the model actually needs it.
diff --git a/docs/en/s06-context-compact.md b/docs/en/s06-context-compact.md
index 2fbef2ec1..f51df3aab 100644
--- a/docs/en/s06-context-compact.md
+++ b/docs/en/s06-context-compact.md
@@ -1,29 +1,42 @@
 # s06: Context Compact
 
-`s01 > s02 > s03 > s04 > s05 > [ s06 ] | s07 > s08 > s09 > s10 > s11 > s12`
+`s01 > s02 > s03 > s04 > s05 > [ s06 ] > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
 
-> *"Context will fill up; you need a way to make room"* -- three-layer compression strategy for infinite sessions.
->
-> **Harness layer**: Compression -- clean memory for infinite sessions.
+## What You'll Learn
 
-## Problem
+- Why long sessions inevitably run out of context space, and what happens when they do
+- A four-lever compression strategy: persisted output, micro-compact, auto-compact, and manual compact
+- How to move detail out of active memory without losing it
+- How to keep a session alive indefinitely by summarizing and continuing
 
-The context window is finite. A single `read_file` on a 1000-line file costs ~4000 tokens. After reading 30 files and running 20 bash commands, you hit 100,000+ tokens. The agent cannot work on large codebases without compression.
+Your 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.
 
-## Solution
+## The Problem
 
-Three layers, increasing in aggressiveness:
+Every 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.
+
+The 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.
+
+## The Solution
+
+We use four levers, each working at a different stage of the pipeline, from output-time filtering to full conversation summarization.
 
 ```
-Every turn:
+Every tool call:
 +------------------+
 | Tool call result |
 +------------------+
         |
         v
-[Layer 1: micro_compact]        (silent, every turn)
+[Lever 0: persisted-output]     (at tool execution time)
+  Large outputs (>50KB, bash >30KB) are written to disk
+  and replaced with a <persisted-output> preview marker.
+        |
+        v
+[Lever 1: micro_compact]        (silent, every turn)
   Replace tool_result > 3 turns old
   with "[Previous: used {tool_name}]"
+  (preserves read_file results as reference material)
         |
         v
 [Check: tokens > 50000?]
@@ -31,38 +44,62 @@ Every turn:
    no              yes
    |               |
    v               v
-continue    [Layer 2: auto_compact]
+continue    [Lever 2: auto_compact]
               Save transcript to .transcripts/
               LLM summarizes conversation.
               Replace all messages with [summary].
                     |
                     v
-            [Layer 3: compact tool]
+            [Lever 3: compact tool]
               Model calls compact explicitly.
               Same summarization as auto_compact.
 ```
 
 ## How It Works
 
-1. **Layer 1 -- micro_compact**: Before each LLM call, replace old tool results with placeholders.
+### Step 1: Lever 0 -- Persisted Output
+
+The 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.
 
 ```python
+PERSIST_OUTPUT_TRIGGER_CHARS_DEFAULT = 50000
+PERSIST_OUTPUT_TRIGGER_CHARS_BASH = 30000   # bash uses a lower threshold
+
+def maybe_persist_output(tool_use_id, output, trigger_chars=None):
+    if len(output) <= trigger:
+        return output                                    # small enough -- keep inline
+    stored_path = _persist_tool_result(tool_use_id, output)
+    return _build_persisted_marker(stored_path, output)  # swap in a compact preview
+    # Returns: <persisted-output>
+    #   Output too large (48.8KB). Full output saved to: .task_outputs/tool-results/abc123.txt
+    #   Preview (first 2.0KB):
+    #   ... first 2000 chars ...
+    # </persisted-output>
+```
+
+The 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.
+
+### Step 2: Lever 1 -- Micro-Compact
+
+Before 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.
+
+```python
+PRESERVE_RESULT_TOOLS = {"read_file"}
+
 def micro_compact(messages: list) -> list:
-    tool_results = []
-    for i, msg in enumerate(messages):
-        if msg["role"] == "user" and isinstance(msg.get("content"), list):
-            for j, part in enumerate(msg["content"]):
-                if isinstance(part, dict) and part.get("type") == "tool_result":
-                    tool_results.append((i, j, part))
+    tool_results = [...]  # collect all tool_result entries
     if len(tool_results) <= KEEP_RECENT:
-        return messages
-    for _, _, part in tool_results[:-KEEP_RECENT]:
-        if len(part.get("content", "")) > 100:
-            part["content"] = f"[Previous: used {tool_name}]"
+        return messages                                  # not enough results to compact yet
+    for part in tool_results[:-KEEP_RECENT]:
+        if tool_name in PRESERVE_RESULT_TOOLS:
+            continue   # keep reference material
+        part["content"] = f"[Previous: used {tool_name}]"  # replace with short placeholder
     return messages
 ```
 
-2. **Layer 2 -- auto_compact**: When tokens exceed threshold, save full transcript to disk, then ask the LLM to summarize.
+### Step 3: Lever 2 -- Auto-Compact
+
+When 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.
 
 ```python
 def auto_compact(messages: list) -> list:
@@ -76,7 +113,7 @@ def auto_compact(messages: list) -> list:
         model=MODEL,
         messages=[{"role": "user", "content":
             "Summarize this conversation for continuity..."
-            + json.dumps(messages, default=str)[:80000]}],
+            + json.dumps(messages, default=str)[:80000]}],  # cap at 80K chars for the summary call
         max_tokens=2000,
     )
     return [
@@ -84,33 +121,38 @@ def auto_compact(messages: list) -> list:
     ]
 ```
 
-3. **Layer 3 -- manual compact**: The `compact` tool triggers the same summarization on demand.
+### Step 4: Lever 3 -- Manual Compact
+
+The `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.
+
+### Step 5: Integration in the Agent Loop
 
-4. The loop integrates all three:
+All four levers compose naturally inside the main loop:
 
 ```python
 def agent_loop(messages: list):
     while True:
-        micro_compact(messages)                        # Layer 1
+        micro_compact(messages)                        # Lever 1
         if estimate_tokens(messages) > THRESHOLD:
-            messages[:] = auto_compact(messages)       # Layer 2
+            messages[:] = auto_compact(messages)       # Lever 2
         response = client.messages.create(...)
-        # ... tool execution ...
+        # ... tool execution with persisted-output ... # Lever 0
         if manual_compact:
-            messages[:] = auto_compact(messages)       # Layer 3
+            messages[:] = auto_compact(messages)       # Lever 3
 ```
 
-Transcripts preserve full history on disk. Nothing is truly lost -- just moved out of active context.
+Transcripts preserve full history on disk. Large outputs are saved to `.task_outputs/tool-results/`. Nothing is truly lost -- just moved out of active context.
 
 ## What Changed From s05
 
-| Component      | Before (s05)     | After (s06)                |
-|----------------|------------------|----------------------------|
-| Tools          | 5                | 5 (base + compact)         |
-| Context mgmt   | None             | Three-layer compression    |
-| Micro-compact  | None             | Old results -> placeholders|
-| Auto-compact   | None             | Token threshold trigger    |
-| Transcripts    | None             | Saved to .transcripts/     |
+| Component         | Before (s05)     | After (s06)                |
+|-------------------|------------------|----------------------------|
+| Tools             | 5                | 5 (base + compact)         |
+| Context mgmt      | None             | Four-lever compression     |
+| Persisted-output  | None             | Large outputs -> disk + preview |
+| Micro-compact     | None             | Old results -> placeholders|
+| Auto-compact      | None             | Token threshold trigger    |
+| Transcripts       | None             | Saved to .transcripts/     |
 
 ## Try It
 
@@ -122,3 +164,25 @@ python agents/s06_context_compact.py
 1. `Read every Python file in the agents/ directory one by one` (watch micro-compact replace old results)
 2. `Keep reading files until compression triggers automatically`
 3. `Use the compact tool to manually compress the conversation`
+
+## What You've Mastered
+
+At this point, you can:
+
+- Explain why a long agent session degrades and eventually fails without compression
+- Intercept oversized tool outputs before they enter the context window
+- Silently replace stale tool results with lightweight placeholders each turn
+- Trigger a full conversation summarization -- automatically on a threshold or manually via a tool call
+- Preserve full transcripts on disk so nothing is permanently lost
+
+## Stage 1 Complete
+
+You 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.
+
+Before 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.
+
+Stage 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.
+
+## Key Takeaway
+
+> Compaction is not deleting history -- it is relocating detail so the agent can keep working.
diff --git a/docs/en/s07-permission-system.md b/docs/en/s07-permission-system.md
new file mode 100644
index 000000000..92a625f7b
--- /dev/null
+++ b/docs/en/s07-permission-system.md
@@ -0,0 +1,157 @@
+# s07: Permission System
+
+`s01 > s02 > s03 > s04 > s05 > s06 > [ s07 ] > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
+
+## What You'll Learn
+
+- A four-stage permission pipeline that every tool call must pass through before execution
+- Three permission modes that control how aggressively the agent auto-approves actions
+- How deny and allow rules use pattern matching to create a first-match-wins policy
+- Interactive approval with an "always" option that writes permanent allow rules at runtime
+
+Your 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."
+
+## The Problem
+
+Imagine 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.
+
+## The Solution
+
+Every 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.
+
+```
+tool_call from LLM
+     |
+     v
+[1. Deny rules]     -- blocklist: always block these
+     |
+     v
+[2. Mode check]     -- plan mode? auto mode? default?
+     |
+     v
+[3. Allow rules]    -- allowlist: always allow these
+     |
+     v
+[4. Ask user]       -- interactive y/n/always prompt
+     |
+     v
+execute (or reject)
+```
+
+## Read Together
+
+- 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).
+- 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.
+- If `PermissionRule`, `PermissionDecision`, and `tool_result` start to collapse into one vague idea, [`data-structures.md`](./data-structures.md) can reset them.
+
+## How It Works
+
+**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.
+
+| Mode | Behavior | Use Case |
+|------|----------|----------|
+| `default` | Ask user for every unmatched tool call | Normal interactive use |
+| `plan` | Block all writes, allow reads | Planning/review mode |
+| `auto` | Auto-allow reads, ask for writes | Fast exploration mode |
+
+**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.
+
+```python
+rules = [
+    # Always deny dangerous patterns
+    {"tool": "bash", "content": "rm -rf /", "behavior": "deny"},
+    {"tool": "bash", "content": "sudo *",   "behavior": "deny"},
+    # Allow reading anything
+    {"tool": "read_file", "path": "*", "behavior": "allow"},
+]
+```
+
+When the user answers "always" at the interactive prompt, a permanent allow rule is added at runtime.
+
+**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.
+
+```python
+def check(self, tool_name, tool_input):
+    # Step 1: Deny rules (bypass-immune, always checked first)
+    for rule in self.rules:
+        if rule["behavior"] == "deny" and self._matches(rule, ...):
+            return {"behavior": "deny", "reason": "..."}
+
+    # Step 2: Mode-based decisions
+    if self.mode == "plan" and tool_name in WRITE_TOOLS:
+        return {"behavior": "deny", "reason": "Plan mode: writes blocked"}
+    if self.mode == "auto" and tool_name in READ_ONLY_TOOLS:
+        return {"behavior": "allow", "reason": "Auto: read-only approved"}
+
+    # Step 3: Allow rules
+    for rule in self.rules:
+        if rule["behavior"] == "allow" and self._matches(rule, ...):
+            return {"behavior": "allow", "reason": "..."}
+
+    # Step 4: Fall through to ask user
+    return {"behavior": "ask", "reason": "..."}
+```
+
+**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).
+
+```python
+for block in response.content:
+    if block.type == "tool_use":
+        decision = perms.check(block.name, block.input)
+
+        if decision["behavior"] == "deny":
+            output = f"Permission denied: {decision['reason']}"
+        elif decision["behavior"] == "ask":
+            if perms.ask_user(block.name, block.input):
+                output = handler(**block.input)
+            else:
+                output = "Permission denied by user"
+        else:  # allow
+            output = handler(**block.input)
+
+        results.append({"type": "tool_result", ...})
+```
+
+**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.
+
+## What Changed From s06
+
+| Component | Before (s06) | After (s07) |
+|-----------|-------------|-------------|
+| Safety | None | 4-stage permission pipeline |
+| Modes | None | 3 modes: default, plan, auto |
+| Rules | None | Deny/allow rules with pattern matching |
+| User control | None | Interactive approval with "always" option |
+| Denial tracking | None | Circuit breaker after 3 consecutive denials |
+
+## Try It
+
+```sh
+cd learn-claude-code
+python agents/s07_permission_system.py
+```
+
+1. Start in `default` mode -- every write tool asks for approval
+2. Try `plan` mode -- all writes are blocked, reads pass through
+3. Try `auto` mode -- reads auto-approved, writes still ask
+4. Answer "always" to permanently allow a tool
+5. Type `/mode plan` to switch modes at runtime
+6. Type `/rules` to inspect current rule set
+
+## What You've Mastered
+
+At this point, you can:
+
+- Explain why model intent must pass through a decision pipeline before it becomes execution
+- Build a four-stage permission check: deny, mode, allow, ask
+- Configure three permission modes that give you different safety/speed tradeoffs
+- Add rules dynamically at runtime when a user answers "always"
+- Implement a simple circuit breaker that catches repeated denial loops
+
+## What's Next
+
+Your 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.
+
+## Key Takeaway
+
+> Safety is a pipeline, not a boolean -- deny first, then consider mode, then check allow rules, then ask the user.
diff --git a/docs/en/s07-task-system.md b/docs/en/s07-task-system.md
deleted file mode 100644
index b110d0ca4..000000000
--- a/docs/en/s07-task-system.md
+++ /dev/null
@@ -1,131 +0,0 @@
-# s07: Task System
-
-`s01 > s02 > s03 > s04 > s05 > s06 | [ s07 ] s08 > s09 > s10 > s11 > s12`
-
-> *"Break big goals into small tasks, order them, persist to disk"* -- a file-based task graph with dependencies, laying the foundation for multi-agent collaboration.
->
-> **Harness layer**: Persistent tasks -- goals that outlive any single conversation.
-
-## Problem
-
-s03's TodoManager is a flat checklist in memory: no ordering, no dependencies, no status beyond done-or-not. Real goals have structure -- task B depends on task A, tasks C and D can run in parallel, task E waits for both C and D.
-
-Without explicit relationships, the agent can't tell what's ready, what's blocked, or what can run concurrently. And because the list lives only in memory, context compression (s06) wipes it clean.
-
-## Solution
-
-Promote the checklist into a **task graph** persisted to disk. Each task is a JSON file with status, dependencies (`blockedBy`). The graph answers three questions at any moment:
-
-- **What's ready?** -- tasks with `pending` status and empty `blockedBy`.
-- **What's blocked?** -- tasks waiting on unfinished dependencies.
-- **What's done?** -- `completed` tasks, whose completion automatically unblocks dependents.
-
-```
-.tasks/
-  task_1.json  {"id":1, "status":"completed"}
-  task_2.json  {"id":2, "blockedBy":[1], "status":"pending"}
-  task_3.json  {"id":3, "blockedBy":[1], "status":"pending"}
-  task_4.json  {"id":4, "blockedBy":[2,3], "status":"pending"}
-
-Task graph (DAG):
-                 +----------+
-            +--> | task 2   | --+
-            |    | pending  |   |
-+----------+     +----------+    +--> +----------+
-| task 1   |                          | task 4   |
-| completed| --> +----------+    +--> | blocked  |
-+----------+     | task 3   | --+     +----------+
-                 | pending  |
-                 +----------+
-
-Ordering:     task 1 must finish before 2 and 3
-Parallelism:  tasks 2 and 3 can run at the same time
-Dependencies: task 4 waits for both 2 and 3
-Status:       pending -> in_progress -> completed
-```
-
-This task graph becomes the coordination backbone for everything after s07: background execution (s08), multi-agent teams (s09+), and worktree isolation (s12) all read from and write to this same structure.
-
-## How It Works
-
-1. **TaskManager**: one JSON file per task, CRUD with dependency graph.
-
-```python
-class TaskManager:
-    def __init__(self, tasks_dir: Path):
-        self.dir = tasks_dir
-        self.dir.mkdir(exist_ok=True)
-        self._next_id = self._max_id() + 1
-
-    def create(self, subject, description=""):
-        task = {"id": self._next_id, "subject": subject,
-                "status": "pending", "blockedBy": [],
-                "owner": ""}
-        self._save(task)
-        self._next_id += 1
-        return json.dumps(task, indent=2)
-```
-
-2. **Dependency resolution**: completing a task clears its ID from every other task's `blockedBy` list, automatically unblocking dependents.
-
-```python
-def _clear_dependency(self, completed_id):
-    for f in self.dir.glob("task_*.json"):
-        task = json.loads(f.read_text())
-        if completed_id in task.get("blockedBy", []):
-            task["blockedBy"].remove(completed_id)
-            self._save(task)
-```
-
-3. **Status + dependency wiring**: `update` handles transitions and dependency edges.
-
-```python
-def update(self, task_id, status=None,
-           add_blocked_by=None, remove_blocked_by=None):
-    task = self._load(task_id)
-    if status:
-        task["status"] = status
-        if status == "completed":
-            self._clear_dependency(task_id)
-    if add_blocked_by:
-        task["blockedBy"] = list(set(task["blockedBy"] + add_blocked_by))
-    if remove_blocked_by:
-        task["blockedBy"] = [x for x in task["blockedBy"] if x not in remove_blocked_by]
-    self._save(task)
-```
-
-4. Four task tools go into the dispatch map.
-
-```python
-TOOL_HANDLERS = {
-    # ...base tools...
-    "task_create": lambda **kw: TASKS.create(kw["subject"]),
-    "task_update": lambda **kw: TASKS.update(kw["task_id"], kw.get("status")),
-    "task_list":   lambda **kw: TASKS.list_all(),
-    "task_get":    lambda **kw: TASKS.get(kw["task_id"]),
-}
-```
-
-From s07 onward, the task graph is the default for multi-step work. s03's Todo remains for quick single-session checklists.
-
-## What Changed From s06
-
-| Component | Before (s06) | After (s07) |
-|---|---|---|
-| Tools | 5 | 8 (`task_create/update/list/get`) |
-| Planning model | Flat checklist (in-memory) | Task graph with dependencies (on disk) |
-| Relationships | None | `blockedBy` edges |
-| Status tracking | Done or not | `pending` -> `in_progress` -> `completed` |
-| Persistence | Lost on compression | Survives compression and restarts |
-
-## Try It
-
-```sh
-cd learn-claude-code
-python agents/s07_task_system.py
-```
-
-1. `Create 3 tasks: "Setup project", "Write code", "Write tests". Make them depend on each other in order.`
-2. `List all tasks and show the dependency graph`
-3. `Complete task 1 and then list tasks to see task 2 unblocked`
-4. `Create a task board for refactoring: parse -> transform -> emit -> test, where transform and emit can run in parallel after parse`
diff --git a/docs/en/s08-background-tasks.md b/docs/en/s08-background-tasks.md
deleted file mode 100644
index 5a98f2126..000000000
--- a/docs/en/s08-background-tasks.md
+++ /dev/null
@@ -1,107 +0,0 @@
-# s08: Background Tasks
-
-`s01 > s02 > s03 > s04 > s05 > s06 | s07 > [ s08 ] s09 > s10 > s11 > s12`
-
-> *"Run slow operations in the background; the agent keeps thinking"* -- daemon threads run commands, inject notifications on completion.
->
-> **Harness layer**: Background execution -- the model thinks while the harness waits.
-
-## Problem
-
-Some commands take minutes: `npm install`, `pytest`, `docker build`. With a blocking loop, the model sits idle waiting. If the user asks "install dependencies and while that runs, create the config file," the agent does them sequentially, not in parallel.
-
-## Solution
-
-```
-Main thread                Background thread
-+-----------------+        +-----------------+
-| agent loop      |        | subprocess runs |
-| ...             |        | ...             |
-| [LLM call] <---+------- | enqueue(result) |
-|  ^drain queue   |        +-----------------+
-+-----------------+
-
-Timeline:
-Agent --[spawn A]--[spawn B]--[other work]----
-             |          |
-             v          v
-          [A runs]   [B runs]      (parallel)
-             |          |
-             +-- results injected before next LLM call --+
-```
-
-## How It Works
-
-1. BackgroundManager tracks tasks with a thread-safe notification queue.
-
-```python
-class BackgroundManager:
-    def __init__(self):
-        self.tasks = {}
-        self._notification_queue = []
-        self._lock = threading.Lock()
-```
-
-2. `run()` starts a daemon thread and returns immediately.
-
-```python
-def run(self, command: str) -> str:
-    task_id = str(uuid.uuid4())[:8]
-    self.tasks[task_id] = {"status": "running", "command": command}
-    thread = threading.Thread(
-        target=self._execute, args=(task_id, command), daemon=True)
-    thread.start()
-    return f"Background task {task_id} started"
-```
-
-3. When the subprocess finishes, its result goes into the notification queue.
-
-```python
-def _execute(self, task_id, command):
-    try:
-        r = subprocess.run(command, shell=True, cwd=WORKDIR,
-            capture_output=True, text=True, timeout=300)
-        output = (r.stdout + r.stderr).strip()[:50000]
-    except subprocess.TimeoutExpired:
-        output = "Error: Timeout (300s)"
-    with self._lock:
-        self._notification_queue.append({
-            "task_id": task_id, "result": output[:500]})
-```
-
-4. The agent loop drains notifications before each LLM call.
-
-```python
-def agent_loop(messages: list):
-    while True:
-        notifs = BG.drain_notifications()
-        if notifs:
-            notif_text = "\n".join(
-                f"[bg:{n['task_id']}] {n['result']}" for n in notifs)
-            messages.append({"role": "user",
-                "content": f"<background-results>\n{notif_text}\n"
-                           f"</background-results>"})
-        response = client.messages.create(...)
-```
-
-The loop stays single-threaded. Only subprocess I/O is parallelized.
-
-## What Changed From s07
-
-| Component      | Before (s07)     | After (s08)                |
-|----------------|------------------|----------------------------|
-| Tools          | 8                | 6 (base + background_run + check)|
-| Execution      | Blocking only    | Blocking + background threads|
-| Notification   | None             | Queue drained per loop     |
-| Concurrency    | None             | Daemon threads             |
-
-## Try It
-
-```sh
-cd learn-claude-code
-python agents/s08_background_tasks.py
-```
-
-1. `Run "sleep 5 && echo done" in the background, then create a file while it runs`
-2. `Start 3 background tasks: "sleep 2", "sleep 4", "sleep 6". Check their status.`
-3. `Run pytest in the background and keep working on other things`
diff --git a/docs/en/s08-hook-system.md b/docs/en/s08-hook-system.md
new file mode 100644
index 000000000..7575391f9
--- /dev/null
+++ b/docs/en/s08-hook-system.md
@@ -0,0 +1,163 @@
+# s08: Hook System
+
+`s01 > s02 > s03 > s04 > s05 > s06 > s07 > [ s08 ] > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
+
+## What You'll Learn
+
+- Three lifecycle events that let external code observe and influence the agent loop
+- How shell-based hooks run as subprocesses with full context about the current tool call
+- The exit code protocol: 0 means continue, 1 means block, 2 means inject a message
+- How to configure hooks in an external JSON file so you never touch the main loop code
+
+Your 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.
+
+## The Problem
+
+You 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.
+
+## The Solution
+
+The 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.
+
+```
+tool_call from LLM
+     |
+     v
+[PreToolUse hooks]
+     |  exit 0 -> continue
+     |  exit 1 -> block tool, return stderr as error
+     |  exit 2 -> inject stderr into conversation, continue
+     |
+     v
+[execute tool]
+     |
+     v
+[PostToolUse hooks]
+     |  exit 0 -> continue
+     |  exit 2 -> append stderr to result
+     |
+     v
+return result
+```
+
+## Read Together
+
+- 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.
+- 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.
+- 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.
+
+## How It Works
+
+**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.
+
+| Event | When | Can Block? |
+|-------|------|-----------|
+| `SessionStart` | Once at session start | No |
+| `PreToolUse` | Before each tool call | Yes (exit 1) |
+| `PostToolUse` | After each tool call | No |
+
+**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.
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {"matcher": "bash", "command": "echo 'Checking bash command...'"},
+      {"matcher": "write_file", "command": "/path/to/lint-check.sh"}
+    ],
+    "PostToolUse": [
+      {"command": "echo 'Tool finished'"}
+    ],
+    "SessionStart": [
+      {"command": "echo 'Session started at $(date)'"}
+    ]
+  }
+}
+```
+
+**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.
+
+| Exit Code | Meaning | PreToolUse | PostToolUse |
+|-----------|---------|-----------|------------|
+| 0 | Success | Continue to execute tool | Continue normally |
+| 1 | Block | Tool NOT executed, stderr returned as error | Warning logged |
+| 2 | Inject | stderr injected as message, tool still executes | stderr appended to result |
+
+**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.
+
+```
+HOOK_EVENT=PreToolUse
+HOOK_TOOL_NAME=bash
+HOOK_TOOL_INPUT={"command": "npm test"}
+HOOK_TOOL_OUTPUT=...  (PostToolUse only)
+```
+
+**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.
+
+```python
+# Before tool execution
+pre_result = hooks.run_hooks("PreToolUse", ctx)
+if pre_result["blocked"]:
+    output = f"Blocked by hook: {pre_result['block_reason']}"
+    continue
+
+# Execute tool
+output = handler(**tool_input)
+
+# After tool execution
+post_result = hooks.run_hooks("PostToolUse", ctx)
+for msg in post_result["messages"]:
+    output += f"\n[Hook note]: {msg}"
+```
+
+## What Changed From s07
+
+| Component | Before (s07) | After (s08) |
+|-----------|-------------|-------------|
+| Extensibility | None | Shell-based hook system |
+| Events | None | PreToolUse, PostToolUse, SessionStart |
+| Control flow | Permission pipeline only | Permission + hooks |
+| Configuration | In-code rules | External `.hooks.json` file |
+
+## Try It
+
+```sh
+cd learn-claude-code
+# Create a hook config
+cat > .hooks.json << 'EOF'
+{
+  "hooks": {
+    "PreToolUse": [
+      {"matcher": "bash", "command": "echo 'Auditing bash command' >&2; exit 0"}
+    ],
+    "SessionStart": [
+      {"command": "echo 'Agent session started'"}
+    ]
+  }
+}
+EOF
+python agents/s08_hook_system.py
+```
+
+1. Watch SessionStart hook fire at startup
+2. Ask the agent to run a bash command -- see PreToolUse hook fire
+3. Create a blocking hook (exit 1) and watch it prevent tool execution
+4. Create an injecting hook (exit 2) and watch it add messages to the conversation
+
+## What You've Mastered
+
+At this point, you can:
+
+- Explain why extension points are better than in-loop conditionals for adding new behavior
+- Define lifecycle events at the right moments in the agent loop
+- Write shell hooks that communicate intent through a three-code exit protocol
+- Configure hooks externally so different teams can customize behavior without touching the agent code
+- Maintain the boundary: the loop owns control flow, the handler owns execution, hooks only observe, block, or annotate
+
+## What's Next
+
+Your 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.
+
+## Key Takeaway
+
+> 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.
diff --git a/docs/en/s09-agent-teams.md b/docs/en/s09-agent-teams.md
deleted file mode 100644
index 9f19723aa..000000000
--- a/docs/en/s09-agent-teams.md
+++ /dev/null
@@ -1,125 +0,0 @@
-# s09: Agent Teams
-
-`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > [ s09 ] s10 > s11 > s12`
-
-> *"When the task is too big for one, delegate to teammates"* -- persistent teammates + async mailboxes.
->
-> **Harness layer**: Team mailboxes -- multiple models, coordinated through files.
-
-## Problem
-
-Subagents (s04) are disposable: spawn, work, return summary, die. No identity, no memory between invocations. Background tasks (s08) run shell commands but can't make LLM-guided decisions.
-
-Real teamwork needs: (1) persistent agents that outlive a single prompt, (2) identity and lifecycle management, (3) a communication channel between agents.
-
-## Solution
-
-```
-Teammate lifecycle:
-  spawn -> WORKING -> IDLE -> WORKING -> ... -> SHUTDOWN
-
-Communication:
-  .team/
-    config.json           <- team roster + statuses
-    inbox/
-      alice.jsonl         <- append-only, drain-on-read
-      bob.jsonl
-      lead.jsonl
-
-              +--------+    send("alice","bob","...")    +--------+
-              | alice  | -----------------------------> |  bob   |
-              | loop   |    bob.jsonl << {json_line}    |  loop  |
-              +--------+                                +--------+
-                   ^                                         |
-                   |        BUS.read_inbox("alice")          |
-                   +---- alice.jsonl -> read + drain ---------+
-```
-
-## How It Works
-
-1. TeammateManager maintains config.json with the team roster.
-
-```python
-class TeammateManager:
-    def __init__(self, team_dir: Path):
-        self.dir = team_dir
-        self.dir.mkdir(exist_ok=True)
-        self.config_path = self.dir / "config.json"
-        self.config = self._load_config()
-        self.threads = {}
-```
-
-2. `spawn()` creates a teammate and starts its agent loop in a thread.
-
-```python
-def spawn(self, name: str, role: str, prompt: str) -> str:
-    member = {"name": name, "role": role, "status": "working"}
-    self.config["members"].append(member)
-    self._save_config()
-    thread = threading.Thread(
-        target=self._teammate_loop,
-        args=(name, role, prompt), daemon=True)
-    thread.start()
-    return f"Spawned teammate '{name}' (role: {role})"
-```
-
-3. MessageBus: append-only JSONL inboxes. `send()` appends a JSON line; `read_inbox()` reads all and drains.
-
-```python
-class MessageBus:
-    def send(self, sender, to, content, msg_type="message", extra=None):
-        msg = {"type": msg_type, "from": sender,
-               "content": content, "timestamp": time.time()}
-        if extra:
-            msg.update(extra)
-        with open(self.dir / f"{to}.jsonl", "a") as f:
-            f.write(json.dumps(msg) + "\n")
-
-    def read_inbox(self, name):
-        path = self.dir / f"{name}.jsonl"
-        if not path.exists(): return "[]"
-        msgs = [json.loads(l) for l in path.read_text().strip().splitlines() if l]
-        path.write_text("")  # drain
-        return json.dumps(msgs, indent=2)
-```
-
-4. Each teammate checks its inbox before every LLM call, injecting received messages into context.
-
-```python
-def _teammate_loop(self, name, role, prompt):
-    messages = [{"role": "user", "content": prompt}]
-    for _ in range(50):
-        inbox = BUS.read_inbox(name)
-        if inbox != "[]":
-            messages.append({"role": "user",
-                "content": f"<inbox>{inbox}</inbox>"})
-        response = client.messages.create(...)
-        if response.stop_reason != "tool_use":
-            break
-        # execute tools, append results...
-    self._find_member(name)["status"] = "idle"
-```
-
-## What Changed From s08
-
-| Component      | Before (s08)     | After (s09)                |
-|----------------|------------------|----------------------------|
-| Tools          | 6                | 9 (+spawn/send/read_inbox) |
-| Agents         | Single           | Lead + N teammates         |
-| Persistence    | None             | config.json + JSONL inboxes|
-| Threads        | Background cmds  | Full agent loops per thread|
-| Lifecycle      | Fire-and-forget  | idle -> working -> idle    |
-| Communication  | None             | message + broadcast        |
-
-## Try It
-
-```sh
-cd learn-claude-code
-python agents/s09_agent_teams.py
-```
-
-1. `Spawn alice (coder) and bob (tester). Have alice send bob a message.`
-2. `Broadcast "status update: phase 1 complete" to all teammates`
-3. `Check the lead inbox for any messages`
-4. Type `/team` to see the team roster with statuses
-5. Type `/inbox` to manually check the lead's inbox
diff --git a/docs/en/s09-memory-system.md b/docs/en/s09-memory-system.md
new file mode 100644
index 000000000..39bdc8d79
--- /dev/null
+++ b/docs/en/s09-memory-system.md
@@ -0,0 +1,176 @@
+# s09: Memory System
+
+`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > [ s09 ] > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
+
+## What You'll Learn
+
+- Four memory categories that cover what is worth remembering: user preferences, feedback, project facts, and references
+- How YAML frontmatter files give each memory record a name, type, and description
+- What should NOT go into memory -- and why getting this boundary wrong is the most common mistake
+- The difference between memory, tasks, plans, and CLAUDE.md
+
+Your 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.
+
+## The Problem
+
+Without 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.
+
+## The Solution
+
+A 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.
+
+```text
+conversation
+   |
+   | durable fact appears
+   v
+save_memory
+   |
+   v
+.memory/
+  ├── MEMORY.md
+  ├── prefer_pnpm.md
+  ├── ask_before_codegen.md
+  └── incident_dashboard.md
+   |
+   v
+next session loads relevant entries
+```
+
+## Read Together
+
+- 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.
+- If `messages[]`, summary blocks, and the memory store start to blend together, keeping [`data-structures.md`](./data-structures.md) open while reading can help.
+- 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.
+
+## How It Works
+
+**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.
+
+### 1. `user` -- Stable user preferences
+
+Examples: prefers `pnpm`, wants concise answers, dislikes large refactors without a plan.
+
+### 2. `feedback` -- Corrections the user wants enforced
+
+Examples: "do not change test snapshots unless I ask", "ask before modifying generated files."
+
+### 3. `project` -- Durable project facts not obvious from the repo
+
+Examples: "this old directory still cannot be deleted because deployment depends on it", "this service exists because of a compliance requirement, not technical preference."
+
+### 4. `reference` -- Pointers to external resources
+
+Examples: incident board URL, monitoring dashboard location, spec document location.
+
+```python
+MEMORY_TYPES = ("user", "feedback", "project", "reference")
+```
+
+**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.
+
+```md
+---
+name: prefer_pnpm
+description: User prefers pnpm over npm
+type: user
+---
+The user explicitly prefers pnpm for package management commands.
+```
+
+```python
+def save_memory(name, description, mem_type, content):
+    path = memory_dir / f"{slugify(name)}.md"
+    path.write_text(render_frontmatter(name, description, mem_type) + content)
+    rebuild_index()
+```
+
+**Step 3.** Build a small index so the system knows what memories exist without reading every file.
+
+```md
+# Memory Index
+
+- prefer_pnpm [user]
+- ask_before_codegen [feedback]
+- incident_dashboard [reference]
+```
+
+The index is not the memory itself -- it is a quick map of what exists.
+
+**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.
+
+```python
+memories = memory_store.load_all()
+```
+
+**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.
+
+| Do not store | Why |
+|---|---|
+| file tree layout | can be re-read from the repo |
+| function names and signatures | code is the source of truth |
+| current task status | belongs to task / plan, not memory |
+| temporary branch names or PR numbers | gets stale quickly |
+| secrets or credentials | security risk |
+
+The right rule is: only keep information that still matters across sessions and cannot be cheaply re-derived from the current workspace.
+
+**Step 6.** Understand the boundaries against neighbor concepts. These four things sound similar but serve different purposes.
+
+| Concept | Purpose | Lifetime |
+|---------|---------|----------|
+| Memory | Facts that should survive across sessions | Persistent |
+| Task | What the system is trying to finish right now | One task |
+| Plan | How this turn or session intends to proceed | One session |
+| CLAUDE.md | Stable instruction documents and project-level standing rules | Persistent |
+
+Short 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`.
+
+## Common Mistakes
+
+**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.
+
+**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.
+
+**Mistake 3: Treating memory as absolute truth.** Memory can be stale. The safer rule is: memory gives direction, current observation gives truth.
+
+## What Changed From s08
+
+| Component | Before (s08) | After (s09) |
+|-----------|-------------|-------------|
+| Cross-session state | None | File-based memory store |
+| Memory types | None | user, feedback, project, reference |
+| Storage format | None | YAML frontmatter markdown files |
+| Session start | Cold start | Loads relevant memories |
+| Durability | Everything forgotten | Key facts persist |
+
+## Try It
+
+```sh
+cd learn-claude-code
+python agents/s09_memory_system.py
+```
+
+Try asking it to remember:
+
+- a user preference
+- a correction you want enforced later
+- a project fact that is not obvious from the repository
+
+## What You've Mastered
+
+At this point, you can:
+
+- Explain why memory is a curated store of durable facts, not a dump of everything the agent has seen
+- Categorize facts into four types: user preferences, feedback, project knowledge, and references
+- Store and retrieve memories using frontmatter-based markdown files
+- Draw a clear line between what belongs in memory and what belongs in task state, plans, or CLAUDE.md
+- Avoid the three most common mistakes: duplicating the repo, storing transient state, and treating memories as ground truth
+
+## What's Next
+
+Your 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.
+
+## Key Takeaway
+
+> 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.
diff --git a/docs/en/s10-system-prompt.md b/docs/en/s10-system-prompt.md
new file mode 100644
index 000000000..e0bfdfb4c
--- /dev/null
+++ b/docs/en/s10-system-prompt.md
@@ -0,0 +1,158 @@
+# s10: System Prompt
+
+`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > [ s10 ] > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
+
+## What You'll Learn
+
+- How to assemble the system prompt from independent sections instead of one hardcoded string
+- The boundary between stable content (role, rules) and dynamic content (date, cwd, per-turn reminders)
+- How CLAUDE.md files layer instructions without overwriting each other
+- Why memory must be re-injected through the prompt pipeline to actually guide the agent
+
+When 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.
+
+## The Problem
+
+Imagine 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.
+
+This is not a hypothetical scenario -- it is the natural trajectory of every agent that keeps its prompt in a single variable.
+
+## The Solution
+
+Turn 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.
+
+```text
+1. core identity and rules
+2. tool catalog
+3. skills
+4. memory
+5. CLAUDE.md instruction chain
+6. dynamic runtime context
+```
+
+Then assemble:
+
+```text
+core
++ tools
++ skills
++ memory
++ claude_md
++ dynamic_context
+= final model input
+```
+
+## How It Works
+
+**Step 1. Define the builder.** Each method owns exactly one source of content.
+
+```python
+class SystemPromptBuilder:
+    def build(self) -> str:
+        parts = []
+        parts.append(self._build_core())
+        parts.append(self._build_tools())
+        parts.append(self._build_skills())
+        parts.append(self._build_memory())
+        parts.append(self._build_claude_md())
+        parts.append(self._build_dynamic())
+        return "\n\n".join(p for p in parts if p)
+```
+
+That 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.
+
+**Step 2. Separate stable content from dynamic content.** This is the most important boundary in the entire pipeline.
+
+Stable content changes rarely or never during a session:
+
+- role description
+- tool contract (the list of tools and their schemas)
+- long-lived safety rules
+- project instruction chain (CLAUDE.md files)
+
+Dynamic content changes every turn or every few turns:
+
+- current date
+- current working directory
+- current mode (plan mode, code mode, etc.)
+- per-turn warnings or reminders
+
+Mixing 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.
+
+**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:
+
+1. user-level instruction file (`~/.claude/CLAUDE.md`)
+2. project-root instruction file (`<project>/CLAUDE.md`)
+3. deeper subdirectory instruction files
+
+The important point is not the filename itself. The important point is that instruction sources can be layered instead of overwritten.
+
+**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:
+
+- save durable facts in `s09`
+- re-inject them through the prompt builder in `s10`
+
+**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:
+
+- this-turn-only instructions
+- temporary notices
+- transient recovery guidance
+
+## What Changed from s09
+
+| Aspect | s09: Memory System | s10: System Prompt |
+|--------|--------------------|--------------------|
+| Core concern | Persist durable facts across sessions | Assemble all sources into model input |
+| Memory's role | Write and store | Read and inject |
+| Prompt structure | Assumed but not managed | Explicit pipeline with sections |
+| Instruction files | Not addressed | CLAUDE.md layering introduced |
+| Dynamic context | Not addressed | Separated from stable content |
+
+## Read Together
+
+- 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.
+- 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`.
+- 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).
+
+## Common Beginner Mistakes
+
+**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.
+
+**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.
+
+**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:
+
+- `skills`: optional capability packages loaded on demand
+- `memory`: durable cross-session facts about the user or project
+- `CLAUDE.md`: standing instruction documents that layer without overwriting
+
+## Try It
+
+```sh
+cd learn-claude-code
+python agents/s10_system_prompt.py
+```
+
+Look for these three things:
+
+1. where each section comes from
+2. which parts are stable
+3. which parts are generated dynamically each turn
+
+## What You've Mastered
+
+At this point, you can:
+
+- Build a system prompt from independent, testable sections instead of one opaque string
+- Draw a clear line between stable content and dynamic content
+- Layer instruction files so that project-level and directory-level rules coexist without overwriting
+- Re-inject memory into the prompt pipeline so saved facts actually influence the model
+- Attach per-turn reminders separately from the main system prompt
+
+## What's Next
+
+The 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.
+
+## Key Takeaway
+
+> The system prompt is an assembly pipeline with clear sections and clear boundaries, not one big mysterious string.
diff --git a/docs/en/s10-team-protocols.md b/docs/en/s10-team-protocols.md
deleted file mode 100644
index e784e5ee0..000000000
--- a/docs/en/s10-team-protocols.md
+++ /dev/null
@@ -1,106 +0,0 @@
-# s10: Team Protocols
-
-`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > [ s10 ] s11 > s12`
-
-> *"Teammates need shared communication rules"* -- one request-response pattern drives all negotiation.
->
-> **Harness layer**: Protocols -- structured handshakes between models.
-
-## Problem
-
-In s09, teammates work and communicate but lack structured coordination:
-
-**Shutdown**: Killing a thread leaves files half-written and config.json stale. You need a handshake: the lead requests, the teammate approves (finish and exit) or rejects (keep working).
-
-**Plan approval**: When the lead says "refactor the auth module," the teammate starts immediately. For high-risk changes, the lead should review the plan first.
-
-Both share the same structure: one side sends a request with a unique ID, the other responds referencing that ID.
-
-## Solution
-
-```
-Shutdown Protocol            Plan Approval Protocol
-==================           ======================
-
-Lead             Teammate    Teammate           Lead
-  |                 |           |                 |
-  |--shutdown_req-->|           |--plan_req------>|
-  | {req_id:"abc"}  |           | {req_id:"xyz"}  |
-  |                 |           |                 |
-  |<--shutdown_resp-|           |<--plan_resp-----|
-  | {req_id:"abc",  |           | {req_id:"xyz",  |
-  |  approve:true}  |           |  approve:true}  |
-
-Shared FSM:
-  [pending] --approve--> [approved]
-  [pending] --reject---> [rejected]
-
-Trackers:
-  shutdown_requests = {req_id: {target, status}}
-  plan_requests     = {req_id: {from, plan, status}}
-```
-
-## How It Works
-
-1. The lead initiates shutdown by generating a request_id and sending through the inbox.
-
-```python
-shutdown_requests = {}
-
-def handle_shutdown_request(teammate: str) -> str:
-    req_id = str(uuid.uuid4())[:8]
-    shutdown_requests[req_id] = {"target": teammate, "status": "pending"}
-    BUS.send("lead", teammate, "Please shut down gracefully.",
-             "shutdown_request", {"request_id": req_id})
-    return f"Shutdown request {req_id} sent (status: pending)"
-```
-
-2. The teammate receives the request and responds with approve/reject.
-
-```python
-if tool_name == "shutdown_response":
-    req_id = args["request_id"]
-    approve = args["approve"]
-    shutdown_requests[req_id]["status"] = "approved" if approve else "rejected"
-    BUS.send(sender, "lead", args.get("reason", ""),
-             "shutdown_response",
-             {"request_id": req_id, "approve": approve})
-```
-
-3. Plan approval follows the identical pattern. The teammate submits a plan (generating a request_id), the lead reviews (referencing the same request_id).
-
-```python
-plan_requests = {}
-
-def handle_plan_review(request_id, approve, feedback=""):
-    req = plan_requests[request_id]
-    req["status"] = "approved" if approve else "rejected"
-    BUS.send("lead", req["from"], feedback,
-             "plan_approval_response",
-             {"request_id": request_id, "approve": approve})
-```
-
-One FSM, two applications. The same `pending -> approved | rejected` state machine handles any request-response protocol.
-
-## What Changed From s09
-
-| Component      | Before (s09)     | After (s10)                  |
-|----------------|------------------|------------------------------|
-| Tools          | 9                | 12 (+shutdown_req/resp +plan)|
-| Shutdown       | Natural exit only| Request-response handshake   |
-| Plan gating    | None             | Submit/review with approval  |
-| Correlation    | None             | request_id per request       |
-| FSM            | None             | pending -> approved/rejected |
-
-## Try It
-
-```sh
-cd learn-claude-code
-python agents/s10_team_protocols.py
-```
-
-1. `Spawn alice as a coder. Then request her shutdown.`
-2. `List teammates to see alice's status after shutdown approval`
-3. `Spawn bob with a risky refactoring task. Review and reject his plan.`
-4. `Spawn charlie, have him submit a plan, then approve it.`
-5. Type `/team` to monitor statuses
diff --git a/docs/en/s10a-message-prompt-pipeline.md b/docs/en/s10a-message-prompt-pipeline.md
new file mode 100644
index 000000000..6143537db
--- /dev/null
+++ b/docs/en/s10a-message-prompt-pipeline.md
@@ -0,0 +1,188 @@
+# s10a: Message & Prompt Pipeline
+
+> **Deep Dive** -- Best read alongside s10. It shows why the system prompt is only one piece of the model's full input.
+
+### When to Read This
+
+When you're working on prompt assembly and want to see the complete input pipeline.
+
+---
+
+> This bridge document extends `s10`.
+>
+> It exists to make one crucial idea explicit:
+>
+> **the system prompt matters, but it is not the whole model input.**
+
+## Why This Document Exists
+
+`s10` already upgrades the system prompt from one giant string into a maintainable assembly process.
+
+That is important.
+
+But a higher-completion system goes one step further and treats the whole model input as a pipeline made from multiple sources:
+
+- system prompt blocks
+- normalized messages
+- memory attachments
+- reminder injections
+- dynamic runtime context
+
+So the true structure is:
+
+**a prompt pipeline, not only a prompt builder.**
+
+## Terms First
+
+### Prompt block
+
+A structured piece inside the system prompt, such as:
+
+- core identity
+- tool instructions
+- memory section
+- CLAUDE.md section
+
+### Normalized message
+
+A message that has already been converted into a stable shape suitable for the model API.
+
+This is necessary because the raw system may contain:
+
+- user messages
+- assistant replies
+- tool results
+- reminder injections
+- attachment-like content
+
+Normalization ensures all of these fit the same structural contract before they reach the API.
+
+### System reminder
+
+A small temporary instruction injected for the current turn or current mode.
+
+Unlike 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.
+
+## The Smallest Useful Mental Model
+
+Think of the full input as a pipeline:
+
+```text
+multiple sources
+  |
+  +-- system prompt blocks
+  +-- messages
+  +-- attachments
+  +-- reminders
+  |
+  v
+normalize
+  |
+  v
+final API payload
+```
+
+The key teaching point is:
+
+**separate the sources first, then normalize them into one stable input.**
+
+## Why System Prompt Is Not Everything
+
+The system prompt is the right place for:
+
+- identity
+- stable rules
+- long-lived constraints
+- tool capability descriptions
+
+But it is usually the wrong place for:
+
+- the latest `tool_result`
+- one-turn hook injections
+- temporary reminders
+- dynamic memory attachments
+
+Those belong in the message stream or in adjacent input surfaces.
+
+## Core Structures
+
+### `SystemPromptBlock`
+
+```python
+block = {
+    "text": "...",
+    "cache_scope": None,
+}
+```
+
+### `PromptParts`
+
+```python
+parts = {
+    "core": "...",
+    "tools": "...",
+    "skills": "...",
+    "memory": "...",
+    "claude_md": "...",
+    "dynamic": "...",
+}
+```
+
+### `NormalizedMessage`
+
+```python
+message = {
+    "role": "user" | "assistant",
+    "content": [...],
+}
+```
+
+Treat `content` as a list of blocks, not just one string.
+
+### `ReminderMessage`
+
+```python
+reminder = {
+    "role": "system",
+    "content": "Current mode: plan",
+}
+```
+
+Even if your teaching implementation does not literally use `role="system"` here, you should still keep the mental split:
+
+- long-lived prompt block
+- short-lived reminder
+
+## Minimal Implementation Path
+
+### 1. Keep a `SystemPromptBuilder`
+
+Do not throw away the prompt-builder step.
+
+### 2. Make messages a separate pipeline
+
+```python
+def build_messages(raw_messages, attachments, reminders):
+    messages = normalize_messages(raw_messages)
+    messages = attach_memory(messages, attachments)
+    messages = append_reminders(messages, reminders)
+    return messages
+```
+
+### 3. Assemble the final payload only at the end
+
+```python
+payload = {
+    "system": build_system_prompt(),
+    "messages": build_messages(...),
+    "tools": build_tools(...),
+}
+```
+
+This is the important mental upgrade:
+
+**system prompt, messages, and tools are parallel input surfaces, not replacements for one another.**
+
+## Key Takeaway
+
+**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.**
diff --git a/docs/en/s11-autonomous-agents.md b/docs/en/s11-autonomous-agents.md
deleted file mode 100644
index a3c283675..000000000
--- a/docs/en/s11-autonomous-agents.md
+++ /dev/null
@@ -1,142 +0,0 @@
-# s11: Autonomous Agents
-
-`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > [ s11 ] s12`
-
-> *"Teammates scan the board and claim tasks themselves"* -- no need for the lead to assign each one.
->
-> **Harness layer**: Autonomy -- models that find work without being told.
-
-## Problem
-
-In s09-s10, teammates only work when explicitly told to. The lead must spawn each one with a specific prompt. 10 unclaimed tasks on the board? The lead assigns each one manually. Doesn't scale.
-
-True autonomy: teammates scan the task board themselves, claim unclaimed tasks, work on them, then look for more.
-
-One subtlety: after context compression (s06), the agent might forget who it is. Identity re-injection fixes this.
-
-## Solution
-
-```
-Teammate lifecycle with idle cycle:
-
-+-------+
-| spawn |
-+---+---+
-    |
-    v
-+-------+   tool_use     +-------+
-| WORK  | <------------- |  LLM  |
-+---+---+                +-------+
-    |
-    | stop_reason != tool_use (or idle tool called)
-    v
-+--------+
-|  IDLE  |  poll every 5s for up to 60s
-+---+----+
-    |
-    +---> check inbox --> message? ----------> WORK
-    |
-    +---> scan .tasks/ --> unclaimed? -------> claim -> WORK
-    |
-    +---> 60s timeout ----------------------> SHUTDOWN
-
-Identity re-injection after compression:
-  if len(messages) <= 3:
-    messages.insert(0, identity_block)
-```
-
-## How It Works
-
-1. The teammate loop has two phases: WORK and IDLE. When the LLM stops calling tools (or calls `idle`), the teammate enters IDLE.
-
-```python
-def _loop(self, name, role, prompt):
-    while True:
-        # -- WORK PHASE --
-        messages = [{"role": "user", "content": prompt}]
-        for _ in range(50):
-            response = client.messages.create(...)
-            if response.stop_reason != "tool_use":
-                break
-            # execute tools...
-            if idle_requested:
-                break
-
-        # -- IDLE PHASE --
-        self._set_status(name, "idle")
-        resume = self._idle_poll(name, messages)
-        if not resume:
-            self._set_status(name, "shutdown")
-            return
-        self._set_status(name, "working")
-```
-
-2. The idle phase polls inbox and task board in a loop.
-
-```python
-def _idle_poll(self, name, messages):
-    for _ in range(IDLE_TIMEOUT // POLL_INTERVAL):  # 60s / 5s = 12
-        time.sleep(POLL_INTERVAL)
-        inbox = BUS.read_inbox(name)
-        if inbox:
-            messages.append({"role": "user",
-                "content": f"<inbox>{inbox}</inbox>"})
-            return True
-        unclaimed = scan_unclaimed_tasks()
-        if unclaimed:
-            claim_task(unclaimed[0]["id"], name)
-            messages.append({"role": "user",
-                "content": f"<auto-claimed>Task #{unclaimed[0]['id']}: "
-                           f"{unclaimed[0]['subject']}</auto-claimed>"})
-            return True
-    return False  # timeout -> shutdown
-```
-
-3. Task board scanning: find pending, unowned, unblocked tasks.
-
-```python
-def scan_unclaimed_tasks() -> list:
-    unclaimed = []
-    for f in sorted(TASKS_DIR.glob("task_*.json")):
-        task = json.loads(f.read_text())
-        if (task.get("status") == "pending"
-                and not task.get("owner")
-                and not task.get("blockedBy")):
-            unclaimed.append(task)
-    return unclaimed
-```
-
-4. Identity re-injection: when context is too short (compression happened), insert an identity block.
-
-```python
-if len(messages) <= 3:
-    messages.insert(0, {"role": "user",
-        "content": f"<identity>You are '{name}', role: {role}, "
-                   f"team: {team_name}. Continue your work.</identity>"})
-    messages.insert(1, {"role": "assistant",
-        "content": f"I am {name}. Continuing."})
-```
-
-## What Changed From s10
-
-| Component      | Before (s10)     | After (s11)                |
-|----------------|------------------|----------------------------|
-| Tools          | 12               | 14 (+idle, +claim_task)    |
-| Autonomy       | Lead-directed    | Self-organizing            |
-| Idle phase     | None             | Poll inbox + task board    |
-| Task claiming  | Manual only      | Auto-claim unclaimed tasks |
-| Identity       | System prompt    | + re-injection after compress|
-| Timeout        | None             | 60s idle -> auto shutdown  |
-
-## Try It
-
-```sh
-cd learn-claude-code
-python agents/s11_autonomous_agents.py
-```
-
-1. `Create 3 tasks on the board, then spawn alice and bob. Watch them auto-claim.`
-2. `Spawn a coder teammate and let it find work from the task board itself`
-3. `Create tasks with dependencies. Watch teammates respect the blocked order.`
-4. Type `/tasks` to see the task board with owners
-5. Type `/team` to monitor who is working vs idle
diff --git a/docs/en/s11-error-recovery.md b/docs/en/s11-error-recovery.md
new file mode 100644
index 000000000..9fe7dcaaf
--- /dev/null
+++ b/docs/en/s11-error-recovery.md
@@ -0,0 +1,204 @@
+# s11: Error Recovery
+
+`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > [ s11 ] > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
+
+## What You'll Learn
+
+- Three categories of recoverable failure: truncation, context overflow, and transient transport errors
+- How to route each failure to the right recovery branch (continuation, compaction, or backoff)
+- Why retry budgets prevent infinite loops
+- How recovery state keeps the "why" visible instead of burying it in a catch block
+
+Your 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.
+
+## The Problem
+
+Your 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.
+
+Or: 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.
+
+Or: a momentary network hiccup drops the connection. Without recovery, the agent crashes even though the same request would succeed one second later.
+
+Each 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.
+
+## The Solution
+
+Classify the failure first, choose the recovery branch second, and enforce a retry budget so the system cannot loop forever.
+
+```text
+LLM call
+  |
+  +-- stop_reason == "max_tokens"
+  |      -> append continuation reminder
+  |      -> retry
+  |
+  +-- prompt too long
+  |      -> compact context
+  |      -> retry
+  |
+  +-- timeout / rate limit / connection error
+         -> back off
+         -> retry
+```
+
+## How It Works
+
+**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:
+
+```python
+recovery_state = {
+    "continuation_attempts": 0,
+    "compact_attempts": 0,
+    "transport_attempts": 0,
+}
+```
+
+**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:
+
+```python
+def choose_recovery(stop_reason: str | None, error_text: str | None) -> dict:
+    if stop_reason == "max_tokens":
+        return {"kind": "continue", "reason": "output truncated"}
+
+    if error_text and "prompt" in error_text and "long" in error_text:
+        return {"kind": "compact", "reason": "context too large"}
+
+    if error_text and any(word in error_text for word in [
+        "timeout", "rate", "unavailable", "connection"
+    ]):
+        return {"kind": "backoff", "reason": "transient transport failure"}
+
+    return {"kind": "fail", "reason": "unknown or non-recoverable error"}
+```
+
+The separation matters: classify first, act second. That way the recovery reason stays visible in state instead of disappearing inside a catch block.
+
+**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:
+
+```python
+CONTINUE_MESSAGE = (
+    "Output limit hit. Continue directly from where you stopped. "
+    "Do not restart or repeat."
+)
+```
+
+Without 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.
+
+**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:
+
+```python
+if decision["kind"] == "compact":
+    messages = auto_compact(messages)
+    continue
+```
+
+**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:
+
+```python
+def backoff_delay(attempt: int) -> float:
+    delay = min(BACKOFF_BASE_DELAY * (2 ** attempt), BACKOFF_MAX_DELAY)
+    jitter = random.uniform(0, 1)
+    return delay + jitter
+```
+
+**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:
+
+```python
+while True:
+    try:
+        response = client.messages.create(...)
+        decision = choose_recovery(response.stop_reason, None)
+    except Exception as e:
+        response = None
+        decision = choose_recovery(None, str(e).lower())
+
+    if decision["kind"] == "continue":
+        messages.append({"role": "user", "content": CONTINUE_MESSAGE})
+        continue
+
+    if decision["kind"] == "compact":
+        messages = auto_compact(messages)
+        continue
+
+    if decision["kind"] == "backoff":
+        time.sleep(backoff_delay(...))
+        continue
+
+    if decision["kind"] == "fail":
+        break
+```
+
+The point is not clever code. The point is: classify, choose, retry with a budget.
+
+## What Changed from s10
+
+| Aspect | s10: System Prompt | s11: Error Recovery |
+|--------|--------------------|--------------------|
+| Core concern | Assemble model input from sections | Handle failures without crashing |
+| Loop behavior | Runs until end_turn or tool_use | Adds recovery branches before giving up |
+| Compaction | Not addressed | Triggered reactively on context overflow |
+| Retry logic | Not addressed | Budgeted per failure category |
+| State tracking | Prompt sections | Recovery counters |
+
+## A Note on Real Systems
+
+Real 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.
+
+## Read Together
+
+- 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).
+- 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."
+- 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.
+
+## Common Beginner Mistakes
+
+**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.
+
+**Mistake 2: no retry budget.** Without budgets, the system can loop forever. Each recovery category needs its own counter and its own maximum.
+
+**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.
+
+## Try It
+
+```sh
+cd learn-claude-code
+python agents/s11_error_recovery.py
+```
+
+Try forcing:
+
+- a long response (to trigger max_tokens continuation)
+- a large context (to trigger compaction)
+- a temporary timeout (to trigger backoff)
+
+Then observe which recovery branch the system chooses and how the retry counter increments.
+
+## What You've Mastered
+
+At this point, you can:
+
+- Classify agent failures into three recoverable categories and one terminal category
+- Route each failure to the correct recovery branch: continuation, compaction, or backoff
+- Enforce retry budgets so the system never loops forever
+- Keep recovery decisions visible as structured state instead of burying them in exception handlers
+- Explain why different failure types need different recovery actions
+
+## Stage 2 Complete
+
+You have finished Stage 2 of the harness. Look at what you have built since Stage 1:
+
+- **s07 Permission System** -- the harness asks before acting, and the user controls what gets auto-approved
+- **s08 Hook System** -- external scripts run at lifecycle points without touching the agent loop
+- **s09 Memory System** -- durable facts survive across sessions
+- **s10 System Prompt** -- the prompt is an assembly pipeline with clear sections, not one big string
+- **s11 Error Recovery** -- failures route to the right recovery path instead of crashing
+
+Your 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.
+
+That is a real agent harness. If you stopped here and built a product on top of it, you would have something genuinely useful.
+
+But 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).
+
+## Key Takeaway
+
+> 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.
diff --git a/docs/en/s12-task-system.md b/docs/en/s12-task-system.md
new file mode 100644
index 000000000..3be263481
--- /dev/null
+++ b/docs/en/s12-task-system.md
@@ -0,0 +1,149 @@
+# s12: Task System
+
+`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > [ s12 ] > s13 > s14 > s15 > s16 > s17 > s18 > s19`
+
+## What You'll Learn
+
+- How to promote a flat checklist into a task graph with explicit dependencies
+- How `blockedBy` and `blocks` edges express ordering and parallelism
+- How status transitions (`pending` -> `in_progress` -> `completed`) drive automatic unblocking
+- How persisting tasks to disk makes them survive compression and restarts
+
+Back 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.
+
+## The Problem
+
+Imagine 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.
+
+## The Solution
+
+Promote 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.
+
+```
+.tasks/
+  task_1.json  {"id":1, "status":"completed"}
+  task_2.json  {"id":2, "blockedBy":[1], "status":"pending"}
+  task_3.json  {"id":3, "blockedBy":[1], "status":"pending"}
+  task_4.json  {"id":4, "blockedBy":[2,3], "status":"pending"}
+
+Task graph (DAG):
+                 +----------+
+            +--> | task 2   | --+
+            |    | pending  |   |
++----------+     +----------+    +--> +----------+
+| task 1   |                          | task 4   |
+| completed| --> +----------+    +--> | blocked  |
++----------+     | task 3   | --+     +----------+
+                 | pending  |
+                 +----------+
+
+Ordering:     task 1 must finish before 2 and 3
+Parallelism:  tasks 2 and 3 can run at the same time
+Dependencies: task 4 waits for both 2 and 3
+Status:       pending -> in_progress -> completed
+```
+
+The 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.
+
+## How It Works
+
+**Step 1.** Create a `TaskManager` that stores one JSON file per task, with CRUD operations and a dependency graph.
+
+```python
+class TaskManager:
+    def __init__(self, tasks_dir: Path):
+        self.dir = tasks_dir
+        self.dir.mkdir(exist_ok=True)
+        self._next_id = self._max_id() + 1
+
+    def create(self, subject, description=""):
+        task = {"id": self._next_id, "subject": subject,
+                "status": "pending", "blockedBy": [],
+                "blocks": [], "owner": ""}
+        self._save(task)
+        self._next_id += 1
+        return json.dumps(task, indent=2)
+```
+
+**Step 2.** Implement dependency resolution. When a task completes, clear its ID from every other task's `blockedBy` list, automatically unblocking dependents.
+
+```python
+def _clear_dependency(self, completed_id):
+    for f in self.dir.glob("task_*.json"):
+        task = json.loads(f.read_text())
+        if completed_id in task.get("blockedBy", []):
+            task["blockedBy"].remove(completed_id)
+            self._save(task)
+```
+
+**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.
+
+```python
+def update(self, task_id, status=None,
+           add_blocked_by=None, add_blocks=None):
+    task = self._load(task_id)
+    if status:
+        task["status"] = status
+        if status == "completed":
+            self._clear_dependency(task_id)
+    self._save(task)
+```
+
+**Step 4.** Register four task tools in the dispatch map, giving the agent full control over creating, updating, listing, and inspecting tasks.
+
+```python
+TOOL_HANDLERS = {
+    # ...base tools...
+    "task_create": lambda **kw: TASKS.create(kw["subject"]),
+    "task_update": lambda **kw: TASKS.update(kw["task_id"], kw.get("status")),
+    "task_list":   lambda **kw: TASKS.list_all(),
+    "task_get":    lambda **kw: TASKS.get(kw["task_id"]),
+}
+```
+
+From 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.
+
+## Read Together
+
+- 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.
+- 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.
+- 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.
+
+## What Changed
+
+| Component | Before (s06) | After (s12) |
+|---|---|---|
+| Tools | 5 | 8 (`task_create/update/list/get`) |
+| Planning model | Flat checklist (in-memory) | Task graph with dependencies (on disk) |
+| Relationships | None | `blockedBy` + `blocks` edges |
+| Status tracking | Done or not | `pending` -> `in_progress` -> `completed` |
+| Persistence | Lost on compression | Survives compression and restarts |
+
+## Try It
+
+```sh
+cd learn-claude-code
+python agents/s12_task_system.py
+```
+
+1. `Create 3 tasks: "Setup project", "Write code", "Write tests". Make them depend on each other in order.`
+2. `List all tasks and show the dependency graph`
+3. `Complete task 1 and then list tasks to see task 2 unblocked`
+4. `Create a task board for refactoring: parse -> transform -> emit -> test, where transform and emit can run in parallel after parse`
+
+## What You've Mastered
+
+At this point, you can:
+
+- Build a file-based task graph where each task is a self-contained JSON record
+- Express ordering and parallelism through `blockedBy` and `blocks` dependency edges
+- Implement automatic unblocking when upstream tasks complete
+- Persist planning state so it survives context compression and process restarts
+
+## What's Next
+
+Tasks 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.
+
+## Key Takeaway
+
+> 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.
diff --git a/docs/en/s12-worktree-task-isolation.md b/docs/en/s12-worktree-task-isolation.md
deleted file mode 100644
index a54282aca..000000000
--- a/docs/en/s12-worktree-task-isolation.md
+++ /dev/null
@@ -1,121 +0,0 @@
-# s12: Worktree + Task Isolation
-
-`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > [ s12 ]`
-
-> *"Each works in its own directory, no interference"* -- tasks manage goals, worktrees manage directories, bound by ID.
->
-> **Harness layer**: Directory isolation -- parallel execution lanes that never collide.
-
-## Problem
-
-By s11, agents can claim and complete tasks autonomously. But every task runs in one shared directory. Two agents refactoring different modules at the same time will collide: agent A edits `config.py`, agent B edits `config.py`, unstaged changes mix, and neither can roll back cleanly.
-
-The task board tracks *what to do* but has no opinion about *where to do it*. The fix: give each task its own git worktree directory. Tasks manage goals, worktrees manage execution context. Bind them by task ID.
-
-## Solution
-
-```
-Control plane (.tasks/)             Execution plane (.worktrees/)
-+------------------+                +------------------------+
-| task_1.json      |                | auth-refactor/         |
-|   status: in_progress  <------>   branch: wt/auth-refactor
-|   worktree: "auth-refactor"   |   task_id: 1             |
-+------------------+                +------------------------+
-| task_2.json      |                | ui-login/              |
-|   status: pending    <------>     branch: wt/ui-login
-|   worktree: "ui-login"       |   task_id: 2             |
-+------------------+                +------------------------+
-                                    |
-                          index.json (worktree registry)
-                          events.jsonl (lifecycle log)
-
-State machines:
-  Task:     pending -> in_progress -> completed
-  Worktree: absent  -> active      -> removed | kept
-```
-
-## How It Works
-
-1. **Create a task.** Persist the goal first.
-
-```python
-TASKS.create("Implement auth refactor")
-# -> .tasks/task_1.json  status=pending  worktree=""
-```
-
-2. **Create a worktree and bind to the task.** Passing `task_id` auto-advances the task to `in_progress`.
-
-```python
-WORKTREES.create("auth-refactor", task_id=1)
-# -> git worktree add -b wt/auth-refactor .worktrees/auth-refactor HEAD
-# -> index.json gets new entry, task_1.json gets worktree="auth-refactor"
-```
-
-The binding writes state to both sides:
-
-```python
-def bind_worktree(self, task_id, worktree):
-    task = self._load(task_id)
-    task["worktree"] = worktree
-    if task["status"] == "pending":
-        task["status"] = "in_progress"
-    self._save(task)
-```
-
-3. **Run commands in the worktree.** `cwd` points to the isolated directory.
-
-```python
-subprocess.run(command, shell=True, cwd=worktree_path,
-               capture_output=True, text=True, timeout=300)
-```
-
-4. **Close out.** Two choices:
-   - `worktree_keep(name)` -- preserve the directory for later.
-   - `worktree_remove(name, complete_task=True)` -- remove directory, complete the bound task, emit event. One call handles teardown + completion.
-
-```python
-def remove(self, name, force=False, complete_task=False):
-    self._run_git(["worktree", "remove", wt["path"]])
-    if complete_task and wt.get("task_id") is not None:
-        self.tasks.update(wt["task_id"], status="completed")
-        self.tasks.unbind_worktree(wt["task_id"])
-        self.events.emit("task.completed", ...)
-```
-
-5. **Event stream.** Every lifecycle step emits to `.worktrees/events.jsonl`:
-
-```json
-{
-  "event": "worktree.remove.after",
-  "task": {"id": 1, "status": "completed"},
-  "worktree": {"name": "auth-refactor", "status": "removed"},
-  "ts": 1730000000
-}
-```
-
-Events emitted: `worktree.create.before/after/failed`, `worktree.remove.before/after/failed`, `worktree.keep`, `task.completed`.
-
-After a crash, state reconstructs from `.tasks/` + `.worktrees/index.json` on disk. Conversation memory is volatile; file state is durable.
-
-## What Changed From s11
-
-| Component          | Before (s11)               | After (s12)                                  |
-|--------------------|----------------------------|----------------------------------------------|
-| Coordination       | Task board (owner/status)  | Task board + explicit worktree binding       |
-| Execution scope    | Shared directory           | Task-scoped isolated directory               |
-| Recoverability     | Task status only           | Task status + worktree index                 |
-| Teardown           | Task completion            | Task completion + explicit keep/remove       |
-| Lifecycle visibility | Implicit in logs         | Explicit events in `.worktrees/events.jsonl` |
-
-## Try It
-
-```sh
-cd learn-claude-code
-python agents/s12_worktree_task_isolation.py
-```
-
-1. `Create tasks for backend auth and frontend login page, then list tasks.`
-2. `Create worktree "auth-refactor" for task 1, then bind task 2 to a new worktree "ui-login".`
-3. `Run "git status --short" in worktree "auth-refactor".`
-4. `Keep worktree "ui-login", then list worktrees and inspect events.`
-5. `Remove worktree "auth-refactor" with complete_task=true, then list tasks/worktrees/events.`
diff --git a/docs/en/s13-background-tasks.md b/docs/en/s13-background-tasks.md
new file mode 100644
index 000000000..b2ce326dc
--- /dev/null
+++ b/docs/en/s13-background-tasks.md
@@ -0,0 +1,139 @@
+# s13: Background Tasks
+
+`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > [ s13 ] > s14 > s15 > s16 > s17 > s18 > s19`
+
+## What You'll Learn
+
+- How to run slow commands in background threads while the main loop stays responsive
+- How a thread-safe notification queue delivers results back to the agent
+- How daemon threads keep the process clean on exit
+- How the drain-before-call pattern injects background results at exactly the right moment
+
+You 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.
+
+## The Problem
+
+Consider 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.
+
+## The Solution
+
+Keep 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.
+
+```
+Main thread                Background thread
++-----------------+        +-----------------+
+| agent loop      |        | subprocess runs |
+| ...             |        | ...             |
+| [LLM call] <---+------- | enqueue(result) |
+|  ^drain queue   |        +-----------------+
++-----------------+
+
+Timeline:
+Agent --[spawn A]--[spawn B]--[other work]----
+             |          |
+             v          v
+          [A runs]   [B runs]      (parallel)
+             |          |
+             +-- results injected before next LLM call --+
+```
+
+## How It Works
+
+**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.
+
+```python
+class BackgroundManager:
+    def __init__(self):
+        self.tasks = {}
+        self._notification_queue = []
+        self._lock = threading.Lock()
+```
+
+**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.
+
+```python
+def run(self, command: str) -> str:
+    task_id = str(uuid.uuid4())[:8]
+    self.tasks[task_id] = {"status": "running", "command": command}
+    thread = threading.Thread(
+        target=self._execute, args=(task_id, command), daemon=True)
+    thread.start()
+    return f"Background task {task_id} started"
+```
+
+**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.
+
+```python
+def _execute(self, task_id, command):
+    try:
+        r = subprocess.run(command, shell=True, cwd=WORKDIR,
+            capture_output=True, text=True, timeout=300)
+        output = (r.stdout + r.stderr).strip()[:50000]
+    except subprocess.TimeoutExpired:
+        output = "Error: Timeout (300s)"
+    with self._lock:
+        self._notification_queue.append({
+            "task_id": task_id, "result": output[:500]})
+```
+
+**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.
+
+```python
+def agent_loop(messages: list):
+    while True:
+        notifs = BG.drain_notifications()
+        if notifs:
+            notif_text = "\n".join(
+                f"[bg:{n['task_id']}] {n['result']}" for n in notifs)
+            messages.append({"role": "user",
+                "content": f"<background-results>\n{notif_text}\n"
+                           f"</background-results>"})
+            messages.append({"role": "assistant",
+                "content": "Noted background results."})
+        response = client.messages.create(...)
+```
+
+This 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.
+
+## Read Together
+
+- 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.
+- 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.
+- 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.
+
+## What Changed
+
+| Component      | Before (s12)     | After (s13)                |
+|----------------|------------------|----------------------------|
+| Tools          | 8                | 6 (base + background_run + check)|
+| Execution      | Blocking only    | Blocking + background threads|
+| Notification   | None             | Queue drained per loop     |
+| Concurrency    | None             | Daemon threads             |
+
+## Try It
+
+```sh
+cd learn-claude-code
+python agents/s13_background_tasks.py
+```
+
+1. `Run "sleep 5 && echo done" in the background, then create a file while it runs`
+2. `Start 3 background tasks: "sleep 2", "sleep 4", "sleep 6". Check their status.`
+3. `Run pytest in the background and keep working on other things`
+
+## What You've Mastered
+
+At this point, you can:
+
+- Run slow subprocesses on daemon threads without blocking the main agent loop
+- Collect results through a thread-safe notification queue
+- Inject background results into the conversation using the drain-before-call pattern
+- Let the agent work on other things while long-running commands finish in parallel
+
+## What's Next
+
+Background 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.
+
+## Key Takeaway
+
+> 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.
diff --git a/docs/en/s13a-runtime-task-model.md b/docs/en/s13a-runtime-task-model.md
new file mode 100644
index 000000000..7ae7cf850
--- /dev/null
+++ b/docs/en/s13a-runtime-task-model.md
@@ -0,0 +1,273 @@
+# s13a: Runtime Task Model
+
+> **Deep Dive** -- Best read between s12 and s13. It prevents the most common confusion in Stage 3.
+
+### When to Read This
+
+Right after s12 (Task System), before you start s13 (Background Tasks). This note separates two meanings of "task" that beginners frequently collapse into one.
+
+---
+
+> This bridge note resolves one confusion that becomes expensive very quickly:
+>
+> **the task in the work graph is not the same thing as the task that is currently running**
+
+## How to Read This with the Mainline
+
+This note works best between these documents:
+
+- read [`s12-task-system.md`](./s12-task-system.md) first to lock in the durable work graph
+- then read [`s13-background-tasks.md`](./s13-background-tasks.md) to see background execution
+- if the terms begin to blur, you might find it helpful to revisit [`glossary.md`](./glossary.md)
+- 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)
+
+## Why This Deserves Its Own Bridge Note
+
+The mainline is still correct:
+
+- `s12` teaches the task system
+- `s13` teaches background tasks
+
+But without one more bridge layer, you can easily start collapsing two different meanings of "task" into one bucket.
+
+For example:
+
+- a work-graph task such as "implement auth module"
+- a background execution such as "run pytest"
+- a teammate execution such as "alice is editing files"
+
+All three can be casually called tasks, but they do not live on the same layer.
+
+## Two Very Different Kinds of Task
+
+### 1. Work-graph task
+
+This is the durable node introduced in `s12`.
+
+It answers:
+
+- what should be done
+- which work depends on which other work
+- who owns it
+- what the progress status is
+
+It is best understood as:
+
+> a durable unit of planned work
+
+### 2. Runtime task
+
+This layer answers:
+
+- what execution unit is alive right now
+- what kind of execution it is
+- whether it is running, completed, failed, or killed
+- where its output lives
+
+It is best understood as:
+
+> a live execution slot inside the runtime
+
+## The Minimum Mental Model
+
+Treat these as two separate tables:
+
+```text
+work-graph task
+  - durable
+  - goal and dependency oriented
+  - longer lifecycle
+
+runtime task
+  - execution oriented
+  - output and status oriented
+  - shorter lifecycle
+```
+
+Their relationship is not "pick one."
+
+It is:
+
+```text
+one work-graph task
+  can spawn
+one or more runtime tasks
+```
+
+For example:
+
+```text
+work-graph task:
+  "Implement auth module"
+
+runtime tasks:
+  1. run tests in the background
+  2. launch a coder teammate
+  3. monitor an external service
+```
+
+## Why the Distinction Matters
+
+If you do not keep these layers separate, the later chapters start tangling together:
+
+- `s13` background execution blurs into the `s12` task board
+- `s15-s17` teammate work has nowhere clean to attach
+- `s18` worktrees become unclear because you no longer know what layer they belong to
+
+The shortest correct summary is:
+
+**work-graph tasks manage goals; runtime tasks manage execution**
+
+## Core Records
+
+### 1. `WorkGraphTaskRecord`
+
+This is the durable task from `s12`.
+
+```python
+task = {
+    "id": 12,
+    "subject": "Implement auth module",
+    "status": "in_progress",
+    "blockedBy": [],
+    "blocks": [13],
+    "owner": "alice",
+    "worktree": "auth-refactor",
+}
+```
+
+### 2. `RuntimeTaskState`
+
+A minimal teaching shape can look like this:
+
+```python
+runtime_task = {
+    "id": "b8k2m1qz",
+    "type": "local_bash",
+    "status": "running",
+    "description": "Run pytest",
+    "start_time": 1710000000.0,
+    "end_time": None,
+    "output_file": ".task_outputs/b8k2m1qz.txt",
+    "notified": False,
+}
+```
+
+The key fields are:
+
+- `type`: what execution unit this is
+- `status`: whether it is active or terminal
+- `output_file`: where the result is stored
+- `notified`: whether the system already surfaced the result
+
+### 3. `RuntimeTaskType`
+
+You do not need to implement every type in the teaching repo immediately.
+
+But you should still know that runtime task is a family, not just one shell command type.
+
+A minimal table:
+
+```text
+local_bash
+local_agent
+remote_agent
+in_process_teammate
+monitor
+workflow
+```
+
+## Minimum Implementation Steps
+
+### Step 1: keep the `s12` task board intact
+
+Do not overload it.
+
+### Step 2: add a separate runtime task manager
+
+```python
+class RuntimeTaskManager:
+    def __init__(self):
+        self.tasks = {}
+```
+
+### Step 3: create runtime tasks when background work starts
+
+```python
+def spawn_bash_task(command: str):
+    task_id = new_runtime_id()
+    runtime_tasks[task_id] = {
+        "id": task_id,
+        "type": "local_bash",
+        "status": "running",
+        "description": command,
+    }
+```
+
+### Step 4: optionally link runtime execution back to the work graph
+
+```python
+runtime_tasks[task_id]["work_graph_task_id"] = 12
+```
+
+You do not need that field on day one, but it becomes increasingly important once the system reaches teams and worktrees.
+
+## The Picture You Should Hold
+
+```text
+Work Graph
+  task #12: Implement auth module
+        |
+        +-- runtime task A: local_bash (pytest)
+        +-- runtime task B: local_agent (coder worker)
+        +-- runtime task C: monitor (watch service status)
+
+Runtime Task Layer
+  A/B/C each have:
+  - their own runtime ID
+  - their own status
+  - their own output
+  - their own lifecycle
+```
+
+## How This Connects to Later Chapters
+
+Once this layer is clear, the rest of the runtime and platform chapters become much easier:
+
+- `s13` background commands are runtime tasks
+- `s15-s17` teammates can also be understood as runtime task variants
+- `s18` worktrees mostly bind to durable work, but still affect runtime execution
+- `s19` some monitoring or async external work can also land in the runtime layer
+
+Whenever you see "something is alive in the background and advancing work," ask two questions:
+
+- is this a durable goal from the work graph?
+- or is this a live execution slot in the runtime?
+
+## Common Beginner Mistakes
+
+### 1. Putting background shell state directly into the task board
+
+That mixes durable task state and runtime execution state.
+
+### 2. Assuming one work-graph task can only have one runtime task
+
+In real systems, one goal often spawns multiple execution units.
+
+### 3. Reusing the same status vocabulary for both layers
+
+For example:
+
+- durable tasks: `pending / in_progress / completed`
+- runtime tasks: `running / completed / failed / killed`
+
+Those should stay distinct when possible.
+
+### 4. Ignoring runtime-only fields such as `output_file` and `notified`
+
+The durable task board does not care much about them.
+The runtime layer cares a lot.
+
+## Key Takeaway
+
+**"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.**
diff --git a/docs/en/s14-cron-scheduler.md b/docs/en/s14-cron-scheduler.md
new file mode 100644
index 000000000..97b03fbf6
--- /dev/null
+++ b/docs/en/s14-cron-scheduler.md
@@ -0,0 +1,158 @@
+# s14: Cron Scheduler
+
+`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > [ s14 ] > s15 > s16 > s17 > s18 > s19`
+
+## What You'll Learn
+
+- How schedule records store future intent as durable data
+- How a time-based checker turns cron expressions into triggered notifications
+- The difference between durable jobs (survive restarts) and session-only jobs (die with the process)
+- How scheduled work re-enters the agent system through the same notification queue from s13
+
+In 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).
+
+## The Problem
+
+Your 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.
+
+## The Solution
+
+Add 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.
+
+```text
+schedule_create(...)
+  ->
+write a durable schedule record
+  ->
+time checker wakes up and tests "does this rule match now?"
+  ->
+if yes, enqueue a scheduled notification
+  ->
+main loop injects that notification as new work
+```
+
+The 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.
+
+## How It Works
+
+**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.
+
+```python
+schedule = {
+    "id": "job_001",
+    "cron": "0 9 * * 1",
+    "prompt": "Run the weekly status report.",
+    "recurring": True,
+    "durable": True,
+    "created_at": 1710000000.0,
+    "last_fired_at": None,
+}
+```
+
+A 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.
+
+**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.
+
+```python
+def create(self, cron_expr: str, prompt: str, recurring: bool = True):
+    job = {
+        "id": new_id(),
+        "cron": cron_expr,
+        "prompt": prompt,
+        "recurring": recurring,
+        "created_at": time.time(),
+        "last_fired_at": None,
+    }
+    self.jobs.append(job)
+    return job
+```
+
+**Step 3.** Run a background checker loop that wakes up every 60 seconds and tests each schedule against the current time.
+
+```python
+def check_loop(self):
+    while True:
+        now = datetime.now()
+        self.check_jobs(now)
+        time.sleep(60)
+```
+
+**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.
+
+```python
+def check_jobs(self, now):
+    for job in self.jobs:
+        if cron_matches(job["cron"], now):
+            self.queue.put({
+                "type": "scheduled_prompt",
+                "schedule_id": job["id"],
+                "prompt": job["prompt"],
+            })
+            job["last_fired_at"] = now.timestamp()
+```
+
+**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.
+
+```python
+notifications = scheduler.drain()
+for item in notifications:
+    messages.append({
+        "role": "user",
+        "content": f"[scheduled:{item['schedule_id']}] {item['prompt']}",
+    })
+```
+
+## Read Together
+
+- 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.
+- 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).
+- 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.
+
+## What Changed
+
+| Mechanism | Main question |
+|---|---|
+| Background tasks (s13) | "How does slow work continue without blocking?" |
+| Scheduling (s14) | "When should future work begin?" |
+
+| Component | Before (s13) | After (s14) |
+|---|---|---|
+| Tools | 6 (base + background) | 8 (+ schedule_create, schedule_list, schedule_delete) |
+| Time awareness | None | Cron-based future triggers |
+| Persistence | Background tasks in memory | Durable schedules survive restarts |
+| Trigger model | User-initiated only | User-initiated + time-triggered |
+
+## Try It
+
+```sh
+cd learn-claude-code
+python agents/s14_cron_scheduler.py
+```
+
+1. Create a repeating schedule: `Schedule "echo hello" to run every 2 minutes`
+2. Create a one-shot reminder: `Remind me in 1 minute to check the build`
+3. Create a delayed follow-up: `In 5 minutes, run the test suite and report results`
+
+## What You've Mastered
+
+At this point, you can:
+
+- Define schedule records that store future intent as durable data
+- Run a background time checker that matches cron expressions to the current clock
+- Distinguish durable jobs (persist to disk) from session-only jobs (in-memory)
+- Feed scheduled triggers back into the main loop through the same notification queue used by background tasks
+- Prevent double-firing with `last_fired_at` tracking
+
+## Stage 3 Complete
+
+You have finished Stage 3: the execution and scheduling layer. Looking back at the three chapters together:
+
+- **s12** gave the agent a task graph with dependencies and persistence -- it can plan structured work that survives restarts.
+- **s13** added background execution -- slow work runs in parallel instead of blocking the loop.
+- **s14** added time-based triggers -- the agent can schedule future work without the user having to remember.
+
+Together, 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.
+
+## Key Takeaway
+
+> 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.
diff --git a/docs/en/s15-agent-teams.md b/docs/en/s15-agent-teams.md
new file mode 100644
index 000000000..61075a198
--- /dev/null
+++ b/docs/en/s15-agent-teams.md
@@ -0,0 +1,192 @@
+# s15: Agent Teams
+
+`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > [ s15 ] > s16 > s17 > s18 > s19`
+
+## What You'll Learn
+- How persistent teammates differ from disposable subagents
+- How JSONL-based inboxes give agents a durable communication channel
+- How the team lifecycle moves through spawn, working, idle, and shutdown
+- How file-based coordination lets multiple agent loops run side by side
+
+Sometimes 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.
+
+## The Problem
+
+Subagents 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.
+
+Real 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.
+
+## The Solution
+
+The 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.
+
+```
+Teammate lifecycle:
+  spawn -> WORKING -> IDLE -> WORKING -> ... -> SHUTDOWN
+
+Communication:
+  .team/
+    config.json           <- team roster + statuses
+    inbox/
+      alice.jsonl         <- append-only, drain-on-read
+      bob.jsonl
+      lead.jsonl
+
+              +--------+    send("alice","bob","...")    +--------+
+              | alice  | -----------------------------> |  bob   |
+              | loop   |    bob.jsonl << {json_line}    |  loop  |
+              +--------+                                +--------+
+                   ^                                         |
+                   |        BUS.read_inbox("alice")          |
+                   +---- alice.jsonl -> read + drain ---------+
+```
+
+## How It Works
+
+**Step 1.** `TeammateManager` maintains `config.json` with the team roster. It tracks every teammate's name, role, and current status.
+
+```python
+class TeammateManager:
+    def __init__(self, team_dir: Path):
+        self.dir = team_dir
+        self.dir.mkdir(exist_ok=True)
+        self.config_path = self.dir / "config.json"
+        self.config = self._load_config()
+        self.threads = {}
+```
+
+**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.
+
+```python
+def spawn(self, name: str, role: str, prompt: str) -> str:
+    member = {"name": name, "role": role, "status": "working"}
+    self.config["members"].append(member)
+    self._save_config()
+    thread = threading.Thread(
+        target=self._teammate_loop,
+        args=(name, role, prompt), daemon=True)
+    thread.start()
+    return f"Spawned teammate '{name}' (role: {role})"
+```
+
+**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.
+
+```python
+class MessageBus:
+    def send(self, sender, to, content, msg_type="message", extra=None):
+        msg = {"type": msg_type, "from": sender,
+               "content": content, "timestamp": time.time()}
+        if extra:
+            msg.update(extra)
+        with open(self.dir / f"{to}.jsonl", "a") as f:
+            f.write(json.dumps(msg) + "\n")
+
+    def read_inbox(self, name):
+        path = self.dir / f"{name}.jsonl"
+        if not path.exists(): return "[]"
+        msgs = [json.loads(l) for l in path.read_text().strip().splitlines() if l]
+        path.write_text("")  # drain
+        return json.dumps(msgs, indent=2)
+```
+
+**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.
+
+```python
+def _teammate_loop(self, name, role, prompt):
+    messages = [{"role": "user", "content": prompt}]
+    for _ in range(50):
+        inbox = BUS.read_inbox(name)
+        if inbox != "[]":
+            messages.append({"role": "user",
+                "content": f"<inbox>{inbox}</inbox>"})
+            messages.append({"role": "assistant",
+                "content": "Noted inbox messages."})
+        response = client.messages.create(...)
+        if response.stop_reason != "tool_use":
+            break
+        # execute tools, append results...
+    self._find_member(name)["status"] = "idle"
+```
+
+## Read Together
+
+- If you still treat a teammate like s04's disposable subagent, revisit [`entity-map.md`](./entity-map.md) to see how they differ.
+- 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.
+- 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).
+
+## How It Plugs Into The Earlier System
+
+This chapter is not just "more model calls." It adds durable executors on top of work structures you already built in s12-s14.
+
+```text
+lead identifies work that needs a long-lived worker
+  ->
+spawn teammate
+  ->
+write roster entry in .team/config.json
+  ->
+send inbox message / task hint
+  ->
+teammate drains inbox before its next loop
+  ->
+teammate runs its own agent loop and tools
+  ->
+result returns through team messages or task updates
+```
+
+Keep the boundary straight:
+
+- s12-s14 gave you tasks, runtime slots, and schedules
+- s15 adds durable named workers
+- s15 is still mostly lead-assigned work
+- structured protocols arrive in s16
+- autonomous claiming arrives in s17
+
+## Teammate vs Subagent vs Runtime Slot
+
+| Mechanism | Think of it as | Lifecycle | Main boundary |
+|---|---|---|---|
+| subagent | a disposable helper | spawn -> work -> summary -> gone | isolates one exploratory branch |
+| runtime slot | a live execution slot | exists while background work is running | tracks long-running execution, not identity |
+| teammate | a durable worker | can go idle, resume, and keep receiving work | has a name, inbox, and independent loop |
+
+## What Changed From s14
+
+| Component      | Before (s14)     | After (s15)                |
+|----------------|------------------|----------------------------|
+| Tools          | 6                | 9 (+spawn/send/read_inbox) |
+| Agents         | Single           | Lead + N teammates         |
+| Persistence    | None             | config.json + JSONL inboxes|
+| Threads        | Background cmds  | Full agent loops per thread|
+| Lifecycle      | Fire-and-forget  | idle -> working -> idle    |
+| Communication  | None             | message + broadcast        |
+
+## Try It
+
+```sh
+cd learn-claude-code
+python agents/s15_agent_teams.py
+```
+
+1. `Spawn alice (coder) and bob (tester). Have alice send bob a message.`
+2. `Broadcast "status update: phase 1 complete" to all teammates`
+3. `Check the lead inbox for any messages`
+4. Type `/team` to see the team roster with statuses
+5. Type `/inbox` to manually check the lead's inbox
+
+## What You've Mastered
+
+At this point, you can:
+
+- Spawn persistent teammates that each run their own independent agent loop
+- Send messages between agents through durable JSONL inboxes
+- Track teammate status through a shared config file
+- Coordinate multiple agents without funneling everything through a single conversation
+
+## What's Next
+
+Your 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.
+
+## Key Takeaway
+
+> Teammates persist beyond one prompt, each with identity, lifecycle, and a durable mailbox -- coordination is no longer limited to a single parent loop.
diff --git a/docs/en/s16-team-protocols.md b/docs/en/s16-team-protocols.md
new file mode 100644
index 000000000..8b1ab1f7d
--- /dev/null
+++ b/docs/en/s16-team-protocols.md
@@ -0,0 +1,173 @@
+# s16: Team Protocols
+
+`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > [ s16 ] > s17 > s18 > s19`
+
+## What You'll Learn
+- How a request-response pattern with a tracking ID structures multi-agent negotiation
+- How the shutdown protocol lets a lead gracefully stop a teammate
+- How plan approval gates risky work behind a review step
+- How one reusable FSM (a simple status tracker with defined transitions) covers both protocols
+
+In 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.
+
+## The Problem
+
+Two coordination gaps become obvious once your team grows past toy examples:
+
+**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).
+
+**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.
+
+Both 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.
+
+## The Solution
+
+Both 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`).
+
+```
+Shutdown Protocol            Plan Approval Protocol
+==================           ======================
+
+Lead             Teammate    Teammate           Lead
+  |                 |           |                 |
+  |--shutdown_req-->|           |--plan_req------>|
+  | {req_id:"abc"}  |           | {req_id:"xyz"}  |
+  |                 |           |                 |
+  |<--shutdown_resp-|           |<--plan_resp-----|
+  | {req_id:"abc",  |           | {req_id:"xyz",  |
+  |  approve:true}  |           |  approve:true}  |
+
+Shared FSM:
+  [pending] --approve--> [approved]
+  [pending] --reject---> [rejected]
+
+Trackers:
+  shutdown_requests = {req_id: {target, status}}
+  plan_requests     = {req_id: {from, plan, status}}
+```
+
+## How It Works
+
+**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.
+
+```python
+shutdown_requests = {}
+
+def handle_shutdown_request(teammate: str) -> str:
+    req_id = str(uuid.uuid4())[:8]
+    shutdown_requests[req_id] = {"target": teammate, "status": "pending"}
+    BUS.send("lead", teammate, "Please shut down gracefully.",
+             "shutdown_request", {"request_id": req_id})
+    return f"Shutdown request {req_id} sent (status: pending)"
+```
+
+**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.
+
+```python
+if tool_name == "shutdown_response":
+    req_id = args["request_id"]
+    approve = args["approve"]
+    shutdown_requests[req_id]["status"] = "approved" if approve else "rejected"
+    BUS.send(sender, "lead", args.get("reason", ""),
+             "shutdown_response",
+             {"request_id": req_id, "approve": approve})
+```
+
+**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).
+
+```python
+plan_requests = {}
+
+def handle_plan_review(request_id, approve, feedback=""):
+    req = plan_requests[request_id]
+    req["status"] = "approved" if approve else "rejected"
+    BUS.send("lead", req["from"], feedback,
+             "plan_approval_response",
+             {"request_id": request_id, "approve": approve})
+```
+
+In 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.
+
+## Read Together
+
+- 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.
+- 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.
+- 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).
+
+## How It Plugs Into The Team System
+
+The real upgrade in s16 is not "two new message types." It is a durable coordination path:
+
+```text
+requester starts a protocol action
+  ->
+write RequestRecord
+  ->
+send ProtocolEnvelope through inbox
+  ->
+receiver drains inbox on its next loop
+  ->
+update request status by request_id
+  ->
+send structured response
+  ->
+requester continues based on approved / rejected
+```
+
+That is the missing layer between "agents can chat" and "agents can coordinate reliably."
+
+## Message vs Protocol vs Request vs Task
+
+| Object | What question it answers | Typical fields |
+|---|---|---|
+| `MessageEnvelope` | who said what to whom | `from`, `to`, `content` |
+| `ProtocolEnvelope` | is this a structured request / response | `type`, `request_id`, `payload` |
+| `RequestRecord` | where is this coordination flow now | `kind`, `status`, `from`, `to` |
+| `TaskRecord` | what actual work item is being advanced | `subject`, `status`, `blockedBy`, `owner` |
+
+Do not collapse them:
+
+- a protocol request is not the task itself
+- the request store is not the task board
+- protocols track coordination flow
+- tasks track work progression
+
+## What Changed From s15
+
+| Component      | Before (s15)     | After (s16)                  |
+|----------------|------------------|------------------------------|
+| Tools          | 9                | 12 (+shutdown_req/resp +plan)|
+| Shutdown       | Natural exit only| Request-response handshake   |
+| Plan gating    | None             | Submit/review with approval  |
+| Correlation    | None             | request_id per request       |
+| FSM            | None             | pending -> approved/rejected |
+
+## Try It
+
+```sh
+cd learn-claude-code
+python agents/s16_team_protocols.py
+```
+
+1. `Spawn alice as a coder. Then request her shutdown.`
+2. `List teammates to see alice's status after shutdown approval`
+3. `Spawn bob with a risky refactoring task. Review and reject his plan.`
+4. `Spawn charlie, have him submit a plan, then approve it.`
+5. Type `/team` to monitor statuses
+
+## What You've Mastered
+
+At this point, you can:
+
+- Build request-response protocols that use a unique ID for correlation
+- Implement graceful shutdown through a two-step handshake
+- Gate risky work behind a plan approval step
+- Reuse a single FSM pattern (`pending -> approved/rejected`) for any new protocol you invent
+
+## What's Next
+
+Your 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.
+
+## Key Takeaway
+
+> 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.
diff --git a/docs/en/s17-autonomous-agents.md b/docs/en/s17-autonomous-agents.md
new file mode 100644
index 000000000..e39a3e36f
--- /dev/null
+++ b/docs/en/s17-autonomous-agents.md
@@ -0,0 +1,171 @@
+# s17: Autonomous Agents
+
+`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > [ s17 ] > s18 > s19`
+
+## What You'll Learn
+- How idle polling lets a teammate find new work without being told
+- How auto-claim turns the task board into a self-service work queue
+- How identity re-injection restores a teammate's sense of self after context compression
+- How a timeout-based shutdown prevents idle agents from running forever
+
+Manual 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.
+
+## The Problem
+
+In 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.
+
+True 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.
+
+One 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.
+
+## The Solution
+
+Each 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.
+
+```
+Teammate lifecycle with idle cycle:
+
++-------+
+| spawn |
++---+---+
+    |
+    v
++-------+   tool_use     +-------+
+| WORK  | <------------- |  LLM  |
++---+---+                +-------+
+    |
+    | stop_reason != tool_use (or idle tool called)
+    v
++--------+
+|  IDLE  |  poll every 5s for up to 60s
++---+----+
+    |
+    +---> check inbox --> message? ----------> WORK
+    |
+    +---> scan .tasks/ --> unclaimed? -------> claim -> WORK
+    |
+    +---> 60s timeout ----------------------> SHUTDOWN
+
+Identity re-injection after compression:
+  if len(messages) <= 3:
+    messages.insert(0, identity_block)
+```
+
+## How It Works
+
+**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.
+
+```python
+def _loop(self, name, role, prompt):
+    while True:
+        # -- WORK PHASE --
+        messages = [{"role": "user", "content": prompt}]
+        for _ in range(50):
+            response = client.messages.create(...)
+            if response.stop_reason != "tool_use":
+                break
+            # execute tools...
+            if idle_requested:
+                break
+
+        # -- IDLE PHASE --
+        self._set_status(name, "idle")
+        resume = self._idle_poll(name, messages)
+        if not resume:
+            self._set_status(name, "shutdown")
+            return
+        self._set_status(name, "working")
+```
+
+**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.
+
+```python
+def _idle_poll(self, name, messages):
+    for _ in range(IDLE_TIMEOUT // POLL_INTERVAL):  # 60s / 5s = 12
+        time.sleep(POLL_INTERVAL)
+        inbox = BUS.read_inbox(name)
+        if inbox:
+            messages.append({"role": "user",
+                "content": f"<inbox>{inbox}</inbox>"})
+            return True
+        unclaimed = scan_unclaimed_tasks()
+        if unclaimed:
+            claim_task(unclaimed[0]["id"], name)
+            messages.append({"role": "user",
+                "content": f"<auto-claimed>Task #{unclaimed[0]['id']}: "
+                           f"{unclaimed[0]['subject']}</auto-claimed>"})
+            return True
+    return False  # timeout -> shutdown
+```
+
+**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.
+
+```python
+def scan_unclaimed_tasks() -> list:
+    unclaimed = []
+    for f in sorted(TASKS_DIR.glob("task_*.json")):
+        task = json.loads(f.read_text())
+        if (task.get("status") == "pending"
+                and not task.get("owner")
+                and not task.get("blockedBy")):
+            unclaimed.append(task)
+    return unclaimed
+```
+
+**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.
+
+```python
+if len(messages) <= 3:
+    messages.insert(0, {"role": "user",
+        "content": f"<identity>You are '{name}', role: {role}, "
+                   f"team: {team_name}. Continue your work.</identity>"})
+    messages.insert(1, {"role": "assistant",
+        "content": f"I am {name}. Continuing."})
+```
+
+## Read Together
+
+- 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.
+- 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.
+- 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).
+
+## What Changed From s16
+
+| Component      | Before (s16)     | After (s17)                |
+|----------------|------------------|----------------------------|
+| Tools          | 12               | 14 (+idle, +claim_task)    |
+| Autonomy       | Lead-directed    | Self-organizing            |
+| Idle phase     | None             | Poll inbox + task board    |
+| Task claiming  | Manual only      | Auto-claim unclaimed tasks |
+| Identity       | System prompt    | + re-injection after compress|
+| Timeout        | None             | 60s idle -> auto shutdown  |
+
+## Try It
+
+```sh
+cd learn-claude-code
+python agents/s17_autonomous_agents.py
+```
+
+1. `Create 3 tasks on the board, then spawn alice and bob. Watch them auto-claim.`
+2. `Spawn a coder teammate and let it find work from the task board itself`
+3. `Create tasks with dependencies. Watch teammates respect the blocked order.`
+4. Type `/tasks` to see the task board with owners
+5. Type `/team` to monitor who is working vs idle
+
+## What You've Mastered
+
+At this point, you can:
+
+- Build teammates that find and claim work from a shared task board without lead intervention
+- Implement an idle polling loop that balances responsiveness with resource efficiency
+- Restore agent identity after context compression so long-running teammates stay coherent
+- Use timeout-based shutdown to prevent abandoned agents from running indefinitely
+
+## What's Next
+
+Your 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.
+
+## Key Takeaway
+
+> Autonomous teammates scan the task board, claim unclaimed work, and shut down when idle -- removing the lead as a coordination bottleneck.
diff --git a/docs/en/s18-worktree-task-isolation.md b/docs/en/s18-worktree-task-isolation.md
new file mode 100644
index 000000000..529cbea67
--- /dev/null
+++ b/docs/en/s18-worktree-task-isolation.md
@@ -0,0 +1,151 @@
+# s18: Worktree + Task Isolation
+
+`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > [ s18 ] > s19`
+
+## What You'll Learn
+- How git worktrees (isolated copies of your project directory, managed by git) prevent file conflicts between parallel agents
+- How to bind a task to a dedicated worktree so that "what to do" and "where to do it" stay cleanly separated
+- How lifecycle events give you an observable record of every create, keep, and remove action
+- How parallel execution lanes let multiple agents work on different tasks without ever stepping on each other's files
+
+When 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.
+
+## The Problem
+
+By 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.
+
+The 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.
+
+## Read Together
+
+- 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.
+- If you want to confirm which fields belong on task records versus worktree records, [`data-structures.md`](./data-structures.md) has the full schema.
+- 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.
+
+## The Solution
+
+The 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.
+
+```
+Control plane (.tasks/)             Execution plane (.worktrees/)
++------------------+                +------------------------+
+| task_1.json      |                | auth-refactor/         |
+|   status: in_progress  <------>   branch: wt/auth-refactor
+|   worktree: "auth-refactor"   |   task_id: 1             |
++------------------+                +------------------------+
+| task_2.json      |                | ui-login/              |
+|   status: pending    <------>     branch: wt/ui-login
+|   worktree: "ui-login"       |   task_id: 2             |
++------------------+                +------------------------+
+                                    |
+                          index.json (worktree registry)
+                          events.jsonl (lifecycle log)
+
+State machines:
+  Task:     pending -> in_progress -> completed
+  Worktree: absent  -> active      -> removed | kept
+```
+
+## How It Works
+
+**Step 1.** Create a task. The goal is recorded first, before any directory exists.
+
+```python
+TASKS.create("Implement auth refactor")
+# -> .tasks/task_1.json  status=pending  worktree=""
+```
+
+**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.
+
+```python
+WORKTREES.create("auth-refactor", task_id=1)
+# -> git worktree add -b wt/auth-refactor .worktrees/auth-refactor HEAD
+# -> index.json gets new entry, task_1.json gets worktree="auth-refactor"
+```
+
+The binding writes state to both sides so you can traverse the relationship from either direction:
+
+```python
+def bind_worktree(self, task_id, worktree):
+    task = self._load(task_id)
+    task["worktree"] = worktree
+    if task["status"] == "pending":
+        task["status"] = "in_progress"
+    self._save(task)
+```
+
+**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.
+
+```python
+subprocess.run(command, shell=True, cwd=worktree_path,
+               capture_output=True, text=True, timeout=300)
+```
+
+**Step 4.** Close out the worktree. You have two choices, depending on whether the work is done:
+
+- `worktree_keep(name)` -- preserve the directory for later (useful when a task is paused or needs review).
+- `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.
+
+```python
+def remove(self, name, force=False, complete_task=False):
+    self._run_git(["worktree", "remove", wt["path"]])
+    if complete_task and wt.get("task_id") is not None:
+        self.tasks.update(wt["task_id"], status="completed")
+        self.tasks.unbind_worktree(wt["task_id"])
+        self.events.emit("task.completed", ...)
+```
+
+**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:
+
+```json
+{
+  "event": "worktree.remove.after",
+  "task": {"id": 1, "status": "completed"},
+  "worktree": {"name": "auth-refactor", "status": "removed"},
+  "ts": 1730000000
+}
+```
+
+Events emitted: `worktree.create.before/after/failed`, `worktree.remove.before/after/failed`, `worktree.keep`, `task.completed`.
+
+In 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.
+
+## What Changed From s17
+
+| Component          | Before (s17)               | After (s18)                                  |
+|--------------------|----------------------------|----------------------------------------------|
+| Coordination       | Task board (owner/status)  | Task board + explicit worktree binding       |
+| Execution scope    | Shared directory           | Task-scoped isolated directory               |
+| Recoverability     | Task status only           | Task status + worktree index                 |
+| Teardown           | Task completion            | Task completion + explicit keep/remove       |
+| Lifecycle visibility | Implicit in logs         | Explicit events in `.worktrees/events.jsonl` |
+
+## Try It
+
+```sh
+cd learn-claude-code
+python agents/s18_worktree_task_isolation.py
+```
+
+1. `Create tasks for backend auth and frontend login page, then list tasks.`
+2. `Create worktree "auth-refactor" for task 1, then bind task 2 to a new worktree "ui-login".`
+3. `Run "git status --short" in worktree "auth-refactor".`
+4. `Keep worktree "ui-login", then list worktrees and inspect events.`
+5. `Remove worktree "auth-refactor" with complete_task=true, then list tasks/worktrees/events.`
+
+## What You've Mastered
+
+At this point, you can:
+
+- Create isolated git worktrees so that parallel agents never produce file conflicts
+- Bind tasks to worktrees with a two-way reference (task points to worktree name, worktree points to task ID)
+- Choose between keeping and removing a worktree at closeout, with automatic task status updates
+- Read the event stream in `events.jsonl` to understand the full lifecycle of every worktree
+
+## What's Next
+
+You 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.
+
+## Key Takeaway
+
+> 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.
diff --git a/docs/en/s19-mcp-plugin.md b/docs/en/s19-mcp-plugin.md
new file mode 100644
index 000000000..628c7ef11
--- /dev/null
+++ b/docs/en/s19-mcp-plugin.md
@@ -0,0 +1,267 @@
+# s19: MCP & Plugin
+
+`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > [ s19 ]`
+
+## What You'll Learn
+- 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
+- How tool name normalization with a `mcp__{server}__{tool}` prefix keeps external tools from colliding with native ones
+- How a unified router dispatches tool calls to local handlers or remote servers through the same path
+- How plugin manifests let external capability servers be discovered and launched automatically
+
+Up 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.
+
+## The Problem
+
+Your 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.
+
+## The Solution
+
+MCP 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.
+
+```text
+LLM
+  |
+  | asks to call a tool
+  v
+Agent tool router
+  |
+  +-- native tool  -> local Python handler
+  |
+  +-- MCP tool     -> external MCP server
+                        |
+                        v
+                    return result
+```
+
+## Read Together
+
+- 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.
+- 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).
+- 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.
+
+## How It Works
+
+There are three essential pieces. Once you understand them, MCP stops being mysterious.
+
+**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.
+
+```python
+class MCPClient:
+    def __init__(self, server_name, command, args=None, env=None):
+        self.server_name = server_name
+        self.command = command
+        self.args = args or []
+        self.process = None
+        self._tools = []
+
+    def connect(self):
+        self.process = subprocess.Popen(
+            [self.command] + self.args,
+            stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE, text=True,
+        )
+        self._send({"method": "initialize", "params": {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {},
+            "clientInfo": {"name": "teaching-agent", "version": "1.0"},
+        }})
+        response = self._recv()
+        if response and "result" in response:
+            self._send({"method": "notifications/initialized"})
+            return True
+        return False
+
+    def list_tools(self):
+        self._send({"method": "tools/list", "params": {}})
+        response = self._recv()
+        if response and "result" in response:
+            self._tools = response["result"].get("tools", [])
+        return self._tools
+
+    def call_tool(self, tool_name, arguments):
+        self._send({"method": "tools/call", "params": {
+            "name": tool_name, "arguments": arguments,
+        }})
+        response = self._recv()
+        if response and "result" in response:
+            content = response["result"].get("content", [])
+            return "\n".join(c.get("text", str(c)) for c in content)
+        return "MCP Error: no response"
+```
+
+**Step 2.** Normalize external tool names with a prefix so they never collide with native tools. The convention is simple: `mcp__{server}__{tool}`.
+
+```text
+mcp__postgres__query
+mcp__browser__open_tab
+```
+
+This prefix serves double duty: it prevents name collisions, and it tells the router exactly which server should handle the call.
+
+```python
+def get_agent_tools(self):
+    agent_tools = []
+    for tool in self._tools:
+        prefixed_name = f"mcp__{self.server_name}__{tool['name']}"
+        agent_tools.append({
+            "name": prefixed_name,
+            "description": tool.get("description", ""),
+            "input_schema": tool.get("inputSchema", {
+                "type": "object", "properties": {}
+            }),
+        })
+    return agent_tools
+```
+
+**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.
+
+```python
+if tool_name.startswith("mcp__"):
+    return mcp_router.call(tool_name, arguments)
+else:
+    return native_handler(arguments)
+```
+
+**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:
+
+```json
+{
+  "name": "my-db-tools",
+  "version": "1.0.0",
+  "mcpServers": {
+    "postgres": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-postgres"]
+    }
+  }
+}
+```
+
+This lives in `.claude-plugin/plugin.json`. The `PluginLoader` scans for these manifests, extracts the server configs, and hands them to the `MCPToolRouter` for connection.
+
+**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.
+
+```python
+decision = permission_gate.check(block.name, block.input or {})
+# Same check for "bash", "read_file", and "mcp__postgres__query"
+```
+
+## How It Plugs Into The Full Harness
+
+MCP gets confusing when it is treated like a separate universe. The cleaner model is:
+
+```text
+startup
+  ->
+plugin loader finds manifests
+  ->
+server configs are extracted
+  ->
+MCP clients connect and list tools
+  ->
+external tools are normalized into the same tool pool
+
+runtime
+  ->
+LLM emits tool_use
+  ->
+shared permission gate
+  ->
+native route or MCP route
+  ->
+result normalization
+  ->
+tool_result returns to the same loop
+```
+
+Different entry point, same control plane and execution plane.
+
+## Plugin vs Server vs Tool
+
+| Layer | What it is | What it is for |
+|---|---|---|
+| plugin manifest | a config declaration | tells the harness which servers to discover and launch |
+| MCP server | an external process / connection | exposes a set of capabilities |
+| MCP tool | one callable capability from that server | the concrete thing the model invokes |
+
+Shortest memory aid:
+
+- plugin = discovery
+- server = connection
+- tool = invocation
+
+## Key Data Structures
+
+### Server config
+
+```python
+{
+    "command": "npx",
+    "args": ["-y", "..."],
+    "env": {}
+}
+```
+
+### Normalized external tool definition
+
+```python
+{
+    "name": "mcp__postgres__query",
+    "description": "Run a SQL query",
+    "input_schema": {...}
+}
+```
+
+### Client registry
+
+```python
+clients = {
+    "postgres": mcp_client_instance
+}
+```
+
+## What Changed From s18
+
+| Component          | Before (s18)                      | After (s19)                                      |
+|--------------------|-----------------------------------|--------------------------------------------------|
+| Tool sources       | All native (local Python)         | Native + external MCP servers                    |
+| Tool naming        | Flat names (`bash`, `read_file`)  | Prefixed for externals (`mcp__postgres__query`)  |
+| Routing            | Single handler map                | Unified router: native dispatch + MCP dispatch   |
+| Capability growth  | Edit harness code for each tool   | Add a plugin manifest or connect a server        |
+| Permission scope   | Native tools only                 | Native + external tools through same gate        |
+
+## Try It
+
+```sh
+cd learn-claude-code
+python agents/s19_mcp_plugin.py
+```
+
+1. Watch how external tools are discovered from plugin manifests at startup.
+2. Type `/tools` to see native and MCP tools listed side by side in one flat pool.
+3. Type `/mcp` to see which MCP servers are connected and how many tools each provides.
+4. Ask the agent to use a tool and notice how results return through the same loop as local tools.
+
+## What You've Mastered
+
+At this point, you can:
+
+- Connect to external capability servers using the MCP stdio protocol
+- Normalize external tool names with a `mcp__{server}__{tool}` prefix to prevent collisions
+- Route tool calls through a unified dispatcher that handles both native and MCP tools
+- Discover and launch MCP servers automatically through plugin manifests
+- Enforce the same permission checks on external tools as on native ones
+
+## The Full Picture
+
+You have now walked through the complete design backbone of a production coding agent, from s01 to s19.
+
+You 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.
+
+Each 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.
+
+If 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.
+
+## Key Takeaway
+
+> 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.
diff --git a/docs/en/s19a-mcp-capability-layers.md b/docs/en/s19a-mcp-capability-layers.md
new file mode 100644
index 000000000..cb094fe0a
--- /dev/null
+++ b/docs/en/s19a-mcp-capability-layers.md
@@ -0,0 +1,265 @@
+# s19a: MCP Capability Layers
+
+> **Deep Dive** -- Best read alongside s19. It shows that MCP is more than just external tools.
+
+### When to Read This
+
+After reading s19's tools-first approach, when you're ready to see the full MCP capability stack.
+
+---
+
+> `s19` should still keep a tools-first mainline.
+> This bridge note adds the second mental model:
+>
+> **MCP is not only external tool access. It is a stack of capability layers.**
+
+## How to Read This with the Mainline
+
+If you want to study MCP without drifting away from the teaching goal:
+
+- read [`s19-mcp-plugin.md`](./s19-mcp-plugin.md) first and keep the tools-first path clear
+- 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
+- if state records begin to blur, you might find it helpful to revisit [`data-structures.md`](./data-structures.md)
+- if concept boundaries blur, you might find it helpful to revisit [`glossary.md`](./glossary.md) and [`entity-map.md`](./entity-map.md)
+
+## Why This Deserves a Separate Bridge Note
+
+For a teaching repo, keeping the mainline focused on external tools first is correct.
+
+That is the easiest entry:
+
+- connect an external server
+- receive tool definitions
+- call a tool
+- bring the result back into the agent
+
+But if you want the system shape to approach real high-completion behavior, you quickly meet deeper questions:
+
+- is the server connected through stdio, HTTP, SSE, or WebSocket
+- why are some servers `connected`, while others are `pending` or `needs-auth`
+- where do resources and prompts fit relative to tools
+- why does elicitation become a special kind of interaction
+- where should OAuth or other auth flows be placed conceptually
+
+Without a capability-layer map, MCP starts to feel scattered.
+
+## Terms First
+
+### What capability layers means
+
+A capability layer is simply:
+
+> one responsibility slice in a larger system
+
+The point is to avoid mixing every MCP concern into one bag.
+
+### What transport means
+
+Transport is the connection channel between your agent and an MCP server:
+
+- stdio (standard input/output, good for local processes)
+- HTTP
+- SSE (Server-Sent Events, a one-way streaming protocol over HTTP)
+- WebSocket
+
+### What elicitation means
+
+This is one of the less familiar terms.
+
+A simple teaching definition is:
+
+> an interaction where the MCP server asks the user for more input before it can continue
+
+So the system is no longer only:
+
+> agent calls tool -> tool returns result
+
+The server can also say:
+
+> I need more information before I can finish
+
+This turns a simple call-and-return into a multi-step conversation between the agent and the server.
+
+## The Minimum Mental Model
+
+A clear six-layer picture:
+
+```text
+1. Config Layer
+   what the server configuration looks like
+
+2. Transport Layer
+   how the server connection is carried
+
+3. Connection State Layer
+   connected / pending / failed / needs-auth
+
+4. Capability Layer
+   tools / resources / prompts / elicitation
+
+5. Auth Layer
+   whether authentication is required and what state it is in
+
+6. Router Integration Layer
+   how MCP routes back into tool routing, permissions, and notifications
+```
+
+The key lesson is:
+
+**tools are one layer, not the whole MCP story**
+
+## Why the Mainline Should Still Stay Tools-First
+
+This matters a lot for teaching.
+
+Even though MCP contains multiple layers, the chapter mainline should still teach:
+
+### Step 1: external tools first
+
+Because that connects most naturally to everything you already learned:
+
+- local tools
+- external tools
+- one shared router
+
+### Step 2: show that more capability layers exist
+
+For example:
+
+- resources
+- prompts
+- elicitation
+- auth
+
+### Step 3: decide which advanced layers the repo should actually implement
+
+That matches the teaching goal:
+
+**build the similar system first, then add the heavier platform layers**
+
+## Core Records
+
+### 1. `ScopedMcpServerConfig`
+
+Even a minimal teaching version should expose this idea:
+
+```python
+config = {
+    "name": "postgres",
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "..."],
+    "scope": "project",
+}
+```
+
+`scope` matters because server configuration may come from different places (global user settings, project-level settings, or even per-workspace overrides).
+
+### 2. MCP connection state
+
+```python
+server_state = {
+    "name": "postgres",
+    "status": "connected",   # pending / failed / needs-auth / disabled
+    "config": {...},
+}
+```
+
+### 3. `MCPToolSpec`
+
+```python
+tool = {
+    "name": "mcp__postgres__query",
+    "description": "...",
+    "input_schema": {...},
+}
+```
+
+### 4. `ElicitationRequest`
+
+```python
+request = {
+    "server_name": "some-server",
+    "message": "Please provide additional input",
+    "requested_schema": {...},
+}
+```
+
+The teaching point is not that you need to implement elicitation immediately.
+
+The point is:
+
+**MCP is not guaranteed to stay a one-way tool invocation forever**
+
+## The Cleaner Platform Picture
+
+```text
+MCP Config
+  |
+  v
+Transport
+  |
+  v
+Connection State
+  |
+  +-- connected
+  +-- pending
+  +-- needs-auth
+  +-- failed
+  |
+  v
+Capabilities
+  +-- tools
+  +-- resources
+  +-- prompts
+  +-- elicitation
+  |
+  v
+Router / Permission / Notification Integration
+```
+
+## Why Auth Should Not Dominate the Chapter Mainline
+
+Auth is a real layer in the full platform.
+
+But if the mainline falls into OAuth or vendor-specific auth flow details too early, beginners lose the actual system shape.
+
+A better teaching order is:
+
+- first explain that an auth layer exists
+- then explain that `connected` and `needs-auth` are different connection states
+- only later, in advanced platform work, expand the full auth state machine
+
+That keeps the repo honest without derailing your learning path.
+
+## How This Relates to `s19` and `s02a`
+
+- the `s19` chapter keeps teaching the tools-first external capability path
+- this note supplies the broader platform map
+- `s02a` explains how MCP capability eventually reconnects to the unified tool control plane
+
+Together, they teach the actual idea:
+
+**MCP is an external capability platform, and tools are only the first face of it that enters the mainline**
+
+## Common Beginner Mistakes
+
+### 1. Treating MCP as only an external tool catalog
+
+That makes resources, prompts, auth, and elicitation feel surprising later.
+
+### 2. Diving into transport or OAuth details too early
+
+That breaks the teaching mainline.
+
+### 3. Letting MCP tools bypass permission checks
+
+That opens a dangerous side door in the system boundary.
+
+### 4. Mixing server config, connection state, and exposed capabilities into one blob
+
+Those layers should stay conceptually separate.
+
+## Key Takeaway
+
+**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.**
diff --git a/docs/en/teaching-scope.md b/docs/en/teaching-scope.md
new file mode 100644
index 000000000..f86abd8d2
--- /dev/null
+++ b/docs/en/teaching-scope.md
@@ -0,0 +1,155 @@
+# Teaching Scope
+
+This 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.
+
+## The Goal Of This Repo
+
+This is not a line-by-line commentary on some upstream production codebase.
+
+The real goal is:
+
+**teach you how to build a high-completion coding-agent harness from scratch.**
+
+That implies three obligations:
+
+1. you can actually rebuild it
+2. you keep the mainline clear instead of drowning in side detail
+3. you do not absorb mechanisms that do not really exist
+
+## What Every Chapter Should Cover
+
+Every mainline chapter should make these things explicit:
+
+- what problem the mechanism solves
+- which module or layer it belongs to
+- what state it owns
+- what data structures it introduces
+- how it plugs back into the loop
+- what changes in the runtime flow after it appears
+
+If you finish a chapter and still cannot say where the mechanism lives or what state it owns, the chapter is not done yet.
+
+## What We Deliberately Keep Simple
+
+These topics are not forbidden, but they should not dominate your learning path:
+
+- packaging, build, and release flow
+- cross-platform compatibility glue
+- telemetry and enterprise policy wiring
+- historical compatibility branches
+- product-specific naming accidents
+- line-by-line upstream code matching
+
+Those belong in appendices, maintainer notes, or later productization notes, not at the center of the beginner path.
+
+## What "High Fidelity" Really Means Here
+
+High fidelity in a teaching repo does not mean reproducing every edge detail 1:1.
+
+It means staying close to the true system backbone:
+
+- core runtime model
+- module boundaries
+- key records
+- state transitions
+- cooperation between major subsystems
+
+In short:
+
+**be highly faithful to the trunk, and deliberate about teaching simplifications at the edges.**
+
+## Who This Is For
+
+You do not need to be an expert in agent platforms.
+
+A better assumption about you:
+
+- basic Python is familiar
+- functions, classes, lists, and dictionaries are familiar
+- agent systems may be completely new
+
+That means the chapters should:
+
+- explain new concepts before using them
+- keep one concept complete in one main place
+- move from "what it is" to "why it exists" to "how to build it"
+
+## Recommended Chapter Structure
+
+Mainline chapters should roughly follow this order:
+
+1. what problem appears without this mechanism
+2. first explain the new terms
+3. give the smallest useful mental model
+4. show the core records / data structures
+5. show the smallest correct implementation
+6. show how it plugs into the main loop
+7. show common beginner mistakes
+8. show what a higher-completion version would add later
+
+## Terminology Guideline
+
+If a chapter introduces a term from these categories, it should explain it:
+
+- design pattern
+- data structure
+- concurrency term
+- protocol / networking term
+- uncommon engineering vocabulary
+
+Examples:
+
+- state machine
+- scheduler
+- queue
+- worktree
+- DAG
+- protocol envelope
+
+Do not drop the name without the explanation.
+
+## Minimal Correct Version Principle
+
+Real mechanisms are often complex, but teaching works best when it does not start with every branch at once.
+
+Prefer this sequence:
+
+1. show the smallest correct version
+2. explain what core problem it already solves
+3. show what later iterations would add
+
+Examples:
+
+- permission system: first `deny -> mode -> allow -> ask`
+- error recovery: first three major recovery branches
+- task system: first task records, dependencies, and unlocks
+- team protocols: first request / response plus `request_id`
+
+## Checklist For Rewriting A Chapter
+
+- Does the first screen explain why the mechanism exists?
+- Are new terms explained before they are used?
+- Is there a small mental model or flow picture?
+- Are key records listed explicitly?
+- Is the plug-in point back into the loop explained?
+- Are core mechanisms separated from peripheral product detail?
+- Are the easiest confusion points called out?
+- Does the chapter avoid inventing mechanisms not supported by the repo?
+
+## How To Use Reverse-Engineered Source Material
+
+Reverse-engineered source should be used as:
+
+**maintainer calibration material**
+
+Use it to:
+
+- verify the mainline mechanism is described correctly
+- verify important boundaries and records are not missing
+- verify the teaching implementation did not drift into fiction
+
+It should never become a prerequisite for understanding the teaching docs.
+
+## Key Takeaway
+
+**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.**
diff --git a/docs/en/team-task-lane-model.md b/docs/en/team-task-lane-model.md
new file mode 100644
index 000000000..6f49b65fc
--- /dev/null
+++ b/docs/en/team-task-lane-model.md
@@ -0,0 +1,316 @@
+# Team Task Lane Model
+
+> **Deep Dive** -- Best read at the start of Stage 4 (s15-s18). It separates five concepts that look similar but live on different layers.
+
+### When to Read This
+
+Before you start the team chapters. Keep it open as a reference during s15-s18.
+
+---
+
+> By the time you reach `s15-s18`, the easiest thing to blur is not a function name.
+>
+> It is this:
+>
+> **Who is working, who is coordinating, what records the goal, and what provides the execution lane.**
+
+## What This Bridge Doc Fixes
+
+Across `s15-s18`, you will encounter these words that can easily blur into one vague idea:
+
+- teammate
+- protocol request
+- task
+- runtime task
+- worktree
+
+They all relate to work getting done, but they do **not** live on the same layer.
+
+If you do not separate them, the later chapters start to feel tangled:
+
+- Is a teammate the same thing as a task?
+- What is the difference between `request_id` and `task_id`?
+- Is a worktree just another runtime task?
+- Why can a task be complete while a worktree is still kept?
+
+This document exists to separate those layers cleanly.
+
+## Recommended Reading Order
+
+1. Read [`s15-agent-teams.md`](./s15-agent-teams.md) for long-lived teammates.
+2. Read [`s16-team-protocols.md`](./s16-team-protocols.md) for tracked request-response coordination.
+3. Read [`s17-autonomous-agents.md`](./s17-autonomous-agents.md) for self-claiming teammates.
+4. Read [`s18-worktree-task-isolation.md`](./s18-worktree-task-isolation.md) for isolated execution lanes.
+
+If the vocabulary starts to blur, you might find it helpful to revisit:
+
+- [`entity-map.md`](./entity-map.md)
+- [`data-structures.md`](./data-structures.md)
+- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)
+
+## The Core Separation
+
+```text
+teammate
+  = who participates over time
+
+protocol request
+  = one tracked coordination request inside the team
+
+task
+  = what should be done
+
+runtime task / execution slot
+  = what is actively running right now
+
+worktree
+  = where the work executes without colliding with other lanes
+```
+
+The most common confusion is between the last three:
+
+- `task`
+- `runtime task`
+- `worktree`
+
+Ask three separate questions every time:
+
+- Is this the goal?
+- Is this the running execution unit?
+- Is this the isolated execution directory?
+
+## The Smallest Clean Diagram
+
+```text
+Team Layer
+  teammate: alice (frontend)
+
+Protocol Layer
+  request_id=req_01
+  kind=plan_approval
+  status=pending
+
+Work Graph Layer
+  task_id=12
+  subject="Implement login page"
+  owner="alice"
+  status="in_progress"
+
+Runtime Layer
+  runtime_id=rt_01
+  type=in_process_teammate
+  status=running
+
+Execution Lane Layer
+  worktree=login-page
+  path=.worktrees/login-page
+  status=active
+```
+
+Only one of those records the work goal itself:
+
+> `task_id=12`
+
+The others support coordination, execution, or isolation around that goal.
+
+## 1. Teammate: Who Is Collaborating
+
+Introduced in `s15`.
+
+This layer answers:
+
+- what the long-lived worker is called
+- what role it has
+- whether it is `working`, `idle`, or `shutdown`
+- whether it has its own inbox
+
+Example:
+
+```python
+member = {
+    "name": "alice",
+    "role": "frontend",
+    "status": "idle",
+}
+```
+
+The point is not "another agent instance."
+
+The point is:
+
+> a persistent identity that can repeatedly receive work.
+
+## 2. Protocol Request: What Is Being Coordinated
+
+Introduced in `s16`.
+
+This layer answers:
+
+- who asked whom
+- what kind of request this is
+- whether it is still pending or already resolved
+
+Example:
+
+```python
+request = {
+    "request_id": "a1b2c3d4",
+    "kind": "plan_approval",
+    "from": "alice",
+    "to": "lead",
+    "status": "pending",
+}
+```
+
+This is not ordinary chat.
+
+It is:
+
+> a coordination record whose state can continue to evolve.
+
+## 3. Task: What Should Be Done
+
+This is the durable work-graph task from `s12`, and it is what `s17` teammates claim.
+
+It answers:
+
+- what the goal is
+- who owns it
+- what blocks it
+- what progress state it is in
+
+Example:
+
+```python
+task = {
+    "id": 12,
+    "subject": "Implement login page",
+    "status": "in_progress",
+    "owner": "alice",
+    "blockedBy": [],
+}
+```
+
+Keyword:
+
+**goal**
+
+Not directory. Not protocol. Not process.
+
+## 4. Runtime Task / Execution Slot: What Is Running
+
+This layer was already clarified in the `s13a` bridge doc, but it matters even more in `s15-s18`.
+
+Examples:
+
+- a background shell command
+- a long-lived teammate currently working
+- a monitor process watching an external state
+
+These are best understood as:
+
+> active execution slots
+
+Example:
+
+```python
+runtime = {
+    "id": "rt_01",
+    "type": "in_process_teammate",
+    "status": "running",
+    "work_graph_task_id": 12,
+}
+```
+
+Important boundary:
+
+- one work-graph task may spawn multiple runtime tasks
+- a runtime task is an execution instance, not the durable goal itself
+
+## 5. Worktree: Where the Work Happens
+
+Introduced in `s18`.
+
+This layer answers:
+
+- which isolated directory is used
+- which task it is bound to
+- whether that lane is `active`, `kept`, or `removed`
+
+Example:
+
+```python
+worktree = {
+    "name": "login-page",
+    "path": ".worktrees/login-page",
+    "task_id": 12,
+    "status": "active",
+}
+```
+
+Keyword:
+
+**execution boundary**
+
+It is not the task goal itself. It is the isolated lane where that goal is executed.
+
+## How The Layers Connect
+
+```text
+teammate
+  coordinates through protocol requests
+  claims a task
+  runs as an execution slot
+  works inside a worktree lane
+```
+
+In a more concrete sentence:
+
+> `alice` claims `task #12` and progresses it inside the `login-page` worktree lane.
+
+That sentence is much cleaner than saying:
+
+> "alice is doing the login-page worktree task"
+
+because the shorter sentence incorrectly merges:
+
+- the teammate
+- the task
+- the worktree
+
+## Common Mistakes
+
+### 1. Treating teammate and task as the same object
+
+The teammate executes. The task expresses the goal.
+
+### 2. Treating `request_id` and `task_id` as interchangeable
+
+One tracks coordination. The other tracks work goals.
+
+### 3. Treating the runtime slot as the durable task
+
+The running execution may end while the durable task still exists.
+
+### 4. Treating the worktree as the task itself
+
+The worktree is only the execution lane.
+
+### 5. Saying "the system works in parallel" without naming the layers
+
+Good teaching does not stop at "there are many agents."
+
+It can say clearly:
+
+> teammates provide long-lived collaboration, requests track coordination, tasks record goals, runtime slots carry execution, and worktrees isolate the execution directory.
+
+## What You Should Be Able to Say After Reading This
+
+1. `s17` autonomy claims `s12` work-graph tasks, not `s13` runtime slots.
+2. `s18` worktrees bind execution lanes to tasks; they do not turn tasks into directories.
+3. A teammate can be idle while the task still exists and while the worktree is still kept.
+4. A protocol request tracks a coordination exchange, not a work goal.
+
+## Key Takeaway
+
+**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.**
diff --git a/docs/ja/data-structures.md b/docs/ja/data-structures.md
new file mode 100644
index 000000000..65f993cbd
--- /dev/null
+++ b/docs/ja/data-structures.md
@@ -0,0 +1,1191 @@
+# Core Data Structures (主要データ構造マップ)
+
+> agent 学習でいちばん迷いやすいのは、機能の多さそのものではなく、  
+> **「今の状態がどの record に入っているのか」が見えなくなること**です。  
+> この文書は、主線章と bridge doc に繰り返し出てくる record をひとつの地図として並べ直し、  
+> 読者が system 全体を「機能一覧」ではなく「状態の配置図」として理解できるようにするための資料です。
+
+## どう使うか
+
+この資料は辞書というより、`state map` として使ってください。
+
+- 単語の意味が怪しくなったら [`glossary.md`](./glossary.md) へ戻る
+- object 同士の境界が混ざったら [`entity-map.md`](./entity-map.md) を開く
+- `TaskRecord` と `RuntimeTaskState` が混ざったら [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) を読む
+- MCP で tools 以外の layer が混ざったら [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md) を併読する
+
+## 最初にこの 2 本だけは覚える
+
+### 原則 1: 内容状態と制御状態を分ける
+
+内容状態とは、system が「何を扱っているか」を表す状態です。
+
+例:
+
+- `messages`
+- `tool_result`
+- memory の本文
+- task の title や description
+
+制御状態とは、system が「次にどう進むか」を表す状態です。
+
+例:
+
+- `turn_count`
+- `transition`
+- `has_attempted_compact`
+- `max_output_tokens_override`
+- `pending_classifier_check`
+
+この 2 つを混ぜると、読者はすぐに次の疑問で詰まります。
+
+- なぜ `messages` だけでは足りないのか
+- なぜ control plane が必要なのか
+- なぜ recovery や compact が別 state を持つのか
+
+### 原則 2: durable state と runtime state を分ける
+
+`durable state` は、session をまたいでも残す価値がある状態です。
+
+例:
+
+- task
+- memory
+- schedule
+- team roster
+
+`runtime state` は、system が動いている間だけ意味を持つ状態です。
+
+例:
+
+- 現在の permission decision
+- 今走っている runtime task
+- active MCP connection
+- 今回の query の continuation reason
+
+この区別が曖昧だと、task・runtime slot・notification・schedule・worktree が全部同じ層に見えてしまいます。
+
+## 1. Query と会話制御の状態
+
+この層の核心は:
+
+> 会話内容を持つ record と、query の進行理由を持つ record は別物である
+
+です。
+
+### `Message`
+
+役割:
+
+- user と assistant の会話履歴を持つ
+- tool 呼び出し前後の往復も保存する
+
+最小形:
+
+```python
+message = {
+    "role": "user" | "assistant",
+    "content": "...",
+}
+```
+
+agent が tool を使い始めると、`content` は単なる文字列では足りなくなり、次のような block list になることがあります。
+
+- text block
+- `tool_use`
+- `tool_result`
+
+この record の本質は、**会話内容の記録**です。  
+「なぜ次ターンへ進んだか」は `Message` の責務ではありません。
+
+関連章:
+
+- `s01`
+- `s02`
+- `s06`
+- `s10`
+
+### `NormalizedMessage`
+
+役割:
+
+- さまざまな内部 message を、model API に渡せる統一形式へ揃える
+
+最小形:
+
+```python
+message = {
+    "role": "user" | "assistant",
+    "content": [
+        {"type": "text", "text": "..."},
+    ],
+}
+```
+
+`Message` と `NormalizedMessage` の違い:
+
+- `Message`: system 内部の履歴 record に近い
+- `NormalizedMessage`: model 呼び出し直前の入力形式に近い
+
+つまり、前者は「何を覚えているか」、後者は「何を送るか」です。
+
+関連章:
+
+- `s10`
+- [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md)
+
+### `CompactSummary`
+
+役割:
+
+- context が長くなり過ぎたとき、古い会話を要約へ置き換える
+
+最小形:
+
+```python
+summary = {
+    "task_overview": "...",
+    "current_state": "...",
+    "key_decisions": ["..."],
+    "next_steps": ["..."],
+}
+```
+
+重要なのは、compact が「ログ削除」ではないことです。  
+compact summary は次の query 継続に必要な最小構造を残す record です。
+
+最低でも次の 4 つは落とさないようにします。
+
+- task の大枠
+- ここまで終わったこと
+- 重要な判断
+- 次にやるべきこと
+
+関連章:
+
+- `s06`
+- `s11`
+
+### `SystemPromptBlock`
+
+役割:
+
+- system prompt を section 単位で管理する
+
+最小形:
+
+```python
+block = {
+    "text": "...",
+    "cache_scope": None,
+}
+```
+
+この record を持つ意味:
+
+- prompt を一枚岩の巨大文字列にしない
+- どの section が何の役割か説明できる
+- 後から block 単位で差し替えや検査ができる
+
+`cache_scope` は最初は不要でも構いません。  
+ただ、「この block は比較的安定」「この block は毎ターン変わる」という発想は早めに持っておくと、system prompt の理解が崩れにくくなります。
+
+関連章:
+
+- `s10`
+- [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md)
+
+### `PromptParts`
+
+役割:
+
+- system prompt を最終連結する前に、構成 source ごとに分けて持つ
+
+最小形:
+
+```python
+parts = {
+    "core": "...",
+    "tools": "...",
+    "skills": "...",
+    "memory": "...",
+    "dynamic": "...",
+}
+```
+
+この record は、読者に次のことを教えます。
+
+- prompt は「書かれている」のではなく「組み立てられている」
+- stable policy と volatile runtime data は同じ section ではない
+- input source ごとに責務を分けた方が debug しやすい
+
+関連章:
+
+- `s10`
+
+### `QueryParams`
+
+役割:
+
+- query 開始時点で外部から受け取る入口入力
+
+最小形:
+
+```python
+params = {
+    "messages": [...],
+    "system_prompt": "...",
+    "user_context": {...},
+    "system_context": {...},
+    "tool_use_context": {...},
+    "fallback_model": None,
+    "max_output_tokens_override": None,
+    "max_turns": None,
+}
+```
+
+ここで大切なのは:
+
+- これは query の**入口入力**である
+- query の途中でどんどん変わる内部状態とは別である
+
+つまり `QueryParams` は「入る前に決まっているもの」、`QueryState` は「入ってから変わるもの」です。
+
+関連章:
+
+- [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)
+
+### `QueryState`
+
+役割:
+
+- 1 本の query が複数ターンにわたって進む間の制御状態を持つ
+
+最小形:
+
+```python
+state = {
+    "messages": [...],
+    "tool_use_context": {...},
+    "turn_count": 1,
+    "max_output_tokens_recovery_count": 0,
+    "has_attempted_reactive_compact": False,
+    "max_output_tokens_override": None,
+    "pending_tool_use_summary": None,
+    "stop_hook_active": False,
+    "transition": None,
+}
+```
+
+この record に入るものの共通点:
+
+- 対話内容そのものではない
+- 「次をどう続けるか」を決める情報である
+
+初心者がよく詰まる点:
+
+- `messages` が入っているので「全部 conversation state に見える」
+- しかし `turn_count` や `transition` は会話ではなく control state
+
+この record を理解できると、
+
+- recovery
+- compact
+- hook continuation
+- token budget continuation
+
+がすべて「同じ query を継続する理由の差分」として読めるようになります。
+
+関連章:
+
+- [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)
+- `s11`
+
+### `TransitionReason`
+
+役割:
+
+- 前ターンが終わらず、次ターンへ続いた理由を明示する
+
+最小形:
+
+```python
+transition = {
+    "reason": "next_turn",
+}
+```
+
+より実用的には次のような値が入ります。
+
+- `next_turn`
+- `tool_result_continuation`
+- `reactive_compact_retry`
+- `max_output_tokens_recovery`
+- `stop_hook_continuation`
+
+これを別 record として持つ利点:
+
+- log が読みやすい
+- test が書きやすい
+- recovery の分岐理由を説明しやすい
+
+つまりこれは「高度な最適化」ではなく、  
+**継続理由を見える状態へ変えるための最小構造**です。
+
+関連章:
+
+- [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)
+- `s11`
+
+## 2. Tool 実行・権限・hook の状態
+
+この層の核心は:
+
+> tool は `name -> handler` だけで完結せず、その前後に permission / runtime / hook の状態が存在する
+
+です。
+
+### `ToolSpec`
+
+役割:
+
+- model に「どんな tool があり、どんな入力を受け取るか」を見せる
+
+最小形:
+
+```python
+tool = {
+    "name": "read_file",
+    "description": "Read file contents.",
+    "input_schema": {...},
+}
+```
+
+これは execution 実装そのものではありません。  
+あくまで **model に見せる contract** です。
+
+関連章:
+
+- `s02`
+- `s19`
+
+### `ToolDispatchMap`
+
+役割:
+
+- tool 名を実際の handler 関数へ引く
+
+最小形:
+
+```python
+dispatch = {
+    "read_file": run_read_file,
+    "write_file": run_write_file,
+}
+```
+
+この record の仕事は単純です。
+
+- 正しい handler を見つける
+
+ただし実システムではこれだけで足りません。  
+本当に難しいのは:
+
+- いつ実行するか
+- 並列にしてよいか
+- permission を通すか
+- 結果をどう loop へ戻すか
+
+です。
+
+関連章:
+
+- `s02`
+- [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md)
+
+### `ToolUseContext`
+
+役割:
+
+- tool が共有状態へ触るための窓口を持つ
+
+最小形:
+
+```python
+context = {
+    "workspace": "...",
+    "permission_system": perms,
+    "notifications": queue,
+    "memory_store": memory,
+}
+```
+
+この record がないと、各 tool が勝手に global state を触り始め、system 全体の境界が崩れます。
+
+つまり `ToolUseContext` は、
+
+> tool が system とどこで接続するか
+
+を見える形にするための record です。
+
+関連章:
+
+- `s02`
+- `s07`
+- `s09`
+- `s13`
+
+### `ToolResultEnvelope`
+
+役割:
+
+- tool 実行結果を loop が扱える統一形式で包む
+
+最小形:
+
+```python
+result = {
+    "tool_use_id": "toolu_123",
+    "content": "...",
+}
+```
+
+大切なのは、tool 結果が「ただの文字列」ではないことです。  
+最低でも:
+
+- どの tool call に対する結果か
+- loop にどう書き戻すか
+
+を持たせる必要があります。
+
+関連章:
+
+- `s02`
+
+### `PermissionRule`
+
+役割:
+
+- 特定 tool / path / content に対する allow / deny / ask 条件を表す
+
+最小形:
+
+```python
+rule = {
+    "tool": "bash",
+    "behavior": "deny",
+    "path": None,
+    "content": "sudo *",
+}
+```
+
+この record があることで、permission system は次を言えるようになります。
+
+- どの tool に対する rule か
+- 何にマッチしたら発火するか
+- 発火後に何を返すか
+
+関連章:
+
+- `s07`
+
+### `PermissionDecision`
+
+役割:
+
+- 今回の tool 実行に対する permission 結果を表す
+
+最小形:
+
+```python
+decision = {
+    "behavior": "allow" | "deny" | "ask",
+    "reason": "...",
+}
+```
+
+これを独立 record にする意味:
+
+- deny 理由を model が見える
+- ask を loop に戻して次アクションを組み立てられる
+- log や UI にも同じ object を流せる
+
+関連章:
+
+- `s07`
+
+### `HookEvent`
+
+役割:
+
+- pre_tool / post_tool / on_error などの lifecycle event を統一形で渡す
+
+最小形:
+
+```python
+event = {
+    "kind": "post_tool",
+    "tool_name": "edit_file",
+    "input": {...},
+    "result": "...",
+    "error": None,
+    "duration_ms": 42,
+}
+```
+
+hook が安定して増やせるかどうかは、この record の形が揃っているかに大きく依存します。
+
+もし毎回適当な文字列だけを hook に渡すと:
+
+- audit hook
+- metrics hook
+- policy hook
+
+のたびに payload 形式がばらけます。
+
+関連章:
+
+- `s08`
+
+### `ToolExecutionBatch`
+
+役割:
+
+- 同じ execution lane でまとめて調度してよい tool block の束を表す
+
+最小形:
+
+```python
+batch = {
+    "is_concurrency_safe": True,
+    "blocks": [tool_use_1, tool_use_2],
+}
+```
+
+この record を導入すると、読者は:
+
+- tool を常に 1 個ずつ実行する必要はない
+- ただし何でも並列にしてよいわけでもない
+
+という 2 本の境界を同時に理解しやすくなります。
+
+関連章:
+
+- [`s02b-tool-execution-runtime.md`](./s02b-tool-execution-runtime.md)
+
+### `TrackedTool`
+
+役割:
+
+- 各 tool の lifecycle を個別に追う
+
+最小形:
+
+```python
+tracked = {
+    "id": "toolu_01",
+    "name": "read_file",
+    "status": "queued",
+    "is_concurrency_safe": True,
+    "pending_progress": [],
+    "results": [],
+    "context_modifiers": [],
+}
+```
+
+これがあると runtime は次のことを説明できます。
+
+- 何が待機中か
+- 何が実行中か
+- 何が progress を出したか
+- 何が完了したか
+
+関連章:
+
+- [`s02b-tool-execution-runtime.md`](./s02b-tool-execution-runtime.md)
+
+### `queued_context_modifiers`
+
+役割:
+
+- 並列 tool が生んだ共有 state 変更を、先に queue し、後で安定順に merge する
+
+最小形:
+
+```python
+queued = {
+    "toolu_01": [modifier_a],
+    "toolu_02": [modifier_b],
+}
+```
+
+ここで守りたい境界:
+
+- 並列実行してよい
+- しかし共有 state を完了順でそのまま書き換えてよいとは限らない
+
+この record は、parallel execution と stable merge を切り分けるための最小構造です。
+
+関連章:
+
+- [`s02b-tool-execution-runtime.md`](./s02b-tool-execution-runtime.md)
+
+## 3. Skill・memory・prompt source の状態
+
+この層の核心は:
+
+> model input の材料は、その場でひとつの文字列に溶けているのではなく、複数の source record として存在する
+
+です。
+
+### `SkillRegistry`
+
+役割:
+
+- 利用可能な skill の索引を持つ
+
+最小形:
+
+```python
+registry = [
+    {"name": "agent-browser", "path": "...", "description": "..."},
+]
+```
+
+これは「何があるか」を示す record であり、skill 本文そのものではありません。
+
+関連章:
+
+- `s05`
+
+### `SkillContent`
+
+役割:
+
+- 実際に読み込んだ skill の本文や補助資料を持つ
+
+最小形:
+
+```python
+skill = {
+    "name": "agent-browser",
+    "body": "...markdown...",
+}
+```
+
+`SkillRegistry` と `SkillContent` を分ける理由:
+
+- registry は discovery 用
+- content は injection 用
+
+つまり「見つける record」と「使う record」を分けるためです。
+
+関連章:
+
+- `s05`
+
+### `MemoryEntry`
+
+役割:
+
+- 長期に残すべき事実を 1 件ずつ持つ
+
+最小形:
+
+```python
+entry = {
+    "key": "package_manager_preference",
+    "value": "pnpm",
+    "scope": "user",
+    "reason": "user explicit preference",
+}
+```
+
+memory の重要境界:
+
+- 会話全文を残す record ではない
+- durable fact を残す record である
+
+関連章:
+
+- `s09`
+
+### `MemoryWriteCandidate`
+
+役割:
+
+- 今回のターンから「long-term memory に昇格させる候補」を一時的に保持する
+
+最小形:
+
+```python
+candidate = {
+    "fact": "Use pnpm by default",
+    "scope": "user",
+    "confidence": "high",
+}
+```
+
+教学 repo では必須ではありません。  
+ただし reader が「memory はいつ書くのか」で混乱しやすい場合、この record を挟むと
+
+- その場の conversation detail
+- durable fact candidate
+- 実際に保存された memory
+
+の 3 層を分けやすくなります。
+
+関連章:
+
+- `s09`
+
+## 4. Todo・task・runtime・team の状態
+
+この層が一番混ざりやすいです。  
+理由は、全部が「仕事っぽい object」に見えるからです。
+
+### `TodoItem`
+
+役割:
+
+- 今の session 内での短期的な進行メモ
+
+最小形:
+
+```python
+todo = {
+    "content": "Inspect auth tests",
+    "status": "pending",
+}
+```
+
+これは durable work graph ではありません。  
+今ターンの認知負荷を軽くするための session-local 補助構造です。
+
+関連章:
+
+- `s03`
+
+### `PlanState`
+
+役割:
+
+- 複数の `TodoItem` と current focus をまとめる
+
+最小形:
+
+```python
+plan = {
+    "todos": [...],
+    "current_focus": "Inspect auth tests",
+}
+```
+
+これも基本は session-local です。  
+`TaskRecord` と違って、再起動しても必ず復元したい durable board とは限りません。
+
+関連章:
+
+- `s03`
+
+### `TaskRecord`
+
+役割:
+
+- durable work goal を表す
+
+最小形:
+
+```python
+task = {
+    "id": "task-auth-migrate",
+    "title": "Migrate auth layer",
+    "status": "pending",
+    "dependencies": [],
+}
+```
+
+この record が持つべき心智:
+
+- 何を達成したいか
+- 依存関係は何か
+- 今どの状態か
+
+ここで大切なのは、**task は goal node であって、今まさに走っている process ではない**ことです。
+
+関連章:
+
+- `s12`
+
+### `RuntimeTaskState`
+
+役割:
+
+- いま動いている 1 回の execution slot を表す
+
+最小形:
+
+```python
+runtime_task = {
+    "id": "rt_42",
+    "task_id": "task-auth-migrate",
+    "status": "running",
+    "preview": "...",
+    "output_file": ".runtime-tasks/rt_42.log",
+}
+```
+
+`TaskRecord` との違い:
+
+- `TaskRecord`: 何を達成するか
+- `RuntimeTaskState`: その goal に向かう今回の実行は今どうなっているか
+
+関連章:
+
+- `s13`
+- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)
+
+### `NotificationRecord`
+
+役割:
+
+- background 実行や外部 capability から main loop へ戻る preview を持つ
+
+最小形:
+
+```python
+note = {
+    "source": "runtime_task",
+    "task_id": "rt_42",
+    "preview": "3 tests failing...",
+}
+```
+
+この record は全文ログの保存先ではありません。  
+役割は:
+
+- main loop に「戻ってきた事実」を知らせる
+- prompt space を全文ログで埋めない
+
+ことです。
+
+関連章:
+
+- `s13`
+
+### `ScheduleRecord`
+
+役割:
+
+- いつ何を trigger するかを表す
+
+最小形:
+
+```python
+schedule = {
+    "name": "nightly-health-check",
+    "cron": "0 2 * * *",
+    "task_template": "repo_health_check",
+}
+```
+
+重要な境界:
+
+- `ScheduleRecord` は時間規則
+- `TaskRecord` は work goal
+- `RuntimeTaskState` は live execution
+
+この 3 つを一緒にしないことが `s14` の核心です。
+
+関連章:
+
+- `s14`
+
+### `TeamMember`
+
+役割:
+
+- 長期に存在する teammate の身元を表す
+
+最小形:
+
+```python
+member = {
+    "name": "alice",
+    "role": "test-specialist",
+    "status": "working",
+}
+```
+
+`TeamMember` は task ではありません。  
+「誰が長く system 内に存在しているか」を表す actor record です。
+
+関連章:
+
+- `s15`
+
+### `TeamConfig`
+
+役割:
+
+- team roster 全体をまとめる
+
+最小形:
+
+```python
+config = {
+    "team_name": "default",
+    "members": [member1, member2],
+}
+```
+
+この record を durable に持つことで、
+
+- team に誰がいるか
+- 役割が何か
+- 次回起動時に何を復元するか
+
+が見えるようになります。
+
+関連章:
+
+- `s15`
+
+### `MessageEnvelope`
+
+役割:
+
+- teammate 間の message を、本文とメタ情報込みで包む
+
+最小形:
+
+```python
+envelope = {
+    "type": "message",
+    "from": "lead",
+    "to": "alice",
+    "content": "Review retry tests",
+    "timestamp": 1710000000.0,
+}
+```
+
+`envelope` を使う理由:
+
+- 誰から誰へ送ったか分かる
+- 普通の会話と protocol request を区別しやすい
+- mailbox を durable channel として扱える
+
+関連章:
+
+- `s15`
+- `s16`
+
+### `RequestRecord`
+
+役割:
+
+- approval や shutdown のような構造化 protocol state を持つ
+
+最小形:
+
+```python
+request = {
+    "request_id": "req_91",
+    "kind": "plan_approval",
+    "status": "pending",
+    "payload": {...},
+}
+```
+
+これを別 record にすることで、
+
+- ただの chat message
+- 追跡可能な coordination request
+
+を明確に分けられます。
+
+関連章:
+
+- `s16`
+
+### `ClaimPolicy`
+
+役割:
+
+- autonomous worker が何を self-claim してよいかを表す
+
+最小形:
+
+```python
+policy = {
+    "role": "test-specialist",
+    "may_claim": ["retry-related"],
+}
+```
+
+この record がないと autonomy は「空いている worker が勝手に全部取りに行く」設計になりやすく、  
+race condition と重複実行を呼び込みます。
+
+関連章:
+
+- `s17`
+
+### `WorktreeRecord`
+
+役割:
+
+- isolated execution lane を表す
+
+最小形:
+
+```python
+worktree = {
+    "path": ".worktrees/wt-auth-migrate",
+    "task_id": "task-auth-migrate",
+    "status": "active",
+}
+```
+
+この record の核心:
+
+- task は goal
+- runtime slot は live execution
+- worktree は「どこで走るか」の lane
+
+関連章:
+
+- `s18`
+
+## 5. MCP・plugin・外部 capability の状態
+
+この層の核心は:
+
+> 外部 capability も「ただの tool list」ではなく、接続状態と routing を持つ platform object である
+
+です。
+
+### `MCPServerConfig`
+
+役割:
+
+- 外部 server の設定を表す
+
+最小形:
+
+```python
+config = {
+    "name": "figma",
+    "transport": "stdio",
+    "command": "...",
+}
+```
+
+これは capability そのものではなく、接続の入口設定です。
+
+関連章:
+
+- `s19`
+
+### `ConnectionState`
+
+役割:
+
+- remote capability の現在状態を表す
+
+最小形:
+
+```python
+state = {
+    "status": "connected",
+    "needs_auth": False,
+    "last_error": None,
+}
+```
+
+この record が必要な理由:
+
+- 外部 capability は常に使えるとは限らない
+- 問題が tool schema なのか connection なのか区別する必要がある
+
+関連章:
+
+- `s19`
+- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)
+
+### `CapabilityRoute`
+
+役割:
+
+- native tool / plugin / MCP server のどこへ解決されたかを表す
+
+最小形:
+
+```python
+route = {
+    "source": "mcp",
+    "target": "figma.inspect",
+}
+```
+
+この record があると、
+
+- 発見
+- routing
+- permission
+- 実行
+- result normalization
+
+が同じ capability bus 上で説明できます。
+
+関連章:
+
+- `s19`
+
+## 最後に、特に混同しやすい組み合わせ
+
+### `TodoItem` vs `TaskRecord`
+
+- `TodoItem`: 今 session で何を見るか
+- `TaskRecord`: durable work goal と dependency をどう持つか
+
+### `TaskRecord` vs `RuntimeTaskState`
+
+- `TaskRecord`: 何を達成したいか
+- `RuntimeTaskState`: 今回の実行は今どう進んでいるか
+
+### `RuntimeTaskState` vs `ScheduleRecord`
+
+- `RuntimeTaskState`: live execution
+- `ScheduleRecord`: いつ trigger するか
+
+### `SubagentContext` vs `TeamMember`
+
+- `SubagentContext`: 一回きりの delegation branch
+- `TeamMember`: 長期に残る actor identity
+
+### `TeamMember` vs `RequestRecord`
+
+- `TeamMember`: 誰が存在するか
+- `RequestRecord`: どんな coordination request が進行中か
+
+### `TaskRecord` vs `WorktreeRecord`
+
+- `TaskRecord`: 何をやるか
+- `WorktreeRecord`: どこでやるか
+
+### `ToolSpec` vs `CapabilityRoute`
+
+- `ToolSpec`: model に見せる contract
+- `CapabilityRoute`: 実際にどこへ routing するか
+
+## 読み終えたら言えるべきこと
+
+少なくとも次の 3 文を、自分の言葉で説明できる状態を目指してください。
+
+1. `messages` は内容状態であり、`transition` は制御状態である。
+2. `TaskRecord` は goal node であり、`RuntimeTaskState` は live execution slot である。
+3. `TeamMember`、`RequestRecord`、`WorktreeRecord` は全部「仕事っぽい」が、それぞれ actor、protocol、lane という別層の object である。
+
+## 一文で覚える
+
+**どの record が内容を持ち、どの record が流れを持ち、どれが durable でどれが runtime かを分けられれば、agent system の複雑さは急に読める形になります。**
diff --git a/docs/ja/entity-map.md b/docs/ja/entity-map.md
new file mode 100644
index 000000000..b21a0471c
--- /dev/null
+++ b/docs/ja/entity-map.md
@@ -0,0 +1,117 @@
+# エンティティ地図
+
+> この文書は「単語が似て見えるが、同じものではない」という混乱をほどくための地図です。
+
+## 何を分けるための文書か
+
+- [`glossary.md`](./glossary.md) は「この言葉は何か」を説明します
+- [`data-structures.md`](./data-structures.md) は「コードではどんな形か」を説明します
+- この文書は「どの層に属するか」を分けます
+
+## まず層を見る
+
+```text
+conversation layer
+  - message
+  - prompt block
+  - reminder
+
+action layer
+  - tool call
+  - tool result
+  - hook event
+
+work layer
+  - work-graph task
+  - runtime task
+  - protocol request
+
+execution layer
+  - subagent
+  - teammate
+  - worktree lane
+
+platform layer
+  - MCP server
+  - memory record
+  - capability router
+```
+
+## 混同しやすい組
+
+### `Message` vs `PromptBlock`
+
+| エンティティ | 何か | 何ではないか |
+|---|---|---|
+| `Message` | 会話履歴の内容 | 安定した system rule ではない |
+| `PromptBlock` | system instruction の断片 | 直近の会話イベントではない |
+
+### `Todo / Plan` vs `Task`
+
+| エンティティ | 何か | 何ではないか |
+|---|---|---|
+| `todo / plan` | セッション内の進行ガイド | durable work graph ではない |
+| `task` | durable な work node | その場の思いつきではない |
+
+### `Work-Graph Task` vs `RuntimeTaskState`
+
+| エンティティ | 何か | 何ではないか |
+|---|---|---|
+| work-graph task | 仕事目標と依存関係の node | 今動いている executor ではない |
+| runtime task | live execution slot | durable dependency node ではない |
+
+### `Subagent` vs `Teammate`
+
+| エンティティ | 何か | 何ではないか |
+|---|---|---|
+| subagent | 一回きりの委譲 worker | 長期に存在する team member ではない |
+| teammate | identity を持つ persistent collaborator | 使い捨て summary worker ではない |
+
+### `ProtocolRequest` vs normal message
+
+| エンティティ | 何か | 何ではないか |
+|---|---|---|
+| normal message | 自由文のやり取り | 追跡可能な approval workflow ではない |
+| protocol request | `request_id` を持つ構造化要求 | 雑談テキストではない |
+
+### `Task` vs `Worktree`
+
+| エンティティ | 何か | 何ではないか |
+|---|---|---|
+| task | 何をするか | ディレクトリではない |
+| worktree | どこで分離実行するか | 仕事目標そのものではない |
+
+### `Memory` vs `CLAUDE.md`
+
+| エンティティ | 何か | 何ではないか |
+|---|---|---|
+| memory | 後の session でも価値がある事実 | project rule file ではない |
+| `CLAUDE.md` | 安定した local rule / instruction surface | user 固有の long-term fact store ではない |
+
+### `MCPServer` vs `MCPTool`
+
+| エンティティ | 何か | 何ではないか |
+|---|---|---|
+| MCP server | 外部 capability provider | 1 個の tool 定義ではない |
+| MCP tool | server が公開する 1 つの capability | 接続面全体ではない |
+
+## 速見表
+
+| エンティティ | 主な役割 | 典型的な置き場 |
+|---|---|---|
+| `Message` | 会話履歴 | `messages[]` |
+| `PromptParts` | 入力 assembly の断片 | prompt builder |
+| `PermissionRule` | 実行可否の判断 | settings / session state |
+| `HookEvent` | lifecycle extension point | hook layer |
+| `MemoryEntry` | durable fact | memory store |
+| `TaskRecord` | durable work goal | task board |
+| `RuntimeTaskState` | live execution slot | runtime manager |
+| `TeamMember` | persistent actor | team config |
+| `MessageEnvelope` | teammate 間の構造化 message | inbox |
+| `RequestRecord` | protocol workflow state | request tracker |
+| `WorktreeRecord` | isolated execution lane | worktree index |
+| `MCPServerConfig` | 外部 capability provider 設定 | plugin / settings |
+
+## 一文で覚える
+
+**システムが複雑になるほど、単語を増やすことよりも、境界を混ぜないことの方が重要です。**
diff --git a/docs/ja/glossary.md b/docs/ja/glossary.md
new file mode 100644
index 000000000..9aa621b24
--- /dev/null
+++ b/docs/ja/glossary.md
@@ -0,0 +1,516 @@
+# 用語集
+
+> この用語集は、教材主線で特に重要で、初学者が混ぜやすい言葉だけを集めたものです。  
+> 何となく見覚えはあるのに、「結局これは何を指すのか」が言えなくなったら、まずここへ戻ってください。
+
+## いっしょに見ると整理しやすい文書
+
+- [`entity-map.md`](./entity-map.md): それぞれの言葉がどの層に属するかを見る
+- [`data-structures.md`](./data-structures.md): 実際にどんな record 形へ落ちるかを見る
+- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md): `task` という語が 2 種類に分かれ始めたときに戻る
+- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md): MCP が tool list だけに見えなくなったときに戻る
+
+## Agent
+
+この教材での `agent` は、
+
+> 入力を読み、判断し、必要なら tool を呼び出して仕事を進める model
+
+を指します。
+
+簡単に言えば、
+
+- model が考える
+- harness が作業環境を与える
+
+という分担の、考える側です。
+
+## Harness
+
+`harness` は agent の周囲に置く作業環境です。
+
+たとえば次を含みます。
+
+- tools
+- filesystem
+- permission system
+- prompt assembly
+- memory
+- task runtime
+
+model そのものは harness ではありません。  
+harness そのものも model ではありません。
+
+## Agent Loop
+
+`agent loop` は agent system の主循環です。
+
+最小形は次の 5 手順です。
+
+1. 現在の context を model に渡す
+2. response が普通の返答か tool_use かを見る
+3. tool を実行する
+4. result を context に戻す
+5. 次の turn へ続くか止まるかを決める
+
+この loop がなければ、system は単発の chat で終わります。
+
+## Message / `messages[]`
+
+`message` は 1 件の message、`messages[]` はその一覧です。
+
+多くの章では次を含みます。
+
+- user message
+- assistant message
+- tool_result
+
+これは agent の main working memory にあたります。  
+ただし permanent memory ではありません。
+
+## Tool
+
+`tool` は model が要求できる動作です。
+
+たとえば、
+
+- file を読む
+- file を書く
+- shell command を走らせる
+- text を検索する
+
+などです。
+
+重要なのは、
+
+> model が直接 OS command を叩くのではなく、tool 名と引数を宣言し、実際の実行は harness 側の code が行う
+
+という点です。
+
+## Tool Schema
+
+`tool schema` は tool の使い方を model に説明する構造です。
+
+普通は次を含みます。
+
+- tool 名
+- 何をするか
+- 必要な parameter
+- parameter の型
+
+初心者向けに言えば、tool の説明書です。
+
+## Dispatch Map
+
+`dispatch map` は、
+
+> tool 名から実際の handler 関数へつなぐ対応表
+
+です。
+
+たとえば次のような形です。
+
+```python
+{
+    "read_file": read_file_handler,
+    "write_file": write_file_handler,
+    "bash": bash_handler,
+}
+```
+
+## Stop Reason
+
+`stop_reason` は、model のこの turn がなぜ止まったかを示す理由です。
+
+代表例:
+
+- `end_turn`: 返答を終えた
+- `tool_use`: tool を要求した
+- `max_tokens`: 出力が token 上限で切れた
+
+main loop はこの値を見て次の動きを決めます。
+
+## Context
+
+`context` は model が今見えている情報全体です。
+
+ふつうは次を含みます。
+
+- `messages`
+- system prompt
+- dynamic reminder
+- tool_result
+
+context は permanent storage ではなく、
+
+> 今この turn の机の上に出ている情報
+
+と考えると分かりやすいです。
+
+## Compact / Compaction
+
+`compact` は active context を縮めることです。
+
+狙いは、
+
+- 本当に必要な流れを残す
+- 重複や雑音を削る
+- 後続 turn のための space を作る
+
+ことです。
+
+大事なのは「削ること」そのものではなく、
+
+**次の turn に必要な構造を保ったまま薄くすること**
+
+です。
+
+## Subagent
+
+`subagent` は親 agent から切り出された、一回限りの delegated worker です。
+
+価値は次です。
+
+- 親 context を汚さずに subtask を処理できる
+- 結果だけを summary として返せる
+
+`teammate` とは違い、長く system に残る actor ではありません。
+
+## Fork
+
+この教材での `fork` は、
+
+> 子 agent を空白から始めるのではなく、親の context を引き継いで始める方式
+
+を指します。
+
+subtask が親の議論背景を理解している必要があるときに使います。
+
+## Permission
+
+`permission` は、
+
+> model が要求した操作を実行してよいか判定する層
+
+です。
+
+良い permission system は少なくとも次を分けます。
+
+- すぐ拒否すべきもの
+- 自動許可してよいもの
+- user に確認すべきもの
+
+## Permission Mode
+
+`permission mode` は permission system の動作方針です。
+
+例:
+
+- `default`
+- `plan`
+- `auto`
+
+つまり個々の request の判定規則ではなく、
+
+> 判定の全体方針
+
+です。
+
+## Hook
+
+`hook` は主 loop を書き換えずに、特定の timing で追加動作を差し込む拡張点です。
+
+たとえば、
+
+- tool 実行前に検査する
+- tool 実行後に監査 log を書く
+
+のようなことを行えます。
+
+## Memory
+
+`memory` は session をまたいで残す価値のある情報です。
+
+向いているもの:
+
+- user の長期的 preference
+- 何度も再登場する重要事実
+- 将来の session でも役に立つ feedback
+
+向いていないもの:
+
+- その場限りの冗長な chat 履歴
+- すぐ再導出できる一時情報
+
+## System Prompt
+
+`system prompt` は system-level の instruction surface です。
+
+ここでは model に対して、
+
+- あなたは何者か
+- 何を守るべきか
+- どのように協力すべきか
+
+を与えます。
+
+普通の user message より安定して効く層です。
+
+## System Reminder
+
+`system reminder` は毎 turn 動的に差し込まれる短い補助情報です。
+
+たとえば、
+
+- current working directory
+- 現在日付
+- この turn だけ必要な補足
+
+などです。
+
+stable な system prompt とは役割が違います。
+
+## Query
+
+この教材での `query` は、
+
+> 1 つの user request を完了させるまで続く多 turn の処理全体
+
+を指します。
+
+単発の 1 回応答ではなく、
+
+- model 呼び出し
+- tool 実行
+- continuation
+- recovery
+
+を含んだまとまりです。
+
+## Transition Reason
+
+`transition reason` は、
+
+> なぜこの system が次の turn へ続いたのか
+
+を説明する理由です。
+
+これが見えるようになると、
+
+- 普通の tool continuation
+- retry
+- compact 後の再開
+- recovery path
+
+を混ぜずに見られるようになります。
+
+## Task
+
+`task` は durable work graph の中にある仕事目標です。
+
+ふつう次を持ちます。
+
+- subject
+- status
+- owner
+- dependency
+
+ここでの task は「いま実行中の command」ではなく、
+
+> system が長く持ち続ける work goal
+
+です。
+
+## Dependency Graph
+
+`dependency graph` は task 間の依存関係です。
+
+たとえば、
+
+- A が終わってから B
+- C と D は並行可
+- E は C と D の両方待ち
+
+のような関係を表します。
+
+これにより system は、
+
+- 今できる task
+- まだ blocked な task
+- 並行可能な task
+
+を判断できます。
+
+## Runtime Task / Runtime Slot
+
+`runtime task` または `runtime slot` は、
+
+> いま実行中、待機中、または直前まで動いていた live execution unit
+
+を指します。
+
+例:
+
+- background の `pytest`
+- 走っている teammate
+- monitor process
+
+`task` との違いはここです。
+
+- `task`: goal
+- `runtime slot`: live execution
+
+## Teammate
+
+`teammate` は multi-agent system 内で長く存在する collaborator です。
+
+`subagent` との違い:
+
+- `subagent`: 一回限りの委譲 worker
+- `teammate`: 長く残り、繰り返し仕事を受ける actor
+
+## Protocol
+
+`protocol` は、事前に決めた協調ルールです。
+
+答える内容は次です。
+
+- message はどんな shape か
+- response はどう返すか
+- approve / reject / expire をどう記録するか
+
+team 章では多くの場合、
+
+```text
+request -> response -> status update
+```
+
+という骨格で現れます。
+
+## Envelope
+
+`envelope` は、
+
+> 本文に加えてメタデータも一緒に包んだ構造化 record
+
+です。
+
+たとえば message 本文に加えて、
+
+- `from`
+- `to`
+- `request_id`
+- `timestamp`
+
+を一緒に持つものです。
+
+## State Machine
+
+`state machine` は難しい理論名に見えますが、ここでは
+
+> 状態がどう変化してよいかを書いた規則表
+
+です。
+
+たとえば、
+
+```text
+pending -> approved
+pending -> rejected
+pending -> expired
+```
+
+だけでも最小の state machine です。
+
+## Router
+
+`router` は分配器です。
+
+役割は、
+
+- request がどの種類かを見る
+- 正しい処理経路へ送る
+
+ことです。
+
+tool system では、
+
+- local handler
+- MCP client
+- plugin bridge
+
+のどこへ送るかを決める層として現れます。
+
+## Control Plane
+
+`control plane` は、
+
+> 自分で本仕事をするというより、誰がどう実行するかを調整する層
+
+です。
+
+たとえば、
+
+- permission 判定
+- prompt assembly
+- continuation 理由
+- lane 選択
+
+などがここに寄ります。
+
+初見では怖く見えるかもしれませんが、この教材ではまず
+
+> 実作業そのものではなく、作業の進め方を調整する層
+
+と覚えれば十分です。
+
+## Capability
+
+`capability` は能力項目です。
+
+MCP の文脈では、capability は tool だけではありません。
+
+たとえば、
+
+- tools
+- resources
+- prompts
+- elicitation
+
+のように複数層があります。
+
+## Worktree
+
+`worktree` は同じ repository の別 working copy です。
+
+この教材では、
+
+> task ごとに割り当てる isolated execution directory
+
+として使います。
+
+価値は次です。
+
+- 並行作業が互いの未コミット変更を汚染しない
+- task と execution lane の対応が見える
+- review や closeout がしやすい
+
+## MCP
+
+`MCP` は Model Context Protocol です。
+
+この教材では単なる remote tool list より広く、
+
+> 外部 capability を統一的に接続する surface
+
+として扱います。
+
+つまり「外部 tool を呼べる」だけではなく、
+
+- connection
+- auth
+- resources
+- prompts
+- capability routing
+
+まで含む層です。
diff --git a/docs/ja/s00-architecture-overview.md b/docs/ja/s00-architecture-overview.md
new file mode 100644
index 000000000..b3f740d05
--- /dev/null
+++ b/docs/ja/s00-architecture-overview.md
@@ -0,0 +1,341 @@
+# s00: アーキテクチャ全体図
+
+> この章は教材全体の地図です。  
+> 「結局この repository は何を教えようとしていて、なぜこの順番で章が並んでいるのか」を先に掴みたいなら、まずここから読むのがいちばん安全です。
+
+## 先に結論
+
+この教材の章順は妥当です。
+
+大事なのは章数の多さではありません。  
+大事なのは、初学者が無理なく積み上がる順番で system を育てていることです。
+
+全体は次の 4 段階に分かれています。
+
+1. まず本当に動く単一 agent を作る
+2. その上に安全性、拡張点、memory、prompt、recovery を足す
+3. 会話中の一時的 progress を durable work system へ押し上げる
+4. 最後に teams、protocols、autonomy、worktree、MCP / plugin へ広げる
+
+この順番が自然なのは、学習者が最初に固めるべき主線がたった 1 本だからです。
+
+```text
+user input
+  ->
+model reasoning
+  ->
+tool execution
+  ->
+result write-back
+  ->
+next turn or finish
+```
+
+この主線がまだ曖昧なまま後段の mechanism を積むと、
+
+- permission
+- hook
+- memory
+- MCP
+- worktree
+
+のような言葉が全部ばらばらの trivia に見えてしまいます。
+
+## この教材が再構成したいもの
+
+この教材の目標は、どこかの production code を逐行でなぞることではありません。
+
+本当に再構成したいのは次の部分です。
+
+- 主要 module は何か
+- module 同士がどう協調するか
+- 各 module の責務は何か
+- 重要 state がどこに住むか
+- 1 つの request が system の中をどう流れるか
+
+つまり狙っているのは、
+
+**設計主脈への高い忠実度であって、周辺実装の 1:1 再現ではありません。**
+
+これはとても重要です。
+
+もしあなたが本当に知りたいのが、
+
+> 0 から自分で高完成度の coding agent harness を作れるようになること
+
+なら、優先して掴むべきなのは次です。
+
+- agent loop
+- tools
+- planning
+- context management
+- permissions
+- hooks
+- memory
+- prompt assembly
+- tasks
+- teams
+- isolated execution lanes
+- external capability routing
+
+逆に、最初の主線に持ち込まなくてよいものもあります。
+
+- packaging / release
+- cross-platform compatibility の細かな枝
+- enterprise wiring
+- telemetry
+- 歴史的 compatibility layer
+- product 固有の naming accident
+
+これらが存在しうること自体は否定しません。  
+ただし 0-to-1 教学の中心に置くべきではありません。
+
+## 読むときの 3 つの原則
+
+### 1. まず最小で正しい版を学ぶ
+
+たとえば subagent なら、最初に必要なのはこれだけです。
+
+- 親 agent が subtask を切る
+- 子 agent が自分の `messages` を持つ
+- 子 agent が summary を返す
+
+これだけで、
+
+**親 context を汚さずに探索作業を切り出せる**
+
+という核心は学べます。
+
+そのあとでようやく、
+
+- 親 context を引き継ぐ fork
+- 独立 permission
+- background 実行
+- worktree 隔離
+
+を足せばよいです。
+
+### 2. 新しい語は使う前に意味を固める
+
+この教材では次のような語が頻繁に出ます。
+
+- state machine
+- dispatch map
+- dependency graph
+- worktree
+- protocol envelope
+- capability
+- control plane
+
+意味が曖昧なまま先へ進むと、後ろの章で一気に詰まります。
+
+そのときは無理に本文を読み切ろうとせず、次の文書へ戻ってください。
+
+- [`glossary.md`](./glossary.md)
+- [`entity-map.md`](./entity-map.md)
+- [`data-structures.md`](./data-structures.md)
+
+### 3. 周辺の複雑さを主線へ持ち込みすぎない
+
+良い教材は「全部話す教材」ではありません。
+
+良い教材は、
+
+- 核心は完全に話す
+- 周辺で重く複雑なものは後ろへ回す
+
+という構造を持っています。
+
+だからこの repository では、あえて主線の外に置いている内容があります。
+
+- packaging / release
+- enterprise policy glue
+- telemetry
+- client integration の細部
+- 逐行の逆向き比較 trivia
+
+## 先に開いておくと楽な補助文書
+
+主線 chapter と一緒に、次の文書を補助地図として持っておくと理解が安定します。
+
+| 文書 | 用途 |
+|---|---|
+| [`teaching-scope.md`](./teaching-scope.md) | 何を教え、何を意図的に省くかを見る |
+| [`data-structures.md`](./data-structures.md) | system 全体の重要 record を一か所で見る |
+| [`s00f-code-reading-order.md`](./s00f-code-reading-order.md) | chapter order と local code reading order をそろえる |
+
+さらに、後半で mechanism 間のつながりが曖昧になったら、次の bridge docs が効きます。
+
+| 文書 | 補うもの |
+|---|---|
+| [`s00d-chapter-order-rationale.md`](./s00d-chapter-order-rationale.md) | なぜ今の順番で学ぶのか |
+| [`s00e-reference-module-map.md`](./s00e-reference-module-map.md) | 参照 repository の高信号 module 群と教材章の対応 |
+| [`s00a-query-control-plane.md`](./s00a-query-control-plane.md) | 高完成度 system に loop 以外の control plane が必要になる理由 |
+| [`s00b-one-request-lifecycle.md`](./s00b-one-request-lifecycle.md) | 1 request が system 全体をどう流れるか |
+| [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md) | tool layer が単なる `tool_name -> handler` で終わらない理由 |
+| [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md) | message / prompt / memory がどこで合流するか |
+| [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) | durable task と live runtime slot の違い |
+| [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md) | MCP を capability bus として見るための地図 |
+| [`entity-map.md`](./entity-map.md) | entity の境界を徹底的に分ける |
+
+## 4 段階の学習パス
+
+### Stage 1: Core Single-Agent (`s01-s06`)
+
+ここでの目標は、
+
+**まず本当に役に立つ単一 agent を作ること**
+
+です。
+
+| 章 | 学ぶもの | 解く問題 |
+|---|---|---|
+| `s01` | Agent Loop | loop がなければ agent にならない |
+| `s02` | Tool Use | model を「話すだけ」から「実際に動く」へ変える |
+| `s03` | Todo / Planning | multi-step work が漂わないようにする |
+| `s04` | Subagent | 探索作業で親 context を汚さない |
+| `s05` | Skills | 必要な知識だけ後から載せる |
+| `s06` | Context Compact | 会話が長くなっても主線を保つ |
+
+### Stage 2: Hardening (`s07-s11`)
+
+ここでの目標は、
+
+**動くだけの agent を、安全で拡張可能な agent へ押し上げること**
+
+です。
+
+| 章 | 学ぶもの | 解く問題 |
+|---|---|---|
+| `s07` | Permission System | 危険な操作を gate の後ろへ置く |
+| `s08` | Hook System | loop 本体を書き換えず周辺拡張する |
+| `s09` | Memory System | 本当に価値ある情報だけを跨 session で残す |
+| `s10` | System Prompt | stable rule と runtime input を組み立てる |
+| `s11` | Error Recovery | 失敗後も stop 一択にしない |
+
+### Stage 3: Runtime Work (`s12-s14`)
+
+ここでの目標は、
+
+**session 中の計画を durable work graph と runtime execution に分けること**
+
+です。
+
+| 章 | 学ぶもの | 解く問題 |
+|---|---|---|
+| `s12` | Task System | work goal を disk 上に持つ |
+| `s13` | Background Tasks | 遅い command が前景思考を止めないようにする |
+| `s14` | Cron Scheduler | 時間そのものを trigger にする |
+
+### Stage 4: Platform (`s15-s19`)
+
+ここでの目標は、
+
+**single-agent harness を協調 platform へ広げること**
+
+です。
+
+| 章 | 学ぶもの | 解く問題 |
+|---|---|---|
+| `s15` | Agent Teams | persistent teammate を持つ |
+| `s16` | Team Protocols | 協調を自由文から structured flow へ上げる |
+| `s17` | Autonomous Agents | idle teammate が自分で次の work を取れるようにする |
+| `s18` | Worktree Isolation | 並行 task が同じ directory を踏み荒らさないようにする |
+| `s19` | MCP & Plugin | 外部 capability を統一 surface で扱う |
+
+## 各章が system に足す中核構造
+
+読者が中盤で混乱しやすいのは、
+
+- 今の章は何を増やしているのか
+- その state は system のどこに属するのか
+
+が曖昧になるからです。
+
+そこで各章を「新しく足す構造」で見直すとこうなります。
+
+| 章 | 中核構造 | 学習後に言えるべきこと |
+|---|---|---|
+| `s01` | `LoopState` | 最小の agent loop を自分で書ける |
+| `s02` | `ToolSpec` / dispatch map | model の意図を安定して実行へ落とせる |
+| `s03` | `TodoItem` / `PlanState` | 現在の progress を外部 state として持てる |
+| `s04` | `SubagentContext` | 親 context を汚さず委譲できる |
+| `s05` | `SkillRegistry` | 必要な knowledge を必要な時だけ注入できる |
+| `s06` | compaction records | 長い対話でも主線を保てる |
+| `s07` | `PermissionDecision` | 実行を gate の後ろへ置ける |
+| `s08` | hook events | loop を壊さず extension を追加できる |
+| `s09` | memory records | 跨 session で残すべき情報を選別できる |
+| `s10` | prompt parts | 入力を section 単位で組み立てられる |
+| `s11` | recovery state / transition reason | なぜ続行するのかを state として説明できる |
+| `s12` | `TaskRecord` | durable work graph を作れる |
+| `s13` | `RuntimeTaskState` | live execution と work goal を分けて見られる |
+| `s14` | `ScheduleRecord` | time-based trigger を足せる |
+| `s15` | `TeamMember` | persistent actor を持てる |
+| `s16` | `ProtocolEnvelope` / `RequestRecord` | structured coordination を作れる |
+| `s17` | `ClaimPolicy` / autonomy state | 自治的な claim / resume を説明できる |
+| `s18` | `WorktreeRecord` / `TaskBinding` | 並行 execution lane を分離できる |
+| `s19` | `MCPServerConfig` / capability route | native / plugin / MCP を同じ外側境界で見られる |
+
+## system 全体を 3 層で見る
+
+全体を最も簡単に捉えるなら、次の 3 層に分けてください。
+
+```text
+1. Main Loop
+   user input を受け、model を呼び、結果に応じて続く
+
+2. Control / Context Layer
+   permission、hook、memory、prompt、recovery が loop を支える
+
+3. Work / Platform Layer
+   tasks、teams、runtime slots、worktrees、MCP が大きな作業面を作る
+```
+
+図で見るとこうです。
+
+```text
+User
+  |
+  v
+messages[]
+  |
+  v
++-------------------------+
+| Agent Loop (s01)        |
+| 1. 入力を組み立てる      |
+| 2. model を呼ぶ         |
+| 3. stop_reason を見る   |
+| 4. tool を実行する      |
+| 5. result を write-back |
+| 6. 次 turn を決める     |
++-------------------------+
+  |
+  +------------------------------+
+  |                              |
+  v                              v
+Tool / Control Plane         Context / State Layer
+(s02, s07, s08, s19)         (s03, s06, s09, s10, s11)
+  |                              |
+  v                              v
+Tasks / Teams / Worktree / Runtime (s12-s18)
+```
+
+ここで大切なのは、system 全体を 1 本の巨大な file や 1 つの class として捉えないことです。
+
+**chapter order とは、system をどの層の順で理解すると最も心智負荷が低いかを表したもの**
+
+です。
+
+## この章を読み終えたら何が言えるべきか
+
+この章のゴールは、個々の API を覚えることではありません。
+
+読み終えた時点で、少なくとも次の 3 文を自分の言葉で言える状態を目指してください。
+
+1. この教材は production implementation の周辺 detail ではなく、agent harness の主設計を教えている
+2. chapter order は `single agent -> hardening -> runtime work -> platform` の 4 段階で意味がある
+3. 後ろの章の mechanism は前の章の上に自然に積み上がるので、順番を大きく崩すと学習心智が乱れる
+
+## 一文で覚える
+
+**良い章順とは、機能一覧ではなく、前の層から次の層が自然に育つ学習経路です。**
diff --git a/docs/ja/s00a-query-control-plane.md b/docs/ja/s00a-query-control-plane.md
new file mode 100644
index 000000000..f39966f2b
--- /dev/null
+++ b/docs/ja/s00a-query-control-plane.md
@@ -0,0 +1,243 @@
+# s00a: Query Control Plane
+
+> これは主線章ではなく橋渡し文書です。  
+> ここで答えたいのは次の問いです。
+>
+> **なぜ高完成度の agent は `messages[]` と `while True` だけでは足りないのか。**
+
+## なぜこの文書が必要か
+
+`s01` では最小の loop を学びます。
+
+```text
+ユーザー入力
+  ->
+モデル応答
+  ->
+tool_use があれば実行
+  ->
+tool_result を戻す
+  ->
+次ターン
+```
+
+これは正しい出発点です。
+
+ただし実システムが成長すると、支えるのは loop 本体だけではなく:
+
+- 今どの turn か
+- なぜ続行したのか
+- compact を試したか
+- token recovery 中か
+- hook が終了条件に影響しているか
+
+といった **query 制御状態** です。
+
+この層を明示しないと、動く demo は作れても、高完成度 harness へ育てにくくなります。
+
+## まず用語を分ける
+
+### Query
+
+ここでの `query` は database query ではありません。
+
+意味は:
+
+> 1つのユーザー要求を完了するまで続く、多ターンの処理全体
+
+です。
+
+### Control Plane
+
+`control plane` は:
+
+> 実際の業務動作をする層ではなく、流れをどう進めるかを管理する層
+
+です。
+
+ここでは:
+
+- model 応答や tool result は内容
+- 「次に続けるか」「なぜ続けるか」は control plane
+
+と考えると分かりやすいです。
+
+### Transition Reason
+
+`transition reason` は:
+
+> 前のターンが終わらず、次ターンへ進んだ理由
+
+です。
+
+たとえば:
+
+- tool が終わった
+- 出力が切れて続きを書く必要がある
+- compact 後に再実行する
+- hook が続行を要求した
+
+などがあります。
+
+## 最小の心智モデル
+
+```text
+1. 入力層
+   - messages
+   - system prompt
+   - runtime context
+
+2. 制御層
+   - query state
+   - turn count
+   - transition reason
+   - compact / recovery flags
+
+3. 実行層
+   - model call
+   - tool execution
+   - write-back
+```
+
+この層は loop を置き換えるためではありません。
+
+**小さな loop を、分岐と状態を扱える system に育てるため**にあります。
+
+## なぜ `messages[]` だけでは足りないか
+
+最小 demo では、多くのことを `messages[]` に押し込めても動きます。
+
+しかし次の情報は会話内容ではなく制御状態です。
+
+- reactive compact を既に試したか
+- 出力続行を何回したか
+- 今回の続行が tool によるものか recovery によるものか
+- 今だけ output budget を変えているか
+
+これらを全部 `messages[]` に混ぜると、状態の境界が崩れます。
+
+## 主要なデータ構造
+
+### `QueryParams`
+
+query に入るときの外部入力です。
+
+```python
+params = {
+    "messages": [...],
+    "system_prompt": "...",
+    "user_context": {...},
+    "system_context": {...},
+    "tool_use_context": {...},
+    "max_output_tokens_override": None,
+    "max_turns": None,
+}
+```
+
+これは「入口で既に分かっているもの」です。
+
+### `QueryState`
+
+query の途中で変わり続ける制御状態です。
+
+```python
+state = {
+    "messages": [...],
+    "tool_use_context": {...},
+    "turn_count": 1,
+    "continuation_count": 0,
+    "has_attempted_compact": False,
+    "max_output_tokens_override": None,
+    "stop_hook_active": False,
+    "transition": None,
+}
+```
+
+重要なのは:
+
+- 内容状態と制御状態を分ける
+- どの continue site も同じ state を更新する
+
+ことです。
+
+### `TransitionReason`
+
+続行理由は文字列でも enum でもよいですが、明示する方がよいです。
+
+```python
+TRANSITIONS = (
+    "tool_result_continuation",
+    "max_tokens_recovery",
+    "compact_retry",
+    "stop_hook_continuation",
+)
+```
+
+これで:
+
+- log
+- test
+- debug
+- 教材説明
+
+がずっと分かりやすくなります。
+
+## 最小実装の流れ
+
+### 1. 外部入力と内部状態を分ける
+
+```python
+def query(params):
+    state = {
+        "messages": params["messages"],
+        "tool_use_context": params["tool_use_context"],
+        "turn_count": 1,
+        "continuation_count": 0,
+        "has_attempted_compact": False,
+        "transition": None,
+    }
+```
+
+### 2. 各ターンで state を読んで実行する
+
+```python
+while True:
+    response = call_model(...)
+```
+
+### 3. 続行時は必ず state に理由を書き戻す
+
+```python
+if response.stop_reason == "tool_use":
+    state["messages"] = append_tool_results(...)
+    state["transition"] = "tool_result_continuation"
+    state["turn_count"] += 1
+    continue
+```
+
+大事なのは:
+
+**ただ `continue` するのではなく、なぜ `continue` したかを状態に残すこと**
+
+です。
+
+## 初学者が混ぜやすいもの
+
+### 1. 会話内容と制御状態
+
+- `messages` は内容
+- `turn_count` や `transition` は制御
+
+### 2. Loop と Control Plane
+
+- loop は反復の骨格
+- control plane はその反復を管理する層
+
+### 3. Prompt assembly と query state
+
+- prompt assembly は「このターンに model へ何を渡すか」
+- query state は「この query が今どういう状態か」
+
+## 一文で覚える
+
+**高完成度の agent では、会話内容を持つ層と、続行理由を持つ層を分けた瞬間に system の見通しが良くなります。**
diff --git a/docs/ja/s00b-one-request-lifecycle.md b/docs/ja/s00b-one-request-lifecycle.md
new file mode 100644
index 000000000..aab6b4a57
--- /dev/null
+++ b/docs/ja/s00b-one-request-lifecycle.md
@@ -0,0 +1,263 @@
+# s00b: 1 リクエストのライフサイクル
+
+> これは橋渡し文書です。  
+> 章ごとの説明を、1本の実行の流れとしてつなぎ直します。
+>
+> 問いたいのは次です。
+>
+> **ユーザーの一言が system に入ってから、どう流れ、どこで状態が変わり、どう loop に戻るのか。**
+
+## なぜ必要か
+
+章を順に読むと、個別の仕組みは理解できます。
+
+- `s01`: loop
+- `s02`: tools
+- `s07`: permissions
+- `s09`: memory
+- `s12-s19`: tasks / teams / worktree / MCP
+
+しかし実装段階では、次の疑問で詰まりやすいです。
+
+- 先に走るのは prompt か memory か
+- tool 実行前に permissions と hooks はどこへ入るのか
+- task、runtime task、teammate、worktree はどの段で関わるのか
+
+この文書はその縦の流れをまとめます。
+
+## まず全体図
+
+```text
+ユーザー要求
+  |
+  v
+Query State 初期化
+  |
+  v
+system prompt / messages / reminders を組み立てる
+  |
+  v
+モデル呼び出し
+  |
+  +-- 普通の応答 --------------------------> 今回の request は終了
+  |
+  +-- tool_use
+        |
+        v
+    Tool Router
+        |
+        +-- permission gate
+        +-- hook interception
+        +-- native tool / task / teammate / MCP
+        |
+        v
+    実行結果
+        |
+        +-- task / runtime / memory / worktree 状態を書き換える場合がある
+        |
+        v
+    tool_result を messages へ write-back
+        |
+        v
+    Query State 更新
+        |
+        v
+    次ターン
+```
+
+## 第 1 段: Query State を作る
+
+ユーザーが:
+
+```text
+tests/test_auth.py の失敗を直して、原因も説明して
+```
+
+と言ったとき、最初に起きるのは shell 実行ではありません。
+
+まず「今回の request の状態」が作られます。
+
+```python
+query_state = {
+    "messages": [{"role": "user", "content": user_text}],
+    "turn_count": 1,
+    "transition": None,
+    "tool_use_context": {...},
+}
+```
+
+ポイントは:
+
+**1 リクエスト = 1 API call ではなく、複数ターンにまたがる処理**
+
+ということです。
+
+## 第 2 段: モデル入力を組み立てる
+
+実システムは、生の `messages` だけをそのまま送らないことが多いです。
+
+組み立てる対象はたとえば:
+
+- system prompt blocks
+- normalized messages
+- memory section
+- reminders
+- tool list
+
+つまりモデルが実際に見るのは:
+
+```text
+system prompt
++ normalized messages
++ optional memory / reminders / attachments
++ tools
+```
+
+ここで大事なのは:
+
+**system prompt は入力全体ではなく、その一部**
+
+だということです。
+
+## 第 3 段: モデルは 2 種類の出力を返す
+
+### 1. 普通の回答
+
+結論や説明だけを返し、今回の request が終わる場合です。
+
+### 2. 動作意図
+
+tool call です。
+
+例:
+
+```text
+read_file(...)
+bash(...)
+todo_write(...)
+agent(...)
+mcp__server__tool(...)
+```
+
+ここで system が受け取るのは単なる文章ではなく:
+
+> モデルが「現実の動作を起こしたい」という意図
+
+です。
+
+## 第 4 段: Tool Router が受け取る
+
+`tool_use` が出たら、次は tool control plane の責任です。
+
+最低でも次を決めます。
+
+1. これはどの tool か
+2. どの handler / capability へ送るか
+3. 実行前に permission が必要か
+4. hook が割り込むか
+5. どの共有状態へアクセスするか
+
+## 第 5 段: Permission が gate をかける
+
+危険な動作は、そのまま実行されるべきではありません。
+
+たとえば:
+
+- file write
+- bash
+- 外部 service 呼び出し
+- worktree の削除
+
+ここで system は:
+
+```text
+deny
+  -> mode
+  -> allow
+  -> ask
+```
+
+のような判断経路を持ちます。
+
+permission が扱うのは:
+
+> この動作を起こしてよいか
+
+です。
+
+## 第 6 段: Hook が周辺ロジックを足す
+
+hook は permission とは別です。
+
+hook は:
+
+- 実行前の補助チェック
+- 実行後の記録
+- 補助メッセージの注入
+
+など、loop の周辺で side effect を足します。
+
+つまり:
+
+- permission は gate
+- hook は extension
+
+です。
+
+## 第 7 段: 実行結果が状態を変える
+
+tool は text だけを返すとは限りません。
+
+実行によって:
+
+- task board が更新される
+- runtime task が生成される
+- memory 候補が増える
+- worktree lane が作られる
+- teammate へ request が飛ぶ
+- MCP resource / tool result が返る
+
+といった状態変化が起きます。
+
+ここでの大原則は:
+
+**tool result は内容を返すだけでなく、system state を進める**
+
+ということです。
+
+## 第 8 段: tool_result を loop へ戻す
+
+最後に system は結果を `messages` へ戻します。
+
+```python
+messages.append({
+    "role": "user",
+    "content": [
+        {"type": "tool_result", ...}
+    ],
+})
+```
+
+そして query state を更新し:
+
+- `turn_count`
+- `transition`
+- compact / recovery flags
+
+などを整えて、次ターンへ進みます。
+
+## 後半章はどこで関わるか
+
+| 仕組み | 1 request の中での役割 |
+|---|---|
+| `s09` memory | 入力 assembly の一部になる |
+| `s10` prompt pipeline | 各 source を 1 つの model input へ組む |
+| `s12` task | durable work goal を持つ |
+| `s13` runtime task | 今動いている execution slot を持つ |
+| `s15-s17` teammate / protocol / autonomy | request を actor 間で回す |
+| `s18` worktree | 実行ディレクトリを分離する |
+| `s19` MCP | 外部 capability provider と接続する |
+
+## 一文で覚える
+
+**1 request の本体は「モデルを 1 回呼ぶこと」ではなく、「入力を組み、動作を実行し、結果を state に戻し、必要なら次ターンへ続けること」です。**
diff --git a/docs/ja/s00c-query-transition-model.md b/docs/ja/s00c-query-transition-model.md
new file mode 100644
index 000000000..71a4c7dd2
--- /dev/null
+++ b/docs/ja/s00c-query-transition-model.md
@@ -0,0 +1,264 @@
+# s00c: Query Transition Model
+
+> この bridge doc は次の一点を解くためのものです。
+>
+> **高完成度の agent では、なぜ query が次の turn へ続くのかを明示しなければならないのか。**
+
+## なぜこの資料が必要か
+
+主線では次を順に学びます。
+
+- `s01`: 最小 loop
+- `s06`: context compact
+- `s11`: error recovery
+
+流れ自体は正しいです。
+
+ただし、章ごとに別々に読むと多くの読者は次のように理解しがちです。
+
+> 「とにかく `continue` したから次へ進む」
+
+これは toy demo なら動きます。
+
+しかし高完成度システムではすぐに破綻します。
+
+なぜなら query が継続する理由は複数あり、それぞれ本質が違うからです。
+
+- tool が終わり、その結果を model に戻す
+- 出力が token 上限で切れて続きが必要
+- compact 後に再試行する
+- transport error の後で backoff して再試行する
+- stop hook がまだ終わるなと指示する
+- budget policy がまだ継続を許している
+
+これら全部を曖昧な `continue` に潰すと、すぐに次が悪化します。
+
+- log が読みにくくなる
+- test が書きにくくなる
+- 学習者の心智モデルが濁る
+
+## まず用語
+
+### transition とは
+
+ここでの `transition` は:
+
+> 前の turn が次の turn へ移った理由
+
+を指します。
+
+message 内容そのものではなく、制御上の原因です。
+
+### continuation とは
+
+continuation は:
+
+> この query がまだ終わっておらず、先へ進むべき状態
+
+のことです。
+
+ただし continuation は一種類ではありません。
+
+### query boundary とは
+
+query boundary は turn と次の turn の境目です。
+
+この境界を越えるたびに、システムは次を知っているべきです。
+
+- なぜ続くのか
+- 続く前にどの state を変えたのか
+- 次の turn がその変更をどう解釈するのか
+
+## 最小の心智モデル
+
+query を一本の直線だと思わないでください。
+
+より実像に近い理解は次です。
+
+```text
+1 本の query
+  = 明示された continuation reason を持つ
+    state transition の連鎖
+```
+
+例えば:
+
+```text
+user input
+  ->
+model emits tool_use
+  ->
+tool finishes
+  ->
+tool_result_continuation
+  ->
+model output is truncated
+  ->
+max_tokens_recovery
+  ->
+compact_retry
+  ->
+final completion
+```
+
+重要なのは:
+
+> システムは while loop を漫然と回しているのではなく、
+> 明示された transition reason の列で進んでいる
+
+ということです。
+
+## 主要 record
+
+### 1. query state の `transition`
+
+教材版でも次のような field は明示しておくべきです。
+
+```python
+state = {
+    "messages": [...],
+    "turn_count": 3,
+    "continuation_count": 1,
+    "has_attempted_compact": False,
+    "transition": None,
+}
+```
+
+この field は飾りではありません。
+
+これによって:
+
+- この turn がなぜ存在するか
+- log がどう説明すべきか
+- test がどの path を assert すべきか
+
+が明確になります。
+
+### 2. `TransitionReason`
+
+教材版の最小集合は次の程度で十分です。
+
+```python
+TRANSITIONS = (
+    "tool_result_continuation",
+    "max_tokens_recovery",
+    "compact_retry",
+    "transport_retry",
+    "stop_hook_continuation",
+    "budget_continuation",
+)
+```
+
+これらは同じではありません。
+
+- `tool_result_continuation`
+  は通常の主線継続
+- `max_tokens_recovery`
+  は切れた出力の回復継続
+- `compact_retry`
+  は context 再構成後の継続
+- `transport_retry`
+  は基盤失敗後の再試行継続
+- `stop_hook_continuation`
+  は外部制御による継続
+- `budget_continuation`
+  は budget policy による継続
+
+### 3. continuation budget
+
+高完成度システムは単に続行するだけではなく、続行回数を制御します。
+
+```python
+state = {
+    "max_output_tokens_recovery_count": 2,
+    "has_attempted_reactive_compact": True,
+}
+```
+
+本質は:
+
+> continuation は無限の抜け道ではなく、制御された資源
+
+という点です。
+
+## 最小実装の進め方
+
+### Step 1: continue site を明示する
+
+初心者の loop はよくこうなります。
+
+```python
+continue
+```
+
+教材版は一歩進めます。
+
+```python
+state["transition"] = "tool_result_continuation"
+continue
+```
+
+### Step 2: continuation と state patch を対にする
+
+```python
+if response.stop_reason == "tool_use":
+    state["messages"] = append_tool_results(...)
+    state["turn_count"] += 1
+    state["transition"] = "tool_result_continuation"
+    continue
+
+if response.stop_reason == "max_tokens":
+    state["messages"].append({
+        "role": "user",
+        "content": CONTINUE_MESSAGE,
+    })
+    state["max_output_tokens_recovery_count"] += 1
+    state["transition"] = "max_tokens_recovery"
+    continue
+```
+
+大事なのは「1 行増えた」ことではありません。
+
+大事なのは:
+
+> 続行する前に、理由と state mutation を必ず知っている
+
+ことです。
+
+### Step 3: 通常継続と recovery 継続を分ける
+
+```python
+if should_retry_transport(error):
+    time.sleep(backoff(...))
+    state["transition"] = "transport_retry"
+    continue
+
+if should_recompact(error):
+    state["messages"] = compact_messages(state["messages"])
+    state["transition"] = "compact_retry"
+    continue
+```
+
+ここまで来ると `continue` は曖昧な動作ではなく、型付きの control transition になります。
+
+## 何を test すべきか
+
+教材 repo では少なくとも次を test しやすくしておくべきです。
+
+- tool result が `tool_result_continuation` を書く
+- truncated output が `max_tokens_recovery` を書く
+- compact retry が古い reason を黙って使い回さない
+- transport retry が通常 turn に見えない
+
+これが test しづらいなら、まだ model が暗黙的すぎます。
+
+## 何を教えすぎないか
+
+vendor 固有の transport detail や細かすぎる enum を全部教える必要はありません。
+
+教材 repo で本当に必要なのは次です。
+
+> 1 本の query は明示された transition の連鎖であり、
+> 各 transition は reason・state patch・budget rule を持つ
+
+ここが分かれば、開発者は高完成度 agent を 0 から組み直せます。
diff --git a/docs/ja/s00d-chapter-order-rationale.md b/docs/ja/s00d-chapter-order-rationale.md
new file mode 100644
index 000000000..51c727156
--- /dev/null
+++ b/docs/ja/s00d-chapter-order-rationale.md
@@ -0,0 +1,325 @@
+# s00d: Chapter Order Rationale
+
+> この資料は 1 つの仕組みを説明するためのものではありません。  
+> もっと基礎的な問いに答えるための資料です:
+>
+> **なぜこの教材は今の順序で教えるのか。なぜ source file の並びや機能の派手さ、実装難度の順ではないのか。**
+
+## 先に結論
+
+現在の `s01 -> s19` の順序は妥当です。
+
+この順序の価値は、単に章数が多いことではなく、学習者が理解すべき依存順でシステムを育てていることです。
+
+1. 最小の agent loop を作る
+2. その loop の周囲に control plane と hardening を足す
+3. session 内 planning を durable work と runtime state へ広げる
+4. その後で teammate、isolation lane、external capability へ広げる
+
+つまりこの教材は:
+
+**mechanism の依存順**
+
+で構成されています。
+
+## 4 本の依存線
+
+この教材は大きく 4 本の依存線で並んでいます。
+
+1. `core loop dependency`
+2. `control-plane dependency`
+3. `work-state dependency`
+4. `platform-boundary dependency`
+
+雑に言うと:
+
+```text
+まず agent を動かす
+  -> 次に安全に動かす
+  -> 次に長く動かす
+  -> 最後に platform として動かす
+```
+
+これが今の順序の核心です。
+
+## 全体の並び
+
+```text
+s01-s06
+  単一 agent の最小主線を作る
+
+s07-s11
+  control plane と hardening を足す
+
+s12-s14
+  durable work と runtime を作る
+
+s15-s19
+  teammate・protocol・autonomy・worktree・external capability を足す
+```
+
+各段の終わりで、学習者は次のように言えるべきです。
+
+- `s06` の後: 「動く単一 agent harness を自力で作れる」
+- `s11` の後: 「それをより安全に、安定して、拡張しやすくできる」
+- `s14` の後: 「durable task、background runtime、time trigger を整理して説明できる」
+- `s19` の後: 「高完成度 agent platform の外周境界が見えている」
+
+## なぜ前半は今の順序で固定すべきか
+
+### `s01` は必ず最初
+
+ここで定義されるのは:
+
+- 最小の入口
+- turn ごとの進み方
+- tool result がなぜ次の model call に戻るのか
+
+これがないと、後ろの章はすべて空中に浮いた feature 説明になります。
+
+### `s02` は `s01` の直後でよい
+
+tool がない agent は、まだ「話しているだけ」で「作業している」状態ではありません。
+
+`s02` で初めて:
+
+- model が `tool_use` を出す
+- system が handler を選ぶ
+- tool が実行される
+- `tool_result` が loop に戻る
+
+という、harness の実在感が出ます。
+
+### `s03` は `s04` より前であるべき
+
+教育上ここは重要です。
+
+先に教えるべきなのは:
+
+- 現在の agent が自分の仕事をどう整理するか
+
+その後に教えるべきなのが:
+
+- どの仕事を subagent へ切り出すべきか
+
+`s04` を早くしすぎると、subagent が isolation mechanism ではなく逃げ道に見えてしまいます。
+
+### `s05` は `s06` の前で正しい
+
+この 2 章は同じ問題の前半と後半です。
+
+- `s05`: そもそも不要な知識を context へ入れすぎない
+- `s06`: それでも残る context をどう compact するか
+
+先に膨張を減らし、その後で必要なものだけ compact する。  
+この順序はとても自然です。
+
+## なぜ `s07-s11` は 1 つの hardening block なのか
+
+この 5 章は別々に見えて、実は同じ問いに答えています:
+
+**loop はもう動く。では、それをどう安定した本当の system にするか。**
+
+### `s07` は `s08` より前で正しい
+
+先に必要なのは:
+
+- その action を実行してよいか
+- deny するか
+- user に ask するか
+
+という gate の考え方です。
+
+その後で:
+
+- loop の周囲に何を hook するか
+
+を教える方が自然です。
+
+つまり:
+
+**gate が先、extend が後**
+
+です。
+
+### `s09` は `s10` より前で正しい
+
+`s09` は:
+
+- durable information が何か
+- 何を long-term に残すべきか
+
+を教えます。
+
+`s10` は:
+
+- 複数の入力源をどう model input に組み立てるか
+
+を教えます。
+
+つまり:
+
+- memory は content source を定義する
+- prompt assembly は source たちの組み立て順を定義する
+
+逆にすると、prompt pipeline が不自然で謎の文字列操作に見えやすくなります。
+
+### `s11` はこの block の締めとして適切
+
+error recovery は独立した機能ではありません。
+
+ここで system は初めて:
+
+- なぜ continue するのか
+- なぜ retry するのか
+- なぜ stop するのか
+
+を明示する必要があります。
+
+そのためには、input path、tool path、state path、control path が先に見えている必要があります。
+
+## なぜ `s12-s14` は goal -> runtime -> schedule の順なのか
+
+ここは順番を崩すと一気に混乱します。
+
+### `s12` は `s13` より先
+
+`s12` は:
+
+- 仕事そのものが何か
+- dependency がどう張られるか
+- downstream work がいつ unlock されるか
+
+を教えます。
+
+`s13` は:
+
+- 今まさに何が live execution として動いているか
+- background result がどこへ戻るか
+- runtime state がどう write-back されるか
+
+を教えます。
+
+つまり:
+
+- `task` は durable goal
+- `runtime task` は live execution slot
+
+です。
+
+ここを逆にすると、この 2 つが一語の task に潰れてしまいます。
+
+### `s14` は `s13` の後であるべき
+
+cron は別種の task を増やす章ではありません。
+
+追加するのは:
+
+**time という start condition**
+
+です。
+
+だから自然な順序は:
+
+`durable task graph -> runtime slot -> schedule trigger`
+
+になります。
+
+## なぜ `s15-s19` は team -> protocol -> autonomy -> worktree -> capability bus なのか
+
+### `s15` で system 内に誰が持続するかを定義する
+
+protocol や autonomy より前に必要なのは durable actor です。
+
+- teammate は誰か
+- どんな identity を持つか
+- どう持続するか
+
+### `s16` で actor 間の coordination rule を定義する
+
+protocol は actor より先には来ません。
+
+protocol は次を構造化するために存在します。
+
+- 誰が request するか
+- 誰が approve するか
+- 誰が respond するか
+- どう trace するか
+
+### `s17` はその後で初めて明確になる
+
+autonomy は曖昧に説明しやすい概念です。
+
+しかし本当に必要なのは:
+
+- persistent teammate がすでに存在する
+- structured coordination がすでに存在する
+
+という前提です。
+
+そうでないと autonomous claim は魔法っぽく見えてしまいます。
+
+### `s18` は `s19` より前がよい
+
+worktree isolation は local execution boundary の問題です。
+
+- 並列作業がどこで走るか
+- lane 同士をどう隔離するか
+
+これを先に見せてから:
+
+- plugin
+- MCP server
+- external capability route
+
+へ進む方が、自作実装の足場が崩れません。
+
+### `s19` は最後で正しい
+
+ここは platform の最外周です。
+
+local の:
+
+- actor
+- lane
+- durable task
+- runtime execution
+
+が見えた後で、ようやく:
+
+- external capability provider
+
+がきれいに入ってきます。
+
+## コースを悪くする 5 つの誤った並べ替え
+
+1. `s04` を `s03` より前に動かす  
+   local planning より先に delegation を教えてしまう。
+
+2. `s10` を `s09` より前に動かす  
+   input source の理解なしに prompt assembly を教えることになる。
+
+3. `s13` を `s12` より前に動かす  
+   durable goal と live runtime slot が混ざる。
+
+4. `s17` を `s15` や `s16` より前に動かす  
+   autonomy が曖昧な polling magic に見える。
+
+5. `s19` を `s18` より前に動かす  
+   local platform boundary より external capability が目立ってしまう。
+
+## Maintainer が順序変更前に確認すべきこと
+
+章を動かす前に次を確認するとよいです。
+
+1. 前提概念はすでに前で説明されているか
+2. この変更で別の層の概念同士が混ざらないか
+3. この章が主に追加するのは goal か、runtime state か、actor か、capability boundary か
+4. これを早めても、学習者は最小正解版をまだ自力で作れるか
+5. これは開発者理解のための変更か、それとも source file の順を真似ているだけか
+
+5 番目が後者なら、たいてい変更しない方がよいです。
+
+## 一文で残すなら
+
+**良い章順とは、mechanism の一覧ではなく、各章が前章から自然に伸びた次の層として見える並びです。**
diff --git a/docs/ja/s00e-reference-module-map.md b/docs/ja/s00e-reference-module-map.md
new file mode 100644
index 000000000..1da5d6f70
--- /dev/null
+++ b/docs/ja/s00e-reference-module-map.md
@@ -0,0 +1,213 @@
+# s00e: 参照リポジトリのモジュール対応表
+
+> これは保守者と本気で学ぶ読者向けの校正文書です。  
+> 逆向きソースを逐行で読ませるための資料ではありません。
+>
+> ここで答えたいのは、次の一点です。
+>
+> **参照リポジトリの高信号なモジュール群と現在の教材の章順を突き合わせると、今のカリキュラム順は本当に妥当なのか。**
+
+## 結論
+
+妥当です。
+
+現在の `s01 -> s19` の順序は大筋で正しく、単純に「ソースツリーの並び順」に合わせるより、実際の設計主幹に近いです。
+
+理由は単純です。
+
+- 参照リポジトリには表層のディレクトリがたくさんある
+- しかし本当に設計の重みを持つのは、制御・状態・タスク・チーム・worktree・外部 capability に関する一部のクラスタ
+- それらは現在の 4 段階の教材構成ときれいに対応している
+
+したがって、すべきことは「教材をソース木順へ潰す」ことではありません。
+
+すべきことは:
+
+- 今の依存関係ベースの順序を維持する
+- 参照リポジトリとの対応を明文化する
+- 主線に不要な製品周辺の細部を入れ過ぎない
+
+## この比較で見た高信号クラスタ
+
+主に次のようなモジュール群を見ています。
+
+- `Tool.ts`
+- `state/AppStateStore.ts`
+- `coordinator/coordinatorMode.ts`
+- `memdir/*`
+- `services/SessionMemory/*`
+- `services/toolUseSummary/*`
+- `constants/prompts.ts`
+- `tasks/*`
+- `tools/TodoWriteTool/*`
+- `tools/AgentTool/*`
+- `tools/ScheduleCronTool/*`
+- `tools/EnterWorktreeTool/*`
+- `tools/ExitWorktreeTool/*`
+- `tools/MCPTool/*`
+- `services/mcp/*`
+- `plugins/*`
+- `hooks/toolPermission/*`
+
+これだけで、設計主脈絡の整合性は十分に判断できます。
+
+## 対応関係
+
+| 参照リポジトリのクラスタ | 典型例 | 対応する教材章 | この配置が妥当な理由 |
+|---|---|---|---|
+| Query ループと制御状態 | `Tool.ts`、`AppStateStore.ts`、query / coordinator 状態 | `s00`、`s00a`、`s00b`、`s01`、`s11` | 実システムは `messages[] + while True` だけではない。教材が最小ループから始め、後で control plane を補う流れは正しい。 |
+| Tool routing と実行面 | `Tool.ts`、native tools、tool context、実行 helper | `s02`、`s02a`、`s02b` | 参照実装は tools を共有 execution plane として扱っている。教材の分け方は妥当。 |
+| セッション計画 | `TodoWriteTool` | `s03` | セッション内の進行整理は小さいが重要な層で、持続タスクより先に学ぶべき。 |
+| 一回きりの委譲 | `AgentTool` の最小部分 | `s04` | 参照実装の agent machinery は大きいが、教材がまず「新しい文脈 + サブタスク + 要約返却」を教えるのは正しい。 |
+| Skill の発見と読み込み | `DiscoverSkillsTool`、`skills/*`、関連 prompt | `s05` | skills は飾りではなく知識注入層なので、prompt の複雑化より前に置くのが自然。 |
+| Context 圧縮と collapse | `services/toolUseSummary/*`、`services/contextCollapse/*` | `s06` | 参照実装に明示的な compact 層がある以上、これを早めに学ぶ構成は正しい。 |
+| Permission gate | `types/permissions.ts`、`hooks/toolPermission/*` | `s07` | 実行可否は独立した gate であり、単なる hook ではない。 |
+| Hooks と周辺拡張 | `types/hooks.ts`、hook runner | `s08` | 参照実装でも gate と extend は分かれている。順序は現状のままでよい。 |
+| Durable memory | `memdir/*`、`services/SessionMemory/*` | `s09` | memory は「何でも残すノート」ではなく、選択的な跨セッション層として扱われている。 |
+| Prompt 組み立て | `constants/prompts.ts`、prompt sections | `s10`、`s10a` | 入力は複数 source の合成物であり、教材が pipeline として説明するのは正しい。 |
+| Recovery / continuation | query transition、retry、compact retry、token recovery | `s11`、`s00c` | 続行理由は実システムで明示的に存在するため、前段の層を理解した後に学ぶのが自然。 |
+| Durable work graph | task record、dependency unlock | `s12` | 会話内の plan と durable work graph を分けている点が妥当。 |
+| Live runtime task | `tasks/types.ts`、`LocalShellTask`、`LocalAgentTask`、`RemoteAgentTask` | `s13`、`s13a` | 参照実装の runtime task union は、`TaskRecord` と `RuntimeTaskState` を分けるべき強い根拠になる。 |
+| Scheduled trigger | `ScheduleCronTool/*`、`useScheduledTasks` | `s14` | scheduling は runtime work の上に乗る開始条件なので、この順序でよい。 |
+| Persistent teammate | `InProcessTeammateTask`、team tools、agent registry | `s15` | 一回限りの subagent から durable actor へ広がる流れが参照実装にある。 |
+| Structured protocol | send-message、request tracking、coordinator mode | `s16` | protocol は actor が先に存在して初めて意味を持つ。 |
+| Autonomous claim / resume | task claiming、async worker lifecycle、resume logic | `s17` | autonomy は actor と task と protocol の上に成り立つ。 |
+| Worktree lane | `EnterWorktreeTool`、`ExitWorktreeTool`、worktree helper | `s18` | worktree は単なる git 小技ではなく、実行レーンと closeout 状態の仕組み。 |
+| External capability bus | `MCPTool`、`services/mcp/*`、`plugins/*` | `s19`、`s19a` | 参照実装でも MCP / plugin は外側の platform boundary にある。最後に置くのが正しい。 |
+
+## 特に強く裏付けられた 5 点
+
+### 1. `s03` は `s12` より前でよい
+
+参照実装には:
+
+- セッション内の小さな計画
+- 持続する task / runtime machinery
+
+の両方があります。
+
+これは同じものではありません。
+
+### 2. `s09` は `s10` より前でよい
+
+prompt assembly は memory を含む複数 source を組み立てます。
+
+したがって:
+
+- 先に memory という source を理解する
+- その後で prompt pipeline を理解する
+
+の順が自然です。
+
+### 3. `s12` は `s13` より前でなければならない
+
+`tasks/types.ts` に見える runtime task union は非常に重要です。
+
+これは:
+
+- durable な仕事目標
+- 今まさに動いている実行スロット
+
+が別物であることをはっきり示しています。
+
+### 4. `s15 -> s16 -> s17` の順は妥当
+
+参照実装でも:
+
+- actor
+- protocol
+- autonomy
+
+の順で積み上がっています。
+
+### 5. `s18` は `s19` より前でよい
+
+worktree はまずローカルな実行境界として理解されるべきです。
+
+そのあとで:
+
+- plugin
+- MCP server
+- 外部 capability provider
+
+へ広げる方が、心智がねじれません。
+
+## 教材主線に入れ過ぎない方がよいもの
+
+参照リポジトリに実在していても、主線へ入れ過ぎるべきではないものがあります。
+
+- CLI command 面の広がり
+- UI rendering の細部
+- telemetry / analytics 分岐
+- remote / enterprise の配線
+- compatibility layer
+- ファイル名や行番号レベルの trivia
+
+これらは本番では意味があります。
+
+ただし 0 から 1 の教材主線の中心ではありません。
+
+## 教材側が特に注意すべき点
+
+### 1. Subagent と Teammate を混ぜない
+
+参照実装の `AgentTool` は:
+
+- 一回きりの委譲
+- background worker
+- persistent teammate
+- worktree-isolated worker
+
+をまたいでいます。
+
+だからこそ教材では:
+
+- `s04`
+- `s15`
+- `s17`
+- `s18`
+
+に分けて段階的に教える方がよいです。
+
+### 2. Worktree を「git の小技」へ縮めない
+
+参照実装には keep / remove、resume、cleanup、dirty check があります。
+
+`s18` は今後も:
+
+- lane identity
+- task binding
+- closeout
+- cleanup
+
+を教える章として保つべきです。
+
+### 3. MCP を「外部 tool 一覧」へ縮めない
+
+参照実装には tools 以外にも:
+
+- resources
+- prompts
+- elicitation / connection state
+- plugin mediation
+
+があります。
+
+したがって `s19` は tools-first で入ってよいですが、capability bus という外側の境界も説明すべきです。
+
+## 最終判断
+
+参照リポジトリの高信号クラスタと照らす限り、現在の章順は妥当です。
+
+今後の大きな加点ポイントは、さらに大規模な並べ替えではなく:
+
+- bridge docs の充実
+- エンティティ境界の明確化
+- 多言語の整合
+- web 側での学習導線の明快さ
+
+にあります。
+
+## 一文で覚える
+
+**よい教材順は、ファイルが並んでいる順ではなく、学習者が依存関係に沿って実装を再構成できる順です。**
diff --git a/docs/ja/s00f-code-reading-order.md b/docs/ja/s00f-code-reading-order.md
new file mode 100644
index 000000000..b4a80e1a2
--- /dev/null
+++ b/docs/ja/s00f-code-reading-order.md
@@ -0,0 +1,142 @@
+# s00f: このリポジトリのコード読解順
+
+> このページは「もっと多くコードを読め」という話ではありません。  
+> もっと狭い問題を解決します。
+>
+> **章順が安定したあと、このリポジトリのコードをどんな順で読めば心智モデルを崩さずに理解できるのか。**
+
+## 先に結論
+
+次の読み方は避けます。
+
+- いちばん長いファイルから読む
+- いちばん高度そうな章へ飛ぶ
+- 先に `web/` を開いて主線を逆算する
+- `agents/*.py` 全体を 1 つの平坦なソース群として眺める
+
+安定したルールは 1 つです。
+
+**コードもカリキュラムと同じ順番で読む。**
+
+各章ファイルの中では、毎回同じ順で読みます。
+
+1. 状態構造
+2. tool 定義や registry
+3. 1 ターンを進める関数
+4. CLI 入口は最後
+
+## なぜこのページが必要か
+
+読者が詰まるのは文章だけではありません。実際にコードを開いた瞬間に、間違った場所から読み始めてまた混ざることが多いからです。
+
+## どの agent ファイルでも同じテンプレートで読む
+
+### 1. まずファイル先頭
+
+最初に答えること:
+
+- この章は何を教えているか
+- まだ何を故意に教えていないか
+
+### 2. 状態構造や manager class
+
+優先して探すもの:
+
+- `LoopState`
+- `PlanningState`
+- `CompactState`
+- `TaskManager`
+- `BackgroundManager`
+- `TeammateManager`
+- `WorktreeManager`
+
+### 3. tool 一覧や registry
+
+優先して見る入口:
+
+- `TOOLS`
+- `TOOL_HANDLERS`
+- `build_tool_pool()`
+- 主要な `run_*`
+
+### 4. ターンを進める関数
+
+たとえば:
+
+- `run_one_turn(...)`
+- `agent_loop(...)`
+- 章固有の `handle_*`
+
+### 5. CLI 入口は最後
+
+`if __name__ == "__main__"` は大事ですが、最初に見る場所ではありません。
+
+## Stage 1: `s01-s06`
+
+この段階は single-agent の背骨です。
+
+| 章 | ファイル | 先に見るもの | 次に見るもの | 次へ進む前に確認すること |
+|---|---|---|---|---|
+| `s01` | `agents/s01_agent_loop.py` | `LoopState` | `TOOLS` -> `run_one_turn()` -> `agent_loop()` | `messages -> model -> tool_result -> next turn` を追える |
+| `s02` | `agents/s02_tool_use.py` | `safe_path()` | handler 群 -> `TOOL_HANDLERS` -> `agent_loop()` | ループを変えずに tool が増える形が分かる |
+| `s03` | `agents/s03_todo_write.py` | planning state | todo 更新経路 -> `agent_loop()` | 会話内 plan の外化が分かる |
+| `s04` | `agents/s04_subagent.py` | `AgentTemplate` | `run_subagent()` -> 親 `agent_loop()` | 文脈隔離としての subagent が分かる |
+| `s05` | `agents/s05_skill_loading.py` | skill registry | registry 周り -> `agent_loop()` | discover light / load deep が分かる |
+| `s06` | `agents/s06_context_compact.py` | `CompactState` | compact 周辺 -> `agent_loop()` | compact の本質が分かる |
+
+### Stage 1 の Deep Agents トラック
+
+手書き版の `agents/s01-s06` を読んだ後で、`agents_deepagents/s01_agent_loop.py` から `agents_deepagents/s11_error_recovery.py` を Deep Agents トラックとして読めます。既存の `agents/*.py` は変更せず、OpenAI 形式の `OPENAI_API_KEY` / `OPENAI_MODEL`（必要なら `OPENAI_BASE_URL`）を使いながら、能力は章ごとに段階的に開放されます。つまり `s01` は最小 loop のまま、`s03` で planning、`s04` で subagent、`s05` で skills、`s06` で context compact が入ります。現時点では web UI には表示しません。
+
+## Stage 2: `s07-s11`
+
+### Stage 2 の Deep Agents トラック
+
+続けて `agents_deepagents/s07_permission_system.py` から `agents_deepagents/s11_error_recovery.py` を読みます。この段階では元の章順を保ったまま、permissions・hooks・memory・prompt・error recovery を同じ Deep Agents 段階トラックへ戻します。
+
+ここは control plane を固める段階です。
+
+| 章 | ファイル | 先に見るもの | 次に見るもの | 次へ進む前に確認すること |
+|---|---|---|---|---|
+| `s07` | `agents/s07_permission_system.py` | validator / manager | permission path -> `agent_loop()` | gate before execute |
+| `s08` | `agents/s08_hook_system.py` | `HookManager` | hook dispatch -> `agent_loop()` | 固定拡張点としての hook |
+| `s09` | `agents/s09_memory_system.py` | memory manager | save / prompt build -> `agent_loop()` | 長期情報層としての memory |
+| `s10` | `agents/s10_system_prompt.py` | `SystemPromptBuilder` | input build -> `agent_loop()` | pipeline としての prompt |
+| `s11` | `agents/s11_error_recovery.py` | compact / backoff helper | recovery 分岐 -> `agent_loop()` | 失敗後の続行 |
+
+## Stage 3: `s12-s14`
+
+ここから harness は work runtime へ広がります。
+
+| 章 | ファイル | 先に見るもの | 次に見るもの | 次へ進む前に確認すること |
+|---|---|---|---|---|
+| `s12` | `agents/s12_task_system.py` | `TaskManager` | task create / unlock -> `agent_loop()` | durable goal |
+| `s13` | `agents/s13_background_tasks.py` | `NotificationQueue` / `BackgroundManager` | background registration -> `agent_loop()` | runtime slot |
+| `s14` | `agents/s14_cron_scheduler.py` | `CronLock` / `CronScheduler` | trigger path -> `agent_loop()` | 未来の開始条件 |
+
+## Stage 4: `s15-s19`
+
+ここは platform 境界を作る段階です。
+
+| 章 | ファイル | 先に見るもの | 次に見るもの | 次へ進む前に確認すること |
+|---|---|---|---|---|
+| `s15` | `agents/s15_agent_teams.py` | `MessageBus` / `TeammateManager` | roster / inbox / loop -> `agent_loop()` | persistent teammate |
+| `s16` | `agents/s16_team_protocols.py` | `RequestStore` | request handler -> `agent_loop()` | request-response + `request_id` |
+| `s17` | `agents/s17_autonomous_agents.py` | claim helper / identity helper | claim -> resume -> `agent_loop()` | idle check -> safe claim -> resume |
+| `s18` | `agents/s18_worktree_task_isolation.py` | manager 群 | worktree lifecycle -> `agent_loop()` | goal と execution lane の分離 |
+| `s19` | `agents/s19_mcp_plugin.py` | capability 周辺 class | route / normalize -> `agent_loop()` | external capability が同じ control plane に戻ること |
+
+## 最良の「文書 + コード」学習ループ
+
+各章で次を繰り返します。
+
+1. 章本文を読む
+2. bridge doc を読む
+3. 対応する `agents/sXX_*.py` を開く
+4. 状態 -> tools -> turn driver -> CLI 入口 の順で読む
+5. demo を 1 回動かす
+6. 最小版を自分で書き直す
+
+## 一言で言うと
+
+**コード読解順も教学順に従うべきです。まず境界、その次に状態、最後に主ループをどう進めるかを見ます。**
diff --git a/docs/ja/s01-the-agent-loop.md b/docs/ja/s01-the-agent-loop.md
index ddb54b973..ef7a3fe93 100644
--- a/docs/ja/s01-the-agent-loop.md
+++ b/docs/ja/s01-the-agent-loop.md
@@ -1,56 +1,229 @@
 # s01: The Agent Loop
 
-`[ s01 ] s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
+`s00 > [ s01 ] > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
 
-> *"One loop & Bash is all you need"* -- 1つのツール + 1つのループ = エージェント。
->
-> **Harness 層**: ループ -- モデルと現実世界を繋ぐ最初の接点。
+> *loop がなければ agent は生まれません。*  
+> この章では、最小だけれど正しい loop を先に作り、そのあとで「なぜ後ろの章で control plane が必要になるのか」を理解できる土台を作ります。
 
-## 問題
+## この章が解く問題
 
-言語モデルはコードについて推論できるが、現実世界に触れられない。ファイルを読めず、テストを実行できず、エラーを確認できない。ループがなければ、ツール呼び出しのたびにユーザーが手動で結果をコピーペーストする必要がある。つまりユーザー自身がループになる。
+言語 model 自体は「次にどんな文字列を出すか」を予測する存在です。
 
-## 解決策
+それだけでは自分で次のことはできません。
 
+- file を開く
+- command を実行する
+- error を観察する
+- その観察結果を次の判断へつなぐ
+
+もし system 側に次の流れを繰り返す code がなければ、
+
+```text
+model に聞く
+  ->
+tool を使いたいと言う
+  ->
+本当に実行する
+  ->
+結果を model へ戻す
+  ->
+次の一手を考えさせる
+```
+
+model は「会話できる program」に留まり、「仕事を進める agent」にはなりません。
+
+だからこの章の目標は 1 つです。
+
+**model と tool を閉ループに接続し、仕事を継続的に前へ進める最小 agent を作ること**
+
+です。
+
+## 先に言葉をそろえる
+
+### loop とは何か
+
+ここでの `loop` は「無意味な無限ループ」ではありません。
+
+意味は、
+
+> 仕事がまだ終わっていない限り、同じ処理手順を繰り返す主循環
+
+です。
+
+### turn とは何か
+
+`turn` は 1 ラウンドです。
+
+最小版では 1 turn にだいたい次が入ります。
+
+1. 現在の messages を model に送る
+2. model response を受け取る
+3. tool_use があれば tool を実行する
+4. tool_result を messages に戻す
+
+そのあとで次の turn へ進むか、終了するかが決まります。
+
+### tool_result とは何か
+
+`tool_result` は terminal 上の一時ログではありません。
+
+正しくは、
+
+> model が次の turn で読めるよう、message history へ書き戻される結果 block
+
+です。
+
+### state とは何か
+
+`state` は、その loop が前へ進むために持ち続ける情報です。
+
+この章の最小 state は次です。
+
+- `messages`
+- `turn_count`
+- 次 turn に続く理由
+
+## 最小心智モデル
+
+まず agent 全体を次の回路として見てください。
+
+```text
+user message
+   |
+   v
+LLM
+   |
+   +-- 普通の返答 ----------> 終了
+   |
+   +-- tool_use ----------> tool 実行
+                              |
+                              v
+                         tool_result
+                              |
+                              v
+                         messages へ write-back
+                              |
+                              v
+                         次の turn
+```
+
+この図の中で一番重要なのは `while True` という文法ではありません。
+
+最も重要なのは次の 1 文です。
+
+**tool の結果は message history に戻され、次の推論入力になる**
+
+ここが欠けると、model は現実の観察を踏まえて次の一手を考えられません。
+
+## この章の核になるデータ構造
+
+### 1. Message
+
+最小教材版では、message はまず次の形で十分です。
+
+```python
+{"role": "user", "content": "..."}
+{"role": "assistant", "content": [...]}
+```
+
+ここで忘れてはいけないのは、
+
+**message history は UI 表示用の chat transcript ではなく、次 turn の作業 context**
+
+だということです。
+
+### 2. Tool Result Block
+
+tool 実行後は、その出力を対応する block として messages へ戻します。
+
+```python
+{
+    "type": "tool_result",
+    "tool_use_id": "...",
+    "content": "...",
+}
+```
+
+`tool_use_id` は単純に、
+
+> どの tool 呼び出しに対応する結果か
+
+を model に示すための ID です。
+
+### 3. LoopState
+
+この章では散らばった local variable だけで済ませるより、
+
+> loop が持つ state を 1 か所へ寄せて見る
+
+癖を作る方が後で効きます。
+
+最小形は次で十分です。
+
+```python
+state = {
+    "messages": [...],
+    "turn_count": 1,
+    "transition_reason": None,
+}
 ```
-+--------+      +-------+      +---------+
-|  User  | ---> |  LLM  | ---> |  Tool   |
-| prompt |      |       |      | execute |
-+--------+      +---+---+      +----+----+
-                    ^                |
-                    |   tool_result  |
-                    +----------------+
-                    (loop until stop_reason != "tool_use")
+
+ここでの `transition_reason` はまず、
+
+> なぜこの turn のあとにさらに続くのか
+
+を示す field とだけ理解してください。
+
+この章の最小版では、理由は 1 種類でも十分です。
+
+```python
+"tool_result"
 ```
 
-1つの終了条件がフロー全体を制御する。モデルがツール呼び出しを止めるまでループが回り続ける。
+つまり、
+
+> tool を実行したので、その結果を踏まえてもう一度 model を呼ぶ
+
+という continuation です。
+
+## 最小実装を段階で追う
 
-## 仕組み
+### 第 1 段階: 初期 message を作る
 
-1. ユーザーのプロンプトが最初のメッセージになる。
+まず user request を history に入れます。
 
 ```python
-messages.append({"role": "user", "content": query})
+messages = [{"role": "user", "content": query}]
 ```
 
-2. メッセージとツール定義をLLMに送信する。
+### 第 2 段階: model を呼ぶ
+
+messages、system prompt、tools をまとめて model に送ります。
 
 ```python
 response = client.messages.create(
-    model=MODEL, system=SYSTEM, messages=messages,
-    tools=TOOLS, max_tokens=8000,
+    model=MODEL,
+    system=SYSTEM,
+    messages=messages,
+    tools=TOOLS,
+    max_tokens=8000,
 )
 ```
 
-3. アシスタントのレスポンスを追加し、`stop_reason`を確認する。ツールが呼ばれなければ終了。
+### 第 3 段階: assistant response 自体も history へ戻す
 
 ```python
-messages.append({"role": "assistant", "content": response.content})
-if response.stop_reason != "tool_use":
-    return
+messages.append({
+    "role": "assistant",
+    "content": response.content,
+})
 ```
 
-4. 各ツール呼び出しを実行し、結果を収集してuserメッセージとして追加。ステップ2に戻る。
+ここは初心者がとても落としやすい点です。
+
+「最終答えだけ取れればいい」と思って assistant response を保存しないと、次 turn の context が切れます。
+
+### 第 4 段階: tool_use があればจริง行する
 
 ```python
 results = []
@@ -62,55 +235,125 @@ for block in response.content:
             "tool_use_id": block.id,
             "content": output,
         })
-messages.append({"role": "user", "content": results})
 ```
 
-1つの関数にまとめると:
+この段階で初めて、model の意図が real execution へ落ちます。
+
+### 第 5 段階: tool_result を user-side message として write-back する
 
 ```python
-def agent_loop(query):
-    messages = [{"role": "user", "content": query}]
+messages.append({
+    "role": "user",
+    "content": results,
+})
+```
+
+これで次 turn の model は、
+
+- さっき自分が何を要求したか
+- その結果が何だったか
+
+を両方読めます。
+
+### 全体を 1 つの loop にまとめる
+
+```python
+def agent_loop(state):
     while True:
         response = client.messages.create(
-            model=MODEL, system=SYSTEM, messages=messages,
-            tools=TOOLS, max_tokens=8000,
+            model=MODEL,
+            system=SYSTEM,
+            messages=state["messages"],
+            tools=TOOLS,
+            max_tokens=8000,
         )
-        messages.append({"role": "assistant", "content": response.content})
+
+        state["messages"].append({
+            "role": "assistant",
+            "content": response.content,
+        })
 
         if response.stop_reason != "tool_use":
+            state["transition_reason"] = None
             return
 
         results = []
         for block in response.content:
             if block.type == "tool_use":
-                output = run_bash(block.input["command"])
+                output = run_tool(block)
                 results.append({
                     "type": "tool_result",
                     "tool_use_id": block.id,
                     "content": output,
                 })
-        messages.append({"role": "user", "content": results})
+
+        state["messages"].append({
+            "role": "user",
+            "content": results,
+        })
+        state["turn_count"] += 1
+        state["transition_reason"] = "tool_result"
 ```
 
-これでエージェント全体が30行未満に収まる。本コースの残りはすべてこのループの上に積み重なる -- ループ自体は変わらない。
+これがこの course 全体の核です。
 
-## 変更点
+後ろの章で何が増えても、
 
-| Component     | Before     | After                          |
-|---------------|------------|--------------------------------|
-| Agent loop    | (none)     | `while True` + stop_reason     |
-| Tools         | (none)     | `bash` (one tool)              |
-| Messages      | (none)     | Accumulating list              |
-| Control flow  | (none)     | `stop_reason != "tool_use"`    |
+**model を呼び、tool を実行し、result を戻して、必要なら続く**
 
-## 試してみる
+という骨格自体は残ります。
 
-```sh
-cd learn-claude-code
-python agents/s01_agent_loop.py
-```
+## この章でわざと単純化していること
+
+この章では最初から複雑な control plane を教えません。
+
+まだ出していないもの:
+
+- permission gate
+- hook
+- memory
+- prompt assembly pipeline
+- recovery branch
+- compact 後の continuation
+
+なぜなら初学者が最初に理解すべきなのは、
+
+**agent の最小閉ループ**
+
+だからです。
+
+もし最初から複数の continuation reason や recovery branch を混ぜると、
+読者は「loop そのもの」が見えなくなります。
+
+## 高完成度 system ではどう広がるか
+
+教材版は最も重要な骨格だけを教えます。
+
+高完成度 system では、その同じ loop の外側に次の層が足されます。
+
+| 観点 | この章の最小版 | 高完成度 system |
+|---|---|---|
+| loop 形状 | 単純な `while True` | event-driven / streaming continuation |
+| 継続理由 | `tool_result` が中心 | retry、compact resume、recovery など複数 |
+| tool execution | response 全体を見てから実行 | 並列実行や先行起動を含む runtime |
+| state | `messages` 中心 | turn、budget、transition、recovery を explicit に持つ |
+| error handling | ほぼなし | truncation、transport error、retry branch |
+| observability | 最小 | progress event、structured logs、UI stream |
+
+ここで覚えるべき本質は細かな branch 名ではありません。
+
+本質は次の 1 文です。
+
+**agent は最後まで「結果を model に戻し続ける loop」であり、周囲に state 管理と continuation の理由が増えていく**
+
+ということです。
+
+## この章を読み終えたら何が言えるべきか
+
+1. model だけでは agent にならず、tool result を戻す loop が必要
+2. assistant response 自体も history に残さないと次 turn が切れる
+3. tool_result は terminal log ではなく、次 turn の input block である
+
+## 一文で覚える
 
-1. `Create a file called hello.py that prints "Hello, World!"`
-2. `List all Python files in this directory`
-3. `What is the current git branch?`
-4. `Create a directory called test_output and write 3 files in it`
+**agent loop とは、model の要求を現実の観察へ変え、その観察をまた model に返し続ける主循環です。**
diff --git a/docs/ja/s02-tool-use.md b/docs/ja/s02-tool-use.md
index 3c41c1d5c..98bbc277a 100644
--- a/docs/ja/s02-tool-use.md
+++ b/docs/ja/s02-tool-use.md
@@ -1,6 +1,6 @@
 # s02: Tool Use
 
-`s01 > [ s02 ] s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
+`s01 > [ s02 ] > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
 
 > *"ツールを足すなら、ハンドラーを1つ足すだけ"* -- ループは変わらない。新ツールは dispatch map に登録するだけ。
 >
@@ -97,3 +97,30 @@ python agents/s02_tool_use.py
 2. `Create a file called greet.py with a greet(name) function`
 3. `Edit greet.py to add a docstring to the function`
 4. `Read greet.py to verify the edit worked`
+
+## 教学上の簡略化
+
+この章で本当に学ぶべきなのは、細かな production 差分ではありません。
+
+学ぶべき中心は次の 4 点です。
+
+1. モデルに見せる tool schema がある
+2. 実装側には handler がある
+3. 両者は dispatch map で結ばれる
+4. 実行結果は `tool_result` として主ループへ戻る
+
+より完成度の高い system では、この周りに権限、hook、並列実行、結果永続化、外部 capability routing などが増えていきます。
+
+しかし、それらをここで全部追い始めると、初学者は
+
+- schema と handler の違い
+- dispatch map の役割
+- `tool_result` がなぜ主ループへ戻るのか
+
+という本章の主眼を見失いやすくなります。
+
+この段階では、まず
+
+**新しい tool を足しても主ループ自体は作り替えなくてよい**
+
+という設計の強さを、自分で実装して理解できれば十分です。
diff --git a/docs/ja/s02a-tool-control-plane.md b/docs/ja/s02a-tool-control-plane.md
new file mode 100644
index 000000000..e4fe4fe3e
--- /dev/null
+++ b/docs/ja/s02a-tool-control-plane.md
@@ -0,0 +1,177 @@
+# s02a: Tool Control Plane
+
+> これは `s02` を深く理解するための橋渡し文書です。  
+> 問いたいのは:
+>
+> **なぜ tool system は単なる `tool_name -> handler` 表では足りないのか。**
+
+## 先に結論
+
+最小 demo では dispatch map だけでも動きます。
+
+しかし高完成度の system では tool layer は次の責任をまとめて持ちます。
+
+- tool schema をモデルへ見せる
+- tool 名から実行先を解決する
+- 実行前に permission を通す
+- hook / classifier / side check を差し込む
+- 実行中 progress を扱う
+- 結果を整形して loop へ戻す
+- 実行で変わる共有 state へアクセスする
+
+つまり tool layer は:
+
+**関数表ではなく、共有 execution plane**
+
+です。
+
+## 最小の心智モデル
+
+```text
+model emits tool_use
+  |
+  v
+tool spec lookup
+  |
+  v
+permission / hook / validation
+  |
+  v
+actual execution
+  |
+  v
+tool result shaping
+  |
+  v
+write-back to loop
+```
+
+## `dispatch map` だけでは足りない理由
+
+単なる map だと、せいぜい:
+
+- この名前ならこの関数
+
+しか表せません。
+
+でも実システムで必要なのは:
+
+- モデルへ何を見せるか
+- 実行前に何を確認するか
+- 実行中に何を表示するか
+- 実行後にどんな result block を返すか
+- どの shared context を触れるか
+
+です。
+
+## 主要なデータ構造
+
+### `ToolSpec`
+
+モデルに見せる tool の定義です。
+
+```python
+tool = {
+    "name": "read_file",
+    "description": "...",
+    "input_schema": {...},
+}
+```
+
+### `ToolDispatchMap`
+
+名前から handler を引く表です。
+
+```python
+dispatch = {
+    "read_file": run_read,
+    "bash": run_bash,
+}
+```
+
+これは必要ですが、これだけでは足りません。
+
+### `ToolUseContext`
+
+tool が共有状態へ触るための文脈です。
+
+たとえば:
+
+- app state getter / setter
+- permission context
+- notifications
+- file-state cache
+- current agent identity
+
+などが入ります。
+
+### `ToolResultEnvelope`
+
+loop へ返すときの整形済み result です。
+
+```python
+{
+    "type": "tool_result",
+    "tool_use_id": "...",
+    "content": "...",
+}
+```
+
+高完成度版では content だけでなく:
+
+- progress
+- warnings
+- structured result
+
+なども関わります。
+
+## 実行面として見ると何が変わるか
+
+### 1. Tool は「名前」ではなく「実行契約」になる
+
+1つの tool には:
+
+- 入力 schema
+- 実行権限
+- 実行時 context
+- 出力の形
+
+がひとまとまりで存在します。
+
+### 2. Permission と Hook の差が見えやすくなる
+
+- permission: 実行してよいか
+- hook: 実行の周辺で何を足すか
+
+### 3. Native / Task / Agent / MCP を同じ平面で見やすくなる
+
+参照実装でも重要なのは:
+
+**能力の出どころが違っても、loop から見れば 1 つの tool execution plane に入る**
+
+という点です。
+
+## 初学者がやりがちな誤り
+
+### 1. tool spec と handler を混同する
+
+- spec はモデル向け説明
+- handler は実行コード
+
+### 2. permission を handler の中へ埋め込む
+
+これをやると gate が共有層にならず、system が読みにくくなります。
+
+### 3. result shaping を軽く見る
+
+tool 実行結果は「文字列が返ればよい」ではありません。
+
+loop が読み戻しやすい形に整える必要があります。
+
+### 4. 実行状態を `messages[]` だけで持とうとする
+
+tool 実行は app state や runtime state を触ることがあります。
+
+## 一文で覚える
+
+**tool system が本物らしくなるのは、名前から関数を呼べた瞬間ではなく、schema・gate・context・result を含む共有 execution plane として見えた瞬間です。**
diff --git a/docs/ja/s02b-tool-execution-runtime.md b/docs/ja/s02b-tool-execution-runtime.md
new file mode 100644
index 000000000..b03320dbd
--- /dev/null
+++ b/docs/ja/s02b-tool-execution-runtime.md
@@ -0,0 +1,281 @@
+# s02b: Tool Execution Runtime
+
+> この bridge doc は tool の登録方法ではなく、次の問いを扱います。
+>
+> **model が複数の tool call を出したとき、何を基準に並列化し、進捗を出し、結果順を安定させ、context をマージするのか。**
+
+## なぜこの資料が必要か
+
+`s02` では正しく次を教えています。
+
+- tool schema
+- dispatch map
+- `tool_result` の main loop への回流
+
+出発点としては十分です。
+
+ただしシステムが大きくなると、本当に難しくなるのはもっと深い層です。
+
+- どの tool は並列実行できるか
+- どの tool は直列でなければならないか
+- 遅い tool は途中 progress を出すべきか
+- 並列結果を完了順で返すのか、元の順序で返すのか
+- tool 実行が共有 context を変更するのか
+- 並列変更をどう安全にマージするのか
+
+これらはもはや「登録」の話ではありません。
+
+それは:
+
+**tool execution runtime**
+
+の話です。
+
+## まず用語
+
+### tool execution runtime とは
+
+ここでの runtime は言語 runtime の意味ではありません。
+
+ここでは:
+
+> tool call が実際に動き始めた後、システムがそれらをどう調度し、追跡し、回写するか
+
+という実行規則のことです。
+
+### concurrency safe とは
+
+concurrency safe とは:
+
+> 同種の仕事と同時に走っても共有 state を壊しにくい
+
+という意味です。
+
+よくある read-only tool は安全なことが多いです。
+
+- `read_file`
+- いくつかの search tool
+- 読み取り専用の MCP tool
+
+一方で write 系は安全でないことが多いです。
+
+- `write_file`
+- `edit_file`
+- 共有 app state を変える tool
+
+### progress message とは
+
+progress message とは:
+
+> tool はまだ終わっていないが、「今何をしているか」を先に上流へ見せる更新
+
+のことです。
+
+### context modifier とは
+
+ある tool は text result だけでなく共有 runtime context も変更します。
+
+例えば:
+
+- notification queue を更新する
+- 実行中 tool の状態を更新する
+- app state を変更する
+
+この共有 state 変更を context modifier と考えられます。
+
+## 最小の心智モデル
+
+tool 実行を次のように平坦化しないでください。
+
+```text
+tool_use -> handler -> result
+```
+
+より実像に近い理解は次です。
+
+```text
+tool_use blocks
+  ->
+concurrency safety で partition
+  ->
+並列 lane か直列 lane を選ぶ
+  ->
+必要なら progress を吐く
+  ->
+安定順で結果を回写する
+  ->
+queued context modifiers をマージする
+```
+
+ここで大事なのは二つです。
+
+- 並列化は「全部まとめて走らせる」ではない
+- 共有 context は完了順で勝手に書き換えない
+
+## 主要 record
+
+### 1. `ToolExecutionBatch`
+
+教材版なら次の程度の batch 概念で十分です。
+
+```python
+batch = {
+    "is_concurrency_safe": True,
+    "blocks": [tool_use_1, tool_use_2, tool_use_3],
+}
+```
+
+意味は単純です。
+
+- tool を常に 1 個ずつ扱うわけではない
+- runtime はまず execution batch に分ける
+
+### 2. `TrackedTool`
+
+完成度を上げたいなら各 tool を明示的に追跡します。
+
+```python
+tracked_tool = {
+    "id": "toolu_01",
+    "name": "read_file",
+    "status": "queued",   # queued / executing / completed / yielded
+    "is_concurrency_safe": True,
+    "pending_progress": [],
+    "results": [],
+    "context_modifiers": [],
+}
+```
+
+これにより runtime は次に答えられます。
+
+- 何が待機中か
+- 何が実行中か
+- 何が完了したか
+- 何がすでに progress を出したか
+
+### 3. `MessageUpdate`
+
+tool 実行は最終結果 1 個だけを返すとは限りません。
+
+最小理解は次で十分です。
+
+```python
+update = {
+    "message": maybe_message,
+    "new_context": current_context,
+}
+```
+
+高完成度 runtime では、更新は通常二つに分かれます。
+
+- すぐ上流へ見せる message update
+- 後で merge すべき内部 context update
+
+### 4. queued context modifiers
+
+これは見落とされやすいですが、とても重要です。
+
+並列 batch で安全なのは:
+
+> 先に終わった tool がその順で共有 context を先に変える
+
+ことではありません。
+
+より安全なのは:
+
+> context modifier を一旦 queue し、最後に元の tool 順序で merge する
+
+ことです。
+
+```python
+queued_context_modifiers = {
+    "toolu_01": [modify_ctx_a],
+    "toolu_02": [modify_ctx_b],
+}
+```
+
+## 最小実装の進め方
+
+### Step 1: concurrency safety を判定する
+
+```python
+def is_concurrency_safe(tool_name: str, tool_input: dict) -> bool:
+    return tool_name in {"read_file", "search_files"}
+```
+
+### Step 2: 実行前に partition する
+
+```python
+batches = partition_tool_calls(tool_uses)
+
+for batch in batches:
+    if batch["is_concurrency_safe"]:
+        run_concurrently(batch["blocks"])
+    else:
+        run_serially(batch["blocks"])
+```
+
+### Step 3: 並列 lane では progress を先に出せるようにする
+
+```python
+for update in run_concurrently(...):
+    if update.get("message"):
+        yield update["message"]
+```
+
+### Step 4: context merge は安定順で行う
+
+```python
+queued_modifiers = {}
+
+for update in concurrent_updates:
+    if update.get("context_modifier"):
+        queued_modifiers[update["tool_id"]].append(update["context_modifier"])
+
+for tool in original_batch_order:
+    for modifier in queued_modifiers.get(tool["id"], []):
+        context = modifier(context)
+```
+
+ここは教材 repo でも簡略化しすぎず、しかし主線を崩さずに教えられる重要点です。
+
+## 開発者が持つべき図
+
+```text
+tool_use blocks
+  |
+  v
+partition by concurrency safety
+  |
+  +-- safe batch ----------> concurrent execution
+  |                            |
+  |                            +-- progress updates
+  |                            +-- final results
+  |                            +-- queued context modifiers
+  |
+  +-- exclusive batch -----> serial execution
+                               |
+                               +-- direct result
+                               +-- direct context update
+```
+
+## なぜ後半では dispatch map より重要になるのか
+
+小さい demo では:
+
+```python
+handlers[tool_name](tool_input)
+```
+
+で十分です。
+
+しかし高完成度 agent で本当に難しいのは、正しい handler を呼ぶことそのものではありません。
+
+難しいのは:
+
+- 複数 tool を安全に調度する
+- progress を見えるようにする
+- 結果順を安定させる
+- 共有 context を非決定的にしない
+
+だからこそ tool execution runtime は独立した bridge doc として教える価値があります。
diff --git a/docs/ja/s03-todo-write.md b/docs/ja/s03-todo-write.md
index 541d33c39..12350d127 100644
--- a/docs/ja/s03-todo-write.md
+++ b/docs/ja/s03-todo-write.md
@@ -1,96 +1,388 @@
 # s03: TodoWrite
 
-`s01 > s02 > [ s03 ] s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
+`s00 > s01 > s02 > [ s03 ] > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
 
-> *"計画のないエージェントは行き当たりばったり"* -- まずステップを書き出し、それから実行。
->
-> **Harness 層**: 計画 -- 航路を描かずにモデルを軌道に乗せる。
+> *planning は model の代わりに考えるためのものではありません。いま何をやっているかを、外から見える state にするためのものです。*
 
-## 問題
+## この章が解く問題
 
-マルチステップのタスクで、モデルは途中で迷子になる。作業を繰り返したり、ステップを飛ばしたり、脱線したりする。長い会話になるほど悪化する -- ツール結果がコンテキストを埋めるにつれ、システムプロンプトの影響力が薄れる。10ステップのリファクタリングでステップ1-3を完了した後、残りを忘れて即興を始めてしまう。
+`s02` まで来ると agent はすでに、
 
-## 解決策
+- file を読む
+- file を書く
+- command を実行する
 
+ことができます。
+
+するとすぐに別の問題が出ます。
+
+- multi-step task で一歩前の確認を忘れる
+- もう終えた確認をまた繰り返す
+- 最初は計画しても、数 turn 後には即興に戻る
+
+これは model が「考えられない」からではありません。
+
+問題は、
+
+**現在の plan を explicit に置いておく stable state がないこと**
+
+です。
+
+この章で足すのはより強い tool ではなく、
+
+**今の session で何をどの順で進めているかを外部状態として見えるようにする仕組み**
+
+です。
+
+## 先に言葉をそろえる
+
+### session 内 planning とは何か
+
+ここで扱う planning は long-term project management ではありません。
+
+意味は、
+
+> 今回の user request を終えるために、直近の数手を外へ書き出し、途中で更新し続けること
+
+です。
+
+### todo とは何か
+
+`todo` は特定 product の固有名詞として覚える必要はありません。
+
+この章では単に、
+
+> model が current plan を更新するための入口
+
+として使います。
+
+### active step とは何か
+
+`active step` は、
+
+> いま本当に進めている 1 手
+
+です。
+
+教材版では `in_progress` で表します。
+
+ここで狙っているのは形式美ではなく、
+
+**同時にあれもこれも進めて plan をぼかさないこと**
+
+です。
+
+### reminder とは何か
+
+reminder は model の代わりに plan を作るものではありません。
+
+意味は、
+
+> 数 turn 連続で plan 更新を忘れたときに、軽く plan へ意識を戻すナッジ
+
+です。
+
+## 最初に強調したい境界
+
+この章は task system ではありません。
+
+`s03` で扱うのは、
+
+- session 内の軽量な current plan
+- 進行中の focus を保つための外部状態
+- turn ごとに書き換わりうる planning panel
+
+です。
+
+ここでまだ扱わないもの:
+
+- durable task board
+- dependency graph
+- multi-agent 共有 task graph
+- background runtime task manager
+
+それらは `s12-s14` であらためて教えます。
+
+この境界を守らないと、初心者はすぐに次を混同します。
+
+- 今この session で次にやる一手
+- system 全体に長く残る work goal
+
+## 最小心智モデル
+
+この章を最も簡単に捉えるなら、plan はこういう panel です。
+
+```text
+user が大きな仕事を頼む
+  |
+  v
+model が今の plan を書き出す
+  |
+  v
+plan state
+  - [ ] まだ着手していない
+  - [>] いま進めている
+  - [x] 完了した
+  |
+  v
+1 手進むたびに更新する
 ```
-+--------+      +-------+      +---------+
-|  User  | ---> |  LLM  | ---> | Tools   |
-| prompt |      |       |      | + todo  |
-+--------+      +---+---+      +----+----+
-                    ^                |
-                    |   tool_result  |
-                    +----------------+
-                          |
-              +-----------+-----------+
-              | TodoManager state     |
-              | [ ] task A            |
-              | [>] task B  <- doing  |
-              | [x] task C            |
-              +-----------------------+
-                          |
-              if rounds_since_todo >= 3:
-                inject <reminder> into tool_result
+
+つまり流れはこうです。
+
+1. まず current work を数手に割る
+2. 1 つを `in_progress` にする
+3. 終わったら `completed` にする
+4. 次の 1 つを `in_progress` にする
+5. しばらく更新がなければ reminder する
+
+この 5 手が見えていれば、この章の幹はつかめています。
+
+## この章の核になるデータ構造
+
+### 1. PlanItem
+
+最小の item は次のように考えられます。
+
+```python
+{
+    "content": "Read the failing test",
+    "status": "pending" | "in_progress" | "completed",
+    "activeForm": "Reading the failing test",
+}
 ```
 
-## 仕組み
+意味は単純です。
+
+- `content`: 何をするか
+- `status`: いまどの段階か
+- `activeForm`: 実行中に自然文でどう見せるか
+
+教材コードによっては `id` や `text` を使っていても本質は同じです。
+
+### 2. PlanningState
 
-1. TodoManagerはアイテムのリストをステータス付きで保持する。`in_progress`にできるのは同時に1つだけ。
+item だけでは足りません。
+
+plan 全体には最低限、次の running state も要ります。
+
+```python
+{
+    "items": [...],
+    "rounds_since_update": 0,
+}
+```
+
+`rounds_since_update` の意味は、
+
+> 何 turn 連続で plan が更新されていないか
+
+です。
+
+この値があるから reminder を出せます。
+
+### 3. 状態制約
+
+教材版では次の制約を置くのが有効です。
+
+```text
+同時に in_progress は最大 1 つ
+```
+
+これは宇宙の真理ではありません。  
+でも初学者にとっては非常に良い制約です。
+
+理由は単純で、
+
+**current focus を system 側から明示できる**
+
+からです。
+
+## 最小実装を段階で追う
+
+### 第 1 段階: plan manager を用意する
 
 ```python
 class TodoManager:
-    def update(self, items: list) -> str:
-        validated, in_progress_count = [], 0
-        for item in items:
-            status = item.get("status", "pending")
-            if status == "in_progress":
-                in_progress_count += 1
-            validated.append({"id": item["id"], "text": item["text"],
-                              "status": status})
-        if in_progress_count > 1:
-            raise ValueError("Only one task can be in_progress")
-        self.items = validated
-        return self.render()
+    def __init__(self):
+        self.items = []
 ```
 
-2. `todo`ツールは他のツールと同様にディスパッチマップに追加される。
+最初はこれで十分です。
+
+ここで導入したいのは UI ではなく、
+
+> plan を model の頭の中ではなく harness 側の state として持つ
+
+という発想です。
+
+### 第 2 段階: plan 全体を更新できるようにする
+
+教材版では item をちまちま差分更新するより、
+
+**現在の plan を丸ごと更新する**
+
+方が理解しやすいです。
+
+```python
+def update(self, items: list) -> str:
+    validated = []
+    in_progress_count = 0
+
+    for item in items:
+        status = item.get("status", "pending")
+        if status == "in_progress":
+            in_progress_count += 1
+
+        validated.append({
+            "content": item["content"],
+            "status": status,
+            "activeForm": item.get("activeForm", ""),
+        })
+
+    if in_progress_count > 1:
+        raise ValueError("Only one item can be in_progress")
+
+    self.items = validated
+    return self.render()
+```
+
+ここでやっていることは 2 つです。
+
+- current plan を受け取る
+- 状態制約をチェックする
+
+### 第 3 段階: render して可読にする
+
+```python
+def render(self) -> str:
+    lines = []
+    for item in self.items:
+        marker = {
+            "pending": "[ ]",
+            "in_progress": "[>]",
+            "completed": "[x]",
+        }[item["status"]]
+        lines.append(f"{marker} {item['content']}")
+    return "\n".join(lines)
+```
+
+render の価値は見た目だけではありません。
+
+plan が text として安定して見えることで、
+
+- user が current progress を理解しやすい
+- model も自分が何をどこまで進めたか確認しやすい
+
+状態になります。
+
+### 第 4 段階: `todo` を 1 つの tool として loop へ接ぐ
 
 ```python
 TOOL_HANDLERS = {
-    # ...base tools...
+    "read_file": run_read,
+    "write_file": run_write,
+    "edit_file": run_edit,
+    "bash": run_bash,
     "todo": lambda **kw: TODO.update(kw["items"]),
 }
 ```
 
-3. nagリマインダーが、モデルが3ラウンド以上`todo`を呼ばなかった場合にナッジを注入する。
+ここで重要なのは、plan 更新を特別扱いの hidden logic にせず、
+
+**tool call として explicit に loop へ入れる**
+
+ことです。
+
+### 第 5 段階: 数 turn 更新がなければ reminder を挿入する
 
 ```python
-if rounds_since_todo >= 3 and messages:
-    last = messages[-1]
-    if last["role"] == "user" and isinstance(last.get("content"), list):
-        last["content"].insert(0, {
-            "type": "text",
-            "text": "<reminder>Update your todos.</reminder>",
-        })
+if rounds_since_update >= 3:
+    results.insert(0, {
+        "type": "text",
+        "text": "<reminder>Refresh your plan before continuing.</reminder>",
+    })
 ```
 
-「一度にin_progressは1つだけ」の制約が逐次的な集中を強制し、nagリマインダーが説明責任を生む。
+この reminder の意味は「system が代わりに plan を立てる」ではありません。
+
+正しくは、
+
+> plan state がしばらく stale なので、model に current plan を更新させる
+
+です。
 
-## s02からの変更点
+## main loop に何が増えるのか
 
-| Component      | Before (s02)     | After (s03)                |
-|----------------|------------------|----------------------------|
-| Tools          | 4                | 5 (+todo)                  |
-| Planning       | None             | TodoManager with statuses  |
-| Nag injection  | None             | `<reminder>` after 3 rounds|
-| Agent loop     | Simple dispatch  | + rounds_since_todo counter|
+この章以後、main loop は `messages` だけを持つわけではなくなります。
 
-## 試してみる
+持つ state が少なくとも 2 本になります。
 
-```sh
-cd learn-claude-code
-python agents/s03_todo_write.py
+```text
+messages
+  -> model が読む会話と観察の history
+
+planning state
+  -> 今回の session で current work をどう進めるか
 ```
 
-1. `Refactor the file hello.py: add type hints, docstrings, and a main guard`
-2. `Create a Python package with __init__.py, utils.py, and tests/test_utils.py`
-3. `Review all Python files and fix any style issues`
+これがこの章の本当の upgrade です。
+
+agent はもはや単に chat history を伸ばしているだけではなく、
+
+**「いま何をしているか」を外から見える panel として維持する**
+
+ようになります。
+
+## なぜここで task graph まで教えないのか
+
+初心者は planning の話が出るとすぐ、
+
+> だったら durable task board も同時に作った方がよいのでは
+
+と考えがちです。
+
+でも教学順序としては早すぎます。
+
+理由は、ここで理解してほしいのが
+
+**session 内の軽い plan と、長く残る durable work graph は別物**
+
+という境界だからです。
+
+`s03` は current focus の外部化です。  
+`s12` 以降は durable task system です。
+
+順番を守ると、後で混ざりにくくなります。
+
+## 初学者が混ぜやすいポイント
+
+### 1. plan を model の頭の中だけに置く
+
+これでは multi-step work がすぐ漂います。
+
+### 2. `in_progress` を複数許してしまう
+
+current focus がぼやけ、plan が checklist ではなく wish list になります。
+
+### 3. plan を一度書いたら更新しない
+
+それでは plan は living state ではなく dead note です。
+
+### 4. reminder を system の強制 planning と誤解する
+
+reminder は軽いナッジであって、plan の中身を system が代行するものではありません。
+
+### 5. session plan と durable task graph を同一視する
+
+この章で扱うのは current request を進めるための軽量 state です。
+
+## この章を読み終えたら何が言えるべきか
+
+1. planning は model の代わりに考えることではなく、current progress を外部 state にすること
+2. session plan は durable task system とは別層であること
+3. `in_progress` を 1 つに絞ると初心者の心智が安定すること
+
+## 一文で覚える
+
+**TodoWrite とは、「次に何をするか」を model の頭の中ではなく、system が見える外部 state に書き出すことです。**
diff --git a/docs/ja/s04-subagent.md b/docs/ja/s04-subagent.md
index bfffc3165..2462ce45b 100644
--- a/docs/ja/s04-subagent.md
+++ b/docs/ja/s04-subagent.md
@@ -1,94 +1,320 @@
 # s04: Subagents
 
-`s01 > s02 > s03 > [ s04 ] s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
+`s00 > s01 > s02 > s03 > [ s04 ] > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
 
-> *"大きなタスクを分割し、各サブタスクにクリーンなコンテキストを"* -- サブエージェントは独立した messages[] を使い、メイン会話を汚さない。
->
-> **Harness 層**: コンテキスト隔離 -- モデルの思考の明晰さを守る。
+> *大きな仕事を全部 1 つの context に詰め込む必要はありません。*  
+> subagent の価値は「model を 1 個増やすこと」ではなく、「clean な別 context を 1 つ持てること」にあります。
 
-## 問題
+## この章が解く問題
 
-エージェントが作業するにつれ、messages配列は膨張し続ける。すべてのファイル読み取り、すべてのbash出力がコンテキストに永久に残る。「このプロジェクトはどのテストフレームワークを使っているか」という質問は5つのファイルを読む必要があるかもしれないが、親に必要なのは「pytest」という答えだけだ。
+agent がいろいろな調査や実装を進めると、親の `messages` はどんどん長くなります。
 
-## 解決策
+たとえば user の質問が単に
 
+> 「この project は何の test framework を使っているの？」
+
+だけでも、親 agent は答えるために、
+
+- `pyproject.toml` を読む
+- `requirements.txt` を読む
+- `pytest` を検索する
+- 実際に test command を走らせる
+
+かもしれません。
+
+でも本当に親に必要な最終答えは、
+
+> 「主に `pytest` を使っています」
+
+の一文だけかもしれません。
+
+もしこの途中作業を全部親 context に積み続けると、あとで別の質問に答えるときに、
+
+- さっきの局所調査の noise
+- 大量の file read
+- 一時的な bash 出力
+
+が main context を汚染します。
+
+subagent が解くのはこの問題です。
+
+**局所 task を別 context に閉じ込め、親には必要な summary だけを持ち帰る**
+
+のがこの章の主線です。
+
+## 先に言葉をそろえる
+
+### 親 agent とは何か
+
+いま user と直接やり取りし、main `messages` を持っている actor が親 agent です。
+
+### 子 agent とは何か
+
+親が一時的に派生させ、特定の subtask だけを処理させる actor が子 agent、つまり subagent です。
+
+### context isolation とは何か
+
+これは単に、
+
+- 親は親の `messages`
+- 子は子の `messages`
+
+を持ち、
+
+> 子の途中経過が自動で親 history に混ざらないこと
+
+を指します。
+
+## 最小心智モデル
+
+この章は次の図でほぼ言い切れます。
+
+```text
+Parent agent
+  |
+  | 1. 局所 task を外へ出すと決める
+  v
+Subagent
+  |
+  | 2. 自分の context で file read / search / tool execution
+  v
+Summary
+  |
+  | 3. 必要な結果だけを親へ返す
+  v
+Parent agent continues
 ```
-Parent agent                     Subagent
-+------------------+             +------------------+
-| messages=[...]   |             | messages=[]      | <-- fresh
-|                  |  dispatch   |                  |
-| tool: task       | ----------> | while tool_use:  |
-|   prompt="..."   |             |   call tools     |
-|                  |  summary    |   append results |
-|   result = "..." | <---------- | return last text |
-+------------------+             +------------------+
-
-Parent context stays clean. Subagent context is discarded.
-```
 
-## 仕組み
+ここで一番大事なのは次の 1 文です。
+
+**subagent の価値は別 model instance ではなく、別 state boundary にある**
+
+ということです。
 
-1. 親に`task`ツールを追加する。子は`task`を除くすべての基本ツールを取得する(再帰的な生成は不可)。
+## 最小実装を段階で追う
+
+### 第 1 段階: 親に `task` tool を持たせる
+
+親 agent は model が明示的に言える入口を持つ必要があります。
+
+> この局所仕事は clean context に外注したい
+
+その最小 schema は非常に簡単で構いません。
 
 ```python
-PARENT_TOOLS = CHILD_TOOLS + [
-    {"name": "task",
-     "description": "Spawn a subagent with fresh context.",
-     "input_schema": {
-         "type": "object",
-         "properties": {"prompt": {"type": "string"}},
-         "required": ["prompt"],
-     }},
-]
+{
+    "name": "task",
+    "description": "Run a subtask in a clean context and return a summary.",
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "prompt": {"type": "string"}
+        },
+        "required": ["prompt"]
+    }
+}
 ```
 
-2. サブエージェントは`messages=[]`で開始し、自身のループを実行する。最終テキストだけが親に返る。
+### 第 2 段階: subagent は自分専用の `messages` で始める
+
+subagent の本体はここです。
 
 ```python
 def run_subagent(prompt: str) -> str:
     sub_messages = [{"role": "user", "content": prompt}]
-    for _ in range(30):  # safety limit
-        response = client.messages.create(
-            model=MODEL, system=SUBAGENT_SYSTEM,
-            messages=sub_messages,
-            tools=CHILD_TOOLS, max_tokens=8000,
-        )
-        sub_messages.append({"role": "assistant",
-                             "content": response.content})
-        if response.stop_reason != "tool_use":
-            break
-        results = []
-        for block in response.content:
-            if block.type == "tool_use":
-                handler = TOOL_HANDLERS.get(block.name)
-                output = handler(**block.input)
-                results.append({"type": "tool_result",
-                    "tool_use_id": block.id,
-                    "content": str(output)[:50000]})
-        sub_messages.append({"role": "user", "content": results})
-    return "".join(
-        b.text for b in response.content if hasattr(b, "text")
-    ) or "(no summary)"
+    ...
+```
+
+親の `messages` をそのまま共有しないことが、最小の isolation です。
+
+### 第 3 段階: 子に渡す tool は絞る
+
+subagent は親と完全に同じ tool set を持つ必要はありません。
+
+むしろ最初は絞った方がよいです。
+
+たとえば、
+
+- `read_file`
+- 検索系 tool
+- read-only 寄りの `bash`
+
+だけを持たせ、
+
+- さらに `task` 自体は子に渡さない
+
+ようにすれば、無限再帰を避けやすくなります。
+
+### 第 4 段階: 子は最後に summary だけ返す
+
+一番大事なのはここです。
+
+subagent は内部 history を親に全部戻しません。
+
+戻すのは必要な summary だけです。
+
+```python
+return {
+    "type": "tool_result",
+    "tool_use_id": block.id,
+    "content": summary_text,
+}
+```
+
+これにより親 context は、
+
+- 必要な答え
+- もしくは短い結論
+
+だけを保持し、局所ノイズから守られます。
+
+## この章の核になるデータ構造
+
+この章で 1 つだけ覚えるなら、次の骨格です。
+
+```python
+class SubagentContext:
+    messages: list
+    tools: list
+    handlers: dict
+    max_turns: int
 ```
 
-子のメッセージ履歴全体(30回以上のツール呼び出し)は破棄される。親は1段落の要約を通常の`tool_result`として受け取る。
+意味は次の通りです。
+
+- `messages`: 子自身の context
+- `tools`: 子が使える道具
+- `handlers`: その tool が実際にどの code を呼ぶか
+- `max_turns`: 子が無限に走り続けないための上限
+
+つまり subagent は「関数呼び出し」ではなく、
+
+**自分の state と tool boundary を持つ小さな agent**
+
+です。
+
+## なぜ本当に useful なのか
+
+### 1. 親 context を軽く保てる
+
+局所 task の途中経過が main conversation に積み上がりません。
+
+### 2. subtask の prompt を鋭くできる
+
+子に渡す prompt は次のように非常に集中できます。
+
+- 「この directory の test framework を 1 文で答えて」
+- 「この file の bug を探して原因だけ返して」
+- 「3 file を読んで module 関係を summary して」
+
+### 3. 後の multi-agent chapter の準備になる
+
+subagent は long-lived teammate より前に学ぶべき最小の delegation model です。
+
+まず「1 回限りの clean delegation」を理解してから、
+
+- persistent teammate
+- structured protocol
+- autonomous claim
+
+へ進むと心智がずっと滑らかになります。
+
+## 0-to-1 の実装順序
+
+### Version 1: blank-context subagent
+
+最初はこれで十分です。
+
+- `task` tool
+- `run_subagent(prompt)`
+- 子専用 `messages`
+- 最後に summary を返す
+
+### Version 2: tool set を制限する
+
+親より小さく安全な tool set を渡します。
+
+### Version 3: safety bound を足す
+
+最低限、
+
+- 最大 turn 数
+- tool failure 時の終了条件
+
+は入れてください。
+
+### Version 4: fork を検討する
+
+この順番を守ることが大事です。
+
+最初から fork を入れる必要はありません。
 
-## s03からの変更点
+## fork とは何か、なぜ「次の段階」なのか
 
-| Component      | Before (s03)     | After (s04)               |
-|----------------|------------------|---------------------------|
-| Tools          | 5                | 5 (base) + task (parent)  |
-| Context        | Single shared    | Parent + child isolation  |
-| Subagent       | None             | `run_subagent()` function |
-| Return value   | N/A              | Summary text only         |
+最小 subagent は blank context から始めます。
 
-## 試してみる
+でも subtask によっては、親が直前まで話していた内容を知らないと困ることがあります。
 
-```sh
-cd learn-claude-code
-python agents/s04_subagent.py
+たとえば、
+
+> 「さっき決めた方針に沿って、この module へ test を追加して」
+
+のような場面です。
+
+そのとき使うのが `fork` です。
+
+```python
+sub_messages = list(parent_messages)
+sub_messages.append({"role": "user", "content": prompt})
 ```
 
-1. `Use a subtask to find what testing framework this project uses`
-2. `Delegate: read all .py files and summarize what each one does`
-3. `Use a task to create a new module, then verify it from here`
+fork の本質は、
+
+**空白から始めるのではなく、親の既存 context を引き継いで子を始めること**
+
+です。
+
+ただし teaching order としては、blank-context subagent を理解してからの方が安全です。
+
+先に fork を入れると、初心者は
+
+- 何が isolation で
+- 何が inherited context なのか
+
+を混ぜやすくなります。
+
+## 初学者が混ぜやすいポイント
+
+### 1. subagent を「並列アピール機能」だと思う
+
+subagent の第一目的は concurrency 自慢ではなく、context hygiene です。
+
+### 2. 子の history を全部親へ戻してしまう
+
+それでは isolation の価値がほとんど消えます。
+
+### 3. 最初から役割を増やしすぎる
+
+explorer、reviewer、planner、tester などを一気に作る前に、
+
+**clean context の一回限り worker**
+
+を正しく作る方が先です。
+
+### 4. 子に `task` を持たせて無限に spawn させる
+
+境界がないと recursion で system が荒れます。
+
+### 5. `max_turns` のような safety bound を持たない
+
+局所 task だからこそ、終わらない子を放置しない設計が必要です。
+
+## この章を読み終えたら何が言えるべきか
+
+1. subagent の価値は clean context を作ることにある
+2. 子は親と別の `messages` を持つべきである
+3. 親へ戻すのは内部 history 全量ではなく summary でよい
+
+## 一文で覚える
+
+**Subagent とは、局所 task を clean context へ切り出し、親には必要な結論だけを持ち帰るための最小 delegation mechanism です。**
diff --git a/docs/ja/s05-skill-loading.md b/docs/ja/s05-skill-loading.md
index 14774bec9..b219f96dc 100644
--- a/docs/ja/s05-skill-loading.md
+++ b/docs/ja/s05-skill-loading.md
@@ -1,6 +1,6 @@
 # s05: Skills
 
-`s01 > s02 > s03 > s04 > [ s05 ] s06 | s07 > s08 > s09 > s10 > s11 > s12`
+`s01 > s02 > s03 > s04 > [ s05 ] > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
 
 > *"必要な知識を、必要な時に読み込む"* -- system prompt ではなく tool_result で注入。
 >
@@ -106,3 +106,26 @@ python agents/s05_skill_loading.py
 2. `Load the agent-builder skill and follow its instructions`
 3. `I need to do a code review -- load the relevant skill first`
 4. `Build an MCP server using the mcp-builder skill`
+
+## 高完成度システムではどう広がるか
+
+この章の核心は 2 層モデルです。  
+まず軽い一覧で「何があるか」を知らせ、必要になったときだけ本文を深く読み込む。これはそのまま有効です。
+
+より完成度の高いシステムでは、その周りに次のような広がりが出ます。
+
+| 観点 | 教材版 | 高完成度システム |
+|------|--------|------------------|
+| 発見レイヤー | プロンプト内に名前一覧 | 予算付きの専用インベントリやリマインダ面 |
+| 読み込み | `load_skill` が本文を返す | 同じ文脈へ注入、別ワーカーで実行、補助コンテキストとして添付など |
+| ソース | `skills/` ディレクトリのみ | user、project、bundled、plugin、外部ソースなど |
+| 適用範囲 | 常に見える | タスク種別、触ったファイル、明示指示に応じて有効化 |
+| 引数 | なし | スキルへパラメータやテンプレート値を渡せる |
+| ライフサイクル | 一度読むだけ | compact や再開後に復元されることがある |
+| ガードレール | なし | スキルごとの許可範囲や行動制約を持てる |
+
+教材としては、2 層モデルだけで十分です。  
+ここで学ぶべき本質は：
+
+**専門知識は最初から全部抱え込まず、必要な時だけ深く読み込む**  
+という設計です。
diff --git a/docs/ja/s06-context-compact.md b/docs/ja/s06-context-compact.md
index 6927e7d1c..ceddf9fd0 100644
--- a/docs/ja/s06-context-compact.md
+++ b/docs/ja/s06-context-compact.md
@@ -1,10 +1,8 @@
 # s06: Context Compact
 
-`s01 > s02 > s03 > s04 > s05 > [ s06 ] | s07 > s08 > s09 > s10 > s11 > s12`
+`s01 > s02 > s03 > s04 > s05 > [ s06 ] > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
 
-> *"コンテキストはいつか溢れる、空ける手段が要る"* -- 3層圧縮で無限セッションを実現。
->
-> **Harness 層**: 圧縮 -- クリーンな記憶、無限のセッション。
+> *"コンテキストはいつか溢れる、空ける手段が要る"* -- 4レバー圧縮で無限セッションを実現。
 
 ## 問題
 
@@ -12,18 +10,24 @@
 
 ## 解決策
 
-積極性を段階的に上げる3層構成:
+ツール出力時から手動トリガーまで、4つの圧縮レバー:
 
 ```
-Every turn:
+Every tool call:
 +------------------+
 | Tool call result |
 +------------------+
         |
         v
-[Layer 1: micro_compact]        (silent, every turn)
+[Lever 0: persisted-output]     (at tool execution time)
+  Large outputs (>50KB, bash >30KB) are written to disk
+  and replaced with a <persisted-output> preview marker.
+        |
+        v
+[Lever 1: micro_compact]        (silent, every turn)
   Replace tool_result > 3 turns old
   with "[Previous: used {tool_name}]"
+  (preserves read_file results as reference material)
         |
         v
 [Check: tokens > 50000?]
@@ -31,47 +35,63 @@ Every turn:
    no              yes
    |               |
    v               v
-continue    [Layer 2: auto_compact]
+continue    [Lever 2: auto_compact]
               Save transcript to .transcripts/
               LLM summarizes conversation.
               Replace all messages with [summary].
                     |
                     v
-            [Layer 3: compact tool]
+            [Lever 3: compact tool]
               Model calls compact explicitly.
               Same summarization as auto_compact.
 ```
 
 ## 仕組み
 
-1. **第1層 -- micro_compact**: 各LLM呼び出しの前に、古いツール結果をプレースホルダーに置換する。
+0. **レバー 0 -- persisted-output**: ツール出力がサイズ閾値を超えた場合、ディスクに書き込みプレビューマーカーに置換する。巨大な出力がコンテキストウィンドウに入るのを防ぐ。
+
+```python
+PERSIST_OUTPUT_TRIGGER_CHARS_DEFAULT = 50000
+PERSIST_OUTPUT_TRIGGER_CHARS_BASH = 30000   # bashはより低い閾値を使用
+
+def maybe_persist_output(tool_use_id, output, trigger_chars=None):
+    if len(output) <= trigger:
+        return output
+    stored_path = _persist_tool_result(tool_use_id, output)
+    return _build_persisted_marker(stored_path, output)
+    # Returns: <persisted-output>
+    #   Output too large (48.8KB). Full output saved to: .task_outputs/tool-results/abc123.txt
+    #   Preview (first 2.0KB):
+    #   ... first 2000 chars ...
+    # </persisted-output>
+```
+
+モデルは後から`read_file`で保存パスにアクセスし、完全な内容を取得できる。
+
+1. **レバー 1 -- micro_compact**: 各LLM呼び出しの前に、古いツール結果をプレースホルダーに置換する。`read_file`の結果は参照資料として保持する。
 
 ```python
+PRESERVE_RESULT_TOOLS = {"read_file"}
+
 def micro_compact(messages: list) -> list:
-    tool_results = []
-    for i, msg in enumerate(messages):
-        if msg["role"] == "user" and isinstance(msg.get("content"), list):
-            for j, part in enumerate(msg["content"]):
-                if isinstance(part, dict) and part.get("type") == "tool_result":
-                    tool_results.append((i, j, part))
+    tool_results = [...]  # collect all tool_result entries
     if len(tool_results) <= KEEP_RECENT:
         return messages
-    for _, _, part in tool_results[:-KEEP_RECENT]:
-        if len(part.get("content", "")) > 100:
-            part["content"] = f"[Previous: used {tool_name}]"
+    for part in tool_results[:-KEEP_RECENT]:
+        if tool_name in PRESERVE_RESULT_TOOLS:
+            continue   # keep reference material
+        part["content"] = f"[Previous: used {tool_name}]"
     return messages
 ```
 
-2. **第2層 -- auto_compact**: トークンが閾値を超えたら、完全なトランスクリプトをディスクに保存し、LLMに要約を依頼する。
+2. **レバー 2 -- auto_compact**: トークンが閾値を超えたら、完全なトランスクリプトをディスクに保存し、LLMに要約を依頼する。
 
 ```python
 def auto_compact(messages: list) -> list:
-    # Save transcript for recovery
     transcript_path = TRANSCRIPT_DIR / f"transcript_{int(time.time())}.jsonl"
     with open(transcript_path, "w") as f:
         for msg in messages:
             f.write(json.dumps(msg, default=str) + "\n")
-    # LLM summarizes
     response = client.messages.create(
         model=MODEL,
         messages=[{"role": "user", "content":
@@ -84,33 +104,34 @@ def auto_compact(messages: list) -> list:
     ]
 ```
 
-3. **第3層 -- manual compact**: `compact`ツールが同じ要約処理をオンデマンドでトリガーする。
+3. **レバー 3 -- manual compact**: `compact`ツールが同じ要約処理をオンデマンドでトリガーする。
 
-4. ループが3層すべてを統合する:
+4. ループが4つのレバーすべてを統合する:
 
 ```python
 def agent_loop(messages: list):
     while True:
-        micro_compact(messages)                        # Layer 1
+        micro_compact(messages)                        # Lever 1
         if estimate_tokens(messages) > THRESHOLD:
-            messages[:] = auto_compact(messages)       # Layer 2
+            messages[:] = auto_compact(messages)       # Lever 2
         response = client.messages.create(...)
-        # ... tool execution ...
+        # ... tool execution with persisted-output ... # Lever 0
         if manual_compact:
-            messages[:] = auto_compact(messages)       # Layer 3
+            messages[:] = auto_compact(messages)       # Lever 3
 ```
 
-トランスクリプトがディスク上に完全な履歴を保持する。何も真に失われず、アクティブなコンテキストの外に移動されるだけ。
+トランスクリプトがディスク上に完全な履歴を保持する。大きな出力は`.task_outputs/tool-results/`に保存される。何も真に失われず、アクティブなコンテキストの外に移動されるだけ。
 
 ## s05からの変更点
 
-| Component      | Before (s05)     | After (s06)                |
-|----------------|------------------|----------------------------|
-| Tools          | 5                | 5 (base + compact)         |
-| Context mgmt   | None             | Three-layer compression    |
-| Micro-compact  | None             | Old results -> placeholders|
-| Auto-compact   | None             | Token threshold trigger    |
-| Transcripts    | None             | Saved to .transcripts/     |
+| Component         | Before (s05)     | After (s06)                |
+|-------------------|------------------|----------------------------|
+| Tools             | 5                | 5 (base + compact)         |
+| Context mgmt      | None             | Four-lever compression     |
+| Persisted-output  | None             | Large outputs -> disk + preview |
+| Micro-compact     | None             | Old results -> placeholders|
+| Auto-compact      | None             | Token threshold trigger    |
+| Transcripts       | None             | Saved to .transcripts/     |
 
 ## 試してみる
 
@@ -122,3 +143,21 @@ python agents/s06_context_compact.py
 1. `Read every Python file in the agents/ directory one by one` (micro-compactが古い結果を置換するのを観察する)
 2. `Keep reading files until compression triggers automatically`
 3. `Use the compact tool to manually compress the conversation`
+
+## 高完成度システムではどう広がるか
+
+教材版は compact を理解しやすくするために、仕組みを大きく 4 本に絞っています。  
+より完成度の高いシステムでは、その周りに追加の段階が増えます。
+
+| レイヤー | 教材版 | 高完成度システム |
+|---------|--------|------------------|
+| 大きな出力 | 大きすぎる結果をディスクへ逃がす | 複数ツールの合計量も見ながら、文脈に入る前に予算調整する |
+| 軽い整理 | 単純な micro-compact | フル要約の前に複数の軽量整理パスを入れる |
+| フル compact | 閾値を超えたら要約 | 事前 compact、回復用 compact、エラー後 compact など役割分担が増える |
+| 回復 | 要約 1 本に置き換える | compact 後に最近のファイル、計画、スキル、非同期状態などを戻す |
+| 起動条件 | 自動または手動ツール | ユーザー操作、内部閾値、回復処理など複数の入口 |
+
+ここで覚えるべき核心は変わりません。
+
+**compact は「履歴を捨てること」ではなく、「細部をアクティブ文脈の外へ移し、連続性を保つこと」**  
+です。
diff --git a/docs/ja/s07-permission-system.md b/docs/ja/s07-permission-system.md
new file mode 100644
index 000000000..22fda7fb6
--- /dev/null
+++ b/docs/ja/s07-permission-system.md
@@ -0,0 +1,371 @@
+# s07: Permission System
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > [ s07 ] > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
+
+> *model は「こうしたい」と提案できます。けれど本当に実行する前には、必ず安全 gate を通さなければなりません。*
+
+## この章の核心目標
+
+`s06` まで来ると agent はすでに、
+
+- file を読む
+- file を書く
+- command を実行する
+- plan を持つ
+- context を compact する
+
+ことができます。
+
+能力が増えるほど、当然危険も増えます。
+
+- 間違った file を書き換える
+- 危険な shell command を実行する
+- user がまだ許可していない操作に踏み込む
+
+だからここから先は、
+
+**「model の意図」がそのまま「実行」へ落ちる**
+
+構造をやめなければなりません。
+
+この章で入れるのは、
+
+**tool request を実行前に判定する permission pipeline**
+
+です。
+
+## 併読すると楽になる資料
+
+- model の提案と system の実実行が混ざるなら [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)
+- なぜ tool request を直接 handler に落としてはいけないか不安なら [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md)
+- `PermissionRule`、`PermissionDecision`、`tool_result` が混ざるなら [`data-structures.md`](./data-structures.md)
+
+## 先に言葉をそろえる
+
+### permission system とは何か
+
+permission system は真偽値 1 個ではありません。
+
+むしろ次の 3 問に順番に答える pipeline です。
+
+1. これは即拒否すべきか
+2. 自動で許可してよいか
+3. 残りは user に確認すべきか
+
+### permission mode とは何か
+
+mode は、その session 全体の安全姿勢です。
+
+たとえば、
+
+- 慎重に進める
+- 読み取りだけ許す
+- 安全そうなものは自動通過させる
+
+といった大きな方針です。
+
+### rule とは何か
+
+rule は、
+
+> ある tool request に当たったらどう振る舞うか
+
+を表す小さな条項です。
+
+最小形なら次のような record で表せます。
+
+```python
+{
+    "tool": "bash",
+    "content": "sudo *",
+    "behavior": "deny",
+}
+```
+
+意味は、
+
+- `bash` に対して
+- command 内容が `sudo *` に当たれば
+- 拒否する
+
+です。
+
+## 最小 permission system の形
+
+0 から手で作るなら、最小で正しい pipeline は 4 段で十分です。
+
+```text
+tool_call
+  |
+  v
+1. deny rules
+  -> 危険なら即拒否
+  |
+  v
+2. mode check
+  -> 現在 mode に照らして判定
+  |
+  v
+3. allow rules
+  -> 安全で明確なら自動許可
+  |
+  v
+4. ask user
+  -> 残りは確認に回す
+```
+
+この 4 段で teaching repo の主線としては十分に強いです。
+
+## なぜ順番がこの形なのか
+
+### 1. deny を先に見る理由
+
+ある種の request は mode に関係なく危険です。
+
+たとえば、
+
+- 明白に危険な shell command
+- workspace の外へ逃げる path
+
+などです。
+
+こうしたものは「いま auto mode だから」などの理由で通すべきではありません。
+
+### 2. mode を次に見る理由
+
+mode はその session の大きな姿勢だからです。
+
+たとえば `plan` mode なら、
+
+> まだ review / analysis 段階なので write 系をまとめて抑える
+
+という全体方針を早い段で効かせたいわけです。
+
+### 3. allow を後に見る理由
+
+deny と mode を抜けたあとで、
+
+> これは何度も出てくる安全な操作だから自動で通してよい
+
+というものを allow します。
+
+たとえば、
+
+- `read_file`
+- code search
+- `git status`
+
+などです。
+
+### 4. ask を最後に置く理由
+
+前段で明確に決められなかった灰色領域だけを user に回すためです。
+
+これで、
+
+- 危険なものは system が先に止める
+- 明らかに安全なものは system が先に通す
+- 本当に曖昧なものだけ user が判断する
+
+という自然な構図になります。
+
+## 最初に実装すると良い 3 つの mode
+
+最初から mode を増やしすぎる必要はありません。
+
+まずは次の 3 つで十分です。
+
+| mode | 意味 | 向いている場面 |
+|---|---|---|
+| `default` | rule に当たらないものは user に確認 | 普通の対話 |
+| `plan` | write を止め、read 中心で進める | planning / review / analysis |
+| `auto` | 明らかに安全な read は自動許可 | 高速探索 |
+
+この 3 つだけでも、
+
+- 慎重さ
+- 計画モード
+- 流暢さ
+
+のバランスを十分教えられます。
+
+## この章の核になるデータ構造
+
+### 1. PermissionRule
+
+```python
+PermissionRule = {
+    "tool": str,
+    "behavior": "allow" | "deny" | "ask",
+    "path": str | None,
+    "content": str | None,
+}
+```
+
+必ずしも最初から `path` と `content` の両方を使う必要はありません。
+
+でも少なくとも rule は次を表現できる必要があります。
+
+- どの tool に対する rule か
+- 当たったらどう振る舞うか
+
+### 2. Permission Mode
+
+```python
+mode = "default" | "plan" | "auto"
+```
+
+これは個々の rule ではなく session 全体の posture です。
+
+### 3. PermissionDecision
+
+```python
+{
+    "behavior": "allow" | "deny" | "ask",
+    "reason": "why this decision was made",
+}
+```
+
+ここで `reason` を持つのが大切です。
+
+なぜなら permission system は「通した / 止めた」だけではなく、
+
+**なぜそうなったかを説明できるべき**
+
+だからです。
+
+## 最小実装を段階で追う
+
+### 第 1 段階: 判定関数を書く
+
+```python
+def check_permission(tool_name: str, tool_input: dict) -> dict:
+    # 1. deny rules
+    for rule in deny_rules:
+        if matches(rule, tool_name, tool_input):
+            return {"behavior": "deny", "reason": "matched deny rule"}
+
+    # 2. mode check
+    if mode == "plan" and tool_name in WRITE_TOOLS:
+        return {"behavior": "deny", "reason": "plan mode blocks writes"}
+    if mode == "auto" and tool_name in READ_ONLY_TOOLS:
+        return {"behavior": "allow", "reason": "auto mode allows reads"}
+
+    # 3. allow rules
+    for rule in allow_rules:
+        if matches(rule, tool_name, tool_input):
+            return {"behavior": "allow", "reason": "matched allow rule"}
+
+    # 4. fallback
+    return {"behavior": "ask", "reason": "needs confirmation"}
+```
+
+重要なのは code の華やかさではなく、
+
+**先に分類し、その後で分岐する**
+
+という構造です。
+
+### 第 2 段階: tool 実行直前に接ぐ
+
+permission は tool request が来たあと、handler を呼ぶ前に入ります。
+
+```python
+decision = perms.check(tool_name, tool_input)
+
+if decision["behavior"] == "deny":
+    return f"Permission denied: {decision['reason']}"
+
+if decision["behavior"] == "ask":
+    ok = ask_user(...)
+    if not ok:
+        return "Permission denied by user"
+
+return handler(**tool_input)
+```
+
+これで初めて、
+
+**tool request と real execution の間に control gate**
+
+が立ちます。
+
+## `bash` を特別に気にする理由
+
+すべての tool の中で `bash` は特別に危険です。
+
+なぜなら、
+
+- `read_file` は読むだけ
+- `write_file` は書くだけ
+- でも `bash` は理論上ほとんど何でもできる
+
+からです。
+
+したがって `bash` をただの文字列入力として見るのは危険です。
+
+成熟した system では、`bash` を小さな executable language として扱います。
+
+教材版でも最低限、次のような危険要素は先に弾く方がよいです。
+
+- `sudo`
+- `rm -rf`
+- 危険な redirection
+- suspicious command substitution
+- 明白な shell metacharacter chaining
+
+核心は 1 文です。
+
+**bash は普通の text ではなく、可実行 action の記述**
+
+です。
+
+## 初学者が混ぜやすいポイント
+
+### 1. permission を yes/no の 2 値で考える
+
+実際には `deny / allow / ask` の 3 分岐以上が必要です。
+
+### 2. mode を rule の代わりにしようとする
+
+mode は全体 posture、rule は個別条項です。役割が違います。
+
+### 3. `bash` を普通の string と同じ感覚で通す
+
+execution power が桁違いです。
+
+### 4. deny / allow より先に user へ全部投げる
+
+それでは system 側の safety design を学べません。
+
+### 5. decision に reason を残さない
+
+あとで「なぜ止まったか」が説明できなくなります。
+
+## 拒否トラッキングの意味
+
+教材コードでは、連続拒否を数える簡単な circuit breaker を持たせるのも有効です。
+
+なぜなら agent が同じ危険 request を何度も繰り返すとき、
+
+- mode が合っていない
+- plan を作り直すべき
+- 別 route を選ぶべき
+
+という合図になるからです。
+
+これは高度な observability ではなく、
+
+**permission failure も agent の progress 状態の一部である**
+
+と教えるための最小観測です。
+
+## この章を読み終えたら何が言えるべきか
+
+1. model の意図は handler へ直結させず、permission pipeline を通すべき
+2. `default / plan / auto` の 3 mode だけでも十分に teaching mainline が作れる
+3. `bash` は普通の text 入力ではなく、高い実行力を持つ tool なので特別に警戒すべき
+
+## 一文で覚える
+
+**Permission System とは、model の意図をそのまま実行に落とさず、deny / mode / allow / ask の pipeline で安全に変換する層です。**
diff --git a/docs/ja/s08-background-tasks.md b/docs/ja/s08-background-tasks.md
deleted file mode 100644
index b3fe0773e..000000000
--- a/docs/ja/s08-background-tasks.md
+++ /dev/null
@@ -1,107 +0,0 @@
-# s08: Background Tasks
-
-`s01 > s02 > s03 > s04 > s05 > s06 | s07 > [ s08 ] s09 > s10 > s11 > s12`
-
-> *"遅い操作はバックグラウンドへ、エージェントは次を考え続ける"* -- デーモンスレッドがコマンド実行、完了後に通知を注入。
->
-> **Harness 層**: バックグラウンド実行 -- モデルが考え続ける間、Harness が待つ。
-
-## 問題
-
-一部のコマンドは数分かかる: `npm install`、`pytest`、`docker build`。ブロッキングループでは、モデルはサブプロセスの完了を待って座っている。ユーザーが「依存関係をインストールして、その間にconfigファイルを作って」と言っても、エージェントは並列ではなく逐次的に処理する。
-
-## 解決策
-
-```
-Main thread                Background thread
-+-----------------+        +-----------------+
-| agent loop      |        | subprocess runs |
-| ...             |        | ...             |
-| [LLM call] <---+------- | enqueue(result) |
-|  ^drain queue   |        +-----------------+
-+-----------------+
-
-Timeline:
-Agent --[spawn A]--[spawn B]--[other work]----
-             |          |
-             v          v
-          [A runs]   [B runs]      (parallel)
-             |          |
-             +-- results injected before next LLM call --+
-```
-
-## 仕組み
-
-1. BackgroundManagerがスレッドセーフな通知キューでタスクを追跡する。
-
-```python
-class BackgroundManager:
-    def __init__(self):
-        self.tasks = {}
-        self._notification_queue = []
-        self._lock = threading.Lock()
-```
-
-2. `run()`がデーモンスレッドを開始し、即座にリターンする。
-
-```python
-def run(self, command: str) -> str:
-    task_id = str(uuid.uuid4())[:8]
-    self.tasks[task_id] = {"status": "running", "command": command}
-    thread = threading.Thread(
-        target=self._execute, args=(task_id, command), daemon=True)
-    thread.start()
-    return f"Background task {task_id} started"
-```
-
-3. サブプロセス完了時に、結果を通知キューへ。
-
-```python
-def _execute(self, task_id, command):
-    try:
-        r = subprocess.run(command, shell=True, cwd=WORKDIR,
-            capture_output=True, text=True, timeout=300)
-        output = (r.stdout + r.stderr).strip()[:50000]
-    except subprocess.TimeoutExpired:
-        output = "Error: Timeout (300s)"
-    with self._lock:
-        self._notification_queue.append({
-            "task_id": task_id, "result": output[:500]})
-```
-
-4. エージェントループが各LLM呼び出しの前に通知をドレインする。
-
-```python
-def agent_loop(messages: list):
-    while True:
-        notifs = BG.drain_notifications()
-        if notifs:
-            notif_text = "\n".join(
-                f"[bg:{n['task_id']}] {n['result']}" for n in notifs)
-            messages.append({"role": "user",
-                "content": f"<background-results>\n{notif_text}\n"
-                           f"</background-results>"})
-        response = client.messages.create(...)
-```
-
-ループはシングルスレッドのまま。サブプロセスI/Oだけが並列化される。
-
-## s07からの変更点
-
-| Component      | Before (s07)     | After (s08)                |
-|----------------|------------------|----------------------------|
-| Tools          | 8                | 6 (base + background_run + check)|
-| Execution      | Blocking only    | Blocking + background threads|
-| Notification   | None             | Queue drained per loop     |
-| Concurrency    | None             | Daemon threads             |
-
-## 試してみる
-
-```sh
-cd learn-claude-code
-python agents/s08_background_tasks.py
-```
-
-1. `Run "sleep 5 && echo done" in the background, then create a file while it runs`
-2. `Start 3 background tasks: "sleep 2", "sleep 4", "sleep 6". Check their status.`
-3. `Run pytest in the background and keep working on other things`
diff --git a/docs/ja/s08-hook-system.md b/docs/ja/s08-hook-system.md
new file mode 100644
index 000000000..7df109931
--- /dev/null
+++ b/docs/ja/s08-hook-system.md
@@ -0,0 +1,151 @@
+# s08: Hook System
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > [ s08 ] > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
+
+> *ループそのものを書き換えなくても、ライフサイクルの周囲に拡張点を置ける。*
+
+## この章が解決する問題
+
+`s07` までで、agent はかなり実用的になりました。
+
+しかし実際には、ループの外側で足したい振る舞いが増えていきます。
+
+- 監査ログ
+- 実行追跡
+- 通知
+- 追加の安全チェック
+- 実行前後の補助メッセージ
+
+こうした周辺機能を毎回メインループに直接書き込むと、すぐに主線が読みにくくなります。
+
+そこで必要なのが Hook です。
+
+## 主線とどう併読するか
+
+- Hook を「主ループの中へ if/else を足すこと」だと思い始めたら、まず [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md) に戻ります。
+- 主ループ、tool handler、hook の副作用が同じ層に見えてきたら、[`entity-map.md`](./entity-map.md) で「主状態を進めるもの」と「横から観測するもの」を分けます。
+- この先で prompt、recovery、teams まで読むつもりなら、[`s00e-reference-module-map.md`](./s00e-reference-module-map.md) を近くに置いておくと、「control plane + sidecar 拡張」が何度も出てきても崩れにくくなります。
+
+## Hook を最も簡単に言うと
+
+Hook は:
+
+**主ループの決まった節目で、追加動作を差し込む拡張点**
+
+です。
+
+ここで大切なのは、Hook が主ループの代わりになるわけではないことです。  
+主ループは引き続き:
+
+- モデル呼び出し
+- ツール実行
+- 結果の追記
+
+を担当します。
+
+## 最小の心智モデル
+
+```text
+tool_call from model
+     |
+     v
+[PreToolUse hooks]
+     |
+     v
+[execute tool]
+     |
+     v
+[PostToolUse hooks]
+     |
+     v
+append result and continue
+```
+
+この形なら、ループの主線を壊さずに拡張できます。
+
+## まず教えるべき 3 つのイベント
+
+| イベント | いつ発火するか | 主な用途 |
+|---|---|---|
+| `SessionStart` | セッション開始時 | 初期通知、ウォームアップ |
+| `PreToolUse` | ツール実行前 | 監査、ブロック、補助判断 |
+| `PostToolUse` | ツール実行後 | 結果記録、通知、追跡 |
+
+これだけで教学版としては十分です。
+
+## 重要な境界
+
+### Hook は主状態遷移を置き換えない
+
+Hook がやるのは「観察して補助すること」です。
+
+メッセージ履歴、停止条件、ツール呼び出しの主責任は、あくまでメインループに残します。
+
+### Hook には整ったイベント情報を渡す
+
+理想的には、各 Hook は同じ形の情報を受け取ります。
+
+たとえば:
+
+- `event`
+- `tool_name`
+- `tool_input`
+- `tool_output`
+- `error`
+
+この形が揃っていると、Hook を増やしても心智が崩れません。
+
+## 最小実装
+
+### 1. 設定を読む
+
+```python
+hooks = {
+    "PreToolUse": [...],
+    "PostToolUse": [...],
+    "SessionStart": [...],
+}
+```
+
+### 2. 実行関数を作る
+
+```python
+def run_hooks(event_name: str, ctx: dict):
+    for hook in hooks.get(event_name, []):
+        run_one_hook(hook, ctx)
+```
+
+### 3. ループに接続する
+
+```python
+run_hooks("PreToolUse", ctx)
+output = handler(**tool_input)
+run_hooks("PostToolUse", ctx)
+```
+
+## 初学者が混乱しやすい点
+
+### 1. Hook を第二の主ループのように考える
+
+そうすると制御が分裂して、一気に分かりにくくなります。
+
+### 2. Hook ごとに別のデータ形を渡す
+
+新しい Hook を足すたびに、読む側の心智コストが増えてしまいます。
+
+### 3. 何でも Hook に入れようとする
+
+Hook は便利ですが、メインの状態遷移まで押し込む場所ではありません。
+
+## Try It
+
+```sh
+cd learn-claude-code
+python agents/s08_hook_system.py
+```
+
+見るポイント:
+
+1. どのイベントで Hook が走るか
+2. Hook が主ループを壊さずに追加動作だけを行っているか
+3. イベント情報の形が揃っているか
diff --git a/docs/ja/s09-agent-teams.md b/docs/ja/s09-agent-teams.md
deleted file mode 100644
index 671b6e660..000000000
--- a/docs/ja/s09-agent-teams.md
+++ /dev/null
@@ -1,125 +0,0 @@
-# s09: Agent Teams
-
-`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > [ s09 ] s10 > s11 > s12`
-
-> *"一人で終わらないなら、チームメイトに任せる"* -- 永続チームメイト + 非同期メールボックス。
->
-> **Harness 層**: チームメールボックス -- 複数モデルをファイルで協調。
-
-## 問題
-
-サブエージェント(s04)は使い捨てだ: 生成し、作業し、要約を返し、消滅する。アイデンティティもなく、呼び出し間の記憶もない。バックグラウンドタスク(s08)はシェルコマンドを実行するが、LLM誘導の意思決定はできない。
-
-本物のチームワークには: (1)単一プロンプトを超えて存続する永続エージェント、(2)アイデンティティとライフサイクル管理、(3)エージェント間の通信チャネルが必要だ。
-
-## 解決策
-
-```
-Teammate lifecycle:
-  spawn -> WORKING -> IDLE -> WORKING -> ... -> SHUTDOWN
-
-Communication:
-  .team/
-    config.json           <- team roster + statuses
-    inbox/
-      alice.jsonl         <- append-only, drain-on-read
-      bob.jsonl
-      lead.jsonl
-
-              +--------+    send("alice","bob","...")    +--------+
-              | alice  | -----------------------------> |  bob   |
-              | loop   |    bob.jsonl << {json_line}    |  loop  |
-              +--------+                                +--------+
-                   ^                                         |
-                   |        BUS.read_inbox("alice")          |
-                   +---- alice.jsonl -> read + drain ---------+
-```
-
-## 仕組み
-
-1. TeammateManagerがconfig.jsonでチーム名簿を管理する。
-
-```python
-class TeammateManager:
-    def __init__(self, team_dir: Path):
-        self.dir = team_dir
-        self.dir.mkdir(exist_ok=True)
-        self.config_path = self.dir / "config.json"
-        self.config = self._load_config()
-        self.threads = {}
-```
-
-2. `spawn()`がチームメイトを作成し、そのエージェントループをスレッドで開始する。
-
-```python
-def spawn(self, name: str, role: str, prompt: str) -> str:
-    member = {"name": name, "role": role, "status": "working"}
-    self.config["members"].append(member)
-    self._save_config()
-    thread = threading.Thread(
-        target=self._teammate_loop,
-        args=(name, role, prompt), daemon=True)
-    thread.start()
-    return f"Spawned teammate '{name}' (role: {role})"
-```
-
-3. MessageBus: 追記専用のJSONLインボックス。`send()`がJSON行を追記し、`read_inbox()`がすべて読み取ってドレインする。
-
-```python
-class MessageBus:
-    def send(self, sender, to, content, msg_type="message", extra=None):
-        msg = {"type": msg_type, "from": sender,
-               "content": content, "timestamp": time.time()}
-        if extra:
-            msg.update(extra)
-        with open(self.dir / f"{to}.jsonl", "a") as f:
-            f.write(json.dumps(msg) + "\n")
-
-    def read_inbox(self, name):
-        path = self.dir / f"{name}.jsonl"
-        if not path.exists(): return "[]"
-        msgs = [json.loads(l) for l in path.read_text().strip().splitlines() if l]
-        path.write_text("")  # drain
-        return json.dumps(msgs, indent=2)
-```
-
-4. 各チームメイトは各LLM呼び出しの前にインボックスを確認し、受信メッセージをコンテキストに注入する。
-
-```python
-def _teammate_loop(self, name, role, prompt):
-    messages = [{"role": "user", "content": prompt}]
-    for _ in range(50):
-        inbox = BUS.read_inbox(name)
-        if inbox != "[]":
-            messages.append({"role": "user",
-                "content": f"<inbox>{inbox}</inbox>"})
-        response = client.messages.create(...)
-        if response.stop_reason != "tool_use":
-            break
-        # execute tools, append results...
-    self._find_member(name)["status"] = "idle"
-```
-
-## s08からの変更点
-
-| Component      | Before (s08)     | After (s09)                |
-|----------------|------------------|----------------------------|
-| Tools          | 6                | 9 (+spawn/send/read_inbox) |
-| Agents         | Single           | Lead + N teammates         |
-| Persistence    | None             | config.json + JSONL inboxes|
-| Threads        | Background cmds  | Full agent loops per thread|
-| Lifecycle      | Fire-and-forget  | idle -> working -> idle    |
-| Communication  | None             | message + broadcast        |
-
-## 試してみる
-
-```sh
-cd learn-claude-code
-python agents/s09_agent_teams.py
-```
-
-1. `Spawn alice (coder) and bob (tester). Have alice send bob a message.`
-2. `Broadcast "status update: phase 1 complete" to all teammates`
-3. `Check the lead inbox for any messages`
-4. `/team`と入力してステータス付きのチーム名簿を確認する
-5. `/inbox`と入力してリーダーのインボックスを手動確認する
diff --git a/docs/ja/s09-memory-system.md b/docs/ja/s09-memory-system.md
new file mode 100644
index 000000000..9e1b94a6f
--- /dev/null
+++ b/docs/ja/s09-memory-system.md
@@ -0,0 +1,184 @@
+# s09: Memory System
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > [ s09 ] > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
+
+> *memory は会話の全部を保存する場所ではない。次のセッションでも残すべき事実だけを小さく持つ場所である。*
+
+## この章が解決する問題
+
+memory がなければ、新しいセッションは毎回ゼロから始まります。
+
+その結果、agent は何度も同じことを忘れます。
+
+- ユーザーの好み
+- すでに何度も訂正された注意点
+- コードだけでは分かりにくいプロジェクト事情
+- 外部参照の場所
+
+そこで必要になるのが memory です。
+
+## 最初に立てるべき境界
+
+この章で最も大事なのは:
+
+**何でも memory に入れない**
+
+ことです。
+
+memory に入れるべきなのは:
+
+- セッションをまたいでも価値がある
+- 現在のリポジトリを読み直すだけでは分かりにくい
+
+こうした情報だけです。
+
+## 主線とどう併読するか
+
+- memory を「長い context の置き場」だと思ってしまうなら、[`s06-context-compact.md`](./s06-context-compact.md) に戻って compact と durable memory を分けます。
+- `messages[]`、summary block、memory store が頭の中で混ざってきたら、[`data-structures.md`](./data-structures.md) を見ながら読みます。
+- このあと `s10` へ進むなら、[`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md) を横に置くと、memory が次の入力へどう戻るかをつかみやすくなります。
+
+## 初学者向けの 4 分類
+
+### 1. `user`
+
+安定したユーザーの好み。
+
+例:
+
+- `pnpm` を好む
+- 回答は短めがよい
+
+### 2. `feedback`
+
+ユーザーが明示的に直した点。
+
+例:
+
+- 生成ファイルは勝手に触らない
+- テストの更新前に確認する
+
+### 3. `project`
+
+コードを見ただけでは分かりにくい持続的事情。
+
+### 4. `reference`
+
+外部資料や外部ボードへの参照先。
+
+## 入れてはいけないもの
+
+| 入れないもの | 理由 |
+|---|---|
+| ディレクトリ構造 | コードを読めば分かる |
+| 関数名やシグネチャ | ソースが真実だから |
+| 現在タスクの進捗 | task / plan の責務 |
+| 一時的なブランチ名 | すぐ古くなる |
+| 秘密情報 | 危険 |
+
+## 最小の心智モデル
+
+```text
+conversation
+   |
+   | 長期的に残すべき事実が出る
+   v
+save_memory
+   |
+   v
+.memory/
+  ├── MEMORY.md
+  ├── prefer_pnpm.md
+  └── ask_before_codegen.md
+   |
+   v
+次回セッション開始時に再読込
+```
+
+## 重要なデータ構造
+
+### 1. 1 メモリ = 1 ファイル
+
+```md
+---
+name: prefer_pnpm
+description: User prefers pnpm over npm
+type: user
+---
+The user explicitly prefers pnpm for package management commands.
+```
+
+### 2. 小さな索引
+
+```md
+# Memory Index
+
+- prefer_pnpm [user]
+- ask_before_codegen [feedback]
+```
+
+索引は内容そのものではなく、「何があるか」を素早く知るための地図です。
+
+## 最小実装
+
+```python
+MEMORY_TYPES = ("user", "feedback", "project", "reference")
+```
+
+```python
+def save_memory(name, description, mem_type, content):
+    path = memory_dir / f"{slugify(name)}.md"
+    path.write_text(render_frontmatter(name, description, mem_type) + content)
+    rebuild_index()
+```
+
+次に、セッション開始時に読み込みます。
+
+```python
+memories = memory_store.load_all()
+```
+
+そして `s10` で prompt 組み立てに入れます。
+
+## 近い概念との違い
+
+### memory
+
+次回以降も役立つ事実。
+
+### task
+
+いま何を完了したいか。
+
+### plan
+
+このターンでどう進めるか。
+
+### `CLAUDE.md`
+
+より安定した指示文書や standing rules。
+
+## 初学者がよくやる間違い
+
+### 1. コードを読めば分かることまで保存する
+
+それは memory ではなく、重複です。
+
+### 2. 現在の作業状況を memory に入れる
+
+それは task / plan の責務です。
+
+### 3. memory を絶対真実のように扱う
+
+memory は古くなり得ます。
+
+安全な原則は:
+
+**memory は方向を与え、現在観測は真実を与える。**
+
+## Try It
+
+```sh
+cd learn-claude-code
+python agents/s09_memory_system.py
+```
diff --git a/docs/ja/s10-system-prompt.md b/docs/ja/s10-system-prompt.md
new file mode 100644
index 000000000..3c1868b83
--- /dev/null
+++ b/docs/ja/s10-system-prompt.md
@@ -0,0 +1,156 @@
+# s10: System Prompt
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > [ s10 ] > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
+
+> *system prompt は巨大な固定文字列ではなく、複数ソースから組み立てるパイプラインである。*
+
+## なぜこの章が必要か
+
+最初は 1 本の system prompt 文字列でも動きます。
+
+しかし機能が増えると、入力の材料が増えます。
+
+- 安定した役割説明
+- ツール一覧
+- skills
+- memory
+- `CLAUDE.md`
+- 現在ディレクトリや日時のような動的状態
+
+こうなると、1 本の固定文字列では心智が崩れます。
+
+## 主線とどう併読するか
+
+- prompt をまだ「大きな謎の文字列」として見てしまうなら、[`s00a-query-control-plane.md`](./s00a-query-control-plane.md) に戻って、モデル入力がどの control 層を通るかを見直します。
+- どの順で何を組み立てるかを安定させたいなら、[`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md) をこの章の橋渡し資料として併読します。
+- system rules、tool docs、memory、runtime state が 1 つの入力塊に見えてきたら、[`data-structures.md`](./data-structures.md) で入力片の出所を分け直します。
+
+## 最小の心智モデル
+
+```text
+1. core identity
+2. tools
+3. skills
+4. memory
+5. CLAUDE.md chain
+6. dynamic runtime context
+```
+
+最後に順に連結します。
+
+```text
+core
++ tools
++ skills
++ memory
++ claude_md
++ dynamic_context
+= final model input
+```
+
+## 最も重要な境界
+
+分けるべきなのは:
+
+- 安定したルール
+- 毎ターン変わる補足情報
+
+安定したもの:
+
+- 役割
+- 安全ルール
+- ツール契約
+- 長期指示
+
+動的なもの:
+
+- 現在日時
+- cwd
+- 現在モード
+- このターンだけの注意
+
+## 最小 builder
+
+```python
+class SystemPromptBuilder:
+    def build(self) -> str:
+        parts = []
+        parts.append(self._build_core())
+        parts.append(self._build_tools())
+        parts.append(self._build_skills())
+        parts.append(self._build_memory())
+        parts.append(self._build_claude_md())
+        parts.append(self._build_dynamic())
+        return "\n\n".join(p for p in parts if p)
+```
+
+ここで重要なのは、各メソッドが 1 つの責務だけを持つことです。
+
+## 1 本の大文字列より良い理由
+
+### 1. どこから来た情報か分かる
+
+### 2. 部分ごとにテストしやすい
+
+### 3. 安定部分と動的部分を分けて育てられる
+
+## `system prompt` と `system reminder`
+
+より分かりやすい考え方は:
+
+- `system prompt`: 安定した土台
+- `system reminder`: このターンだけの追加注意
+
+こうすると、長期ルールと一時的ノイズが混ざりにくくなります。
+
+## `CLAUDE.md` が独立した段なのはなぜか
+
+`CLAUDE.md` は memory でも skill でもありません。
+
+より安定した指示文書の層です。
+
+教学版では、次のように積み上げると理解しやすいです。
+
+1. ユーザー級
+2. プロジェクト根
+3. サブディレクトリ級
+
+重要なのは:
+
+**指示源は上書き一発ではなく、層として積める**
+
+ということです。
+
+## memory とこの章の関係
+
+memory は保存するだけでは意味がありません。
+
+モデル入力に再び入って初めて、agent の行動に効いてきます。
+
+だから:
+
+- `s09` で記憶する
+- `s10` で入力に組み込む
+
+という流れになります。
+
+## 初学者が混乱しやすい点
+
+### 1. system prompt を固定文字列だと思う
+
+### 2. 毎回変わる情報も全部同じ塊に入れる
+
+### 3. skills、memory、`CLAUDE.md` を同じものとして扱う
+
+似て見えても責務は違います。
+
+- `skills`: 任意の能力パッケージ
+- `memory`: セッションをまたぐ事実
+- `CLAUDE.md`: 立ち続ける指示文書
+
+## Try It
+
+```sh
+cd learn-claude-code
+python agents/s10_system_prompt.py
+```
diff --git a/docs/ja/s10-team-protocols.md b/docs/ja/s10-team-protocols.md
deleted file mode 100644
index fd19562d9..000000000
--- a/docs/ja/s10-team-protocols.md
+++ /dev/null
@@ -1,106 +0,0 @@
-# s10: Team Protocols
-
-`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > [ s10 ] s11 > s12`
-
-> *"チームメイト間には統一の通信ルールが必要"* -- 1つの request-response パターンが全交渉を駆動。
->
-> **Harness 層**: プロトコル -- モデル間の構造化されたハンドシェイク。
-
-## 問題
-
-s09ではチームメイトが作業し通信するが、構造化された協調がない:
-
-**シャットダウン**: スレッドを強制終了するとファイルが中途半端に書かれ、config.jsonが不正な状態になる。ハンドシェイクが必要 -- リーダーが要求し、チームメイトが承認(完了して退出)か拒否(作業継続)する。
-
-**プラン承認**: リーダーが「認証モジュールをリファクタリングして」と言うと、チームメイトは即座に開始する。リスクの高い変更では、実行前にリーダーが計画をレビューすべきだ。
-
-両方とも同じ構造: 一方がユニークIDを持つリクエストを送り、他方がそのIDで応答する。
-
-## 解決策
-
-```
-Shutdown Protocol            Plan Approval Protocol
-==================           ======================
-
-Lead             Teammate    Teammate           Lead
-  |                 |           |                 |
-  |--shutdown_req-->|           |--plan_req------>|
-  | {req_id:"abc"}  |           | {req_id:"xyz"}  |
-  |                 |           |                 |
-  |<--shutdown_resp-|           |<--plan_resp-----|
-  | {req_id:"abc",  |           | {req_id:"xyz",  |
-  |  approve:true}  |           |  approve:true}  |
-
-Shared FSM:
-  [pending] --approve--> [approved]
-  [pending] --reject---> [rejected]
-
-Trackers:
-  shutdown_requests = {req_id: {target, status}}
-  plan_requests     = {req_id: {from, plan, status}}
-```
-
-## 仕組み
-
-1. リーダーがrequest_idを生成し、インボックス経由でシャットダウンを開始する。
-
-```python
-shutdown_requests = {}
-
-def handle_shutdown_request(teammate: str) -> str:
-    req_id = str(uuid.uuid4())[:8]
-    shutdown_requests[req_id] = {"target": teammate, "status": "pending"}
-    BUS.send("lead", teammate, "Please shut down gracefully.",
-             "shutdown_request", {"request_id": req_id})
-    return f"Shutdown request {req_id} sent (status: pending)"
-```
-
-2. チームメイトがリクエストを受信し、承認または拒否で応答する。
-
-```python
-if tool_name == "shutdown_response":
-    req_id = args["request_id"]
-    approve = args["approve"]
-    shutdown_requests[req_id]["status"] = "approved" if approve else "rejected"
-    BUS.send(sender, "lead", args.get("reason", ""),
-             "shutdown_response",
-             {"request_id": req_id, "approve": approve})
-```
-
-3. プラン承認も同一パターン。チームメイトがプランを提出(request_idを生成)、リーダーがレビュー(同じrequest_idを参照)。
-
-```python
-plan_requests = {}
-
-def handle_plan_review(request_id, approve, feedback=""):
-    req = plan_requests[request_id]
-    req["status"] = "approved" if approve else "rejected"
-    BUS.send("lead", req["from"], feedback,
-             "plan_approval_response",
-             {"request_id": request_id, "approve": approve})
-```
-
-1つのFSM、2つの応用。同じ`pending -> approved | rejected`状態機械が、あらゆるリクエスト-レスポンスプロトコルに適用できる。
-
-## s09からの変更点
-
-| Component      | Before (s09)     | After (s10)                  |
-|----------------|------------------|------------------------------|
-| Tools          | 9                | 12 (+shutdown_req/resp +plan)|
-| Shutdown       | Natural exit only| Request-response handshake   |
-| Plan gating    | None             | Submit/review with approval  |
-| Correlation    | None             | request_id per request       |
-| FSM            | None             | pending -> approved/rejected |
-
-## 試してみる
-
-```sh
-cd learn-claude-code
-python agents/s10_team_protocols.py
-```
-
-1. `Spawn alice as a coder. Then request her shutdown.`
-2. `List teammates to see alice's status after shutdown approval`
-3. `Spawn bob with a risky refactoring task. Review and reject his plan.`
-4. `Spawn charlie, have him submit a plan, then approve it.`
-5. `/team`と入力してステータスを監視する
diff --git a/docs/ja/s10a-message-prompt-pipeline.md b/docs/ja/s10a-message-prompt-pipeline.md
new file mode 100644
index 000000000..3866b81d6
--- /dev/null
+++ b/docs/ja/s10a-message-prompt-pipeline.md
@@ -0,0 +1,127 @@
+# s10a: Message / Prompt 組み立てパイプライン
+
+> これは `s10` を補う橋渡し文書です。  
+> ここでの問いは:
+>
+> **モデルが実際に見る入力は、system prompt 1 本だけなのか。**
+
+## 結論
+
+違います。
+
+高完成度の system では、モデル入力は複数 source の合成物です。
+
+たとえば:
+
+- stable system prompt blocks
+- normalized messages
+- memory section
+- dynamic reminders
+- tool instructions
+
+つまり system prompt は大事ですが、**入力全体の一部**です。
+
+## 最小の心智モデル
+
+```text
+stable rules
+  +
+tool surface
+  +
+memory / CLAUDE.md / skills
+  +
+normalized messages
+  +
+dynamic reminders
+  =
+final model input
+```
+
+## 主要な構造
+
+### `PromptParts`
+
+入力 source を組み立て前に分けて持つ構造です。
+
+```python
+parts = {
+    "core": "...",
+    "tools": "...",
+    "memory": "...",
+    "skills": "...",
+    "dynamic": "...",
+}
+```
+
+### `SystemPromptBlock`
+
+1 本の巨大文字列ではなく、section 単位で扱うための単位です。
+
+```python
+block = {
+    "text": "...",
+    "cache_scope": None,
+}
+```
+
+### `NormalizedMessage`
+
+API に渡す前に整えられた messages です。
+
+```python
+{
+    "role": "user",
+    "content": [
+        {"type": "text", "text": "..."}
+    ],
+}
+```
+
+## なぜ分ける必要があるか
+
+### 1. 何が stable で何が dynamic かを分けるため
+
+- system rules は比較的 stable
+- current messages は dynamic
+- reminders はより短命
+
+### 2. どの source が何を足しているか追えるようにするため
+
+source を混ぜて 1 本にすると:
+
+- memory がどこから来たか
+- skill がいつ入ったか
+- reminder がなぜ入ったか
+
+が見えにくくなります。
+
+### 3. compact / recovery / retry の説明がしやすくなるため
+
+入力 source が分かれていると:
+
+- 何を再利用するか
+- 何を要約するか
+- 何を次ターンで作り直すか
+
+が明確になります。
+
+## 初学者が混ぜやすい境界
+
+### `Message` と `PromptBlock`
+
+- `Message`: 会話履歴
+- `PromptBlock`: system 側の説明断片
+
+### `Memory` と `Prompt`
+
+- memory は内容 source
+- prompt pipeline は source を組む仕組み
+
+### `Tool instructions` と `Messages`
+
+- tool instructions は model が使える surface の説明
+- messages は今まで起きた対話 / 結果
+
+## 一文で覚える
+
+**system prompt は入力の全部ではなく、複数 source を束ねた pipeline の 1 つの section です。**
diff --git a/docs/ja/s11-autonomous-agents.md b/docs/ja/s11-autonomous-agents.md
deleted file mode 100644
index 4bc690e61..000000000
--- a/docs/ja/s11-autonomous-agents.md
+++ /dev/null
@@ -1,142 +0,0 @@
-# s11: Autonomous Agents
-
-`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > [ s11 ] s12`
-
-> *"チームメイトが自らボードを見て、仕事を取る"* -- リーダーが逐一割り振る必要はない。
->
-> **Harness 層**: 自律 -- 指示なしで仕事を見つけるモデル。
-
-## 問題
-
-s09-s10では、チームメイトは明示的に指示された時のみ作業する。リーダーは各チームメイトを特定のプロンプトでspawnしなければならない。タスクボードに未割り当てのタスクが10個あっても、リーダーが手動で各タスクを割り当てる。これはスケールしない。
-
-真の自律性とは、チームメイトが自分で作業を見つけること: タスクボードをスキャンし、未確保のタスクを確保し、作業し、完了したら次を探す。
-
-もう1つの問題: コンテキスト圧縮(s06)後にエージェントが自分の正体を忘れる可能性がある。アイデンティティ再注入がこれを解決する。
-
-## 解決策
-
-```
-Teammate lifecycle with idle cycle:
-
-+-------+
-| spawn |
-+---+---+
-    |
-    v
-+-------+   tool_use     +-------+
-| WORK  | <------------- |  LLM  |
-+---+---+                +-------+
-    |
-    | stop_reason != tool_use (or idle tool called)
-    v
-+--------+
-|  IDLE  |  poll every 5s for up to 60s
-+---+----+
-    |
-    +---> check inbox --> message? ----------> WORK
-    |
-    +---> scan .tasks/ --> unclaimed? -------> claim -> WORK
-    |
-    +---> 60s timeout ----------------------> SHUTDOWN
-
-Identity re-injection after compression:
-  if len(messages) <= 3:
-    messages.insert(0, identity_block)
-```
-
-## 仕組み
-
-1. チームメイトのループはWORKとIDLEの2フェーズ。LLMがツール呼び出しを止めた時(または`idle`ツールを呼んだ時)、IDLEフェーズに入る。
-
-```python
-def _loop(self, name, role, prompt):
-    while True:
-        # -- WORK PHASE --
-        messages = [{"role": "user", "content": prompt}]
-        for _ in range(50):
-            response = client.messages.create(...)
-            if response.stop_reason != "tool_use":
-                break
-            # execute tools...
-            if idle_requested:
-                break
-
-        # -- IDLE PHASE --
-        self._set_status(name, "idle")
-        resume = self._idle_poll(name, messages)
-        if not resume:
-            self._set_status(name, "shutdown")
-            return
-        self._set_status(name, "working")
-```
-
-2. IDLEフェーズがインボックスとタスクボードをポーリングする。
-
-```python
-def _idle_poll(self, name, messages):
-    for _ in range(IDLE_TIMEOUT // POLL_INTERVAL):  # 60s / 5s = 12
-        time.sleep(POLL_INTERVAL)
-        inbox = BUS.read_inbox(name)
-        if inbox:
-            messages.append({"role": "user",
-                "content": f"<inbox>{inbox}</inbox>"})
-            return True
-        unclaimed = scan_unclaimed_tasks()
-        if unclaimed:
-            claim_task(unclaimed[0]["id"], name)
-            messages.append({"role": "user",
-                "content": f"<auto-claimed>Task #{unclaimed[0]['id']}: "
-                           f"{unclaimed[0]['subject']}</auto-claimed>"})
-            return True
-    return False  # timeout -> shutdown
-```
-
-3. タスクボードスキャン: pendingかつ未割り当てかつブロックされていないタスクを探す。
-
-```python
-def scan_unclaimed_tasks() -> list:
-    unclaimed = []
-    for f in sorted(TASKS_DIR.glob("task_*.json")):
-        task = json.loads(f.read_text())
-        if (task.get("status") == "pending"
-                and not task.get("owner")
-                and not task.get("blockedBy")):
-            unclaimed.append(task)
-    return unclaimed
-```
-
-4. アイデンティティ再注入: コンテキストが短すぎる(圧縮が起きた)場合にアイデンティティブロックを挿入する。
-
-```python
-if len(messages) <= 3:
-    messages.insert(0, {"role": "user",
-        "content": f"<identity>You are '{name}', role: {role}, "
-                   f"team: {team_name}. Continue your work.</identity>"})
-    messages.insert(1, {"role": "assistant",
-        "content": f"I am {name}. Continuing."})
-```
-
-## s10からの変更点
-
-| Component      | Before (s10)     | After (s11)                |
-|----------------|------------------|----------------------------|
-| Tools          | 12               | 14 (+idle, +claim_task)    |
-| Autonomy       | Lead-directed    | Self-organizing            |
-| Idle phase     | None             | Poll inbox + task board    |
-| Task claiming  | Manual only      | Auto-claim unclaimed tasks |
-| Identity       | System prompt    | + re-injection after compress|
-| Timeout        | None             | 60s idle -> auto shutdown  |
-
-## 試してみる
-
-```sh
-cd learn-claude-code
-python agents/s11_autonomous_agents.py
-```
-
-1. `Create 3 tasks on the board, then spawn alice and bob. Watch them auto-claim.`
-2. `Spawn a coder teammate and let it find work from the task board itself`
-3. `Create tasks with dependencies. Watch teammates respect the blocked order.`
-4. `/tasks`と入力してオーナー付きのタスクボードを確認する
-5. `/team`と入力して誰が作業中でアイドルかを監視する
diff --git a/docs/ja/s11-error-recovery.md b/docs/ja/s11-error-recovery.md
new file mode 100644
index 000000000..ee9e62345
--- /dev/null
+++ b/docs/ja/s11-error-recovery.md
@@ -0,0 +1,396 @@
+# s11: Error Recovery
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > [ s11 ] > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
+
+> *error は例外イベントではなく、main loop が最初から用意しておくべき通常分岐です。*
+
+## この章が解く問題
+
+`s10` まで来ると agent はもう demo ではありません。
+
+すでに system には、
+
+- main loop
+- tool use
+- planning
+- compaction
+- permission
+- hook
+- memory
+- prompt assembly
+
+があります。
+
+こうなると failure も自然に増えます。
+
+- model output が途中で切れる
+- context が大きすぎて request が入らない
+- API timeout や rate limit で一時的に失敗する
+
+もし recovery がなければ、main loop は最初の失敗で止まります。
+
+そして初心者はよく、
+
+> agent が不安定なのは model が弱いからだ
+
+と誤解します。
+
+しかし実際には多くの failure は、
+
+**task そのものが失敗したのではなく、この turn の続け方を変える必要があるだけ**
+
+です。
+
+この章の目標は 1 つです。
+
+**「error が出たら停止」から、「error の種類を見て recovery path を選ぶ」へ進むこと**
+
+です。
+
+## 併読すると楽になる資料
+
+- 今の query がなぜまだ続いているのか見失ったら [`s00c-query-transition-model.md`](./s00c-query-transition-model.md)
+- compact と recovery が同じ mechanism に見えたら [`s06-context-compact.md`](./s06-context-compact.md)
+- このあと `s12` へ進む前に、recovery state と durable task state を混ぜたくなったら [`data-structures.md`](./data-structures.md)
+
+## 先に言葉をそろえる
+
+### recovery とは何か
+
+recovery は「error をなかったことにする」ことではありません。
+
+意味は次です。
+
+- これは一時的 failure かを判定する
+- 一時的なら有限回の補救動作を試す
+- だめなら明示的に fail として返す
+
+### retry budget とは何か
+
+retry budget は、
+
+> 最大で何回までこの recovery path を試すか
+
+です。
+
+例:
+
+- continuation は最大 3 回
+- transport retry は最大 3 回
+
+これがないと loop が無限に回る危険があります。
+
+### state machine とは何か
+
+この章での state machine は難しい theory ではありません。
+
+単に、
+
+> normal execution と各 recovery branch を、明確な状態遷移として見ること
+
+です。
+
+この章から query の進行は次のように見えるようになります。
+
+- normal
+- continue after truncation
+- compact then retry
+- backoff then retry
+- final fail
+
+## 最小心智モデル
+
+最初は 3 種類の failure だけ区別できれば十分です。
+
+```text
+1. output truncated
+   model はまだ言い終わっていないが token が尽きた
+
+2. context too large
+   request 全体が model window に入らない
+
+3. transient transport failure
+   timeout / rate limit / temporary connection issue
+```
+
+それぞれに対応する recovery path はこうです。
+
+```text
+LLM call
+  |
+  +-- stop_reason == "max_tokens"
+  |      -> continuation message を入れる
+  |      -> retry
+  |
+  +-- prompt too long
+  |      -> compact する
+  |      -> retry
+  |
+  +-- timeout / rate limit / connection error
+         -> 少し待つ
+         -> retry
+```
+
+これが最小ですが、十分に正しい recovery model です。
+
+## この章の核になるデータ構造
+
+### 1. Recovery State
+
+```python
+recovery_state = {
+    "continuation_attempts": 0,
+    "compact_attempts": 0,
+    "transport_attempts": 0,
+}
+```
+
+役割は 2 つあります。
+
+- 各 recovery path ごとの retry 回数を分けて数える
+- 無限 recovery を防ぐ
+
+### 2. Recovery Decision
+
+```python
+{
+    "kind": "continue" | "compact" | "backoff" | "fail",
+    "reason": "why this branch was chosen",
+}
+```
+
+ここで大事なのは、
+
+**error の見た目と、次に選ぶ動作を分ける**
+
+ことです。
+
+この分離があると loop が読みやすくなります。
+
+### 3. Continuation Message
+
+```python
+CONTINUE_MESSAGE = (
+    "Output limit hit. Continue directly from where you stopped. "
+    "Do not restart or repeat."
+)
+```
+
+この message は地味ですが非常に重要です。
+
+なぜなら model は「続けて」とだけ言うと、
+
+- 最初から言い直す
+- もう一度要約し直す
+- 直前の内容を繰り返す
+
+ことがあるからです。
+
+## 最小実装を段階で追う
+
+### 第 1 段階: recovery chooser を作る
+
+```python
+def choose_recovery(stop_reason: str | None, error_text: str | None) -> dict:
+    if stop_reason == "max_tokens":
+        return {"kind": "continue", "reason": "output truncated"}
+
+    if error_text and "prompt" in error_text and "long" in error_text:
+        return {"kind": "compact", "reason": "context too large"}
+
+    if error_text and any(word in error_text for word in [
+        "timeout", "rate", "unavailable", "connection"
+    ]):
+        return {"kind": "backoff", "reason": "transient transport failure"}
+
+    return {"kind": "fail", "reason": "unknown or non-recoverable error"}
+```
+
+この関数がやっている本質は、
+
+**まず分類し、そのあと branch を返す**
+
+という 1 点です。
+
+### 第 2 段階: main loop に差し込む
+
+```python
+while True:
+    try:
+        response = client.messages.create(...)
+        decision = choose_recovery(response.stop_reason, None)
+    except Exception as e:
+        response = None
+        decision = choose_recovery(None, str(e).lower())
+
+    if decision["kind"] == "continue":
+        messages.append({"role": "user", "content": CONTINUE_MESSAGE})
+        continue
+
+    if decision["kind"] == "compact":
+        messages = auto_compact(messages)
+        continue
+
+    if decision["kind"] == "backoff":
+        time.sleep(backoff_delay(...))
+        continue
+
+    if decision["kind"] == "fail":
+        break
+
+    # normal tool handling
+```
+
+ここで一番大事なのは、
+
+- catch したら即 stop
+
+ではなく、
+
+- 何の失敗かを見る
+- どの recovery path を試すか決める
+
+という構造です。
+
+## 3 つの主 recovery path が埋めている穴
+
+### 1. continuation
+
+これは「model が言い終わる前に output budget が切れた」問題を埋めます。
+
+本質は、
+
+> task が失敗したのではなく、1 turn の出力空間が足りなかった
+
+ということです。
+
+最小形はこうです。
+
+```python
+if response.stop_reason == "max_tokens":
+    if state["continuation_attempts"] >= 3:
+        return "Error: output recovery exhausted"
+    state["continuation_attempts"] += 1
+    messages.append({"role": "user", "content": CONTINUE_MESSAGE})
+    continue
+```
+
+### 2. compact
+
+これは「task が無理」ではなく、
+
+> active context が大きすぎて request が入らない
+
+ときに使います。
+
+ここで大事なのは、compact を delete と考えないことです。
+
+compact は、
+
+**過去を、そのままの原文ではなく、まだ続行可能な summary へ変換する**
+
+操作です。
+
+最小例:
+
+```python
+def auto_compact(messages: list) -> list:
+    summary = summarize_messages(messages)
+    return [{
+        "role": "user",
+        "content": "This session was compacted. Continue from this summary:\n" + summary,
+    }]
+```
+
+最低限 summary に残したいのは次です。
+
+- 今の task は何か
+- 何をすでに終えたか
+- 重要 decision は何か
+- 次に何をするつもりか
+
+### 3. backoff
+
+これは timeout、rate limit、temporary connection issue のような
+
+**時間を置けば通るかもしれない failure**
+
+に対して使います。
+
+考え方は単純です。
+
+```python
+if decision["kind"] == "backoff":
+    if state["transport_attempts"] >= 3:
+        break
+    state["transport_attempts"] += 1
+    time.sleep(backoff_delay(state["transport_attempts"]))
+    continue
+```
+
+ここで大切なのは「retry すること」よりも、
+
+**retry にも budget があり、同じ速度で無限に叩かないこと**
+
+です。
+
+## compact と recovery を混ぜない
+
+これは初学者が特に混ぜやすい点です。
+
+- `s06` の compact は context hygiene のために行うことがある
+- `s11` の compact recovery は request failure から戻るために行う
+
+同じ compact という操作でも、
+
+**目的が違います。**
+
+目的が違えば、それを呼ぶ branch も別に見るべきです。
+
+## recovery は query の continuation 理由でもある
+
+`s11` の重要な学びは、error handling を `except` の奥へ隠さないことです。
+
+むしろ次を explicit に持つ方が良いです。
+
+- なぜまだ続いているのか
+- 何回その branch を試したのか
+- 次にどの branch を試すのか
+
+すると recovery は hidden plumbing ではなく、
+
+**query transition を説明する状態**
+
+になります。
+
+## 初学者が混ぜやすいポイント
+
+### 1. すべての failure に同じ retry をかける
+
+truncation と transport error は同じ問題ではありません。
+
+### 2. retry budget を持たない
+
+無限 loop の原因になります。
+
+### 3. compact と recovery を 1 つの話にしてしまう
+
+context hygiene と failure recovery は目的が違います。
+
+### 4. continuation message を曖昧にする
+
+「続けて」だけでは model が restart / repeat しやすいです。
+
+### 5. なぜ続行しているのかを state に残さない
+
+debug も teaching も急に難しくなります。
+
+## この章を読み終えたら何が言えるべきか
+
+1. 多くの error は task failure ではなく、「この turn の続け方を変えるべき」信号である
+2. recovery は `continue / compact / backoff / fail` の branch として考えられる
+3. recovery path ごとに budget を持たないと loop が壊れやすい
+
+## 一文で覚える
+
+**Error Recovery とは、failure を見た瞬間に止まるのではなく、failure の種類に応じて continuation path を選び直す control layer です。**
diff --git a/docs/ja/s07-task-system.md b/docs/ja/s12-task-system.md
similarity index 76%
rename from docs/ja/s07-task-system.md
rename to docs/ja/s12-task-system.md
index 0a500a87c..62c0a4fbd 100644
--- a/docs/ja/s07-task-system.md
+++ b/docs/ja/s12-task-system.md
@@ -1,6 +1,6 @@
-# s07: Task System
+# s12: Task System
 
-`s01 > s02 > s03 > s04 > s05 > s06 | [ s07 ] s08 > s09 > s10 > s11 > s12`
+`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > [ s12 ]`
 
 > *"大きな目標を小タスクに分解し、順序付けし、ディスクに記録する"* -- ファイルベースのタスクグラフ、マルチエージェント協調の基盤。
 >
@@ -12,6 +12,12 @@ s03のTodoManagerはメモリ上のフラットなチェックリストに過ぎ
 
 明示的な関係がなければ、エージェントは何が実行可能で、何がブロックされ、何が同時に走れるかを判断できない。しかもリストはメモリ上にしかないため、コンテキスト圧縮(s06)で消える。
 
+## 主線とどう併読するか
+
+- `s03` からそのまま来たなら、[`data-structures.md`](./data-structures.md) へ戻って `TodoItem` / `PlanState` と `TaskRecord` を分けます。
+- object 境界が混ざり始めたら、[`entity-map.md`](./entity-map.md) で message、task、runtime task、teammate を分離してから戻ります。
+- 次に `s13` を読むなら、[`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) を横に置いて、durable task と runtime task を同じ言葉で潰さないようにします。
+
 ## 解決策
 
 フラットなチェックリストをディスクに永続化する**タスクグラフ**に昇格させる。各タスクは1つのJSONファイルで、ステータス・前方依存(`blockedBy`)を持つ。タスクグラフは常に3つの問いに答える:
@@ -44,7 +50,7 @@ s03のTodoManagerはメモリ上のフラットなチェックリストに過ぎ
 ステータス: pending -> in_progress -> completed
 ```
 
-このタスクグラフは s07 以降の全メカニズムの協調バックボーンとなる: バックグラウンド実行(s08)、マルチエージェントチーム(s09+)、worktree分離(s12)はすべてこの同じ構造を読み書きする。
+このタスクグラフは後続の runtime / platform 章の協調バックボーンになる: バックグラウンド実行(`s13`)、マルチエージェントチーム(`s15+`)、worktree 分離(`s18`)はすべてこの durable な構造の恩恵を受ける。
 
 ## 仕組み
 
@@ -106,11 +112,11 @@ TOOL_HANDLERS = {
 }
 ```
 
-s07以降、タスクグラフがマルチステップ作業のデフォルト。s03のTodoは軽量な単一セッション用チェックリストとして残る。
+`s12` 以降、タスクグラフが durable なマルチステップ作業のデフォルトになる。`s03` の Todo は軽量な単一セッション用チェックリストとして残る。
 
 ## s06からの変更点
 
-| コンポーネント | Before (s06) | After (s07) |
+| コンポーネント | Before (s06) | After (s12) |
 |---|---|---|
 | Tools | 5 | 8 (`task_create/update/list/get`) |
 | 計画モデル | フラットチェックリスト (メモリ) | 依存関係付きタスクグラフ (ディスク) |
@@ -122,10 +128,23 @@ s07以降、タスクグラフがマルチステップ作業のデフォルト
 
 ```sh
 cd learn-claude-code
-python agents/s07_task_system.py
+python agents/s12_task_system.py
 ```
 
 1. `Create 3 tasks: "Setup project", "Write code", "Write tests". Make them depend on each other in order.`
 2. `List all tasks and show the dependency graph`
 3. `Complete task 1 and then list tasks to see task 2 unblocked`
 4. `Create a task board for refactoring: parse -> transform -> emit -> test, where transform and emit can run in parallel after parse`
+
+## 教学上の境界
+
+このリポジトリで本当に重要なのは、完全な製品向け保存層の再現ではありません。
+
+重要なのは:
+
+- durable なタスク記録
+- 明示的な依存エッジ
+- 分かりやすい状態遷移
+- 後続章が再利用できる構造
+
+この 4 点を自分で実装できれば、タスクシステムの核心はつかめています。
diff --git a/docs/ja/s12-worktree-task-isolation.md b/docs/ja/s12-worktree-task-isolation.md
deleted file mode 100644
index 380422c52..000000000
--- a/docs/ja/s12-worktree-task-isolation.md
+++ /dev/null
@@ -1,121 +0,0 @@
-# s12: Worktree + Task Isolation
-
-`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > [ s12 ]`
-
-> *"各自のディレクトリで作業し、互いに干渉しない"* -- タスクは目標を管理、worktree はディレクトリを管理、IDで紐付け。
->
-> **Harness 層**: ディレクトリ隔離 -- 決して衝突しない並列実行レーン。
-
-## 問題
-
-s11までにエージェントはタスクを自律的に確保して完了できるようになった。しかし全タスクが1つの共有ディレクトリで走る。2つのエージェントが同時に異なるモジュールをリファクタリングすると衝突する: 片方が`config.py`を編集し、もう片方も`config.py`を編集し、未コミットの変更が混ざり合い、どちらもクリーンにロールバックできない。
-
-タスクボードは*何をやるか*を追跡するが、*どこでやるか*には関知しない。解決策: 各タスクに専用のgit worktreeディレクトリを与える。タスクが目標を管理し、worktreeが実行コンテキストを管理する。タスクIDで紐付ける。
-
-## 解決策
-
-```
-Control plane (.tasks/)             Execution plane (.worktrees/)
-+------------------+                +------------------------+
-| task_1.json      |                | auth-refactor/         |
-|   status: in_progress  <------>   branch: wt/auth-refactor
-|   worktree: "auth-refactor"   |   task_id: 1             |
-+------------------+                +------------------------+
-| task_2.json      |                | ui-login/              |
-|   status: pending    <------>     branch: wt/ui-login
-|   worktree: "ui-login"       |   task_id: 2             |
-+------------------+                +------------------------+
-                                    |
-                          index.json (worktree registry)
-                          events.jsonl (lifecycle log)
-
-State machines:
-  Task:     pending -> in_progress -> completed
-  Worktree: absent  -> active      -> removed | kept
-```
-
-## 仕組み
-
-1. **タスクを作成する。** まず目標を永続化する。
-
-```python
-TASKS.create("Implement auth refactor")
-# -> .tasks/task_1.json  status=pending  worktree=""
-```
-
-2. **worktreeを作成してタスクに紐付ける。** `task_id`を渡すと、タスクが自動的に`in_progress`に遷移する。
-
-```python
-WORKTREES.create("auth-refactor", task_id=1)
-# -> git worktree add -b wt/auth-refactor .worktrees/auth-refactor HEAD
-# -> index.json gets new entry, task_1.json gets worktree="auth-refactor"
-```
-
-紐付けは両側に状態を書き込む:
-
-```python
-def bind_worktree(self, task_id, worktree):
-    task = self._load(task_id)
-    task["worktree"] = worktree
-    if task["status"] == "pending":
-        task["status"] = "in_progress"
-    self._save(task)
-```
-
-3. **worktree内でコマンドを実行する。** `cwd`が分離ディレクトリを指す。
-
-```python
-subprocess.run(command, shell=True, cwd=worktree_path,
-               capture_output=True, text=True, timeout=300)
-```
-
-4. **終了処理。** 2つの選択肢:
-   - `worktree_keep(name)` -- ディレクトリを保持する。
-   - `worktree_remove(name, complete_task=True)` -- ディレクトリを削除し、紐付けられたタスクを完了し、イベントを発行する。1回の呼び出しで後片付けと完了を処理する。
-
-```python
-def remove(self, name, force=False, complete_task=False):
-    self._run_git(["worktree", "remove", wt["path"]])
-    if complete_task and wt.get("task_id") is not None:
-        self.tasks.update(wt["task_id"], status="completed")
-        self.tasks.unbind_worktree(wt["task_id"])
-        self.events.emit("task.completed", ...)
-```
-
-5. **イベントストリーム。** ライフサイクルの各ステップが`.worktrees/events.jsonl`に記録される:
-
-```json
-{
-  "event": "worktree.remove.after",
-  "task": {"id": 1, "status": "completed"},
-  "worktree": {"name": "auth-refactor", "status": "removed"},
-  "ts": 1730000000
-}
-```
-
-発行されるイベント: `worktree.create.before/after/failed`, `worktree.remove.before/after/failed`, `worktree.keep`, `task.completed`。
-
-クラッシュ後も`.tasks/` + `.worktrees/index.json`から状態を再構築できる。会話メモリは揮発性だが、ファイル状態は永続的だ。
-
-## s11からの変更点
-
-| Component          | Before (s11)               | After (s12)                                  |
-|--------------------|----------------------------|----------------------------------------------|
-| Coordination       | Task board (owner/status)  | Task board + explicit worktree binding       |
-| Execution scope    | Shared directory           | Task-scoped isolated directory               |
-| Recoverability     | Task status only           | Task status + worktree index                 |
-| Teardown           | Task completion            | Task completion + explicit keep/remove       |
-| Lifecycle visibility | Implicit in logs         | Explicit events in `.worktrees/events.jsonl` |
-
-## 試してみる
-
-```sh
-cd learn-claude-code
-python agents/s12_worktree_task_isolation.py
-```
-
-1. `Create tasks for backend auth and frontend login page, then list tasks.`
-2. `Create worktree "auth-refactor" for task 1, then bind task 2 to a new worktree "ui-login".`
-3. `Run "git status --short" in worktree "auth-refactor".`
-4. `Keep worktree "ui-login", then list worktrees and inspect events.`
-5. `Remove worktree "auth-refactor" with complete_task=true, then list tasks/worktrees/events.`
diff --git a/docs/ja/s13-background-tasks.md b/docs/ja/s13-background-tasks.md
new file mode 100644
index 000000000..9d60025cd
--- /dev/null
+++ b/docs/ja/s13-background-tasks.md
@@ -0,0 +1,390 @@
+# s13: バックグラウンドタスク
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > [ s13 ] > s14 > s15 > s16 > s17 > s18 > s19`
+
+> *遅い command は横で待たせればよく、main loop まで一緒に止まる必要はありません。*
+
+## この章が解く問題
+
+前の章までの tool call は、基本的に次の形でした。
+
+```text
+model が tool を要求する
+  ->
+すぐ実行する
+  ->
+すぐ結果を返す
+```
+
+短い command ならこれで問題ありません。
+
+でも次のような処理はすぐに詰まります。
+
+- `npm install`
+- `pytest`
+- `docker build`
+- 重い code generation
+- 長時間の lint / typecheck
+
+もし main loop がその完了を同期的に待ち続けると、2 つの問題が起きます。
+
+- model は待ち時間のあいだ次の判断へ進めない
+- user は別の軽い作業を進めたいのに、agent 全体が足止めされる
+
+この章で入れるのは、
+
+**遅い実行を background へ逃がし、main loop は次の仕事へ進めるようにすること**
+
+です。
+
+## 併読すると楽になる資料
+
+- `task goal` と `live execution slot` がまだ混ざるなら [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)
+- `RuntimeTaskRecord` と task board の境界を見直したいなら [`data-structures.md`](./data-structures.md)
+- background execution が「別の main loop」に見えてきたら [`s02b-tool-execution-runtime.md`](./s02b-tool-execution-runtime.md)
+
+## 先に言葉をそろえる
+
+### foreground とは何か
+
+ここで言う foreground は、
+
+> この turn の中で今すぐ結果が必要なので、main loop がその場で待つ実行
+
+です。
+
+### background とは何か
+
+background は謎の裏世界ではありません。
+
+意味は単純で、
+
+> command を別の execution line に任せ、main loop は先に別のことを進める
+
+ことです。
+
+### 通知キューとは何か
+
+background task が終わっても、その完全な出力をいきなり model へ丸ごと押し込む必要はありません。
+
+いったん queue に要約通知として積み、
+
+> 次の model call の直前にまとめて main loop へ戻す
+
+のが分かりやすい設計です。
+
+## 最小心智モデル
+
+この章で最も大切な 1 文は次です。
+
+**並行になるのは実行と待機であって、main loop 自体が増えるわけではありません。**
+
+図にするとこうです。
+
+```text
+Main loop
+  |
+  +-- background_run("pytest")
+  |      -> すぐ task_id を返す
+  |
+  +-- そのまま別の仕事を続ける
+  |
+  +-- 次の model call の前
+         -> drain_notifications()
+         -> 結果要約を messages へ注入
+
+Background lane
+  |
+  +-- 実際に subprocess を実行
+  +-- 終了後に result preview を queue へ積む
+```
+
+この図を保ったまま理解すれば、後でもっと複雑な runtime へ進んでも心智が崩れにくくなります。
+
+## この章の核になるデータ構造
+
+### 1. RuntimeTaskRecord
+
+この章で扱う background task は durable task board の task とは別物です。
+
+教材コードでは、background 実行はおおむね次の record を持ちます。
+
+```python
+task = {
+    "id": "a1b2c3d4",
+    "command": "pytest",
+    "status": "running",
+    "started_at": 1710000000.0,
+    "finished_at": None,
+    "result_preview": "",
+    "output_file": ".runtime-tasks/a1b2c3d4.log",
+}
+```
+
+各 field の意味は次の通りです。
+
+- `id`: runtime slot の識別子
+- `command`: 今走っている command
+- `status`: `running` / `completed` / `timeout` / `error`
+- `started_at`: いつ始まったか
+- `finished_at`: いつ終わったか
+- `result_preview`: model に戻す短い要約
+- `output_file`: 完全出力の保存先
+
+教材版ではこれを disk 上にも分けて残します。
+
+```text
+.runtime-tasks/
+  a1b2c3d4.json
+  a1b2c3d4.log
+```
+
+これで読者は、
+
+- `json` は状態 record
+- `log` は完全出力
+- model へ戻すのはまず preview
+
+という 3 層を自然に見分けられます。
+
+### 2. Notification
+
+background result はまず notification queue に入ります。
+
+```python
+notification = {
+    "task_id": "a1b2c3d4",
+    "status": "completed",
+    "command": "pytest",
+    "preview": "42 tests passed",
+    "output_file": ".runtime-tasks/a1b2c3d4.log",
+}
+```
+
+notification の役割は 1 つだけです。
+
+> main loop に「結果が戻ってきた」と知らせること
+
+ここに完全出力の全量を埋め込む必要はありません。
+
+## 最小実装を段階で追う
+
+### 第 1 段階: background manager を持つ
+
+最低限必要なのは次の 2 つの状態です。
+
+- `tasks`: いま存在する runtime task
+- `_notification_queue`: main loop にまだ回収されていない結果
+
+```python
+class BackgroundManager:
+    def __init__(self):
+        self.tasks = {}
+        self._notification_queue = []
+        self._lock = threading.Lock()
+```
+
+ここで lock を置いているのは、background thread と main loop が同じ queue / dict を触るからです。
+
+### 第 2 段階: `run()` はすぐ返す
+
+background 化の一番大きな変化はここです。
+
+```python
+def run(self, command: str) -> str:
+    task_id = str(uuid.uuid4())[:8]
+    self.tasks[task_id] = {
+        "id": task_id,
+        "status": "running",
+        "command": command,
+        "started_at": time.time(),
+    }
+
+    thread = threading.Thread(
+        target=self._execute,
+        args=(task_id, command),
+        daemon=True,
+    )
+    thread.start()
+    return task_id
+```
+
+重要なのは thread 自体より、
+
+**main loop が結果ではなく `task_id` を受け取り、先に進める**
+
+ことです。
+
+### 第 3 段階: subprocess が終わったら notification を積む
+
+```python
+def _execute(self, task_id: str, command: str):
+    try:
+        result = subprocess.run(..., timeout=300)
+        status = "completed"
+        preview = (result.stdout + result.stderr)[:500]
+    except subprocess.TimeoutExpired:
+        status = "timeout"
+        preview = "command timed out"
+
+    with self._lock:
+        self.tasks[task_id]["status"] = status
+        self._notification_queue.append({
+            "task_id": task_id,
+            "status": status,
+            "preview": preview,
+        })
+```
+
+ここでの設計意図ははっきりしています。
+
+- execution lane は command を実際に走らせる
+- notification queue は main loop へ戻すための要約を持つ
+
+役割を分けることで、result transport が見やすくなります。
+
+### 第 4 段階: 次の model call 前に queue を drain する
+
+```python
+def agent_loop(messages: list):
+    while True:
+        notifications = BG.drain_notifications()
+        if notifications:
+            notif_text = "\n".join(
+                f"[bg:{n['task_id']}] {n['preview']}" for n in notifications
+            )
+            messages.append({
+                "role": "user",
+                "content": f"<background-results>\n{notif_text}\n</background-results>",
+            })
+            messages.append({
+                "role": "assistant",
+                "content": "Noted background results.",
+            })
+```
+
+この構造が大切です。
+
+結果は「いつでも割り込んで model へ押し込まれる」のではなく、
+
+**次の model call の入口でまとめて注入される**
+
+からです。
+
+### 第 5 段階: preview と full output を分ける
+
+教材コードでは `result_preview` と `output_file` を分けています。
+
+これは初心者にも非常に大事な設計です。
+
+なぜなら background result にはしばしば次の問題があるからです。
+
+- 出力が長い
+- model に全量を見せる必要がない
+- user だけ詳細 log を見れば十分なことが多い
+
+そこでまず model には短い preview を返し、必要なら後で `read_file` 等で full log を読む形にします。
+
+### 第 6 段階: stalled task も見られるようにする
+
+教材コードは `STALL_THRESHOLD_S` を持ち、長く走りすぎている task を拾えます。
+
+```python
+def detect_stalled(self) -> list[str]:
+    now = time.time()
+    stalled = []
+    for task_id, info in self.tasks.items():
+        if info["status"] != "running":
+            continue
+        elapsed = now - info.get("started_at", now)
+        if elapsed > STALL_THRESHOLD_S:
+            stalled.append(task_id)
+    return stalled
+```
+
+ここで学ぶべき本質は sophisticated monitoring ではありません。
+
+**background 化したら「開始したまま返ってこないもの」を見張る観点が必要になる**
+
+ということです。
+
+## これは task board の task とは違う
+
+ここは混ざりやすいので強調します。
+
+`s12` の `task` は durable goal node です。
+
+一方この章の background task は、
+
+> いま実行中の live runtime slot
+
+です。
+
+同じ `task` という言葉を使っても指している層が違います。
+
+だから分からなくなったら、本文だけを往復せずに次へ戻るべきです。
+
+- [`entity-map.md`](./entity-map.md)
+- [`data-structures.md`](./data-structures.md)
+- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)
+
+## 前の章とどうつながるか
+
+この章は `s12` の durable task graph を否定する章ではありません。
+
+むしろ、
+
+- `s12` が「何の仕事が存在するか」を管理し
+- `s13` が「いまどの command が走っているか」を管理する
+
+という役割分担を教える章です。
+
+後の `s14`、`s17`、`s18` へ行く前に、
+
+**goal と runtime slot を分けて見る癖**
+
+をここで作っておくことが重要です。
+
+## 初学者が混ぜやすいポイント
+
+### 1. background execution を「もう 1 本の main loop」と考える
+
+実際に増えているのは subprocess waiting lane であって、main conversational loop ではありません。
+
+### 2. result を queue ではなく即座に messages へ乱暴に書き込む
+
+これでは model input の入口が分散し、system の流れが追いにくくなります。
+
+### 3. full output と preview を分けない
+
+長い log で context がすぐあふれます。
+
+### 4. runtime task と durable task を同一視する
+
+「いま走っている command」と「長く残る work goal」は別物です。
+
+### 5. queue 操作に lock を使わない
+
+background thread と main loop の競合で状態が壊れやすくなります。
+
+### 6. timeout / error を `completed` と同じように扱う
+
+戻すべき情報は同じではありません。終了理由は explicit に残すべきです。
+
+## 教学上の境界
+
+この章でまず理解すべき中心は、製品用の完全な async runtime ではありません。
+
+中心は次の 3 行です。
+
+- 遅い仕事を foreground から切り離す
+- 結果は notification として main loop に戻す
+- runtime slot は durable task board とは別層で管理する
+
+ここが腹落ちしてから、
+
+- より複雑な scheduler
+- 複数種類の background lane
+- 分散 worker
+
+へ進めば十分です。
diff --git a/docs/ja/s13a-runtime-task-model.md b/docs/ja/s13a-runtime-task-model.md
new file mode 100644
index 000000000..a82df1c45
--- /dev/null
+++ b/docs/ja/s13a-runtime-task-model.md
@@ -0,0 +1,262 @@
+# s13a: Runtime Task Model
+
+> この bridge doc はすぐに混ざる次の点をほどくためのものです。
+>
+> **work graph 上の task と、いま実行中の task は同じものではありません。**
+
+## 主線とどう併読するか
+
+次の順で読むのが最も分かりやすいです。
+
+- まず [`s12-task-system.md`](./s12-task-system.md) を読み、durable な work graph を固める
+- 次に [`s13-background-tasks.md`](./s13-background-tasks.md) を読み、background execution を見る
+- 用語が混ざり始めたら [`glossary.md`](./glossary.md) を見直す
+- field を正確に合わせたいなら [`data-structures.md`](./data-structures.md) と [`entity-map.md`](./entity-map.md) を見直す
+
+## なぜこの橋渡しが必要か
+
+主線自体は正しいです。
+
+- `s12` は task system
+- `s13` は background tasks
+
+ただし bridge layer を一枚挟まないと、読者は二種類の「task」をすぐに同じ箱へ入れてしまいます。
+
+例えば:
+
+- 「auth module を実装する」という work-graph task
+- 「pytest を走らせる」という background execution
+- 「alice がコード修正をしている」という teammate execution
+
+どれも日常語では task と呼べますが、同じ層にはありません。
+
+## 二つの全く違う task
+
+### 1. work-graph task
+
+これは `s12` の durable node です。
+
+答えるものは:
+
+- 何をやるか
+- どの仕事がどの仕事に依存するか
+- 誰が owner か
+- 進捗はどうか
+
+つまり:
+
+> 目標として管理される durable work unit
+
+です。
+
+### 2. runtime task
+
+こちらが答えるものは:
+
+- 今どの execution unit が生きているか
+- それが何の type か
+- running / completed / failed / killed のどれか
+- 出力がどこにあるか
+
+つまり:
+
+> runtime の中で生きている execution slot
+
+です。
+
+## 最小の心智モデル
+
+まず二つの表として分けて考えてください。
+
+```text
+work-graph task
+  - durable
+  - goal / dependency oriented
+  - 寿命が長い
+
+runtime task
+  - execution oriented
+  - output / status oriented
+  - 寿命が短い
+```
+
+両者の関係は「どちらか一方」ではありません。
+
+```text
+1 つの work-graph task
+  から
+1 個以上の runtime task が派生しうる
+```
+
+例えば:
+
+```text
+work-graph task:
+  "Implement auth module"
+
+runtime tasks:
+  1. background で test を走らせる
+  2. coder teammate を起動する
+  3. 外部 service を monitor する
+```
+
+## なぜこの区別が重要か
+
+この境界が崩れると、後続章がすぐに絡み始めます。
+
+- `s13` の background execution が `s12` の task board と混ざる
+- `s15-s17` の teammate work がどこにぶら下がるか不明になる
+- `s18` の worktree が何に紐づくのか曖昧になる
+
+最短の正しい要約はこれです。
+
+**work-graph task は目標を管理し、runtime task は実行を管理する**
+
+## 主要 record
+
+### 1. `WorkGraphTaskRecord`
+
+これは `s12` の durable task です。
+
+```python
+task = {
+    "id": 12,
+    "subject": "Implement auth module",
+    "status": "in_progress",
+    "blockedBy": [],
+    "blocks": [13],
+    "owner": "alice",
+    "worktree": "auth-refactor",
+}
+```
+
+### 2. `RuntimeTaskState`
+
+教材版の最小形は次の程度で十分です。
+
+```python
+runtime_task = {
+    "id": "b8k2m1qz",
+    "type": "local_bash",
+    "status": "running",
+    "description": "Run pytest",
+    "start_time": 1710000000.0,
+    "end_time": None,
+    "output_file": ".task_outputs/b8k2m1qz.txt",
+    "notified": False,
+}
+```
+
+重要 field は:
+
+- `type`: どの execution unit か
+- `status`: active か terminal か
+- `output_file`: 結果がどこにあるか
+- `notified`: 結果を system がもう表に出したか
+
+### 3. `RuntimeTaskType`
+
+教材 repo ですべての type を即実装する必要はありません。
+
+ただし runtime task は単なる shell 1 種ではなく、型族だと読者に見せるべきです。
+
+最小表は:
+
+```text
+local_bash
+local_agent
+remote_agent
+in_process_teammate
+monitor
+workflow
+```
+
+## 最小実装の進め方
+
+### Step 1: `s12` の task board はそのまま保つ
+
+ここへ runtime state を混ぜないでください。
+
+### Step 2: 別の runtime task manager を足す
+
+```python
+class RuntimeTaskManager:
+    def __init__(self):
+        self.tasks = {}
+```
+
+### Step 3: background work 開始時に runtime task を作る
+
+```python
+def spawn_bash_task(command: str):
+    task_id = new_runtime_id()
+    runtime_tasks[task_id] = {
+        "id": task_id,
+        "type": "local_bash",
+        "status": "running",
+        "description": command,
+    }
+```
+
+### Step 4: 必要なら work graph へ結び戻す
+
+```python
+runtime_tasks[task_id]["work_graph_task_id"] = 12
+```
+
+初日から必須ではありませんが、teams や worktrees へ進むほど重要になります。
+
+## 開発者が持つべき図
+
+```text
+Work Graph
+  task #12: Implement auth module
+        |
+        +-- runtime task A: local_bash (pytest)
+        +-- runtime task B: local_agent (coder worker)
+        +-- runtime task C: monitor (watch service status)
+
+Runtime Task Layer
+  A/B/C each have:
+  - own runtime ID
+  - own status
+  - own output
+  - own lifecycle
+```
+
+## 後続章とのつながり
+
+この層が明確になると、後続章がかなり読みやすくなります。
+
+- `s13` の background command は runtime task
+- `s15-s17` の teammate も runtime task の一種として見られる
+- `s18` の worktree は主に durable work に紐づくが runtime execution にも影響する
+- `s19` の monitor や async external work も runtime layer に落ちうる
+
+「裏で生きていて仕事を進めているもの」を見たら、まず二つ問います。
+
+- これは work graph 上の durable goal か
+- それとも runtime 上の live execution slot か
+
+## 初学者がやりがちな間違い
+
+### 1. background shell の state を task board に直接入れる
+
+durable task state と runtime execution state が混ざります。
+
+### 2. 1 つの work-graph task は 1 つの runtime task しか持てないと思う
+
+現実の system では、1 つの goal から複数 execution unit が派生することは普通です。
+
+### 3. 両層で同じ status 語彙を使い回す
+
+例えば:
+
+- durable tasks: `pending / in_progress / completed`
+- runtime tasks: `running / completed / failed / killed`
+
+可能な限り分けた方が安全です。
+
+### 4. `output_file` や `notified` のような runtime 専用 field を軽視する
+
+durable task board はそこまで気にしませんが、runtime layer は強く依存します。
diff --git a/docs/ja/s14-cron-scheduler.md b/docs/ja/s14-cron-scheduler.md
new file mode 100644
index 000000000..ecdc344a2
--- /dev/null
+++ b/docs/ja/s14-cron-scheduler.md
@@ -0,0 +1,182 @@
+# s14: Cron Scheduler
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > [ s14 ] > s15 > s16 > s17 > s18 > s19`
+
+> *バックグラウンドタスクが「遅い仕事をどう続けるか」を扱うなら、スケジューラは「未来のいつ仕事を始めるか」を扱う。*
+
+## この章が解決する問題
+
+`s13` で、遅い処理をバックグラウンドへ逃がせるようになりました。
+
+でもそれは「今すぐ始める仕事」です。
+
+現実には:
+
+- 毎晩実行したい
+- 毎週決まった時刻にレポートを作りたい
+- 30 分後に再確認したい
+
+といった未来トリガーが必要になります。
+
+この章の核心は:
+
+**未来の意図を今記録して、時刻が来たら新しい仕事として戻す**
+
+ことです。
+
+## 教学上の境界
+
+この章の中心は cron 構文の暗記ではありません。
+
+本当に理解すべきなのは:
+
+**schedule record が通知になり、通知が主ループへ戻る流れ**
+
+です。
+
+## 主線とどう併読するか
+
+- `schedule`、`task`、`runtime task` がまだ同じ object に見えるなら、[`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) に戻ります。
+- 1 つの trigger が最終的にどう主線へ戻るかを見たいなら、[`s00b-one-request-lifecycle.md`](./s00b-one-request-lifecycle.md) と一緒に読みます。
+- 未来トリガーが別の実行系に見えてきたら、[`data-structures.md`](./data-structures.md) で schedule record と runtime record を分け直します。
+
+## 最小の心智モデル
+
+```text
+1. schedule records
+2. time checker
+3. notification queue
+```
+
+流れ:
+
+```text
+schedule_create(...)
+  ->
+記録を保存
+  ->
+time checker が定期的に一致判定
+  ->
+一致したら scheduled notification を積む
+  ->
+主ループがそれを新しい仕事として受け取る
+```
+
+重要なのは:
+
+**scheduler 自体は第二の agent ではない**
+
+ということです。
+
+## 重要なデータ構造
+
+### 1. schedule record
+
+```python
+schedule = {
+    "id": "job_001",
+    "cron": "0 9 * * 1",
+    "prompt": "Run the weekly status report.",
+    "recurring": True,
+    "durable": True,
+    "created_at": 1710000000.0,
+    "last_fired_at": None,
+}
+```
+
+### 2. scheduled notification
+
+```python
+{
+    "type": "scheduled_prompt",
+    "schedule_id": "job_001",
+    "prompt": "Run the weekly status report.",
+}
+```
+
+### 3. check interval
+
+教学版なら分単位で十分です。
+
+## 最小実装
+
+```python
+def create(self, cron_expr: str, prompt: str, recurring: bool = True):
+    job = {
+        "id": new_id(),
+        "cron": cron_expr,
+        "prompt": prompt,
+        "recurring": recurring,
+        "created_at": time.time(),
+        "last_fired_at": None,
+    }
+    self.jobs.append(job)
+    return job
+```
+
+```python
+def check_loop(self):
+    while True:
+        now = datetime.now()
+        self.check_jobs(now)
+        time.sleep(60)
+```
+
+```python
+def check_jobs(self, now):
+    for job in self.jobs:
+        if cron_matches(job["cron"], now):
+            self.queue.put({
+                "type": "scheduled_prompt",
+                "schedule_id": job["id"],
+                "prompt": job["prompt"],
+            })
+            job["last_fired_at"] = now.timestamp()
+```
+
+最後に主ループへ戻します。
+
+```python
+notifications = scheduler.drain()
+for item in notifications:
+    messages.append({
+        "role": "user",
+        "content": f"[scheduled:{item['schedule_id']}] {item['prompt']}",
+    })
+```
+
+## なぜ `s13` の後なのか
+
+この 2 章は近い問いを扱います。
+
+| 仕組み | 中心の問い |
+|---|---|
+| background tasks | 遅い仕事を止めずにどう続けるか |
+| scheduling | 未来の仕事をいつ始めるか |
+
+この順序の方が、初学者には自然です。
+
+## 初学者がやりがちな間違い
+
+### 1. cron 構文だけに意識を取られる
+
+### 2. `last_fired_at` を持たない
+
+### 3. スケジュールをメモリにしか置かない
+
+### 4. 未来トリガーの仕事を裏で黙って全部実行する
+
+より分かりやすい主線は:
+
+- trigger
+- notify
+- main loop が処理を決める
+
+です。
+
+## Try It
+
+```sh
+cd learn-claude-code
+python agents/s14_cron_scheduler.py
+```
diff --git a/docs/ja/s15-agent-teams.md b/docs/ja/s15-agent-teams.md
new file mode 100644
index 000000000..a01a17a66
--- /dev/null
+++ b/docs/ja/s15-agent-teams.md
@@ -0,0 +1,426 @@
+# s15: Agent Teams
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > [ s15 ] > s16 > s17 > s18 > s19`
+
+> *subagent は一回きりの委譲に向く。team system が解くのは、「誰かが長く online で残り、繰り返し仕事を受け取り、互いに協調できる」状態です。*
+
+## この章が本当に解きたい問題
+
+`s04` の subagent は、main agent が作業を小さく切り出すのに十分役立ちます。
+
+ただし subagent には明確な境界があります。
+
+```text
+生成される
+  ->
+少し作業する
+  ->
+要約を返す
+  ->
+消える
+```
+
+これは一回きりの調査や短い委譲にはとても向いています。  
+しかし、次のような system を作りたいときには足りません。
+
+- テスト担当の agent を長く待機させる
+- リファクタ担当とテスト担当を並行して持ち続ける
+- ある teammate が後のターンでも同じ責任を持ち続ける
+- lead が後で同じ teammate へ再び仕事を振る
+
+つまり今不足しているのは「model call を 1 回増やすこと」ではありません。
+
+不足しているのは:
+
+**名前・役割・inbox・状態を持った、長期的に存在する実行者の集まり**
+
+です。
+
+## 併読のすすめ
+
+- teammate と `s04` の subagent をまだ同じものに見てしまうなら、[`entity-map.md`](./entity-map.md) に戻ります。
+- `s16-s18` まで続けて読むなら、[`team-task-lane-model.md`](./team-task-lane-model.md) を手元に置き、teammate、protocol request、task、runtime slot、worktree lane を混ぜないようにします。
+- 長く生きる teammate と background 実行の runtime slot が混ざり始めたら、[`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) で goal / execution の境界を先に固めます。
+
+## まず用語をはっきり分ける
+
+### teammate とは何か
+
+ここでの `teammate` は:
+
+> 名前、役割、inbox、lifecycle を持ち、複数ターンにまたがって system 内へ残る agent
+
+のことです。
+
+重要なのは「賢い helper」ではなく、**持続する actor** だという点です。
+
+### roster とは何か
+
+`roster` は team member の名簿です。
+
+少なくとも次を答えられる必要があります。
+
+- 今 team に誰がいるか
+- その人の role は何か
+- その人は idle か、working か、shutdown 済みか
+
+### mailbox とは何か
+
+`mailbox` は各 teammate が持つ受信箱です。
+
+他の member はそこへ message を送ります。  
+受信側は、自分の次の work loop に入る前に mailbox を drain します。
+
+この設計の利点は、協調が次のように見えることです。
+
+- 誰が誰に送ったか
+- どの member がまだ未読か
+- どの message が actor 間通信なのか
+
+## 最小心智モデル
+
+この章をいちばん壊れにくく理解する方法は、各 teammate を次のように見ることです。
+
+> 自分の `messages`、自分の mailbox、自分の agent loop を持った長期 actor
+
+```text
+lead
+  |
+  +-- spawn alice (tester)
+  +-- spawn bob (refactorer)
+  |
+  +-- send message -> alice inbox
+  +-- send message -> bob inbox
+
+alice
+  |
+  +-- 自分の messages
+  +-- 自分の inbox
+  +-- 自分の agent loop
+
+bob
+  |
+  +-- 自分の messages
+  +-- 自分の inbox
+  +-- 自分の agent loop
+```
+
+この章の一番大事な対比は次です。
+
+- subagent: 一回きりの探索 helper
+- teammate: 長く存在し続ける協調 member
+
+## それまでの章にどう接続するか
+
+`s15` は単に「人数を増やす章」ではありません。  
+`s12-s14` でできた task / runtime / schedule の上に、**長く残る実行者層**を足す章です。
+
+接続の主線は次です。
+
+```text
+lead が「長く担当させたい仕事」を見つける
+  ->
+teammate を spawn する
+  ->
+team roster に登録する
+  ->
+mailbox に仕事の手がかりや依頼を送る
+  ->
+teammate が自分の inbox を drain する
+  ->
+自分の agent loop と tools を回す
+  ->
+結果を message / task update として返す
+```
+
+ここで見失ってはいけない境界は 4 つです。
+
+1. `s12-s14` が作ったのは work layer であり、ここでは actor layer を足している
+2. `s15` の default はまだ lead 主導である
+3. structured protocol は次章 `s16`
+4. autonomous claim は `s17`
+
+つまりこの章は、team system の中でもまだ:
+
+- 名付ける
+- 残す
+- 送る
+- 受け取る
+
+という基礎層を作っている段階です。
+
+## 主要データ構造
+
+### `TeamMember`
+
+```python
+member = {
+    "name": "alice",
+    "role": "tester",
+    "status": "working",
+}
+```
+
+教学版では、まずこの 3 つが揃っていれば十分です。
+
+- `name`: 誰か
+- `role`: 何を主に担当するか
+- `status`: 今どういう状態か
+
+最初から大量の field を足す必要はありません。  
+この章で大事なのは「長く存在する actor が立ち上がること」です。
+
+### `TeamConfig`
+
+```python
+config = {
+    "team_name": "default",
+    "members": [member1, member2],
+}
+```
+
+通常は次のような場所に置きます。
+
+```text
+.team/config.json
+```
+
+この record があると system は再起動後も、
+
+- 以前誰がいたか
+- 誰がどの role を持っていたか
+
+を失わずに済みます。
+
+### `MessageEnvelope`
+
+```python
+message = {
+    "type": "message",
+    "from": "lead",
+    "to": "alice",
+    "content": "Please review auth module.",
+    "timestamp": 1710000000.0,
+}
+```
+
+`envelope` は「本文だけでなくメタ情報も含めて包んだ 1 件の message record」です。
+
+これを使う理由:
+
+- sender が分かる
+- receiver が分かる
+- message type を分けられる
+- mailbox を durable channel として扱える
+
+## 最小実装の進め方
+
+### Step 1: まず roster を持つ
+
+```python
+class TeammateManager:
+    def __init__(self, team_dir: Path):
+        self.team_dir = team_dir
+        self.config_path = team_dir / "config.json"
+        self.config = self._load_config()
+```
+
+この章の起点は roster です。  
+roster がないまま team を語ると、結局「今この場で数回呼び出した model たち」にしか見えません。
+
+### Step 2: teammate を spawn する
+
+```python
+def spawn(self, name: str, role: str, prompt: str):
+    member = {"name": name, "role": role, "status": "working"}
+    self.config["members"].append(member)
+    self._save_config()
+
+    thread = threading.Thread(
+        target=self._teammate_loop,
+        args=(name, role, prompt),
+        daemon=True,
+    )
+    thread.start()
+```
+
+ここで大切なのは thread という実装選択そのものではありません。  
+大切なのは次のことです。
+
+**一度 spawn された teammate は、一回限りの tool call ではなく、継続する lifecycle を持つ**
+
+### Step 3: 各 teammate に mailbox を持たせる
+
+教学版で一番分かりやすいのは JSONL inbox です。
+
+```text
+.team/inbox/alice.jsonl
+.team/inbox/bob.jsonl
+```
+
+送信側:
+
+```python
+def send(self, sender: str, to: str, content: str):
+    with open(f"{to}.jsonl", "a") as f:
+        f.write(json.dumps({
+            "type": "message",
+            "from": sender,
+            "to": to,
+            "content": content,
+            "timestamp": time.time(),
+        }) + "\n")
+```
+
+受信側:
+
+1. すべて読む
+2. JSON として parse する
+3. 読み終わったら inbox を drain する
+
+ここで教えたいのは storage trick ではありません。
+
+教えたいのは:
+
+**協調は shared `messages[]` ではなく、mailbox boundary を通して起こる**
+
+という構造です。
+
+### Step 4: teammate は毎ラウンド mailbox を先に確認する
+
+```python
+def teammate_loop(name: str, role: str, prompt: str):
+    messages = [{"role": "user", "content": prompt}]
+
+    while True:
+        inbox = bus.read_inbox(name)
+        for item in inbox:
+            messages.append({"role": "user", "content": json.dumps(item)})
+
+        response = client.messages.create(...)
+        ...
+```
+
+この step をあいまいにすると、読者はすぐこう誤解します。
+
+- 新しい仕事を与えるたびに teammate を再生成するのか
+- 元の context はどこに残るのか
+
+正しくは:
+
+- teammate は残る
+- messages も残る
+- 新しい仕事は inbox 経由で入る
+- 次ラウンドに入る前に mailbox を見る
+
+です。
+
+## Teammate / Subagent / Runtime Slot をどう分けるか
+
+この段階で最も混ざりやすいのはこの 3 つです。  
+次の表をそのまま覚えて構いません。
+
+| 仕組み | 何に近いか | lifecycle | 核心境界 |
+|---|---|---|---|
+| subagent | 一回きりの外部委託 helper | 作って、少し働いて、終わる | 小さな探索文脈の隔離 |
+| runtime slot | 実行中の background slot | その実行が終われば消える | 長い execution を追跡する |
+| teammate | 長期に残る team member | idle と working を行き来する | 名前、role、mailbox、独立 loop |
+
+口語的に言い換えると:
+
+- subagent: 「ちょっと調べて戻ってきて」
+- runtime slot: 「これは裏で走らせて、あとで知らせて」
+- teammate: 「あなたは今後しばらくテスト担当ね」
+
+## ここで教えるべき境界
+
+この章でまず固めるべきは 3 つだけです。
+
+- roster
+- mailbox
+- 独立 loop
+
+これだけで「長く残る teammate」という実体は十分立ち上がります。
+
+ただし、まだここでは教え過ぎない方がよいものがあります。
+
+### 1. protocol request layer
+
+つまり:
+
+- どの message が普通の会話か
+- どの message が `request_id` を持つ構造化 request か
+
+これは `s16` の範囲です。
+
+### 2. autonomous claim layer
+
+つまり:
+
+- teammate が自分で仕事を探すか
+- どの policy で self-claim するか
+- resume は何を根拠に行うか
+
+これは `s17` の範囲です。
+
+`s15` の default はあくまで:
+
+- lead が作る
+- lead が送る
+- teammate が受ける
+
+です。
+
+## 初学者が特によくやる間違い
+
+### 1. teammate を「名前付き subagent」にする
+
+名前が付いていても、実装が
+
+```text
+spawn -> work -> summary -> destroy
+```
+
+なら本質的にはまだ subagent です。
+
+### 2. team 全員で 1 本の `messages` を共有する
+
+これは一見簡単ですが、文脈汚染がすぐ起きます。
+
+各 teammate は少なくとも:
+
+- 自分の messages
+- 自分の inbox
+- 自分の status
+
+を持つべきです。
+
+### 3. roster を durable にしない
+
+system を止めた瞬間に「team に誰がいたか」を完全に失うなら、長期 actor layer としてはかなり弱いです。
+
+### 4. mailbox なしで shared variable だけで会話させる
+
+実装は短くできますが、teammate 間協調の境界が見えなくなります。  
+教学 repo では durable mailbox を置いた方が、読者の心智がずっと安定します。
+
+## 学び終わったら言えるべきこと
+
+少なくとも次の 4 つを自分の言葉で説明できれば、この章の主線は掴めています。
+
+1. teammate の本質は「多 model」ではなく「長期に残る actor identity」である
+2. team system の最小構成は「roster + mailbox + 独立 loop」である
+3. subagent と teammate の違いは lifecycle の長さにある
+4. teammate と runtime slot の違いは、「actor identity」か「live execution」かにある
+
+## 次章で何を足すか
+
+この章が解いているのは:
+
+> team member が長く存在し、互いに message を送り合えるようにすること
+
+次章 `s16` が解くのは:
+
+> message が単なる自由文ではなく、追跡・承認・拒否・期限切れを持つ protocol object になるとき、どう設計するか
+
+つまり `s15` が「team の存在」を作り、`s16` が「team の構造化協調」を作ります。
diff --git a/docs/ja/s16-team-protocols.md b/docs/ja/s16-team-protocols.md
new file mode 100644
index 000000000..27552fc0e
--- /dev/null
+++ b/docs/ja/s16-team-protocols.md
@@ -0,0 +1,382 @@
+# s16: Team Protocols
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > [ s16 ] > s17 > s18 > s19`
+
+> *mailbox があるだけでは「話せる team」に過ぎません。protocol が入って初めて、「規則に従って協調できる team」になります。*
+
+## この章が解く問題
+
+`s15` までで teammate 同士は message を送り合えます。
+
+しかし自由文だけに頼ると、すぐに 2 つの問題が出ます。
+
+- 明確な承認 / 拒否が必要な場面で、曖昧な返事しか残らない
+- request が複数同時に走ると、どの返答がどの件に対応するのか分からなくなる
+
+特に分かりやすいのは次の 2 場面です。
+
+1. graceful shutdown を依頼したい
+2. 高リスク plan を実行前に approval したい
+
+一見別の話に見えても、骨格は同じです。
+
+```text
+requester が request を送る
+  ->
+receiver が明確に response する
+  ->
+両者が同じ request_id で対応関係を追える
+```
+
+この章で追加するのは message の量ではなく、
+
+**追跡可能な request-response protocol**
+
+です。
+
+## 併読すると楽になる資料
+
+- 普通の message と protocol request が混ざったら [`glossary.md`](./glossary.md) と [`entity-map.md`](./entity-map.md)
+- `s17` や `s18` に進む前に境界を固めたいなら [`team-task-lane-model.md`](./team-task-lane-model.md)
+- request が主システムへどう戻るか見直したいなら [`s00b-one-request-lifecycle.md`](./s00b-one-request-lifecycle.md)
+
+## 先に言葉をそろえる
+
+### protocol とは何か
+
+ここでの `protocol` は難しい通信理論ではありません。
+
+意味は、
+
+> message の形、処理手順、状態遷移を事前に決めた協調ルール
+
+です。
+
+### request_id とは何か
+
+`request_id` は request の一意な番号です。
+
+役割は 1 つで、
+
+> 後から届く response や status update を、元の request と正確に結びつけること
+
+です。
+
+### request-response pattern とは何か
+
+これも難しく考える必要はありません。
+
+```text
+requester: この操作をしたい
+receiver: 承認する / 拒否する
+```
+
+この往復を、自然文の雰囲気で済ませず、**構造化 record として残す**のがこの章です。
+
+## 最小心智モデル
+
+教学上は、protocol を 2 層で見ると分かりやすくなります。
+
+```text
+1. protocol envelope
+2. durable request record
+```
+
+### protocol envelope
+
+これは inbox を流れる 1 通の構造化 message です。
+
+```python
+{
+    "type": "shutdown_request",
+    "from": "lead",
+    "to": "alice",
+    "request_id": "req_001",
+    "payload": {},
+}
+```
+
+### durable request record
+
+これは request の lifecycle を disk に追う record です。
+
+```python
+{
+    "request_id": "req_001",
+    "kind": "shutdown",
+    "from": "lead",
+    "to": "alice",
+    "status": "pending",
+}
+```
+
+この 2 層がそろうと system は、
+
+- いま何を送ったのか
+- その request は今どの状態か
+
+を両方説明できるようになります。
+
+## この章の核になるデータ構造
+
+### 1. ProtocolEnvelope
+
+protocol message は普通の message より多くのメタデータを持ちます。
+
+```python
+message = {
+    "type": "shutdown_request",
+    "from": "lead",
+    "to": "alice",
+    "request_id": "req_001",
+    "payload": {},
+    "timestamp": 1710000000.0,
+}
+```
+
+特に重要なのは次の 3 つです。
+
+- `type`: これは何の protocol message か
+- `request_id`: どの request thread に属するか
+- `payload`: 本文以外の構造化内容
+
+### 2. RequestRecord
+
+request record は `.team/requests/` に durable に保存されます。
+
+```python
+request = {
+    "request_id": "req_001",
+    "kind": "shutdown",
+    "from": "lead",
+    "to": "alice",
+    "status": "pending",
+    "created_at": 1710000000.0,
+    "updated_at": 1710000000.0,
+}
+```
+
+この record があることで、system は message を送ったあとでも request の状態を追い続けられます。
+
+教材コードでは実際に次のような path を使います。
+
+```text
+.team/requests/
+  req_001.json
+  req_002.json
+```
+
+これにより、
+
+- request の状態を再読込できる
+- protocol の途中経過をあとから確認できる
+- main loop が先へ進んでも request thread が消えない
+
+という利点が生まれます。
+
+### 3. 状態機械
+
+この章の state machine は難しくありません。
+
+```text
+pending -> approved
+pending -> rejected
+pending -> expired
+```
+
+ここで大事なのは theory ではなく、
+
+**承認系の協調には「いまどの状態か」を explicit に持つ必要がある**
+
+ということです。
+
+## 最小実装を段階で追う
+
+### 第 1 段階: team mailbox の上に protocol line を通す
+
+この章の本質は新しい message type を 2 個足すことではありません。
+
+本質は、
+
+```text
+requester が protocol action を開始する
+  ->
+request record を保存する
+  ->
+protocol envelope を inbox に送る
+  ->
+receiver が request_id 付きで response する
+  ->
+record の status を更新する
+```
+
+という一本の durable flow を通すことです。
+
+### 第 2 段階: shutdown protocol を作る
+
+graceful shutdown は「thread を即 kill する」ことではありません。
+
+正しい流れは次です。
+
+1. shutdown request を作る
+2. teammate が approve / reject を返す
+3. approve なら後始末して終了する
+
+request 側の最小形はこうです。
+
+```python
+def request_shutdown(target: str):
+    request_id = new_id()
+    REQUEST_STORE.create({
+        "request_id": request_id,
+        "kind": "shutdown",
+        "from": "lead",
+        "to": target,
+        "status": "pending",
+    })
+    BUS.send(
+        "lead",
+        target,
+        "Please shut down gracefully.",
+        "shutdown_request",
+        {"request_id": request_id},
+    )
+```
+
+response 側は request_id を使って同じ record を更新します。
+
+```python
+def handle_shutdown_response(request_id: str, approve: bool):
+    record = REQUEST_STORE.update(
+        request_id,
+        status="approved" if approve else "rejected",
+    )
+```
+
+### 第 3 段階: plan approval も同じ骨格で扱う
+
+高リスクな変更を teammate が即時実行してしまうと危険なことがあります。
+
+そこで plan approval protocol を入れます。
+
+```python
+def submit_plan(name: str, plan_text: str):
+    request_id = new_id()
+    REQUEST_STORE.create({
+        "request_id": request_id,
+        "kind": "plan_approval",
+        "from": name,
+        "to": "lead",
+        "status": "pending",
+        "plan": plan_text,
+    })
+```
+
+lead はその `request_id` を見て承認または却下します。
+
+```python
+def review_plan(request_id: str, approve: bool, feedback: str = ""):
+    REQUEST_STORE.update(
+        request_id,
+        status="approved" if approve else "rejected",
+        feedback=feedback,
+    )
+```
+
+ここで伝えたい中心は、
+
+**shutdown と plan approval は中身は違っても、request-response correlation の骨格は同じ**
+
+という点です。
+
+## Message / Protocol / Request / Task の境界
+
+この章で最も混ざりやすい 4 つを表で分けます。
+
+| オブジェクト | 何を答えるか | 典型 field |
+|---|---|---|
+| `MessageEnvelope` | 誰が誰に何を送ったか | `from`, `to`, `content` |
+| `ProtocolEnvelope` | それが構造化 request / response か | `type`, `request_id`, `payload` |
+| `RequestRecord` | その協調フローはいまどこまで進んだか | `kind`, `status`, `from`, `to` |
+| `TaskRecord` | 実際の work goal は何か | `subject`, `status`, `owner`, `blockedBy` |
+
+ここで絶対に混ぜないでほしい点は次です。
+
+- protocol request は task そのものではない
+- request store は task board ではない
+- protocol は協調フローを追う
+- task は仕事の進行を追う
+
+## `s15` から何が増えたか
+
+`s15` の team system は「話せる team」でした。
+
+`s16` ではそこへ、
+
+- request_id
+- durable request store
+- approved / rejected の explicit status
+- protocol-specific message type
+
+が入ります。
+
+すると team は単なる chat 集合ではなく、
+
+**追跡可能な coordination system**
+
+に進みます。
+
+## 初学者が混ぜやすいポイント
+
+### 1. request を普通の text message と同じように扱う
+
+これでは承認状態を追えません。
+
+### 2. request_id を持たせない
+
+同時に複数 request が走った瞬間に対応関係が壊れます。
+
+### 3. request の状態を memory 内 dict にしか置かない
+
+プロセスをまたいで追えず、観測性も悪くなります。
+
+### 4. approved / rejected を曖昧な文章だけで表す
+
+state machine が読めなくなります。
+
+### 5. protocol と task を混同する
+
+plan approval request は「plan を実行してよいか」の協調であって、work item 本体ではありません。
+
+## 前の章とどうつながるか
+
+この章は `s15` の mailbox-based team を次の段階へ押し上げます。
+
+- `s15`: teammate が message を送れる
+- `s16`: teammate が structured protocol で協調できる
+
+そしてこの先、
+
+- `s17`: idle teammate が自分で task を claim する
+- `s18`: task ごとに isolation lane を持つ
+
+へ進む準備になります。
+
+もしここで protocol の境界が曖昧なままだと、後の autonomy や worktree を読むときに
+
+- 誰が誰に依頼したのか
+- どの state が協調の state で、どれが work の state か
+
+がすぐ混ざります。
+
+## 教学上の境界
+
+この章でまず教えるべきのは、製品に存在しうる全 protocol の一覧ではありません。
+
+中心は次の 3 点です。
+
+- request と response を同じ `request_id` で結び付けること
+- 承認状態を explicit state として残すこと
+- team coordination を自由文から durable workflow へ進めること
+
+ここが見えていれば、後から protocol の種類が増えても骨格は崩れません。
diff --git a/docs/ja/s17-autonomous-agents.md b/docs/ja/s17-autonomous-agents.md
new file mode 100644
index 000000000..a98e6c315
--- /dev/null
+++ b/docs/ja/s17-autonomous-agents.md
@@ -0,0 +1,546 @@
+# s17: Autonomous Agents
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > [ s17 ] > s18 > s19`
+
+> *本当にチームらしくなる瞬間は、人数が増えたときではなく、空いている teammate が次の仕事を自分で拾えるようになったときです。*
+
+## この章が解く問題
+
+`s16` まで来ると、チームにはすでに次のものがあります。
+
+- 長く生きる teammate
+- inbox
+- protocol request / response
+- task board
+
+それでも、まだ 1 つ大きな詰まりが残っています。
+
+**仕事の割り振りが lead に集中しすぎることです。**
+
+たとえば task board に ready な task が 10 個あっても、
+
+- Alice はこれ
+- Bob はこれ
+- Charlie はこれ
+
+と lead が 1 件ずつ指名し続けるなら、team は増えても coordination の中心は 1 人のままです。
+
+この章で入れるのは、
+
+**空いている teammate が、自分で board を見て、取ってよい task を安全に claim する仕組み**
+
+です。
+
+## 併読すると楽になる資料
+
+- teammate / task / runtime slot の境界が怪しくなったら [`team-task-lane-model.md`](./team-task-lane-model.md)
+- `auto-claim` を読んで runtime record の置き場所が曖昧なら [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)
+- 長期 teammate と一回限りの subagent の違いが薄れたら [`entity-map.md`](./entity-map.md)
+
+## 先に言葉をそろえる
+
+### 自治とは何か
+
+ここで言う `autonomous` は、
+
+> 何の制御もなく勝手に暴走すること
+
+ではありません。
+
+正しくは、
+
+> 事前に与えたルールに従って、空いている teammate が次の仕事を自分で選べること
+
+です。
+
+つまり自治は自由放任ではなく、**規則付きの自律再開**です。
+
+### claim とは何か
+
+`claim` は、
+
+> まだ owner が付いていない task を「今から自分が担当する」と確定させること
+
+です。
+
+「見つける」だけでは不十分で、**owner を書き込み、他の teammate が同じ task を取らないようにする**ところまでが claim です。
+
+### idle とは何か
+
+`idle` は終了でも停止でもありません。
+
+意味は次の通りです。
+
+> 今この teammate には active work がないが、まだ system の中で生きていて、新しい input を待てる状態
+
+です。
+
+## 最小心智モデル
+
+この章を最も簡単に捉えるなら、teammate の lifecycle を 2 フェーズで見ます。
+
+```text
+WORK
+  |
+  | 今の作業を終える / idle を選ぶ
+  v
+IDLE
+  |
+  +-- inbox に新着がある -> WORK
+  |
+  +-- task board に claimable task がある -> claim -> WORK
+  |
+  +-- 一定時間なにもない -> shutdown
+```
+
+ここで大事なのは、
+
+**main loop を無限に回し続けることではなく、idle 中に何を見て、どの順番で resume するか**
+
+です。
+
+## この章の核になるデータ構造
+
+### 1. Claimable Predicate
+
+最初に理解すべきなのは、
+
+> どんな task なら「この teammate が今 claim してよい」と判定できるのか
+
+です。
+
+教材コードでは、判定は単に `status == "pending"` では終わりません。
+
+```python
+def is_claimable_task(task: dict, role: str | None = None) -> bool:
+    return (
+        task.get("status") == "pending"
+        and not task.get("owner")
+        and not task.get("blockedBy")
+        and _task_allows_role(task, role)
+    )
+```
+
+この 4 条件はそれぞれ別の意味を持ちます。
+
+- `status == "pending"`: まだ開始していない
+- `not owner`: まだ誰も担当していない
+- `not blockedBy`: 前提 task が残っていない
+- `_task_allows_role(...)`: この teammate の role が claim policy に合っている
+
+最後の条件が特に重要です。
+
+task は今の教材コードでは次のような role 制約を持てます。
+
+- `claim_role`
+- `required_role`
+
+たとえば、
+
+```python
+{
+    "id": 7,
+    "subject": "Implement login page",
+    "status": "pending",
+    "owner": "",
+    "blockedBy": [],
+    "claim_role": "frontend",
+}
+```
+
+なら、空いている teammate 全員が取れるわけではありません。
+
+**frontend role の teammate だけが claim 候補になります。**
+
+### 2. Claim 後の TaskRecord
+
+claim が成功すると、task record は少なくとも次のように更新されます。
+
+```python
+{
+    "id": 7,
+    "owner": "alice",
+    "status": "in_progress",
+    "claimed_at": 1710000000.0,
+    "claim_source": "auto",
+}
+```
+
+この中で初心者が見落としやすいのは `claimed_at` と `claim_source` です。
+
+- `claimed_at`: いつ取られたか
+- `claim_source`: 手動か自動か
+
+これがあることで system は、
+
+- 今だれが担当しているか
+- その担当は lead の指名か
+- それとも idle scan による auto-claim か
+
+をあとから説明できます。
+
+### 3. Claim Event Log
+
+task file の更新だけでは、今の最終状態しか見えません。
+
+そこでこの章では claim 操作を別の append-only log にも書きます。
+
+```text
+.tasks/claim_events.jsonl
+```
+
+中身のイメージはこうです。
+
+```python
+{
+    "event": "task.claimed",
+    "task_id": 7,
+    "owner": "alice",
+    "role": "frontend",
+    "source": "auto",
+    "ts": 1710000000.0,
+}
+```
+
+この log があると、
+
+- task がいつ取られたか
+- 誰が取ったか
+- 手動か自動か
+
+が current state とは別に追えます。
+
+### 4. Durable Request Record
+
+`s17` は autonomy を追加する章ですが、`s16` の protocol line を捨てる章ではありません。
+
+そのため shutdown や plan approval の request は引き続き disk に保存されます。
+
+```text
+.team/requests/{request_id}.json
+```
+
+これは重要です。
+
+なぜなら autonomous teammate は、
+
+> protocol を無視して好きに動く worker
+
+ではなく、
+
+> 既存の protocol system の上で、idle 時に自分で次の仕事を探せる teammate
+
+だからです。
+
+### 5. Identity Block
+
+compact の後や idle からの復帰直後は、teammate が自分の identity を見失いやすくなります。
+
+そのため教材コードには identity block の再注入があります。
+
+```python
+{
+    "role": "user",
+    "content": "<identity>You are 'alice', role: frontend, team: default. Continue your work.</identity>",
+}
+```
+
+さらに短い assistant acknowledgement も添えています。
+
+```python
+{"role": "assistant", "content": "I am alice. Continuing."}
+```
+
+この 2 行は装飾ではありません。
+
+ここで守っているのは次の 3 点です。
+
+- 私は誰か
+- どの role か
+- どの team に属しているか
+
+## 最小実装を段階で追う
+
+### 第 1 段階: WORK と IDLE を分ける
+
+まず teammate loop を 2 フェーズに分けます。
+
+```python
+while True:
+    run_work_phase(...)
+    should_resume = run_idle_phase(...)
+    if not should_resume:
+        break
+```
+
+これで初めて、
+
+- いま作業中なのか
+- いま待機中なのか
+- 次に resume する理由は何か
+
+を分けて考えられます。
+
+### 第 2 段階: idle では先に inbox を見る
+
+`idle` に入ったら最初に見るべきは task board ではなく inbox です。
+
+```python
+def idle_phase(name: str, messages: list) -> bool:
+    inbox = bus.read_inbox(name)
+    if inbox:
+        messages.append({
+            "role": "user",
+            "content": json.dumps(inbox),
+        })
+        return True
+```
+
+理由は単純で、
+
+**明示的に自分宛てに来た仕事の方が、board 上の一般 task より優先度が高い**
+
+からです。
+
+### 第 3 段階: inbox が空なら role 付きで task board を走査する
+
+```python
+unclaimed = scan_unclaimed_tasks(role)
+if unclaimed:
+    task = unclaimed[0]
+    claim_result = claim_task(
+        task["id"],
+        name,
+        role=role,
+        source="auto",
+    )
+```
+
+ここでの要点は 2 つです。
+
+- `scan_unclaimed_tasks(role)` は role を無視して全件取るわけではない
+- `source="auto"` を書いて claim の由来を残している
+
+つまり自治とは、
+
+> 何でも空いていれば奪うこと
+
+ではなく、
+
+> role、block 状態、owner 状態を見たうえで、今この teammate に許された仕事だけを取ること
+
+です。
+
+### 第 4 段階: claim 後は identity と task hint を両方戻す
+
+claim 成功後は、そのまま resume してはいけません。
+
+```python
+ensure_identity_context(messages, name, role, team_name)
+messages.append({
+    "role": "user",
+    "content": f"<auto-claimed>Task #{task['id']}: {task['subject']}</auto-claimed>",
+})
+messages.append({
+    "role": "assistant",
+    "content": f"{claim_result}. Working on it.",
+})
+return True
+```
+
+この段で context に戻しているのは 2 種類の情報です。
+
+- identity: この teammate は誰か
+- fresh work item: いま何を始めたのか
+
+この 2 つがそろって初めて、次の WORK phase が迷わず進みます。
+
+### 第 5 段階: 長時間なにもなければ shutdown する
+
+idle teammate を永久に残す必要はありません。
+
+教材版では、
+
+> 一定時間 inbox も task board も空なら shutdown
+
+という単純な出口で十分です。
+
+ここでの主眼は resource policy の最適化ではなく、
+
+**idle からの再開条件と終了条件を明示すること**
+
+です。
+
+## なぜ claim は原子的でなければならないか
+
+`atomic` という言葉は難しく見えますが、ここでは次の意味です。
+
+> claim 処理は「全部成功する」か「起きない」かのどちらかでなければならない
+
+理由は race condition です。
+
+Alice と Bob が同時に同じ task を見たら、
+
+- Alice も `owner == ""` を見る
+- Bob も `owner == ""` を見る
+- 両方が自分を owner として保存する
+
+という事故が起こりえます。
+
+そのため教材コードでも lock を使っています。
+
+```python
+with claim_lock:
+    task = load(task_id)
+    if task["owner"]:
+        return "already claimed"
+    task["owner"] = name
+    task["status"] = "in_progress"
+    save(task)
+```
+
+初心者向けに言い換えるなら、
+
+**claim は「見てから書く」までを他の teammate に割り込まれずに一気に行う**
+
+必要があります。
+
+## identity 再注入が重要な理由
+
+これは地味ですが、自治の品質を大きく左右します。
+
+compact の後や long-lived teammate の再開時には、context 冒頭から次の情報が薄れがちです。
+
+- 私は誰か
+- 何 role か
+- どの team か
+
+この状態で work を再開すると、
+
+- role に合わない判断をしやすくなる
+- protocol 上の責務を忘れやすくなる
+- それまでの persona がぶれやすくなる
+
+だから教材版では、
+
+> idle から戻る前、または compact 後に identity が薄いなら再注入する
+
+という復帰ルールを置いています。
+
+## `s17` は `s16` を上書きしない
+
+ここは誤解しやすいので強調します。
+
+`s17` で増えるのは autonomy ですが、だからといって `s16` の protocol layer が消えるわけではありません。
+
+両者はこういう関係です。
+
+```text
+s16:
+  request_id を持つ durable protocol
+
+s17:
+  idle teammate が board を見て次の仕事を探せる
+```
+
+つまり `s17` は、
+
+**protocol がある team に autonomy を足す章**
+
+であって、
+
+**自由に動く worker 群へ退化させる章**
+
+ではありません。
+
+## 前の章とどうつながるか
+
+この章は前の複数章が初めて強く結びつく場所です。
+
+- `s12`: task board を作る
+- `s15`: persistent teammate を作る
+- `s16`: request / response protocol を作る
+- `s17`: 指名がなくても次の work を自分で取れるようにする
+
+したがって `s17` は、
+
+**受け身の team から、自分で回り始める team への橋渡し**
+
+と考えると分かりやすいです。
+
+## 自治するのは long-lived teammate であって subagent ではない
+
+ここで `s04` と混ざる人が多いです。
+
+この章の actor は one-shot subagent ではありません。
+
+この章の teammate は次の特徴を持ちます。
+
+- 名前がある
+- role がある
+- inbox がある
+- idle state がある
+- 複数回 task を受け取れる
+
+一方、subagent は通常、
+
+- 一度 delegated work を受ける
+- 独立 context で処理する
+- summary を返して終わる
+
+という使い方です。
+
+また、この章で claim する対象は `s12` の task であり、`s13` の runtime slot ではありません。
+
+## 初学者が混ぜやすいポイント
+
+### 1. `pending` だけ見て `blockedBy` を見ない
+
+task が `pending` でも dependency が残っていればまだ取れません。
+
+### 2. role 条件を無視する
+
+`claim_role` や `required_role` を見ないと、間違った teammate が task を取ります。
+
+### 3. claim lock を置かない
+
+同一 task の二重 claim が起こります。
+
+### 4. idle 中に board しか見ない
+
+これでは明示的な inbox message を取りこぼします。
+
+### 5. event log を書かない
+
+「いま誰が持っているか」は分かっても、
+
+- いつ取ったか
+- 自動か手動か
+
+が追えません。
+
+### 6. idle teammate を永遠に残す
+
+教材版では shutdown 条件を持たせた方が lifecycle を理解しやすくなります。
+
+### 7. compact 後に identity を戻さない
+
+長く動く teammate ほど、identity drift が起きやすくなります。
+
+## 教学上の境界
+
+この章でまず掴むべき主線は 1 本です。
+
+**idle で待つ -> 安全に claim する -> identity を整えて work に戻る**
+
+ここで学ぶ中心は自治の骨格であって、
+
+- 高度な scheduler 最適化
+- 分散環境での claim
+- 複雑な fairness policy
+
+ではありません。
+
+その先へ進む前に、読者が自分の言葉で次の 1 文を言えることが大切です。
+
+> autonomous teammate とは、空いたときに勝手に暴走する worker ではなく、inbox と task board を規則通りに見て、取ってよい仕事だけを自分で取りにいける長期 actor である。
diff --git a/docs/ja/s18-worktree-task-isolation.md b/docs/ja/s18-worktree-task-isolation.md
new file mode 100644
index 000000000..34bac72af
--- /dev/null
+++ b/docs/ja/s18-worktree-task-isolation.md
@@ -0,0 +1,534 @@
+# s18: Worktree + Task Isolation
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > [ s18 ] > s19`
+
+> *task board が答えるのは「何をやるか」、worktree が答えるのは「どこでやるか、しかも互いに踏み荒らさずに」です。*
+
+## この章が解く問題
+
+`s17` までで system はすでに次のことができます。
+
+- task を作る
+- teammate が task を claim する
+- 複数の teammate が並行に作業する
+
+それでも、全員が同じ working directory で作業するなら、すぐに限界が来ます。
+
+典型的な壊れ方は次の通りです。
+
+- 2 つの task が同じ file を同時に編集する
+- 片方の未完了変更がもう片方の task を汚染する
+- 「この task の変更だけ見たい」が非常に難しくなる
+
+つまり `s12-s17` までで答えられていたのは、
+
+**誰が何をやるか**
+
+までであって、
+
+**その仕事をどの execution lane で進めるか**
+
+はまだ答えられていません。
+
+それを担当するのが `worktree` です。
+
+## 併読すると楽になる資料
+
+- task / runtime slot / worktree lane が同じものに見えたら [`team-task-lane-model.md`](./team-task-lane-model.md)
+- task record と worktree record に何を保存すべきか確認したいなら [`data-structures.md`](./data-structures.md)
+- なぜ worktree の章が tasks / teams より後ろに来るか再確認したいなら [`s00e-reference-module-map.md`](./s00e-reference-module-map.md)
+
+## 先に言葉をそろえる
+
+### worktree とは何か
+
+Git に慣れている人なら、
+
+> 同じ repository を別ディレクトリへ独立 checkout した作業コピー
+
+と見て構いません。
+
+まだ Git の言葉に慣れていないなら、まずは次の理解で十分です。
+
+> 1 つの task に割り当てる専用の作業レーン
+
+### isolation とは何か
+
+`isolation` は、
+
+> task A は task A の directory で実行し、task B は task B の directory で実行して、未コミット変更を最初から共有しないこと
+
+です。
+
+### binding とは何か
+
+`binding` は、
+
+> task ID と worktree record を明示的に結びつけること
+
+です。
+
+これがないと、system は「この directory が何のために存在しているのか」を説明できません。
+
+## 最小心智モデル
+
+この章は 2 枚の表を別物として見ると一気に分かりやすくなります。
+
+```text
+Task Board
+  - 何をやるか
+  - 誰が持っているか
+  - 今どの状態か
+
+Worktree Registry
+  - どこでやるか
+  - どの branch / path か
+  - どの task に結び付いているか
+```
+
+両者は `task_id` でつながります。
+
+```text
+.tasks/task_12.json
+  {
+    "id": 12,
+    "subject": "Refactor auth flow",
+    "status": "in_progress",
+    "worktree": "auth-refactor"
+  }
+
+.worktrees/index.json
+  {
+    "worktrees": [
+      {
+        "name": "auth-refactor",
+        "path": ".worktrees/auth-refactor",
+        "branch": "wt/auth-refactor",
+        "task_id": 12,
+        "status": "active"
+      }
+    ]
+  }
+```
+
+この 2 つを見て、
+
+- task は goal を記録する
+- worktree は execution lane を記録する
+
+と分けて理解できれば、この章の幹はつかめています。
+
+## この章の核になるデータ構造
+
+### 1. TaskRecord 側の lane 情報
+
+この段階の教材コードでは、task 側に単に `worktree` という名前だけがあるわけではありません。
+
+```python
+task = {
+    "id": 12,
+    "subject": "Refactor auth flow",
+    "status": "in_progress",
+    "owner": "alice",
+    "worktree": "auth-refactor",
+    "worktree_state": "active",
+    "last_worktree": "auth-refactor",
+    "closeout": None,
+}
+```
+
+それぞれの意味は次の通りです。
+
+- `worktree`: 今この task がどの lane に結び付いているか
+- `worktree_state`: その lane が `active` / `kept` / `removed` / `unbound` のどれか
+- `last_worktree`: 直近で使っていた lane 名
+- `closeout`: 最後にどういう終わらせ方をしたか
+
+ここが重要です。
+
+task 側はもはや単に「現在の directory 名」を持っているだけではありません。
+
+**いま結び付いている lane と、最後にどう閉じたかまで記録し始めています。**
+
+### 2. WorktreeRecord
+
+worktree registry 側の record は path の写しではありません。
+
+```python
+worktree = {
+    "name": "auth-refactor",
+    "path": ".worktrees/auth-refactor",
+    "branch": "wt/auth-refactor",
+    "task_id": 12,
+    "status": "active",
+    "last_entered_at": 1710000000.0,
+    "last_command_at": 1710000012.0,
+    "last_command_preview": "pytest tests/auth -q",
+    "closeout": None,
+}
+```
+
+ここで答えているのは path だけではありません。
+
+- いつ lane に入ったか
+- 最近何を実行したか
+- どんな closeout が最後に行われたか
+
+つまり worktree record は、
+
+**directory mapping ではなく、観測可能な execution lane record**
+
+です。
+
+### 3. CloseoutRecord
+
+closeout は「最後に削除したかどうか」だけではありません。
+
+教材コードでは次のような record を残します。
+
+```python
+closeout = {
+    "action": "keep",
+    "reason": "Need follow-up review",
+    "at": 1710000100.0,
+}
+```
+
+これにより system は、
+
+- keep したのか
+- remove したのか
+- なぜそうしたのか
+
+を state として残せます。
+
+初心者にとって大事なのはここです。
+
+**closeout は単なる cleanup コマンドではなく、execution lane の終わり方を明示する操作**
+
+です。
+
+### 4. Event Record
+
+worktree は lifecycle が長いので event log も必要です。
+
+```python
+{
+    "event": "worktree.closeout.keep",
+    "task_id": 12,
+    "worktree": "auth-refactor",
+    "reason": "Need follow-up review",
+    "ts": 1710000100.0,
+}
+```
+
+なぜ state file だけでは足りないかというと、lane の lifecycle には複数段階があるからです。
+
+- create
+- enter
+- run
+- keep
+- remove
+- remove failed
+
+append-only の event があれば、いまの最終状態だけでなく、
+
+**そこへ至る途中の挙動**
+
+も追えます。
+
+## 最小実装を段階で追う
+
+### 第 1 段階: 先に task を作り、そのあと lane を作る
+
+順番は非常に大切です。
+
+```python
+task = tasks.create("Refactor auth flow")
+worktrees.create("auth-refactor", task_id=task["id"])
+```
+
+この順番にする理由は、
+
+**worktree は task の代替ではなく、task にぶら下がる execution lane**
+
+だからです。
+
+最初に goal があり、そのあと goal に lane を割り当てます。
+
+### 第 2 段階: worktree を作り、registry に書く
+
+```python
+def create(self, name: str, task_id: int):
+    path = self.root / ".worktrees" / name
+    branch = f"wt/{name}"
+
+    run_git(["worktree", "add", "-b", branch, str(path), "HEAD"])
+
+    record = {
+        "name": name,
+        "path": str(path),
+        "branch": branch,
+        "task_id": task_id,
+        "status": "active",
+    }
+    self.index["worktrees"].append(record)
+    self._save_index()
+```
+
+ここで registry は次を答えられるようになります。
+
+- lane 名
+- 実 directory
+- branch
+- 対応 task
+- active かどうか
+
+### 第 3 段階: task record 側も同時に更新する
+
+lane registry を書くだけでは不十分です。
+
+```python
+def bind_worktree(task_id: int, name: str):
+    task = tasks.load(task_id)
+    task["worktree"] = name
+    task["last_worktree"] = name
+    task["worktree_state"] = "active"
+    if task["status"] == "pending":
+        task["status"] = "in_progress"
+    tasks.save(task)
+```
+
+なぜ両側へ書く必要があるか。
+
+もし registry だけ更新して task board 側を更新しなければ、
+
+- task 一覧から lane が見えない
+- closeout 時にどの task を終わらせるか分かりにくい
+- crash 後の再構成が不自然になる
+
+からです。
+
+### 第 4 段階: lane に入ることと、lane で command を実行することを分ける
+
+教材コードでは `enter` と `run` を分けています。
+
+```python
+worktree_enter("auth-refactor")
+worktree_run("auth-refactor", "pytest tests/auth -q")
+```
+
+底では本質的に次のことをしています。
+
+```python
+def enter(self, name: str):
+    self._update_entry(name, last_entered_at=time.time())
+    self.events.emit("worktree.enter", ...)
+
+def run(self, name: str, command: str):
+    subprocess.run(command, cwd=worktree_path, ...)
+```
+
+特に大事なのは `cwd=worktree_path` です。
+
+同じ `pytest` でも、どの `cwd` で走るかによって影響範囲が変わります。
+
+`enter` を別操作として教える理由は、読者に次の境界を見せるためです。
+
+- lane を割り当てた
+- 実際にその lane へ入った
+- その lane で command を実行した
+
+この 3 段階が分かれているからこそ、
+
+- `last_entered_at`
+- `last_command_at`
+- `last_command_preview`
+
+のような観測項目が自然に見えてきます。
+
+### 第 5 段階: 終わるときは closeout を明示する
+
+教材上は、`keep` と `remove` をバラバラの小技として見せるより、
+
+> closeout という 1 つの判断に 2 分岐ある
+
+と見せた方が心智が安定します。
+
+```python
+worktree_closeout(
+    name="auth-refactor",
+    action="keep",  # or "remove"
+    reason="Need follow-up review",
+    complete_task=False,
+)
+```
+
+これで読者は次のことを一度に理解できます。
+
+- lane の終わらせ方には選択肢がある
+- その選択には理由を持たせられる
+- closeout は task record / lane record / event log に反映される
+
+もちろん実装下層では、
+
+- `worktree_keep(name)`
+- `worktree_remove(name, reason=..., complete_task=True)`
+
+のような分離 API を持っていても構いません。
+
+ただし教学の主線では、
+
+**closeout decision -> keep / remove**
+
+という形にまとめた方が初心者には伝わります。
+
+## なぜ `status` と `worktree_state` を分けるのか
+
+これは非常に大事な区別です。
+
+初学者はよく、
+
+> task に `status` があるなら十分ではないか
+
+と考えます。
+
+しかし実際は答えている質問が違います。
+
+- `task.status`: その仕事が `pending` / `in_progress` / `completed` のどれか
+- `worktree_state`: その execution lane が `active` / `kept` / `removed` / `unbound` のどれか
+
+たとえば、
+
+```text
+task は completed
+でも worktree は kept
+```
+
+という状態は自然に起こります。
+
+review 用に directory を残しておきたいからです。
+
+したがって、
+
+**goal state と lane state は同じ field に潰してはいけません。**
+
+## なぜ worktree は「Git の小技」で終わらないのか
+
+初見では「別 directory を増やしただけ」に見えるかもしれません。
+
+でも教学上の本質はそこではありません。
+
+本当に重要なのは、
+
+**task と execution directory の対応関係を明示 record として持つこと**
+
+です。
+
+それがあるから system は、
+
+- どの lane がどの task に属するか
+- 完了時に何を closeout すべきか
+- crash 後に何を復元すべきか
+
+を説明できます。
+
+## 前の章とどうつながるか
+
+この章は前段を次のように結びます。
+
+- `s12`: task ID を与える
+- `s15-s17`: teammate と claim を与える
+- `s18`: 各 task に独立 execution lane を与える
+
+流れで書くとこうです。
+
+```text
+task を作る
+  ->
+teammate が claim する
+  ->
+system が worktree lane を割り当てる
+  ->
+commands がその lane の directory で走る
+  ->
+終了時に keep / remove を選ぶ
+```
+
+ここまで来ると multi-agent の並行作業が「同じ場所に集まる chaos」ではなく、
+
+**goal と lane を分けた協調システム**
+
+として見えてきます。
+
+## worktree は task そのものではない
+
+ここは何度でも繰り返す価値があります。
+
+- task は「何をやるか」
+- worktree は「どこでやるか」
+
+です。
+
+同様に、
+
+- runtime slot は「今動いている execution」
+- worktree lane は「どの directory / branch で動くか」
+
+という別軸です。
+
+もしこの辺りが混ざり始めたら、次を開いて整理し直してください。
+
+- [`team-task-lane-model.md`](./team-task-lane-model.md)
+- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)
+- [`entity-map.md`](./entity-map.md)
+
+## 初学者が混ぜやすいポイント
+
+### 1. registry だけあって task record に `worktree` がない
+
+task board から lane の情報が見えなくなります。
+
+### 2. task ID はあるのに command が repo root で走っている
+
+`cwd` が切り替わっていなければ isolation は成立していません。
+
+### 3. `remove` だけを覚えて closeout の意味を教えない
+
+読者は「directory を消す小技」としか理解できなくなります。
+
+### 4. remove 前に dirty state を気にしない
+
+教材版でも最低限、
+
+**消す前に未コミット変更を確認する**
+
+という原則は持たせるべきです。
+
+### 5. `worktree_state` や `closeout` を持たない
+
+lane の終わり方が state として残らなくなります。
+
+### 6. lane を増やすだけで掃除しない
+
+長く使うと registry も directory もすぐ乱れます。
+
+### 7. event log を持たない
+
+create / remove failure や binding ミスの調査が極端にやりづらくなります。
+
+## 教学上の境界
+
+この章でまず教えるべき中心は、製品レベルの Git 運用細目ではありません。
+
+中心は次の 3 行です。
+
+- task が「何をやるか」を記録する
+- worktree が「どこでやるか」を記録する
+- enter / run / closeout が execution lane の lifecycle を構成する
+
+merge 自動化、複雑な回収 policy、cross-machine execution などは、その幹が見えてからで十分です。
+
+この章を読み終えた読者が次の 1 文を言えれば成功です。
+
+> task system は仕事の目標を管理し、worktree system はその仕事を安全に進めるための独立レーンを管理する。
diff --git a/docs/ja/s19-mcp-plugin.md b/docs/ja/s19-mcp-plugin.md
new file mode 100644
index 000000000..27740520d
--- /dev/null
+++ b/docs/ja/s19-mcp-plugin.md
@@ -0,0 +1,255 @@
+# s19: MCP & Plugin
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > [ s19 ]`
+
+> *すべての能力を主プログラムへ直書きする必要はない。外部能力も同じ routing 面へ接続できる。*
+
+## この章が本当に教えるもの
+
+前の章までは、ツールの多くが自分の Python コード内にありました。
+
+これは教学として正しい出発点です。
+
+しかしシステムが大きくなると、自然に次の要望が出ます。
+
+> "外部プログラムの能力を、毎回主プログラムを書き換えずに使えないか?"
+
+それに答えるのが MCP です。
+
+## MCP を一番簡単に言うと
+
+MCP は:
+
+**agent が外部 capability server と会話するための標準的な方法**
+
+と考えれば十分です。
+
+主線は次の 4 ステップです。
+
+1. 外部 server を起動する
+2. どんなツールがあるか聞く
+3. 必要な呼び出しをその server へ転送する
+4. 結果を標準化して主ループへ戻す
+
+## なぜ最後の章なのか
+
+MCP は出発点ではありません。
+
+先に理解しておくべきものがあります。
+
+- agent loop
+- tool routing
+- permissions
+- tasks
+- worktree isolation
+
+それらが見えてからだと、MCP は:
+
+**新しい capability source**
+
+として自然に理解できます。
+
+## 主線とどう併読するか
+
+- MCP を「遠隔 tool」だけで理解しているなら、[`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md) を読んで tools、resources、prompts、plugin discovery を 1 つの platform boundary へ戻します。
+- 外部 capability がなぜ同じ execution surface へ戻るのかを確かめたいなら、[`s02b-tool-execution-runtime.md`](./s02b-tool-execution-runtime.md) を併読します。
+- query control と外部 capability routing が頭の中で分離し始めたら、[`s00a-query-control-plane.md`](./s00a-query-control-plane.md) に戻ります。
+
+## 最小の心智モデル
+
+```text
+LLM
+  |
+  | tool を呼びたい
+  v
+Agent tool router
+  |
+  +-- native tool  -> local Python handler
+  |
+  +-- MCP tool     -> external MCP server
+                        |
+                        v
+                    return result
+```
+
+## 重要な 3 要素
+
+### 1. `MCPClient`
+
+役割:
+
+- server へ接続
+- tool 一覧取得
+- tool 呼び出し
+
+### 2. 命名規則
+
+外部ツールとローカルツールが衝突しないように prefix を付けます。
+
+```text
+mcp__{server}__{tool}
+```
+
+例:
+
+```text
+mcp__postgres__query
+mcp__browser__open_tab
+```
+
+### 3. 1 本の unified router
+
+```python
+if tool_name.startswith("mcp__"):
+    return mcp_router.call(tool_name, arguments)
+else:
+    return native_handler(arguments)
+```
+
+## Plugin は何をするか
+
+MCP が:
+
+> 外部 server とどう会話するか
+
+を扱うなら、plugin は:
+
+> その server をどう発見し、どう設定するか
+
+を扱います。
+
+最小 plugin は:
+
+```text
+.claude-plugin/
+  plugin.json
+```
+
+だけでも十分です。
+
+## 最小設定
+
+```json
+{
+  "name": "my-db-tools",
+  "version": "1.0.0",
+  "mcpServers": {
+    "postgres": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-postgres"]
+    }
+  }
+}
+```
+
+これは要するに:
+
+> "この server が必要なら、このコマンドで起動する"
+
+と主プログラムへ教えているだけです。
+
+## システム全体へどう接続するか
+
+MCP が急に難しく見えるのは、別世界の仕組みとして見てしまうときです。  
+より安定した心智モデルは次です。
+
+```text
+startup
+  ->
+plugin loader が manifest を見つける
+  ->
+server config を取り出す
+  ->
+MCP client が connect / list_tools する
+  ->
+external tools を同じ tool pool に正規化して入れる
+
+runtime
+  ->
+LLM が tool_use を出す
+  ->
+共有 permission gate
+  ->
+native route または MCP route
+  ->
+result normalization
+  ->
+同じ loop へ tool_result を返す
+```
+
+入口は違っても、control plane と execution plane は同じです。
+
+## 重要なデータ構造
+
+### 1. server config
+
+```python
+{
+    "command": "npx",
+    "args": ["-y", "..."],
+    "env": {}
+}
+```
+
+### 2. 標準化された外部ツール定義
+
+```python
+{
+    "name": "mcp__postgres__query",
+    "description": "Run a SQL query",
+    "input_schema": {...}
+}
+```
+
+### 3. client registry
+
+```python
+clients = {
+    "postgres": mcp_client_instance
+}
+```
+
+## 絶対に崩してはいけない境界
+
+この章で最も重要なのは:
+
+**外部ツールも同じ permission 面を通る**
+
+ということです。
+
+MCP が permission を素通りしたら、外側に安全穴を開けるだけです。
+
+## Plugin / Server / Tool を同じ層にしない
+
+| 層 | 何か | 何を担当するか |
+|---|---|---|
+| plugin manifest | 設定宣言 | どの server を見つけて起動するかを教える |
+| MCP server | 外部 process / connection | 能力の集合を expose する |
+| MCP tool | server が出す 1 つの callable capability | モデルが実際に呼ぶ対象 |
+
+最短で覚えるなら:
+
+- plugin = discovery
+- server = connection
+- tool = invocation
+
+## 初学者が迷いやすい点
+
+### 1. いきなりプロトコル細部へ入る
+
+先に見るべきは capability routing です。
+
+### 2. MCP を別世界だと思う
+
+実際には、同じ routing、同じ permission、同じ result append に戻します。
+
+### 3. 正規化を省く
+
+外部ツールをローカルツールと同じ形へ揃えないと、後の心智が急に重くなります。
+
+## Try It
+
+```sh
+cd learn-claude-code
+python agents/s19_mcp_plugin.py
+```
diff --git a/docs/ja/s19a-mcp-capability-layers.md b/docs/ja/s19a-mcp-capability-layers.md
new file mode 100644
index 000000000..40b056394
--- /dev/null
+++ b/docs/ja/s19a-mcp-capability-layers.md
@@ -0,0 +1,257 @@
+# s19a: MCP Capability Layers
+
+> `s19` の主線は引き続き tools-first で進めるべきです。
+> その上で、この bridge doc は次の心智を足します。
+>
+> **MCP は単なる外部 tool 接続ではなく、複数の capability layer を持つ platform です。**
+
+## 主線とどう併読するか
+
+MCP を主線から外れずに学ぶなら次の順がよいです。
+
+- まず [`s19-mcp-plugin.md`](./s19-mcp-plugin.md) を読み、tools-first の入口を固める
+- 次に [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md) を見直し、外部 capability がどう unified tool bus に戻るかを見る
+- state record が混ざり始めたら [`data-structures.md`](./data-structures.md) を見直す
+- concept boundary が混ざり始めたら [`glossary.md`](./glossary.md) と [`entity-map.md`](./entity-map.md) を見直す
+
+## なぜ別立てで必要か
+
+教材 repo として、正文を external tools から始めるのは正しいです。
+
+最も入りやすい入口は:
+
+- 外部 server に接続する
+- tool 定義を受け取る
+- tool を呼ぶ
+- 結果を agent へ戻す
+
+しかし完成度を上げようとすると、すぐ次の問いに出会います。
+
+- server は stdio / HTTP / SSE / WebSocket のどれでつながるのか
+- なぜ `connected` の server もあれば `pending` や `needs-auth` の server もあるのか
+- resources や prompts は tools とどう並ぶのか
+- elicitation はなぜ特別な対話になるのか
+- OAuth のような auth flow はどの層で理解すべきか
+
+capability-layer map がないと、MCP は急に散らばって見えます。
+
+## まず用語
+
+### capability layer とは
+
+capability layer は:
+
+> 大きな system の中の 1 つの責務面
+
+です。
+
+MCP のすべてを 1 つの袋に入れないための考え方です。
+
+### transport とは
+
+transport は接続通路です。
+
+- stdio
+- HTTP
+- SSE
+- WebSocket
+
+### elicitation とは
+
+これは見慣れない用語ですが、教材版では次の理解で十分です。
+
+> MCP server 側が追加情報を要求し、user からさらに入力を引き出す対話
+
+つまり常に:
+
+> agent calls tool -> tool returns result
+
+だけとは限らず、server 側から:
+
+> 続けるためにもっと入力が必要
+
+と言ってくる場合があります。
+
+## 最小の心智モデル
+
+MCP を 6 層で見ると整理しやすいです。
+
+```text
+1. Config Layer
+   server 設定がどう表現されるか
+
+2. Transport Layer
+   何の通路で接続するか
+
+3. Connection State Layer
+   connected / pending / failed / needs-auth
+
+4. Capability Layer
+   tools / resources / prompts / elicitation
+
+5. Auth Layer
+   認証が必要か、認証状態は何か
+
+6. Router Integration Layer
+   tool routing / permission / notifications にどう戻るか
+```
+
+ここで最重要なのは:
+
+**tools は一層であって、MCP の全体ではない**
+
+という点です。
+
+## なぜ正文は tools-first のままでよいか
+
+教材として大事なポイントです。
+
+MCP に複数 layer があっても、正文主線はまず次で十分です。
+
+### Step 1: 外部 tools から入る
+
+これは読者がすでに学んだものと最も自然につながります。
+
+- local tools
+- external tools
+- 1 本の shared router
+
+### Step 2: その上で他の layer があると知らせる
+
+例えば:
+
+- resources
+- prompts
+- elicitation
+- auth
+
+### Step 3: どこまで実装するかを決める
+
+これが教材 repo の目的に合っています。
+
+**まず似た system を作り、その後で platform layer を厚くする**
+
+## 主要 record
+
+### 1. `ScopedMcpServerConfig`
+
+教材版でも最低限この概念は見せるべきです。
+
+```python
+config = {
+    "name": "postgres",
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "..."],
+    "scope": "project",
+}
+```
+
+`scope` が重要なのは、server config が 1 つの場所からだけ来るとは限らないからです。
+
+### 2. MCP connection state
+
+```python
+server_state = {
+    "name": "postgres",
+    "status": "connected",   # pending / failed / needs-auth / disabled
+    "config": {...},
+}
+```
+
+### 3. `MCPToolSpec`
+
+```python
+tool = {
+    "name": "mcp__postgres__query",
+    "description": "...",
+    "input_schema": {...},
+}
+```
+
+### 4. `ElicitationRequest`
+
+```python
+request = {
+    "server_name": "some-server",
+    "message": "Please provide additional input",
+    "requested_schema": {...},
+}
+```
+
+ここでの教材上の要点は、elicitation を今すぐ全部実装することではありません。
+
+要点は:
+
+**MCP は常に一方向の tool invocation だけとは限らない**
+
+という点です。
+
+## より整理された図
+
+```text
+MCP Config
+  |
+  v
+Transport
+  |
+  v
+Connection State
+  |
+  +-- connected
+  +-- pending
+  +-- needs-auth
+  +-- failed
+  |
+  v
+Capabilities
+  +-- tools
+  +-- resources
+  +-- prompts
+  +-- elicitation
+  |
+  v
+Router / Permission / Notification Integration
+```
+
+## なぜ auth を主線の中心にしない方がよいか
+
+auth は platform 全体では本物の layer です。
+
+しかし正文が早い段階で OAuth や vendor 固有 detail へ落ちると、初学者は system shape を失います。
+
+教材としては次の順がよいです。
+
+- まず auth layer が存在すると知らせる
+- 次に `connected` と `needs-auth` が違う connection state だと教える
+- さらに進んだ platform work の段階で auth state machine を詳しく扱う
+
+これなら正確さを保ちつつ、主線を壊しません。
+
+## `s19` と `s02a` との関係
+
+- `s19` 本文は tools-first の external capability path を教える
+- この note は broader platform map を補う
+- `s02a` は MCP capability が unified tool control plane にどう戻るかを補う
+
+三つを合わせて初めて、読者は本当の構図を持てます。
+
+**MCP は外部 capability platform であり、tools はその最初の切り口にすぎない**
+
+## 初学者がやりがちな間違い
+
+### 1. MCP を外部 tool catalog だけだと思う
+
+その理解だと resources / prompts / auth / elicitation が後で急に見えて混乱します。
+
+### 2. transport や OAuth detail に最初から沈み込む
+
+これでは主線が壊れます。
+
+### 3. MCP tool を permission の外に置く
+
+system boundary に危険な横穴を開けます。
+
+### 4. server config・connection state・exposed capabilities を一つに混ぜる
+
+この三層は概念的に分けておくべきです。
diff --git a/docs/ja/teaching-scope.md b/docs/ja/teaching-scope.md
new file mode 100644
index 000000000..e0ab36b29
--- /dev/null
+++ b/docs/ja/teaching-scope.md
@@ -0,0 +1,142 @@
+# 教材の守備範囲
+
+> この文書は、この教材が何を教え、何を意図的に主線から外すかを明示するためのものです。
+
+## この教材の目標
+
+これは、ある実運用コードベースを逐行で注釈するためのリポジトリではありません。
+
+本当の目標は:
+
+**高完成度の coding-agent harness を 0 から自力で作れるようにすること**
+
+です。
+
+そのために守るべき条件は 3 つあります。
+
+1. 学習者が本当に自分で作り直せること
+2. 主線が side detail に埋もれないこと
+3. 実在しない mechanism を学ばせないこと
+
+## 主線章で必ず明示すべきこと
+
+各章は次をはっきりさせるべきです。
+
+- その mechanism が何の問題を解くか
+- どの module / layer に属するか
+- どんな state を持つか
+- どんな data structure を導入するか
+- loop にどうつながるか
+- runtime flow がどう変わるか
+
+## 主線を支配させない方がよいもの
+
+次の話題は存在してよいですが、初心者向け主線の中心に置くべきではありません。
+
+- packaging / build / release flow
+- cross-platform compatibility glue
+- telemetry / enterprise policy wiring
+- historical compatibility branches
+- product 固有の naming accident
+- 上流コードとの逐行一致
+
+## ここでいう高忠実度とは何か
+
+高忠実度とは、すべての周辺 detail を 1:1 で再現することではありません。
+
+ここで寄せるべき対象は:
+
+- core runtime model
+- module boundaries
+- key records
+- state transitions
+- major subsystem cooperation
+
+つまり:
+
+**幹には忠実に、枝葉は教材として意識的に簡略化する**
+
+ということです。
+
+## 想定読者
+
+標準的な想定読者は:
+
+- 基本的な Python は読める
+- 関数、クラス、list、dict は分かる
+- ただし agent platform は初学者でもよい
+
+したがって文章は:
+
+- 先に概念を説明する
+- 1つの概念を1か所で完結させる
+- `what -> why -> how` の順で進める
+
+のが望ましいです。
+
+## 各章の推奨構成
+
+1. これが無いと何が困るか
+2. 先に新しい言葉を説明する
+3. 最小の心智モデルを示す
+4. 主要 record / data structure を示す
+5. 最小で正しい実装を示す
+6. loop への接続点を示す
+7. 初学者がやりがちな誤りを示す
+8. 高完成度版で後から足すものを示す
+
+## 用語の扱い
+
+次の種類の語が出るときは、名前だけ投げず意味を説明した方がよいです。
+
+- design pattern
+- data structure
+- concurrency term
+- protocol / networking term
+- 一般的ではない engineering vocabulary
+
+例:
+
+- state machine
+- scheduler
+- queue
+- worktree
+- DAG
+- protocol envelope
+
+## 最小正解版の原則
+
+現実の mechanism は複雑でも、教材は最初から全分岐を見せる必要はありません。
+
+よい順序は:
+
+1. 最小で正しい版を示す
+2. それで既に解ける core problem を示す
+3. 後で何を足すかを示す
+
+例:
+
+- permission: `deny -> mode -> allow -> ask`
+- error recovery: 主要な回復枝から始める
+- task system: records / dependencies / unlocks から始める
+- team protocol: request / response + `request_id` から始める
+
+## 逆向きソースの使い方
+
+逆向きで得たソースは:
+
+**保守者の校正材料**
+
+として使うのが正しいです。
+
+役割は:
+
+- 主線 mechanism の説明がズレていないか確かめる
+- 重要な境界や record が抜けていないか確かめる
+- 教材実装が fiction に流れていないか確かめる
+
+読者がそれを見ないと本文を理解できない構成にしてはいけません。
+
+## 一文で覚える
+
+**よい教材は、細部をたくさん言うことより、重要な細部を完全に説明し、重要でない細部を安全に省くことによって質が決まります。**
diff --git a/docs/ja/team-task-lane-model.md b/docs/ja/team-task-lane-model.md
new file mode 100644
index 000000000..58109c93c
--- /dev/null
+++ b/docs/ja/team-task-lane-model.md
@@ -0,0 +1,308 @@
+# Team Task Lane Model
+
+> `s15-s18` に入ると、関数名よりも先に混ざりやすいものがあります。
+>
+> それは、
+>
+> **誰が働き、誰が調整し、何が目標を記録し、何が実行レーンを提供しているのか**
+>
+> という層の違いです。
+
+## この橋渡し資料が解決すること
+
+`s15-s18` を通して読むと、次の言葉が一つの曖昧な塊になりやすくなります。
+
+- teammate
+- protocol request
+- task
+- runtime task
+- worktree
+
+全部「仕事が進む」ことに関係していますが、同じ層ではありません。
+
+ここを分けないと、後半が急に分かりにくくなります。
+
+- teammate は task と同じなのか
+- `request_id` と `task_id` は何が違うのか
+- worktree は runtime task の一種なのか
+- task が終わっているのに、なぜ worktree が kept のままなのか
+
+この資料は、その層をきれいに分けるためのものです。
+
+## 読む順番
+
+1. [`s15-agent-teams.md`](./s15-agent-teams.md) で長寿命 teammate を確認する
+2. [`s16-team-protocols.md`](./s16-team-protocols.md) で追跡可能な request-response を確認する
+3. [`s17-autonomous-agents.md`](./s17-autonomous-agents.md) で自律 claim を確認する
+4. [`s18-worktree-task-isolation.md`](./s18-worktree-task-isolation.md) で隔離 execution lane を確認する
+
+用語が混ざってきたら、次も見直してください。
+
+- [`entity-map.md`](./entity-map.md)
+- [`data-structures.md`](./data-structures.md)
+- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)
+
+## まずはこの区別を固定する
+
+```text
+teammate
+  = 長期に協力する主体
+
+protocol request
+  = チーム内で追跡される調整要求
+
+task
+  = 何をやるべきか
+
+runtime task / execution slot
+  = 今まさに動いている実行単位
+
+worktree
+  = 他の変更とぶつからずに仕事を進める実行ディレクトリ
+```
+
+特に混ざりやすいのは最後の3つです。
+
+- `task`
+- `runtime task`
+- `worktree`
+
+毎回、次の3つを別々に問い直してください。
+
+- これは目標か
+- これは実行中の単位か
+- これは隔離された実行ディレクトリか
+
+## 一番小さい図
+
+```text
+Team Layer
+  teammate: alice (frontend)
+
+Protocol Layer
+  request_id=req_01
+  kind=plan_approval
+  status=pending
+
+Work Graph Layer
+  task_id=12
+  subject="Implement login page"
+  owner="alice"
+  status="in_progress"
+
+Runtime Layer
+  runtime_id=rt_01
+  type=in_process_teammate
+  status=running
+
+Execution Lane Layer
+  worktree=login-page
+  path=.worktrees/login-page
+  status=active
+```
+
+この中で、仕事そのものの目標を表しているのは一つだけです。
+
+> `task_id=12`
+
+他は、その目標のまわりで協調・実行・分離を支える層です。
+
+## 1. Teammate: 誰が協力しているか
+
+`s15` で導入される層です。
+
+ここが答えること：
+
+- 長寿命 worker の名前
+- 役割
+- `working` / `idle` / `shutdown`
+- 独立した inbox を持つか
+
+例：
+
+```python
+member = {
+    "name": "alice",
+    "role": "frontend",
+    "status": "idle",
+}
+```
+
+大事なのは「agent をもう1個増やす」ことではありません。
+
+> 繰り返し仕事を受け取れる長寿命の身元
+
+これが本質です。
+
+## 2. Protocol Request: 何を調整しているか
+
+`s16` の層です。
+
+ここが答えること：
+
+- 誰が誰に依頼したか
+- どんな種類の request か
+- pending なのか、もう解決済みなのか
+
+例：
+
+```python
+request = {
+    "request_id": "a1b2c3d4",
+    "kind": "plan_approval",
+    "from": "alice",
+    "to": "lead",
+    "status": "pending",
+}
+```
+
+これは普通の会話ではありません。
+
+> 状態更新を続けられる調整記録
+
+です。
+
+## 3. Task: 何をやるのか
+
+これは `s12` の durable work-graph task であり、`s17` で teammate が claim する対象です。
+
+ここが答えること：
+
+- 目標は何か
+- 誰が担当しているか
+- 何にブロックされているか
+- 進捗状態はどうか
+
+例：
+
+```python
+task = {
+    "id": 12,
+    "subject": "Implement login page",
+    "status": "in_progress",
+    "owner": "alice",
+    "blockedBy": [],
+}
+```
+
+キーワードは：
+
+**目標**
+
+ディレクトリでも、protocol でも、process でもありません。
+
+## 4. Runtime Task / Execution Slot: 今なにが走っているか
+
+この層は `s13` の橋渡し資料ですでに説明されていますが、`s15-s18` ではさらに重要になります。
+
+例：
+
+- background shell が走っている
+- 長寿命 teammate が今作業している
+- monitor が外部状態を見ている
+
+これらは、
+
+> 実行中の slot
+
+として理解するのが一番きれいです。
+
+例：
+
+```python
+runtime = {
+    "id": "rt_01",
+    "type": "in_process_teammate",
+    "status": "running",
+    "work_graph_task_id": 12,
+}
+```
+
+大事な境界：
+
+- 1つの task から複数の runtime task が派生しうる
+- runtime task は durable な目標そのものではなく、実行インスタンスである
+
+## 5. Worktree: どこでやるのか
+
+`s18` で導入される execution lane 層です。
+
+ここが答えること：
+
+- どの隔離ディレクトリを使うか
+- どの task と結び付いているか
+- その lane は `active` / `kept` / `removed` のどれか
+
+例：
+
+```python
+worktree = {
+    "name": "login-page",
+    "path": ".worktrees/login-page",
+    "task_id": 12,
+    "status": "active",
+}
+```
+
+キーワードは：
+
+**実行境界**
+
+task そのものではなく、その task を進めるための隔離レーンです。
+
+## 層はどうつながるか
+
+```text
+teammate
+  protocol request で協調し
+  task を claim し
+  execution slot として走り
+  worktree lane の中で作業する
+```
+
+もっと具体的に言うなら：
+
+> `alice` が `task #12` を claim し、`login-page` worktree lane の中でそれを進める
+
+この言い方は、
+
+> "alice is doing the login-page worktree task"
+
+のような曖昧な言い方よりずっと正確です。
+
+後者は次の3層を一つに潰してしまいます。
+
+- teammate
+- task
+- worktree
+
+## よくある間違い
+
+### 1. teammate と task を同じものとして扱う
+
+teammate は実行者、task は目標です。
+
+### 2. `request_id` と `task_id` を同じ種類の ID だと思う
+
+片方は調整、片方は目標です。
+
+### 3. runtime slot を durable task だと思う
+
+実行は終わっても、durable task は残ることがあります。
+
+### 4. worktree を task そのものだと思う
+
+worktree は execution lane でしかありません。
+
+### 5. 「並列で動く」とだけ言って層の名前を出さない
+
+良い教材は「agent がたくさんいる」で止まりません。
+
+次のように言える必要があります。
+
+> teammate は長期協力を担い、request は調整を追跡し、task は目標を記録し、runtime slot は実行を担い、worktree は実行ディレクトリを隔離する。
+
+## 読み終えたら言えるようになってほしいこと
+
+1. `s17` の自律 claim は `s12` の work-graph task を取るのであって、`s13` の runtime slot を取るのではない。
+2. `s18` の worktree は task に execution lane を結び付けるのであって、task をディレクトリへ変えるのではない。
diff --git a/docs/zh/data-structures.md b/docs/zh/data-structures.md
new file mode 100644
index 000000000..8b7ff979c
--- /dev/null
+++ b/docs/zh/data-structures.md
@@ -0,0 +1,800 @@
+# Core Data Structures (核心数据结构总表)
+
+> 学习 agent，最容易迷路的地方不是功能太多，而是不知道“状态到底放在哪”。这份文档把主线章节和桥接章节里反复出现的关键数据结构集中列出来，方便你把整套系统看成一张图。
+
+## 推荐联读
+
+建议把这份总表当成“状态地图”来用：
+
+- 先不懂词，就回 [`glossary.md`](./glossary.md)。
+- 先不懂边界，就回 [`entity-map.md`](./entity-map.md)。
+- 如果卡在 `TaskRecord` 和 `RuntimeTaskState`，继续看 [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)。
+- 如果卡在 MCP 为什么还有 resource / prompt / elicitation，继续看 [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)。
+
+## 先记住两个总原则
+
+### 原则 1：区分“内容状态”和“流程状态”
+
+- `messages`、`tool_result`、memory 正文，属于内容状态。
+- `turn_count`、`transition`、`pending_classifier_check`，属于流程状态。
+
+很多初学者会把这两类状态混在一起。  
+一混，后面就很难看懂为什么一个结构完整的系统会需要控制平面。
+
+### 原则 2：区分“持久状态”和“运行时状态”
+
+- task、memory、schedule 这类状态，通常会落盘，跨会话存在。
+- runtime task、当前 permission decision、当前 MCP connection 这类状态，通常只在系统运行时活着。
+
+## 1. 查询与对话控制状态
+
+### Message
+
+作用：保存当前对话和工具往返历史。
+
+最小形状：
+
+```python
+message = {
+    "role": "user" | "assistant",
+    "content": "...",
+}
+```
+
+支持工具调用后，`content` 常常不再只是字符串，而会变成块列表，其中可能包含：
+
+- text block
+- `tool_use`
+- `tool_result`
+
+相关章节：
+
+- `s01`
+- `s02`
+- `s06`
+- `s10`
+
+### NormalizedMessage
+
+作用：把不同来源的消息整理成统一、稳定、可送给模型 API 的消息格式。
+
+最小形状：
+
+```python
+message = {
+    "role": "user" | "assistant",
+    "content": [
+        {"type": "text", "text": "..."},
+    ],
+}
+```
+
+它和普通 `Message` 的区别是：
+
+- `Message` 偏“系统内部记录”
+- `NormalizedMessage` 偏“准备发给模型之前的统一输入”
+
+相关章节：
+
+- `s10`
+- [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md)
+
+### CompactSummary
+
+作用：上下文太长时，用摘要替代旧消息原文。
+
+最小形状：
+
+```python
+summary = {
+    "task_overview": "...",
+    "current_state": "...",
+    "key_decisions": ["..."],
+    "next_steps": ["..."],
+}
+```
+
+相关章节：
+
+- `s06`
+- `s11`
+
+### SystemPromptBlock
+
+作用：把 system prompt 从一整段大字符串，拆成若干可管理片段。
+
+最小形状：
+
+```python
+block = {
+    "text": "...",
+    "cache_scope": None,
+}
+```
+
+你可以把它理解成：
+
+- `text`：这一段提示词正文
+- `cache_scope`：这一段是否可以复用缓存
+
+相关章节：
+
+- `s10`
+- [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md)
+
+### PromptParts
+
+作用：在真正拼成 system prompt 之前，先把各部分拆开管理。
+
+最小形状：
+
+```python
+parts = {
+    "core": "...",
+    "tools": "...",
+    "skills": "...",
+    "memory": "...",
+    "claude_md": "...",
+    "dynamic": "...",
+}
+```
+
+相关章节：
+
+- `s10`
+
+### QueryParams
+
+作用：进入查询主循环时，外部一次性传进来的输入集合。
+
+最小形状：
+
+```python
+params = {
+    "messages": [...],
+    "system_prompt": "...",
+    "user_context": {...},
+    "system_context": {...},
+    "tool_use_context": {...},
+    "fallback_model": None,
+    "max_output_tokens_override": None,
+    "max_turns": None,
+}
+```
+
+它的重要点在于：
+
+- 这是“本次 query 的入口输入”
+- 它和循环内部不断变化的状态，不是同一层
+
+相关章节：
+
+- [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)
+
+### QueryState
+
+作用：保存一条 query 在多轮循环之间不断变化的流程状态。
+
+最小形状：
+
+```python
+state = {
+    "messages": [...],
+    "tool_use_context": {...},
+    "turn_count": 1,
+    "max_output_tokens_recovery_count": 0,
+    "has_attempted_reactive_compact": False,
+    "max_output_tokens_override": None,
+    "pending_tool_use_summary": None,
+    "stop_hook_active": False,
+    "transition": None,
+}
+```
+
+这类字段的共同特点是：
+
+- 它们不是对话内容
+- 它们是“这一轮该怎么继续”的控制状态
+
+相关章节：
+
+- [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)
+- `s11`
+
+### TransitionReason
+
+作用：记录“上一轮为什么继续了，而不是结束”。
+
+最小形状：
+
+```python
+transition = {
+    "reason": "next_turn",
+}
+```
+
+在更完整的 query 状态里，这个 `reason` 常见会有这些类型：
+
+- `next_turn`
+- `reactive_compact_retry`
+- `token_budget_continuation`
+- `max_output_tokens_recovery`
+- `stop_hook_continuation`
+
+它的价值不是炫技，而是让：
+
+- 日志更清楚
+- 测试更清楚
+- 恢复链路更清楚
+
+相关章节：
+
+- [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)
+- `s11`
+
+## 2. 工具、权限与 hook 执行状态
+
+### ToolSpec
+
+作用：告诉模型“有哪些工具、每个工具要什么输入”。
+
+最小形状：
+
+```python
+tool = {
+    "name": "read_file",
+    "description": "Read file contents.",
+    "input_schema": {...},
+}
+```
+
+相关章节：
+
+- `s02`
+- `s19`
+
+### ToolDispatchMap
+
+作用：把工具名映射到真实执行函数。
+
+最小形状：
+
+```python
+handlers = {
+    "read_file": run_read,
+    "write_file": run_write,
+    "bash": run_bash,
+}
+```
+
+相关章节：
+
+- `s02`
+
+### ToolUseContext
+
+作用：把工具运行时需要的共享环境打成一个总线。
+
+最小形状：
+
+```python
+tool_use_context = {
+    "tools": handlers,
+    "permission_context": {...},
+    "mcp_clients": [],
+    "messages": [...],
+    "app_state": {...},
+    "cwd": "...",
+    "read_file_state": {...},
+    "notifications": [],
+}
+```
+
+这层很关键。  
+因为在更完整的工具执行环境里，工具拿到的不只是 `tool_input`，还包括：
+
+- 当前权限环境
+- 当前消息
+- 当前 app state
+- 当前 MCP client
+- 当前文件读取缓存
+
+相关章节：
+
+- [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md)
+- `s07`
+- `s19`
+
+### PermissionRule
+
+作用：描述某类工具调用命中后该怎么处理。
+
+最小形状：
+
+```python
+rule = {
+    "tool_name": "bash",
+    "rule_content": "rm -rf *",
+    "behavior": "deny",
+}
+```
+
+相关章节：
+
+- `s07`
+
+### PermissionRuleSource
+
+作用：标记一条权限规则是从哪里来的。
+
+最小形状：
+
+```python
+source = (
+    "userSettings"
+    | "projectSettings"
+    | "localSettings"
+    | "flagSettings"
+    | "policySettings"
+    | "cliArg"
+    | "command"
+    | "session"
+)
+```
+
+这个结构的意义是：
+
+- 你不只知道“有什么规则”
+- 还知道“这条规则是谁加进来的”
+
+相关章节：
+
+- `s07`
+
+### PermissionDecision
+
+作用：表示一次工具调用当前该允许、拒绝还是提问。
+
+最小形状：
+
+```python
+decision = {
+    "behavior": "allow" | "deny" | "ask",
+    "reason": "matched deny rule",
+}
+```
+
+在更完整的权限流里，`ask` 结果还可能带：
+
+- 修改后的输入
+- 建议写回哪些规则更新
+- 一个后台自动分类检查
+
+相关章节：
+
+- `s07`
+
+### PermissionUpdate
+
+作用：描述“这次权限确认之后，要把什么改回配置里”。
+
+最小形状：
+
+```python
+update = {
+    "type": "addRules" | "removeRules" | "setMode" | "addDirectories",
+    "destination": "userSettings" | "projectSettings" | "localSettings" | "session",
+    "rules": [],
+}
+```
+
+它解决的是一个很容易被漏掉的问题：
+
+用户这次点了“允许”，到底只是这一次放行，还是要写回会话、项目，甚至用户级配置。
+
+相关章节：
+
+- `s07`
+
+### HookContext
+
+作用：把某个 hook 事件发生时的上下文打包给外部脚本。
+
+最小形状：
+
+```python
+context = {
+    "event": "PreToolUse",
+    "tool_name": "bash",
+    "tool_input": {...},
+    "tool_result": "...",
+}
+```
+
+相关章节：
+
+- `s08`
+
+### RecoveryState
+
+作用：记录恢复流程已经尝试到哪里。
+
+最小形状：
+
+```python
+state = {
+    "continuation_attempts": 0,
+    "compact_attempts": 0,
+    "transport_attempts": 0,
+}
+```
+
+相关章节：
+
+- `s11`
+
+## 3. 持久化工作状态
+
+### TodoItem
+
+作用：当前会话里的轻量计划项。
+
+最小形状：
+
+```python
+todo = {
+    "content": "Read parser.py",
+    "status": "pending" | "completed",
+}
+```
+
+相关章节：
+
+- `s03`
+
+### MemoryEntry
+
+作用：保存跨会话仍然有价值的信息。
+
+最小形状：
+
+```python
+memory = {
+    "name": "prefer_tabs",
+    "description": "User prefers tabs for indentation",
+    "type": "user" | "feedback" | "project" | "reference",
+    "scope": "private" | "team",
+    "body": "...",
+}
+```
+
+这里最重要的不是字段多，而是边界清楚：
+
+- 只存不容易从当前项目状态重新推出来的东西
+- 记忆可能会过时，要验证
+
+相关章节：
+
+- `s09`
+
+### TaskRecord
+
+作用：磁盘上的工作图任务节点。
+
+最小形状：
+
+```python
+task = {
+    "id": 12,
+    "subject": "Implement auth module",
+    "description": "",
+    "status": "pending",
+    "blockedBy": [],
+    "blocks": [],
+    "owner": "",
+    "worktree": "",
+}
+```
+
+重点字段：
+
+- `blockedBy`：谁挡着我
+- `blocks`：我挡着谁
+- `owner`：谁认领了
+- `worktree`：在哪个隔离目录里做
+
+相关章节：
+
+- `s12`
+- `s17`
+- `s18`
+- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)
+
+### ScheduleRecord
+
+作用：记录未来要触发的调度任务。
+
+最小形状：
+
+```python
+schedule = {
+    "id": "job_001",
+    "cron": "0 9 * * 1",
+    "prompt": "Generate weekly report",
+    "recurring": True,
+    "durable": True,
+    "created_at": 1710000000.0,
+    "last_fired_at": None,
+}
+```
+
+相关章节：
+
+- `s14`
+
+## 4. 运行时执行状态
+
+### RuntimeTaskState
+
+作用：表示系统里一个“正在运行的执行单元”。
+
+最小形状：
+
+```python
+runtime_task = {
+    "id": "b8k2m1qz",
+    "type": "local_bash",
+    "status": "running",
+    "description": "Run pytest",
+    "start_time": 1710000000.0,
+    "end_time": None,
+    "output_file": ".task_outputs/b8k2m1qz.txt",
+    "notified": False,
+}
+```
+
+这和 `TaskRecord` 不是一回事：
+
+- `TaskRecord` 管工作目标
+- `RuntimeTaskState` 管当前执行槽位
+
+相关章节：
+
+- `s13`
+- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)
+
+### TeamMember
+
+作用：记录一个持久队友是谁、在做什么。
+
+最小形状：
+
+```python
+member = {
+    "name": "alice",
+    "role": "coder",
+    "status": "idle",
+}
+```
+
+相关章节：
+
+- `s15`
+- `s17`
+
+### MessageEnvelope
+
+作用：队友之间传递结构化消息。
+
+最小形状：
+
+```python
+message = {
+    "type": "message" | "shutdown_request" | "plan_approval",
+    "from": "lead",
+    "to": "alice",
+    "request_id": "req_001",
+    "content": "...",
+    "payload": {},
+    "timestamp": 1710000000.0,
+}
+```
+
+相关章节：
+
+- `s15`
+- `s16`
+
+### RequestRecord
+
+作用：追踪一个协议请求当前走到哪里。
+
+最小形状：
+
+```python
+request = {
+    "request_id": "req_001",
+    "kind": "shutdown" | "plan_review",
+    "status": "pending" | "approved" | "rejected" | "expired",
+    "from": "lead",
+    "to": "alice",
+}
+```
+
+相关章节：
+
+- `s16`
+
+### WorktreeRecord
+
+作用：记录一个任务绑定的隔离工作目录。
+
+最小形状：
+
+```python
+worktree = {
+    "name": "auth-refactor",
+    "path": ".worktrees/auth-refactor",
+    "branch": "wt/auth-refactor",
+    "task_id": 12,
+    "status": "active",
+}
+```
+
+相关章节：
+
+- `s18`
+
+### WorktreeEvent
+
+作用：记录 worktree 生命周期事件，便于恢复和排查。
+
+最小形状：
+
+```python
+event = {
+    "event": "worktree.create.after",
+    "task_id": 12,
+    "worktree": "auth-refactor",
+    "ts": 1710000000.0,
+}
+```
+
+相关章节：
+
+- `s18`
+
+## 5. 外部平台与 MCP 状态
+
+### ScopedMcpServerConfig
+
+作用：描述一个 MCP server 应该如何连接，以及它的配置来自哪个作用域。
+
+最小形状：
+
+```python
+config = {
+    "name": "postgres",
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "..."],
+    "scope": "project",
+}
+```
+
+这个 `scope` 很重要，因为 server 配置可能来自：
+
+- 本地
+- 用户
+- 项目
+- 动态注入
+- 插件或托管来源
+
+相关章节：
+
+- `s19`
+- [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md)
+- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)
+- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)
+
+### MCPServerConnectionState
+
+作用：表示一个 MCP server 当前连到了哪一步。
+
+最小形状：
+
+```python
+server_state = {
+    "name": "postgres",
+    "type": "connected",   # pending / failed / needs-auth / disabled
+    "config": {...},
+}
+```
+
+这层特别重要，因为“有没有接上”不是布尔值，而是多种状态：
+
+- `connected`
+- `pending`
+- `failed`
+- `needs-auth`
+- `disabled`
+
+相关章节：
+
+- `s19`
+- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)
+
+### MCPToolSpec
+
+作用：把外部 MCP 工具转换成 agent 内部统一工具定义。
+
+最小形状：
+
+```python
+mcp_tool = {
+    "name": "mcp__postgres__query",
+    "description": "Run a SQL query",
+    "input_schema": {...},
+}
+```
+
+相关章节：
+
+- `s19`
+
+### ElicitationRequest
+
+作用：表示 MCP server 反过来向用户请求额外输入。
+
+最小形状：
+
+```python
+request = {
+    "server_name": "some-server",
+    "message": "Please provide additional input",
+    "requested_schema": {...},
+}
+```
+
+它提醒你一件事：
+
+- MCP 不只是“模型主动调工具”
+- 外部 server 也可能反过来请求补充输入
+
+相关章节：
+
+- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)
+
+## 最后用一句话把它们串起来
+
+如果你只想记一条总线索，可以记这个：
+
+```text
+messages / prompt / query state
+  管本轮输入和继续理由
+
+tools / permissions / hooks
+  管动作怎么安全执行
+
+memory / task / schedule
+  管跨轮、跨会话的持久工作
+
+runtime task / team / worktree
+  管当前执行车道
+
+mcp
+  管系统怎样向外接能力
+```
+
+这份总表最好配合 [`s00-architecture-overview.md`](./s00-architecture-overview.md) 和 [`entity-map.md`](./entity-map.md) 一起看。
+
+## 教学边界
+
+这份总表只负责做两件事：
+
+- 帮你确认一个状态到底属于哪一层
+- 帮你确认这个状态大概长什么样
+
+它不负责穷举真实系统里的每一个字段、每一条兼容分支、每一种产品化补丁。
+
+如果你已经知道某个状态归谁管、什么时候创建、什么时候销毁，再回到对应章节看执行路径，理解会顺很多。
diff --git a/docs/zh/entity-map.md b/docs/zh/entity-map.md
new file mode 100644
index 000000000..4df407720
--- /dev/null
+++ b/docs/zh/entity-map.md
@@ -0,0 +1,199 @@
+# Entity Map (系统实体边界图)
+
+> 这份文档不是某一章的正文，而是一张“别再混词”的地图。  
+> 到了仓库后半程，真正让读者困惑的往往不是代码，而是：
+>
+> **同一个系统里，为什么会同时出现这么多看起来很像、但其实不是一回事的实体。**
+
+## 这张图和另外几份桥接文档怎么分工
+
+- 这份图先回答：一个词到底属于哪一层。
+- [`glossary.md`](./glossary.md) 先回答：这个词到底是什么意思。
+- [`data-structures.md`](./data-structures.md) 再回答：这个词落到代码里时，状态长什么样。
+- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) 专门补“工作图任务”和“运行时任务”的分层。
+- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md) 专门补 MCP 平台层不是只有 tools。
+
+## 先给一个总图
+
+```text
+对话层
+  - message
+  - prompt block
+  - reminder
+
+动作层
+  - tool call
+  - tool result
+  - hook event
+
+工作层
+  - work-graph task
+  - runtime task
+  - protocol request
+
+执行层
+  - subagent
+  - teammate
+  - worktree lane
+
+平台层
+  - mcp server
+  - mcp capability
+  - memory record
+```
+
+## 最容易混淆的 8 对概念
+
+### 1. Message vs Prompt Block
+
+| 实体 | 它是什么 | 它不是什么 | 常见位置 |
+|---|---|---|---|
+| `Message` | 对话历史中的一条消息 | 不是长期系统规则 | `messages[]` |
+| `Prompt Block` | system prompt 内的一段稳定说明 | 不是某一轮刚发生的事件 | prompt builder |
+
+简单记法：
+
+- message 更像“对话内容”
+- prompt block 更像“系统说明”
+
+### 2. Todo / Plan vs Task
+
+| 实体 | 它是什么 | 它不是什么 |
+|---|---|---|
+| `todo / plan` | 当前轮或当前阶段的过程性安排 | 不是长期持久化工作图 |
+| `task` | 持久化的工作节点 | 不是某一轮的临时思路 |
+
+### 3. Work-Graph Task vs Runtime Task
+
+| 实体 | 它是什么 | 它不是什么 |
+|---|---|---|
+| `work-graph task` | 任务板上的工作节点 | 不是系统里活着的执行单元 |
+| `runtime task` | 当前正在执行的后台/agent/monitor 槽位 | 不是依赖图节点 |
+
+这对概念是整个仓库后半程最关键的区分之一。
+
+### 4. Subagent vs Teammate
+
+| 实体 | 它是什么 | 它不是什么 |
+|---|---|---|
+| `subagent` | 一次性委派执行者 | 不是长期在线成员 |
+| `teammate` | 持久存在、可重复接活的队友 | 不是一次性摘要工具 |
+
+### 5. Protocol Request vs Normal Message
+
+| 实体 | 它是什么 | 它不是什么 |
+|---|---|---|
+| `normal message` | 自由文本沟通 | 不是可追踪的审批流程 |
+| `protocol request` | 带 request_id 的结构化请求 | 不是随便说一句话 |
+
+### 6. Worktree vs Task
+
+| 实体 | 它是什么 | 它不是什么 |
+|---|---|---|
+| `task` | 说明要做什么 | 不是目录 |
+| `worktree` | 说明在哪做 | 不是工作目标 |
+
+### 7. Memory vs CLAUDE.md
+
+| 实体 | 它是什么 | 它不是什么 |
+|---|---|---|
+| `memory` | 跨会话仍有价值、但不易从当前代码直接推出来的信息 | 不是项目规则文件 |
+| `CLAUDE.md` | 长期规则、约束和说明 | 不是用户偏好或项目动态背景 |
+
+### 8. MCP Server vs MCP Tool
+
+| 实体 | 它是什么 | 它不是什么 |
+|---|---|---|
+| `MCP server` | 外部能力提供者 | 不是单个工具定义 |
+| `MCP tool` | 某个 server 暴露出来的一项具体能力 | 不是完整平台连接本身 |
+
+## 一张“是什么 / 存在哪里”的速查表
+
+| 实体 | 主要作用 | 典型存放位置 |
+|---|---|---|
+| `Message` | 当前对话历史 | `messages[]` |
+| `PromptParts` | system prompt 的组装片段 | prompt builder |
+| `PermissionRule` | 工具执行前的决策规则 | settings / session state |
+| `HookEvent` | 某个时机触发的扩展点 | hook config |
+| `MemoryEntry` | 跨会话有价值信息 | `.memory/` |
+| `TaskRecord` | 持久化工作节点 | `.tasks/` |
+| `RuntimeTaskState` | 正在执行的任务槽位 | runtime task manager |
+| `TeamMember` | 持久队友 | `.team/config.json` |
+| `MessageEnvelope` | 队友间结构化消息 | `.team/inbox/*.jsonl` |
+| `RequestRecord` | 审批/关机等协议状态 | request tracker |
+| `WorktreeRecord` | 隔离工作目录记录 | `.worktrees/index.json` |
+| `MCPServerConfig` | 外部 server 配置 | plugin / settings |
+
+## 后半程推荐怎么记
+
+如果你到了 `s15` 以后开始觉得名词多，可以只记这条线：
+
+```text
+message / prompt
+   管输入
+
+tool / permission / hook
+   管动作
+
+task / runtime task / protocol
+   管工作推进
+
+subagent / teammate / worktree
+   管执行者和执行车道
+
+mcp / memory / claude.md
+   管平台外延和长期上下文
+```
+
+## 初学者最容易心智打结的地方
+
+### 1. 把“任务”这个词用在所有层
+
+这是最常见的混乱来源。
+
+所以建议你在写正文时，尽量直接写全：
+
+- 工作图任务
+- 运行时任务
+- 后台任务
+- 协议请求
+
+不要都叫“任务”。
+
+### 2. 把队友和子 agent 混成一类
+
+如果生命周期不同，就不是同一类实体。
+
+### 3. 把 worktree 当成 task 的别名
+
+一个是“做什么”，一个是“在哪做”。
+
+### 4. 把 memory 当成通用笔记本
+
+它不是。它只保存很特定的一类长期信息。
+
+## 这份图应该怎么用
+
+最好的用法不是读一遍背下来，而是：
+
+- 每次你发现两个词开始混
+- 先来这张图里确认它们是不是一个层级
+- 再回去读对应章节
+
+如果你确认“不在一个层级”，下一步最好立刻去找它们对应的数据结构，而不是继续凭感觉读正文。
+
+## 教学边界
+
+这张图只解决“实体边界”这一个问题。
+
+它不负责展开每个实体的全部字段，也不负责把所有产品化分支一起讲完。
+
+你可以把它当成一张分层地图：
+
+- 先确认词属于哪一层
+- 再去对应章节看机制
+- 最后去 [`data-structures.md`](./data-structures.md) 看状态形状
+
+## 一句话记住
+
+**一个结构完整的系统最怕的不是功能多，而是实体边界不清；边界一清，很多复杂度会自动塌下来。**
diff --git a/docs/zh/glossary.md b/docs/zh/glossary.md
new file mode 100644
index 000000000..4daa80ee1
--- /dev/null
+++ b/docs/zh/glossary.md
@@ -0,0 +1,471 @@
+# Glossary (术语表)
+
+> 这份术语表只收录本仓库主线里最重要、最容易让初学者卡住的词。  
+> 如果某个词你看着眼熟但说不清它到底是什么，先回这里。
+
+## 推荐联读
+
+如果你不是单纯查词，而是已经开始分不清“这些词分别活在哪一层”，建议按这个顺序一起看：
+
+- 先看 [`entity-map.md`](./entity-map.md)：搞清每个实体属于哪一层。
+- 再看 [`data-structures.md`](./data-structures.md)：搞清这些词真正落成什么状态结构。
+- 如果你卡在“任务”这个词上，再看 [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)。
+- 如果你卡在 MCP 不只等于 tools，再看 [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)。
+
+## Agent
+
+在这套仓库里，`agent` 指的是：  
+**一个能根据输入做判断，并且会调用工具去完成任务的模型。**
+
+你可以简单理解成：
+
+- 模型负责思考
+- harness 负责给模型工作环境
+
+## Harness
+
+`harness` 可以理解成“给 agent 准备好的工作台”。
+
+它包括：
+
+- 工具
+- 文件系统
+- 权限
+- 提示词
+- 记忆
+- 任务系统
+
+模型本身不是 harness。  
+harness 也不是模型。
+
+## Agent Loop
+
+`agent loop` 是系统反复执行的一条主循环：
+
+1. 把当前上下文发给模型
+2. 看模型是要直接回答，还是要调工具
+3. 如果调工具，就执行工具
+4. 把工具结果写回上下文
+5. 再继续下一轮
+
+没有这条循环，就没有 agent 系统。
+
+## Message / Messages
+
+`message` 是一条消息。  
+`messages` 是消息列表。
+
+它通常包含：
+
+- 用户消息
+- assistant 消息
+- tool_result 消息
+
+这份列表就是 agent 最主要的工作记忆。
+
+## Tool
+
+`tool` 是模型可以调用的一种动作。
+
+例如：
+
+- 读文件
+- 写文件
+- 改文件
+- 跑 shell 命令
+- 搜索文本
+
+模型并不直接执行系统命令。  
+模型只是说“我要调哪个工具、传什么参数”，真正执行的是你的代码。
+
+## Tool Schema
+
+`tool schema` 是工具的输入说明。
+
+它告诉模型：
+
+- 这个工具叫什么
+- 这个工具做什么
+- 需要哪些参数
+- 参数是什么类型
+
+可以把它想成“工具使用说明书”。
+
+## Dispatch Map
+
+`dispatch map` 是一张映射表：
+
+```python
+{
+    "read_file": read_file_handler,
+    "write_file": write_file_handler,
+    "bash": bash_handler,
+}
+```
+
+意思是：
+
+- 模型说要调用 `read_file`
+- 代码就去表里找到 `read_file_handler`
+- 然后执行它
+
+## Stop Reason
+
+`stop_reason` 是模型这一轮为什么停下来的原因。
+
+常见的有：
+
+- `end_turn`：模型说完了
+- `tool_use`：模型要调用工具
+- `max_tokens`：模型输出被截断了
+
+它决定主循环下一步怎么走。
+
+## Context
+
+`context` 是模型当前能看到的信息总和。
+
+包括：
+
+- `messages`
+- system prompt
+- 动态补充信息
+- tool_result
+
+上下文不是永久记忆。  
+上下文是“这一轮工作时当前摆在桌上的东西”。
+
+## Compact / Compaction
+
+`compact` 指压缩上下文。
+
+因为对话越长，模型能看到的历史就越多，成本和混乱也会一起增加。
+
+压缩的目标不是“删除有用信息”，而是：
+
+- 保留真正关键的内容
+- 去掉重复和噪声
+- 给后面的轮次腾空间
+
+## Subagent
+
+`subagent` 是从当前 agent 派生出来的一个子任务执行者。
+
+它最重要的价值是：
+
+**把一个大任务放到独立上下文里处理，避免污染父上下文。**
+
+## Fork
+
+`fork` 在本仓库语境里，指一种子 agent 启动方式：
+
+- 不是从空白上下文开始
+- 而是先继承父 agent 的已有上下文
+
+这适合“子任务必须理解当前讨论背景”的场景。
+
+## Permission
+
+`permission` 就是“这个工具调用能不能执行”。
+
+一个好的权限系统通常要回答三件事：
+
+- 应不应该直接拒绝
+- 能不能自动允许
+- 剩下的是不是要问用户
+
+## Permission Mode
+
+`permission mode` 是权限系统的工作模式。
+
+例如：
+
+- `default`：默认询问
+- `plan`：只允许读，不允许写
+- `auto`：简单安全的操作自动过，危险操作再问
+
+## Hook
+
+`hook` 是一个插入点。
+
+意思是：  
+在不改主循环代码的前提下，在某个时机额外执行一段逻辑。
+
+例如：
+
+- 工具调用前先检查一下
+- 工具调用后追加一条审计信息
+
+## Memory
+
+`memory` 是跨会话保存的信息。
+
+但不是所有东西都该存 memory。
+
+适合存 memory 的，通常是：
+
+- 用户长期偏好
+- 多次出现的重要反馈
+- 未来别的会话仍然有价值的信息
+
+## System Prompt
+
+`system prompt` 是系统级说明。
+
+它告诉模型：
+
+- 你是谁
+- 你能做什么
+- 你有哪些规则
+- 你应该如何协作
+
+它比普通用户消息更稳定。
+
+## System Reminder
+
+`system reminder` 是每一轮临时追加的动态提醒。
+
+例如：
+
+- 当前目录
+- 当前日期
+- 某个本轮才需要的额外上下文
+
+它和稳定的 system prompt 不是一回事。
+
+## Task
+
+`task` 是持久化任务系统里的一个任务节点。
+
+一个 task 通常不只是一句待办事项，还会带：
+
+- 状态
+- 描述
+- 依赖关系
+- owner
+
+## Dependency Graph
+
+`dependency graph` 指任务之间的依赖关系图。
+
+最简单的理解：
+
+- A 做完，B 才能开始
+- C 和 D 可以并行
+- E 要等 C 和 D 都完成
+
+这类结构能帮助 agent 判断：
+
+- 现在能做什么
+- 什么被卡住了
+- 什么能同时做
+
+## Worktree
+
+`worktree` 是 Git 提供的一个机制：
+
+同一个仓库，可以在多个不同目录里同时展开多个工作副本。
+
+它的价值是：
+
+- 并行做多个任务
+- 不互相污染文件改动
+- 便于多 agent 并行工作
+
+## MCP
+
+`MCP` 是 Model Context Protocol。
+
+你可以先把它理解成一套统一接口，让 agent 能接入外部工具。
+
+它解决的核心问题是：
+
+- 工具不必都写死在主程序里
+- 可以通过统一协议接入外部能力
+
+如果你已经知道“能接外部工具”，但开始分不清 server、connection、tool、resource、prompt 这些层，继续看：
+
+- [`data-structures.md`](./data-structures.md)
+- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)
+
+## Runtime Task
+
+`runtime task` 指的是：
+
+> 系统当前正在运行、等待完成、或者刚刚结束的一条执行单元。
+
+例如：
+
+- 一个后台 `pytest`
+- 一个正在工作的 teammate
+- 一个正在运行的 monitor
+
+它和 `task` 不一样。
+
+- `task` 更像工作目标
+- `runtime task` 更像执行槽位
+
+如果你总把这两个词混掉，不要只在正文里来回翻，直接去看：
+
+- [`entity-map.md`](./entity-map.md)
+- [`data-structures.md`](./data-structures.md)
+- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)
+
+## Teammate
+
+`teammate` 是长期存在的队友 agent。
+
+它和 `subagent` 的区别是：
+
+- `subagent`：一次性委派，干完就结束
+- `teammate`：长期存在，可以反复接任务
+
+如果你发现自己开始把这两个词混用，说明你需要回看：
+
+- `s04`
+- `s15`
+- `entity-map.md`
+
+## Protocol
+
+`protocol` 就是一套提前约好的协作规则。
+
+它回答的是：
+
+- 消息应该长什么样
+- 收到以后要怎么处理
+- 批准、拒绝、超时这些状态怎么记录
+
+在团队章节里，它最常见的形状是：
+
+```text
+request
+  ->
+response
+  ->
+status update
+```
+
+## Envelope
+
+`envelope` 本意是“信封”。
+
+在程序里，它表示：
+
+> 把正文和一些元信息一起包起来的一条结构化记录。
+
+例如一条协议消息里，正文之外还会附带：
+
+- `from`
+- `to`
+- `request_id`
+- `timestamp`
+
+这整包东西，就可以叫一个 `envelope`。
+
+## State Machine
+
+`state machine` 不是很玄的高级理论。
+
+你可以先把它理解成：
+
+> 一张“状态可以怎么变化”的规则表。
+
+例如：
+
+```text
+pending -> approved
+pending -> rejected
+pending -> expired
+```
+
+这就是一个最小状态机。
+
+## Router
+
+`router` 可以简单理解成“分发器”。
+
+它的任务是：
+
+- 看请求属于哪一类
+- 把它送去正确的处理路径
+
+例如工具层里：
+
+- 本地工具走本地 handler
+- `mcp__...` 工具走 MCP client
+
+## Control Plane
+
+`control plane` 可以理解成“负责协调和控制的一层”。
+
+它通常不直接产出最终业务结果，  
+而是负责决定：
+
+- 谁来执行
+- 在什么环境里执行
+- 有没有权限
+- 执行后要不要通知别的模块
+
+这个词第一次看到容易怕。  
+但在本仓库里，你只需要把它先记成：
+
+> 不直接干活，负责协调怎么干活的一层。
+
+## Capability
+
+`capability` 就是“能力项”。
+
+例如在 MCP 里，能力不只可能是工具，还可能包括：
+
+- tools
+- resources
+- prompts
+- elicitation
+
+所以 `capability` 比 `tool` 更宽。
+
+## Resource
+
+`resource` 可以理解成：
+
+> 一个可读取、可引用、但不一定是“执行动作”的外部内容入口。
+
+例如：
+
+- 一份文档
+- 一个只读配置
+- 一块可被模型读取的数据内容
+
+它和 `tool` 的区别是：
+
+- `tool` 更像动作
+- `resource` 更像可读取内容
+
+## Elicitation
+
+`elicitation` 可以先理解成：
+
+> 外部系统反过来向用户要补充输入。
+
+也就是说，不再只是 agent 主动调用外部能力。  
+外部能力也可能说：
+
+“我还缺一点信息，请你补一下。”
+
+## 最容易混的几对词
+
+如果你是初学者，下面这几对词最值得一起记。
+
+| 词对 | 最简单的区分方法 |
+|---|---|
+| `message` vs `system prompt` | 一个更像对话内容，一个更像系统说明 |
+| `todo` vs `task` | 一个更像临时步骤，一个更像持久化工作节点 |
+| `task` vs `runtime task` | 一个管目标，一个管执行 |
+| `subagent` vs `teammate` | 一个一次性，一个长期存在 |
+| `tool` vs `resource` | 一个更像动作，一个更像内容 |
+| `permission` vs `hook` | 一个决定能不能做，一个决定要不要额外插入行为 |
+
+---
+
+如果读文档时又遇到新词卡住，优先回这里，不要硬顶着往后读。
diff --git a/docs/zh/s00-architecture-overview.md b/docs/zh/s00-architecture-overview.md
new file mode 100644
index 000000000..09fc90ae3
--- /dev/null
+++ b/docs/zh/s00-architecture-overview.md
@@ -0,0 +1,461 @@
+# s00: Architecture Overview (架构总览)
+
+> 这一章是全仓库的地图。  
+> 如果你只想先知道“整个系统到底由哪些模块组成、为什么是这个学习顺序”，先读这一章。
+
+## 先说结论
+
+这套仓库的主线是合理的。
+
+它最重要的优点，不是“章节数量多”，而是它把学习过程拆成了四个阶段：
+
+1. 先做出一个真的能工作的 agent。
+2. 再补安全、扩展、记忆和恢复。
+3. 再把临时清单升级成持久化任务系统。
+4. 最后再进入多 agent、隔离执行和外部工具平台。
+
+这个顺序符合初学者的心智。
+
+因为一个新手最需要的，不是先知道所有高级细节，而是先建立一条稳定的主线：
+
+`用户输入 -> 模型思考 -> 调工具 -> 拿结果 -> 继续思考 -> 完成`
+
+只要这条主线还没真正理解，后面的权限、hook、memory、MCP 都会变成一堆零散名词。
+
+## 这套仓库到底要还原什么
+
+本仓库的目标不是逐行复制任何一个生产仓库。
+
+本仓库真正要还原的是：
+
+- 主要模块有哪些
+- 模块之间怎么协作
+- 每个模块的核心职责是什么
+- 关键状态存在哪里
+- 一条请求在系统里是怎么流动的
+
+也就是说，我们追求的是：
+
+**设计主脉络高保真，而不是所有外围实现细节 1:1。**
+
+这很重要。
+
+如果你是为了自己从 0 到 1 做一个类似系统，那么你真正需要掌握的是：
+
+- 核心循环
+- 工具机制
+- 规划与任务
+- 上下文管理
+- 权限与扩展点
+- 持久化
+- 多 agent 协作
+- 工作隔离
+- 外部工具接入
+
+而不是打包、跨平台兼容、历史兼容分支或产品化胶水代码。
+
+## 三条阅读原则
+
+### 1. 先学最小版本，再学结构更完整的版本
+
+比如子 agent。
+
+最小版本只需要：
+
+- 父 agent 发一个子任务
+- 子 agent 用自己的 `messages`
+- 子 agent 返回一个摘要
+
+这已经能解决 80% 的核心问题：上下文隔离。
+
+等这个最小版本你真的能写出来，再去补更完整的能力，比如：
+
+- 继承父上下文的 fork 模式
+- 独立权限
+- 背景运行
+- worktree 隔离
+
+### 2. 每个新名词都必须先解释
+
+本仓库会经常用到一些词：
+
+- `state machine`
+- `dispatch map`
+- `dependency graph`
+- `frontmatter`
+- `worktree`
+- `MCP`
+
+如果你对这些词不熟，不要硬扛。  
+应该立刻去看术语表：[`glossary.md`](./glossary.md)
+
+如果你想先知道“这套仓库到底教什么、不教什么”，建议配合看：
+
+- [`teaching-scope.md`](./teaching-scope.md)
+
+如果你想先把最关键的数据结构建立成整体地图，可以配合看：
+
+- [`data-structures.md`](./data-structures.md)
+
+如果你已经知道章节顺序没问题，但一打开本地 `agents/*.py` 就会重新乱掉，建议再配合看：
+
+- [`s00f-code-reading-order.md`](./s00f-code-reading-order.md)
+
+### 3. 不把复杂外围细节伪装成“核心机制”
+
+好的教学，不是把一切都讲进去。
+
+好的教学，是把真正关键的东西讲完整，把不关键但很复杂的东西先拿掉。
+
+所以本仓库会刻意省略一些不属于主干的内容，比如：
+
+- 打包与发布
+- 企业策略接线
+- 遥测
+- 多客户端表层集成
+- 历史兼容层
+
+## 建议配套阅读的文档
+
+除了主线章节，我建议把下面两份文档当作全程辅助地图：
+
+| 文档 | 用途 |
+|---|---|
+| [`teaching-scope.md`](./teaching-scope.md) | 帮你分清哪些内容属于教学主线，哪些只是维护者侧补充 |
+| [`data-structures.md`](./data-structures.md) | 帮你集中理解整个系统的关键状态和数据结构 |
+| [`s00f-code-reading-order.md`](./s00f-code-reading-order.md) | 帮你把“章节顺序”和“本地代码阅读顺序”对齐，避免重新乱翻源码 |
+
+如果你已经读到中后半程，想把“章节之间缺的那一层”补上，再加看下面这些桥接文档：
+
+| 文档 | 它补的是什么 |
+|---|---|
+| [`s00d-chapter-order-rationale.md`](./s00d-chapter-order-rationale.md) | 为什么这套课要按现在这个顺序讲，哪些重排会把读者心智讲乱 |
+| [`s00e-reference-module-map.md`](./s00e-reference-module-map.md) | 参考仓库里真正重要的模块簇，和当前课程章节是怎样一一对应的 |
+| [`s00a-query-control-plane.md`](./s00a-query-control-plane.md) | 为什么一个更完整的系统不能只靠 `messages[] + while True` |
+| [`s00b-one-request-lifecycle.md`](./s00b-one-request-lifecycle.md) | 一条请求如何从用户输入一路流过 query、tools、permissions、tasks、teams、MCP 再回到主循环 |
+| [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md) | 为什么工具层不只是 `tool_name -> handler` |
+| [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md) | 为什么 system prompt 不是模型完整输入的全部 |
+| [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) | 为什么任务板里的 task 和正在运行的 task 不是一回事 |
+| [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md) | 为什么 MCP 正文先讲 tools-first，但平台层还要再补一张地图 |
+| [`entity-map.md`](./entity-map.md) | 帮你把 message、task、runtime task、subagent、teammate、worktree、MCP server 这些实体彻底分开 |
+
+## 四阶段学习路径
+
+### 阶段 1：核心单 agent (`s01-s06`)
+
+目标：先做出一个能干活的 agent。
+
+| 章节 | 学什么 | 解决什么问题 |
+|---|---|---|
+| `s01` | Agent Loop | 没有循环，就没有 agent |
+| `s02` | Tool Use | 让模型从“会说”变成“会做” |
+| `s03` | Todo / Planning | 防止大任务乱撞 |
+| `s04` | Subagent | 防止上下文被大任务污染 |
+| `s05` | Skills | 按需拿知识，不把所有知识塞进提示词 |
+| `s06` | Context Compact | 防止上下文无限膨胀 |
+
+这一阶段结束后，你已经有了一个真正可运行的 coding agent 雏形。
+
+### 阶段 2：生产加固 (`s07-s11`)
+
+目标：让 agent 不只是能跑，而是更安全、更稳、更可扩展。
+
+| 章节 | 学什么 | 解决什么问题 |
+|---|---|---|
+| `s07` | Permission System | 危险操作先过权限关 |
+| `s08` | Hook System | 不改主循环也能扩展行为 |
+| `s09` | Memory System | 让真正有价值的信息跨会话存在 |
+| `s10` | System Prompt | 把系统说明、工具、约束组装成稳定输入 |
+| `s11` | Error Recovery | 出错后能恢复，而不是直接崩溃 |
+
+### 阶段 3：任务管理 (`s12-s14`)
+
+目标：把“聊天中的清单”升级成“磁盘上的任务图”。
+
+| 章节 | 学什么 | 解决什么问题 |
+|---|---|---|
+| `s12` | Task System | 大任务要有持久结构 |
+| `s13` | Background Tasks | 慢操作不应该卡住前台思考 |
+| `s14` | Cron Scheduler | 让系统能在未来自动做事 |
+
+### 阶段 4：多 agent 与外部系统 (`s15-s19`)
+
+目标：从单 agent 升级成真正的平台。
+
+| 章节 | 学什么 | 解决什么问题 |
+|---|---|---|
+| `s15` | Agent Teams | 让多个 agent 协作 |
+| `s16` | Team Protocols | 让协作有统一规则 |
+| `s17` | Autonomous Agents | 让 agent 自己找活、认领任务 |
+| `s18` | Worktree Isolation | 并行工作时互不踩目录 |
+| `s19` | MCP & Plugin | 接入外部工具与外部能力 |
+
+## 章节速查表：每章到底新增了哪一层状态
+
+很多读者读到中途会开始觉得：
+
+- 这一章到底是在加工具，还是在加状态
+- 这个机制是“输入层”的，还是“执行层”的
+- 学完这一章以后，我手里到底多了一个什么东西
+
+所以这里给一张全局速查表。  
+读每章以前，先看这一行；读完以后，再回来检查自己是不是真的吃透了这一行。
+
+| 章节 | 新增的核心结构 | 它接在系统哪一层 | 学完你应该会什么 |
+|---|---|---|---|
+| `s01` | `messages` / `LoopState` | 主循环 | 手写一个最小 agent 闭环 |
+| `s02` | `ToolSpec` / `ToolDispatchMap` | 工具层 | 把模型意图路由成真实动作 |
+| `s03` | `TodoItem` / `PlanState` | 过程规划层 | 让 agent 按步骤推进，而不是乱撞 |
+| `s04` | `SubagentContext` | 执行隔离层 | 把探索性工作丢进干净子上下文 |
+| `s05` | `SkillRegistry` / `SkillContent` | 知识注入层 | 只在需要时加载额外知识 |
+| `s06` | `CompactSummary` / `PersistedOutput` | 上下文管理层 | 控制上下文大小又不丢主线 |
+| `s07` | `PermissionRule` / `PermissionDecision` | 安全控制层 | 让危险动作先经过决策管道 |
+| `s08` | `HookEvent` / `HookResult` | 扩展控制层 | 不改主循环也能插入扩展逻辑 |
+| `s09` | `MemoryEntry` / `MemoryStore` | 持久上下文层 | 只把真正跨会话有价值的信息留下 |
+| `s10` | `PromptParts` / `SystemPromptBlock` | 输入组装层 | 把模型输入拆成可管理的管道 |
+| `s11` | `RecoveryState` / `TransitionReason` | 恢复控制层 | 出错后知道为什么继续、怎么继续 |
+| `s12` | `TaskRecord` / `TaskStatus` | 工作图层 | 把临时清单升级成持久化任务图 |
+| `s13` | `RuntimeTaskState` / `Notification` | 运行时执行层 | 让慢任务后台运行、稍后回送结果 |
+| `s14` | `ScheduleRecord` / `CronTrigger` | 定时触发层 | 让时间本身成为工作触发器 |
+| `s15` | `TeamMember` / `MessageEnvelope` | 多 agent 基础层 | 让队友长期存在、反复接活 |
+| `s16` | `ProtocolEnvelope` / `RequestRecord` | 协作协议层 | 让团队从自由聊天升级成结构化协作 |
+| `s17` | `ClaimPolicy` / `AutonomyState` | 自治调度层 | 让 agent 空闲时自己找活、恢复工作 |
+| `s18` | `WorktreeRecord` / `TaskBinding` | 隔离执行层 | 给并行任务分配独立工作目录 |
+| `s19` | `MCPServerConfig` / `CapabilityRoute` | 外部能力层 | 把外部能力并入系统主控制面 |
+
+## 整个系统的大图
+
+先看最重要的一张图：
+
+```text
+User
+  |
+  v
+messages[]
+  |
+  v
++-------------------------+
+|  Agent Loop (s01)       |
+|                         |
+|  1. 组装输入            |
+|  2. 调模型              |
+|  3. 看 stop_reason      |
+|  4. 如果要调工具就执行   |
+|  5. 把结果写回 messages  |
+|  6. 继续下一轮           |
++-------------------------+
+  |
+  +------------------------------+
+  |                              |
+  v                              v
+Tool Pipeline                Context / State
+(s02, s07, s08)              (s03, s06, s09, s10, s11)
+  |                              |
+  v                              v
+Tasks / Teams / Worktree / MCP (s12-s19)
+```
+
+你可以把它理解成三层：
+
+### 第一层：主循环
+
+这是系统心脏。
+
+它只做一件事：  
+**不停地推动“思考 -> 行动 -> 观察 -> 再思考”的循环。**
+
+### 第二层：横切机制
+
+这些机制不是替代主循环，而是“包在主循环周围”：
+
+- 权限
+- hooks
+- memory
+- prompt 组装
+- 错误恢复
+- 上下文压缩
+
+它们的作用，是让主循环更安全、更稳定、更聪明。
+
+### 第三层：更大的工作平台
+
+这些机制把单 agent 升级成更完整的系统：
+
+- 任务图
+- 后台任务
+- 多 agent 团队
+- worktree 隔离
+- MCP 外部工具
+
+## 你真正需要掌握的关键状态
+
+理解 agent，最重要的不是背很多功能名，而是知道**状态放在哪里**。
+
+下面是这个仓库里最关键的几类状态：
+
+### 1. 对话状态：`messages`
+
+这是 agent 当前上下文的主体。
+
+它保存：
+
+- 用户说了什么
+- 模型回复了什么
+- 调用了哪些工具
+- 工具返回了什么
+
+你可以把它想成 agent 的“工作记忆”。
+
+### 2. 工具注册表：`tools` / `handlers`
+
+这是一张“工具名 -> Python 函数”的映射表。
+
+这类结构常被叫做 `dispatch map`。
+
+意思很简单：
+
+- 模型说“我要调用 `read_file`”
+- 代码就去表里找 `read_file` 对应的函数
+- 找到以后执行
+
+### 3. 计划与任务状态：`todo` / `tasks`
+
+这部分保存：
+
+- 当前有哪些事要做
+- 哪些已经完成
+- 哪些被别的任务阻塞
+- 哪些可以并行
+
+### 4. 权限与策略状态
+
+这部分保存：
+
+- 当前权限模式是什么
+- 允许规则有哪些
+- 拒绝规则有哪些
+- 最近是否连续被拒绝
+
+### 5. 持久化状态
+
+这部分保存那些“不该跟着一次对话一起消失”的东西：
+
+- memory 文件
+- task 文件
+- transcript
+- background task 输出
+- worktree 绑定信息
+
+## 如果你想做出结构完整的版本，至少要有哪些数据结构
+
+如果你的目标是自己写一个结构完整、接近真实主脉络的类似系统，最低限度要把下面这些数据结构设计清楚：
+
+```python
+class AppState:
+    messages: list
+    tools: dict
+    tool_schemas: list
+
+    todo: object | None
+    tasks: object | None
+
+    permissions: object | None
+    hooks: object | None
+    memories: object | None
+    prompt_builder: object | None
+
+    compact_state: dict
+    recovery_state: dict
+
+    background: object | None
+    cron: object | None
+
+    teammates: object | None
+    worktree_session: dict | None
+    mcp_clients: dict
+```
+
+这不是要求你一开始就把这些全写完。
+
+这张表的作用只是告诉你：
+
+**一个像样的 agent 系统，不只是 `messages + tools`。**
+
+它最终会长成一个带很多子模块的状态系统。
+
+## 一条请求是怎么流动的
+
+```text
+1. 用户发来任务
+2. 系统组装 prompt 和上下文
+3. 模型返回普通文本，或者返回 tool_use
+4. 如果返回 tool_use：
+   - 先过 permission
+   - 再过 hook
+   - 然后执行工具
+   - 把 tool_result 写回 messages
+5. 主循环继续
+6. 如果任务太大：
+   - 可能写入 todo / tasks
+   - 可能派生 subagent
+   - 可能触发 compact
+   - 可能走 background / team / worktree / MCP
+7. 直到模型结束这一轮
+```
+
+这条流是全仓库最重要的主脉络。
+
+你在后面所有章节里看到的机制，本质上都只是插在这条流的不同位置。
+
+## 读者最容易混淆的几组概念
+
+### `Todo` 和 `Task` 不是一回事
+
+- `Todo`：轻量、临时、偏会话内
+- `Task`：持久化、带状态、带依赖关系
+
+### `Memory` 和 `Context` 不是一回事
+
+- `Context`：这一轮工作临时需要的信息
+- `Memory`：未来别的会话也可能仍然有价值的信息
+
+### `Subagent` 和 `Teammate` 不是一回事
+
+- `Subagent`：通常是当前 agent 派生出来的一次性帮手
+- `Teammate`：更偏向长期存在于团队中的协作角色
+
+### `Prompt` 和 `System Reminder` 不是一回事
+
+- `System Prompt`：较稳定的系统级输入
+- `System Reminder`：每轮动态变化的补充上下文
+
+## 这套仓库刻意省略了什么
+
+为了让初学者能顺着学下去，本仓库不会把下面这些内容塞进主线：
+
+- 产品级启动流程里的全部外围初始化
+- 真实商业产品中的账号、策略、遥测、灰度等逻辑
+- 只服务于兼容性和历史负担的复杂分支
+- 某些非常复杂但教学收益很低的边角机制
+
+这不是因为这些东西“不存在”。
+
+而是因为对一个从 0 到 1 造类似系统的读者来说，主干先于枝叶。
+
+## 这一章之后怎么读
+
+推荐顺序：
+
+1. 先读 `s01` 和 `s02`
+2. 然后读 `s03` 到 `s06`
+3. 进入 `s07` 到 `s10`
+4. 接着补 `s11`
+5. 最后再读 `s12` 到 `s19`
+
+如果你在某一章觉得名词开始打结，回来看这一章和术语表就够了。
+
+---
+
+**一句话记住全仓库：**
+
+先做出能工作的最小循环，再一层一层给它补上规划、隔离、安全、记忆、任务、协作和外部能力。
diff --git a/docs/zh/s00a-query-control-plane.md b/docs/zh/s00a-query-control-plane.md
new file mode 100644
index 000000000..8f61f2a36
--- /dev/null
+++ b/docs/zh/s00a-query-control-plane.md
@@ -0,0 +1,318 @@
+# s00a: Query Control Plane (查询控制平面)
+
+> 这不是新的主线章节，而是一份桥接文档。  
+> 它用来回答一个问题：
+>
+> **为什么一个结构更完整的 agent，不会只靠 `messages[]` 和一个 `while True` 就够了？**
+
+## 这一篇为什么要存在
+
+主线里的 `s01` 会先教你做出一个最小可运行循环：
+
+```text
+用户输入
+  ->
+模型回复
+  ->
+如果要调工具就执行
+  ->
+把结果喂回去
+  ->
+继续下一轮
+```
+
+这条主线是对的，而且必须先学这个。
+
+但当系统开始长功能以后，真正支撑一个完整 harness 的，不再只是“循环”本身，而是：
+
+**一层专门负责管理查询过程的控制平面。**
+
+这一层在真实系统里通常会统一处理：
+
+- 当前对话消息
+- 当前轮次
+- 为什么继续下一轮
+- 是否正在恢复错误
+- 是否已经压缩过上下文
+- 是否需要切换输出预算
+- hook 是否暂时影响了结束条件
+
+如果不把这层讲出来，读者虽然能做出一个能跑的 demo，但很难自己把系统推到接近 95%-99% 的完成度。
+
+## 先解释几个名词
+
+### 什么是 query
+
+这里的 `query` 不是“数据库查询”。
+
+这里说的 query，更接近：
+
+> 系统为了完成用户当前这一次请求，而运行的一整段主循环过程。
+
+也就是说：
+
+- 用户说一句话
+- 系统可能要经过很多轮模型调用和工具调用
+- 最后才结束这一次请求
+
+这整段过程，就可以看成一条 query。
+
+### 什么是控制平面
+
+`控制平面` 这个词第一次看会有点抽象。
+
+它的意思其实很简单：
+
+> 不是直接做业务动作，而是负责协调、调度、决定流程怎么往下走的一层。
+
+在这里：
+
+- 模型回复内容，算“业务内容”
+- 工具执行结果，算“业务动作”
+- 决定“要不要继续下一轮、为什么继续、现在属于哪种继续”，这层就是控制平面
+
+### 什么是 transition
+
+`transition` 可以翻成“转移原因”。
+
+它回答的是：
+
+> 上一轮为什么没有结束，而是继续下一轮了？
+
+例如：
+
+- 因为工具刚执行完
+- 因为输出被截断，要续写
+- 因为刚做完压缩，要重试
+- 因为 hook 要求继续
+- 因为预算还允许继续
+
+## 最小心智模型
+
+先把 query 控制平面想成 3 层：
+
+```text
+1. 输入层
+   - messages
+   - system prompt
+   - user/system context
+
+2. 控制层
+   - 当前状态 state
+   - 当前轮 turn
+   - 当前继续原因 transition
+   - 恢复/压缩/预算等标记
+
+3. 执行层
+   - 调模型
+   - 执行工具
+   - 写回消息
+```
+
+它的工作不是“替代主循环”，而是：
+
+**让主循环从一个小 demo，升级成一个能管理很多分支和状态的系统。**
+
+## 为什么只靠 `messages[]` 不够
+
+很多初学者第一次实现 agent 时，会把所有状态都堆进 `messages[]`。
+
+这在最小 demo 里没问题。
+
+但一旦系统长出下面这些能力，就不够了：
+
+- 你要知道自己是不是已经做过一次 reactive compact
+- 你要知道输出被截断已经续写了几次
+- 你要知道这次继续是因为工具，还是因为错误恢复
+- 你要知道当前轮是否启用了特殊输出预算
+
+这些信息不是“对话内容”，而是“流程控制状态”。
+
+所以它们不该都硬塞进 `messages[]` 里。
+
+## 关键数据结构
+
+### 1. QueryParams
+
+这是进入 query 引擎时的外部输入。
+
+最小形状可以这样理解：
+
+```python
+params = {
+    "messages": [...],
+    "system_prompt": "...",
+    "user_context": {...},
+    "system_context": {...},
+    "tool_use_context": {...},
+    "fallback_model": None,
+    "max_output_tokens_override": None,
+    "max_turns": None,
+}
+```
+
+它的作用是：
+
+- 带进来这次查询一开始已知的输入
+- 这些值大多不在每轮里随便乱改
+
+### 2. QueryState
+
+这才是跨迭代真正会变化的部分。
+
+最小教学版建议你把它显式做成一个结构：
+
+```python
+state = {
+    "messages": [...],
+    "tool_use_context": {...},
+    "continuation_count": 0,
+    "has_attempted_compact": False,
+    "max_output_tokens_override": None,
+    "stop_hook_active": False,
+    "turn_count": 1,
+    "transition": None,
+}
+```
+
+它的价值在于：
+
+- 把“会变的流程状态”集中放在一起
+- 让每个 continue site 修改的是同一份 state，而不是散落在很多局部变量里
+
+### 3. TransitionReason
+
+建议你单独定义一组继续原因：
+
+```python
+TRANSITIONS = (
+    "tool_result_continuation",
+    "max_tokens_recovery",
+    "compact_retry",
+    "transport_retry",
+    "stop_hook_continuation",
+    "budget_continuation",
+)
+```
+
+这不是为了炫技。
+
+它的作用很实在：
+
+- 日志更清楚
+- 调试更清楚
+- 测试更清楚
+- 教学更清楚
+
+## 最小实现
+
+### 第一步：把外部输入和内部状态分开
+
+```python
+def query(params):
+    state = {
+        "messages": params["messages"],
+        "tool_use_context": params["tool_use_context"],
+        "continuation_count": 0,
+        "has_attempted_compact": False,
+        "max_output_tokens_override": params.get("max_output_tokens_override"),
+        "turn_count": 1,
+        "transition": None,
+    }
+```
+
+### 第二步：每一轮先读 state，再决定如何执行
+
+```python
+while True:
+    messages = state["messages"]
+    transition = state["transition"]
+    turn_count = state["turn_count"]
+
+    response = call_model(...)
+    ...
+```
+
+### 第三步：所有“继续下一轮”的地方都写回 state
+
+```python
+if response.stop_reason == "tool_use":
+    state["messages"] = append_tool_results(...)
+    state["transition"] = "tool_result_continuation"
+    state["turn_count"] += 1
+    continue
+
+if response.stop_reason == "max_tokens":
+    state["messages"].append({"role": "user", "content": CONTINUE_MESSAGE})
+    state["continuation_count"] += 1
+    state["transition"] = "max_tokens_recovery"
+    continue
+```
+
+这一点非常关键。
+
+**不要只做 `continue`，要知道自己为什么 continue。**
+
+## 一张真正清楚的心智图
+
+```text
+params
+  |
+  v
+init state
+  |
+  v
+query loop
+  |
+  +-- normal assistant end --------------> terminal
+  |
+  +-- tool_use --------------------------> write tool_result -> transition=tool_result_continuation
+  |
+  +-- max_tokens ------------------------> inject continue -> transition=max_tokens_recovery
+  |
+  +-- prompt too long -------------------> compact -> transition=compact_retry
+  |
+  +-- transport error -------------------> backoff -> transition=transport_retry
+  |
+  +-- stop hook asks to continue --------> transition=stop_hook_continuation
+```
+
+## 它和 `s01`、`s11` 的关系
+
+- `s01` 负责建立“最小主循环”
+- `s11` 负责建立“错误恢复分支”
+- 这一篇负责把两者再往上抽象一层，解释为什么一个更完整的系统会出现一个 query control plane
+
+所以这篇不是替代主线，而是把主线补完整。
+
+## 初学者最容易犯的错
+
+### 1. 把所有控制状态都塞进消息里
+
+这样日志和调试都会很难看，也会让消息层和控制层混在一起。
+
+### 2. `continue` 了，但没有记录为什么继续
+
+短期看起来没问题，系统一复杂就会变成黑盒。
+
+### 3. 每个分支都直接改很多局部变量
+
+这样后面你很难看出“哪些状态是跨轮共享的”。
+
+### 4. 把 query loop 讲成“只是一个 while True”
+
+这对最小 demo 是真话，对一个正在长出控制面的 harness 就不是完整真话了。
+
+## 教学边界
+
+这篇最重要的，不是把所有控制状态一次列满，而是先让你守住三件事：
+
+- query loop 不只是 `while True`，而是一条带着共享状态往前推进的控制面
+- 每次 `continue` 都应该有明确原因，而不是黑盒跳转
+- 消息层、工具回写、压缩恢复、重试恢复，最终都要回到同一份 query 状态上
+
+更细的 `transition taxonomy`、预算跟踪、prefetch 等扩展，可以放到你把这条最小控制面真正手搓稳定以后再补。
+
+## 一句话记住
+
+**更完整的 query loop 不只是“循环”，而是“拿着一份跨轮状态不断推进的查询控制平面”。**
diff --git a/docs/zh/s00b-one-request-lifecycle.md b/docs/zh/s00b-one-request-lifecycle.md
new file mode 100644
index 000000000..e9fcb3edb
--- /dev/null
+++ b/docs/zh/s00b-one-request-lifecycle.md
@@ -0,0 +1,424 @@
+# s00b: One Request Lifecycle (一次请求的完整生命周期)
+
+> 这是一份桥接文档。  
+> 它不替代主线章节，而是把整套系统串成一条真正连续的执行链。
+>
+> 它要回答的问题是：
+>
+> **用户的一句话，进入系统以后，到底是怎样一路流动、分发、执行、再回到主循环里的？**
+
+## 为什么必须补这一篇
+
+很多读者在按顺序看教程时，会逐章理解：
+
+- `s01` 讲循环
+- `s02` 讲工具
+- `s03` 讲规划
+- `s07` 讲权限
+- `s09` 讲 memory
+- `s12-s19` 讲任务、多 agent、MCP
+
+每章单看都能懂。
+
+但一旦开始自己实现，就会很容易卡住：
+
+- 这些模块到底谁先谁后？
+- 一条请求进来时，先走 prompt，还是先走 memory？
+- 工具执行前，权限和 hook 在哪一层？
+- task、runtime task、teammate、worktree、MCP 到底是在一次请求里的哪个阶段介入？
+
+所以你需要一张“纵向流程图”。
+
+## 先给一条最重要的总图
+
+```text
+用户请求
+  |
+  v
+Query State 初始化
+  |
+  v
+组装 system prompt / messages / reminders
+  |
+  v
+调用模型
+  |
+  +-- 普通回答 -------------------------------> 结束本次请求
+  |
+  +-- tool_use
+        |
+        v
+    Tool Router
+        |
+        +-- 权限判断
+        +-- Hook 拦截/注入
+        +-- 本地工具 / MCP / agent / task / team
+        |
+        v
+    执行结果
+        |
+        +-- 可能写入 task / runtime task / memory / worktree 状态
+        |
+        v
+    tool_result 写回 messages
+        |
+        v
+    Query State 更新
+        |
+        v
+    下一轮继续
+```
+
+你可以把整条链先理解成三层：
+
+1. `Query Loop`
+2. `Tool Control Plane`
+3. `Platform State`
+
+## 第 1 段：用户请求进入查询控制平面
+
+当用户说：
+
+```text
+修复 tests/test_auth.py 的失败，并告诉我原因
+```
+
+系统最先做的，不是立刻跑工具，而是先为这次请求建立一份查询状态。
+
+最小可以理解成：
+
+```python
+query_state = {
+    "messages": [{"role": "user", "content": user_text}],
+    "turn_count": 1,
+    "transition": None,
+    "tool_use_context": {...},
+}
+```
+
+这里的重点是：
+
+**这次请求不是“单次 API 调用”，而是一段可能包含很多轮的查询过程。**
+
+如果你对这一层还不够熟，先回看：
+
+- [`s01-the-agent-loop.md`](./s01-the-agent-loop.md)
+- [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)
+
+## 第 2 段：组装本轮真正送给模型的输入
+
+主循环不会直接把原始 `messages` 裸发出去。
+
+在更完整的系统里，它通常会先组装：
+
+- system prompt blocks
+- 规范化后的 messages
+- memory section
+- 当前轮 reminder
+- 工具清单
+
+也就是说，真正发给模型的通常是：
+
+```text
+system prompt
++ normalized messages
++ tools
++ optional reminders / attachments
+```
+
+这里涉及的章节是：
+
+- `s09` memory
+- `s10` system prompt
+- `s10a` message & prompt pipeline
+
+这一段的核心心智是：
+
+**system prompt 不是全部输入，它只是输入管道中的一段。**
+
+## 第 3 段：模型产出两类东西
+
+模型这一轮的输出，最关键地分成两种：
+
+### 第一种：普通回复
+
+如果模型直接给出结论或说明，本次请求可能就结束了。
+
+### 第二种：动作意图
+
+也就是工具调用。
+
+例如：
+
+```text
+read_file("tests/test_auth.py")
+bash("pytest tests/test_auth.py -q")
+todo([...])
+load_skill("code-review")
+task_create(...)
+mcp__postgres__query(...)
+```
+
+这时候系统真正收到的，不只是“文本”，而是：
+
+> 模型想让真实世界发生某些动作。
+
+## 第 4 段：工具路由层接管动作意图
+
+一旦出现 `tool_use`，系统就进入工具控制平面。
+
+这一层至少要回答：
+
+1. 这是什么工具？
+2. 它应该路由到哪类能力来源？
+3. 执行前要不要先过权限？
+4. hook 有没有要拦截或补充？
+5. 它执行时能访问哪些共享状态？
+
+最小图可以这样看：
+
+```text
+tool_use
+  |
+  v
+Tool Router
+  |
+  +-- native tool handler
+  +-- MCP client
+  +-- agent/team/task handler
+```
+
+如果你对这一层不够清楚，回看：
+
+- [`s02-tool-use.md`](./s02-tool-use.md)
+- [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md)
+
+## 第 5 段：权限系统决定“能不能执行”
+
+不是所有动作意图都应该直接变成真实执行。
+
+例如：
+
+- 写文件
+- 跑 bash
+- 改工作目录
+- 调外部服务
+
+这时会先进入权限判断：
+
+```text
+deny rules
+  -> mode
+  -> allow rules
+  -> ask user
+```
+
+权限系统处理的是：
+
+> 这次动作是否允许发生。
+
+相关章节：
+
+- [`s07-permission-system.md`](./s07-permission-system.md)
+
+## 第 6 段：Hook 可以在边上做扩展
+
+通过权限检查以后，系统还可能在工具执行前后跑 hook。
+
+你可以把 hook 理解成：
+
+> 不改主循环主干，也能插入自定义行为的扩展点。
+
+例如：
+
+- 执行前记录日志
+- 执行后做额外检查
+- 根据结果注入额外提醒
+
+相关章节：
+
+- [`s08-hook-system.md`](./s08-hook-system.md)
+
+## 第 7 段：真正执行动作，并影响不同层的状态
+
+这是很多人最容易低估的一段。
+
+工具执行结果，不只是“一段文本输出”。
+
+它还可能修改系统别的状态层。
+
+### 例子 1：规划状态
+
+如果工具是 `todo`，它会更新的是当前会话计划。
+
+相关章节：
+
+- [`s03-todo-write.md`](./s03-todo-write.md)
+
+### 例子 2：持久任务图
+
+如果工具是 `task_create` / `task_update`，它会修改磁盘上的任务板。
+
+相关章节：
+
+- [`s12-task-system.md`](./s12-task-system.md)
+
+### 例子 3：运行时任务
+
+如果工具启动了后台 bash、后台 agent 或监控任务，它会创建 runtime task。
+
+相关章节：
+
+- [`s13-background-tasks.md`](./s13-background-tasks.md)
+- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)
+
+### 例子 4：多 agent / teammate
+
+如果工具是 `delegate`、`spawn_agent` 一类，它会在平台层生成新的执行单元。
+
+相关章节：
+
+- [`s15-agent-teams.md`](./s15-agent-teams.md)
+- [`s16-team-protocols.md`](./s16-team-protocols.md)
+- [`s17-autonomous-agents.md`](./s17-autonomous-agents.md)
+
+### 例子 5：worktree
+
+如果系统要为某个任务提供隔离工作目录，这会影响文件系统级执行环境。
+
+相关章节：
+
+- [`s18-worktree-task-isolation.md`](./s18-worktree-task-isolation.md)
+
+### 例子 6：MCP
+
+如果调用的是外部 MCP 能力，那么执行主体可能根本不在本地 handler，而在外部能力端。
+
+相关章节：
+
+- [`s19-mcp-plugin.md`](./s19-mcp-plugin.md)
+- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)
+
+## 第 8 段：执行结果被包装回消息流
+
+不管执行落在哪一层，最后都要回到同一个位置：
+
+```text
+tool_result -> messages
+```
+
+这是整个系统最核心的闭环。
+
+因为无论工具背后多复杂，模型下一轮真正能继续工作的依据，仍然是：
+
+> 系统把执行结果重新写回了它可见的消息流。
+
+这也是为什么 `s01` 永远是根。
+
+## 第 9 段：主循环根据结果决定下一轮是否继续
+
+当 `tool_result` 写回以后，查询状态也会一起更新：
+
+- `messages` 变了
+- `turn_count` 增加了
+- `transition` 被记录成某种续行原因
+
+这时系统就进入下一轮。
+
+如果中间发生下面这些情况，控制平面还会继续介入：
+
+- 上下文太长，需要压缩
+- 输出被截断，需要续写
+- 请求失败，需要恢复
+
+相关章节：
+
+- [`s06-context-compact.md`](./s06-context-compact.md)
+- [`s11-error-recovery.md`](./s11-error-recovery.md)
+
+## 第 10 段：哪些信息不会跟着一次请求一起结束
+
+这也是非常容易混的地方。
+
+一次请求结束后，并不是所有状态都随之消失。
+
+### 会跟着当前请求结束的
+
+- 当前轮 messages 中的临时推进过程
+- 会话内 todo 状态
+- 当前轮 reminder
+
+### 可能跨请求继续存在的
+
+- memory
+- 持久任务图
+- runtime task 输出
+- worktree
+- MCP 连接状态
+
+所以你要逐渐学会区分：
+
+```text
+query-scope state
+session-scope state
+project-scope state
+platform-scope state
+```
+
+## 用一个完整例子串一次
+
+还是用这个请求：
+
+```text
+修复 tests/test_auth.py 的失败，并告诉我原因
+```
+
+系统可能会这样流动：
+
+1. 用户请求进入 `QueryState`
+2. system prompt + memory + tools 被组装好
+3. 模型先调用 `todo`，写出三步计划
+4. 模型调用 `read_file("tests/test_auth.py")`
+5. 工具路由到本地文件读取 handler
+6. 读取结果包装成 `tool_result` 写回消息流
+7. 下一轮模型调用 `bash("pytest tests/test_auth.py -q")`
+8. 权限系统判断这条命令是否可执行
+9. 执行测试，输出太长则先落盘并留预览
+10. 失败日志回到消息流
+11. 模型再读实现文件并修改代码
+12. 修改后再跑测试
+13. 如果对话变长，`s06` 触发压缩
+14. 如果任务被拆给子 agent，`s15-s17` 介入
+15. 最后模型输出结论，本次请求结束
+
+你会发现：
+
+**整套系统再复杂，也始终没有脱离“输入 -> 动作意图 -> 执行 -> 结果写回 -> 下一轮”这条主骨架。**
+
+## 读这篇时最该记住的三件事
+
+### 1. 所有模块都不是平铺摆在那里的
+
+它们是在一次请求的不同阶段依次介入的。
+
+### 2. 真正的闭环只有一个
+
+那就是：
+
+```text
+tool_result 回到 messages
+```
+
+### 3. 很多高级机制，本质上只是围绕这条闭环加的保护层
+
+例如：
+
+- 权限是执行前保护层
+- hook 是扩展层
+- compact 是上下文预算保护层
+- recovery 是出错后的恢复层
+- task/team/worktree/MCP 是更大的平台能力层
+
+## 一句话记住
+
+**一次请求的完整生命周期，本质上就是：系统围绕同一条主循环，把不同模块按阶段接进来，最终持续把真实执行结果送回模型继续推理。**
diff --git a/docs/zh/s00c-query-transition-model.md b/docs/zh/s00c-query-transition-model.md
new file mode 100644
index 000000000..cbd036282
--- /dev/null
+++ b/docs/zh/s00c-query-transition-model.md
@@ -0,0 +1,331 @@
+# s00c: Query Transition Model (查询转移模型)
+
+> 这篇桥接文档专门解决一个问题：
+>
+> **为什么一个只会 `continue` 的 agent，不足以支撑完整系统，而必须显式知道“为什么继续到下一轮”？**
+
+## 这一篇为什么要存在
+
+主线里：
+
+- `s01` 先教你最小循环
+- `s06` 开始教上下文压缩
+- `s11` 开始教错误恢复
+
+这些都对。  
+但如果你只分别学这几章，脑子里很容易还是停留在一种过于粗糙的理解：
+
+> “反正 `continue` 了就继续呗。”
+
+这在最小 demo 里能跑。  
+但当系统开始长出恢复、压缩和外部控制以后，这样理解会很快失灵。
+
+因为系统继续下一轮的原因其实很多，而且这些原因不是一回事：
+
+- 工具刚执行完，要把结果喂回模型
+- 输出被截断了，要续写
+- 上下文刚压缩完，要重试
+- 运输层刚超时了，要退避后重试
+- stop hook 要求当前 turn 先不要结束
+- token budget 还允许继续推进
+
+如果你不把这些“继续原因”从一开始拆开，后面会出现三个大问题：
+
+- 日志看不清
+- 测试不好写
+- 教学心智会越来越模糊
+
+## 先解释几个名词
+
+### 什么叫 transition
+
+这里的 `transition`，你可以先把它理解成：
+
+> 上一轮为什么转移到了下一轮。
+
+它不是“消息内容”，而是“流程原因”。
+
+### 什么叫 continuation
+
+continuation 就是：
+
+> 这条 query 当前还没有结束，要继续推进。
+
+但 continuation 不止一种。
+
+### 什么叫 query boundary
+
+query boundary 就是一轮和下一轮之间的边界。
+
+每次跨过这个边界，系统最好都知道：
+
+- 这次为什么继续
+- 这次继续前有没有修改状态
+- 这次继续后应该怎么读主循环
+
+## 最小心智模型
+
+先不要把 query 想成一条线。
+
+更接近真实情况的理解是：
+
+```text
+一条 query
+  = 一组“继续原因”串起来的状态转移
+```
+
+例如：
+
+```text
+用户输入
+  ->
+模型产生 tool_use
+  ->
+工具执行完
+  ->
+tool_result_continuation
+  ->
+模型输出过长
+  ->
+max_tokens_recovery
+  ->
+压缩后继续
+  ->
+compact_retry
+  ->
+最终结束
+```
+
+这样看，你会更容易理解：
+
+**系统不是单纯在 while loop 里转圈，而是在一串显式的转移原因里推进。**
+
+## 关键数据结构
+
+### 1. QueryState 里的 `transition`
+
+最小版建议就把这类字段显式放进状态里：
+
+```python
+state = {
+    "messages": [...],
+    "turn_count": 3,
+    "has_attempted_compact": False,
+    "continuation_count": 1,
+    "transition": None,
+}
+```
+
+这里的 `transition` 不是可有可无。
+
+它的意义是：
+
+- 当前这轮为什么会出现
+- 下一轮日志应该怎么解释
+- 测试时应该断言哪条路径被走到
+
+### 2. TransitionReason
+
+教学版最小可以先这样分：
+
+```python
+TRANSITIONS = (
+    "tool_result_continuation",
+    "max_tokens_recovery",
+    "compact_retry",
+    "transport_retry",
+    "stop_hook_continuation",
+    "budget_continuation",
+)
+```
+
+这几种原因的本质不一样：
+
+- `tool_result_continuation`
+  是正常主线继续
+- `max_tokens_recovery`
+  是输出被截断后的恢复继续
+- `compact_retry`
+  是上下文处理后的恢复继续
+- `transport_retry`
+  是基础设施抖动后的恢复继续
+- `stop_hook_continuation`
+  是外部控制逻辑阻止本轮结束
+- `budget_continuation`
+  是系统主动利用预算继续推进
+
+### 3. Continuation Budget
+
+更完整的 query 状态不只会说“继续”，还会限制：
+
+- 最多续写几次
+- 最多压缩后重试几次
+- 某类恢复是不是已经尝试过
+
+例如：
+
+```python
+state = {
+    "max_output_tokens_recovery_count": 2,
+    "has_attempted_reactive_compact": True,
+}
+```
+
+这些字段的本质都是：
+
+> continuation 不是无限制的。
+
+## 最小实现
+
+### 第一步：把 continue site 显式化
+
+很多初学者写主循环时，所有继续逻辑都长这样：
+
+```python
+continue
+```
+
+教学版应该往前走一步：
+
+```python
+state["transition"] = "tool_result_continuation"
+continue
+```
+
+### 第二步：不同继续原因，配不同状态修改
+
+```python
+if response.stop_reason == "tool_use":
+    state["messages"] = append_tool_results(...)
+    state["turn_count"] += 1
+    state["transition"] = "tool_result_continuation"
+    continue
+
+if response.stop_reason == "max_tokens":
+    state["messages"].append({
+        "role": "user",
+        "content": CONTINUE_MESSAGE,
+    })
+    state["max_output_tokens_recovery_count"] += 1
+    state["transition"] = "max_tokens_recovery"
+    continue
+```
+
+重点不是“多写一行”。
+
+重点是：
+
+**每次继续之前，你都要知道自己做了什么状态更新，以及为什么继续。**
+
+### 第三步：把恢复继续和正常继续分开
+
+```python
+if should_retry_transport(error):
+    time.sleep(backoff(...))
+    state["transition"] = "transport_retry"
+    continue
+
+if should_recompact(error):
+    state["messages"] = compact_messages(state["messages"])
+    state["transition"] = "compact_retry"
+    continue
+```
+
+这时候你就开始得到一条非常清楚的控制链：
+
+```text
+继续
+  不再是一个动作
+  而是一类带原因的转移
+```
+
+## 一张真正应该建立的图
+
+```text
+query loop
+  |
+  +-- tool executed --------------------> transition = tool_result_continuation
+  |
+  +-- output truncated -----------------> transition = max_tokens_recovery
+  |
+  +-- compact just happened -----------> transition = compact_retry
+  |
+  +-- network / transport retry -------> transition = transport_retry
+  |
+  +-- stop hook blocked termination ---> transition = stop_hook_continuation
+  |
+  +-- budget says keep going ----------> transition = budget_continuation
+```
+
+## 它和逆向仓库主脉络为什么对得上
+
+如果你去看更完整系统的查询入口，会发现它真正难的地方从来不是：
+
+- 再调一次模型
+
+而是：
+
+- 什么时候该继续
+- 继续前改哪份状态
+- 继续属于哪一种路径
+
+所以这篇桥接文档讲的，不是额外装饰，而是完整 query engine 的主骨架之一。
+
+## 它和主线章节怎么接
+
+- `s01` 让你先把 loop 跑起来
+- `s06` 让你知道为什么上下文管理会介入继续路径
+- `s11` 让你知道为什么恢复路径不是一种
+- 这篇则把“继续原因”统一抬成显式状态
+
+所以你可以把它理解成：
+
+> 给前后几章之间补上一条“为什么继续”的统一主线。
+
+## 初学者最容易犯的错
+
+### 1. 只有 `continue`，没有 `transition`
+
+这样日志和测试都会越来越难看。
+
+### 2. 把所有继续都当成一种
+
+这样会把：
+
+- 正常主线继续
+- 错误恢复继续
+- 压缩后重试
+
+全部混成一锅。
+
+### 3. 没有 continuation budget
+
+没有预算，系统就会在某些坏路径里无限试下去。
+
+### 4. 把 `transition` 写进消息文本，而不是流程状态
+
+消息是给模型看的。  
+`transition` 是给系统自己看的。
+
+### 5. 压缩、恢复、hook 都发生了，却没有统一的查询状态
+
+这会导致控制逻辑散落在很多局部变量里，越长越乱。
+
+## 教学边界
+
+这篇最重要的，不是一次枚举完所有 transition 名字，而是先让你守住三件事：
+
+- `continue` 最好总能对应一个显式的 `transition reason`
+- 正常继续、恢复继续、压缩后重试，不应该被混成同一种路径
+- continuation 需要预算和状态，而不是无限重来
+
+只要这三点成立，你就已经能把 `s01 / s06 / s11` 真正串成一条完整主线。  
+更细的 transition taxonomy、预算策略和日志分类，可以放到你把最小 query 状态机写稳以后再补。
+
+## 读完这一篇你应该能说清楚
+
+至少能完整说出这句话：
+
+> 一条 query 不是简单 while loop，而是一串显式 continuation reason 驱动的状态转移。
+
+如果这句话你已经能稳定说清，那么你再回头看 `s11`、`s19`，心智会顺很多。
diff --git a/docs/zh/s00d-chapter-order-rationale.md b/docs/zh/s00d-chapter-order-rationale.md
new file mode 100644
index 000000000..487c4e3a6
--- /dev/null
+++ b/docs/zh/s00d-chapter-order-rationale.md
@@ -0,0 +1,513 @@
+# s00d: Chapter Order Rationale (为什么是这个章节顺序)
+
+> 这份文档不讲某一个机制本身。  
+> 它专门回答一个更基础的问题：
+>
+> **为什么这套仓库要按现在这个顺序教，而不是按源码目录顺序、功能热闹程度，或者“哪里复杂先讲哪里”。**
+
+## 先说结论
+
+当前这套 `s01 -> s19` 的主线顺序，整体上是合理的。
+
+它最大的优点不是“覆盖面广”，而是：
+
+- 先建立最小闭环
+- 再补横切控制面
+- 再补持久化工作层
+- 最后才扩成多 agent 平台和外部能力总线
+
+这个顺序适合教学，因为它遵守的不是“源码文件先后”，而是：
+
+**机制依赖顺序。**
+
+也就是：
+
+- 后一章需要建立在前一章已经清楚的心智之上
+- 同一层的新概念尽量一起讲完
+- 不把高阶平台能力提前压给还没建立主闭环的读者
+
+如果要把这套课程改到更接近满分，一个很重要的标准不是“加更多内容”，而是：
+
+**让读者始终知道这一章为什么现在学，而不是上一章或下一章。**
+
+这份文档就是干这件事的。
+
+## 这份顺序到底按什么排
+
+不是按这些排：
+
+- 不是按逆向源码里文件顺序排
+- 不是按实现难度排
+- 不是按功能看起来酷不酷排
+- 不是按产品里出现得早不早排
+
+它真正按的是四条依赖线：
+
+1. `主闭环依赖`
+2. `控制面依赖`
+3. `工作状态依赖`
+4. `平台边界依赖`
+
+你可以先把整套课粗暴地看成下面这条线：
+
+```text
+先让 agent 能跑
+  -> 再让它不乱跑
+  -> 再让它能长期跑
+  -> 最后让它能分工跑、隔离跑、接外部能力跑
+```
+
+这才是当前章节顺序最核心的逻辑。
+
+## 一张总图：章节之间真正的依赖关系
+
+```text
+s00 总览与地图
+  |
+  v
+s01 主循环
+  ->
+s02 工具执行
+  ->
+s03 会话计划
+  ->
+s04 子任务隔离
+  ->
+s05 按需知识注入
+  ->
+s06 上下文压缩
+
+s06 之后，单 agent 主骨架成立
+  |
+  v
+s07 权限闸门
+  ->
+s08 生命周期 Hook
+  ->
+s09 跨会话记忆
+  ->
+s10 Prompt / 输入装配
+  ->
+s11 恢复与续行
+
+s11 之后，单 agent 的高完成度控制面成立
+  |
+  v
+s12 持久任务图
+  ->
+s13 运行时后台槽位
+  ->
+s14 时间触发器
+
+s14 之后，工作系统从“聊天过程”升级成“可持续运行时”
+  |
+  v
+s15 持久队友
+  ->
+s16 协议化协作
+  ->
+s17 自治认领
+  ->
+s18 worktree 执行车道
+  ->
+s19 外部能力总线
+```
+
+如果你记不住所有章节，只记住每段结束后的“系统里多了什么”：
+
+- `s06` 结束：你有了能工作的单 agent
+- `s11` 结束：你有了更稳、更可控的单 agent
+- `s14` 结束：你有了能长期推进工作的运行时
+- `s19` 结束：你有了接近完整的平台边界
+
+## 为什么 `s01-s06` 必须先成一整段
+
+### `s01` 必须最先
+
+因为它定义的是：
+
+- 这套系统的最小入口
+- 每一轮到底怎么推进
+- 工具结果为什么能再次进入模型
+
+如果连这一条都没建立，后面所有内容都会变成“往空气里挂功能”。
+
+### `s02` 必须紧跟 `s01`
+
+因为没有工具，agent 只是会说，不是真的会做。
+
+开发者第一次真正感受到“harness 在做什么”，往往就是在 `s02`：
+
+- 模型产出 `tool_use`
+- 系统找到 handler
+- 执行工具
+- 回写 `tool_result`
+
+这是整个仓库第一条真正的“行动回路”。
+
+### `s03` 放在 `s04` 前面是对的
+
+很多人会直觉上想先讲 subagent，因为它更“高级”。
+
+但教学上不该这样排。
+
+原因很简单：
+
+- `s03` 先解决“当前 agent 自己怎么不乱撞”
+- `s04` 再解决“哪些工作要交给别的执行者”
+
+如果主 agent 连本地计划都没有，就提前进入子 agent，读者只会觉得：
+
+- 为什么要委派
+- 委派和待办到底是什么关系
+- 哪些是主流程，哪些是探索性流程
+
+都不清楚。
+
+所以：
+
+**先有本地计划，再有上下文隔离委派。**
+
+### `s05` 放在 `s06` 前面是对的
+
+这两个章节很多人会低估。
+
+实际上它们解决的是同一类问题的前后两半：
+
+- `s05` 解决：知识不要一开始全塞进来
+- `s06` 解决：已经塞进来的上下文怎么控制体积
+
+如果先讲压缩，再讲技能加载，读者容易误会成：
+
+- 上下文膨胀主要靠“事后压缩”解决
+
+但更合理的心智应该是：
+
+1. 先减少不必要进入上下文的东西
+2. 再处理已经进入上下文、且必须继续保留的东西
+
+所以 `s05 -> s06` 的顺序很合理。
+
+## 为什么 `s07-s11` 应该成一整段“控制面加固”
+
+这五章看起来分散，实际上它们共同在回答同一个问题：
+
+**主循环已经能跑了，但要怎样才能跑得稳、跑得可控、跑得更像一个完整系统。**
+
+### `s07` 权限必须早于 `s08` Hook
+
+因为权限是在问：
+
+- 这件事能不能做
+- 这件事做到哪一步要停
+- 这件事要不要先问用户
+
+Hook 是在问：
+
+- 系统这个时刻要不要额外做点什么
+
+如果先讲 Hook，再讲权限，读者很容易误会：
+
+- 安全判断也只是某个 hook
+
+但实际上不是。
+
+更清楚的教学顺序应该是：
+
+1. 先建立“执行前必须先过闸门”的概念
+2. 再建立“主循环周围可以挂扩展点”的概念
+
+也就是：
+
+**先 gate，再 extend。**
+
+### `s09` 记忆放在 `s10` Prompt 前面是对的
+
+这是整套课程里很关键的一条顺序。
+
+很多人容易反过来讲，先讲 prompt，再讲 memory。
+
+但对开发者心智更友好的顺序其实是现在这样：
+
+- `s09` 先讲“长期信息从哪里来、哪些值得留下”
+- `s10` 再讲“这些来源最终怎样被组装进模型输入”
+
+也就是说：
+
+- `memory` 先回答“内容源是什么”
+- `prompt pipeline` 再回答“这些内容源怎么装配”
+
+如果反过来，读者会在 `s10` 里不断追问：
+
+- 为什么这里会有 memory block
+- 这块内容到底是谁准备的
+- 它和 messages、CLAUDE.md、skills 的边界在哪里
+
+所以这一条顺序不要乱换。
+
+### `s11` 放在这一段结尾很合理
+
+因为恢复与续行不是单独一层业务功能，而是：
+
+- 对前面所有输入、执行、状态、权限、压缩分支的总回收
+
+它天然适合做“控制面阶段的收口章”。
+
+只有当读者已经知道：
+
+- 一轮输入怎么组装
+- 执行时会走哪些分支
+- 发生什么状态变化
+
+他才真正看得懂恢复系统在恢复什么。
+
+## 为什么 `s12-s14` 必须先讲“任务图”，再讲“后台运行”，最后讲“定时触发”
+
+这是后半程最容易排错的一段。
+
+### `s12` 必须先于 `s13`
+
+因为 `s12` 解决的是：
+
+- 事情本身是什么
+- 依赖关系是什么
+- 哪个工作节点已完成、未完成、阻塞中
+
+而 `s13` 解决的是：
+
+- 某个执行单元现在是不是正在后台跑
+- 跑到什么状态
+- 结果怎么回流
+
+也就是：
+
+- `task` 是工作目标
+- `runtime task` 是执行槽位
+
+如果没有 `s12` 先铺开 durable work graph，读者到了 `s13` 会把后台任务误当成任务系统本体。
+
+这会直接导致后面：
+
+- cron 概念混乱
+- teammate 认领概念混乱
+- worktree lane 概念混乱
+
+所以这里一定要守住：
+
+**先有目标，再有执行体。**
+
+### `s14` 必须紧跟 `s13`
+
+因为 cron 本质上不是又一种任务。
+
+它只是回答：
+
+**如果现在不是用户当场触发，而是由时间触发一次执行，该怎么接到现有运行时里。**
+
+也就是说：
+
+- 没有 runtime slot，cron 没地方发车
+- 没有 task graph，cron 不知道在触发什么工作
+
+所以最合理顺序一定是：
+
+`task graph -> runtime slot -> schedule trigger`
+
+## 为什么 `s15-s19` 要按“队友 -> 协议 -> 自治 -> 隔离车道 -> 外部能力”排
+
+这一段如果顺序乱了，读者最容易开始觉得：
+
+- 队友、协议、任务、worktree、MCP 全都像“高级功能堆叠”
+
+但其实它们之间有很强的前后依赖。
+
+### `s15` 先定义“谁在系统里长期存在”
+
+这一章先把对象立起来：
+
+- 队友是谁
+- 他们有没有身份
+- 他们是不是可以持续存在
+
+如果连 actor 都还没清楚，协议对象就无从谈起。
+
+### `s16` 再定义“这些 actor 之间按什么规则说话”
+
+协议层不应该早于 actor 层。
+
+因为协议不是凭空存在的。
+
+它一定是服务于：
+
+- 请求谁
+- 谁审批
+- 谁响应
+- 如何回执
+
+所以：
+
+**先有队友，再有协议。**
+
+### `s17` 再进入“队友自己找活”
+
+自治不是“又多一种 agent 功能”。
+
+自治其实是建立在前两章之上的：
+
+- 前提 1：队友是长期存在的
+- 前提 2：队友之间有可追踪的协作规则
+
+只有这两个前提都建立了，自治认领才不会讲成一团雾。
+
+### `s18` 为什么在 `s19` 前面
+
+因为在平台层里，worktree 是执行隔离边界，MCP 是能力边界。
+
+对开发者自己手搓系统来说，更应先搞清：
+
+- 多个执行者如何不互相踩目录
+- 一个任务与一个执行车道如何绑定
+
+这些是“本地多执行者平台”先要解决的问题。
+
+把这个问题讲完后，再去讲：
+
+- 外部 server
+- 外部 tool
+- capability route
+
+开发者才不会把“MCP 很强”误解成“本地平台边界可以先不管”。
+
+### `s19` 放最后是对的
+
+因为它本质上是平台边界的最外层。
+
+它关心的是：
+
+- 本地系统之外的能力如何并入
+- 外部 server 和本地 tool 如何统一纳入 capability bus
+
+这个东西只有在前面这些边界都已经清楚后，读者才真的能吸收：
+
+- 本地 actor
+- 本地 work lane
+- 本地 task / runtime state
+- 外部 capability provider
+
+分别是什么。
+
+## 五种最容易让课程变差的“错误重排”
+
+### 错误 1：把 `s04` 提到 `s03` 前面
+
+坏处：
+
+- 读者先学会“把活丢出去”
+- 却还没学会“本地怎么规划”
+
+最后 subagent 只会变成“遇事就开新 agent”的逃避按钮。
+
+### 错误 2：把 `s10` 提到 `s09` 前面
+
+坏处：
+
+- 输入装配先讲了
+- 但输入源的边界还没立住
+
+结果 prompt pipeline 会看起来像一堆神秘字符串拼接。
+
+### 错误 3：把 `s13` 提到 `s12` 前面
+
+坏处：
+
+- 读者会把后台执行槽位误认成工作任务本体
+- 后面 cron、自治认领、worktree 都会越来越混
+
+### 错误 4：把 `s17` 提到 `s15` 或 `s16` 前面
+
+坏处：
+
+- 还没定义持久队友
+- 也还没定义结构化协作规则
+- 就先讲自治认领
+
+最后“自治”会被理解成模糊的自动轮询魔法。
+
+### 错误 5：把 `s19` 提到 `s18` 前面
+
+坏处：
+
+- 读者会先被外部能力系统吸引注意力
+- 却还没真正看清本地多执行者平台怎么稳定成立
+
+这会让整个课程后半程“看起来很大”，但“落到自己实现时没有抓手”。
+
+## 如果你自己手搓，可以在哪些地方先停
+
+这套课不是说一定要一次把 `s01-s19` 全做完。
+
+更稳的实现节奏是：
+
+### 里程碑 A：先做到 `s06`
+
+你已经有：
+
+- 主循环
+- 工具
+- 计划
+- 子任务隔离
+- 技能按需注入
+- 上下文压缩
+
+这已经足够做出一个“能用的单 agent 原型”。
+
+### 里程碑 B：再做到 `s11`
+
+你多了：
+
+- 权限
+- Hook
+- Memory
+- Prompt pipeline
+- 错误恢复
+
+到这里，单 agent 系统已经接近“高完成度教学实现”。
+
+### 里程碑 C：做到 `s14`
+
+你多了：
+
+- durable task
+- background runtime slot
+- cron trigger
+
+到这里，系统开始脱离“只会跟着当前会话走”的状态。
+
+### 里程碑 D：做到 `s19`
+
+这时再进入：
+
+- persistent teammate
+- protocol
+- autonomy
+- worktree lane
+- MCP / plugin
+
+这时你手里才是接近完整的平台结构。
+
+## 维护者在重排章节前该问自己什么
+
+如果你准备改顺序，先问下面这些问题：
+
+1. 这一章依赖的前置概念，前面有没有已经讲清？
+2. 这次重排会不会让两个同名但不同层的概念更容易混？
+3. 这一章新增的是“目标状态”“运行状态”“执行者”还是“外部能力”？
+4. 如果把它提前，读者会不会只记住名词，反而抓不到最小实现？
+5. 这次重排是在服务开发者实现路径，还是只是在模仿某个源码目录顺序？
+6. 读者按当前章节学完以后，本地代码到底该按什么顺序打开，这条代码阅读顺序有没有一起讲清？
+
+如果第 5 个问题的答案偏向后者，那大概率不该改。
+
+## 一句话记住
+
+**好的章节顺序，不是把所有机制排成一列，而是让每一章都像前一章自然长出来的下一层。**
diff --git a/docs/zh/s00e-reference-module-map.md b/docs/zh/s00e-reference-module-map.md
new file mode 100644
index 000000000..dedfcd1ae
--- /dev/null
+++ b/docs/zh/s00e-reference-module-map.md
@@ -0,0 +1,215 @@
+# s00e: 参考仓库模块映射图
+
+> 这是一份给维护者和认真学习者用的校准文档。  
+> 它不是让读者逐行读逆向源码。
+>
+> 它只回答一个很关键的问题：
+>
+> **如果把参考仓库里真正重要的模块簇，和当前教学仓库的章节顺序对照起来看，现在这套课程顺序到底合不合理？**
+
+## 先说结论
+
+合理。
+
+当前这套 `s01 -> s19` 的顺序，整体上是对的，而且比“按源码目录顺序讲”更接近真实系统的设计主干。
+
+原因很简单：
+
+- 参考仓库里目录很多
+- 但真正决定系统骨架的，是少数几簇控制、状态、任务、团队、隔离执行和外部能力模块
+- 这些高信号模块，和当前教学仓库的四阶段主线基本是对齐的
+
+所以正确动作不是把教程改成“跟着源码树走”。
+
+正确动作是：
+
+- 保留现在这条按依赖关系展开的主线
+- 把它和参考仓库的映射关系讲明白
+- 继续把低价值的产品外围细节挡在主线外
+
+## 这份对照是怎么做的
+
+这次对照主要看的是参考仓库里真正决定系统骨架的部分，例如：
+
+- `Tool.ts`
+- `state/AppStateStore.ts`
+- `coordinator/coordinatorMode.ts`
+- `memdir/*`
+- `services/SessionMemory/*`
+- `services/toolUseSummary/*`
+- `constants/prompts.ts`
+- `tasks/*`
+- `tools/TodoWriteTool/*`
+- `tools/AgentTool/*`
+- `tools/ScheduleCronTool/*`
+- `tools/EnterWorktreeTool/*`
+- `tools/ExitWorktreeTool/*`
+- `tools/MCPTool/*`
+- `services/mcp/*`
+- `plugins/*`
+- `hooks/toolPermission/*`
+
+这些已经足够判断“设计主脉络”。
+
+没有必要为了教学，再把每个命令目录、兼容分支、UI 细节和产品接线全部拖进正文。
+
+## 真正的映射关系
+
+| 参考仓库模块簇 | 典型例子 | 对应教学章节 | 为什么这样放是对的 |
+|---|---|---|---|
+| 查询主循环 + 控制状态 | `Tool.ts`、`AppStateStore.ts`、query / coordinator 状态 | `s00`、`s00a`、`s00b`、`s01`、`s11` | 真实系统绝不只是 `messages[] + while True`。教学上先讲最小循环，再补控制平面，是对的。 |
+| 工具路由与执行面 | `Tool.ts`、原生 tools、tool context、执行辅助逻辑 | `s02`、`s02a`、`s02b` | 参考仓库明确把 tools 做成统一执行面，不只是玩具版分发表。当前拆法是合理的。 |
+| 会话规划 | `TodoWriteTool` | `s03` | 这是“当前会话怎么不乱撞”的小结构，应该早于持久任务图。 |
+| 一次性委派 | `AgentTool` 的最小子集 | `s04` | 参考仓库的 agent 体系很大，但教学仓库先教“新上下文 + 子任务 + 摘要返回”这个最小正确版本，是对的。 |
+| 技能发现与按需加载 | `DiscoverSkillsTool`、`skills/*`、相关 prompt 片段 | `s05` | 技能不是花哨外挂，而是知识注入层，所以应早于 prompt 复杂化和上下文压力。 |
+| 上下文压力与压缩 | `services/toolUseSummary/*`、`services/contextCollapse/*`、compact 逻辑 | `s06` | 参考仓库明确存在显式压缩机制，把这一层放在平台化能力之前完全正确。 |
+| 权限闸门 | `types/permissions.ts`、`hooks/toolPermission/*`、审批处理器 | `s07` | 执行安全是明确闸门，不是“某个 hook 顺手干的事”，所以必须早于 hook。 |
+| Hook 与侧边扩展 | `types/hooks.ts`、hook runner、生命周期接线 | `s08` | 参考仓库把扩展点和权限分开。教学顺序保持“先 gate，再 extend”是对的。 |
+| 持久记忆选择 | `memdir/*`、`services/SessionMemory/*`、记忆提取与筛选 | `s09` | 参考仓库把 memory 处理成“跨会话、选择性装配”的层，不是通用笔记本。 |
+| Prompt 组装 | `constants/prompts.ts`、prompt sections、memory prompt 注入 | `s10`、`s10a` | 参考仓库明显把输入拆成多个 section。教学版把 prompt 讲成流水线，而不是一段大字符串，是正确的。 |
+| 恢复与续行 | query transition、retry 分支、compact retry、token recovery | `s11`、`s00c` | 真实系统里“为什么继续下一轮”是显式存在的，所以恢复应当晚于 loop / tools / compact / permissions / memory / prompt。 |
+| 持久工作图 | 任务记录、任务板、依赖解锁 | `s12` | 当前教程把“持久任务目标”和“会话内待办”分开，是对的。 |
+| 活着的运行时任务 | `tasks/types.ts`、`LocalShellTask`、`LocalAgentTask`、`RemoteAgentTask`、`MonitorMcpTask` | `s13`、`s13a` | 参考仓库里 runtime task 是明确的联合类型，这强烈证明 `TaskRecord` 和 `RuntimeTaskState` 必须分开教。 |
+| 定时触发 | `ScheduleCronTool/*`、`useScheduledTasks` | `s14` | 调度是建在 runtime work 之上的新启动条件，放在 `s13` 后非常合理。 |
+| 持久队友 | `InProcessTeammateTask`、team tools、agent registry | `s15` | 参考仓库清楚地从一次性 subagent 继续长成长期 actor。把 teammate 放到后段是对的。 |
+| 结构化团队协作 | send-message 流、request tracking、coordinator mode | `s16` | 协议必须建立在“已有持久 actor”之上，所以不能提前。 |
+| 自治认领与恢复 | coordinator mode、任务认领、异步 worker 生命周期、resume 逻辑 | `s17` | 参考仓库里的 autonomy 不是魔法，而是建立在 actor、任务和协议之上的。 |
+| Worktree 执行车道 | `EnterWorktreeTool`、`ExitWorktreeTool`、agent worktree 辅助逻辑 | `s18` | 参考仓库把 worktree 当作执行边界 + 收尾状态来处理。当前放在 tasks / teams 后是正确的。 |
+| 外部能力总线 | `MCPTool`、`services/mcp/*`、`plugins/*`、MCP resources / prompts / tools | `s19`、`s19a` | 参考仓库把 MCP / plugin 放在平台最外层边界。把它放最后是合理的。 |
+
+## 这份对照最能证明的 5 件事
+
+### 1. `s03` 应该继续放在 `s12` 前面
+
+参考仓库里同时存在：
+
+- 小范围的会话计划
+- 大范围的持久任务 / 运行时系统
+
+它们不是一回事。
+
+所以教学顺序应当继续保持：
+
+`会话内计划 -> 持久任务图`
+
+### 2. `s09` 应该继续放在 `s10` 前面
+
+参考仓库里的输入装配，明确把 memory 当成输入来源之一。
+
+也就是说：
+
+- `memory` 先回答“内容从哪里来”
+- `prompt pipeline` 再回答“这些内容怎么组装进去”
+
+所以先讲 `s09`，再讲 `s10`，顺序不要反过来。
+
+### 3. `s12` 必须早于 `s13`
+
+`tasks/types.ts` 这类运行时任务联合类型，是这次对照里最强的证据之一。
+
+它非常清楚地说明：
+
+- 持久化的工作目标
+- 当前活着的执行槽位
+
+必须是两层不同状态。
+
+如果先讲 `s13`，读者几乎一定会把这两层混掉。
+
+### 4. `s15 -> s16 -> s17` 的顺序是对的
+
+参考仓库里明确能看到：
+
+- 持久 actor
+- 结构化协作
+- 自治认领 / 恢复
+
+自治必须建立在前两者之上，所以当前顺序合理。
+
+### 5. `s18` 应该继续早于 `s19`
+
+参考仓库把 worktree 当作本地执行边界机制。
+
+这应该先于：
+
+- 外部能力提供者
+- MCP server
+- plugin 装配面
+
+被讲清。
+
+否则读者会误以为“外部能力系统比本地执行边界更核心”。
+
+## 这套教学仓库仍然不该抄进主线的内容
+
+参考仓库里有很多真实但不应该占据主线的内容，例如：
+
+- CLI 命令面的完整铺开
+- UI 渲染细节
+- 遥测与分析分支
+- 远程 / 企业产品接线
+- 平台兼容层
+- 文件名、函数名、行号级 trivia
+
+这些不是假的。
+
+但它们不该成为 0 到 1 教学路径的中心。
+
+## 当前教学最容易漂掉的地方
+
+### 1. 不要把 subagent 和 teammate 混成一个模糊概念
+
+参考仓库里的 `AgentTool` 横跨了：
+
+- 一次性委派
+- 后台 worker
+- 持久 worker / teammate
+- worktree 隔离 worker
+
+这恰恰说明教学仓库应该继续拆开讲：
+
+- `s04`
+- `s15`
+- `s17`
+- `s18`
+
+不要在早期就把这些东西混成一个“大 agent 能力”。
+
+### 2. 不要把 worktree 教成“只是 git 小技巧”
+
+参考仓库里有 closeout、resume、cleanup、dirty-check 等状态。
+
+所以 `s18` 必须继续讲清：
+
+- lane 身份
+- task 绑定
+- keep / remove 收尾
+- 恢复与清理
+
+而不是只讲 `git worktree add`。
+
+### 3. 不要把 MCP 缩成“远程 tools”
+
+参考仓库里明显不只有工具，还有：
+
+- resources
+- prompts
+- elicitation / connection state
+- plugin 中介层
+
+所以 `s19` 可以继续用 tools-first 的教学路径切入，但一定要补平台边界那一层地图。
+
+## 最终判断
+
+如果只拿“章节顺序是否贴近参考仓库的设计主干”这个问题来打分，那么当前这套顺序是过关而且方向正确的。
+
+真正还能继续加分的地方，不再是再做一次大重排，而是：
+
+- 把桥接文档补齐
+- 把实体边界讲得更硬
+- 把多语言内容统一到同一个心智层次
+- 让 web 页面把这套学习地图展示得更清楚
+
+## 一句话记住
+
+**最好的教学顺序，不是源码文件出现的顺序，而是一个初学实现者真正能顺着依赖关系把系统重建出来的顺序。**
diff --git a/docs/zh/s00f-code-reading-order.md b/docs/zh/s00f-code-reading-order.md
new file mode 100644
index 000000000..f85d97c27
--- /dev/null
+++ b/docs/zh/s00f-code-reading-order.md
@@ -0,0 +1,283 @@
+# s00f: 本仓库代码阅读顺序
+
+> 这份文档不是让你“多看代码”。  
+> 它专门解决另一个问题：
+>
+> **当你已经知道章节顺序是对的以后，本仓库代码到底应该按什么顺序读，才不会把心智重新读乱。**
+
+## 先说结论
+
+不要这样读代码：
+
+- 不要从文件最长的那一章开始
+- 不要随机点一个你觉得“高级”的章节开始
+- 不要先钻 `web/` 再回头猜主线
+- 不要把 19 个 `agents/*.py` 当成一个源码池乱翻
+
+最稳的读法只有一句话：
+
+**文档顺着章节读，代码也顺着章节读。**
+
+而且每一章的代码，都先按同一个模板看：
+
+1. 先看状态结构
+2. 再看工具定义或注册表
+3. 再看“这一轮怎么推进”的主函数
+4. 最后才看 CLI 入口和试运行方式
+
+## 为什么需要这份文档
+
+很多读者不是看不懂某一章文字，而是会在真正打开代码以后重新乱掉。
+
+典型症状是：
+
+- 一上来先盯住 300 行以上的文件底部
+- 先看一堆 `run_*` 函数，却不知道它们挂在哪条主线上
+- 先看“最复杂”的平台章节，然后觉得前面的章节好像都太简单
+- 把 `task`、`runtime task`、`teammate`、`worktree` 在代码里重新混成一团
+
+这份阅读顺序就是为了防止这种情况。
+
+## 读每个 agent 文件时，都先按同一个模板
+
+不管你打开的是哪一章，本仓库里的 `agents/sXX_*.py` 都建议先按下面顺序读：
+
+### 第一步：先看文件头注释
+
+先回答两个问题：
+
+- 这一章到底在教什么
+- 它故意没有教什么
+
+如果连这一步都没建立，后面你会把每个函数都看成同等重要。
+
+### 第二步：先看状态结构或管理器类
+
+优先找这些东西：
+
+- `LoopState`
+- `PlanningState`
+- `CompactState`
+- `TaskManager`
+- `BackgroundManager`
+- `TeammateManager`
+- `WorktreeManager`
+
+原因很简单：
+
+**先知道系统到底记住了什么，后面才看得懂它为什么要这样流动。**
+
+### 第三步：再看工具列表或注册表
+
+优先找这些入口：
+
+- `TOOLS`
+- `TOOL_HANDLERS`
+- 各种 `run_*`
+- `build_tool_pool()`
+
+这一层回答的是：
+
+- 模型到底能调用什么
+- 这些调用会落到哪条执行面上
+
+### 第四步：最后才看主推进函数
+
+重点函数通常长这样：
+
+- `run_one_turn(...)`
+- `agent_loop(...)`
+- 某个 `handle_*`
+
+这一步要回答的是：
+
+- 这一章新机制到底接在主循环哪一环
+- 哪个分支是新增的
+- 新状态是在哪里写入、回流、继续的
+
+### 第五步：最后再看 `if __name__ == "__main__"`
+
+CLI 入口当然有用，但它不应该成为第一屏。
+
+因为它通常只是在做：
+
+- 读用户输入
+- 初始化状态
+- 调用 `agent_loop`
+
+真正决定一章心智主干的，不在这里。
+
+## 阶段 1：`s01-s06` 应该怎样读代码
+
+这一段不是在学“很多功能”，而是在学：
+
+**一个单 agent 主骨架到底怎样成立。**
+
+| 章节 | 文件 | 先看什么 | 再看什么 | 读完要确认什么 |
+|---|---|---|---|---|
+| `s01` | `agents/s01_agent_loop.py` | `LoopState` | `TOOLS` -> `execute_tool_calls()` -> `run_one_turn()` -> `agent_loop()` | 你已经能看懂 `messages -> model -> tool_result -> next turn` |
+| `s02` | `agents/s02_tool_use.py` | `safe_path()` | `run_read()` / `run_write()` / `run_edit()` -> `TOOL_HANDLERS` -> `agent_loop()` | 你已经能看懂“主循环不变，工具靠分发面增长” |
+| `s03` | `agents/s03_todo_write.py` | `PlanItem` / `PlanningState` / `TodoManager` | `todo` 相关 handler -> reminder 注入 -> `agent_loop()` | 你已经能看懂“会话计划状态”怎么外显化 |
+| `s04` | `agents/s04_subagent.py` | `AgentTemplate` | `run_subagent()` -> 父 `agent_loop()` | 你已经能看懂“子智能体首先是上下文隔离” |
+| `s05` | `agents/s05_skill_loading.py` | `SkillManifest` / `SkillDocument` / `SkillRegistry` | `get_descriptions()` / `get_content()` -> `agent_loop()` | 你已经能看懂“先发现、再按需加载” |
+| `s06` | `agents/s06_context_compact.py` | `CompactState` | `persist_large_output()` -> `micro_compact()` -> `compact_history()` -> `agent_loop()` | 你已经能看懂“压缩不是删历史，而是转移细节” |
+
+### 阶段 1 的 Deep Agents 轨道
+
+读完手写版 `agents/s01-s06` 以后，可以继续看 `agents_deepagents/s01_agent_loop.py` 到 `agents_deepagents/s11_error_recovery.py`。这是一条 Deep Agents 教学轨道：原来的 `agents/*.py` 不变，运行时继续使用 OpenAI 风格的 `OPENAI_API_KEY` / `OPENAI_MODEL`（可选 `OPENAI_BASE_URL`）配置，但能力会按章节逐步开放——`s01` 只保留最小 loop，`s03` 才引入 planning，`s04` 才引入 subagent，`s05` 才引入 skills，`s06` 才引入 context compact。当前 web UI 暂不展示这条轨道。
+
+### 这一段最值得反复看的 3 个代码点
+
+1. `state` 在哪里第一次从“聊天内容”升级成“显式系统状态”
+2. `tool_result` 是怎么一直保持为统一回流接口的
+3. 新机制是怎样接进 `agent_loop()` 而不是把 `agent_loop()` 重写烂的
+
+### 这一段读完后，最好的动作
+
+不要立刻去看 `s07`。
+
+先自己从空目录手写一遍下面这些最小件：
+
+- 一个 loop
+- 一个 dispatch map
+- 一个会话计划状态
+- 一个一次性子任务隔离
+- 一个按需技能加载
+- 一个最小压缩层
+
+## 阶段 2：`s07-s11` 应该怎样读代码
+
+### 阶段 2 的 Deep Agents 轨道
+
+继续阅读 `agents_deepagents/s07_permission_system.py` 到 `agents_deepagents/s11_error_recovery.py`。这一段保持原教程章节顺序，把 permissions、hooks、memory、prompt、error recovery 挂回同一条 Deep Agents 分阶段轨道。
+
+这一段不是在学“又多了五种功能”。
+
+它真正是在学：
+
+**单 agent 的控制面是怎样长出来的。**
+
+| 章节 | 文件 | 先看什么 | 再看什么 | 读完要确认什么 |
+|---|---|---|---|---|
+| `s07` | `agents/s07_permission_system.py` | `BashSecurityValidator` / `PermissionManager` | 权限判定入口 -> `run_bash()` -> `agent_loop()` | 你已经能看懂“先 gate，再 execute” |
+| `s08` | `agents/s08_hook_system.py` | `HookManager` | hook 注册与触发 -> `agent_loop()` | 你已经能看懂 hook 是固定时机的插口，不是散落 if |
+| `s09` | `agents/s09_memory_system.py` | `MemoryManager` / `DreamConsolidator` | `run_save_memory()` -> `build_system_prompt()` -> `agent_loop()` | 你已经能看懂 memory 是长期信息层，不是上下文垃圾桶 |
+| `s10` | `agents/s10_system_prompt.py` | `SystemPromptBuilder` | `build_system_reminder()` -> `agent_loop()` | 你已经能看懂输入是流水线，不是单块 prompt |
+| `s11` | `agents/s11_error_recovery.py` | `estimate_tokens()` / `auto_compact()` / `backoff_delay()` | 各恢复分支 -> `agent_loop()` | 你已经能看懂“恢复以后怎样继续下一轮” |
+
+### 这一段读代码时，最容易重新读乱的地方
+
+1. 把权限和 hook 混成一类
+2. 把 memory 和 prompt 装配混成一类
+3. 把 `s11` 看成很多异常判断，而不是“续行控制”
+
+如果你开始混，先回：
+
+- `docs/zh/s00a-query-control-plane.md`
+- `docs/zh/s10a-message-prompt-pipeline.md`
+- `docs/zh/s00c-query-transition-model.md`
+
+## 阶段 3：`s12-s14` 应该怎样读代码
+
+这一段开始，代码理解的关键不再是“工具多了什么”，而是：
+
+**系统第一次真正长出会话外工作状态和运行时槽位。**
+
+| 章节 | 文件 | 先看什么 | 再看什么 | 读完要确认什么 |
+|---|---|---|---|---|
+| `s12` | `agents/s12_task_system.py` | `TaskManager` | 任务创建、依赖、解锁 -> `agent_loop()` | 你已经能看懂 task 是持久工作图，不是 todo |
+| `s13` | `agents/s13_background_tasks.py` | `NotificationQueue` / `BackgroundManager` | 后台执行登记 -> 通知排空 -> `agent_loop()` | 你已经能看懂 background task 是运行槽位 |
+| `s14` | `agents/s14_cron_scheduler.py` | `CronLock` / `CronScheduler` | `cron_matches()` -> schedule 触发 -> `agent_loop()` | 你已经能看懂调度器只负责“未来何时开始” |
+
+### 这一段读代码时一定要守住的边界
+
+- `task` 是工作目标
+- `runtime task` 是正在跑的执行槽位
+- `schedule` 是何时触发工作
+
+只要这三层在代码里重新混掉，后面 `s15-s19` 会一起变难。
+
+## 阶段 4：`s15-s19` 应该怎样读代码
+
+这一段不要当成“功能狂欢”去读。
+
+它真正建立的是：
+
+**平台边界。**
+
+| 章节 | 文件 | 先看什么 | 再看什么 | 读完要确认什么 |
+|---|---|---|---|---|
+| `s15` | `agents/s15_agent_teams.py` | `MessageBus` / `TeammateManager` | 队友名册、邮箱、独立循环 -> `agent_loop()` | 你已经能看懂 teammate 是长期 actor，不是一次性 subagent |
+| `s16` | `agents/s16_team_protocols.py` | `RequestStore` / `TeammateManager` | `handle_shutdown_request()` / `handle_plan_review()` -> `agent_loop()` | 你已经能看懂 request-response + `request_id` |
+| `s17` | `agents/s17_autonomous_agents.py` | `RequestStore` / `TeammateManager` | `is_claimable_task()` / `claim_task()` / `ensure_identity_context()` -> `agent_loop()` | 你已经能看懂自治主线：空闲检查 -> 安全认领 -> 恢复工作 |
+| `s18` | `agents/s18_worktree_task_isolation.py` | `TaskManager` / `WorktreeManager` / `EventBus` | `worktree_enter` 相关生命周期 -> `agent_loop()` | 你已经能看懂 task 管目标，worktree 管执行车道 |
+| `s19` | `agents/s19_mcp_plugin.py` | `CapabilityPermissionGate` / `MCPClient` / `PluginLoader` / `MCPToolRouter` | `build_tool_pool()` / `handle_tool_call()` / `normalize_tool_result()` -> `agent_loop()` | 你已经能看懂外部能力如何接回同一控制面 |
+
+### 这一段最容易误读的地方
+
+1. 把 `s15` 的 teammate 当成 `s04` 的 subagent 放大版
+2. 把 `s17` 自治看成“agent 自己乱跑”
+3. 把 `s18` worktree 看成一个 git 小技巧
+4. 把 `s19` MCP 缩成“只是远程 tools”
+
+## 代码阅读时，哪些文件不要先看
+
+如果你的目标是建立主线心智，下面这些内容不要先看：
+
+- `web/` 里的可视化实现细节
+- `web/src/data/generated/*`
+- `.next/` 或其他构建产物
+- `agents/s_full.py`
+
+原因不是它们没价值。
+
+而是：
+
+- `web/` 解决的是展示与学习界面
+- `generated` 是抽取结果，不是机制本身
+- `s_full.py` 是整合参考，不适合第一次建立边界
+
+## 最推荐的“文档 + 代码 + 运行”循环
+
+每一章最稳的学习动作不是只看文档，也不是只看代码。
+
+推荐固定走这一套：
+
+1. 先读这一章正文
+2. 再读这一章的桥接资料
+3. 再打开对应 `agents/sXX_*.py`
+4. 按“状态 -> 工具 -> 主推进函数 -> CLI 入口”的顺序看
+5. 跑一次这章的 demo
+6. 自己从空目录重写一个最小版本
+
+只要你每章都这样走一次，代码理解会非常稳。
+
+## 初学者最容易犯的 6 个代码阅读错误
+
+### 1. 先看最长文件
+
+这通常只会先把自己看晕。
+
+### 2. 先盯 `run_bash()` 这种工具细节
+
+工具实现细节不是主干。
+
+### 3. 不先找状态结构
+
+这样你永远不知道系统到底记住了什么。
+
+### 4. 把 `agent_loop()` 当成唯一重点
+
+主循环当然重要，但每章真正新增的边界，往往在状态容器和分支入口。
+
+### 5. 读完代码不跑 demo
+
+不实际跑一次，很难建立“这一章到底新增了哪条回路”的感觉。
+
+### 6. 一口气连看三四章代码，不停下来自己重写
+
+这样最容易出现“我好像都看过，但其实自己不会写”的错觉。
+
+## 一句话记住
+
+**代码阅读顺序也必须服从教学顺序：先看边界，再看状态，再看主线如何推进，而不是随机翻源码。**
diff --git a/docs/zh/s01-the-agent-loop.md b/docs/zh/s01-the-agent-loop.md
index 86788dc98..bf2241b5a 100644
--- a/docs/zh/s01-the-agent-loop.md
+++ b/docs/zh/s01-the-agent-loop.md
@@ -1,56 +1,214 @@
-# s01: The Agent Loop (Agent 循环)
+# s01: The Agent Loop (智能体循环)
 
-`[ s01 ] s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
+`s00 > [ s01 ] > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
 
-> *"One loop & Bash is all you need"* -- 一个工具 + 一个循环 = 一个 Agent。
->
-> **Harness 层**: 循环 -- 模型与真实世界的第一道连接。
+> *没有循环，就没有 agent。*  
+> 这一章先教你做出一个最小但正确的循环，再告诉你为什么后面还需要更完整的控制平面。
 
-## 问题
+## 这一章要解决什么问题
 
-语言模型能推理代码, 但碰不到真实世界 -- 不能读文件、跑测试、看报错。没有循环, 每次工具调用你都得手动把结果粘回去。你自己就是那个循环。
+语言模型本身只会“生成下一段内容”。
 
-## 解决方案
+它不会自己：
 
+- 打开文件
+- 运行命令
+- 观察报错
+- 把工具结果再接着用于下一步推理
+
+如果没有一层代码在中间反复做这件事：
+
+```text
+发请求给模型
+  -> 发现模型想调工具
+  -> 真的去执行工具
+  -> 把结果再喂回模型
+  -> 继续下一轮
 ```
-+--------+      +-------+      +---------+
-|  User  | ---> |  LLM  | ---> |  Tool   |
-| prompt |      |       |      | execute |
-+--------+      +---+---+      +----+----+
-                    ^                |
-                    |   tool_result  |
-                    +----------------+
-                    (loop until stop_reason != "tool_use")
+
+那模型就只是一个“会说话的程序”，还不是一个“会干活的 agent”。
+
+所以这一章的核心目标只有一个：
+
+**把“模型 + 工具”连接成一个能持续推进任务的主循环。**
+
+## 先解释几个名词
+
+### 什么是 loop
+
+`loop` 就是循环。
+
+这里的意思不是“程序死循环”，而是：
+
+> 只要任务还没做完，系统就继续重复同一套步骤。
+
+### 什么是 turn
+
+`turn` 可以理解成“一轮”。
+
+最小版本里，一轮通常包含：
+
+1. 把当前消息发给模型
+2. 读取模型回复
+3. 如果模型调用了工具，就执行工具
+4. 把工具结果写回消息历史
+
+然后才进入下一轮。
+
+### 什么是 tool_result
+
+`tool_result` 就是工具执行结果。
+
+它不是随便打印在终端上的日志，而是：
+
+> 要重新写回对话历史、让模型下一轮真的能看见的结果块。
+
+### 什么是 state
+
+`state` 是“当前运行状态”。
+
+第一次看到这个词时，你可以先把它理解成：
+
+> 主循环继续往下走时，需要一直带着走的那份数据。
+
+最小版本里，最重要的状态就是：
+
+- `messages`
+- 当前是第几轮
+- 这一轮结束后为什么还要继续
+
+## 最小心智模型
+
+先把整个 agent 想成下面这条回路：
+
+```text
+user message
+   |
+   v
+LLM
+   |
+   +-- 普通回答 ----------> 结束
+   |
+   +-- tool_use ----------> 执行工具
+                              |
+                              v
+                         tool_result
+                              |
+                              v
+                         写回 messages
+                              |
+                              v
+                         下一轮继续
 ```
 
-一个退出条件控制整个流程。循环持续运行, 直到模型不再调用工具。
+这条图里最关键的，不是“有一个 while True”。
 
-## 工作原理
+真正关键的是这句：
 
-1. 用户 prompt 作为第一条消息。
+**工具结果必须重新进入消息历史，成为下一轮推理的输入。**
+
+如果少了这一步，模型就无法基于真实观察继续工作。
+
+## 关键数据结构
+
+### 1. Message
+
+最小教学版里，可以先把消息理解成：
 
 ```python
-messages.append({"role": "user", "content": query})
+{"role": "user", "content": "..."}
+{"role": "assistant", "content": [...]}
 ```
 
-2. 将消息和工具定义一起发给 LLM。
+这里最重要的不是字段名字，而是你要记住：
+
+**消息历史不是聊天记录展示层，而是模型下一轮要读的工作上下文。**
+
+### 2. Tool Result Block
+
+当工具执行完后，你要把它包装回消息流：
+
+```python
+{
+    "type": "tool_result",
+    "tool_use_id": "...",
+    "content": "...",
+}
+```
+
+`tool_use_id` 的作用很简单：
+
+> 告诉模型“这条结果对应的是你刚才哪一次工具调用”。
+
+### 3. LoopState
+
+这章建议你不要只用一堆零散局部变量。
+
+最小也应该显式收拢出一个循环状态：
+
+```python
+state = {
+    "messages": [...],
+    "turn_count": 1,
+    "transition_reason": None,
+}
+```
+
+这里的 `transition_reason` 先只需要理解成：
+
+> 这一轮结束后，为什么要继续下一轮。
+
+最小教学版只用一种原因就够了：
+
+```python
+"tool_result"
+```
+
+也就是：
+
+> 因为刚执行完工具，所以要继续。
+
+后面到了控制面更完整的章节里，你会看到它逐渐长成更多种原因。  
+如果你想先看完整一点的形状，可以配合读：
+
+- [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)
+
+## 最小实现
+
+### 第一步：准备初始消息
+
+用户的请求先进入 `messages`：
+
+```python
+messages = [{"role": "user", "content": query}]
+```
+
+### 第二步：调用模型
+
+把消息历史、system prompt 和工具定义一起发给模型：
 
 ```python
 response = client.messages.create(
-    model=MODEL, system=SYSTEM, messages=messages,
-    tools=TOOLS, max_tokens=8000,
+    model=MODEL,
+    system=SYSTEM,
+    messages=messages,
+    tools=TOOLS,
+    max_tokens=8000,
 )
 ```
 
-3. 追加助手响应。检查 `stop_reason` -- 如果模型没有调用工具, 结束。
+### 第三步：追加 assistant 回复
 
 ```python
 messages.append({"role": "assistant", "content": response.content})
-if response.stop_reason != "tool_use":
-    return
 ```
 
-4. 执行每个工具调用, 收集结果, 作为 user 消息追加。回到第 2 步。
+这一步非常重要。
+
+很多初学者会只关心“最后有没有答案”，忽略把 assistant 回复本身写回历史。  
+这样一来，下一轮上下文就会断掉。
+
+### 第四步：如果模型调用了工具，就执行
 
 ```python
 results = []
@@ -62,57 +220,135 @@ for block in response.content:
             "tool_use_id": block.id,
             "content": output,
         })
+```
+
+### 第五步：把工具结果作为新消息写回去
+
+```python
 messages.append({"role": "user", "content": results})
 ```
 
-组装为一个完整函数:
+然后下一轮重新发给模型。
+
+### 组合成一个完整循环
 
 ```python
-def agent_loop(query):
-    messages = [{"role": "user", "content": query}]
+def agent_loop(state):
     while True:
         response = client.messages.create(
-            model=MODEL, system=SYSTEM, messages=messages,
-            tools=TOOLS, max_tokens=8000,
+            model=MODEL,
+            system=SYSTEM,
+            messages=state["messages"],
+            tools=TOOLS,
+            max_tokens=8000,
         )
-        messages.append({"role": "assistant", "content": response.content})
+
+        state["messages"].append({
+            "role": "assistant",
+            "content": response.content,
+        })
 
         if response.stop_reason != "tool_use":
+            state["transition_reason"] = None
             return
 
         results = []
         for block in response.content:
             if block.type == "tool_use":
-                output = run_bash(block.input["command"])
+                output = run_tool(block)
                 results.append({
                     "type": "tool_result",
                     "tool_use_id": block.id,
                     "content": output,
                 })
-        messages.append({"role": "user", "content": results})
+
+        state["messages"].append({"role": "user", "content": results})
+        state["turn_count"] += 1
+        state["transition_reason"] = "tool_result"
 ```
 
-不到 30 行, 这就是整个 Agent。后面 11 个章节都在这个循环上叠加机制 -- 循环本身始终不变。
+这就是最小 agent loop。
+
+## 它如何接进整个系统
+
+从现在开始，后面所有章节本质上都在做同一件事：
+
+**往这个循环里增加新的状态、新的分支判断和新的执行能力。**
+
+例如：
+
+- `s02` 往里面接工具路由
+- `s03` 往里面接规划状态
+- `s06` 往里面接上下文压缩
+- `s07` 往里面接权限判断
+- `s11` 往里面接错误恢复
+
+所以请把这一章牢牢记成一句话：
 
-## 变更内容
+> agent 的核心不是“模型很聪明”，而是“系统持续把现实结果喂回模型”。
 
-| 组件          | 之前       | 之后                           |
-|---------------|------------|--------------------------------|
-| Agent loop    | (无)       | `while True` + stop_reason     |
-| Tools         | (无)       | `bash` (单一工具)              |
-| Messages      | (无)       | 累积式消息列表                 |
-| Control flow  | (无)       | `stop_reason != "tool_use"`    |
+## 为什么教学版先接受 `stop_reason == "tool_use"` 这个简化
 
-## 试一试
+这一章里，我们先用：
 
-```sh
-cd learn-claude-code
-python agents/s01_agent_loop.py
+```python
+if response.stop_reason != "tool_use":
+    return
 ```
 
-试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):
+这完全合理。
+
+因为初学者在第一章真正要学会的，不是所有复杂边界，而是：
+
+1. assistant 回复要写回历史
+2. tool_result 要写回历史
+3. 主循环要持续推进
+
+但你也要知道，这只是第一层简化。
+
+更完整的系统不会只依赖 `stop_reason`，还会自己维护更明确的续行状态。  
+这是后面要补的，不是这一章一开始就要背下来的东西。
+
+## 初学者最容易犯的错
+
+### 1. 把工具结果打印出来，但不写回 `messages`
+
+这样模型下一轮根本看不到真实执行结果。
+
+### 2. 只保存用户消息，不保存 assistant 消息
+
+这样上下文会断层，模型会越来越不像“接着刚才做”。
+
+### 3. 不给工具结果绑定 `tool_use_id`
+
+模型会分不清哪条结果对应哪次调用。
+
+### 4. 一上来就把流式、并发、恢复、压缩全塞进第一章
+
+这会让主线变得非常难学。
+
+第一章最重要的是先把最小回路搭起来。
+
+### 5. 以为 `messages` 只是聊天展示
+
+不是。
+
+在 agent 里，`messages` 更像“下一轮工作输入”。
+
+## 教学边界
+
+这一章只需要先讲透一件事：
+
+**Agent 之所以从“会说”变成“会做”，是因为模型输出能走到工具，工具结果又能回到下一轮模型输入。**
+
+所以教学仓库在这里要刻意停住：
+
+- 不要一开始就拉进 streaming、retry、budget、recovery
+- 不要一开始就混入权限、Hook、任务系统
+- 不要把第一章写成整套系统所有后续机制的总图
+
+如果读者已经能凭记忆写出 `messages -> model -> tool_result -> next turn` 这条回路，这一章就已经达标了。
+
+## 一句话记住
 
-1. `Create a file called hello.py that prints "Hello, World!"`
-2. `List all Python files in this directory`
-3. `What is the current git branch?`
-4. `Create a directory called test_output and write 3 files in it`
+**Agent Loop 的本质，是把“模型的动作意图”变成“真实执行结果”，再把结果送回模型继续推理。**
diff --git a/docs/zh/s02-tool-use.md b/docs/zh/s02-tool-use.md
index a26d0a190..aee04179e 100644
--- a/docs/zh/s02-tool-use.md
+++ b/docs/zh/s02-tool-use.md
@@ -1,6 +1,6 @@
 # s02: Tool Use (工具使用)
 
-`s01 > [ s02 ] s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
+`s00 > s01 > [ s02 ] > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
 
 > *"加一个工具, 只加一个 handler"* -- 循环不用动, 新工具注册进 dispatch map 就行。
 >
@@ -99,3 +99,122 @@ python agents/s02_tool_use.py
 2. `Create a file called greet.py with a greet(name) function`
 3. `Edit greet.py to add a docstring to the function`
 4. `Read greet.py to verify the edit worked`
+
+## 如果你开始觉得“工具不只是 handler map”
+
+到这里为止，教学主线先把工具讲成：
+
+- schema
+- handler
+- `tool_result`
+
+这是对的，而且必须先这么学。
+
+但如果你继续把系统做大，很快就会发现工具层还会继续长出：
+
+- 权限环境
+- 当前消息和 app state
+- MCP client
+- 文件读取缓存
+- 通知与 query 跟踪
+
+也就是说，在一个结构更完整的系统里，工具层最后会更像一条“工具控制平面”，而不只是一张分发表。
+
+这层不要抢正文主线。  
+你先把这一章吃透，再继续看：
+
+- [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md)
+
+## 消息规范化
+
+教学版的 `messages` 列表直接发给 API, 所见即所发。但当系统变复杂后 (工具超时、用户取消、压缩替换), 内部消息列表会出现 API 不接受的格式问题。需要在发送前做一次规范化。
+
+### 为什么需要
+
+API 协议有三条硬性约束:
+1. 每个 `tool_use` 块**必须**有匹配的 `tool_result` (通过 `tool_use_id` 关联)
+2. `user` / `assistant` 消息必须**严格交替** (不能连续两条同角色)
+3. 只接受协议定义的字段 (内部元数据会导致 400 错误)
+
+### 实现
+
+```python
+def normalize_messages(messages: list) -> list:
+    """将内部消息列表规范化为 API 可接受的格式。"""
+    normalized = []
+
+    for msg in messages:
+        # Step 1: 剥离内部字段
+        clean = {"role": msg["role"]}
+        if isinstance(msg.get("content"), str):
+            clean["content"] = msg["content"]
+        elif isinstance(msg.get("content"), list):
+            clean["content"] = [
+                {k: v for k, v in block.items()
+                 if k not in ("_internal", "_source", "_timestamp")}
+                for block in msg["content"]
+            ]
+        normalized.append(clean)
+
+    # Step 2: tool_result 配对补齐
+    # 收集所有已有的 tool_result ID
+    existing_results = set()
+    for msg in normalized:
+        if isinstance(msg.get("content"), list):
+            for block in msg["content"]:
+                if block.get("type") == "tool_result":
+                    existing_results.add(block.get("tool_use_id"))
+
+    # 找出缺失配对的 tool_use, 插入占位 result
+    for msg in normalized:
+        if msg["role"] == "assistant" and isinstance(msg.get("content"), list):
+            for block in msg["content"]:
+                if (block.get("type") == "tool_use"
+                        and block.get("id") not in existing_results):
+                    # 在下一条 user 消息中补齐
+                    normalized.append({"role": "user", "content": [{
+                        "type": "tool_result",
+                        "tool_use_id": block["id"],
+                        "content": "(cancelled)",
+                    }]})
+
+    # Step 3: 合并连续同角色消息
+    merged = [normalized[0]] if normalized else []
+    for msg in normalized[1:]:
+        if msg["role"] == merged[-1]["role"]:
+            # 合并内容
+            prev = merged[-1]
+            prev_content = prev["content"] if isinstance(prev["content"], list) \
+                else [{"type": "text", "text": prev["content"]}]
+            curr_content = msg["content"] if isinstance(msg["content"], list) \
+                else [{"type": "text", "text": msg["content"]}]
+            prev["content"] = prev_content + curr_content
+        else:
+            merged.append(msg)
+
+    return merged
+```
+
+在 agent loop 中, 每次 API 调用前运行:
+
+```python
+response = client.messages.create(
+    model=MODEL, system=system,
+    messages=normalize_messages(messages),  # 规范化后再发送
+    tools=TOOLS, max_tokens=8000,
+)
+```
+
+**关键洞察**: `messages` 列表是系统的内部表示, API 看到的是规范化后的副本。两者不是同一个东西。
+
+## 教学边界
+
+这一章最重要的，不是把完整工具运行时一次讲全，而是先讲清 3 个稳定点：
+
+- tool schema 是给模型看的说明
+- handler map 是代码里的分发入口
+- `tool_result` 是结果回流到主循环的统一出口
+
+只要这三点稳住，读者就已经能自己在不改主循环的前提下新增工具。
+
+权限、hook、并发、流式执行、外部工具来源这些后续层次当然重要，但都应该建立在这层最小分发模型之后。
diff --git a/docs/zh/s02a-tool-control-plane.md b/docs/zh/s02a-tool-control-plane.md
new file mode 100644
index 000000000..abd430ed7
--- /dev/null
+++ b/docs/zh/s02a-tool-control-plane.md
@@ -0,0 +1,296 @@
+# s02a: Tool Control Plane (工具控制平面)
+
+> 这篇桥接文档用来回答另一个关键问题：
+>
+> **为什么“工具系统”不只是一个 `tool_name -> handler` 的映射表？**
+
+## 这一篇为什么要存在
+
+`s02` 先教你工具注册和分发，这完全正确。  
+因为如果你一开始连工具调用都没做出来，后面的一切都无从谈起。
+
+但当系统长大以后，工具层会逐渐承载越来越多的责任：
+
+- 权限判断
+- MCP 接入
+- 通知发送
+- subagent / teammate 共享状态
+- file state cache
+- 当前消息和当前会话环境
+- 某些工具专属限制
+
+这时候，“工具层”就已经不是一张函数表了。
+
+它更像一条总线：
+
+**模型通过工具名发出动作意图，系统通过工具控制平面决定这条意图在什么环境里执行。**
+
+## 先解释几个名词
+
+### 什么是工具控制平面
+
+这里的“控制平面”可以继续沿用上一份桥接文档的理解：
+
+> 不直接做业务结果，而是负责协调工具如何执行的一层。
+
+它关心的问题不是“这个工具最后返回了什么”，而是：
+
+- 它在哪执行
+- 它有没有权限
+- 它可不可以访问某些共享状态
+- 它是本地工具还是外部工具
+
+### 什么是执行上下文
+
+执行上下文，就是工具运行时能看到的环境。
+
+例如：
+
+- 当前工作目录
+- 当前 app state
+- 当前消息列表
+- 当前权限模式
+- 当前可用 MCP client
+
+### 什么是能力来源
+
+不是所有工具都来自同一个地方。
+
+系统里常见的能力来源有：
+
+- 本地原生工具
+- MCP 外部工具
+- agent 工具
+- task / worktree / team 这类平台工具
+
+## 最小心智模型
+
+工具系统可以先画成 4 层：
+
+```text
+1. ToolSpec
+   模型看见的工具名字、描述、输入 schema
+
+2. Tool Router
+   根据工具名把请求送去正确的能力来源
+
+3. ToolUseContext
+   工具运行时能访问的共享环境
+
+4. Tool Result Envelope
+   把输出包装回主循环
+```
+
+最重要的升级点在第三层：
+
+**更完整系统的核心，不是 tool table，而是 ToolUseContext。**
+
+## 关键数据结构
+
+### 1. ToolSpec
+
+这还是最基础的结构：
+
+```python
+tool = {
+    "name": "read_file",
+    "description": "Read file contents.",
+    "input_schema": {...},
+}
+```
+
+### 2. ToolDispatchMap
+
+```python
+handlers = {
+    "read_file": read_file,
+    "write_file": write_file,
+    "bash": run_bash,
+}
+```
+
+这依旧需要，但它不是全部。
+
+### 3. ToolUseContext
+
+教学版可以先做一个简化版本：
+
+```python
+tool_use_context = {
+    "tools": handlers,
+    "permission_context": {...},
+    "mcp_clients": {},
+    "messages": [...],
+    "app_state": {...},
+    "notifications": [],
+    "cwd": "...",
+}
+```
+
+这个结构的关键点是：
+
+- 工具不再只拿到“输入参数”
+- 工具还能拿到“共享运行环境”
+
+### 4. ToolResultEnvelope
+
+不要把返回值只想成字符串。
+
+更稳妥的形状是：
+
+```python
+result = {
+    "ok": True,
+    "content": "...",
+    "is_error": False,
+    "attachments": [],
+}
+```
+
+这样后面你才能平滑承接：
+
+- 普通文本结果
+- 结构化结果
+- 错误结果
+- 附件类结果
+
+## 为什么更完整的系统一定会出现 ToolUseContext
+
+想象两个系统。
+
+### 系统 A：只有 dispatch map
+
+```python
+output = handlers[tool_name](**tool_input)
+```
+
+这适合最小 demo。
+
+### 系统 B：有 ToolUseContext
+
+```python
+output = handlers[tool_name](tool_input, tool_use_context)
+```
+
+这个版本才更接近一个真实平台。
+
+因为工具现在不只是“做一个动作”，而是在一个复杂系统里做动作。
+
+例如：
+
+- `bash` 要看权限
+- `mcp__postgres__query` 要找对应 client
+- `agent` 工具要创建子执行环境
+- `task_output` 工具可能要写磁盘并发通知
+
+这些都要求它们共享同一个上下文总线。
+
+## 最小实现
+
+### 第一步：仍然保留 ToolSpec 和 handler
+
+这个主线不要丢。
+
+### 第二步：引入一个统一 context
+
+```python
+class ToolUseContext:
+    def __init__(self):
+        self.handlers = {}
+        self.permission_context = {}
+        self.mcp_clients = {}
+        self.messages = []
+        self.app_state = {}
+        self.notifications = []
+```
+
+### 第三步：让所有 handler 都能看到 context
+
+```python
+def run_tool(tool_name: str, tool_input: dict, ctx: ToolUseContext):
+    handler = ctx.handlers[tool_name]
+    return handler(tool_input, ctx)
+```
+
+### 第四步：在 router 层分不同能力来源
+
+```python
+def route_tool(tool_name: str, tool_input: dict, ctx: ToolUseContext):
+    if tool_name.startswith("mcp__"):
+        return run_mcp_tool(tool_name, tool_input, ctx)
+    return run_native_tool(tool_name, tool_input, ctx)
+```
+
+## 一张应该讲清楚的图
+
+```text
+LLM tool call
+  |
+  v
+Tool Router
+  |
+  +-- native tools ----------> local handlers
+  |
+  +-- mcp tools -------------> mcp client
+  |
+  +-- agent/task/team tools --> platform handlers
+            |
+            v
+       ToolUseContext
+         - permissions
+         - messages
+         - app state
+         - notifications
+         - mcp clients
+```
+
+## 它和 `s02`、`s19` 的关系
+
+- `s02` 先教你工具调用为什么成立
+- 这篇解释更完整的系统里工具层为什么会长成一个控制平面
+- `s19` 再把 MCP 作为外部能力来源接进来
+
+也就是说：
+
+**MCP 不是另一套独立系统，而是 Tool Control Plane 的一个能力来源。**
+
+## 初学者最容易犯的错
+
+### 1. 以为工具上下文只是 `cwd`
+
+不是。
+
+更完整的系统里，工具上下文往往还包含权限、状态、外部连接和通知接口。
+
+### 2. 让每个工具自己去全局变量里找环境
+
+这样工具层会变得非常散。
+
+更清楚的做法，是显式传一个统一 context。
+
+### 3. 把本地工具和 MCP 工具拆成完全不同体系
+
+这会让系统边界越来越乱。
+
+更好的方式是：
+
+- 能力来源不同
+- 但都汇入统一 router 和统一 result envelope
+
+### 4. 把 tool result 永远当成纯字符串
+
+这样后面接附件、错误、结构化信息时会很别扭。
+
+## 教学边界
+
+这篇最重要的，不是把工具层做成一个庞大的企业总线，而是先把下面三层边界讲清：
+
+- tool call 不是直接执行，而是先进入统一调度入口
+- 工具 handler 不应该各自去偷拿环境，而应该共享一份显式 `ToolUseContext`
+- 本地工具、插件工具、MCP 工具可以来源不同，但结果都应该回到统一控制面
+
+类型化上下文、能力注册中心、大结果存储和更细的工具限额，都是你把这条最小控制总线讲稳以后再补的扩展。
+
+## 一句话记住
+
+**最小工具系统靠 dispatch map，更完整的工具系统靠 ToolUseContext 这条控制总线。**
diff --git a/docs/zh/s02b-tool-execution-runtime.md b/docs/zh/s02b-tool-execution-runtime.md
new file mode 100644
index 000000000..fe6eac5ac
--- /dev/null
+++ b/docs/zh/s02b-tool-execution-runtime.md
@@ -0,0 +1,332 @@
+# s02b: Tool Execution Runtime (工具执行运行时)
+
+> 这篇桥接文档解决的不是“工具怎么注册”，而是：
+>
+> **当模型一口气发出多个工具调用时，系统到底按什么规则执行、并发、回写、合并上下文？**
+
+## 这一篇为什么要存在
+
+`s02` 先教你：
+
+- 工具 schema
+- dispatch map
+- tool_result 回流
+
+这完全正确。  
+因为工具调用先得成立，后面才谈得上复杂度。
+
+但系统一旦长大，真正棘手的问题会变成下面这些：
+
+- 多个工具能不能并行执行
+- 哪些工具必须串行
+- 工具执行过程中要不要先发进度消息
+- 并发工具的结果应该按完成顺序回写，还是按原始出现顺序回写
+- 工具执行会不会改共享上下文
+- 多个并发工具如果都要改上下文，最后怎么合并
+
+这些问题已经不是“工具注册”能解释的了。
+
+它们属于更深一层：
+
+**工具执行运行时。**
+
+## 先解释几个名词
+
+### 什么叫工具执行运行时
+
+这里的运行时，不是指编程语言 runtime。
+
+这里说的是：
+
+> 当工具真正开始执行时，系统用什么规则去调度、并发、跟踪和回写这些工具。
+
+### 什么叫 concurrency safe
+
+你可以先把它理解成：
+
+> 这个工具能不能和别的同类工具同时跑，而不会把共享状态搞乱。
+
+例如很多只读工具常常是 concurrency safe：
+
+- `read_file`
+- 某些搜索工具
+- 某些纯查询类 MCP 工具
+
+而很多写操作不是：
+
+- `write_file`
+- `edit_file`
+- 某些会改全局状态的工具
+
+### 什么叫 progress message
+
+有些工具跑得慢，不适合一直静默。
+
+progress message 就是：
+
+> 工具还没结束，但系统先把“它正在做什么”告诉上层。
+
+### 什么叫 context modifier
+
+有些工具执行完不只是返回结果，还会修改共享环境。
+
+例如：
+
+- 更新通知队列
+- 更新 app state
+- 更新“哪些工具正在运行”
+
+这种“对共享上下文的修改动作”，就可以理解成 context modifier。
+
+## 最小心智模型
+
+先不要把工具执行想成：
+
+```text
+tool_use -> handler -> result
+```
+
+更接近真实可扩展系统的理解是：
+
+```text
+tool_use blocks
+  ->
+按执行安全性分批
+  ->
+每批决定串行还是并行
+  ->
+执行过程中可能产出 progress
+  ->
+最终按稳定顺序回写结果
+  ->
+必要时再合并 context modifiers
+```
+
+这里最关键的升级点有两个：
+
+- 并发不是默认全开
+- 上下文修改不是谁先跑完谁先直接乱写
+
+## 关键数据结构
+
+### 1. ToolExecutionBatch
+
+教学版最小可以先用这样一个概念：
+
+```python
+batch = {
+    "is_concurrency_safe": True,
+    "blocks": [tool_use_1, tool_use_2, tool_use_3],
+}
+```
+
+它的意义是：
+
+- 不是每个工具都单独处理
+- 系统会先把工具调用按可否并发分成一批一批
+
+### 2. TrackedTool
+
+如果你准备把执行层做得更稳、更清楚，建议显式跟踪每个工具：
+
+```python
+tracked_tool = {
+    "id": "toolu_01",
+    "name": "read_file",
+    "status": "queued",   # queued / executing / completed / yielded
+    "is_concurrency_safe": True,
+    "pending_progress": [],
+    "results": [],
+    "context_modifiers": [],
+}
+```
+
+这类结构的价值很大。
+
+因为系统终于开始能回答：
+
+- 哪些工具还在排队
+- 哪些已经开始
+- 哪些已经完成
+- 哪些已经先吐出了中间进度
+
+### 3. MessageUpdate
+
+工具执行过程中，不一定只有最终结果。
+
+最小可以先理解成：
+
+```python
+update = {
+    "message": maybe_message,
+    "new_context": current_context,
+}
+```
+
+更完整的执行层里，一个工具执行运行时往往会产出两类更新：
+
+- 要立刻往上游发的消息更新
+- 只影响内部共享环境的 context 更新
+
+### 4. Queued Context Modifiers
+
+这是最容易被忽略、但很关键的一层。
+
+在并发工具批次里，更稳的策略不是“谁先完成谁先改 context”，而是：
+
+> 先把 context modifier 暂存起来，最后按原始工具顺序统一合并。
+
+最小理解方式：
+
+```python
+queued_context_modifiers = {
+    "toolu_01": [modify_ctx_a],
+    "toolu_02": [modify_ctx_b],
+}
+```
+
+## 最小实现
+
+### 第一步：先分清哪些工具能并发
+
+```python
+def is_concurrency_safe(tool_name: str, tool_input: dict) -> bool:
+    return tool_name in {"read_file", "search_files"}
+```
+
+### 第二步：先分批，再执行
+
+```python
+batches = partition_tool_calls(tool_uses)
+
+for batch in batches:
+    if batch["is_concurrency_safe"]:
+        run_concurrently(batch["blocks"])
+    else:
+        run_serially(batch["blocks"])
+```
+
+### 第三步：并发批次先吐进度，再收最终结果
+
+```python
+for update in run_concurrently(...):
+    if update.get("message"):
+        yield update["message"]
+```
+
+### 第四步：context modifier 不要乱序落地
+
+```python
+queued_modifiers = {}
+
+for update in concurrent_updates:
+    if update.get("context_modifier"):
+        queued_modifiers[update["tool_id"]].append(update["context_modifier"])
+
+for tool in original_batch_order:
+    for modifier in queued_modifiers.get(tool["id"], []):
+        context = modifier(context)
+```
+
+这一步是整篇里最容易被低估，但其实最接近真实系统开始长出执行运行时的点之一。
+
+## 一张真正应该建立的图
+
+```text
+tool_use blocks
+  |
+  v
+partition by concurrency safety
+  |
+  +-- read-only / safe batch -----> concurrent execution
+  |                                   |
+  |                                   +-- progress updates
+  |                                   +-- final results
+  |                                   +-- queued context modifiers
+  |
+  +-- exclusive batch ------------> serial execution
+                                      |
+                                      +-- direct result + direct context update
+```
+
+## 为什么这层比“dispatch map”更接近真实系统主脉络
+
+最小 demo 里：
+
+```python
+handlers[tool_name](tool_input)
+```
+
+就够了。
+
+但在更完整系统里，真正复杂的不是“找到 handler”。
+
+真正复杂的是：
+
+- 多工具之间如何共存
+- 哪些能并发
+- 并发时如何保证回写顺序稳定
+- 并发时如何避免共享 context 被抢写
+- 工具报错时是否中止其他工具
+
+所以这层讲的不是边角优化，而是：
+
+> 工具系统从“可调用”升级到“可调度”的关键一步。
+
+## 它和前后章节怎么接
+
+- `s02` 先教你工具为什么能被调用
+- [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md) 讲工具为什么会长成统一控制面
+- 这篇继续讲，工具真的开始运行以后，系统如何调度它们
+- `s07`、`s13`、`s19` 往后都还会继续用到这层心智
+
+尤其是：
+
+- 权限系统会影响工具能不能执行
+- 后台任务会影响工具是否立即结束
+- MCP / plugin 会让工具来源更多、执行形态更复杂
+
+## 初学者最容易犯的错
+
+### 1. 看到多个工具调用，就默认全部并发
+
+这样很容易把共享状态搞乱。
+
+### 2. 只按完成顺序回写结果
+
+如果你完全按“谁先跑完谁先写”，主循环看到的顺序会越来越不稳定。
+
+### 3. 并发工具直接同时改共享 context
+
+这会制造很多很难解释的隐性状态问题。
+
+### 4. 认为 progress message 是“可有可无的 UI 装饰”
+
+它其实会影响：
+
+- 上层何时知道工具还活着
+- 长工具调用期间用户是否困惑
+- streaming 执行体验是否稳定
+
+### 5. 只讲工具 schema，不讲工具调度
+
+这样读者最后只会“注册工具”，却不理解真实 agent 为什么还要长出工具执行运行时。
+
+## 教学边界
+
+这篇最重要的，不是把工具调度层一次讲成一个庞大 runtime，而是先让读者守住三件事：
+
+- 工具调用要先分批，而不是默认看到多个 `tool_use` 就全部并发
+- 并发执行和稳定回写是两件事，不应该混成一个动作
+- 共享 context 的修改最好先排队，再按稳定顺序统一合并
+
+只要这三条边界已经清楚，后面的权限、后台任务和 MCP 接入就都有地方挂。  
+更细的队列模型、取消策略、流式输出协议，都可以放到你把这条最小运行时自己手搓出来以后再补。
+
+## 读完这一篇你应该能说清楚
+
+至少能完整说出这句话：
+
+> 工具系统不只是 `tool_name -> handler`，它还需要一层执行运行时来决定哪些工具并发、哪些串行、结果如何回写、共享上下文如何稳定合并。
+
+如果这句话你已经能稳定说清，那么你对 agent 工具层的理解，就已经比“会注册几个工具”深一大层了。
diff --git a/docs/zh/s03-todo-write.md b/docs/zh/s03-todo-write.md
index e593233a6..f89935294 100644
--- a/docs/zh/s03-todo-write.md
+++ b/docs/zh/s03-todo-write.md
@@ -1,98 +1,325 @@
-# s03: TodoWrite (待办写入)
+# s03: TodoWrite (会话内规划)
 
-`s01 > s02 > [ s03 ] s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
+`s00 > s01 > s02 > [ s03 ] > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
 
-> *"没有计划的 agent 走哪算哪"* -- 先列步骤再动手, 完成率翻倍。
->
-> **Harness 层**: 规划 -- 让模型不偏航, 但不替它画航线。
+> *计划不是替模型思考，而是把“正在做什么”明确写出来。*
 
-## 问题
+## 这一章要解决什么问题
 
-多步任务中, 模型会丢失进度 -- 重复做过的事、跳步、跑偏。对话越长越严重: 工具结果不断填满上下文, 系统提示的影响力逐渐被稀释。一个 10 步重构可能做完 1-3 步就开始即兴发挥, 因为 4-10 步已经被挤出注意力了。
+到了 `s02`，agent 已经会读文件、写文件、跑命令。
 
-## 解决方案
+问题也马上出现了：
 
+- 多步任务容易走一步忘一步
+- 明明已经做过的检查，会重复再做
+- 一口气列出很多步骤后，很快又回到即兴发挥
+
+这是因为模型虽然“能想”，但它的当前注意力始终受上下文影响。  
+如果没有一块**显式、稳定、可反复更新**的计划状态，大任务就很容易漂。
+
+所以这一章要补上的，不是“更强的工具”，而是：
+
+**让 agent 把当前会话里的计划外显出来，并且持续更新。**
+
+## 先解释几个名词
+
+### 什么是会话内规划
+
+这里说的规划，不是长期项目管理，也不是磁盘上的任务系统。
+
+它更像：
+
+> 为了完成当前这次请求，先把接下来几步写出来，并在过程中不断更新。
+
+### 什么是 todo
+
+`todo` 在这一章里只是一个载体。
+
+你不要把它理解成“某个特定产品里的某个工具名”，更应该把它理解成：
+
+> 模型用来写入当前计划的一条入口。
+
+### 什么是 active step
+
+`active step` 可以理解成“当前正在做的那一步”。
+
+教学版里我们用 `in_progress` 表示它。  
+这么做的目的不是形式主义，而是帮助模型维持焦点：
+
+> 同一时间，先把一件事做完，再进入下一件。
+
+### 什么是提醒
+
+提醒不是替模型规划，而是当它连续几轮都忘记更新计划时，轻轻拉它回来。
+
+## 先立清边界：这章不是任务系统
+
+这是这一章最重要的边界。
+
+`s03` 讲的是：
+
+- 当前会话里的轻量计划
+- 用来帮助模型聚焦下一步
+- 可以随任务推进不断改写
+
+它**不是**：
+
+- 持久化任务板
+- 依赖图
+- 多 agent 共用的工作图
+- 后台运行时任务管理
+
+这些会在 `s12-s14` 再系统展开。
+
+如果你现在就把 `s03` 讲成完整任务平台，初学者会很快混淆：
+
+- “当前这一步要做什么”
+- “整个系统长期还有哪些工作项”
+
+## 最小心智模型
+
+把这一章先想成一个很简单的结构：
+
+```text
+用户提出大任务
+   |
+   v
+模型先写一份当前计划
+   |
+   v
+计划状态
+  - [ ] 还没做
+  - [>] 正在做
+  - [x] 已完成
+   |
+   v
+每做完一步，就更新计划
 ```
-+--------+      +-------+      +---------+
-|  User  | ---> |  LLM  | ---> | Tools   |
-| prompt |      |       |      | + todo  |
-+--------+      +---+---+      +----+----+
-                    ^                |
-                    |   tool_result  |
-                    +----------------+
-                          |
-              +-----------+-----------+
-              | TodoManager state     |
-              | [ ] task A            |
-              | [>] task B  <- doing  |
-              | [x] task C            |
-              +-----------------------+
-                          |
-              if rounds_since_todo >= 3:
-                inject <reminder> into tool_result
+
+更具体一点：
+
+```text
+1. 先拆几步
+2. 选一项作为当前 active step
+3. 做完后标记 completed
+4. 把下一项改成 in_progress
+5. 如果好几轮没更新，系统提醒一下
+```
+
+这就是最小版本最该教清楚的部分。
+
+## 关键数据结构
+
+### 1. PlanItem
+
+最小条目可以长这样：
+
+```python
+{
+    "content": "Read the failing test",
+    "status": "pending" | "in_progress" | "completed",
+    "activeForm": "Reading the failing test",
+}
 ```
 
-## 工作原理
+这里的字段分别表示：
 
-1. TodoManager 存储带状态的项目。同一时间只允许一个 `in_progress`。
+- `content`：这一步要做什么
+- `status`：这一步现在处在什么状态
+- `activeForm`：当它正在进行中时，可以用更自然的进行时描述
+
+### 2. PlanningState
+
+除了计划条目本身，还应该有一点最小运行状态：
+
+```python
+{
+    "items": [...],
+    "rounds_since_update": 0,
+}
+```
+
+`rounds_since_update` 的意思很简单：
+
+> 连续多少轮过去了，模型还没有更新这份计划。
+
+### 3. 状态约束
+
+教学版推荐先立一条简单规则：
+
+```text
+同一时间，最多一个 in_progress
+```
+
+这不是宇宙真理。  
+它只是一个非常适合初学者的教学约束：
+
+**强制模型聚焦当前一步。**
+
+## 最小实现
+
+### 第一步：准备一个计划管理器
 
 ```python
 class TodoManager:
-    def update(self, items: list) -> str:
-        validated, in_progress_count = [], 0
-        for item in items:
-            status = item.get("status", "pending")
-            if status == "in_progress":
-                in_progress_count += 1
-            validated.append({"id": item["id"], "text": item["text"],
-                              "status": status})
-        if in_progress_count > 1:
-            raise ValueError("Only one task can be in_progress")
-        self.items = validated
-        return self.render()
+    def __init__(self):
+        self.items = []
+```
+
+### 第二步：允许模型整体更新当前计划
+
+```python
+def update(self, items: list) -> str:
+    validated = []
+    in_progress_count = 0
+
+    for item in items:
+        status = item.get("status", "pending")
+        if status == "in_progress":
+            in_progress_count += 1
+        validated.append({
+            "content": item["content"],
+            "status": status,
+            "activeForm": item.get("activeForm", ""),
+        })
+
+    if in_progress_count > 1:
+        raise ValueError("Only one item can be in_progress")
+
+    self.items = validated
+    return self.render()
+```
+
+教学版让模型“整份重写”当前计划，比做一堆局部增删改更容易理解。
+
+### 第三步：把计划渲染成可读文本
+
+```python
+def render(self) -> str:
+    lines = []
+    for item in self.items:
+        marker = {
+            "pending": "[ ]",
+            "in_progress": "[>]",
+            "completed": "[x]",
+        }[item["status"]]
+        lines.append(f"{marker} {item['content']}")
+    return "\n".join(lines)
 ```
 
-2. `todo` 工具和其他工具一样加入 dispatch map。
+### 第四步：把 `todo` 接成一个工具
 
 ```python
 TOOL_HANDLERS = {
-    # ...base tools...
+    "read_file": run_read,
+    "write_file": run_write,
+    "edit_file": run_edit,
+    "bash": run_bash,
     "todo": lambda **kw: TODO.update(kw["items"]),
 }
 ```
 
-3. nag reminder: 模型连续 3 轮以上不调用 `todo` 时注入提醒。
+### 第五步：如果连续几轮没更新计划，就提醒
 
 ```python
-if rounds_since_todo >= 3 and messages:
-    last = messages[-1]
-    if last["role"] == "user" and isinstance(last.get("content"), list):
-        last["content"].insert(0, {
-            "type": "text",
-            "text": "<reminder>Update your todos.</reminder>",
-        })
+if rounds_since_update >= 3:
+    results.insert(0, {
+        "type": "text",
+        "text": "<reminder>Refresh your plan before continuing.</reminder>",
+    })
 ```
 
-"同时只能有一个 in_progress" 强制顺序聚焦。nag reminder 制造问责压力 -- 你不更新计划, 系统就追着你问。
+这一步的核心意义不是“催促”本身，而是：
+
+> 系统开始把“计划状态是否失活”也看成主循环的一部分。
+
+## 它如何接到主循环里
+
+这一章以后，主循环不再只维护：
 
-## 相对 s02 的变更
+- `messages`
 
-| 组件           | 之前 (s02)       | 之后 (s03)                     |
-|----------------|------------------|--------------------------------|
-| Tools          | 4                | 5 (+todo)                      |
-| 规划           | 无               | 带状态的 TodoManager           |
-| Nag 注入       | 无               | 3 轮后注入 `<reminder>`        |
-| Agent loop     | 简单分发         | + rounds_since_todo 计数器     |
+还开始维护一份额外的会话状态：
 
-## 试一试
+- `PlanningState`
 
-```sh
-cd learn-claude-code
-python agents/s03_todo_write.py
+也就是说，agent loop 现在不只是在“对话”。
+
+它还在维持一块当前工作面板：
+
+```text
+messages          -> 模型看到的历史
+planning state    -> 当前计划的显式外部状态
 ```
 
-试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):
+这就是这一章真正想让你学会的升级：
+
+**把“当前要做什么”从模型脑内，移到系统可观察的状态里。**
+
+## 为什么这章故意不讲成任务图
+
+因为这里的重点是：
+
+- 帮模型聚焦下一步
+- 让当前进度变得外显
+- 给主循环一个“过程性状态”
+
+而不是：
+
+- 任务依赖
+- 长期持久化
+- 多人协作任务板
+- 后台运行槽位
+
+如果你已经开始关心这些问题，说明你快进入：
+
+- [`s12-task-system.md`](./s12-task-system.md)
+- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)
+
+## 初学者最容易犯的错
+
+### 1. 把计划写得过长
+
+计划不是越多越好。
+
+如果一上来列十几步，模型很快就会失去维护意愿。
+
+### 2. 不区分“当前一步”和“未来几步”
+
+如果同时有很多个 `in_progress`，焦点就会散。
+
+### 3. 把会话计划当成长期任务系统
+
+这会让 `s03` 和 `s12` 的边界完全混掉。
+
+### 4. 只在开始时写一次计划，后面从不更新
+
+那这份计划就失去价值了。
+
+### 5. 以为 reminder 是可有可无的小装饰
+
+不是。
+
+提醒机制说明了一件很重要的事：
+
+> 主循环不仅要执行动作，还要维护动作过程中的结构化状态。
+
+## 教学边界
+
+这一章讲的是：
+
+**会话里的外显计划状态。**
+
+它还不是后面那种持久任务系统，所以边界要守住：
+
+- 这里的 `todo` 只服务当前会话，不负责跨阶段持久化
+- `{id, text, status}` 这种小结构已经够教会核心模式
+- reminder 直接一点没问题，重点是让模型持续更新计划
+
+这一章真正要让读者看见的是：
+
+**当计划进入结构化状态，而不是散在自然语言里时，agent 的漂移会明显减少。**
+
+## 一句话记住
 
-1. `Refactor the file hello.py: add type hints, docstrings, and a main guard`
-2. `Create a Python package with __init__.py, utils.py, and tests/test_utils.py`
-3. `Review all Python files and fix any style issues`
+**`s03` 的 todo，不是任务平台，而是当前会话里的“外显计划状态”。**
diff --git a/docs/zh/s04-subagent.md b/docs/zh/s04-subagent.md
index 708be1f60..b215a37b6 100644
--- a/docs/zh/s04-subagent.md
+++ b/docs/zh/s04-subagent.md
@@ -1,96 +1,306 @@
-# s04: Subagents (Subagent)
+# s04: Subagents (子智能体)
 
-`s01 > s02 > s03 > [ s04 ] s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
+`s00 > s01 > s02 > s03 > [ s04 ] > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
 
-> *"大任务拆小, 每个小任务干净的上下文"* -- Subagent 用独立 messages[], 不污染主对话。
->
-> **Harness 层**: 上下文隔离 -- 守护模型的思维清晰度。
+> *一个大任务，不一定要塞进一个上下文里做完。*
 
-## 问题
+## 这一章到底要解决什么问题
 
-Agent 工作越久, messages 数组越臃肿。每次读文件、跑命令的输出都永久留在上下文里。"这个项目用什么测试框架?" 可能要读 5 个文件, 但父 Agent 只需要一个词: "pytest。"
+当 agent 连续做很多事时，`messages` 会越来越长。
 
-## 解决方案
+比如用户只问：
 
+> “这个项目用什么测试框架？”
+
+但 agent 可能为了回答这个问题：
+
+- 读了 `pyproject.toml`
+- 读了 `requirements.txt`
+- 搜了 `pytest`
+- 跑了测试命令
+
+真正有价值的最终答案，可能只有一句话：
+
+> “这个项目主要用 `pytest`。”
+
+如果这些中间过程都永久堆在父对话里，后面的问题会越来越难回答，因为上下文被大量局部任务的噪声填满了。
+
+这就是子智能体要解决的问题：
+
+**把局部任务放进独立上下文里做，做完只把必要结果带回来。**
+
+## 先解释几个名词
+
+### 什么是“父智能体”
+
+当前正在和用户对话、持有主 `messages` 的 agent，就是父智能体。
+
+### 什么是“子智能体”
+
+父智能体临时派生出来，专门处理某个子任务的 agent，就是子智能体。
+
+### 什么叫“上下文隔离”
+
+意思是：
+
+- 父智能体有自己的 `messages`
+- 子智能体也有自己的 `messages`
+- 子智能体的中间过程不会自动写回父智能体
+
+## 最小心智模型
+
+```text
+Parent agent
+  |
+  | 1. 决定把一个局部任务外包出去
+  v
+Subagent
+  |
+  | 2. 在自己的上下文里读文件 / 搜索 / 执行工具
+  v
+Summary
+  |
+  | 3. 只把最终摘要或结果带回父智能体
+  v
+Parent agent continues
 ```
-Parent agent                     Subagent
-+------------------+             +------------------+
-| messages=[...]   |             | messages=[]      | <-- fresh
-|                  |  dispatch   |                  |
-| tool: task       | ----------> | while tool_use:  |
-|   prompt="..."   |             |   call tools     |
-|                  |  summary    |   append results |
-|   result = "..." | <---------- | return last text |
-+------------------+             +------------------+
-
-Parent context stays clean. Subagent context is discarded.
-```
 
-## 工作原理
+最重要的点只有一个：
+
+**子智能体的价值，不是“多一个模型实例”本身，而是“多一个干净上下文”。**
+
+## 最小实现长什么样
 
-1. 父 Agent 有一个 `task` 工具。Subagent 拥有除 `task` 外的所有基础工具 (禁止递归生成)。
+### 第一步：给父智能体一个 `task` 工具
+
+父智能体需要一个工具，让模型可以主动说：
+
+> “这个子任务我想交给一个独立上下文去做。”
+
+最小 schema 可以非常简单：
 
 ```python
-PARENT_TOOLS = CHILD_TOOLS + [
-    {"name": "task",
-     "description": "Spawn a subagent with fresh context.",
-     "input_schema": {
-         "type": "object",
-         "properties": {"prompt": {"type": "string"}},
-         "required": ["prompt"],
-     }},
-]
+{
+    "name": "task",
+    "description": "Run a subtask in a clean context and return a summary.",
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "prompt": {"type": "string"}
+        },
+        "required": ["prompt"]
+    }
+}
 ```
 
-2. Subagent 以 `messages=[]` 启动, 运行自己的循环。只有最终文本返回给父 Agent。
+### 第二步：子智能体使用自己的消息列表
 
 ```python
 def run_subagent(prompt: str) -> str:
     sub_messages = [{"role": "user", "content": prompt}]
-    for _ in range(30):  # safety limit
-        response = client.messages.create(
-            model=MODEL, system=SUBAGENT_SYSTEM,
-            messages=sub_messages,
-            tools=CHILD_TOOLS, max_tokens=8000,
-        )
-        sub_messages.append({"role": "assistant",
-                             "content": response.content})
-        if response.stop_reason != "tool_use":
-            break
-        results = []
-        for block in response.content:
-            if block.type == "tool_use":
-                handler = TOOL_HANDLERS.get(block.name)
-                output = handler(**block.input)
-                results.append({"type": "tool_result",
-                    "tool_use_id": block.id,
-                    "content": str(output)[:50000]})
-        sub_messages.append({"role": "user", "content": results})
-    return "".join(
-        b.text for b in response.content if hasattr(b, "text")
-    ) or "(no summary)"
+    ...
 ```
 
-Subagent 可能跑了 30+ 次工具调用, 但整个消息历史直接丢弃。父 Agent 收到的只是一段摘要文本, 作为普通 `tool_result` 返回。
+这就是隔离的关键。
+
+不是共享父智能体的 `messages`，而是从一份新的列表开始。
+
+### 第三步：子智能体只拿必要工具
+
+子智能体通常不需要拥有和父智能体完全一样的能力。
+
+最小版本里，常见做法是：
+
+- 给它文件读取、搜索、bash 之类的基础工具
+- 不给它继续派生子智能体的能力
+
+这样可以防止它无限递归。
+
+### 第四步：只把结果带回父智能体
+
+子智能体做完事后，不把全部内部历史写回去，而是返回一段总结。
+
+```python
+return {
+    "type": "tool_result",
+    "tool_use_id": block.id,
+    "content": summary_text,
+}
+```
+
+## 这一章最关键的数据结构
+
+如果你只记一个结构，就记这个：
+
+```python
+class SubagentContext:
+    messages: list
+    tools: list
+    handlers: dict
+    max_turns: int
+```
+
+解释一下：
+
+- `messages`：子智能体自己的上下文
+- `tools`：子智能体可以调用哪些工具
+- `handlers`：这些工具到底对应哪些 Python 函数
+- `max_turns`：防止子智能体无限跑
+
+这就是最小子智能体的骨架。
+
+## 为什么它真的有用
+
+### 用处 1：给父上下文减负
+
+局部任务的中间噪声不会全都留在主对话里。
+
+### 用处 2：让任务描述更清楚
+
+一个子智能体接到的 prompt 可以非常聚焦：
+
+- “读完这几个文件，给我一句总结”
+- “检查这个目录里有没有测试”
+- “对这个函数写一个最小修复”
+
+### 用处 3：让后面的多 agent 协作有基础
+
+你可以把子智能体理解成多 agent 系统的最小起点。
+
+先把一次性子任务外包做明白，后面再升级到长期 teammate、任务认领、团队协议，会顺很多。
 
-## 相对 s03 的变更
+## 从 0 到 1 的实现顺序
 
-| 组件           | 之前 (s03)       | 之后 (s04)                    |
-|----------------|------------------|-------------------------------|
-| Tools          | 5                | 5 (基础) + task (仅父端)      |
-| 上下文         | 单一共享         | 父 + 子隔离                   |
-| Subagent       | 无               | `run_subagent()` 函数         |
-| 返回值         | 不适用           | 仅摘要文本                    |
+推荐按这个顺序写：
 
-## 试一试
+### 版本 1：空白上下文子智能体
 
-```sh
-cd learn-claude-code
-python agents/s04_subagent.py
+先只实现：
+
+- 一个 `task` 工具
+- 一个 `run_subagent(prompt)` 函数
+- 子智能体自己的 `messages`
+- 子智能体最后返回摘要
+
+这已经够了。
+
+### 版本 2：限制工具集
+
+给子智能体一个更小、更安全的工具集。
+
+比如：
+
+- 允许 `read_file`
+- 允许 `grep`
+- 允许只读 bash
+- 不允许 `task`
+
+### 版本 3：加入最大轮数和失败保护
+
+至少补两个保护：
+
+- 最多跑多少轮
+- 工具出错时怎么退出
+
+### 版本 4：再考虑 fork
+
+只有当你已经稳定跑通前面三步，才考虑 fork。
+
+## 什么是 fork，为什么它是“下一步”，不是“起步”
+
+前面的最小实现是：
+
+- 子智能体从空白上下文开始
+
+这叫最朴素的子智能体。
+
+但有时一个子任务必须知道父智能体之前在聊什么。
+
+例如：
+
+> “基于我们刚才已经讨论出来的方案，去补测试。”
+
+这时可以用 `fork`：
+
+- 不是从空白 `messages` 开始
+- 而是先复制父智能体的已有上下文，再追加子任务 prompt
+
+```python
+sub_messages = list(parent_messages)
+sub_messages.append({"role": "user", "content": prompt})
 ```
 
-试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):
+这就是 fork 的本质：
+
+**继承上下文，而不是重头开始。**
+
+## 初学者最容易踩的坑
+
+### 坑 1：把子智能体当成“为了炫技的并发”
+
+子智能体首先是为了解决上下文问题，不是为了展示“我有很多 agent”。
+
+### 坑 2：把父历史全部原样灌回去
+
+如果你最后又把子智能体全量历史粘回父对话，那隔离价值就几乎没了。
+
+### 坑 3：一上来就做特别复杂的角色系统
+
+比如一开始就加：
+
+- explorer
+- reviewer
+- planner
+- tester
+- implementer
+
+这些都可以做，但不应该先做。
+
+先把“一个干净上下文的子任务执行器”做对，后面角色化只是在它上面再包一层。
+
+### 坑 4：忘记给子智能体设置停止条件
+
+如果没有：
+
+- 最大轮数
+- 异常处理
+- 工具过滤
+
+子智能体很容易无限转。
+
+## 教学边界
+
+这章要先打牢的，不是“多 agent 很高级”，而是：
+
+**子智能体首先是一个上下文边界。**
+
+所以教学版先停在这里就够了：
+
+- 一次性子任务就够
+- 摘要返回就够
+- 新 `messages` + 工具过滤就够
+
+不要提前把 `fork`、后台运行、transcript 持久化、worktree 绑定一起塞进来。
+
+真正该守住的顺序仍然是：
+
+**先做隔离，再做高级化。**
+
+## 和后续章节的关系
+
+- `s04` 解决的是“局部任务的上下文隔离”
+- `s15-s17` 解决的是“多个长期角色如何协作”
+- `s18` 解决的是“多个执行者如何在文件系统层面隔离”
+
+它们不是重复关系，而是递进关系。
+
+## 这一章学完后，你应该能回答
+
+- 为什么大任务不应该总塞在一个 `messages` 里？
+- 子智能体最小版为什么只需要独立上下文和摘要返回？
+- fork 是什么，为什么它不该成为第一步？
+- 为什么子智能体的第一价值是“减噪”，而不是“炫多 agent”？
+
+---
 
-1. `Use a subtask to find what testing framework this project uses`
-2. `Delegate: read all .py files and summarize what each one does`
-3. `Use a task to create a new module, then verify it from here`
+**一句话记住：子智能体的核心，不是多一个角色，而是多一个干净上下文。**
diff --git a/docs/zh/s05-skill-loading.md b/docs/zh/s05-skill-loading.md
index 29790d4bd..726ea29bd 100644
--- a/docs/zh/s05-skill-loading.md
+++ b/docs/zh/s05-skill-loading.md
@@ -1,110 +1,309 @@
-# s05: Skills (Skill 加载)
+# s05: Skills (按需知识加载)
 
-`s01 > s02 > s03 > s04 > [ s05 ] s06 | s07 > s08 > s09 > s10 > s11 > s12`
+`s00 > s01 > s02 > s03 > s04 > [ s05 ] > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
 
-> *"用到什么知识, 临时加载什么知识"* -- 通过 tool_result 注入, 不塞 system prompt。
->
-> **Harness 层**: 按需知识 -- 模型开口要时才给的领域专长。
+> *不是把所有知识永远塞进 prompt，而是在需要的时候再加载正确那一份。*
 
-## 问题
+## 这一章要解决什么问题
 
-你希望 Agent 遵循特定领域的工作流: git 约定、测试模式、代码审查清单。全塞进系统提示太浪费 -- 10 个 Skill, 每个 2000 token, 就是 20,000 token, 大部分跟当前任务毫无关系。
+到了 `s04`，你的 agent 已经会：
 
-## 解决方案
+- 调工具
+- 做会话内规划
+- 把大任务分给子 agent
 
+接下来很自然会遇到另一个问题：
+
+> 不同任务需要的领域知识不一样。
+
+例如：
+
+- 做代码审查，需要一套审查清单
+- 做 Git 操作，需要一套提交约定
+- 做 MCP 集成，需要一套专门步骤
+
+如果你把这些知识包全部塞进 system prompt，就会出现两个问题：
+
+1. 大部分 token 都浪费在当前用不到的说明上
+2. prompt 越来越臃肿，主线规则越来越不清楚
+
+所以这一章真正要做的是：
+
+**把“长期可选知识”从 system prompt 主体里拆出来，改成按需加载。**
+
+## 先解释几个名词
+
+### 什么是 skill
+
+这里的 `skill` 可以先简单理解成：
+
+> 一份围绕某类任务的可复用说明书。
+
+它通常会告诉 agent：
+
+- 什么时候该用它
+- 做这类任务时有哪些步骤
+- 有哪些注意事项
+
+### 什么是 discovery
+
+`discovery` 指“发现有哪些 skill 可用”。
+
+这一层只需要很轻量的信息，例如：
+
+- skill 名字
+- 一句描述
+
+### 什么是 loading
+
+`loading` 指“把某个 skill 的完整正文真正读进来”。
+
+这一层才是昂贵的，因为它会把完整内容放进当前上下文。
+
+## 最小心智模型
+
+把这一章先理解成两层：
+
+```text
+第 1 层：轻量目录
+  - skill 名称
+  - skill 描述
+  - 让模型知道“有哪些可用”
+
+第 2 层：按需正文
+  - 只有模型真正需要时才加载
+  - 通过工具结果注入当前上下文
 ```
-System prompt (Layer 1 -- always present):
-+--------------------------------------+
-| You are a coding agent.              |
-| Skills available:                    |
-|   - git: Git workflow helpers        |  ~100 tokens/skill
-|   - test: Testing best practices     |
-+--------------------------------------+
-
-When model calls load_skill("git"):
-+--------------------------------------+
-| tool_result (Layer 2 -- on demand):  |
-| <skill name="git">                   |
-|   Full git workflow instructions...  |  ~2000 tokens
-|   Step 1: ...                        |
-| </skill>                             |
-+--------------------------------------+
+
+可以画成这样：
+
+```text
+system prompt
+  |
+  +-- Skills available:
+      - code-review: review checklist
+      - git-workflow: branch and commit guidance
+      - mcp-builder: build an MCP server
+```
+
+当模型判断自己需要某份知识时：
+
+```text
+load_skill("code-review")
+   |
+   v
+tool_result
+   |
+   v
+<skill name="code-review">
+完整审查说明
+</skill>
+```
+
+这就是这一章最核心的设计。
+
+## 关键数据结构
+
+### 1. SkillManifest
+
+先准备一份很轻的元信息：
+
+```python
+{
+    "name": "code-review",
+    "description": "Checklist for reviewing code changes",
+}
 ```
 
-第一层: 系统提示中放 Skill 名称 (低成本)。第二层: tool_result 中按需放完整内容。
+它的作用只是让模型知道：
 
-## 工作原理
+> 这份 skill 存在，并且大概是干什么的。
 
-1. 每个 Skill 是一个目录, 包含 `SKILL.md` 文件和 YAML frontmatter。
+### 2. SkillDocument
 
+真正被加载时，再读取完整内容：
+
+```python
+{
+    "manifest": {...},
+    "body": "... full skill text ...",
+}
+```
+
+### 3. SkillRegistry
+
+你最好不要把 skill 散着读取。
+
+更清楚的方式是做一个统一注册表：
+
+```python
+registry = {
+    "code-review": SkillDocument(...),
+    "git-workflow": SkillDocument(...),
+}
 ```
+
+它至少要能回答两个问题：
+
+1. 有哪些 skill 可用
+2. 某个 skill 的完整内容是什么
+
+## 最小实现
+
+### 第一步：把每个 skill 放成一个目录
+
+最小结构可以这样：
+
+```text
 skills/
-  pdf/
-    SKILL.md       # ---\n name: pdf\n description: Process PDF files\n ---\n ...
   code-review/
-    SKILL.md       # ---\n name: code-review\n description: Review code\n ---\n ...
+    SKILL.md
+  git-workflow/
+    SKILL.md
 ```
 
-2. SkillLoader 递归扫描 `SKILL.md` 文件, 用目录名作为 Skill 标识。
+### 第二步：从 `SKILL.md` 里读取最小元信息
 
 ```python
-class SkillLoader:
-    def __init__(self, skills_dir: Path):
+class SkillRegistry:
+    def __init__(self, skills_dir):
         self.skills = {}
-        for f in sorted(skills_dir.rglob("SKILL.md")):
-            text = f.read_text()
-            meta, body = self._parse_frontmatter(text)
-            name = meta.get("name", f.parent.name)
-            self.skills[name] = {"meta": meta, "body": body}
-
-    def get_descriptions(self) -> str:
-        lines = []
-        for name, skill in self.skills.items():
-            desc = skill["meta"].get("description", "")
-            lines.append(f"  - {name}: {desc}")
-        return "\n".join(lines)
-
-    def get_content(self, name: str) -> str:
-        skill = self.skills.get(name)
-        if not skill:
-            return f"Error: Unknown skill '{name}'."
-        return f"<skill name=\"{name}\">\n{skill['body']}\n</skill>"
+        self._load_all()
+
+    def _load_all(self):
+        for path in skills_dir.rglob("SKILL.md"):
+            meta, body = parse_frontmatter(path.read_text())
+            name = meta.get("name", path.parent.name)
+            self.skills[name] = {
+                "manifest": {
+                    "name": name,
+                    "description": meta.get("description", ""),
+                },
+                "body": body,
+            }
 ```
 
-3. 第一层写入系统提示。第二层不过是 dispatch map 中的又一个工具。
+这里的 `frontmatter` 你可以先简单理解成：
+
+> 放在正文前面的一小段结构化元数据。
+
+### 第三步：把 skill 目录放进 system prompt
 
 ```python
-SYSTEM = f"""You are a coding agent at {WORKDIR}.
+SYSTEM = f"""You are a coding agent.
 Skills available:
-{SKILL_LOADER.get_descriptions()}"""
+{SKILL_REGISTRY.describe_available()}
+"""
+```
+
+注意这里放的是**目录信息**，不是完整正文。
 
+### 第四步：提供一个 `load_skill` 工具
+
+```python
 TOOL_HANDLERS = {
-    # ...base tools...
-    "load_skill": lambda **kw: SKILL_LOADER.get_content(kw["name"]),
+    "load_skill": lambda **kw: SKILL_REGISTRY.load_full_text(kw["name"]),
 }
 ```
 
-模型知道有哪些 Skill (便宜), 需要时再加载完整内容 (贵)。
+当模型调用它时，把完整 skill 正文作为 `tool_result` 返回。
+
+### 第五步：让 skill 正文只在当前需要时进入上下文
+
+这一步的核心思想就是：
+
+> 平时只展示“有哪些知识包”，真正工作时才把那一包展开。
+
+## skill、memory、CLAUDE.md 的边界
+
+这三个概念很容易混。
+
+### skill
+
+可选知识包。  
+只有在某类任务需要时才加载。
+
+### memory
+
+跨会话仍然有价值的信息。  
+它是系统记住的东西，不是任务手册。
+
+### CLAUDE.md
+
+更稳定、更长期的规则说明。  
+它通常比单个 skill 更“全局”。
+
+一个简单判断法：
+
+- 这是某类任务才需要的做法或知识：`skill`
+- 这是需要长期记住的事实或偏好：`memory`
+- 这是更稳定的全局规则：`CLAUDE.md`
 
-## 相对 s04 的变更
+## 它如何接到主循环里
 
-| 组件           | 之前 (s04)       | 之后 (s05)                     |
-|----------------|------------------|--------------------------------|
-| Tools          | 5 (基础 + task)  | 5 (基础 + load_skill)          |
-| 系统提示       | 静态字符串       | + Skill 描述列表               |
-| 知识库         | 无               | skills/\*/SKILL.md 文件        |
-| 注入方式       | 无               | 两层 (系统提示 + result)       |
+这一章以后，system prompt 不再只是一段固定身份说明。
 
-## 试一试
+它开始长出一个很重要的新段落：
 
-```sh
-cd learn-claude-code
-python agents/s05_skill_loading.py
+- 可用技能目录
+
+而消息流里则会出现新的按需注入内容：
+
+- 某个 skill 的完整正文
+
+也就是说，系统输入现在开始分成两层：
+
+```text
+稳定层：
+  身份、规则、工具、skill 目录
+
+按需层：
+  当前真的加载进来的 skill 正文
 ```
 
-试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):
+这也是 `s10` 会继续系统化展开的东西。
+
+## 初学者最容易犯的错
+
+### 1. 把所有 skill 正文永远塞进 system prompt
+
+这样会让 prompt 很快臃肿到难以维护。
+
+### 2. skill 目录信息写得太弱
+
+如果只有名字，没有描述，模型就不知道什么时候该加载它。
+
+### 3. 把 skill 当成“绝对规则”
+
+skill 更像“可选工作手册”，不是所有轮次都必须用。
+
+### 4. 把 skill 和 memory 混成一类
+
+skill 解决的是“怎么做一类事”，memory 解决的是“记住长期事实”。
+
+### 5. 一上来就讲太多多源加载细节
+
+教学主线真正要先讲清的是：
+
+**轻量发现，重内容按需加载。**
+
+## 教学边界
+
+这章只要先守住两层就够了：
+
+- 轻量发现：先告诉模型有哪些 skill
+- 按需深加载：真正需要时再把正文放进输入
+
+所以这里不用提前扩到：
+
+- 多来源收集
+- 条件激活
+- skill 参数化
+- fork 式执行
+- 更复杂的 prompt 管道拼装
+
+如果读者已经明白“为什么不能把所有 skill 永远塞进 system prompt，而应该先列目录、再按需加载”，这章就已经讲到位了。
+
+## 一句话记住
 
-1. `What skills are available?`
-2. `Load the agent-builder skill and follow its instructions`
-3. `I need to do a code review -- load the relevant skill first`
-4. `Build an MCP server using the mcp-builder skill`
+**Skill 系统的核心，不是“多一个工具”，而是“把可选知识从常驻 prompt 里拆出来，改成按需加载”。**
diff --git a/docs/zh/s06-context-compact.md b/docs/zh/s06-context-compact.md
index 40108e2ed..95bb1f1ec 100644
--- a/docs/zh/s06-context-compact.md
+++ b/docs/zh/s06-context-compact.md
@@ -1,126 +1,330 @@
 # s06: Context Compact (上下文压缩)
 
-`s01 > s02 > s03 > s04 > s05 > [ s06 ] | s07 > s08 > s09 > s10 > s11 > s12`
+`s00 > s01 > s02 > s03 > s04 > s05 > [ s06 ] > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
 
-> *"上下文总会满, 要有办法腾地方"* -- 三层压缩策略, 换来无限会话。
->
-> **Harness 层**: 压缩 -- 干净的记忆, 无限的会话。
+> *上下文不是越多越好，而是要把“仍然有用的部分”留在活跃工作面里。*
 
-## 问题
+## 这一章要解决什么问题
 
-上下文窗口是有限的。读一个 1000 行的文件就吃掉 ~4000 token; 读 30 个文件、跑 20 条命令, 轻松突破 100k token。不压缩, Agent 根本没法在大项目里干活。
+到了 `s05`，agent 已经会：
 
-## 解决方案
+- 读写文件
+- 规划步骤
+- 派子 agent
+- 按需加载 skill
 
-三层压缩, 激进程度递增:
+也正因为它会做的事情更多了，上下文会越来越快膨胀：
 
+- 读一个大文件，会塞进很多文本
+- 跑一条长命令，会得到大段输出
+- 多轮任务推进后，旧结果会越来越多
+
+如果没有压缩机制，很快就会出现这些问题：
+
+1. 模型注意力被旧结果淹没
+2. API 请求越来越重，越来越贵
+3. 最终直接撞上上下文上限，任务中断
+
+所以这一章真正要解决的是：
+
+**怎样在不丢掉主线连续性的前提下，把活跃上下文重新腾出空间。**
+
+## 先解释几个名词
+
+### 什么是上下文窗口
+
+你可以把上下文窗口理解成：
+
+> 模型这一轮真正能一起看到的输入容量。
+
+它不是无限的。
+
+### 什么是活跃上下文
+
+并不是历史上出现过的所有内容，都必须一直留在窗口里。
+
+活跃上下文更像：
+
+> 当前这几轮继续工作时，最值得模型马上看到的那一部分。
+
+### 什么是压缩
+
+这里的压缩，不是 ZIP 压缩文件。
+
+它的意思是：
+
+> 用更短的表示方式，保留继续工作真正需要的信息。
+
+例如：
+
+- 大输出只保留预览，全文写到磁盘
+- 很久以前的工具结果改成占位提示
+- 整段长历史总结成一份摘要
+
+## 最小心智模型
+
+这一章建议你先记三层，不要一上来记八层十层：
+
+```text
+第 1 层：大结果不直接塞进上下文
+  -> 写到磁盘，只留预览
+
+第 2 层：旧结果不一直原样保留
+  -> 替换成简短占位
+
+第 3 层：整体历史太长时
+  -> 生成一份连续性摘要
+```
+
+可以画成这样：
+
+```text
+tool output
+   |
+   +-- 太大 -----------------> 保存到磁盘 + 留预览
+   |
+   v
+messages
+   |
+   +-- 太旧 -----------------> 替换成占位提示
+   |
+   v
+if whole context still too large:
+   |
+   v
+compact history -> summary
 ```
-Every turn:
-+------------------+
-| Tool call result |
-+------------------+
-        |
-        v
-[Layer 1: micro_compact]        (silent, every turn)
-  Replace tool_result > 3 turns old
-  with "[Previous: used {tool_name}]"
-        |
-        v
-[Check: tokens > 50000?]
-   |               |
-   no              yes
-   |               |
-   v               v
-continue    [Layer 2: auto_compact]
-              Save transcript to .transcripts/
-              LLM summarizes conversation.
-              Replace all messages with [summary].
-                    |
-                    v
-            [Layer 3: compact tool]
-              Model calls compact explicitly.
-              Same summarization as auto_compact.
+
+手动触发 `/compact` 或 `compact` 工具，本质上也是走第 3 层。
+
+## 关键数据结构
+
+### 1. Persisted Output Marker
+
+当工具输出太大时，不要把全文强塞进当前对话。
+
+最小标记可以长这样：
+
+```text
+<persisted-output>
+Full output saved to: .task_outputs/tool-results/abc123.txt
+Preview:
+...
+</persisted-output>
+```
+
+这个结构表达的是：
+
+- 全文没有丢
+- 只是搬去了磁盘
+- 当前上下文里只保留一个足够让模型继续判断的预览
+
+### 2. CompactState
+
+最小教学版建议你显式维护一份压缩状态：
+
+```python
+{
+    "has_compacted": False,
+    "last_summary": "",
+    "recent_files": [],
+}
+```
+
+这里的字段分别表示：
+
+- `has_compacted`：这一轮之前是否已经做过完整压缩
+- `last_summary`：最近一次压缩得到的摘要
+- `recent_files`：最近碰过哪些文件，压缩后方便继续追踪
+
+### 3. Micro-Compact Boundary
+
+教学版可以先设一条简单规则：
+
+```text
+只保留最近 3 个工具结果的完整内容
+更旧的改成占位提示
+```
+
+这就已经足够让初学者理解：
+
+**不是所有历史都要原封不动地一直带着跑。**
+
+## 最小实现
+
+### 第一步：大工具结果先写磁盘
+
+```python
+def persist_large_output(tool_use_id: str, output: str) -> str:
+    if len(output) <= PERSIST_THRESHOLD:
+        return output
+
+    stored_path = save_to_disk(tool_use_id, output)
+    preview = output[:2000]
+    return (
+        "<persisted-output>\n"
+        f"Full output saved to: {stored_path}\n"
+        f"Preview:\n{preview}\n"
+        "</persisted-output>"
+    )
 ```
 
-## 工作原理
+这一步的关键思想是：
+
+> 让模型知道“发生了什么”，但不强迫它一直背着整份原始大输出。
 
-1. **第一层 -- micro_compact**: 每次 LLM 调用前, 将旧的 tool result 替换为占位符。
+### 第二步：旧工具结果做微压缩
 
 ```python
 def micro_compact(messages: list) -> list:
-    tool_results = []
-    for i, msg in enumerate(messages):
-        if msg["role"] == "user" and isinstance(msg.get("content"), list):
-            for j, part in enumerate(msg["content"]):
-                if isinstance(part, dict) and part.get("type") == "tool_result":
-                    tool_results.append((i, j, part))
-    if len(tool_results) <= KEEP_RECENT:
-        return messages
-    for _, _, part in tool_results[:-KEEP_RECENT]:
-        if len(part.get("content", "")) > 100:
-            part["content"] = f"[Previous: used {tool_name}]"
+    tool_results = collect_tool_results(messages)
+    for result in tool_results[:-3]:
+        result["content"] = "[Earlier tool result omitted for brevity]"
     return messages
 ```
 
-2. **第二层 -- auto_compact**: token 超过阈值时, 保存完整对话到磁盘, 让 LLM 做摘要。
+这一步不是为了优雅，而是为了防止上下文被旧结果持续霸占。
+
+### 第三步：整体历史过长时，做一次完整压缩
 
 ```python
-def auto_compact(messages: list) -> list:
-    # Save transcript for recovery
-    transcript_path = TRANSCRIPT_DIR / f"transcript_{int(time.time())}.jsonl"
-    with open(transcript_path, "w") as f:
-        for msg in messages:
-            f.write(json.dumps(msg, default=str) + "\n")
-    # LLM summarizes
-    response = client.messages.create(
-        model=MODEL,
-        messages=[{"role": "user", "content":
-            "Summarize this conversation for continuity..."
-            + json.dumps(messages, default=str)[:80000]}],
-        max_tokens=2000,
-    )
-    return [
-        {"role": "user", "content": f"[Compressed]\n\n{response.content[0].text}"},
-    ]
+def compact_history(messages: list) -> list:
+    summary = summarize_conversation(messages)
+    return [{
+        "role": "user",
+        "content": (
+            "This conversation was compacted for continuity.\n\n"
+            + summary
+        ),
+    }]
 ```
 
-3. **第三层 -- manual compact**: `compact` 工具按需触发同样的摘要机制。
+这里最重要的不是摘要格式多么复杂，而是你要保住这几类信息：
+
+- 当前目标是什么
+- 已经做了什么
+- 改过哪些文件
+- 还有什么没完成
+- 哪些决定不能丢
 
-4. 循环整合三层:
+### 第四步：在主循环里接入压缩
 
 ```python
-def agent_loop(messages: list):
+def agent_loop(state):
     while True:
-        micro_compact(messages)                        # Layer 1
-        if estimate_tokens(messages) > THRESHOLD:
-            messages[:] = auto_compact(messages)       # Layer 2
-        response = client.messages.create(...)
-        # ... tool execution ...
-        if manual_compact:
-            messages[:] = auto_compact(messages)       # Layer 3
+        state["messages"] = micro_compact(state["messages"])
+
+        if estimate_context_size(state["messages"]) > CONTEXT_LIMIT:
+            state["messages"] = compact_history(state["messages"])
+            state["has_compacted"] = True
+
+        response = call_model(...)
+        ...
 ```
 
-完整历史通过 transcript 保存在磁盘上。信息没有真正丢失, 只是移出了活跃上下文。
+### 第五步：手动压缩和自动压缩复用同一条机制
+
+教学版里，`compact` 工具不需要重新发明另一套逻辑。
+
+它只需要表达：
+
+> 用户或模型现在主动要求执行一次完整压缩。
+
+## 压缩后，真正要保住什么
+
+这是这章最容易讲虚的地方。
+
+压缩不是“把历史缩短”这么简单。
+
+真正重要的是：
+
+**让模型还能继续接着干活。**
+
+所以一份合格的压缩结果，至少要保住下面这些东西：
+
+1. 当前任务目标
+2. 已完成的关键动作
+3. 已修改或重点查看过的文件
+4. 关键决定与约束
+5. 下一步应该做什么
+
+如果这些没有保住，那压缩虽然腾出了空间，却打断了工作连续性。
+
+## 它如何接到主循环里
+
+从这一章开始，主循环不再只是：
+
+- 收消息
+- 调模型
+- 跑工具
 
-## 相对 s05 的变更
+它还多了一个很关键的责任：
 
-| 组件           | 之前 (s05)       | 之后 (s06)                     |
-|----------------|------------------|--------------------------------|
-| Tools          | 5                | 5 (基础 + compact)             |
-| 上下文管理     | 无               | 三层压缩                       |
-| Micro-compact  | 无               | 旧结果 -> 占位符               |
-| Auto-compact   | 无               | token 阈值触发                 |
-| Transcripts    | 无               | 保存到 .transcripts/           |
+- 管理活跃上下文的预算
 
-## 试一试
+也就是说，agent loop 现在开始同时维护两件事：
 
-```sh
-cd learn-claude-code
-python agents/s06_context_compact.py
+```text
+任务推进
+上下文预算
 ```
 
-试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):
+这一步非常重要，因为后面的很多机制都会和它联动：
+
+- `s09` memory 决定什么信息值得长期保存
+- `s10` prompt pipeline 决定哪些块应该重新注入
+- `s11` error recovery 会处理压缩不足时的恢复分支
+
+## 初学者最容易犯的错
+
+### 1. 以为压缩等于删除
+
+不是。
+
+更准确地说，是把“不必常驻活跃上下文”的内容换一种表示。
+
+### 2. 只在撞到上限后才临时乱补
+
+更好的做法是从一开始就有三层思路：
+
+- 大结果先落盘
+- 旧结果先缩短
+- 整体过长再摘要
+
+### 3. 摘要只写成一句空话
+
+如果摘要没有保住文件、决定、下一步，它对继续工作没有帮助。
+
+### 4. 把压缩和 memory 混成一类
+
+压缩解决的是：
+
+- 当前会话太长了怎么办
+
+memory 解决的是：
+
+- 哪些信息跨会话仍然值得保留
+
+### 5. 一上来就给初学者讲过多产品化层级
+
+教学主线先讲清最小正确模型，比堆很多层名词更重要。
+
+## 教学边界
+
+这章不要滑成“所有产品化压缩技巧大全”。
+
+教学版只需要讲清三件事：
+
+1. 什么该留在活跃上下文里
+2. 什么该搬到磁盘或占位标记里
+3. 完整压缩后，哪些连续性信息一定不能丢
+
+这已经足够建立稳定心智：
+
+**压缩不是删历史，而是把细节搬走，好让系统继续工作。**
+
+如果读者已经能用 `persisted output + micro compact + summary compact` 保住长会话连续性，这章就已经够深了。
+
+## 一句话记住
 
-1. `Read every Python file in the agents/ directory one by one` (观察 micro-compact 替换旧结果)
-2. `Keep reading files until compression triggers automatically`
-3. `Use the compact tool to manually compress the conversation`
+**上下文压缩的核心，不是尽量少字，而是让模型在更短的活跃上下文里，仍然保住继续工作的连续性。**
diff --git a/docs/zh/s07-permission-system.md b/docs/zh/s07-permission-system.md
new file mode 100644
index 000000000..dbb97f0d0
--- /dev/null
+++ b/docs/zh/s07-permission-system.md
@@ -0,0 +1,314 @@
+# s07: Permission System (权限系统)
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > [ s07 ] > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
+
+> *模型可以提出行动建议，但真正执行之前，必须先过安全关。*
+
+## 这一章的核心目标
+
+到了 `s06`，你的 agent 已经能读文件、改文件、跑命令、做规划、压缩上下文。
+
+问题也随之出现了：
+
+- 模型可能会写错文件
+- 模型可能会执行危险命令
+- 模型可能会在不该动手的时候动手
+
+所以从这一章开始，系统需要一条新的管道：
+
+**“意图”不能直接变成“执行”，中间必须经过权限检查。**
+
+## 建议联读
+
+- 如果你开始把“模型提议动作”和“系统真的执行动作”混成一件事，先回 [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)，重新确认 query 是怎么进入控制面的。
+- 如果你还没彻底稳住“工具请求为什么不能直接落到 handler”，建议把 [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md) 放在手边一起读。
+- 如果你在 `PermissionRule / PermissionDecision / tool_result` 这几层对象上开始打结，先回 [`data-structures.md`](./data-structures.md)，把状态边界重新拆开。
+
+## 先解释几个名词
+
+### 什么是权限系统
+
+权限系统不是“有没有权限”这样一个布尔值。
+
+它更像一条管道，用来回答：
+
+1. 这次调用要不要直接拒绝？
+2. 能不能自动放行？
+3. 剩下的要不要问用户？
+
+### 什么是权限模式
+
+权限模式是系统当前的总体风格。
+
+例如：
+
+- 谨慎一点：大多数操作都问用户
+- 保守一点：只允许读，不允许写
+- 流畅一点：简单安全的操作自动放行
+
+### 什么是规则
+
+规则就是“遇到某种工具调用时，该怎么处理”的小条款。
+
+最小规则通常包含三部分：
+
+```python
+{
+    "tool": "bash",
+    "content": "sudo *",
+    "behavior": "deny",
+}
+```
+
+意思是：
+
+- 针对 `bash`
+- 如果命令内容匹配 `sudo *`
+- 就拒绝
+
+## 最小权限系统应该长什么样
+
+如果你是从 0 开始手写，一个最小但正确的权限系统只需要四步：
+
+```text
+tool_call
+  |
+  v
+1. deny rules     -> 命中了就拒绝
+  |
+  v
+2. mode check     -> 根据当前模式决定
+  |
+  v
+3. allow rules    -> 命中了就放行
+  |
+  v
+4. ask user       -> 剩下的交给用户确认
+```
+
+这四步已经能覆盖教学仓库 80% 的核心需要。
+
+## 为什么顺序是这样
+
+### 第 1 步先看 deny rules
+
+因为有些东西不应该交给“模式”去决定。
+
+比如：
+
+- 明显危险的命令
+- 明显越界的路径
+
+这些应该优先挡掉。
+
+### 第 2 步看 mode
+
+因为模式决定当前会话的大方向。
+
+例如在 `plan` 模式下，系统就应该天然更保守。
+
+### 第 3 步看 allow rules
+
+有些安全、重复、常见的操作可以直接过。
+
+比如：
+
+- 读文件
+- 搜索代码
+- 查看 git 状态
+
+### 第 4 步才 ask
+
+前面都没命中的灰区，才交给用户。
+
+## 推荐先实现的 3 种模式
+
+不要一上来就做特别多模式。  
+先把下面三种做稳：
+
+| 模式 | 含义 | 适合什么场景 |
+|---|---|---|
+| `default` | 未命中规则时问用户 | 日常交互 |
+| `plan` | 只允许读，不允许写 | 计划、审查、分析 |
+| `auto` | 简单安全操作自动过，危险操作再问 | 高流畅度探索 |
+
+先有这三种，你就已经有了一个可用的权限系统。
+
+## 这一章最重要的数据结构
+
+### 1. 权限规则
+
+```python
+PermissionRule = {
+    "tool": str,
+    "behavior": "allow" | "deny" | "ask",
+    "path": str | None,
+    "content": str | None,
+}
+```
+
+你不一定一开始就需要 `path` 和 `content` 都支持。  
+但规则至少要能表达：
+
+- 针对哪个工具
+- 命中后怎么处理
+
+### 2. 权限模式
+
+```python
+mode = "default" | "plan" | "auto"
+```
+
+### 3. 权限决策结果
+
+```python
+{
+    "behavior": "allow" | "deny" | "ask",
+    "reason": "why this decision was made"
+}
+```
+
+这三个结构已经足够搭起最小系统。
+
+## 最小实现怎么写
+
+```python
+def check_permission(tool_name: str, tool_input: dict) -> dict:
+    # 1. deny rules
+    for rule in deny_rules:
+        if matches(rule, tool_name, tool_input):
+            return {"behavior": "deny", "reason": "matched deny rule"}
+
+    # 2. mode
+    if mode == "plan" and tool_name in WRITE_TOOLS:
+        return {"behavior": "deny", "reason": "plan mode blocks writes"}
+    if mode == "auto" and tool_name in READ_ONLY_TOOLS:
+        return {"behavior": "allow", "reason": "auto mode allows reads"}
+
+    # 3. allow rules
+    for rule in allow_rules:
+        if matches(rule, tool_name, tool_input):
+            return {"behavior": "allow", "reason": "matched allow rule"}
+
+    # 4. fallback
+    return {"behavior": "ask", "reason": "needs confirmation"}
+```
+
+然后在执行工具前接进去：
+
+```python
+decision = perms.check(tool_name, tool_input)
+
+if decision["behavior"] == "deny":
+    return f"Permission denied: {decision['reason']}"
+if decision["behavior"] == "ask":
+    ok = ask_user(...)
+    if not ok:
+        return "Permission denied by user"
+
+return handler(**tool_input)
+```
+
+## Bash 为什么值得单独讲
+
+所有工具里，`bash` 通常最危险。
+
+因为：
+
+- `read_file` 只能读文件
+- `write_file` 只能写文件
+- 但 `bash` 几乎能做任何事
+
+所以你不能只把 bash 当成一个普通字符串。
+
+一个更成熟的系统，通常会把 bash 当成一门小语言来检查。
+
+哪怕教学版不做完整语法分析，也建议至少先挡住这些明显危险点：
+
+- `sudo`
+- `rm -rf`
+- 命令替换
+- 可疑重定向
+- 明显的 shell 元字符拼接
+
+这背后的核心思想只有一句：
+
+**bash 不是普通文本，而是可执行动作描述。**
+
+## 初学者怎么把这章做对
+
+### 第一步：先做 3 个模式
+
+不要一开始就做 6 个模式、10 个来源、复杂 classifier。
+
+先稳稳做出：
+
+- `default`
+- `plan`
+- `auto`
+
+### 第二步：先做 deny / allow 两类规则
+
+这已经足够表达很多现实需求。
+
+### 第三步：给 bash 加最小安全检查
+
+哪怕只是模式匹配版，也比完全裸奔好很多。
+
+### 第四步：加拒绝计数
+
+如果 agent 连续多次被拒绝，说明它可能卡住了。
+
+这时可以：
+
+- 给出提示
+- 建议切到 `plan`
+- 让用户重新澄清目标
+
+## 教学边界
+
+这一章先只讲透一条权限管道就够了：
+
+- 工具意图先进入权限判断
+- 权限结果只分成 `allow / ask / deny`
+- 通过以后才真的执行
+
+先把这条主线做稳，比一开始塞进很多模式名、规则来源、写回配置、额外目录、自动分类器都更重要。
+
+换句话说，这章要先让读者真正理解的是：
+
+**任何工具调用，都不应该直接执行；中间必须先过一条权限管道。**
+
+## 这章不应该讲太多什么
+
+为了不打乱初学者心智，这章不应该过早陷入：
+
+- 企业策略源的全部优先级
+- 非常复杂的自动分类器
+- 产品环境里的所有无头模式细节
+- 某个特定生产代码里的全部 validator 名称
+
+这些东西存在，但不属于第一层理解。
+
+第一层理解只有一句话：
+
+**任何工具调用，都不应该直接执行；中间必须先过一条权限管道。**
+
+## 这一章和后续章节的关系
+
+- `s07` 决定“能不能执行”
+- `s08` 决定“执行前后还能不能插入额外逻辑”
+- `s10` 会把当前模式和权限说明放进 prompt 组装里
+
+所以这章是后面很多机制的安全前提。
+
+## 学完这章后，你应该能回答
+
+- 为什么权限系统不是一个简单开关？
+- 为什么 deny 要先于 allow？
+- 为什么要先做 3 个模式，而不是一上来做很复杂？
+- 为什么 bash 要被特殊对待？
+
+---
+
+**一句话记住：权限系统不是为了让 agent 更笨，而是为了让 agent 的行动先经过一道可靠的安全判断。**
diff --git a/docs/zh/s07-task-system.md b/docs/zh/s07-task-system.md
deleted file mode 100644
index 4b9be120a..000000000
--- a/docs/zh/s07-task-system.md
+++ /dev/null
@@ -1,133 +0,0 @@
-# s07: Task System (任务系统)
-
-`s01 > s02 > s03 > s04 > s05 > s06 | [ s07 ] s08 > s09 > s10 > s11 > s12`
-
-> *"大目标要拆成小任务, 排好序, 记在磁盘上"* -- 文件持久化的任务图, 为多 agent 协作打基础。
->
-> **Harness 层**: 持久化任务 -- 比任何一次对话都长命的目标。
-
-## 问题
-
-s03 的 TodoManager 只是内存中的扁平清单: 没有顺序、没有依赖、状态只有做完没做完。真实目标是有结构的 -- 任务 B 依赖任务 A, 任务 C 和 D 可以并行, 任务 E 要等 C 和 D 都完成。
-
-没有显式的关系, Agent 分不清什么能做、什么被卡住、什么能同时跑。而且清单只活在内存里, 上下文压缩 (s06) 一跑就没了。
-
-## 解决方案
-
-把扁平清单升级为持久化到磁盘的**任务图**。每个任务是一个 JSON 文件, 有状态、前置依赖 (`blockedBy`)。任务图随时回答三个问题:
-
-- **什么可以做?** -- 状态为 `pending` 且 `blockedBy` 为空的任务。
-- **什么被卡住?** -- 等待前置任务完成的任务。
-- **什么做完了?** -- 状态为 `completed` 的任务, 完成时自动解锁后续任务。
-
-```
-.tasks/
-  task_1.json  {"id":1, "status":"completed"}
-  task_2.json  {"id":2, "blockedBy":[1], "status":"pending"}
-  task_3.json  {"id":3, "blockedBy":[1], "status":"pending"}
-  task_4.json  {"id":4, "blockedBy":[2,3], "status":"pending"}
-
-任务图 (DAG):
-                 +----------+
-            +--> | task 2   | --+
-            |    | pending  |   |
-+----------+     +----------+    +--> +----------+
-| task 1   |                          | task 4   |
-| completed| --> +----------+    +--> | blocked  |
-+----------+     | task 3   | --+     +----------+
-                 | pending  |
-                 +----------+
-
-顺序:   task 1 必须先完成, 才能开始 2 和 3
-并行:   task 2 和 3 可以同时执行
-依赖:   task 4 要等 2 和 3 都完成
-状态:   pending -> in_progress -> completed
-```
-
-这个任务图是 s07 之后所有机制的协调骨架: 后台执行 (s08)、多 agent 团队 (s09+)、worktree 隔离 (s12) 都读写这同一个结构。
-
-## 工作原理
-
-1. **TaskManager**: 每个任务一个 JSON 文件, CRUD + 依赖图。
-
-```python
-class TaskManager:
-    def __init__(self, tasks_dir: Path):
-        self.dir = tasks_dir
-        self.dir.mkdir(exist_ok=True)
-        self._next_id = self._max_id() + 1
-
-    def create(self, subject, description=""):
-        task = {"id": self._next_id, "subject": subject,
-                "status": "pending", "blockedBy": [],
-                "owner": ""}
-        self._save(task)
-        self._next_id += 1
-        return json.dumps(task, indent=2)
-```
-
-2. **依赖解除**: 完成任务时, 自动将其 ID 从其他任务的 `blockedBy` 中移除, 解锁后续任务。
-
-```python
-def _clear_dependency(self, completed_id):
-    for f in self.dir.glob("task_*.json"):
-        task = json.loads(f.read_text())
-        if completed_id in task.get("blockedBy", []):
-            task["blockedBy"].remove(completed_id)
-            self._save(task)
-```
-
-3. **状态变更 + 依赖关联**: `update` 处理状态转换和依赖边。
-
-```python
-def update(self, task_id, status=None,
-           add_blocked_by=None, remove_blocked_by=None):
-    task = self._load(task_id)
-    if status:
-        task["status"] = status
-        if status == "completed":
-            self._clear_dependency(task_id)
-    if add_blocked_by:
-        task["blockedBy"] = list(set(task["blockedBy"] + add_blocked_by))
-    if remove_blocked_by:
-        task["blockedBy"] = [x for x in task["blockedBy"] if x not in remove_blocked_by]
-    self._save(task)
-```
-
-4. 四个任务工具加入 dispatch map。
-
-```python
-TOOL_HANDLERS = {
-    # ...base tools...
-    "task_create": lambda **kw: TASKS.create(kw["subject"]),
-    "task_update": lambda **kw: TASKS.update(kw["task_id"], kw.get("status")),
-    "task_list":   lambda **kw: TASKS.list_all(),
-    "task_get":    lambda **kw: TASKS.get(kw["task_id"]),
-}
-```
-
-从 s07 起, 任务图是多步工作的默认选择。s03 的 Todo 仍可用于单次会话内的快速清单。
-
-## 相对 s06 的变更
-
-| 组件 | 之前 (s06) | 之后 (s07) |
-|---|---|---|
-| Tools | 5 | 8 (`task_create/update/list/get`) |
-| 规划模型 | 扁平清单 (仅内存) | 带依赖关系的任务图 (磁盘) |
-| 关系 | 无 | `blockedBy` 边 |
-| 状态追踪 | 做完没做完 | `pending` -> `in_progress` -> `completed` |
-| 持久化 | 压缩后丢失 | 压缩和重启后存活 |
-
-## 试一试
-
-```sh
-cd learn-claude-code
-python agents/s07_task_system.py
-```
-
-试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):
-
-1. `Create 3 tasks: "Setup project", "Write code", "Write tests". Make them depend on each other in order.`
-2. `List all tasks and show the dependency graph`
-3. `Complete task 1 and then list tasks to see task 2 unblocked`
-4. `Create a task board for refactoring: parse -> transform -> emit -> test, where transform and emit can run in parallel after parse`
diff --git a/docs/zh/s08-background-tasks.md b/docs/zh/s08-background-tasks.md
deleted file mode 100644
index 2931c31b9..000000000
--- a/docs/zh/s08-background-tasks.md
+++ /dev/null
@@ -1,109 +0,0 @@
-# s08: Background Tasks (后台任务)
-
-`s01 > s02 > s03 > s04 > s05 > s06 | s07 > [ s08 ] s09 > s10 > s11 > s12`
-
-> *"慢操作丢后台, agent 继续想下一步"* -- 后台线程跑命令, 完成后注入通知。
->
-> **Harness 层**: 后台执行 -- 模型继续思考, harness 负责等待。
-
-## 问题
-
-有些命令要跑好几分钟: `npm install`、`pytest`、`docker build`。阻塞式循环下模型只能干等。用户说 "装依赖, 顺便建个配置文件", Agent 却只能一个一个来。
-
-## 解决方案
-
-```
-Main thread                Background thread
-+-----------------+        +-----------------+
-| agent loop      |        | subprocess runs |
-| ...             |        | ...             |
-| [LLM call] <---+------- | enqueue(result) |
-|  ^drain queue   |        +-----------------+
-+-----------------+
-
-Timeline:
-Agent --[spawn A]--[spawn B]--[other work]----
-             |          |
-             v          v
-          [A runs]   [B runs]      (parallel)
-             |          |
-             +-- results injected before next LLM call --+
-```
-
-## 工作原理
-
-1. BackgroundManager 用线程安全的通知队列追踪任务。
-
-```python
-class BackgroundManager:
-    def __init__(self):
-        self.tasks = {}
-        self._notification_queue = []
-        self._lock = threading.Lock()
-```
-
-2. `run()` 启动守护线程, 立即返回。
-
-```python
-def run(self, command: str) -> str:
-    task_id = str(uuid.uuid4())[:8]
-    self.tasks[task_id] = {"status": "running", "command": command}
-    thread = threading.Thread(
-        target=self._execute, args=(task_id, command), daemon=True)
-    thread.start()
-    return f"Background task {task_id} started"
-```
-
-3. 子进程完成后, 结果进入通知队列。
-
-```python
-def _execute(self, task_id, command):
-    try:
-        r = subprocess.run(command, shell=True, cwd=WORKDIR,
-            capture_output=True, text=True, timeout=300)
-        output = (r.stdout + r.stderr).strip()[:50000]
-    except subprocess.TimeoutExpired:
-        output = "Error: Timeout (300s)"
-    with self._lock:
-        self._notification_queue.append({
-            "task_id": task_id, "result": output[:500]})
-```
-
-4. 每次 LLM 调用前排空通知队列。
-
-```python
-def agent_loop(messages: list):
-    while True:
-        notifs = BG.drain_notifications()
-        if notifs:
-            notif_text = "\n".join(
-                f"[bg:{n['task_id']}] {n['result']}" for n in notifs)
-            messages.append({"role": "user",
-                "content": f"<background-results>\n{notif_text}\n"
-                           f"</background-results>"})
-        response = client.messages.create(...)
-```
-
-循环保持单线程。只有子进程 I/O 被并行化。
-
-## 相对 s07 的变更
-
-| 组件           | 之前 (s07)       | 之后 (s08)                         |
-|----------------|------------------|------------------------------------|
-| Tools          | 8                | 6 (基础 + background_run + check)  |
-| 执行方式       | 仅阻塞           | 阻塞 + 后台线程                    |
-| 通知机制       | 无               | 每轮排空的队列                     |
-| 并发           | 无               | 守护线程                           |
-
-## 试一试
-
-```sh
-cd learn-claude-code
-python agents/s08_background_tasks.py
-```
-
-试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):
-
-1. `Run "sleep 5 && echo done" in the background, then create a file while it runs`
-2. `Start 3 background tasks: "sleep 2", "sleep 4", "sleep 6". Check their status.`
-3. `Run pytest in the background and keep working on other things`
diff --git a/docs/zh/s08-hook-system.md b/docs/zh/s08-hook-system.md
new file mode 100644
index 000000000..fd5c0a43d
--- /dev/null
+++ b/docs/zh/s08-hook-system.md
@@ -0,0 +1,296 @@
+# s08: Hook System (Hook 系统)
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > [ s08 ] > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
+
+> *不改主循环代码，也能在关键时机插入额外行为。*
+
+## 这章要解决什么问题
+
+到了 `s07`，我们已经能在工具执行前做权限判断。
+
+但很多真实需求并不属于“允许 / 拒绝”这条线，而属于：
+
+- 在某个固定时机顺手做一点事
+- 不改主循环主体，也能接入额外规则
+- 让用户或插件在系统边缘扩展能力
+
+例如：
+
+- 会话开始时打印欢迎信息
+- 工具执行前做一次额外检查
+- 工具执行后补一条审计日志
+
+如果每增加一个需求，你都去修改主循环，主循环就会越来越重，最后谁都不敢动。
+
+所以这一章要引入的机制是：
+
+**主循环只负责暴露“时机”，真正的附加行为交给 hook。**
+
+## 建议联读
+
+- 如果你还在把 hook 想成“往主循环里继续塞 if/else”，先回 [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md)，重新确认主循环和控制面的边界。
+- 如果你开始把主循环、tool handler、hook side effect 混成一层，建议先看 [`entity-map.md`](./entity-map.md)，把谁负责推进主状态、谁只是旁路观察分开。
+- 如果你准备继续读后面的 prompt、recovery、teams，可以把 [`s00e-reference-module-map.md`](./s00e-reference-module-map.md) 一起放在旁边，因为从这一章开始“控制面 + 侧车扩展”会反复一起出现。
+
+## 什么是 hook
+
+你可以把 `hook` 理解成一个“预留插口”。
+
+意思是：
+
+1. 主系统运行到某个固定时机
+2. 把当前上下文交给 hook
+3. hook 返回结果
+4. 主系统再决定下一步怎么继续
+
+最重要的一句话是：
+
+**hook 让系统可扩展，但不要求主循环理解每个扩展需求。**
+
+主循环只需要知道三件事：
+
+- 现在是什么事件
+- 要把哪些上下文交出去
+- 收到结果以后怎么处理
+
+## 最小心智模型
+
+教学版先只讲 3 个事件：
+
+- `SessionStart`
+- `PreToolUse`
+- `PostToolUse`
+
+这样做不是因为系统永远只有 3 个事件，  
+而是因为初学者先把这 3 个事件学明白，就已经能自己做出一套可用的 hook 机制。
+
+可以把它想成这条流程：
+
+```text
+主循环继续往前跑
+  |
+  +-- 到了某个预留时机
+  |
+  +-- 调用 hook runner
+  |
+  +-- 收到 hook 返回结果
+  |
+  +-- 决定继续、阻止、还是补充说明
+```
+
+## 教学版统一返回约定
+
+这一章最容易把人讲乱的地方，就是“不同 hook 事件的返回语义”。
+
+教学版建议先统一成下面这套规则：
+
+| 退出码 | 含义 |
+|---|---|
+| `0` | 正常继续 |
+| `1` | 阻止当前动作 |
+| `2` | 注入一条补充消息，再继续 |
+
+这套规则的价值不在于“最真实”，而在于“最容易学会”。
+
+因为它让你先记住 hook 最核心的 3 种作用：
+
+- 观察
+- 拦截
+- 补充
+
+等教学版跑通以后，再去做“不同事件采用不同语义”的细化，也不会乱。
+
+## 关键数据结构
+
+### 1. HookEvent
+
+```python
+event = {
+    "name": "PreToolUse",
+    "payload": {
+        "tool_name": "bash",
+        "input": {"command": "pytest"},
+    },
+}
+```
+
+它回答的是：
+
+- 现在发生了什么事
+- 这件事的上下文是什么
+
+### 2. HookResult
+
+```python
+result = {
+    "exit_code": 0,
+    "message": "",
+}
+```
+
+它回答的是：
+
+- hook 想不想阻止主流程
+- 要不要向模型补一条说明
+
+### 3. HookRunner
+
+```python
+class HookRunner:
+    def run(self, event_name: str, payload: dict) -> dict:
+        ...
+```
+
+主循环不直接关心“每个 hook 的细节实现”。  
+它只把事件交给统一的 runner。
+
+这就是这一章的关键抽象边界：
+
+**主循环知道事件名，hook runner 知道怎么调扩展逻辑。**
+
+## 最小执行流程
+
+先看最重要的 `PreToolUse` / `PostToolUse`：
+
+```text
+model 发起 tool_use
+    |
+    v
+run_hook("PreToolUse", ...)
+    |
+    +-- exit 1 -> 阻止工具执行
+    +-- exit 2 -> 先补一条消息给模型，再继续
+    +-- exit 0 -> 直接继续
+    |
+    v
+执行工具
+    |
+    v
+run_hook("PostToolUse", ...)
+    |
+    +-- exit 2 -> 追加补充说明
+    +-- exit 0 -> 正常结束
+```
+
+再加上 `SessionStart`，一整套最小 hook 机制就立住了。
+
+## 最小实现
+
+### 第一步：准备一个事件到处理器的映射
+
+```python
+HOOKS = {
+    "SessionStart": [on_session_start],
+    "PreToolUse": [pre_tool_guard],
+    "PostToolUse": [post_tool_log],
+}
+```
+
+这里先用“一个事件对应一组处理函数”的最小结构就够了。
+
+### 第二步：统一运行 hook
+
+```python
+def run_hooks(event_name: str, payload: dict) -> dict:
+    for handler in HOOKS.get(event_name, []):
+        result = handler(payload)
+        if result["exit_code"] in (1, 2):
+            return result
+    return {"exit_code": 0, "message": ""}
+```
+
+教学版里先用“谁先返回阻止/注入，谁就优先”的简单规则。
+
+### 第三步：接进主循环
+
+```python
+pre = run_hooks("PreToolUse", {
+    "tool_name": block.name,
+    "input": block.input,
+})
+
+if pre["exit_code"] == 1:
+    results.append(blocked_tool_result(pre["message"]))
+    continue
+
+if pre["exit_code"] == 2:
+    messages.append({"role": "user", "content": pre["message"]})
+
+output = run_tool(...)
+
+post = run_hooks("PostToolUse", {
+    "tool_name": block.name,
+    "input": block.input,
+    "output": output,
+})
+```
+
+这一步最关键的不是代码量，而是心智：
+
+**hook 不是主循环的替代品，hook 是主循环在固定时机对外发出的调用。**
+
+## 这一章的教学边界
+
+如果你后面继续扩展平台，hook 事件面当然会继续扩大。
+
+常见扩展方向包括：
+
+- 生命周期事件：开始、结束、配置变化
+- 工具事件：执行前、执行后、失败后
+- 压缩事件：压缩前、压缩后
+- 多 agent 事件：子 agent 启动、任务完成、队友空闲
+
+但教学仓这里要守住一个原则：
+
+**先把 hook 的统一模型讲清，再慢慢增加事件种类。**
+
+不要一开始就把几十种事件、几十套返回语义全部灌给读者。
+
+## 初学者最容易犯的错
+
+### 1. 把 hook 当成“到处插 if”
+
+如果还是散落在主循环里写条件分支，那还不是真正的 hook 设计。
+
+### 2. 没有统一的返回结构
+
+今天返回字符串，明天返回布尔值，后天返回整数，最后主循环一定会变乱。
+
+### 3. 一上来就把所有事件做全
+
+教学顺序应该是：
+
+1. 先学会 3 个事件
+2. 再学会统一返回协议
+3. 最后才扩事件面
+
+### 4. 忘了说明“教学版统一语义”和“高完成度细化语义”的区别
+
+如果这层不提前说清，读者后面看到更复杂实现时会以为前面学错了。
+
+其实不是学错了，而是：
+
+**先学统一模型，再学事件细化。**
+
+## 学完这一章，你应该真正掌握什么
+
+学完以后，你应该能自己清楚说出下面几句话：
+
+1. hook 的作用，是在固定时机扩展系统，而不是改写主循环。
+2. hook 至少需要“事件名 + payload + 返回结果”这三样东西。
+3. 教学版可以先用统一的 `0 / 1 / 2` 返回约定。
+4. `PreToolUse` 和 `PostToolUse` 已经足够支撑最核心的扩展能力。
+
+如果这 4 句话你已经能独立复述，说明这一章的核心心智已经建立起来了。
+
+## 下一章学什么
+
+这一章解决的是：
+
+> 在固定时机插入行为。
+
+下一章 `s09` 要解决的是：
+
+> 哪些信息应该跨会话留下，哪些不该留。
+
+也就是从“扩展点”进一步走向“持久状态”。
diff --git a/docs/zh/s09-agent-teams.md b/docs/zh/s09-agent-teams.md
deleted file mode 100644
index d43be9448..000000000
--- a/docs/zh/s09-agent-teams.md
+++ /dev/null
@@ -1,127 +0,0 @@
-# s09: Agent Teams (Agent 团队)
-
-`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > [ s09 ] s10 > s11 > s12`
-
-> *"任务太大一个人干不完, 要能分给队友"* -- 持久化队友 + JSONL 邮箱。
->
-> **Harness 层**: 团队邮箱 -- 多个模型, 通过文件协调。
-
-## 问题
-
-Subagent (s04) 是一次性的: 生成、干活、返回摘要、消亡。没有身份, 没有跨调用的记忆。Background Tasks (s08) 能跑 shell 命令, 但做不了 LLM 引导的决策。
-
-真正的团队协作需要三样东西: (1) 能跨多轮对话存活的持久 Agent, (2) 身份和生命周期管理, (3) Agent 之间的通信通道。
-
-## 解决方案
-
-```
-Teammate lifecycle:
-  spawn -> WORKING -> IDLE -> WORKING -> ... -> SHUTDOWN
-
-Communication:
-  .team/
-    config.json           <- team roster + statuses
-    inbox/
-      alice.jsonl         <- append-only, drain-on-read
-      bob.jsonl
-      lead.jsonl
-
-              +--------+    send("alice","bob","...")    +--------+
-              | alice  | -----------------------------> |  bob   |
-              | loop   |    bob.jsonl << {json_line}    |  loop  |
-              +--------+                                +--------+
-                   ^                                         |
-                   |        BUS.read_inbox("alice")          |
-                   +---- alice.jsonl -> read + drain ---------+
-```
-
-## 工作原理
-
-1. TeammateManager 通过 config.json 维护团队名册。
-
-```python
-class TeammateManager:
-    def __init__(self, team_dir: Path):
-        self.dir = team_dir
-        self.dir.mkdir(exist_ok=True)
-        self.config_path = self.dir / "config.json"
-        self.config = self._load_config()
-        self.threads = {}
-```
-
-2. `spawn()` 创建队友并在线程中启动 agent loop。
-
-```python
-def spawn(self, name: str, role: str, prompt: str) -> str:
-    member = {"name": name, "role": role, "status": "working"}
-    self.config["members"].append(member)
-    self._save_config()
-    thread = threading.Thread(
-        target=self._teammate_loop,
-        args=(name, role, prompt), daemon=True)
-    thread.start()
-    return f"Spawned teammate '{name}' (role: {role})"
-```
-
-3. MessageBus: append-only 的 JSONL 收件箱。`send()` 追加一行; `read_inbox()` 读取全部并清空。
-
-```python
-class MessageBus:
-    def send(self, sender, to, content, msg_type="message", extra=None):
-        msg = {"type": msg_type, "from": sender,
-               "content": content, "timestamp": time.time()}
-        if extra:
-            msg.update(extra)
-        with open(self.dir / f"{to}.jsonl", "a") as f:
-            f.write(json.dumps(msg) + "\n")
-
-    def read_inbox(self, name):
-        path = self.dir / f"{name}.jsonl"
-        if not path.exists(): return "[]"
-        msgs = [json.loads(l) for l in path.read_text().strip().splitlines() if l]
-        path.write_text("")  # drain
-        return json.dumps(msgs, indent=2)
-```
-
-4. 每个队友在每次 LLM 调用前检查收件箱, 将消息注入上下文。
-
-```python
-def _teammate_loop(self, name, role, prompt):
-    messages = [{"role": "user", "content": prompt}]
-    for _ in range(50):
-        inbox = BUS.read_inbox(name)
-        if inbox != "[]":
-            messages.append({"role": "user",
-                "content": f"<inbox>{inbox}</inbox>"})
-        response = client.messages.create(...)
-        if response.stop_reason != "tool_use":
-            break
-        # execute tools, append results...
-    self._find_member(name)["status"] = "idle"
-```
-
-## 相对 s08 的变更
-
-| 组件           | 之前 (s08)       | 之后 (s09)                         |
-|----------------|------------------|------------------------------------|
-| Tools          | 6                | 9 (+spawn/send/read_inbox)         |
-| Agent 数量     | 单一             | 领导 + N 个队友                    |
-| 持久化         | 无               | config.json + JSONL 收件箱         |
-| 线程           | 后台命令         | 每线程完整 agent loop              |
-| 生命周期       | 一次性           | idle -> working -> idle            |
-| 通信           | 无               | message + broadcast                |
-
-## 试一试
-
-```sh
-cd learn-claude-code
-python agents/s09_agent_teams.py
-```
-
-试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):
-
-1. `Spawn alice (coder) and bob (tester). Have alice send bob a message.`
-2. `Broadcast "status update: phase 1 complete" to all teammates`
-3. `Check the lead inbox for any messages`
-4. 输入 `/team` 查看团队名册和状态
-5. 输入 `/inbox` 手动检查领导的收件箱
diff --git a/docs/zh/s09-memory-system.md b/docs/zh/s09-memory-system.md
new file mode 100644
index 000000000..e4c755959
--- /dev/null
+++ b/docs/zh/s09-memory-system.md
@@ -0,0 +1,408 @@
+# s09: Memory System (记忆系统)
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > [ s09 ] > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
+
+> *不是所有信息都该进入 memory；只有跨会话仍然有价值的信息，才值得留下。*
+
+## 这一章在解决什么问题
+
+如果一个 agent 每次新会话都完全从零开始，它就会不断重复忘记这些事情：
+
+- 用户长期偏好
+- 用户多次纠正过的错误
+- 某些不容易从代码直接看出来的项目约定
+- 某些外部资源在哪里找
+
+这会让系统显得“每次都像第一次合作”。
+
+所以需要 memory。
+
+## 但先立一个边界：memory 不是什么都存
+
+这是这一章最容易讲歪的地方。
+
+memory 不是“把一切有用信息都记下来”。
+
+如果你这样做，很快就会出现两个问题：
+
+1. memory 变成垃圾堆，越存越乱
+2. agent 开始依赖过时记忆，而不是读取当前真实状态
+
+所以这章必须先立一个原则：
+
+**只有那些跨会话仍然有价值，而且不能轻易从当前仓库状态直接推出来的信息，才适合进入 memory。**
+
+## 建议联读
+
+- 如果你还把 memory 想成“更长一点的上下文窗口”，先回 [`s06-context-compact.md`](./s06-context-compact.md)，重新确认 compact 和长期记忆是两套机制。
+- 如果你在 `messages[]`、摘要块、memory store 这三层之间开始读混，建议边看边对照 [`data-structures.md`](./data-structures.md)。
+- 如果你准备继续读 `s10`，最好把 [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md) 放在旁边，因为 memory 真正重要的是它怎样重新进入下一轮输入。
+
+## 先解释几个名词
+
+### 什么是“跨会话”
+
+意思是：
+
+- 当前对话结束了
+- 下次重新开始一个新对话
+- 这条信息仍然可能有用
+
+### 什么是“不可轻易重新推导”
+
+例如：
+
+- 用户明确说“我讨厌这种写法”
+- 某个架构决定背后的真实原因是合规要求
+- 某个团队总在某个外部看板里跟踪问题
+
+这些东西，往往不是你重新扫一遍代码就能立刻知道的。
+
+## 最适合先教的 4 类 memory
+
+### 1. `user`
+
+用户偏好。
+
+例如：
+
+- 喜欢什么代码风格
+- 回答希望简洁还是详细
+- 更偏好什么工具链
+
+### 2. `feedback`
+
+用户明确纠正过你的地方。
+
+例如：
+
+- “不要这样改”
+- “这个判断方式之前错过”
+- “以后遇到这种情况要先做 X”
+
+### 3. `project`
+
+这里只保存**不容易从代码直接重新看出来**的项目约定或背景。
+
+例如：
+
+- 某个设计决定是因为合规而不是技术偏好
+- 某个目录虽然看起来旧，但短期内不能动
+- 某条规则是团队故意定下来的，不是历史残留
+
+### 4. `reference`
+
+外部资源指针。
+
+例如：
+
+- 某个问题单在哪个看板里
+- 某个监控面板在哪里
+- 某个资料库在哪个 URL
+
+## 哪些东西不要存进 memory
+
+这是比“该存什么”更重要的一张表：
+
+| 不要存的东西 | 为什么 |
+|---|---|
+| 文件结构、函数签名、目录布局 | 这些可以重新读代码得到 |
+| 当前任务进度 | 这属于 task / plan，不属于 memory |
+| 临时分支名、当前 PR 号 | 很快会过时 |
+| 修 bug 的具体代码细节 | 代码和提交记录才是准确信息 |
+| 密钥、密码、凭证 | 安全风险 |
+
+这条边界一定要稳。
+
+否则 memory 会从“帮助系统长期变聪明”变成“帮助系统长期产生幻觉”。
+
+## 最小心智模型
+
+```text
+conversation
+   |
+   | 用户提到一个长期重要信息
+   v
+save_memory
+   |
+   v
+.memory/
+  ├── MEMORY.md        # 索引
+  ├── prefer_tabs.md
+  ├── feedback_tests.md
+  └── incident_board.md
+   |
+   v
+下次新会话开始时重新加载
+```
+
+## 这一章最关键的数据结构
+
+### 1. 单条 memory 文件
+
+最简单也最清晰的做法，是每条 memory 一个文件。
+
+```md
+---
+name: prefer_tabs
+description: User prefers tabs for indentation
+type: user
+---
+The user explicitly prefers tabs over spaces when editing source files.
+```
+
+这里的 `frontmatter` 可以理解成：
+
+**放在正文前面的结构化元数据。**
+
+它让系统先知道：
+
+- 这条 memory 叫什么
+- 大致是什么
+- 属于哪一类
+
+### 2. 索引文件 `MEMORY.md`
+
+最小实现里，再加一个索引文件就够了：
+
+```md
+# Memory Index
+
+- prefer_tabs: User prefers tabs for indentation [user]
+- avoid_mock_heavy_tests: User dislikes mock-heavy tests [feedback]
+```
+
+索引的作用不是重复保存全部内容。  
+它只是帮系统快速知道“有哪些 memory 可用”。
+
+## 最小实现步骤
+
+### 第一步：定义 memory 类型
+
+```python
+MEMORY_TYPES = ("user", "feedback", "project", "reference")
+```
+
+### 第二步：写一个 `save_memory` 工具
+
+最小参数就四个：
+
+- `name`
+- `description`
+- `type`
+- `content`
+
+### 第三步：每条 memory 独立落盘
+
+```python
+def save_memory(name, description, mem_type, content):
+    path = memory_dir / f"{safe_name}.md"
+    path.write_text(frontmatter + content)
+    rebuild_index()
+```
+
+### 第四步：会话开始时重新加载
+
+把 memory 文件重新读出来，拼成一段 memory section。
+
+### 第五步：把 memory section 接进系统输入
+
+这一步会在 `s10` 的 prompt 组装里系统化。
+
+## memory、task、plan、CLAUDE.md 的边界
+
+这是最值得初学者反复区分的一组概念。
+
+### memory
+
+保存跨会话仍有价值的信息。
+
+### task
+
+保存当前工作要做什么、依赖关系如何、进度如何。
+
+### plan
+
+保存“这一轮我要怎么做”的过程性安排。
+
+### CLAUDE.md
+
+保存更稳定、更像长期规则的说明文本。
+
+一个简单判断法：
+
+- 只对这次任务有用：`task / plan`
+- 以后很多会话可能都还会有用：`memory`
+- 属于长期系统级或项目级固定说明：`CLAUDE.md`
+
+## 初学者最容易犯的错
+
+### 错误 1：把代码结构也存进 memory
+
+例如：
+
+- “这个项目有 `src/` 和 `tests/`”
+- “这个函数在 `app.py`”
+
+这些都不该存。
+
+因为系统完全可以重新去读。
+
+### 错误 2：把当前任务状态存进 memory
+
+例如：
+
+- “我现在正在改认证模块”
+- “这个 PR 还有两项没做”
+
+这些是 task / plan，不是 memory。
+
+### 错误 3：把 memory 当成绝对真相
+
+memory 可能过时。
+
+所以更稳妥的规则是：
+
+**memory 用来提供方向，不用来替代当前观察。**
+
+如果 memory 和当前代码状态冲突，优先相信你现在看到的真实状态。
+
+## 从教学版到高完成度版：记忆系统还要补的 6 条边界
+
+最小教学版只要先把“该存什么 / 不该存什么”讲清楚。  
+但如果你要把系统做到更稳、更像真实工作平台，下面这 6 条边界也必须讲清。
+
+### 1. 不是所有 memory 都该放在同一个作用域
+
+更完整系统里，至少要分清：
+
+- `private`：只属于当前用户或当前 agent 的记忆
+- `team`：整个项目团队都该共享的记忆
+
+一个很稳的教学判断法是：
+
+- `user` 类型，几乎总是 `private`
+- `feedback` 类型，默认 `private`；只有它明确是团队规则时才升到 `team`
+- `project` 和 `reference`，通常更偏向 `team`
+
+这样做的价值是：
+
+- 不把个人偏好误写成团队规范
+- 不把团队规范只锁在某一个人的私有记忆里
+
+### 2. 不只保存“你做错了”，也要保存“这样做是对的”
+
+很多人讲 memory 时，只会想到纠错。
+
+这不够。
+
+因为真正能长期使用的系统，还需要记住：
+
+- 哪种不明显的做法，用户已经明确认可
+- 哪个判断方式，项目里已经被验证有效
+
+也就是说，`feedback` 不只来自负反馈，也来自被验证的正反馈。
+
+如果只存纠错，不存被确认有效的做法，系统会越来越保守，却不一定越来越聪明。
+
+### 3. 有些东西即使用户要求你存，也不该直接存
+
+这条边界一定要说死。
+
+就算用户说“帮我记住”，下面这些东西也不应该直接写进 memory：
+
+- 本周 PR 列表
+- 当前分支名
+- 今天改了哪些文件
+- 某个函数现在在什么路径
+- 当前正在做哪两个子任务
+
+这些内容的问题不是“没有价值”，而是：
+
+- 太容易过时
+- 更适合存在代码、任务板、git 记录里
+- 会把 memory 变成活动日志
+
+更好的做法是追问一句：
+
+> 这里面真正值得长期留下的、非显然的信息到底是什么？
+
+### 4. memory 会漂移，所以回答前要先核对当前状态
+
+memory 记录的是“曾经成立过的事实”，不是永久真理。
+
+所以更稳的工作方式是：
+
+1. 先把 memory 当作方向提示
+2. 再去读当前文件、当前资源、当前配置
+3. 如果冲突，优先相信你刚观察到的真实状态
+
+这点对初学者尤其重要。  
+因为他们最容易把 memory 当成“已经查证过的答案”。
+
+### 5. 用户说“忽略 memory”时，就当它是空的
+
+这是一个很容易漏讲的行为边界。
+
+如果用户明确说：
+
+- “这次不要参考 memory”
+- “忽略之前的记忆”
+
+那系统更合理的处理不是：
+
+- 一边继续用 memory
+- 一边嘴上说“我知道但先忽略”
+
+而是：
+
+**在这一轮里，按 memory 为空来工作。**
+
+### 6. 推荐具体路径、函数、外部资源前，要再验证一次
+
+memory 很适合保存：
+
+- 哪个看板通常有上下文
+- 哪个目录以前是关键入口
+- 某种项目约定为什么存在
+
+但在你真的要对用户说：
+
+- “去改 `src/auth.py`”
+- “调用 `AuthManager`”
+- “看这个 URL 就对了”
+
+之前，最好再核对一次。
+
+因为命名、路径、系统入口、外部链接，都是会变的。
+
+所以更稳妥的做法不是：
+
+> memory 里写过，就直接复述。
+
+而是：
+
+> memory 先告诉我去哪里验证；验证完，再给用户结论。
+
+## 教学边界
+
+这章最重要的，不是 memory 以后还能多自动、多复杂，而是先把存储边界讲清楚：
+
+- 什么值得跨会话留下
+- 什么只是当前任务状态，不该进 memory
+- memory 和 task / plan / CLAUDE.md 各自负责什么
+
+只要这几层边界清楚，教学目标就已经达成了。
+
+更复杂的自动整合、作用域分层、自动抽取，都应该放在这个最小边界之后。
+
+## 学完这章后，你应该能回答
+
+- 为什么 memory 不是“什么都记”？
+- 什么样的信息适合跨会话保存？
+- 为什么代码结构和当前任务状态不应该进 memory？
+- memory 和 task / plan / CLAUDE.md 的边界是什么？
+
+---
+
+**一句话记住：memory 保存的是“以后还可能有价值、但当前代码里不容易直接重新看出来”的信息。**
diff --git a/docs/zh/s10-system-prompt.md b/docs/zh/s10-system-prompt.md
new file mode 100644
index 000000000..c6394bc58
--- /dev/null
+++ b/docs/zh/s10-system-prompt.md
@@ -0,0 +1,308 @@
+# s10: System Prompt Construction (系统提示词构建)
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > [ s10 ] > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
+
+> *系统提示词不是一整块大字符串，而是一条可维护的组装流水线。*
+
+## 这一章为什么重要
+
+很多初学者一开始会把 system prompt 写成一大段固定文本。
+
+这样在最小 demo 里当然能跑。
+
+但一旦系统开始长功能，你很快会遇到这些问题：
+
+- 工具列表会变
+- skills 会变
+- memory 会变
+- 当前目录、日期、模式会变
+- 某些提醒只在这一轮有效，不该永远塞进系统说明
+
+所以到了这个阶段，system prompt 不能再当成一块硬编码文本。
+
+它应该升级成：
+
+**由多个来源共同组装出来的一条流水线。**
+
+## 建议联读
+
+- 如果你还习惯把 prompt 看成“神秘大段文本”，先回 [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)，重新确认模型输入在进模型前经历了哪些控制层。
+- 如果你想真正稳住“哪些内容先拼、哪些后拼”，建议把 [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md) 放在手边，这页就是本章最关键的桥。
+- 如果你开始把 system rules、工具说明、memory、runtime state 混成一个大块，先看 [`data-structures.md`](./data-structures.md)，把这些输入片段的来源重新拆开。
+
+## 先解释几个名词
+
+### 什么是 system prompt
+
+system prompt 是给模型的系统级说明。
+
+它通常负责告诉模型：
+
+- 你是谁
+- 你能做什么
+- 你应该遵守什么规则
+- 你现在处在什么环境里
+
+### 什么是“组装流水线”
+
+意思是：
+
+- 不同信息来自不同地方
+- 最后按顺序拼接成一份输入
+
+它不是一个死字符串，而是一条构建过程。
+
+### 什么是动态信息
+
+有些信息经常变化，例如：
+
+- 当前日期
+- 当前工作目录
+- 本轮新增的提醒
+
+这些信息不适合和所有稳定说明混在一起。
+
+## 最小心智模型
+
+最容易理解的方式，是把 system prompt 想成 6 段：
+
+```text
+1. 核心身份和行为说明
+2. 工具列表
+3. skills 元信息
+4. memory 内容
+5. CLAUDE.md 指令链
+6. 动态环境信息
+```
+
+然后按顺序拼起来：
+
+```text
+core
++ tools
++ skills
++ memory
++ claude_md
++ dynamic_context
+= final system prompt
+```
+
+## 为什么不能把所有东西都硬塞进一个大字符串
+
+因为这样会有三个问题：
+
+### 1. 不好维护
+
+你很难知道：
+
+- 哪一段来自哪里
+- 该修改哪一部分
+- 哪一段是固定说明，哪一段是临时上下文
+
+### 2. 不好测试
+
+如果 system prompt 是一大坨文本，你很难分别测试：
+
+- 工具说明生成得对不对
+- memory 是否被正确拼进去
+- CLAUDE.md 是否被正确读取
+
+### 3. 不好做缓存和动态更新
+
+一些稳定内容其实不需要每轮大变。  
+一些临时内容又只该活一轮。
+
+这就要求你把“稳定块”和“动态块”分开思考。
+
+## 最小实现结构
+
+### 第一步：做一个 builder
+
+```python
+class SystemPromptBuilder:
+    def build(self) -> str:
+        parts = []
+        parts.append(self._build_core())
+        parts.append(self._build_tools())
+        parts.append(self._build_skills())
+        parts.append(self._build_memory())
+        parts.append(self._build_claude_md())
+        parts.append(self._build_dynamic())
+        return "\n\n".join(p for p in parts if p)
+```
+
+这就是这一章最核心的设计。
+
+### 第二步：每一段只负责一种来源
+
+例如：
+
+- `_build_tools()` 只负责把工具说明生成出来
+- `_build_memory()` 只负责拿 memory
+- `_build_claude_md()` 只负责读指令文件
+
+这样每一段的职责就很清楚。
+
+## 这一章最关键的结构化边界
+
+### 边界 1：稳定说明 vs 动态提醒
+
+最重要的一组边界是：
+
+- 稳定的系统说明
+- 每轮临时变化的提醒
+
+这两类东西不应该混为一谈。
+
+### 边界 2：system prompt vs system reminder
+
+system prompt 适合放：
+
+- 身份
+- 规则
+- 工具
+- 长期约束
+
+system reminder 适合放：
+
+- 这一轮才临时需要的补充上下文
+- 当前变动的状态
+
+所以更清晰的做法是：
+
+- 主 system prompt 保持相对稳定
+- 每轮额外变化的内容，用单独的 reminder 方式追加
+
+## 一个实用的教学版本
+
+教学版可以先这样分：
+
+```text
+静态部分：
+- core
+- tools
+- skills
+- memory
+- CLAUDE.md
+
+动态部分：
+- date
+- cwd
+- model
+- current mode
+```
+
+如果你还想再清楚一点，可以加一个边界标记：
+
+```text
+=== DYNAMIC_BOUNDARY ===
+```
+
+它的作用不是神秘魔法。
+
+它只是提醒你：
+
+**上面更稳定，下面更容易变。**
+
+## CLAUDE.md 为什么要单独一段
+
+因为它的角色不是“某一次任务的临时上下文”，而是更稳定的长期说明。
+
+教学仓里，最容易理解的链条是：
+
+1. 用户全局级
+2. 项目根目录级
+3. 当前子目录级
+
+然后全部拼进去，而不是互相覆盖。
+
+这样读者更容易理解“规则来源可以分层叠加”这个思想。
+
+## memory 为什么要和 system prompt 有关系
+
+因为 memory 的本质是：
+
+**把跨会话仍然有价值的信息，重新带回模型当前的工作环境。**
+
+如果保存了 memory，却从来不在系统输入中重新呈现，那它就等于没被真正用起来。
+
+所以 memory 最终一定要进入 prompt 组装链条。
+
+## 初学者最容易混淆的点
+
+### 1. 把 system prompt 讲成一个固定字符串
+
+这会让读者看不到系统是如何长大的。
+
+### 2. 把所有变化信息都塞进 system prompt
+
+这会把稳定说明和临时提醒搅在一起。
+
+### 3. 把 CLAUDE.md、memory、skills 写成同一种东西
+
+它们都可能进入 prompt，但来源和职责不同：
+
+- `skills`：可选能力或知识包
+- `memory`：跨会话记住的信息
+- `CLAUDE.md`：长期规则说明
+
+## 教学边界
+
+这一章先只建立一个核心心智：
+
+**prompt 不是一整块静态文本，而是一条被逐段组装出来的输入流水线。**
+
+所以这里先不要扩到太多外层细节：
+
+- 不要先讲复杂的 section 注册系统
+- 不要先讲缓存与预算
+- 不要先讲所有外部能力如何追加 prompt 说明
+
+只要读者已经能把稳定规则、动态提醒、memory、skills 这些来源看成不同输入段，而不是同一种“大 prompt”，这一章就已经讲到位了。
+
+## 如果你开始分不清 prompt、message、reminder
+
+这是非常正常的。
+
+因为到了这一章，系统输入已经不再只有一个 system prompt 了。  
+它至少会同时出现：
+
+- system prompt blocks
+- 普通对话消息
+- tool_result 消息
+- memory attachment
+- 当前轮 reminder
+
+如果你开始有这类困惑：
+
+- “这个信息到底该放 prompt 里，还是放 message 里？”
+- “为什么 system prompt 不是全部输入？”
+- “reminder 和长期规则到底差在哪？”
+
+建议继续看：
+
+- [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md)
+- [`entity-map.md`](./entity-map.md)
+
+## 这章和后续章节的关系
+
+这一章像一个汇合点：
+
+- `s05` skills 会汇进来
+- `s09` memory 会汇进来
+- `s07` 的当前模式也可能汇进来
+- `s19` MCP 以后也可能给 prompt 增加说明
+
+所以 `s10` 的价值不是“新加一个功能”，  
+而是“把前面长出来的功能组织成一份清楚的系统输入”。
+
+## 学完这章后，你应该能回答
+
+- 为什么 system prompt 不能只是一整块硬编码文本？
+- 为什么要把不同来源拆成独立 section？
+- system prompt 和 system reminder 的边界是什么？
+- memory、skills、CLAUDE.md 为什么都可能进入 prompt，但又不是一回事？
+
+---
+
+**一句话记住：system prompt 的关键不是“写一段很长的话”，而是“把不同来源的信息按清晰边界组装起来”。**
diff --git a/docs/zh/s10-team-protocols.md b/docs/zh/s10-team-protocols.md
deleted file mode 100644
index a57c926b7..000000000
--- a/docs/zh/s10-team-protocols.md
+++ /dev/null
@@ -1,108 +0,0 @@
-# s10: Team Protocols (团队协议)
-
-`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > [ s10 ] s11 > s12`
-
-> *"队友之间要有统一的沟通规矩"* -- 一个 request-response 模式驱动所有协商。
->
-> **Harness 层**: 协议 -- 模型之间的结构化握手。
-
-## 问题
-
-s09 中队友能干活能通信, 但缺少结构化协调:
-
-**关机**: 直接杀线程会留下写了一半的文件和过期的 config.json。需要握手 -- 领导请求, 队友批准 (收尾退出) 或拒绝 (继续干)。
-
-**计划审批**: 领导说 "重构认证模块", 队友立刻开干。高风险变更应该先过审。
-
-两者结构一样: 一方发带唯一 ID 的请求, 另一方引用同一 ID 响应。
-
-## 解决方案
-
-```
-Shutdown Protocol            Plan Approval Protocol
-==================           ======================
-
-Lead             Teammate    Teammate           Lead
-  |                 |           |                 |
-  |--shutdown_req-->|           |--plan_req------>|
-  | {req_id:"abc"}  |           | {req_id:"xyz"}  |
-  |                 |           |                 |
-  |<--shutdown_resp-|           |<--plan_resp-----|
-  | {req_id:"abc",  |           | {req_id:"xyz",  |
-  |  approve:true}  |           |  approve:true}  |
-
-Shared FSM:
-  [pending] --approve--> [approved]
-  [pending] --reject---> [rejected]
-
-Trackers:
-  shutdown_requests = {req_id: {target, status}}
-  plan_requests     = {req_id: {from, plan, status}}
-```
-
-## 工作原理
-
-1. 领导生成 request_id, 通过收件箱发起关机请求。
-
-```python
-shutdown_requests = {}
-
-def handle_shutdown_request(teammate: str) -> str:
-    req_id = str(uuid.uuid4())[:8]
-    shutdown_requests[req_id] = {"target": teammate, "status": "pending"}
-    BUS.send("lead", teammate, "Please shut down gracefully.",
-             "shutdown_request", {"request_id": req_id})
-    return f"Shutdown request {req_id} sent (status: pending)"
-```
-
-2. 队友收到请求后, 用 approve/reject 响应。
-
-```python
-if tool_name == "shutdown_response":
-    req_id = args["request_id"]
-    approve = args["approve"]
-    shutdown_requests[req_id]["status"] = "approved" if approve else "rejected"
-    BUS.send(sender, "lead", args.get("reason", ""),
-             "shutdown_response",
-             {"request_id": req_id, "approve": approve})
-```
-
-3. 计划审批遵循完全相同的模式。队友提交计划 (生成 request_id), 领导审查 (引用同一个 request_id)。
-
-```python
-plan_requests = {}
-
-def handle_plan_review(request_id, approve, feedback=""):
-    req = plan_requests[request_id]
-    req["status"] = "approved" if approve else "rejected"
-    BUS.send("lead", req["from"], feedback,
-             "plan_approval_response",
-             {"request_id": request_id, "approve": approve})
-```
-
-一个 FSM, 两种用途。同样的 `pending -> approved | rejected` 状态机可以套用到任何请求-响应协议上。
-
-## 相对 s09 的变更
-
-| 组件           | 之前 (s09)       | 之后 (s10)                           |
-|----------------|------------------|--------------------------------------|
-| Tools          | 9                | 12 (+shutdown_req/resp +plan)        |
-| 关机           | 仅自然退出       | 请求-响应握手                        |
-| 计划门控       | 无               | 提交/审查与审批                      |
-| 关联           | 无               | 每个请求一个 request_id              |
-| FSM            | 无               | pending -> approved/rejected         |
-
-## 试一试
-
-```sh
-cd learn-claude-code
-python agents/s10_team_protocols.py
-```
-
-试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):
-
-1. `Spawn alice as a coder. Then request her shutdown.`
-2. `List teammates to see alice's status after shutdown approval`
-3. `Spawn bob with a risky refactoring task. Review and reject his plan.`
-4. `Spawn charlie, have him submit a plan, then approve it.`
-5. 输入 `/team` 监控状态
diff --git a/docs/zh/s10a-message-prompt-pipeline.md b/docs/zh/s10a-message-prompt-pipeline.md
new file mode 100644
index 000000000..2ab35c428
--- /dev/null
+++ b/docs/zh/s10a-message-prompt-pipeline.md
@@ -0,0 +1,298 @@
+# s10a: Message & Prompt Pipeline (消息与提示词管道)
+
+> 这篇桥接文档是 `s10` 的扩展。  
+> 它要补清一个很关键的心智：
+>
+> **system prompt 很重要，但它不是模型完整输入的全部。**
+
+## 为什么要补这一篇
+
+`s10` 已经把 system prompt 从“大字符串”升级成“可维护的组装流水线”，这一步非常重要。
+
+但当系统开始长出更多输入来源时，还会继续往前走一步：
+
+它会发现，真正送给模型的输入，不只包含：
+
+- system prompt
+
+还包含：
+
+- 规范化后的 messages
+- memory attachments
+- hook 注入消息
+- system reminder
+- 当前轮次的动态上下文
+
+也就是说，真正的输入更像一条完整管道：
+
+**Prompt Pipeline，而不只是 Prompt Builder。**
+
+## 先解释几个名词
+
+### 什么是 prompt block
+
+你可以把 `prompt block` 理解成：
+
+> system prompt 内部的一段结构化片段。
+
+例如：
+
+- 核心身份说明
+- 工具说明
+- memory section
+- CLAUDE.md section
+
+### 什么是 normalized message
+
+`normalized message` 的意思是：
+
+> 把不同来源、不同格式的消息整理成统一、稳定、可发给模型的消息形式。
+
+为什么需要这一步？
+
+因为系统里可能出现：
+
+- 普通用户消息
+- assistant 回复
+- tool_result
+- 系统提醒
+- attachment 包裹消息
+
+如果不先整理，模型输入层会越来越乱。
+
+### 什么是 system reminder
+
+这在 `s10` 已经提到过。
+
+它不是长期规则，而是：
+
+> 只在当前轮或当前阶段临时追加的一小段系统信息。
+
+## 最小心智模型
+
+把完整输入先理解成下面这条流水线：
+
+```text
+多种输入来源
+  |
+  +-- system prompt blocks
+  +-- messages
+  +-- attachments
+  +-- reminders
+  |
+  v
+normalize
+  |
+  v
+final api payload
+```
+
+这条图里最重要的不是“normalize”这个词有多高级，而是：
+
+**所有来源先分清边界，再在最后一步统一整理。**
+
+## system prompt 为什么不是全部
+
+这是初学者非常容易混的一个点。
+
+system prompt 适合放：
+
+- 身份
+- 规则
+- 工具能力描述
+- 长期说明
+
+但有些东西不适合放进去：
+
+- 这一轮刚发生的 tool_result
+- 某个 hook 刚注入的补充说明
+- 某条 memory attachment
+- 当前临时提醒
+
+这些更适合存在消息流里，而不是塞进 prompt block。
+
+## 关键数据结构
+
+### 1. SystemPromptBlock
+
+```python
+block = {
+    "text": "...",
+    "cache_scope": None,
+}
+```
+
+最小教学版可以只理解成：
+
+- 一段文本
+- 可选的缓存信息
+
+### 2. PromptParts
+
+```python
+parts = {
+    "core": "...",
+    "tools": "...",
+    "skills": "...",
+    "memory": "...",
+    "claude_md": "...",
+    "dynamic": "...",
+}
+```
+
+### 3. NormalizedMessage
+
+```python
+message = {
+    "role": "user" | "assistant",
+    "content": [...],
+}
+```
+
+这里的 `content` 建议直接理解成“块列表”，而不是只是一段字符串。  
+因为后面你会自然遇到：
+
+- text block
+- tool_use block
+- tool_result block
+- attachment-like block
+
+### 4. ReminderMessage
+
+```python
+reminder = {
+    "role": "system",
+    "content": "Current mode: plan",
+}
+```
+
+教学版里你不一定真的要用 `system` role 单独传，但心智上要区分：
+
+- 这是长期 prompt block
+- 还是当前轮临时 reminder
+
+## 最小实现
+
+### 第一步：继续保留 `SystemPromptBuilder`
+
+这一步不能丢。
+
+### 第二步：把消息输入做成独立管道
+
+```python
+def build_messages(raw_messages, attachments, reminders):
+    messages = normalize_messages(raw_messages)
+    messages = attach_memory(messages, attachments)
+    messages = append_reminders(messages, reminders)
+    return messages
+```
+
+### 第三步：在最后一层统一生成 API payload
+
+```python
+payload = {
+    "system": build_system_prompt(),
+    "messages": build_messages(...),
+    "tools": build_tools(...),
+}
+```
+
+这一步特别关键。
+
+它会让读者明白：
+
+**system prompt、messages、tools 是并列输入面，而不是互相替代。**
+
+## 一张更完整但仍然容易理解的图
+
+```text
+Prompt Blocks
+  - core
+  - tools
+  - memory
+  - CLAUDE.md
+  - dynamic context
+
+Messages
+  - user messages
+  - assistant messages
+  - tool_result messages
+  - injected reminders
+
+Attachments
+  - memory attachment
+  - hook attachment
+
+          |
+          v
+   normalize + assemble
+          |
+          v
+     final API payload
+```
+
+## 什么时候该放在 prompt，什么时候该放在 message
+
+可以先记这个简单判断法：
+
+### 更适合放在 prompt block
+
+- 长期稳定规则
+- 工具列表
+- 长期身份说明
+- CLAUDE.md
+
+### 更适合放在 message 流
+
+- 当前轮 tool_result
+- 刚发生的提醒
+- 当前轮追加的上下文
+- 某次 hook 输出
+
+### 更适合做 attachment
+
+- 大块但可选的补充信息
+- 需要按需展开的说明
+
+## 初学者最容易犯的错
+
+### 1. 把所有东西都塞进 system prompt
+
+这样会让 prompt 越来越脏，也会模糊稳定信息和动态信息的边界。
+
+### 2. 完全不做 normalize
+
+随着消息来源增多，输入格式会越来越不稳定。
+
+### 3. 把 memory、hook、tool_result 都当成一类东西
+
+它们都能影响模型，但进入输入层的方式并不相同。
+
+### 4. 忽略“临时 reminder”这一层
+
+这会让很多本该只活一轮的信息，被错误地塞进长期 system prompt。
+
+## 它和 `s10`、`s19` 的关系
+
+- `s10` 讲 prompt builder
+- 这篇讲 message + prompt 的完整输入管道
+- `s19` 则会把 MCP 带来的额外说明和外部能力继续接入这条管道
+
+也就是说：
+
+**builder 是 prompt 的内部结构，pipeline 是模型输入的整体结构。**
+
+## 教学边界
+
+这篇最重要的，不是罗列所有输入来源，而是先把三条管线边界讲稳：
+
+- 什么该进 system blocks
+- 什么该进 normalized messages
+- 什么只应该作为临时 reminder 或 attachment
+
+只要这三层边界清楚，读者就已经能自己搭出一条可靠输入管道。  
+更细的 cache scope、attachment 去重和大结果外置，都可以放到后续扩展里再补。
+
+## 一句话记住
+
+**真正送给模型的，不只是一个 prompt，而是“prompt blocks + normalized messages + attachments + reminders”组成的输入管道。**
diff --git a/docs/zh/s11-autonomous-agents.md b/docs/zh/s11-autonomous-agents.md
deleted file mode 100644
index b1f51278b..000000000
--- a/docs/zh/s11-autonomous-agents.md
+++ /dev/null
@@ -1,144 +0,0 @@
-# s11: Autonomous Agents (Autonomous Agent)
-
-`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > [ s11 ] s12`
-
-> *"队友自己看看板, 有活就认领"* -- 不需要领导逐个分配, 自组织。
->
-> **Harness 层**: 自治 -- 模型自己找活干, 无需指派。
-
-## 问题
-
-s09-s10 中, 队友只在被明确指派时才动。领导得给每个队友写 prompt, 任务看板上 10 个未认领的任务得手动分配。这扩展不了。
-
-真正的自治: 队友自己扫描任务看板, 认领没人做的任务, 做完再找下一个。
-
-一个细节: Context Compact (s06) 后 Agent 可能忘了自己是谁。身份重注入解决这个问题。
-
-## 解决方案
-
-```
-Teammate lifecycle with idle cycle:
-
-+-------+
-| spawn |
-+---+---+
-    |
-    v
-+-------+   tool_use     +-------+
-| WORK  | <------------- |  LLM  |
-+---+---+                +-------+
-    |
-    | stop_reason != tool_use (or idle tool called)
-    v
-+--------+
-|  IDLE  |  poll every 5s for up to 60s
-+---+----+
-    |
-    +---> check inbox --> message? ----------> WORK
-    |
-    +---> scan .tasks/ --> unclaimed? -------> claim -> WORK
-    |
-    +---> 60s timeout ----------------------> SHUTDOWN
-
-Identity re-injection after compression:
-  if len(messages) <= 3:
-    messages.insert(0, identity_block)
-```
-
-## 工作原理
-
-1. 队友循环分两个阶段: WORK 和 IDLE。LLM 停止调用工具 (或调用了 `idle`) 时, 进入 IDLE。
-
-```python
-def _loop(self, name, role, prompt):
-    while True:
-        # -- WORK PHASE --
-        messages = [{"role": "user", "content": prompt}]
-        for _ in range(50):
-            response = client.messages.create(...)
-            if response.stop_reason != "tool_use":
-                break
-            # execute tools...
-            if idle_requested:
-                break
-
-        # -- IDLE PHASE --
-        self._set_status(name, "idle")
-        resume = self._idle_poll(name, messages)
-        if not resume:
-            self._set_status(name, "shutdown")
-            return
-        self._set_status(name, "working")
-```
-
-2. 空闲阶段循环轮询收件箱和任务看板。
-
-```python
-def _idle_poll(self, name, messages):
-    for _ in range(IDLE_TIMEOUT // POLL_INTERVAL):  # 60s / 5s = 12
-        time.sleep(POLL_INTERVAL)
-        inbox = BUS.read_inbox(name)
-        if inbox:
-            messages.append({"role": "user",
-                "content": f"<inbox>{inbox}</inbox>"})
-            return True
-        unclaimed = scan_unclaimed_tasks()
-        if unclaimed:
-            claim_task(unclaimed[0]["id"], name)
-            messages.append({"role": "user",
-                "content": f"<auto-claimed>Task #{unclaimed[0]['id']}: "
-                           f"{unclaimed[0]['subject']}</auto-claimed>"})
-            return True
-    return False  # timeout -> shutdown
-```
-
-3. 任务看板扫描: 找 pending 状态、无 owner、未被阻塞的任务。
-
-```python
-def scan_unclaimed_tasks() -> list:
-    unclaimed = []
-    for f in sorted(TASKS_DIR.glob("task_*.json")):
-        task = json.loads(f.read_text())
-        if (task.get("status") == "pending"
-                and not task.get("owner")
-                and not task.get("blockedBy")):
-            unclaimed.append(task)
-    return unclaimed
-```
-
-4. 身份重注入: 上下文过短 (说明发生了压缩) 时, 在开头插入身份块。
-
-```python
-if len(messages) <= 3:
-    messages.insert(0, {"role": "user",
-        "content": f"<identity>You are '{name}', role: {role}, "
-                   f"team: {team_name}. Continue your work.</identity>"})
-    messages.insert(1, {"role": "assistant",
-        "content": f"I am {name}. Continuing."})
-```
-
-## 相对 s10 的变更
-
-| 组件           | 之前 (s10)       | 之后 (s11)                       |
-|----------------|------------------|----------------------------------|
-| Tools          | 12               | 14 (+idle, +claim_task)          |
-| 自治性         | 领导指派         | 自组织                           |
-| 空闲阶段       | 无               | 轮询收件箱 + 任务看板            |
-| 任务认领       | 仅手动           | 自动认领未分配任务               |
-| 身份           | 系统提示         | + 压缩后重注入                   |
-| 超时           | 无               | 60 秒空闲 -> 自动关机            |
-
-## 试一试
-
-```sh
-cd learn-claude-code
-python agents/s11_autonomous_agents.py
-```
-
-试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):
-
-1. `Create 3 tasks on the board, then spawn alice and bob. Watch them auto-claim.`
-2. `Spawn a coder teammate and let it find work from the task board itself`
-3. `Create tasks with dependencies. Watch teammates respect the blocked order.`
-4. 输入 `/tasks` 查看带 owner 的任务看板
-5. 输入 `/team` 监控谁在工作、谁在空闲
diff --git a/docs/zh/s11-error-recovery.md b/docs/zh/s11-error-recovery.md
new file mode 100644
index 000000000..81da62625
--- /dev/null
+++ b/docs/zh/s11-error-recovery.md
@@ -0,0 +1,391 @@
+# s11: Error Recovery (错误恢复)
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > [ s11 ] > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`
+
+> *错误不是例外，而是主循环必须预留出来的一条正常分支。*
+
+## 这一章要解决什么问题
+
+到了 `s10`，你的 agent 已经有了：
+
+- 主循环
+- 工具调用
+- 规划
+- 上下文压缩
+- 权限、hook、memory、system prompt
+
+这时候系统已经不再是一个“只会聊天”的 demo，而是一个真的在做事的程序。
+
+问题也随之出现：
+
+- 模型输出写到一半被截断
+- 上下文太长，请求直接失败
+- 网络暂时抖动，API 超时或限流
+
+如果没有恢复机制，主循环会在第一个错误上直接停住。  
+这对初学者很危险，因为他们会误以为“agent 不稳定是模型的问题”。
+
+实际上，很多失败并不是“任务真的失败了”，而只是：
+
+**这一轮需要换一种继续方式。**
+
+所以这一章的目标只有一个：
+
+**把“报错就崩”升级成“先判断错误类型，再选择恢复路径”。**
+
+## 建议联读
+
+- 如果你开始分不清“为什么这一轮还在继续”，先回 [`s00c-query-transition-model.md`](./s00c-query-transition-model.md)，重新确认 transition reason 为什么是独立状态。
+- 如果你在恢复逻辑里又把上下文压缩和错误恢复混成一团，建议顺手回看 [`s06-context-compact.md`](./s06-context-compact.md)，区分“为了缩上下文而压缩”和“因为失败而恢复”。
+- 如果你准备继续往 `s12` 走，建议把 [`data-structures.md`](./data-structures.md) 放在旁边，因为后面任务系统会在“恢复状态之外”再引入新的 durable work 状态。
+
+## 先解释几个名词
+
+### 什么叫恢复
+
+恢复，不是把所有错误都藏起来。
+
+恢复的意思是：
+
+- 先判断这是不是临时问题
+- 如果是，就尝试一个有限次数的补救动作
+- 如果补救失败，再把失败明确告诉用户
+
+### 什么叫重试预算
+
+重试预算，就是“最多试几次”。
+
+比如：
+
+- 续写最多 3 次
+- 网络重连最多 3 次
+
+如果没有这个预算，程序就可能无限循环。
+
+### 什么叫状态机
+
+状态机这个词听起来很大，其实意思很简单：
+
+> 一个东西会在几个明确状态之间按规则切换。
+
+在这一章里，主循环就从“普通执行”变成了：
+
+- 正常执行
+- 续写恢复
+- 压缩恢复
+- 退避重试
+- 最终失败
+
+## 最小心智模型
+
+不要把错误恢复想得太神秘。
+
+教学版只需要先区分 3 类问题：
+
+```text
+1. 输出被截断
+   模型还没说完，但 token 用完了
+
+2. 上下文太长
+   请求装不进模型窗口了
+
+3. 临时连接失败
+   网络、超时、限流、服务抖动
+```
+
+对应 3 条恢复路径：
+
+```text
+LLM call
+  |
+  +-- stop_reason == "max_tokens"
+  |      -> 注入续写提示
+  |      -> 再试一次
+  |
+  +-- prompt too long
+  |      -> 压缩旧上下文
+  |      -> 再试一次
+  |
+  +-- timeout / rate limit / transient API error
+         -> 等一会儿
+         -> 再试一次
+```
+
+这就是最小但正确的恢复模型。
+
+## 关键数据结构
+
+### 1. 恢复状态
+
+```python
+recovery_state = {
+    "continuation_attempts": 0,
+    "compact_attempts": 0,
+    "transport_attempts": 0,
+}
+```
+
+它的作用不是“记录一切”，而是：
+
+- 防止无限重试
+- 让每种恢复路径各算各的次数
+
+### 2. 恢复决策
+
+```python
+{
+    "kind": "continue" | "compact" | "backoff" | "fail",
+    "reason": "why this branch was chosen",
+}
+```
+
+把“错误长什么样”和“接下来怎么做”分开，会更清楚。
+
+### 3. 续写提示
+
+```python
+CONTINUE_MESSAGE = (
+    "Output limit hit. Continue directly from where you stopped. "
+    "Do not restart or repeat."
+)
+```
+
+这条提示非常重要。
+
+因为如果你只说“继续”，模型经常会：
+
+- 重新总结
+- 重新开头
+- 重复已经输出过的内容
+
+## 最小实现
+
+先写一个恢复选择器：
+
+```python
+def choose_recovery(stop_reason: str | None, error_text: str | None) -> dict:
+    if stop_reason == "max_tokens":
+        return {"kind": "continue", "reason": "output truncated"}
+
+    if error_text and "prompt" in error_text and "long" in error_text:
+        return {"kind": "compact", "reason": "context too large"}
+
+    if error_text and any(word in error_text for word in [
+        "timeout", "rate", "unavailable", "connection"
+    ]):
+        return {"kind": "backoff", "reason": "transient transport failure"}
+
+    return {"kind": "fail", "reason": "unknown or non-recoverable error"}
+```
+
+再把它接进主循环：
+
+```python
+while True:
+    try:
+        response = client.messages.create(...)
+        decision = choose_recovery(response.stop_reason, None)
+    except Exception as e:
+        response = None
+        decision = choose_recovery(None, str(e).lower())
+
+    if decision["kind"] == "continue":
+        messages.append({"role": "user", "content": CONTINUE_MESSAGE})
+        continue
+
+    if decision["kind"] == "compact":
+        messages = auto_compact(messages)
+        continue
+
+    if decision["kind"] == "backoff":
+        time.sleep(backoff_delay(...))
+        continue
+
+    if decision["kind"] == "fail":
+        break
+
+    # 正常工具处理
+```
+
+注意这里的重点不是代码花哨，而是：
+
+- 先分类
+- 再选动作
+- 每条动作有自己的预算
+
+## 三条恢复路径分别在补什么洞
+
+### 路径 1：输出被截断时，做续写
+
+这个问题的本质不是“模型不会”，而是“这一轮输出空间不够”。
+
+所以最小补法是：
+
+1. 追加一条续写消息
+2. 告诉模型不要重来，不要重复
+3. 让主循环继续
+
+```python
+if response.stop_reason == "max_tokens":
+    if state["continuation_attempts"] >= 3:
+        return "Error: output recovery exhausted"
+    state["continuation_attempts"] += 1
+    messages.append({"role": "user", "content": CONTINUE_MESSAGE})
+    continue
+```
+
+### 路径 2：上下文太长时，先压缩再重试
+
+这里要先明确一点：
+
+压缩不是“把历史删掉”，而是：
+
+**把旧对话从原文，变成一份仍然可继续工作的摘要。**
+
+最小压缩结果建议至少保留：
+
+- 当前任务是什么
+- 已经做了什么
+- 关键决定是什么
+- 下一步准备做什么
+
+```python
+def auto_compact(messages: list) -> list:
+    summary = summarize_messages(messages)
+    return [{
+        "role": "user",
+        "content": "This session was compacted. Continue from this summary:\n" + summary,
+    }]
+```
+
+### 路径 3：连接抖动时，退避重试
+
+“退避”这个词的意思是：
+
+> 别立刻再打一次，而是等一小会儿再试。
+
+为什么要等？
+
+因为这类错误往往是临时拥堵：
+
+- 刚超时
+- 刚限流
+- 服务器刚好抖了一下
+
+如果你瞬间连续重打，只会更容易失败。
+
+```python
+def backoff_delay(attempt: int) -> float:
+    return min(1.0 * (2 ** attempt), 30.0) + random.uniform(0, 1)
+```
+
+## 如何接到主循环里
+
+最干净的接法，是把恢复逻辑放在两个位置：
+
+### 位置 1：模型调用外层
+
+负责处理：
+
+- API 报错
+- 网络错误
+- 超时
+
+### 位置 2：拿到 response 以后
+
+负责处理：
+
+- `stop_reason == "max_tokens"`
+- 正常的 `tool_use`
+- 正常的结束
+
+也就是说，主循环现在不只是“调模型 -> 执行工具”，而是：
+
+```text
+1. 调模型
+2. 如果调用报错，判断是否可以恢复
+3. 如果拿到响应，判断是否被截断
+4. 如果需要恢复，就修改 messages 或等待
+5. 如果不需要恢复，再进入正常工具分支
+```
+
+## 初学者最容易犯的错
+
+### 1. 把所有错误都当成一种错误
+
+这样会导致：
+
+- 该续写的去压缩
+- 该等待的去重试
+- 该失败的却无限拖延
+
+### 2. 没有重试预算
+
+没有预算，主循环就可能永远卡在“继续”“继续”“继续”。
+
+### 3. 续写提示写得太模糊
+
+只写一个“continue”通常不够。  
+你要明确告诉模型：
+
+- 不要重复
+- 不要重新总结
+- 直接从中断点接着写
+
+### 4. 压缩后没有告诉模型“这是续场”
+
+如果压缩后只给一份摘要，不告诉模型“这是前文摘要”，模型很可能重新向用户提问。
+
+### 5. 恢复过程完全没有日志
+
+教学系统最好打印类似：
+
+- `[Recovery] continue`
+- `[Recovery] compact`
+- `[Recovery] backoff`
+
+这样读者才看得见主循环到底做了什么。
+
+## 这一章和前后章节怎么衔接
+
+- `s06` 讲的是“什么时候该压缩”
+- `s10` 讲的是“系统提示词怎么组装”
+- `s11` 讲的是“当执行失败时，主循环怎么续下去”
+- `s12` 开始，恢复机制会保护更长、更复杂的任务流
+
+所以 `s11` 的位置非常关键。
+
+它不是外围小功能，而是：
+
+**把 agent 从“能跑”推进到“遇到问题也能继续跑”。**
+
+## 教学边界
+
+这一章先把 3 条最小恢复路径讲稳就够了：
+
+- 输出截断后续写
+- 上下文过长后压缩再试
+- 请求抖动后退避重试
+
+对教学主线来说，重点不是把所有“为什么继续下一轮”的原因一次讲全，而是先让读者明白：
+
+**恢复不是简单 try/except，而是系统知道该怎么续下去。**
+
+更大的 query 续行模型、预算续行、hook 介入这些内容，应该放回控制平面的桥接文档里看，而不是抢掉这章主线。
+
+## 试一试
+
+```sh
+cd learn-claude-code
+python agents/s11_error_recovery.py
+```
+
+可以试试这些任务：
+
+1. 让模型生成一段特别长的内容，观察它是否会自动续写。
+2. 连续读取一些大文件，观察上下文压缩是否会介入。
+3. 临时制造一次请求失败，观察系统是否会退避重试。
+
+读这一章时，你真正要记住的不是某个具体异常名，而是这条主线：
+
+**错误先分类，恢复再执行，失败最后才暴露给用户。**
diff --git a/docs/zh/s12-task-system.md b/docs/zh/s12-task-system.md
new file mode 100644
index 000000000..10b68f172
--- /dev/null
+++ b/docs/zh/s12-task-system.md
@@ -0,0 +1,349 @@
+# s12: Task System (任务系统)
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > [ s12 ] > s13 > s14 > s15 > s16 > s17 > s18 > s19`
+
+> *Todo 只能提醒你“有事要做”，任务系统才能告诉你“先做什么、谁在等谁、哪一步还卡着”。*
+
+## 这一章要解决什么问题
+
+`s03` 的 todo 已经能帮 agent 把大目标拆成几步。
+
+但 todo 仍然有两个明显限制：
+
+- 它更像当前会话里的临时清单
+- 它不擅长表达“谁先谁后、谁依赖谁”
+
+例如下面这组工作：
+
+```text
+1. 先写解析器
+2. 再写语义检查
+3. 测试和文档可以并行
+4. 最后整体验收
+```
+
+这已经不是单纯的列表，而是一张“依赖关系图”。
+
+如果没有专门的任务系统，agent 很容易出现这些问题：
+
+- 前置工作没做完，就贸然开始后面的任务
+- 某个任务完成以后，不知道解锁了谁
+- 多个 agent 协作时，没有统一任务板可读
+
+所以这一章要做的升级是：
+
+**把“会话里的 todo”升级成“可持久化的任务图”。**
+
+## 建议联读
+
+- 如果你刚从 `s03` 过来，先回 [`data-structures.md`](./data-structures.md)，重新确认 `TodoItem / PlanState` 和 `TaskRecord` 不是同一层状态。
+- 如果你开始把“对象边界”读混，先回 [`entity-map.md`](./entity-map.md)，把 message、task、runtime task、teammate 这几层拆开。
+- 如果你准备继续读 `s13`，建议把 [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) 先放在手边，因为从这里开始最容易把 durable task 和 runtime task 混成一个词。
+
+## 先把几个词讲明白
+
+### 什么是任务
+
+这里的 `task` 指的是：
+
+> 一个可以被跟踪、被分配、被完成、被阻塞的小工作单元。
+
+它不是整段用户需求，而是用户需求拆出来的一小块工作。
+
+### 什么是依赖
+
+依赖的意思是：
+
+> 任务 B 必须等任务 A 完成，才能开始。
+
+### 什么是任务图
+
+任务图就是：
+
+> 任务节点 + 依赖连线
+
+你可以把它理解成：
+
+- 点：每个任务
+- 线：谁依赖谁
+
+### 什么是 ready
+
+`ready` 的意思很简单：
+
+> 这条任务现在已经满足开工条件。
+
+也就是：
+
+- 自己还没开始
+- 前置依赖已经全部完成
+
+## 最小心智模型
+
+本章最重要的，不是复杂调度算法，而是先回答 4 个问题：
+
+1. 现在有哪些任务？
+2. 每个任务是什么状态？
+3. 哪些任务还被卡住？
+4. 哪些任务已经可以开始？
+
+只要这 4 个问题能稳定回答，一个最小任务系统就已经成立了。
+
+## 关键数据结构
+
+### 1. TaskRecord
+
+```python
+task = {
+    "id": 1,
+    "subject": "Write parser",
+    "description": "",
+    "status": "pending",
+    "blockedBy": [],
+    "blocks": [],
+    "owner": "",
+}
+```
+
+每个字段都对应一个很实用的问题：
+
+- `id`：怎么唯一找到这条任务
+- `subject`：这条任务一句话在做什么
+- `description`：还有哪些补充说明
+- `status`：现在走到哪一步
+- `blockedBy`：还在等谁
+- `blocks`：它完成后会解锁谁
+- `owner`：现在由谁来做
+
+### 2. TaskStatus
+
+教学版先只保留最少 4 个状态：
+
+```text
+pending -> in_progress -> completed
+deleted
+```
+
+解释如下：
+
+- `pending`：还没开始
+- `in_progress`：已经有人在做
+- `completed`：已经做完
+- `deleted`：逻辑删除，不再参与工作流
+
+### 3. Ready Rule
+
+这是本章最关键的一条判断规则：
+
+```python
+def is_ready(task: dict) -> bool:
+    return task["status"] == "pending" and not task["blockedBy"]
+```
+
+如果你把这条规则讲明白，读者就会第一次真正明白：
+
+**任务系统的核心不是“保存清单”，而是“判断什么时候能开工”。**
+
+## 最小实现
+
+### 第一步：让任务落盘
+
+不要只把任务放在 `messages` 里。  
+教学版最简单的做法，就是“一任务一文件”：
+
+```text
+.tasks/
+  task_1.json
+  task_2.json
+  task_3.json
+```
+
+创建任务时，直接写成一条 JSON 记录：
+
+```python
+class TaskManager:
+    def create(self, subject: str, description: str = "") -> dict:
+        task = {
+            "id": self._next_id(),
+            "subject": subject,
+            "description": description,
+            "status": "pending",
+            "blockedBy": [],
+            "blocks": [],
+            "owner": "",
+        }
+        self._save(task)
+        return task
+```
+
+### 第二步：把依赖关系写成双向
+
+如果任务 A 完成后会解锁任务 B，最好同时维护两边：
+
+- A 的 `blocks` 里有 B
+- B 的 `blockedBy` 里有 A
+
+```python
+def add_dependency(self, task_id: int, blocks_id: int):
+    task = self._load(task_id)
+    blocked = self._load(blocks_id)
+
+    if blocks_id not in task["blocks"]:
+        task["blocks"].append(blocks_id)
+    if task_id not in blocked["blockedBy"]:
+        blocked["blockedBy"].append(task_id)
+
+    self._save(task)
+    self._save(blocked)
+```
+
+这样做的好处是：
+
+- 从前往后读得懂
+- 从后往前也读得懂
+
+### 第三步：完成任务时自动解锁后续任务
+
+```python
+def complete(self, task_id: int):
+    task = self._load(task_id)
+    task["status"] = "completed"
+    self._save(task)
+
+    for other in self._all_tasks():
+        if task_id in other["blockedBy"]:
+            other["blockedBy"].remove(task_id)
+            self._save(other)
+```
+
+这一步非常关键。
+
+因为它说明：
+
+**任务系统不是静态记录表，而是会随着完成事件自动推进的工作图。**
+
+### 第四步：把任务工具接给模型
+
+教学版最小工具集建议先只做这 4 个：
+
+- `task_create`
+- `task_update`
+- `task_get`
+- `task_list`
+
+这样模型就能：
+
+- 新建任务
+- 更新状态
+- 看单条任务
+- 看整张任务板
+
+## 如何接到主循环里
+
+从 `s12` 开始，主循环第一次拥有了“会话外状态”。
+
+典型流程是：
+
+```text
+用户提出复杂目标
+  ->
+模型决定先拆任务
+  ->
+调用 task_create / task_update
+  ->
+任务落到 .tasks/
+  ->
+后续轮次继续读取并推进
+```
+
+这里要牢牢记住一句话：
+
+**todo 更像本轮计划，task 更像长期工作板。**
+
+## 这一章和 s03、s13 的边界
+
+这一层边界必须讲清楚，不然后面一定会混。
+
+### 和 `s03` 的区别
+
+| 机制 | 更适合什么 |
+|---|---|
+| `todo` | 当前会话里快速列步骤 |
+| `task` | 持久化工作、依赖关系、多人协作 |
+
+如果只是“先看文件，再改代码，再跑测试”，todo 往往就够。  
+如果是“跨很多轮、多人协作、还要管依赖”，就要上 task。
+
+### 和 `s13` 的区别
+
+本章的 `task` 指的是：
+
+> 一条工作目标
+
+它回答的是：
+
+- 要做什么
+- 现在做到哪一步
+- 谁在等谁
+
+它不是：
+
+- 某个正在后台跑的 `pytest`
+- 某个正在执行的 worker
+- 某条当前活着的执行线程
+
+后面这些属于下一章要讲的：
+
+> 运行中的执行任务
+
+## 初学者最容易犯的错
+
+### 1. 只会创建任务，不会维护依赖
+
+那最后得到的还是一张普通清单，不是任务图。
+
+### 2. 任务只放内存，不落盘
+
+系统一重启，整个工作结构就没了。
+
+### 3. 完成任务后不自动解锁后续任务
+
+这样系统永远不知道下一步谁可以开工。
+
+### 4. 把工作目标和运行中的执行混成一层
+
+这会导致后面 `s13` 的后台任务系统很难讲清。
+
+## 教学边界
+
+这一章先要守住的，不是任务平台以后还能长出多少管理功能，而是任务记录本身的最小主干：
+
+- `TaskRecord`
+- 依赖关系
+- 持久化
+- 就绪判断
+
+只要读者已经能把 todo 和 task、工作目标和运行执行明确分开，并且能手写一个会解锁后续任务的最小任务图，这章就已经讲到位了。
+
+## 学完这一章，你应该真正掌握什么
+
+学完以后，你应该能独立说清这几件事：
+
+1. 任务系统比 todo 多出来的核心能力，是“依赖关系”和“持久化”。
+2. `TaskRecord` 是本章最关键的数据结构。
+3. `blockedBy` / `blocks` 让系统能看懂前后关系。
+4. `is_ready()` 让系统能判断“谁现在可以开始”。
+
+如果这 4 件事都已经清楚，说明你已经能从 0 到 1 手写一个最小任务系统。
+
+## 下一章学什么
+
+这一章解决的是：
+
+> 工作目标如何被长期组织。
+
+下一章 `s13` 要解决的是：
+
+> 某个慢命令正在后台跑时，主循环怎么继续前进。
+
+也就是从“工作图”走向“运行时执行层”。
diff --git a/docs/zh/s12-worktree-task-isolation.md b/docs/zh/s12-worktree-task-isolation.md
deleted file mode 100644
index 31bddba23..000000000
--- a/docs/zh/s12-worktree-task-isolation.md
+++ /dev/null
@@ -1,123 +0,0 @@
-# s12: Worktree + Task Isolation (Worktree 任务隔离)
-
-`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > [ s12 ]`
-
-> *"各干各的目录, 互不干扰"* -- 任务管目标, worktree 管目录, 按 ID 绑定。
->
-> **Harness 层**: 目录隔离 -- 永不碰撞的并行执行通道。
-
-## 问题
-
-到 s11, Agent 已经能自主认领和完成任务。但所有任务共享一个目录。两个 Agent 同时重构不同模块 -- A 改 `config.py`, B 也改 `config.py`, 未提交的改动互相污染, 谁也没法干净回滚。
-
-任务板管 "做什么" 但不管 "在哪做"。解法: 给每个任务一个独立的 git worktree 目录, 用任务 ID 把两边关联起来。
-
-## 解决方案
-
-```
-Control plane (.tasks/)             Execution plane (.worktrees/)
-+------------------+                +------------------------+
-| task_1.json      |                | auth-refactor/         |
-|   status: in_progress  <------>   branch: wt/auth-refactor
-|   worktree: "auth-refactor"   |   task_id: 1             |
-+------------------+                +------------------------+
-| task_2.json      |                | ui-login/              |
-|   status: pending    <------>     branch: wt/ui-login
-|   worktree: "ui-login"       |   task_id: 2             |
-+------------------+                +------------------------+
-                                    |
-                          index.json (worktree registry)
-                          events.jsonl (lifecycle log)
-
-State machines:
-  Task:     pending -> in_progress -> completed
-  Worktree: absent  -> active      -> removed | kept
-```
-
-## 工作原理
-
-1. **创建任务。** 先把目标持久化。
-
-```python
-TASKS.create("Implement auth refactor")
-# -> .tasks/task_1.json  status=pending  worktree=""
-```
-
-2. **创建 worktree 并绑定任务。** 传入 `task_id` 自动将任务推进到 `in_progress`。
-
-```python
-WORKTREES.create("auth-refactor", task_id=1)
-# -> git worktree add -b wt/auth-refactor .worktrees/auth-refactor HEAD
-# -> index.json gets new entry, task_1.json gets worktree="auth-refactor"
-```
-
-绑定同时写入两侧状态:
-
-```python
-def bind_worktree(self, task_id, worktree):
-    task = self._load(task_id)
-    task["worktree"] = worktree
-    if task["status"] == "pending":
-        task["status"] = "in_progress"
-    self._save(task)
-```
-
-3. **在 worktree 中执行命令。** `cwd` 指向隔离目录。
-
-```python
-subprocess.run(command, shell=True, cwd=worktree_path,
-               capture_output=True, text=True, timeout=300)
-```
-
-4. **收尾。** 两种选择:
-   - `worktree_keep(name)` -- 保留目录供后续使用。
-   - `worktree_remove(name, complete_task=True)` -- 删除目录, 完成绑定任务, 发出事件。一个调用搞定拆除 + 完成。
-
-```python
-def remove(self, name, force=False, complete_task=False):
-    self._run_git(["worktree", "remove", wt["path"]])
-    if complete_task and wt.get("task_id") is not None:
-        self.tasks.update(wt["task_id"], status="completed")
-        self.tasks.unbind_worktree(wt["task_id"])
-        self.events.emit("task.completed", ...)
-```
-
-5. **事件流。** 每个生命周期步骤写入 `.worktrees/events.jsonl`:
-
-```json
-{
-  "event": "worktree.remove.after",
-  "task": {"id": 1, "status": "completed"},
-  "worktree": {"name": "auth-refactor", "status": "removed"},
-  "ts": 1730000000
-}
-```
-
-事件类型: `worktree.create.before/after/failed`, `worktree.remove.before/after/failed`, `worktree.keep`, `task.completed`。
-
-崩溃后从 `.tasks/` + `.worktrees/index.json` 重建现场。会话记忆是易失的; 磁盘状态是持久的。
-
-## 相对 s11 的变更
-
-| 组件               | 之前 (s11)                 | 之后 (s12)                                   |
-|--------------------|----------------------------|----------------------------------------------|
-| 协调               | 任务板 (owner/status)      | 任务板 + worktree 显式绑定                   |
-| 执行范围           | 共享目录                   | 每个任务独立目录                             |
-| 可恢复性           | 仅任务状态                 | 任务状态 + worktree 索引                     |
-| 收尾               | 任务完成                   | 任务完成 + 显式 keep/remove                  |
-| 生命周期可见性     | 隐式日志                   | `.worktrees/events.jsonl` 显式事件流         |
-
-## 试一试
-
-```sh
-cd learn-claude-code
-python agents/s12_worktree_task_isolation.py
-```
-
-试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):
-
-1. `Create tasks for backend auth and frontend login page, then list tasks.`
-2. `Create worktree "auth-refactor" for task 1, then bind task 2 to a new worktree "ui-login".`
-3. `Run "git status --short" in worktree "auth-refactor".`
-4. `Keep worktree "ui-login", then list worktrees and inspect events.`
-5. `Remove worktree "auth-refactor" with complete_task=true, then list tasks/worktrees/events.`
diff --git a/docs/zh/s13-background-tasks.md b/docs/zh/s13-background-tasks.md
new file mode 100644
index 000000000..0327565a6
--- /dev/null
+++ b/docs/zh/s13-background-tasks.md
@@ -0,0 +1,367 @@
+# s13: Background Tasks (后台任务)
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > [ s13 ] > s14 > s15 > s16 > s17 > s18 > s19`
+
+> *慢命令可以在旁边等，主循环不必陪着发呆。*
+
+## 这一章要解决什么问题
+
+前面几章里，工具调用基本都是：
+
+```text
+模型发起
+  ->
+立刻执行
+  ->
+立刻返回结果
+```
+
+这对短命令没有问题。  
+但一旦遇到这些慢操作，就会卡住：
+
+- `npm install`
+- `pytest`
+- `docker build`
+- 大型代码生成或检查任务
+
+如果主循环一直同步等待，会出现两个坏处：
+
+- 模型在等待期间什么都做不了
+- 用户明明还想继续别的工作，却被整轮流程堵住
+
+所以这一章要解决的是：
+
+**把“慢执行”移到后台，让主循环继续推进别的事情。**
+
+## 建议联读
+
+- 如果你还没有彻底稳住“任务目标”和“执行槽位”是两层对象，先看 [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)。
+- 如果你开始分不清哪些状态该落在 `RuntimeTaskRecord`、哪些还应留在任务板，回看 [`data-structures.md`](./data-structures.md)。
+- 如果你开始把后台执行理解成“另一条主循环”，先看 [`s02b-tool-execution-runtime.md`](./s02b-tool-execution-runtime.md)，重新校正“并行的是执行与等待，不是主循环本身”。
+
+## 先把几个词讲明白
+
+### 什么叫前台
+
+前台指的是：
+
+> 主循环这轮发起以后，必须立刻等待结果的执行路径。
+
+### 什么叫后台
+
+后台不是神秘系统。  
+后台只是说：
+
+> 命令先在另一条执行线上跑，主循环先去做别的事。
+
+### 什么叫通知队列
+
+通知队列就是一条“稍后再告诉主循环”的收件箱。
+
+后台任务完成以后，不是直接把全文硬塞回模型，  
+而是先写一条摘要通知，等下一轮再统一带回去。
+
+## 最小心智模型
+
+这一章最关键的句子是：
+
+**主循环仍然只有一条，并行的是等待，不是主循环本身。**
+
+可以把结构画成这样：
+
+```text
+主循环
+  |
+  +-- background_run("pytest")
+  |      -> 立刻返回 task_id
+  |
+  +-- 继续别的工作
+  |
+  +-- 下一轮模型调用前
+         -> drain_notifications()
+         -> 把摘要注入 messages
+
+后台执行线
+  |
+  +-- 真正执行 pytest
+  +-- 完成后写入通知队列
+```
+
+如果读者能牢牢记住这张图，后面扩展成更复杂的异步系统也不会乱。
+
+## 关键数据结构
+
+### 1. RuntimeTaskRecord
+
+```python
+task = {
+    "id": "a1b2c3d4",
+    "command": "pytest",
+    "status": "running",
+    "started_at": 1710000000.0,
+    "result_preview": "",
+    "output_file": "",
+}
+```
+
+这些字段分别表示：
+
+- `id`：唯一标识
+- `command`：正在跑什么命令
+- `status`：运行中、完成、失败、超时
+- `started_at`：什么时候开始
+- `result_preview`：先给模型看的简短摘要
+- `output_file`：完整输出写到了哪里
+
+教学版再往前走一步时，建议把它直接落成两份文件：
+
+```text
+.runtime-tasks/
+  a1b2c3d4.json   # RuntimeTaskRecord
+  a1b2c3d4.log    # 完整输出
+```
+
+这样读者会更容易理解：
+
+- `json` 记录的是运行状态
+- `log` 保存的是完整产物
+- 通知只负责把 `preview` 带回主循环
+
+### 2. Notification
+
+```python
+notification = {
+    "type": "background_completed",
+    "task_id": "a1b2c3d4",
+    "status": "completed",
+    "preview": "tests passed",
+}
+```
+
+通知只负责做一件事：
+
+> 告诉主循环“有结果回来了，你要不要看”。
+
+它不是完整日志本体。
+
+## 最小实现
+
+### 第一步：登记后台任务
+
+```python
+class BackgroundManager:
+    def __init__(self):
+        self.tasks = {}
+        self.notifications = []
+        self.lock = threading.Lock()
+```
+
+这里最少要有两块状态：
+
+- `tasks`：当前有哪些后台任务
+- `notifications`：哪些结果已经回来，等待主循环领取
+
+### 第二步：启动后台执行线
+
+“线程”这个词第一次见可能会有点紧张。  
+你可以先把它理解成：
+
+> 同一个程序里，另一条可以独立往前跑的执行线。
+
+```python
+def run(self, command: str) -> str:
+    task_id = new_id()
+    self.tasks[task_id] = {
+        "id": task_id,
+        "command": command,
+        "status": "running",
+    }
+
+    thread = threading.Thread(
+        target=self._execute,
+        args=(task_id, command),
+        daemon=True,
+    )
+    thread.start()
+    return task_id
+```
+
+这一步最重要的不是线程本身，而是：
+
+**主循环拿到 `task_id` 后就可以先继续往前走。**
+
+### 第三步：完成后写通知
+
+```python
+def _execute(self, task_id: str, command: str):
+    try:
+        result = subprocess.run(..., timeout=300)
+        status = "completed"
+        preview = (result.stdout + result.stderr)[:500]
+    except subprocess.TimeoutExpired:
+        status = "timeout"
+        preview = "command timed out"
+
+    with self.lock:
+        self.tasks[task_id]["status"] = status
+        self.notifications.append({
+            "type": "background_completed",
+            "task_id": task_id,
+            "status": status,
+            "preview": preview,
+        })
+```
+
+这里体现的思想很重要：
+
+**后台执行负责产出结果，通知队列负责把结果送回主循环。**
+
+### 第四步：下一轮前排空通知
+
+```python
+def before_model_call(messages: list):
+    notifications = bg.drain_notifications()
+    if not notifications:
+        return
+
+    text = "\n".join(
+        f"[bg:{n['task_id']}] {n['status']} - {n['preview']}"
+        for n in notifications
+    )
+    messages.append({"role": "user", "content": text})
+```
+
+这样模型在下一轮就会知道：
+
+- 哪个后台任务完成了
+- 是成功、失败还是超时
+- 如果要看全文，该再去读文件
+
+## 为什么完整输出不要直接塞回 prompt
+
+这是本章必须讲透的点。
+
+如果后台任务输出几万行日志，你不能每次都把全文塞回上下文。  
+更稳的做法是：
+
+1. 完整输出写磁盘
+2. 通知里只放简短摘要
+3. 模型真的要看全文时，再调用 `read_file`
+
+这背后的心智很重要：
+
+**通知负责提醒，文件负责存原文。**
+
+## 如何接到主循环里
+
+从 `s13` 开始，主循环多出一个标准前置步骤：
+
+```text
+1. 先排空通知队列
+2. 再调用模型
+3. 普通工具照常同步执行
+4. 如果模型调用 background_run，就登记后台任务并立刻返回 task_id
+5. 下一轮再把后台结果带回模型
+```
+
+教学版最小工具建议先做两个：
+
+- `background_run`
+- `background_check`
+
+这样已经足够支撑最小异步执行闭环。
+
+## 这一章和任务系统的边界
+
+这是本章最容易和 `s12` 混掉的地方。
+
+### `s12` 的 task 是什么
+
+`s12` 里的 `task` 是：
+
+> 工作目标
+
+它关心的是：
+
+- 要做什么
+- 谁依赖谁
+- 现在总体进度如何
+
+### `s13` 的 background task 是什么
+
+本章里的后台任务是：
+
+> 正在运行的执行单元
+
+它关心的是：
+
+- 哪个命令正在跑
+- 跑到什么状态
+- 结果什么时候回来
+
+所以最稳的记法是：
+
+- `task` 更像工作板
+- `background task` 更像运行中的作业
+
+两者相关，但不是同一个东西。
+
+## 初学者最容易犯的错
+
+### 1. 以为“后台”就是更复杂的主循环
+
+不是。  
+主循环仍然尽量保持单主线。
+
+### 2. 只开线程，不登记状态
+
+这样任务一多，你根本不知道：
+
+- 谁还在跑
+- 谁已经完成
+- 谁失败了
+
+### 3. 把长日志全文塞进上下文
+
+上下文很快就会被撑爆。
+
+### 4. 把 `s12` 的工作目标和本章的运行任务混为一谈
+
+这会让后面多 agent 和调度章节全部打结。
+
+## 教学边界
+
+这一章只需要先把一个最小运行时模式讲清楚：
+
+- 慢工作在后台跑
+- 主循环继续保持单主线
+- 结果通过通知路径在后面回到模型
+
+只要这条模式稳了，线程池、更多 worker 类型、更复杂的事件系统都可以后补。
+
+这章真正要让读者守住的是：
+
+**并行的是等待与执行槽位，不是主循环本身。**
+
+## 学完这一章，你应该真正掌握什么
+
+学完以后，你应该能独立复述下面几句话：
+
+1. 主循环只有一条，并行的是等待，不是主循环本身。
+2. 后台任务至少需要“任务表 + 通知队列”两块状态。
+3. `background_run` 应该立刻返回 `task_id`，而不是同步卡住。
+4. 通知只放摘要，完整输出放文件。
+
+如果这 4 句话都已经非常清楚，说明你已经掌握了后台任务系统的核心。
+
+## 下一章学什么
+
+这一章解决的是：
+
+> 慢命令如何在后台运行。
+
+下一章 `s14` 要解决的是：
+
+> 如果连“启动后台任务”这件事都不一定由当前用户触发，而是由时间触发，该怎么做。
+
+也就是从“异步运行”继续走向“定时触发”。
diff --git a/docs/zh/s13a-runtime-task-model.md b/docs/zh/s13a-runtime-task-model.md
new file mode 100644
index 000000000..ee107fb9b
--- /dev/null
+++ b/docs/zh/s13a-runtime-task-model.md
@@ -0,0 +1,276 @@
+# s13a: Runtime Task Model (运行时任务模型)
+
+> 这篇桥接文档专门解决一个非常容易混淆的问题：
+>
+> **任务板里的 task，和后台/队友/监控这些“正在运行的任务”，不是同一个东西。**
+
+## 建议怎么联读
+
+这篇最好夹在下面几份文档中间读：
+
+- 先看 [`s12-task-system.md`](./s12-task-system.md)，确认工作图任务在讲什么。
+- 再看 [`s13-background-tasks.md`](./s13-background-tasks.md)，确认后台执行在讲什么。
+- 如果词开始混，再回 [`glossary.md`](./glossary.md)。
+- 如果想把字段和状态彻底对上，再对照 [`data-structures.md`](./data-structures.md) 和 [`entity-map.md`](./entity-map.md)。
+
+## 为什么必须单独讲这一篇
+
+主线里：
+
+- `s12` 讲的是任务系统
+- `s13` 讲的是后台任务
+
+这两章各自都没错。  
+但如果不额外补一层桥接，很多读者很快就会把两种“任务”混在一起。
+
+例如：
+
+- 任务板里的 “实现 auth 模块”
+- 后台执行里的 “正在跑 pytest”
+- 队友执行里的 “alice 正在做代码改动”
+
+这些都可以叫“任务”，但它们不在同一层。
+
+为了让整个仓库接近满分，这一层必须讲透。
+
+## 先解释两个完全不同的“任务”
+
+### 第一种：工作图任务
+
+这就是 `s12` 里的任务板节点。
+
+它回答的是：
+
+- 要做什么
+- 谁依赖谁
+- 谁认领了
+- 当前进度如何
+
+它更像：
+
+> 工作计划中的一个可跟踪工作单元。
+
+### 第二种：运行时任务
+
+这类任务回答的是：
+
+- 现在有什么执行单元正在跑
+- 它是什么类型
+- 是在运行、完成、失败还是被杀掉
+- 输出文件在哪
+
+它更像：
+
+> 系统当前活着的一条执行槽位。
+
+## 最小心智模型
+
+你可以先把两者画成两张表：
+
+```text
+工作图任务
+  - durable
+  - 面向目标与依赖
+  - 生命周期更长
+
+运行时任务
+  - runtime
+  - 面向执行与输出
+  - 生命周期更短
+```
+
+它们的关系不是“二选一”，而是：
+
+```text
+一个工作图任务
+  可以派生
+一个或多个运行时任务
+```
+
+例如：
+
+```text
+工作图任务：
+  "实现 auth 模块"
+
+运行时任务：
+  1. 后台跑测试
+  2. 启动一个 coder teammate
+  3. 监控一个 MCP 服务返回结果
+```
+
+## 为什么这层区别非常重要
+
+如果不区分这两层，后面很多章节都会开始缠在一起：
+
+- `s13` 的后台任务会和 `s12` 的任务板混淆
+- `s15-s17` 的队友任务会不知道该挂在哪
+- `s18` 的 worktree 到底绑定哪一层任务，也会变模糊
+
+所以你要先记住一句：
+
+**工作图任务管“目标”，运行时任务管“执行”。**
+
+## 关键数据结构
+
+### 1. WorkGraphTaskRecord
+
+这就是 `s12` 里的那条 durable task。
+
+```python
+task = {
+    "id": 12,
+    "subject": "Implement auth module",
+    "status": "in_progress",
+    "blockedBy": [],
+    "blocks": [13],
+    "owner": "alice",
+    "worktree": "auth-refactor",
+}
+```
+
+### 2. RuntimeTaskState
+
+教学版可以先用这个最小形状：
+
+```python
+runtime_task = {
+    "id": "b8k2m1qz",
+    "type": "local_bash",
+    "status": "running",
+    "description": "Run pytest",
+    "start_time": 1710000000.0,
+    "end_time": None,
+    "output_file": ".task_outputs/b8k2m1qz.txt",
+    "notified": False,
+}
+```
+
+这里的字段重点在于：
+
+- `type`：它是什么执行单元
+- `status`：它现在在运行态还是终态
+- `output_file`：它的产出在哪
+- `notified`：结果有没有回通知系统
+
+### 3. RuntimeTaskType
+
+你不必在教学版里一次性实现所有类型，  
+但应该让读者知道“运行时任务”是一个类型族，而不只是 `background shell` 一种。
+
+最小类型表可以先这样讲：
+
+```text
+local_bash
+local_agent
+remote_agent
+in_process_teammate
+monitor
+workflow
+```
+
+## 最小实现
+
+### 第一步：继续保留 `s12` 的任务板
+
+这一层不要动。
+
+### 第二步：单独加一个 RuntimeTaskManager
+
+```python
+class RuntimeTaskManager:
+    def __init__(self):
+        self.tasks = {}
+```
+
+### 第三步：后台运行时创建 runtime task
+
+```python
+def spawn_bash_task(command: str):
+    task_id = new_runtime_id()
+    runtime_tasks[task_id] = {
+        "id": task_id,
+        "type": "local_bash",
+        "status": "running",
+        "description": command,
+    }
+```
+
+### 第四步：必要时把 runtime task 关联回工作图任务
+
+```python
+runtime_tasks[task_id]["work_graph_task_id"] = 12
+```
+
+这一步不是必须一上来就做，但如果系统进入多 agent / worktree 阶段，就会越来越重要。
+
+## 一张真正清楚的图
+
+```text
+Work Graph
+  task #12: Implement auth module
+        |
+        +-- spawns runtime task A: local_bash (pytest)
+        +-- spawns runtime task B: local_agent (coder worker)
+        +-- spawns runtime task C: monitor (watch service status)
+
+Runtime Task Layer
+  A/B/C each have:
+  - own runtime ID
+  - own status
+  - own output
+  - own lifecycle
+```
+
+## 它和后面章节怎么连
+
+这层一旦讲清楚，后面几章会顺很多：
+
+- `s13` 后台命令，本质上是 runtime task
+- `s15-s17` 队友/agent，也可以看成 runtime task 的一种
+- `s18` worktree 主要绑定工作图任务，但也会影响运行时执行环境
+- `s19` 某些外部监控或异步调用，也可能落成 runtime task
+
+所以后面只要你看到“有东西在后台活着并推进工作”，都可以先问自己两句：
+
+- 它是不是某个 durable work graph task 派生出来的执行槽位。
+- 它的状态是不是应该放在 runtime layer，而不是任务板节点里。
+
+## 初学者最容易犯的错
+
+### 1. 把后台 shell 直接写成任务板状态
+
+这样 durable task 和 runtime state 就混在一起了。
+
+### 2. 认为一个工作图任务只能对应一个运行时任务
+
+现实里很常见的是一个工作目标派生多个执行单元。
+
+### 3. 用同一套状态名描述两层对象
+
+例如：
+
+- 工作图任务的 `pending / in_progress / completed`
+- 运行时任务的 `running / completed / failed / killed`
+
+这两套状态最好不要混。
+
+### 4. 忽略 output file 和 notified 这类运行时字段
+
+工作图任务不太关心这些，运行时任务非常关心。
+
+## 教学边界
+
+这篇最重要的，不是把运行时字段一次加满，而是先把下面三层对象彻底拆开：
+
+- durable task 是长期工作目标
+- runtime task 是当前活着的执行槽位
+- notification / output 只是运行时把结果带回来的通道
+
+运行时任务类型枚举、增量输出 offset、槽位清理策略，都可以等你先把这三层边界手写清楚以后再扩展。
+
+## 一句话记住
+
+**工作图任务管“长期目标和依赖”，运行时任务管“当前活着的执行单元和输出”。**
+
+**`s12` 的 task 是工作图节点，`s13+` 的 runtime task 是系统里真正跑起来的执行单元。**
diff --git a/docs/zh/s14-cron-scheduler.md b/docs/zh/s14-cron-scheduler.md
new file mode 100644
index 000000000..044f4e86c
--- /dev/null
+++ b/docs/zh/s14-cron-scheduler.md
@@ -0,0 +1,288 @@
+# s14: Cron Scheduler (定时调度)
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > [ s14 ] > s15 > s16 > s17 > s18 > s19`
+
+> *如果后台任务解决的是“稍后回来拿结果”，那么定时调度解决的是“将来某个时间再开始做事”。*
+
+## 这一章要解决什么问题
+
+`s13` 已经让系统学会了把慢命令放到后台。
+
+但后台任务默认还是“现在就启动”。
+
+很多真实需求并不是现在做，而是：
+
+- 每天晚上跑一次测试
+- 每周一早上生成报告
+- 30 分钟后提醒我继续检查某个结果
+
+如果没有调度能力，用户就只能每次手动再说一遍。  
+这会让系统看起来像“只能响应当下”，而不是“能安排未来工作”。
+
+所以这一章要加上的能力是：
+
+**把一条未来要执行的意图，先记下来，等时间到了再触发。**
+
+## 建议联读
+
+- 如果你还没完全分清 `schedule`、`task`、`runtime task` 各自表示什么，先回 [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)。
+- 如果你想重新看清“一条触发最终是怎样回到主循环里的”，可以配合读 [`s00b-one-request-lifecycle.md`](./s00b-one-request-lifecycle.md)。
+- 如果你开始把“未来触发”误以为“又多了一套执行系统”，先回 [`data-structures.md`](./data-structures.md)，确认调度记录和运行时记录不是同一个表。
+
+## 先解释几个名词
+
+### 什么是调度器
+
+调度器，就是一段专门负责“看时间、查任务、决定是否触发”的代码。
+
+### 什么是 cron 表达式
+
+`cron` 是一种很常见的定时写法。
+
+最小 5 字段版本长这样：
+
+```text
+分 时 日 月 周
+```
+
+例如：
+
+```text
+*/5 * * * *   每 5 分钟
+0 9 * * 1     每周一 9 点
+30 14 * * *   每天 14:30
+```
+
+如果你是初学者，不用先背全。
+
+这一章真正重要的不是语法细节，而是：
+
+> “系统如何把一条未来任务记住，并在合适时刻放回主循环。”
+
+### 什么是持久化调度
+
+持久化，意思是：
+
+> 就算程序重启，这条调度记录还在。
+
+## 最小心智模型
+
+先把调度看成 3 个部分：
+
+```text
+1. 调度记录
+2. 定时检查器
+3. 通知队列
+```
+
+它们之间的关系是：
+
+```text
+schedule_create(...)
+  ->
+把记录写到列表或文件里
+  ->
+后台检查器每分钟看一次“现在是否匹配”
+  ->
+如果匹配，就把 prompt 放进通知队列
+  ->
+主循环下一轮把它当成新的用户消息喂给模型
+```
+
+这条链路很重要。
+
+因为它说明了一点：
+
+**定时调度并不是另一套 agent。它最终还是回到同一条主循环。**
+
+## 关键数据结构
+
+### 1. ScheduleRecord
+
+```python
+schedule = {
+    "id": "job_001",
+    "cron": "0 9 * * 1",
+    "prompt": "Run the weekly status report.",
+    "recurring": True,
+    "durable": True,
+    "created_at": 1710000000.0,
+    "last_fired_at": None,
+}
+```
+
+字段含义：
+
+- `id`：唯一编号
+- `cron`：定时规则
+- `prompt`：到点后要注入主循环的提示
+- `recurring`：是不是反复触发
+- `durable`：是否落盘保存
+- `created_at`：创建时间
+- `last_fired_at`：上次触发时间
+
+### 2. 调度通知
+
+```python
+{
+    "type": "scheduled_prompt",
+    "schedule_id": "job_001",
+    "prompt": "Run the weekly status report.",
+}
+```
+
+### 3. 检查周期
+
+教学版建议先按“分钟级”思考，而不是“秒级严格精度”。
+
+因为大多数 cron 任务本来就不是为了卡秒执行。
+
+## 最小实现
+
+### 第一步：允许创建一条调度记录
+
+```python
+def create(self, cron_expr: str, prompt: str, recurring: bool = True):
+    job = {
+        "id": new_id(),
+        "cron": cron_expr,
+        "prompt": prompt,
+        "recurring": recurring,
+        "created_at": time.time(),
+        "last_fired_at": None,
+    }
+    self.jobs.append(job)
+    return job
+```
+
+### 第二步：写一个定时检查循环
+
+```python
+def check_loop(self):
+    while True:
+        now = datetime.now()
+        self.check_jobs(now)
+        time.sleep(60)
+```
+
+最小教学版先每分钟检查一次就足够。
+
+### 第三步：时间到了就发通知
+
+```python
+def check_jobs(self, now):
+    for job in self.jobs:
+        if cron_matches(job["cron"], now):
+            self.queue.put({
+                "type": "scheduled_prompt",
+                "schedule_id": job["id"],
+                "prompt": job["prompt"],
+            })
+            job["last_fired_at"] = now.timestamp()
+```
+
+### 第四步：主循环像处理后台通知一样处理定时通知
+
+```python
+notifications = scheduler.drain()
+for item in notifications:
+    messages.append({
+        "role": "user",
+        "content": f"[scheduled:{item['schedule_id']}] {item['prompt']}",
+    })
+```
+
+这样一来，定时任务最终还是由模型接手继续做。
+
+## 为什么这章放在后台任务之后
+
+因为这两章解决的问题很接近，但不是同一件事。
+
+可以这样区分：
+
+| 机制 | 回答的问题 |
+|---|---|
+| 后台任务 | “已经启动的慢操作，结果什么时候回来？” |
+| 定时调度 | “一件事应该在未来什么时候开始？” |
+
+这个顺序对初学者很友好。
+
+因为先理解“异步结果回来”，再理解“未来触发一条新意图”，心智会更顺。
+
+## 初学者最容易犯的错
+
+### 1. 一上来沉迷 cron 语法细节
+
+这章最容易跑偏到一大堆表达式规则。
+
+但教学主线其实不是“背语法”，而是：
+
+**调度记录如何进入通知队列，又如何回到主循环。**
+
+### 2. 没有 `last_fired_at`
+
+没有这个字段，系统很容易在短时间内重复触发同一条任务。
+
+### 3. 只放内存，不支持落盘
+
+如果用户希望“明天再提醒我”，程序一重启就没了，这就不是真正的调度。
+
+### 4. 把调度触发结果直接在后台默默执行
+
+教学主线里更清楚的做法是：
+
+- 时间到了
+- 先发通知
+- 再让主循环决定怎么处理
+
+这样系统行为更透明，读者也更容易理解。
+
+### 5. 误以为定时任务必须绝对准点
+
+很多初学者会把调度想成秒表。
+
+但这里更重要的是“有计划地触发”，而不是追求毫秒级精度。
+
+## 如何接到整个系统里
+
+到了这一章，系统已经有两条重要的“外部事件输入”：
+
+- 后台任务完成通知
+- 定时调度触发通知
+
+二者最好的统一方式是：
+
+**都走通知队列，再在下一次模型调用前统一注入。**
+
+这样主循环结构不会越来越乱。
+
+## 教学边界
+
+这一章先讲清一条主线就够了：
+
+**调度器做的是“记住未来”，不是“取代主循环”。**
+
+所以教学版先只需要让读者看清：
+
+- schedule record 负责记住未来何时开工
+- 真正执行工作时，仍然回到任务系统和通知队列
+- 它只是多了一种“开始入口”，不是多了一条新的主循环
+
+多进程锁、漏触发补报、自然语言时间语法这些，都应该排在这条主线之后。
+
+## 试一试
+
+```sh
+cd learn-claude-code
+python agents/s14_cron_scheduler.py
+```
+
+可以试试这些任务：
+
+1. 建一个每分钟触发一次的小任务，观察它是否会按时进入通知队列。
+2. 建一个只触发一次的任务，确认触发后是否会消失。
+3. 重启程序，检查持久化的调度记录是否还在。
+
+读完这一章，你应该能自己说清这句话：
+
+**后台任务是在“等结果”，定时调度是在“等开始”。**
diff --git a/docs/zh/s15-agent-teams.md b/docs/zh/s15-agent-teams.md
new file mode 100644
index 000000000..1f82cef3f
--- /dev/null
+++ b/docs/zh/s15-agent-teams.md
@@ -0,0 +1,358 @@
+# s15: Agent Teams (智能体团队)
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > [ s15 ] > s16 > s17 > s18 > s19`
+
+> *子 agent 适合一次性委派；团队系统解决的是“有人长期在线、能继续接活、能互相协作”。*
+
+## 这一章要解决什么问题
+
+`s04` 的 subagent 已经能帮主 agent 拆小任务。
+
+但 subagent 有一个很明显的边界：
+
+```text
+创建 -> 执行 -> 返回摘要 -> 消失
+```
+
+这很适合一次性的小委派。  
+可如果你想做这些事，就不够用了：
+
+- 让一个测试 agent 长期待命
+- 让两个 agent 长期分工
+- 让某个 agent 未来收到新任务后继续工作
+
+也就是说，系统现在缺的不是“再开一个模型调用”，而是：
+
+**一批有身份、能长期存在、能反复协作的队友。**
+
+## 建议联读
+
+- 如果你还在把 teammate 和 `s04` 的 subagent 混成一类，先回 [`entity-map.md`](./entity-map.md)。
+- 如果你准备继续读 `s16-s18`，建议把 [`team-task-lane-model.md`](./team-task-lane-model.md) 放在手边，它会把 teammate、protocol request、task、runtime slot、worktree lane 这五层一起拆开。
+- 如果你开始怀疑“长期队友”和“活着的执行槽位”到底是什么关系，配合看 [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)。
+
+## 先把几个词讲明白
+
+### 什么是队友
+
+这里的 `teammate` 指的是：
+
+> 一个拥有名字、角色、消息入口和生命周期的持久 agent。
+
+### 什么是名册
+
+名册就是团队成员列表。
+
+它回答的是：
+
+- 现在队伍里有谁
+- 每个人是什么角色
+- 每个人现在是空闲、工作中还是已关闭
+
+### 什么是邮箱
+
+邮箱就是每个队友的收件箱。
+
+别人把消息发给它，  
+它在自己的下一轮工作前先去收消息。
+
+## 最小心智模型
+
+这一章最简单的理解方式，是把每个队友都想成：
+
+> 一个有自己循环、自己收件箱、自己上下文的人。
+
+```text
+lead
+  |
+  +-- spawn alice (coder)
+  +-- spawn bob (tester)
+  |
+  +-- send message --> alice inbox
+  +-- send message --> bob inbox
+
+alice
+  |
+  +-- 自己的 messages
+  +-- 自己的 inbox
+  +-- 自己的 agent loop
+
+bob
+  |
+  +-- 自己的 messages
+  +-- 自己的 inbox
+  +-- 自己的 agent loop
+```
+
+和 `s04` 的最大区别是：
+
+**subagent 是一次性执行单元，teammate 是长期存在的协作成员。**
+
+## 关键数据结构
+
+### 1. TeamMember
+
+```python
+member = {
+    "name": "alice",
+    "role": "coder",
+    "status": "working",
+}
+```
+
+教学版先只保留这 3 个字段就够了：
+
+- `name`：名字
+- `role`：角色
+- `status`：状态
+
+### 2. TeamConfig
+
+```python
+config = {
+    "team_name": "default",
+    "members": [member1, member2],
+}
+```
+
+它通常可以放在：
+
+```text
+.team/config.json
+```
+
+这份名册让系统重启以后，仍然知道：
+
+- 团队里曾经有谁
+- 每个人当前是什么角色
+
+### 3. MessageEnvelope
+
+```python
+message = {
+    "type": "message",
+    "from": "lead",
+    "content": "Please review auth module.",
+    "timestamp": 1710000000.0,
+}
+```
+
+`envelope` 这个词本来是“信封”的意思。  
+程序里用它表示：
+
+> 把消息正文和元信息一起包起来的一条记录。
+
+## 最小实现
+
+### 第一步：先有一份队伍名册
+
+```python
+class TeammateManager:
+    def __init__(self, team_dir: Path):
+        self.team_dir = team_dir
+        self.config_path = team_dir / "config.json"
+        self.config = self._load_config()
+```
+
+名册是本章的起点。  
+没有名册，就没有真正的“团队实体”。
+
+### 第二步：spawn 一个持久队友
+
+```python
+def spawn(self, name: str, role: str, prompt: str):
+    member = {"name": name, "role": role, "status": "working"}
+    self.config["members"].append(member)
+    self._save_config()
+
+    thread = threading.Thread(
+        target=self._teammate_loop,
+        args=(name, role, prompt),
+        daemon=True,
+    )
+    thread.start()
+```
+
+这里的关键不在于线程本身，而在于：
+
+**队友一旦被创建，就不只是一次性工具调用，而是一个有持续生命周期的成员。**
+
+### 第三步：给每个队友一个邮箱
+
+教学版最简单的做法可以直接用 JSONL 文件：
+
+```text
+.team/inbox/alice.jsonl
+.team/inbox/bob.jsonl
+```
+
+发消息时追加一行：
+
+```python
+def send(self, sender: str, to: str, content: str):
+    with open(f"{to}.jsonl", "a") as f:
+        f.write(json.dumps({
+            "type": "message",
+            "from": sender,
+            "content": content,
+            "timestamp": time.time(),
+        }) + "\n")
+```
+
+收消息时：
+
+1. 读出全部
+2. 解析为消息列表
+3. 清空收件箱
+
+### 第四步：队友每轮先看邮箱，再继续工作
+
+```python
+def teammate_loop(name: str, role: str, prompt: str):
+    messages = [{"role": "user", "content": prompt}]
+
+    while True:
+        inbox = bus.read_inbox(name)
+        for item in inbox:
+            messages.append({"role": "user", "content": json.dumps(item)})
+
+        response = client.messages.create(...)
+        ...
+```
+
+这一步一定要讲透。
+
+因为它说明：
+
+**队友不是靠“被重新创建”来获得新任务，而是靠“下一轮先检查邮箱”来接收新工作。**
+
+## 如何接到前面章节的系统里
+
+这章最容易出现的误解是：
+
+> 好像系统突然“多了几个人”，但不知道这些人到底接在之前哪一层。
+
+更准确的接法应该是：
+
+```text
+用户目标 / lead 判断需要长期分工
+  ->
+spawn teammate
+  ->
+写入 .team/config.json
+  ->
+通过 inbox 分派消息、摘要、任务线索
+  ->
+teammate 先 drain inbox
+  ->
+进入自己的 agent loop 和工具调用
+  ->
+把结果回送给 lead，或继续等待下一轮工作
+```
+
+这里要特别看清三件事：
+
+1. `s12-s14` 已经给了你任务板、后台执行、时间触发这些“工作层”。
+2. `s15` 现在补的是“长期执行者”，也就是谁长期在线、谁能反复接活。
+3. 本章还没有进入“自己找活”或“自动认领”。
+
+也就是说，`s15` 的默认工作方式仍然是：
+
+- 由 lead 手动创建队友
+- 由 lead 通过邮箱分派事情
+- 队友在自己的循环里持续处理
+
+真正的自治认领，要到 `s17` 才展开。
+
+## Teammate、Subagent、Runtime Task 到底怎么区分
+
+这是这一组章节里最容易混的点。
+
+可以直接记这张表：
+
+| 机制 | 更像什么 | 生命周期 | 关键边界 |
+|---|---|---|
+| subagent | 一次性外包助手 | 干完就结束 | 重点是“隔离一小段探索性上下文” |
+| runtime task | 正在运行的后台执行槽位 | 任务跑完或取消就结束 | 重点是“慢任务稍后回来”，不是长期身份 |
+| teammate | 长期在线队友 | 可以反复接任务 | 重点是“有名字、有邮箱、有独立循环” |
+
+再换成更口语的话说：
+
+- subagent 适合“帮我查一下再回来汇报”
+- runtime task 适合“这件事你后台慢慢跑，结果稍后通知我”
+- teammate 适合“你以后长期负责测试方向”
+
+## 这一章的教学边界
+
+本章先只把 3 件事讲稳：
+
+- 名册
+- 邮箱
+- 独立循环
+
+这已经足够把“长期队友”这个实体立起来。
+
+但它还没有展开后面两层能力：
+
+### 第一层：结构化协议
+
+也就是：
+
+- 哪些消息只是普通交流
+- 哪些消息是带 `request_id` 的结构化请求
+
+这部分放到下一章 `s16`。
+
+### 第二层：自治认领
+
+也就是：
+
+- 队友空闲时能不能自己找活
+- 能不能自己恢复工作
+
+这部分放到 `s17`。
+
+## 初学者最容易犯的错
+
+### 1. 把队友当成“名字不同的 subagent”
+
+如果生命周期还是“执行完就销毁”，那本质上还不是 teammate。
+
+### 2. 队友之间共用同一份 messages
+
+这样上下文会互相污染。
+
+每个队友都应该有自己的对话状态。
+
+### 3. 没有持久名册
+
+如果系统关掉以后完全不知道“团队里曾经有谁”，那就很难继续做长期协作。
+
+### 4. 没有邮箱，靠共享变量直接喊话
+
+教学上不建议一开始就这么做。
+
+因为它会把“队友通信”和“进程内部细节”绑得太死。
+
+## 学完这一章，你应该真正掌握什么
+
+学完以后，你应该能独立说清下面几件事：
+
+1. teammate 的核心不是“多一个模型调用”，而是“多一个长期存在的执行者”。
+2. 团队系统至少需要“名册 + 邮箱 + 独立循环”。
+3. 每个队友都应该有自己的 `messages` 和自己的 inbox。
+4. subagent 和 teammate 的根本区别在生命周期，而不是名字。
+
+如果这 4 点已经稳了，说明你已经真正理解了“多 agent 团队”是怎么从单 agent 演化出来的。
+
+## 下一章学什么
+
+这一章解决的是：
+
+> 团队成员如何长期存在、互相发消息。
+
+下一章 `s16` 要解决的是：
+
+> 当消息不再只是自由聊天，而要变成可追踪、可批准、可拒绝的协作流程时，该怎么设计。
+
+也就是从“有团队”继续走向“团队协议”。
diff --git a/docs/zh/s16-team-protocols.md b/docs/zh/s16-team-protocols.md
new file mode 100644
index 000000000..0f4f13f02
--- /dev/null
+++ b/docs/zh/s16-team-protocols.md
@@ -0,0 +1,401 @@
+# s16: Team Protocols (团队协议)
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > [ s16 ] > s17 > s18 > s19`
+
+> *有了邮箱以后，团队已经能说话；有了协议以后，团队才开始会“按规矩协作”。*
+
+## 这一章要解决什么问题
+
+`s15` 已经让队友之间可以互相发消息。
+
+但如果所有事情都只靠自由文本，会有两个明显问题：
+
+- 某些动作必须明确批准或拒绝，不能只靠一句模糊回复
+- 一旦多个请求同时存在，系统很难知道“这条回复对应哪一件事”
+
+最典型的两个场景就是：
+
+1. 队友要不要优雅关机
+2. 某个高风险计划要不要先审批
+
+这两件事看起来不同，但结构其实一样：
+
+```text
+一方发请求
+另一方明确回复
+双方都能用同一个 request_id 对上号
+```
+
+所以这一章要加的，不是更多自由聊天，而是：
+
+**一层结构化协议。**
+
+## 建议联读
+
+- 如果你开始把普通消息和协议请求混掉，先回 [`glossary.md`](./glossary.md) 和 [`entity-map.md`](./entity-map.md)。
+- 如果你准备继续读 `s17` 和 `s18`，建议先看 [`team-task-lane-model.md`](./team-task-lane-model.md)，这样后面自治认领和 worktree 车道不会一下子缠在一起。
+- 如果你想重新确认协议请求最终怎样回流到主系统，可以配合看 [`s00b-one-request-lifecycle.md`](./s00b-one-request-lifecycle.md)。
+
+## 先把几个词讲明白
+
+### 什么是协议
+
+协议可以简单理解成：
+
+> 双方提前约定好“消息长什么样、收到以后怎么处理”。
+
+### 什么是 request_id
+
+`request_id` 就是请求编号。
+
+它的作用是：
+
+- 某个请求发出去以后有一个唯一身份
+- 之后的批准、拒绝、超时都能准确指向这一个请求
+
+### 什么是请求-响应模式
+
+这个词听起来像高级概念，其实很简单：
+
+```text
+请求方：我发起一件事
+响应方：我明确回答同意还是不同意
+```
+
+本章做的，就是把这种模式从“口头表达”升级成“结构化数据”。
+
+## 最小心智模型
+
+从教学角度，你可以先把协议看成两层：
+
+```text
+1. 协议消息
+2. 请求追踪表
+```
+
+### 协议消息
+
+```python
+{
+    "type": "shutdown_request",
+    "from": "lead",
+    "to": "alice",
+    "request_id": "req_001",
+    "payload": {},
+}
+```
+
+### 请求追踪表
+
+```python
+requests = {
+    "req_001": {
+        "kind": "shutdown",
+        "status": "pending",
+    }
+}
+```
+
+只要这两层都存在，系统就能同时回答：
+
+- 现在发生了什么
+- 这件事目前走到哪一步
+
+## 关键数据结构
+
+### 1. ProtocolEnvelope
+
+```python
+message = {
+    "type": "shutdown_request",
+    "from": "lead",
+    "to": "alice",
+    "request_id": "req_001",
+    "payload": {},
+    "timestamp": 1710000000.0,
+}
+```
+
+它比普通消息多出来的关键字段就是：
+
+- `type`
+- `request_id`
+- `payload`
+
+### 2. RequestRecord
+
+```python
+request = {
+    "request_id": "req_001",
+    "kind": "shutdown",
+    "from": "lead",
+    "to": "alice",
+    "status": "pending",
+}
+```
+
+它负责记录：
+
+- 这是哪种请求
+- 谁发给谁
+- 当前状态是什么
+
+如果你想把教学版再往真实系统推进一步，建议不要只放在内存字典里，而是直接落盘：
+
+```text
+.team/requests/
+  req_001.json
+  req_002.json
+```
+
+这样系统就能做到：
+
+- 请求状态可恢复
+- 协议过程可检查
+- 即使主循环继续往前，请求记录也不会丢
+
+### 3. 状态机
+
+本章里的状态机非常简单：
+
+```text
+pending -> approved
+pending -> rejected
+pending -> expired
+```
+
+这里再次提醒读者：
+
+`状态机` 的意思不是复杂理论，  
+只是“状态之间如何变化的一张规则表”。
+
+## 最小实现
+
+### 协议 1：优雅关机
+
+“优雅关机”的意思不是直接把线程硬砍掉。  
+而是：
+
+1. 先发关机请求
+2. 队友明确回复同意或拒绝
+3. 如果同意，先收尾，再退出
+
+发请求：
+
+```python
+def request_shutdown(target: str):
+    request_id = new_id()
+    requests[request_id] = {
+        "kind": "shutdown",
+        "target": target,
+        "status": "pending",
+    }
+    bus.send(
+        "lead",
+        target,
+        msg_type="shutdown_request",
+        extra={"request_id": request_id},
+        content="Please shut down gracefully.",
+    )
+```
+
+收响应：
+
+```python
+def handle_shutdown_response(request_id: str, approve: bool):
+    record = requests[request_id]
+    record["status"] = "approved" if approve else "rejected"
+```
+
+### 协议 2：计划审批
+
+这其实还是同一个请求-响应模板。
+
+比如某个队友想做高风险改动，可以先提计划：
+
+```python
+def submit_plan(name: str, plan_text: str):
+    request_id = new_id()
+    requests[request_id] = {
+        "kind": "plan_approval",
+        "from": name,
+        "status": "pending",
+        "plan": plan_text,
+    }
+    bus.send(
+        name,
+        "lead",
+        msg_type="plan_approval",
+        extra={"request_id": request_id, "plan": plan_text},
+        content="Requesting review.",
+    )
+```
+
+领导审批：
+
+```python
+def review_plan(request_id: str, approve: bool, feedback: str = ""):
+    record = requests[request_id]
+    record["status"] = "approved" if approve else "rejected"
+    bus.send(
+        "lead",
+        record["from"],
+        msg_type="plan_approval_response",
+        extra={"request_id": request_id, "approve": approve},
+        content=feedback,
+    )
+```
+
+看到这里，读者应该开始意识到：
+
+**本章最重要的不是“关机”或“计划”本身，而是同一个协议模板可以反复复用。**
+
+## 协议请求不是普通消息
+
+这一点一定要讲透。
+
+邮箱里虽然都叫“消息”，但 `s16` 以后其实已经分成两类：
+
+### 1. 普通消息
+
+适合：
+
+- 讨论
+- 提醒
+- 补充说明
+
+### 2. 协议消息
+
+适合：
+
+- 审批
+- 关机
+- 交接
+- 签收
+
+它至少要带：
+
+- `type`
+- `request_id`
+- `from`
+- `to`
+- `payload`
+
+最简单的记法是：
+
+- 普通消息解决“说了什么”
+- 协议消息解决“这件事走到哪一步了”
+
+## 如何接到团队系统里
+
+这章真正补上的，不只是两个新工具名，而是一条新的协作回路：
+
+```text
+某个队友 / lead 发起请求
+  ->
+写入 RequestRecord
+  ->
+把 ProtocolEnvelope 投递进对方 inbox
+  ->
+对方下一轮 drain inbox
+  ->
+按 request_id 更新请求状态
+  ->
+必要时再回一条 response
+  ->
+请求方根据 approved / rejected 继续后续动作
+```
+
+你可以把它理解成：
+
+- `s15` 给了团队“邮箱”
+- `s16` 现在给邮箱里的某些消息加上“编号 + 状态机 + 回执”
+
+如果少了这条结构化回路，团队虽然能沟通，但无法稳定协作。
+
+## MessageEnvelope、ProtocolEnvelope、RequestRecord、TaskRecord 的边界
+
+这 4 个对象很容易一起打结。最稳的记法是：
+
+| 对象 | 它回答什么问题 | 典型字段 |
+|---|---|---|
+| `MessageEnvelope` | 谁跟谁说了什么 | `from` / `to` / `content` |
+| `ProtocolEnvelope` | 这是不是一条结构化请求或响应 | `type` / `request_id` / `payload` |
+| `RequestRecord` | 这件协作流程现在走到哪一步 | `kind` / `status` / `from` / `to` |
+| `TaskRecord` | 真正的工作项是什么、谁在做、还卡着谁 | `subject` / `status` / `blockedBy` / `owner` |
+
+一定要牢牢记住：
+
+- 协议请求不是任务本身
+- 请求状态表也不是任务板
+- 协议只负责“协作流程”
+- 任务系统才负责“真正的工作推进”
+
+## 这一章的教学边界
+
+教学版先只讲 2 类协议就够了：
+
+- `shutdown`
+- `plan_approval`
+
+因为这两类已经足够把下面几件事讲清楚：
+
+- 什么是结构化消息
+- 什么是 request_id
+- 为什么要有请求状态表
+- 为什么协议不是自由文本
+
+等这套模板学稳以后，你完全可以再扩展：
+
+- 任务认领协议
+- 交接协议
+- 结果签收协议
+
+但这些都应该建立在本章的统一模板之上。
+
+## 初学者最容易犯的错
+
+### 1. 没有 `request_id`
+
+没有编号，多个请求同时存在时很快就会乱。
+
+### 2. 收到请求以后只回一句自然语言
+
+例如：
+
+```text
+好的，我知道了
+```
+
+人类可能看得懂，但系统很难稳定处理。
+
+### 3. 没有请求状态表
+
+如果系统不记录 `pending` / `approved` / `rejected`，协议其实就没有真正落地。
+
+### 4. 把协议消息和普通消息混成一种结构
+
+这样后面一多，处理逻辑会越来越混。
+
+## 学完这一章，你应该真正掌握什么
+
+学完以后，你应该能独立复述下面几件事：
+
+1. 团队协议的核心，是“请求-响应 + request_id + 状态表”。
+2. 协议消息和普通聊天消息不是一回事。
+3. 关机协议和计划审批虽然业务不同，但底层模板可以复用。
+4. 团队一旦进入结构化协作，就要靠协议，而不是只靠自然语言。
+
+如果这 4 点已经非常稳定，说明这一章真正学到了。
+
+## 下一章学什么
+
+这一章解决的是：
+
+> 团队如何按规则协作。
+
+下一章 `s17` 要解决的是：
+
+> 如果没有人每次都手动派活，队友能不能在空闲时自己找任务、自己恢复工作。
+
+也就是从“协议化协作”继续走向“自治行为”。
diff --git a/docs/zh/s17-autonomous-agents.md b/docs/zh/s17-autonomous-agents.md
new file mode 100644
index 000000000..3a7f0efe4
--- /dev/null
+++ b/docs/zh/s17-autonomous-agents.md
@@ -0,0 +1,540 @@
+# s17: Autonomous Agents (自治智能体)
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > [ s17 ] > s18 > s19`
+
+> *一个团队真正开始“自己运转”，不是因为 agent 数量变多，而是因为空闲的队友会自己去找下一份工作。*
+
+## 这一章要解决什么问题
+
+到了 `s16`，团队已经有：
+
+- 持久队友
+- 邮箱
+- 协议
+- 任务板
+
+但还有一个明显瓶颈：
+
+**很多事情仍然要靠 lead 手动分配。**
+
+例如任务板上已经有 10 条可做任务，如果还要 lead 一个个点名：
+
+- Alice 做 1
+- Bob 做 2
+- Charlie 做 3
+
+那团队规模一大，lead 就会变成瓶颈。
+
+所以这一章要解决的核心问题是：
+
+**让空闲队友自己扫描任务板，找到可做的任务并认领。**
+
+## 建议联读
+
+- 如果你开始把 teammate、task、runtime slot 三层一起讲糊，先回 [`team-task-lane-model.md`](./team-task-lane-model.md)。
+- 如果你读到“auto-claim”时开始疑惑“活着的执行槽位”到底放在哪，继续看 [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)。
+- 如果你开始忘记“长期队友”和“一次性 subagent”最根本的区别，回看 [`entity-map.md`](./entity-map.md)。
+
+## 先解释几个名词
+
+### 什么叫自治
+
+这里的自治，不是完全没人管。
+
+这里说的自治是：
+
+> 在提前给定规则的前提下，队友可以自己决定下一步接哪份工作。
+
+### 什么叫认领
+
+认领，就是把一条原本没人负责的任务，标记成“现在由我负责”。
+
+### 什么叫空闲阶段
+
+空闲阶段不是关机，也不是消失。
+
+它表示：
+
+> 这个队友当前手头没有活，但仍然活着，随时准备接新活。
+
+## 最小心智模型
+
+最清楚的理解方式，是把每个队友想成在两个阶段之间切换：
+
+```text
+WORK
+  |
+  | 当前轮工作做完，或者主动进入 idle
+  v
+IDLE
+  |
+  +-- 看邮箱，有新消息 -> 回到 WORK
+  |
+  +-- 看任务板，有 ready task -> 认领 -> 回到 WORK
+  |
+  +-- 长时间什么都没有 -> shutdown
+```
+
+这里的关键不是“让它永远不停想”，而是：
+
+**空闲时，按规则检查两类新输入：邮箱和任务板。**
+
+## 关键数据结构
+
+### 1. Claimable Predicate
+
+和 `s12` 一样，这里最重要的是：
+
+**什么任务算“当前这个队友可以安全认领”的任务。**
+
+在当前教学代码里，判定已经不是单纯看 `pending`，而是：
+
+```python
+def is_claimable_task(task: dict, role: str | None = None) -> bool:
+    return (
+        task.get("status") == "pending"
+        and not task.get("owner")
+        and not task.get("blockedBy")
+        and _task_allows_role(task, role)
+    )
+```
+
+这 4 个条件缺一不可：
+
+- 任务还没开始
+- 还没人认领
+- 没有前置阻塞
+- 当前队友角色满足认领策略
+
+最后一条很关键。
+
+因为现在任务可以带：
+
+- `claim_role`
+- `required_role`
+
+例如：
+
+```python
+task = {
+    "id": 7,
+    "subject": "Implement login page",
+    "status": "pending",
+    "owner": "",
+    "blockedBy": [],
+    "claim_role": "frontend",
+}
+```
+
+这表示：
+
+> 这条任务不是“谁空着谁就拿”，而是要先过角色条件。
+
+### 2. 认领后的任务记录
+
+一旦认领成功，任务记录至少会发生这些变化：
+
+```python
+{
+    "id": 7,
+    "owner": "alice",
+    "status": "in_progress",
+    "claimed_at": 1710000000.0,
+    "claim_source": "auto",
+}
+```
+
+这里新增的两个字段很值得单独记住：
+
+- `claimed_at`：什么时候被认领
+- `claim_source`：这次认领是 `auto` 还是 `manual`
+
+因为到这一步，系统开始不只是知道“任务现在有人做了”，还开始知道：
+
+- 这是谁拿走的
+- 是主动扫描拿走，还是手动点名拿走
+
+### 3. Claim Event Log
+
+除了回写任务文件，这章还会把认领动作追加到：
+
+```text
+.tasks/claim_events.jsonl
+```
+
+每条事件大致长这样：
+
+```python
+{
+    "event": "task.claimed",
+    "task_id": 7,
+    "owner": "alice",
+    "role": "frontend",
+    "source": "auto",
+    "ts": 1710000000.0,
+}
+```
+
+为什么这层日志重要？
+
+因为它回答的是“自治系统刚刚做了什么”。
+
+只看最终任务文件，你知道的是：
+
+- 现在是谁 owner
+
+而看事件日志，你才能知道：
+
+- 它是什么时候被拿走的
+- 是谁拿走的
+- 是空闲时自动拿走，还是人工调用 `claim_task`
+
+### 4. Durable Request Record
+
+这章虽然重点是自治，但它**不能从 `s16` 退回到“协议请求只放内存里”**。
+
+所以当前代码里仍然保留了持久化请求记录：
+
+```text
+.team/requests/{request_id}.json
+```
+
+它保存的是：
+
+- shutdown request
+- plan approval request
+- 对应的状态更新
+
+这层边界很重要，因为自治队友并不是在“脱离协议系统另起炉灶”，而是：
+
+> 在已有团队协议之上，额外获得“空闲时自己找活”的能力。
+
+### 5. 身份块
+
+当上下文被压缩后，队友有时会“忘记自己是谁”。
+
+最小补法是重新注入一段身份提示：
+
+```python
+identity = {
+    "role": "user",
+    "content": "<identity>You are 'alice', role: frontend, team: default. Continue your work.</identity>",
+}
+```
+
+当前实现里还会同时补一条很短的确认语：
+
+```python
+{"role": "assistant", "content": "I am alice. Continuing."}
+```
+
+这样做的目的不是好看，而是为了让恢复后的下一轮继续知道：
+
+- 我是谁
+- 我的角色是什么
+- 我属于哪个团队
+
+## 最小实现
+
+### 第一步：让队友拥有 `WORK -> IDLE` 的循环
+
+```python
+while True:
+    run_work_phase(...)
+    should_resume = run_idle_phase(...)
+    if not should_resume:
+        break
+```
+
+### 第二步：在 IDLE 里先看邮箱
+
+```python
+def idle_phase(name: str, messages: list) -> bool:
+    inbox = bus.read_inbox(name)
+    if inbox:
+        messages.append({
+            "role": "user",
+            "content": json.dumps(inbox),
+        })
+        return True
+```
+
+这一步的意思是：
+
+如果有人明确找我，那我优先处理“明确发给我的工作”。
+
+### 第三步：如果邮箱没消息，再按“当前角色”扫描可认领任务
+
+```python
+    unclaimed = scan_unclaimed_tasks(role)
+    if unclaimed:
+        task = unclaimed[0]
+        claim_result = claim_task(
+            task["id"],
+            name,
+            role=role,
+            source="auto",
+        )
+```
+
+这里当前代码有两个很关键的升级：
+
+- `scan_unclaimed_tasks(role)` 不是无差别扫任务，而是带着角色过滤
+- `claim_task(..., source="auto")` 会把“这次是自治认领”显式写进任务与事件日志
+
+也就是说，自治不是“空闲了就乱抢一条”，而是：
+
+> 按当前队友的角色、任务状态和阻塞关系，挑出一条真正允许它接手的工作。
+
+### 第四步：认领后先补身份，再把任务提示塞回主循环
+
+```python
+        ensure_identity_context(messages, name, role, team_name)
+        messages.append({
+            "role": "user",
+            "content": f"<auto-claimed>Task #{task['id']}: {task['subject']}</auto-claimed>",
+        })
+        messages.append({
+            "role": "assistant",
+            "content": f"{claim_result}. Working on it.",
+        })
+        return True
+```
+
+这一步非常关键。
+
+因为“认领成功”本身还不等于“队友真的能顺利继续”。
+
+还必须把两件事接回上下文里：
+
+- 身份上下文
+- 新任务提示
+
+只有这样，下一轮 `WORK` 才不是无头苍蝇，而是：
+
+> 带着明确身份和明确任务恢复工作。
+
+### 第五步：长时间没事就退出
+
+```python
+    time.sleep(POLL_INTERVAL)
+    ...
+    return False
+```
+
+为什么需要这个退出路径？
+
+因为空闲队友不一定要永远占着资源。  
+教学版先做“空闲一段时间后关闭”就够了。
+
+## 为什么认领必须是原子动作
+
+“原子”这个词第一次看到可能不熟。
+
+这里它的意思是：
+
+> 认领这一步要么完整成功，要么不发生，不能一半成功一半失败。
+
+为什么？
+
+因为两个队友可能同时扫描到同一个可做任务。
+
+如果没有锁，就可能发生：
+
+- Alice 看见任务 3 没主人
+- Bob 也看见任务 3 没主人
+- 两人都把自己写成 owner
+
+所以最小教学版也应该加一个认领锁：
+
+```python
+with claim_lock:
+    task = load(task_id)
+    if task["owner"]:
+        return "already claimed"
+    task["owner"] = name
+    task["status"] = "in_progress"
+    save(task)
+```
+
+## 身份重注入为什么重要
+
+这是这章里一个很容易被忽视，但很关键的点。
+
+当上下文压缩发生以后，队友可能丢掉这些关键信息：
+
+- 我是谁
+- 我的角色是什么
+- 我属于哪个团队
+
+如果没有这些信息，队友后续行为很容易漂。
+
+所以一个很实用的做法是：
+
+如果发现 messages 的开头已经没有身份块，就把身份块重新插回去。
+
+这里你可以把它理解成一条恢复规则：
+
+> 任何一次从 idle 恢复、或任何一次压缩后恢复，只要身份上下文可能变薄，就先补身份，再继续工作。
+
+## 为什么 s17 不能从 s16 退回“内存协议”
+
+这是一个很容易被漏讲，但其实非常重要的点。
+
+很多人一看到“自治”，就容易只盯：
+
+- idle
+- auto-claim
+- 轮询
+
+然后忘了 `s16` 已经建立过的另一条主线：
+
+- 请求必须可追踪
+- 协议状态必须可恢复
+
+所以现在教学代码里，像：
+
+- shutdown request
+- plan approval
+
+仍然会写进：
+
+```text
+.team/requests/{request_id}.json
+```
+
+也就是说，`s17` 不是推翻 `s16`，而是在 `s16` 上继续加一条新能力：
+
+```text
+协议系统继续存在
+  +
+自治扫描与认领开始存在
+```
+
+这两条线一起存在，团队才会像一个真正的平台，而不是一堆各自乱跑的 worker。
+
+## 如何接到前面几章里
+
+这一章其实是前面几章第一次真正“串起来”的地方：
+
+- `s12` 提供任务板
+- `s15` 提供持久队友
+- `s16` 提供结构化协议
+- `s17` 则让队友在没有明确点名时，也能自己找活
+
+所以你可以把 `s17` 理解成：
+
+**从“被动协作”升级到“主动协作”。**
+
+## 自治的是“长期队友”，不是“一次性 subagent”
+
+这层边界如果不讲清，读者很容易把 `s04` 和 `s17` 混掉。
+
+`s17` 里的自治执行者，仍然是 `s15` 那种长期队友：
+
+- 有名字
+- 有角色
+- 有邮箱
+- 有 idle 阶段
+- 可以反复接活
+
+它不是那种：
+
+- 接一条子任务
+- 做完返回摘要
+- 然后立刻消失
+
+的一次性 subagent。
+
+同样地，这里认领的也是：
+
+- `s12` 里的工作图任务
+
+而不是：
+
+- `s13` 里的后台执行槽位
+
+所以这章其实是在两条已存在的主线上再往前推一步：
+
+- 长期队友
+- 工作图任务
+
+再把它们用“自治认领”连接起来。
+
+如果你开始把下面这些词混在一起：
+
+- teammate
+- protocol request
+- task
+- runtime task
+
+建议回看：
+
+- [`team-task-lane-model.md`](./team-task-lane-model.md)
+- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)
+
+## 初学者最容易犯的错
+
+### 1. 只看 `pending`，不看 `blockedBy`
+
+如果一个任务虽然是 `pending`，但前置任务还没完成，它就不应该被认领。
+
+### 2. 只看状态，不看 `claim_role` / `required_role`
+
+这会让错误的队友接走错误的任务。
+
+教学版虽然简单，但从这一章开始，已经应该明确告诉读者：
+
+- 并不是所有 ready task 都适合所有队友
+- 角色条件本身也是 claim policy 的一部分
+
+### 3. 没有认领锁
+
+这会直接导致重复抢同一条任务。
+
+### 4. 空闲阶段只轮询任务板，不看邮箱
+
+这样队友会错过别人明确发给它的消息。
+
+### 5. 认领了任务，但没有写 claim event
+
+这样最后你只能看到“任务现在被谁做”，却看不到：
+
+- 它是什么时候被拿走的
+- 是自动认领还是手动认领
+
+### 6. 队友永远不退出
+
+教学版里，长时间无事可做时退出是合理的。  
+否则读者会更难理解资源何时释放。
+
+### 7. 上下文压缩后不重注入身份
+
+这很容易让队友后面的行为越来越不像“它本来的角色”。
+
+## 教学边界
+
+这一章先只把自治主线讲清楚：
+
+**空闲检查 -> 安全认领 -> 恢复工作。**
+
+只要这条链路稳了，读者就已经真正理解了“自治”是什么。
+
+更细的 claim policy、公平调度、事件驱动唤醒、长期保活，都应该建立在这条最小自治链之后，而不是抢在前面。
+
+## 试一试
+
+```sh
+cd learn-claude-code
+python agents/s17_autonomous_agents.py
+```
+
+可以试试这些任务：
+
+1. 先建几条 ready task，再生成两个队友，观察它们是否会自动分工。
+2. 建几条被阻塞的任务，确认队友不会错误认领。
+3. 让某个队友进入 idle，再发一条消息给它，观察它是否会重新被唤醒。
+
+这一章要建立的核心心智是：
+
+**自治不是让 agent 乱跑，而是让它在清晰规则下自己接住下一份工作。**
diff --git a/docs/zh/s18-worktree-task-isolation.md b/docs/zh/s18-worktree-task-isolation.md
new file mode 100644
index 000000000..33f811725
--- /dev/null
+++ b/docs/zh/s18-worktree-task-isolation.md
@@ -0,0 +1,499 @@
+# s18: Worktree + Task Isolation (Worktree 任务隔离)
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > [ s18 ] > s19`
+
+> *任务板解决“做什么”，worktree 解决“在哪做而不互相踩到”。*
+
+## 这一章要解决什么问题
+
+到 `s17` 为止，系统已经可以：
+
+- 拆任务
+- 认领任务
+- 让多个 agent 并行推进不同工作
+
+但如果所有人都在同一个工作目录里改文件，很快就会出现这些问题：
+
+- 两个任务同时改同一个文件
+- 一个任务还没做完，另一个任务的修改已经把目录污染了
+- 想单独回看某个任务的改动范围时，很难分清
+
+也就是说，任务系统已经回答了“谁做什么”，却还没有回答：
+
+**每个任务应该在哪个独立工作空间里执行。**
+
+这就是 worktree 要解决的问题。
+
+## 建议联读
+
+- 如果你开始把 task、runtime slot、worktree lane 三层混成一个词，先看 [`team-task-lane-model.md`](./team-task-lane-model.md)。
+- 如果你想确认 worktree 记录和任务记录分别该保存哪些字段，回看 [`data-structures.md`](./data-structures.md)。
+- 如果你想从“参考仓库主干”角度确认这一章为什么必须晚于 tasks / teams，再看 [`s00e-reference-module-map.md`](./s00e-reference-module-map.md)。
+
+## 先解释几个名词
+
+### 什么是 worktree
+
+如果你熟悉 git，可以把 worktree 理解成：
+
+> 同一个仓库的另一个独立检出目录。
+
+如果你还不熟悉 git，也可以先把它理解成：
+
+> 一条属于某个任务的独立工作车道。
+
+### 什么叫隔离执行
+
+隔离执行就是：
+
+> 任务 A 在自己的目录里跑，任务 B 在自己的目录里跑，彼此默认不共享未提交改动。
+
+### 什么叫绑定
+
+绑定的意思是：
+
+> 把某个任务 ID 和某个 worktree 记录明确关联起来。
+
+## 最小心智模型
+
+最容易理解的方式，是把这一章拆成两张表：
+
+```text
+任务板
+  负责回答：做什么、谁在做、状态如何
+
+worktree 注册表
+  负责回答：在哪做、目录在哪、对应哪个任务
+```
+
+两者通过 `task_id` 连起来：
+
+```text
+.tasks/task_12.json
+  {
+    "id": 12,
+    "subject": "Refactor auth flow",
+    "status": "in_progress",
+    "worktree": "auth-refactor"
+  }
+
+.worktrees/index.json
+  {
+    "worktrees": [
+      {
+        "name": "auth-refactor",
+        "path": ".worktrees/auth-refactor",
+        "branch": "wt/auth-refactor",
+        "task_id": 12,
+        "status": "active"
+      }
+    ]
+  }
+```
+
+看懂这两条记录，这一章的主线就已经抓住了：
+
+**任务记录工作目标，worktree 记录执行车道。**
+
+## 关键数据结构
+
+### 1. TaskRecord 不再只记录 `worktree`
+
+到当前教学代码这一步，任务记录里和车道相关的字段已经不只一个：
+
+```python
+task = {
+    "id": 12,
+    "subject": "Refactor auth flow",
+    "status": "in_progress",
+    "owner": "alice",
+    "worktree": "auth-refactor",
+    "worktree_state": "active",
+    "last_worktree": "auth-refactor",
+    "closeout": None,
+}
+```
+
+这 4 个字段分别回答不同问题：
+
+- `worktree`：当前还绑定着哪条车道
+- `worktree_state`：这条绑定现在是 `active`、`kept`、`removed` 还是 `unbound`
+- `last_worktree`：最近一次用过哪条车道
+- `closeout`：最后一次收尾动作是什么
+
+为什么要拆这么细？
+
+因为到多 agent 并行阶段，系统已经不只需要知道“现在在哪做”，还需要知道：
+
+- 这条车道现在是不是还活着
+- 它最后是保留还是回收
+- 之后如果恢复或排查，应该看哪条历史车道
+
+### 2. WorktreeRecord 不只是路径映射
+
+```python
+worktree = {
+    "name": "auth-refactor",
+    "path": ".worktrees/auth-refactor",
+    "branch": "wt/auth-refactor",
+    "task_id": 12,
+    "status": "active",
+    "last_entered_at": 1710000000.0,
+    "last_command_at": 1710000012.0,
+    "last_command_preview": "pytest tests/auth -q",
+    "closeout": None,
+}
+```
+
+这里也要特别注意：
+
+worktree 记录回答的不只是“目录在哪”，还开始回答：
+
+- 最近什么时候进入过
+- 最近跑过什么命令
+- 最后是怎么收尾的
+
+这就是为什么这章讲的是：
+
+**可观察的执行车道**
+
+而不只是“多开一个目录”。
+
+### 3. CloseoutRecord
+
+这一章在当前代码里，一个完整的收尾记录大致是：
+
+```python
+closeout = {
+    "action": "keep",
+    "reason": "Need follow-up review",
+    "at": 1710000100.0,
+}
+```
+
+这层记录很重要，因为它把“结尾到底发生了什么”显式写出来，而不是靠人猜：
+
+- 是保留目录，方便继续追看
+- 还是回收目录，表示这条执行车道已经结束
+
+### 4. EventRecord
+
+```python
+event = {
+    "event": "worktree.closeout.keep",
+    "task_id": 12,
+    "worktree": "auth-refactor",
+    "reason": "Need follow-up review",
+    "ts": 1710000100.0,
+}
+```
+
+为什么还要事件记录？
+
+因为 worktree 的生命周期经常跨很多步：
+
+- 创建
+- 进入
+- 运行命令
+- 保留
+- 删除
+- 删除失败
+
+有显式事件日志，会比只看当前状态更容易排查问题。
+
+## 最小实现
+
+### 第一步：先有任务，再有 worktree
+
+不要先开目录再回头补任务。
+
+更清楚的顺序是：
+
+1. 先创建任务
+2. 再为这个任务分配 worktree
+
+```python
+task = tasks.create("Refactor auth flow")
+worktrees.create("auth-refactor", task_id=task["id"])
+```
+
+### 第二步：创建 worktree 并写入注册表
+
+```python
+def create(self, name: str, task_id: int):
+    path = self.root / ".worktrees" / name
+    branch = f"wt/{name}"
+
+    run_git(["worktree", "add", "-b", branch, str(path), "HEAD"])
+
+    record = {
+        "name": name,
+        "path": str(path),
+        "branch": branch,
+        "task_id": task_id,
+        "status": "active",
+    }
+    self.index["worktrees"].append(record)
+    self._save_index()
+```
+
+### 第三步：同时更新任务记录，不只是写一个 `worktree`
+
+```python
+def bind_worktree(task_id: int, name: str):
+    task = tasks.load(task_id)
+    task["worktree"] = name
+    task["last_worktree"] = name
+    task["worktree_state"] = "active"
+    if task["status"] == "pending":
+        task["status"] = "in_progress"
+    tasks.save(task)
+```
+
+为什么这一步很关键？
+
+因为如果只更新 worktree 注册表，不更新任务记录，系统就无法从任务板一眼看出“这个任务在哪个隔离目录里做”。
+
+### 第四步：显式进入车道，再在对应目录里执行命令
+
+当前代码里，进入和运行已经拆成两步：
+
+```python
+worktree_enter("auth-refactor")
+worktree_run("auth-refactor", "pytest tests/auth -q")
+```
+
+对应到底层，大致就是：
+
+```python
+def enter(self, name: str):
+    self._update_entry(name, last_entered_at=time.time())
+    self.events.emit("worktree.enter", ...)
+
+def run(self, name: str, command: str):
+    subprocess.run(command, cwd=worktree_path, ...)
+```
+
+```python
+subprocess.run(command, cwd=worktree_path, ...)
+```
+
+这一行看起来普通，但它正是隔离的核心：
+
+**同一个命令，在不同 `cwd` 里执行，影响范围就不一样。**
+
+为什么还要单独补一个 `worktree_enter`？
+
+因为教学上你要让读者看见：
+
+- “分配车道”是一回事
+- “真正进入并开始在这条车道里工作”是另一回事
+
+这层边界一清楚，后面的观察字段才有意义：
+
+- `last_entered_at`
+- `last_command_at`
+- `last_command_preview`
+
+### 第五步：收尾时显式走 `worktree_closeout`
+
+不要让收尾是隐式的。
+
+当前更清楚的教学接口不是“分散记两个命令”，而是统一成一个 closeout 动作：
+
+```python
+worktree_closeout(
+    name="auth-refactor",
+    action="keep",   # or "remove"
+    reason="Need follow-up review",
+    complete_task=False,
+)
+```
+
+这样读者会更容易理解：
+
+- 收尾一定要选动作
+- 收尾可以带原因
+- 收尾会同时回写任务记录、车道记录和事件日志
+
+当然，底层仍然保留：
+
+- `worktree_keep(name)`
+- `worktree_remove(name, reason=..., complete_task=True)`
+
+但教学主线最好先把：
+
+> `keep` 和 `remove` 看成同一个 closeout 决策的两个分支
+
+这样读者心智会更顺。
+
+## 为什么 `worktree_state` 和 `status` 要分开
+
+这也是一个很容易被忽略的细点。
+
+很多初学者会想：
+
+> “任务有 `status` 了，为什么还要 `worktree_state`？”
+
+因为这两个状态根本不是一层东西：
+
+- 任务 `status` 回答：这件工作现在是 `pending`、`in_progress` 还是 `completed`
+- `worktree_state` 回答：这条执行车道现在是 `active`、`kept`、`removed` 还是 `unbound`
+
+举个最典型的例子：
+
+```text
+任务已经 completed
+  但 worktree 仍然 kept
+```
+
+这完全可能，而且很常见。  
+比如你已经做完了，但还想保留目录给 reviewer 看。
+
+所以：
+
+**任务状态和车道状态不能混成一个字段。**
+
+## 为什么 worktree 不是“只是一个 git 小技巧”
+
+很多初学者第一次看到这一章，会觉得：
+
+> “这不就是多开几个目录吗？”
+
+这句话只说对了一半。
+
+真正关键的不只是“多开目录”，而是：
+
+**把任务和执行目录做显式绑定，让并行工作有清楚的边界。**
+
+如果没有这层绑定，系统仍然不知道：
+
+- 哪个目录属于哪个任务
+- 收尾时该完成哪条任务
+- 崩溃后该恢复哪条关系
+
+## 如何接到前面章节里
+
+这章和前面几章是强耦合的：
+
+- `s12` 提供任务 ID
+- `s15-s17` 提供队友和认领机制
+- `s18` 则给这些任务提供独立执行车道
+
+把三者连起来看，会变成：
+
+```text
+任务被创建
+  ->
+队友认领任务
+  ->
+系统为任务分配 worktree
+  ->
+命令在对应目录里执行
+  ->
+任务完成时决定保留还是删除 worktree
+```
+
+这条链一旦建立，多 agent 并行工作就会清楚很多。
+
+## worktree 不是任务本身，而是任务的执行车道
+
+这句话值得单独再说一次。
+
+很多读者第一次学到这里时，会把这两个词混着用：
+
+- task
+- worktree
+
+但它们回答的其实不是同一个问题：
+
+- task：做什么
+- worktree：在哪做
+
+所以更完整、也更不容易混的表达方式是：
+
+- 工作图任务
+- worktree 执行车道
+
+如果你开始分不清：
+
+- 任务
+- 运行时任务
+- worktree
+
+建议回看：
+
+- [`team-task-lane-model.md`](./team-task-lane-model.md)
+- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)
+- [`entity-map.md`](./entity-map.md)
+
+## 初学者最容易犯的错
+
+### 1. 有 worktree 注册表，但任务记录里没有 `worktree`
+
+这样任务板就丢掉了最重要的一条执行信息。
+
+### 2. 有任务 ID，但命令仍然在主目录执行
+
+如果 `cwd` 没切过去，worktree 形同虚设。
+
+### 3. 只会 `worktree_remove`，不会解释 closeout 的含义
+
+这样读者最后只记住“删目录”这个动作，却不知道系统真正想表达的是：
+
+- 保留
+- 回收
+- 为什么这么做
+- 是否同时完结对应任务
+
+### 4. 删除 worktree 前不看未提交改动
+
+这是最危险的一类错误。
+
+教学版也应该至少先建立一个原则：
+
+**删除前先检查是否有脏改动。**
+
+### 5. 没有 `worktree_state` / `closeout` 这类显式收尾状态
+
+这样系统就会只剩下“现在目录还在不在”，而没有：
+
+- 这条车道最后怎么收尾
+- 是主动保留还是主动删除
+
+### 6. 把 worktree 当成长期垃圾堆
+
+如果从不清理，目录会越来越多，状态越来越乱。
+
+### 7. 没有事件日志
+
+一旦创建失败、删除失败或任务关系错乱，没有事件日志会很难排查。
+
+## 教学边界
+
+这章先要讲透的不是所有 worktree 运维细节，而是主干分工：
+
+- task 记录“做什么”
+- worktree 记录“在哪做”
+- enter / execute / closeout 串起这条隔离执行车道
+
+只要这条主干清楚，教学目标就已经达成。
+
+崩溃恢复、删除安全检查、全局缓存区、非 git 回退这些，都应该放在这条主干之后。
+
+## 试一试
+
+```sh
+cd learn-claude-code
+python agents/s18_worktree_task_isolation.py
+```
+
+可以试试这些任务：
+
+1. 为两个不同任务各建一个 worktree，观察任务板和注册表的对应关系。
+2. 分别在两个 worktree 里运行 `git status`，感受目录隔离。
+3. 删除一个 worktree，并确认对应任务是否被正确收尾。
+
+读完这一章，你应该能自己说清楚这句话：
+
+**任务系统管“做什么”，worktree 系统管“在哪做且互不干扰”。**
diff --git a/docs/zh/s19-mcp-plugin.md b/docs/zh/s19-mcp-plugin.md
new file mode 100644
index 000000000..af745fc86
--- /dev/null
+++ b/docs/zh/s19-mcp-plugin.md
@@ -0,0 +1,392 @@
+# s19: MCP & Plugin System (MCP 与插件系统)
+
+`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > [ s19 ]`
+
+> *工具不必都写死在主程序里。外部进程也可以把能力接进你的 agent。*
+
+## 这一章到底在讲什么
+
+前面所有章节里，工具基本都写在你自己的 Python 代码里。
+
+这当然是最适合教学的起点。
+
+但真实系统走到一定阶段以后，会很自然地遇到这个需求：
+
+> “能不能让外部程序也把工具接进来，而不用每次都改主程序？”
+
+这就是 MCP 要解决的问题。
+
+## 先用最简单的话解释 MCP
+
+你可以先把 MCP 理解成：
+
+**一套让 agent 和外部工具程序对话的统一协议。**
+
+在教学版里，不必一开始就背很多协议细节。  
+你只要先抓住这条主线：
+
+1. 启动一个外部工具服务进程
+2. 问它“你有哪些工具”
+3. 当模型要用它的工具时，把请求转发给它
+4. 再把结果带回 agent 主循环
+
+这已经够理解 80% 的核心机制了。
+
+## 为什么这一章放在最后
+
+因为 MCP 不是主循环的起点，而是主循环稳定之后的扩展层。
+
+如果你还没真正理解：
+
+- agent loop
+- tool call
+- permission
+- task
+- worktree
+
+那 MCP 只会看起来像又一套复杂接口。
+
+但当你已经有了前面的心智，再看 MCP，你会发现它本质上只是：
+
+**把“工具来源”从“本地硬编码”升级成“外部可插拔”。**
+
+## 建议联读
+
+- 如果你只把 MCP 理解成“远程 tools”，先看 [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)，把 tools、resources、prompts、plugin 中介层一起放回平台边界里。
+- 如果你想确认外部能力为什么仍然要回到同一条执行面，回看 [`s02b-tool-execution-runtime.md`](./s02b-tool-execution-runtime.md)。
+- 如果你开始把“query 控制平面”和“外部能力路由”完全分开理解，建议配合看 [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)。
+
+## 最小心智模型
+
+```text
+LLM
+  |
+  | asks to call a tool
+  v
+Agent tool router
+  |
+  +-- native tool  -> 本地 Python handler
+  |
+  +-- MCP tool     -> 外部 MCP server
+                        |
+                        v
+                    return result
+```
+
+## 最小系统里最重要的三件事
+
+### 1. 有一个 MCP client
+
+它负责：
+
+- 启动外部进程
+- 发送请求
+- 接收响应
+
+### 2. 有一个工具名前缀规则
+
+这是为了避免命名冲突。
+
+最常见的做法是：
+
+```text
+mcp__{server}__{tool}
+```
+
+比如：
+
+```text
+mcp__postgres__query
+mcp__browser__open_tab
+```
+
+这样一眼就知道：
+
+- 这是 MCP 工具
+- 它来自哪个 server
+- 它原始工具名是什么
+
+### 3. 有一个统一路由器
+
+路由器只做一件事：
+
+- 如果是本地工具，就交给本地 handler
+- 如果是 MCP 工具，就交给 MCP client
+
+## Plugin 又是什么
+
+如果 MCP 解决的是“外部工具怎么通信”，  
+那 plugin 解决的是“这些外部工具配置怎么被发现”。
+
+最小 plugin 可以非常简单：
+
+```text
+.claude-plugin/
+  plugin.json
+```
+
+里面写：
+
+- 插件名
+- 版本
+- 它提供哪些 MCP server
+- 每个 server 的启动命令是什么
+
+## 最小配置长什么样
+
+```json
+{
+  "name": "my-db-tools",
+  "version": "1.0.0",
+  "mcpServers": {
+    "postgres": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-postgres"]
+    }
+  }
+}
+```
+
+这个配置并不复杂。
+
+它本质上只是在告诉主程序：
+
+> “如果你想接这个 server，就用这条命令把它拉起来。”
+
+## 最小实现步骤
+
+### 第一步：写一个 `MCPClient`
+
+它至少要有三个能力：
+
+- `connect()`
+- `list_tools()`
+- `call_tool()`
+
+### 第二步：把外部工具标准化成 agent 能看懂的工具定义
+
+也就是说，把 MCP server 暴露的工具，转成 agent 工具池里的统一格式。
+
+### 第三步：加前缀
+
+这样主程序就能区分：
+
+- 本地工具
+- 外部工具
+
+### 第四步：写一个 router
+
+```python
+if tool_name.startswith("mcp__"):
+    return mcp_router.call(tool_name, arguments)
+else:
+    return native_handler(arguments)
+```
+
+### 第五步：仍然走同一条权限管道
+
+这是非常关键的一点：
+
+**MCP 工具虽然来自外部，但不能绕开 permission。**
+
+不然你等于在系统边上开了个安全后门。
+
+如果你想把这一层再收得更稳，最好再把结果也标准化回同一条总线：
+
+```python
+{
+    "source": "mcp",
+    "server": "figma",
+    "tool": "inspect",
+    "status": "ok",
+    "preview": "...",
+}
+```
+
+这表示：
+
+- 路由前要过共享权限闸门
+- 路由后不论本地还是远程，结果都要转成主循环看得懂的统一格式
+
+## 如何接到整个系统里
+
+如果你读到这里还觉得 MCP 像“外挂”，通常是因为没有把它放回整条主回路里。
+
+更完整的接法应该看成：
+
+```text
+启动时
+  ->
+PluginLoader 找到 manifest
+  ->
+得到 server 配置
+  ->
+MCP client 连接 server
+  ->
+list_tools 并标准化名字
+  ->
+和 native tools 一起合并进同一个工具池
+
+运行时
+  ->
+LLM 产出 tool_use
+  ->
+统一权限闸门
+  ->
+native route 或 mcp route
+  ->
+结果标准化
+  ->
+tool_result 回到同一个主循环
+```
+
+这段流程里最关键的不是“外部”两个字，而是：
+
+**进入方式不同，但进入后必须回到同一条控制面和执行面。**
+
+## Plugin、MCP Server、MCP Tool 不要混成一层
+
+这是初学者最容易在本章里打结的地方。
+
+可以直接按下面三层记：
+
+| 层级 | 它是什么 | 它负责什么 |
+|---|---|---|
+| plugin manifest | 一份配置声明 | 告诉系统要发现和启动哪些 server |
+| MCP server | 一个外部进程 / 连接对象 | 对外暴露一组能力 |
+| MCP tool | server 暴露的一项具体调用能力 | 真正被模型点名调用 |
+
+换成一句最短的话说：
+
+- plugin 负责“发现”
+- server 负责“连接”
+- tool 负责“调用”
+
+只要这三层还分得清，MCP 这章的主体心智就不会乱。
+
+## 这一章最关键的数据结构
+
+### 1. server 配置
+
+```python
+{
+    "command": "npx",
+    "args": ["-y", "..."],
+    "env": {}
+}
+```
+
+### 2. 标准化后的工具定义
+
+```python
+{
+    "name": "mcp__postgres__query",
+    "description": "Run a SQL query",
+    "input_schema": {...}
+}
+```
+
+### 3. client 注册表
+
+```python
+clients = {
+    "postgres": mcp_client_instance
+}
+```
+
+## 初学者最容易被带偏的地方
+
+### 1. 一上来讲太多协议细节
+
+这章最容易失控。
+
+因为一旦开始讲完整协议生态，很快会出现：
+
+- transports
+- auth
+- resources
+- prompts
+- streaming
+- connection recovery
+
+这些都存在，但不该挡住主线。
+
+主线只有一句话：
+
+**外部工具也能像本地工具一样接进 agent。**
+
+### 2. 把 MCP 当成一套完全不同的工具系统
+
+不是。
+
+它最终仍然应该汇入你原来的工具体系：
+
+- 一样要注册
+- 一样要出现在工具池里
+- 一样要过权限
+- 一样要返回 `tool_result`
+
+### 3. 忽略命名与路由
+
+如果没有统一前缀和统一路由，系统会很快乱掉。
+
+## 教学边界
+
+这一章正文先停在 `tools-first` 是对的。
+
+因为教学主线最需要先讲清的是：
+
+- 外部能力怎样被发现
+- 怎样被统一命名和路由
+- 怎样继续经过同一条权限与 `tool_result` 回流
+
+只要这一层已经成立，读者就已经真正理解了：
+
+**MCP / plugin 不是外挂，而是接回同一控制面的外部能力入口。**
+
+transport、认证、resources、prompts、插件生命周期这些更大范围的内容，应该放到平台桥接资料里继续展开。
+
+## 正文先停在 tools-first，平台层再看桥接文档
+
+这一章的正文故意停在“外部工具如何接进 agent”这一层。  
+这是教学上的刻意取舍，不是缺失。
+
+如果你准备继续补平台边界，再去看：
+
+- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)
+
+那篇会把 MCP 再往上补成一张平台地图，包括：
+
+- server 配置作用域
+- transport 类型
+- 连接状态：`connected / pending / needs-auth / failed / disabled`
+- tools 之外的 `resources / prompts / elicitation`
+- auth 该放在哪一层理解
+
+这样安排的好处是：
+
+- 正文不失焦
+- 读者又不会误以为 MCP 只有一个 `list_tools + call_tool`
+
+## 这一章和全仓库的关系
+
+如果说前 18 章都在教你把系统内部搭起来，  
+那 `s19` 在教你：
+
+**如何把系统向外打开。**
+
+从这里开始，工具不再只来自你手写的 Python 文件，  
+还可以来自别的进程、别的系统、别的服务。
+
+这就是为什么它适合作为最后一章。
+
+## 学完这章后，你应该能回答
+
+- MCP 的核心到底是什么？
+- 为什么它应该放在整个学习路径的最后？
+- 为什么 MCP 工具也必须走同一条权限与路由逻辑？
+- plugin 和 MCP 分别解决什么问题？
+
+---
+
+**一句话记住：MCP 的本质，不是协议名词堆砌，而是把外部工具安全、统一地接进你的 agent。**
diff --git a/docs/zh/s19a-mcp-capability-layers.md b/docs/zh/s19a-mcp-capability-layers.md
new file mode 100644
index 000000000..cd7736507
--- /dev/null
+++ b/docs/zh/s19a-mcp-capability-layers.md
@@ -0,0 +1,266 @@
+# s19a: MCP Capability Layers (MCP 能力层地图)
+
+> `s19` 的主线仍然应该坚持“先做 tools-first”。  
+> 这篇桥接文档负责补上另一层心智：
+>
+> **MCP 不只是外部工具接入，它是一组能力层。**
+
+## 建议怎么联读
+
+如果你希望 MCP 这块既不学偏，也不学浅，推荐这样看：
+
+- 先看 [`s19-mcp-plugin.md`](./s19-mcp-plugin.md)，先把 tools-first 主线走通。
+- 再看 [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md)，确认外部能力最后怎样接回统一工具总线。
+- 如果状态结构开始混，再对照 [`data-structures.md`](./data-structures.md)。
+- 如果概念边界开始混，再回 [`glossary.md`](./glossary.md) 和 [`entity-map.md`](./entity-map.md)。
+
+## 为什么要单独补这一篇
+
+如果你是为了教学，从 0 到 1 手搓一个类似系统，那么 `s19` 主线先只讲外部工具，这是对的。
+
+因为最容易理解的入口就是：
+
+- 连接一个外部 server
+- 拿到工具列表
+- 调用工具
+- 把结果带回 agent
+
+但如果你想把系统做到接近 95%-99% 的还原度，你迟早会遇到这些问题：
+
+- server 是用 stdio、http、sse 还是 ws 连接？
+- 为什么有些 server 是 connected，有些是 pending，有些是 needs-auth？
+- tools 之外，resources 和 prompts 是什么位置？
+- elicitation 为什么会变成一类特殊交互？
+- OAuth / XAA 这种认证流程该放在哪一层理解？
+
+这时候如果没有一张“能力层地图”，MCP 就会越学越散。
+
+## 先解释几个名词
+
+### 什么是能力层
+
+能力层，就是把一个复杂系统拆成几层职责清楚的面。
+
+这里的意思是：
+
+> 不要把所有 MCP 细节混成一团，而要知道每一层到底解决什么问题。
+
+### 什么是 transport
+
+`transport` 可以理解成“连接通道”。
+
+比如：
+
+- stdio
+- http
+- sse
+- websocket
+
+### 什么是 elicitation
+
+这个词比较生。
+
+你可以先把它理解成：
+
+> 外部 MCP server 反过来向用户请求额外输入的一种交互。
+
+也就是说，不再只是 agent 主动调工具，而是 server 也能说：
+
+“我还需要你给我一点信息，我才能继续。”
+
+## 最小心智模型
+
+先把 MCP 画成 6 层：
+
+```text
+1. Config Layer
+   server 配置长什么样
+
+2. Transport Layer
+   用什么通道连 server
+
+3. Connection State Layer
+   现在是 connected / pending / failed / needs-auth
+
+4. Capability Layer
+   tools / resources / prompts / elicitation
+
+5. Auth Layer
+   是否需要认证，认证状态如何
+
+6. Router Integration Layer
+   如何接回 tool router / permission / notifications
+```
+
+最重要的一点是：
+
+**tools 只是其中一层，不是全部。**
+
+## 为什么正文仍然应该坚持 tools-first
+
+这点非常重要。
+
+虽然 MCP 平台本身有多层能力，但正文主线仍然应该这样安排：
+
+### 第一步：先教外部 tools
+
+因为它和前面的主线最自然衔接：
+
+- 本地工具
+- 外部工具
+- 同一条 router
+
+### 第二步：再告诉读者还有其他能力层
+
+例如：
+
+- resources
+- prompts
+- elicitation
+- auth
+
+### 第三步：再决定是否继续实现
+
+这才符合你的教学目标：
+
+**先做出类似系统，再补平台层高级能力。**
+
+## 关键数据结构
+
+### 1. ScopedMcpServerConfig
+
+最小教学版建议至少让读者看到这个概念：
+
+```python
+config = {
+    "name": "postgres",
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "..."],
+    "scope": "project",
+}
+```
+
+这里的 `scope` 很重要。
+
+因为 server 配置不一定都来自同一个地方。
+
+### 2. MCP Connection State
+
+```python
+server_state = {
+    "name": "postgres",
+    "status": "connected",   # pending / failed / needs-auth / disabled
+    "config": {...},
+}
+```
+
+### 3. MCPToolSpec
+
+```python
+tool = {
+    "name": "mcp__postgres__query",
+    "description": "...",
+    "input_schema": {...},
+}
+```
+
+### 4. ElicitationRequest
+
+```python
+request = {
+    "server_name": "some-server",
+    "message": "Please provide additional input",
+    "requested_schema": {...},
+}
+```
+
+这一步不是要求你主线立刻实现它，而是要让读者知道：
+
+**MCP 不一定永远只是“模型调工具”。**
+
+## 一张更完整但仍然清楚的图
+
+```text
+MCP Config
+  |
+  v
+Transport
+  |
+  v
+Connection State
+  |
+  +-- connected
+  +-- pending
+  +-- needs-auth
+  +-- failed
+  |
+  v
+Capabilities
+  +-- tools
+  +-- resources
+  +-- prompts
+  +-- elicitation
+  |
+  v
+Router / Permission / Notification Integration
+```
+
+## Auth 为什么不要在主线里讲太多
+
+这也是教学取舍里很重要的一点。
+
+认证是真实系统里确实存在的能力层。  
+但如果正文一开始就掉进 OAuth/XAA 流程，初学者会立刻丢主线。
+
+所以更好的讲法是：
+
+- 先告诉读者：有 auth layer
+- 再告诉读者：connected / needs-auth 是不同连接状态
+- 只有做平台层进阶时，再详细展开认证流程
+
+这就既没有幻觉，也没有把人带偏。
+
+## 它和 `s19`、`s02a` 的关系
+
+- `s19` 正文继续负责 tools-first 教学
+- 这篇负责补清平台层地图
+- `s02a` 的 Tool Control Plane 则解释 MCP 最终怎么接回统一工具总线
+
+三者合在一起，读者才会真正知道：
+
+**MCP 是外部能力平台，而 tools 只是它最先进入主线的那个切面。**
+
+## 初学者最容易犯的错
+
+### 1. 把 MCP 只理解成“外部工具目录”
+
+这会让后面遇到 auth / resources / prompts / elicitation 时很困惑。
+
+### 2. 一上来就沉迷 transport 和 OAuth 细节
+
+这样会直接打断主线。
+
+### 3. 让 MCP 工具绕过 permission
+
+这会在系统边上开一个很危险的后门。
+
+### 4. 不区分 server 配置、连接状态、能力暴露
+
+这三层一混，平台层就会越学越乱。
+
+## 教学边界
+
+这篇最重要的，不是把 MCP 所有外设细节都讲完，而是先守住四层边界：
+
+- server 配置
+- 连接状态
+- capability 暴露
+- permission / routing 接入点
+
+只要这四层不混，你就已经能自己手搓一个接近真实系统主脉络的外部能力入口。  
+认证状态机、resource/prompt 接入、server 回问和重连策略，都属于后续平台扩展。
+
+## 一句话记住
+
+**`s19` 主线应该先教“外部工具接入”，而平台层还需要额外理解 MCP 的能力层地图。**
diff --git a/docs/zh/teaching-scope.md b/docs/zh/teaching-scope.md
new file mode 100644
index 000000000..3f87cd660
--- /dev/null
+++ b/docs/zh/teaching-scope.md
@@ -0,0 +1,213 @@
+# Teaching Scope (教学范围说明)
+
+> 这份文档不是讲某一章，而是说明整个教学仓库到底要教什么、不教什么，以及每一章应该怎么写才不会把读者带偏。
+
+## 这份仓库的目标
+
+这不是一份“逐行对照某份源码”的注释仓库。
+
+这份仓库真正的目标是：
+
+**教开发者从 0 到 1 手搓一个结构完整、高保真的 coding agent harness。**
+
+这里强调 3 件事：
+
+1. 读者真的能自己实现出来。
+2. 读者能抓住系统主脉络，而不是淹没在边角细节里。
+3. 读者对关键机制的理解足够高保真，不会学到不存在的机制。
+
+## 什么必须讲清楚
+
+主线章节必须优先讲清下面这些内容：
+
+- 整个系统有哪些核心模块
+- 模块之间如何协作
+- 每个模块解决什么问题
+- 关键状态保存在哪里
+- 关键数据结构长什么样
+- 主循环如何把这些机制接进来
+
+如果一个章节讲完以后，读者还不知道“这个机制到底放在系统哪一层、保存了哪些状态、什么时候被调用”，那这章就还没讲透。
+
+## 什么不要占主线篇幅
+
+下面这些内容，不是完全不能提，而是**不应该占用主线正文的大量篇幅**：
+
+- 打包、编译、发布流程
+- 跨平台兼容胶水
+- 遥测、企业策略、账号体系
+- 与教学主线无关的历史兼容分支
+- 只对特定产品环境有意义的接线细节
+- 某份上游源码里的函数名、文件名、行号级对照
+
+这些内容最多作为：
+
+- 维护者备注
+- 附录
+- 桥接资料里的平台扩展说明
+
+而不应该成为初学者第一次学习时的主线。
+
+## 真正的“高保真”是什么意思
+
+教学仓库追求的高保真，不是所有边角细节都 1:1。
+
+这里的高保真，是指这些东西要尽量贴近真实系统主干：
+
+- 核心运行模式
+- 主要模块边界
+- 关键数据结构
+- 模块之间的协作方式
+- 关键状态转换
+
+换句话说：
+
+**主干尽量高保真，外围细节可以做教学取舍。**
+
+## 面向谁来写
+
+本仓库默认读者不是“已经做过复杂 agent 平台的人”。
+
+更合理的默认读者应该是：
+
+- 会一点编程
+- 能读懂基本 Python
+- 但没有系统实现过 agent
+
+所以写作时要假设：
+
+- 很多术语是第一次见
+- 很多系统设计名词不能直接甩出来不解释
+- 同一个概念不能分散在五个地方才拼得完整
+
+## 每一章的推荐结构
+
+主线章节尽量遵守这条顺序：
+
+1. `这一章要解决什么问题`
+2. `先解释几个名词`
+3. `最小心智模型`
+4. `关键数据结构`
+5. `最小实现`
+6. `如何接到主循环里`
+7. `初学者最容易犯的错`
+8. `教学边界`
+
+这条顺序的价值在于：
+
+- 先让读者知道为什么需要这个机制
+- 再让读者知道这个机制到底是什么
+- 然后马上看到它怎么落地
+
+这里把最后一节写成 `教学边界`，而不是“继续补一大串外围复杂度清单”，是因为教学仓库更应该先帮读者守住：
+
+- 这一章先学到哪里就够了
+- 哪些复杂度现在不要一起拖进来
+- 读者真正该自己手搓出来的最小正确版本是什么
+
+## 术语使用规则
+
+只要出现这些类型的词，就应该解释：
+
+- 软件设计模式
+- 数据结构名词
+- 并发与进程相关名词
+- 协议与网络相关名词
+- 初学者不熟悉的工程术语
+
+例如：
+
+- 状态机
+- 调度器
+- 队列
+- worktree
+- DAG
+- 协议 envelope
+
+不要只给名字，不给解释。
+
+## “最小正确版本”原则
+
+很多真实机制都很复杂。
+
+但教学版不应该一开始就把所有分支一起讲。
+
+更好的顺序是：
+
+1. 先给出一个最小但正确的版本
+2. 解释它已经解决了哪部分核心问题
+3. 再讲如果继续迭代应该补什么
+
+例如：
+
+- 权限系统先做 `deny -> mode -> allow -> ask`
+- 错误恢复先做 3 条主恢复路径
+- 任务系统先做任务记录、依赖、解锁
+- 团队协议先做 request/response + request_id
+
+## 文档和代码要一起维护，而不是各讲各的
+
+如果正文和本地 `agents/*.py` 没有对齐，读者一打开代码就会重新混乱。
+
+所以维护者重写章节时，应该同步检查三件事：
+
+1. 这章正文里的关键状态，代码里是否真有对应结构
+2. 这章正文里的主回路，代码里是否真有对应入口函数
+3. 这章正文里强调的“教学边界”，代码里是否也没有提前塞进过多外层复杂度
+
+最稳的做法是让每章都能对应到：
+
+- 1 个主文件
+- 1 组关键状态结构
+- 1 条最值得先看的执行路径
+
+如果维护者需要一份“按章节读本仓库代码”的地图，建议配合看：
+
+- [`s00f-code-reading-order.md`](./s00f-code-reading-order.md)
+
+## 维护者重写时的检查清单
+
+如果你在重写某一章，可以用下面这份清单自检：
+
+- 这章第一屏有没有明确说明“为什么需要它”
+- 是否先解释了新名词，再使用新名词
+- 是否给出了最小心智模型图或流程
+- 是否明确列出关键数据结构
+- 是否说明了它如何接进主循环
+- 是否区分了“核心机制”和“产品化外围细节”
+- 是否列出了初学者最容易混淆的点
+- 是否避免制造源码里并不存在的幻觉机制
+
+## 维护者如何使用“逆向源码”
+
+逆向得到的源码，在这套仓库里应当只扮演一个角色：
+
+**维护者的校准参考。**
+
+它的用途是：
+
+- 校验主干机制有没有讲错
+- 校验关键状态和模块边界有没有遗漏
+- 校验教学实现有没有偏离到错误方向
+
+它不应该成为读者理解正文的前提。
+
+正文应该做到：
+
+> 即使读者完全不看那份源码，也能把核心系统自己做出来。
+
+## 这份教学仓库应该追求什么分数
+
+如果满分是 150 分，一个接近满分的教学仓库应同时做到：
+
+- 主线清楚
+- 章节顺序合理
+- 新名词解释完整
+- 数据结构清晰
+- 机制边界准确
+- 例子可运行
+- 升级路径自然
+
+真正决定分数高低的，不是“提到了多少细节”，而是：
+
+**提到的关键细节是否真的讲透，没提的非关键细节是否真的可以安全省略。**
diff --git a/docs/zh/team-task-lane-model.md b/docs/zh/team-task-lane-model.md
new file mode 100644
index 000000000..6385733aa
--- /dev/null
+++ b/docs/zh/team-task-lane-model.md
@@ -0,0 +1,339 @@
+# Team Task Lane Model (队友-任务-车道模型)
+
+> 到了 `s15-s18`，读者最容易混掉的，不是某个函数名，而是：
+>
+> **系统里到底是谁在工作、谁在协调、谁在记录目标、谁在提供执行目录。**
+
+## 这篇桥接文档解决什么问题
+
+如果你一路从 `s15` 看到 `s18`，脑子里很容易把下面这些词混在一起：
+
+- teammate
+- protocol request
+- task
+- runtime task
+- worktree
+
+它们都和“工作推进”有关。  
+但它们不是同一层。
+
+如果这层边界不单独讲清，后面读者会经常出现这些困惑：
+
+- 队友是不是任务本身？
+- `request_id` 和 `task_id` 有什么区别？
+- worktree 是不是后台任务的一种？
+- 一个任务完成了，为什么 worktree 还能保留？
+
+这篇就是专门用来把这几层拆开的。
+
+## 建议怎么联读
+
+最推荐的读法是：
+
+1. 先看 [`s15-agent-teams.md`](./s15-agent-teams.md)，确认长期队友在讲什么。
+2. 再看 [`s16-team-protocols.md`](./s16-team-protocols.md)，确认请求-响应协议在讲什么。
+3. 再看 [`s17-autonomous-agents.md`](./s17-autonomous-agents.md)，确认自治认领在讲什么。
+4. 最后看 [`s18-worktree-task-isolation.md`](./s18-worktree-task-isolation.md)，确认隔离执行车道在讲什么。
+
+如果你开始混：
+
+- 回 [`entity-map.md`](./entity-map.md) 看模块边界。
+- 回 [`data-structures.md`](./data-structures.md) 看记录结构。
+- 回 [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) 看“目标任务”和“运行时执行槽位”的差别。
+
+## 先给结论
+
+先记住这一组最重要的区分：
+
+```text
+teammate
+  = 谁在长期参与协作
+
+protocol request
+  = 团队内部一次需要被追踪的协调请求
+
+task
+  = 要做什么
+
+runtime task / execution slot
+  = 现在有什么执行单元正在跑
+
+worktree
+  = 在哪做，而且不和别人互相踩目录
+```
+
+这五层里，最容易混的是最后三层：
+
+- `task`
+- `runtime task`
+- `worktree`
+
+所以你必须反复问自己：
+
+- 这是“目标”吗？
+- 这是“执行中的东西”吗？
+- 这是“执行目录”吗？
+
+## 一张最小清晰图
+
+```text
+Team Layer
+  teammate: alice (frontend)
+  teammate: bob (backend)
+
+Protocol Layer
+  request_id=req_01
+  kind=plan_approval
+  status=pending
+
+Work Graph Layer
+  task_id=12
+  subject="Implement login page"
+  owner="alice"
+  status="in_progress"
+
+Runtime Layer
+  runtime_id=rt_01
+  type=in_process_teammate
+  status=running
+
+Execution Lane Layer
+  worktree=login-page
+  path=.worktrees/login-page
+  status=active
+```
+
+你可以看到：
+
+- `alice` 不是任务
+- `request_id` 不是任务
+- `runtime_id` 也不是任务
+- `worktree` 更不是任务
+
+真正表达“这件工作本身”的，只有 `task_id=12` 那层。
+
+## 1. Teammate：谁在长期协作
+
+这是 `s15` 开始建立的层。
+
+它回答的是：
+
+- 这个长期 worker 叫什么
+- 它是什么角色
+- 它当前是 working、idle 还是 shutdown
+- 它有没有独立 inbox
+
+最小例子：
+
+```python
+member = {
+    "name": "alice",
+    "role": "frontend",
+    "status": "idle",
+}
+```
+
+这层的核心不是“又多开一个 agent”。
+
+而是：
+
+> 系统开始有长期存在、可重复接活、可被点名协作的身份。
+
+## 2. Protocol Request：谁在协调什么
+
+这是 `s16` 建立的层。
+
+它回答的是：
+
+- 有谁向谁发起了一个需要追踪的请求
+- 这条请求是什么类型
+- 它现在是 pending、approved 还是 rejected
+
+最小例子：
+
+```python
+request = {
+    "request_id": "a1b2c3d4",
+    "kind": "plan_approval",
+    "from": "alice",
+    "to": "lead",
+    "status": "pending",
+}
+```
+
+这一层不要和普通聊天混。
+
+因为它不是“发一条消息就算完”，而是：
+
+> 一条可以被继续更新、继续审核、继续恢复的协调记录。
+
+## 3. Task：要做什么
+
+这是 `s12` 的工作图任务，也是 `s17` 自治认领的对象。
+
+它回答的是：
+
+- 目标是什么
+- 谁负责
+- 是否有阻塞
+- 当前进度如何
+
+最小例子：
+
+```python
+task = {
+    "id": 12,
+    "subject": "Implement login page",
+    "status": "in_progress",
+    "owner": "alice",
+    "blockedBy": [],
+}
+```
+
+这层的关键词是：
+
+**目标**
+
+不是目录，不是协议，不是进程。
+
+## 4. Runtime Task / Execution Slot：现在有什么执行单元在跑
+
+这一层在 `s13` 的桥接文档里已经单独解释过，但到了 `s15-s18` 必须再提醒一次。
+
+比如：
+
+- 一个后台 shell 正在跑
+- 一个长期 teammate 正在工作
+- 一个 monitor 正在观察外部状态
+
+这些都更像：
+
+> 正在运行的执行槽位
+
+而不是“任务目标本身”。
+
+最小例子：
+
+```python
+runtime = {
+    "id": "rt_01",
+    "type": "in_process_teammate",
+    "status": "running",
+    "work_graph_task_id": 12,
+}
+```
+
+这里最重要的边界是：
+
+- 一个任务可以派生多个 runtime task
+- 一个 runtime task 通常只是“如何执行”的一个实例
+
+## 5. Worktree：在哪做
+
+这是 `s18` 建立的执行车道层。
+
+它回答的是：
+
+- 这份工作在哪个独立目录里做
+- 这条目录车道对应哪个任务
+- 这条车道现在是 active、kept 还是 removed
+
+最小例子：
+
+```python
+worktree = {
+    "name": "login-page",
+    "path": ".worktrees/login-page",
+    "task_id": 12,
+    "status": "active",
+}
+```
+
+这层的关键词是：
+
+**执行边界**
+
+它不是工作目标本身，而是：
+
+> 让这份工作在独立目录里推进的执行车道。
+
+## 这五层怎么连起来
+
+你可以把后段章节连成下面这条链：
+
+```text
+teammate
+  通过 protocol request 协调
+  认领 task
+  作为一个 runtime execution slot 持续运行
+  在某条 worktree lane 里改代码
+```
+
+如果写得更具体一点，会变成：
+
+```text
+alice (teammate)
+  ->
+收到或发起一个 request_id
+  ->
+认领 task #12
+  ->
+开始作为执行单元推进工作
+  ->
+进入 worktree "login-page"
+  ->
+在 .worktrees/login-page 里运行命令和改文件
+```
+
+## 一个最典型的混淆例子
+
+很多读者会把这句话说成：
+
+> “alice 就是在做 login-page 这个 worktree 任务。”
+
+这句话把三层东西混成了一句：
+
+- `alice`：队友
+- `login-page`：worktree
+- “任务”：工作图任务
+
+更准确的说法应该是：
+
+> `alice` 认领了 `task #12`，并在 `login-page` 这条 worktree 车道里推进它。
+
+一旦你能稳定地这样表述，后面几章就不容易乱。
+
+## 初学者最容易犯的错
+
+### 1. 把 teammate 和 task 混成一个对象
+
+队友是执行者，任务是目标。
+
+### 2. 把 `request_id` 和 `task_id` 混成一个 ID
+
+一个负责协调，一个负责工作目标，不是同一层。
+
+### 3. 把 runtime slot 当成 durable task
+
+运行时执行单元会结束，但 durable task 还可能继续存在。
+
+### 4. 把 worktree 当成任务本身
+
+worktree 只是执行目录边界，不是任务目标。
+
+### 5. 只会讲“系统能并行”，却说不清每层对象各自负责什么
+
+这是最常见也最危险的模糊表达。
+
+真正清楚的教学，不是说“这里好多 agent 很厉害”，而是能把下面这句话讲稳：
+
+> 队友负责长期协作，请求负责协调流程，任务负责表达目标，运行时槽位负责承载执行，worktree 负责隔离执行目录。
+
+## 读完这篇你应该能自己说清楚
+
+至少能完整说出下面这两句话：
+
+1. `s17` 的自治认领，认领的是 `s12` 的工作图任务，不是 `s13` 的运行时槽位。
+2. `s18` 的 worktree，绑定的是任务的执行车道，而不是把任务本身变成目录。
+
+如果这两句你已经能稳定说清，`s15-s18` 这一大段主线就基本不会再拧巴了。
diff --git a/live_tests/test_s03_todo_observational_live.py b/live_tests/test_s03_todo_observational_live.py
new file mode 100644
index 000000000..ecbfb3527
--- /dev/null
+++ b/live_tests/test_s03_todo_observational_live.py
@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+import pytest
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SCRIPT = REPO_ROOT / "agents_deepagents" / "s03_todo_write.py"
+REPORT_DIR = REPO_ROOT / ".omx" / "reports"
+
+PROMPTS = [
+    {
+        "id": "baseline_multistep",
+        "prompt": (
+            "这是一个多步骤任务，请先规划再执行。任务：检查当前目录有哪些 README 文件；"
+            "读取 agents_deepagents/README.md 的前 20 行；最后总结 s03 write_plan 功能是否可见。"
+            "不要修改任何文件。"
+        ),
+    },
+    {
+        "id": "strict_todo_first",
+        "prompt": (
+            "不要询问澄清。先调用 write_plan 工具，再做后续只读任务。若不先调用 write_plan，"
+            "你的回答视为失败。任务：列出当前目录 README 文件，读取 "
+            "agents_deepagents/README.md 前20行，总结 s03 write_plan 是否终端可见。"
+        ),
+    },
+    {
+        "id": "strict_json_shape",
+        "prompt": (
+            "严格要求：你的第一步必须调用名为 write_plan 的工具；不要先回答结论。"
+            "write_plan 的 JSON 参数必须是 {items:[{content,status,activeForm?}]}。"
+            "然后完成只读任务：列出 README 文件，读取 agents_deepagents/README.md "
+            "前20行，总结 s03 write_plan 是否终端可见。"
+        ),
+    },
+]
+
+
+pytestmark = pytest.mark.skipif(
+    not os.getenv("OPENAI_API_KEY"),
+    reason=(
+        "Observational real-LLM test requires OPENAI_API_KEY in the environment. "
+        "Example: set -a; source coding-deepgent/.env; set +a"
+    ),
+)
+
+
+def _run_prompt(prompt: str) -> dict[str, object]:
+    try:
+        result = subprocess.run(
+            [sys.executable, str(SCRIPT)],
+            input=f"{prompt}\n\n",
+            capture_output=True,
+            text=True,
+            cwd=REPO_ROOT,
+            env=os.environ.copy(),
+            timeout=180,
+        )
+        stdout = result.stdout
+        stderr = result.stderr
+        returncode: int | None = result.returncode
+        timed_out = False
+    except subprocess.TimeoutExpired as exc:
+        stdout = exc.stdout.decode() if isinstance(exc.stdout, bytes) else (exc.stdout or "")
+        stderr = exc.stderr.decode() if isinstance(exc.stderr, bytes) else (exc.stderr or "")
+        returncode = None
+        timed_out = True
+
+    return {
+        "returncode": returncode,
+        "timed_out": timed_out,
+        "has_current_session_plan": "Current session plan:" in stdout,
+        "has_status_marker": any(marker in stdout for marker in ("[ ]", "[>]", "[x]")),
+        "mentions_plan_error": (
+            "调用 write_plan 工具时遇到错误" in stdout
+            or "需要先调用 write_plan 工具" in stdout
+            or "write_plan 工具" in stdout and "错误" in stdout
+        ),
+        "stdout_excerpt": stdout[-2000:],
+        "stderr_excerpt": stderr[-1000:],
+    }
+
+
+def test_s03_observational_real_llm_report() -> None:
+    """观察性真实测试：记录升级后模型在自由代理模式下会不会用 write_plan。
+
+    这是“观察性”测试，不把“必须调用 write_plan”写死成断言。
+    它的目标是：
+    1. 用真实模型跑几组 prompt；
+    2. 记录终端是否出现 `Current session plan:`；
+    3. 记录是否出现工具相关错误提示；
+    4. 输出一份 JSON 报告，便于后续比较不同模型/提示词。
+    """
+
+    observations: list[dict[str, object]] = []
+    for case in PROMPTS:
+        observation = {"id": case["id"], **_run_prompt(case["prompt"])}
+        observations.append(observation)
+
+    REPORT_DIR.mkdir(parents=True, exist_ok=True)
+    report_path = REPORT_DIR / (
+        f"s03-write-plan-observational-live-{datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%SZ')}.json"
+    )
+    report = {
+        "script": str(SCRIPT.relative_to(REPO_ROOT)),
+        "model": os.getenv("OPENAI_MODEL", ""),
+        "base_url": os.getenv("OPENAI_BASE_URL", ""),
+        "observations": observations,
+    }
+    report_path.write_text(json.dumps(report, ensure_ascii=False, indent=2))
+
+    # 这条测试只保证“真实调用过程（含超时观测）和报告落盘”完成，
+    # 不把模型行为本身固定成硬断言。
+    assert len(observations) == len(PROMPTS)
+    assert report_path.exists()
+
+    print(f"\n[observational-report] {report_path}")
+    for item in observations:
+        print(
+            f"[{item['id']}] timeout={item['timed_out']} "
+            f"plan={item['has_current_session_plan']} "
+            f"markers={item['has_status_marker']} "
+            f"plan_error={item['mentions_plan_error']}"
+        )
diff --git a/live_tests/test_s03_todo_visibility_live.py b/live_tests/test_s03_todo_visibility_live.py
new file mode 100644
index 000000000..1b45e84f0
--- /dev/null
+++ b/live_tests/test_s03_todo_visibility_live.py
@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import os
+
+import pytest
+
+
+pytestmark = pytest.mark.skipif(
+    not os.getenv("OPENAI_API_KEY"),
+    reason=(
+        "Real-LLM test requires OPENAI_API_KEY in the environment. "
+        "Example: set -a; source coding-deepgent/.env; set +a"
+    ),
+)
+
+
+PROMPT = (
+    "请创建一个三步 write_plan 计划："
+    "1) 检查当前目录有哪些 README 文件；"
+    "2) 读取 agents_deepagents/README.md 的前20行；"
+    "3) 总结 s03 write_plan 功能是否在终端可见。"
+    "要求恰好三项，第一项必须是 in_progress 并给出 activeForm。"
+)
+
+
+def test_s03_terminal_plan_is_visible_after_real_llm_generates_todo_args() -> None:
+    """真实 LLM 集成测试：验证 s03 的终端计划显示链路是通的。
+
+    这里不用自由代理循环，而是：
+    1. 用真实 OpenAI 模型绑定真实 `write_plan_tool` schema；
+    2. 强制 `tool_choice='required'`，确保模型必须产出 write_plan 参数；
+    3. 用这些真实参数调用 `s03.write_plan(...)`；
+    4. 把返回的 items 写入 SESSION_STATE，再检查 `current_plan_text()`。
+
+    这样测试的是真实 LLM + 真实 tool schema + 真实终端渲染路径，
+    同时避免“模型这次恰好没调用工具”导致测试不稳定。
+    """
+
+    from agents_deepagents import s03_todo_write as s03
+
+    model = s03.build_openai_model().bind_tools(
+        [s03.write_plan_tool],
+        tool_choice="required",
+    )
+    response = model.invoke(PROMPT)
+
+    assert response.tool_calls, "real model did not emit any tool call"
+    write_plan_call = response.tool_calls[0]
+    assert write_plan_call["name"] == "write_plan"
+
+    command = s03._write_plan_command(
+        write_plan_call["args"]["items"],
+        tool_call_id=write_plan_call["id"],
+    )
+
+    previous_state = dict(s03.SESSION_STATE)
+    try:
+        s03.SESSION_STATE["items"] = command.update["items"]
+        s03.SESSION_STATE["rounds_since_update"] = 0
+        terminal_text = s03.current_plan_text()
+    finally:
+        s03.SESSION_STATE.clear()
+        s03.SESSION_STATE.update(previous_state)
+
+    assert terminal_text is not None
+    assert "检查当前目录有哪些 README 文件" in terminal_text
+    assert "读取 agents_deepagents/README.md 的前20行" in terminal_text
+    assert "总结 s03 write_plan 功能是否在终端可见" in terminal_text
+    assert any(marker in terminal_text for marker in ("[ ]", "[>]", "[x]"))
diff --git a/requirements.txt b/requirements.txt
index c27dfcc04..8e3aa9b13 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,3 +1,6 @@
 anthropic>=0.25.0
+deepagents>=0.5.0a2
+langchain>=1.0.0
+langchain-openai>=1.0.0
 python-dotenv>=1.0.0
-pyyaml>=6.0
\ No newline at end of file
+pyyaml>=6.0
diff --git a/tests/conftest.py b/tests/conftest.py
new file mode 100644
index 000000000..441174a4a
--- /dev/null
+++ b/tests/conftest.py
@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import os
+import socket
+from typing import Any
+
+
+PROVIDER_ENV_VARS = (
+    "ANTHROPIC_AUTH_TOKEN",
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_BASE_URL",
+    "OPENAI_API_KEY",
+    "OPENAI_BASE_URL",
+)
+NETWORK_BLOCK_MESSAGE = (
+    "Network access is disabled during automated tests. "
+    "Stub the provider client instead of making live calls."
+)
+ORIGINAL_SOCKET_FUNCS: dict[str, Any] = {}
+
+
+def _block_network(*args: Any, **kwargs: Any) -> None:
+    raise AssertionError(NETWORK_BLOCK_MESSAGE)
+
+
+def _block_socket_connect(self: socket.socket, *args: Any, **kwargs: Any) -> None:
+    raise AssertionError(NETWORK_BLOCK_MESSAGE)
+
+
+def pytest_configure(config: Any) -> None:
+    del config  # pytest hook signature; unused
+
+    for env_name in PROVIDER_ENV_VARS:
+        os.environ.pop(env_name, None)
+
+    ORIGINAL_SOCKET_FUNCS["create_connection"] = socket.create_connection
+    ORIGINAL_SOCKET_FUNCS["getaddrinfo"] = socket.getaddrinfo
+    ORIGINAL_SOCKET_FUNCS["connect"] = socket.socket.connect
+    ORIGINAL_SOCKET_FUNCS["connect_ex"] = socket.socket.connect_ex
+
+    socket.create_connection = _block_network
+    socket.getaddrinfo = _block_network
+    socket.socket.connect = _block_socket_connect
+    socket.socket.connect_ex = _block_socket_connect
+
+
+def pytest_unconfigure(config: Any) -> None:
+    del config  # pytest hook signature; unused
+
+    create_connection = ORIGINAL_SOCKET_FUNCS.get("create_connection")
+    getaddrinfo = ORIGINAL_SOCKET_FUNCS.get("getaddrinfo")
+    connect = ORIGINAL_SOCKET_FUNCS.get("connect")
+    connect_ex = ORIGINAL_SOCKET_FUNCS.get("connect_ex")
+
+    if create_connection is not None:
+        socket.create_connection = create_connection
+    if getaddrinfo is not None:
+        socket.getaddrinfo = getaddrinfo
+    if connect is not None:
+        socket.socket.connect = connect
+    if connect_ex is not None:
+        socket.socket.connect_ex = connect_ex
diff --git a/tests/test_agents_baseline_contract.py b/tests/test_agents_baseline_contract.py
new file mode 100644
index 000000000..fbcdf0808
--- /dev/null
+++ b/tests/test_agents_baseline_contract.py
@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+# This snapshot makes the handwritten `agents/*.py` teaching baseline explicit.
+# If a future change intentionally revises the baseline, update the hashes in the
+# same commit so the diff clearly shows that the teaching reference moved.
+EXPECTED_BASELINE_SHA256 = {
+    "agents/__init__.py": "3858b50108eb569a9347b6d63eba5b70a9e839875989c55d4f2bcd2bde7a46cd",
+    "agents/s01_agent_loop.py": "f767394084f609c80d54ef500b8cbd558b8f2a86df301b275726a028bc47b9a3",
+    "agents/s02_tool_use.py": "6a683a9d3f6176226173e335bd39c906f4fa16fffdda564f7350e6aa43fb807b",
+    "agents/s03_todo_write.py": "d574586bee2122cf61fce8ae7ca0af552c1dd63b5900e90a01a1558f2dde6a4c",
+    "agents/s04_subagent.py": "4f005f32d87b14b25c5605b7e87caca3f07c4f63d80381ddbe8f7491e7749020",
+    "agents/s05_skill_loading.py": "ee4c3849db5379fb7f5d12f05d853b960797adfbde0bd4e089ef2754ac2e95e2",
+    "agents/s06_context_compact.py": "2fde97749962daf9d34e8cacc4469e4d916b10243247ba9c2ffe9e07e2e8430c",
+    "agents/s07_permission_system.py": "da5995910fda061cf9471f2dd1dc9322840e5e16a38f545c6a84b7e5896c0e22",
+    "agents/s08_hook_system.py": "6ff869c7d5d003f01b02ba84687e3a6053a6c314923dad1d8c4f48de78bc9ccd",
+    "agents/s09_memory_system.py": "7b6186774149879dd727347c0ecaf4010e62f765e089b43774f84966abdf1c16",
+    "agents/s10_system_prompt.py": "b02560b9bbaea8907d1316ac104bd8e7dcfb7abccbbc38fb623c0f192388e15d",
+    "agents/s11_error_recovery.py": "05729b2b75a24cb79e1bb8f7c121ed6e8c96da6f1432545dac091f780c30254a",
+    "agents/s12_task_system.py": "b002c0e771b0402ba10150ccf02d7b93e8c0e7a6414823e6e7c2ae855e5400e7",
+    "agents/s13_background_tasks.py": "3ca96351975f8755dd4ec47245f7cf51d779c1a9fb043573115ad53743a1ccbc",
+    "agents/s14_cron_scheduler.py": "165f9f9b010fa31b897f20f0c9f0b37ba42674cb29bd25e4ec3d9c561e9d9d5a",
+    "agents/s15_agent_teams.py": "15799489adb7edc68a810351cc281bf5ac4641f46c0e8a491bcad9a4a544caf4",
+    "agents/s16_team_protocols.py": "e4830a68fd733f4dd709edf27303712dfd7517da13b26d773ec21cfe4b77cfa9",
+    "agents/s17_autonomous_agents.py": "f847b6dbebf3a90a7ec8ff57b3a8db50f7d199331e635ed3a998b9fd0cf212d2",
+    "agents/s18_worktree_task_isolation.py": "310a5f0dc334c960aa6210979d86178f7ea2e0f050b5010584299a240f25e758",
+    "agents/s19_mcp_plugin.py": "eb7f7e7019de840f82767a673b4630430c0f41355e0e798a4270908b191af0e2",
+    "agents/s_full.py": "854efdcdc4372da4d0dc4eed3baa0cf2348d21ae97489506d8c11cd27894a9b2",
+}
+
+
+def sha256_for(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def test_agents_baseline_files_still_exist() -> None:
+    actual_files = {
+        path.relative_to(ROOT).as_posix()
+        for path in sorted((ROOT / "agents").glob("*.py"))
+    }
+    assert actual_files == set(EXPECTED_BASELINE_SHA256)
+
+
+def test_agents_baseline_hashes_have_not_changed() -> None:
+    mismatches: list[str] = []
+    for relative_path, expected_hash in EXPECTED_BASELINE_SHA256.items():
+        actual_hash = sha256_for(ROOT / relative_path)
+        if actual_hash != expected_hash:
+            mismatches.append(
+                f"{relative_path}: expected {expected_hash}, got {actual_hash}"
+            )
+
+    assert not mismatches, "Handwritten agents baseline changed:\n" + "\n".join(mismatches)
diff --git a/tests/test_deepagents_control_plane.py b/tests/test_deepagents_control_plane.py
new file mode 100644
index 000000000..28700ba2f
--- /dev/null
+++ b/tests/test_deepagents_control_plane.py
@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from agents_deepagents import s07_permission_system as s07
+from agents_deepagents import s08_hook_system as s08
+from agents_deepagents import s09_memory_system as s09
+from agents_deepagents import s10_system_prompt as s10
+from agents_deepagents import s11_error_recovery as s11
+
+
+def test_permission_manager_plan_mode_blocks_writes() -> None:
+    manager = s07.PermissionManager(mode="plan")
+    assert manager.check("read_file", {"path": "README.md"})["behavior"] == "allow"
+    assert manager.check("write_file", {"path": "demo.txt", "content": "x"})["behavior"] == "deny"
+
+
+def test_bash_validator_flags_dangerous_patterns() -> None:
+    failures = s07.bash_validator.validate("sudo rm -rf /tmp/demo")
+    assert {name for name, _ in failures} >= {"sudo", "rm_rf"}
+
+
+def test_hook_manager_supports_injected_messages(tmp_path: Path) -> None:
+    config = tmp_path / ".hooks.json"
+    payload = {
+        "hooks": {
+            "SessionStart": [
+                {"command": "python -c \"import sys; sys.stderr.write('session-start'); sys.exit(2)\""}
+            ]
+        }
+    }
+    config.write_text(json.dumps(payload), encoding="utf-8")
+    manager = s08.HookManager(config_path=config, sdk_mode=True)
+    result = manager.run_hooks("SessionStart")
+    assert result["messages"] == ["session-start"]
+    assert result["blocked"] is False
+
+
+def test_memory_manager_saves_and_loads_prompt(tmp_path: Path) -> None:
+    manager = s09.MemoryManager(tmp_path)
+    msg = manager.save_memory("db_schema", "Database schema", "project", "tables: users")
+    assert "Saved memory" in msg
+    prompt = manager.load_memory_prompt()
+    assert "db_schema" in prompt
+    assert "tables: users" in prompt
+
+
+def test_system_prompt_builder_assembles_static_and_dynamic_sections(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    builder = s10.SystemPromptBuilder(workdir=tmp_path, tools=[s10.bash])
+    built = builder.build()
+    assert s10.DYNAMIC_BOUNDARY in built
+    assert "# Available tools" in built
+    assert "# Dynamic context" in built
+
+
+def test_backoff_delay_grows_with_attempt(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(s11.random, "uniform", lambda a, b: 0.0)
+    assert s11.backoff_delay(0) == pytest.approx(1.0)
+    assert s11.backoff_delay(1) == pytest.approx(2.0)
+    assert s11.backoff_delay(2) == pytest.approx(4.0)
diff --git a/tests/test_deepagents_gating_spike.py b/tests/test_deepagents_gating_spike.py
new file mode 100644
index 000000000..dec00c465
--- /dev/null
+++ b/tests/test_deepagents_gating_spike.py
@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+from langchain_core.language_models.fake_chat_models import (
+    FakeMessagesListChatModel,
+)
+from langchain_core.messages import AIMessage, ToolMessage
+from langchain_core.tools import BaseTool
+
+from agents_deepagents._deepagents_gating import build_stage_agent
+
+
+class SpyFakeModel(FakeMessagesListChatModel):
+    bound_tool_names: list[str] = []
+
+    def bind_tools(
+        self,
+        tools: Sequence[dict[str, Any] | type | Any | BaseTool],
+        *,
+        tool_choice: str | None = None,
+        **kwargs: Any,
+    ):
+        self.bound_tool_names = [_tool_name(tool) for tool in tools]
+        return self
+
+
+def _tool_name(tool: dict[str, Any] | type | Any | BaseTool) -> str:
+    if isinstance(tool, dict):
+        return (
+            tool.get("name")
+            or tool.get("function", {}).get("name")
+            or type(tool).__name__
+        )
+    return getattr(tool, "name", type(tool).__name__)
+
+
+def _error_messages(result: dict[str, Any]) -> list[ToolMessage]:
+    return [
+        message
+        for message in result["messages"]
+        if isinstance(message, ToolMessage)
+        and getattr(message, "status", None) == "error"
+    ]
+
+
+def test_s01_tools_exclude_planning_and_subagents() -> None:
+    model = SpyFakeModel(responses=[AIMessage(content="done")])
+
+    build_stage_agent("s01", model=model).invoke(
+        {"messages": [{"role": "user", "content": "inspect the workspace"}]}
+    )
+
+    assert "write_todos" not in model.bound_tool_names
+    assert "task" not in model.bound_tool_names
+    expected_tools = {
+        "ls",
+        "read_file",
+        "write_file",
+        "edit_file",
+        "glob",
+        "grep",
+    }
+    assert expected_tools.issubset(set(model.bound_tool_names))
+
+
+def test_s01_rejects_write_todos_at_runtime() -> None:
+    model = SpyFakeModel(
+        responses=[
+            AIMessage(
+                content="",
+                tool_calls=[
+                    {
+                        "name": "write_todos",
+                        "args": {
+                            "todos": [
+                                {
+                                    "content": "Plan",
+                                    "status": "in_progress",
+                                }
+                            ]
+                        },
+                        "id": "call_1",
+                        "type": "tool_call",
+                    }
+                ],
+            ),
+            AIMessage(content="done"),
+        ]
+    )
+
+    result = build_stage_agent("s01", model=model).invoke(
+        {"messages": [{"role": "user", "content": "plan this work"}]}
+    )
+
+    errors = _error_messages(result)
+    assert len(errors) == 1
+    assert errors[0].name == "write_todos"
+    assert "not a valid tool" in str(errors[0].content)
+
+
+def test_s03_enables_write_todos_but_still_blocks_task() -> None:
+    planning_model = SpyFakeModel(
+        responses=[
+            AIMessage(
+                content="",
+                tool_calls=[
+                    {
+                        "name": "write_todos",
+                        "args": {
+                            "todos": [
+                                {
+                                    "content": "Plan",
+                                    "status": "in_progress",
+                                }
+                            ]
+                        },
+                        "id": "call_1",
+                        "type": "tool_call",
+                    }
+                ],
+            ),
+            AIMessage(content="done"),
+        ]
+    )
+
+    planning_result = build_stage_agent("s03", model=planning_model).invoke(
+        {"messages": [{"role": "user", "content": "plan this work"}]}
+    )
+
+    assert "write_todos" in planning_model.bound_tool_names
+    assert "task" not in planning_model.bound_tool_names
+    assert planning_result["todos"] == [
+        {"content": "Plan", "status": "in_progress"}
+    ]
+
+    task_model = SpyFakeModel(
+        responses=[
+            AIMessage(
+                content="",
+                tool_calls=[
+                    {
+                        "name": "task",
+                        "args": {
+                            "description": "delegate",
+                            "prompt": "inspect",
+                        },
+                        "id": "call_2",
+                        "type": "tool_call",
+                    }
+                ],
+            ),
+            AIMessage(content="done"),
+        ]
+    )
+
+    task_result = build_stage_agent("s03", model=task_model).invoke(
+        {"messages": [{"role": "user", "content": "delegate this"}]}
+    )
+
+    errors = _error_messages(task_result)
+    assert len(errors) == 1
+    assert errors[0].name == "task"
+    assert "not a valid tool" in str(errors[0].content)
diff --git a/tests/test_deepagents_track_smoke.py b/tests/test_deepagents_track_smoke.py
new file mode 100644
index 000000000..c538c00b6
--- /dev/null
+++ b/tests/test_deepagents_track_smoke.py
@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import importlib
+from pathlib import Path
+import py_compile
+
+import pytest
+
+
+ROOT = Path(__file__).resolve().parents[1]
+TRACK_DIR = ROOT / "agents_deepagents"
+TRACK_FILES = sorted(
+    path for path in TRACK_DIR.glob("*.py") if path.name != "__init__.py"
+)
+TRACK_IDS = [path.name for path in TRACK_FILES]
+
+
+@pytest.mark.parametrize("agent_path", TRACK_FILES, ids=TRACK_IDS)
+def test_deepagents_track_scripts_compile(agent_path: Path) -> None:
+    _ = py_compile.compile(str(agent_path), doraise=True)
+
+
+def test_deepagents_track_scripts_exist() -> None:
+    assert TRACK_FILES, "expected Deep Agents teaching scripts"
+    for filename in [
+        "s01_agent_loop.py",
+        "s02_tool_use.py",
+        "s03_todo_write.py",
+        "s04_subagent.py",
+        "s05_skill_loading.py",
+        "s06_context_compact.py",
+    ]:
+        assert TRACK_DIR.joinpath(filename).exists()
+
+
+def test_pure_helpers_import_without_openai_key(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+
+    common = importlib.import_module("agents_deepagents.common")
+    s03 = importlib.import_module("agents_deepagents.s03_todo_write")
+    s06 = importlib.import_module("agents_deepagents.s06_context_compact")
+
+    assert common.deepagents_model_name()
+    assert s06.PIPELINE_STAGE_ORDER[0] == "apply_tool_result_budget"
+    assert "reactive_compact_on_overflow" in s06.PIPELINE_STAGE_ORDER
+    with pytest.raises(RuntimeError, match="OPENAI_API_KEY"):
+        common.build_openai_model()
+
+    normalized = s03.normalize_plan_items([
+        {"content": "Inspect task", "status": "completed"},
+        {
+            "content": "Implement",
+            "status": "in_progress",
+            "activeForm": "Implementing",
+        },
+    ])
+    rendered = s03.render_plan_items(normalized)
+    assert "[x] Inspect task" in rendered
+    assert "[>] Implement (Implementing)" in rendered
+
+
+def test_safe_path_rejects_workspace_escape() -> None:
+    common = importlib.import_module("agents_deepagents.common")
+
+    with pytest.raises(ValueError, match="escapes workspace"):
+        common.safe_path("../outside.txt")
+
+
+def test_s05_read_file_supports_virtual_skill_paths() -> None:
+    s05 = importlib.import_module("agents_deepagents.s05_skill_loading")
+
+    text = s05.read_file.invoke({"path": "/skills/code-review/SKILL.md"})
+
+    assert "name: code-review" in text
+    assert "description:" in text
+    assert "# Code Review Skill" in text
+    assert "## Review Checklist" in text
diff --git a/tests/test_provider_safety.py b/tests/test_provider_safety.py
new file mode 100644
index 000000000..6fa991065
--- /dev/null
+++ b/tests/test_provider_safety.py
@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import importlib
+import socket
+import sys
+import types
+
+import pytest
+
+import conftest
+
+
+class FakeChatOpenAI:
+    def __init__(self, **kwargs):
+        self.kwargs = kwargs
+
+
+@pytest.fixture
+def fake_langchain_openai(
+    monkeypatch: pytest.MonkeyPatch,
+) -> type[FakeChatOpenAI]:
+    module = types.ModuleType("langchain_openai")
+    module.ChatOpenAI = FakeChatOpenAI
+    monkeypatch.setitem(sys.modules, "langchain_openai", module)
+    return FakeChatOpenAI
+
+
+def test_network_access_is_blocked_in_tests() -> None:
+    with pytest.raises(AssertionError, match="Network access is disabled"):
+        socket.create_connection(("example.com", 443))
+
+
+def test_provider_credential_guard_covers_live_auth_env_vars() -> None:
+    assert {
+        "ANTHROPIC_AUTH_TOKEN",
+        "ANTHROPIC_API_KEY",
+        "OPENAI_API_KEY",
+    }.issubset(conftest.PROVIDER_ENV_VARS)
+
+
+def test_common_build_openai_model_uses_stubbed_client(
+    monkeypatch: pytest.MonkeyPatch,
+    fake_langchain_openai: type[FakeChatOpenAI],
+) -> None:
+    del fake_langchain_openai
+
+    common = importlib.import_module("agents_deepagents.common")
+
+    monkeypatch.setenv("OPENAI_API_KEY", "test-key")
+    monkeypatch.setenv("OPENAI_MODEL", "gpt-test-mini")
+    monkeypatch.setenv("OPENAI_BASE_URL", "https://example.invalid/v1")
+    monkeypatch.delenv("MODEL_ID", raising=False)
+
+    model = common.build_openai_model(temperature=0.25, timeout=9)
+
+    assert isinstance(model, FakeChatOpenAI)
+    assert model.kwargs == {
+        "model": "gpt-test-mini",
+        "temperature": 0.25,
+        "timeout": 9,
+        "base_url": "https://example.invalid/v1",
+    }
+
+
+def test_private_common_build_openai_chat_model_uses_stubbed_client(
+    monkeypatch: pytest.MonkeyPatch,
+    fake_langchain_openai: type[FakeChatOpenAI],
+) -> None:
+    del fake_langchain_openai
+
+    common = importlib.import_module("agents_deepagents._common")
+
+    monkeypatch.setenv("OPENAI_API_KEY", "test-key")
+    monkeypatch.setenv("OPENAI_MODEL", "gpt-test-nano")
+    monkeypatch.setenv("OPENAI_BASE_URL", "https://example.invalid/v1")
+    monkeypatch.delenv("MODEL_ID", raising=False)
+
+    model = common.build_openai_chat_model(temperature=0.1, timeout=7)
+
+    assert isinstance(model, FakeChatOpenAI)
+    assert model.kwargs == {
+        "model": "gpt-test-nano",
+        "temperature": 0.1,
+        "timeout": 7,
+        "base_url": "https://example.invalid/v1",
+    }
+
+
+def test_deepagents_model_resolution_does_not_reuse_anthropic_model_id(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    common = importlib.import_module("agents_deepagents.common")
+    private_common = importlib.import_module("agents_deepagents._common")
+
+    monkeypatch.delenv("OPENAI_MODEL", raising=False)
+    monkeypatch.setenv("MODEL_ID", "claude-sonnet-4-6")
+
+    assert common.deepagents_model_name() == common.DEFAULT_OPENAI_MODEL
+    assert (
+        private_common.resolve_openai_model()
+        == private_common.DEFAULT_OPENAI_MODEL
+    )
+
+    monkeypatch.setenv("MODEL_ID", "glm-5")
+
+    assert common.deepagents_model_name() == "glm-5"
+    assert private_common.resolve_openai_model() == "glm-5"
diff --git a/tests/test_s02_runtime_baseline.py b/tests/test_s02_runtime_baseline.py
new file mode 100644
index 000000000..9ac38c710
--- /dev/null
+++ b/tests/test_s02_runtime_baseline.py
@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import importlib
+
+
+def test_s02_normalize_messages_merges_consecutive_roles() -> None:
+    s02 = importlib.import_module('agents_deepagents.s02_tool_use')
+
+    messages = [
+        {'role': 'user', 'content': 'first'},
+        {'role': 'user', 'content': 'second'},
+        {'role': 'assistant', 'content': 'third'},
+        {'role': 'assistant', 'content': 'fourth'},
+    ]
+
+    assert s02.normalize_messages(messages) == [
+        {'role': 'user', 'content': 'first\n\nsecond'},
+        {'role': 'assistant', 'content': 'third\n\nfourth'},
+    ]
+
+
+def test_s02_agent_loop_appends_one_final_answer(monkeypatch) -> None:
+    s02 = importlib.import_module('agents_deepagents.s02_tool_use')
+
+    class FakeAgent:
+        def __init__(self) -> None:
+            self.calls: list[list[dict[str, str]]] = []
+
+        def invoke(self, payload):
+            self.calls.append(payload['messages'])
+            return {'messages': [*payload['messages'], {'role': 'assistant', 'content': 'done'}]}
+
+    fake = FakeAgent()
+    monkeypatch.setattr(s02, 'build_agent', lambda: fake)
+
+    history = [
+        {'role': 'user', 'content': 'hello'},
+        {'role': 'user', 'content': 'again'},
+    ]
+
+    assert s02.agent_loop(history) == 'done'
+    assert history == [
+        {'role': 'user', 'content': 'hello'},
+        {'role': 'user', 'content': 'again'},
+        {'role': 'assistant', 'content': 'done'},
+    ]
+    assert fake.calls == [[{'role': 'user', 'content': 'hello\n\nagain'}]]
+
+
+def test_s02_build_agent_uses_middleware_without_custom_state(monkeypatch) -> None:
+    s02 = importlib.import_module('agents_deepagents.s02_tool_use')
+    captured: dict[str, object] = {}
+
+    def fake_create_agent(*, model, tools, system_prompt, middleware):
+        captured['model'] = model
+        captured['tools'] = tools
+        captured['system_prompt'] = system_prompt
+        captured['middleware'] = middleware
+        return object()
+
+    monkeypatch.setattr(s02, 'build_openai_model', lambda: object())
+    monkeypatch.setattr(s02, 'create_agent', fake_create_agent)
+
+    agent = s02.build_agent()
+
+    assert agent is not None
+    middleware = captured['middleware']
+    assert len(middleware) == 1
+    assert middleware[0].__class__.__name__ == 'ToolUseMiddleware'
+    assert not hasattr(s02, 'ToolUseState')
+    assert captured['tools'] == s02.TOOLS
diff --git a/tests/test_s03_stateful_planning_baseline.py b/tests/test_s03_stateful_planning_baseline.py
new file mode 100644
index 000000000..692125c42
--- /dev/null
+++ b/tests/test_s03_stateful_planning_baseline.py
@@ -0,0 +1,283 @@
+from __future__ import annotations
+
+import importlib
+
+from langchain_core.messages import AIMessage
+from langchain_core.language_models.fake_chat_models import FakeMessagesListChatModel
+from langchain.messages import ToolMessage
+from pydantic import ValidationError
+import pytest
+from langgraph.types import Command
+
+
+def test_s03_write_plan_updates_custom_state_via_command() -> None:
+    s03 = importlib.import_module('agents_deepagents.s03_todo_write')
+
+    command = s03._write_plan_command(
+        [
+            {'content': 'Inspect repo', 'status': 'completed'},
+            {'content': 'Implement change', 'status': 'in_progress', 'activeForm': 'Implementing'},
+        ],
+        tool_call_id='call-1',
+    )
+
+    assert isinstance(command, Command)
+    assert command.update['items'] == [
+        {'content': 'Inspect repo', 'status': 'completed'},
+        {'content': 'Implement change', 'status': 'in_progress', 'activeForm': 'Implementing'},
+    ]
+    assert command.update['rounds_since_update'] == 0
+    assert isinstance(command.update['messages'][0], ToolMessage)
+
+
+def test_s03_write_plan_schema_requires_structured_items() -> None:
+    s03 = importlib.import_module('agents_deepagents.s03_todo_write')
+
+    schema = s03.write_plan_tool.tool_call_schema.model_json_schema()
+    item_schema = schema['$defs']['PlanItemInput']
+
+    assert schema['required'] == ['items']
+    assert item_schema['required'] == ['content', 'status']
+    assert item_schema['additionalProperties'] is False
+    assert item_schema['properties']['status']['enum'] == [
+        'pending',
+        'in_progress',
+        'completed',
+    ]
+    assert 'tool_call_id' not in schema['properties']
+
+
+def test_s03_write_plan_prompts_include_complexity_guidance() -> None:
+    s03 = importlib.import_module('agents_deepagents.s03_todo_write')
+
+    assert 'complex multi-step work' in s03.SYSTEM
+    assert 'Skip the write_plan tool for simple' in s03.SYSTEM
+    assert 'Never call write_plan multiple times in parallel' in s03.SYSTEM
+    assert 'skip it for simple one-step or purely conversational requests' in (
+        s03.write_plan_tool.description
+    )
+
+
+def test_s03_write_plan_rejects_mismatched_json_without_fallback() -> None:
+    s03 = importlib.import_module('agents_deepagents.s03_todo_write')
+
+    with pytest.raises(ValidationError):
+        s03._write_plan_command([{}], tool_call_id='call-1')
+
+    with pytest.raises(ValidationError):
+        s03._write_plan_command(
+            [{'task': 'Inspect README files', 'status': 'done'}],
+            tool_call_id='call-1',
+        )
+
+    with pytest.raises(ValueError, match='tool_call_id is required'):
+        s03._write_plan_command(
+            [{'content': 'Inspect README files', 'status': 'pending'}],
+        )
+
+
+class RecordingFakeModel(FakeMessagesListChatModel):
+    bound_tool_names: list[str] = []
+
+    def bind_tools(self, tools, *, tool_choice=None, **kwargs):
+        del tool_choice, kwargs
+        self.bound_tool_names = [getattr(tool, 'name', type(tool).__name__) for tool in tools]
+        return self
+
+
+def test_s03_after_model_rejects_parallel_write_plan_calls() -> None:
+    s03 = importlib.import_module('agents_deepagents.s03_todo_write')
+    middleware = s03.PlanContextMiddleware()
+
+    state = {
+        'messages': [
+            AIMessage(
+                content='',
+                tool_calls=[
+                    {
+                        'name': 'write_plan',
+                        'args': {
+                            'items': [{'content': 'Inspect repo', 'status': 'in_progress'}]
+                        },
+                        'id': 'call_1',
+                        'type': 'tool_call',
+                    },
+                    {
+                        'name': 'write_plan',
+                        'args': {
+                            'items': [{'content': 'Summarize findings', 'status': 'pending'}]
+                        },
+                        'id': 'call_2',
+                        'type': 'tool_call',
+                    },
+                ],
+            )
+        ]
+    }
+
+    update = middleware.after_model(state, runtime=None)
+
+    assert update is not None
+    assert len(update['messages']) == 2
+    assert all(isinstance(message, ToolMessage) for message in update['messages'])
+    assert all(getattr(message, 'status', None) == 'error' for message in update['messages'])
+    assert 'should never be called multiple times in parallel' in update['messages'][0].content
+
+
+def test_s03_middleware_tracks_stale_rounds() -> None:
+    s03 = importlib.import_module('agents_deepagents.s03_todo_write')
+    middleware = s03.PlanContextMiddleware()
+
+    middleware._updated_this_turn = False
+    assert middleware.after_agent(
+        {
+            'messages': [],
+            'items': [{'content': 'Keep going', 'status': 'pending'}],
+            'rounds_since_update': 2,
+        },
+        runtime=None,
+    ) == {'rounds_since_update': 3}
+
+    middleware._updated_this_turn = True
+    assert middleware.after_agent(
+        {
+            'messages': [],
+            'items': [{'content': 'Keep going', 'status': 'pending'}],
+            'rounds_since_update': 0,
+        },
+        runtime=None,
+    ) is None
+
+
+def test_s03_agent_loop_roundtrips_runtime_state(monkeypatch) -> None:
+    s03 = importlib.import_module('agents_deepagents.s03_todo_write')
+
+    class FakeAgent:
+        def __init__(self) -> None:
+            self.payloads = []
+
+        def invoke(self, payload):
+            self.payloads.append(payload)
+            return {
+                'messages': [*payload['messages'], {'role': 'assistant', 'content': 'planned'}],
+                'items': [{'content': 'Ship it', 'status': 'in_progress', 'activeForm': 'Shipping'}],
+                'rounds_since_update': 0,
+            }
+
+    fake = FakeAgent()
+    monkeypatch.setattr(s03, 'build_agent', lambda: fake)
+    monkeypatch.setattr(
+        s03,
+        'SESSION_STATE',
+        {
+            'items': [{'content': 'Inspect', 'status': 'completed'}],
+            'rounds_since_update': 2,
+        },
+    )
+
+    history = [{'role': 'user', 'content': 'continue'}]
+    assert s03.agent_loop(history) == 'planned'
+    assert fake.payloads[0]['rounds_since_update'] == 2
+    assert fake.payloads[0]['items'] == [
+        {'content': 'Inspect', 'status': 'completed'}
+    ]
+    assert history[-1] == {'role': 'assistant', 'content': 'planned'}
+    assert s03.SESSION_STATE['items'] == [
+        {'content': 'Ship it', 'status': 'in_progress', 'activeForm': 'Shipping'}
+    ]
+
+
+def test_s03_free_agent_path_executes_todo_without_runtime_injection_error(monkeypatch) -> None:
+    s03 = importlib.import_module('agents_deepagents.s03_todo_write')
+
+    model = RecordingFakeModel(
+        responses=[
+            AIMessage(
+                content='',
+                tool_calls=[
+                    {
+                        'name': 'write_plan',
+                        'args': {
+                            'items': [
+                                {
+                                    'content': 'Inspect repo',
+                                    'status': 'in_progress',
+                                    'activeForm': 'Inspecting',
+                                },
+                                {'content': 'Summarize findings', 'status': 'pending'},
+                            ]
+                        },
+                        'id': 'call_1',
+                        'type': 'tool_call',
+                    }
+                ],
+            ),
+            AIMessage(content='planned'),
+        ]
+    )
+
+    monkeypatch.setattr(s03, 'build_openai_model', lambda: model)
+    monkeypatch.setattr(
+        s03,
+        'SESSION_STATE',
+        {
+            'items': [],
+            'rounds_since_update': 0,
+        },
+    )
+
+    history = [{'role': 'user', 'content': 'plan this work'}]
+    assert s03.agent_loop(history) == 'planned'
+    assert 'write_plan' in model.bound_tool_names
+    assert s03.SESSION_STATE['items'] == [
+        {'content': 'Inspect repo', 'status': 'in_progress', 'activeForm': 'Inspecting'},
+        {'content': 'Summarize findings', 'status': 'pending'},
+    ]
+    assert s03.current_plan_text() == (
+        '[>] Inspect repo (Inspecting)\n'
+        '[ ] Summarize findings\n'
+        '\n'
+        '(0/2 completed)'
+    )
+
+
+def test_s03_current_plan_text_renders_session_state(monkeypatch) -> None:
+    s03 = importlib.import_module('agents_deepagents.s03_todo_write')
+    monkeypatch.setattr(
+        s03,
+        'SESSION_STATE',
+        {
+            'items': [{'content': 'Ship it', 'status': 'in_progress'}],
+            'rounds_since_update': 0,
+        },
+    )
+
+    assert s03.current_plan_text() == '[>] Ship it\n\n(0/1 completed)'
+
+
+def test_s03_terminal_plan_renderer_golden_output() -> None:
+    s03 = importlib.import_module('agents_deepagents.s03_todo_write')
+
+    items = [
+        {'content': 'Inspect repo', 'status': 'completed'},
+        {
+            'content': 'Implement renderer seam',
+            'status': 'in_progress',
+            'activeForm': 'Implementing',
+        },
+        {'content': 'Verify behavior', 'status': 'pending'},
+    ]
+
+    assert s03.render_plan_items(items) == (
+        '[x] Inspect repo\n'
+        '[>] Implement renderer seam (Implementing)\n'
+        '[ ] Verify behavior\n'
+        '\n'
+        '(1/3 completed)'
+    )
+    assert s03.render_plan_items([]) == 'No session plan yet.'
+    assert s03.reminder_text([], 99) is None
+    assert s03.reminder_text(items, 2) is None
+    assert s03.reminder_text(items, 3) == (
+        '<reminder>Refresh your current plan before continuing.</reminder>'
+    )
diff --git a/tests/test_s04_s05_langchain_native_baseline.py b/tests/test_s04_s05_langchain_native_baseline.py
new file mode 100644
index 000000000..7121d1888
--- /dev/null
+++ b/tests/test_s04_s05_langchain_native_baseline.py
@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Sequence
+
+from deepagents.backends.filesystem import FilesystemBackend
+from langchain_core.language_models.fake_chat_models import FakeMessagesListChatModel
+from langchain_core.messages import AIMessage, SystemMessage, ToolMessage
+from langchain_core.tools import BaseTool
+
+from agents_deepagents import s04_subagent as s04
+from agents_deepagents import s05_skill_loading as s05
+
+
+def _tool_name(tool: dict[str, Any] | type | Any | BaseTool) -> str:
+    if isinstance(tool, dict):
+        return (
+            tool.get("name")
+            or tool.get("function", {}).get("name")
+            or type(tool).__name__
+        )
+    return getattr(tool, "name", getattr(tool, "__name__", type(tool).__name__))
+
+
+class RecordingFakeModel(FakeMessagesListChatModel):
+    bound_tool_names: list[str] = []
+    seen_messages: list[list[Any]] = []
+
+    def bind_tools(
+        self,
+        tools: Sequence[dict[str, Any] | type | Any | BaseTool],
+        *,
+        tool_choice: str | None = None,
+        **kwargs: Any,
+    ):
+        self.bound_tool_names = [_tool_name(tool) for tool in tools]
+        return self
+
+    def _generate(
+        self,
+        messages: list[Any],
+        stop: list[str] | None = None,
+        run_manager: Any | None = None,
+        **kwargs: Any,
+    ):
+        self.seen_messages.append(list(messages))
+        return super()._generate(
+            messages,
+            stop=stop,
+            run_manager=run_manager,
+            **kwargs,
+        )
+
+
+def _system_text(message: SystemMessage) -> str:
+    content = message.content
+    if isinstance(content, str):
+        return content
+    texts: list[str] = []
+    for block in content:
+        if isinstance(block, dict) and block.get("type") == "text":
+            texts.append(str(block.get("text", "")))
+    return "\n".join(texts)
+
+
+def test_s04_uses_native_task_tool_with_fresh_child_context() -> None:
+    delegated_task_args = {
+        "description": "Inspect README.md and return one short summary.",
+        "subagent_type": s04.SUBAGENT_TYPE,
+    }
+
+    main_model = RecordingFakeModel(
+        responses=[
+            AIMessage(
+                content="",
+                tool_calls=[
+                    {
+                        "name": "task",
+                        "args": delegated_task_args,
+                        "id": "call_1",
+                        "type": "tool_call",
+                    }
+                ],
+            ),
+            AIMessage(content="Parent integrated the child summary."),
+        ]
+    )
+    child_model = RecordingFakeModel(
+        responses=[AIMessage(content="README summary from child.")]
+    )
+
+    result = s04.build_agent(
+        model=main_model,
+        subagent_model=child_model,
+    ).invoke(
+        {
+            "messages": [
+                {
+                    "role": "user",
+                    "content": "First inspect setup.py, then delegate the README check.",
+                }
+            ]
+        }
+    )
+
+    assert "prompt" not in delegated_task_args
+    assert set(delegated_task_args) == {"description", "subagent_type"}
+    assert "task" in main_model.bound_tool_names
+    assert set(child_model.bound_tool_names) == {
+        "bash",
+        "read_file",
+        "write_file",
+        "edit_file",
+    }
+    assert len(child_model.seen_messages) == 1
+    assert [type(message).__name__ for message in child_model.seen_messages[0]] == [
+        "SystemMessage",
+        "HumanMessage",
+    ]
+    assert (
+        child_model.seen_messages[0][1].content
+        == delegated_task_args["description"]
+    )
+
+    tool_messages = [
+        message
+        for message in result["messages"]
+        if isinstance(message, ToolMessage)
+    ]
+    assert len(tool_messages) == 1
+    assert tool_messages[0].name == "task"
+    tool_content = str(tool_messages[0].content)
+    assert "README summary from child." in tool_content
+    assert "First inspect setup.py" not in tool_content
+    assert "SystemMessage" not in tool_content
+
+
+def test_s05_uses_skills_middleware_instead_of_load_skill_tool(
+    tmp_path: Path,
+) -> None:
+    skills_dir = tmp_path / "skills" / "demo"
+    skills_dir.mkdir(parents=True)
+    skills_dir.joinpath("SKILL.md").write_text(
+        "---\nname: demo\ndescription: Demo skill\n---\n\nUse this skill.\n",
+        encoding="utf-8",
+    )
+
+    model = RecordingFakeModel(responses=[AIMessage(content="done")])
+    model.seen_messages = []
+    backend = FilesystemBackend(root_dir=tmp_path, virtual_mode=True)
+
+    s05.build_agent(
+        model=model,
+        backend=backend,
+        skill_sources=["/skills"],
+    ).invoke({"messages": [{"role": "user", "content": "Need a skill."}]})
+
+    assert "load_skill" not in model.bound_tool_names
+    assert set(model.bound_tool_names) == {"bash", "read_file", "write_file", "edit_file"}
+
+    system_messages = [
+        message
+        for message in model.seen_messages[0]
+        if isinstance(message, SystemMessage)
+    ]
+    assert len(system_messages) == 1
+    system_text = _system_text(system_messages[0])
+    assert "Demo skill" in system_text
+    assert "/skills/demo/SKILL.md" in system_text
+    assert "Use this skill." not in system_text
+
+
+def test_s05_default_workspace_skill_path_is_advertised_then_read_on_demand() -> None:
+    model = RecordingFakeModel(responses=[AIMessage(content="done")])
+    model.seen_messages = []
+
+    s05.build_agent(model=model).invoke(
+        {"messages": [{"role": "user", "content": "Need code review guidance."}]}
+    )
+
+    system_messages = [
+        message
+        for message in model.seen_messages[0]
+        if isinstance(message, SystemMessage)
+    ]
+    assert len(system_messages) == 1
+    system_text = _system_text(system_messages[0])
+
+    assert "/skills/code-review/SKILL.md" in system_text
+    assert "Code Review Skill" not in system_text
+    assert "Review Checklist" not in system_text
+
+    full_skill_text = s05.read_file.invoke({"path": "/skills/code-review/SKILL.md"})
+
+    assert "# Code Review Skill" in full_skill_text
+    assert "## Review Checklist" in full_skill_text
diff --git a/tests/test_s04_subagent_baseline.py b/tests/test_s04_subagent_baseline.py
new file mode 100644
index 000000000..54fa81547
--- /dev/null
+++ b/tests/test_s04_subagent_baseline.py
@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+import importlib
+
+
+def test_s04_build_subagents_describes_the_child_agent_surface() -> None:
+    s04 = importlib.import_module("agents_deepagents.s04_subagent")
+    model = object()
+
+    subagents = s04.build_subagents(model)
+
+    assert subagents == [
+        {
+            "name": s04.SUBAGENT_TYPE,
+            "description": s04.SUBAGENT_DESCRIPTION,
+            "system_prompt": s04.SUBAGENT_SYSTEM,
+            "model": model,
+            "tools": s04.TOOLS,
+        }
+    ]
+
+
+def test_s04_documents_original_to_deep_agents_mapping_bridge() -> None:
+    s04 = importlib.import_module("agents_deepagents.s04_subagent")
+
+    assert "run_subagent(prompt)" in (s04.__doc__ or "")
+    assert "task(description, subagent_type)" in (s04.__doc__ or "")
+    assert "ToolMessage" in (s04.__doc__ or "")
+
+
+def test_s04_build_agent_uses_subagent_middleware_instead_of_legacy_helpers(
+    monkeypatch,
+) -> None:
+    s04 = importlib.import_module("agents_deepagents.s04_subagent")
+    captured: dict[str, object] = {}
+
+    class FakeSubAgentMiddleware:
+        def __init__(self, *, backend, subagents):
+            captured["backend"] = backend
+            captured["subagents"] = subagents
+
+    def fake_create_agent(*, model, tools, system_prompt, middleware):
+        captured["model"] = model
+        captured["tools"] = tools
+        captured["system_prompt"] = system_prompt
+        captured["middleware"] = middleware
+        return object()
+
+    main_model = object()
+    child_model = object()
+
+    monkeypatch.setattr(s04, "create_agent", fake_create_agent)
+    monkeypatch.setattr(s04, "SubAgentMiddleware", FakeSubAgentMiddleware)
+
+    agent = s04.build_agent(model=main_model, subagent_model=child_model)
+
+    assert agent is not None
+    assert captured["model"] is main_model
+    assert captured["tools"] == s04.TOOLS
+    assert captured["system_prompt"] == s04.SYSTEM
+    assert len(captured["middleware"]) == 1
+    assert captured["backend"] is s04.StateBackend
+    assert captured["subagents"] == s04.build_subagents(child_model)
+    assert not hasattr(s04, "run_subagent")
+    assert not hasattr(s04, "task")
+    assert not hasattr(s04, "PARENT_TOOLS")
+    assert not hasattr(s04, "CHILD_TOOLS")
+
+
+def test_s04_build_agent_defaults_child_model_to_parent_model(
+    monkeypatch,
+) -> None:
+    s04 = importlib.import_module("agents_deepagents.s04_subagent")
+    main_model = object()
+    captured: dict[str, object] = {}
+
+    class FakeSubAgentMiddleware:
+        def __init__(self, *, backend, subagents):
+            captured["backend"] = backend
+            captured["subagents"] = subagents
+
+    monkeypatch.setattr(s04, "build_openai_model", lambda: main_model)
+    monkeypatch.setattr(s04, "SubAgentMiddleware", FakeSubAgentMiddleware)
+    monkeypatch.setattr(
+        s04,
+        "create_agent",
+        lambda **kwargs: kwargs,
+    )
+
+    agent = s04.build_agent()
+
+    assert agent["model"] is main_model
+    assert captured["backend"] is s04.StateBackend
+    assert captured["subagents"] == s04.build_subagents(main_model)
+
+
+def test_s04_agent_loop_appends_only_parent_summary(monkeypatch) -> None:
+    s04 = importlib.import_module("agents_deepagents.s04_subagent")
+
+    class FakeAgent:
+        def __init__(self) -> None:
+            self.payloads = []
+
+        def invoke(self, payload):
+            self.payloads.append({"messages": [*payload["messages"]]})
+            return {
+                "messages": [
+                    *payload["messages"],
+                    {"role": "assistant", "content": "delegated findings"},
+                ]
+            }
+
+    fake = FakeAgent()
+    monkeypatch.setattr(s04, "build_agent", lambda: fake)
+
+    history = [{"role": "user", "content": "continue"}]
+
+    assert s04.agent_loop(history) == "delegated findings"
+    assert fake.payloads == [
+        {"messages": [{"role": "user", "content": "continue"}]}
+    ]
+    assert history == [
+        {"role": "user", "content": "continue"},
+        {"role": "assistant", "content": "delegated findings"},
+    ]
+
+
+def test_s04_extracts_structured_task_activity_for_non_terminal_ui() -> None:
+    s04 = importlib.import_module("agents_deepagents.s04_subagent")
+    from langchain_core.messages import AIMessage, ToolMessage
+
+    result = {
+        "messages": [
+            AIMessage(
+                content="",
+                tool_calls=[
+                    {
+                        "name": "task",
+                        "args": {
+                            "description": "Inspect README.md and return one short summary.",
+                            "subagent_type": s04.SUBAGENT_TYPE,
+                        },
+                        "id": "call_1",
+                        "type": "tool_call",
+                    }
+                ],
+            ),
+            ToolMessage(
+                content="README summary from child.",
+                tool_call_id="call_1",
+                name="task",
+            ),
+        ]
+    }
+
+    assert s04.extract_task_activity(result) == [
+        {
+            "description": "Inspect README.md and return one short summary.",
+            "subagent_type": s04.SUBAGENT_TYPE,
+            "summary": "README summary from child.",
+        }
+    ]
+
+
+def test_s04_renders_task_activity_for_terminal_output() -> None:
+    s04 = importlib.import_module("agents_deepagents.s04_subagent")
+
+    lines = s04.render_task_activity(
+        [
+            {
+                "description": "Inspect README.md and return one short summary.",
+                "subagent_type": s04.SUBAGENT_TYPE,
+                "summary": "README summary from child.",
+            }
+        ]
+    )
+
+    assert lines == [
+        "> task (general-purpose): Inspect README.md and return one short summary.",
+        "  README summary from child.",
+    ]
diff --git a/tests/test_s06_context_compact_baseline.py b/tests/test_s06_context_compact_baseline.py
new file mode 100644
index 000000000..08018cef9
--- /dev/null
+++ b/tests/test_s06_context_compact_baseline.py
@@ -0,0 +1,256 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from agents_deepagents import s06_context_compact as s06
+
+
+def message(
+    message_id: str,
+    role: s06.MessageRole,
+    content: str,
+    *,
+    name: str | None = None,
+    tool_call_id: str | None = None,
+    **metadata: object,
+) -> s06.ContextMessage:
+    return s06.ContextMessage(
+        id=message_id,
+        role=role,
+        content=content,
+        name=name,
+        tool_call_id=tool_call_id,
+        metadata=dict(metadata),
+    )
+
+
+def summarizer(messages: list[s06.ContextMessage] | tuple[s06.ContextMessage, ...]) -> str:
+    return "summary:" + ",".join(message.id for message in messages)
+
+
+def test_apply_tool_result_budget_persists_large_outputs(tmp_path: Path) -> None:
+    original = "A" * 160
+    state = s06.ContextCompressionState(
+        messages=[
+            message("u1", "user", "Inspect the repo"),
+            message("a1", "assistant", "Running tool"),
+            message(
+                "t1",
+                "tool",
+                original,
+                name="bash",
+                tool_call_id="tool-1",
+                group_id="round-1",
+            ),
+        ]
+    )
+
+    compacted = s06.apply_tool_result_budget(
+        state,
+        storage_dir=tmp_path,
+        per_tool_threshold=80,
+        per_message_budget=1_000,
+        preview_chars=40,
+    )
+
+    assert compacted.messages[2].content == original
+    assert compacted.model_messages[2].content.startswith("<persisted-output>")
+    persisted = compacted.persisted_outputs["tool-1"]
+    assert (tmp_path / "tool-1.txt").read_text() == original
+    assert persisted.preview == "A" * 23 + "... [truncated]"
+    assert compacted.compact_boundaries[-1].kind == "tool_result_budget"
+
+
+def test_aggregate_budget_reuses_frozen_replacement_decisions(tmp_path: Path) -> None:
+    first_state = s06.ContextCompressionState(
+        messages=[
+            message("u1", "user", "Need two tool results"),
+            message(
+                "t-small",
+                "tool",
+                "S" * 80,
+                name="bash",
+                tool_call_id="tool-small",
+                group_id="round-1",
+            ),
+            message(
+                "t-large",
+                "tool",
+                "L" * 140,
+                name="read_file",
+                tool_call_id="tool-large",
+                group_id="round-1",
+            ),
+        ]
+    )
+    first_result = s06.apply_tool_result_budget(
+        first_state,
+        storage_dir=tmp_path,
+        per_tool_threshold=999,
+        per_message_budget=210,
+        preview_chars=50,
+    )
+
+    assert "tool-large" in first_result.replacement_decisions
+
+    second_state = s06.ContextCompressionState(
+        messages=[
+            message("u2", "user", "Replay the same round"),
+            message(
+                "t-small-2",
+                "tool",
+                "S" * 80,
+                name="bash",
+                tool_call_id="tool-small",
+                group_id="round-2",
+            ),
+            message(
+                "t-large-2",
+                "tool",
+                "L" * 140,
+                name="read_file",
+                tool_call_id="tool-large",
+                group_id="round-2",
+            ),
+        ],
+        persisted_outputs=first_result.persisted_outputs,
+        replacement_decisions=first_result.replacement_decisions,
+    )
+    second_result = s06.apply_tool_result_budget(
+        second_state,
+        storage_dir=tmp_path,
+        per_tool_threshold=999,
+        per_message_budget=500,
+        preview_chars=50,
+    )
+
+    assert second_result.model_messages[2].content.startswith("<persisted-output>")
+
+
+def test_snip_projection_preserves_canonical_history() -> None:
+    state = s06.ContextCompressionState(
+        messages=[
+            message(f"m{index}", "user" if index % 2 else "assistant", f"msg {index}")
+            for index in range(1, 9)
+        ]
+    )
+
+    compacted = s06.snip_projection(state, keep_last=2)
+
+    assert len(compacted.messages) == 8
+    assert [msg.id for msg in compacted.model_messages] == ["snip-1", "m7", "m8"]
+    assert compacted.compact_boundaries[-1].kind == "snip"
+
+
+def test_microcompact_messages_clears_older_compactable_results() -> None:
+    state = s06.ContextCompressionState(
+        messages=[
+            message("u1", "user", "Run some tools"),
+            message("t1", "tool", "bash output 1" * 10, name="bash", tool_call_id="t1"),
+            message("t2", "tool", "read output 2" * 10, name="read_file", tool_call_id="t2"),
+            message("t3", "tool", "not compactable" * 10, name="custom", tool_call_id="t3"),
+            message("t4", "tool", "edit output 4" * 10, name="edit_file", tool_call_id="t4"),
+        ]
+    )
+
+    compacted = s06.microcompact_messages(state, keep_recent=1)
+
+    assert compacted.model_messages[1].content == s06.MICROCOMPACT_PLACEHOLDER
+    assert compacted.model_messages[2].content == s06.MICROCOMPACT_PLACEHOLDER
+    assert compacted.model_messages[3].content != s06.MICROCOMPACT_PLACEHOLDER
+    assert compacted.model_messages[4].content != s06.MICROCOMPACT_PLACEHOLDER
+    assert compacted.compact_boundaries[-1].details["cleared_tool_call_ids"] == ["t1", "t2"]
+
+
+def test_context_collapse_summarizes_oldest_groups_without_splitting_tool_pair() -> None:
+    state = s06.ContextCompressionState(
+        messages=[
+            message("u1", "user", "Need repo overview"),
+            message("a1", "assistant", "Calling bash", tool_call_id="tool-1"),
+            message("t1", "tool", "bash result" * 20, name="bash", tool_call_id="tool-1"),
+            message("u2", "user", "Anything else?"),
+            message("a2", "assistant", "Some follow-up"),
+            message("u3", "user", "Keep only the recent round"),
+            message("a3", "assistant", "Recent answer"),
+        ]
+    )
+
+    compacted = s06.context_collapse(
+        state,
+        summarizer,
+        collapse_threshold=40,
+        keep_recent_groups=1,
+    )
+
+    assert compacted.model_messages[0].content == "[context-collapse]\nsummary:u1,a1,t1,u2,a2"
+    assert [message.id for message in compacted.model_messages[1:]] == ["u3", "a3"]
+    assert compacted.compact_boundaries[-1].kind == "context_collapse"
+    assert {"a1", "t1"}.issubset(compacted.compact_boundaries[-1].source_message_ids)
+
+
+def test_auto_compact_if_needed_builds_summary_boundary() -> None:
+    state = s06.ContextCompressionState(
+        messages=[
+            message(f"m{index}", "user" if index % 2 else "assistant", f"content {index} " * 20)
+            for index in range(1, 7)
+        ]
+    )
+
+    compacted = s06.auto_compact_if_needed(
+        state,
+        summarizer,
+        threshold=120,
+        keep_recent=2,
+    )
+
+    assert compacted.model_messages[0].content.startswith("[auto-compact]")
+    assert [message.id for message in compacted.model_messages[1:]] == ["m5", "m6"]
+    assert compacted.compact_boundaries[-1].kind == "auto_compact"
+
+
+def test_reactive_compact_on_overflow_attempts_collapse_before_fallback() -> None:
+    base_state = s06.ContextCompressionState(
+        messages=[
+            message("u1", "user", "Old context" * 20),
+            message("a1", "assistant", "Old answer" * 20),
+            message("u2", "user", "Recent context" * 20),
+            message("a2", "assistant", "Recent answer" * 20),
+        ]
+    )
+    collapsed = s06.context_collapse(
+        base_state,
+        lambda messages: "S" * 400,
+        collapse_threshold=60,
+        keep_recent_groups=1,
+    )
+
+    recovered = s06.reactive_compact_on_overflow(
+        collapsed,
+        s06.PromptTooLongError("prompt too long"),
+        summarizer,
+        threshold=90,
+        keep_recent=1,
+        drain_summary_budget=180,
+    )
+
+    assert recovered.transitions.index("collapse_drain_retry") < recovered.transitions.index(
+        "reactive_compact_retry"
+    )
+    assert recovered.compact_boundaries[-1].kind == "reactive_compact"
+    assert recovered.model_messages[0].content.startswith("[reactive-compact]")
+
+
+def test_metadata_matches_readme_disclosure() -> None:
+    readme = Path("agents_deepagents/README.md").read_text(encoding="utf-8")
+
+    for stage in s06.SOURCE_BACKED_STAGES:
+        assert f"`{stage}`" in readme
+    for stage in s06.INFERRED_STAGES:
+        assert f"`{stage}`" in readme
+    for keyword in [
+        "Character counts stand in for exact tokenizer budgets.",
+        "Persisted tool outputs are stored as plain text files instead of provider",
+        "Snip projection and context collapse are honest teaching equivalents",
+        "Auto compact omits session-memory extraction",
+    ]:
+        assert keyword in readme
diff --git a/tests/test_stage_track_capability_contract.py b/tests/test_stage_track_capability_contract.py
new file mode 100644
index 000000000..a2d45620d
--- /dev/null
+++ b/tests/test_stage_track_capability_contract.py
@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import importlib
+
+
+CAPABILITY_MATRIX = {
+    "s01_agent_loop": {"bash"},
+    "s02_tool_use": {"bash", "read_file", "write_file", "edit_file"},
+    "s03_todo_write": {
+        "bash",
+        "read_file",
+        "write_file",
+        "edit_file",
+        "write_plan",
+    },
+    "s04_subagent": {"bash", "read_file", "write_file", "edit_file", "task"},
+    # s05 skills now arrive through Deep Agents middleware + read_file, not a
+    # bespoke load_skill tool.
+    "s05_skill_loading": {"bash", "read_file", "write_file", "edit_file"},
+    "s06_context_compact": {
+        "bash",
+        "read_file",
+        "write_file",
+        "edit_file",
+        "compact",
+    },
+}
+
+FUTURE_STAGE_CAPABILITIES = {"write_plan", "task", "compact"}
+MIDDLEWARE_TOOL_MATRIX = {
+    "s04_subagent": {"task"},
+}
+
+
+def module_tool_names(module_name: str) -> set[str]:
+    module = importlib.import_module(f"agents_deepagents.{module_name}")
+    tools = getattr(module, "PARENT_TOOLS", None)
+    if tools is None:
+        tools = getattr(module, "TOOLS")
+    names = {
+        getattr(tool, "name", getattr(tool, "__name__", type(tool).__name__))
+        for tool in tools
+    }
+    return names | MIDDLEWARE_TOOL_MATRIX.get(module_name, set())
+
+
+def test_stage_track_exposes_only_expected_capabilities() -> None:
+    for module_name, expected in CAPABILITY_MATRIX.items():
+        assert module_tool_names(module_name) == expected
+
+
+def test_future_stage_capabilities_stay_hidden_until_their_chapter() -> None:
+    for module_name, expected in CAPABILITY_MATRIX.items():
+        available_future_caps = module_tool_names(module_name) & FUTURE_STAGE_CAPABILITIES
+        assert available_future_caps == (expected & FUTURE_STAGE_CAPABILITIES)
diff --git a/web/next.config.ts b/web/next.config.ts
index 4dd888c18..b4b7caf57 100644
--- a/web/next.config.ts
+++ b/web/next.config.ts
@@ -1,9 +1,13 @@
+import path from "node:path";
 import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
   output: "export",
   images: { unoptimized: true },
   trailingSlash: true,
+  turbopack: {
+    root: path.resolve(__dirname),
+  },
 };
 
 export default nextConfig;
diff --git a/web/package.json b/web/package.json
index 984b6028a..d1fe6fe36 100644
--- a/web/package.json
+++ b/web/package.json
@@ -8,7 +8,9 @@
     "dev": "next dev",
     "prebuild": "npm run extract",
     "build": "next build",
-    "start": "next start"
+    "start": "next start",
+    "test:browser:smoke": "bash scripts/browser-smoke.sh",
+    "test:browser:flows": "bash scripts/browser-flows.sh"
   },
   "dependencies": {
     "diff": "^8.0.3",
diff --git a/web/scripts/browser-flows.sh b/web/scripts/browser-flows.sh
new file mode 100644
index 000000000..c8b0397fc
--- /dev/null
+++ b/web/scripts/browser-flows.sh
@@ -0,0 +1,377 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+BASE_URL="${BASE_URL:-${1:-http://127.0.0.1:3002}}"
+LOCALE="${LOCALE:-zh}"
+SESSION_NAME="${SESSION_NAME:-learn-claude-code-flows-${LOCALE}}"
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+source "$ROOT_DIR/scripts/browser-test-lib.sh"
+
+agent-browser() {
+  command agent-browser --session-name "$SESSION_NAME" "$@"
+}
+
+trap 'stop_static_server_if_started; agent-browser close >/dev/null 2>&1 || true' EXIT
+
+locale_text() {
+  local key="$1"
+  case "$LOCALE:$key" in
+    zh:deep_dive) echo '深入探索' ;;
+    en:deep_dive) echo 'Deep Dive' ;;
+    ja:deep_dive) echo '深掘り' ;;
+
+    zh:bridge_control_plane) echo '工具控制平面' ;;
+    en:bridge_control_plane) echo 'Tool Control Plane' ;;
+    ja:bridge_control_plane) echo 'ツール制御プレーン' ;;
+
+    *) echo "Unknown locale text key: ${LOCALE}:${key}" >&2; return 1 ;;
+  esac
+}
+
+wait_page() {
+  agent-browser wait --load networkidle >/dev/null 2>&1 || agent-browser wait 600 >/dev/null 2>&1 || true
+  agent-browser wait 1200 >/dev/null 2>&1 || true
+  agent-browser get title >/dev/null 2>&1 || true
+}
+
+open_page() {
+  local path="$1"
+  local attempt
+
+  agent-browser close >/dev/null 2>&1 || true
+  for attempt in 1 2 3; do
+    agent-browser --json errors --clear >/dev/null 2>&1 || true
+    if ! open_url_with_retry "${BASE_URL}${path}"; then
+      continue
+    fi
+    wait_page
+    if assert_url_contains "$path" >/dev/null 2>&1; then
+      return 0
+    fi
+    agent-browser close >/dev/null 2>&1 || true
+    sleep 0.4
+  done
+
+  echo "Navigation failed for ${BASE_URL}${path}" >&2
+  return 1
+}
+
+assert_url_contains() {
+  local expected="$1"
+  local url_json
+  url_json="$(agent-browser --json get url)"
+  URL_JSON="$url_json" EXPECTED="$expected" python3 - <<'PY'
+import json
+import os
+import sys
+
+payload = json.loads(os.environ["URL_JSON"])
+url = payload.get("data", {}).get("url", "")
+expected = os.environ["EXPECTED"]
+if expected not in url:
+    print(f"Expected URL containing {expected!r}, got {url!r}", file=sys.stderr)
+    sys.exit(1)
+PY
+}
+
+assert_body_contains() {
+  local pattern="$1"
+  agent-browser get text body | rg -q "$pattern"
+}
+
+assert_no_overflow() {
+  local info_json
+  info_json="$(agent-browser --json eval '({
+    overflow: document.documentElement.scrollWidth > window.innerWidth,
+    width: window.innerWidth,
+    scrollWidth: document.documentElement.scrollWidth
+  })')"
+  INFO_JSON="$info_json" python3 - <<'PY'
+import json
+import os
+import sys
+
+payload = json.loads(os.environ["INFO_JSON"])
+result = payload.get("data", {}).get("result", {})
+if result.get("overflow"):
+    print(
+        f"Overflow detected: width={result.get('width')} scrollWidth={result.get('scrollWidth')}",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+PY
+}
+
+assert_no_page_errors() {
+  local errors_json
+  errors_json="$(agent-browser --json errors)"
+  ERRORS_JSON="$errors_json" python3 - <<'PY'
+import json
+import os
+import sys
+
+payload = json.loads(os.environ["ERRORS_JSON"])
+errors = payload.get("data", {}).get("errors", [])
+if errors:
+    print(f"Unexpected page errors: {errors}", file=sys.stderr)
+    sys.exit(1)
+PY
+}
+
+click_locale_button() {
+  local label="$1"
+  agent-browser --json eval "(() => {
+    const buttons = Array.from(document.querySelectorAll('button'));
+    const match = buttons.find((button) => button.textContent.trim() === '${label}');
+    if (!match) {
+      throw new Error('Locale button not found: ${label}');
+    }
+    match.click();
+    return true;
+  })() " >/dev/null
+}
+
+click_link_exact() {
+  local label="$1"
+  agent-browser --json eval "(() => {
+    const links = Array.from(document.querySelectorAll('a'));
+    const match = links.find((link) => link.textContent.trim() === '${label}');
+    if (!match) {
+      throw new Error('Link not found: ${label}');
+    }
+    match.click();
+    return true;
+  })() " >/dev/null
+}
+
+click_link_containing() {
+  local label="$1"
+  agent-browser --json eval "(() => {
+    const normalize = (value) => value.replace(/\s+/g, ' ').trim();
+    const links = Array.from(document.querySelectorAll('a'));
+    const match = links.find((link) => normalize(link.textContent).includes('${label}'));
+    if (!match) {
+      throw new Error('Link not found: ${label}');
+    }
+    match.click();
+    return true;
+  })() " >/dev/null
+}
+
+click_link_by_href() {
+  local href_fragment="$1"
+  local label_fragment="${2:-}"
+  agent-browser --json eval "(() => {
+    const normalize = (value) => value.replace(/\s+/g, ' ').trim();
+    const links = Array.from(document.querySelectorAll('a'));
+    const match = links.find((link) => {
+      const hrefMatches = link.href.includes('${href_fragment}');
+      const labelMatches = '${label_fragment}' ? normalize(link.textContent).includes('${label_fragment}') : true;
+      return hrefMatches && labelMatches;
+    });
+    if (!match) {
+      throw new Error('Link not found for href: ${href_fragment}');
+    }
+    match.click();
+    return true;
+  })() " >/dev/null
+}
+
+run_flow() {
+  local name="$1"
+  shift
+  echo "FLOW\t${name}"
+  "$@"
+  echo "PASS\t${name}"
+}
+
+flow_home_to_s01() {
+  open_page "/${LOCALE}/"
+  click_link_by_href "/${LOCALE}/s01/"
+  wait_page
+  assert_url_contains "/${LOCALE}/s01/"
+  assert_body_contains 's01'
+  assert_no_overflow
+  assert_no_page_errors
+}
+
+flow_home_to_timeline() {
+  open_page "/${LOCALE}/timeline/"
+  assert_url_contains "/${LOCALE}/timeline/"
+  assert_body_contains 's01'
+  assert_body_contains 's19'
+  assert_no_overflow
+  assert_no_page_errors
+}
+
+flow_home_to_layers() {
+  open_page "/${LOCALE}/layers/"
+  assert_url_contains "/${LOCALE}/layers/"
+  assert_body_contains 'P1'
+  assert_body_contains 's19'
+  assert_no_overflow
+  assert_no_page_errors
+}
+
+flow_home_to_compare() {
+  open_page "/${LOCALE}/"
+  click_link_by_href "/${LOCALE}/compare/"
+  wait_page
+  assert_url_contains "/${LOCALE}/compare/"
+  assert_body_contains 's14 -> s15'
+  assert_no_overflow
+  assert_no_page_errors
+}
+
+flow_compare_default_state() {
+  open_page "/${LOCALE}/compare"
+  assert_body_contains 's01'
+  assert_body_contains 's02'
+  assert_body_contains 's14 -> s15'
+  assert_no_overflow
+  assert_no_page_errors
+}
+
+flow_timeline_to_stage_exit() {
+  open_page "/${LOCALE}/timeline"
+  click_link_by_href "/${LOCALE}/s06/"
+  wait_page
+  assert_url_contains "/${LOCALE}/s06/"
+  assert_body_contains 's06'
+  assert_no_overflow
+  assert_no_page_errors
+}
+
+flow_layers_to_stage_entry() {
+  open_page "/${LOCALE}/layers"
+  click_link_by_href "/${LOCALE}/s15/"
+  wait_page
+  assert_url_contains "/${LOCALE}/s15/"
+  assert_body_contains 's15'
+  assert_no_overflow
+  assert_no_page_errors
+}
+
+flow_chapter_to_bridge_doc() {
+  open_page "/${LOCALE}/s02"
+  agent-browser --json find text "$(locale_text deep_dive)" click >/dev/null
+  wait_page
+  click_link_by_href "/${LOCALE}/docs/s02a-tool-control-plane/" "$(locale_text bridge_control_plane)"
+  wait_page
+  assert_url_contains "/${LOCALE}/docs/s02a-tool-control-plane/"
+  assert_body_contains "$(locale_text bridge_control_plane)"
+  assert_no_overflow
+  assert_no_page_errors
+}
+
+flow_bridge_doc_home_return() {
+  open_page "/${LOCALE}/docs/s00f-code-reading-order"
+  click_link_by_href "/${LOCALE}/"
+  wait_page
+  assert_url_contains "/${LOCALE}/"
+  assert_body_contains 's01'
+  assert_no_overflow
+  assert_no_page_errors
+}
+
+flow_bridge_doc_back_to_chapter() {
+  open_page "/${LOCALE}/docs/s02a-tool-control-plane"
+  click_link_by_href "/${LOCALE}/s02/" 's02'
+  wait_page
+  assert_url_contains "/${LOCALE}/s02/"
+  assert_body_contains 's02'
+  assert_no_overflow
+  assert_no_page_errors
+}
+
+flow_bridge_doc_locale_switching() {
+  open_page "/${LOCALE}/docs/s00f-code-reading-order"
+  click_locale_button 'EN'
+  wait_page
+  assert_url_contains '/en/docs/s00f-code-reading-order/'
+  click_locale_button '日本語'
+  wait_page
+  assert_url_contains '/ja/docs/s00f-code-reading-order/'
+  click_locale_button '中文'
+  wait_page
+  assert_url_contains '/zh/docs/s00f-code-reading-order/'
+  assert_no_page_errors
+}
+
+flow_compare_preset() {
+  open_page "/${LOCALE}/compare"
+  agent-browser --json find text 's14 -> s15' click >/dev/null
+  agent-browser wait 800 >/dev/null 2>&1 || true
+  assert_body_contains 's14'
+  assert_body_contains 's15'
+  assert_no_overflow
+  assert_no_page_errors
+}
+
+flow_chapter_next_navigation() {
+  open_page "/${LOCALE}/s15"
+  click_link_by_href "/${LOCALE}/s16/"
+  wait_page
+  assert_url_contains "/${LOCALE}/s16/"
+  assert_body_contains 's16'
+  assert_no_overflow
+  assert_no_page_errors
+}
+
+flow_locale_switching() {
+  open_page "/${LOCALE}/s01"
+  click_locale_button 'EN'
+  wait_page
+  assert_url_contains '/en/s01/'
+  click_locale_button '日本語'
+  wait_page
+  assert_url_contains '/ja/s01/'
+  click_locale_button '中文'
+  wait_page
+  assert_url_contains '/zh/s01/'
+  assert_no_page_errors
+}
+
+flow_mobile_core_pages() {
+  agent-browser set viewport 390 844 >/dev/null 2>&1
+  for path in \
+    "/${LOCALE}/" \
+    "/${LOCALE}/timeline" \
+    "/${LOCALE}/layers" \
+    "/${LOCALE}/compare" \
+    "/${LOCALE}/s15" \
+    "/${LOCALE}/docs/s00f-code-reading-order"
+  do
+    open_page "$path"
+    assert_no_overflow
+    assert_no_page_errors
+  done
+  agent-browser set viewport 1440 960 >/dev/null 2>&1
+}
+
+main() {
+  start_static_server_if_needed "$BASE_URL"
+  agent-browser close >/dev/null 2>&1 || true
+  agent-browser set viewport 1440 960 >/dev/null 2>&1 || true
+  open_url_with_retry "${BASE_URL}/${LOCALE}/" >/dev/null 2>&1 || open_url_with_retry "${BASE_URL}/" >/dev/null 2>&1 || true
+  agent-browser wait 400 >/dev/null 2>&1 || true
+
+  run_flow home-to-s01 flow_home_to_s01
+  run_flow home-to-timeline flow_home_to_timeline
+  run_flow home-to-layers flow_home_to_layers
+  run_flow home-to-compare flow_home_to_compare
+  run_flow compare-default-state flow_compare_default_state
+  run_flow timeline-to-stage-exit flow_timeline_to_stage_exit
+  run_flow layers-to-stage-entry flow_layers_to_stage_entry
+  run_flow chapter-to-bridge-doc flow_chapter_to_bridge_doc
+  run_flow bridge-doc-home-return flow_bridge_doc_home_return
+  run_flow bridge-doc-back-to-chapter flow_bridge_doc_back_to_chapter
+  run_flow bridge-doc-locale-switching flow_bridge_doc_locale_switching
+  run_flow compare-preset flow_compare_preset
+  run_flow chapter-next-navigation flow_chapter_next_navigation
+  run_flow locale-switching flow_locale_switching
+  run_flow mobile-core-pages flow_mobile_core_pages
+}
+
+main "$@"
diff --git a/web/scripts/browser-smoke.sh b/web/scripts/browser-smoke.sh
new file mode 100644
index 000000000..180698859
--- /dev/null
+++ b/web/scripts/browser-smoke.sh
@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+BASE_URL="${BASE_URL:-${1:-http://127.0.0.1:3002}}"
+LOCALES="${LOCALES:-zh}"
+
+TMP_DIR="$(mktemp -d)"
+source "$ROOT_DIR/scripts/browser-test-lib.sh"
+
+trap 'rm -rf "$TMP_DIR"; stop_static_server_if_started; agent-browser close >/dev/null 2>&1 || true' EXIT
+
+discover_routes() {
+  local locale="$1"
+  find "$ROOT_DIR/out/$locale" -type f -name 'index.html' | sort | while read -r file; do
+    local route="${file#"$ROOT_DIR/out"}"
+    route="${route%index.html}"
+    echo "$route"
+  done
+}
+
+check_route() {
+  local route="$1"
+  local safe_name="${route#/}"
+  local snapshot_file="$TMP_DIR/${safe_name//\//_}.png"
+  local info_json
+  local errors_json
+  local check_output=""
+  local attempt
+
+  agent-browser --json errors --clear >/dev/null 2>&1 || true
+  agent-browser close >/dev/null 2>&1 || true
+  if ! open_url_with_retry "${BASE_URL}${route}"; then
+    echo "FAIL	${route}	navigation-failed"
+    return 1
+  fi
+  agent-browser wait --load networkidle >/dev/null 2>&1 || agent-browser wait 500 >/dev/null 2>&1 || true
+  agent-browser get title >/dev/null 2>&1 || true
+
+  for attempt in 1 2 3 4 5; do
+    info_json="$(agent-browser --json eval '({
+      title: document.title,
+      h1Count: document.querySelectorAll("h1").length,
+      mainExists: Boolean(document.querySelector("main")),
+      overflow: document.documentElement.scrollWidth > window.innerWidth,
+      notFound: document.body.innerText.includes("This page could not be found."),
+      bodyLength: document.body.innerText.trim().length
+    })')"
+    errors_json="$(agent-browser --json errors)"
+
+    if check_output="$(
+      INFO_JSON="$info_json" ERRORS_JSON="$errors_json" python3 - "$route" <<'PY'
+import json
+import os
+import sys
+
+route = sys.argv[1]
+info = json.loads(os.environ["INFO_JSON"]) or {}
+errors = json.loads(os.environ["ERRORS_JSON"]) or {}
+
+if not isinstance(info, dict):
+    info = {}
+if not isinstance(errors, dict):
+    errors = {}
+
+result = (info.get("data") or {}).get("result") or {}
+page_errors = (errors.get("data") or {}).get("errors") or []
+issues = []
+
+if not result:
+    issues.append("missing-eval-result")
+if not result.get("title"):
+    issues.append("missing-title")
+if result.get("h1Count", 0) < 1:
+    issues.append("missing-h1")
+if not result.get("mainExists"):
+    issues.append("missing-main")
+if result.get("overflow"):
+    issues.append("horizontal-overflow")
+if result.get("notFound"):
+    issues.append("rendered-404")
+if result.get("bodyLength", 0) < 80:
+    issues.append("body-too-short")
+if page_errors:
+    issues.append(f"page-errors:{len(page_errors)}")
+
+if issues:
+    print(f"FAIL\t{route}\t{','.join(issues)}")
+    sys.exit(1)
+
+print(f"OK\t{route}")
+PY
+    )"; then
+      echo "$check_output"
+      return 0
+    fi
+
+    if [[ "$attempt" -lt 5 ]]; then
+      agent-browser wait 900 >/dev/null 2>&1 || true
+    fi
+  done
+
+  echo "${check_output:-FAIL	${route}	unknown-check-failure}"
+  agent-browser screenshot "$snapshot_file" >/dev/null 2>&1 || true
+  if [[ -f "$snapshot_file" ]]; then
+    echo "ARTIFACT	${route}	${snapshot_file}" >&2
+  fi
+  return 1
+}
+
+main() {
+  local failed=0
+  local total=0
+  local warm_locale="${LOCALES%%,*}"
+
+  start_static_server_if_needed "$BASE_URL"
+  agent-browser close >/dev/null 2>&1 || true
+  agent-browser set viewport 1440 960 >/dev/null 2>&1 || true
+  open_url_with_retry "${BASE_URL}/${warm_locale}/" >/dev/null 2>&1 || open_url_with_retry "${BASE_URL}/" >/dev/null 2>&1 || true
+  agent-browser wait 400 >/dev/null 2>&1 || true
+
+  for locale in ${LOCALES//,/ }; do
+    while read -r route; do
+      [[ -z "$route" ]] && continue
+      total=$((total + 1))
+      if ! check_route "$route"; then
+        failed=$((failed + 1))
+      fi
+    done < <(discover_routes "$locale")
+  done
+
+  echo
+  echo "Smoke summary: ${total} checked, ${failed} failed"
+  if [[ "$failed" -ne 0 ]]; then
+    exit 1
+  fi
+}
+
+main "$@"
diff --git a/web/scripts/browser-test-lib.sh b/web/scripts/browser-test-lib.sh
new file mode 100644
index 000000000..58a4472d0
--- /dev/null
+++ b/web/scripts/browser-test-lib.sh
@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+OUT_DIR="$ROOT_DIR/out"
+TEST_SERVER_PID=""
+
+base_url_port() {
+  python3 - "$1" <<'PY'
+from urllib.parse import urlparse
+import sys
+
+url = sys.argv[1]
+parsed = urlparse(url)
+if not parsed.scheme or not parsed.hostname or not parsed.port:
+    raise SystemExit(f"Unable to parse host/port from BASE_URL: {url}")
+print(parsed.port)
+PY
+}
+
+base_url_ready() {
+  local base_url="$1"
+  curl -fsS -o /dev/null "${base_url}/" >/dev/null 2>&1
+}
+
+start_static_server_if_needed() {
+  local base_url="$1"
+  local port
+  local log_file
+  local attempt
+
+  if base_url_ready "$base_url"; then
+    return 0
+  fi
+
+  if [[ ! -d "$OUT_DIR" ]]; then
+    echo "Static export not found at $OUT_DIR. Run 'npm run build' first." >&2
+    return 1
+  fi
+
+  port="$(base_url_port "$base_url")"
+  log_file="${TMPDIR:-/tmp}/learn-claude-code-browser-tests-${port}.log"
+
+  python3 -m http.server "$port" -d "$OUT_DIR" >"$log_file" 2>&1 &
+  TEST_SERVER_PID=$!
+
+  for attempt in {1..40}; do
+    if base_url_ready "$base_url"; then
+      return 0
+    fi
+    sleep 0.25
+  done
+
+  echo "Failed to start static server for ${base_url}" >&2
+  if [[ -f "$log_file" ]]; then
+    cat "$log_file" >&2
+  fi
+  return 1
+}
+
+stop_static_server_if_started() {
+  if [[ -n "${TEST_SERVER_PID:-}" ]]; then
+    kill "$TEST_SERVER_PID" >/dev/null 2>&1 || true
+    wait "$TEST_SERVER_PID" >/dev/null 2>&1 || true
+    TEST_SERVER_PID=""
+  fi
+}
+
+open_url_with_retry() {
+  local url="$1"
+  local attempt
+  local current_url=""
+
+  for attempt in 1 2 3; do
+    if agent-browser open "$url" >/dev/null 2>&1; then
+      agent-browser wait --load networkidle >/dev/null 2>&1 || agent-browser wait 800 >/dev/null 2>&1 || true
+      current_url="$(agent-browser get url 2>/dev/null | tr -d '\r' | tail -n 1)"
+      current_url="${current_url%/}"
+      if [[ -n "$current_url" && "$current_url" != "about:blank" ]]; then
+        return 0
+      fi
+      agent-browser wait 600 >/dev/null 2>&1 || true
+      current_url="$(agent-browser get url 2>/dev/null | tr -d '\r' | tail -n 1)"
+      current_url="${current_url%/}"
+      if [[ -n "$current_url" && "$current_url" != "about:blank" ]]; then
+        return 0
+      fi
+    fi
+    agent-browser close >/dev/null 2>&1 || true
+    sleep 0.4
+  done
+
+  return 1
+}
diff --git a/web/scripts/extract-content.ts b/web/scripts/extract-content.ts
index 6e35badd9..3f4fc33de 100644
--- a/web/scripts/extract-content.ts
+++ b/web/scripts/extract-content.ts
@@ -115,6 +115,14 @@ function extractDocVersion(filename: string): string | null {
   return m ? m[1] : null;
 }
 
+function isMainlineChapterVersion(version: string | null): boolean {
+  return version !== null && (LEARNING_PATH as readonly string[]).includes(version);
+}
+
+function slugFromFilename(filename: string): string {
+  return path.basename(filename, ".md");
+}
+
 // Main extraction
 function main() {
   console.log("Extracting content from agents and docs...");
@@ -168,7 +176,7 @@ function main() {
       keyInsight: meta?.keyInsight ?? "",
       classes,
       functions,
-      layer: meta?.layer ?? "tools",
+      layer: meta?.layer ?? "core",
       source,
     });
   }
@@ -234,18 +242,22 @@ function main() {
 
       for (const filename of docFiles) {
         const version = extractDocVersion(filename);
-        if (!version) {
-          console.warn(`  Skipping doc ${locale}/${filename}: could not determine version`);
-          continue;
-        }
-
+        const kind = isMainlineChapterVersion(version) ? "chapter" : "bridge";
         const filePath = path.join(localeDir, filename);
         const content = fs.readFileSync(filePath, "utf-8");
 
         const titleMatch = content.match(/^#\s+(.+)$/m);
         const title = titleMatch ? titleMatch[1] : filename;
 
-        docs.push({ version, locale: locale as "en" | "zh" | "ja", title, content });
+        docs.push({
+          version: kind === "chapter" ? version : null,
+          slug: slugFromFilename(filename),
+          locale: locale as "en" | "zh" | "ja",
+          title,
+          kind,
+          filename,
+          content,
+        });
       }
     }
 
diff --git a/web/src/app/[locale]/(learn)/[version]/client.tsx b/web/src/app/[locale]/(learn)/[version]/client.tsx
index 83c7850aa..32adb97f7 100644
--- a/web/src/app/[locale]/(learn)/[version]/client.tsx
+++ b/web/src/app/[locale]/(learn)/[version]/client.tsx
@@ -1,5 +1,6 @@
 "use client";
 
+import Link from "next/link";
 import { ArchDiagram } from "@/components/architecture/arch-diagram";
 import { WhatsNew } from "@/components/diff/whats-new";
 import { DesignDecisions } from "@/components/architecture/design-decisions";
@@ -8,8 +9,23 @@ import { SourceViewer } from "@/components/code/source-viewer";
 import { AgentLoopSimulator } from "@/components/simulator/agent-loop-simulator";
 import { ExecutionFlow } from "@/components/architecture/execution-flow";
 import { SessionVisualization } from "@/components/visualizations";
+import { Card } from "@/components/ui/card";
 import { Tabs } from "@/components/ui/tabs";
-import { useTranslations } from "@/lib/i18n";
+import { useLocale, useTranslations } from "@/lib/i18n";
+
+interface GuideData {
+  focus: string;
+  confusion: string;
+  goal: string;
+}
+
+interface BridgeDoc {
+  slug: string;
+  kind: "map" | "mechanism";
+  title: string;
+  summary: Record<"zh" | "en" | "ja", string>;
+  fallbackLocale: string | null;
+}
 
 interface VersionDetailClientProps {
   version: string;
@@ -23,6 +39,9 @@ interface VersionDetailClientProps {
   } | null;
   source: string;
   filename: string;
+  guideData: GuideData | null;
+  bridgeDocs: BridgeDoc[];
+  locale: string;
 }
 
 export function VersionDetailClient({
@@ -30,53 +49,130 @@ export function VersionDetailClient({
   diff,
   source,
   filename,
+  guideData,
+  bridgeDocs,
+  locale: serverLocale,
 }: VersionDetailClientProps) {
   const t = useTranslations("version");
+  const locale = useLocale() || serverLocale;
 
   const tabs = [
     { id: "learn", label: t("tab_learn") },
-    { id: "simulate", label: t("tab_simulate") },
     { id: "code", label: t("tab_code") },
     { id: "deep-dive", label: t("tab_deep_dive") },
   ];
 
   return (
-    <div className="space-y-6">
-      {/* Hero Visualization */}
-      <SessionVisualization version={version} />
+    <Tabs tabs={tabs} defaultTab="learn">
+      {(activeTab) => (
+        <>
+          {activeTab === "learn" && <DocRenderer version={version} />}
 
-      {/* Tabbed content */}
-      <Tabs tabs={tabs} defaultTab="learn">
-        {(activeTab) => (
-          <>
-            {activeTab === "learn" && <DocRenderer version={version} />}
-            {activeTab === "simulate" && (
-              <AgentLoopSimulator version={version} />
-            )}
-            {activeTab === "code" && (
-              <SourceViewer source={source} filename={filename} />
-            )}
-            {activeTab === "deep-dive" && (
-              <div className="space-y-8">
-                <section>
-                  <h2 className="mb-4 text-xl font-semibold">
+          {activeTab === "code" && (
+            <SourceViewer source={source} filename={filename} />
+          )}
+
+          {activeTab === "deep-dive" && (
+            <div className="space-y-8">
+              {/* Interactive visualization */}
+              <SessionVisualization version={version} />
+
+              {/* Execution flow + Architecture side by side */}
+              <div className="grid grid-cols-1 gap-6 xl:grid-cols-2">
+                <section className="space-y-3">
+                  <h3 className="text-sm font-semibold uppercase tracking-wide text-zinc-500 dark:text-zinc-400">
                     {t("execution_flow")}
-                  </h2>
+                  </h3>
                   <ExecutionFlow version={version} />
                 </section>
-                <section>
-                  <h2 className="mb-4 text-xl font-semibold">
+                <section className="space-y-3">
+                  <h3 className="text-sm font-semibold uppercase tracking-wide text-zinc-500 dark:text-zinc-400">
                     {t("architecture")}
-                  </h2>
+                  </h3>
                   <ArchDiagram version={version} />
                 </section>
-                {diff && <WhatsNew diff={diff} />}
-                <DesignDecisions version={version} />
               </div>
-            )}
-          </>
-        )}
-      </Tabs>
-    </div>
+
+              {/* Simulator */}
+              <AgentLoopSimulator version={version} />
+
+              {/* Diff / Design decisions */}
+              {diff && <WhatsNew diff={diff} />}
+              <DesignDecisions version={version} />
+
+              {/* Guide cards */}
+              {guideData && (
+                <section className="grid grid-cols-1 gap-4 md:grid-cols-3">
+                  <Card className="border-emerald-200/70 bg-gradient-to-br from-emerald-50 via-white to-emerald-100/60 p-5 dark:border-emerald-900/70 dark:from-emerald-950/40 dark:via-zinc-950 dark:to-zinc-900">
+                    <p className="text-xs uppercase tracking-widest text-emerald-500/80 dark:text-emerald-300/70">
+                      {t("guide_focus_title")}
+                    </p>
+                    <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                      {guideData.focus}
+                    </p>
+                  </Card>
+                  <Card className="border-amber-200/70 bg-gradient-to-br from-amber-50 via-white to-amber-100/70 p-5 dark:border-amber-900/70 dark:from-amber-950/30 dark:via-zinc-950 dark:to-zinc-900">
+                    <p className="text-xs uppercase tracking-widest text-amber-500/80 dark:text-amber-300/70">
+                      {t("guide_confusion_title")}
+                    </p>
+                    <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                      {guideData.confusion}
+                    </p>
+                  </Card>
+                  <Card className="border-sky-200/70 bg-gradient-to-br from-sky-50 via-white to-sky-100/60 p-5 dark:border-sky-900/70 dark:from-sky-950/30 dark:via-zinc-950 dark:to-zinc-900">
+                    <p className="text-xs uppercase tracking-widest text-sky-500/80 dark:text-sky-300/70">
+                      {t("guide_goal_title")}
+                    </p>
+                    <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                      {guideData.goal}
+                    </p>
+                  </Card>
+                </section>
+              )}
+
+              {/* Bridge doc links */}
+              {bridgeDocs.length > 0 && (
+                <section className="space-y-3">
+                  <h3 className="text-sm font-semibold uppercase tracking-wide text-zinc-500 dark:text-zinc-400">
+                    {t("bridge_docs_title")}
+                  </h3>
+                  <p className="text-sm text-zinc-500 dark:text-zinc-400">
+                    {t("bridge_docs_intro")}
+                  </p>
+                  <div className="grid grid-cols-1 gap-3 sm:grid-cols-2">
+                    {bridgeDocs.map((doc) => (
+                      <Link
+                        key={doc.slug}
+                        href={`/${locale}/docs/${doc.slug}`}
+                        className="group rounded-xl border border-zinc-200/80 bg-white p-4 transition-colors hover:border-zinc-300 dark:border-zinc-800/80 dark:bg-zinc-900 dark:hover:border-zinc-700"
+                      >
+                        <div className="flex items-center gap-2">
+                          <span className="rounded-full border border-zinc-200 bg-zinc-50 px-2 py-0.5 text-[11px] font-medium text-zinc-600 dark:border-zinc-700 dark:bg-zinc-800 dark:text-zinc-300">
+                            {doc.kind === "map"
+                              ? t("bridge_docs_kind_map")
+                              : t("bridge_docs_kind_mechanism")}
+                          </span>
+                          {doc.fallbackLocale && (
+                            <span className="rounded-full border border-amber-200 bg-amber-50 px-2 py-0.5 text-[11px] font-medium text-amber-700 dark:border-amber-900/70 dark:bg-amber-950/30 dark:text-amber-300">
+                              {doc.fallbackLocale}
+                            </span>
+                          )}
+                        </div>
+                        <h4 className="mt-2 text-sm font-semibold text-zinc-900 dark:text-zinc-100">
+                          {doc.title}
+                        </h4>
+                        <p className="mt-1 text-xs leading-5 text-zinc-500 dark:text-zinc-400">
+                          {doc.summary[locale as "zh" | "en" | "ja"] ?? doc.summary.en}
+                        </p>
+                      </Link>
+                    ))}
+                  </div>
+                </section>
+              )}
+            </div>
+          )}
+        </>
+      )}
+    </Tabs>
   );
 }
diff --git a/web/src/app/[locale]/(learn)/[version]/diff/diff-content.tsx b/web/src/app/[locale]/(learn)/[version]/diff/diff-content.tsx
index d6e21011e..8c3fee0d1 100644
--- a/web/src/app/[locale]/(learn)/[version]/diff/diff-content.tsx
+++ b/web/src/app/[locale]/(learn)/[version]/diff/diff-content.tsx
@@ -2,8 +2,9 @@
 
 import { useMemo } from "react";
 import Link from "next/link";
-import { useLocale } from "@/lib/i18n";
+import { useLocale, useTranslations } from "@/lib/i18n";
 import { VERSION_META } from "@/lib/constants";
+import { getVersionContent } from "@/lib/version-content";
 import { Card, CardHeader, CardTitle } from "@/components/ui/card";
 import { LayerBadge } from "@/components/ui/badge";
 import { CodeDiff } from "@/components/diff/code-diff";
@@ -19,7 +20,9 @@ interface DiffPageContentProps {
 
 export function DiffPageContent({ version }: DiffPageContentProps) {
   const locale = useLocale();
+  const tSession = useTranslations("sessions");
   const meta = VERSION_META[version];
+  const content = getVersionContent(version, locale);
 
   const { currentVersion, prevVersion, diff } = useMemo(() => {
     const current = data.versions.find((v) => v.id === version);
@@ -48,9 +51,9 @@ export function DiffPageContent({ version }: DiffPageContentProps) {
           className="mb-6 inline-flex items-center gap-1 text-sm text-zinc-500 hover:text-zinc-700 dark:hover:text-zinc-300"
         >
           <ArrowLeft size={14} />
-          Back to {meta.title}
+          Back to {tSession(version) || meta.title}
         </Link>
-        <h1 className="text-3xl font-bold">{meta.title}</h1>
+        <h1 className="text-3xl font-bold">{tSession(version) || meta.title}</h1>
         <p className="mt-4 text-zinc-500">
           This is the first version -- there is no previous version to compare against.
         </p>
@@ -59,6 +62,9 @@ export function DiffPageContent({ version }: DiffPageContentProps) {
   }
 
   const prevMeta = VERSION_META[prevVersion.id];
+  const prevContent = getVersionContent(prevVersion.id, locale);
+  const currentTitle = tSession(version) || meta.title;
+  const prevTitle = tSession(prevVersion.id) || prevMeta?.title || prevVersion.id;
 
   return (
     <div className="py-4">
@@ -67,13 +73,13 @@ export function DiffPageContent({ version }: DiffPageContentProps) {
         className="mb-6 inline-flex items-center gap-1 text-sm text-zinc-500 hover:text-zinc-700 dark:hover:text-zinc-300"
       >
         <ArrowLeft size={14} />
-        Back to {meta.title}
+        Back to {currentTitle}
       </Link>
 
       {/* Header */}
       <div className="mb-8">
         <h1 className="text-3xl font-bold">
-          {prevMeta?.title || prevVersion.id} → {meta.title}
+          {prevTitle} → {currentTitle}
         </h1>
         <p className="mt-2 text-zinc-500 dark:text-zinc-400">
           {prevVersion.id} ({prevVersion.loc} LOC) → {version} ({currentVersion.loc} LOC)
@@ -165,8 +171,8 @@ export function DiffPageContent({ version }: DiffPageContentProps) {
       <div className="mb-8 grid grid-cols-1 gap-4 sm:grid-cols-2">
         <Card className="border-l-4 border-l-red-300 dark:border-l-red-700">
           <CardHeader>
-            <CardTitle>{prevMeta?.title || prevVersion.id}</CardTitle>
-            <p className="text-sm text-zinc-500">{prevMeta?.subtitle}</p>
+            <CardTitle>{prevTitle}</CardTitle>
+            <p className="text-sm text-zinc-500">{prevContent.subtitle}</p>
           </CardHeader>
           <div className="space-y-1 text-sm text-zinc-600 dark:text-zinc-400">
             <p>{prevVersion.loc} LOC</p>
@@ -176,8 +182,8 @@ export function DiffPageContent({ version }: DiffPageContentProps) {
         </Card>
         <Card className="border-l-4 border-l-green-300 dark:border-l-green-700">
           <CardHeader>
-            <CardTitle>{meta.title}</CardTitle>
-            <p className="text-sm text-zinc-500">{meta.subtitle}</p>
+            <CardTitle>{currentTitle}</CardTitle>
+            <p className="text-sm text-zinc-500">{content.subtitle}</p>
           </CardHeader>
           <div className="space-y-1 text-sm text-zinc-600 dark:text-zinc-400">
             <p>{currentVersion.loc} LOC</p>
diff --git a/web/src/app/[locale]/(learn)/[version]/page.tsx b/web/src/app/[locale]/(learn)/[version]/page.tsx
index 90c35a22b..bbf4a4831 100644
--- a/web/src/app/[locale]/(learn)/[version]/page.tsx
+++ b/web/src/app/[locale]/(learn)/[version]/page.tsx
@@ -2,8 +2,12 @@ import Link from "next/link";
 import { LEARNING_PATH, VERSION_META, LAYERS } from "@/lib/constants";
 import { LayerBadge } from "@/components/ui/badge";
 import versionsData from "@/data/generated/versions.json";
+import docsData from "@/data/generated/docs.json";
 import { VersionDetailClient } from "./client";
 import { getTranslations } from "@/lib/i18n-server";
+import { getChapterGuide } from "@/lib/chapter-guides";
+import { getBridgeDocDescriptors } from "@/lib/bridge-docs";
+import { getVersionContent } from "@/lib/version-content";
 
 export function generateStaticParams() {
   return LEARNING_PATH.map((version) => ({ version }));
@@ -18,6 +22,7 @@ export default async function VersionPage({
 
   const versionData = versionsData.versions.find((v) => v.id === version);
   const meta = VERSION_META[version];
+  const content = getVersionContent(version, locale);
   const diff = versionsData.diffs.find((d) => d.to === version) ?? null;
 
   if (!versionData || !meta) {
@@ -33,6 +38,66 @@ export default async function VersionPage({
   const tSession = getTranslations(locale, "sessions");
   const tLayer = getTranslations(locale, "layer_labels");
   const layer = LAYERS.find((l) => l.id === meta.layer);
+  const guide = getChapterGuide(version, locale);
+  const bridgeDocs = getBridgeDocDescriptors(
+    version as (typeof LEARNING_PATH)[number]
+  )
+    .map((descriptor) => {
+      const doc =
+        (docsData as Array<{
+          slug?: string;
+          locale?: string;
+          kind?: string;
+          title?: string;
+        }>).find(
+          (item) =>
+            item.slug === descriptor.slug &&
+            item.kind === "bridge" &&
+            item.locale === locale
+        ) ??
+        (docsData as Array<{
+          slug?: string;
+          locale?: string;
+          kind?: string;
+          title?: string;
+        }>).find(
+          (item) =>
+            item.slug === descriptor.slug &&
+            item.kind === "bridge" &&
+            item.locale === "zh"
+        ) ??
+        (docsData as Array<{
+          slug?: string;
+          locale?: string;
+          kind?: string;
+          title?: string;
+        }>).find(
+          (item) =>
+            item.slug === descriptor.slug &&
+            item.kind === "bridge" &&
+            item.locale === "en"
+        );
+
+      if (!doc?.slug || !doc.title) return null;
+
+      return {
+        ...descriptor,
+        title:
+          descriptor.title[locale as "zh" | "en" | "ja"] ?? descriptor.title.en,
+        fallbackLocale: doc.locale !== locale ? doc.locale : null,
+      };
+    })
+    .filter(
+      (
+        item
+      ): item is {
+        slug: string;
+        kind: "map" | "mechanism";
+        title: string;
+        summary: Record<"zh" | "en" | "ja", string>;
+        fallbackLocale: string | null;
+      } => Boolean(item)
+    );
 
   const pathIndex = LEARNING_PATH.indexOf(version as typeof LEARNING_PATH[number]);
   const prevVersion = pathIndex > 0 ? LEARNING_PATH[pathIndex - 1] : null;
@@ -42,9 +107,9 @@ export default async function VersionPage({
       : null;
 
   return (
-    <div className="mx-auto max-w-3xl space-y-10 py-4">
-      {/* Header */}
-      <header className="space-y-3">
+    <div className="mx-auto max-w-3xl space-y-6 py-4">
+      {/* Compact header: 3 lines */}
+      <header className="space-y-2">
         <div className="flex flex-wrap items-center gap-3">
           <span className="rounded-lg bg-zinc-100 px-3 py-1 font-mono text-lg font-bold dark:bg-zinc-800">
             {version}
@@ -54,31 +119,29 @@ export default async function VersionPage({
             <LayerBadge layer={meta.layer}>{tLayer(layer.id)}</LayerBadge>
           )}
         </div>
-        <p className="text-lg text-zinc-500 dark:text-zinc-400">
-          {meta.subtitle}
-        </p>
-        <div className="flex flex-wrap items-center gap-4 text-sm text-zinc-500 dark:text-zinc-400">
+        <p className="text-sm text-zinc-500 dark:text-zinc-400">
+          {content.subtitle}
+          <span className="mx-2 text-zinc-300 dark:text-zinc-600">|</span>
           <span className="font-mono">{versionData.loc} LOC</span>
+          <span className="mx-2 text-zinc-300 dark:text-zinc-600">|</span>
           <span>{versionData.tools.length} {t("tools")}</span>
-          {meta.coreAddition && (
-            <span className="rounded-full bg-zinc-100 px-2.5 py-0.5 text-xs dark:bg-zinc-800">
-              {meta.coreAddition}
-            </span>
-          )}
-        </div>
-        {meta.keyInsight && (
+        </p>
+        {content.keyInsight && (
           <blockquote className="border-l-4 border-zinc-300 pl-4 text-sm italic text-zinc-500 dark:border-zinc-600 dark:text-zinc-400">
-            {meta.keyInsight}
+            {content.keyInsight}
           </blockquote>
         )}
       </header>
 
-      {/* Client-rendered interactive sections */}
+      {/* Main content: client-rendered tabs (Learn / Code / Deep Dive) */}
       <VersionDetailClient
         version={version}
         diff={diff}
         source={versionData.source}
         filename={versionData.filename}
+        guideData={guide}
+        bridgeDocs={bridgeDocs}
+        locale={locale}
       />
 
       {/* Prev / Next navigation */}
diff --git a/web/src/app/[locale]/(learn)/compare/page.tsx b/web/src/app/[locale]/(learn)/compare/page.tsx
index a38a4204e..b048fe551 100644
--- a/web/src/app/[locale]/(learn)/compare/page.tsx
+++ b/web/src/app/[locale]/(learn)/compare/page.tsx
@@ -1,166 +1,495 @@
 "use client";
 
-import { useState, useMemo } from "react";
+import Link from "next/link";
+import { useMemo, useState } from "react";
 import { useLocale, useTranslations } from "@/lib/i18n";
-import { LEARNING_PATH, VERSION_META } from "@/lib/constants";
+import { LEARNING_PATH } from "@/lib/constants";
 import { Card, CardHeader, CardTitle } from "@/components/ui/card";
 import { LayerBadge } from "@/components/ui/badge";
 import { CodeDiff } from "@/components/diff/code-diff";
 import { ArchDiagram } from "@/components/architecture/arch-diagram";
-import { ArrowRight, FileCode, Wrench, Box, FunctionSquare } from "lucide-react";
-import type { VersionIndex } from "@/types/agent-data";
+import { ExecutionFlow } from "@/components/architecture/execution-flow";
+import { ArrowRight, FileCode, Layers3, Lightbulb, Sparkles, Wrench } from "lucide-react";
+import type { DocContent, VersionIndex } from "@/types/agent-data";
 import versionData from "@/data/generated/versions.json";
+import docsData from "@/data/generated/docs.json";
+import { getBridgeDocDescriptors } from "@/lib/bridge-docs";
+import { getChapterGuide } from "@/lib/chapter-guides";
 
 const data = versionData as VersionIndex;
+const docs = docsData as DocContent[];
+type RecommendedBridgeDoc = {
+  slug: string;
+  title: string;
+  summary: string;
+  fallbackLocale: DocContent["locale"] | null;
+};
+
+function extractLead(content?: string) {
+  if (!content) return "";
+  const match = content.match(/> \*([^*]+)\*/);
+  if (!match) return "";
+  return match[1].replace(/^"+|"+$/g, "").trim();
+}
+
+function pickText(
+  locale: string,
+  value: { zh: string; en: string; ja: string }
+) {
+  if (locale === "zh") return value.zh;
+  if (locale === "ja") return value.ja;
+  return value.en;
+}
+
+const COMPARE_EXTRA_TEXT = {
+  goal: {
+    zh: "学完 B 后",
+    en: "After B",
+    ja: "B を読み終えた後の到達点",
+  },
+  emptyGoal: {
+    zh: "该章节的学习目标暂未整理。",
+    en: "The learning goal for this chapter has not been filled in yet.",
+    ja: "この章の学習目標はまだ整理されていません。",
+  },
+  diagnosisLabel: {
+    zh: "跃迁诊断",
+    en: "Jump Diagnosis",
+    ja: "ジャンプ診断",
+  },
+  nextBestLabel: {
+    zh: "更稳的读法",
+    en: "Safer Reading Move",
+    ja: "より安定した読み方",
+  },
+  adjacentTitle: {
+    zh: "这是最稳的一步升级",
+    en: "This is the safest upgrade step",
+    ja: "これは最も安定した1段階の比較です",
+  },
+  adjacentBody: {
+    zh: "A 和 B 相邻，最适合看“系统刚刚多了一条什么分支、一个什么状态容器、为什么现在引入它”。",
+    en: "A and B are adjacent, so this is the cleanest way to see the exact new branch, state container, and reason for introducing it now.",
+    ja: "A と B は隣接しているため、何が新しい分岐で、何が新しい状態容器で、なぜ今入るのかを最も素直に見られます。",
+  },
+  adjacentNext: {
+    zh: "先看执行流，再看架构图，最后再决定要不要往下看源码 diff。",
+    en: "Read the execution flow first, then the architecture view, and only then decide whether you need the source diff.",
+    ja: "まず実行フロー、その後アーキテクチャ図を見て、最後に必要ならソース diff へ進みます。",
+  },
+  sameLayerTitle: {
+    zh: "这是同阶段内的跳读",
+    en: "This is a same-stage skip",
+    ja: "これは同一段階内の飛び読みです",
+  },
+  sameLayerBody: {
+    zh: "你仍然在同一个能力阶段里，但中间被跳过的章节往往刚好承担了“把概念拆开”的工作，所以阅读风险已经明显高于相邻章节对比。",
+    en: "You are still inside one stage, but the skipped chapters often carry the conceptual separation work, so the reading risk is already much higher than an adjacent comparison.",
+    ja: "同じ段階内ではありますが、飛ばした章が概念分離を担っていることが多く、隣接比較より理解リスクはかなり高くなります。",
+  },
+  sameLayerNext: {
+    zh: "如果开始读混，先回看 B 的前一章，再回桥接资料，而不是直接硬啃源码差异。",
+    en: "If things start to blur, revisit the chapter right before B and then the bridge docs before forcing the source diff.",
+    ja: "混ざり始めたら、まず B の直前の章と bridge doc に戻ってからソース diff を見ます。",
+  },
+  crossLayerTitle: {
+    zh: "这是一次跨阶段跃迁",
+    en: "This is a cross-stage jump",
+    ja: "これは段階をまたぐジャンプです",
+  },
+  crossLayerBody: {
+    zh: "跨阶段对比最大的风险，不是“功能更多了”，而是系统边界已经重画了。你需要先确认自己稳住了前一个阶段的目标，再去看 B。",
+    en: "The main risk in a cross-stage jump is not more features. It is that the system boundary has been redrawn. Make sure you actually hold the previous stage before reading B.",
+    ja: "段階またぎの最大リスクは機能量ではなく、システム境界そのものが描き直されていることです。B を読む前に前段階を本当に保持している必要があります。",
+  },
+  crossLayerNext: {
+    zh: "先补桥接文档，再用时间线确认阶段切换理由；如果还虚，就先比较 `B` 的前一章和 `B` 本章。",
+    en: "Start with the bridge docs, then use the timeline to confirm why the stage boundary changes here. If it still feels shaky, compare the chapter right before B with B first.",
+    ja: "先に bridge doc を見て、その後 timeline でなぜここで段階が切り替わるのかを確認します。まだ不安なら、まず B の直前章と B を比較します。",
+  },
+  bridgeNudge: {
+    zh: "这次跳跃前最值得先补的桥接资料",
+    en: "Bridge docs most worth reading before this jump",
+    ja: "このジャンプ前に最も先に補いたい bridge doc",
+  },
+  quickLabel: {
+    zh: "一键对比入口",
+    en: "One-Click Compare",
+    ja: "ワンクリック比較",
+  },
+  quickTitle: {
+    zh: "先用这些最稳的比较入口，不必每次手选两章",
+    en: "Start with these safe comparison moves instead of selecting two chapters every time",
+    ja: "毎回2章を手で選ぶ前に、まず安定した比較入口を使う",
+  },
+  quickBody: {
+    zh: "这些按钮优先覆盖最值得反复看的相邻升级和阶段切换，适合第一次理解章节边界，也适合读到一半开始混时快速重启。",
+    en: "These presets cover the most useful adjacent upgrades and stage boundaries. They work both for a first pass and for resetting when chapter boundaries start to blur.",
+    ja: "ここには最も見返す価値の高い隣接アップグレードと段階切り替えを置いてあります。初回読みにも、途中で境界が混ざった時の立て直しにも向いています。",
+  },
+  quickPrevious: {
+    zh: "直接改成 B 的前一章 -> B",
+    en: "Use B's Previous Chapter -> B",
+    ja: "B の直前章と B を比べる",
+  },
+  quickPreviousBody: {
+    zh: "如果现在这次跳跃太大，先退回 B 的前一章和 B 做相邻对比，会更容易看清这章真正新增了什么。",
+    en: "If the current jump is too large, compare the chapter right before B with B first. That is usually the clearest way to see what B really adds.",
+    ja: "今のジャンプが大きすぎるなら、まず B の直前章と B を比較すると、この章が本当に何を増やしたのかを最も見やすくなります。",
+  },
+} as const;
+
+const QUICK_COMPARE_PRESETS = [
+  { a: "s01", b: "s02" },
+  { a: "s06", b: "s07" },
+  { a: "s11", b: "s12" },
+  { a: "s14", b: "s15" },
+  { a: "s18", b: "s19" },
+] as const;
 
 export default function ComparePage() {
   const t = useTranslations("compare");
+  const tSession = useTranslations("sessions");
+  const tLayer = useTranslations("layer_labels");
   const locale = useLocale();
-  const [versionA, setVersionA] = useState<string>("");
-  const [versionB, setVersionB] = useState<string>("");
+  const [versionA, setVersionA] = useState<string>(QUICK_COMPARE_PRESETS[0].a);
+  const [versionB, setVersionB] = useState<string>(QUICK_COMPARE_PRESETS[0].b);
+
+  const previousOfB = useMemo(() => {
+    if (!versionB) return null;
+    const index = LEARNING_PATH.indexOf(versionB as (typeof LEARNING_PATH)[number]);
+    if (index <= 0) return null;
+    return LEARNING_PATH[index - 1];
+  }, [versionB]);
 
   const infoA = useMemo(() => data.versions.find((v) => v.id === versionA), [versionA]);
   const infoB = useMemo(() => data.versions.find((v) => v.id === versionB), [versionB]);
-  const metaA = versionA ? VERSION_META[versionA] : null;
-  const metaB = versionB ? VERSION_META[versionB] : null;
+
+  const docA = useMemo(
+    () => docs.find((doc) => doc.version === versionA && doc.locale === locale),
+    [locale, versionA]
+  );
+  const docB = useMemo(
+    () => docs.find((doc) => doc.version === versionB && doc.locale === locale),
+    [locale, versionB]
+  );
+
+  const leadA = useMemo(() => extractLead(docA?.content), [docA]);
+  const leadB = useMemo(() => extractLead(docB?.content), [docB]);
 
   const comparison = useMemo(() => {
     if (!infoA || !infoB) return null;
+
     const toolsA = new Set(infoA.tools);
     const toolsB = new Set(infoB.tools);
-    const onlyA = infoA.tools.filter((t) => !toolsB.has(t));
-    const onlyB = infoB.tools.filter((t) => !toolsA.has(t));
-    const shared = infoA.tools.filter((t) => toolsB.has(t));
-
-    const classesA = new Set(infoA.classes.map((c) => c.name));
-    const classesB = new Set(infoB.classes.map((c) => c.name));
-    const newClasses = infoB.classes.map((c) => c.name).filter((c) => !classesA.has(c));
-
-    const funcsA = new Set(infoA.functions.map((f) => f.name));
-    const funcsB = new Set(infoB.functions.map((f) => f.name));
-    const newFunctions = infoB.functions.map((f) => f.name).filter((f) => !funcsA.has(f));
 
     return {
+      toolsOnlyA: infoA.tools.filter((tool) => !toolsB.has(tool)),
+      toolsOnlyB: infoB.tools.filter((tool) => !toolsA.has(tool)),
+      toolsShared: infoA.tools.filter((tool) => toolsB.has(tool)),
+      newSurface: infoB.classes.filter((cls) => !infoA.classes.some((other) => other.name === cls.name)).length
+        + infoB.functions.filter((fn) => !infoA.functions.some((other) => other.name === fn.name)).length,
       locDelta: infoB.loc - infoA.loc,
-      toolsOnlyA: onlyA,
-      toolsOnlyB: onlyB,
-      toolsShared: shared,
-      newClasses,
-      newFunctions,
     };
   }, [infoA, infoB]);
 
+  const progression = useMemo(() => {
+    if (!infoA || !infoB) return "";
+
+    const indexA = LEARNING_PATH.indexOf(versionA as (typeof LEARNING_PATH)[number]);
+    const indexB = LEARNING_PATH.indexOf(versionB as (typeof LEARNING_PATH)[number]);
+
+    if (indexA === indexB) return t("progression_same_chapter");
+    if (indexB < indexA) return t("progression_reverse");
+    if (indexB === indexA + 1) return t("progression_direct");
+    if (infoA.layer === infoB.layer) return t("progression_same_layer");
+    return t("progression_cross_layer");
+  }, [infoA, infoB, t, versionA, versionB]);
+
+  const chapterDistance = useMemo(() => {
+    const indexA = LEARNING_PATH.indexOf(versionA as (typeof LEARNING_PATH)[number]);
+    const indexB = LEARNING_PATH.indexOf(versionB as (typeof LEARNING_PATH)[number]);
+    if (indexA < 0 || indexB < 0) return 0;
+    return Math.abs(indexB - indexA);
+  }, [versionA, versionB]);
+
+  const recommendedBridgeDocs = useMemo(() => {
+    if (!versionB) return [];
+
+    return getBridgeDocDescriptors(versionB as (typeof LEARNING_PATH)[number])
+      .map((descriptor) => {
+        const doc =
+          docs.find(
+            (item) =>
+              item.slug === descriptor.slug &&
+              item.kind === "bridge" &&
+              item.locale === locale
+          ) ??
+          docs.find(
+            (item) =>
+              item.slug === descriptor.slug &&
+              item.kind === "bridge" &&
+              item.locale === "zh"
+          ) ??
+          docs.find(
+            (item) =>
+              item.slug === descriptor.slug &&
+              item.kind === "bridge" &&
+              item.locale === "en"
+          );
+
+        if (!doc?.slug) return null;
+
+        return {
+          slug: doc.slug,
+          title: pickText(locale, descriptor.title),
+          summary: pickText(locale, descriptor.summary),
+          fallbackLocale: doc.locale !== locale ? doc.locale : null,
+        } satisfies RecommendedBridgeDoc;
+      })
+      .filter(
+        (item): item is RecommendedBridgeDoc => Boolean(item)
+      );
+  }, [locale, versionB]);
+
+  const guideB = useMemo(() => {
+    if (!versionB) return null;
+    return (
+      getChapterGuide(versionB as (typeof LEARNING_PATH)[number], locale) ??
+      getChapterGuide(versionB as (typeof LEARNING_PATH)[number], "en")
+    );
+  }, [locale, versionB]);
+
+  const jumpDiagnosis = useMemo(() => {
+    if (!infoA || !infoB) return null;
+
+    const crossLayer = infoA.layer !== infoB.layer;
+    if (chapterDistance <= 1) {
+      return {
+        title: pickText(locale, COMPARE_EXTRA_TEXT.adjacentTitle),
+        body: pickText(locale, COMPARE_EXTRA_TEXT.adjacentBody),
+        next: pickText(locale, COMPARE_EXTRA_TEXT.adjacentNext),
+      };
+    }
+
+    if (crossLayer) {
+      return {
+        title: pickText(locale, COMPARE_EXTRA_TEXT.crossLayerTitle),
+        body: pickText(locale, COMPARE_EXTRA_TEXT.crossLayerBody),
+        next: pickText(locale, COMPARE_EXTRA_TEXT.crossLayerNext),
+      };
+    }
+
+    return {
+      title: pickText(locale, COMPARE_EXTRA_TEXT.sameLayerTitle),
+      body: pickText(locale, COMPARE_EXTRA_TEXT.sameLayerBody),
+      next: pickText(locale, COMPARE_EXTRA_TEXT.sameLayerNext),
+    };
+  }, [chapterDistance, infoA, infoB, locale]);
+
   return (
-    <div className="py-4">
+    <div className="min-w-0 overflow-x-hidden py-4">
       <div className="mb-8">
         <h1 className="text-3xl font-bold">{t("title")}</h1>
-        <p className="mt-2 text-zinc-500 dark:text-zinc-400">{t("subtitle")}</p>
+        <p className="mt-2 max-w-3xl text-zinc-500 dark:text-zinc-400">{t("subtitle")}</p>
       </div>
 
-      {/* Selectors */}
-      <div className="mb-8 flex flex-col items-start gap-4 sm:flex-row sm:items-center">
-        <div className="flex-1">
-          <label className="mb-1 block text-sm font-medium text-zinc-600 dark:text-zinc-400">
-            {t("select_a")}
-          </label>
-          <select
-            value={versionA}
-            onChange={(e) => setVersionA(e.target.value)}
-            className="w-full rounded-lg border border-zinc-300 bg-white px-3 py-2 text-sm dark:border-zinc-600 dark:bg-zinc-800 dark:text-zinc-200"
-          >
-            <option value="">-- select --</option>
-            {LEARNING_PATH.map((v) => (
-              <option key={v} value={v}>
-                {v} - {VERSION_META[v]?.title}
-              </option>
-            ))}
-          </select>
+      <Card className="mb-8 overflow-hidden border-zinc-200/80 bg-[radial-gradient(circle_at_top_left,_rgba(14,165,233,0.12),_transparent_32%),radial-gradient(circle_at_bottom_right,_rgba(251,191,36,0.16),_transparent_34%),linear-gradient(135deg,_rgba(255,255,255,0.98),_rgba(250,250,250,0.98))] dark:border-zinc-800/80 dark:bg-[radial-gradient(circle_at_top_left,_rgba(14,165,233,0.16),_transparent_32%),radial-gradient(circle_at_bottom_right,_rgba(251,191,36,0.14),_transparent_34%),linear-gradient(135deg,_rgba(24,24,27,0.98),_rgba(10,10,10,0.98))]">
+        <CardHeader className="mb-6">
+          <p className="text-xs uppercase tracking-[0.22em] text-zinc-500 dark:text-zinc-400">
+            {t("learning_jump")}
+          </p>
+          <CardTitle className="text-xl sm:text-2xl">{t("selector_title")}</CardTitle>
+          <p className="mt-2 max-w-2xl text-sm text-zinc-600 dark:text-zinc-300">
+            {t("selector_note")}
+          </p>
+        </CardHeader>
+
+        <div className="flex flex-col items-start gap-4 sm:flex-row sm:items-center">
+          <div className="w-full flex-1">
+            <label className="mb-1 block text-sm font-medium text-zinc-700 dark:text-zinc-300">
+              {t("select_a")}
+            </label>
+            <select
+              value={versionA}
+              onChange={(e) => setVersionA(e.target.value)}
+              className="w-full rounded-xl border border-zinc-300/80 bg-white/80 px-3 py-2 text-sm text-zinc-900 shadow-sm outline-none transition focus:border-sky-400 dark:border-zinc-700 dark:bg-zinc-950/70 dark:text-zinc-100"
+            >
+              <option value="">{t("select_placeholder")}</option>
+              {LEARNING_PATH.map((version) => (
+                <option key={version} value={version}>
+                  {version} - {tSession(version)}
+                </option>
+              ))}
+            </select>
+          </div>
+
+          <div className="mt-5 hidden rounded-full border border-zinc-300/80 bg-white/70 p-2 text-zinc-500 shadow-sm sm:block dark:border-zinc-700 dark:bg-zinc-900/80 dark:text-zinc-300">
+            <ArrowRight size={18} />
+          </div>
+
+          <div className="w-full flex-1">
+            <label className="mb-1 block text-sm font-medium text-zinc-700 dark:text-zinc-300">
+              {t("select_b")}
+            </label>
+            <select
+              value={versionB}
+              onChange={(e) => setVersionB(e.target.value)}
+              className="w-full rounded-xl border border-zinc-300/80 bg-white/80 px-3 py-2 text-sm text-zinc-900 shadow-sm outline-none transition focus:border-amber-400 dark:border-zinc-700 dark:bg-zinc-950/70 dark:text-zinc-100"
+            >
+              <option value="">{t("select_placeholder")}</option>
+              {LEARNING_PATH.map((version) => (
+                <option key={version} value={version}>
+                  {version} - {tSession(version)}
+                </option>
+              ))}
+            </select>
+          </div>
         </div>
 
-        <ArrowRight size={20} className="mt-5 hidden text-zinc-400 sm:block" />
-
-        <div className="flex-1">
-          <label className="mb-1 block text-sm font-medium text-zinc-600 dark:text-zinc-400">
-            {t("select_b")}
-          </label>
-          <select
-            value={versionB}
-            onChange={(e) => setVersionB(e.target.value)}
-            className="w-full rounded-lg border border-zinc-300 bg-white px-3 py-2 text-sm dark:border-zinc-600 dark:bg-zinc-800 dark:text-zinc-200"
-          >
-            <option value="">-- select --</option>
-            {LEARNING_PATH.map((v) => (
-              <option key={v} value={v}>
-                {v} - {VERSION_META[v]?.title}
-              </option>
-            ))}
-          </select>
+        <div className="mt-6 space-y-4">
+          <div className="rounded-2xl border border-zinc-200/80 bg-white/70 p-4 dark:border-zinc-800/80 dark:bg-zinc-950/60">
+            <p className="text-xs uppercase tracking-[0.22em] text-zinc-400">
+              {pickText(locale, COMPARE_EXTRA_TEXT.quickLabel)}
+            </p>
+            <h2 className="mt-2 text-base font-semibold text-zinc-950 dark:text-zinc-50">
+              {pickText(locale, COMPARE_EXTRA_TEXT.quickTitle)}
+            </h2>
+            <p className="mt-2 max-w-3xl text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+              {pickText(locale, COMPARE_EXTRA_TEXT.quickBody)}
+            </p>
+
+            <div className="mt-4 flex flex-wrap gap-2">
+              {QUICK_COMPARE_PRESETS.map((preset) => (
+                <button
+                  key={`${preset.a}-${preset.b}`}
+                  type="button"
+                  onClick={() => {
+                    setVersionA(preset.a);
+                    setVersionB(preset.b);
+                  }}
+                  className="rounded-full border border-zinc-200 bg-white px-3 py-1.5 text-sm font-medium text-zinc-700 transition-colors hover:border-zinc-300 hover:text-zinc-950 dark:border-zinc-700 dark:bg-zinc-950 dark:text-zinc-300 dark:hover:border-zinc-600 dark:hover:text-zinc-50"
+                >
+                  {preset.a} {"->"} {preset.b}
+                </button>
+              ))}
+            </div>
+          </div>
+
+          {versionB && previousOfB && previousOfB !== versionA && (
+            <div className="rounded-2xl border border-amber-200/80 bg-amber-50/70 p-4 dark:border-amber-900/60 dark:bg-amber-950/20">
+              <p className="text-xs uppercase tracking-[0.22em] text-amber-600/80 dark:text-amber-300/80">
+                {pickText(locale, COMPARE_EXTRA_TEXT.quickLabel)}
+              </p>
+              <h2 className="mt-2 text-base font-semibold text-zinc-950 dark:text-zinc-50">
+                {pickText(locale, COMPARE_EXTRA_TEXT.quickPrevious)}
+              </h2>
+              <p className="mt-2 max-w-3xl text-sm leading-6 text-zinc-700 dark:text-zinc-300">
+                {pickText(locale, COMPARE_EXTRA_TEXT.quickPreviousBody)}
+              </p>
+              <div className="mt-4">
+                <button
+                  type="button"
+                  onClick={() => setVersionA(previousOfB)}
+                  className="rounded-full border border-amber-200 bg-white px-3 py-1.5 text-sm font-medium text-amber-800 transition-colors hover:border-amber-300 dark:border-amber-900/70 dark:bg-zinc-950 dark:text-amber-200 dark:hover:border-amber-800"
+                >
+                  {previousOfB} {"->"} {versionB}
+                </button>
+              </div>
+            </div>
+          )}
         </div>
-      </div>
+      </Card>
 
-      {/* Results */}
       {infoA && infoB && comparison && (
         <div className="space-y-8">
-          {/* Side-by-side version info */}
-          <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
-            <Card>
-              <CardHeader>
-                <CardTitle>{metaA?.title || versionA}</CardTitle>
-                <p className="text-sm text-zinc-500">{metaA?.subtitle}</p>
-              </CardHeader>
-              <div className="space-y-2 text-sm text-zinc-600 dark:text-zinc-400">
-                <p>{infoA.loc} LOC</p>
-                <p>{infoA.tools.length} tools</p>
-                {metaA && <LayerBadge layer={metaA.layer}>{metaA.layer}</LayerBadge>}
+          <Card className="overflow-hidden border-zinc-200/80 bg-[radial-gradient(circle_at_top_left,_rgba(16,185,129,0.14),_transparent_30%),radial-gradient(circle_at_bottom_right,_rgba(59,130,246,0.14),_transparent_36%),linear-gradient(160deg,_rgba(255,255,255,0.98),_rgba(244,244,245,0.98))] dark:border-zinc-800/80 dark:bg-[radial-gradient(circle_at_top_left,_rgba(16,185,129,0.16),_transparent_30%),radial-gradient(circle_at_bottom_right,_rgba(59,130,246,0.18),_transparent_36%),linear-gradient(160deg,_rgba(24,24,27,0.98),_rgba(10,10,10,0.98))]">
+            <CardHeader className="mb-6">
+              <p className="text-xs uppercase tracking-[0.22em] text-zinc-500 dark:text-zinc-400">
+                {t("learning_jump")}
+              </p>
+              <CardTitle className="flex flex-wrap items-center gap-3 text-2xl">
+                <span>{tSession(versionA)}</span>
+                <ArrowRight className="text-zinc-400" size={20} />
+                <span>{tSession(versionB)}</span>
+              </CardTitle>
+              <p className="mt-2 max-w-3xl text-sm text-zinc-600 dark:text-zinc-300">
+                {progression}
+              </p>
+            </CardHeader>
+
+            <div className="grid gap-4 xl:grid-cols-4">
+              <div className="rounded-2xl border border-white/70 bg-white/75 p-4 shadow-sm dark:border-zinc-800/80 dark:bg-zinc-900/70">
+                <div className="mb-2 flex items-center gap-2 text-sm font-medium text-zinc-700 dark:text-zinc-200">
+                  <Lightbulb size={16} />
+                  <span>{t("carry_from_a")}</span>
+                </div>
+                <p className="text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                  {leadA || t("empty_lead")}
+                </p>
               </div>
-            </Card>
-            <Card>
-              <CardHeader>
-                <CardTitle>{metaB?.title || versionB}</CardTitle>
-                <p className="text-sm text-zinc-500">{metaB?.subtitle}</p>
-              </CardHeader>
-              <div className="space-y-2 text-sm text-zinc-600 dark:text-zinc-400">
-                <p>{infoB.loc} LOC</p>
-                <p>{infoB.tools.length} tools</p>
-                {metaB && <LayerBadge layer={metaB.layer}>{metaB.layer}</LayerBadge>}
+
+              <div className="rounded-2xl border border-white/70 bg-white/75 p-4 shadow-sm dark:border-zinc-800/80 dark:bg-zinc-900/70">
+                <div className="mb-2 flex items-center gap-2 text-sm font-medium text-zinc-700 dark:text-zinc-200">
+                  <Sparkles size={16} />
+                  <span>{t("new_in_b")}</span>
+                </div>
+                <p className="text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                  {leadB || t("empty_lead")}
+                </p>
               </div>
-            </Card>
-          </div>
 
-          {/* Side-by-side Architecture Diagrams */}
-          <div>
-            <h2 className="mb-4 text-xl font-semibold">{t("architecture")}</h2>
-            <div className="grid grid-cols-1 gap-4 lg:grid-cols-2">
-              <div>
-                <h3 className="mb-3 text-sm font-medium text-zinc-500 dark:text-zinc-400">
-                  {metaA?.title || versionA}
-                </h3>
-                <ArchDiagram version={versionA} />
+              <div className="rounded-2xl border border-white/70 bg-white/75 p-4 shadow-sm dark:border-zinc-800/80 dark:bg-zinc-900/70">
+                <div className="mb-2 flex items-center gap-2 text-sm font-medium text-zinc-700 dark:text-zinc-200">
+                  <Layers3 size={16} />
+                  <span>{t("progression")}</span>
+                </div>
+                <p className="text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                  {progression}
+                </p>
               </div>
-              <div>
-                <h3 className="mb-3 text-sm font-medium text-zinc-500 dark:text-zinc-400">
-                  {metaB?.title || versionB}
-                </h3>
-                <ArchDiagram version={versionB} />
+
+              <div className="rounded-2xl border border-white/70 bg-white/75 p-4 shadow-sm dark:border-zinc-800/80 dark:bg-zinc-900/70">
+                <div className="mb-2 flex items-center gap-2 text-sm font-medium text-zinc-700 dark:text-zinc-200">
+                  <Wrench size={16} />
+                  <span>{pickText(locale, COMPARE_EXTRA_TEXT.goal)}</span>
+                </div>
+                <p className="text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                  {guideB?.goal ?? pickText(locale, COMPARE_EXTRA_TEXT.emptyGoal)}
+                </p>
               </div>
             </div>
+          </Card>
+
+          <div className="grid grid-cols-1 gap-4 xl:grid-cols-2">
+            {[{ version: versionA, info: infoA, lead: leadA }, { version: versionB, info: infoB, lead: leadB }].map(
+              ({ version, info, lead }) => (
+                <Card key={version}>
+                  <CardHeader>
+                    <CardTitle>{tSession(version)}</CardTitle>
+                    <p className="text-sm leading-6 text-zinc-500 dark:text-zinc-400">
+                      {lead || t("empty_lead")}
+                    </p>
+                  </CardHeader>
+                  <div className="flex flex-wrap items-center gap-3 text-sm text-zinc-600 dark:text-zinc-300">
+                    <span>{info.loc} LOC</span>
+                    <span>{info.tools.length} tools</span>
+                    <LayerBadge layer={info.layer}>{tLayer(info.layer)}</LayerBadge>
+                  </div>
+                </Card>
+              )
+            )}
           </div>
 
-          {/* Structural diff */}
-          <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">
+          <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 xl:grid-cols-4">
             <Card>
               <CardHeader>
                 <div className="flex items-center gap-2 text-zinc-500 dark:text-zinc-400">
-                  <FileCode size={16} />
-                  <span className="text-sm">{t("loc_delta")}</span>
+                  <Layers3 size={16} />
+                  <span className="text-sm">{t("chapter_distance")}</span>
                 </div>
               </CardHeader>
-              <CardTitle>
-                <span className={comparison.locDelta >= 0 ? "text-green-600 dark:text-green-400" : "text-red-600 dark:text-red-400"}>
-                  {comparison.locDelta >= 0 ? "+" : ""}{comparison.locDelta}
-                </span>
-                <span className="ml-2 text-sm font-normal text-zinc-500">{t("lines")}</span>
-              </CardTitle>
+              <CardTitle>{chapterDistance}</CardTitle>
             </Card>
 
             <Card>
@@ -170,64 +499,195 @@ export default function ComparePage() {
                   <span className="text-sm">{t("new_tools_in_b")}</span>
                 </div>
               </CardHeader>
-              <CardTitle>
-                <span className="text-blue-600 dark:text-blue-400">{comparison.toolsOnlyB.length}</span>
-              </CardTitle>
-              {comparison.toolsOnlyB.length > 0 && (
-                <div className="mt-2 flex flex-wrap gap-1">
-                  {comparison.toolsOnlyB.map((tool) => (
-                    <span key={tool} className="rounded bg-blue-100 px-1.5 py-0.5 text-xs text-blue-700 dark:bg-blue-900/30 dark:text-blue-300">
-                      {tool}
-                    </span>
-                  ))}
-                </div>
-              )}
+              <CardTitle>{comparison.toolsOnlyB.length}</CardTitle>
             </Card>
 
             <Card>
               <CardHeader>
                 <div className="flex items-center gap-2 text-zinc-500 dark:text-zinc-400">
-                  <Box size={16} />
-                  <span className="text-sm">{t("new_classes_in_b")}</span>
+                  <Wrench size={16} />
+                  <span className="text-sm">{t("shared_tools_count")}</span>
                 </div>
               </CardHeader>
-              <CardTitle>
-                <span className="text-purple-600 dark:text-purple-400">{comparison.newClasses.length}</span>
-              </CardTitle>
-              {comparison.newClasses.length > 0 && (
-                <div className="mt-2 flex flex-wrap gap-1">
-                  {comparison.newClasses.map((cls) => (
-                    <span key={cls} className="rounded bg-purple-100 px-1.5 py-0.5 text-xs text-purple-700 dark:bg-purple-900/30 dark:text-purple-300">
-                      {cls}
-                    </span>
-                  ))}
-                </div>
-              )}
+              <CardTitle>{comparison.toolsShared.length}</CardTitle>
             </Card>
 
             <Card>
               <CardHeader>
                 <div className="flex items-center gap-2 text-zinc-500 dark:text-zinc-400">
-                  <FunctionSquare size={16} />
-                  <span className="text-sm">{t("new_functions_in_b")}</span>
+                  <FileCode size={16} />
+                  <span className="text-sm">{t("new_surface")}</span>
                 </div>
               </CardHeader>
-              <CardTitle>
-                <span className="text-amber-600 dark:text-amber-400">{comparison.newFunctions.length}</span>
-              </CardTitle>
-              {comparison.newFunctions.length > 0 && (
-                <div className="mt-2 flex flex-wrap gap-1">
-                  {comparison.newFunctions.map((fn) => (
-                    <span key={fn} className="rounded bg-amber-100 px-1.5 py-0.5 text-xs text-amber-700 dark:bg-amber-900/30 dark:text-amber-300">
-                      {fn}
-                    </span>
-                  ))}
+              <CardTitle>{comparison.newSurface}</CardTitle>
+            </Card>
+          </div>
+
+          {jumpDiagnosis && (
+            <Card className="overflow-hidden border-zinc-200/80 bg-[linear-gradient(145deg,rgba(255,255,255,0.98),rgba(244,244,245,0.94))] dark:border-zinc-800/80 dark:bg-[linear-gradient(145deg,rgba(24,24,27,0.96),rgba(9,9,11,0.92))]">
+              <CardHeader>
+                <p className="text-xs uppercase tracking-[0.22em] text-zinc-500 dark:text-zinc-400">
+                  {pickText(locale, COMPARE_EXTRA_TEXT.diagnosisLabel)}
+                </p>
+                <CardTitle>{jumpDiagnosis.title}</CardTitle>
+                <p className="text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                  {jumpDiagnosis.body}
+                </p>
+              </CardHeader>
+
+              <div className="grid grid-cols-1 gap-4 px-6 pb-6 lg:grid-cols-[minmax(0,1fr)_minmax(0,0.9fr)]">
+                <div className="rounded-2xl border border-zinc-200/80 bg-white/85 p-4 dark:border-zinc-800/80 dark:bg-zinc-950/70">
+                  <p className="text-xs uppercase tracking-[0.18em] text-zinc-400">
+                    {pickText(locale, COMPARE_EXTRA_TEXT.nextBestLabel)}
+                  </p>
+                  <p className="mt-2 text-sm leading-6 text-zinc-700 dark:text-zinc-300">
+                    {jumpDiagnosis.next}
+                  </p>
+                </div>
+
+                <div className="rounded-2xl border border-zinc-200/80 bg-white/85 p-4 dark:border-zinc-800/80 dark:bg-zinc-950/70">
+                  <p className="text-xs uppercase tracking-[0.18em] text-zinc-400">
+                    {pickText(locale, COMPARE_EXTRA_TEXT.bridgeNudge)}
+                  </p>
+                  <div className="mt-3 flex flex-wrap gap-2">
+                    {recommendedBridgeDocs.slice(0, 3).map((doc) => (
+                      <Link
+                        key={doc.slug}
+                        href={`/${locale}/docs/${doc.slug}`}
+                        className="rounded-full border border-zinc-200 bg-zinc-50 px-3 py-1.5 text-sm text-zinc-700 transition-colors hover:border-zinc-300 hover:text-zinc-950 dark:border-zinc-700 dark:bg-zinc-900 dark:text-zinc-300 dark:hover:border-zinc-600 dark:hover:text-zinc-50"
+                      >
+                        {doc.title}
+                      </Link>
+                    ))}
+                    {recommendedBridgeDocs.length === 0 && (
+                      <p className="text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                        {t("empty_lead")}
+                      </p>
+                    )}
+                  </div>
                 </div>
-              )}
+              </div>
+            </Card>
+          )}
+
+          {recommendedBridgeDocs.length > 0 && (
+            <Card className="overflow-hidden border-zinc-200/80 bg-[linear-gradient(135deg,rgba(255,255,255,0.98),rgba(244,244,245,0.92))] dark:border-zinc-800/80 dark:bg-[linear-gradient(135deg,rgba(24,24,27,0.96),rgba(9,9,11,0.92))]">
+              <CardHeader>
+                <p className="text-xs uppercase tracking-[0.22em] text-zinc-500 dark:text-zinc-400">
+                  {pickText(locale, {
+                    zh: "跳读辅助",
+                    en: "Jump Reading Support",
+                    ja: "飛び読み補助",
+                  })}
+                </p>
+                <CardTitle>
+                  {pickText(locale, {
+                    zh: `从 ${tSession(versionA)} 跳到 ${tSession(versionB)} 前，先补这几张图`,
+                    en: `Before jumping from ${tSession(versionA)} to ${tSession(versionB)}, read these bridge docs`,
+                    ja: `${tSession(versionA)} から ${tSession(versionB)} へ飛ぶ前に、この橋渡し資料を読む`,
+                  })}
+                </CardTitle>
+                <p className="text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                  {pickText(locale, {
+                    zh: "对比页不只是告诉你“多了什么”，还应该告诉你为了消化这次跃迁，哪些结构地图和机制展开最值得先看。",
+                    en: "A good comparison page should not only show what was added. It should also point you to the best bridge docs for understanding the jump.",
+                    ja: "比較ページは「何が増えたか」だけでなく、そのジャンプを理解する前に何を補うべきかも示すべきです。",
+                  })}
+                </p>
+              </CardHeader>
+
+              <div className="grid grid-cols-1 gap-4 px-6 pb-6 md:grid-cols-2">
+                {recommendedBridgeDocs.map((doc) => (
+                  <Link
+                    key={doc.slug}
+                    href={`/${locale}/docs/${doc.slug}`}
+                    className="group rounded-2xl border border-zinc-200/80 bg-white/85 p-4 transition-colors hover:border-zinc-300 dark:border-zinc-800/80 dark:bg-zinc-950/75 dark:hover:border-zinc-700"
+                  >
+                    <div className="flex items-start justify-between gap-3">
+                      <div>
+                        <h3 className="text-sm font-semibold text-zinc-950 dark:text-zinc-50">
+                          {doc.title}
+                        </h3>
+                        <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                          {doc.summary}
+                        </p>
+                      </div>
+                      <ArrowRight
+                        size={16}
+                        className="mt-1 shrink-0 text-zinc-300 transition-colors group-hover:text-zinc-600 dark:text-zinc-600 dark:group-hover:text-zinc-300"
+                      />
+                    </div>
+                    {doc.fallbackLocale && (
+                      <p className="mt-3 text-xs text-amber-700 dark:text-amber-300">
+                        {pickText(locale, {
+                          zh: `当前语言缺稿，自动回退到 ${doc.fallbackLocale}`,
+                          en: `Missing in this locale, falling back to ${doc.fallbackLocale}`,
+                          ja: `この言語では未整備のため ${doc.fallbackLocale} へフォールバック`,
+                        })}
+                      </p>
+                    )}
+                  </Link>
+                ))}
+              </div>
             </Card>
+          )}
+
+          <div>
+            <div className="mb-4">
+              <h2 className="text-xl font-semibold">
+                {pickText(locale, {
+                  zh: "主线执行对比",
+                  en: "Mainline Flow Comparison",
+                  ja: "主線実行の比較",
+                })}
+              </h2>
+              <p className="mt-1 text-sm text-zinc-500 dark:text-zinc-400">
+                {pickText(locale, {
+                  zh: "先看一条请求在两章之间是怎么变的：新的分支出现在哪里，哪些结果会回流到主循环，哪些部分只是侧车或外部车道。",
+                  en: "Compare how one request evolves between the two chapters: where the new branch appears, what writes back into the loop, and what remains a side lane.",
+                  ja: "1つの要求が2つの章の間でどう変わるかを先に見ます。どこで新しい分岐が生まれ、何が主ループへ戻り、何が側車レーンに残るのかを比較します。",
+                })}
+              </p>
+            </div>
+            <div className="grid grid-cols-1 gap-4 lg:grid-cols-2">
+              <div>
+                <h3 className="mb-3 text-sm font-medium text-zinc-500 dark:text-zinc-400">
+                  {tSession(versionA)}
+                </h3>
+                <ExecutionFlow version={versionA} />
+              </div>
+              <div>
+                <h3 className="mb-3 text-sm font-medium text-zinc-500 dark:text-zinc-400">
+                  {tSession(versionB)}
+                </h3>
+                <ExecutionFlow version={versionB} />
+              </div>
+            </div>
+          </div>
+
+          <div>
+            <div className="mb-4">
+              <h2 className="text-xl font-semibold">{t("architecture")}</h2>
+              <p className="mt-1 text-sm text-zinc-500 dark:text-zinc-400">
+                {t("architecture_note")}
+              </p>
+            </div>
+            <div className="grid grid-cols-1 gap-4 lg:grid-cols-2">
+              <div>
+                <h3 className="mb-3 text-sm font-medium text-zinc-500 dark:text-zinc-400">
+                  {tSession(versionA)}
+                </h3>
+                <ArchDiagram version={versionA} />
+              </div>
+              <div>
+                <h3 className="mb-3 text-sm font-medium text-zinc-500 dark:text-zinc-400">
+                  {tSession(versionB)}
+                </h3>
+                <ArchDiagram version={versionB} />
+              </div>
+            </div>
           </div>
 
-          {/* Tool comparison */}
           <Card>
             <CardHeader>
               <CardTitle>{t("tool_comparison")}</CardTitle>
@@ -235,20 +695,21 @@ export default function ComparePage() {
             <div className="grid grid-cols-1 gap-6 sm:grid-cols-3">
               <div>
                 <h4 className="mb-2 text-sm font-medium text-zinc-600 dark:text-zinc-400">
-                  {t("only_in")} {metaA?.title || versionA}
+                  {t("only_in")} {tSession(versionA)}
                 </h4>
                 {comparison.toolsOnlyA.length === 0 ? (
                   <p className="text-xs text-zinc-400">{t("none")}</p>
                 ) : (
                   <div className="flex flex-wrap gap-1">
                     {comparison.toolsOnlyA.map((tool) => (
-                      <span key={tool} className="rounded bg-red-100 px-1.5 py-0.5 text-xs text-red-700 dark:bg-red-900/30 dark:text-red-300">
+                      <span key={tool} className="rounded bg-rose-100 px-1.5 py-0.5 text-xs text-rose-700 dark:bg-rose-900/30 dark:text-rose-300">
                         {tool}
                       </span>
                     ))}
                   </div>
                 )}
               </div>
+
               <div>
                 <h4 className="mb-2 text-sm font-medium text-zinc-600 dark:text-zinc-400">
                   {t("shared")}
@@ -265,16 +726,17 @@ export default function ComparePage() {
                   </div>
                 )}
               </div>
+
               <div>
                 <h4 className="mb-2 text-sm font-medium text-zinc-600 dark:text-zinc-400">
-                  {t("only_in")} {metaB?.title || versionB}
+                  {t("only_in")} {tSession(versionB)}
                 </h4>
                 {comparison.toolsOnlyB.length === 0 ? (
                   <p className="text-xs text-zinc-400">{t("none")}</p>
                 ) : (
                   <div className="flex flex-wrap gap-1">
                     {comparison.toolsOnlyB.map((tool) => (
-                      <span key={tool} className="rounded bg-green-100 px-1.5 py-0.5 text-xs text-green-700 dark:bg-green-900/30 dark:text-green-300">
+                      <span key={tool} className="rounded bg-emerald-100 px-1.5 py-0.5 text-xs text-emerald-700 dark:bg-emerald-900/30 dark:text-emerald-300">
                         {tool}
                       </span>
                     ))}
@@ -284,9 +746,18 @@ export default function ComparePage() {
             </div>
           </Card>
 
-          {/* Code Diff */}
           <div>
-            <h2 className="mb-4 text-xl font-semibold">{t("source_diff")}</h2>
+            <div className="mb-4">
+              <h2 className="text-xl font-semibold">{t("source_diff")}</h2>
+              <p className="mt-1 text-sm text-zinc-500 dark:text-zinc-400">
+                {t("source_diff_note")} {t("loc_delta")}:{" "}
+                <span className={comparison.locDelta >= 0 ? "text-emerald-600 dark:text-emerald-400" : "text-rose-600 dark:text-rose-400"}>
+                  {comparison.locDelta >= 0 ? "+" : ""}
+                  {comparison.locDelta}
+                </span>{" "}
+                {t("lines")}
+              </p>
+            </div>
             <CodeDiff
               oldSource={infoA.source}
               newSource={infoB.source}
@@ -297,9 +768,8 @@ export default function ComparePage() {
         </div>
       )}
 
-      {/* Empty state */}
       {(!versionA || !versionB) && (
-        <div className="rounded-lg border border-dashed border-zinc-300 p-12 text-center dark:border-zinc-700">
+        <div className="rounded-2xl border border-dashed border-zinc-300 bg-zinc-50/60 p-12 text-center dark:border-zinc-700 dark:bg-zinc-900/40">
           <p className="text-zinc-400">{t("empty_hint")}</p>
         </div>
       )}
diff --git a/web/src/app/[locale]/(learn)/docs/[slug]/page.tsx b/web/src/app/[locale]/(learn)/docs/[slug]/page.tsx
new file mode 100644
index 000000000..0424a2e00
--- /dev/null
+++ b/web/src/app/[locale]/(learn)/docs/[slug]/page.tsx
@@ -0,0 +1,170 @@
+import Link from "next/link";
+import docsData from "@/data/generated/docs.json";
+import { DocRenderer } from "@/components/docs/doc-renderer";
+import { getTranslations } from "@/lib/i18n-server";
+import { BRIDGE_DOCS, getChaptersForBridgeDoc } from "@/lib/bridge-docs";
+
+const SUPPORTED_LOCALES = ["en", "zh", "ja"] as const;
+
+function findBridgeDoc(locale: string, slug: string) {
+  return (
+    (docsData as Array<{
+      slug?: string;
+      locale?: string;
+      kind?: string;
+      title?: string;
+    }>).find(
+      (item) => item.kind === "bridge" && item.slug === slug && item.locale === locale
+    ) ??
+    (docsData as Array<{
+      slug?: string;
+      locale?: string;
+      kind?: string;
+      title?: string;
+    }>).find(
+      (item) => item.kind === "bridge" && item.slug === slug && item.locale === "zh"
+    ) ??
+    (docsData as Array<{
+      slug?: string;
+      locale?: string;
+      kind?: string;
+      title?: string;
+    }>).find(
+      (item) => item.kind === "bridge" && item.slug === slug && item.locale === "en"
+    )
+  );
+}
+
+export function generateStaticParams() {
+  const slugs = Array.from(
+    new Set(
+      (docsData as Array<{ kind?: string; slug?: string }>)
+        .filter((doc) => doc.kind === "bridge" && doc.slug)
+        .map((doc) => doc.slug as string)
+    )
+  );
+
+  return SUPPORTED_LOCALES.flatMap((locale) =>
+    slugs.map((slug) => ({ locale, slug }))
+  );
+}
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ locale: string; slug: string }>;
+}) {
+  const { locale, slug } = await params;
+  const descriptor = BRIDGE_DOCS[slug];
+  const doc = findBridgeDoc(locale, slug);
+  const title =
+    descriptor?.title?.[locale as "en" | "zh" | "ja"] ??
+    descriptor?.title?.en ??
+    doc?.title ??
+    "Learn Claude Code";
+  const description =
+    descriptor?.summary?.[locale as "en" | "zh" | "ja"] ??
+    descriptor?.summary?.en ??
+    undefined;
+
+  return {
+    title,
+    description,
+  };
+}
+
+export default async function BridgeDocPage({
+  params,
+}: {
+  params: Promise<{ locale: string; slug: string }>;
+}) {
+  const { locale, slug } = await params;
+  const t = getTranslations(locale, "version");
+  const tSession = getTranslations(locale, "sessions");
+  const descriptor = BRIDGE_DOCS[slug];
+  const doc = findBridgeDoc(locale, slug);
+  const relatedVersions = getChaptersForBridgeDoc(slug);
+
+  if (!doc?.title) {
+    return (
+      <div className="py-20 text-center">
+        <h1 className="text-2xl font-bold">Document not found</h1>
+        <p className="mt-2 text-zinc-500">{slug}</p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="mx-auto max-w-3xl space-y-8 py-4">
+      <header className="space-y-3">
+        <Link
+          href={`/${locale}`}
+          className="inline-flex items-center gap-2 text-sm text-zinc-500 transition-colors hover:text-zinc-900 dark:hover:text-zinc-50"
+        >
+          <span>&larr;</span>
+          <span>{t("bridge_docs_back")}</span>
+        </Link>
+        <div className="space-y-2">
+          <span className="inline-flex rounded-full border border-zinc-200 bg-zinc-50 px-3 py-1 text-xs font-medium text-zinc-600 dark:border-zinc-700 dark:bg-zinc-900 dark:text-zinc-300">
+            {t("bridge_docs_standalone")}
+          </span>
+          <h1 className="text-3xl font-bold tracking-tight text-zinc-950 dark:text-zinc-50">
+            {descriptor?.title?.[locale as "en" | "zh" | "ja"] ??
+              descriptor?.title?.en ??
+              doc.title}
+          </h1>
+          {doc.locale !== locale && (
+            <p className="text-sm text-zinc-500 dark:text-zinc-400">
+              {t("bridge_docs_fallback_note")} {doc.locale}
+            </p>
+          )}
+        </div>
+      </header>
+
+      <section className="rounded-[28px] border border-zinc-200/80 bg-[linear-gradient(135deg,rgba(255,255,255,0.98),rgba(244,244,245,0.92))] px-5 py-6 shadow-sm dark:border-zinc-800/80 dark:bg-[linear-gradient(135deg,rgba(24,24,27,0.96),rgba(9,9,11,0.92))] sm:px-6">
+        <div className="space-y-4">
+          <div>
+            <p className="text-xs uppercase tracking-[0.22em] text-zinc-400">
+              {locale === "zh"
+                ? "这页适合什么时候回看"
+                : locale === "ja"
+                  ? "このページへ戻るべき場面"
+                  : "When This Page Helps"}
+            </p>
+            <p className="mt-3 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+              {descriptor?.summary?.[locale as "en" | "zh" | "ja"] ??
+                descriptor?.summary?.en}
+            </p>
+          </div>
+
+          {relatedVersions.length > 0 && (
+            <div>
+              <p className="text-xs uppercase tracking-[0.22em] text-zinc-400">
+                {locale === "zh"
+                  ? "最适合和这些章节一起读"
+                  : locale === "ja"
+                    ? "いっしょに読むと効く章"
+                    : "Best Read Alongside"}
+              </p>
+              <div className="mt-3 flex flex-wrap gap-2">
+                {relatedVersions.map((version) => (
+                  <Link
+                    key={version}
+                    href={`/${locale}/${version}`}
+                    className="rounded-full border border-zinc-200 bg-white px-3 py-1.5 text-sm text-zinc-700 transition-colors hover:border-zinc-300 hover:text-zinc-950 dark:border-zinc-700 dark:bg-zinc-950 dark:text-zinc-300 dark:hover:border-zinc-600 dark:hover:text-zinc-50"
+                  >
+                    {version} · {tSession(version)}
+                  </Link>
+                ))}
+              </div>
+            </div>
+          )}
+        </div>
+      </section>
+
+      <section className="rounded-[28px] border border-zinc-200/80 bg-white/90 px-5 py-6 shadow-sm dark:border-zinc-800/80 dark:bg-zinc-950/80 sm:px-6">
+        <DocRenderer slug={slug} />
+      </section>
+    </div>
+  );
+}
diff --git a/web/src/app/[locale]/(learn)/layers/page.tsx b/web/src/app/[locale]/(learn)/layers/page.tsx
index ceeee9245..4f4be0874 100644
--- a/web/src/app/[locale]/(learn)/layers/page.tsx
+++ b/web/src/app/[locale]/(learn)/layers/page.tsx
@@ -3,34 +3,257 @@
 import Link from "next/link";
 import { useTranslations, useLocale } from "@/lib/i18n";
 import { LAYERS, VERSION_META } from "@/lib/constants";
-import { Card, CardHeader, CardTitle } from "@/components/ui/card";
+import { getVersionContent } from "@/lib/version-content";
+import { Card } from "@/components/ui/card";
 import { LayerBadge } from "@/components/ui/badge";
 import { cn } from "@/lib/utils";
 import { ChevronRight } from "lucide-react";
 import type { VersionIndex } from "@/types/agent-data";
 import versionData from "@/data/generated/versions.json";
+import docsData from "@/data/generated/docs.json";
+import { BRIDGE_DOCS } from "@/lib/bridge-docs";
+import { getStageCheckpoint } from "@/lib/stage-checkpoints";
 
 const data = versionData as VersionIndex;
 
+const docs = docsData as Array<{
+  slug?: string;
+  locale?: string;
+  kind?: string;
+  title?: string;
+}>;
+
 const LAYER_BORDER_CLASSES: Record<string, string> = {
-  tools: "border-l-blue-500",
-  planning: "border-l-emerald-500",
-  memory: "border-l-purple-500",
-  concurrency: "border-l-amber-500",
-  collaboration: "border-l-red-500",
+  core: "border-l-blue-500",
+  hardening: "border-l-emerald-500",
+  runtime: "border-l-amber-500",
+  platform: "border-l-red-500",
 };
 
 const LAYER_HEADER_BG: Record<string, string> = {
-  tools: "bg-blue-500",
-  planning: "bg-emerald-500",
-  memory: "bg-purple-500",
-  concurrency: "bg-amber-500",
-  collaboration: "bg-red-500",
+  core: "bg-blue-500",
+  hardening: "bg-emerald-500",
+  runtime: "bg-amber-500",
+  platform: "bg-red-500",
+};
+
+const LAYER_CHECKPOINT_SHELL: Record<string, string> = {
+  core: "border-blue-200/80 bg-blue-50/80 dark:border-blue-900/60 dark:bg-blue-950/20",
+  hardening:
+    "border-emerald-200/80 bg-emerald-50/80 dark:border-emerald-900/60 dark:bg-emerald-950/20",
+  runtime: "border-amber-200/80 bg-amber-50/80 dark:border-amber-900/60 dark:bg-amber-950/20",
+  platform: "border-red-200/80 bg-red-50/80 dark:border-red-900/60 dark:bg-red-950/20",
 };
 
+const RUNTIME_SUPPORT_DOCS = [
+  "s13a-runtime-task-model",
+  "data-structures",
+  "entity-map",
+] as const;
+
+const CORE_SUPPORT_DOCS = [
+  "s00-architecture-overview",
+  "s00b-one-request-lifecycle",
+  "s02a-tool-control-plane",
+  "data-structures",
+] as const;
+
+const HARDENING_SUPPORT_DOCS = [
+  "s00a-query-control-plane",
+  "s02b-tool-execution-runtime",
+  "s10a-message-prompt-pipeline",
+  "s00c-query-transition-model",
+  "data-structures",
+] as const;
+
+const PLATFORM_SUPPORT_DOCS = [
+  "team-task-lane-model",
+  "s13a-runtime-task-model",
+  "s19a-mcp-capability-layers",
+  "entity-map",
+  "data-structures",
+] as const;
+
+type SupportDocCard = {
+  slug: string;
+  title: string;
+  summary: string;
+  fallbackLocale: typeof docs[number]["locale"] | null;
+};
+
+type SupportSection = {
+  id: "core" | "hardening" | "runtime" | "platform";
+  eyebrow: string;
+  title: string;
+  body: string;
+  docs: SupportDocCard[];
+};
+
+function pickText(
+  locale: string,
+  value: { zh: string; en: string; ja: string }
+) {
+  if (locale === "zh") return value.zh;
+  if (locale === "ja") return value.ja;
+  return value.en;
+}
+
+const LAYER_CHECKPOINT_TEXT = {
+  label: {
+    zh: "阶段收口提醒",
+    en: "Stage Stop Reminder",
+    ja: "段階の収束ポイント",
+  },
+  body: {
+    zh: "这一层不是读完最后一章就立刻往后冲。更稳的顺序是：先从入口重新走一遍，自己手搓到收口，再进入下一层。",
+    en: "Do not sprint past the last chapter of this layer. The steadier order is: reopen the entry point, rebuild the layer by hand, then enter the next one.",
+    ja: "この層の最後の章を読んだら、そのまま先へ走るのではありません。入口へ戻り、この層を自分で作り直してから次へ進む方が安定します。",
+  },
+  rebuild: {
+    zh: "这一层现在应该能自己做出的东西",
+    en: "What You Should Now Be Able To Rebuild",
+    ja: "この層で今なら自分で作り直せるべきもの",
+  },
+  entry: {
+    zh: "阶段入口",
+    en: "Stage Entry",
+    ja: "段階の入口",
+  },
+  exit: {
+    zh: "阶段收口",
+    en: "Stage Exit",
+    ja: "段階の収束章",
+  },
+} as const;
+
 export default function LayersPage() {
   const t = useTranslations("layers");
+  const tSession = useTranslations("sessions");
+  const tLayer = useTranslations("layer_labels");
   const locale = useLocale();
+  const resolveSupportDocs = (slugs: readonly string[]) =>
+    slugs
+      .map((slug) => {
+        const descriptor = BRIDGE_DOCS[slug];
+        if (!descriptor) return null;
+
+        const doc =
+          docs.find(
+            (item) =>
+              item.slug === slug &&
+              item.kind === "bridge" &&
+              item.locale === locale
+          ) ??
+          docs.find(
+            (item) =>
+              item.slug === slug &&
+              item.kind === "bridge" &&
+              item.locale === "zh"
+          ) ??
+          docs.find(
+            (item) =>
+              item.slug === slug &&
+              item.kind === "bridge" &&
+              item.locale === "en"
+          );
+
+        if (!doc?.slug) return null;
+
+        return {
+          slug: doc.slug,
+          title: pickText(locale, descriptor.title),
+          summary: pickText(locale, descriptor.summary),
+          fallbackLocale: doc.locale !== locale ? doc.locale : null,
+        } satisfies SupportDocCard;
+      })
+      .filter((item): item is SupportDocCard => Boolean(item));
+
+  const coreSupportDocs = resolveSupportDocs(CORE_SUPPORT_DOCS);
+  const hardeningSupportDocs = resolveSupportDocs(HARDENING_SUPPORT_DOCS);
+  const runtimeSupportDocs = resolveSupportDocs(RUNTIME_SUPPORT_DOCS);
+  const platformSupportDocs = resolveSupportDocs(PLATFORM_SUPPORT_DOCS);
+  const supportSections = [
+    {
+      id: "core",
+      eyebrow: pickText(locale, {
+        zh: "核心闭环补课",
+        en: "Core Loop Support Docs",
+        ja: "基礎ループ補助資料",
+      }),
+      title: pickText(locale, {
+        zh: "读 `s01-s06` 时，先把主闭环、工具入口和数据结构边界守住",
+        en: "Before reading `s01-s06`, hold the main loop, tool entry path, and data-structure boundaries steady",
+        ja: "`s01-s06` を読む前に、主ループ・tool 入口・データ構造境界を先に安定させる",
+      }),
+      body: pickText(locale, {
+        zh: "前六章最容易被低估的，不是某个功能点，而是这条最小闭环到底怎样成立：用户输入怎么进入、工具结果怎么回写、状态容器到底有哪些。",
+        en: "The first six chapters are not mainly about isolated features. They are about how the minimal loop truly forms: how user input enters, how tool results write back, and which state containers exist.",
+        ja: "最初の6章で大事なのは個別機能ではなく、最小ループがどう成立するかです。ユーザー入力がどう入り、ツール結果がどう戻り、どんな状態容器があるかを先に押さえます。",
+      }),
+      docs: coreSupportDocs,
+    },
+    {
+      id: "hardening",
+      eyebrow: pickText(locale, {
+        zh: "系统加固补课",
+        en: "Hardening Support Docs",
+        ja: "強化段階補助資料",
+      }),
+      title: pickText(locale, {
+        zh: "读 `s07-s11` 时，先把控制面、输入装配和续行原因这几层拆开",
+        en: "Before reading `s07-s11`, separate the control plane, input assembly, and continuation reasons",
+        ja: "`s07-s11` を読む前に、制御面・入力組み立て・継続理由を分けておく",
+      }),
+      body: pickText(locale, {
+        zh: "加固阶段最容易混的，不是权限、hook、memory 哪个更复杂，而是这些机制都在“控制系统如何继续推进”这一层相遇了。",
+        en: "The hardening stage gets confusing not because one feature is harder than another, but because permissions, hooks, memory, prompts, and recovery all meet at the control plane.",
+        ja: "強化段階で混ざりやすいのは個別機能の難しさではなく、権限・hook・memory・prompt・recovery がすべて制御面で交わる点です。",
+      }),
+      docs: hardeningSupportDocs,
+    },
+    {
+      id: "runtime",
+      eyebrow: pickText(locale, {
+        zh: "运行时补课",
+        en: "Runtime Support Docs",
+        ja: "実行段階補助資料",
+      }),
+      title: pickText(locale, {
+        zh: "读 `s12-s14` 时，先把目标、执行槽位和定时触发这三层分清",
+        en: "Before reading `s12-s14`, separate goals, execution slots, and schedule triggers",
+        ja: "`s12-s14` を読む前に、goal・execution slot・schedule trigger を分けておく",
+      }),
+      body: pickText(locale, {
+        zh: "任务运行时最容易让人混的，不是某个函数，而是 task、runtime task、notification、schedule 这几层对象同时出现时，各自到底管什么。",
+        en: "The runtime chapters get confusing not because of one function, but because task goals, runtime tasks, notifications, and schedules begin to coexist and need clean boundaries.",
+        ja: "実行段階で難しくなるのは個別関数ではなく、作業目標・実行タスク・通知・スケジュールが同時に現れ、それぞれの境界を保つ必要がある点です。",
+      }),
+      docs: runtimeSupportDocs,
+    },
+    {
+      id: "platform",
+      eyebrow: pickText(locale, {
+        zh: "平台层补课",
+        en: "Platform Support Docs",
+        ja: "プラットフォーム補助資料",
+      }),
+      title: pickText(locale, {
+        zh: "读 `s15-s19` 之前，先把这几份桥接资料放在手边",
+        en: "Keep these bridge docs nearby before reading `s15-s19`",
+        ja: "`s15-s19` を読む前に、まずこの橋渡し資料を手元に置く",
+      }),
+      body: pickText(locale, {
+        zh: "后五章最容易混的是队友、协议请求、任务、运行时槽位、worktree 车道，以及最后接进来的外部能力层。这几份文档就是专门用来反复校正这段心智模型的。",
+        en: "The last five chapters are where teammates, protocol requests, tasks, runtime slots, worktree lanes, and finally external capability layers start to blur together. These bridge docs are meant to keep that model clean.",
+        ja: "最後の5章では、チームメイト・プロトコル要求・タスク・実行スロット・worktree レーン、そして最後に入ってくる外部能力層の境界が混ざりやすくなります。ここに並べた資料は、その学習モデルを何度でも補正するためのものです。",
+      }),
+      docs: platformSupportDocs,
+    },
+  ] satisfies SupportSection[];
+
+  const visibleSupportSections = supportSections.filter(
+    (section) => section.docs.length > 0
+  );
 
   return (
     <div className="py-4">
@@ -39,13 +262,90 @@ export default function LayersPage() {
         <p className="mt-2 text-zinc-500 dark:text-zinc-400">{t("subtitle")}</p>
       </div>
 
+      <div className="mb-8 grid grid-cols-1 gap-4 lg:grid-cols-3">
+        <Card className="border-zinc-200/80 bg-zinc-50/70 dark:border-zinc-800/80 dark:bg-zinc-900/60">
+          <p className="text-xs uppercase tracking-[0.22em] text-zinc-400">{t("guide_label")}</p>
+          <h2 className="mt-3 text-base font-semibold">{t("guide_start_title")}</h2>
+          <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+            {t("guide_start_desc")}
+          </p>
+        </Card>
+        <Card className="border-zinc-200/80 bg-zinc-50/70 dark:border-zinc-800/80 dark:bg-zinc-900/60">
+          <p className="text-xs uppercase tracking-[0.22em] text-zinc-400">{t("guide_label")}</p>
+          <h2 className="mt-3 text-base font-semibold">{t("guide_middle_title")}</h2>
+          <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+            {t("guide_middle_desc")}
+          </p>
+        </Card>
+        <Card className="border-zinc-200/80 bg-zinc-50/70 dark:border-zinc-800/80 dark:bg-zinc-900/60">
+          <p className="text-xs uppercase tracking-[0.22em] text-zinc-400">{t("guide_label")}</p>
+          <h2 className="mt-3 text-base font-semibold">{t("guide_finish_title")}</h2>
+          <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+            {t("guide_finish_desc")}
+          </p>
+        </Card>
+      </div>
+
+      {visibleSupportSections.map((section) => (
+        <section
+          key={section.id}
+          className="mb-10 rounded-[28px] border border-zinc-200/80 bg-[linear-gradient(135deg,rgba(255,255,255,0.98),rgba(244,244,245,0.92))] p-5 shadow-sm dark:border-zinc-800/80 dark:bg-[linear-gradient(135deg,rgba(24,24,27,0.96),rgba(9,9,11,0.92))] sm:p-6"
+        >
+          <div className="max-w-2xl">
+            <p className="text-xs uppercase tracking-[0.22em] text-zinc-400">
+              {section.eyebrow}
+            </p>
+            <h2 className="mt-3 text-xl font-semibold tracking-tight text-zinc-950 dark:text-zinc-50">
+              {section.title}
+            </h2>
+            <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+              {section.body}
+            </p>
+          </div>
+
+          <div className="mt-5 grid grid-cols-1 gap-4 md:grid-cols-2">
+            {section.docs.map((doc) => (
+              <Link key={doc.slug} href={`/${locale}/docs/${doc.slug}`} className="group">
+                <Card className="h-full border-zinc-200/80 bg-white/90 transition-colors hover:border-zinc-300 dark:border-zinc-800/80 dark:bg-zinc-950/80 dark:hover:border-zinc-700">
+                  <div className="flex items-start justify-between gap-3">
+                    <div>
+                      <h3 className="text-base font-semibold text-zinc-950 dark:text-zinc-50">
+                        {doc.title}
+                      </h3>
+                      <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                        {doc.summary}
+                      </p>
+                    </div>
+                    <ChevronRight
+                      size={16}
+                      className="mt-1 shrink-0 text-zinc-300 transition-colors group-hover:text-zinc-600 dark:text-zinc-600 dark:group-hover:text-zinc-300"
+                    />
+                  </div>
+                  {doc.fallbackLocale && (
+                    <p className="mt-3 text-xs text-amber-700 dark:text-amber-300">
+                      {pickText(locale, {
+                        zh: `当前语言缺稿，自动回退到 ${doc.fallbackLocale}`,
+                        en: `Missing in this locale, falling back to ${doc.fallbackLocale}`,
+                        ja: `この言語では未整備のため ${doc.fallbackLocale} へフォールバック`,
+                      })}
+                    </p>
+                  )}
+                </Card>
+              </Link>
+            ))}
+          </div>
+        </section>
+      ))}
+
       <div className="space-y-6">
         {LAYERS.map((layer, index) => {
           const versionInfos = layer.versions.map((vId) => {
             const info = data.versions.find((v) => v.id === vId);
             const meta = VERSION_META[vId];
-            return { id: vId, info, meta };
+            const content = getVersionContent(vId, locale);
+            return { id: vId, info, meta, content };
           });
+          const checkpoint = getStageCheckpoint(layer.id);
 
           return (
             <div
@@ -61,38 +361,90 @@ export default function LayersPage() {
                 <div className={cn("h-3 w-3 rounded-full", LAYER_HEADER_BG[layer.id])} />
                 <div>
                   <h2 className="text-xl font-bold">
-                    <span className="text-zinc-400 dark:text-zinc-600">L{index + 1}</span>
+                    <span className="text-zinc-400 dark:text-zinc-600">P{index + 1}</span>
                     {" "}
-                    {layer.label}
+                    {tLayer(layer.id)}
                   </h2>
                   <p className="mt-1 text-sm text-zinc-500 dark:text-zinc-400">
                     {t(layer.id)}
                   </p>
+                  <p className="mt-2 text-sm font-medium text-zinc-700 dark:text-zinc-200">
+                    {t(`${layer.id}_outcome`)}
+                  </p>
                 </div>
               </div>
 
               {/* Version cards within this layer */}
               <div className="border-t border-zinc-200 bg-zinc-50/50 px-6 py-4 dark:border-zinc-800 dark:bg-zinc-900/50">
+                {checkpoint && (
+                  <div
+                    className={cn(
+                      "mb-4 rounded-2xl border p-4",
+                      LAYER_CHECKPOINT_SHELL[layer.id]
+                    )}
+                  >
+                    <div className="flex flex-col gap-4 lg:flex-row lg:items-start lg:justify-between">
+                      <div className="max-w-2xl">
+                        <p className="text-xs uppercase tracking-[0.22em] text-zinc-500 dark:text-zinc-400">
+                          {pickText(locale, LAYER_CHECKPOINT_TEXT.label)}
+                        </p>
+                        <h3 className="mt-2 text-base font-semibold text-zinc-950 dark:text-zinc-50">
+                          {pickText(locale, checkpoint.title)}
+                        </h3>
+                        <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                          {pickText(locale, LAYER_CHECKPOINT_TEXT.body)}
+                        </p>
+                      </div>
+
+                      <div className="grid gap-2 text-sm sm:grid-cols-2 lg:min-w-[240px] lg:grid-cols-1">
+                        <Link
+                          href={`/${locale}/${checkpoint.entryVersion}`}
+                          className="rounded-xl border border-white/70 bg-white/80 px-3 py-2 text-zinc-700 transition-colors hover:border-zinc-300 hover:text-zinc-950 dark:border-zinc-900/60 dark:bg-zinc-950/60 dark:text-zinc-200 dark:hover:border-zinc-700 dark:hover:text-white"
+                        >
+                          <span className="block text-xs uppercase tracking-[0.18em] text-zinc-400">
+                            {pickText(locale, LAYER_CHECKPOINT_TEXT.entry)}
+                          </span>
+                          <span className="mt-1 block font-mono">{checkpoint.entryVersion}</span>
+                        </Link>
+                        <Link
+                          href={`/${locale}/${checkpoint.endVersion}`}
+                          className="rounded-xl border border-white/70 bg-white/80 px-3 py-2 text-zinc-700 transition-colors hover:border-zinc-300 hover:text-zinc-950 dark:border-zinc-900/60 dark:bg-zinc-950/60 dark:text-zinc-200 dark:hover:border-zinc-700 dark:hover:text-white"
+                        >
+                          <span className="block text-xs uppercase tracking-[0.18em] text-zinc-400">
+                            {pickText(locale, LAYER_CHECKPOINT_TEXT.exit)}
+                          </span>
+                          <span className="mt-1 block font-mono">{checkpoint.endVersion}</span>
+                        </Link>
+                      </div>
+                    </div>
+
+                    <div className="mt-4 rounded-xl border border-white/70 bg-white/70 p-4 dark:border-zinc-900/60 dark:bg-zinc-950/50">
+                      <p className="text-xs uppercase tracking-[0.18em] text-zinc-400">
+                        {pickText(locale, LAYER_CHECKPOINT_TEXT.rebuild)}
+                      </p>
+                      <p className="mt-2 text-sm leading-6 text-zinc-700 dark:text-zinc-200">
+                        {pickText(locale, checkpoint.rebuild)}
+                      </p>
+                    </div>
+                  </div>
+                )}
+
                 <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
-                  {versionInfos.map(({ id, info, meta }) => (
-                    <Link
-                      key={id}
-                      href={`/${locale}/${id}`}
-                      className="group"
-                    >
+                  {versionInfos.map(({ id, info, meta, content }) => (
+                    <Link key={id} href={`/${locale}/${id}`} className="group">
                       <Card className="transition-shadow hover:shadow-md">
                         <div className="flex items-start justify-between">
                           <div className="min-w-0 flex-1">
                             <div className="flex items-center gap-2">
                               <span className="text-xs font-mono text-zinc-400">{id}</span>
-                              <LayerBadge layer={layer.id}>{layer.id}</LayerBadge>
+                              <LayerBadge layer={layer.id}>{tLayer(layer.id)}</LayerBadge>
                             </div>
                             <h3 className="mt-1 font-semibold text-zinc-900 dark:text-zinc-100">
-                              {meta?.title || id}
+                              {tSession(id) || meta?.title || id}
                             </h3>
-                            {meta?.subtitle && (
+                            {meta && (
                               <p className="mt-0.5 text-xs text-zinc-500 dark:text-zinc-400">
-                                {meta.subtitle}
+                                {content.subtitle}
                               </p>
                             )}
                           </div>
@@ -105,9 +457,9 @@ export default function LayersPage() {
                           <span>{info?.loc ?? "?"} LOC</span>
                           <span>{info?.tools.length ?? "?"} tools</span>
                         </div>
-                        {meta?.keyInsight && (
+                        {meta && (
                           <p className="mt-2 text-xs leading-relaxed text-zinc-500 dark:text-zinc-400 line-clamp-2">
-                            {meta.keyInsight}
+                            {content.keyInsight}
                           </p>
                         )}
                       </Card>
diff --git a/web/src/app/[locale]/(learn)/reference/page.tsx b/web/src/app/[locale]/(learn)/reference/page.tsx
new file mode 100644
index 000000000..a7a3ae814
--- /dev/null
+++ b/web/src/app/[locale]/(learn)/reference/page.tsx
@@ -0,0 +1,79 @@
+"use client";
+
+import Link from "next/link";
+import { useTranslations, useLocale } from "@/lib/i18n";
+import {
+  BRIDGE_DOCS,
+  FOUNDATION_DOC_SLUGS,
+  MECHANISM_DOC_SLUGS,
+} from "@/lib/bridge-docs";
+
+type SupportedLocale = "zh" | "en" | "ja";
+
+export default function ReferencePage() {
+  const t = useTranslations("reference");
+  const locale = useLocale() as SupportedLocale;
+
+  const foundationDocs = FOUNDATION_DOC_SLUGS.map(
+    (slug) => BRIDGE_DOCS[slug]
+  ).filter(Boolean);
+
+  const mechanismDocs = MECHANISM_DOC_SLUGS.map(
+    (slug) => BRIDGE_DOCS[slug]
+  ).filter(Boolean);
+
+  return (
+    <div className="space-y-10">
+      <header>
+        <h1 className="text-3xl font-bold tracking-tight">{t("title")}</h1>
+        <p className="mt-2 text-zinc-500 dark:text-zinc-400">
+          {t("subtitle")}
+        </p>
+      </header>
+
+      <section>
+        <h2 className="mb-4 text-xl font-semibold">
+          {t("foundation_title")}
+        </h2>
+        <div className="grid gap-4 sm:grid-cols-2">
+          {foundationDocs.map((doc) => (
+            <Link
+              key={doc.slug}
+              href={`/${locale}/docs/${doc.slug}`}
+              className="group rounded-lg border border-[var(--color-border)] p-4 transition-colors hover:border-zinc-400 dark:hover:border-zinc-500"
+            >
+              <h3 className="font-medium group-hover:text-zinc-900 dark:group-hover:text-white">
+                {doc.title[locale] ?? doc.title.en}
+              </h3>
+              <p className="mt-1 text-sm text-zinc-500 dark:text-zinc-400">
+                {doc.summary[locale] ?? doc.summary.en}
+              </p>
+            </Link>
+          ))}
+        </div>
+      </section>
+
+      <section>
+        <h2 className="mb-4 text-xl font-semibold">
+          {t("deep_dive_title")}
+        </h2>
+        <div className="grid gap-4 sm:grid-cols-2">
+          {mechanismDocs.map((doc) => (
+            <Link
+              key={doc.slug}
+              href={`/${locale}/docs/${doc.slug}`}
+              className="group rounded-lg border border-[var(--color-border)] p-4 transition-colors hover:border-zinc-400 dark:hover:border-zinc-500"
+            >
+              <h3 className="font-medium group-hover:text-zinc-900 dark:group-hover:text-white">
+                {doc.title[locale] ?? doc.title.en}
+              </h3>
+              <p className="mt-1 text-sm text-zinc-500 dark:text-zinc-400">
+                {doc.summary[locale] ?? doc.summary.en}
+              </p>
+            </Link>
+          ))}
+        </div>
+      </section>
+    </div>
+  );
+}
diff --git a/web/src/app/[locale]/(learn)/timeline/page.tsx b/web/src/app/[locale]/(learn)/timeline/page.tsx
index a490002be..a426b8018 100644
--- a/web/src/app/[locale]/(learn)/timeline/page.tsx
+++ b/web/src/app/[locale]/(learn)/timeline/page.tsx
@@ -1,10 +1,132 @@
 "use client";
 
+import Link from "next/link";
 import { useTranslations } from "@/lib/i18n";
+import { useLocale } from "@/lib/i18n";
 import { Timeline } from "@/components/timeline/timeline";
+import { Card } from "@/components/ui/card";
+import { LayerBadge } from "@/components/ui/badge";
+import { STAGE_CHECKPOINTS } from "@/lib/stage-checkpoints";
+
+const GUIDE_TEXT = {
+  label: {
+    zh: "怎么使用这页",
+    en: "How to Use This Page",
+    ja: "このページの使い方",
+  },
+  cards: [
+    {
+      title: {
+        zh: "第一次完整读",
+        en: "First Full Pass",
+        ja: "初回の通読",
+      },
+      body: {
+        zh: "从上往下顺序读，不要急着横跳。前六章是主闭环，后面都建立在它上面。",
+        en: "Read top to bottom before jumping around. The first six chapters establish the main loop everything else depends on.",
+        ja: "まずは上から順に読む。最初の6章が主ループで、後半はその上に積まれています。",
+      },
+    },
+    {
+      title: {
+        zh: "中途开始混",
+        en: "If Things Start to Blur",
+        ja: "途中で混ざり始めたら",
+      },
+      body: {
+        zh: "不要死盯源码。先看这章落在哪个阶段，再回桥接资料校正 task、runtime、teammate、worktree 这些边界。",
+        en: "Do not stare at code first. Identify the stage, then use bridge docs to reset boundaries like task, runtime, teammate, and worktree.",
+        ja: "先にコードへ潜らず、この章がどの段階に属するかを見て、bridge doc で task・runtime・teammate・worktree の境界を補正します。",
+      },
+    },
+    {
+      title: {
+        zh: "准备自己实现",
+        en: "If You Are Rebuilding It",
+        ja: "自分で実装するなら",
+      },
+      body: {
+        zh: "每走完一个阶段，就停下来自己手写一版最小实现。不要等到 s19 再一次性回头补。",
+        en: "After each stage, stop and rebuild the minimal version yourself instead of waiting until s19 to backfill everything at once.",
+        ja: "各段階が終わるたびに最小版を自分で書き直す。一気に s19 まで進んでからまとめて補わない。",
+      },
+    },
+  ],
+  supportLabel: {
+    zh: "全程可反复回看的桥接资料",
+    en: "Bridge Docs Worth Re-reading",
+    ja: "何度も戻る価値のある橋渡し資料",
+  },
+  supportBody: {
+    zh: "如果你读到中后段开始打结，先回这些资料，而不是硬闯下一章。",
+    en: "When the middle and late chapters start to tangle, revisit these before forcing the next chapter.",
+    ja: "中盤以降で混線し始めたら、次の章へ突っ込む前にまずここへ戻ります。",
+  },
+  checkpointLabel: {
+    zh: "时间线不仅告诉你顺序，也告诉你哪里该停",
+    en: "The timeline shows both order and where to pause",
+    ja: "このタイムラインは順序だけでなく、どこで止まるべきかも示す",
+  },
+  checkpointTitle: {
+    zh: "每走完一个阶段，先自己重建一版，再进入下一阶段",
+    en: "After each stage, rebuild one working slice before entering the next stage",
+    ja: "各段階のあとで 1 回作り直してから次の段階へ入る",
+  },
+  checkpointBody: {
+    zh: "如果你只是一路往下读，章节边界迟早会糊。最稳的读法是在 `s06 / s11 / s14 / s19` 各停一次，确认自己真的能把该阶段已经成立的系统重新写出来。",
+    en: "If you only keep scrolling downward, chapter boundaries will eventually blur. The safer reading move is to pause at `s06 / s11 / s14 / s19` and confirm that you can rebuild the working system slice for that stage.",
+    ja: "ただ下へ読み進めるだけだと、章境界はいつか必ずぼやけます。`s06 / s11 / s14 / s19` で止まり、その段階で成立した system slice を作り直せるか確認する方が安定します。",
+  },
+  checkpointRebuild: {
+    zh: "此时该能手搓出来的东西",
+    en: "What You Should Be Able To Rebuild Here",
+    ja: "この時点で作り直せるべきもの",
+  },
+  checkpointOpen: {
+    zh: "打开阶段收口",
+    en: "Open Stage Exit",
+    ja: "段階の収束点を開く",
+  },
+  links: [
+    {
+      slug: "s00a-query-control-plane",
+      title: { zh: "查询控制平面", en: "Query Control Plane", ja: "クエリ制御プレーン" },
+    },
+    {
+      slug: "s02b-tool-execution-runtime",
+      title: { zh: "工具执行运行时", en: "Tool Execution Runtime", ja: "ツール実行ランタイム" },
+    },
+    {
+      slug: "s13a-runtime-task-model",
+      title: { zh: "运行时任务模型", en: "Runtime Task Model", ja: "ランタイムタスクモデル" },
+    },
+    {
+      slug: "team-task-lane-model",
+      title: { zh: "队友-任务-车道模型", en: "Team Task Lane Model", ja: "チームメイト・タスク・レーンモデル" },
+    },
+    {
+      slug: "s19a-mcp-capability-layers",
+      title: { zh: "MCP 能力层地图", en: "MCP Capability Layers", ja: "MCP 能力層マップ" },
+    },
+  ],
+} as const;
+
+function pick(
+  locale: string,
+  value: {
+    zh: string;
+    en: string;
+    ja: string;
+  }
+) {
+  if (locale === "zh") return value.zh;
+  if (locale === "ja") return value.ja;
+  return value.en;
+}
 
 export default function TimelinePage() {
   const t = useTranslations("timeline");
+  const locale = useLocale();
 
   return (
     <div>
@@ -14,6 +136,96 @@ export default function TimelinePage() {
           {t("subtitle")}
         </p>
       </div>
+
+      <section className="mb-10 space-y-5">
+        <div>
+          <p className="text-xs uppercase tracking-[0.22em] text-zinc-400">
+            {pick(locale, GUIDE_TEXT.label)}
+          </p>
+        </div>
+        <div className="grid grid-cols-1 gap-4 lg:grid-cols-3">
+          {GUIDE_TEXT.cards.map((card) => (
+            <div
+              key={card.title.en}
+              className="rounded-2xl border border-zinc-200/80 bg-zinc-50/70 p-5 dark:border-zinc-800/80 dark:bg-zinc-900/60"
+            >
+              <h2 className="text-base font-semibold">
+                {pick(locale, card.title)}
+              </h2>
+              <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                {pick(locale, card.body)}
+              </p>
+            </div>
+          ))}
+        </div>
+
+        <div className="rounded-[24px] border border-zinc-200/80 bg-[linear-gradient(135deg,rgba(255,255,255,0.98),rgba(244,244,245,0.92))] p-5 dark:border-zinc-800/80 dark:bg-[linear-gradient(135deg,rgba(24,24,27,0.96),rgba(9,9,11,0.92))]">
+          <h2 className="text-base font-semibold">
+            {pick(locale, GUIDE_TEXT.supportLabel)}
+          </h2>
+          <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+            {pick(locale, GUIDE_TEXT.supportBody)}
+          </p>
+          <div className="mt-4 flex flex-wrap gap-2">
+            {GUIDE_TEXT.links.map((link) => (
+              <Link
+                key={link.slug}
+                href={`/${locale}/docs/${link.slug}`}
+                className="rounded-full border border-zinc-200 bg-white px-3 py-1.5 text-sm text-zinc-700 transition-colors hover:border-zinc-300 hover:text-zinc-950 dark:border-zinc-700 dark:bg-zinc-950 dark:text-zinc-300 dark:hover:border-zinc-600 dark:hover:text-zinc-50"
+              >
+                {pick(locale, link.title)}
+              </Link>
+            ))}
+          </div>
+        </div>
+      </section>
+
+      <section className="mb-10 rounded-[28px] border border-zinc-200/80 bg-[linear-gradient(135deg,rgba(255,255,255,0.98),rgba(244,244,245,0.92))] p-5 dark:border-zinc-800/80 dark:bg-[linear-gradient(135deg,rgba(24,24,27,0.96),rgba(9,9,11,0.92))] sm:p-6">
+        <div className="max-w-3xl">
+          <p className="text-xs uppercase tracking-[0.22em] text-zinc-400">
+            {pick(locale, GUIDE_TEXT.checkpointLabel)}
+          </p>
+          <h2 className="mt-3 text-xl font-semibold tracking-tight text-zinc-950 dark:text-zinc-50">
+            {pick(locale, GUIDE_TEXT.checkpointTitle)}
+          </h2>
+          <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+            {pick(locale, GUIDE_TEXT.checkpointBody)}
+          </p>
+        </div>
+
+        <div className="mt-5 grid grid-cols-1 gap-4 lg:grid-cols-2">
+          {STAGE_CHECKPOINTS.map((checkpoint) => (
+            <Card
+              key={checkpoint.layer}
+              className="border-zinc-200/80 bg-white/90 dark:border-zinc-800/80 dark:bg-zinc-950/75"
+            >
+              <div className="flex flex-wrap items-center gap-2">
+                <LayerBadge layer={checkpoint.layer}>{checkpoint.entryVersion}-{checkpoint.endVersion}</LayerBadge>
+              </div>
+              <h3 className="mt-4 text-base font-semibold text-zinc-950 dark:text-zinc-50">
+                {pick(locale, checkpoint.title)}
+              </h3>
+              <div className="mt-4 rounded-2xl border border-zinc-200/80 bg-zinc-50/70 p-4 dark:border-zinc-800/80 dark:bg-zinc-900/60">
+                <p className="text-xs uppercase tracking-[0.18em] text-zinc-400">
+                  {pick(locale, GUIDE_TEXT.checkpointRebuild)}
+                </p>
+                <p className="mt-2 text-sm leading-6 text-zinc-700 dark:text-zinc-300">
+                  {pick(locale, checkpoint.rebuild)}
+                </p>
+              </div>
+              <div className="mt-4">
+                <Link
+                  href={`/${locale}/${checkpoint.endVersion}`}
+                  className="inline-flex rounded-full border border-zinc-200 bg-white px-3 py-1.5 text-sm font-medium text-zinc-700 transition-colors hover:border-zinc-300 hover:text-zinc-950 dark:border-zinc-700 dark:bg-zinc-950 dark:text-zinc-300 dark:hover:border-zinc-600 dark:hover:text-zinc-50"
+                >
+                  {pick(locale, GUIDE_TEXT.checkpointOpen)}: {checkpoint.endVersion}
+                </Link>
+              </div>
+            </Card>
+          ))}
+        </div>
+      </section>
+
       <Timeline />
     </div>
   );
diff --git a/web/src/app/[locale]/page.tsx b/web/src/app/[locale]/page.tsx
index 686d95615..aaaf0e18b 100644
--- a/web/src/app/[locale]/page.tsx
+++ b/web/src/app/[locale]/page.tsx
@@ -3,48 +3,25 @@
 import Link from "next/link";
 import { useTranslations, useLocale } from "@/lib/i18n";
 import { LEARNING_PATH, VERSION_META, LAYERS } from "@/lib/constants";
-import { LayerBadge } from "@/components/ui/badge";
-import { Card } from "@/components/ui/card";
-import { cn } from "@/lib/utils";
-import versionsData from "@/data/generated/versions.json";
-import { MessageFlow } from "@/components/architecture/message-flow";
+import { getVersionContent } from "@/lib/version-content";
 
 const LAYER_DOT_COLORS: Record<string, string> = {
-  tools: "bg-blue-500",
-  planning: "bg-emerald-500",
-  memory: "bg-purple-500",
-  concurrency: "bg-amber-500",
-  collaboration: "bg-red-500",
+  core: "bg-blue-500",
+  hardening: "bg-emerald-500",
+  runtime: "bg-amber-500",
+  platform: "bg-red-500",
 };
 
-const LAYER_BORDER_COLORS: Record<string, string> = {
-  tools: "border-blue-500/30 hover:border-blue-500/60",
-  planning: "border-emerald-500/30 hover:border-emerald-500/60",
-  memory: "border-purple-500/30 hover:border-purple-500/60",
-  concurrency: "border-amber-500/30 hover:border-amber-500/60",
-  collaboration: "border-red-500/30 hover:border-red-500/60",
-};
-
-const LAYER_BAR_COLORS: Record<string, string> = {
-  tools: "bg-blue-500",
-  planning: "bg-emerald-500",
-  memory: "bg-purple-500",
-  concurrency: "bg-amber-500",
-  collaboration: "bg-red-500",
-};
-
-function getVersionData(id: string) {
-  return versionsData.versions.find((v) => v.id === id);
-}
-
 export default function HomePage() {
   const t = useTranslations("home");
+  const tSession = useTranslations("sessions");
+  const tLayer = useTranslations("layer_labels");
   const locale = useLocale();
 
   return (
-    <div className="flex flex-col gap-20 pb-16">
-      {/* Hero Section */}
-      <section className="flex flex-col items-center px-2 pt-8 text-center sm:pt-20">
+    <div className="flex flex-col gap-16 pb-16">
+      {/* Hero */}
+      <section className="flex flex-col items-center px-2 pt-12 text-center sm:pt-24">
         <h1 className="text-3xl font-bold tracking-tight sm:text-5xl lg:text-6xl">
           {t("hero_title")}
         </h1>
@@ -53,7 +30,7 @@ export default function HomePage() {
         </p>
         <div className="mt-8">
           <Link
-            href={`/${locale}/timeline`}
+            href={`/${locale}/s01`}
             className="inline-flex min-h-[44px] items-center gap-2 rounded-lg bg-zinc-900 px-6 py-3 text-sm font-medium text-white transition-colors hover:bg-zinc-700 dark:bg-white dark:text-zinc-900 dark:hover:bg-zinc-200"
           >
             {t("start")}
@@ -62,172 +39,45 @@ export default function HomePage() {
         </div>
       </section>
 
-      {/* Core Pattern Section */}
-      <section>
-        <div className="mb-6 text-center">
-          <h2 className="text-2xl font-bold sm:text-3xl">{t("core_pattern")}</h2>
-          <p className="mt-2 text-[var(--color-text-secondary)]">
-            {t("core_pattern_desc")}
-          </p>
-        </div>
-        <div className="mx-auto max-w-2xl overflow-hidden rounded-xl border border-zinc-800 bg-zinc-950">
-          <div className="flex items-center gap-2 border-b border-zinc-800 px-4 py-2.5">
-            <span className="h-3 w-3 rounded-full bg-red-500/70" />
-            <span className="h-3 w-3 rounded-full bg-yellow-500/70" />
-            <span className="h-3 w-3 rounded-full bg-green-500/70" />
-            <span className="ml-3 text-xs text-zinc-500">agent_loop.py</span>
-          </div>
-          <pre className="overflow-x-auto p-4 text-sm leading-relaxed">
-            <code>
-              <span className="text-purple-400">while</span>
-              <span className="text-zinc-300"> </span>
-              <span className="text-orange-300">True</span>
-              <span className="text-zinc-500">:</span>
-              {"\n"}
-              <span className="text-zinc-300">{"    "}response = client.messages.</span>
-              <span className="text-blue-400">create</span>
-              <span className="text-zinc-500">(</span>
-              <span className="text-zinc-300">messages=</span>
-              <span className="text-zinc-300">messages</span>
-              <span className="text-zinc-500">,</span>
-              <span className="text-zinc-300"> tools=</span>
-              <span className="text-zinc-300">tools</span>
-              <span className="text-zinc-500">)</span>
-              {"\n"}
-              <span className="text-purple-400">{"    "}if</span>
-              <span className="text-zinc-300"> response.stop_reason != </span>
-              <span className="text-green-400">&quot;tool_use&quot;</span>
-              <span className="text-zinc-500">:</span>
-              {"\n"}
-              <span className="text-purple-400">{"        "}break</span>
-              {"\n"}
-              <span className="text-purple-400">{"    "}for</span>
-              <span className="text-zinc-300"> tool_call </span>
-              <span className="text-purple-400">in</span>
-              <span className="text-zinc-300"> response.content</span>
-              <span className="text-zinc-500">:</span>
-              {"\n"}
-              <span className="text-zinc-300">{"        "}result = </span>
-              <span className="text-blue-400">execute_tool</span>
-              <span className="text-zinc-500">(</span>
-              <span className="text-zinc-300">tool_call.name</span>
-              <span className="text-zinc-500">,</span>
-              <span className="text-zinc-300"> tool_call.input</span>
-              <span className="text-zinc-500">)</span>
-              {"\n"}
-              <span className="text-zinc-300">{"        "}messages.</span>
-              <span className="text-blue-400">append</span>
-              <span className="text-zinc-500">(</span>
-              <span className="text-zinc-300">result</span>
-              <span className="text-zinc-500">)</span>
-            </code>
-          </pre>
-        </div>
-      </section>
-
-      {/* Message Flow Visualization */}
-      <section>
-        <div className="mb-6 text-center">
-          <h2 className="text-2xl font-bold sm:text-3xl">{t("message_flow")}</h2>
-          <p className="mt-2 text-[var(--color-text-secondary)]">
-            {t("message_flow_desc")}
-          </p>
-        </div>
-        <div className="mx-auto max-w-2xl">
-          <MessageFlow />
-        </div>
-      </section>
-
-      {/* Learning Path Preview */}
-      <section>
-        <div className="mb-6 text-center">
-          <h2 className="text-2xl font-bold sm:text-3xl">{t("learning_path")}</h2>
-          <p className="mt-2 text-[var(--color-text-secondary)]">
-            {t("learning_path_desc")}
-          </p>
-        </div>
-        <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
-          {LEARNING_PATH.map((versionId) => {
-            const meta = VERSION_META[versionId];
-            const data = getVersionData(versionId);
-            if (!meta || !data) return null;
-            return (
-              <Link
-                key={versionId}
-                href={`/${locale}/${versionId}`}
-                className="group block"
-              >
-                <Card
-                  className={cn(
-                    "h-full border transition-all duration-200",
-                    LAYER_BORDER_COLORS[meta.layer]
-                  )}
-                >
-                  <div className="flex items-start justify-between gap-2">
-                    <LayerBadge layer={meta.layer}>{versionId}</LayerBadge>
-                    <span className="text-xs tabular-nums text-[var(--color-text-secondary)]">
-                      {data.loc} {t("loc")}
-                    </span>
-                  </div>
-                  <h3 className="mt-3 text-sm font-semibold group-hover:underline">
-                    {meta.title}
-                  </h3>
-                  <p className="mt-1 text-xs text-[var(--color-text-secondary)]">
-                    {meta.keyInsight}
-                  </p>
-                </Card>
-              </Link>
-            );
-          })}
-        </div>
-      </section>
-
-      {/* Layer Overview */}
-      <section>
-        <div className="mb-6 text-center">
-          <h2 className="text-2xl font-bold sm:text-3xl">{t("layers_title")}</h2>
-          <p className="mt-2 text-[var(--color-text-secondary)]">
-            {t("layers_desc")}
-          </p>
-        </div>
-        <div className="flex flex-col gap-3">
-          {LAYERS.map((layer) => (
-            <div
-              key={layer.id}
-              className="flex items-center gap-4 rounded-xl border border-[var(--color-border)] bg-[var(--color-bg)] p-4"
-            >
-              <div
-                className={cn(
-                  "h-full w-1.5 self-stretch rounded-full",
-                  LAYER_BAR_COLORS[layer.id]
-                )}
-              />
-              <div className="flex-1">
-                <div className="flex items-center gap-2">
-                  <h3 className="text-sm font-semibold">{layer.label}</h3>
-                  <span className="text-xs text-[var(--color-text-secondary)]">
-                    {layer.versions.length} {t("versions_in_layer")}
-                  </span>
-                </div>
-                <div className="mt-2 flex flex-wrap gap-1.5">
-                  {layer.versions.map((vid) => {
-                    const meta = VERSION_META[vid];
-                    return (
-                      <Link key={vid} href={`/${locale}/${vid}`}>
-                        <LayerBadge
-                          layer={layer.id}
-                          className="cursor-pointer transition-opacity hover:opacity-80"
-                        >
-                          {vid}: {meta?.title}
-                        </LayerBadge>
-                      </Link>
-                    );
-                  })}
-                </div>
-              </div>
+      {/* Chapter list by stage */}
+      <section className="mx-auto w-full max-w-2xl space-y-10 px-4">
+        {LAYERS.map((layer) => (
+          <div key={layer.id}>
+            <div className="flex items-center gap-2 pb-3">
+              <span className={`h-2.5 w-2.5 rounded-full ${LAYER_DOT_COLORS[layer.id]}`} />
+              <span className="text-xs font-semibold uppercase tracking-wider text-zinc-400 dark:text-zinc-500">
+                {tLayer(layer.id)}
+              </span>
             </div>
-          ))}
-        </div>
+            <ul className="space-y-1">
+              {layer.versions.map((vId) => {
+                const meta = VERSION_META[vId];
+                const content = getVersionContent(vId, locale);
+                if (!meta) return null;
+                return (
+                  <li key={vId}>
+                    <Link
+                      href={`/${locale}/${vId}`}
+                      className="group block rounded-lg px-3 py-2.5 transition-colors hover:bg-zinc-100 dark:hover:bg-zinc-800/60"
+                    >
+                      <div className="flex items-baseline gap-2">
+                        <span className="font-mono text-sm text-zinc-400 dark:text-zinc-500">
+                          {vId}
+                        </span>
+                        <span className="text-sm font-medium text-zinc-900 group-hover:underline dark:text-zinc-100">
+                          {tSession(vId) || meta.title}
+                        </span>
+                      </div>
+                      <p className="mt-0.5 pl-[calc(theme(fontSize.sm)+0.5rem+2ch)] text-xs leading-relaxed text-zinc-500 dark:text-zinc-400">
+                        {content.keyInsight}
+                      </p>
+                    </Link>
+                  </li>
+                );
+              })}
+            </ul>
+          </div>
+        ))}
       </section>
     </div>
   );
diff --git a/web/src/app/globals.css b/web/src/app/globals.css
index 7aeef1a62..dfd7ba99c 100644
--- a/web/src/app/globals.css
+++ b/web/src/app/globals.css
@@ -3,11 +3,10 @@
 @custom-variant dark (&:where(.dark, .dark *));
 
 :root {
-  --color-layer-tools: #3B82F6;
-  --color-layer-planning: #10B981;
-  --color-layer-memory: #8B5CF6;
-  --color-layer-concurrency: #F59E0B;
-  --color-layer-collaboration: #EF4444;
+  --color-layer-core: #2563eb;
+  --color-layer-hardening: #059669;
+  --color-layer-runtime: #d97706;
+  --color-layer-platform: #dc2626;
   --color-bg: #ffffff;
   --color-bg-secondary: #f4f4f5;
   --color-text: #09090b;
@@ -368,10 +367,19 @@ body {
 
 /* -- Tables -- */
 
-.prose-custom table {
+.prose-custom .table-scroll {
   width: 100%;
+  overflow-x: auto;
   margin-top: 1.25rem;
   margin-bottom: 1.25rem;
+  -webkit-overflow-scrolling: touch;
+}
+
+.prose-custom table {
+  width: max-content;
+  min-width: 100%;
+  margin-top: 0;
+  margin-bottom: 0;
   border-collapse: separate;
   border-spacing: 0;
   font-size: 0.8125rem;
diff --git a/web/src/components/architecture/arch-diagram.tsx b/web/src/components/architecture/arch-diagram.tsx
index 2d8fa9e5e..cd931eb8d 100644
--- a/web/src/components/architecture/arch-diagram.tsx
+++ b/web/src/components/architecture/arch-diagram.tsx
@@ -1,228 +1,295 @@
 "use client";
 
 import { motion } from "framer-motion";
+import { useLocale } from "@/lib/i18n";
+import { VERSION_META } from "@/lib/constants";
+import {
+  pickDiagramText,
+  translateArchitectureText,
+} from "@/lib/diagram-localization";
+import { getVersionContent } from "@/lib/version-content";
+import {
+  ARCHITECTURE_BLUEPRINTS,
+  type ArchitectureSliceId,
+} from "@/data/architecture-blueprints";
 import { cn } from "@/lib/utils";
-import { LAYERS } from "@/lib/constants";
-import versionsData from "@/data/generated/versions.json";
-
-const CLASS_DESCRIPTIONS: Record<string, string> = {
-  TodoManager: "Visible task planning with constraints",
-  SkillLoader: "Dynamic knowledge injection from SKILL.md files",
-  ContextManager: "Three-layer context compression pipeline",
-  Task: "File-based persistent task with dependencies",
-  TaskManager: "File-based persistent task CRUD with dependencies",
-  BackgroundTask: "Single background execution unit",
-  BackgroundManager: "Non-blocking thread execution + notification queue",
-  TeammateManager: "Multi-agent team lifecycle and coordination",
-  Teammate: "Individual agent identity and state tracking",
-  SharedBoard: "Cross-agent shared state coordination",
-};
 
 interface ArchDiagramProps {
   version: string;
 }
 
-function getLayerColor(versionId: string): string {
-  const layer = LAYERS.find((l) => (l.versions as readonly string[]).includes(versionId));
-  return layer?.color ?? "#71717a";
-}
-
-function getLayerColorClasses(versionId: string): {
-  border: string;
-  bg: string;
-} {
-  const v =
-    versionsData.versions.find((v) => v.id === versionId) as { layer?: string } | undefined;
-  const layer = v?.layer;
-  switch (layer) {
-    case "tools":
-      return {
-        border: "border-blue-500",
-        bg: "bg-blue-500/10",
-      };
-    case "planning":
-      return {
-        border: "border-emerald-500",
-        bg: "bg-emerald-500/10",
-      };
-    case "memory":
-      return {
-        border: "border-purple-500",
-        bg: "bg-purple-500/10",
-      };
-    case "concurrency":
-      return {
-        border: "border-amber-500",
-        bg: "bg-amber-500/10",
-      };
-    case "collaboration":
-      return {
-        border: "border-red-500",
-        bg: "bg-red-500/10",
-      };
-    default:
-      return {
-        border: "border-zinc-500",
-        bg: "bg-zinc-500/10",
-      };
-  }
-}
-
-function collectClassesUpTo(
-  targetId: string
-): { name: string; introducedIn: string }[] {
-  const { versions, diffs } = versionsData;
-  const order = versions.map((v) => v.id);
-  const targetIdx = order.indexOf(targetId);
-  if (targetIdx < 0) return [];
-
-  const result: { name: string; introducedIn: string }[] = [];
-  const seen = new Set<string>();
-
-  for (let i = 0; i <= targetIdx; i++) {
-    const v = versions[i];
-    if (!v.classes) continue;
-    for (const cls of v.classes) {
-      if (!seen.has(cls.name)) {
-        seen.add(cls.name);
-        result.push({ name: cls.name, introducedIn: v.id });
-      }
-    }
+const SLICE_STYLE: Record<
+  ArchitectureSliceId,
+  {
+    ring: string;
+    badge: string;
+    surface: string;
+    title: { zh: string; en: string; ja?: string };
+    note: { zh: string; en: string; ja?: string };
   }
+> = {
+  mainline: {
+    ring: "ring-blue-500/20",
+    badge:
+      "border-blue-200 bg-blue-50 text-blue-700 dark:border-blue-900/60 dark:bg-blue-950/30 dark:text-blue-300",
+    surface:
+      "from-blue-500/12 via-blue-500/5 to-transparent dark:from-blue-500/10 dark:via-transparent",
+    title: { zh: "主线执行", en: "Mainline", ja: "主線実行" },
+    note: {
+      zh: "真正把系统往前推的那条执行主线。",
+      en: "The path that actually pushes the system forward.",
+      ja: "実際にシステムを前へ進める主線です。",
+    },
+  },
+  control: {
+    ring: "ring-emerald-500/20",
+    badge:
+      "border-emerald-200 bg-emerald-50 text-emerald-700 dark:border-emerald-900/60 dark:bg-emerald-950/30 dark:text-emerald-300",
+    surface:
+      "from-emerald-500/12 via-emerald-500/5 to-transparent dark:from-emerald-500/10 dark:via-transparent",
+    title: { zh: "控制面", en: "Control Plane", ja: "制御面" },
+    note: {
+      zh: "决定怎么运行、何时放行、何时转向。",
+      en: "Decides how execution is controlled, gated, and redirected.",
+      ja: "どう動かし、いつ通し、いつ向きを変えるかを決めます。",
+    },
+  },
+  state: {
+    ring: "ring-amber-500/20",
+    badge:
+      "border-amber-200 bg-amber-50 text-amber-700 dark:border-amber-900/60 dark:bg-amber-950/30 dark:text-amber-300",
+    surface:
+      "from-amber-500/12 via-amber-500/5 to-transparent dark:from-amber-500/10 dark:via-transparent",
+    title: { zh: "状态容器", en: "State Records", ja: "状態レコード" },
+    note: {
+      zh: "真正需要被系统记住和回写的结构。",
+      en: "The structures the system must remember and write back.",
+      ja: "システムが記憶し、回写すべき構造です。",
+    },
+  },
+  lanes: {
+    ring: "ring-rose-500/20",
+    badge:
+      "border-rose-200 bg-rose-50 text-rose-700 dark:border-rose-900/60 dark:bg-rose-950/30 dark:text-rose-300",
+    surface:
+      "from-rose-500/12 via-rose-500/5 to-transparent dark:from-rose-500/10 dark:via-transparent",
+    title: { zh: "并行 / 外部车道", en: "Lanes / External", ja: "並行 / 外部レーン" },
+    note: {
+      zh: "长期队友、后台槽位或外部能力的进入面。",
+      en: "Where long-lived workers, background slots, or external capability enter.",
+      ja: "長期ワーカー、バックグラウンドスロット、外部能力が入ってくる面です。",
+    },
+  },
+};
 
-  return result;
-}
-
-function getNewClassNames(version: string): Set<string> {
-  const diff = versionsData.diffs.find((d) => d.to === version);
-  if (!diff) {
-    const v = versionsData.versions.find((ver) => ver.id === version);
-    return new Set(v?.classes?.map((c) => c.name) ?? []);
-  }
-  return new Set(diff.newClasses ?? []);
-}
+const UI_TEXT = {
+  summaryTitle: {
+    zh: "这章在系统里真正新增了什么",
+    en: "What This Chapter Actually Adds",
+    ja: "この章でシステムに何が増えたか",
+  },
+  recordsTitle: {
+    zh: "关键记录结构",
+    en: "Key Records",
+    ja: "主要レコード",
+  },
+  recordsNote: {
+    zh: "这些不是实现细枝末节，而是开发者自己重建系统时最应该抓住的状态容器。",
+    en: "These are the state containers worth holding onto when you rebuild the system yourself.",
+    ja: "これらは実装の枝葉ではなく、自分で再構築するときに掴むべき状態容器です。",
+  },
+  handoffTitle: {
+    zh: "主回流路径",
+    en: "Primary Handoff Path",
+    ja: "主回流経路",
+  },
+  fresh: {
+    zh: "新增",
+    en: "NEW",
+    ja: "新規",
+  },
+};
 
 export function ArchDiagram({ version }: ArchDiagramProps) {
-  const allClasses = collectClassesUpTo(version);
-  const newClassNames = getNewClassNames(version);
-  const versionData = versionsData.versions.find((v) => v.id === version);
-  const tools = versionData?.tools ?? [];
+  const locale = useLocale();
+  const blueprint =
+    ARCHITECTURE_BLUEPRINTS[version as keyof typeof ARCHITECTURE_BLUEPRINTS];
+  const meta = VERSION_META[version];
+  const content = getVersionContent(version, locale);
 
-  const reversed = [...allClasses].reverse();
+  if (!blueprint || !meta) return null;
+
+  const sliceOrder: ArchitectureSliceId[] = [
+    "mainline",
+    "control",
+    "state",
+    "lanes",
+  ];
+  const visibleSlices = sliceOrder.filter(
+    (sliceId) => (blueprint.slices[sliceId] ?? []).length > 0
+  );
 
   return (
-    <div className="space-y-3">
-      {reversed.map((cls, i) => {
-        const isNew = newClassNames.has(cls.name);
-        const colorClasses = getLayerColorClasses(cls.introducedIn);
+    <div className="space-y-6">
+      <section className="overflow-hidden rounded-[30px] border border-zinc-200/80 bg-white/95 shadow-sm dark:border-zinc-800/80 dark:bg-zinc-950/90">
+        <div className="relative overflow-hidden px-5 py-6 sm:px-6">
+          <div className="absolute inset-x-0 top-0 h-28 bg-[radial-gradient(circle_at_top_left,rgba(251,191,36,0.16),transparent_45%),radial-gradient(circle_at_top_right,rgba(59,130,246,0.14),transparent_38%)] dark:bg-[radial-gradient(circle_at_top_left,rgba(245,158,11,0.16),transparent_45%),radial-gradient(circle_at_top_right,rgba(96,165,250,0.14),transparent_38%)]" />
+          <div className="relative">
+            <p className="text-xs uppercase tracking-[0.22em] text-zinc-400">
+              {pickDiagramText(locale, UI_TEXT.summaryTitle)}
+            </p>
+            <h3 className="mt-3 text-2xl font-semibold tracking-tight text-zinc-950 dark:text-zinc-50">
+              {content.coreAddition}
+            </h3>
+            <p className="mt-3 max-w-3xl text-sm leading-7 text-zinc-600 dark:text-zinc-300">
+              {translateArchitectureText(
+                locale,
+                pickDiagramText(locale, blueprint.summary)
+              )}
+            </p>
+          </div>
+        </div>
+      </section>
+
+      <section className="grid grid-cols-1 gap-4 xl:grid-cols-2">
+        {visibleSlices.map((sliceId, sliceIndex) => {
+          const slice = blueprint.slices[sliceId] ?? [];
+          const style = SLICE_STYLE[sliceId];
 
-        return (
-          <div key={cls.name}>
-            {i > 0 && (
-              <div className="flex justify-center py-1">
-                <motion.svg
-                  width="24"
-                  height="20"
-                  viewBox="0 0 24 20"
-                  initial={{ opacity: 0 }}
-                  animate={{ opacity: 1 }}
-                  transition={{ delay: i * 0.08 + 0.05 }}
-                >
-                  <motion.line
-                    x1={12}
-                    y1={0}
-                    x2={12}
-                    y2={14}
-                    stroke="var(--color-text-secondary)"
-                    strokeWidth={1.5}
-                    initial={{ pathLength: 0 }}
-                    animate={{ pathLength: 1 }}
-                    transition={{ duration: 0.3, delay: i * 0.08 }}
-                  />
-                  <motion.polygon
-                    points="7,12 12,19 17,12"
-                    fill="var(--color-text-secondary)"
-                    initial={{ opacity: 0 }}
-                    animate={{ opacity: 1 }}
-                    transition={{ delay: i * 0.08 + 0.2 }}
-                  />
-                </motion.svg>
+          return (
+            <motion.section
+              key={sliceId}
+              initial={{ opacity: 0, y: 18 }}
+              animate={{ opacity: 1, y: 0 }}
+              transition={{ delay: sliceIndex * 0.06, duration: 0.32 }}
+              className={cn(
+                "overflow-hidden rounded-[28px] border border-zinc-200/80 bg-white/95 shadow-sm ring-1 dark:border-zinc-800/80 dark:bg-zinc-950/90",
+                style.ring
+              )}
+            >
+              <div className={cn("bg-gradient-to-br px-5 py-5 sm:px-6", style.surface)}>
+                <div className="flex flex-wrap items-center gap-2">
+                  <span
+                    className={cn(
+                      "rounded-full border px-2.5 py-1 text-[11px] font-medium",
+                      style.badge
+                    )}
+                  >
+                    {pickDiagramText(locale, style.title)}
+                  </span>
+                </div>
+                <p className="mt-3 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                  {pickDiagramText(locale, style.note)}
+                </p>
               </div>
-            )}
-            <motion.div
-            key={cls.name}
-            initial={{ opacity: 0, y: 20 }}
-            animate={{ opacity: 1, y: 0 }}
-            transition={{ delay: i * 0.08, duration: 0.3 }}
-            className={cn(
-              "rounded-lg border-2 px-4 py-3 transition-colors",
-              isNew
-                ? cn(colorClasses.border, colorClasses.bg)
-                : "border-zinc-200 bg-zinc-50 dark:border-zinc-700 dark:bg-zinc-800/50"
-            )}
-          >
-            <div className="flex items-center justify-between">
-              <div>
-                <span
-                  className={cn(
-                    "font-mono text-sm font-semibold",
-                    isNew
-                      ? "text-zinc-900 dark:text-white"
-                      : "text-zinc-400 dark:text-zinc-500"
+              <div className="space-y-3 px-5 py-5 sm:px-6">
+                {slice.map((item, itemIndex) => (
+                  <motion.div
+                    key={`${sliceId}-${itemIndex}-${translateArchitectureText(locale, pickDiagramText(locale, item.name))}`}
+                    initial={{ opacity: 0, x: -10 }}
+                    animate={{ opacity: 1, x: 0 }}
+                    transition={{ delay: sliceIndex * 0.06 + itemIndex * 0.04, duration: 0.24 }}
+                    className="rounded-2xl border border-zinc-200/80 bg-zinc-50/80 p-4 dark:border-zinc-800/80 dark:bg-zinc-900/70"
+                  >
+                    <div className="flex flex-wrap items-start gap-2">
+                      <h4 className="text-sm font-semibold text-zinc-950 dark:text-zinc-50">
+                        {translateArchitectureText(
+                          locale,
+                          pickDiagramText(locale, item.name)
+                        )}
+                      </h4>
+                      {item.fresh && (
+                        <span className="rounded-full bg-zinc-900 px-2 py-0.5 text-[10px] font-bold uppercase text-white dark:bg-zinc-100 dark:text-zinc-900">
+                          {pickDiagramText(locale, UI_TEXT.fresh)}
+                        </span>
+                      )}
+                    </div>
+                    <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                      {translateArchitectureText(
+                        locale,
+                        pickDiagramText(locale, item.detail)
+                      )}
+                    </p>
+                  </motion.div>
+                ))}
+              </div>
+            </motion.section>
+          );
+        })}
+      </section>
+
+      <section className="rounded-[30px] border border-zinc-200/80 bg-white/95 px-5 py-6 shadow-sm dark:border-zinc-800/80 dark:bg-zinc-950/90 sm:px-6">
+        <div className="flex flex-col gap-5 xl:flex-row xl:items-start xl:justify-between">
+          <div className="max-w-xl space-y-2">
+            <p className="text-xs uppercase tracking-[0.22em] text-zinc-400">
+              {pickDiagramText(locale, UI_TEXT.recordsTitle)}
+            </p>
+            <p className="text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+              {pickDiagramText(locale, UI_TEXT.recordsNote)}
+            </p>
+          </div>
+          <div className="grid flex-1 grid-cols-1 gap-3 md:grid-cols-2">
+            {blueprint.records.map((record, index) => (
+              <motion.div
+                key={`${translateArchitectureText(locale, pickDiagramText(locale, record.name))}-${index}`}
+                initial={{ opacity: 0, scale: 0.98 }}
+                animate={{ opacity: 1, scale: 1 }}
+                transition={{ delay: index * 0.05, duration: 0.24 }}
+                className="rounded-2xl border border-zinc-200/80 bg-zinc-50/80 p-4 dark:border-zinc-800/80 dark:bg-zinc-900/70"
+              >
+                <div className="flex flex-wrap items-center gap-2">
+                  <span className="font-mono text-xs font-semibold tracking-tight text-zinc-900 dark:text-zinc-100">
+                    {translateArchitectureText(
+                      locale,
+                      pickDiagramText(locale, record.name)
+                    )}
+                  </span>
+                  {record.fresh && (
+                    <span className="rounded-full border border-zinc-200 bg-white px-2 py-0.5 text-[10px] font-bold uppercase text-zinc-700 dark:border-zinc-700 dark:bg-zinc-950 dark:text-zinc-300">
+                      {pickDiagramText(locale, UI_TEXT.fresh)}
+                    </span>
                   )}
-                >
-                  {cls.name}
-                </span>
-                <p
-                  className={cn(
-                    "mt-0.5 text-xs",
-                    isNew
-                      ? "text-zinc-600 dark:text-zinc-300"
-                      : "text-zinc-400 dark:text-zinc-500"
+                </div>
+                <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                  {translateArchitectureText(
+                    locale,
+                    pickDiagramText(locale, record.detail)
                   )}
-                >
-                  {CLASS_DESCRIPTIONS[cls.name] || ""}
                 </p>
-              </div>
-              <div className="flex items-center gap-2">
-                <span className="text-xs text-zinc-400 dark:text-zinc-500">
-                  {cls.introducedIn}
-                </span>
-                {isNew && (
-                  <span className="rounded-full bg-zinc-900 px-2 py-0.5 text-[10px] font-bold uppercase text-white dark:bg-white dark:text-zinc-900">
-                    NEW
-                  </span>
-                )}
-              </div>
-            </div>
-          </motion.div>
+              </motion.div>
+            ))}
           </div>
-        );
-      })}
-
-      {allClasses.length === 0 && (
-        <div className="rounded-lg border border-dashed border-zinc-300 px-4 py-6 text-center text-sm text-zinc-400 dark:border-zinc-600">
-          No classes in this version (functions only)
         </div>
-      )}
+      </section>
 
-      {tools.length > 0 && (
-        <motion.div
-          initial={{ opacity: 0 }}
-          animate={{ opacity: 1 }}
-          transition={{ delay: reversed.length * 0.08 + 0.1 }}
-          className="flex flex-wrap gap-1.5 pt-2"
-        >
-          {tools.map((tool) => (
-            <span
-              key={tool}
-              className="rounded-md bg-zinc-100 px-2 py-1 font-mono text-xs text-zinc-600 dark:bg-zinc-800 dark:text-zinc-400"
+      <section className="rounded-[30px] border border-zinc-200/80 bg-white/95 px-5 py-6 shadow-sm dark:border-zinc-800/80 dark:bg-zinc-950/90 sm:px-6">
+        <p className="text-xs uppercase tracking-[0.22em] text-zinc-400">
+          {pickDiagramText(locale, UI_TEXT.handoffTitle)}
+        </p>
+        <div className="mt-5 grid grid-cols-1 gap-3 lg:grid-cols-3">
+          {blueprint.handoff.map((step, index) => (
+            <motion.div
+              key={`${translateArchitectureText(locale, pickDiagramText(locale, step))}-${index}`}
+              initial={{ opacity: 0, y: 10 }}
+              animate={{ opacity: 1, y: 0 }}
+              transition={{ delay: index * 0.06, duration: 0.26 }}
+              className="rounded-2xl border border-zinc-200/80 bg-[linear-gradient(135deg,rgba(255,255,255,0.98),rgba(244,244,245,0.9))] p-4 dark:border-zinc-800/80 dark:bg-[linear-gradient(135deg,rgba(24,24,27,0.96),rgba(9,9,11,0.92))]"
             >
-              {tool}
-            </span>
+              <div className="flex items-start gap-3">
+                <span className="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-full bg-zinc-900 text-xs font-bold text-white dark:bg-zinc-100 dark:text-zinc-900">
+                  {index + 1}
+                </span>
+                <p className="text-sm leading-6 text-zinc-700 dark:text-zinc-200">
+                  {translateArchitectureText(
+                    locale,
+                    pickDiagramText(locale, step)
+                  )}
+                </p>
+              </div>
+            </motion.div>
           ))}
-        </motion.div>
-      )}
+        </div>
+      </section>
     </div>
   );
 }
diff --git a/web/src/components/architecture/design-decisions.tsx b/web/src/components/architecture/design-decisions.tsx
index 5fa47faa4..4a64d04ae 100644
--- a/web/src/components/architecture/design-decisions.tsx
+++ b/web/src/components/architecture/design-decisions.tsx
@@ -5,6 +5,10 @@ import { motion, AnimatePresence } from "framer-motion";
 import { useTranslations, useLocale } from "@/lib/i18n";
 import { ChevronDown } from "lucide-react";
 import { cn } from "@/lib/utils";
+import {
+  isGenericAnnotationVersion,
+  resolveLegacySessionAssetVersion,
+} from "@/lib/session-assets";
 
 import s01Annotations from "@/data/annotations/s01.json";
 import s02Annotations from "@/data/annotations/s02.json";
@@ -19,13 +23,19 @@ import s10Annotations from "@/data/annotations/s10.json";
 import s11Annotations from "@/data/annotations/s11.json";
 import s12Annotations from "@/data/annotations/s12.json";
 
+interface DecisionLocaleCopy {
+  title?: string;
+  description?: string;
+  alternatives?: string;
+}
+
 interface Decision {
   id: string;
   title: string;
   description: string;
   alternatives: string;
-  zh?: { title: string; description: string };
-  ja?: { title: string; description: string };
+  zh?: DecisionLocaleCopy;
+  ja?: DecisionLocaleCopy;
 }
 
 interface AnnotationFile {
@@ -48,6 +58,646 @@ const ANNOTATIONS: Record<string, AnnotationFile> = {
   s12: s12Annotations as AnnotationFile,
 };
 
+const GENERIC_ANNOTATIONS: Record<string, AnnotationFile> = {
+  s07: {
+    version: "s07",
+    decisions: [
+      {
+        id: "permission-before-execution",
+        title: "Permission Is a Gate Before Execution",
+        description:
+          "The model should not call tools directly as if intent were already trusted execution. Normalize the requested action first, then run it through a shared policy gate that returns allow, deny, or ask. This keeps safety rules consistent across every tool.",
+        alternatives:
+          "Tool-local safety checks are simpler at first, but they scatter policy into every handler and make behavior inconsistent. A single permission plane adds one more layer, but it is the only place where global execution policy can stay coherent.",
+        zh: {
+          title: "权限必须是执行前闸门",
+          description:
+            "模型不应该把 tool call 直接当成可信执行。先把请求规范化成统一意图，再送进共享权限层，返回 allow / deny / ask。这样所有工具都遵循同一套安全语义。",
+          alternatives:
+            "把安全判断散落到每个工具里实现起来更快，但策略会碎片化。独立权限层虽然多一层，却能让全局执行规则保持一致。",
+        },
+        ja: {
+          title: "権限は実行前のゲートでなければならない",
+          description:
+            "model は tool call をそのまま信頼済みの実行として扱ってはいけません。まず要求を統一された intent に正規化し、共有 permission layer に通して allow / deny / ask を返します。これで全 tool が同じ安全意味論に従います。",
+          alternatives:
+            "安全判定を各 tool に分散すると最初は速く作れますが、policy がばらけます。独立した permission layer は一段増えますが、全体の実行方針を一貫して保てます。",
+        },
+      },
+      {
+        id: "structured-permission-result",
+        title: "Permission Results Must Be Structured and Visible",
+        description:
+          "A deny or ask outcome is not an implementation detail. The agent must append that result back into the loop so the model can re-plan from it. Otherwise the system silently blocks execution and the model loses the reason why.",
+        alternatives:
+          "Throwing an exception or returning a plain string is easy, but it hides the decision semantics. A structured permission result makes the next model step explainable and recoverable.",
+        zh: {
+          title: "权限结果必须结构化且可见",
+          description:
+            "deny 或 ask 不是内部细节。它们必须回写到主循环，让模型知道为什么没执行、接下来该怎么重规划。否则系统只是静默阻止执行，模型却看不到原因。",
+          alternatives:
+            "直接抛异常或回一段普通字符串最省事，但会把决策语义藏起来。结构化权限结果能让后续一步更可解释、更可恢复。",
+        },
+        ja: {
+          title: "権限結果は構造化され、見える形で戻るべきだ",
+          description:
+            "deny や ask は内部実装の細部ではありません。main loop へ書き戻し、model が「なぜ実行されなかったか」「次にどう再計画するか」を見えるようにする必要があります。そうしないと system は黙って止め、model だけが理由を失います。",
+          alternatives:
+            "例外や単なる文字列で返す方が楽ですが、判断の意味が隠れます。構造化された permission result の方が、次の一手を説明可能で回復可能にします。",
+        },
+      },
+    ],
+  },
+  s08: {
+    version: "s08",
+    decisions: [
+      {
+        id: "hooks-observe-lifecycle",
+        title: "Hooks Extend Lifecycle, Not Core State Progression",
+        description:
+          "Hooks should attach around stable lifecycle boundaries such as pre_tool, post_tool, and on_error. The core loop still owns messages, tool execution, and stop conditions. That separation keeps the system teachable and prevents hidden control flow.",
+        alternatives:
+          "Letting hooks mutate core loop control directly feels flexible, but it makes execution order harder to reason about. Stable lifecycle boundaries keep extension power without dissolving the mainline.",
+        zh: {
+          title: "Hook 扩展生命周期，不接管主状态推进",
+          description:
+            "Hook 应该挂在 pre_tool、post_tool、on_error 这类稳定边界上。messages、工具执行和停止条件仍由主循环掌控。这样系统心智才清晰，不会出现隐藏控制流。",
+          alternatives:
+            "让 Hook 直接改主循环状态看似灵活，但执行顺序会越来越难推理。稳定生命周期边界能保留扩展力，又不破坏主线。",
+        },
+        ja: {
+          title: "Hook はライフサイクルを拡張し、主状態の進行は奪わない",
+          description:
+            "Hook は pre_tool、post_tool、on_error のような安定境界に付けるべきです。messages、tool 実行、停止条件は main loop が持ち続けます。これで system の心智が崩れず、隠れた制御フローも生まれません。",
+          alternatives:
+            "Hook が main loop 制御を直接書き換えると柔軟そうに見えますが、実行順はどんどん読みにくくなります。安定した lifecycle 境界が、拡張力と主線の明瞭さを両立させます。",
+        },
+      },
+      {
+        id: "normalized-hook-event-shape",
+        title: "Hooks Need a Normalized Event Shape",
+        description:
+          "Each hook should receive the same event envelope: tool name, input, result, error, timing, and session identifiers. This lets audit, tracing, metrics, and policy hooks share one mental model instead of inventing custom payloads.",
+        alternatives:
+          "Passing ad hoc strings to each hook is fast, but every new hook then needs custom parsing and drifts from the rest of the system. A normalized event contract costs a little upfront and pays for itself quickly.",
+        zh: {
+          title: "Hook 必须共享统一事件结构",
+          description:
+            "每个 Hook 都应该收到同样的事件封包，例如 tool name、input、result、error、耗时、session id。这样审计、追踪、指标和策略 Hook 才共享同一心智模型。",
+          alternatives:
+            "给每个 Hook 传临时拼接的字符串最省事，但新 Hook 都得自己解析，系统会越来越散。统一事件结构前期多一点设计，后面会省很多心智成本。",
+        },
+        ja: {
+          title: "Hook は正規化されたイベント形を共有する必要がある",
+          description:
+            "各 Hook は tool name、input、result、error、所要時間、session id のような同じ event envelope を受け取るべきです。これで audit、trace、metrics、policy hook が同じ心智モデルを共有できます。",
+          alternatives:
+            "その場しのぎの文字列を各 Hook に渡すのは楽ですが、新しい Hook のたびに独自解析が必要になり、system は散らかります。統一イベント契約は最初に少し設計が必要でも、すぐ元が取れます。",
+        },
+      },
+    ],
+  },
+  s09: {
+    version: "s09",
+    decisions: [
+      {
+        id: "memory-keeps-only-durable-facts",
+        title: "Memory Stores Durable Facts, Not Full History",
+        description:
+          "Long-term memory should hold cross-session facts such as user preferences, durable project constraints, and other information that cannot be cheaply re-derived. That keeps memory small, legible, and useful.",
+        alternatives:
+          "Saving every conversation turn feels safe, but it turns memory into an unbounded log and makes retrieval noisy. Selective durable memory is harder to teach at first, but it is the right system boundary.",
+        zh: {
+          title: "Memory 只保存长期有效事实",
+          description:
+            "长期记忆应该保存跨会话事实，例如用户偏好、稳定项目约束、无法轻易重新推导的信息。这样 memory 才会小而清晰，真正有用。",
+          alternatives:
+            "把整段历史全存进去看起来更稳，但长期会变成无边界日志，检索也会很脏。选择性保存长期事实更符合正确边界。",
+        },
+        ja: {
+          title: "Memory は長く有効な事実だけを保存する",
+          description:
+            "long-term memory には、ユーザー設定、安定した project 制約、簡単には再導出できない情報のような、会話をまたいで有効な事実だけを置くべきです。そうすると memory は小さく、読みやすく、役に立つ状態を保てます。",
+          alternatives:
+            "会話履歴を全部保存すると安全そうですが、やがて無制限ログになり、検索も濁ります。長期事実だけを選んで残す方が正しい境界です。",
+        },
+      },
+      {
+        id: "memory-read-write-phases",
+        title: "Memory Needs Clear Read and Write Phases",
+        description:
+          "Load relevant memory before prompt assembly, then extract and persist new durable facts after the work turn completes. This keeps memory flow visible and prevents the loop from mutating long-term state at arbitrary moments.",
+        alternatives:
+          "Writing memory opportunistically at random tool boundaries is possible, but it makes memory updates hard to explain. Clear read and write phases keep the lifecycle teachable.",
+        zh: {
+          title: "Memory 需要明确读写阶段",
+          description:
+            "在 prompt 装配前读取相关 memory，在任务轮次结束后提炼并写回新的长期事实。这样读写边界清楚，也避免主循环在任意时刻偷偷修改长期状态。",
+          alternatives:
+            "在随机工具边界随手写 memory 虽然也能跑，但很难解释系统到底何时更新长期知识。清晰阶段更适合教学和实现。",
+        },
+        ja: {
+          title: "Memory には明確な読取段階と書込段階が必要だ",
+          description:
+            "prompt 組み立て前に関連 memory を読み込み、作業ターンの後で新しい durable fact を抽出して書き戻します。こうすると読書き境界が見え、main loop が任意の瞬間に長期状態をこっそり変えることも防げます。",
+          alternatives:
+            "適当な tool 境界で memory を書くこともできますが、いつ長期知識が更新されたのか説明しにくくなります。明確な read/write phase の方が、学習にも実装にも向いています。",
+        },
+      },
+    ],
+  },
+  s10: {
+    version: "s10",
+    decisions: [
+      {
+        id: "prompt-is-a-pipeline",
+        title: "The System Prompt Should Be Built as a Pipeline",
+        description:
+          "Role policy, workspace state, tool catalog, memory, and task focus should be assembled as explicit prompt sections in a visible order. This makes model input auditable and keeps the control plane understandable.",
+        alternatives:
+          "A single giant string looks simpler in code, but no one can explain which part came from where or why its order matters. A pipeline adds structure where the system actually needs it.",
+        zh: {
+          title: "系统提示词应被实现成装配流水线",
+          description:
+            "角色策略、工作区状态、工具目录、memory、任务焦点都应该作为显式片段按顺序装配。这样模型输入才可审计，控制平面也才讲得清楚。",
+          alternatives:
+            "一整段大字符串在代码里看起来更省事，但没人能说清每部分从哪来、顺序为什么这样。Prompt pipeline 才符合真实系统结构。",
+        },
+        ja: {
+          title: "System prompt は組み立てパイプラインとして作るべきだ",
+          description:
+            "role policy、workspace state、tool catalog、memory、task focus は、見える順序を持つ prompt section として明示的に組み立てるべきです。これで model input が監査可能になり、control plane も説明しやすくなります。",
+          alternatives:
+            "巨大な 1 本の文字列にすると実装は簡単に見えますが、どこから来た指示なのか、なぜその順番なのかを誰も説明できません。pipeline の方が実際の構造に合っています。",
+        },
+      },
+      {
+        id: "stable-policy-separated-from-runtime-state",
+        title: "Stable Policy Must Stay Separate from Runtime State",
+        description:
+          "Instruction hierarchy becomes clearer when stable rules live separately from volatile runtime data. That separation reduces accidental prompt drift and makes each prompt section easier to test.",
+        alternatives:
+          "Mixing durable policy with per-turn runtime details works for tiny demos, but it breaks down quickly once memory, tasks, and recovery hints all need to join the input.",
+        zh: {
+          title: "稳定策略与运行时状态必须分开",
+          description:
+            "当稳定规则和每轮运行时数据分离后，指令层级会清晰很多，也更不容易出现提示词结构漂移。每一段输入都更容易单独测试。",
+          alternatives:
+            "小 demo 里把所有东西揉在一起还能跑，但一旦 memory、任务状态、恢复提示都要加入输入，混写方式很快就失控。",
+        },
+        ja: {
+          title: "安定した policy と runtime state は分けて保つべきだ",
+          description:
+            "変わりにくい規則と毎ターン変わる runtime data を分けると、指示の階層がずっと明確になります。prompt drift も起きにくくなり、各 section を個別にテストしやすくなります。",
+          alternatives:
+            "小さな demo では全部混ぜても動きますが、memory、task state、recovery hint まで入れ始めるとすぐ破綻します。分離が必要です。",
+        },
+      },
+    ],
+  },
+  s11: {
+    version: "s11",
+    decisions: [
+      {
+        id: "explicit-continuation-reasons",
+        title: "Recovery Needs Explicit Continuation Reasons",
+        description:
+          "After a failure, the agent should record whether it is retrying, degrading, requesting confirmation, or stopping. That reason becomes part of the visible state and lets the next model step act intentionally.",
+        alternatives:
+          "A blind retry loop is easy to implement, but neither the user nor the model can explain what branch the system is on. Explicit continuation reasons make recovery legible.",
+        zh: {
+          title: "恢复分支必须显式写出继续原因",
+          description:
+            "失败后，系统应该明确记录当前是在 retry、fallback、请求确认还是停止。这个原因本身也是可见状态，让下一步模型推理更有依据。",
+          alternatives:
+            "盲重试最容易写，但用户和模型都不知道系统现在处在哪条恢复分支。显式 continuation reason 才能让恢复过程可解释。",
+        },
+        ja: {
+          title: "回復分岐は継続理由を明示して残すべきだ",
+          description:
+            "失敗後、system は retry・fallback・確認要求・停止のどれにいるのかを明示して記録すべきです。この理由自体が visible state になり、次の model step の判断材料になります。",
+          alternatives:
+            "盲目的な retry loop は実装しやすいですが、user も model も今どの回復分岐にいるのか説明できません。explicit continuation reason が回復を読めるものにします。",
+        },
+      },
+      {
+        id: "bounded-retry-branches",
+        title: "Retry Paths Must Be Bounded",
+        description:
+          "Recovery branches need caps, stop conditions, and alternative strategies. Otherwise the system only hides failure behind repetition instead of turning it into progress.",
+        alternatives:
+          "Infinite retries can appear robust in early demos, but they produce loops with no insight. Bounded branches force the design to define when the system should pivot or stop.",
+        zh: {
+          title: "重试分支必须有上限和转向条件",
+          description:
+            "恢复分支必须有次数上限、停止条件和降级路径。否则系统只是把失败藏进重复执行，并没有真正把失败转成进展。",
+          alternatives:
+            "无限重试在早期 demo 里看起来像“更稳”，但其实只是在制造无洞察的循环。明确边界能逼迫系统定义何时转向或停止。",
+        },
+        ja: {
+          title: "Retry 分岐には上限と転向条件が必要だ",
+          description:
+            "回復分岐には試行回数の上限、停止条件、別戦略への切替経路が必要です。そうしないと system は失敗を繰り返しの中へ隠すだけで、進展に変えられません。",
+          alternatives:
+            "無限 retry は初期 demo では頑丈に見えますが、実際は洞察のないループを作るだけです。境界を定めることで、いつ pivot し、いつ止まるかを設計できます。",
+        },
+      },
+    ],
+  },
+  s12: {
+    version: "s12",
+    decisions: [
+      {
+        id: "task-records-are-durable-work-nodes",
+        title: "Task Records Should Describe Durable Work Nodes",
+        description:
+          "A task record should represent work that can survive across turns, not a temporary note for one model call. That means keeping explicit identifiers, states, and dependency edges on disk or in another durable store.",
+        alternatives:
+          "Session-local todo text is cheaper to explain at first, but it cannot coordinate larger work once the loop moves on. Durable records add structure where the runtime actually needs it.",
+        zh: {
+          title: "任务记录必须是可持久的工作节点",
+          description:
+            "Task record 应该表示一项能跨轮次继续推进的工作，而不是某一轮模型调用里的临时备注。这要求它拥有明确 id、status 和依赖边，并被持久化保存。",
+          alternatives:
+            "会话级 todo 文本一开始更容易讲，但主循环一旦继续往前，它就无法协调更大的工作。Durable record 才是正确的系统边界。",
+        },
+        ja: {
+          title: "Task record は持続する作業ノードを表すべきだ",
+          description:
+            "task record は、複数ターンにまたがって進む work を表すべきで、1 回の model call のメモではありません。そのために明示的な id、status、dependency edge を持ち、永続化される必要があります。",
+          alternatives:
+            "session 内 todo text は最初は説明しやすいですが、loop が先へ進むと大きな仕事を調整できません。durable record の方が正しい境界です。",
+        },
+      },
+      {
+        id: "unlock-logic-belongs-to-the-board",
+        title: "Dependency Unlock Logic Belongs to the Task Board",
+        description:
+          "Completing one task should update the board, check dependency satisfaction, and unlock the next nodes. That logic belongs to the task system, not to whatever worker happened to finish the task.",
+        alternatives:
+          "Letting each worker manually decide what becomes available next is flexible, but it scatters dependency semantics across the codebase. Central board logic keeps the graph teachable.",
+        zh: {
+          title: "依赖解锁逻辑必须属于任务板",
+          description:
+            "完成一个任务以后，应该由任务板统一更新状态、检查依赖是否满足，并解锁后续节点。这段逻辑属于 task system，而不该散落到各个执行者手里。",
+          alternatives:
+            "让每个执行者自己判断后续任务是否解锁看似灵活，但依赖语义会散落到整个代码库。集中在任务板里才讲得清楚。",
+        },
+        ja: {
+          title: "依存の解放ロジックは task board が持つべきだ",
+          description:
+            "1 つの task が完了したら、board が状態更新、依存充足の確認、次ノードの解放をまとめて行うべきです。このロジックは task system に属し、たまたま作業した worker に散らしてはいけません。",
+          alternatives:
+            "各 worker が次に何を解放するかを個別判断すると柔軟そうですが、dependency semantics がコード全体へ散ります。board に集中させる方が教えやすく、壊れにくいです。",
+        },
+      },
+    ],
+  },
+  s13: {
+    version: "s13",
+    decisions: [
+      {
+        id: "runtime-records-separate-goal-from-execution",
+        title: "Runtime Records Should Separate Goal from One Execution Attempt",
+        description:
+          "Background execution needs a record that describes the current run itself: status, timestamps, preview, and output location. That keeps the durable task goal separate from one live execution slot.",
+        alternatives:
+          "Reusing the same task record for both goal state and execution state saves one structure, but it blurs what is planned versus what is actively running right now.",
+        zh: {
+          title: "运行记录必须把目标和单次执行分开",
+          description:
+            "后台执行需要一份专门描述这次运行本身的记录，例如 status、时间戳、preview、output 位置。这样 durable task goal 和 live execution slot 才不会混在一起。",
+          alternatives:
+            "把 goal state 和 execution state 强行塞进同一条 task record 虽然省结构，但会模糊“计划中的工作”和“当前正在跑的这一趟执行”之间的边界。",
+        },
+        ja: {
+          title: "Runtime record は goal と単発実行を分けて持つべきだ",
+          description:
+            "background execution には、その実行自身を表す record が必要です。status、timestamp、preview、output location を持たせることで、durable task goal と live execution slot が混ざらなくなります。",
+          alternatives:
+            "goal state と execution state を 1 つの task record へ押し込むと構造は減りますが、「計画された仕事」と「今走っている 1 回の実行」の境界が曖昧になります。",
+        },
+      },
+      {
+        id: "notifications-carry-preview-not-full-output",
+        title: "Notifications Should Carry a Preview, Not the Full Log",
+        description:
+          "Large command output should be written to durable storage, while the notification only carries a compact preview. That preserves the return path into the main loop without flooding the active context window.",
+        alternatives:
+          "Injecting the full background log back into prompt space looks convenient, but it burns context and hides the difference between alerting the loop and storing the artifact.",
+        zh: {
+          title: "通知只带摘要，不直接带全文日志",
+          description:
+            "大输出应该写入持久存储，notification 只带一段 compact preview。这样既保住回到主循环的 return path，又不会把活跃上下文塞满。",
+          alternatives:
+            "把整份后台日志直接塞回 prompt 看起来省事，但会快速吃掉上下文，还会模糊“提醒主循环”和“保存原始产物”这两层职责。",
+        },
+        ja: {
+          title: "通知は全文ログではなく preview だけを運ぶべきだ",
+          description:
+            "大きな出力は durable storage に書き、notification には compact preview だけを載せるべきです。これで main loop へ戻る経路を保ちつつ、活性 context を膨らませずに済みます。",
+          alternatives:
+            "background log 全文を prompt へ戻すのは手軽ですが、context を急速に消費し、「loop への通知」と「artifact の保存」という 2 つの責務も混ざります。",
+        },
+      },
+    ],
+  },
+  s14: {
+    version: "s14",
+    decisions: [
+      {
+        id: "cron-only-triggers-runtime-work",
+        title: "Cron Should Trigger Runtime Work, Not Own Execution",
+        description:
+          "The scheduler's job is to decide when a rule matches. Once it does, it should create runtime work and hand execution off to the runtime layer. This preserves a clean boundary between time and work.",
+        alternatives:
+          "Letting cron directly execute task logic is tempting for small systems, but it mixes rule-matching with execution state and makes both harder to teach and debug.",
+        zh: {
+          title: "Cron 只负责触发，不直接承担执行",
+          description:
+            "调度器的职责是判断时间规则何时命中。命中后应创建 runtime work，再把执行交给运行时层。这样“时间”和“工作”两类职责边界才干净。",
+          alternatives:
+            "小系统里让 cron 直接执行业务逻辑很诱人，但会把规则匹配和执行状态搅在一起，教学和调试都会变难。",
+        },
+        ja: {
+          title: "Cron は発火だけを担当し、実行を抱え込まない",
+          description:
+            "scheduler の役割は時間規則がいつ一致するかを判断することです。一致したら runtime work を生成し、実行は runtime layer へ渡すべきです。これで「時間」と「仕事」の境界がきれいに保てます。",
+          alternatives:
+            "小さな system では cron がそのまま仕事を実行したくなりますが、rule matching と execution state が混ざり、学習にもデバッグにも不利です。",
+        },
+      },
+      {
+        id: "schedule-records-separate-from-runtime-records",
+        title: "Schedule Records Must Stay Separate from Runtime Records",
+        description:
+          "A schedule says what should trigger and when. A runtime record says what is currently running, queued, retried, or completed. Keeping them separate makes both time semantics and execution semantics clearer.",
+        alternatives:
+          "A single merged record reduces file count, but it blurs whether the system is reasoning about recurring policy or one concrete execution instance.",
+        zh: {
+          title: "调度记录与运行时记录必须分离",
+          description:
+            "schedule 记录的是“何时触发什么”，runtime record 记录的是“当前运行、排队、重试或完成到哪一步”。分开后，时间语义和执行语义都更清楚。",
+          alternatives:
+            "把两者合成一条记录看似省事，但会混淆系统此刻究竟在描述长期规则，还是某次具体执行实例。",
+        },
+        ja: {
+          title: "Schedule record と runtime record は分離すべきだ",
+          description:
+            "schedule は「いつ何を起動するか」を記録し、runtime record は「今どの実行が走り、待ち、再試行し、完了したか」を記録します。分けることで時間意味論と実行意味論の両方が明確になります。",
+          alternatives:
+            "両者を 1 レコードにまとめると楽そうですが、system が長期ルールを語っているのか、単発の実行インスタンスを語っているのかが分からなくなります。",
+        },
+      },
+    ],
+  },
+  s15: {
+    version: "s15",
+    decisions: [
+      {
+        id: "teammates-need-persistent-identity",
+        title: "Teammates Need Persistent Identity, Not One-Shot Delegation",
+        description:
+          "A teammate should keep a name, role, inbox, and status across multiple rounds of work. That persistence is what lets the platform assign responsibility instead of recreating a fresh subagent every time.",
+        alternatives:
+          "Disposable delegated workers are easier to implement, but they cannot carry stable responsibility or mailbox-based coordination over time.",
+        zh: {
+          title: "队友必须拥有长期身份，而不是一次性委派",
+          description:
+            "Teammate 应该在多轮工作之间保留名字、角色、inbox 和状态。只有这样，平台才能分配长期责任，而不是每次都重新创建一个临时 subagent。",
+          alternatives:
+            "一次性委派更容易实现，但它承载不了长期职责，也无法自然地进入 mailbox-based 协作。",
+        },
+        ja: {
+          title: "チームメイトには使い捨てではない継続的な身元が必要だ",
+          description:
+            "teammate は複数ラウンドにわたり、名前、役割、inbox、状態を保つべきです。そうして初めて platform は長期責任を割り当てられ、毎回新しい subagent を作り直さずに済みます。",
+          alternatives:
+            "使い捨ての委譲 worker は作りやすいですが、安定した責務も mailbox ベースの協調も持ち運べません。",
+        },
+      },
+      {
+        id: "mailboxes-keep-collaboration-bounded",
+        title: "Independent Mailboxes Keep Collaboration Legible",
+        description:
+          "Each teammate should coordinate through an inbox boundary rather than sharing one giant message history. That keeps ownership, message flow, and wake-up conditions easier to explain.",
+        alternatives:
+          "A shared message buffer looks simpler, but it erases agent boundaries and makes it harder to see who is responsible for what.",
+        zh: {
+          title: "独立邮箱边界让协作保持清晰",
+          description:
+            "每个队友都应该通过 inbox 边界协作，而不是共用一段巨大的消息历史。这样 ownership、消息流和唤醒条件才更容易讲清楚。",
+          alternatives:
+            "共享消息缓冲区看起来更简单，但会抹平 agent 边界，也更难解释到底谁在负责什么。",
+        },
+        ja: {
+          title: "独立 mailbox があると協調の境界が読みやすくなる",
+          description:
+            "各 teammate は巨大な共有 message history を使うのではなく、inbox 境界を通して協調すべきです。これで ownership、message flow、wake-up condition を説明しやすくなります。",
+          alternatives:
+            "共有 message buffer は単純そうですが、agent 境界を消してしまい、誰が何に責任を持つのかが見えにくくなります。",
+        },
+      },
+    ],
+  },
+  s16: {
+    version: "s16",
+    decisions: [
+      {
+        id: "protocols-need-request-correlation",
+        title: "Protocol Messages Need Request Correlation",
+        description:
+          "Structured workflows such as approvals or shutdowns need request_id correlation so every reply, timeout, or rejection can resolve against the right request.",
+        alternatives:
+          "Free-form reply text may work in a tiny demo, but it breaks as soon as several protocol flows exist at once.",
+        zh: {
+          title: "协议消息必须带请求关联 id",
+          description:
+            "审批、关机这类结构化工作流必须带 request_id，这样每条回复、超时或拒绝才能准确对应到正确请求。",
+          alternatives:
+            "自由文本回复在极小 demo 里还能凑合，但一旦同时存在多条协议流程，就很快会对不上号。",
+        },
+        ja: {
+          title: "プロトコルメッセージには request 相関 id が必要だ",
+          description:
+            "approval や shutdown のような構造化 workflow では request_id が必要です。そうして初めて各 reply、timeout、reject を正しい request に結び付けられます。",
+          alternatives:
+            "自由文の返答は極小 demo では動いても、複数の protocol flow が同時に走るとすぐ対応関係が崩れます。",
+        },
+      },
+      {
+        id: "request-state-should-be-durable",
+        title: "Request State Should Be Durable and Inspectable",
+        description:
+          "Pending, approved, rejected, or expired states belong in a durable request record, not only in memory. That makes protocol state recoverable, inspectable, and teachable.",
+        alternatives:
+          "In-memory trackers are quick to write, but they disappear too easily and hide the real object the system is coordinating around.",
+        zh: {
+          title: "请求状态必须可持久、可检查",
+          description:
+            "pending、approved、rejected、expired 这些状态应该写进 durable request record，而不是只存在内存里。这样协议状态才能恢复、检查，也更适合教学。",
+          alternatives:
+            "内存追踪表写起来很快，但太容易消失，也会把系统真正围绕的对象藏起来。",
+        },
+        ja: {
+          title: "Request state は永続化され、検査できるべきだ",
+          description:
+            "pending、approved、rejected、expired のような状態は durable request record に書くべきで、memory の中だけに置いてはいけません。そうすることで protocol state が回復可能・可視化可能になります。",
+          alternatives:
+            "in-memory tracker はすぐ書けますが、消えやすく、system が本当に中心にしている object も隠してしまいます。",
+        },
+      },
+    ],
+  },
+  s17: {
+    version: "s17",
+    decisions: [
+      {
+        id: "autonomy-starts-with-bounded-claim-rules",
+        title: "Autonomy Starts with Bounded Claim Rules",
+        description:
+          "Workers should only self-claim work when clear policies say they may do so. That prevents autonomy from turning into race conditions or duplicate execution.",
+        alternatives:
+          "Letting every idle worker grab anything looks energetic, but it makes the platform unpredictable. Claim rules keep autonomy controlled.",
+        zh: {
+          title: "自治从有边界的认领规则开始",
+          description:
+            "只有在明确策略允许的情况下，worker 才应该 self-claim 工作。这样才能避免自治变成撞车或重复执行。",
+          alternatives:
+            "让所有空闲 worker 见活就抢看起来很积极，但平台会变得不可预测。Claim rule 才能让自治保持可控。",
+        },
+        ja: {
+          title: "自律は境界のある claim rule から始まる",
+          description:
+            "worker が self-claim してよいのは、明確な policy が許すときだけにすべきです。そうしないと autonomy は race condition や重複実行へ変わります。",
+          alternatives:
+            "空いている worker が何でも取りに行く設計は勢いがあるように見えますが、platform は予測不能になります。claim rule があって初めて自律を制御できます。",
+        },
+      },
+      {
+        id: "resume-must-come-from-visible-state",
+        title: "Resumption Must Come from Visible State",
+        description:
+          "A worker should resume from task state, protocol state, mailbox contents, and role state. That keeps autonomy explainable instead of making it look like spontaneous intuition.",
+        alternatives:
+          "Implicit resume logic hides too much. Visible state may feel verbose, but it is what makes autonomous behavior debuggable.",
+        zh: {
+          title: "恢复执行必须建立在可见状态上",
+          description:
+            "Worker 应该根据 task state、protocol state、mailbox 内容和角色状态恢复执行。这样自治才可解释，而不是看起来像神秘直觉。",
+          alternatives:
+            "隐式恢复逻辑会把太多关键条件藏起来。可见状态虽然更啰嗦，但能让自治行为真正可调试。",
+        },
+        ja: {
+          title: "再開は見える state から始まるべきだ",
+          description:
+            "worker は task state、protocol state、mailbox 内容、role state をもとに実行を再開すべきです。そうすることで autonomy は説明可能になり、謎の直感のようには見えません。",
+          alternatives:
+            "暗黙の resume ロジックは重要条件を隠しすぎます。visible state は少し冗長でも、自律挙動を本当にデバッグ可能にします。",
+        },
+      },
+    ],
+  },
+  s18: {
+    version: "s18",
+    decisions: [
+      {
+        id: "worktree-is-a-lane-not-the-task",
+        title: "A Worktree Is an Execution Lane, Not the Task Itself",
+        description:
+          "Tasks describe goals and dependency state. Worktrees describe isolated directories where execution happens. Keeping those two objects separate prevents the runtime model from blurring.",
+        alternatives:
+          "Collapsing task and worktree into one object removes one layer, but it becomes harder to explain whether the system is talking about work intent or execution environment.",
+        zh: {
+          title: "Worktree 是执行车道，不是任务本身",
+          description:
+            "Task 描述目标和依赖状态，worktree 描述隔离执行发生在哪个目录里。把两者分开，运行时模型才不会糊成一团。",
+          alternatives:
+            "把 task 和 worktree 硬合成一个对象虽然少一层，但会让系统很难解释当前说的是工作意图还是执行环境。",
+        },
+        ja: {
+          title: "Worktree は task そのものではなく execution lane だ",
+          description:
+            "task は goal と dependency state を表し、worktree は隔離された実行ディレクトリを表します。この 2 つを分けることで runtime model が曖昧になりません。",
+          alternatives:
+            "task と worktree を 1 つの object に潰すと層は減りますが、system が work intent を語っているのか execution environment を語っているのか分かりにくくなります。",
+        },
+      },
+      {
+        id: "closeout-needs-explicit-keep-remove-semantics",
+        title: "Closeout Needs Explicit Keep / Remove Semantics",
+        description:
+          "After isolated work finishes, the system should explicitly decide whether that lane is kept for follow-up or reclaimed. That makes lifecycle state observable instead of accidental.",
+        alternatives:
+          "Implicit cleanup feels automatic, but it hides important execution-lane decisions. Explicit closeout semantics teach the lifecycle much more clearly.",
+        zh: {
+          title: "收尾阶段必须显式决定保留还是回收",
+          description:
+            "隔离工作结束后，系统应该显式决定这个 lane 是继续保留给后续工作，还是立即回收。这样生命周期状态才可见，而不是碰运气。",
+          alternatives:
+            "隐式清理看起来很自动，但会把很多关键执行车道决策藏起来。显式 closeout 语义更适合教学，也更利于调试。",
+        },
+        ja: {
+          title: "Closeout では保持か回収かを明示的に決めるべきだ",
+          description:
+            "隔離作業が終わった後、その lane を次の作業のために保持するのか、すぐ回収するのかを system が明示的に決めるべきです。これで lifecycle state が運任せではなく見える状態になります。",
+          alternatives:
+            "暗黙 cleanup は自動に見えますが、重要な execution-lane 判断を隠してしまいます。explicit closeout semantics の方が、学習にもデバッグにも向いています。",
+        },
+      },
+    ],
+  },
+  s19: {
+    version: "s19",
+    decisions: [
+      {
+        id: "external-capabilities-share-one-routing-model",
+        title: "External Capabilities Should Share the Same Routing Model as Native Tools",
+        description:
+          "Plugins and MCP servers should enter through the same capability-routing surface as native tools. That means discovery, routing, permission, execution, and result normalization all stay conceptually aligned.",
+        alternatives:
+          "Building a parallel external-capability subsystem may feel cleaner at first, but it doubles the mental model. One routing model keeps the platform understandable.",
+        zh: {
+          title: "外部能力必须共享同一套路由模型",
+          description:
+            "Plugin 和 MCP server 都应该从与本地工具相同的 capability routing 入口进入系统。这样发现、路由、权限、执行、结果标准化才保持同一心智。",
+          alternatives:
+            "单独给外部能力再造一套系统看似整洁，实际会把平台心智翻倍。共享一套 routing model 才更可教、也更可维护。",
+        },
+        ja: {
+          title: "外部 capability は native tool と同じ routing model を共有すべきだ",
+          description:
+            "plugin と MCP server は、native tool と同じ capability routing surface から system へ入るべきです。そうすることで discovery、routing、permission、execution、result normalization が 1 つの心智に揃います。",
+          alternatives:
+            "外部 capability 用に並列 subsystem を作ると最初は整って見えますが、学習モデルが二重になります。1 つの routing model の方が platform を理解しやすく保てます。",
+        },
+      },
+      {
+        id: "scope-external-capabilities",
+        title: "External Capabilities Need Scope and Policy Boundaries",
+        description:
+          "Remote capability does not mean unrestricted capability. Servers, plugins, and credentials need explicit workspace or session scopes so the platform can explain who can call what and why.",
+        alternatives:
+          "Global capability exposure is easier to wire up, but it weakens permission reasoning. Scoped capability access adds a small amount of configuration and a large amount of clarity.",
+        zh: {
+          title: "外部能力必须带作用域和策略边界",
+          description:
+            "远程能力不代表无限能力。server、plugin、credential 都要有 workspace 或 session 级作用域，平台才解释得清楚“谁能调用什么，为什么能调”。",
+          alternatives:
+            "全局暴露所有外部能力接起来最简单，但会削弱权限推理。增加一点 scope 配置，却能换来大量清晰度。",
+        },
+        ja: {
+          title: "外部 capability には scope と policy の境界が必要だ",
+          description:
+            "remote capability だからといって無制限 capability ではありません。server、plugin、credential には workspace あるいは session scope が必要で、誰が何を呼べるのか、なぜ呼べるのかを platform が説明できるようにする必要があります。",
+          alternatives:
+            "すべての外部 capability をグローバル公開するのが最も配線は簡単ですが、permission reasoning が弱くなります。少しの scope 設定で、大きな明瞭さが得られます。",
+        },
+      },
+    ],
+  },
+};
+
 interface DesignDecisionsProps {
   version: string;
 }
@@ -63,10 +713,13 @@ function DecisionCard({
   const t = useTranslations("version");
 
   const localized =
-    locale !== "en" ? (decision as unknown as Record<string, unknown>)[locale] as { title?: string; description?: string } | undefined : undefined;
+    locale !== "en"
+      ? ((decision as unknown as Record<string, unknown>)[locale] as DecisionLocaleCopy | undefined)
+      : undefined;
 
   const title = localized?.title || decision.title;
   const description = localized?.description || decision.description;
+  const alternatives = localized?.alternatives || decision.alternatives;
 
   return (
     <div className="rounded-lg border border-zinc-200 bg-white dark:border-zinc-700 dark:bg-zinc-900">
@@ -100,13 +753,13 @@ function DecisionCard({
                 {description}
               </p>
 
-              {decision.alternatives && (
+              {alternatives && (
                 <div className="mt-3">
                   <h4 className="text-xs font-medium uppercase tracking-wide text-zinc-400 dark:text-zinc-500">
                     {t("alternatives")}
                   </h4>
                   <p className="mt-1 text-sm leading-relaxed text-zinc-500 dark:text-zinc-400">
-                    {decision.alternatives}
+                    {alternatives}
                   </p>
                 </div>
               )}
@@ -122,7 +775,10 @@ export function DesignDecisions({ version }: DesignDecisionsProps) {
   const t = useTranslations("version");
   const locale = useLocale();
 
-  const annotations = ANNOTATIONS[version];
+  const annotations = isGenericAnnotationVersion(version)
+    ? GENERIC_ANNOTATIONS[version]
+    : ANNOTATIONS[resolveLegacySessionAssetVersion(version)];
+
   if (!annotations || annotations.decisions.length === 0) {
     return null;
   }
diff --git a/web/src/components/architecture/execution-flow.tsx b/web/src/components/architecture/execution-flow.tsx
index efeb1b77f..0e7dca873 100644
--- a/web/src/components/architecture/execution-flow.tsx
+++ b/web/src/components/architecture/execution-flow.tsx
@@ -1,15 +1,17 @@
 "use client";
 
-import { useEffect, useState } from "react";
 import { motion } from "framer-motion";
 import { getFlowForVersion } from "@/data/execution-flows";
+import { getChapterGuide } from "@/lib/chapter-guides";
+import { useLocale } from "@/lib/i18n";
+import { pickDiagramText, translateFlowText } from "@/lib/diagram-localization";
 import type { FlowNode, FlowEdge } from "@/types/agent-data";
 
 const NODE_WIDTH = 140;
 const NODE_HEIGHT = 40;
 const DIAMOND_SIZE = 50;
 
-const LAYER_COLORS: Record<string, string> = {
+const NODE_COLORS: Record<string, string> = {
   start: "#3B82F6",
   process: "#10B981",
   decision: "#F59E0B",
@@ -17,6 +19,85 @@ const LAYER_COLORS: Record<string, string> = {
   end: "#EF4444",
 };
 
+const NODE_GUIDE = {
+  start: {
+    title: { zh: "入口", en: "Entry", ja: "入口" },
+    note: {
+      zh: "这轮从哪里开始进入系统。",
+      en: "Where the current turn enters the system.",
+      ja: "このターンがどこから入るかを示します。",
+    },
+  },
+  process: {
+    title: { zh: "主处理", en: "Process", ja: "主処理" },
+    note: {
+      zh: "系统内部稳定推进的一步。",
+      en: "A stable internal processing step.",
+      ja: "システム内部で安定して進む一段です。",
+    },
+  },
+  decision: {
+    title: { zh: "分叉判断", en: "Decision", ja: "分岐判断" },
+    note: {
+      zh: "系统在这里决定往哪条分支走。",
+      en: "Where the system chooses a branch.",
+      ja: "ここでどの分岐へ進むかを決めます。",
+    },
+  },
+  subprocess: {
+    title: { zh: "子流程 / 外部车道", en: "Subprocess / Lane", ja: "子過程 / 外部レーン" },
+    note: {
+      zh: "常见于外部执行、侧车流程或隔离车道。",
+      en: "Often used for external execution, sidecars, or isolated lanes.",
+      ja: "外部実行、サイドカー、隔離レーンなどでよく現れます。",
+    },
+  },
+  end: {
+    title: { zh: "回流 / 结束", en: "Write-back / End", ja: "回流 / 終了" },
+    note: {
+      zh: "这轮在这里结束或回到主循环。",
+      en: "Where the turn ends or writes back into the loop.",
+      ja: "このターンが終わるか、主ループへ戻る場所です。",
+    },
+  },
+} as const;
+
+const UI_TEXT = {
+  readLabel: { zh: "读图方式", en: "How to Read", ja: "読み方" },
+  readTitle: {
+    zh: "先看主线回流，再看左右分支",
+    en: "Read the mainline first, then inspect the side branches",
+    ja: "まず主線の回流を見て、その後で左右の分岐を見る",
+  },
+  readNote: {
+    zh: "从上往下看时间顺序，中间通常是主线，左右是分支、隔离车道或恢复路径。真正重要的不是节点有多少，而是这一章新增的分叉与回流在哪里。",
+    en: "Read top to bottom for time order. The center usually carries the mainline, while the sides hold branches, isolated lanes, or recovery paths. The key question is not how many nodes exist, but where this chapter introduces a new split and write-back.",
+    ja: "上から下へ時間順に読みます。中央は主線、左右は分岐・隔離レーン・回復経路です。大事なのはノード数ではなく、この章で新しく増えた分岐と回流がどこかです。",
+  },
+  focusLabel: { zh: "本章先盯住", en: "Focus First", ja: "まず注目" },
+  confusionLabel: { zh: "最容易混", en: "Easy to Confuse", ja: "混同しやすい点" },
+  goalLabel: { zh: "学完要会", en: "Build Goal", ja: "学習ゴール" },
+  legendLabel: { zh: "节点图例", en: "Node Legend", ja: "ノード凡例" },
+  laneTitle: { zh: "版面分区", en: "Visual Lanes", ja: "レーン区分" },
+  mainline: { zh: "主线", en: "Mainline", ja: "主線" },
+  mainlineNote: {
+    zh: "系统当前回合反复回到的那条路径。",
+    en: "The path the system keeps returning to during the turn.",
+    ja: "システムがこのターン中に繰り返し戻る経路です。",
+  },
+  sideLane: { zh: "分支 / 侧车", en: "Branch / Side Lane", ja: "分岐 / サイドレーン" },
+  sideLaneNote: {
+    zh: "权限分支、自治扫描、后台槽位、worktree 车道常在这里展开。",
+    en: "Permission branches, autonomy scans, background slots, and worktree lanes often expand here.",
+    ja: "権限分岐、自治スキャン、バックグラウンドスロット、worktree レーンはここで展開されます。",
+  },
+  bottomNote: {
+    zh: "虚线边框通常表示子流程或外部车道；箭头标签说明当前分叉为什么发生。",
+    en: "Dashed borders usually indicate a subprocess or external lane; arrow labels explain why a branch was taken.",
+    ja: "破線の枠は子過程や外部レーンを示すことが多く、矢印ラベルはなぜ分岐したかを示します。",
+  },
+} as const;
+
 function getNodeCenter(node: FlowNode): { cx: number; cy: number } {
   return { cx: node.x, cy: node.y };
 }
@@ -41,7 +122,7 @@ function getEdgePath(from: FlowNode, to: FlowNode): string {
 }
 
 function NodeShape({ node }: { node: FlowNode }) {
-  const color = LAYER_COLORS[node.type];
+  const color = NODE_COLORS[node.type];
   const lines = node.label.split("\n");
 
   if (node.type === "decision") {
@@ -137,10 +218,12 @@ function EdgePath({
   edge,
   nodes,
   index,
+  locale,
 }: {
   edge: FlowEdge;
   nodes: FlowNode[];
   index: number;
+  locale: string;
 }) {
   const from = nodes.find((n) => n.id === edge.from);
   const to = nodes.find((n) => n.id === edge.to);
@@ -173,7 +256,7 @@ function EdgePath({
           animate={{ opacity: 1 }}
           transition={{ delay: index * 0.12 + 0.3 }}
         >
-          {edge.label}
+          {translateFlowText(locale, edge.label)}
         </motion.text>
       )}
     </g>
@@ -185,54 +268,180 @@ interface ExecutionFlowProps {
 }
 
 export function ExecutionFlow({ version }: ExecutionFlowProps) {
-  const [flow, setFlow] = useState<ReturnType<typeof getFlowForVersion>>(null);
-
-  useEffect(() => {
-    setFlow(getFlowForVersion(version));
-  }, [version]);
+  const locale = useLocale();
+  const flow = getFlowForVersion(version);
+  const guide = getChapterGuide(version, locale) ?? getChapterGuide(version, "en");
 
   if (!flow) return null;
 
   const maxY = Math.max(...flow.nodes.map((n) => n.y)) + 50;
 
   return (
-    <div className="overflow-x-auto rounded-xl border border-[var(--color-border)] bg-[var(--color-bg)] p-4">
-      <svg
-        viewBox={`0 0 600 ${maxY}`}
-        className="mx-auto w-full max-w-[600px]"
-        style={{ minHeight: 300 }}
-      >
-        <defs>
-          <marker
-            id="arrowhead"
-            markerWidth={8}
-            markerHeight={6}
-            refX={8}
-            refY={3}
-            orient="auto"
-          >
-            <polygon
-              points="0 0, 8 3, 0 6"
-              fill="var(--color-text-secondary)"
-            />
-          </marker>
-        </defs>
-
-        {flow.edges.map((edge, i) => (
-          <EdgePath key={`${edge.from}-${edge.to}`} edge={edge} nodes={flow.nodes} index={i} />
-        ))}
+    <div className="overflow-hidden rounded-[28px] border border-zinc-200/80 bg-white/95 shadow-sm dark:border-zinc-800/80 dark:bg-zinc-950/90">
+      <div className="grid gap-4 border-b border-zinc-200/80 px-5 py-5 dark:border-zinc-800/80 sm:px-6 lg:grid-cols-[1.35fr_0.95fr]">
+        <div className="space-y-4">
+          <div>
+            <p className="text-xs uppercase tracking-[0.22em] text-zinc-400">
+              {pickDiagramText(locale, UI_TEXT.readLabel)}
+            </p>
+            <h3 className="mt-3 text-lg font-semibold tracking-tight text-zinc-950 dark:text-zinc-50">
+              {pickDiagramText(locale, UI_TEXT.readTitle)}
+            </h3>
+            <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+              {pickDiagramText(locale, UI_TEXT.readNote)}
+            </p>
+          </div>
 
-        {flow.nodes.map((node, i) => (
-          <motion.g
-            key={node.id}
-            initial={{ opacity: 0, y: -10 }}
-            animate={{ opacity: 1, y: 0 }}
-            transition={{ delay: i * 0.06, duration: 0.3 }}
-          >
-            <NodeShape node={node} />
-          </motion.g>
-        ))}
-      </svg>
+          {guide && (
+            <div className="grid gap-3 xl:grid-cols-3">
+              <div className="rounded-2xl border border-emerald-200/70 bg-emerald-50/80 p-4 dark:border-emerald-900/60 dark:bg-emerald-950/20">
+                <p className="text-[11px] font-medium uppercase tracking-[0.2em] text-emerald-700/80 dark:text-emerald-300/80">
+                  {pickDiagramText(locale, UI_TEXT.focusLabel)}
+                </p>
+                <p className="mt-2 text-sm leading-6 text-zinc-700 dark:text-zinc-200">
+                  {guide.focus}
+                </p>
+              </div>
+              <div className="rounded-2xl border border-amber-200/70 bg-amber-50/80 p-4 dark:border-amber-900/60 dark:bg-amber-950/20">
+                <p className="text-[11px] font-medium uppercase tracking-[0.2em] text-amber-700/80 dark:text-amber-300/80">
+                  {pickDiagramText(locale, UI_TEXT.confusionLabel)}
+                </p>
+                <p className="mt-2 text-sm leading-6 text-zinc-700 dark:text-zinc-200">
+                  {guide.confusion}
+                </p>
+              </div>
+              <div className="rounded-2xl border border-sky-200/70 bg-sky-50/80 p-4 dark:border-sky-900/60 dark:bg-sky-950/20">
+                <p className="text-[11px] font-medium uppercase tracking-[0.2em] text-sky-700/80 dark:text-sky-300/80">
+                  {pickDiagramText(locale, UI_TEXT.goalLabel)}
+                </p>
+                <p className="mt-2 text-sm leading-6 text-zinc-700 dark:text-zinc-200">
+                  {guide.goal}
+                </p>
+              </div>
+            </div>
+          )}
+        </div>
+
+        <div className="space-y-3">
+          <p className="text-xs uppercase tracking-[0.22em] text-zinc-400">
+            {pickDiagramText(locale, UI_TEXT.legendLabel)}
+          </p>
+          <div className="space-y-2">
+            {(
+              Object.keys(NODE_GUIDE) as Array<keyof typeof NODE_GUIDE>
+            ).map((nodeType) => (
+              <div
+                key={nodeType}
+                className="rounded-2xl border border-zinc-200/80 bg-zinc-50/80 p-3 dark:border-zinc-800/80 dark:bg-zinc-900/70"
+              >
+                <div className="flex items-center gap-2">
+                  <span
+                    className="h-2.5 w-2.5 rounded-full"
+                    style={{ backgroundColor: NODE_COLORS[nodeType] }}
+                  />
+                  <span className="text-sm font-medium text-zinc-900 dark:text-zinc-100">
+                    {pickDiagramText(locale, NODE_GUIDE[nodeType].title)}
+                  </span>
+                </div>
+                <p className="mt-1 text-xs leading-5 text-zinc-500 dark:text-zinc-400">
+                  {pickDiagramText(locale, NODE_GUIDE[nodeType].note)}
+                </p>
+              </div>
+            ))}
+          </div>
+        </div>
+      </div>
+
+      <div className="overflow-x-auto px-4 py-5 sm:px-6">
+        <div className="min-w-[640px]">
+          <div className="mb-4 grid grid-cols-3 gap-3">
+            <div className="rounded-2xl border border-zinc-200/70 bg-zinc-50/70 px-3 py-2.5 dark:border-zinc-800/70 dark:bg-zinc-900/60">
+              <p className="text-xs font-semibold uppercase tracking-[0.18em] text-zinc-500 dark:text-zinc-400">
+                {pickDiagramText(locale, UI_TEXT.sideLane)}
+              </p>
+              <p className="mt-1 text-xs leading-5 text-zinc-500 dark:text-zinc-400">
+                {pickDiagramText(locale, UI_TEXT.sideLaneNote)}
+              </p>
+            </div>
+            <div className="rounded-2xl border border-blue-200/70 bg-blue-50/70 px-3 py-2.5 dark:border-blue-900/60 dark:bg-blue-950/20">
+              <p className="text-xs font-semibold uppercase tracking-[0.18em] text-blue-700 dark:text-blue-300">
+                {pickDiagramText(locale, UI_TEXT.mainline)}
+              </p>
+              <p className="mt-1 text-xs leading-5 text-zinc-600 dark:text-zinc-300">
+                {pickDiagramText(locale, UI_TEXT.mainlineNote)}
+              </p>
+            </div>
+            <div className="rounded-2xl border border-zinc-200/70 bg-zinc-50/70 px-3 py-2.5 dark:border-zinc-800/70 dark:bg-zinc-900/60">
+              <p className="text-xs font-semibold uppercase tracking-[0.18em] text-zinc-500 dark:text-zinc-400">
+                {pickDiagramText(locale, UI_TEXT.sideLane)}
+              </p>
+              <p className="mt-1 text-xs leading-5 text-zinc-500 dark:text-zinc-400">
+                {pickDiagramText(locale, UI_TEXT.sideLaneNote)}
+              </p>
+            </div>
+          </div>
+
+          <div className="relative overflow-hidden rounded-[24px] border border-zinc-200/80 bg-[linear-gradient(180deg,rgba(255,255,255,0.98),rgba(244,244,245,0.92))] dark:border-zinc-800/80 dark:bg-[linear-gradient(180deg,rgba(24,24,27,0.96),rgba(9,9,11,0.92))]">
+            <div className="pointer-events-none absolute inset-0 grid grid-cols-3 gap-3 p-3">
+              <div className="rounded-[20px] bg-zinc-100/60 dark:bg-zinc-900/40" />
+              <div className="rounded-[20px] bg-blue-50/70 dark:bg-blue-950/20" />
+              <div className="rounded-[20px] bg-zinc-100/60 dark:bg-zinc-900/40" />
+            </div>
+
+            <svg
+              viewBox={`0 0 600 ${maxY}`}
+              className="relative mx-auto w-full max-w-[600px]"
+              style={{ minHeight: 320 }}
+            >
+              <defs>
+                <marker
+                  id="arrowhead"
+                  markerWidth={8}
+                  markerHeight={6}
+                  refX={8}
+                  refY={3}
+                  orient="auto"
+                >
+                  <polygon
+                    points="0 0, 8 3, 0 6"
+                    fill="var(--color-text-secondary)"
+                  />
+                </marker>
+              </defs>
+
+              {flow.edges.map((edge, i) => (
+                <EdgePath
+                  key={`${edge.from}-${edge.to}`}
+                  edge={edge}
+                  nodes={flow.nodes}
+                  index={i}
+                  locale={locale}
+                />
+              ))}
+
+              {flow.nodes.map((node, i) => (
+                <motion.g
+                  key={node.id}
+                  initial={{ opacity: 0, y: -10 }}
+                  animate={{ opacity: 1, y: 0 }}
+                  transition={{ delay: i * 0.06, duration: 0.3 }}
+                >
+                  <NodeShape
+                    node={{
+                      ...node,
+                      label: translateFlowText(locale, node.label),
+                    }}
+                  />
+                </motion.g>
+              ))}
+            </svg>
+          </div>
+
+          <p className="mt-4 text-xs leading-5 text-zinc-500 dark:text-zinc-400">
+            {pickDiagramText(locale, UI_TEXT.bottomNote)}
+          </p>
+        </div>
+      </div>
     </div>
   );
 }
diff --git a/web/src/components/architecture/mechanism-lenses.tsx b/web/src/components/architecture/mechanism-lenses.tsx
new file mode 100644
index 000000000..20e70fc0a
--- /dev/null
+++ b/web/src/components/architecture/mechanism-lenses.tsx
@@ -0,0 +1,1288 @@
+import type { VersionId } from "@/lib/constants";
+
+type LocaleText = {
+  zh: string;
+  en: string;
+  ja: string;
+};
+
+interface VersionMechanismLensesProps {
+  version: string;
+  locale: string;
+}
+
+const SECTION_TEXT = {
+  label: {
+    zh: "关键机制镜头",
+    en: "Mechanism Lens",
+    ja: "重要メカニズムの見取り図",
+  },
+  title: {
+    zh: "把本章最容易打结的一层单独拆开",
+    en: "Pull out the one mechanism most likely to tangle in this chapter",
+    ja: "この章で最も混線しやすい層を単独でほどく",
+  },
+  body: {
+    zh: "这不是重复正文，而是把真正关键的运行规则、状态边界和回流方向压成一张能反复回看的教学图。先看这里，再回正文，会更容易守住主线。",
+    en: "This does not replace the chapter body. It compresses the most important runtime rule, state boundary, and write-back path into one reusable teaching view.",
+    ja: "本文の繰り返しではなく、重要な runtime rule・state boundary・write-back path を一枚に圧縮した補助図です。ここを先に見ると本文の主線を保ちやすくなります。",
+  },
+} as const;
+
+const TOOL_RUNTIME_VERSION_ANGLE: Partial<Record<VersionId, LocaleText>> = {
+  s02: {
+    zh: "这一章第一次把 model 的 tool intent 接进统一执行面，所以重点不是“多了几个工具”，而是“调用如何进入稳定 runtime”。",
+    en: "This is the first chapter where model tool intent enters one execution plane. The point is not just more tools, but a stable runtime entry path.",
+    ja: "この章では model の tool intent が初めて 1 つの execution plane に入ります。増えた tool よりも、安定した runtime 入口を作ることが主題です。",
+  },
+  s07: {
+    zh: "权限系统不是独立岛屿，它是插在真正执行之前的一道 runtime 闸门。",
+    en: "The permission system is not an isolated island. It is a runtime gate inserted before real execution.",
+    ja: "権限層は独立した島ではなく、実行直前に差し込まれる安全ゲートです。",
+  },
+  s13: {
+    zh: "后台任务会让结果不再总是当前 turn 立即回写，所以你必须开始把执行槽位和回流顺序分开看。",
+    en: "Background tasks mean results do not always write back in the same turn, so execution slots and write-back order must become separate ideas.",
+    ja: "バックグラウンド実行が入ると、結果は同じ turn に即時回写されるとは限りません。だから実行スロットと回写順序を分けて見る必要があります。",
+  },
+  s19: {
+    zh: "到了 MCP 与 Plugin，这一层的重点是：本地工具、插件和外部 server 虽然来源不同，但最终都要回到同一执行面。",
+    en: "With MCP and plugins, the key is that native tools, plugins, and external servers may come from different places but still return to one execution plane.",
+    ja: "MCP と plugin の段階では、native tool・plugin・外部 server が出自は違っても最終的には同じ execution plane へ戻ることが重要です。",
+  },
+};
+
+const QUERY_TRANSITION_VERSION_ANGLE: Partial<Record<VersionId, LocaleText>> = {
+  s06: {
+    zh: "压缩刚出现时，读者很容易还把 query 想成一个 while loop。这一章开始就该意识到：状态已经会影响下一轮为什么继续。",
+    en: "When compaction first appears, readers still tend to picture a plain while-loop. This is where state starts changing why the next turn exists.",
+    ja: "compact が出た直後は query を単なる while loop と見がちです。しかしこの章から、state が次の turn の存在理由を変え始めます。",
+  },
+  s11: {
+    zh: "错误恢复真正提升系统完成度的地方，不是 try/except，而是系统能明确写出这次继续、重试或结束的原因。",
+    en: "What really raises completion in recovery is not `try/except`, but the system knowing exactly why it continues, retries, or stops.",
+    ja: "error recovery で完成度を押し上げるのは try/except そのものではなく、なぜ continue・retry・stop するのかを明示できる点です。",
+  },
+  s17: {
+    zh: "自治车道会自己认领和恢复任务，所以 transition reason 不再只是单 agent 的内部细节，而是自治行为的稳定器。",
+    en: "Autonomous lanes claim and resume work on their own, so transition reasons stop being an internal detail and become part of the system stabilizer.",
+    ja: "自治レーンは自分で task を claim・resume するため、transition reason は単 agent の内部 detail ではなく、自治動作を安定化する要素になります。",
+  },
+};
+
+const TASK_RUNTIME_VERSION_ANGLE: Partial<Record<VersionId, LocaleText>> = {
+  s12: {
+    zh: "这一章只建立 durable work graph。现在最重要的护栏是：先把“目标任务”讲干净，不要提前把后台执行槽位塞进来。",
+    en: "This chapter only establishes the durable work graph. The main guardrail is to keep goal tasks clean before you push runtime execution slots into the same model.",
+    ja: "この章では durable work graph だけを作ります。最大のガードレールは、バックグラウンド実行スロットを混ぜる前に作業目標タスクをきれいに保つことです。",
+  },
+  s13: {
+    zh: "后台任务真正新增的不是“又一种任务”，而是“任务目标之外，还要单独管理一层活着的执行槽位”。",
+    en: "Background tasks do not add just another task. They add a second layer of live execution slots outside the task goal itself.",
+    ja: "バックグラウンド実行が増やすのは task の別名ではなく、作業目標の外にある live execution slot という別層です。",
+  },
+  s14: {
+    zh: "到了定时调度，读者最容易把 schedule、task、runtime slot 混成一团，所以必须把“谁定义目标、谁负责触发、谁真正执行”拆开看。",
+    en: "Cron scheduling is where schedule, task, and runtime slot start to blur together. The safe mental model is to separate who defines the goal, who triggers it, and who actually executes.",
+    ja: "cron に入ると schedule・task・runtime slot が混ざりやすくなります。goal を定義する層、発火させる層、実行する層を分けて見る必要があります。",
+  },
+};
+
+const TEAM_BOUNDARY_VERSION_ANGLE: Partial<Record<VersionId, LocaleText>> = {
+  s15: {
+    zh: "这章的重点不是“多开几个 agent”，而是让系统第一次拥有长期存在、可重复协作的 teammate 身份层。",
+    en: "The point of this chapter is not merely more agents. It is the first time the system gains persistent teammate identities that can collaborate repeatedly.",
+    ja: "この章の要点は agent を増やすことではなく、反復して協調できる persistent teammate identity を初めて持つことです。",
+  },
+  s16: {
+    zh: "团队协议真正新增的是“可追踪的协调请求层”，不是普通聊天消息的花样变体。",
+    en: "Team protocols introduce a traceable coordination-request layer, not just another style of chat message.",
+    ja: "team protocol が増やすのは追跡可能な協調要求レイヤーであり、普通の chat message の変種ではありません。",
+  },
+  s17: {
+    zh: "自治行为最容易讲糊的地方，是 teammate、task、runtime slot 三层同时动起来。所以这一章必须盯紧“谁在认领、谁在执行、谁在记录目标”。",
+    en: "Autonomy becomes confusing when teammate, task, and runtime slot all move at once. This chapter must keep clear who is claiming, who is executing, and who records the goal.",
+    ja: "autonomy で混線しやすいのは teammate・task・runtime slot が同時に動き出す点です。誰が claim し、誰が execute し、誰が goal を記録しているかを保つ必要があります。",
+  },
+  s18: {
+    zh: "worktree 最容易被误解成另一种任务，其实它只是执行目录车道。任务管目标，runtime slot 管执行，worktree 管在哪做。",
+    en: "Worktrees are easy to misread as another kind of task, but they are execution-directory lanes. Tasks manage goals, runtime slots manage execution, and worktrees manage where execution happens.",
+    ja: "worktree は別種の task と誤解されがちですが、実際は実行ディレクトリのレーンです。task は goal、runtime slot は execution、worktree はどこで実行するかを管理します。",
+  },
+};
+
+const CAPABILITY_LAYER_VERSION_ANGLE: Partial<Record<VersionId, LocaleText>> = {
+  s19: {
+    zh: "这一章正文仍应坚持 tools-first，但页面必须额外提醒读者：MCP 平台真正长出来后，tools 只是 capability stack 里最先进入主线的那一层。",
+    en: "The chapter body should still stay tools-first, but the page should also remind readers that once the MCP platform grows up, tools are only the first layer of the capability stack to enter the mainline.",
+    ja: "本文は引き続き tools-first でよい一方、ページ上では tools が capability stack の最初の層にすぎないことも明示すべきです。",
+  },
+};
+
+const TOOL_RUNTIME_TEXT = {
+  label: {
+    zh: "工具执行运行时",
+    en: "Tool Execution Runtime",
+    ja: "ツール実行の流れ",
+  },
+  title: {
+    zh: "不要把工具调用压扁成“handler 一跑就完”",
+    en: "Do not flatten tool calls into one handler invocation",
+    ja: "tool call を単なる handler 呼び出しに潰さない",
+  },
+  note: {
+    zh: "更完整的系统，会先判断这些 tool block 应该怎么分批、怎么执行、怎么稳定回写，而不是一股脑直接跑。",
+    en: "A more complete system first decides how tool blocks should be batched, executed, and written back instead of running everything immediately.",
+    ja: "より構造の整った system は、tool block を即座に全部走らせるのではなく、どう batch 化し、どう実行し、どう安定回写するかを先に決めます。",
+  },
+  angleLabel: {
+    zh: "本章为什么要盯这层",
+    en: "Why This Lens Matters Here",
+    ja: "この章でこの層を見る理由",
+  },
+  rulesLabel: {
+    zh: "运行规则",
+    en: "Runtime Rules",
+    ja: "実行ルール",
+  },
+  recordsLabel: {
+    zh: "核心记录",
+    en: "Core Records",
+    ja: "主要レコード",
+  },
+  safeLane: {
+    title: {
+      zh: "Safe 批次",
+      en: "Safe Batch",
+      ja: "安全バッチ",
+    },
+    body: {
+      zh: "读多写少、共享状态风险低的工具可以并发执行，但 progress 和 context modifier 仍然要被跟踪。",
+      en: "Read-heavy, low-risk tools can execute concurrently, but progress and context modifiers still need tracking.",
+      ja: "読み取り中心で共有 state リスクの低い tool は並列実行できますが、progress と context modifier の追跡は必要です。",
+    },
+  },
+  exclusiveLane: {
+    title: {
+      zh: "Exclusive 批次",
+      en: "Exclusive Batch",
+      ja: "直列バッチ",
+    },
+    body: {
+      zh: "会改文件、会改共享状态、会影响顺序的工具要留在串行车道，避免把 runtime 变成非确定性。",
+      en: "File writes, shared-state mutation, and order-sensitive tools stay in a serial lane to keep the runtime deterministic.",
+      ja: "file write・共有 state mutation・順序依存の tool は直列 lane に残し、runtime を非決定化させません。",
+    },
+  },
+  stages: [
+    {
+      eyebrow: {
+        zh: "Step 1",
+        en: "Step 1",
+        ja: "ステップ 1",
+      },
+      title: {
+        zh: "接住 tool blocks",
+        en: "Capture tool blocks",
+        ja: "tool blocks を受け止める",
+      },
+      body: {
+        zh: "先把 model 产出的 tool_use block 视为一批待调度对象，而不是一出现就立刻执行。",
+        en: "Treat model-emitted tool_use blocks as a schedulable set before executing them immediately.",
+        ja: "model が出した tool_use block を、即実行する前にまず schedulable set として扱います。",
+      },
+    },
+    {
+      eyebrow: {
+        zh: "Step 2",
+        en: "Step 2",
+        ja: "ステップ 2",
+      },
+      title: {
+        zh: "按并发安全性分批",
+        en: "Partition by concurrency safety",
+        ja: "concurrency safety で分割する",
+      },
+      body: {
+        zh: "先决定哪些工具能并发，哪些必须串行，这一步本质上是在保护共享状态。",
+        en: "Decide which tools can run together and which must stay serial. This step protects shared state.",
+        ja: "どの tool が同時実行でき、どれが直列であるべきかを先に決めます。これは共有 state を守る工程です。",
+      },
+    },
+    {
+      eyebrow: {
+        zh: "Step 3",
+        en: "Step 3",
+        ja: "ステップ 3",
+      },
+      title: {
+        zh: "稳定回写结果",
+        en: "Write back in stable order",
+        ja: "安定順で回写する",
+      },
+      body: {
+        zh: "并发并不代表回写乱序。更完整的运行时会先排队 progress、结果和 context modifier，再按稳定顺序落地。",
+        en: "Concurrency does not imply chaotic write-back. A more complete runtime queues progress, results, and modifiers before landing them in stable order.",
+        ja: "並列実行は乱れた回写を意味しません。より整った runtime は progress・result・modifier をいったん整列させてから安定順で反映します。",
+      },
+    },
+  ],
+  rules: [
+    {
+      title: {
+        zh: "progress 可以先走",
+        en: "progress can surface early",
+        ja: "progress は先に出してよい",
+      },
+      body: {
+        zh: "慢工具不必一直沉默，先让上层知道它在做什么。",
+        en: "Slow tools do not need to stay silent. Let the upper layer see what they are doing.",
+        ja: "遅い tool を黙らせ続ける必要はありません。上位層へ今何をしているかを先に知らせます。",
+      },
+    },
+    {
+      title: {
+        zh: "modifier 先排队再合并",
+        en: "queue modifiers before merge",
+        ja: "modifier は queue してから merge する",
+      },
+      body: {
+        zh: "共享 context 的修改最好不要按完成先后直接落地。",
+        en: "Shared context changes should not land directly in completion order.",
+        ja: "共有 context 変更を完了順でそのまま反映しない方が安全です。",
+      },
+    },
+  ],
+  records: [
+    {
+      name: "ToolExecutionBatch",
+      note: {
+        zh: "表示一批可一起调度的 tool block。",
+        en: "Represents one schedulable batch of tool blocks.",
+        ja: "一緒に調度できる tool block の batch。",
+      },
+    },
+    {
+      name: "TrackedTool",
+      note: {
+        zh: "跟踪每个工具的排队、执行、完成、产出进度。",
+        en: "Tracks queued, executing, completed, and yielded progress states per tool.",
+        ja: "各 tool の queued・executing・completed・yielded progress を追跡します。",
+      },
+    },
+    {
+      name: "queued_context_modifiers",
+      note: {
+        zh: "把并发工具的共享状态修改先存起来，再稳定合并。",
+        en: "Stores shared-state mutations until they can be merged in stable order.",
+        ja: "並列 tool の共有 state 変更を一時保存し、後で安定順に merge します。",
+      },
+    },
+  ],
+} as const;
+
+const QUERY_TRANSITION_TEXT = {
+  label: {
+    zh: "Query 转移模型",
+    en: "Query Transition Model",
+    ja: "クエリ継続モデル",
+  },
+  title: {
+    zh: "不要把所有继续都看成同一个 `continue`",
+    en: "Do not treat every continuation as the same `continue`",
+    ja: "すべての継続を同じ `continue` と見なさない",
+  },
+  note: {
+    zh: "只要系统开始长出恢复、压缩和自治行为，就必须知道：这一轮为什么结束、下一轮为什么存在、继续之前改了哪块状态。只有这样，这几层才不会搅成一团。",
+    en: "Once a system grows recovery, compaction, and autonomy, it must know why this turn ended, why the next turn exists, and what state changed before the jump.",
+    ja: "system に recovery・compact・autonomy が入り始めたら、この turn がなぜ終わり、次の turn がなぜ存在し、移行前にどの state を変えたかを知る必要があります。",
+  },
+  angleLabel: {
+    zh: "本章为什么要盯这层",
+    en: "Why This Lens Matters Here",
+    ja: "この章でこの層を見る理由",
+  },
+  chainLabel: {
+    zh: "转移链",
+    en: "Transition Chain",
+    ja: "遷移チェーン",
+  },
+  reasonsLabel: {
+    zh: "常见继续原因",
+    en: "Common Continuation Reasons",
+    ja: "よくある継続理由",
+  },
+  guardrailLabel: {
+    zh: "实现护栏",
+    en: "Implementation Guardrails",
+    ja: "実装ガードレール",
+  },
+  chain: [
+    {
+      title: {
+        zh: "当前轮撞到边界",
+        en: "The current turn hits a boundary",
+        ja: "現在の turn が境界に当たる",
+      },
+      body: {
+        zh: "可能是 tool 结束、输出截断、compact 触发、transport 出错，或者外部 hook 改写了结束条件。",
+        en: "A tool may have finished, output may be truncated, compaction may have fired, transport may have failed, or a hook may have changed the ending condition.",
+        ja: "tool 完了、出力切断、compact 発火、transport error、hook による終了条件変更などが起こります。",
+      },
+    },
+    {
+      title: {
+        zh: "写入 reason + state patch",
+        en: "Write the reason and the state patch",
+        ja: "reason と state patch を書く",
+      },
+      body: {
+        zh: "在真正继续前，把 transition、重试计数、compact 标志或补充消息写进状态。",
+        en: "Before continuing, record the transition, retry counters, compaction flags, or supplemental messages in state.",
+        ja: "続行前に transition、retry count、compact flag、補助 message などを state へ書き込みます。",
+      },
+    },
+    {
+      title: {
+        zh: "下一轮带着原因进入",
+        en: "The next turn enters with a reason",
+        ja: "次の turn は理由を持って入る",
+      },
+      body: {
+        zh: "下一轮不再是盲目出现，它知道自己是正常回流、恢复重试还是预算延续。",
+        en: "The next turn is no longer blind. It knows whether it exists because of normal write-back, recovery, or budgeted continuation.",
+        ja: "次の turn は盲目的に現れるのではなく、通常回流・recovery retry・budget continuation のどれなのかを知っています。",
+      },
+    },
+  ],
+  reasons: [
+    {
+      name: "tool_result_continuation",
+      note: {
+        zh: "工具完成后的正常回流。",
+        en: "Normal write-back after a tool finishes.",
+        ja: "tool 完了後の通常回流。",
+      },
+    },
+    {
+      name: "max_tokens_recovery",
+      note: {
+        zh: "输出被截断后的续写恢复。",
+        en: "Recovery after truncated model output.",
+        ja: "出力切断後の継続回復。",
+      },
+    },
+    {
+      name: "compact_retry",
+      note: {
+        zh: "上下文重排后的重试。",
+        en: "Retry after context reshaping.",
+        ja: "context 再構成後の retry。",
+      },
+    },
+    {
+      name: "transport_retry",
+      note: {
+        zh: "基础设施抖动后的再试一次。",
+        en: "Retry after infrastructure failure.",
+        ja: "基盤失敗後の再試行。",
+      },
+    },
+  ],
+  guardrails: [
+    {
+      title: {
+        zh: "每个 continue site 都写 reason",
+        en: "every continue site writes a reason",
+        ja: "すべての continue site が reason を書く",
+      },
+    },
+    {
+      title: {
+        zh: "继续前先写 state patch",
+        en: "patch state before continuing",
+        ja: "続行前に state patch を書く",
+      },
+    },
+    {
+      title: {
+        zh: "重试和续写都要有 budget",
+        en: "retries and continuations need budgets",
+        ja: "retry と continuation には budget が必要",
+      },
+    },
+  ],
+} as const;
+
+const TASK_RUNTIME_TEXT = {
+  label: {
+    zh: "任务运行时边界",
+    en: "Task Runtime Boundaries",
+    ja: "タスク実行の境界",
+  },
+  title: {
+    zh: "把目标任务、执行槽位、调度触发拆成三层",
+    en: "Separate goal tasks, execution slots, and schedule triggers",
+    ja: "goal task・execution slot・schedule trigger を三層に分ける",
+  },
+  note: {
+    zh: "从 `s12` 开始，读者最容易把所有“任务”混成一个词。更完整的系统会把 durable goal、live runtime slot 和 optional schedule trigger 分层管理。",
+    en: "From `s12` onward, readers start collapsing every kind of work into the word 'task'. More complete systems keep durable goals, live runtime slots, and optional schedule triggers on separate layers.",
+    ja: "`s12` 以降は、あらゆる仕事を task という一語へ潰しがちです。より構造の整った system は durable goal・live runtime slot・optional schedule trigger を分離して管理します。",
+  },
+  angleLabel: {
+    zh: "本章为什么要盯这层",
+    en: "Why This Lens Matters Here",
+    ja: "この章でこの層を見る理由",
+  },
+  layersLabel: {
+    zh: "三层对象",
+    en: "Three Layers",
+    ja: "三層の対象",
+  },
+  flowLabel: {
+    zh: "真实推进关系",
+    en: "Actual Progression",
+    ja: "実際の進み方",
+  },
+  recordsLabel: {
+    zh: "关键记录",
+    en: "Key Records",
+    ja: "主要レコード",
+  },
+  layers: [
+    {
+      title: {
+        zh: "Work-Graph Task",
+        en: "Work-Graph Task",
+        ja: "ワークグラフ・タスク",
+      },
+      body: {
+        zh: "表示要做什么、谁依赖谁、谁负责。它关心目标和工作关系，不直接代表某个后台进程。",
+        en: "Represents what should be done, who depends on whom, and who owns the work. It is goal-oriented, not a live background process.",
+        ja: "何をやるか、誰が依存し、誰が owner かを表します。goal 指向であり、live background process そのものではありません。",
+      },
+    },
+    {
+      title: {
+        zh: "Runtime Slot",
+        en: "Runtime Slot",
+        ja: "ランタイムスロット",
+      },
+      body: {
+        zh: "表示现在有什么执行单元活着：shell、teammate、monitor、workflow。它关心 status、output 和 notified。",
+        en: "Represents the live execution unit: shell, teammate, monitor, or workflow. It cares about status, output, and notification state.",
+        ja: "いま生きている execution unit を表します。shell・teammate・monitor・workflow などがここに入り、status・output・notified を持ちます。",
+      },
+    },
+    {
+      title: {
+        zh: "Schedule Trigger",
+        en: "Schedule Trigger",
+        ja: "スケジュールトリガー",
+      },
+      body: {
+        zh: "表示什么时候要启动一次工作。它不是任务目标，也不是正在运行的槽位，而是触发规则。",
+        en: "Represents when work should start. It is neither the durable goal nor the live execution slot. It is the trigger rule.",
+        ja: "いつ仕事を起動するかを表します。durable goal でも live slot でもなく、trigger rule です。",
+      },
+    },
+  ],
+  flow: [
+    {
+      title: {
+        zh: "目标先存在",
+        en: "The goal exists first",
+        ja: "goal が先に存在する",
+      },
+      body: {
+        zh: "任务板先定义工作目标和依赖，不必立刻对应到某个后台执行体。",
+        en: "The task board defines goals and dependencies before any specific background execution exists.",
+        ja: "task board はまず goal と dependency を定義し、まだ特定の background execution を必要としません。",
+      },
+    },
+    {
+      title: {
+        zh: "执行时生成 runtime slot",
+        en: "Execution creates runtime slots",
+        ja: "実行時に runtime slot が生まれる",
+      },
+      body: {
+        zh: "当系统真的开跑一个 shell、worker 或 monitor 时，再生成独立 runtime record。",
+        en: "Only when the system actually starts a shell, worker, or monitor does it create a separate runtime record.",
+        ja: "shell・worker・monitor を本当に起動した時点で、独立した runtime record を作ります。",
+      },
+    },
+    {
+      title: {
+        zh: "调度只是触发器",
+        en: "Scheduling is only the trigger",
+        ja: "schedule は trigger にすぎない",
+      },
+      body: {
+        zh: "cron 负责到点触发，不负责代替任务目标，也不直接等同于执行槽位。",
+        en: "Cron decides when to fire. It does not replace the task goal and it is not the execution slot itself.",
+        ja: "cron は発火時刻を決める層であり、task goal を置き換えず、execution slot そのものでもありません。",
+      },
+    },
+  ],
+  records: [
+    {
+      name: "TaskRecord",
+      note: {
+        zh: "durable goal 节点。",
+        en: "The durable goal node.",
+        ja: "durable goal node。",
+      },
+    },
+    {
+      name: "RuntimeTaskState",
+      note: {
+        zh: "活着的执行槽位记录。",
+        en: "The live execution-slot record.",
+        ja: "live execution-slot record。",
+      },
+    },
+    {
+      name: "ScheduleRecord",
+      note: {
+        zh: "描述何时触发工作的规则。",
+        en: "Describes when work should be triggered.",
+        ja: "いつ仕事を発火するかを記述する rule。",
+      },
+    },
+    {
+      name: "Notification",
+      note: {
+        zh: "把 runtime 结果重新带回主线。",
+        en: "Brings runtime results back into the mainline.",
+        ja: "runtime result を主線へ戻す record。",
+      },
+    },
+  ],
+} as const;
+
+const TEAM_BOUNDARY_TEXT = {
+  label: {
+    zh: "团队边界模型",
+    en: "Team Boundary Model",
+    ja: "チーム境界モデル",
+  },
+  title: {
+    zh: "把 teammate、协议请求、任务、执行槽位、worktree 车道分开",
+    en: "Separate teammates, protocol requests, tasks, runtime slots, and worktree lanes",
+    ja: "teammate・protocol request・task・runtime slot・worktree lane を分ける",
+  },
+  note: {
+    zh: "到了 `s15-s18`，最容易让读者打结的不是某个函数，而是这五层对象一起动起来时，到底谁表示身份、谁表示目标、谁表示执行、谁表示目录车道。",
+    en: "From `s15` to `s18`, the hardest thing is not one function. It is keeping identity, coordination, goals, execution, and directory lanes distinct while all five move together.",
+    ja: "`s15-s18` で難しいのは個別の関数ではなく、identity・coordination・goal・execution・directory lane を同時に分けて保つことです。",
+  },
+  angleLabel: {
+    zh: "本章为什么要盯这层",
+    en: "Why This Lens Matters Here",
+    ja: "この章でこの層を見る理由",
+  },
+  layersLabel: {
+    zh: "五层对象",
+    en: "Five Layers",
+    ja: "五層の対象",
+  },
+  rulesLabel: {
+    zh: "读的时候先守住",
+    en: "Read With These Guardrails",
+    ja: "読むときのガードレール",
+  },
+  layers: [
+    {
+      title: {
+        zh: "Teammate",
+        en: "Teammate",
+        ja: "Teammate",
+      },
+      body: {
+        zh: "长期存在、可重复协作的身份层。",
+        en: "The persistent identity layer that can collaborate repeatedly.",
+        ja: "反復して協調できる persistent identity layer。",
+      },
+    },
+    {
+      title: {
+        zh: "Protocol Request",
+        en: "Protocol Request",
+        ja: "Protocol Request",
+      },
+      body: {
+        zh: "团队内部一次可追踪的协调请求，带 `request_id`、kind 和状态。",
+        en: "A trackable coordination request inside the team, carrying a `request_id`, kind, and status.",
+        ja: "team 内の追跡可能な coordination request。`request_id`・kind・status を持ちます。",
+      },
+    },
+    {
+      title: {
+        zh: "Task",
+        en: "Task",
+        ja: "Task",
+      },
+      body: {
+        zh: "表示要做什么的目标层。",
+        en: "The goal layer that records what should be done.",
+        ja: "何をやるかを表す goal layer。",
+      },
+    },
+    {
+      title: {
+        zh: "Runtime Slot",
+        en: "Runtime Slot",
+        ja: "ランタイムスロット",
+      },
+      body: {
+        zh: "表示谁正在执行、执行到什么状态。",
+        en: "Represents who is actively executing and what execution state they are in.",
+        ja: "誰が実行中で、どの execution state にいるかを表します。",
+      },
+    },
+    {
+      title: {
+        zh: "Worktree Lane",
+        en: "Worktree Lane",
+        ja: "Worktree Lane",
+      },
+      body: {
+        zh: "表示在哪个隔离目录里推进工作。",
+        en: "Represents the isolated directory lane where execution happens.",
+        ja: "どの分離ディレクトリ lane で仕事を進めるかを表します。",
+      },
+    },
+  ],
+  rules: [
+    {
+      title: {
+        zh: "身份不是目标",
+        en: "identity is not the goal",
+        ja: "identity は goal ではない",
+      },
+      body: {
+        zh: "teammate 表示谁长期存在，不表示这件工作本身。",
+        en: "A teammate tells you who persists in the system, not what the work item itself is.",
+        ja: "teammate は誰が system に長く存在するかを表し、仕事そのものではありません。",
+      },
+    },
+    {
+      title: {
+        zh: "`request_id` 不等于 `task_id`",
+        en: "`request_id` is not `task_id`",
+        ja: "`request_id` は `task_id` ではない",
+      },
+      body: {
+        zh: "协议请求记录协调过程，任务记录工作目标，两者都可长期存在但职责不同。",
+        en: "Protocol requests record coordination, while tasks record work goals. Both can persist, but they serve different purposes.",
+        ja: "protocol request は coordination を記録し、task は work goal を記録します。どちらも残り得ますが役割は別です。",
+      },
+    },
+    {
+      title: {
+        zh: "worktree 不是另一种任务",
+        en: "a worktree is not another kind of task",
+        ja: "worktree は別種の task ではない",
+      },
+      body: {
+        zh: "它只负责目录隔离和 closeout，不负责定义目标。",
+        en: "It manages directory isolation and closeout, not the work goal itself.",
+        ja: "directory isolation と closeout を管理する層であり、goal を定義する層ではありません。",
+      },
+    },
+  ],
+} as const;
+
+const CAPABILITY_LAYER_TEXT = {
+  label: {
+    zh: "外部能力层地图",
+    en: "External Capability Layers",
+    ja: "外部 capability レイヤー",
+  },
+  title: {
+    zh: "把 MCP 看成能力层，而不只是外部工具目录",
+    en: "See MCP as layered capability, not just an external tool catalog",
+    ja: "MCP を外部 tool catalog ではなく layered capability として見る",
+  },
+  note: {
+    zh: "如果只把 MCP 当作远程工具列表，读者会在 resources、prompts、elicitation、auth 这些点上突然失去主线。更稳的办法是先守住 tools-first，再补整张能力层地图。",
+    en: "If MCP is taught only as a remote tool list, readers lose the thread when resources, prompts, elicitation, and auth appear. The steadier approach is tools-first in the mainline, then the full capability map.",
+    ja: "MCP を remote tool list だけで教えると、resources・prompts・elicitation・auth が出た瞬間に主線を失います。tools-first を守りつつ capability map を補う方が安定です。",
+  },
+  angleLabel: {
+    zh: "本章为什么要盯这层",
+    en: "Why This Lens Matters Here",
+    ja: "この章でこの層を見る理由",
+  },
+  layersLabel: {
+    zh: "六层能力面",
+    en: "Six Capability Layers",
+    ja: "六層の capability",
+  },
+  teachLabel: {
+    zh: "教学顺序",
+    en: "Teaching Order",
+    ja: "教える順序",
+  },
+  layers: [
+    { title: { zh: "Config", en: "Config", ja: "設定" }, body: { zh: "server 配置来自哪里、长什么样。", en: "Where server configuration comes from and what it looks like.", ja: "server config がどこから来て、どんな形か。" } },
+    { title: { zh: "Transport", en: "Transport", ja: "接続方式" }, body: { zh: "stdio / http / sse / ws 这些连接通道。", en: "The connection channel such as stdio, HTTP, SSE, or WebSocket.", ja: "stdio / HTTP / SSE / WS などの接続通路。" } },
+    { title: { zh: "Connection State", en: "Connection State", ja: "接続状態" }, body: { zh: "connected / pending / needs-auth / failed。", en: "States such as connected, pending, needs-auth, and failed.", ja: "connected / pending / needs-auth / failed などの状態。" } },
+    { title: { zh: "Capabilities", en: "Capabilities", ja: "能力層" }, body: { zh: "tools 只是其中之一，旁边还有 resources、prompts、elicitation。", en: "Tools are only one member of the layer beside resources, prompts, and elicitation.", ja: "tools は一員にすぎず、resources・prompts・elicitation も並びます。" } },
+    { title: { zh: "Auth", en: "Auth", ja: "認証" }, body: { zh: "决定 server 能不能真正进入 connected 可用态。", en: "Determines whether a server can actually enter the usable connected state.", ja: "server が実際に使える connected 状態へ入れるかを決めます。" } },
+    { title: { zh: "Router Integration", en: "Router Integration", ja: "ルーター統合" }, body: { zh: "最后怎么回到 tool router、permission 和 notification。", en: "How the result finally routes back into tool routing, permissions, and notifications.", ja: "最後に tool router・permission・notification へどう戻るか。" } },
+  ],
+  teach: [
+    {
+      title: { zh: "先讲 tools-first", en: "Teach tools-first first", ja: "まず tools-first を教える" },
+      body: { zh: "先让读者能把外部工具接回来，不要一开始就被平台细节拖走。", en: "Let readers wire external tools back into the agent before platform details take over.", ja: "最初から platform detail に引き込まず、まず外部 tool を agent へ戻せるようにします。" },
+    },
+    {
+      title: { zh: "再补 capability map", en: "Then add the capability map", ja: "次に capability map を足す" },
+      body: { zh: "告诉读者 tools 只是切面之一，平台还有别的面。", en: "Show readers that tools are only one slice of a broader platform.", ja: "tools が broader platform の一断面にすぎないことを見せます。" },
+    },
+    {
+      title: { zh: "最后再展开 auth 等重层", en: "Expand auth and heavier layers last", ja: "auth など重い層は最後に展開する" },
+      body: { zh: "只有当前两层站稳后，再深入认证和更复杂状态机。", en: "Only after the first two layers are stable should auth and heavier state machines become the focus.", ja: "最初の二層が安定してから、auth や重い state machine を扱います。" },
+    },
+  ],
+} as const;
+
+function pick(locale: string, value: LocaleText): string {
+  if (locale === "zh") return value.zh;
+  if (locale === "ja") return value.ja;
+  return value.en;
+}
+
+function ToolRuntimeLens({
+  locale,
+  angle,
+}: {
+  locale: string;
+  angle: string;
+}) {
+  return (
+    <article className="overflow-hidden rounded-[28px] border border-zinc-200/80 bg-[linear-gradient(160deg,rgba(255,255,255,0.98),rgba(244,244,245,0.94))] shadow-sm dark:border-zinc-800/80 dark:bg-[linear-gradient(160deg,rgba(24,24,27,0.96),rgba(10,10,10,0.92))]">
+      <div className="border-b border-zinc-200/80 px-5 py-5 dark:border-zinc-800/80 sm:px-6">
+        <p className="text-xs uppercase tracking-[0.22em] text-zinc-400">
+          {pick(locale, TOOL_RUNTIME_TEXT.label)}
+        </p>
+        <h3 className="mt-3 text-xl font-semibold tracking-tight text-zinc-950 dark:text-zinc-50">
+          {pick(locale, TOOL_RUNTIME_TEXT.title)}
+        </h3>
+        <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+          {pick(locale, TOOL_RUNTIME_TEXT.note)}
+        </p>
+      </div>
+
+      <div className="space-y-4 px-5 py-5 sm:px-6">
+        <div className="rounded-2xl border border-sky-200/70 bg-sky-50/80 p-4 dark:border-sky-900/50 dark:bg-sky-950/20">
+          <p className="text-[11px] font-medium uppercase tracking-[0.2em] text-sky-700/80 dark:text-sky-300/80">
+            {pick(locale, TOOL_RUNTIME_TEXT.angleLabel)}
+          </p>
+          <p className="mt-2 text-sm leading-6 text-zinc-700 dark:text-zinc-200">
+            {angle}
+          </p>
+        </div>
+
+        <div className="grid gap-4 xl:grid-cols-[1.15fr_0.85fr]">
+          <div className="space-y-4">
+            <div className="grid gap-3 md:grid-cols-3">
+              {TOOL_RUNTIME_TEXT.stages.map((stage) => (
+                <div
+                  key={stage.title.en}
+                  className="rounded-2xl border border-zinc-200/80 bg-white/90 p-4 dark:border-zinc-800/80 dark:bg-zinc-950/70"
+                >
+                  <p className="text-[11px] font-medium uppercase tracking-[0.2em] text-zinc-400">
+                    {pick(locale, stage.eyebrow)}
+                  </p>
+                  <h4 className="mt-2 text-sm font-semibold text-zinc-950 dark:text-zinc-50">
+                    {pick(locale, stage.title)}
+                  </h4>
+                  <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                    {pick(locale, stage.body)}
+                  </p>
+                </div>
+              ))}
+            </div>
+
+            <div className="grid gap-3 md:grid-cols-2">
+              <div className="rounded-2xl border border-emerald-200/70 bg-emerald-50/80 p-4 dark:border-emerald-900/50 dark:bg-emerald-950/20">
+                <p className="text-sm font-semibold text-emerald-800 dark:text-emerald-300">
+                  {pick(locale, TOOL_RUNTIME_TEXT.safeLane.title)}
+                </p>
+                <p className="mt-2 text-sm leading-6 text-zinc-700 dark:text-zinc-200">
+                  {pick(locale, TOOL_RUNTIME_TEXT.safeLane.body)}
+                </p>
+              </div>
+              <div className="rounded-2xl border border-amber-200/70 bg-amber-50/80 p-4 dark:border-amber-900/50 dark:bg-amber-950/20">
+                <p className="text-sm font-semibold text-amber-800 dark:text-amber-300">
+                  {pick(locale, TOOL_RUNTIME_TEXT.exclusiveLane.title)}
+                </p>
+                <p className="mt-2 text-sm leading-6 text-zinc-700 dark:text-zinc-200">
+                  {pick(locale, TOOL_RUNTIME_TEXT.exclusiveLane.body)}
+                </p>
+              </div>
+            </div>
+          </div>
+
+          <div className="space-y-4">
+            <div className="rounded-2xl border border-zinc-200/80 bg-zinc-50/80 p-4 dark:border-zinc-800/80 dark:bg-zinc-900/70">
+              <p className="text-[11px] font-medium uppercase tracking-[0.2em] text-zinc-500 dark:text-zinc-400">
+                {pick(locale, TOOL_RUNTIME_TEXT.rulesLabel)}
+              </p>
+              <div className="mt-3 space-y-3">
+                {TOOL_RUNTIME_TEXT.rules.map((rule) => (
+                  <div
+                    key={rule.title.en}
+                    className="rounded-2xl border border-white/80 bg-white/90 p-3 dark:border-zinc-800/80 dark:bg-zinc-950/70"
+                  >
+                    <p className="text-sm font-semibold text-zinc-950 dark:text-zinc-50">
+                      {pick(locale, rule.title)}
+                    </p>
+                    <p className="mt-1 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                      {pick(locale, rule.body)}
+                    </p>
+                  </div>
+                ))}
+              </div>
+            </div>
+
+            <div className="rounded-2xl border border-zinc-200/80 bg-zinc-50/80 p-4 dark:border-zinc-800/80 dark:bg-zinc-900/70">
+              <p className="text-[11px] font-medium uppercase tracking-[0.2em] text-zinc-500 dark:text-zinc-400">
+                {pick(locale, TOOL_RUNTIME_TEXT.recordsLabel)}
+              </p>
+              <div className="mt-3 space-y-3">
+                {TOOL_RUNTIME_TEXT.records.map((record) => (
+                  <div
+                    key={record.name}
+                    className="rounded-2xl border border-white/80 bg-white/90 p-3 dark:border-zinc-800/80 dark:bg-zinc-950/70"
+                  >
+                    <code className="text-sm font-semibold text-zinc-900 dark:text-zinc-100">
+                      {record.name}
+                    </code>
+                    <p className="mt-1 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                      {pick(locale, record.note)}
+                    </p>
+                  </div>
+                ))}
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </article>
+  );
+}
+
+function QueryTransitionLens({
+  locale,
+  angle,
+}: {
+  locale: string;
+  angle: string;
+}) {
+  return (
+    <article className="overflow-hidden rounded-[28px] border border-zinc-200/80 bg-[linear-gradient(160deg,rgba(255,255,255,0.98),rgba(244,244,245,0.94))] shadow-sm dark:border-zinc-800/80 dark:bg-[linear-gradient(160deg,rgba(24,24,27,0.96),rgba(10,10,10,0.92))]">
+      <div className="border-b border-zinc-200/80 px-5 py-5 dark:border-zinc-800/80 sm:px-6">
+        <p className="text-xs uppercase tracking-[0.22em] text-zinc-400">
+          {pick(locale, QUERY_TRANSITION_TEXT.label)}
+        </p>
+        <h3 className="mt-3 text-xl font-semibold tracking-tight text-zinc-950 dark:text-zinc-50">
+          {pick(locale, QUERY_TRANSITION_TEXT.title)}
+        </h3>
+        <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+          {pick(locale, QUERY_TRANSITION_TEXT.note)}
+        </p>
+      </div>
+
+      <div className="space-y-4 px-5 py-5 sm:px-6">
+        <div className="rounded-2xl border border-rose-200/70 bg-rose-50/80 p-4 dark:border-rose-900/50 dark:bg-rose-950/20">
+          <p className="text-[11px] font-medium uppercase tracking-[0.2em] text-rose-700/80 dark:text-rose-300/80">
+            {pick(locale, QUERY_TRANSITION_TEXT.angleLabel)}
+          </p>
+          <p className="mt-2 text-sm leading-6 text-zinc-700 dark:text-zinc-200">
+            {angle}
+          </p>
+        </div>
+
+        <div className="grid gap-4 xl:grid-cols-[1.05fr_0.95fr]">
+          <div className="rounded-2xl border border-zinc-200/80 bg-zinc-50/80 p-4 dark:border-zinc-800/80 dark:bg-zinc-900/70">
+            <p className="text-[11px] font-medium uppercase tracking-[0.2em] text-zinc-500 dark:text-zinc-400">
+              {pick(locale, QUERY_TRANSITION_TEXT.chainLabel)}
+            </p>
+            <div className="mt-3 space-y-3">
+              {QUERY_TRANSITION_TEXT.chain.map((item, index) => (
+                <div key={item.title.en}>
+                  <div className="rounded-2xl border border-white/80 bg-white/90 p-4 dark:border-zinc-800/80 dark:bg-zinc-950/70">
+                    <p className="text-sm font-semibold text-zinc-950 dark:text-zinc-50">
+                      {pick(locale, item.title)}
+                    </p>
+                    <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                      {pick(locale, item.body)}
+                    </p>
+                  </div>
+                  {index < QUERY_TRANSITION_TEXT.chain.length - 1 && (
+                    <div className="flex justify-center py-2 text-zinc-300 dark:text-zinc-600">
+                      <div className="h-6 w-px bg-current" />
+                    </div>
+                  )}
+                </div>
+              ))}
+            </div>
+          </div>
+
+          <div className="space-y-4">
+            <div className="rounded-2xl border border-zinc-200/80 bg-zinc-50/80 p-4 dark:border-zinc-800/80 dark:bg-zinc-900/70">
+              <p className="text-[11px] font-medium uppercase tracking-[0.2em] text-zinc-500 dark:text-zinc-400">
+                {pick(locale, QUERY_TRANSITION_TEXT.reasonsLabel)}
+              </p>
+              <div className="mt-3 space-y-3">
+                {QUERY_TRANSITION_TEXT.reasons.map((reason) => (
+                  <div
+                    key={reason.name}
+                    className="rounded-2xl border border-white/80 bg-white/90 p-3 dark:border-zinc-800/80 dark:bg-zinc-950/70"
+                  >
+                    <code className="text-sm font-semibold text-zinc-900 dark:text-zinc-100">
+                      {reason.name}
+                    </code>
+                    <p className="mt-1 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                      {pick(locale, reason.note)}
+                    </p>
+                  </div>
+                ))}
+              </div>
+            </div>
+
+            <div className="rounded-2xl border border-zinc-200/80 bg-zinc-50/80 p-4 dark:border-zinc-800/80 dark:bg-zinc-900/70">
+              <p className="text-[11px] font-medium uppercase tracking-[0.2em] text-zinc-500 dark:text-zinc-400">
+                {pick(locale, QUERY_TRANSITION_TEXT.guardrailLabel)}
+              </p>
+              <div className="mt-3 grid gap-3">
+                {QUERY_TRANSITION_TEXT.guardrails.map((item) => (
+                  <div
+                    key={item.title.en}
+                    className="rounded-2xl border border-white/80 bg-white/90 p-3 dark:border-zinc-800/80 dark:bg-zinc-950/70"
+                  >
+                    <p className="text-sm font-semibold text-zinc-950 dark:text-zinc-50">
+                      {pick(locale, item.title)}
+                    </p>
+                  </div>
+                ))}
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </article>
+  );
+}
+
+function TaskRuntimeLens({
+  locale,
+  angle,
+}: {
+  locale: string;
+  angle: string;
+}) {
+  return (
+    <article className="overflow-hidden rounded-[28px] border border-zinc-200/80 bg-[linear-gradient(160deg,rgba(255,255,255,0.98),rgba(244,244,245,0.94))] shadow-sm dark:border-zinc-800/80 dark:bg-[linear-gradient(160deg,rgba(24,24,27,0.96),rgba(10,10,10,0.92))]">
+      <div className="border-b border-zinc-200/80 px-5 py-5 dark:border-zinc-800/80 sm:px-6">
+        <p className="text-xs uppercase tracking-[0.22em] text-zinc-400">
+          {pick(locale, TASK_RUNTIME_TEXT.label)}
+        </p>
+        <h3 className="mt-3 text-xl font-semibold tracking-tight text-zinc-950 dark:text-zinc-50">
+          {pick(locale, TASK_RUNTIME_TEXT.title)}
+        </h3>
+        <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+          {pick(locale, TASK_RUNTIME_TEXT.note)}
+        </p>
+      </div>
+
+      <div className="space-y-4 px-5 py-5 sm:px-6">
+        <div className="rounded-2xl border border-amber-200/70 bg-amber-50/80 p-4 dark:border-amber-900/50 dark:bg-amber-950/20">
+          <p className="text-[11px] font-medium uppercase tracking-[0.2em] text-amber-700/80 dark:text-amber-300/80">
+            {pick(locale, TASK_RUNTIME_TEXT.angleLabel)}
+          </p>
+          <p className="mt-2 text-sm leading-6 text-zinc-700 dark:text-zinc-200">
+            {angle}
+          </p>
+        </div>
+
+        <div className="grid gap-4 xl:grid-cols-[1.08fr_0.92fr]">
+          <div className="space-y-4">
+            <div className="rounded-2xl border border-zinc-200/80 bg-zinc-50/80 p-4 dark:border-zinc-800/80 dark:bg-zinc-900/70">
+              <p className="text-[11px] font-medium uppercase tracking-[0.2em] text-zinc-500 dark:text-zinc-400">
+                {pick(locale, TASK_RUNTIME_TEXT.layersLabel)}
+              </p>
+              <div className="mt-3 grid gap-3 md:grid-cols-3">
+                {TASK_RUNTIME_TEXT.layers.map((layer) => (
+                  <div
+                    key={layer.title.en}
+                    className="rounded-2xl border border-white/80 bg-white/90 p-4 dark:border-zinc-800/80 dark:bg-zinc-950/70"
+                  >
+                    <p className="text-sm font-semibold text-zinc-950 dark:text-zinc-50">
+                      {pick(locale, layer.title)}
+                    </p>
+                    <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                      {pick(locale, layer.body)}
+                    </p>
+                  </div>
+                ))}
+              </div>
+            </div>
+
+            <div className="rounded-2xl border border-zinc-200/80 bg-zinc-50/80 p-4 dark:border-zinc-800/80 dark:bg-zinc-900/70">
+              <p className="text-[11px] font-medium uppercase tracking-[0.2em] text-zinc-500 dark:text-zinc-400">
+                {pick(locale, TASK_RUNTIME_TEXT.flowLabel)}
+              </p>
+              <div className="mt-3 space-y-3">
+                {TASK_RUNTIME_TEXT.flow.map((item, index) => (
+                  <div key={item.title.en}>
+                    <div className="rounded-2xl border border-white/80 bg-white/90 p-4 dark:border-zinc-800/80 dark:bg-zinc-950/70">
+                      <p className="text-sm font-semibold text-zinc-950 dark:text-zinc-50">
+                        {pick(locale, item.title)}
+                      </p>
+                      <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                        {pick(locale, item.body)}
+                      </p>
+                    </div>
+                    {index < TASK_RUNTIME_TEXT.flow.length - 1 && (
+                      <div className="flex justify-center py-2 text-zinc-300 dark:text-zinc-600">
+                        <div className="h-6 w-px bg-current" />
+                      </div>
+                    )}
+                  </div>
+                ))}
+              </div>
+            </div>
+          </div>
+
+          <div className="rounded-2xl border border-zinc-200/80 bg-zinc-50/80 p-4 dark:border-zinc-800/80 dark:bg-zinc-900/70">
+            <p className="text-[11px] font-medium uppercase tracking-[0.2em] text-zinc-500 dark:text-zinc-400">
+              {pick(locale, TASK_RUNTIME_TEXT.recordsLabel)}
+            </p>
+            <div className="mt-3 space-y-3">
+              {TASK_RUNTIME_TEXT.records.map((record) => (
+                <div
+                  key={record.name}
+                  className="rounded-2xl border border-white/80 bg-white/90 p-3 dark:border-zinc-800/80 dark:bg-zinc-950/70"
+                >
+                  <code className="text-sm font-semibold text-zinc-900 dark:text-zinc-100">
+                    {record.name}
+                  </code>
+                  <p className="mt-1 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                    {pick(locale, record.note)}
+                  </p>
+                </div>
+              ))}
+            </div>
+          </div>
+        </div>
+      </div>
+    </article>
+  );
+}
+
+function TeamBoundaryLens({
+  locale,
+  angle,
+}: {
+  locale: string;
+  angle: string;
+}) {
+  return (
+    <article className="overflow-hidden rounded-[28px] border border-zinc-200/80 bg-[linear-gradient(160deg,rgba(255,255,255,0.98),rgba(244,244,245,0.94))] shadow-sm dark:border-zinc-800/80 dark:bg-[linear-gradient(160deg,rgba(24,24,27,0.96),rgba(10,10,10,0.92))]">
+      <div className="border-b border-zinc-200/80 px-5 py-5 dark:border-zinc-800/80 sm:px-6">
+        <p className="text-xs uppercase tracking-[0.22em] text-zinc-400">
+          {pick(locale, TEAM_BOUNDARY_TEXT.label)}
+        </p>
+        <h3 className="mt-3 text-xl font-semibold tracking-tight text-zinc-950 dark:text-zinc-50">
+          {pick(locale, TEAM_BOUNDARY_TEXT.title)}
+        </h3>
+        <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+          {pick(locale, TEAM_BOUNDARY_TEXT.note)}
+        </p>
+      </div>
+
+      <div className="space-y-4 px-5 py-5 sm:px-6">
+        <div className="rounded-2xl border border-red-200/70 bg-red-50/80 p-4 dark:border-red-900/50 dark:bg-red-950/20">
+          <p className="text-[11px] font-medium uppercase tracking-[0.2em] text-red-700/80 dark:text-red-300/80">
+            {pick(locale, TEAM_BOUNDARY_TEXT.angleLabel)}
+          </p>
+          <p className="mt-2 text-sm leading-6 text-zinc-700 dark:text-zinc-200">
+            {angle}
+          </p>
+        </div>
+
+        <div className="grid gap-4 xl:grid-cols-[1.08fr_0.92fr]">
+          <div className="rounded-2xl border border-zinc-200/80 bg-zinc-50/80 p-4 dark:border-zinc-800/80 dark:bg-zinc-900/70">
+            <p className="text-[11px] font-medium uppercase tracking-[0.2em] text-zinc-500 dark:text-zinc-400">
+              {pick(locale, TEAM_BOUNDARY_TEXT.layersLabel)}
+            </p>
+            <div className="mt-3 grid gap-3 md:grid-cols-2">
+              {TEAM_BOUNDARY_TEXT.layers.map((layer) => (
+                <div
+                  key={layer.title.en}
+                  className="rounded-2xl border border-white/80 bg-white/90 p-4 dark:border-zinc-800/80 dark:bg-zinc-950/70"
+                >
+                  <p className="text-sm font-semibold text-zinc-950 dark:text-zinc-50">
+                    {pick(locale, layer.title)}
+                  </p>
+                  <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                    {pick(locale, layer.body)}
+                  </p>
+                </div>
+              ))}
+            </div>
+          </div>
+
+          <div className="rounded-2xl border border-zinc-200/80 bg-zinc-50/80 p-4 dark:border-zinc-800/80 dark:bg-zinc-900/70">
+            <p className="text-[11px] font-medium uppercase tracking-[0.2em] text-zinc-500 dark:text-zinc-400">
+              {pick(locale, TEAM_BOUNDARY_TEXT.rulesLabel)}
+            </p>
+            <div className="mt-3 space-y-3">
+              {TEAM_BOUNDARY_TEXT.rules.map((rule) => (
+                <div
+                  key={rule.title.en}
+                  className="rounded-2xl border border-white/80 bg-white/90 p-3 dark:border-zinc-800/80 dark:bg-zinc-950/70"
+                >
+                  <p className="text-sm font-semibold text-zinc-950 dark:text-zinc-50">
+                    {pick(locale, rule.title)}
+                  </p>
+                  <p className="mt-1 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                    {pick(locale, rule.body)}
+                  </p>
+                </div>
+              ))}
+            </div>
+          </div>
+        </div>
+      </div>
+    </article>
+  );
+}
+
+function CapabilityLayerLens({
+  locale,
+  angle,
+}: {
+  locale: string;
+  angle: string;
+}) {
+  return (
+    <article className="overflow-hidden rounded-[28px] border border-zinc-200/80 bg-[linear-gradient(160deg,rgba(255,255,255,0.98),rgba(244,244,245,0.94))] shadow-sm dark:border-zinc-800/80 dark:bg-[linear-gradient(160deg,rgba(24,24,27,0.96),rgba(10,10,10,0.92))]">
+      <div className="border-b border-zinc-200/80 px-5 py-5 dark:border-zinc-800/80 sm:px-6">
+        <p className="text-xs uppercase tracking-[0.22em] text-zinc-400">
+          {pick(locale, CAPABILITY_LAYER_TEXT.label)}
+        </p>
+        <h3 className="mt-3 text-xl font-semibold tracking-tight text-zinc-950 dark:text-zinc-50">
+          {pick(locale, CAPABILITY_LAYER_TEXT.title)}
+        </h3>
+        <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+          {pick(locale, CAPABILITY_LAYER_TEXT.note)}
+        </p>
+      </div>
+
+      <div className="space-y-4 px-5 py-5 sm:px-6">
+        <div className="rounded-2xl border border-slate-300/70 bg-slate-100/80 p-4 dark:border-slate-700/60 dark:bg-slate-900/40">
+          <p className="text-[11px] font-medium uppercase tracking-[0.2em] text-slate-700/80 dark:text-slate-300/80">
+            {pick(locale, CAPABILITY_LAYER_TEXT.angleLabel)}
+          </p>
+          <p className="mt-2 text-sm leading-6 text-zinc-700 dark:text-zinc-200">
+            {angle}
+          </p>
+        </div>
+
+        <div className="grid gap-4 xl:grid-cols-[1.08fr_0.92fr]">
+          <div className="rounded-2xl border border-zinc-200/80 bg-zinc-50/80 p-4 dark:border-zinc-800/80 dark:bg-zinc-900/70">
+            <p className="text-[11px] font-medium uppercase tracking-[0.2em] text-zinc-500 dark:text-zinc-400">
+              {pick(locale, CAPABILITY_LAYER_TEXT.layersLabel)}
+            </p>
+            <div className="mt-3 grid gap-3 md:grid-cols-2">
+              {CAPABILITY_LAYER_TEXT.layers.map((layer) => (
+                <div
+                  key={layer.title.en}
+                  className="rounded-2xl border border-white/80 bg-white/90 p-4 dark:border-zinc-800/80 dark:bg-zinc-950/70"
+                >
+                  <p className="text-sm font-semibold text-zinc-950 dark:text-zinc-50">
+                    {pick(locale, layer.title)}
+                  </p>
+                  <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                    {pick(locale, layer.body)}
+                  </p>
+                </div>
+              ))}
+            </div>
+          </div>
+
+          <div className="rounded-2xl border border-zinc-200/80 bg-zinc-50/80 p-4 dark:border-zinc-800/80 dark:bg-zinc-900/70">
+            <p className="text-[11px] font-medium uppercase tracking-[0.2em] text-zinc-500 dark:text-zinc-400">
+              {pick(locale, CAPABILITY_LAYER_TEXT.teachLabel)}
+            </p>
+            <div className="mt-3 space-y-3">
+              {CAPABILITY_LAYER_TEXT.teach.map((step) => (
+                <div
+                  key={step.title.en}
+                  className="rounded-2xl border border-white/80 bg-white/90 p-3 dark:border-zinc-800/80 dark:bg-zinc-950/70"
+                >
+                  <p className="text-sm font-semibold text-zinc-950 dark:text-zinc-50">
+                    {pick(locale, step.title)}
+                  </p>
+                  <p className="mt-1 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                    {pick(locale, step.body)}
+                  </p>
+                </div>
+              ))}
+            </div>
+          </div>
+        </div>
+      </div>
+    </article>
+  );
+}
+
+export function VersionMechanismLenses({
+  version,
+  locale,
+}: VersionMechanismLensesProps) {
+  const toolAngle = TOOL_RUNTIME_VERSION_ANGLE[version as VersionId];
+  const queryAngle = QUERY_TRANSITION_VERSION_ANGLE[version as VersionId];
+  const taskAngle = TASK_RUNTIME_VERSION_ANGLE[version as VersionId];
+  const teamAngle = TEAM_BOUNDARY_VERSION_ANGLE[version as VersionId];
+  const capabilityAngle = CAPABILITY_LAYER_VERSION_ANGLE[version as VersionId];
+  const lensCount =
+    Number(Boolean(toolAngle)) +
+    Number(Boolean(queryAngle)) +
+    Number(Boolean(taskAngle)) +
+    Number(Boolean(teamAngle)) +
+    Number(Boolean(capabilityAngle));
+
+  if (!lensCount) return null;
+
+  return (
+    <section className="space-y-5">
+      <div className="max-w-3xl">
+        <p className="text-xs uppercase tracking-[0.22em] text-zinc-400">
+          {pick(locale, SECTION_TEXT.label)}
+        </p>
+        <h2 className="mt-3 text-xl font-semibold tracking-tight text-zinc-950 dark:text-zinc-50">
+          {pick(locale, SECTION_TEXT.title)}
+        </h2>
+        <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+          {pick(locale, SECTION_TEXT.body)}
+        </p>
+      </div>
+
+      <div className={`grid gap-6 ${lensCount > 1 ? "2xl:grid-cols-2" : ""}`}>
+        {toolAngle && <ToolRuntimeLens locale={locale} angle={pick(locale, toolAngle)} />}
+        {queryAngle && <QueryTransitionLens locale={locale} angle={pick(locale, queryAngle)} />}
+        {taskAngle && <TaskRuntimeLens locale={locale} angle={pick(locale, taskAngle)} />}
+        {teamAngle && <TeamBoundaryLens locale={locale} angle={pick(locale, teamAngle)} />}
+        {capabilityAngle && <CapabilityLayerLens locale={locale} angle={pick(locale, capabilityAngle)} />}
+      </div>
+    </section>
+  );
+}
diff --git a/web/src/components/diff/code-diff.tsx b/web/src/components/diff/code-diff.tsx
index a62cfd34a..9973cf363 100644
--- a/web/src/components/diff/code-diff.tsx
+++ b/web/src/components/diff/code-diff.tsx
@@ -2,6 +2,7 @@
 
 import { useState, useMemo } from "react";
 import { diffLines, Change } from "diff";
+import { useTranslations } from "@/lib/i18n";
 import { cn } from "@/lib/utils";
 
 interface CodeDiffProps {
@@ -13,11 +14,12 @@ interface CodeDiffProps {
 
 export function CodeDiff({ oldSource, newSource, oldLabel, newLabel }: CodeDiffProps) {
   const [viewMode, setViewMode] = useState<"unified" | "split">("unified");
+  const t = useTranslations("diff");
 
   const changes = useMemo(() => diffLines(oldSource, newSource), [oldSource, newSource]);
 
   return (
-    <div>
+    <div className="min-w-0">
       <div className="mb-4 flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between">
         <div className="min-w-0 truncate text-sm text-zinc-500 dark:text-zinc-400">
           <span className="font-medium text-zinc-700 dark:text-zinc-300">{oldLabel}</span>
@@ -34,7 +36,7 @@ export function CodeDiff({ oldSource, newSource, oldLabel, newLabel }: CodeDiffP
                 : "text-zinc-500 hover:text-zinc-700 dark:text-zinc-400"
             )}
           >
-            Unified
+            {t("view_unified")}
           </button>
           <button
             onClick={() => setViewMode("split")}
@@ -45,7 +47,7 @@ export function CodeDiff({ oldSource, newSource, oldLabel, newLabel }: CodeDiffP
                 : "text-zinc-500 hover:text-zinc-700 dark:text-zinc-400"
             )}
           >
-            Split
+            {t("view_split")}
           </button>
         </div>
       </div>
@@ -79,8 +81,8 @@ function UnifiedView({ changes }: { changes: Change[] }) {
   }
 
   return (
-    <div className="overflow-x-auto rounded-lg border border-zinc-200 dark:border-zinc-700">
-      <table className="w-full border-collapse font-mono text-xs leading-5">
+    <div className="max-w-full overflow-x-auto rounded-lg border border-zinc-200 dark:border-zinc-700">
+      <table className="min-w-full border-collapse font-mono text-xs leading-5">
         <tbody>
           {rows.map((row, i) => (
             <tr
@@ -179,8 +181,8 @@ function SplitView({ changes }: { changes: Change[] }) {
     );
 
   return (
-    <div className="overflow-x-auto rounded-lg border border-zinc-200 dark:border-zinc-700">
-      <table className="w-full border-collapse font-mono text-xs leading-5">
+    <div className="max-w-full overflow-x-auto rounded-lg border border-zinc-200 dark:border-zinc-700">
+      <table className="min-w-full border-collapse font-mono text-xs leading-5">
         <tbody>
           {rows.map((row, i) => (
             <tr key={i}>
diff --git a/web/src/components/docs/doc-renderer.tsx b/web/src/components/docs/doc-renderer.tsx
index f83f8561e..4bf29b08a 100644
--- a/web/src/components/docs/doc-renderer.tsx
+++ b/web/src/components/docs/doc-renderer.tsx
@@ -12,7 +12,8 @@ import rehypeHighlight from "rehype-highlight";
 import rehypeStringify from "rehype-stringify";
 
 interface DocRendererProps {
-  version: string;
+  version?: string;
+  slug?: string;
 }
 
 function renderMarkdown(md: string): string {
@@ -55,23 +56,38 @@ function postProcessHtml(html: string): string {
     (_, start) => `<ol style="counter-reset:step-counter ${parseInt(start) - 1}">`
   );
 
+  // Wrap markdown tables so wide teaching maps scroll locally instead of
+  // stretching the whole doc page.
+  html = html.replace(/<table>/g, '<div class="table-scroll"><table>');
+  html = html.replace(/<\/table>/g, "</table></div>");
+
   return html;
 }
 
-export function DocRenderer({ version }: DocRendererProps) {
+export function DocRenderer({ version, slug }: DocRendererProps) {
   const locale = useLocale();
 
   const doc = useMemo(() => {
+    if (!version && !slug) return null;
+
     const match = docsData.find(
-      (d: { version: string; locale: string }) =>
-        d.version === version && d.locale === locale
+      (d: { version?: string | null; slug?: string; locale: string; kind?: string }) =>
+        (version ? d.version === version && d.kind === "chapter" : d.slug === slug) &&
+        d.locale === locale
     );
     if (match) return match;
+    const zhFallback = docsData.find(
+      (d: { version?: string | null; slug?: string; locale: string; kind?: string }) =>
+        (version ? d.version === version && d.kind === "chapter" : d.slug === slug) &&
+        d.locale === "zh"
+    );
+    if (zhFallback) return zhFallback;
     return docsData.find(
-      (d: { version: string; locale: string }) =>
-        d.version === version && d.locale === "en"
+      (d: { version?: string | null; slug?: string; locale: string; kind?: string }) =>
+        (version ? d.version === version && d.kind === "chapter" : d.slug === slug) &&
+        d.locale === "en"
     );
-  }, [version, locale]);
+  }, [version, slug, locale]);
 
   if (!doc) return null;
 
diff --git a/web/src/components/layout/header.tsx b/web/src/components/layout/header.tsx
index 3749743e5..d49d1ff53 100644
--- a/web/src/components/layout/header.tsx
+++ b/web/src/components/layout/header.tsx
@@ -8,9 +8,8 @@ import { useState, useEffect } from "react";
 import { cn } from "@/lib/utils";
 
 const NAV_ITEMS = [
-  { key: "timeline", href: "/timeline" },
+  { key: "reference", href: "/reference" },
   { key: "compare", href: "/compare" },
-  { key: "layers", href: "/layers" },
 ] as const;
 
 const LOCALES = [
diff --git a/web/src/components/layout/sidebar.tsx b/web/src/components/layout/sidebar.tsx
index 7d2f6d90d..fa224b29b 100644
--- a/web/src/components/layout/sidebar.tsx
+++ b/web/src/components/layout/sidebar.tsx
@@ -6,14 +6,17 @@ import { LAYERS, VERSION_META } from "@/lib/constants";
 import { useTranslations } from "@/lib/i18n";
 import { cn } from "@/lib/utils";
 
-const LAYER_DOT_BG: Record<string, string> = {
-  tools: "bg-blue-500",
-  planning: "bg-emerald-500",
-  memory: "bg-purple-500",
-  concurrency: "bg-amber-500",
-  collaboration: "bg-red-500",
+const LAYER_DOT_COLORS: Record<string, string> = {
+  core: "bg-blue-500",
+  hardening: "bg-emerald-500",
+  runtime: "bg-amber-500",
+  platform: "bg-red-500",
 };
 
+function isActiveLink(pathname: string, href: string) {
+  return pathname === href || pathname === `${href}/`;
+}
+
 export function Sidebar() {
   const pathname = usePathname();
   const locale = pathname.split("/")[1] || "en";
@@ -21,12 +24,12 @@ export function Sidebar() {
   const tLayer = useTranslations("layer_labels");
 
   return (
-    <nav className="hidden w-56 shrink-0 md:block">
-      <div className="sticky top-[calc(3.5rem+2rem)] space-y-5">
+    <nav className="hidden w-72 shrink-0 md:block">
+      <div className="sticky top-[calc(3.5rem+2rem)] max-h-[calc(100vh-6rem)] space-y-6 overflow-y-auto pr-2">
         {LAYERS.map((layer) => (
           <div key={layer.id}>
-            <div className="flex items-center gap-1.5 pb-1.5">
-              <span className={cn("h-2 w-2 rounded-full", LAYER_DOT_BG[layer.id])} />
+            <div className="flex items-center gap-1.5 pb-2">
+              <span className={cn("h-2 w-2 rounded-full", LAYER_DOT_COLORS[layer.id])} />
               <span className="text-[11px] font-semibold uppercase tracking-wider text-zinc-400 dark:text-zinc-500">
                 {tLayer(layer.id)}
               </span>
@@ -36,8 +39,7 @@ export function Sidebar() {
                 const meta = VERSION_META[vId];
                 const href = `/${locale}/${vId}`;
                 const isActive =
-                  pathname === href ||
-                  pathname === `${href}/` ||
+                  isActiveLink(pathname, href) ||
                   pathname.startsWith(`${href}/diff`);
 
                 return (
diff --git a/web/src/components/simulator/agent-loop-simulator.tsx b/web/src/components/simulator/agent-loop-simulator.tsx
index 8de470cd4..680ad1930 100644
--- a/web/src/components/simulator/agent-loop-simulator.tsx
+++ b/web/src/components/simulator/agent-loop-simulator.tsx
@@ -2,11 +2,15 @@
 
 import { useRef, useEffect, useState } from "react";
 import { AnimatePresence } from "framer-motion";
-import { useTranslations } from "@/lib/i18n";
+import { useLocale, useTranslations } from "@/lib/i18n";
 import { useSimulator } from "@/hooks/useSimulator";
 import { SimulatorControls } from "./simulator-controls";
 import { SimulatorMessage } from "./simulator-message";
 import type { Scenario } from "@/types/agent-data";
+import {
+  isGenericScenarioVersion,
+  resolveLegacySessionAssetVersion,
+} from "@/lib/session-assets";
 
 const scenarioModules: Record<string, () => Promise<{ default: Scenario }>> = {
   s01: () => import("@/data/scenarios/s01.json") as Promise<{ default: Scenario }>,
@@ -23,21 +27,1416 @@ const scenarioModules: Record<string, () => Promise<{ default: Scenario }>> = {
   s12: () => import("@/data/scenarios/s12.json") as Promise<{ default: Scenario }>,
 };
 
+function buildGenericScenario(version: string, locale: string): Scenario {
+  if (locale === "zh") {
+    const zh: Record<string, Scenario> = {
+      s07: {
+        version,
+        title: "权限系统",
+        description: "先把模型意图送进权限闸门，再决定允许、拒绝还是询问用户。",
+        steps: [
+          {
+            type: "user_message",
+            content: "请直接删除整个 build 目录，然后重新生成。",
+            annotation: "模型会尝试执行带破坏性的文件系统操作。",
+          },
+          {
+            type: "system_event",
+            content: "permission_check(action=delete, target=build/, risk=high, mode=ask)",
+            annotation: "权限层先把原始 tool call 规范化成统一意图对象。",
+          },
+          {
+            type: "tool_call",
+            toolName: "request_permission",
+            content: "{ action: 'delete', target: 'build/', reason: 'high-risk filesystem mutation' }",
+            annotation: "高风险操作进入 ask 分支，而不是直接落到 shell。",
+          },
+          {
+            type: "tool_result",
+            toolName: "request_permission",
+            content: "User denied destructive delete. Suggest safer alternative.",
+            annotation: "拒绝结果也会回写到主循环，让模型据此重新规划。",
+          },
+          {
+            type: "assistant_text",
+            content: "我不会直接删除整个 build 目录。更安全的做法是只清理生成产物，或先列出待删除文件让你确认。",
+            annotation: "模型根据 deny 结果调整方案，而不是假装执行成功。",
+          },
+        ],
+      },
+      s08: {
+        version,
+        title: "Hook 系统",
+        description: "主循环保持稳定，日志、审计、追踪等旁路逻辑通过生命周期 Hook 挂接。",
+        steps: [
+          {
+            type: "user_message",
+            content: "修复登录页的表单校验，并把修改过程记录下来。",
+            annotation: "任务既需要执行工具，也需要旁路审计信息。",
+          },
+          {
+            type: "system_event",
+            content: "emit pre_tool(tool=edit_file, path=ui/login.tsx)",
+            annotation: "在真正调用工具前，循环发出统一生命周期事件。",
+          },
+          {
+            type: "tool_call",
+            toolName: "edit_file",
+            content: "ui/login.tsx\n---\nvalidateEmail(value)\n-> validateEmail(value.trim())",
+            annotation: "主流程只负责执行工具本身。",
+          },
+          {
+            type: "system_event",
+            content: "hook[audit_log].append({ tool: 'edit_file', path: 'ui/login.tsx', status: 'ok' })",
+            annotation: "审计 Hook 通过事件拿到结构化信息，不需要改 edit_file 实现。",
+          },
+          {
+            type: "assistant_text",
+            content: "登录页校验已修复，审计记录也已追加到日志通道。",
+            annotation: "Hook 让附加能力围绕主循环扩展，而不是侵入主循环。",
+          },
+        ],
+      },
+      s09: {
+        version,
+        title: "Memory 系统",
+        description: "只把跨会话还需要的事实写入长期记忆，当前过程仍由上下文承担。",
+        steps: [
+          {
+            type: "user_message",
+            content: "以后默认都用 pnpm，不要再用 npm。",
+            annotation: "这是用户偏好，属于跨会话事实。",
+          },
+          {
+            type: "system_event",
+            content: "memory_load(scope=user, keys=['package_manager_preference']) -> none",
+            annotation: "模型调用前先加载相关长期记忆。",
+          },
+          {
+            type: "tool_call",
+            toolName: "memory_write",
+            content: "{ key: 'package_manager_preference', value: 'pnpm', reason: 'user explicit preference' }",
+            annotation: "任务结束后，把可复用事实提炼写回 memory。",
+          },
+          {
+            type: "tool_result",
+            toolName: "memory_write",
+            content: "Stored durable memory: package_manager_preference=pnpm",
+            annotation: "长期记忆写入完成，后续会话可直接加载。",
+          },
+          {
+            type: "assistant_text",
+            content: "已记录。之后涉及包管理命令时，我会默认优先使用 pnpm。",
+            annotation: "Memory 保存的是稳定事实，而不是整段原始对话。",
+          },
+        ],
+      },
+      s10: {
+        version,
+        title: "System Prompt",
+        description: "系统输入由多段信息按顺序装配，而不是一整块不可见的大字符串。",
+        steps: [
+          {
+            type: "user_message",
+            content: "帮我检查这个仓库里和支付有关的实现风险。",
+            annotation: "运行时需要把角色、目录、工具、记忆等一起装到模型输入里。",
+          },
+          {
+            type: "system_event",
+            content: "prompt_build = role_policy + workspace_state + tool_catalog + memory_context + task_focus",
+            annotation: "Prompt pipeline 明确展示了输入由哪些片段构成。",
+          },
+          {
+            type: "tool_call",
+            toolName: "preview_prompt",
+            content: "[role_policy]\nYou are a coding agent...\n[workspace_state]\nrepo=payments-app\n[tool_catalog]\nread_file, rg, ...",
+            annotation: "这一步强调“系统输入是被构建出来的”。",
+          },
+          {
+            type: "tool_result",
+            toolName: "preview_prompt",
+            content: "Prompt sections assembled successfully (5 sections, 2217 chars)",
+            annotation: "只有装配完成后，模型才看到最终输入。",
+          },
+          {
+            type: "assistant_text",
+            content: "我会先根据当前仓库状态和可用工具聚焦支付模块，再逐步检查边界、校验和失败处理逻辑。",
+            annotation: "模型的行为来自有结构的输入流水线，而不是一段神秘提示词。",
+          },
+        ],
+      },
+      s11: {
+        version,
+        title: "错误恢复",
+        description: "恢复分支必须可解释，失败原因也要成为模型后续可见的状态。",
+        steps: [
+          {
+            type: "user_message",
+            content: "运行测试并修复失败用例。",
+            annotation: "这是一个常见会触发工具异常或超时的任务。",
+          },
+          {
+            type: "tool_call",
+            toolName: "bash",
+            content: "pytest tests/auth/test_login.py -q",
+            annotation: "主循环先正常执行工具。",
+          },
+          {
+            type: "tool_result",
+            toolName: "bash",
+            content: "Error: Timeout after 120s",
+            annotation: "工具失败后，系统不能只是把错误静默吞掉。",
+          },
+          {
+            type: "system_event",
+            content: "recovery_branch(reason=timeout, strategy=retry_with_narrow_scope, attempts=1/2)",
+            annotation: "恢复层把失败分类，并写出为什么要继续。",
+          },
+          {
+            type: "assistant_text",
+            content: "完整测试超时了。我先缩小到认证模块的失败用例重试，再根据更小范围的结果定位问题。",
+            annotation: "恢复理由进入上下文后，模型才能稳定地选择下一步。",
+          },
+        ],
+      },
+      s12: {
+        version,
+        title: "任务系统",
+        description: "任务板把工作目标变成持久记录，并用依赖关系控制何时解锁后续工作。",
+        steps: [
+          {
+            type: "user_message",
+            content: "把支付模块重构拆成几个可持续推进的任务。",
+            annotation: "这里要创建的是 durable task records，而不是一次会话里的 todo 文本。",
+          },
+          {
+            type: "tool_call",
+            toolName: "task_create",
+            content: "{ id: 'task-auth-migrate', title: '迁移鉴权层', blocks: ['task-payment-adapter'] }",
+            annotation: "任务记录会显式声明依赖和后继关系。",
+          },
+          {
+            type: "tool_result",
+            toolName: "task_create",
+            content: "Created task-auth-migrate (status=pending, blocks=1)",
+            annotation: "任务板现在知道这项工作存在，并且后续节点暂时被它阻塞。",
+          },
+          {
+            type: "system_event",
+            content: "task_complete(task-auth-migrate) -> unlock(task-payment-adapter)",
+            annotation: "完成一个节点后，系统会检查依赖并解锁后续节点。",
+          },
+          {
+            type: "assistant_text",
+            content: "我先把重构拆成持久任务节点。这样后续工作不是靠记忆硬撑，而是由任务板持续推进。",
+            annotation: "教学重点是 durable graph，而不是会话内提醒清单。",
+          },
+        ],
+      },
+      s13: {
+        version,
+        title: "后台任务",
+        description: "慢命令进入 runtime record，完整输出落盘，下一轮再用通知把结果带回主循环。",
+        steps: [
+          {
+            type: "user_message",
+            content: "后台跑完整测试，同时先继续整理失败模块的文件结构。",
+            annotation: "这是典型的前台继续推进、后台慢执行场景。",
+          },
+          {
+            type: "tool_call",
+            toolName: "background_run",
+            content: "{ command: 'pytest -q', task_id: 'rt_42' }",
+            annotation: "主循环先创建 runtime task，而不是同步等待测试跑完。",
+          },
+          {
+            type: "system_event",
+            content: "runtime_task_saved(id=rt_42, status=running, output_file=.runtime-tasks/rt_42.log)",
+            annotation: "运行记录和完整输出位置被单独保存，和 task goal 分层。",
+          },
+          {
+            type: "system_event",
+            content: "notification_drain -> [bg:rt_42] failed preview='3 tests failing in payments/test_retry.py'",
+            annotation: "下一轮前先把 preview 注入上下文，而不是把整份日志直接塞进 prompt。",
+          },
+          {
+            type: "assistant_text",
+            content: "后台测试已经回来了，我先根据失败摘要聚焦到 retry 用例，必要时再去读完整日志文件。",
+            annotation: "notification 负责提醒，output_file 负责保存原文。",
+          },
+        ],
+      },
+      s14: {
+        version,
+        title: "Cron 调度",
+        description: "时间规则只负责触发，真正执行仍然交给后台运行时。",
+        steps: [
+          {
+            type: "user_message",
+            content: "每天凌晨 2 点自动运行仓库健康检查。",
+            annotation: "用户并没有直接请求一次执行，而是在创建时间触发规则。",
+          },
+          {
+            type: "tool_call",
+            toolName: "cron_schedule_create",
+            content: "{ name: 'nightly-health-check', cron: '0 2 * * *', task_template: 'repo_health_check' }",
+            annotation: "Cron 记录的是触发规则和任务模板。",
+          },
+          {
+            type: "system_event",
+            content: "cron_tick -> rule matched -> runtime_task_spawn(name='repo_health_check')",
+            annotation: "时间命中后，调度器生成 runtime task，而不是直接执行业务逻辑。",
+          },
+          {
+            type: "tool_result",
+            toolName: "runtime_task_spawn",
+            content: "Queued background runtime task #42 for nightly-health-check",
+            annotation: "真正执行交给后台任务层接管。",
+          },
+          {
+            type: "assistant_text",
+            content: "规则已建立。之后每天 02:00 会先触发 runtime task，再由后台执行层完成实际检查。",
+            annotation: "教学重点是调度触发面和执行运行时的职责分离。",
+          },
+        ],
+      },
+      s15: {
+        version,
+        title: "Agent Teams",
+        description: "队友是长期存在的角色，有自己的名字、身份和 inbox，而不是一次性 subagent。",
+        steps: [
+          {
+            type: "user_message",
+            content: "你负责主线，我想让一个专门看测试、一个专门看重构。",
+            annotation: "这时系统需要的是持久队友，而不是短命委派。",
+          },
+          {
+            type: "tool_call",
+            toolName: "spawn_teammate",
+            content: "{ name: 'alice', role: 'test-specialist', prompt: 'Own the failing tests.' }",
+            annotation: "TeammateManager 为队友分配长期身份和职责。",
+          },
+          {
+            type: "tool_result",
+            toolName: "spawn_teammate",
+            content: "Spawned 'alice' (role: test-specialist)",
+            annotation: "队友进入 roster，后续可被反复派活。",
+          },
+          {
+            type: "tool_call",
+            toolName: "send_message",
+            content: "{ to: 'alice', content: '先检查 retry 相关失败用例。' }",
+            annotation: "协作通过 inbox 边界发生，而不是共用一段 messages[]。",
+          },
+          {
+            type: "assistant_text",
+            content: "测试队友已经接入团队。之后我可以继续点名协作，而不是每次都临时重新创建子任务执行者。",
+            annotation: "长期身份和独立 inbox 才是这一章的关键增量。",
+          },
+        ],
+      },
+      s16: {
+        version,
+        title: "团队协议",
+        description: "审批和关机这类协作必须带 request_id 和 request record，而不是只靠自由文本往返。",
+        steps: [
+          {
+            type: "user_message",
+            content: "在 alice 真正改鉴权层前，先让她提交计划给我审批。",
+            annotation: "高风险协作需要结构化 request / response。",
+          },
+          {
+            type: "tool_call",
+            toolName: "plan_approval",
+            content: "{ request_id: 'req_91', from: 'alice', plan: 'Refactor auth boundary before retries.' }",
+            annotation: "协议消息会把 request_id 和 payload 一起发送。",
+          },
+          {
+            type: "system_event",
+            content: "request_record_saved(id=req_91, kind=plan_approval, status=pending)",
+            annotation: "真正被追踪的是 durable request record，而不只是临时内存字典。",
+          },
+          {
+            type: "tool_result",
+            toolName: "plan_review",
+            content: "{ request_id: 'req_91', approve: true, feedback: 'Proceed with adapter boundary first.' }",
+            annotation: "收到明确响应后，请求状态从 pending 进入 approved。",
+          },
+          {
+            type: "assistant_text",
+            content: "这次协作已经有编号和状态了。后面无论继续、拒绝还是超时，都能准确追到同一个请求记录。",
+            annotation: "request_id + request record 才是协议层真正的新结构。",
+          },
+        ],
+      },
+      s17: {
+        version,
+        title: "自治 Agent",
+        description: "队友在空闲时可以轮询共享状态，自行认领工作，再恢复到正确上下文继续推进。",
+        steps: [
+          {
+            type: "system_event",
+            content: "idle_cycle(worker='alice') -> poll inbox + task board",
+            annotation: "自治的入口不是魔法，而是稳定的 idle polling。",
+          },
+          {
+            type: "system_event",
+            content: "claimable_task_found(task='task-payment-adapter', policy='test-specialist may claim retry-related work')",
+            annotation: "只有符合 self-claim 规则的工作才会被队友主动认领。",
+          },
+          {
+            type: "tool_call",
+            toolName: "claim_task",
+            content: "{ teammate: 'alice', task_id: 'task-payment-adapter' }",
+            annotation: "认领动作本身也要回写状态，避免多个队友撞车。",
+          },
+          {
+            type: "tool_result",
+            toolName: "claim_task",
+            content: "alice claimed task-payment-adapter and resumed prior context",
+            annotation: "系统根据任务状态和角色状态恢复执行，而不是凭空继续。",
+          },
+          {
+            type: "assistant_text",
+            content: "alice 已经在没有新指令的情况下接手后续工作了，但她仍然受 claim policy 和团队状态约束。",
+            annotation: "自治的关键是可控地 self-claim 和 self-resume。",
+          },
+        ],
+      },
+      s18: {
+        version,
+        title: "Worktree 隔离",
+        description: "任务被绑定到独立执行车道，进入各自目录执行，再带着 closeout 语义回到主系统。",
+        steps: [
+          {
+            type: "user_message",
+            content: "给重构任务开一个隔离目录，避免和主线修改互相干扰。",
+            annotation: "这里新增的是 execution lane，不是新的任务类型。",
+          },
+          {
+            type: "tool_call",
+            toolName: "worktree_create",
+            content: "{ task_id: 'task-auth-migrate', lane: 'wt-auth-migrate' }",
+            annotation: "系统先分配 worktree，并把它和任务记录绑定。",
+          },
+          {
+            type: "system_event",
+            content: "worktree_event(type=create, task_id=task-auth-migrate, path=.worktrees/wt-auth-migrate)",
+            annotation: "执行车道的生命周期事件被显式写出来，方便观察。",
+          },
+          {
+            type: "tool_result",
+            toolName: "worktree_closeout",
+            content: "{ path: '.worktrees/wt-auth-migrate', keep: true, reason: 'needs follow-up review' }",
+            annotation: "closeout 决定这个车道是保留还是回收，而不是简单结束命令。",
+          },
+          {
+            type: "assistant_text",
+            content: "这项工作现在在独立车道里推进，主线目录不会被混写，后续也能根据 closeout 状态决定是否继续保留该环境。",
+            annotation: "task goal 和 isolated lane 的分层是这一章的主心智。",
+          },
+        ],
+      },
+      s19: {
+        version,
+        title: "MCP 与 Plugin",
+        description: "外部能力进入系统后，也应遵循与本地工具一致的发现、路由、授权和结果回写流程。",
+        steps: [
+          {
+            type: "user_message",
+            content: "读取 Figma 设计稿里的按钮规范，然后同步到当前组件库。",
+            annotation: "这是一个典型需要外部能力接入的请求。",
+          },
+          {
+            type: "system_event",
+            content: "capability_router.resolve(['native_tools', 'plugin_registry', 'mcp_servers']) -> mcp:figma.inspect",
+            annotation: "系统先在统一 capability bus 上做能力发现与路由选择。",
+          },
+          {
+            type: "tool_call",
+            toolName: "mcp.figma.inspect",
+            content: "{ fileId: 'design-123', node: 'PrimaryButton' }",
+            annotation: "外部 MCP 能力被当成标准 capability 调用。",
+          },
+          {
+            type: "tool_result",
+            toolName: "mcp.figma.inspect",
+            content: "{ padding: '12x18', radius: 10, typography: 'SemiBold 14', states: ['default','hover','disabled'] }",
+            annotation: "返回结果先标准化，再回到主循环。",
+          },
+          {
+            type: "assistant_text",
+            content: "我已经拿到设计规范。下一步会按统一结果格式，把这些约束映射到当前按钮组件实现里。",
+            annotation: "MCP 不是外挂世界，而是被接回同一条 agent 控制平面。",
+          },
+        ],
+      },
+    };
+
+    return zh[version] ?? buildFallbackScenario(version, locale);
+  }
+
+  if (locale === "ja") {
+    const ja: Record<string, Scenario> = {
+      s07: {
+        version,
+        title: "権限システム",
+        description: "model の意図をそのまま実行せず、権限ゲートで allow / deny / ask に分岐させます。",
+        steps: [
+          {
+            type: "user_message",
+            content: "build ディレクトリをまるごと削除して、全部作り直してください。",
+            annotation: "model が破壊的なファイル操作を提案しそうな場面です。",
+          },
+          {
+            type: "system_event",
+            content: "permission_check(action=delete, target=build/, risk=high, mode=ask)",
+            annotation: "生の tool call は、まず統一された intent object に正規化されます。",
+          },
+          {
+            type: "tool_call",
+            toolName: "request_permission",
+            content: "{ action: 'delete', target: 'build/', reason: 'high-risk filesystem mutation' }",
+            annotation: "高リスク操作は shell へ直行せず、ask 分岐へ入ります。",
+          },
+          {
+            type: "tool_result",
+            toolName: "request_permission",
+            content: "ユーザーが破壊的な削除を拒否しました。より安全な代替案を提示してください。",
+            annotation: "deny 結果も main loop へ戻り、次の再計画材料になります。",
+          },
+          {
+            type: "assistant_text",
+            content: "build ディレクトリ全体は直接削除しません。まず生成物だけを安全に掃除するか、削除対象一覧を出して確認します。",
+            annotation: "model は deny 結果を見て方針を組み替えます。",
+          },
+        ],
+      },
+      s08: {
+        version,
+        title: "Hook システム",
+        description: "main loop は安定したままにし、監査や追跡のような横断処理は lifecycle hook に載せます。",
+        steps: [
+          {
+            type: "user_message",
+            content: "ログイン画面のフォーム検証を直して、変更履歴も残してください。",
+            annotation: "tool 実行と audit のような横断処理が同時に必要な場面です。",
+          },
+          {
+            type: "system_event",
+            content: "emit pre_tool(tool=edit_file, path=ui/login.tsx)",
+            annotation: "実際の tool 実行前に、loop が安定した lifecycle event を発火します。",
+          },
+          {
+            type: "tool_call",
+            toolName: "edit_file",
+            content: "ui/login.tsx\n---\nvalidateEmail(value)\n-> validateEmail(value.trim())",
+            annotation: "主処理は tool 本体の実行だけに集中します。",
+          },
+          {
+            type: "system_event",
+            content: "hook[audit_log].append({ tool: 'edit_file', path: 'ui/login.tsx', status: 'ok' })",
+            annotation: "audit hook は構造化 event から必要情報を取り出します。",
+          },
+          {
+            type: "assistant_text",
+            content: "ログイン画面の検証を修正し、監査ログにも今回の変更を追記しました。",
+            annotation: "hook は主線を壊さず、loop の周辺機能を増やします。",
+          },
+        ],
+      },
+      s09: {
+        version,
+        title: "Memory システム",
+        description: "今後も効く事実だけを長期 memory に残し、現在ターンの詳細は context 側に置きます。",
+        steps: [
+          {
+            type: "user_message",
+            content: "今後は npm ではなく、必ず pnpm を使ってください。",
+            annotation: "これは一度きりの会話ではなく、次回以降にも効く user preference です。",
+          },
+          {
+            type: "system_event",
+            content: "memory_load(scope=user, keys=['package_manager_preference']) -> none",
+            annotation: "model 呼び出し前に、関連する長期 memory を読み込みます。",
+          },
+          {
+            type: "tool_call",
+            toolName: "memory_write",
+            content: "{ key: 'package_manager_preference', value: 'pnpm', reason: 'user explicit preference' }",
+            annotation: "再利用価値のある事実だけを抽出して memory へ書き込みます。",
+          },
+          {
+            type: "tool_result",
+            toolName: "memory_write",
+            content: "長期 memory を保存しました: package_manager_preference=pnpm",
+            annotation: "次回の session ではこの事実を先に読み戻せます。",
+          },
+          {
+            type: "assistant_text",
+            content: "記録しました。以後、パッケージ管理コマンドでは pnpm を優先して使います。",
+            annotation: "memory に残すのは会話全文ではなく、継続価値のある事実です。",
+          },
+        ],
+      },
+      s10: {
+        version,
+        title: "System Prompt",
+        description: "system input は見えない巨大文字列ではなく、複数の section を順に組み立てた結果です。",
+        steps: [
+          {
+            type: "user_message",
+            content: "このリポジトリの支払い処理まわりの実装リスクを洗い出してください。",
+            annotation: "役割、workspace 状態、tool、memory などを一緒に model input へ積む必要があります。",
+          },
+          {
+            type: "system_event",
+            content: "prompt_build = role_policy + workspace_state + tool_catalog + memory_context + task_focus",
+            annotation: "prompt pipeline は入力がどの section から成るかを可視化します。",
+          },
+          {
+            type: "tool_call",
+            toolName: "preview_prompt",
+            content: "[role_policy]\nYou are a coding agent...\n[workspace_state]\nrepo=payments-app\n[tool_catalog]\nread_file, rg, ...",
+            annotation: "system input は「組み立てられたもの」だと見せるためのプレビューです。",
+          },
+          {
+            type: "tool_result",
+            toolName: "preview_prompt",
+            content: "Prompt sections assembled successfully (5 sections, 2217 chars)",
+            annotation: "組み立てが終わって初めて、model は最終入力を受け取ります。",
+          },
+          {
+            type: "assistant_text",
+            content: "まず現在のリポジトリ状態と利用可能な tool を踏まえて支払いモジュールを絞り込み、境界・検証・失敗処理を順に確認します。",
+            annotation: "model の振る舞いは、構造化された入力パイプラインから生まれます。",
+          },
+        ],
+      },
+      s11: {
+        version,
+        title: "エラー回復",
+        description: "失敗後の分岐には理由を残し、回復そのものを次の推論に見える状態として渡します。",
+        steps: [
+          {
+            type: "user_message",
+            content: "テストを実行して、落ちているケースを直してください。",
+            annotation: "tool 失敗や timeout が起きやすい典型タスクです。",
+          },
+          {
+            type: "tool_call",
+            toolName: "bash",
+            content: "pytest tests/auth/test_login.py -q",
+            annotation: "まずは通常どおり tool を実行します。",
+          },
+          {
+            type: "tool_result",
+            toolName: "bash",
+            content: "Error: Timeout after 120s",
+            annotation: "失敗を黙って飲み込まず、回復分岐へ明示的に渡します。",
+          },
+          {
+            type: "system_event",
+            content: "recovery_branch(reason=timeout, strategy=retry_with_narrow_scope, attempts=1/2)",
+            annotation: "失敗理由と次の継続理由を state に書き込みます。",
+          },
+          {
+            type: "assistant_text",
+            content: "全体テストは timeout しました。まず認証まわりの失敗ケースだけに絞って再実行し、そこから原因を詰めます。",
+            annotation: "継続理由が見えているから、次の行動も説明可能になります。",
+          },
+        ],
+      },
+      s12: {
+        version,
+        title: "タスクシステム",
+        description: "作業目標を durable task record に変換し、依存関係で次の仕事を解放します。",
+        steps: [
+          {
+            type: "user_message",
+            content: "支払いモジュールのリファクタリングを、継続できる複数の仕事に分解してください。",
+            annotation: "ここで作るべきなのは session 内メモではなく durable task node です。",
+          },
+          {
+            type: "tool_call",
+            toolName: "task_create",
+            content: "{ id: 'task-auth-migrate', title: 'Migrate auth layer', blocks: ['task-payment-adapter'] }",
+            annotation: "task record には dependency edge を明示します。",
+          },
+          {
+            type: "tool_result",
+            toolName: "task_create",
+            content: "Created task-auth-migrate (status=pending, blocks=1)",
+            annotation: "task board はこの仕事の存在と依存状態を覚えます。",
+          },
+          {
+            type: "system_event",
+            content: "task_complete(task-auth-migrate) -> unlock(task-payment-adapter)",
+            annotation: "ある node が終わると、board が依存を見て次ノードを解放します。",
+          },
+          {
+            type: "assistant_text",
+            content: "まず durable task node に落としておきます。これで次の作業は記憶頼みではなく、task board 上で継続できます。",
+            annotation: "重点は todo text ではなく durable graph です。",
+          },
+        ],
+      },
+      s13: {
+        version,
+        title: "バックグラウンドタスク",
+        description: "遅い実行は runtime record と出力ファイルに逃がし、次ターンで notification preview だけを main loop へ戻します。",
+        steps: [
+          {
+            type: "user_message",
+            content: "フルテストを裏で走らせつつ、先に失敗モジュールの構造を整理してください。",
+            annotation: "前景の作業継続と、裏で遅い処理を走らせる典型場面です。",
+          },
+          {
+            type: "tool_call",
+            toolName: "background_run",
+            content: "{ command: 'pytest -q', task_id: 'rt_42' }",
+            annotation: "同期で待たず、まず runtime task を作成します。",
+          },
+          {
+            type: "system_event",
+            content: "runtime_task_saved(id=rt_42, status=running, output_file=.runtime-tasks/rt_42.log)",
+            annotation: "実行状態と完全出力の保存先を、goal task と分けて記録します。",
+          },
+          {
+            type: "system_event",
+            content: "notification_drain -> [bg:rt_42] failed preview='3 tests failing in payments/test_retry.py'",
+            annotation: "次ターン前には preview だけを context へ戻し、全文ログは出力ファイル側に置きます。",
+          },
+          {
+            type: "assistant_text",
+            content: "バックグラウンドテスト結果は戻ってきました。まず失敗サマリから retry 系のケースへ絞り、必要なら完全ログを読みます。",
+            annotation: "notification は知らせる役、output_file は原文を保持する役です。",
+          },
+        ],
+      },
+      s14: {
+        version,
+        title: "Cron スケジューラ",
+        description: "時間規則は trigger だけを担当し、実際の実行は background runtime に渡します。",
+        steps: [
+          {
+            type: "user_message",
+            content: "毎日午前 2 時にリポジトリ健全性チェックを自動実行してください。",
+            annotation: "これは今すぐ 1 回走らせる依頼ではなく、時間規則を作る依頼です。",
+          },
+          {
+            type: "tool_call",
+            toolName: "cron_schedule_create",
+            content: "{ name: 'nightly-health-check', cron: '0 2 * * *', task_template: 'repo_health_check' }",
+            annotation: "cron record は trigger rule と task template を保存します。",
+          },
+          {
+            type: "system_event",
+            content: "cron_tick -> rule matched -> runtime_task_spawn(name='repo_health_check')",
+            annotation: "時間条件が一致すると、scheduler は runtime task を生成します。",
+          },
+          {
+            type: "tool_result",
+            toolName: "runtime_task_spawn",
+            content: "Queued background runtime task #42 for nightly-health-check",
+            annotation: "実際の作業は background task layer が引き継ぎます。",
+          },
+          {
+            type: "assistant_text",
+            content: "ルールを登録しました。今後は毎日 02:00 に runtime task を起こし、その後の実行は background layer が担当します。",
+            annotation: "教えるべき要点は、trigger 面と execution 面の責務分離です。",
+          },
+        ],
+      },
+      s15: {
+        version,
+        title: "Agent Teams",
+        description: "チームメイトは長く存在する役割であり、毎回作り直す一時 subagent ではありません。",
+        steps: [
+          {
+            type: "user_message",
+            content: "主線はあなたが担当して、テスト専任とリファクタ専任の 2 人を置きたいです。",
+            annotation: "必要なのは一回きりの委譲ではなく、継続的に残る teammate です。",
+          },
+          {
+            type: "tool_call",
+            toolName: "spawn_teammate",
+            content: "{ name: 'alice', role: 'test-specialist', prompt: 'Own the failing tests.' }",
+            annotation: "TeammateManager は名前・役割・状態を持つ長期メンバーを作ります。",
+          },
+          {
+            type: "tool_result",
+            toolName: "spawn_teammate",
+            content: "Spawned 'alice' (role: test-specialist)",
+            annotation: "新しい teammate は roster に入り、後続ラウンドでも再利用できます。",
+          },
+          {
+            type: "tool_call",
+            toolName: "send_message",
+            content: "{ to: 'alice', content: '先に retry 系の失敗ケースを確認してください。' }",
+            annotation: "協調は inbox 境界を通して行い、1 本の messages[] を共有しません。",
+          },
+          {
+            type: "assistant_text",
+            content: "テスト担当の teammate をチームへ追加しました。以後は毎回作り直さず、このメンバーへ継続して仕事を振れます。",
+            annotation: "この章の増分は、長期 identity と独立 inbox です。",
+          },
+        ],
+      },
+      s16: {
+        version,
+        title: "チームプロトコル",
+        description: "承認や停止のような協調は、自由文ではなく request_id と request record を伴う構造化プロトコルで扱います。",
+        steps: [
+          {
+            type: "user_message",
+            content: "alice が認証境界を本当に触る前に、まず作業計画を私に承認依頼してください。",
+            annotation: "高リスク協調では request / response を構造化する必要があります。",
+          },
+          {
+            type: "tool_call",
+            toolName: "plan_approval",
+            content: "{ request_id: 'req_91', from: 'alice', plan: 'Refactor auth boundary before retries.' }",
+            annotation: "protocol message は request_id と payload を一緒に送ります。",
+          },
+          {
+            type: "system_event",
+            content: "request_record_saved(id=req_91, kind=plan_approval, status=pending)",
+            annotation: "追跡対象は durable request record であり、単なる一時メモではありません。",
+          },
+          {
+            type: "tool_result",
+            toolName: "plan_review",
+            content: "{ request_id: 'req_91', approve: true, feedback: 'Proceed with adapter boundary first.' }",
+            annotation: "response が返ると request 状態が pending から approved へ進みます。",
+          },
+          {
+            type: "assistant_text",
+            content: "この協調には番号と状態が付いたので、承認・拒否・タイムアウトのどれになっても同じ request を追跡できます。",
+            annotation: "protocol 層の新しい中核は request_id と request record です。",
+          },
+        ],
+      },
+      s17: {
+        version,
+        title: "自律 Agent",
+        description: "idle な teammate は共有状態を見て自分で仕事を claim し、必要な state を復元してから再開します。",
+        steps: [
+          {
+            type: "system_event",
+            content: "idle_cycle(worker='alice') -> poll inbox + task board",
+            annotation: "自律の入口は魔法ではなく、安定した idle polling です。",
+          },
+          {
+            type: "system_event",
+            content: "claimable_task_found(task='task-payment-adapter', policy='test-specialist may claim retry-related work')",
+            annotation: "self-claim は常に policy 境界の内側でのみ起こります。",
+          },
+          {
+            type: "tool_call",
+            toolName: "claim_task",
+            content: "{ teammate: 'alice', task_id: 'task-payment-adapter' }",
+            annotation: "claim 動作自体を state に残し、複数 worker の衝突を防ぎます。",
+          },
+          {
+            type: "tool_result",
+            toolName: "claim_task",
+            content: "alice claimed task-payment-adapter and resumed prior context",
+            annotation: "再開は task / role / mailbox state を見える形で復元してから行います。",
+          },
+          {
+            type: "assistant_text",
+            content: "alice は新しい指示がなくても後続作業を引き取りましたが、claim policy と team state の範囲内でのみ動いています。",
+            annotation: "この章の本質は、制御された self-claim と self-resume です。",
+          },
+        ],
+      },
+      s18: {
+        version,
+        title: "Worktree 分離",
+        description: "task は goal を持ち、worktree はその task が走る execution lane を持ちます。",
+        steps: [
+          {
+            type: "user_message",
+            content: "リファクタ作業は隔離ディレクトリで進めて、主線の変更と混ざらないようにしてください。",
+            annotation: "増えるのは新しい task 種別ではなく、独立した execution lane です。",
+          },
+          {
+            type: "tool_call",
+            toolName: "worktree_create",
+            content: "{ task_id: 'task-auth-migrate', lane: 'wt-auth-migrate' }",
+            annotation: "system は worktree を作り、task あるいは runtime slot と結び付けます。",
+          },
+          {
+            type: "system_event",
+            content: "worktree_event(type=create, task_id=task-auth-migrate, path=.worktrees/wt-auth-migrate)",
+            annotation: "lane の lifecycle event を見える形で残します。",
+          },
+          {
+            type: "tool_result",
+            toolName: "worktree_closeout",
+            content: "{ path: '.worktrees/wt-auth-migrate', keep: true, reason: 'needs follow-up review' }",
+            annotation: "closeout は keep / remove の意味を明示し、単なる終了にしません。",
+          },
+          {
+            type: "assistant_text",
+            content: "この作業は独立した lane に入りました。主線ディレクトリを汚さず進められ、あとで保持するか回収するかも closeout で判断できます。",
+            annotation: "この章の心智は、goal task と isolated lane を分けることです。",
+          },
+        ],
+      },
+      s19: {
+        version,
+        title: "MCP と Plugin",
+        description: "外部 capability も native tool と同じく、発見・ルーティング・権限・結果正規化の主線へ戻します。",
+        steps: [
+          {
+            type: "user_message",
+            content: "Figma のデザイン稿からボタン仕様を読んで、今のコンポーネントへ反映してください。",
+            annotation: "外部 capability 接続が必要な典型リクエストです。",
+          },
+          {
+            type: "system_event",
+            content: "capability_router.resolve(['native_tools', 'plugin_registry', 'mcp_servers']) -> mcp:figma.inspect",
+            annotation: "system は統一 capability bus 上で discovery と routing を行います。",
+          },
+          {
+            type: "tool_call",
+            toolName: "mcp.figma.inspect",
+            content: "{ fileId: 'design-123', node: 'PrimaryButton' }",
+            annotation: "外部 MCP capability も標準 capability として呼び出されます。",
+          },
+          {
+            type: "tool_result",
+            toolName: "mcp.figma.inspect",
+            content: "{ padding: '12x18', radius: 10, typography: 'SemiBold 14', states: ['default','hover','disabled'] }",
+            annotation: "remote response は正規化されてから main loop に戻ります。",
+          },
+          {
+            type: "assistant_text",
+            content: "デザイン仕様を取得しました。次はこの制約を現在のボタン実装へマッピングし、既存 UI と整合させます。",
+            annotation: "MCP は外の別世界ではなく、同じ control plane へ接続される能力層です。",
+          },
+        ],
+      },
+    };
+
+    return ja[version] ?? buildFallbackScenario(version, locale);
+  }
+
+  const en: Record<string, Scenario> = {
+    s07: {
+      version,
+      title: "Permission System",
+      description: "Intent passes through a permission gate before it becomes execution.",
+      steps: [
+        {
+          type: "user_message",
+          content: "Delete the whole build directory and regenerate everything.",
+          annotation: "The model is about to propose a destructive action.",
+        },
+        {
+          type: "system_event",
+          content: "permission_check(action=delete, target=build/, risk=high, mode=ask)",
+          annotation: "The raw tool request is normalized into a structured intent first.",
+        },
+        {
+          type: "tool_call",
+          toolName: "request_permission",
+          content: "{ action: 'delete', target: 'build/', reason: 'high-risk filesystem mutation' }",
+          annotation: "High-risk work goes to ask-mode instead of executing immediately.",
+        },
+        {
+          type: "tool_result",
+          toolName: "request_permission",
+          content: "User denied destructive delete. Suggest safer alternative.",
+          annotation: "The denial is written back into the loop as visible state.",
+        },
+        {
+          type: "assistant_text",
+          content: "I will not delete the entire build directory directly. A safer option is to clear generated artifacts or show the exact files first.",
+          annotation: "The model replans from the deny result instead of pretending it succeeded.",
+        },
+      ],
+    },
+    s08: {
+      version,
+      title: "Hook System",
+      description: "Lifecycle hooks add side effects around the loop without rewriting the loop.",
+      steps: [
+        {
+          type: "user_message",
+          content: "Fix login-form validation and keep an audit trail of the change.",
+          annotation: "The task needs both execution and side-channel bookkeeping.",
+        },
+        {
+          type: "system_event",
+          content: "emit pre_tool(tool=edit_file, path=ui/login.tsx)",
+          annotation: "The loop emits a normalized lifecycle event before the tool runs.",
+        },
+        {
+          type: "tool_call",
+          toolName: "edit_file",
+          content: "ui/login.tsx\n---\nvalidateEmail(value)\n-> validateEmail(value.trim())",
+          annotation: "The core path still only executes the requested tool.",
+        },
+        {
+          type: "system_event",
+          content: "hook[audit_log].append({ tool: 'edit_file', path: 'ui/login.tsx', status: 'ok' })",
+          annotation: "The audit hook consumes the event without modifying tool code.",
+        },
+        {
+          type: "assistant_text",
+          content: "The validation fix is in place, and the audit channel now contains the change record.",
+          annotation: "Hooks grow the system around the loop instead of invading the loop.",
+        },
+      ],
+    },
+    s09: {
+      version,
+      title: "Memory System",
+      description: "Only durable cross-session facts belong in memory.",
+      steps: [
+        {
+          type: "user_message",
+          content: "From now on, prefer pnpm instead of npm.",
+          annotation: "This is durable user preference, not temporary task state.",
+        },
+        {
+          type: "system_event",
+          content: "memory_load(scope=user, keys=['package_manager_preference']) -> none",
+          annotation: "Relevant long-term memory is loaded before prompt assembly.",
+        },
+        {
+          type: "tool_call",
+          toolName: "memory_write",
+          content: "{ key: 'package_manager_preference', value: 'pnpm', reason: 'user explicit preference' }",
+          annotation: "After the task, durable facts are extracted and written back.",
+        },
+        {
+          type: "tool_result",
+          toolName: "memory_write",
+          content: "Stored durable memory: package_manager_preference=pnpm",
+          annotation: "The fact is now available to future sessions.",
+        },
+        {
+          type: "assistant_text",
+          content: "Recorded. I will default to pnpm for future package-manager commands.",
+          annotation: "Memory stores stable facts, not whole conversations.",
+        },
+      ],
+    },
+    s10: {
+      version,
+      title: "System Prompt",
+      description: "The system input is assembled from ordered sections instead of one giant hidden string.",
+      steps: [
+        {
+          type: "user_message",
+          content: "Review the implementation risks around payments in this repo.",
+          annotation: "The model needs role policy, workspace state, tools, and memory together.",
+        },
+        {
+          type: "system_event",
+          content: "prompt_build = role_policy + workspace_state + tool_catalog + memory_context + task_focus",
+          annotation: "The prompt pipeline shows which sections make up the final model input.",
+        },
+        {
+          type: "tool_call",
+          toolName: "preview_prompt",
+          content: "[role_policy]\nYou are a coding agent...\n[workspace_state]\nrepo=payments-app\n[tool_catalog]\nread_file, rg, ...",
+          annotation: "This makes the assembled structure visible to the learner.",
+        },
+        {
+          type: "tool_result",
+          toolName: "preview_prompt",
+          content: "Prompt sections assembled successfully (5 sections, 2217 chars)",
+          annotation: "Only after assembly is the final input ready for the model.",
+        },
+        {
+          type: "assistant_text",
+          content: "I will inspect payment boundaries, validation, and failure handling based on the current repo state and tool context.",
+          annotation: "The model behavior comes from a structured input pipeline.",
+        },
+      ],
+    },
+    s11: {
+      version,
+      title: "Error Recovery",
+      description: "Recovery branches stay explicit so failures can turn into continued work instead of silent loops.",
+      steps: [
+        {
+          type: "user_message",
+          content: "Run the tests and fix the failing cases.",
+          annotation: "This task commonly triggers tool failures or timeouts.",
+        },
+        {
+          type: "tool_call",
+          toolName: "bash",
+          content: "pytest tests/auth/test_login.py -q",
+          annotation: "The tool runs normally first.",
+        },
+        {
+          type: "tool_result",
+          toolName: "bash",
+          content: "Error: Timeout after 120s",
+          annotation: "The system cannot just swallow the failure.",
+        },
+        {
+          type: "system_event",
+          content: "recovery_branch(reason=timeout, strategy=retry_with_narrow_scope, attempts=1/2)",
+          annotation: "Recovery classifies the reason and records why execution will continue.",
+        },
+        {
+          type: "assistant_text",
+          content: "The full test run timed out. I will retry on the narrower auth subset and use that result to localize the issue.",
+          annotation: "The recovery reason becomes visible state for the next step.",
+        },
+      ],
+    },
+    s12: {
+      version,
+      title: "Task System",
+      description: "The task board turns work goals into durable records and uses dependency edges to unlock later work.",
+      steps: [
+        {
+          type: "user_message",
+          content: "Break the payment refactor into a few durable tasks we can keep advancing.",
+          annotation: "This creates durable task records, not just a per-session todo list.",
+        },
+        {
+          type: "tool_call",
+          toolName: "task_create",
+          content: "{ id: 'task-auth-migrate', title: 'Migrate auth layer', blocks: ['task-payment-adapter'] }",
+          annotation: "The task record explicitly declares dependency and unlock edges.",
+        },
+        {
+          type: "tool_result",
+          toolName: "task_create",
+          content: "Created task-auth-migrate (status=pending, blocks=1)",
+          annotation: "The board now knows the work exists and what it is blocking.",
+        },
+        {
+          type: "system_event",
+          content: "task_complete(task-auth-migrate) -> unlock(task-payment-adapter)",
+          annotation: "Completing one node checks dependencies and unlocks downstream work.",
+        },
+        {
+          type: "assistant_text",
+          content: "I am turning the refactor into durable task nodes so the system can keep progressing without relying on conversational memory alone.",
+          annotation: "The teaching focus is the durable graph, not a temporary reminder list.",
+        },
+      ],
+    },
+    s13: {
+      version,
+      title: "Background Tasks",
+      description: "Slow commands get a runtime record, full output goes to disk, and notifications carry a preview back on a later turn.",
+      steps: [
+        {
+          type: "user_message",
+          content: "Run the full test suite in the background while we keep organizing the failing module.",
+          annotation: "This is the classic foreground-progress plus background-execution case.",
+        },
+        {
+          type: "tool_call",
+          toolName: "background_run",
+          content: "{ command: 'pytest -q', task_id: 'rt_42' }",
+          annotation: "The loop creates runtime work instead of blocking on the full command.",
+        },
+        {
+          type: "system_event",
+          content: "runtime_task_saved(id=rt_42, status=running, output_file=.runtime-tasks/rt_42.log)",
+          annotation: "The runtime record and full output path are persisted separately from the task goal.",
+        },
+        {
+          type: "system_event",
+          content: "notification_drain -> [bg:rt_42] failed preview='3 tests failing in payments/test_retry.py'",
+          annotation: "Only a preview returns to context; the full log stays on disk.",
+        },
+        {
+          type: "assistant_text",
+          content: "The background run has reported back. I will use the preview to focus the next step and read the full log only if needed.",
+          annotation: "Notifications alert the loop; output files keep the heavy detail.",
+        },
+      ],
+    },
+    s14: {
+      version,
+      title: "Cron Scheduler",
+      description: "Time rules trigger runtime work; execution still belongs to the runtime layer.",
+      steps: [
+        {
+          type: "user_message",
+          content: "Run a repo health check every day at 2:00 AM.",
+          annotation: "The user is creating a time trigger, not directly starting one execution.",
+        },
+        {
+          type: "tool_call",
+          toolName: "cron_schedule_create",
+          content: "{ name: 'nightly-health-check', cron: '0 2 * * *', task_template: 'repo_health_check' }",
+          annotation: "Cron stores a rule and a task template.",
+        },
+        {
+          type: "system_event",
+          content: "cron_tick -> rule matched -> runtime_task_spawn(name='repo_health_check')",
+          annotation: "A time hit creates runtime work instead of running the business logic directly.",
+        },
+        {
+          type: "tool_result",
+          toolName: "runtime_task_spawn",
+          content: "Queued background runtime task #42 for nightly-health-check",
+          annotation: "The background runtime takes over the actual execution.",
+        },
+        {
+          type: "assistant_text",
+          content: "The schedule is active. Every day at 02:00 it will spawn a runtime task and let the background layer execute it.",
+          annotation: "The teaching boundary is trigger-time vs execution-time responsibility.",
+        },
+      ],
+    },
+    s15: {
+      version,
+      title: "Agent Teams",
+      description: "Teammates are long-lived workers with names, roles, and inboxes, not disposable subagents.",
+      steps: [
+        {
+          type: "user_message",
+          content: "Keep me on the mainline and add one specialist for tests and one for refactors.",
+          annotation: "This requires persistent teammates rather than one-shot delegation.",
+        },
+        {
+          type: "tool_call",
+          toolName: "spawn_teammate",
+          content: "{ name: 'alice', role: 'test-specialist', prompt: 'Own the failing tests.' }",
+          annotation: "The team manager assigns a durable identity and role.",
+        },
+        {
+          type: "tool_result",
+          toolName: "spawn_teammate",
+          content: "Spawned 'alice' (role: test-specialist)",
+          annotation: "The teammate joins the roster and can be reused later.",
+        },
+        {
+          type: "tool_call",
+          toolName: "send_message",
+          content: "{ to: 'alice', content: 'Start with the retry-related failures.' }",
+          annotation: "Coordination travels through inbox boundaries instead of one shared messages[] buffer.",
+        },
+        {
+          type: "assistant_text",
+          content: "The test specialist is now part of the standing team, so I can keep assigning work without recreating a child worker each time.",
+          annotation: "Persistent identity and inboxes are the key chapter boundary.",
+        },
+      ],
+    },
+    s16: {
+      version,
+      title: "Team Protocols",
+      description: "Approvals and shutdown flows need request IDs and durable request records, not only free-form messages.",
+      steps: [
+        {
+          type: "user_message",
+          content: "Before alice changes the auth boundary, make her submit a plan for approval.",
+          annotation: "Risky coordination needs a structured request / response flow.",
+        },
+        {
+          type: "tool_call",
+          toolName: "plan_approval",
+          content: "{ request_id: 'req_91', from: 'alice', plan: 'Refactor auth boundary before retries.' }",
+          annotation: "The protocol envelope carries a request_id and payload together.",
+        },
+        {
+          type: "system_event",
+          content: "request_record_saved(id=req_91, kind=plan_approval, status=pending)",
+          annotation: "The durable request record is the real thing being tracked.",
+        },
+        {
+          type: "tool_result",
+          toolName: "plan_review",
+          content: "{ request_id: 'req_91', approve: true, feedback: 'Proceed with adapter boundary first.' }",
+          annotation: "The explicit response moves state from pending to approved.",
+        },
+        {
+          type: "assistant_text",
+          content: "This collaboration now has a stable request record. Future approval, rejection, or timeout can all resolve against the same ID.",
+          annotation: "request_id plus durable state is the actual protocol upgrade.",
+        },
+      ],
+    },
+    s17: {
+      version,
+      title: "Autonomous Agents",
+      description: "Workers become autonomous when they can poll for eligible work, claim it, and resume with the right state.",
+      steps: [
+        {
+          type: "system_event",
+          content: "idle_cycle(worker='alice') -> poll inbox + task board",
+          annotation: "Autonomy begins with stable idle polling, not with magic.",
+        },
+        {
+          type: "system_event",
+          content: "claimable_task_found(task='task-payment-adapter', policy='test-specialist may claim retry-related work')",
+          annotation: "Only work allowed by the self-claim policy becomes eligible.",
+        },
+        {
+          type: "tool_call",
+          toolName: "claim_task",
+          content: "{ teammate: 'alice', task_id: 'task-payment-adapter' }",
+          annotation: "The claim action itself writes state so multiple workers do not collide.",
+        },
+        {
+          type: "tool_result",
+          toolName: "claim_task",
+          content: "alice claimed task-payment-adapter and resumed prior context",
+          annotation: "The worker resumes from visible task and role state, not from nowhere.",
+        },
+        {
+          type: "assistant_text",
+          content: "alice has picked up the next step without a new user turn, but still remains bounded by claim rules and team state.",
+          annotation: "Controlled self-claim and self-resume are the important autonomy mechanics.",
+        },
+      ],
+    },
+    s18: {
+      version,
+      title: "Worktree Isolation",
+      description: "Tasks get their own execution lanes, run in isolated directories, and return through explicit closeout semantics.",
+      steps: [
+        {
+          type: "user_message",
+          content: "Give the refactor task its own isolated directory so it does not interfere with the mainline.",
+          annotation: "The new object here is an execution lane, not a new task type.",
+        },
+        {
+          type: "tool_call",
+          toolName: "worktree_create",
+          content: "{ task_id: 'task-auth-migrate', lane: 'wt-auth-migrate' }",
+          annotation: "The system allocates a worktree and binds it to the task record.",
+        },
+        {
+          type: "system_event",
+          content: "worktree_event(type=create, task_id=task-auth-migrate, path=.worktrees/wt-auth-migrate)",
+          annotation: "Execution-lane lifecycle events are emitted explicitly.",
+        },
+        {
+          type: "tool_result",
+          toolName: "worktree_closeout",
+          content: "{ path: '.worktrees/wt-auth-migrate', keep: true, reason: 'needs follow-up review' }",
+          annotation: "Closeout decides whether the lane is preserved or reclaimed.",
+        },
+        {
+          type: "assistant_text",
+          content: "That refactor is now running in its own lane, and the closeout record will decide whether the environment stays around for follow-up work.",
+          annotation: "The chapter boundary is task goal vs isolated execution lane.",
+        },
+      ],
+    },
+    s19: {
+      version,
+      title: "MCP & Plugin",
+      description: "External capability still follows the same discovery, routing, policy, and write-back path as native tools.",
+      steps: [
+        {
+          type: "user_message",
+          content: "Inspect the button spec from Figma and sync it into the current component library.",
+          annotation: "This requires external capability instead of only local tools.",
+        },
+        {
+          type: "system_event",
+          content: "capability_router.resolve(['native_tools', 'plugin_registry', 'mcp_servers']) -> mcp:figma.inspect",
+          annotation: "The system resolves the request on one shared capability bus.",
+        },
+        {
+          type: "tool_call",
+          toolName: "mcp.figma.inspect",
+          content: "{ fileId: 'design-123', node: 'PrimaryButton' }",
+          annotation: "The external MCP capability is called through the same routing model.",
+        },
+        {
+          type: "tool_result",
+          toolName: "mcp.figma.inspect",
+          content: "{ padding: '12x18', radius: 10, typography: 'SemiBold 14', states: ['default','hover','disabled'] }",
+          annotation: "The remote response is normalized before returning to the loop.",
+        },
+        {
+          type: "assistant_text",
+          content: "I have the design spec. Next I will map those constraints into the current button component implementation.",
+          annotation: "MCP is not a separate universe. It plugs back into the same control plane.",
+        },
+      ],
+    },
+  };
+
+  return en[version] ?? buildFallbackScenario(version, locale);
+}
+
+function buildFallbackScenario(version: string, locale: string): Scenario {
+  return {
+    version,
+    title: version,
+    description:
+      locale === "zh"
+        ? "该章节暂未提供专属模拟脚本，当前展示的是最小占位场景。"
+        : locale === "ja"
+          ? "この章にはまだ専用シミュレーションがないため、最小のプレースホルダーを表示しています。"
+        : "This chapter does not have a dedicated simulation yet. Showing a minimal placeholder.",
+    steps: [
+      {
+        type: "system_event",
+        content:
+          locale === "zh"
+            ? `simulator_unavailable(version=${version})`
+            : `simulator_unavailable(version=${version})`,
+        annotation:
+          locale === "zh"
+            ? "可视化层已迁移到新章节主线，但这里还缺专门的逐步模拟数据。"
+            : locale === "ja"
+              ? "可視化レイヤーは新しい章立てへ移りましたが、この章専用の段階シナリオはまだ未整備です。"
+            : "The visualization layer has moved to the new chapter map, but this session still lacks a dedicated step-by-step scenario.",
+      },
+    ],
+  };
+}
+
 interface AgentLoopSimulatorProps {
   version: string;
 }
 
 export function AgentLoopSimulator({ version }: AgentLoopSimulatorProps) {
   const t = useTranslations("version");
+  const locale = useLocale();
   const [scenario, setScenario] = useState<Scenario | null>(null);
   const scrollRef = useRef<HTMLDivElement>(null);
 
   useEffect(() => {
-    const loader = scenarioModules[version];
-    if (loader) {
-      loader().then((mod) => setScenario(mod.default));
+    let active = true;
+    setScenario(null);
+
+    if (isGenericScenarioVersion(version)) {
+      setScenario(buildGenericScenario(version, locale));
+      return () => {
+        active = false;
+      };
+    }
+
+    const loader = scenarioModules[resolveLegacySessionAssetVersion(version)];
+    if (!loader) {
+      setScenario(buildFallbackScenario(version, locale));
+      return () => {
+        active = false;
+      };
     }
-  }, [version]);
+
+    loader().then((mod) => {
+      if (!active) return;
+      setScenario({ ...mod.default, version });
+    });
+
+    return () => {
+      active = false;
+    };
+  }, [locale, version]);
 
   const sim = useSimulator(scenario?.steps ?? []);
 
@@ -50,7 +1449,27 @@ export function AgentLoopSimulator({ version }: AgentLoopSimulatorProps) {
     }
   }, [sim.visibleSteps.length]);
 
-  if (!scenario) return null;
+  if (!scenario) {
+    return (
+      <section>
+        <h2 className="mb-2 text-xl font-semibold">{t("simulator")}</h2>
+        <div className="rounded-xl border border-[var(--color-border)] bg-[var(--color-bg)] p-6 text-sm text-[var(--color-text-secondary)]">
+          {locale === "zh"
+            ? "正在加载当前章节的模拟场景..."
+            : locale === "ja"
+              ? "この章のシミュレーションを読み込んでいます..."
+              : "Loading the simulation scenario for this chapter..."}
+        </div>
+      </section>
+    );
+  }
+
+  const readyText =
+    locale === "zh"
+      ? "点击播放或单步开始"
+      : locale === "ja"
+        ? "再生またはステップで開始"
+        : "Press Play or Step to begin";
 
   return (
     <section>
@@ -81,7 +1500,7 @@ export function AgentLoopSimulator({ version }: AgentLoopSimulatorProps) {
         >
           {sim.visibleSteps.length === 0 && (
             <div className="flex flex-1 items-center justify-center text-sm text-[var(--color-text-secondary)]">
-              Press Play or Step to begin
+              {readyText}
             </div>
           )}
           <AnimatePresence mode="popLayout">
diff --git a/web/src/components/simulator/simulator-controls.tsx b/web/src/components/simulator/simulator-controls.tsx
index 056e88a04..764d590e0 100644
--- a/web/src/components/simulator/simulator-controls.tsx
+++ b/web/src/components/simulator/simulator-controls.tsx
@@ -41,6 +41,7 @@ export function SimulatorControls({
             onClick={onPause}
             className="flex h-9 w-9 items-center justify-center rounded-lg bg-zinc-900 text-white transition-colors hover:bg-zinc-700 dark:bg-white dark:text-zinc-900 dark:hover:bg-zinc-200"
             title={t("pause")}
+            aria-label={t("pause")}
           >
             <Pause size={16} />
           </button>
@@ -50,6 +51,7 @@ export function SimulatorControls({
             disabled={isComplete}
             className="flex h-9 w-9 items-center justify-center rounded-lg bg-zinc-900 text-white transition-colors hover:bg-zinc-700 disabled:opacity-40 dark:bg-white dark:text-zinc-900 dark:hover:bg-zinc-200"
             title={t("play")}
+            aria-label={t("play")}
           >
             <Play size={16} />
           </button>
@@ -59,6 +61,7 @@ export function SimulatorControls({
           disabled={isComplete}
           className="flex h-9 w-9 items-center justify-center rounded-lg border border-[var(--color-border)] transition-colors hover:bg-zinc-100 disabled:opacity-40 dark:hover:bg-zinc-800"
           title={t("step")}
+          aria-label={t("step")}
         >
           <SkipForward size={16} />
         </button>
@@ -66,6 +69,7 @@ export function SimulatorControls({
           onClick={onReset}
           className="flex h-9 w-9 items-center justify-center rounded-lg border border-[var(--color-border)] transition-colors hover:bg-zinc-100 dark:hover:bg-zinc-800"
           title={t("reset")}
+          aria-label={t("reset")}
         >
           <RotateCcw size={16} />
         </button>
diff --git a/web/src/components/simulator/simulator-message.tsx b/web/src/components/simulator/simulator-message.tsx
index 2984e3d49..a777e2eb9 100644
--- a/web/src/components/simulator/simulator-message.tsx
+++ b/web/src/components/simulator/simulator-message.tsx
@@ -2,6 +2,7 @@
 
 import { motion } from "framer-motion";
 import { cn } from "@/lib/utils";
+import { useLocale } from "@/lib/i18n";
 import type { SimStep } from "@/types/agent-data";
 import { User, Bot, Terminal, ArrowRight, AlertCircle } from "lucide-react";
 
@@ -47,8 +48,34 @@ const TYPE_CONFIG: Record<
 };
 
 export function SimulatorMessage({ step, index }: SimulatorMessageProps) {
+  const locale = useLocale();
+  const labels =
+    locale === "zh"
+      ? {
+          user_message: "用户",
+          assistant_text: "助手",
+          tool_call: "工具调用",
+          tool_result: "工具结果",
+          system_event: "系统事件",
+        }
+      : locale === "ja"
+        ? {
+            user_message: "ユーザー",
+            assistant_text: "アシスタント",
+            tool_call: "ツール呼び出し",
+            tool_result: "ツール結果",
+            system_event: "システムイベント",
+          }
+        : {
+            user_message: "User",
+            assistant_text: "Assistant",
+            tool_call: "Tool Call",
+            tool_result: "Tool Result",
+            system_event: "System",
+          };
   const config = TYPE_CONFIG[step.type] || TYPE_CONFIG.assistant_text;
   const Icon = config.icon;
+  const label = labels[step.type as keyof typeof labels] || config.label;
 
   return (
     <motion.div
@@ -64,7 +91,7 @@ export function SimulatorMessage({ step, index }: SimulatorMessageProps) {
       <div className="mb-1.5 flex items-center gap-2">
         <Icon size={14} className="shrink-0 text-[var(--color-text-secondary)]" />
         <span className="text-xs font-medium text-[var(--color-text-secondary)]">
-          {config.label}
+          {label}
           {step.toolName && (
             <span className="ml-1.5 font-mono text-[var(--color-text)]">
               {step.toolName}
diff --git a/web/src/components/timeline/timeline.tsx b/web/src/components/timeline/timeline.tsx
index a30647b92..ec9a52d13 100644
--- a/web/src/components/timeline/timeline.tsx
+++ b/web/src/components/timeline/timeline.tsx
@@ -4,34 +4,34 @@ import Link from "next/link";
 import { motion } from "framer-motion";
 import { useTranslations, useLocale } from "@/lib/i18n";
 import { LEARNING_PATH, VERSION_META, LAYERS } from "@/lib/constants";
+import { getVersionContent } from "@/lib/version-content";
 import { LayerBadge } from "@/components/ui/badge";
 import { cn } from "@/lib/utils";
 import versionsData from "@/data/generated/versions.json";
 
 const LAYER_DOT_BG: Record<string, string> = {
-  tools: "bg-blue-500",
-  planning: "bg-emerald-500",
-  memory: "bg-purple-500",
-  concurrency: "bg-amber-500",
-  collaboration: "bg-red-500",
+  core: "bg-blue-500",
+  hardening: "bg-emerald-500",
+  runtime: "bg-amber-500",
+  platform: "bg-red-500",
 };
 
 const LAYER_LINE_BG: Record<string, string> = {
-  tools: "bg-blue-500/30",
-  planning: "bg-emerald-500/30",
-  memory: "bg-purple-500/30",
-  concurrency: "bg-amber-500/30",
-  collaboration: "bg-red-500/30",
+  core: "bg-blue-500/30",
+  hardening: "bg-emerald-500/30",
+  runtime: "bg-amber-500/30",
+  platform: "bg-red-500/30",
 };
 
 const LAYER_BAR_BG: Record<string, string> = {
-  tools: "bg-blue-500",
-  planning: "bg-emerald-500",
-  memory: "bg-purple-500",
-  concurrency: "bg-amber-500",
-  collaboration: "bg-red-500",
+  core: "bg-blue-500",
+  hardening: "bg-emerald-500",
+  runtime: "bg-amber-500",
+  platform: "bg-red-500",
 };
 
+const LAYER_HEADER_BG = LAYER_BAR_BG;
+
 function getVersionData(id: string) {
   return versionsData.versions.find((v) => v.id === id);
 }
@@ -45,10 +45,13 @@ const MAX_LOC = Math.max(
 export function Timeline() {
   const t = useTranslations("timeline");
   const tv = useTranslations("version");
+  const tSession = useTranslations("sessions");
+  const tLayer = useTranslations("layer_labels");
+  const tLayersPage = useTranslations("layers");
   const locale = useLocale();
 
   return (
-    <div className="flex flex-col gap-12">
+    <div className="flex flex-col gap-12 overflow-x-hidden">
       {/* Layer Legend */}
       <div>
         <h3 className="mb-3 text-sm font-medium text-[var(--color-text-secondary)]">
@@ -60,7 +63,7 @@ export function Timeline() {
               <span
                 className={cn("h-3 w-3 rounded-full", LAYER_DOT_BG[layer.id])}
               />
-              <span className="text-xs font-medium">{layer.label}</span>
+              <span className="text-xs font-medium">{tLayer(layer.id)}</span>
             </div>
           ))}
         </div>
@@ -71,97 +74,143 @@ export function Timeline() {
         {LEARNING_PATH.map((versionId, index) => {
           const meta = VERSION_META[versionId];
           const data = getVersionData(versionId);
+          const content = getVersionContent(versionId, locale);
           if (!meta || !data) return null;
 
           const isLast = index === LEARNING_PATH.length - 1;
           const locPercent = Math.round((data.loc / MAX_LOC) * 100);
+          const previousVersion = index > 0 ? LEARNING_PATH[index - 1] : null;
+          const previousLayer = previousVersion ? VERSION_META[previousVersion]?.layer : null;
+          const isLayerStart = previousLayer !== meta.layer;
+          const layerMeta = LAYERS.find((layer) => layer.id === meta.layer);
+          const layerRange =
+            layerMeta && layerMeta.versions.length > 0
+              ? `${layerMeta.versions[0]}-${layerMeta.versions[layerMeta.versions.length - 1]}`
+              : versionId;
 
           return (
-            <div key={versionId} className="relative flex gap-4 pb-8 sm:gap-6">
-              {/* Timeline line + dot */}
-              <div className="flex flex-col items-center">
-                <div
-                  className={cn(
-                    "z-10 flex h-8 w-8 shrink-0 items-center justify-center rounded-full ring-4 ring-[var(--color-bg)] sm:h-10 sm:w-10",
-                    LAYER_DOT_BG[meta.layer]
-                  )}
+            <div key={versionId} className="space-y-4">
+              {isLayerStart && layerMeta && (
+                <motion.section
+                  initial={{ opacity: 0, y: 18 }}
+                  whileInView={{ opacity: 1, y: 0 }}
+                  viewport={{ once: true, margin: "-60px" }}
+                  transition={{ duration: 0.32 }}
+                  className="rounded-[24px] border border-zinc-200/80 bg-[linear-gradient(135deg,rgba(255,255,255,0.98),rgba(244,244,245,0.9))] p-5 shadow-sm dark:border-zinc-800/80 dark:bg-[linear-gradient(135deg,rgba(24,24,27,0.96),rgba(9,9,11,0.92))]"
                 >
-                  <span className="text-[10px] font-bold text-white sm:text-xs">
-                    {versionId.replace("s", "").replace("_mini", "m")}
-                  </span>
-                </div>
-                {!isLast && (
+                  <div className="flex flex-wrap items-start justify-between gap-3">
+                    <div>
+                      <div className="flex flex-wrap items-center gap-2">
+                        <LayerBadge layer={meta.layer}>{tLayer(meta.layer)}</LayerBadge>
+                        <span className="text-xs uppercase tracking-[0.2em] text-zinc-400">
+                          {layerRange}
+                        </span>
+                      </div>
+                      <h3 className="mt-3 text-lg font-semibold text-zinc-950 dark:text-zinc-50">
+                        {tLayersPage(meta.layer)}
+                      </h3>
+                      <p className="mt-2 max-w-3xl text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                        {tLayersPage(`${meta.layer}_outcome`)}
+                      </p>
+                    </div>
+                    <div
+                      className={cn(
+                        "rounded-full px-3 py-1 text-xs font-semibold uppercase tracking-[0.16em] text-white",
+                        LAYER_HEADER_BG[meta.layer]
+                      )}
+                    >
+                      {t("layer_legend")}
+                    </div>
+                  </div>
+                </motion.section>
+              )}
+
+              <div className="relative flex gap-4 pb-8 sm:gap-6">
+                {/* Timeline line + dot */}
+                <div className="flex flex-col items-center">
                   <div
                     className={cn(
-                      "w-0.5 flex-1",
-                      LAYER_LINE_BG[
-                        VERSION_META[LEARNING_PATH[index + 1]]?.layer || meta.layer
-                      ]
+                      "z-10 flex h-8 w-8 shrink-0 items-center justify-center rounded-full ring-4 ring-[var(--color-bg)] sm:h-10 sm:w-10",
+                      LAYER_DOT_BG[meta.layer]
                     )}
-                  />
-                )}
-              </div>
-
-              {/* Content card */}
-              <div className="flex-1 pb-2">
-                <motion.div
-                  initial={{ opacity: 0, x: 30 }}
-                  whileInView={{ opacity: 1, x: 0 }}
-                  viewport={{ once: true, margin: "-50px" }}
-                  transition={{ duration: 0.4, delay: 0.1 }}
-                  className="rounded-xl border border-[var(--color-border)] bg-[var(--color-bg)] p-4 transition-colors hover:border-[var(--color-text-secondary)]/30 sm:p-5"
-                >
-                  <div className="flex flex-wrap items-start gap-2">
-                    <LayerBadge layer={meta.layer}>{versionId}</LayerBadge>
-                    <span className="text-xs text-[var(--color-text-secondary)]">
-                      {meta.coreAddition}
-                    </span>
-                  </div>
-
-                  <h3 className="mt-2 text-base font-semibold sm:text-lg">
-                    {meta.title}
-                    <span className="ml-2 text-sm font-normal text-[var(--color-text-secondary)]">
-                      {meta.subtitle}
-                    </span>
-                  </h3>
-
-                  {/* Stats row */}
-                  <div className="mt-3 flex flex-wrap items-center gap-4 text-xs text-[var(--color-text-secondary)]">
-                    <span className="tabular-nums">
-                      {data.loc} {tv("loc")}
-                    </span>
-                    <span className="tabular-nums">
-                      {data.tools.length} {tv("tools")}
+                  >
+                    <span className="text-[10px] font-bold text-white sm:text-xs">
+                      {versionId.replace("s", "").replace("_mini", "m")}
                     </span>
                   </div>
-
-                  {/* LOC bar */}
-                  <div className="mt-2 h-1.5 w-full overflow-hidden rounded-full bg-zinc-100 dark:bg-zinc-800">
+                  {!isLast && (
                     <div
                       className={cn(
-                        "h-full rounded-full transition-all",
-                        LAYER_BAR_BG[meta.layer]
+                        "w-0.5 flex-1",
+                        LAYER_LINE_BG[
+                          VERSION_META[LEARNING_PATH[index + 1]]?.layer || meta.layer
+                        ]
                       )}
-                      style={{ width: `${locPercent}%` }}
                     />
-                  </div>
-
-                  {/* Key insight */}
-                  {meta.keyInsight && (
-                    <p className="mt-3 text-sm italic text-[var(--color-text-secondary)]">
-                      &ldquo;{meta.keyInsight}&rdquo;
-                    </p>
                   )}
+                </div>
 
-                  {/* Link */}
-                  <Link
-                    href={`/${locale}/${versionId}`}
-                    className="mt-3 inline-flex items-center gap-1 text-sm font-medium text-zinc-900 hover:underline dark:text-zinc-100"
+                {/* Content card */}
+                <div className="min-w-0 flex-1 pb-2">
+                  <motion.div
+                    initial={{ opacity: 0, x: 30 }}
+                    whileInView={{ opacity: 1, x: 0 }}
+                    viewport={{ once: true, margin: "-50px" }}
+                    transition={{ duration: 0.4, delay: 0.1 }}
+                    className="w-full min-w-0 rounded-xl border border-[var(--color-border)] bg-[var(--color-bg)] p-4 transition-colors hover:border-[var(--color-text-secondary)]/30 sm:p-5"
                   >
-                    {t("learn_more")}
-                    <span aria-hidden="true">&rarr;</span>
-                  </Link>
-                </motion.div>
+                    <div className="flex min-w-0 flex-wrap items-start gap-2">
+                      <LayerBadge layer={meta.layer}>{versionId}</LayerBadge>
+                      <span className="min-w-0 break-words text-xs text-[var(--color-text-secondary)]">
+                        {content.coreAddition}
+                      </span>
+                    </div>
+
+                    <h3 className="mt-2 break-words text-base font-semibold sm:text-lg">
+                      {tSession(versionId) || meta.title}
+                      <span className="ml-2 break-words text-sm font-normal text-[var(--color-text-secondary)]">
+                        {content.subtitle}
+                      </span>
+                    </h3>
+
+                    {/* Stats row */}
+                    <div className="mt-3 flex flex-wrap items-center gap-4 text-xs text-[var(--color-text-secondary)]">
+                      <span className="tabular-nums">
+                        {data.loc} {tv("loc")}
+                      </span>
+                      <span className="tabular-nums">
+                        {data.tools.length} {tv("tools")}
+                      </span>
+                    </div>
+
+                    {/* LOC bar */}
+                    <div className="mt-2 h-1.5 w-full overflow-hidden rounded-full bg-zinc-100 dark:bg-zinc-800">
+                      <div
+                        className={cn(
+                          "h-full rounded-full transition-all",
+                          LAYER_BAR_BG[meta.layer]
+                        )}
+                        style={{ width: `${locPercent}%` }}
+                      />
+                    </div>
+
+                    {/* Key insight */}
+                    {content.keyInsight && (
+                      <p className="mt-3 text-sm italic text-[var(--color-text-secondary)]">
+                        &ldquo;{content.keyInsight}&rdquo;
+                      </p>
+                    )}
+
+                    {/* Link */}
+                    <Link
+                      href={`/${locale}/${versionId}`}
+                      className="mt-3 inline-flex items-center gap-1 text-sm font-medium text-zinc-900 hover:underline dark:text-zinc-100"
+                    >
+                      {t("learn_more")}
+                      <span aria-hidden="true">&rarr;</span>
+                    </Link>
+                  </motion.div>
+                </div>
               </div>
             </div>
           );
diff --git a/web/src/components/ui/badge.tsx b/web/src/components/ui/badge.tsx
index e80d61b4b..64af170ec 100644
--- a/web/src/components/ui/badge.tsx
+++ b/web/src/components/ui/badge.tsx
@@ -1,15 +1,13 @@
 import { cn } from "@/lib/utils";
 
 const LAYER_COLORS = {
-  tools:
+  core:
     "bg-blue-100 text-blue-800 dark:bg-blue-900/30 dark:text-blue-300",
-  planning:
+  hardening:
     "bg-emerald-100 text-emerald-800 dark:bg-emerald-900/30 dark:text-emerald-300",
-  memory:
-    "bg-purple-100 text-purple-800 dark:bg-purple-900/30 dark:text-purple-300",
-  concurrency:
+  runtime:
     "bg-amber-100 text-amber-800 dark:bg-amber-900/30 dark:text-amber-300",
-  collaboration:
+  platform:
     "bg-red-100 text-red-800 dark:bg-red-900/30 dark:text-red-300",
 } as const;
 
diff --git a/web/src/components/visualizations/generic-session-overview.tsx b/web/src/components/visualizations/generic-session-overview.tsx
new file mode 100644
index 000000000..ed10ff401
--- /dev/null
+++ b/web/src/components/visualizations/generic-session-overview.tsx
@@ -0,0 +1,1017 @@
+"use client";
+
+import { motion } from "framer-motion";
+import { useLocale, useTranslations } from "@/lib/i18n";
+import { VERSION_META, type VersionId } from "@/lib/constants";
+import { getChapterGuide } from "@/lib/chapter-guides";
+import { getVersionContent } from "@/lib/version-content";
+import { LayerBadge } from "@/components/ui/badge";
+import {
+  LateStageTeachingMap,
+  hasLateStageTeachingMap,
+} from "./late-stage-teaching-map";
+
+interface OverviewSection {
+  title: string;
+  body: string;
+}
+
+interface OverviewCopy {
+  eyebrow: string;
+  summary: string;
+  sections: OverviewSection[];
+  flowLabel: string;
+  flow: string[];
+  cautionLabel: string;
+  caution: string;
+  outcomeLabel: string;
+  outcome: string;
+}
+
+const SURFACE_CLASSES: Record<string, string> = {
+  core: "from-blue-500/10 via-blue-500/5 to-transparent",
+  hardening: "from-emerald-500/10 via-emerald-500/5 to-transparent",
+  runtime: "from-amber-500/10 via-amber-500/5 to-transparent",
+  platform: "from-red-500/10 via-red-500/5 to-transparent",
+};
+
+const RING_CLASSES: Record<string, string> = {
+  core: "ring-blue-500/20",
+  hardening: "ring-emerald-500/20",
+  runtime: "ring-amber-500/20",
+  platform: "ring-red-500/20",
+};
+
+const ZH_COPY: Record<string, OverviewCopy> = {
+  s07: {
+    eyebrow: "执行前先过权限闸门",
+    summary:
+      "权限系统的核心不是把工具藏起来，而是把“模型想做什么”先翻译成结构化意图，再按策略决定允许、拒绝还是询问用户。",
+    sections: [
+      {
+        title: "输入要先规范化",
+        body:
+          "不要直接拿原始 tool call 执行。先抽出动作类型、目标路径、风险级别，变成权限层能判断的统一结构。",
+      },
+      {
+        title: "策略是独立控制面",
+        body:
+          "允许名单、只读模式、危险命令拦截、需要确认的模式，都应该在权限层统一判断，而不是散在每个工具里。",
+      },
+      {
+        title: "结果必须可回写",
+        body:
+          "无论是 allow、deny 还是 ask，最终都要回到主循环，成为模型下一步推理可以看到的上下文。",
+      },
+    ],
+    flowLabel: "Permission Pipeline",
+    flow: ["模型产生命令", "提取意图", "策略判定", "执行或回写拒绝"],
+    cautionLabel: "最容易讲错",
+    caution:
+      "权限系统不是一个 if 语句集合。它是主循环前的独立闸门，负责把不安全执行拦在工具层之前。",
+    outcomeLabel: "学完应掌握",
+    outcome:
+      "你应该能手写一个统一 permission check，让所有工具共享同一套 allow / deny / ask 语义。",
+  },
+  s08: {
+    eyebrow: "在循环外加扩展点",
+    summary:
+      "Hook 的价值是把日志、审计、追踪、策略注入这些旁路能力挂到生命周期事件上，而不是反复改主循环核心代码。",
+    sections: [
+      {
+        title: "核心循环保持最小",
+        body:
+          "主循环只负责推进状态。pre_tool、post_tool、on_error 这类附加动作，应该通过 hook 注册进来。",
+      },
+      {
+        title: "事件边界要稳定",
+        body:
+          "Hook 接收到的不是随意拼出来的文本，而是统一事件对象，例如 toolName、input、result、error、duration。",
+      },
+      {
+        title: "副作用与主流程解耦",
+        body:
+          "这样新增审计、埋点、自动修复建议时，不会反复打断主线心智，也不会污染每个工具处理函数。",
+      },
+    ],
+    flowLabel: "Lifecycle Events",
+    flow: ["主循环推进", "发出事件", "Hook 观察", "副作用回写"],
+    cautionLabel: "最容易讲错",
+    caution:
+      "Hook 不是另一个主循环。它应该观察和补充，而不是偷偷接管核心状态机。",
+    outcomeLabel: "学完应掌握",
+    outcome:
+      "你应该能定义一套生命周期事件，并用注册表把多个 hook 稳定挂接到同一个循环上。",
+  },
+  s09: {
+    eyebrow: "把跨会话知识单独存放",
+    summary:
+      "Memory 系统只保存那些跨轮次、跨会话、无法从当前工作目录重新推导出来的事实，而不是把所有历史都塞进长期记忆。",
+    sections: [
+      {
+        title: "记忆要有类型",
+        body:
+          "用户偏好、项目约束、稳定环境信息应该分类型存，不要把随手观察到的临时输出和真实长期知识混在一起。",
+      },
+      {
+        title: "读取与写入分两段",
+        body:
+          "模型调用前加载相关记忆，任务结束后再提炼新增记忆。这样主循环里每次读写点都清晰可控。",
+      },
+      {
+        title: "记忆不能替代上下文",
+        body:
+          "短期上下文负责当前过程，长期记忆只保留压缩后仍然重要的事实。两者职责必须明确分层。",
+      },
+    ],
+    flowLabel: "Memory Lifecycle",
+    flow: ["加载记忆", "组装输入", "完成工作", "提炼并落盘"],
+    cautionLabel: "最容易讲错",
+    caution:
+      "Memory 不是无限对话历史仓库。真正要教清楚的是“什么值得记”和“什么时候写回”。",
+    outcomeLabel: "学完应掌握",
+    outcome:
+      "你应该能区分短期 messages[]、压缩摘要、长期 memory 三种状态容器各自的职责。",
+  },
+  s10: {
+    eyebrow: "把提示词拆成装配流水线",
+    summary:
+      "系统提示词不应该被讲成一大段神秘文本。真正关键的是：哪些信息先拼、哪些后拼、哪些属于稳定规则、哪些属于运行时状态。",
+    sections: [
+      {
+        title: "稳定规则单独存放",
+        body:
+          "角色、底线、安全策略这些长期稳定内容，与任务说明、目录信息、临时记忆不该写在同一段字符串里。",
+      },
+      {
+        title: "运行时片段按顺序装配",
+        body:
+          "工作目录、可用工具、记忆、待办、错误恢复提示等都应该有明确的拼接顺序，避免提示词结构漂移。",
+      },
+      {
+        title: "输入其实是控制平面",
+        body:
+          "Prompt pipeline 决定了模型在每一轮能看到什么、看见的顺序是什么，这本质上就是控制系统行为。",
+      },
+    ],
+    flowLabel: "Prompt Assembly",
+    flow: ["稳定规则", "运行时状态", "工具/记忆注入", "形成最终输入"],
+    cautionLabel: "最容易讲错",
+    caution:
+      "不要把“提示词工程”讲成玄学调参。这里真正需要讲清的是数据来源、拼接顺序和信息边界。",
+    outcomeLabel: "学完应掌握",
+    outcome:
+      "你应该能把 system prompt 改写成一条显式的构建流水线，而不是一段越来越长的大字符串。",
+  },
+  s11: {
+    eyebrow: "失败后仍能继续推进",
+    summary:
+      "结构更完整的 Agent 关键不是永不出错，而是每次出错后都知道当前处于什么恢复分支，以及应该怎样把失败转成下一步可继续的状态。",
+    sections: [
+      {
+        title: "错误先分类",
+        body:
+          "权限拒绝、工具异常、环境缺失、超时、冲突写入，不应该都走同一条 retry 逻辑。先分类，恢复才会稳定。",
+      },
+      {
+        title: "恢复原因要显式",
+        body:
+          "继续执行前，要把“为什么继续”写回上下文，例如 retry、fallback、user confirmation required，而不是静默吞错。",
+      },
+      {
+        title: "恢复分支有上限",
+        body:
+          "重试次数、降级路径、终止条件都要清楚。否则系统只是把失败隐藏成无限循环。",
+      },
+    ],
+    flowLabel: "Recovery Branches",
+    flow: ["发现错误", "分类原因", "选择恢复分支", "带着原因继续"],
+    cautionLabel: "最容易讲错",
+    caution:
+      "错误恢复不是 try/except 包一下。真正重要的是恢复状态也要进入消息历史，成为模型可见事实。",
+    outcomeLabel: "学完应掌握",
+    outcome:
+      "你应该能设计 continuation reason，并把 retry / fallback / stop 变成可解释的状态迁移。",
+  },
+  s12: {
+    eyebrow: "把会话步骤升级成持久工作图",
+    summary:
+      "任务系统不是把 todo 列表存盘那么简单，而是把工作拆成可追踪、可解锁、可跨轮次继续推进的 durable task graph。",
+    sections: [
+      {
+        title: "任务先是记录，不是线程",
+        body:
+          "TaskRecord 记录目标、状态、依赖和解锁关系。它表达的是“还有什么工作要推进”，不是“现在谁正在跑”。",
+      },
+      {
+        title: "依赖关系必须显式",
+        body:
+          "blockedBy、blocks、status 这类字段要写清楚，不然后续任务何时能开始、为什么还不能开始都会变得模糊。",
+      },
+      {
+        title: "任务板负责推进顺序",
+        body:
+          "真正要教清楚的是：完成一个节点以后，系统如何检查依赖、解锁后继任务，并把状态变化回写到任务板。",
+      },
+    ],
+    flowLabel: "Durable Task Graph",
+    flow: ["创建任务记录", "写入依赖关系", "完成当前节点", "解锁后续任务"],
+    cautionLabel: "最容易讲错",
+    caution:
+      "Task 不是后台线程，也不是模型的一轮计划文本。它是系统里一条可持久推进的工作记录。",
+    outcomeLabel: "学完应掌握",
+    outcome:
+      "你应该能实现带依赖和解锁逻辑的最小任务板，而不是只会维护会话级 todo 列表。",
+  },
+  s13: {
+    eyebrow: "把目标记录和运行槽位分开",
+    summary:
+      "后台任务这一章真正要教的是：任务目标依然留在 task board，正在执行的那一份工作则进入独立的 runtime record，并用通知把结果带回主循环。",
+    sections: [
+      {
+        title: "运行记录必须独立",
+        body:
+          "RuntimeTaskRecord 应该有自己的 id、status、started_at、result_preview、output_file。它描述的是“这次执行本身”，不是任务目标本体。",
+      },
+      {
+        title: "预览和全文要分层",
+        body:
+          "完整输出写文件，通知里只放 preview。这样模型先知道“有结果了、结果大概是什么”，真要看细节再去读文件。",
+      },
+      {
+        title: "通知是回到主循环的桥",
+        body:
+          "后台线程并不直接改模型状态。它只写 runtime record 和 notification，等下一轮前再统一注入上下文。",
+      },
+    ],
+    flowLabel: "Runtime Task Return Path",
+    flow: ["创建 runtime record", "后台执行", "写入 preview / output", "下一轮通知回写"],
+    cautionLabel: "最容易讲错",
+    caution:
+      "后台任务不是另一个会思考的 agent。并行的是等待和执行，不是主循环本身。",
+    outcomeLabel: "学完应掌握",
+    outcome:
+      "你应该能把慢命令放到后台执行，并用 runtime record + notification 把结果稳稳接回主循环。",
+  },
+  s14: {
+    eyebrow: "让时间成为启动源",
+    summary:
+      "当任务系统和后台执行已经成立后，Cron 章节要讲清的是：时间只负责触发，不负责执行。这样调度器和运行时边界才不会混乱。",
+    sections: [
+      {
+        title: "调度器只管命中规则",
+        body:
+          "Cron 负责判断“什么时候该触发”，例如每小时、每天、工作日；它不直接承担具体任务执行逻辑。",
+      },
+      {
+        title: "命中后仍生成运行任务",
+        body:
+          "时间触发到来时，应该像用户请求一样生成 runtime task，再交给后台执行层处理。",
+      },
+      {
+        title: "时间与执行要解耦",
+        body:
+          "这样你才能分别解释：一个任务为什么被触发，以及它被触发后如何进入执行、重试、通知和完成流程。",
+      },
+    ],
+    flowLabel: "Scheduled Trigger",
+    flow: ["Cron tick", "规则匹配", "创建 runtime task", "交给后台执行"],
+    cautionLabel: "最容易讲错",
+    caution:
+      "不要把 Cron 讲成“后台线程每分钟跑一下”。真正的关键是时间触发面和执行运行时是两套职责。",
+    outcomeLabel: "学完应掌握",
+    outcome:
+      "你应该能把 schedule 记录和 runtime task 记录分开，并说明它们如何衔接。",
+  },
+  s15: {
+    eyebrow: "让队友成为长期存在的角色",
+    summary:
+      "Agent Teams 的重点不是多开几个模型调用，而是给系统引入一组长期存在、能反复接活、能被点名协作的 persistent specialists。",
+    sections: [
+      {
+        title: "身份先于单次任务",
+        body:
+          "Teammate 需要名字、角色、状态和 inbox。它的价值来自持续存在，而不是像一次性 subagent 那样跑完就消失。",
+      },
+      {
+        title: "邮箱是协作边界",
+        body:
+          "团队协作不应该靠共享 messages[]。更清晰的做法是每个队友有自己的收件箱和独立执行线，再通过消息互相联系。",
+      },
+      {
+        title: "负责人仍然掌控编排",
+        body:
+          "Lead 不只是转发消息，它负责生成 roster、分配职责、观察状态，让团队协作保持可理解。",
+      },
+    ],
+    flowLabel: "Persistent Team Loop",
+    flow: ["生成队友身份", "投递消息", "队友独立执行", "回信或继续协作"],
+    cautionLabel: "最容易讲错",
+    caution:
+      "teammate 不是换了名字的 subagent。核心差别是长期身份、独立 inbox 和可重复协作。",
+    outcomeLabel: "学完应掌握",
+    outcome:
+      "你应该能搭出一个最小 team roster，让多个长期存在的执行者通过邮箱协作。",
+  },
+  s16: {
+    eyebrow: "把协作从自由文本升级成协议",
+    summary:
+      "团队协议这一章的关键不是多几种消息类型，而是让重要协作拥有统一 envelope、request_id 和 durable request record，从而做到可追踪、可审批、可收尾。",
+    sections: [
+      {
+        title: "协议消息要有固定外壳",
+        body:
+          "type、from、to、request_id、payload 这些字段必须成套出现。这样同一类协作才能稳定匹配、稳定处理。",
+      },
+      {
+        title: "请求记录必须落盘",
+        body:
+          "真正需要追踪的是 RequestRecord，而不是临时内存字典。审批、关机、交接都应该能在记录里看到当前状态和响应结果。",
+      },
+      {
+        title: "状态流要比文本更重要",
+        body:
+          "pending、approved、rejected、expired 这些状态迁移，才是协议章节真正的教学主线，文本只是承载说明。",
+      },
+    ],
+    flowLabel: "Protocol Request Lifecycle",
+    flow: ["发协议请求", "登记 request record", "收到明确响应", "更新状态继续协作"],
+    cautionLabel: "最容易讲错",
+    caution:
+      "协议不是更正式的聊天文案。它是带 request_id 和状态机的结构化协作通道。",
+    outcomeLabel: "学完应掌握",
+    outcome:
+      "你应该能实现一套最小 request / response protocol，并用 durable request record 跟踪其状态。",
+  },
+  s17: {
+    eyebrow: "让队友会自己接活和恢复",
+    summary:
+      "自治并不意味着神秘智能爆发，而是系统开始允许队友在空闲时主动寻找可认领工作、恢复自己的执行上下文，并按规则继续推进。",
+    sections: [
+      {
+        title: "空闲轮询是自治入口",
+        body:
+          "Teammate 在 idle cycle 中轮询 inbox、共享任务板或待处理请求，这一步决定它能否在没有新指令时继续前进。",
+      },
+      {
+        title: "认领规则必须清楚",
+        body:
+          "什么工作可以自领、如何避免重复认领、何时应该放弃，这些边界决定自治是稳定推进还是混乱抢活。",
+      },
+      {
+        title: "恢复上下文要有依据",
+        body:
+          "队友不是凭空继续工作，而是根据 task state、request state、mailbox 和自身状态恢复到正确分支。",
+      },
+    ],
+    flowLabel: "Autonomy Loop",
+    flow: ["进入空闲轮询", "发现可认领工作", "恢复上下文执行", "回写状态后继续"],
+    cautionLabel: "最容易讲错",
+    caution:
+      "自治不是让 agent 随便乱动。真正关键的是 self-claim 规则和 resume 所依赖的状态边界。",
+    outcomeLabel: "学完应掌握",
+    outcome:
+      "你应该能解释 agent 怎样在没有新用户输入时，自主发现、认领并恢复工作。",
+  },
+  s18: {
+    eyebrow: "把任务绑定到独立执行车道",
+    summary:
+      "Worktree Isolation 章节的核心不是 git 命令细节，而是把任务和执行车道绑定，让不同工作在各自目录里推进，并拥有清晰的 enter / run / closeout 生命周期。",
+    sections: [
+      {
+        title: "任务和车道要分层",
+        body:
+          "Task 管目标，worktree 管隔离执行环境。只有把两者分开，系统才知道“做什么”和“在哪做”分别由谁负责。",
+      },
+      {
+        title: "生命周期要完整",
+        body:
+          "分配 worktree、进入目录、执行任务、closeout 保留或删除，这几步都应该显式存在，而不是做完命令就算结束。",
+      },
+      {
+        title: "事件流帮助观察执行面",
+        body:
+          "create、enter、closeout 这些 worktree event 让主系统能看到执行车道发生了什么，而不是只看到最后结果。",
+      },
+    ],
+    flowLabel: "Isolated Execution Lane",
+    flow: ["分配 worktree", "进入隔离目录", "执行任务", "closeout / 保留事件"],
+    cautionLabel: "最容易讲错",
+    caution:
+      "Worktree 不是任务系统本身。它只是给任务提供一条独立、可回收、可观察的执行车道。",
+    outcomeLabel: "学完应掌握",
+    outcome:
+      "你应该能把 task record 和 worktree lifecycle 连接起来，并讲清 keep / remove 何时发生。",
+  },
+  s19: {
+    eyebrow: "把外部能力挂回同一控制面",
+    summary:
+      "MCP 与 Plugin 章节的重点不是罗列外部生态，而是说明：外部能力进入系统后，如何像本地工具一样被发现、路由、授权、调用和回写。",
+    sections: [
+      {
+        title: "能力先做统一抽象",
+        body:
+          "无论是本地工具、插件能力还是 MCP server 提供的远程能力，都应该被整理到同一种 capability 视图里。",
+      },
+      {
+        title: "路由前仍要过策略层",
+        body:
+          "外部能力不是例外。发现、选择、权限控制、错误恢复这些控制面流程都应该保持一致。",
+      },
+      {
+        title: "结果回到同一消息总线",
+        body:
+          "调用远程能力后，返回结果仍然要标准化成主循环能消费的 tool_result 或结构化事件。",
+      },
+    ],
+    flowLabel: "Capability Bus",
+    flow: ["发现能力", "选择路由", "远程调用", "标准化回写"],
+    cautionLabel: "最容易讲错",
+    caution:
+      "不要把 MCP 讲成一个孤立外挂。教学上真正要强调的是“它如何接回原本的 agent 控制平面”。",
+    outcomeLabel: "学完应掌握",
+    outcome:
+      "你应该能解释本地工具、插件和 MCP server 为何可以共享同一套 capability routing 模型。",
+  },
+};
+
+const EN_COPY: Record<string, OverviewCopy> = {
+  s07: {
+    eyebrow: "Intent must pass a gate before execution",
+    summary:
+      "The permission chapter should teach a control gate, not scattered safety checks. Model intent becomes executable action only after policy classification.",
+    sections: [
+      {
+        title: "Normalize the request first",
+        body:
+          "Convert raw tool calls into a structured intent with action type, target, and risk level before making any permission decision.",
+      },
+      {
+        title: "Keep policy separate",
+        body:
+          "Read-only modes, allowlists, dangerous-command blocks, and ask-before-run rules should live in one permission plane.",
+      },
+      {
+        title: "Always write back the outcome",
+        body:
+          "Allow, deny, and ask all need to flow back into the loop so the model can reason over what happened next.",
+      },
+    ],
+    flowLabel: "Permission Pipeline",
+    flow: ["Model proposes action", "Intent is classified", "Policy decides", "Execute or return denial"],
+    cautionLabel: "Common mistake",
+    caution:
+      "Permission is not just a few if statements. It is a gate in front of execution with its own control-plane semantics.",
+    outcomeLabel: "You should be able to build",
+    outcome:
+      "A shared permission check that gives every tool the same allow / deny / ask contract.",
+  },
+  s08: {
+    eyebrow: "Extend the loop without rewriting it",
+    summary:
+      "Hooks let you add audit trails, tracing, policy side effects, and instrumentation around the loop while keeping the loop itself small and legible.",
+    sections: [
+      {
+        title: "The loop stays minimal",
+        body:
+          "Core state progression stays in the loop. Extra behavior hangs off lifecycle points like pre_tool, post_tool, and on_error.",
+      },
+      {
+        title: "Events need a stable shape",
+        body:
+          "Hooks should receive normalized lifecycle events with tool name, input, result, error, and duration, not ad hoc strings.",
+      },
+      {
+        title: "Side effects stay decoupled",
+        body:
+          "That keeps auditing, metrics, or repair hints from leaking into every tool implementation.",
+      },
+    ],
+    flowLabel: "Lifecycle Events",
+    flow: ["Loop advances", "Event emitted", "Hooks observe", "Side effects write back"],
+    cautionLabel: "Common mistake",
+    caution:
+      "A hook system should observe and extend the loop, not secretly replace the loop's state machine.",
+    outcomeLabel: "You should be able to build",
+    outcome:
+      "A lifecycle event registry with multiple hooks attached to one stable execution loop.",
+  },
+  s09: {
+    eyebrow: "Persist only what survives sessions",
+    summary:
+      "Memory is for cross-session facts that cannot be re-derived cheaply, not for storing every conversation turn forever.",
+    sections: [
+      {
+        title: "Use typed memory buckets",
+        body:
+          "Preferences, project constraints, and durable environment facts should be separated from temporary observations.",
+      },
+      {
+        title: "Read and write at clear moments",
+        body:
+          "Load relevant memory before prompt assembly. Extract and persist new memory after the work is done.",
+      },
+      {
+        title: "Memory is not context",
+        body:
+          "Short-term messages carry the live process. Long-term memory keeps only compressed, durable facts.",
+      },
+    ],
+    flowLabel: "Memory Lifecycle",
+    flow: ["Load memory", "Assemble input", "Finish work", "Extract and persist"],
+    cautionLabel: "Common mistake",
+    caution:
+      "Memory is not an infinite history log. The hard part is deciding what deserves to survive.",
+    outcomeLabel: "You should be able to build",
+    outcome:
+      "A clear separation between messages[], compacted summaries, and cross-session memory.",
+  },
+  s10: {
+    eyebrow: "Prompting becomes an assembly pipeline",
+    summary:
+      "The system prompt should be taught as a pipeline that assembles stable policy, runtime state, tools, and memory in a predictable order.",
+    sections: [
+      {
+        title: "Separate stable policy",
+        body:
+          "Role, safety rules, and non-negotiable constraints should not be tangled with temporary runtime details.",
+      },
+      {
+        title: "Assemble runtime fragments explicitly",
+        body:
+          "Workspace state, available tools, memory, task state, and recovery hints need a visible assembly order.",
+      },
+      {
+        title: "Input is a control plane",
+        body:
+          "The ordering and boundaries of prompt fragments control what the model sees and how it reasons.",
+      },
+    ],
+    flowLabel: "Prompt Assembly",
+    flow: ["Stable policy", "Runtime state", "Tool and memory injection", "Final model input"],
+    cautionLabel: "Common mistake",
+    caution:
+      "Do not teach this as mystical prompt engineering. Teach data sources, assembly order, and information boundaries.",
+    outcomeLabel: "You should be able to build",
+    outcome:
+      "A prompt builder pipeline instead of a single giant prompt string.",
+  },
+  s11: {
+    eyebrow: "Recovery keeps the system moving",
+    summary:
+      "A high-completion agent is not error-free. It is explicit about why it is retrying, degrading, or stopping after each failure.",
+    sections: [
+      {
+        title: "Classify failures first",
+        body:
+          "Permission denials, tool crashes, missing dependencies, timeouts, and write conflicts should not all use the same retry branch.",
+      },
+      {
+        title: "Continuation reasons stay explicit",
+        body:
+          "Before continuing, record whether this branch is a retry, fallback, or user-confirmation path.",
+      },
+      {
+        title: "Recovery needs hard limits",
+        body:
+          "Caps on retries, fallback paths, and stop conditions prevent silent infinite loops.",
+      },
+    ],
+    flowLabel: "Recovery Branches",
+    flow: ["Failure detected", "Reason classified", "Recovery chosen", "Continue with context"],
+    cautionLabel: "Common mistake",
+    caution:
+      "Recovery is not just a try/except wrapper. The recovery reason itself must become visible state.",
+    outcomeLabel: "You should be able to build",
+    outcome:
+      "Explicit continuation reasons that make retry / fallback / stop into understandable state transitions.",
+  },
+  s12: {
+    eyebrow: "Turn session steps into a durable work graph",
+    summary:
+      "The task system is not just a saved todo list. It turns work into durable records with dependency edges so progress can unlock later work across turns.",
+    sections: [
+      {
+        title: "A task is a record before it is execution",
+        body:
+          "TaskRecord stores goal, state, and dependency edges. It answers what work exists and what is blocked, not what thread is currently running.",
+      },
+      {
+        title: "Dependency edges must stay explicit",
+        body:
+          "Fields like blockedBy, blocks, and status make it clear why a task cannot start yet and which downstream work becomes eligible next.",
+      },
+      {
+        title: "The board owns unlock logic",
+        body:
+          "The key runtime lesson is how completing one node updates the board, checks dependency satisfaction, and unlocks the next nodes.",
+      },
+    ],
+    flowLabel: "Durable Task Graph",
+    flow: ["Create task record", "Write dependency edges", "Complete current node", "Unlock downstream work"],
+    cautionLabel: "Common mistake",
+    caution:
+      "A task is not a background thread and not a plan paragraph. It is a durable work record inside the system.",
+    outcomeLabel: "You should be able to build",
+    outcome:
+      "A minimal task board with dependency and unlock logic, not just a session-scoped todo list.",
+  },
+  s13: {
+    eyebrow: "Separate goal records from running slots",
+    summary:
+      "The real lesson in background tasks is that the durable task goal stays on the board while each live execution gets its own runtime record and returns through notifications.",
+    sections: [
+      {
+        title: "Running work needs its own record",
+        body:
+          "A RuntimeTaskRecord should carry id, status, started_at, result_preview, and output_file. It describes one execution attempt, not the task goal itself.",
+      },
+      {
+        title: "Preview and full output should split",
+        body:
+          "Write the complete output to disk, then send only a preview back through notifications. The loop learns what happened without flooding prompt space.",
+      },
+      {
+        title: "Notifications rejoin the main loop",
+        body:
+          "The background thread should not mutate model state directly. It writes runtime state and notifications, then the next turn injects them back into context.",
+      },
+    ],
+    flowLabel: "Runtime Task Return Path",
+    flow: ["Create runtime record", "Run in background", "Write preview and output", "Inject notification next turn"],
+    cautionLabel: "Common mistake",
+    caution:
+      "A background task is not another thinking agent. What runs in parallel is waiting and execution, not the main loop itself.",
+    outcomeLabel: "You should be able to build",
+    outcome:
+      "A background execution path that returns through runtime records and notifications instead of blocking the foreground loop.",
+  },
+  s14: {
+    eyebrow: "Time becomes another trigger source",
+    summary:
+      "Once tasks can run in the background, a scheduler should only decide when to trigger work. Execution still belongs to the runtime layer.",
+    sections: [
+      {
+        title: "The scheduler only matches rules",
+        body:
+          "Cron owns time rules like hourly, daily, or weekdays. It should not directly own the runtime execution model.",
+      },
+      {
+        title: "A trigger creates runtime work",
+        body:
+          "When a rule matches, generate the same kind of runtime task that other sources would create.",
+      },
+      {
+        title: "Time and execution stay decoupled",
+        body:
+          "That lets you explain both why work started and how it moved through execution, retries, and completion.",
+      },
+    ],
+    flowLabel: "Scheduled Trigger",
+    flow: ["Cron tick", "Rule match", "Create runtime task", "Hand off to background runtime"],
+    cautionLabel: "Common mistake",
+    caution:
+      "Do not reduce cron to a timer thread. The teaching value is the separation between trigger time and execution runtime.",
+    outcomeLabel: "You should be able to build",
+    outcome:
+      "Separate schedule records from runtime task records and show how one hands off to the other.",
+  },
+  s15: {
+    eyebrow: "Make teammates long-lived roles",
+    summary:
+      "Agent teams matter when specialists stop being disposable subtasks and become persistent identities with roles, inboxes, and repeatable responsibilities.",
+    sections: [
+      {
+        title: "Identity comes before one task",
+        body:
+          "A teammate needs a name, role, status, and inbox. Its value comes from remaining available across multiple rounds of work.",
+      },
+      {
+        title: "Mailbox boundaries keep coordination clear",
+        body:
+          "Teams should not share one giant messages[] buffer. Each worker has an inbox and its own execution line, then coordination travels through messages.",
+      },
+      {
+        title: "The lead still owns orchestration",
+        body:
+          "The lead builds the roster, assigns work, and watches state. Team structure is what keeps persistence understandable instead of chaotic.",
+      },
+    ],
+    flowLabel: "Persistent Team Loop",
+    flow: ["Create teammate identity", "Deliver message", "Worker runs independently", "Reply or continue"],
+    cautionLabel: "Common mistake",
+    caution:
+      "A teammate is not just a renamed subagent. The important difference is long-lived identity and repeatable collaboration.",
+    outcomeLabel: "You should be able to build",
+    outcome:
+      "A minimal team roster where persistent workers collaborate through mailboxes.",
+  },
+  s16: {
+    eyebrow: "Upgrade coordination from chat to protocol",
+    summary:
+      "Team protocols matter because important coordination needs a fixed envelope, a request_id, and a durable request record, not just free-form text in a mailbox.",
+    sections: [
+      {
+        title: "Protocol messages need a stable envelope",
+        body:
+          "type, from, to, request_id, and payload should travel together so one workflow can always be parsed and handled the same way.",
+      },
+      {
+        title: "Requests should be durable records",
+        body:
+          "The real object to teach is the RequestRecord, not an in-memory tracker. Approval, shutdown, or handoff should survive long enough to inspect and resume.",
+      },
+      {
+        title: "State transitions matter more than wording",
+        body:
+          "pending, approved, rejected, and expired are the actual teaching spine. The human-readable text is only the explanation layer around that state machine.",
+      },
+    ],
+    flowLabel: "Protocol Request Lifecycle",
+    flow: ["Send protocol request", "Persist request record", "Receive explicit response", "Update state and continue"],
+    cautionLabel: "Common mistake",
+    caution:
+      "A protocol is not just more formal chat. It is a structured coordination path with request correlation and state transitions.",
+    outcomeLabel: "You should be able to build",
+    outcome:
+      "A small request / response protocol with durable request tracking.",
+  },
+  s17: {
+    eyebrow: "Let workers self-claim and self-resume",
+    summary:
+      "Autonomy is not magic intelligence. It begins when a worker can poll for eligible work, restore the right context, and continue under clear claim rules.",
+    sections: [
+      {
+        title: "Idle polling is the autonomy entry point",
+        body:
+          "During idle cycles, a worker checks inboxes, boards, or pending requests to discover whether something can now be claimed.",
+      },
+      {
+        title: "Claim rules must stay explicit",
+        body:
+          "The system needs clear rules for what a worker may claim, how collisions are avoided, and when it should back off.",
+      },
+      {
+        title: "Resume depends on visible state",
+        body:
+          "A worker does not continue from nowhere. It resumes from task state, protocol state, mailbox contents, and its own role state.",
+      },
+    ],
+    flowLabel: "Autonomy Loop",
+    flow: ["Enter idle poll", "Find claimable work", "Resume with context", "Write back state"],
+    cautionLabel: "Common mistake",
+    caution:
+      "Autonomy does not mean uncontrolled motion. The important part is the claim policy and the state used to resume safely.",
+    outcomeLabel: "You should be able to build",
+    outcome:
+      "A worker loop that can discover, claim, and resume work without waiting for a new user turn.",
+  },
+  s18: {
+    eyebrow: "Bind tasks to isolated execution lanes",
+    summary:
+      "Worktree isolation is not about git trivia. It is about giving each task a separate execution lane with explicit enter, run, and closeout lifecycle steps.",
+    sections: [
+      {
+        title: "Tasks and lanes are different layers",
+        body:
+          "Tasks describe the goal. Worktrees describe where isolated execution happens. Keeping those layers separate prevents the runtime model from blurring.",
+      },
+      {
+        title: "Lifecycle steps should stay explicit",
+        body:
+          "Allocate the worktree, enter the directory, run the work, then decide whether to keep or remove it during closeout.",
+      },
+      {
+        title: "Lifecycle events make lanes observable",
+        body:
+          "Create, enter, and closeout events let the rest of the system observe execution-lane state instead of only seeing the final result.",
+      },
+    ],
+    flowLabel: "Isolated Execution Lane",
+    flow: ["Allocate worktree", "Enter isolated dir", "Run task", "Close out or keep"],
+    cautionLabel: "Common mistake",
+    caution:
+      "A worktree is not the task system itself. It is an isolated, observable execution lane for a task.",
+    outcomeLabel: "You should be able to build",
+    outcome:
+      "A task-to-worktree binding with explicit keep / remove closeout semantics.",
+  },
+  s19: {
+    eyebrow: "External capability joins the same control plane",
+    summary:
+      "MCP and plugins matter because they extend the agent's capability bus without inventing a second execution universe.",
+    sections: [
+      {
+        title: "Unify capability abstraction first",
+        body:
+          "Native tools, plugins, and MCP server actions should all enter the system through one capability view.",
+      },
+      {
+        title: "External calls still pass policy",
+        body:
+          "Discovery, routing, permission checks, and recovery logic should apply to external capabilities too.",
+      },
+      {
+        title: "Results return on the same bus",
+        body:
+          "Remote outputs should be normalized into the same tool_result or structured event format the loop already understands.",
+      },
+    ],
+    flowLabel: "Capability Bus",
+    flow: ["Discover capability", "Choose route", "Call external system", "Normalize and append"],
+    cautionLabel: "Common mistake",
+    caution:
+      "Do not teach MCP as an isolated addon. The key is how it plugs back into the existing agent control plane.",
+    outcomeLabel: "You should be able to build",
+    outcome:
+      "One capability-routing model that can explain native tools, plugins, and MCP servers together.",
+  },
+};
+
+const JA_FALLBACK_TEXT = {
+  sectionA: "この章で本当に増えるもの",
+  sectionB: "最初に守る境界",
+  sectionC: "実装で到達したい形",
+  flowLabel: "読む順序",
+  cautionLabel: "混同しやすい点",
+  outcomeLabel: "学習後にできること",
+  flow: [
+    "まず増分を見る",
+    "次に状態境界を分ける",
+    "その後で回写経路を追う",
+    "最後に自分で最小実装を作る",
+  ],
+} as const;
+
+function buildJapaneseFallbackOverview(version: string): OverviewCopy | null {
+  const versionId = version as VersionId;
+  const content = getVersionContent(version, "ja");
+  const guide = getChapterGuide(versionId, "ja") ?? getChapterGuide(versionId, "en");
+
+  if (!guide) return null;
+
+  return {
+    eyebrow: content.subtitle,
+    summary: `本章の中核増分は「${content.coreAddition}」です。${content.keyInsight}`,
+    sections: [
+      {
+        title: JA_FALLBACK_TEXT.sectionA,
+        body: `ここで本当に新しく成立するのは「${content.coreAddition}」です。読むときは実装の枝葉よりも、この構造が主線のどこへ差し込み、どの状態を増やし、どう主ループへ戻るかを先に押さえます。`,
+      },
+      {
+        title: JA_FALLBACK_TEXT.sectionB,
+        body: `${guide.focus} ${guide.confusion}`,
+      },
+      {
+        title: JA_FALLBACK_TEXT.sectionC,
+        body: `${guide.goal} 一度に全部を再現しようとするより、この章で増えた最小構造だけを独立に成立させてから次へ進む方が理解も実装も安定します。`,
+      },
+    ],
+    flowLabel: JA_FALLBACK_TEXT.flowLabel,
+    flow: [...JA_FALLBACK_TEXT.flow],
+    cautionLabel: JA_FALLBACK_TEXT.cautionLabel,
+    caution: guide.confusion,
+    outcomeLabel: JA_FALLBACK_TEXT.outcomeLabel,
+    outcome: guide.goal,
+  };
+}
+
+export function GenericSessionOverview({
+  version,
+  title,
+}: {
+  version: string;
+  title?: string;
+}) {
+  const locale = useLocale();
+  const tLayer = useTranslations("layer_labels");
+  const tSession = useTranslations("sessions");
+  const meta = VERSION_META[version];
+  const content = getVersionContent(version, locale);
+
+  if (!meta) return null;
+
+  const copy =
+    locale === "zh"
+      ? ZH_COPY[version] ?? EN_COPY[version]
+      : locale === "ja"
+        ? buildJapaneseFallbackOverview(version) ?? EN_COPY[version]
+        : EN_COPY[version];
+  const coreAdditionLabel =
+    locale === "zh"
+      ? "核心增量"
+      : locale === "ja"
+        ? "中核の追加"
+        : "Core Addition";
+
+  if (!copy) return null;
+
+  return (
+    <section className="min-h-[500px] space-y-4">
+      <div
+        className={`overflow-hidden rounded-[28px] border border-[var(--color-border)] bg-[var(--color-bg)] shadow-sm ring-1 ${RING_CLASSES[meta.layer]}`}
+      >
+        <div
+          className={`relative overflow-hidden bg-gradient-to-br ${SURFACE_CLASSES[meta.layer]} px-5 py-6 sm:px-6`}
+        >
+          <div className="absolute right-[-40px] top-[-40px] h-36 w-36 rounded-full bg-white/40 blur-3xl dark:bg-white/5" />
+          <div className="relative">
+            <div className="flex flex-wrap items-center gap-2">
+              <LayerBadge layer={meta.layer}>{tLayer(meta.layer)}</LayerBadge>
+              <span className="rounded-full border border-white/50 bg-white/70 px-2.5 py-1 text-[11px] font-medium text-zinc-700 backdrop-blur dark:border-white/10 dark:bg-zinc-950/40 dark:text-zinc-300">
+                {copy.eyebrow}
+              </span>
+            </div>
+            <h2 className="mt-4 text-2xl font-semibold tracking-tight text-zinc-950 dark:text-zinc-50">
+              {title || tSession(version)}
+            </h2>
+            <p className="mt-2 max-w-3xl text-sm leading-7 text-zinc-700 dark:text-zinc-300">
+              {copy.summary}
+            </p>
+            <div className="mt-4 inline-flex items-center gap-2 rounded-2xl border border-zinc-200/70 bg-white/85 px-3 py-2 text-xs text-zinc-600 backdrop-blur dark:border-zinc-700/70 dark:bg-zinc-950/50 dark:text-zinc-300">
+              <span className="font-medium">{coreAdditionLabel}</span>
+              <span className="font-mono text-[11px] text-zinc-500 dark:text-zinc-400">
+                {content.coreAddition}
+              </span>
+            </div>
+          </div>
+        </div>
+
+        {hasLateStageTeachingMap(version) && (
+          <div className="px-5 pt-5 sm:px-6">
+            <LateStageTeachingMap version={version} />
+          </div>
+        )}
+
+        <div className="grid gap-3 px-5 py-5 sm:grid-cols-3 sm:px-6">
+          {copy.sections.map((section, index) => (
+            <motion.div
+              key={section.title}
+              initial={{ opacity: 0, y: 14 }}
+              animate={{ opacity: 1, y: 0 }}
+              transition={{ delay: index * 0.08, duration: 0.32 }}
+              className="rounded-2xl border border-zinc-200/80 bg-white/90 p-4 shadow-sm dark:border-zinc-800 dark:bg-zinc-950/60"
+            >
+              <div className="text-[11px] font-semibold uppercase tracking-[0.18em] text-zinc-400 dark:text-zinc-500">
+                0{index + 1}
+              </div>
+              <h3 className="mt-2 text-sm font-semibold text-zinc-900 dark:text-zinc-100">
+                {section.title}
+              </h3>
+              <p className="mt-2 text-sm leading-6 text-zinc-600 dark:text-zinc-300">
+                {section.body}
+              </p>
+            </motion.div>
+          ))}
+        </div>
+
+        <div className="grid gap-4 border-t border-[var(--color-border)] px-5 py-5 lg:grid-cols-[minmax(0,1.45fr)_minmax(0,1fr)] sm:px-6">
+          <div className="rounded-2xl border border-zinc-200/80 bg-zinc-50/80 p-4 dark:border-zinc-800 dark:bg-zinc-950/50">
+            <div className="text-xs font-medium text-zinc-500 dark:text-zinc-400">
+              {copy.flowLabel}
+            </div>
+            <div className="mt-4 flex flex-wrap items-center gap-2">
+              {copy.flow.map((step, index) => (
+                <div key={step} className="contents">
+                  <motion.div
+                    initial={{ opacity: 0, scale: 0.94 }}
+                    animate={{ opacity: 1, scale: 1 }}
+                    transition={{ delay: index * 0.07, duration: 0.28 }}
+                    className="inline-flex items-center rounded-full border border-zinc-200 bg-white px-3 py-2 text-xs font-medium text-zinc-700 shadow-sm dark:border-zinc-700 dark:bg-zinc-900 dark:text-zinc-200"
+                  >
+                    <span className="mr-2 font-mono text-[10px] text-zinc-400 dark:text-zinc-500">
+                      {index + 1}
+                    </span>
+                    {step}
+                  </motion.div>
+                  {index < copy.flow.length - 1 && (
+                    <span className="text-zinc-300 dark:text-zinc-600">-&gt;</span>
+                  )}
+                </div>
+              ))}
+            </div>
+          </div>
+
+          <div className="grid gap-3">
+            <div className="rounded-2xl border border-zinc-200/80 bg-white/90 p-4 dark:border-zinc-800 dark:bg-zinc-950/60">
+              <div className="text-xs font-medium text-zinc-500 dark:text-zinc-400">
+                {copy.cautionLabel}
+              </div>
+              <p className="mt-2 text-sm leading-6 text-zinc-700 dark:text-zinc-300">
+                {copy.caution}
+              </p>
+            </div>
+            <div className="rounded-2xl border border-zinc-200/80 bg-white/90 p-4 dark:border-zinc-800 dark:bg-zinc-950/60">
+              <div className="text-xs font-medium text-zinc-500 dark:text-zinc-400">
+                {copy.outcomeLabel}
+              </div>
+              <p className="mt-2 text-sm leading-6 text-zinc-700 dark:text-zinc-300">
+                {copy.outcome}
+              </p>
+            </div>
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+}
diff --git a/web/src/components/visualizations/index.tsx b/web/src/components/visualizations/index.tsx
index 5fc622223..72a231a2a 100644
--- a/web/src/components/visualizations/index.tsx
+++ b/web/src/components/visualizations/index.tsx
@@ -2,6 +2,8 @@
 
 import { lazy, Suspense } from "react";
 import { useTranslations } from "@/lib/i18n";
+import { isGenericOverviewVersion } from "@/lib/session-assets";
+import { GenericSessionOverview } from "./generic-session-overview";
 
 const visualizations: Record<
   string,
@@ -13,18 +15,21 @@ const visualizations: Record<
   s04: lazy(() => import("./s04-subagent")),
   s05: lazy(() => import("./s05-skill-loading")),
   s06: lazy(() => import("./s06-context-compact")),
-  s07: lazy(() => import("./s07-task-system")),
-  s08: lazy(() => import("./s08-background-tasks")),
-  s09: lazy(() => import("./s09-agent-teams")),
-  s10: lazy(() => import("./s10-team-protocols")),
-  s11: lazy(() => import("./s11-autonomous-agents")),
-  s12: lazy(() => import("./s12-worktree-task-isolation")),
 };
 
 export function SessionVisualization({ version }: { version: string }) {
   const t = useTranslations("viz");
+  const title = t(version);
+
+  if (isGenericOverviewVersion(version)) {
+    return <GenericSessionOverview version={version} title={title} />;
+  }
+
   const Component = visualizations[version];
-  if (!Component) return null;
+  if (!Component) {
+    return <GenericSessionOverview version={version} title={title} />;
+  }
+
   return (
     <Suspense
       fallback={
@@ -32,7 +37,7 @@ export function SessionVisualization({ version }: { version: string }) {
       }
     >
       <div className="min-h-[500px]">
-        <Component title={t(version)} />
+        <Component title={title} />
       </div>
     </Suspense>
   );
diff --git a/web/src/components/visualizations/late-stage-teaching-map.tsx b/web/src/components/visualizations/late-stage-teaching-map.tsx
new file mode 100644
index 000000000..18a2654ef
--- /dev/null
+++ b/web/src/components/visualizations/late-stage-teaching-map.tsx
@@ -0,0 +1,1105 @@
+"use client";
+
+import { motion } from "framer-motion";
+import { VERSION_META, type VersionId } from "@/lib/constants";
+import { useLocale } from "@/lib/i18n";
+import { useSteppedVisualization } from "@/hooks/useSteppedVisualization";
+import { StepControls } from "@/components/visualizations/shared/step-controls";
+
+type LateStageVersion =
+  | "s07"
+  | "s08"
+  | "s09"
+  | "s10"
+  | "s11"
+  | "s12"
+  | "s13"
+  | "s14"
+  | "s15"
+  | "s16"
+  | "s17"
+  | "s18"
+  | "s19";
+
+type LocaleText = {
+  zh: string;
+  en: string;
+  ja?: string;
+};
+
+interface ScenarioLane {
+  id: string;
+  label: LocaleText;
+  note: LocaleText;
+}
+
+interface ScenarioNode {
+  id: string;
+  lane: string;
+  label: LocaleText;
+  detail: LocaleText;
+}
+
+interface ScenarioRecord {
+  id: string;
+  label: LocaleText;
+  note: LocaleText;
+}
+
+interface ScenarioStep {
+  title: LocaleText;
+  description: LocaleText;
+  activeNodes: string[];
+  activeRecords: string[];
+  boundary: LocaleText;
+  writeBack: LocaleText;
+}
+
+interface ChapterScenario {
+  lanes: ScenarioLane[];
+  nodes: ScenarioNode[];
+  records: ScenarioRecord[];
+  steps: ScenarioStep[];
+}
+
+const UI_TEXT = {
+  label: {
+    zh: "机制演示",
+    en: "Mechanism Walkthrough",
+    ja: "メカニズムの実演",
+  },
+  title: {
+    zh: "把这一章真正新增的车道、记录和回流顺序分开看",
+    en: "Separate the new lanes, records, and write-back order introduced by this chapter",
+    ja: "この章で増えたレーン、レコード、回流順を切り分けて見る",
+  },
+  body: {
+    zh: "中后段最容易拧巴的点，不是名词多，而是多个层同时动起来。先看这张演示图，再进正文，能更快守住“谁在决策、谁在执行、谁在记录、最后怎么回到主循环”。",
+    en: "The middle and late chapters become confusing not because they use more terms, but because several layers move at once. Read this walkthrough first to keep straight who decides, who executes, who records state, and how control returns to the main loop.",
+    ja: "中盤以降が難しくなるのは用語が増えるからではなく、複数の層が同時に動き始めるからです。先にこの図を見ると、誰が判断し、誰が実行し、誰が記録し、どう主ループへ戻るかを保ちやすくなります。",
+  },
+  systemLanes: {
+    zh: "系统车道",
+    en: "System Lanes",
+    ja: "システムレーン",
+  },
+  activePath: {
+    zh: "当前主线",
+    en: "Current Mainline",
+    ja: "現在の主線",
+  },
+  activeRecords: {
+    zh: "这一步真正活跃的记录",
+    en: "Records Active in This Step",
+    ja: "この段階で本当に動くレコード",
+  },
+  boundary: {
+    zh: "这一步要守住的边界",
+    en: "Boundary to Protect Here",
+    ja: "この段階で守るべき境界",
+  },
+  writeBack: {
+    zh: "最后怎么回到主线",
+    en: "How Control Returns to the Mainline",
+    ja: "最後にどう主線へ戻るか",
+  },
+  inactiveRecord: {
+    zh: "当前未激活",
+    en: "Not active in this step",
+    ja: "この段階では未使用",
+  },
+} as const;
+
+const ACCENT_CLASSES: Record<
+  "core" | "hardening" | "runtime" | "platform",
+  {
+    tint: string;
+    ring: string;
+    soft: string;
+    pill: string;
+    border: string;
+  }
+> = {
+  core: {
+    tint: "from-blue-500/18 via-blue-500/8 to-transparent",
+    ring: "ring-blue-500/20",
+    soft: "bg-blue-500/10 text-blue-700 dark:text-blue-200",
+    pill: "border-blue-300/80 bg-blue-50/90 text-blue-700 dark:border-blue-900/70 dark:bg-blue-950/30 dark:text-blue-200",
+    border: "border-blue-200/80 dark:border-blue-900/60",
+  },
+  hardening: {
+    tint: "from-emerald-500/18 via-emerald-500/8 to-transparent",
+    ring: "ring-emerald-500/20",
+    soft: "bg-emerald-500/10 text-emerald-700 dark:text-emerald-200",
+    pill: "border-emerald-300/80 bg-emerald-50/90 text-emerald-700 dark:border-emerald-900/70 dark:bg-emerald-950/30 dark:text-emerald-200",
+    border: "border-emerald-200/80 dark:border-emerald-900/60",
+  },
+  runtime: {
+    tint: "from-amber-500/18 via-amber-500/8 to-transparent",
+    ring: "ring-amber-500/20",
+    soft: "bg-amber-500/10 text-amber-700 dark:text-amber-200",
+    pill: "border-amber-300/80 bg-amber-50/90 text-amber-700 dark:border-amber-900/70 dark:bg-amber-950/30 dark:text-amber-200",
+    border: "border-amber-200/80 dark:border-amber-900/60",
+  },
+  platform: {
+    tint: "from-rose-500/18 via-rose-500/8 to-transparent",
+    ring: "ring-rose-500/20",
+    soft: "bg-rose-500/10 text-rose-700 dark:text-rose-200",
+    pill: "border-rose-300/80 bg-rose-50/90 text-rose-700 dark:border-rose-900/70 dark:bg-rose-950/30 dark:text-rose-200",
+    border: "border-rose-200/80 dark:border-rose-900/60",
+  },
+};
+
+function pick(locale: string, text: LocaleText): string {
+  if (locale === "zh") return text.zh;
+  if (locale === "ja") return text.ja ?? text.en;
+  return text.en;
+}
+
+function l(zh: string, en: string, ja?: string): LocaleText {
+  return { zh, en, ja };
+}
+
+const SCENARIOS: Record<LateStageVersion, ChapterScenario> = {
+  s07: {
+    lanes: [
+      { id: "input", label: l("模型入口", "Model Entry", "モデル入口"), note: l("模型先提出动作意图。", "The model proposes an action first.", "モデルが先に行動意図を出します。") },
+      { id: "control", label: l("权限控制面", "Permission Plane", "権限制御面"), note: l("这里决定 allow / ask / deny。", "This is where allow / ask / deny is decided.", "ここで allow / ask / deny を決めます。") },
+      { id: "runtime", label: l("执行面", "Execution Plane", "実行面"), note: l("只有放行后才真正触发工具。", "Tools run only after approval.", "許可されたあとで初めて tool が動きます。") },
+      { id: "history", label: l("消息回流", "Message Write-back", "メッセージ回流"), note: l("所有结果都要回写给主循环。", "Every result must write back to the main loop.", "すべての結果は主ループへ回流します。") },
+    ],
+    nodes: [
+      { id: "intent", lane: "input", label: l("工具意图", "Tool Intent", "tool 意図"), detail: l("模型想执行某个动作。", "The model wants to perform an action.", "モデルが何かを実行したがっています。") },
+      { id: "normalize", lane: "control", label: l("意图规范化", "Normalize Intent", "意図正規化"), detail: l("先抽出动作、目标和风险。", "Extract action, target, and risk first.", "行動・対象・危険度を先に抽出します。") },
+      { id: "policy", lane: "control", label: l("规则与模式", "Rules + Mode", "ルールとモード"), detail: l("deny / mode / allow 顺序判断。", "Evaluate deny / mode / allow in order.", "deny / mode / allow を順番に判定します。") },
+      { id: "decision", lane: "control", label: l("权限决策", "Permission Decision", "権限判断"), detail: l("输出 allow / ask / deny。", "Return allow / ask / deny.", "allow / ask / deny を返します。") },
+      { id: "tool", lane: "runtime", label: l("实际执行", "Tool Execution", "実行"), detail: l("只有 allow 时才落到工具。", "Execution happens only after allow.", "allow のときだけ tool 実行へ進みます。") },
+      { id: "writeback", lane: "history", label: l("结构化回写", "Structured Write-back", "構造化回写"), detail: l("拒绝、询问、执行结果都回到主循环。", "Deny, ask, or execute results all return to the loop.", "拒否・確認・実行結果はすべて主ループへ戻ります。") },
+    ],
+    records: [
+      { id: "normalized-intent", label: l("NormalizedIntent", "NormalizedIntent", "NormalizedIntent"), note: l("供权限层统一判断的对象。", "A normalized object the policy layer can inspect.", "policy 層が統一的に見られる正規化オブジェクトです。") },
+      { id: "permission-rule", label: l("PermissionRule", "PermissionRule", "PermissionRule"), note: l("定义匹配条件和行为。", "Defines match conditions and behavior.", "一致条件と挙動を定義します。") },
+      { id: "permission-decision", label: l("PermissionDecision", "PermissionDecision", "PermissionDecision"), note: l("把 allow / ask / deny 带着原因写回。", "Writes allow / ask / deny back with a reason.", "理由付きで allow / ask / deny を回写します。") },
+    ],
+    steps: [
+      {
+        title: l("先把动作变成可判断对象", "Turn the action into a policy object", "行動を policy 判定可能な形へ変える"),
+        description: l("权限章第一步不是拦截命令字符串，而是把模型意图翻译成规则层看得懂的统一对象。", "The first step is not blocking raw command strings. It is translating model intent into a uniform object the policy layer can understand.", "最初にやるのは生の文字列ブロックではなく、モデル意図を policy 層が分かる統一オブジェクトへ翻訳することです。"),
+        activeNodes: ["intent", "normalize"],
+        activeRecords: ["normalized-intent"],
+        boundary: l("不要直接拿原始 tool call 执行。先规范化，后决策。", "Do not execute raw tool calls directly. Normalize first, decide second.", "生の tool call をそのまま実行しない。先に正規化し、その後で判断します。"),
+        writeBack: l("规范化结果继续送进权限链，不直接落到工具。", "The normalized intent continues into the permission chain, not straight into execution.", "正規化結果はそのまま実行へ行かず、permission chain へ進みます。"),
+      },
+      {
+        title: l("规则和模式一起决定权限", "Rules and mode decide together", "ルールとモードが一緒に権限を決める"),
+        description: l("deny 规则、模式限制和 allow 规则构成完整权限管道，重点是顺序，不是零散 if。", "Deny rules, mode restrictions, and allow rules form one pipeline. The important part is their order, not scattered if statements.", "deny rule・mode 制限・allow rule が 1 本の pipeline を作ります。大事なのは零散な if ではなく順序です。"),
+        activeNodes: ["normalize", "policy", "decision"],
+        activeRecords: ["permission-rule", "permission-decision"],
+        boundary: l("权限系统是独立控制面，不要把判断逻辑拆散到每个工具里。", "The permission system is its own control plane. Do not scatter this logic into every tool.", "permission system は独立した control plane です。各 tool に散らさないでください。"),
+        writeBack: l("决策结果先形成 PermissionDecision，再决定是否往执行面流动。", "PermissionDecision is produced before anything flows to execution.", "実行面へ進む前に、まず PermissionDecision が作られます。"),
+      },
+      {
+        title: l("只有 allow 才触发工具", "Only allow reaches execution", "allow のときだけ実行へ進む"),
+        description: l("执行面只处理被允许的动作。ask 和 deny 同样是结果，但它们不会落到工具处理器。", "The execution plane only handles allowed actions. Ask and deny are also outcomes, but they do not enter the tool handler.", "実行面は許可された行動だけを処理します。ask と deny も結果ですが、tool handler へは入りません。"),
+        activeNodes: ["decision", "tool"],
+        activeRecords: ["permission-decision"],
+        boundary: l("权限层和执行层是两层，不要把询问用户和真正运行工具混成一条路。", "Permission and execution are two layers. Do not mix user confirmation with real tool execution.", "permission と execution は別層です。ユーザー確認と実行を同じ道にしないでください。"),
+        writeBack: l("allow 通过后才进入工具处理器，工具输出仍要再回写。", "Only after allow does execution begin, and tool output still writes back afterward.", "allow のあとで初めて tool が動き、その結果もさらに回写されます。"),
+      },
+      {
+        title: l("所有权限结果都回到主循环", "Every permission outcome returns to the loop", "あらゆる権限結果が主ループへ戻る"),
+        description: l("教学上最重要的是：拒绝、询问、执行成功，都必须变成模型下一步能看见的事实。", "The critical teaching point is that deny, ask, and successful execution all become facts the model can see on the next turn.", "拒否・確認・成功のすべてが、次のターンでモデルが見られる事実になることが重要です。"),
+        activeNodes: ["decision", "tool", "writeback"],
+        activeRecords: ["permission-decision"],
+        boundary: l("不要让权限判断静默消失，否则模型不会知道为什么没执行。", "Do not let permission outcomes disappear silently, or the model will not know why something did not run.", "permission の結果を黙って消さないこと。そうしないとモデルはなぜ実行されなかったか分かりません。"),
+        writeBack: l("最终回流的是结构化 permission result 或 tool result，它们一起维持下一轮推理。", "The loop receives either a structured permission result or a tool result, and both support the next reasoning step.", "最終的に戻るのは構造化 permission result か tool result であり、どちらも次の推論を支えます。"),
+      },
+    ],
+  },
+  s08: {
+    lanes: [
+      { id: "loop", label: l("主循环", "Main Loop", "主ループ"), note: l("核心状态推进仍留在这里。", "Core state progression stays here.", "中核の状態遷移はここに残ります。") },
+      { id: "events", label: l("生命周期事件", "Lifecycle Events", "ライフサイクルイベント"), note: l("固定时机发出结构化事件。", "Structured events are emitted at fixed moments.", "固定タイミングで構造化イベントが出ます。") },
+      { id: "hooks", label: l("Hook 侧车", "Hook Sidecars", "Hook サイドカー"), note: l("审计、追踪、策略副作用挂在这里。", "Audit, tracing, and policy side effects live here.", "監査・追跡・副作用はここに乗ります。") },
+      { id: "history", label: l("结果回流", "Result Write-back", "結果回流"), note: l("副作用和主线结果都可回写。", "Both side effects and mainline results can write back.", "副作用も主線結果も回写できます。") },
+    ],
+    nodes: [
+      { id: "advance", lane: "loop", label: l("推进主线", "Advance Loop", "主線を進める"), detail: l("循环继续负责主状态。", "The loop still owns the main state.", "主状態は引き続きループが持ちます。") },
+      { id: "emit", lane: "events", label: l("发事件", "Emit Event", "イベント送出"), detail: l("在 pre_tool / post_tool / on_error 发事件。", "Emit events at pre_tool / post_tool / on_error.", "pre_tool / post_tool / on_error でイベントを出します。") },
+      { id: "registry", lane: "hooks", label: l("Hook 注册表", "Hook Registry", "Hook レジストリ"), detail: l("统一管理谁来观察。", "One registry decides who observes.", "誰が観測するかを一元管理します。") },
+      { id: "audit", lane: "hooks", label: l("日志/审计", "Audit / Trace", "監査 / 追跡"), detail: l("旁路能力不侵入主逻辑。", "Side effects stay out of the core loop.", "副作用は主ロジックへ侵入しません。") },
+      { id: "tool-path", lane: "loop", label: l("核心执行", "Core Execution", "コア実行"), detail: l("主循环照常执行本轮工作。", "The main loop still runs the actual work.", "主ループは通常どおり本輪の仕事を実行します。") },
+      { id: "writeback", lane: "history", label: l("统一回写", "Unified Write-back", "統一回写"), detail: l("结果与旁路观察都能进入历史。", "Results and observations can both enter history.", "結果も観測も履歴へ入れます。") },
+    ],
+    records: [
+      { id: "hook-event", label: l("HookEvent", "HookEvent", "HookEvent"), note: l("固定字段的事件对象。", "A structured event object with stable fields.", "安定したフィールドを持つイベントオブジェクトです。") },
+      { id: "hook-result", label: l("HookResult", "HookResult", "HookResult"), note: l("Hook 处理后的副作用结果。", "The side-effect result from a hook.", "Hook が返す副作用結果です。") },
+      { id: "hook-registry", label: l("HookRegistry", "HookRegistry", "HookRegistry"), note: l("统一登记和分发 Hook。", "Registers and dispatches hooks centrally.", "Hook を一元的に登録・配布します。") },
+    ],
+    steps: [
+      {
+        title: l("先确定事件边界", "Define the event boundary first", "先にイベント境界を定義する"),
+        description: l("主循环不是随便让外部逻辑插进来，而是在固定时机主动发出 HookEvent。", "The loop does not allow random code to jump in. It emits HookEvent at stable moments.", "主ループは場当たり的に外部ロジックを差し込むのではなく、固定時点で HookEvent を出します。"),
+        activeNodes: ["advance", "emit"],
+        activeRecords: ["hook-event"],
+        boundary: l("先定义什么时候能观察，再定义谁来观察。", "Define when the loop is observable before deciding who observes it.", "誰が観測するかの前に、いつ観測可能かを定義します。"),
+        writeBack: l("事件不是终点，它会把本轮状态送到 Hook 侧车继续处理。", "The event is not the endpoint. It hands the current state to sidecar hooks.", "イベントは終点ではなく、このターンの状態を sidecar hook へ渡します。"),
+      },
+      {
+        title: l("Hook 通过注册表挂上去", "Hooks attach through a registry", "Hook は registry 経由で接続する"),
+        description: l("多个 Hook 可以共享同一事件契约，主循环不需要知道每个 Hook 的内部细节。", "Multiple hooks can share the same contract, and the loop does not need to know their internal details.", "複数 Hook が同じ契約を共有でき、主ループは各 Hook の中身を知る必要がありません。"),
+        activeNodes: ["emit", "registry", "audit"],
+        activeRecords: ["hook-event", "hook-registry"],
+        boundary: l("不要把 Hook 写成另一套主循环。它应该观察和补充，而不是接管。", "Do not turn hooks into a second main loop. They should observe and extend, not take over.", "Hook を第2の主ループにしないでください。観測と補助が役目です。"),
+        writeBack: l("Hook 产出的副作用结果仍然经统一入口回到系统。", "Hook side effects still return through a unified entry path.", "Hook の副作用結果も統一入口からシステムへ戻ります。"),
+      },
+      {
+        title: l("主线继续执行，Hook 在旁边观察", "The mainline keeps running while hooks observe", "主線は進み、Hook は横で観測する"),
+        description: l("Hook 的价值不是阻止主线，而是把审计、追踪、策略副作用和核心执行拆成两条心智线。", "Hooks are valuable because they separate auditing, tracing, and policy side effects from the core execution path.", "Hook の価値は主線を止めることではなく、監査や追跡をコア実行から分離することです。"),
+        activeNodes: ["registry", "audit", "tool-path"],
+        activeRecords: ["hook-result"],
+        boundary: l("副作用和主流程必须解耦，否则每个工具都会被日志逻辑污染。", "Side effects must stay decoupled from the main flow or every tool gets polluted by observability logic.", "副作用と主処理を分離しないと、全 tool が観測ロジックで汚れてしまいます。"),
+        writeBack: l("核心执行结果和 Hook 副作用都汇到统一回写层。", "Core execution and hook side effects both converge in one write-back layer.", "コア実行結果と Hook 副作用は統一回写層へ集まります。"),
+      },
+      {
+        title: l("副作用结果也能被下一轮看见", "Side effects can be visible to later turns", "副作用結果も次のターンで見える"),
+        description: l("一旦需要审计、追踪或修复提示，Hook 产物也应该像主线结果那样成为下一轮可见事实。", "When auditing, tracing, or repair hints matter, hook output should become visible facts for later turns just like core results.", "監査・追跡・修復ヒントが重要なら、Hook 出力も主線結果と同じく後続ターンで見える事実にすべきです。"),
+        activeNodes: ["tool-path", "audit", "writeback"],
+        activeRecords: ["hook-result"],
+        boundary: l("Hook 不是只给人类看日志，它也可以给系统留下可消费的旁路信息。", "Hooks are not just for human-readable logs. They can also leave machine-consumable side information.", "Hook は人間向けログだけではなく、システムが消費できる側路情報も残せます。"),
+        writeBack: l("统一回写后，下一轮既知道主线结果，也知道旁路观察到了什么。", "After unified write-back, the next turn can see both the mainline result and what the sidecars observed.", "統一回写のあと、次のターンは主線結果と sidecar の観測結果の両方を見られます。"),
+      },
+    ],
+  },
+  s09: {
+    lanes: [
+      { id: "turn", label: l("新一轮", "New Turn", "新しいターン"), note: l("当前请求进入系统。", "The current request enters the system.", "現在のリクエストがシステムへ入ります。") },
+      { id: "memory", label: l("记忆层", "Memory Layer", "記憶層"), note: l("跨会话事实只在这里保存。", "Cross-session facts live here.", "会話をまたぐ事実はここに残ります。") },
+      { id: "prompt", label: l("输入装配", "Prompt Assembly", "入力組み立て"), note: l("相关记忆在这里重新进入当前轮。", "Relevant memory re-enters the current turn here.", "関連記憶はここで今のターンへ戻ります。") },
+      { id: "writeback", label: l("提炼回写", "Extraction + Persist", "抽出と保存"), note: l("只有 durable fact 才会写回。", "Only durable facts are written back.", "durable fact だけが書き戻されます。") },
+    ],
+    nodes: [
+      { id: "request", lane: "turn", label: l("当前请求", "Current Request", "現在の要求"), detail: l("新任务开始。", "A new task begins.", "新しい仕事が始まります。") },
+      { id: "load", lane: "memory", label: l("载入相关记忆", "Load Relevant Memory", "関連記憶を読む"), detail: l("只挑和当前任务相关的事实。", "Load only the facts relevant to this task.", "この仕事に関係する事実だけを読みます。") },
+      { id: "assemble", lane: "prompt", label: l("组装输入", "Assemble Prompt", "入力を組み立てる"), detail: l("把记忆和当前上下文并列放进去。", "Place memory beside the live context.", "記憶を現在の文脈と並べて入れます。") },
+      { id: "work", lane: "prompt", label: l("完成当前工作", "Do the Work", "現在の仕事を進める"), detail: l("模型和工具继续本轮工作。", "The model and tools continue the current work.", "モデルと tool がこのターンの仕事を進めます。") },
+      { id: "extract", lane: "writeback", label: l("提炼 durable fact", "Extract Durable Facts", "durable fact を抽出"), detail: l("不是所有内容都值得记。", "Not everything deserves to be remembered.", "すべてを覚えるわけではありません。") },
+      { id: "persist", lane: "writeback", label: l("写回记忆库", "Persist Memory", "記憶へ保存"), detail: l("跨会话仍重要的内容才进入 store。", "Only facts that still matter across sessions enter the store.", "会話をまたいでも重要な内容だけが store に入ります。") },
+    ],
+    records: [
+      { id: "memory-entry", label: l("MemoryEntry", "MemoryEntry", "MemoryEntry"), note: l("长期保存的事实条目。", "A durable fact entry.", "長期保存される事実エントリです。") },
+      { id: "memory-query", label: l("MemoryQuery", "MemoryQuery", "MemoryQuery"), note: l("决定本轮要读哪些记忆。", "Determines which memory to load for this turn.", "このターンで読む記憶を決めます。") },
+      { id: "memory-candidate", label: l("MemoryCandidate", "MemoryCandidate", "MemoryCandidate"), note: l("本轮结束后候选写回事实。", "A candidate fact extracted after the turn.", "ターン終了後に候補として抽出された事実です。") },
+    ],
+    steps: [
+      {
+        title: l("先读和当前任务有关的记忆", "Load only memory relevant to the current task", "現在の仕事に関係する記憶だけ読む"),
+        description: l("记忆系统的第一护栏是少而准。不是每次都把整个长期记忆塞回 prompt。", "The first guardrail of memory is being selective. You do not dump the entire memory store back into every prompt.", "記憶システムの第一ガードレールは少なく正確であることです。毎回すべてを prompt に戻しません。"),
+        activeNodes: ["request", "load"],
+        activeRecords: ["memory-query", "memory-entry"],
+        boundary: l("长期记忆不是上下文备份，它是本轮按需取回的知识层。", "Long-term memory is not a context backup. It is a knowledge layer loaded on demand.", "長期記憶は文脈バックアップではなく、必要時だけ戻す知識層です。"),
+        writeBack: l("读到的记忆随后进入输入装配，而不是直接覆盖当前上下文。", "Loaded memory proceeds into prompt assembly instead of replacing the live context.", "読み込んだ記憶は現在文脈を置き換えず、入力組み立てへ進みます。"),
+      },
+      {
+        title: l("记忆和当前上下文并列进入输入", "Memory and live context enter the prompt side by side", "記憶と現在文脈を並列で入力へ入れる"),
+        description: l("messages[] 负责当前过程，memory 负责跨会话事实。真正关键是两者分层，不是谁取代谁。", "messages[] carries the live process while memory carries cross-session facts. The key is layering them, not replacing one with the other.", "messages[] は現在の過程、memory は会話をまたぐ事実を持ちます。重要なのは置き換えではなく分層です。"),
+        activeNodes: ["load", "assemble", "work"],
+        activeRecords: ["memory-entry"],
+        boundary: l("记忆不能取代当前上下文，否则模型会失去正在做什么的连贯性。", "Memory cannot replace live context, or the model loses continuity about what it is currently doing.", "memory が現在文脈を置き換えると、モデルは今何をしているかの連続性を失います。"),
+        writeBack: l("模型完成工作后，才会进入下一步提炼哪些内容值得留下。", "Only after the work turn finishes do you ask what deserves to persist.", "仕事ターンが終わってから、何を残すべきかを考えます。"),
+      },
+      {
+        title: l("完成工作后再提炼 durable fact", "Extract durable facts only after the work turn", "仕事後に durable fact を抽出する"),
+        description: l("写记忆最稳的时机是任务阶段性结束后。这样你才看得见什么是稳定事实，什么只是临时输出。", "The safest moment to write memory is after a meaningful work segment completes, when you can tell durable facts from temporary output.", "記憶を書き出す最も安定したタイミングは、意味のある仕事区間が終わったあとです。"),
+        activeNodes: ["work", "extract"],
+        activeRecords: ["memory-candidate"],
+        boundary: l("不是所有模型输出都值得长期保留。先过滤，再决定要不要写入。", "Not every model output deserves long-term storage. Filter first, then decide whether to persist.", "すべての出力を長期保存しない。先に絞り込みます。"),
+        writeBack: l("提炼出的 candidate 会进入记忆库，而当前轮上下文继续留在 messages[]。", "Extracted candidates go to the memory store while the live process stays in messages[].", "抽出候補は memory store へ、現在の過程は messages[] に残ります。"),
+      },
+      {
+        title: l("只有值得跨会话保留的事实才入库", "Only cross-session facts enter the memory store", "会話をまたいで残す価値のある事実だけ入庫する"),
+        description: l("记忆系统真正教的是取舍。什么值得留下，决定了后续 agent 是更稳还是更乱。", "The deepest lesson of memory is selection. What you keep determines whether later sessions become steadier or noisier.", "記憶システムの本質は選別です。何を残すかで、次回以降が安定するか騒がしくなるかが決まります。"),
+        activeNodes: ["extract", "persist"],
+        activeRecords: ["memory-candidate", "memory-entry"],
+        boundary: l("长期记忆只收 durable fact，不收一整段对话流水账。", "Long-term memory should store durable facts, not full chat transcripts.", "長期記憶は durable fact を保存し、会話の逐語録は保存しません。"),
+        writeBack: l("保存后的 MemoryEntry 会在未来相关任务中被重新装配进输入。", "Persisted MemoryEntry can be reloaded into future relevant turns.", "保存された MemoryEntry は将来の関連ターンで再び入力へ組み込まれます。"),
+      },
+    ],
+  },
+  s10: {
+    lanes: [
+      { id: "policy", label: l("稳定规则", "Stable Policy", "安定ルール"), note: l("长期不变的系统约束。", "Long-lived system rules.", "長期的に変わらない制約です。") },
+      { id: "runtime", label: l("运行时状态", "Runtime State", "ランタイム状態"), note: l("当前目录、工具、待办、任务等。", "Current workspace, tools, todos, tasks, and more.", "現在の workspace、tool、todo、task などです。") },
+      { id: "assembly", label: l("装配流水线", "Assembly Pipeline", "組み立てパイプライン"), note: l("决定按什么顺序拼输入。", "Decides the assembly order.", "どんな順番で入力を組むかを決めます。") },
+      { id: "loop", label: l("模型可见输入", "Model-Visible Input", "モデル可視入力"), note: l("真正给模型看的只有最后产物。", "The model only sees the final assembled input.", "モデルが見るのは最終的に組み上がった入力だけです。") },
+    ],
+    nodes: [
+      { id: "stable-policy", lane: "policy", label: l("角色/底线", "Role + Hard Rules", "役割 / ハードルール"), detail: l("稳定内容单独存在。", "Stable content lives in its own layer.", "安定内容は独立して置きます。") },
+      { id: "tools", lane: "runtime", label: l("工具信息", "Tool Catalog", "ツール情報"), detail: l("本轮可用工具集。", "The tool set available for this turn.", "このターンで使える tool 集です。") },
+      { id: "memory", lane: "runtime", label: l("记忆与任务", "Memory + Task State", "記憶と task 状態"), detail: l("动态上下文分块进入。", "Dynamic context enters in distinct blocks.", "動的文脈が分割された状態で入ります。") },
+      { id: "assemble", lane: "assembly", label: l("PromptBuilder", "PromptBuilder", "PromptBuilder"), detail: l("显式拼装顺序。", "Explicit assembly order.", "明示的な組み立て順です。") },
+      { id: "final-input", lane: "loop", label: l("最终输入", "Final Input", "最終入力"), detail: l("模型真正看到的单一入口。", "The single input the model really sees.", "モデルが実際に見る単一の入口です。") },
+      { id: "response", lane: "loop", label: l("模型响应", "Model Response", "モデル応答"), detail: l("下一轮又会回到这条装配链。", "The next turn returns to this pipeline again.", "次のターンでもこの組み立て列に戻ります。") },
+    ],
+    records: [
+      { id: "prompt-parts", label: l("PromptParts", "PromptParts", "PromptParts"), note: l("系统输入的分块容器。", "Structured prompt fragments.", "system 入力の断片コンテナです。") },
+      { id: "prompt-builder", label: l("PromptBuilder", "PromptBuilder", "PromptBuilder"), note: l("定义装配顺序。", "Defines the prompt assembly order.", "組み立て順を定義します。") },
+      { id: "runtime-context", label: l("RuntimeContext", "RuntimeContext", "RuntimeContext"), note: l("本轮动态注入的上下文。", "Dynamic runtime context for the current turn.", "このターンで動的注入される文脈です。") },
+    ],
+    steps: [
+      {
+        title: l("先把稳定规则单独拿出来", "Pull stable policy into its own layer first", "安定ルールを独立層へ出す"),
+        description: l("系统提示词最容易讲糊的地方，是把所有内容揉成一大段字符串。教学上要先拆出稳定规则。", "The biggest prompt-teaching mistake is flattening everything into one giant string. Start by separating stable policy.", "prompt 教学で最も混乱しやすいのは、全部を巨大な文字列へ潰すことです。まず安定ルールを分離します。"),
+        activeNodes: ["stable-policy"],
+        activeRecords: ["prompt-parts"],
+        boundary: l("稳定规则和当前任务状态不是一回事，必须分层。", "Stable policy and current task state are not the same thing and must stay separate.", "安定ルールと現在の task 状態は別物です。"),
+        writeBack: l("稳定规则不会直接被模型消费，它会进入 PromptBuilder 参与最终装配。", "Stable policy is not consumed alone; it enters the PromptBuilder for final assembly.", "安定ルールは単独消費されず、PromptBuilder で最終組み立てへ入ります。"),
+      },
+      {
+        title: l("动态状态按块进入 PromptBuilder", "Dynamic state enters the PromptBuilder in blocks", "動的状態をブロック単位で PromptBuilder へ入れる"),
+        description: l("工具、记忆、待办、错误恢复提示都属于动态片段。重要的是它们要有清楚来源和顺序。", "Tools, memory, todos, and recovery hints are dynamic fragments. What matters is that they have clear sources and order.", "tool・memory・todo・recovery hint は動的断片です。重要なのは出所と順序が明確であることです。"),
+        activeNodes: ["tools", "memory", "assemble"],
+        activeRecords: ["runtime-context", "prompt-builder"],
+        boundary: l("不要把动态状态硬拼到稳定规则里，否则后续很难解释清楚哪些东西是临时的。", "Do not hardcode dynamic state into stable policy, or you lose the ability to explain what is temporary.", "動的状態を安定ルールへ埋め込むと、一時情報がどれか説明しづらくなります。"),
+        writeBack: l("所有动态块按顺序进入 PromptBuilder，形成最终模型输入。", "All dynamic blocks flow into the PromptBuilder in order to create the final input.", "すべての動的ブロックが順番に PromptBuilder へ入り、最終入力になります。"),
+      },
+      {
+        title: l("模型真正看到的是最终装配产物", "The model sees the assembled product, not the parts", "モデルが見るのは最終組み立て結果"),
+        description: l("教学上要让读者意识到：模型不是直接读取工具系统或记忆库，它只看到最终输入。", "Readers should understand that the model does not directly inspect the tool system or memory store. It only sees the assembled input.", "モデルは tool system や memory store を直接見るのではなく、組み上がった最終入力だけを見ます。"),
+        activeNodes: ["assemble", "final-input"],
+        activeRecords: ["prompt-builder", "prompt-parts"],
+        boundary: l("输入装配本身就是控制面，因为它决定模型这一轮能看到什么。", "Prompt assembly is itself a control plane because it decides what the model can see this turn.", "入力組み立て自体が control plane です。モデルがこのターンで何を見られるかを決めるからです。"),
+        writeBack: l("最终输入喂给模型后，系统才得到下一步动作或文本响应。", "Only after the final input is built does the system get the model's next action or text response.", "最終入力を渡したあとで、モデルの次の行動や応答が返ります。"),
+      },
+      {
+        title: l("下一轮又回到同一装配管道", "The next turn re-enters the same assembly pipeline", "次のターンも同じ組み立て経路へ戻る"),
+        description: l("这章真正建立的是输入控制面。每一轮都在重复“取规则、取动态状态、装配、调用模型”这条主线。", "This chapter really establishes an input control plane. Every turn repeats the same mainline: gather rules, gather runtime state, assemble, call the model.", "この章が作るのは入力 control plane です。毎ターン、ルール収集・動的状態収集・組み立て・モデル呼び出しを繰り返します。"),
+        activeNodes: ["final-input", "response", "stable-policy"],
+        activeRecords: ["prompt-builder"],
+        boundary: l("Prompt pipeline 不是一次性的字符串拼接，而是会在每轮反复运行的系统流程。", "The prompt pipeline is not one-off string concatenation. It is a system flow that runs every turn.", "prompt pipeline は一回限りの文字列連結ではなく、毎ターン動くシステム流程です。"),
+        writeBack: l("模型响应会更新当前状态，然后再次进入 PromptBuilder 所在的装配链。", "The model response updates the live state and then re-enters the same prompt-building chain.", "モデル応答は現在状態を更新し、その後また同じ prompt-building chain に戻ります。"),
+      },
+    ],
+  },
+  s11: {
+    lanes: [
+      { id: "runtime", label: l("执行结果", "Execution Result", "実行結果"), note: l("本轮执行到了成功或失败。", "The current execution finishes in success or failure.", "この実行は成功か失敗で一区切りします。") },
+      { id: "recovery", label: l("恢复分支", "Recovery Branch", "回復分岐"), note: l("失败后要分类再处理。", "Failures must be classified before recovery.", "失敗は分類してから回復します。") },
+      { id: "state", label: l("续行状态", "Continuation State", "続行状態"), note: l("继续的原因要写清。", "The reason for continuing must be explicit.", "なぜ続行するかを明示します。") },
+      { id: "loop", label: l("主循环", "Main Loop", "主ループ"), note: l("恢复后才能决定继续还是结束。", "Only after recovery can the loop continue or stop.", "回復後に続行か終了かを決めます。") },
+    ],
+    nodes: [
+      { id: "result", lane: "runtime", label: l("工具结果", "Tool Result", "tool 結果"), detail: l("成功与失败都从这里开始。", "Both success and failure start here.", "成功も失敗もここから始まります。") },
+      { id: "detect", lane: "recovery", label: l("发现异常", "Detect Failure", "失敗検知"), detail: l("先看这是不是恢复分支。", "First decide whether this is a recovery path.", "まず回復分岐かどうかを見ます。") },
+      { id: "classify", lane: "recovery", label: l("分类原因", "Classify Reason", "理由分類"), detail: l("权限、超时、环境缺失等不能混成一类。", "Permission, timeout, and missing environment errors should not be one bucket.", "権限・タイムアウト・環境欠如を一括りにしません。") },
+      { id: "branch", lane: "recovery", label: l("选择恢复分支", "Choose Recovery Branch", "回復分岐選択"), detail: l("retry / fallback / ask / stop。", "retry / fallback / ask / stop.", "retry / fallback / ask / stop を選びます。") },
+      { id: "reason", lane: "state", label: l("写明续行原因", "Write Continuation Reason", "続行理由を書く"), detail: l("下一轮必须知道为什么继续。", "The next turn must know why it is continuing.", "次のターンはなぜ続行するかを知る必要があります。") },
+      { id: "continue", lane: "loop", label: l("继续或结束", "Continue or Stop", "続行か終了"), detail: l("恢复分支完成后才决定下一步。", "Only after recovery do you choose the next step.", "回復後に次の一歩を決めます。") },
+    ],
+    records: [
+      { id: "error-event", label: l("ErrorEvent", "ErrorEvent", "ErrorEvent"), note: l("记录本次失败发生了什么。", "Captures what failed this time.", "今回何が失敗したかを記録します。") },
+      { id: "recovery-state", label: l("RecoveryState", "RecoveryState", "RecoveryState"), note: l("当前处于哪条恢复分支。", "Tracks the current recovery branch.", "どの回復分岐にいるかを追跡します。") },
+      { id: "transition-reason", label: l("TransitionReason", "TransitionReason", "TransitionReason"), note: l("为什么继续、重试或停止。", "Explains why the system continues, retries, or stops.", "なぜ続行・再試行・停止するかを示します。") },
+    ],
+    steps: [
+      {
+        title: l("先确认这是不是恢复分支", "First confirm whether this is a recovery path", "まず回復分岐か確認する"),
+        description: l("错误恢复不是永远存在，它只在失败发生时接管。第一步是把失败从普通结果里分出来。", "Recovery is not always active. It only takes over when failure happens, so first separate failures from ordinary results.", "回復は常時動くわけではありません。失敗時だけ主導するので、まず通常結果と分けます。"),
+        activeNodes: ["result", "detect"],
+        activeRecords: ["error-event"],
+        boundary: l("不要把所有工具结果都扔进统一 retry 逻辑。先确认是不是错误。", "Do not dump every tool result into one retry branch. First confirm whether it is actually a failure.", "すべての tool 結果を一律 retry に入れないでください。まず失敗か確認します。"),
+        writeBack: l("一旦确认失败，控制流转向恢复层而不是继续假装成功。", "Once failure is confirmed, control moves into recovery instead of pretending the turn succeeded.", "失敗が確認されたら、成功したふりをせず recovery 層へ移ります。"),
+      },
+      {
+        title: l("错误要先分类再恢复", "Classify failures before recovering", "失敗は分類してから回復する"),
+        description: l("权限拒绝、超时、环境缺失、写冲突的恢复策略不同，所以恢复前一定先分类。", "Permission denials, timeouts, missing dependencies, and write conflicts recover differently, so classification must come first.", "権限拒否・タイムアウト・依存欠如・書き込み競合は回復方法が違うため、まず分類します。"),
+        activeNodes: ["detect", "classify", "branch"],
+        activeRecords: ["error-event", "recovery-state"],
+        boundary: l("恢复稳定性的来源不是多重 try/except，而是分类足够清楚。", "Recovery becomes stable not through more try/except blocks, but through clear classification.", "回復が安定するのは try/except の数ではなく、分類が明確だからです。"),
+        writeBack: l("分类后的 RecoveryState 决定接下来走 retry、fallback、ask 还是 stop。", "RecoveryState determines whether the next branch is retry, fallback, ask, or stop.", "分類後の RecoveryState が retry / fallback / ask / stop を決めます。"),
+      },
+      {
+        title: l("恢复动作要带着理由继续", "Recovery continues with an explicit reason", "回復後は理由付きで続行する"),
+        description: l("真正关键的点在于：系统不只是继续了，而是知道自己为什么继续。", "The key point is not that the system continues, but that it knows why it is continuing.", "本当に重要なのは、system がただ続くことではなく、なぜ続くのかを自分で分かっていることです。"),
+        activeNodes: ["branch", "reason"],
+        activeRecords: ["recovery-state", "transition-reason"],
+        boundary: l("retry、fallback、ask 都应该显式写成 TransitionReason，而不是静默吞掉。", "retry, fallback, and ask should all be written as TransitionReason instead of silently swallowed.", "retry・fallback・ask は黙って飲み込まず、TransitionReason として明示します。"),
+        writeBack: l("恢复原因进入续行状态，供下一轮推理理解当前分支。", "The recovery reason becomes visible state for the next reasoning step.", "回復理由は見える状態となり、次の推論が今の分岐を理解できるようにします。"),
+      },
+      {
+        title: l("只有写明原因后，主循环才能稳定继续", "The main loop resumes safely only after the reason is written", "理由を書いてから主ループが安全に再開する"),
+        description: l("恢复系统的终点不是“又试一次”，而是把恢复后的当前状态重新变成主循环可消费的事实。", "The endpoint of recovery is not “try again.” It is turning the recovered branch into visible state the main loop can consume.", "回復の終点は『もう一度試す』ではなく、回復後の状態を主ループが消費できる事実へ戻すことです。"),
+        activeNodes: ["reason", "continue"],
+        activeRecords: ["transition-reason"],
+        boundary: l("没有续行原因，下一轮会不知道自己为什么还在这条分支上。", "Without a continuation reason, the next turn will not know why it is still on this branch.", "続行理由がないと、次のターンはなぜこの分岐にいるのか分かりません。"),
+        writeBack: l("主循环看到 TransitionReason 后，才能按当前恢复状态继续、降级或结束。", "Once the main loop sees TransitionReason, it can continue, degrade, or stop coherently.", "主ループが TransitionReason を見ることで、続行・降格・終了を筋道立てて選べます。"),
+      },
+    ],
+  },
+  s12: {
+    lanes: [
+      { id: "input", label: l("目标入口", "Goal Entry", "目標入口"), note: l("一个更大的目标进入系统。", "A larger goal enters the system.", "より大きな目標がシステムへ入ります。") },
+      { id: "board", label: l("任务板", "Task Board", "タスクボード"), note: l("这里保存 durable work graph。", "The durable work graph lives here.", "durable work graph はここにあります。") },
+      { id: "records", label: l("记录层", "Record Layer", "レコード層"), note: l("任务、依赖和状态都必须显式。", "Tasks, dependencies, and status must be explicit.", "task・依存・状態を明示します。") },
+      { id: "return", label: l("回流顺序", "Return Order", "回流順"), note: l("完成一个节点后如何解锁后继。", "How finishing one node unlocks the next.", "1 つ完了したあとでどう次を解放するかです。") },
+    ],
+    nodes: [
+      { id: "goal", lane: "input", label: l("目标拆分", "Split Goal", "目標分解"), detail: l("把大任务拆成多个 durable node。", "Split a large goal into durable work nodes.", "大きな目標を durable node へ分解します。") },
+      { id: "board", lane: "board", label: l("任务板登记", "Register on Board", "ボード登録"), detail: l("任务先成为记录，再考虑执行。", "A task becomes a record before it becomes execution.", "task はまず record になります。") },
+      { id: "edges", lane: "records", label: l("依赖边", "Dependency Edges", "依存エッジ"), detail: l("blockedBy / blocks 决定谁先谁后。", "blockedBy / blocks decide ordering.", "blockedBy / blocks が順序を決めます。") },
+      { id: "status", lane: "records", label: l("任务状态", "Task Status", "task 状態"), detail: l("pending / blocked / done 必须可见。", "pending / blocked / done must stay visible.", "pending / blocked / done を見える状態にします。") },
+      { id: "complete", lane: "return", label: l("完成当前节点", "Complete Node", "現在ノード完了"), detail: l("一个节点完成后才检查后继。", "Only after completion do you inspect downstream work.", "完了後に後続を確認します。") },
+      { id: "unlock", lane: "return", label: l("解锁后续任务", "Unlock Downstream", "後続解放"), detail: l("任务板根据依赖关系更新资格。", "The board updates eligibility from dependency state.", "ボードが依存状態から実行資格を更新します。") },
+    ],
+    records: [
+      { id: "task-record", label: l("TaskRecord", "TaskRecord", "TaskRecord"), note: l("durable task 节点本体。", "The durable task node itself.", "durable task node 本体です。") },
+      { id: "blocked-by", label: l("blockedBy", "blockedBy", "blockedBy"), note: l("当前节点还被谁卡住。", "Which upstream work still blocks this node.", "どの上流作業がこの node を止めているかです。") },
+      { id: "blocks", label: l("blocks", "blocks", "blocks"), note: l("这个节点完成后会放行谁。", "Which downstream nodes this task unlocks.", "この node 完了後に誰を解放するかです。") },
+      { id: "task-status", label: l("status", "status", "status"), note: l("任务板上的可见状态。", "The visible board state for a task.", "ボード上で見える task 状態です。") },
+    ],
+    steps: [
+      {
+        title: l("先把目标变成 durable task node", "Turn the goal into durable task nodes first", "目標を durable task node へ変える"),
+        description: l("这一章真正新增的是任务记录本体，而不是后台线程。任务先是 durable work graph 上的节点。", "The real addition in this chapter is the task record itself, not a background thread. A task is first a node in a durable work graph.", "この章で増える本体は background thread ではなく task record です。task は durable work graph の node から始まります。"),
+        activeNodes: ["goal", "board"],
+        activeRecords: ["task-record"],
+        boundary: l("现在讲的是目标记录，不是执行槽位。不要提前把后台执行混进来。", "This chapter is about goal records, not execution slots. Do not mix background execution in too early.", "ここで扱うのは goal record であり execution slot ではありません。"),
+        writeBack: l("目标进入任务板后，系统才知道自己未来有哪些 durable work 要推进。", "Once the goal enters the board, the system knows what durable work exists to be advanced later.", "目標が task board に入ることで、将来進める durable work が見えるようになります。"),
+      },
+      {
+        title: l("依赖边把任务排成工作图", "Dependency edges turn tasks into a work graph", "依存エッジが task を work graph にする"),
+        description: l("blockedBy 和 blocks 是任务系统真正的骨架，它们决定为什么一个节点现在不能开始。", "blockedBy and blocks are the true skeleton of the task system. They explain why a node cannot start yet.", "blockedBy と blocks は task system の骨格であり、なぜまだ始められないかを説明します。"),
+        activeNodes: ["board", "edges", "status"],
+        activeRecords: ["task-record", "blocked-by", "blocks", "task-status"],
+        boundary: l("没有显式依赖边，任务板就只是一份更大的 todo list。", "Without explicit dependency edges, the board is just a larger todo list.", "明示的な依存エッジがなければ、task board は大きい todo list にすぎません。"),
+        writeBack: l("依赖关系和状态一起写在任务板里，为后续解锁逻辑做准备。", "Dependency state is written into the board alongside status so unlock logic can run later.", "依存状態と status を task board に書き込み、後続の unlock logic を準備します。"),
+      },
+      {
+        title: l("完成一个节点后检查谁被放行", "After one node completes, check who becomes eligible", "1 つ完了したあとで誰が実行可能になるかを見る"),
+        description: l("任务系统的运行感来自‘完成一个节点以后，后继节点为什么突然能开始’。这一步必须显式。", "The runtime feel of tasks comes from explicitly showing why a downstream node becomes eligible after one node completes.", "task system の実感は『1 つ終わるとなぜ次が始められるか』を明示することから生まれます。"),
+        activeNodes: ["status", "complete", "unlock"],
+        activeRecords: ["task-status", "blocked-by", "blocks"],
+        boundary: l("不要把完成和解锁写成隐式副作用。读者必须看见状态是怎么变的。", "Do not hide completion and unlock as implicit side effects. Readers need to see how state changes.", "完了と解放を暗黙副作用にしないでください。状態変化を見せる必要があります。"),
+        writeBack: l("任务板重新计算依赖后，新的 eligible task 会浮到下一步工作入口。", "After the board recomputes dependencies, newly eligible tasks rise into the next work entry point.", "依存再計算のあと、新しく eligible になった task が次の仕事入口に上がります。"),
+      },
+      {
+        title: l("任务板把下一步工作重新送回主线", "The task board sends the next unit of work back to the mainline", "task board が次の仕事を主線へ戻す"),
+        description: l("教学上最关键的是让读者看到：任务系统不是静态表格，它会持续把新的可做工作重新送回系统主线。", "The important teaching point is that the task board is not a static table. It continuously sends newly eligible work back into the mainline.", "重要なのは、task board が静的な表ではなく、新しく可能になった仕事を主線へ返し続けることです。"),
+        activeNodes: ["board", "unlock", "goal"],
+        activeRecords: ["task-record", "task-status"],
+        boundary: l("任务板负责描述和解锁工作，不负责直接执行工作。", "The task board describes and unlocks work. It does not execute the work itself.", "task board は仕事を記述し解放しますが、直接実行はしません。"),
+        writeBack: l("被解锁的任务重新变成系统下一段主线要推进的目标。", "Unlocked tasks become the next mainline goals the system should push forward.", "解放された task が次の主線目標になります。"),
+      },
+    ],
+  },
+  s13: {
+    lanes: [
+      { id: "board", label: l("任务板", "Task Board", "タスクボード"), note: l("目标任务仍留在这里。", "Goal tasks remain here.", "goal task はここに残ります。") },
+      { id: "runtime", label: l("运行槽位", "Runtime Slot", "実行スロット"), note: l("正在跑的那一份工作独立存在。", "Live execution exists in its own slot.", "実行中の仕事は独立した slot にあります。") },
+      { id: "output", label: l("输出分层", "Output Layer", "出力層"), note: l("preview 和全文分层保存。", "Preview and full output are saved separately.", "preview と全文を分けて保存します。") },
+      { id: "notify", label: l("通知回流", "Notification Return", "通知回流"), note: l("结果在未来某轮再回到主循环。", "Results return on a later turn.", "結果は後続のターンで戻ります。") },
+    ],
+    nodes: [
+      { id: "goal-task", lane: "board", label: l("目标任务", "Goal Task", "goal task"), detail: l("durable 目标仍在任务板。", "The durable goal stays on the board.", "durable な目標は board に残ります。") },
+      { id: "spawn-runtime", lane: "runtime", label: l("生成运行记录", "Spawn Runtime Record", "runtime record 生成"), detail: l("为这次执行创建独立记录。", "Create a separate record for this execution attempt.", "今回の実行のために独立 record を作ります。") },
+      { id: "background-run", lane: "runtime", label: l("后台执行", "Run in Background", "バックグラウンド実行"), detail: l("慢工作不再阻塞前台循环。", "Slow work stops blocking the foreground loop.", "遅い仕事が前景ループを塞がなくなります。") },
+      { id: "preview", lane: "output", label: l("结果预览", "Result Preview", "結果 preview"), detail: l("通知里只放可读摘要。", "Only a readable summary goes into notifications.", "通知には読める要約だけを入れます。") },
+      { id: "full-output", lane: "output", label: l("完整输出文件", "Full Output File", "完全出力ファイル"), detail: l("长输出写文件，不撑爆 prompt。", "Long output goes to disk instead of bloating the prompt.", "長い出力は disk へ書き、prompt を膨らませません。") },
+      { id: "notification", lane: "notify", label: l("通知写回", "Write Notification", "通知回写"), detail: l("下一轮前再注入主循环。", "Inject it into the main loop on a later turn.", "後続ターンで主ループへ注入します。") },
+    ],
+    records: [
+      { id: "runtime-task", label: l("RuntimeTaskRecord", "RuntimeTaskRecord", "RuntimeTaskRecord"), note: l("描述这次执行本身。", "Describes this specific execution.", "この実行そのものを表します。") },
+      { id: "notification-record", label: l("Notification", "Notification", "Notification"), note: l("把结果带回前台循环的桥。", "The bridge that brings results back to the foreground loop.", "結果を前景ループへ戻す橋です。") },
+      { id: "output-file", label: l("output_file", "output_file", "output_file"), note: l("存放完整输出内容。", "Stores the full output.", "完全な出力を保存します。") },
+    ],
+    steps: [
+      {
+        title: l("目标任务和运行记录先分开", "Separate the goal task from the runtime record first", "goal task と runtime record を先に分ける"),
+        description: l("后台任务章真正新增的不是另一种 task，而是一层专门描述‘这次执行本身’的 runtime record。", "The chapter does not add a second kind of task. It adds a runtime record dedicated to this execution attempt.", "この章で増えるのは別種の task ではなく、『今回の実行そのもの』を記述する runtime record です。"),
+        activeNodes: ["goal-task", "spawn-runtime"],
+        activeRecords: ["runtime-task"],
+        boundary: l("目标任务记录‘要做什么’，运行记录记录‘这次怎么跑’。两者不能混。", "The goal task records what should be done, while the runtime record records how this attempt is running. They should not be merged.", "goal task は『何をするか』、runtime record は『今回どう走るか』を持ちます。混ぜません。"),
+        writeBack: l("生成 RuntimeTaskRecord 后，前台循环就可以先继续，慢任务进入后台车道。", "Once the RuntimeTaskRecord exists, the foreground loop can continue while the slow task enters a background lane.", "RuntimeTaskRecord ができたら、前景ループは先へ進み、遅い仕事は背景レーンへ移れます。"),
+      },
+      {
+        title: l("慢工作在后台槽位执行", "Slow work runs inside the background slot", "遅い仕事は background slot で走る"),
+        description: l("并行的不是第二个主循环，而是等待和执行这件事本身。主循环没有消失。", "What runs in parallel is the waiting/execution work itself, not a second main loop. The main loop still exists.", "並列になるのは待ち時間と実行そのものであり、第2の主ループではありません。"),
+        activeNodes: ["spawn-runtime", "background-run"],
+        activeRecords: ["runtime-task"],
+        boundary: l("后台执行不等于后台思考。不要把它误讲成另一个完整 agent。", "Background execution does not mean a second background thinker. Do not teach it as another full agent.", "バックグラウンド実行は、別の思考 agent が生まれたことではありません。"),
+        writeBack: l("后台槽位完成后，不直接改 messages[]，而是先生成输出和通知。", "When the background slot finishes, it does not edit messages[] directly. It writes output and notifications first.", "背景 slot は終わっても messages[] を直接触らず、まず出力と通知を作ります。"),
+      },
+      {
+        title: l("预览和全文必须分层保存", "Preview and full output must be stored separately", "preview と全文を分層保存する"),
+        description: l("真正稳的设计不是把大段后台输出塞回 prompt，而是只把 preview 带回前台，把全文落盘。", "The stable design is not to stuff huge background output back into the prompt, but to return only a preview while persisting the full output.", "安定した設計は巨大出力を prompt に戻すことではなく、preview だけ返して全文は保存することです。"),
+        activeNodes: ["background-run", "preview", "full-output"],
+        activeRecords: ["runtime-task", "output-file"],
+        boundary: l("通知负责告诉主循环‘有结果了’，不负责承载全部结果内容。", "Notifications should tell the main loop that work finished, not carry the entire output payload.", "通知は『結果が出た』ことを伝え、全文を背負いません。"),
+        writeBack: l("preview 进入 Notification，全文进入 output_file，二者在未来按需重连。", "The preview goes into Notification, the full text goes into output_file, and they reconnect later on demand.", "preview は Notification へ、全文は output_file へ入り、必要時だけ再接続します。"),
+      },
+      {
+        title: l("通知在下一轮前把结果接回主循环", "Notifications reconnect the result on a later turn", "通知が後続ターンで結果を主ループへ戻す"),
+        description: l("后台结果之所以不拧巴，是因为它通过 Notification 这座桥，重新以‘本轮可见事实’的形式返回。", "Background results stay understandable because they return through Notification as visible facts for a later turn.", "背景結果が分かりやすいのは、Notification という橋を通って後続ターンの可視事実として戻るからです。"),
+        activeNodes: ["preview", "notification", "goal-task"],
+        activeRecords: ["notification-record", "runtime-task"],
+        boundary: l("后台线程不要直接篡改模型状态，统一回流时机要留在前台控制面。", "Background workers should not mutate model state directly. The write-back moment belongs to the foreground control plane.", "背景 worker がモデル状態を直接書き換えないこと。回流タイミングは前景 control plane に残します。"),
+        writeBack: l("下一轮注入 Notification 后，主循环再决定要不要去读完整输出文件。", "After injecting Notification on a later turn, the main loop decides whether it needs to read the full output file.", "後続ターンで Notification を注入したあと、主ループが全文ファイルを読むかどうかを決めます。"),
+      },
+    ],
+  },
+  s14: {
+    lanes: [
+      { id: "clock", label: l("时间触发", "Time Trigger", "時間トリガ"), note: l("时间第一次成为启动源。", "Time becomes a trigger source.", "時間が起動源になります。") },
+      { id: "schedule", label: l("调度规则", "Schedule Rules", "スケジュールルール"), note: l("这里只决定是否命中。", "This layer only decides whether a rule matched.", "ここはヒット判定だけを行います。") },
+      { id: "runtime", label: l("运行时接力", "Runtime Handoff", "ランタイム受け渡し"), note: l("命中后仍然创建 runtime work。", "A match still creates runtime work.", "ヒット後も runtime work を作ります。") },
+      { id: "return", label: l("事件回流", "Event Return", "イベント回流"), note: l("调度结果也要被系统看见。", "Schedule outcomes should also remain visible.", "スケジュール結果もシステムから見えるようにします。") },
+    ],
+    nodes: [
+      { id: "tick", lane: "clock", label: l("Cron Tick", "Cron Tick", "Cron Tick"), detail: l("定期检查时间规则。", "Periodically check schedule rules.", "定期的にルールを確認します。") },
+      { id: "match", lane: "schedule", label: l("规则命中?", "Rule Match?", "ルール一致?"), detail: l("时间只负责判断要不要启动。", "Time only decides whether work should start.", "時間は起動可否だけを決めます。") },
+      { id: "schedule-record", lane: "schedule", label: l("调度记录", "Schedule Record", "schedule record"), detail: l("描述何时、按什么规则触发。", "Describes when and why work was triggered.", "いつどのルールで起動したかを表します。") },
+      { id: "spawn", lane: "runtime", label: l("创建运行任务", "Create Runtime Task", "runtime task 作成"), detail: l("命中后仍生成 runtime task。", "A matching schedule still creates a runtime task.", "一致後も runtime task を作ります。") },
+      { id: "background", lane: "runtime", label: l("交给后台运行时", "Hand Off to Background Runtime", "背景 runtime へ渡す"), detail: l("执行仍由后台任务层负责。", "Execution is still owned by the runtime layer.", "実行は引き続き runtime 層が担います。") },
+      { id: "notify", lane: "return", label: l("调度事件回写", "Write Schedule Event", "schedule event 回写"), detail: l("系统要知道这次工作是被时间触发的。", "The system should know this work came from a schedule.", "この仕事が時間トリガで始まったと分かる必要があります。") },
+    ],
+    records: [
+      { id: "schedule-rule", label: l("ScheduleRecord", "ScheduleRecord", "ScheduleRecord"), note: l("保存时间规则和触发目标。", "Stores the schedule rule and target work.", "時間ルールと起動対象を保存します。") },
+      { id: "runtime-task", label: l("RuntimeTaskRecord", "RuntimeTaskRecord", "RuntimeTaskRecord"), note: l("真正执行的那一份工作。", "The runtime record for actual execution.", "実際に動く仕事の runtime record です。") },
+      { id: "schedule-event", label: l("ScheduleEvent", "ScheduleEvent", "ScheduleEvent"), note: l("记录本次时间触发已经发生。", "Captures that a schedule trigger fired.", "今回 schedule trigger が起きたことを記録します。") },
+    ],
+    steps: [
+      {
+        title: l("时间先命中规则，不直接执行", "Time matches rules before anything executes", "時間はまずルール一致を判定し、直接実行しない"),
+        description: l("Cron 章节真正想建立的是‘时间只是启动源’，所以第一步只判断规则有没有命中。", "The core idea of cron is that time is only a trigger source, so the first step is rule matching, not execution.", "cron の核心は『時間は起動源にすぎない』ことです。最初にやるのは実行ではなくルール一致判定です。"),
+        activeNodes: ["tick", "match", "schedule-record"],
+        activeRecords: ["schedule-rule"],
+        boundary: l("不要把时间线程误讲成执行线程。调度层先只决定要不要启动。", "Do not confuse a timing loop with an execution loop. The schedule layer first decides only whether to trigger work.", "時間ループを実行ループと混同しないでください。schedule 層は起動可否だけを決めます。"),
+        writeBack: l("一旦规则命中，控制流才会去创建真正的 runtime task。", "Only after a rule matches does control move toward creating real runtime work.", "ルール一致のあとで初めて runtime task 作成へ進みます。"),
+      },
+      {
+        title: l("命中后生成 runtime work，而不是自己执行", "A match creates runtime work instead of executing by itself", "一致後は自分で実行せず runtime work を作る"),
+        description: l("时间触发的工作和用户触发的工作，最终都应该收敛到同一 runtime task 模型。", "Work triggered by time should converge into the same runtime task model as user-triggered work.", "時間トリガ仕事もユーザートリガ仕事も、最終的には同じ runtime task model に収束すべきです。"),
+        activeNodes: ["match", "spawn"],
+        activeRecords: ["schedule-rule", "runtime-task"],
+        boundary: l("调度器只管触发，不管执行细节。否则 schedule 和 runtime 会混成一团。", "The scheduler owns triggering, not runtime execution detail. Otherwise schedule and runtime blur together.", "scheduler は trigger を持ち、実行詳細は持ちません。そうしないと schedule と runtime が混ざります。"),
+        writeBack: l("创建好的 RuntimeTaskRecord 会被交给后台运行时继续处理。", "The created RuntimeTaskRecord is handed to the background runtime for actual execution.", "作成された RuntimeTaskRecord は背景 runtime へ渡されます。"),
+      },
+      {
+        title: l("执行仍由后台运行时负责", "Execution still belongs to the background runtime", "実行は引き続き背景 runtime が担う"),
+        description: l("Cron 不需要重复发明执行模型。命中后的工作直接交给 s13 那层 runtime slot 去跑。", "Cron does not need a second execution model. Triggered work hands off to the same background runtime introduced in s13.", "cron は第2の実行モデルを発明しません。起動後の仕事は s13 の background runtime へ渡します。"),
+        activeNodes: ["spawn", "background"],
+        activeRecords: ["runtime-task"],
+        boundary: l("Cron 不是后台槽位；后台槽位才真正持有执行生命周期。", "Cron is not the background slot. The slot owns the execution lifecycle.", "cron は background slot ではありません。実行ライフサイクルは slot が持ちます。"),
+        writeBack: l("运行时完成后，再把‘这是一次时间触发工作’的事实回写给系统。", "After runtime execution completes, the system still writes back the fact that this work came from a schedule.", "runtime 実行後も『これは schedule 起動の仕事だった』という事実をシステムへ返します。"),
+      },
+      {
+        title: l("系统要看见这次工作来自时间触发", "The system should see that this work came from a schedule", "この仕事が時間トリガ由来だと見えるようにする"),
+        description: l("时间触发不是隐形来源。它应该形成可见的 ScheduleEvent，让系统理解为什么这个任务会在此时出现。", "A schedule trigger should not be invisible. It should become a visible ScheduleEvent so the system knows why this work appeared now.", "schedule trigger は見えない起源にしません。見える ScheduleEvent にして、なぜ今この仕事が現れたかを理解できるようにします。"),
+        activeNodes: ["schedule-record", "notify"],
+        activeRecords: ["schedule-event", "schedule-rule"],
+        boundary: l("如果不写回触发来源，后面的 agent 很容易不知道任务为什么会突然出现。", "If the trigger source is not written back, later agents may not understand why the task suddenly appeared.", "起動源を書き戻さないと、後続 agent はなぜ突然 task が現れたか分からなくなります。"),
+        writeBack: l("ScheduleEvent 把时间来源重新接回系统主线，供后续任务板和通知层继续理解。", "ScheduleEvent reconnects time as a visible source for later task-board and notification logic.", "ScheduleEvent が時間起源を主線へ戻し、後続の task board や通知層が理解できるようにします。"),
+      },
+    ],
+  },
+  s15: {
+    lanes: [
+      { id: "lead", label: l("Lead 编排者", "Lead Orchestrator", "Lead 編成者"), note: l("由它生成 roster 并分配工作。", "It creates the roster and assigns work.", "roster を作り、仕事を割り当てます。") },
+      { id: "roster", label: l("团队身份层", "Team Identity Layer", "チーム identity 層"), note: l("长期存在的 teammate 从这里开始。", "Persistent teammates begin here.", "長寿命 teammate はここから始まります。") },
+      { id: "mailbox", label: l("邮箱协作", "Mailbox Collaboration", "メールボックス協調"), note: l("不是共用一份 messages[]。", "The team does not share one messages[] buffer.", "1 つの messages[] を共有しません。") },
+      { id: "workers", label: l("独立执行线", "Independent Worker Lines", "独立実行線"), note: l("每个队友沿自己的车道执行。", "Each teammate runs on its own line.", "各 teammate が自分の実行線を持ちます。") },
+    ],
+    nodes: [
+      { id: "lead", lane: "lead", label: l("Lead", "Lead", "Lead"), detail: l("负责看全局并分配角色。", "Owns the global picture and assignment.", "全体像と割り当てを持ちます。") },
+      { id: "roster", lane: "roster", label: l("TeamRoster", "TeamRoster", "TeamRoster"), detail: l("列出长期存在的 teammates。", "Lists persistent teammates.", "長寿命 teammate を列挙します。") },
+      { id: "teammates", lane: "roster", label: l("Teammates", "Teammates", "Teammates"), detail: l("每个都有自己的身份和职责。", "Each has its own identity and responsibility.", "各自が固有の identity と責務を持ちます。") },
+      { id: "mail", lane: "mailbox", label: l("投递信件", "Deliver Message", "メッセージ配送"), detail: l("通过 envelope 发任务，不靠共享上下文。", "Send work via envelopes instead of shared context.", "共有文脈ではなく envelope 経由で仕事を送ります。") },
+      { id: "inbox", lane: "mailbox", label: l("独立 Inbox", "Independent Inbox", "独立 Inbox"), detail: l("每个队友只看自己的收件箱。", "Each teammate watches its own inbox.", "各 teammate は自分の inbox を見ます。") },
+      { id: "worker-run", lane: "workers", label: l("队友执行", "Teammate Execution", "teammate 実行"), detail: l("不同执行线可以反复接活。", "Worker lines can receive repeat work over time.", "worker line は繰り返し仕事を受けられます。") },
+      { id: "reply", lane: "workers", label: l("回信或继续协作", "Reply or Continue", "返信または継続協調"), detail: l("结果可以回给 Lead 或别的队友。", "Results can return to the Lead or other teammates.", "結果は Lead や他 teammate に戻せます。") },
+    ],
+    records: [
+      { id: "team-member", label: l("TeamMember", "TeamMember", "TeamMember"), note: l("长期身份、角色和状态。", "Persistent identity, role, and status.", "長寿命の identity・role・status を持ちます。") },
+      { id: "message-envelope", label: l("MessageEnvelope", "MessageEnvelope", "MessageEnvelope"), note: l("队友之间传递任务和回应的壳。", "The envelope used to pass work and replies.", "仕事や返信を渡す外殻です。") },
+      { id: "inbox-record", label: l("Inbox", "Inbox", "Inbox"), note: l("每个 teammate 的独立消息入口。", "Each teammate's independent message entry.", "各 teammate の独立メッセージ入口です。") },
+    ],
+    steps: [
+      {
+        title: l("先让队友成为长期身份", "Make teammates persistent identities first", "まず teammate を長寿命 identity にする"),
+        description: l("Agent Teams 这一章的关键不是‘多开几个模型调用’，而是先建立能长期存在的 teammate 身份层。", "The key lesson is not “more model calls,” but persistent teammate identities that survive beyond a single subtask.", "要点は『モデル呼び出しを増やすこと』ではなく、1 回きりで終わらない teammate identity を作ることです。"),
+        activeNodes: ["lead", "roster", "teammates"],
+        activeRecords: ["team-member"],
+        boundary: l("teammate 不是换了名字的 subagent。它得能长期存在、重复接活。", "A teammate is not a renamed subagent. It must persist and take repeated work.", "teammate は名前を変えた subagent ではありません。継続存在し、繰り返し仕事を受けます。"),
+        writeBack: l("Lead 生成 roster 后，系统才第一次拥有长期存在的多角色结构。", "Once the Lead builds the roster, the system gains its first persistent multi-role structure.", "Lead が roster を作ることで、システムは初めて長寿命の多役割構造を持ちます。"),
+      },
+      {
+        title: l("协作通过邮箱而不是共享上下文", "Collaboration runs through mailboxes, not shared context", "協調は共有文脈ではなく mailbox で行う"),
+        description: l("真正清晰的团队协作依赖独立 inbox 和结构化 envelope，而不是大家共用一份 messages[]。", "Clear team collaboration depends on independent inboxes and structured envelopes, not one shared messages[] buffer.", "明快なチーム協調は独立 inbox と構造化 envelope に依存し、共有 messages[] には依存しません。"),
+        activeNodes: ["teammates", "mail", "inbox"],
+        activeRecords: ["message-envelope", "inbox-record"],
+        boundary: l("如果所有队友都看同一份上下文，协作边界会很快混乱。", "If every teammate reads the same context buffer, collaboration boundaries become blurry fast.", "全 teammate が同じ文脈を読むと、協調境界はすぐ曖昧になります。"),
+        writeBack: l("任务通过 MessageEnvelope 投递进各自 Inbox，每个队友按自己的节奏取件。", "Work enters each Inbox via MessageEnvelope so teammates can process it independently.", "仕事は MessageEnvelope で各 Inbox に入り、各 teammate が独立に取り出します。"),
+      },
+      {
+        title: l("队友沿各自执行线推进工作", "Teammates advance work along their own lines", "teammate は各自の実行線で仕事を進める"),
+        description: l("团队价值来自长期分工。每个 teammate 都有自己的执行线，而不是每次都回到 Lead 重新推理一遍。", "Team value comes from durable specialization. Each teammate has its own execution line instead of bouncing all work back to the Lead.", "チーム価値は持続的な分業から生まれます。各 teammate は独自の実行線を持ちます。"),
+        activeNodes: ["inbox", "worker-run"],
+        activeRecords: ["team-member", "inbox-record"],
+        boundary: l("Lead 负责编排，不等于 Lead 亲自执行所有细节。", "The Lead orchestrates, but that does not mean it executes every detail itself.", "Lead は編成を担いますが、細部をすべて自分で実行するわけではありません。"),
+        writeBack: l("队友消费 inbox 后，在自己的执行线中推进工作，再产出回信或后续消息。", "After consuming inbox messages, teammates advance work on their own lines and then emit replies or follow-up messages.", "Inbox を消費した teammate は自分の実行線で仕事を進め、返信や次のメッセージを出します。"),
+      },
+      {
+        title: l("结果可以回给 Lead，也可以继续队友协作", "Results can return to the Lead or continue peer collaboration", "結果は Lead に戻ることも、隊友間で続くこともある"),
+        description: l("一旦团队身份和邮箱成立，协作就不再是单向的‘Lead 发任务，队友做完就结束’，而是可以持续往复。", "Once identity and mailboxes exist, collaboration stops being a single one-way delegation. It can continue as a durable exchange.", "identity と mailbox が成立すると、協調は一方向の委譲ではなく、継続的な往復になります。"),
+        activeNodes: ["worker-run", "reply", "lead"],
+        activeRecords: ["message-envelope", "team-member"],
+        boundary: l("团队系统的结束条件不只是‘任务完成’，还包括‘结果该回给谁继续处理’。", "A team flow is not finished only when work is done, but also when the result is routed back to the right owner.", "チームフローは『仕事完了』だけで終わらず、『結果を誰へ戻すか』も含みます。"),
+        writeBack: l("回信进入下一段编排，Lead 或别的 teammate 再根据结果决定后续协作。", "Replies enter the next orchestration step so the Lead or another teammate can decide what happens next.", "返信が次の編成段階に入り、Lead や別 teammate が次を決めます。"),
+      },
+    ],
+  },
+  s16: {
+    lanes: [
+      { id: "request", label: l("协议请求", "Protocol Request", "プロトコル要求"), note: l("重要协作先变成结构化请求。", "Important coordination becomes a structured request first.", "重要な協調はまず構造化要求になります。") },
+      { id: "record", label: l("请求记录", "Request Record", "要求レコード"), note: l("状态要能被持续追踪。", "State must stay traceable over time.", "状態を継続追跡できるようにします。") },
+      { id: "response", label: l("明确响应", "Explicit Response", "明示応答"), note: l("批准、拒绝、超时都要可见。", "Approve, reject, and timeout must stay visible.", "承認・拒否・タイムアウトを見えるようにします。") },
+      { id: "team", label: l("团队继续协作", "Team Continues", "チーム継続"), note: l("有了协议后，协作才真正稳。", "Shared protocols stabilize the team.", "共有 protocol がチームを安定させます。") },
+    ],
+    nodes: [
+      { id: "envelope", lane: "request", label: l("协议外壳", "Protocol Envelope", "protocol envelope"), detail: l("type / from / to / request_id / payload。", "type / from / to / request_id / payload.", "type / from / to / request_id / payload を持ちます。") },
+      { id: "request-id", lane: "request", label: l("request_id", "request_id", "request_id"), detail: l("把同一次请求和响应串起来。", "Correlates a request with its response.", "要求と応答を結びつけます。") },
+      { id: "request-record", lane: "record", label: l("落盘请求记录", "Persist Request Record", "request record 保存"), detail: l("状态必须 durable，不只在内存里。", "State must be durable, not just in memory.", "状態は memory だけでなく durable である必要があります。") },
+      { id: "pending", lane: "record", label: l("Pending 状态", "Pending State", "Pending 状態"), detail: l("等待响应期间状态也清楚可见。", "The waiting state stays visible too.", "待機中の状態も見えるようにします。") },
+      { id: "response", lane: "response", label: l("批准/拒绝/过期", "Approve / Reject / Expire", "承認 / 拒否 / 期限切れ"), detail: l("协议响应不是自由文本。", "Protocol responses are not free-form chat.", "protocol 応答は自由文ではありません。") },
+      { id: "update", lane: "team", label: l("更新请求状态", "Update Request State", "request 状態更新"), detail: l("团队依据结构化状态继续。", "The team continues based on structured status.", "チームは構造化状態に基づいて続行します。") },
+    ],
+    records: [
+      { id: "protocol-envelope", label: l("ProtocolEnvelope", "ProtocolEnvelope", "ProtocolEnvelope"), note: l("团队协议消息的统一壳。", "The shared envelope for protocol messages.", "protocol message の共通外殻です。") },
+      { id: "request-record", label: l("RequestRecord", "RequestRecord", "RequestRecord"), note: l("保存一次协议请求的整个生命周期。", "Stores the lifecycle of a protocol request.", "protocol request のライフサイクルを保存します。") },
+      { id: "request-id", label: l("request_id", "request_id", "request_id"), note: l("在请求和响应之间做关联。", "Correlates requests and responses.", "要求と応答を関連づけます。") },
+    ],
+    steps: [
+      {
+        title: l("重要协作先被包成协议请求", "Important coordination is wrapped into a protocol request first", "重要協調を先に protocol request に包む"),
+        description: l("协议章的第一护栏是：重要协作不再只靠自由文本，而是先拥有固定 envelope。", "The first guardrail of protocols is that important coordination no longer relies on free-form text. It gets a fixed envelope first.", "protocol 章の第一ガードレールは、重要協調が自由文ではなく固定 envelope を持つことです。"),
+        activeNodes: ["envelope", "request-id"],
+        activeRecords: ["protocol-envelope", "request-id"],
+        boundary: l("‘正式一点的聊天’还不是协议。协议要先有固定字段。", "“More formal chat” is still not a protocol. A protocol needs fixed fields first.", "『少し丁寧な会話』は protocol ではありません。固定フィールドが必要です。"),
+        writeBack: l("结构化请求带着 request_id 进入 durable request record。", "The structured request, together with its request_id, enters a durable request record.", "構造化要求は request_id とともに durable request record へ入ります。"),
+      },
+      {
+        title: l("请求状态必须落盘可追踪", "Request state must persist durably and remain traceable", "request 状態は durable に保存し追跡可能であるべき"),
+        description: l("真正稳定的团队协议，不是临时内存里的标记，而是 durable RequestRecord。", "Stable team protocols depend on durable RequestRecord, not temporary in-memory flags.", "安定した team protocol は一時 memory flag ではなく durable RequestRecord に依存します。"),
+        activeNodes: ["request-id", "request-record", "pending"],
+        activeRecords: ["request-record", "request-id"],
+        boundary: l("如果请求状态不 durable，审批、接力和恢复都会失去依据。", "If request state is not durable, approval, handoff, and recovery all lose their ground truth.", "request 状態が durable でないと、承認・引き継ぎ・回復の根拠が失われます。"),
+        writeBack: l("一旦 RequestRecord 进入 pending，系统就能跨轮次继续等待、催促或恢复。", "Once a RequestRecord enters pending, the system can wait, remind, or recover across turns.", "RequestRecord が pending に入ると、ターンをまたいで待機・催促・回復できます。"),
+      },
+      {
+        title: l("响应必须是显式状态，而不是自由聊天", "Responses must be explicit state transitions, not free chat", "応答は自由会話ではなく明示状態遷移にする"),
+        description: l("批准、拒绝、过期的核心价值在于状态迁移可见，而不是语言本身多好看。", "Approve, reject, and expire matter because the state transition is visible, not because the language sounds more formal.", "承認・拒否・期限切れの価値は、状態遷移が見えることであって、文面が丁寧なことではありません。"),
+        activeNodes: ["pending", "response"],
+        activeRecords: ["request-record"],
+        boundary: l("协议响应要优先表达状态，不要先沉迷于消息文案。", "Protocol responses must express state first; message wording comes second.", "protocol 応答はまず状態を表し、文面はその後です。"),
+        writeBack: l("响应会更新 RequestRecord，团队后续协作都以这个状态为依据。", "Responses update the RequestRecord, and later coordination uses that state as truth.", "応答は RequestRecord を更新し、以後の協調はその状態を真実として使います。"),
+      },
+      {
+        title: l("团队根据协议状态继续协作", "The team continues based on protocol state", "チームは protocol 状態に基づいて協調を続ける"),
+        description: l("协议的终点不是发出一条消息，而是团队后续每一步都能基于同一个请求状态继续行动。", "The endpoint of protocol is not sending a message. It is enabling every later coordination step to use the same request state.", "protocol の終点はメッセージ送信ではなく、その後の各段階が同じ request state に基づいて動けることです。"),
+        activeNodes: ["response", "update"],
+        activeRecords: ["request-record", "protocol-envelope"],
+        boundary: l("协议系统真正管理的是状态机，而不是聊天内容。", "The protocol system really manages a state machine, not the chat text itself.", "protocol system が本当に管理しているのは状態機械であり、会話文そのものではありません。"),
+        writeBack: l("更新后的 RequestRecord 成为团队下一轮协作、恢复和审批的共同依据。", "The updated RequestRecord becomes shared ground truth for later coordination, recovery, and approval.", "更新後の RequestRecord が次の協調・回復・承認の共通根拠になります。"),
+      },
+    ],
+  },
+  s17: {
+    lanes: [
+      { id: "idle", label: l("空闲巡检", "Idle Scan", "アイドル巡回"), note: l("自治从空闲时还能找工作开始。", "Autonomy begins when idle workers keep looking for work.", "自律は idle worker が仕事を探し続けるところから始まります。") },
+      { id: "claim", label: l("认领规则", "Claim Policy", "claim ルール"), note: l("不是任何工作都能自领。", "Not every task can be self-claimed.", "何でも self-claim できるわけではありません。") },
+      { id: "resume", label: l("恢复上下文", "Resume Context", "再開文脈"), note: l("认领后还要恢复正确身份。", "After claiming, the worker must resume the right identity and context.", "claim 後に正しい identity と文脈へ戻る必要があります。") },
+      { id: "return", label: l("状态回写", "State Write-back", "状態回写"), note: l("自治行为也要留下可见状态。", "Autonomous behavior still leaves visible state.", "自律動作も見える状態を残します。") },
+    ],
+    nodes: [
+      { id: "idle-worker", lane: "idle", label: l("空闲队友", "Idle Teammate", "idle teammate"), detail: l("没有新指令时也会继续检查。", "Keeps checking even without new instructions.", "新しい指示がなくても確認を続けます。") },
+      { id: "scan", lane: "idle", label: l("巡检 inbox / task board", "Scan Inbox / Task Board", "Inbox / Task Board を巡回"), detail: l("自治入口从这一步开始。", "Autonomy begins with this scan.", "自律の入口はこの巡回から始まります。") },
+      { id: "policy", lane: "claim", label: l("claim policy", "Claim Policy", "claim policy"), detail: l("按角色、资格和占用状态判断能否接活。", "Role, eligibility, and occupancy decide whether work can be claimed.", "役割・資格・占有状態で claim 可否を決めます。") },
+      { id: "claim", lane: "claim", label: l("认领工作", "Claim Work", "仕事を claim"), detail: l("自领工作时也要生成显式事件。", "Self-claiming should still generate explicit events.", "self-claim でも明示イベントを作ります。") },
+      { id: "resume", lane: "resume", label: l("恢复身份与上下文", "Resume Identity + Context", "identity と文脈を再開"), detail: l("恢复 mailbox、task、role-aware context。", "Restore mailbox, task, and role-aware context.", "mailbox・task・role-aware context を戻します。") },
+      { id: "execute", lane: "resume", label: l("继续执行", "Continue Execution", "実行継続"), detail: l("认领后沿正确车道继续工作。", "After claiming, work continues on the right lane.", "claim 後に正しい lane で仕事を続けます。") },
+      { id: "writeback", lane: "return", label: l("回写 claim / resume 状态", "Write Back Claim / Resume State", "claim / resume 状態を回写"), detail: l("自治过程也必须可见。", "Autonomous progress must stay visible too.", "自律過程も見える必要があります。") },
+    ],
+    records: [
+      { id: "claim-event", label: l("ClaimEvent", "ClaimEvent", "ClaimEvent"), note: l("记录谁认领了哪份工作。", "Records who claimed which work item.", "誰が何を claim したかを記録します。") },
+      { id: "runtime-task", label: l("RuntimeTaskState", "RuntimeTaskState", "RuntimeTaskState"), note: l("执行槽位仍然独立存在。", "The execution slot still exists independently.", "execution slot は引き続き独立しています。") },
+      { id: "identity-context", label: l("IdentityContext", "IdentityContext", "IdentityContext"), note: l("恢复时要重新注入角色化身份。", "Role identity must be re-injected when resuming.", "再開時に役割 identity を再注入します。") },
+    ],
+    steps: [
+      {
+        title: l("自治从空闲巡检开始", "Autonomy starts with idle scanning", "自律は idle scan から始まる"),
+        description: l("自治不是神秘地‘自己会想’，而是空闲队友在没有新指令时，仍会去巡检 inbox 和 task board。", "Autonomy is not mysterious self-thinking. It begins when idle teammates keep scanning inboxes and task boards even without new instructions.", "自律は神秘的な『自分で考える』ことではなく、新しい指示がなくても inbox と task board を見に行くことから始まります。"),
+        activeNodes: ["idle-worker", "scan"],
+        activeRecords: [],
+        boundary: l("没有 idle 巡检，自治就不会发生；系统只会在被点名时行动。", "Without idle scanning, autonomy never starts. The system acts only when explicitly called.", "idle scan がなければ自律は始まりません。"),
+        writeBack: l("巡检发现可处理线索后，控制流才进入 claim policy。", "Only after the scan finds candidate work does control move into the claim policy.", "巡回で候補仕事が見つかってから、claim policy へ進みます。"),
+      },
+      {
+        title: l("不是所有工作都能自领，先过 claim policy", "Not all work may be self-claimed; pass through claim policy first", "すべての仕事を self-claim できるわけではない"),
+        description: l("真正让自治稳定的，不是‘敢不敢动’，而是系统有没有定义清楚谁能认领什么。", "What makes autonomy stable is not boldness but a clear definition of who may claim what.", "自律を安定させるのは大胆さではなく、誰が何を claim できるかが明確なことです。"),
+        activeNodes: ["scan", "policy", "claim"],
+        activeRecords: ["claim-event"],
+        boundary: l("如果没有 claim policy，多 agent 很容易重复认领同一份工作。", "Without a claim policy, multiple agents may grab the same work repeatedly.", "claim policy がなければ複数 agent が同じ仕事を重複 claim しやすくなります。"),
+        writeBack: l("一旦 claim 成功，就写下 ClaimEvent，避免自治动作变成黑箱。", "Once a claim succeeds, write a ClaimEvent so autonomy does not become a black box.", "claim 成功時には ClaimEvent を残し、自律動作をブラックボックスにしません。"),
+      },
+      {
+        title: l("认领后先恢复正确身份，再继续执行", "After claiming, restore the right identity before execution", "claim 後に正しい identity を復元してから実行する"),
+        description: l("自治难点不在于开始执行，而在于恢复正确上下文。谁在执行、为什么轮到它，都必须重新注入。", "The hard part of autonomy is not starting execution, but restoring the right context: who is acting and why it is their turn.", "自律で難しいのは実行開始ではなく、正しい文脈を復元することです。"),
+        activeNodes: ["claim", "resume", "execute"],
+        activeRecords: ["claim-event", "identity-context", "runtime-task"],
+        boundary: l("自领工作不等于无上下文乱跑，resume context 才是自治可控的关键。", "Self-claiming does not mean acting without context. Resume context is what keeps autonomy under control.", "self-claim は文脈なし暴走ではありません。resume context が制御の鍵です。"),
+        writeBack: l("恢复后的身份和任务状态进入 RuntimeTaskState，执行线才真正继续。", "Restored identity and task state enter RuntimeTaskState before the execution lane continues.", "復元された identity と task 状態が RuntimeTaskState に入り、その後で実行線が続きます。"),
+      },
+      {
+        title: l("自治行为也必须留下可见状态", "Autonomous behavior must also leave visible state", "自律動作も見える状態を残す"),
+        description: l("自治不是偷偷干活。系统必须看得见 claim 了什么、恢复到了哪里、目前执行到哪一步。", "Autonomy is not hidden activity. The system must still see what was claimed, what context was restored, and how far execution progressed.", "自律は隠れた作業ではありません。何を claim し、どこまで復元し、どこまで進んだかが見える必要があります。"),
+        activeNodes: ["execute", "writeback", "idle-worker"],
+        activeRecords: ["claim-event", "runtime-task"],
+        boundary: l("如果自治过程没有状态回写，系统就很难调度、恢复和解释。", "Without write-back for autonomous progress, scheduling, recovery, and explanation all become harder.", "自律過程の回写がないと、調度・回復・説明が難しくなります。"),
+        writeBack: l("回写后的自治状态会在下一次 idle 巡检或团队协作中继续被读取。", "Once written back, autonomous state becomes readable by the next idle scan or later collaboration.", "回写された自律状態は次の idle scan や後続協調で再び読まれます。"),
+      },
+    ],
+  },
+  s18: {
+    lanes: [
+      { id: "task", label: l("任务目标", "Task Goal", "task 目標"), note: l("任务板继续描述做什么。", "The task board still describes what to do.", "task board は引き続き何をするかを記述します。") },
+      { id: "worktree", label: l("隔离车道", "Isolated Lane", "分離レーン"), note: l("worktree 管在哪做。", "The worktree decides where execution happens.", "worktree はどこで実行するかを管理します。") },
+      { id: "runtime", label: l("执行生命周期", "Execution Lifecycle", "実行ライフサイクル"), note: l("enter / run / closeout 都要显式。", "enter / run / closeout must stay explicit.", "enter / run / closeout を明示します。") },
+      { id: "return", label: l("收尾与事件", "Closeout + Events", "収束とイベント"), note: l("keep / remove 也是系统状态。", "keep / remove is also visible system state.", "keep / remove もシステム状態です。") },
+    ],
+    nodes: [
+      { id: "task-goal", lane: "task", label: l("目标任务", "Task Goal", "task goal"), detail: l("任务记录仍是目标层。", "The task record still owns the goal.", "task record は引き続き goal を持ちます。") },
+      { id: "assign", lane: "worktree", label: l("分配 worktree", "Assign Worktree", "worktree 割当"), detail: l("为任务分配隔离目录。", "Assign an isolated directory to the task.", "task に分離ディレクトリを割り当てます。") },
+      { id: "enter", lane: "runtime", label: l("进入车道", "Enter Lane", "レーンに入る"), detail: l("显式进入隔离目录工作。", "Explicitly enter the isolated directory.", "明示的に分離ディレクトリへ入ります。") },
+      { id: "run", lane: "runtime", label: l("隔离执行", "Run in Isolation", "分離実行"), detail: l("执行动作发生在独立车道。", "Execution happens inside the isolated lane.", "実行は独立レーンの中で起こります。") },
+      { id: "closeout", lane: "return", label: l("closeout", "closeout", "closeout"), detail: l("决定 keep / remove / summarize。", "Decides keep / remove / summarize.", "keep / remove / summarize を決めます。") },
+      { id: "event", lane: "return", label: l("车道事件", "Worktree Event", "worktree event"), detail: l("主系统要看见 create / enter / closeout。", "The main system should see create / enter / closeout.", "主システムは create / enter / closeout を見えるようにします。") },
+    ],
+    records: [
+      { id: "worktree-state", label: l("worktree_state", "worktree_state", "worktree_state"), note: l("记录当前车道归属和状态。", "Tracks the worktree lane and its state.", "worktree lane と状態を記録します。") },
+      { id: "last-worktree", label: l("last_worktree", "last_worktree", "last_worktree"), note: l("帮助系统知道任务最近在哪条车道上。", "Helps the system remember the last lane for a task.", "task が直近どの lane にいたかを覚えます。") },
+      { id: "closeout-record", label: l("closeout", "closeout", "closeout"), note: l("描述车道最终怎么收尾。", "Describes how the lane is closed out.", "lane をどう収束させるかを表します。") },
+    ],
+    steps: [
+      {
+        title: l("任务目标和执行车道先分层", "Separate the task goal from the execution lane first", "task goal と execution lane を先に分ける"),
+        description: l("这一章最重要的第一步是把‘做什么’和‘在哪做’拆开。任务板仍管目标，worktree 只管隔离执行环境。", "The first crucial step is to separate what should be done from where it runs. The task board still owns goals, while the worktree owns isolated execution space.", "最初の重要点は『何をするか』と『どこでやるか』を分けることです。"),
+        activeNodes: ["task-goal", "assign"],
+        activeRecords: ["worktree-state"],
+        boundary: l("worktree 不是另一种 task，它只是任务的隔离执行车道。", "A worktree is not another kind of task. It is the task's isolated execution lane.", "worktree は別種の task ではなく、task の分離実行レーンです。"),
+        writeBack: l("一旦分配了 worktree，任务就获得了明确的执行地点和 lane 状态。", "Once a worktree is assigned, the task gets a clear execution location and lane state.", "worktree が割り当てられると、task は明確な実行場所と lane 状態を持ちます。"),
+      },
+      {
+        title: l("进入隔离目录后再执行", "Enter the isolated directory before executing", "分離ディレクトリへ入ってから実行する"),
+        description: l("好的教学顺序要让读者看到：不是直接在目录里跑命令，而是先有 enter 动作，再有 run 动作。", "The right teaching order shows that you do not just run commands in a directory. You first enter the lane, then run inside it.", "正しい学習順序は『その場でコマンドを打つ』のではなく、『まず enter し、その後 run する』ことを見せます。"),
+        activeNodes: ["assign", "enter", "run"],
+        activeRecords: ["worktree-state", "last-worktree"],
+        boundary: l("enter 是显式生命周期动作，不要把它写成隐含前提。", "enter is an explicit lifecycle action, not an implicit assumption.", "enter は明示的な lifecycle action であり、暗黙前提ではありません。"),
+        writeBack: l("进入车道后，系统会更新 last_worktree，并在隔离目录里继续执行任务。", "After entering the lane, the system updates last_worktree and continues execution inside the isolated directory.", "lane へ入ったあと、last_worktree が更新され、その分離ディレクトリで実行が続きます。"),
+      },
+      {
+        title: l("执行结束后必须走 closeout", "After execution, closeout is mandatory", "実行後は必ず closeout を通る"),
+        description: l("Worktree 章节真正完整的地方不在 create，而在 closeout。keep、remove、summarize 都是显式收尾动作。", "What makes the worktree chapter complete is not creation but closeout. keep, remove, and summarize are all explicit end-of-lane actions.", "worktree 章が完全になるのは create ではなく closeout にあります。"),
+        activeNodes: ["run", "closeout"],
+        activeRecords: ["closeout-record", "worktree-state"],
+        boundary: l("不要把 worktree 用完就静默丢掉；收尾策略本身就是系统机制。", "Do not silently discard a worktree after use. Closeout strategy is itself a system mechanism.", "使い終わった worktree を黙って捨てないでください。closeout 戦略そのものがシステム機構です。"),
+        writeBack: l("closeout 决定这条 lane 是被保留、移除还是总结，并把结论写回主系统。", "closeout decides whether the lane is kept, removed, or summarized, and writes that conclusion back into the system.", "closeout は lane を keep / remove / summarize のどれにするかを決め、主システムへ書き戻します。"),
+      },
+      {
+        title: l("车道事件让主系统看见执行面发生了什么", "Worktree events let the main system see what happened in the lane", "worktree event で主システムが lane 内の出来事を見えるようにする"),
+        description: l("教学上要强调的是观察能力：主系统不仅看到结果，还看到 create、enter、closeout 等生命周期事件。", "The teaching emphasis here is observability. The main system should see not only the final result, but lifecycle events like create, enter, and closeout.", "ここで強調したいのは観測可能性です。主システムは最終結果だけでなく create・enter・closeout も見えるべきです。"),
+        activeNodes: ["closeout", "event", "task-goal"],
+        activeRecords: ["closeout-record", "worktree-state", "last-worktree"],
+        boundary: l("没有 lane 事件，系统就只能看到‘做完了’，却不知道执行车道里发生过什么。", "Without lane events, the system only sees “done” and misses what happened inside the execution lane.", "lane event がないと、システムは『終わった』しか見えず、中で何が起きたか分かりません。"),
+        writeBack: l("closeout 和 worktree event 一起把隔离车道的生命周期重新接回任务主线。", "closeout and worktree events reconnect the lane lifecycle back into the task mainline.", "closeout と worktree event がレーンのライフサイクルを task 主線へ戻します。"),
+      },
+    ],
+  },
+  s19: {
+    lanes: [
+      { id: "request", label: l("能力请求", "Capability Request", "capability 要求"), note: l("系统先提出‘需要什么能力’。", "The system first asks what capability it needs.", "システムはまず『どんな capability が必要か』を出します。") },
+      { id: "router", label: l("统一路由", "Unified Router", "統一路由"), note: l("本地工具、插件和 MCP 在这里汇合。", "Native tools, plugins, and MCP converge here.", "native tool・plugin・MCP がここで合流します。") },
+      { id: "execution", label: l("能力执行面", "Capability Execution", "capability 実行面"), note: l("本地与外部能力都能被调起。", "Both local and external capabilities can be invoked.", "ローカル能力も外部能力も呼び出せます。") },
+      { id: "return", label: l("统一回流", "Unified Write-back", "統一回流"), note: l("结果最终要标准化回到主循环。", "Results must be normalized back into the main loop.", "結果は最終的に標準化され主ループへ戻ります。") },
+    ],
+    nodes: [
+      { id: "capability-request", lane: "request", label: l("能力请求", "Capability Request", "capability request"), detail: l("不是先问它来自哪里，而是先问需要什么能力。", "Ask what capability is needed before asking where it comes from.", "どこから来たかより先に、何の capability が必要かを問います。") },
+      { id: "catalog", lane: "router", label: l("能力目录", "Capability Catalog", "capability catalog"), detail: l("整理 native / plugin / MCP 能力视图。", "Unify native, plugin, and MCP capabilities in one catalog.", "native / plugin / MCP を 1 つの catalog にまとめます。") },
+      { id: "policy", lane: "router", label: l("策略与授权", "Policy + Permission", "ポリシーと権限"), detail: l("外部能力也要过同一控制面。", "External capabilities still pass the same control plane.", "外部 capability も同じ control plane を通ります。") },
+      { id: "native", lane: "execution", label: l("本地工具", "Native Tool", "native tool"), detail: l("本地能力是一种 capability。", "Native tools are one kind of capability.", "native tool も capability の一種です。") },
+      { id: "plugin", lane: "execution", label: l("插件能力", "Plugin Capability", "plugin capability"), detail: l("插件把额外能力挂回系统。", "Plugins attach extra capability back into the system.", "plugin は追加 capability をシステムへ戻します。") },
+      { id: "mcp", lane: "execution", label: l("MCP Server", "MCP Server", "MCP Server"), detail: l("远程 server 也能像 tool 一样被路由。", "Remote servers can be routed like tools.", "遠隔 server も tool のように route できます。") },
+      { id: "normalize", lane: "return", label: l("标准化结果", "Normalize Result", "結果標準化"), detail: l("不同来源的结果都要转成统一格式。", "Results from different sources must become one common format.", "出所の違う結果を共通形式に変えます。") },
+      { id: "tool-result", lane: "return", label: l("回写主循环", "Write Back to Loop", "主ループへ回写"), detail: l("最后回到统一 tool_result / event 通道。", "Everything returns through the same tool_result / event bus.", "最後は同じ tool_result / event bus に戻ります。") },
+    ],
+    records: [
+      { id: "capability-spec", label: l("CapabilitySpec", "CapabilitySpec", "CapabilitySpec"), note: l("把本地与外部能力抽象到同一视图。", "Abstracts local and external capabilities into one view.", "ローカル能力と外部能力を同じ視点へ抽象化します。") },
+      { id: "permission-decision", label: l("PermissionDecision", "PermissionDecision", "PermissionDecision"), note: l("外部能力仍然共享权限层。", "External capabilities still share the permission plane.", "外部 capability も permission plane を共有します。") },
+      { id: "tool-result", label: l("tool_result / event", "tool_result / event", "tool_result / event"), note: l("最后统一回流的格式。", "The unified return format.", "最終的な統一回流形式です。") },
+    ],
+    steps: [
+      {
+        title: l("先从‘需要什么能力’而不是‘它来自哪里’开始", "Start from the needed capability, not its origin", "必要な capability から始め、出所から始めない"),
+        description: l("MCP 与 Plugin 章节最重要的第一步，是把注意力放在 capability request，而不是 transport 细节。", "The first important move in the MCP and plugin chapter is to focus on capability requests, not transport details.", "MCP と plugin 章で最初に重要なのは transport 詳細ではなく capability request に注目することです。"),
+        activeNodes: ["capability-request", "catalog"],
+        activeRecords: ["capability-spec"],
+        boundary: l("教学主线应先坚持 tools-first / capability-first，而不是先掉进协议细节。", "The teaching mainline should stay tools-first / capability-first before diving into protocol detail.", "学習主線は protocol 詳細より先に tools-first / capability-first を保つべきです。"),
+        writeBack: l("能力请求进入统一 catalog，系统才知道有哪些 native / plugin / MCP 路由可选。", "The capability request enters a unified catalog so the system can see native, plugin, and MCP routes together.", "capability request が統一 catalog へ入り、native / plugin / MCP の選択肢が見えるようになります。"),
+      },
+      {
+        title: l("所有能力都先过统一路由与策略层", "All capabilities pass through one router and policy layer first", "すべての capability を統一路由とポリシー層へ通す"),
+        description: l("MCP 不是例外外挂。只要它是系统能力，就应该像本地工具一样被发现、选择、授权。", "MCP is not a special exception. If it is a system capability, it should be discovered, selected, and authorized like any native tool.", "MCP は特例ではありません。システム capability なら native tool と同じように発見・選択・認可されます。"),
+        activeNodes: ["catalog", "policy"],
+        activeRecords: ["capability-spec", "permission-decision"],
+        boundary: l("外部能力不能绕过权限与路由层，否则整套控制面会断裂。", "External capabilities must not bypass routing and permissions or the control plane breaks apart.", "外部 capability が routing と permission を迂回すると control plane が壊れます。"),
+        writeBack: l("通过策略后，路由器才决定是走 native tool、plugin 还是 MCP server。", "Only after policy approval does the router choose between native, plugin, or MCP execution.", "ポリシー通過後に router が native / plugin / MCP のどれへ行くか決めます。"),
+      },
+      {
+        title: l("本地工具、插件、MCP 只是不同执行来源", "Native tools, plugins, and MCP are different execution sources", "native tool・plugin・MCP は実行元が違うだけ"),
+        description: l("一旦进入能力执行面，教学重点就变成：来源不同，但都是被同一 capability bus 调起。", "Once you enter capability execution, the teaching focus becomes: the sources differ, but the same capability bus invokes them all.", "capability 実行面に入ると、重要なのは『出所は違っても同じ bus で呼ばれる』ことです。"),
+        activeNodes: ["policy", "native", "plugin", "mcp"],
+        activeRecords: ["capability-spec"],
+        boundary: l("不要把 plugin 或 MCP 讲成孤立外挂；它们只是统一能力总线上的不同端点。", "Do not teach plugins or MCP as isolated add-ons. They are different endpoints on one shared capability bus.", "plugin や MCP を孤立した追加物として教えないでください。共有 capability bus 上の別 endpoint です。"),
+        writeBack: l("无论走哪条执行来源，结果都还需要再标准化后才能回到主循环。", "No matter which execution source is used, the result still must be normalized before it re-enters the main loop.", "どの実行元を通っても、結果は標準化されてから主ループへ戻ります。"),
+      },
+      {
+        title: l("最终仍回到统一结果总线", "Everything still returns through one result bus", "最終的には同じ結果 bus へ戻る"),
+        description: l("这章真正让系统完整的地方，是外部能力虽然多源，但最后仍然回到统一 tool_result / event 总线。", "The chapter becomes complete when multi-source external capability still returns through one unified tool_result / event bus.", "この章が完成するのは、多元の外部 capability が最終的に同じ tool_result / event bus へ戻るときです。"),
+        activeNodes: ["native", "plugin", "mcp", "normalize", "tool-result"],
+        activeRecords: ["permission-decision", "tool-result"],
+        boundary: l("如果不同来源的结果不能统一回流，主循环就会被迫理解很多套执行语义。", "If results from different sources cannot be normalized, the main loop must understand too many execution dialects.", "出所ごとに結果がバラバラだと、主ループが多くの実行方言を理解しなければなりません。"),
+        writeBack: l("标准化后的 tool_result / event 把外部能力重新接回原有 agent 主线。", "Normalized tool_result / event reconnects external capability back into the existing agent mainline.", "標準化された tool_result / event が外部 capability を既存の agent 主線へ戻します。"),
+      },
+    ],
+  },
+};
+
+export function hasLateStageTeachingMap(version: string): version is LateStageVersion {
+  return version in SCENARIOS;
+}
+
+export function LateStageTeachingMap({ version }: { version: LateStageVersion }) {
+  const locale = useLocale();
+  const scenario = SCENARIOS[version];
+  const meta = VERSION_META[version];
+
+  if (!scenario || !meta) return null;
+
+  const accent = ACCENT_CLASSES[meta.layer];
+  const {
+    currentStep,
+    totalSteps,
+    next,
+    prev,
+    reset,
+    isPlaying,
+    toggleAutoPlay,
+  } = useSteppedVisualization({
+    totalSteps: scenario.steps.length,
+    autoPlayInterval: 2600,
+  });
+
+  const step = scenario.steps[currentStep];
+  const nodeMap = new Map(scenario.nodes.map((node) => [node.id, node]));
+  const activeNodes = new Set(step.activeNodes);
+  const activeRecords = new Set(step.activeRecords);
+
+  return (
+    <div
+      className={`overflow-hidden rounded-[28px] border border-zinc-200/80 bg-[var(--color-bg)] shadow-sm ring-1 dark:border-zinc-800/80 ${accent.ring}`}
+    >
+      <div className={`relative overflow-hidden bg-gradient-to-br ${accent.tint} px-5 py-6 sm:px-6`}>
+        <div className="absolute right-[-50px] top-[-46px] h-40 w-40 rounded-full bg-white/35 blur-3xl dark:bg-white/5" />
+        <div className="relative space-y-3">
+          <span className={`inline-flex items-center rounded-full border px-3 py-1 text-[11px] font-semibold uppercase tracking-[0.18em] ${accent.pill}`}>
+            {pick(locale, UI_TEXT.label)}
+          </span>
+          <div>
+            <h3 className="text-xl font-semibold tracking-tight text-zinc-950 dark:text-zinc-50">
+              {pick(locale, UI_TEXT.title)}
+            </h3>
+            <p className="mt-2 max-w-4xl text-sm leading-7 text-zinc-700 dark:text-zinc-300">
+              {pick(locale, UI_TEXT.body)}
+            </p>
+          </div>
+        </div>
+      </div>
+
+      <div className="space-y-6 px-5 py-5 sm:px-6">
+        <StepControls
+          currentStep={currentStep}
+          totalSteps={totalSteps}
+          onPrev={prev}
+          onNext={next}
+          onReset={reset}
+          isPlaying={isPlaying}
+          onToggleAutoPlay={toggleAutoPlay}
+          stepTitle={pick(locale, step.title)}
+          stepDescription={pick(locale, step.description)}
+        />
+
+        <div className="grid gap-4 xl:grid-cols-[minmax(0,1.5fr)_minmax(320px,0.95fr)]">
+          <section className="rounded-[24px] border border-zinc-200/80 bg-white/90 p-4 dark:border-zinc-800 dark:bg-zinc-950/60">
+            <div className="mb-4 flex items-center justify-between gap-3">
+              <div>
+                <p className="text-xs uppercase tracking-[0.18em] text-zinc-400">
+                  {pick(locale, UI_TEXT.systemLanes)}
+                </p>
+              </div>
+              <div className={`rounded-full px-3 py-1 text-xs font-medium ${accent.soft}`}>
+                {version.toUpperCase()}
+              </div>
+            </div>
+
+            <div className="space-y-3">
+              {scenario.lanes.map((lane, laneIndex) => {
+                const laneNodes = scenario.nodes.filter((node) => node.lane === lane.id);
+                return (
+                  <motion.div
+                    key={lane.id}
+                    initial={{ opacity: 0, y: 12 }}
+                    animate={{ opacity: 1, y: 0 }}
+                    transition={{ duration: 0.28, delay: laneIndex * 0.05 }}
+                    className={`rounded-[22px] border bg-zinc-50/80 p-3 dark:bg-zinc-900/80 ${accent.border}`}
+                  >
+                    <div className="grid gap-3 lg:grid-cols-[152px_minmax(0,1fr)]">
+                      <div className="rounded-2xl border border-dashed border-zinc-300/80 bg-white/80 px-3 py-3 dark:border-zinc-700 dark:bg-zinc-950/60">
+                        <div className="text-sm font-semibold text-zinc-900 dark:text-zinc-100">
+                          {pick(locale, lane.label)}
+                        </div>
+                        <p className="mt-1 text-xs leading-5 text-zinc-500 dark:text-zinc-400">
+                          {pick(locale, lane.note)}
+                        </p>
+                      </div>
+
+                      <div className="flex flex-wrap gap-3">
+                        {laneNodes.map((node, nodeIndex) => {
+                          const isActive = activeNodes.has(node.id);
+                          return (
+                            <motion.div
+                              key={node.id}
+                              initial={{ opacity: 0, scale: 0.96 }}
+                              animate={{
+                                opacity: 1,
+                                scale: isActive ? 1.02 : 1,
+                                y: isActive ? -1 : 0,
+                              }}
+                              transition={{ duration: 0.24, delay: nodeIndex * 0.04 }}
+                              className={`min-w-[172px] flex-1 rounded-2xl border px-4 py-3 shadow-sm transition-colors ${
+                                isActive
+                                  ? `${accent.pill} ring-1 ${accent.ring}`
+                                  : "border-zinc-200/80 bg-white text-zinc-700 dark:border-zinc-800 dark:bg-zinc-950/70 dark:text-zinc-300"
+                              }`}
+                            >
+                              <div className="text-sm font-semibold">
+                                {pick(locale, node.label)}
+                              </div>
+                              <p className="mt-1 text-xs leading-5 opacity-85">
+                                {pick(locale, node.detail)}
+                              </p>
+                            </motion.div>
+                          );
+                        })}
+                      </div>
+                    </div>
+                  </motion.div>
+                );
+              })}
+            </div>
+          </section>
+
+          <section className="space-y-3">
+            <div className="rounded-[22px] border border-zinc-200/80 bg-white/90 p-4 dark:border-zinc-800 dark:bg-zinc-950/60">
+              <p className="text-xs uppercase tracking-[0.18em] text-zinc-400">
+                {pick(locale, UI_TEXT.activePath)}
+              </p>
+              <div className="mt-3 flex flex-wrap items-center gap-2">
+                {step.activeNodes.map((nodeId, index) => {
+                  const node = nodeMap.get(nodeId);
+                  if (!node) return null;
+                  return (
+                    <div key={nodeId} className="contents">
+                      <motion.div
+                        initial={{ opacity: 0, scale: 0.95 }}
+                        animate={{ opacity: 1, scale: 1 }}
+                        transition={{ duration: 0.24, delay: index * 0.05 }}
+                        className={`inline-flex items-center rounded-full border px-3 py-2 text-xs font-medium shadow-sm ${accent.pill}`}
+                      >
+                        {pick(locale, node.label)}
+                      </motion.div>
+                      {index < step.activeNodes.length - 1 && (
+                        <span className="text-zinc-300 dark:text-zinc-600">-&gt;</span>
+                      )}
+                    </div>
+                  );
+                })}
+              </div>
+            </div>
+
+            <div className="rounded-[22px] border border-zinc-200/80 bg-white/90 p-4 dark:border-zinc-800 dark:bg-zinc-950/60">
+              <p className="text-xs uppercase tracking-[0.18em] text-zinc-400">
+                {pick(locale, UI_TEXT.activeRecords)}
+              </p>
+              <div className="mt-3 space-y-2">
+                {scenario.records.map((record) => {
+                  const isActive = activeRecords.has(record.id);
+                  return (
+                    <div
+                      key={record.id}
+                      className={`rounded-2xl border px-3 py-3 transition-colors ${
+                        isActive
+                          ? `${accent.pill} ring-1 ${accent.ring}`
+                          : "border-zinc-200/80 bg-zinc-50/80 dark:border-zinc-800 dark:bg-zinc-900/70"
+                      }`}
+                    >
+                      <div className="flex items-center justify-between gap-3">
+                        <div className="text-sm font-semibold text-zinc-900 dark:text-zinc-100">
+                          {pick(locale, record.label)}
+                        </div>
+                        {!isActive && (
+                          <span className="text-[11px] text-zinc-400">
+                            {pick(locale, UI_TEXT.inactiveRecord)}
+                          </span>
+                        )}
+                      </div>
+                      <p className="mt-1 text-xs leading-5 text-zinc-500 dark:text-zinc-400">
+                        {pick(locale, record.note)}
+                      </p>
+                    </div>
+                  );
+                })}
+              </div>
+            </div>
+
+            <div className={`rounded-[22px] border bg-zinc-50/90 p-4 dark:bg-zinc-900/70 ${accent.border}`}>
+              <p className="text-xs uppercase tracking-[0.18em] text-zinc-400">
+                {pick(locale, UI_TEXT.boundary)}
+              </p>
+              <p className="mt-2 text-sm leading-6 text-zinc-700 dark:text-zinc-300">
+                {pick(locale, step.boundary)}
+              </p>
+            </div>
+
+            <div className={`rounded-[22px] border bg-zinc-50/90 p-4 dark:bg-zinc-900/70 ${accent.border}`}>
+              <p className="text-xs uppercase tracking-[0.18em] text-zinc-400">
+                {pick(locale, UI_TEXT.writeBack)}
+              </p>
+              <p className="mt-2 text-sm leading-6 text-zinc-700 dark:text-zinc-300">
+                {pick(locale, step.writeBack)}
+              </p>
+            </div>
+          </section>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/web/src/components/visualizations/s01-agent-loop.tsx b/web/src/components/visualizations/s01-agent-loop.tsx
index 9e911889e..d56bcb88d 100644
--- a/web/src/components/visualizations/s01-agent-loop.tsx
+++ b/web/src/components/visualizations/s01-agent-loop.tsx
@@ -4,8 +4,7 @@ import { motion, AnimatePresence } from "framer-motion";
 import { useSteppedVisualization } from "@/hooks/useSteppedVisualization";
 import { StepControls } from "@/components/visualizations/shared/step-controls";
 import { useSvgPalette } from "@/hooks/useDarkMode";
-
-// -- Flowchart node definitions --
+import { useLocale } from "@/lib/i18n";
 
 interface FlowNode {
   id: string;
@@ -17,22 +16,30 @@ interface FlowNode {
   type: "rect" | "diamond";
 }
 
-const NODES: FlowNode[] = [
-  { id: "start", label: "Start", x: 160, y: 30, w: 120, h: 40, type: "rect" },
-  { id: "api_call", label: "API Call", x: 160, y: 110, w: 120, h: 40, type: "rect" },
-  { id: "check", label: "stop_reason?", x: 160, y: 200, w: 140, h: 50, type: "diamond" },
-  { id: "execute", label: "Execute Tool", x: 160, y: 300, w: 120, h: 40, type: "rect" },
-  { id: "append", label: "Append Result", x: 160, y: 380, w: 120, h: 40, type: "rect" },
-  { id: "end", label: "Break / Done", x: 380, y: 200, w: 120, h: 40, type: "rect" },
-];
-
-// Edges between nodes (SVG path data computed inline)
 interface FlowEdge {
   from: string;
   to: string;
   label?: string;
 }
 
+interface MessageBlock {
+  role: string;
+  detail: string;
+  colorClass: string;
+}
+
+type SupportedLocale = "zh" | "en" | "ja";
+type NodeId = "start" | "api_call" | "check" | "execute" | "append" | "end";
+
+const BASE_NODES: Array<Omit<FlowNode, "label">> = [
+  { id: "start", x: 160, y: 30, w: 120, h: 40, type: "rect" },
+  { id: "api_call", x: 160, y: 110, w: 120, h: 40, type: "rect" },
+  { id: "check", x: 160, y: 200, w: 140, h: 50, type: "diamond" },
+  { id: "execute", x: 160, y: 300, w: 120, h: 40, type: "rect" },
+  { id: "append", x: 160, y: 380, w: 120, h: 40, type: "rect" },
+  { id: "end", x: 380, y: 200, w: 120, h: 40, type: "rect" },
+];
+
 const EDGES: FlowEdge[] = [
   { from: "start", to: "api_call" },
   { from: "api_call", to: "check" },
@@ -42,7 +49,6 @@ const EDGES: FlowEdge[] = [
   { from: "check", to: "end", label: "end_turn" },
 ];
 
-// Which nodes light up at each step
 const ACTIVE_NODES_PER_STEP: string[][] = [
   [],
   ["start"],
@@ -53,7 +59,6 @@ const ACTIVE_NODES_PER_STEP: string[][] = [
   ["check", "end"],
 ];
 
-// Which edges highlight at each step
 const ACTIVE_EDGES_PER_STEP: string[][] = [
   [],
   [],
@@ -64,50 +69,192 @@ const ACTIVE_EDGES_PER_STEP: string[][] = [
   ["api_call->check", "check->end"],
 ];
 
-// -- Message blocks --
-
-interface MessageBlock {
-  role: string;
-  detail: string;
-  colorClass: string;
+const COPY: Record<
+  SupportedLocale,
+  {
+    title: string;
+    loopLabel: string;
+    emptyLabel: string;
+    lengthLabel: string;
+    iterationLabel: string;
+    nodeLabels: Record<NodeId, string>;
+    messagesPerStep: (MessageBlock | null)[][];
+    stepInfo: { title: string; desc: string }[];
+  }
+> = {
+  zh: {
+    title: "Agent 主循环",
+    loopLabel: 'while (stop_reason === "tool_use")',
+    emptyLabel: "[ 空 ]",
+    lengthLabel: "长度",
+    iterationLabel: "第 2 轮",
+    nodeLabels: {
+      start: "开始",
+      api_call: "调用模型",
+      check: "stop_reason?",
+      execute: "执行工具",
+      append: "追加结果",
+      end: "结束 / 完成",
+    },
+    messagesPerStep: [
+      [],
+      [{ role: "user", detail: "修复登录 bug", colorClass: "bg-blue-500 dark:bg-blue-600" }],
+      [],
+      [{ role: "assistant", detail: "tool_use: read_file", colorClass: "bg-zinc-600 dark:bg-zinc-500" }],
+      [{ role: "tool_result", detail: "auth.ts 内容...", colorClass: "bg-emerald-500 dark:bg-emerald-600" }],
+      [
+        { role: "assistant", detail: "tool_use: edit_file", colorClass: "bg-zinc-600 dark:bg-zinc-500" },
+        { role: "tool_result", detail: "文件已更新", colorClass: "bg-emerald-500 dark:bg-emerald-600" },
+      ],
+      [{ role: "assistant", detail: "end_turn: 完成！", colorClass: "bg-purple-500 dark:bg-purple-600" }],
+    ],
+    stepInfo: [
+      {
+        title: "主循环本身",
+        desc: "每个 agent 的核心都是一个 while 循环：不断调用模型，直到它明确表示这一轮该结束。",
+      },
+      {
+        title: "用户输入",
+        desc: "循环从用户消息进入 messages[] 开始。",
+      },
+      {
+        title: "调用模型",
+        desc: "把当前消息历史整体发给模型，让它基于已有上下文决定下一步。",
+      },
+      {
+        title: "stop_reason: tool_use",
+        desc: "模型想调用工具，所以主循环不能结束，而要继续进入执行分支。",
+      },
+      {
+        title: "执行并回写",
+        desc: "执行工具，把结果追加回 messages[]，再喂给下一轮推理。",
+      },
+      {
+        title: "再跑一轮",
+        desc: "还是同一条代码路径，只是现在模型已经能看到刚才的真实工具结果。",
+      },
+      {
+        title: "stop_reason: end_turn",
+        desc: "模型这轮已经完成，循环退出。这就是最小 agent 的完整闭环。",
+      },
+    ],
+  },
+  en: {
+    title: "The Agent While-Loop",
+    loopLabel: 'while (stop_reason === "tool_use")',
+    emptyLabel: "[ empty ]",
+    lengthLabel: "length",
+    iterationLabel: "iter #2",
+    nodeLabels: {
+      start: "Start",
+      api_call: "API Call",
+      check: "stop_reason?",
+      execute: "Execute Tool",
+      append: "Append Result",
+      end: "Break / Done",
+    },
+    messagesPerStep: [
+      [],
+      [{ role: "user", detail: "Fix the login bug", colorClass: "bg-blue-500 dark:bg-blue-600" }],
+      [],
+      [{ role: "assistant", detail: "tool_use: read_file", colorClass: "bg-zinc-600 dark:bg-zinc-500" }],
+      [{ role: "tool_result", detail: "auth.ts contents...", colorClass: "bg-emerald-500 dark:bg-emerald-600" }],
+      [
+        { role: "assistant", detail: "tool_use: edit_file", colorClass: "bg-zinc-600 dark:bg-zinc-500" },
+        { role: "tool_result", detail: "file updated", colorClass: "bg-emerald-500 dark:bg-emerald-600" },
+      ],
+      [{ role: "assistant", detail: "end_turn: Done!", colorClass: "bg-purple-500 dark:bg-purple-600" }],
+    ],
+    stepInfo: [
+      { title: "The While Loop", desc: "Every agent is a while loop that keeps calling the model until it says 'stop'." },
+      { title: "User Input", desc: "The loop starts when the user sends a message." },
+      { title: "Call the Model", desc: "Send all messages to the LLM. It sees everything and decides what to do." },
+      { title: "stop_reason: tool_use", desc: "The model wants to use a tool. The loop continues." },
+      { title: "Execute & Append", desc: "Run the tool, append the result to messages[]. Feed it back." },
+      { title: "Loop Again", desc: "Same code path, second iteration. The model decides to edit a file." },
+      { title: "stop_reason: end_turn", desc: "The model is done. Loop exits. That's the entire agent." },
+    ],
+  },
+  ja: {
+    title: "Agent 主ループ",
+    loopLabel: 'while (stop_reason === "tool_use")',
+    emptyLabel: "[ 空 ]",
+    lengthLabel: "長さ",
+    iterationLabel: "2 周目",
+    nodeLabels: {
+      start: "開始",
+      api_call: "API 呼び出し",
+      check: "stop_reason?",
+      execute: "Tool 実行",
+      append: "結果を追加",
+      end: "終了 / 完了",
+    },
+    messagesPerStep: [
+      [],
+      [{ role: "user", detail: "ログイン bug を直す", colorClass: "bg-blue-500 dark:bg-blue-600" }],
+      [],
+      [{ role: "assistant", detail: "tool_use: read_file", colorClass: "bg-zinc-600 dark:bg-zinc-500" }],
+      [{ role: "tool_result", detail: "auth.ts の内容...", colorClass: "bg-emerald-500 dark:bg-emerald-600" }],
+      [
+        { role: "assistant", detail: "tool_use: edit_file", colorClass: "bg-zinc-600 dark:bg-zinc-500" },
+        { role: "tool_result", detail: "ファイルを更新", colorClass: "bg-emerald-500 dark:bg-emerald-600" },
+      ],
+      [{ role: "assistant", detail: "end_turn: 完了！", colorClass: "bg-purple-500 dark:bg-purple-600" }],
+    ],
+    stepInfo: [
+      {
+        title: "主ループそのもの",
+        desc: "すべての agent の核は while ループです。モデルが明示的に止まるまで呼び続けます。",
+      },
+      {
+        title: "ユーザー入力",
+        desc: "ループはユーザーのメッセージが messages[] に入るところから始まります。",
+      },
+      {
+        title: "モデル呼び出し",
+        desc: "現在のメッセージ履歴をまとめてモデルへ渡し、次に何をするか判断させます。",
+      },
+      {
+        title: "stop_reason: tool_use",
+        desc: "モデルは tool を使いたいので、ループは終了せず実行分岐へ進みます。",
+      },
+      {
+        title: "実行して回写",
+        desc: "tool を実行し、その結果を messages[] に追加して次の推論へ戻します。",
+      },
+      {
+        title: "もう一度回る",
+        desc: "コード経路は同じですが、今回は直前の実行結果を見た上でモデルが次を決めます。",
+      },
+      {
+        title: "stop_reason: end_turn",
+        desc: "モデルはこのターンを終えました。ループが抜けて、最小 agent 閉ループが完成します。",
+      },
+    ],
+  },
+};
+
+function normalizeLocale(locale: string): SupportedLocale {
+  if (locale === "zh" || locale === "ja") return locale;
+  return "en";
 }
 
-const MESSAGES_PER_STEP: (MessageBlock | null)[][] = [
-  [],
-  [{ role: "user", detail: "Fix the login bug", colorClass: "bg-blue-500 dark:bg-blue-600" }],
-  [],
-  [{ role: "assistant", detail: "tool_use: read_file", colorClass: "bg-zinc-600 dark:bg-zinc-500" }],
-  [{ role: "tool_result", detail: "auth.ts contents...", colorClass: "bg-emerald-500 dark:bg-emerald-600" }],
-  [
-    { role: "assistant", detail: "tool_use: edit_file", colorClass: "bg-zinc-600 dark:bg-zinc-500" },
-    { role: "tool_result", detail: "file updated", colorClass: "bg-emerald-500 dark:bg-emerald-600" },
-  ],
-  [{ role: "assistant", detail: "end_turn: Done!", colorClass: "bg-purple-500 dark:bg-purple-600" }],
-];
-
-// -- Step annotations --
-
-const STEP_INFO = [
-  { title: "The While Loop", desc: "Every agent is a while loop that keeps calling the model until it says 'stop'." },
-  { title: "User Input", desc: "The loop starts when the user sends a message." },
-  { title: "Call the Model", desc: "Send all messages to the LLM. It sees everything and decides what to do." },
-  { title: "stop_reason: tool_use", desc: "The model wants to use a tool. The loop continues." },
-  { title: "Execute & Append", desc: "Run the tool, append the result to messages[]. Feed it back." },
-  { title: "Loop Again", desc: "Same code path, second iteration. The model decides to edit a file." },
-  { title: "stop_reason: end_turn", desc: "The model is done. Loop exits. That's the entire agent." },
-];
-
-// -- Helpers --
+function getNodes(locale: SupportedLocale): FlowNode[] {
+  const labels = COPY[locale].nodeLabels;
+  return BASE_NODES.map((node) => ({
+    ...node,
+    label: labels[node.id as NodeId],
+  }));
+}
 
-function getNode(id: string): FlowNode {
-  return NODES.find((n) => n.id === id)!;
+function getNode(nodes: FlowNode[], id: string): FlowNode {
+  return nodes.find((node) => node.id === id)!;
 }
 
-function edgePath(fromId: string, toId: string): string {
-  const from = getNode(fromId);
-  const to = getNode(toId);
+function edgePath(nodes: FlowNode[], fromId: string, toId: string): string {
+  const from = getNode(nodes, fromId);
+  const to = getNode(nodes, toId);
 
-  // Loop-back: append -> api_call (goes to the left side and back up)
   if (fromId === "append" && toId === "api_call") {
     const startX = from.x - from.w / 2;
     const startY = from.y;
@@ -116,7 +263,6 @@ function edgePath(fromId: string, toId: string): string {
     return `M ${startX} ${startY} L ${startX - 50} ${startY} L ${endX - 50} ${endY} L ${endX} ${endY}`;
   }
 
-  // Horizontal: check -> end
   if (fromId === "check" && toId === "end") {
     const startX = from.x + from.w / 2;
     const startY = from.y;
@@ -125,7 +271,6 @@ function edgePath(fromId: string, toId: string): string {
     return `M ${startX} ${startY} L ${endX} ${endY}`;
   }
 
-  // Vertical (default)
   const startX = from.x;
   const startY = from.y + from.h / 2;
   const endX = to.x;
@@ -133,9 +278,10 @@ function edgePath(fromId: string, toId: string): string {
   return `M ${startX} ${startY} L ${endX} ${endY}`;
 }
 
-// -- Component --
-
 export default function AgentLoop({ title }: { title?: string }) {
+  const locale = normalizeLocale(useLocale());
+  const copy = COPY[locale];
+  const nodes = getNodes(locale);
   const {
     currentStep,
     totalSteps,
@@ -149,29 +295,27 @@ export default function AgentLoop({ title }: { title?: string }) {
   const palette = useSvgPalette();
   const activeNodes = ACTIVE_NODES_PER_STEP[currentStep];
   const activeEdges = ACTIVE_EDGES_PER_STEP[currentStep];
-
-  // Build accumulated messages up to the current step
   const visibleMessages: MessageBlock[] = [];
-  for (let s = 0; s <= currentStep; s++) {
-    for (const msg of MESSAGES_PER_STEP[s]) {
-      if (msg) visibleMessages.push(msg);
+
+  for (let step = 0; step <= currentStep; step++) {
+    for (const message of copy.messagesPerStep[step]) {
+      if (message) visibleMessages.push(message);
     }
   }
 
-  const stepInfo = STEP_INFO[currentStep];
+  const stepInfo = copy.stepInfo[currentStep];
 
   return (
     <section className="min-h-[500px] space-y-4">
       <h2 className="text-xl font-semibold text-zinc-900 dark:text-zinc-100">
-        {title || "The Agent While-Loop"}
+        {title || copy.title}
       </h2>
 
       <div className="rounded-lg border border-zinc-200 bg-white p-4 dark:border-zinc-700 dark:bg-zinc-900">
         <div className="flex flex-col gap-4 lg:flex-row">
-          {/* Left panel: SVG Flowchart (60%) */}
           <div className="w-full lg:w-[60%]">
             <div className="mb-2 font-mono text-xs text-zinc-400 dark:text-zinc-500">
-              while (stop_reason === "tool_use")
+              {copy.loopLabel}
             </div>
             <svg
               viewBox="0 0 500 440"
@@ -185,33 +329,18 @@ export default function AgentLoop({ title }: { title?: string }) {
                 <filter id="glow-purple">
                   <feDropShadow dx="0" dy="0" stdDeviation="4" floodColor="#a855f7" floodOpacity="0.7" />
                 </filter>
-                <marker
-                  id="arrowhead"
-                  markerWidth="8"
-                  markerHeight="6"
-                  refX="8"
-                  refY="3"
-                  orient="auto"
-                >
+                <marker id="arrowhead" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
                   <polygon points="0 0, 8 3, 0 6" fill={palette.arrowFill} />
                 </marker>
-                <marker
-                  id="arrowhead-active"
-                  markerWidth="8"
-                  markerHeight="6"
-                  refX="8"
-                  refY="3"
-                  orient="auto"
-                >
+                <marker id="arrowhead-active" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
                   <polygon points="0 0, 8 3, 0 6" fill={palette.activeEdgeStroke} />
                 </marker>
               </defs>
 
-              {/* Edges */}
               {EDGES.map((edge) => {
                 const key = `${edge.from}->${edge.to}`;
                 const isActive = activeEdges.includes(key);
-                const d = edgePath(edge.from, edge.to);
+                const d = edgePath(nodes, edge.from, edge.to);
 
                 return (
                   <g key={key}>
@@ -220,7 +349,6 @@ export default function AgentLoop({ title }: { title?: string }) {
                       fill="none"
                       stroke={isActive ? palette.activeEdgeStroke : palette.edgeStroke}
                       strokeWidth={isActive ? 2.5 : 1.5}
-                      strokeDasharray={isActive ? "none" : "none"}
                       markerEnd={isActive ? "url(#arrowhead-active)" : "url(#arrowhead)"}
                       animate={{
                         stroke: isActive ? palette.activeEdgeStroke : palette.edgeStroke,
@@ -232,13 +360,13 @@ export default function AgentLoop({ title }: { title?: string }) {
                       <text
                         x={
                           edge.from === "check" && edge.to === "end"
-                            ? (getNode("check").x + getNode("end").x) / 2
-                            : getNode(edge.from).x + 75
+                            ? (getNode(nodes, "check").x + getNode(nodes, "end").x) / 2
+                            : getNode(nodes, edge.from).x + 75
                         }
                         y={
                           edge.from === "check" && edge.to === "end"
-                            ? getNode("check").y - 10
-                            : (getNode(edge.from).y + getNode(edge.to).y) / 2
+                            ? getNode(nodes, "check").y - 10
+                            : (getNode(nodes, edge.from).y + getNode(nodes, edge.to).y) / 2
                         }
                         textAnchor="middle"
                         className="fill-zinc-400 text-[10px] dark:fill-zinc-500"
@@ -250,8 +378,7 @@ export default function AgentLoop({ title }: { title?: string }) {
                 );
               })}
 
-              {/* Nodes */}
-              {NODES.map((node) => {
+              {nodes.map((node) => {
                 const isActive = activeNodes.includes(node.id);
                 const isEnd = node.id === "end";
                 const filterAttr = isActive
@@ -261,17 +388,16 @@ export default function AgentLoop({ title }: { title?: string }) {
                   : "none";
 
                 if (node.type === "diamond") {
-                  // Diamond shape for decision node
                   const cx = node.x;
                   const cy = node.y;
                   const hw = node.w / 2;
                   const hh = node.h / 2;
                   const points = `${cx},${cy - hh} ${cx + hw},${cy} ${cx},${cy + hh} ${cx - hw},${cy}`;
+
                   return (
                     <g key={node.id}>
                       <motion.polygon
                         points={points}
-                        rx={6}
                         fill={isActive ? palette.activeNodeFill : palette.nodeFill}
                         stroke={isActive ? palette.activeNodeStroke : palette.nodeStroke}
                         strokeWidth={1.5}
@@ -332,7 +458,6 @@ export default function AgentLoop({ title }: { title?: string }) {
                 );
               })}
 
-              {/* Iteration counter */}
               {currentStep >= 5 && (
                 <motion.text
                   x={60}
@@ -344,13 +469,12 @@ export default function AgentLoop({ title }: { title?: string }) {
                   initial={{ opacity: 0 }}
                   animate={{ opacity: 1 }}
                 >
-                  iter #2
+                  {copy.iterationLabel}
                 </motion.text>
               )}
             </svg>
           </div>
 
-          {/* Right panel: messages[] array (40%) */}
           <div className="w-full lg:w-[40%]">
             <div className="mb-2 font-mono text-xs text-zinc-400 dark:text-zinc-500">
               messages[]
@@ -365,33 +489,33 @@ export default function AgentLoop({ title }: { title?: string }) {
                     exit={{ opacity: 0 }}
                     className="py-8 text-center text-xs text-zinc-400 dark:text-zinc-600"
                   >
-                    [ empty ]
+                    {copy.emptyLabel}
                   </motion.div>
                 )}
-                {visibleMessages.map((msg, i) => (
+
+                {visibleMessages.map((message, index) => (
                   <motion.div
-                    key={`${msg.role}-${msg.detail}-${i}`}
+                    key={`${message.role}-${message.detail}-${index}`}
                     initial={{ opacity: 0, y: 12, scale: 0.9 }}
                     animate={{ opacity: 1, y: 0, scale: 1 }}
                     exit={{ opacity: 0, scale: 0.9 }}
                     transition={{ duration: 0.35, type: "spring", bounce: 0.3 }}
-                    className={`rounded-md px-3 py-2 ${msg.colorClass}`}
+                    className={`rounded-md px-3 py-2 ${message.colorClass}`}
                   >
                     <div className="font-mono text-[11px] font-semibold text-white">
-                      {msg.role}
+                      {message.role}
                     </div>
                     <div className="mt-0.5 text-[10px] text-white/80">
-                      {msg.detail}
+                      {message.detail}
                     </div>
                   </motion.div>
                 ))}
               </AnimatePresence>
 
-              {/* Array index markers */}
               {visibleMessages.length > 0 && (
                 <div className="mt-3 border-t border-zinc-200 pt-2 dark:border-zinc-700">
                   <span className="font-mono text-[10px] text-zinc-400">
-                    length: {visibleMessages.length}
+                    {copy.lengthLabel}: {visibleMessages.length}
                   </span>
                 </div>
               )}
diff --git a/web/src/components/visualizations/shared/step-controls.tsx b/web/src/components/visualizations/shared/step-controls.tsx
index cd0beaa2c..bc33b7308 100644
--- a/web/src/components/visualizations/shared/step-controls.tsx
+++ b/web/src/components/visualizations/shared/step-controls.tsx
@@ -1,6 +1,7 @@
 "use client";
 
 import { Play, Pause, SkipBack, SkipForward, RotateCcw } from "lucide-react";
+import { useTranslations } from "@/lib/i18n";
 import { cn } from "@/lib/utils";
 
 interface StepControlsProps {
@@ -28,6 +29,8 @@ export function StepControls({
   stepDescription,
   className,
 }: StepControlsProps) {
+  const t = useTranslations("sim");
+
   return (
     <div className={cn("space-y-3", className)}>
       {/* Annotation */}
@@ -46,7 +49,8 @@ export function StepControls({
           <button
             onClick={onReset}
             className="rounded-md p-1.5 text-zinc-500 hover:bg-zinc-100 hover:text-zinc-700 dark:text-zinc-400 dark:hover:bg-zinc-800 dark:hover:text-zinc-200"
-            title="Reset"
+            title={t("reset")}
+            aria-label={t("reset")}
           >
             <RotateCcw size={16} />
           </button>
@@ -54,14 +58,16 @@ export function StepControls({
             onClick={onPrev}
             disabled={currentStep === 0}
             className="rounded-md p-1.5 text-zinc-500 hover:bg-zinc-100 hover:text-zinc-700 disabled:opacity-30 dark:text-zinc-400 dark:hover:bg-zinc-800 dark:hover:text-zinc-200"
-            title="Previous step"
+            title={t("previous_step")}
+            aria-label={t("previous_step")}
           >
             <SkipBack size={16} />
           </button>
           <button
             onClick={onToggleAutoPlay}
             className="rounded-md p-1.5 text-zinc-500 hover:bg-zinc-100 hover:text-zinc-700 dark:text-zinc-400 dark:hover:bg-zinc-800 dark:hover:text-zinc-200"
-            title={isPlaying ? "Pause" : "Auto-play"}
+            title={isPlaying ? t("pause") : t("autoplay")}
+            aria-label={isPlaying ? t("pause") : t("autoplay")}
           >
             {isPlaying ? <Pause size={16} /> : <Play size={16} />}
           </button>
@@ -69,7 +75,8 @@ export function StepControls({
             onClick={onNext}
             disabled={currentStep === totalSteps - 1}
             className="rounded-md p-1.5 text-zinc-500 hover:bg-zinc-100 hover:text-zinc-700 disabled:opacity-30 dark:text-zinc-400 dark:hover:bg-zinc-800 dark:hover:text-zinc-200"
-            title="Next step"
+            title={t("next_step")}
+            aria-label={t("next_step")}
           >
             <SkipForward size={16} />
           </button>
diff --git a/web/src/data/architecture-blueprints.ts b/web/src/data/architecture-blueprints.ts
new file mode 100644
index 000000000..bef2af5bf
--- /dev/null
+++ b/web/src/data/architecture-blueprints.ts
@@ -0,0 +1,535 @@
+import type { VersionId } from "@/lib/constants";
+
+type LocalizedText = {
+  zh: string;
+  en: string;
+  ja?: string;
+};
+
+export type ArchitectureSliceId =
+  | "mainline"
+  | "control"
+  | "state"
+  | "lanes";
+
+export interface ArchitectureItem {
+  name: LocalizedText;
+  detail: LocalizedText;
+  fresh?: boolean;
+}
+
+export interface ArchitectureBlueprint {
+  summary: LocalizedText;
+  slices: Partial<Record<ArchitectureSliceId, ArchitectureItem[]>>;
+  records: ArchitectureItem[];
+  handoff: LocalizedText[];
+}
+
+const l = (zh: string, en: string): LocalizedText => ({ zh, en });
+
+export const ARCHITECTURE_BLUEPRINTS: Record<VersionId, ArchitectureBlueprint> = {
+  s01: {
+    summary: l(
+      "第一章先建立最小闭环：用户输入进入 messages[]，模型决定要不要调工具，结果再回写到同一条循环里。",
+      "The first chapter establishes the smallest closed loop: user input enters messages[], the model decides whether to call a tool, and the result flows back into the same loop."
+    ),
+    slices: {
+      mainline: [
+        { name: l("Agent Loop", "Agent Loop"), detail: l("每轮都走一次调用模型 -> 处理输出 -> 再决定是否继续。", "Each turn calls the model, handles the output, then decides whether to continue."), fresh: true },
+      ],
+      state: [
+        { name: l("messages[]", "messages[]"), detail: l("所有用户、助手和工具结果都累积在这里。", "User, assistant, and tool result history accumulates here."), fresh: true },
+        { name: l("tool_result 回流", "tool_result write-back"), detail: l("真正让 agent 能行动的是工具结果会回到下一轮推理。", "The agent becomes real when tool results return into the next reasoning step."), fresh: true },
+      ],
+    },
+    records: [
+      { name: l("LoopState", "LoopState"), detail: l("最小可运行会话状态。", "The smallest runnable session state."), fresh: true },
+      { name: l("Assistant Content", "Assistant Content"), detail: l("模型本轮输出。", "The model output for the current turn."), fresh: true },
+    ],
+    handoff: [
+      l("用户消息进入 messages[]", "User message enters messages[]"),
+      l("模型产出 tool_use 或文本", "Model emits tool_use or text"),
+      l("工具结果回写到下一轮", "Tool result writes back into the next turn"),
+    ],
+  },
+  s02: {
+    summary: l(
+      "这一章把“会调一个工具”升级成“能稳定路由很多工具”，主循环不变，工具层长出来。",
+      "This chapter upgrades one tool call into a stable multi-tool routing layer while keeping the main loop unchanged."
+    ),
+    slices: {
+      mainline: [
+        { name: l("稳定主循环", "Stable Main Loop"), detail: l("主循环继续只管模型调用与结果回写。", "The main loop still only owns model calls and write-back."), },
+      ],
+      control: [
+        { name: l("ToolSpec 目录", "ToolSpec Catalog"), detail: l("把工具能力描述给模型看。", "Describes tool capabilities to the model."), fresh: true },
+        { name: l("Dispatch Map", "Dispatch Map"), detail: l("按工具名把调用路由到对应 handler。", "Routes a tool call to the correct handler by name."), fresh: true },
+      ],
+      state: [
+        { name: l("tool_input", "tool_input"), detail: l("模型传入的结构化工具参数。", "Structured tool arguments emitted by the model."), fresh: true },
+      ],
+    },
+    records: [
+      { name: l("ToolSpec", "ToolSpec"), detail: l("schema + 描述。", "Schema plus description."), fresh: true },
+      { name: l("Dispatch Entry", "Dispatch Entry"), detail: l("工具名到函数的映射。", "Mapping from tool name to function."), fresh: true },
+    ],
+    handoff: [
+      l("模型说要调哪个工具", "The model selects a tool"),
+      l("dispatch map 找到 handler", "The dispatch map resolves the handler"),
+      l("handler 输出 tool_result", "The handler returns a tool_result"),
+    ],
+  },
+  s03: {
+    summary: l(
+      "第三章把会话内的工作拆解显式化，agent 开始有一块自己的 session planning 状态。",
+      "The third chapter makes session planning explicit so the agent gains a dedicated session-planning state."
+    ),
+    slices: {
+      mainline: [
+        { name: l("计划先行", "Plan Before Execution"), detail: l("先把大目标拆成当前轮可追踪步骤，再去行动。", "Break the larger goal into trackable steps before acting."), fresh: true },
+      ],
+      control: [
+        { name: l("提醒回路", "Reminder Loop"), detail: l("每轮重新看到当前 todo，避免中途漂移。", "Each turn revisits the current todo list to avoid drift."), fresh: true },
+      ],
+      state: [
+        { name: l("TodoItem", "TodoItem"), detail: l("当前会话里的最小计划单位。", "The smallest planning unit inside one session."), fresh: true },
+        { name: l("PlanState", "PlanState"), detail: l("记录有哪些步骤、做到了哪一步。", "Tracks what steps exist and which one is active."), fresh: true },
+      ],
+    },
+    records: [
+      { name: l("Todo List", "Todo List"), detail: l("会话级，不持久。", "Session-scoped, not durable."), fresh: true },
+    ],
+    handoff: [
+      l("目标先变成步骤", "The goal becomes steps first"),
+      l("当前步骤指导工具选择", "The current step guides tool choice"),
+      l("进展再回写计划状态", "Progress writes back into planning state"),
+    ],
+  },
+  s04: {
+    summary: l(
+      "这里开始把子任务从父上下文中隔离出来，系统第一次有了显式的多循环结构。",
+      "This chapter isolates subtasks from the parent context and introduces the first explicit multi-loop structure."
+    ),
+    slices: {
+      mainline: [
+        { name: l("父循环", "Parent Loop"), detail: l("保持主线目标和最终整合责任。", "Keeps the main goal and the integration responsibility."), },
+        { name: l("子循环", "Child Loop"), detail: l("为子任务提供一份干净上下文。", "Provides a clean context for the subtask."), fresh: true },
+      ],
+      control: [
+        { name: l("委派边界", "Delegation Boundary"), detail: l("什么时候把工作交给子 agent，什么时候留在父循环。", "Defines when work is delegated versus kept in the parent loop."), fresh: true },
+      ],
+      state: [
+        { name: l("Parent messages", "Parent messages"), detail: l("父 agent 的长期上下文。", "The parent agent's long-lived context."), },
+        { name: l("Child messages", "Child messages"), detail: l("子任务一次性的独立上下文。", "An isolated one-shot context for the delegated subtask."), fresh: true },
+      ],
+      lanes: [
+        { name: l("一次性 Subagent", "One-shot Subagent"), detail: l("做完摘要后就退出，不承担长期身份。", "Exits after returning a summary and does not keep long-lived identity."), fresh: true },
+      ],
+    },
+    records: [
+      { name: l("Subtask Request", "Subtask Request"), detail: l("父循环交给子循环的边界对象。", "The boundary object handed from parent to child."), fresh: true },
+    ],
+    handoff: [
+      l("父循环定义子任务", "The parent loop defines a subtask"),
+      l("子循环在独立 messages 里执行", "The child loop runs in isolated messages"),
+      l("摘要回到父循环继续主线", "A summary returns to the parent loop"),
+    ],
+  },
+  s05: {
+    summary: l(
+      "技能系统把知识获取拆成发现层和按需加载层，避免把所有说明一开始全塞进 prompt。",
+      "The skill system splits knowledge into a discovery layer and an on-demand loading layer so the prompt does not start bloated."
+    ),
+    slices: {
+      control: [
+        { name: l("Skill Discovery", "Skill Discovery"), detail: l("先用便宜方式知道有哪些技能可用。", "Learns which skills exist through a cheap discovery pass."), fresh: true },
+        { name: l("Skill Load", "Skill Load"), detail: l("真正需要时再把深说明注入。", "Loads deep instructions only when they are actually needed."), fresh: true },
+      ],
+      state: [
+        { name: l("Skill Registry", "Skill Registry"), detail: l("保存技能名字、简介和路径。", "Stores skill names, summaries, and paths."), fresh: true },
+      ],
+      mainline: [
+        { name: l("主循环保持轻量", "Keep the Loop Lightweight"), detail: l("技能不是固定写进系统 prompt，而是按需补进当前轮。", "Skills are injected on demand instead of being permanently fused into the system prompt."), },
+      ],
+    },
+    records: [
+      { name: l("SKILL.md", "SKILL.md"), detail: l("技能的深说明载体。", "The deep instruction source for a skill."), fresh: true },
+    ],
+    handoff: [
+      l("先发现技能入口", "Discover the skill entry first"),
+      l("需要时读取 SKILL.md", "Read SKILL.md when needed"),
+      l("再把结果回注给主循环", "Feed the loaded result back into the main loop"),
+    ],
+  },
+  s06: {
+    summary: l(
+      "上下文压缩让系统第一次区分活跃窗口和被转移出去的细节，长会话开始变得可持续。",
+      "Context compaction is where the system first separates the active window from offloaded detail so long sessions stay usable."
+    ),
+    slices: {
+      control: [
+        { name: l("压缩触发器", "Compaction Trigger"), detail: l("接近 token 上限时决定何时压缩。", "Decides when to compact as the token budget grows."), fresh: true },
+        { name: l("微压缩与摘要压缩", "Micro and Summary Compaction"), detail: l("按损失程度分两层压缩。", "Compacts in layers with different levels of loss."), fresh: true },
+      ],
+      state: [
+        { name: l("活跃上下文", "Active Context"), detail: l("当前轮必须直接看到的内容。", "What the current turn must see directly."), },
+        { name: l("Persisted Output", "Persisted Output"), detail: l("被移出活跃窗口但仍可再读的细节。", "Detail moved out of the active window but still readable later."), fresh: true },
+        { name: l("Summary State", "Summary State"), detail: l("压缩后保留下来的主线。", "The retained storyline after compaction."), fresh: true },
+      ],
+    },
+    records: [
+      { name: l("Micro Compact Record", "Micro Compact Record"), detail: l("短期挪走细节。", "Moves recent detail out of the hot window."), fresh: true },
+      { name: l("Summary Compact", "Summary Compact"), detail: l("保住主线连续性。", "Preserves continuity of the mainline."), fresh: true },
+    ],
+    handoff: [
+      l("细节先移出活跃窗口", "Detail leaves the active window first"),
+      l("主线被压成摘要", "The mainline is preserved as a summary"),
+      l("后续真需要时再读回原文", "Raw detail is read back only when needed"),
+    ],
+  },
+  s07: {
+    summary: l(
+      "从这一章开始，执行前出现了真正的控制面闸门：模型意图必须先变成可判断的权限请求。",
+      "From this chapter onward, execution gets a real control-plane gate: model intent must become a permission request before it runs."
+    ),
+    slices: {
+      control: [
+        { name: l("Permission Gate", "Permission Gate"), detail: l("deny / ask / allow 决策发生在执行之前。", "deny / ask / allow happens before execution."), fresh: true },
+        { name: l("模式控制", "Mode Control"), detail: l("default、plan、auto 等模式影响整条权限路径。", "Modes such as default, plan, and auto affect the whole permission path."), fresh: true },
+      ],
+      state: [
+        { name: l("PermissionRule", "PermissionRule"), detail: l("定义哪些工具或路径直接允许、拒绝或询问。", "Defines which tools or paths are allowed, denied, or sent for confirmation."), fresh: true },
+        { name: l("PermissionDecision", "PermissionDecision"), detail: l("把 allow / ask / deny 结构化回写。", "Writes allow / ask / deny back in structured form."), fresh: true },
+      ],
+      mainline: [
+        { name: l("主循环不再直达工具", "The Loop No Longer Reaches Tools Directly"), detail: l("tool call 先过权限层，再决定是否真正执行。", "A tool call passes through the permission layer before actual execution."), },
+      ],
+    },
+    records: [
+      { name: l("Normalized Intent", "Normalized Intent"), detail: l("把原始工具调用翻译成可判断对象。", "Translates raw tool calls into a policy-checkable object."), fresh: true },
+    ],
+    handoff: [
+      l("模型提出动作", "The model proposes an action"),
+      l("权限层做出 allow / ask / deny", "The permission layer returns allow / ask / deny"),
+      l("结果回写给主循环继续推理", "That result writes back into the main loop"),
+    ],
+  },
+  s08: {
+    summary: l(
+      "Hook 让主循环第一次拥有稳定的旁路扩展点，日志、审计、追踪开始从核心逻辑中分离。",
+      "Hooks give the loop stable sidecar extension points so logging, audit, and tracing separate from the core path."
+    ),
+    slices: {
+      control: [
+        { name: l("Lifecycle Events", "Lifecycle Events"), detail: l("主循环在 pre_tool / post_tool / on_error 等边界发出事件。", "The loop emits events at boundaries like pre_tool, post_tool, and on_error."), fresh: true },
+        { name: l("Hook Registry", "Hook Registry"), detail: l("多个 hook 共享同一事件契约。", "Multiple hooks share one event contract."), fresh: true },
+      ],
+      state: [
+        { name: l("HookEvent", "HookEvent"), detail: l("tool、input、result、error 等结构化事件包。", "A structured event envelope carrying tool, input, result, error, and more."), fresh: true },
+      ],
+      mainline: [
+        { name: l("主线保持最小", "Keep the Mainline Small"), detail: l("副作用通过 hook 附着，不侵入每个工具 handler。", "Side effects attach through hooks instead of invading every handler."), },
+      ],
+    },
+    records: [
+      { name: l("Audit Sink", "Audit Sink"), detail: l("一个具体副作用落点。", "A concrete side-effect sink."), fresh: true },
+    ],
+    handoff: [
+      l("主循环发事件", "The loop emits an event"),
+      l("Hook 观察并产出副作用", "Hooks observe and produce side effects"),
+      l("主线继续推进不被重写", "The mainline continues without being rewritten"),
+    ],
+  },
+  s09: {
+    summary: l(
+      "长期记忆把跨会话事实从即时上下文里分层出来，系统第一次有了真正的 durable knowledge 容器。",
+      "Long-term memory layers cross-session facts away from immediate context and introduces a real durable knowledge container."
+    ),
+    slices: {
+      control: [
+        { name: l("Memory Load/Write", "Memory Load/Write"), detail: l("模型调用前读取，任务结束后提炼并写回。", "Load before the model call, then extract and write after the work turn."), fresh: true },
+      ],
+      state: [
+        { name: l("messages[]", "messages[]"), detail: l("承载当前过程，不负责跨会话长期知识。", "Carries the live process, not long-term cross-session knowledge."), },
+        { name: l("Memory Store", "Memory Store"), detail: l("只保存跨会话仍然有价值的事实。", "Stores only durable facts that still matter across sessions."), fresh: true },
+      ],
+    },
+    records: [
+      { name: l("MemoryEntry", "MemoryEntry"), detail: l("用户偏好、项目约束等长期事实。", "Long-lived facts such as preferences and project constraints."), fresh: true },
+    ],
+    handoff: [
+      l("先读取相关 memory", "Relevant memory is loaded first"),
+      l("主循环完成本轮工作", "The main loop completes the current turn"),
+      l("再把新事实提炼写回", "New durable facts are extracted and written back"),
+    ],
+  },
+  s10: {
+    summary: l(
+      "系统输入在这里变成装配流水线，模型看到的不再是一段神秘大 prompt，而是一组有边界的输入片段。",
+      "System input becomes an assembly pipeline here: the model no longer sees one giant mysterious prompt, but a bounded set of input sections."
+    ),
+    slices: {
+      control: [
+        { name: l("Prompt Builder", "Prompt Builder"), detail: l("按顺序装配稳定规则、运行时状态、工具和记忆。", "Assembles stable policy, runtime state, tools, and memory in a visible order."), fresh: true },
+      ],
+      state: [
+        { name: l("Prompt Parts", "Prompt Parts"), detail: l("每一段输入都有单独边界。", "Each input fragment has its own explicit boundary."), fresh: true },
+        { name: l("Runtime Context", "Runtime Context"), detail: l("工作目录、任务状态、记忆等运行时片段。", "Runtime fragments such as workspace state, task state, and memory."), fresh: true },
+      ],
+      mainline: [
+        { name: l("模型输入构建", "Model Input Construction"), detail: l("主循环在调用模型前先构建完整输入。", "The loop constructs the full input before calling the model."), },
+      ],
+    },
+    records: [
+      { name: l("Section Order", "Section Order"), detail: l("哪一段先拼、哪一段后拼。", "Which fragment is assembled first versus later."), fresh: true },
+    ],
+    handoff: [
+      l("稳定策略先装配", "Stable policy is assembled first"),
+      l("运行时片段再注入", "Runtime fragments are injected next"),
+      l("最终输入才交给模型", "Only then does the final input reach the model"),
+    ],
+  },
+  s11: {
+    summary: l(
+      "错误恢复把失败正式纳入状态机，系统开始显式记录为什么继续、为什么重试、为什么停止。",
+      "Error recovery formally brings failure into the state machine so the system records why it continues, retries, or stops."
+    ),
+    slices: {
+      control: [
+        { name: l("Recovery Manager", "Recovery Manager"), detail: l("按失败类型选择 retry、fallback、ask 或 stop。", "Chooses retry, fallback, ask, or stop by failure type."), fresh: true },
+      ],
+      state: [
+        { name: l("Continuation Reason", "Continuation Reason"), detail: l("把“为什么继续”写成可见状态。", "Makes the reason for continuation visible state."), fresh: true },
+        { name: l("Retry Bounds", "Retry Bounds"), detail: l("限制恢复分支不会无限循环。", "Prevents recovery branches from looping forever."), fresh: true },
+      ],
+      mainline: [
+        { name: l("失败仍回到主循环", "Failures Still Return to the Loop"), detail: l("失败不是丢掉，而是带着恢复语义回写。", "Failures are not discarded; they write back with recovery semantics."), },
+      ],
+    },
+    records: [
+      { name: l("RecoveryState", "RecoveryState"), detail: l("错误分类和恢复分支状态。", "The error classification and branch state."), fresh: true },
+    ],
+    handoff: [
+      l("工具失败先分类", "A tool failure is classified first"),
+      l("恢复层选择分支", "The recovery layer chooses a branch"),
+      l("继续原因写回主循环", "The continuation reason returns to the main loop"),
+    ],
+  },
+  s12: {
+    summary: l(
+      "任务系统第一次把会话步骤提升成 durable work graph，系统开始能跨轮次推进一组真正的工作节点。",
+      "The task system is where session steps become a durable work graph that can progress real work nodes across turns."
+    ),
+    slices: {
+      control: [
+        { name: l("Unlock Rules", "Unlock Rules"), detail: l("完成一个任务后检查哪些后继节点可以开始。", "Checks which downstream nodes can start once one task completes."), fresh: true },
+      ],
+      state: [
+        { name: l("Task Board", "Task Board"), detail: l("所有工作节点的持久记录面。", "The durable record surface for all work nodes."), fresh: true },
+        { name: l("Dependency Edges", "Dependency Edges"), detail: l("blockedBy / blocks 记录谁依赖谁。", "blockedBy / blocks record who depends on whom."), fresh: true },
+      ],
+      mainline: [
+        { name: l("任务与会话分层", "Tasks Layer Away From the Session"), detail: l("会话内的 todo 退到次要位置，durable task 进入主设计。", "Session-local todo becomes secondary while durable tasks enter the main architecture."), fresh: true },
+      ],
+    },
+    records: [
+      { name: l("TaskRecord", "TaskRecord"), detail: l("目标、状态、依赖、owner 等持久字段。", "Durable fields for goal, status, dependencies, owner, and more."), fresh: true },
+    ],
+    handoff: [
+      l("任务节点被创建", "A task node is created"),
+      l("依赖边决定何时 ready", "Dependency edges decide when work becomes ready"),
+      l("完成后解锁后继节点", "Completion unlocks downstream nodes"),
+    ],
+  },
+  s13: {
+    summary: l(
+      "后台任务把“这项工作存在”和“这次执行正在跑”两层彻底分开，runtime record 正式成立。",
+      "Background tasks fully separate the existence of work from one live execution attempt, which is where runtime records become first-class."
+    ),
+    slices: {
+      control: [
+        { name: l("Notification Drain", "Notification Drain"), detail: l("下一轮调用模型前先把后台摘要带回。", "Drains background notifications before the next model call."), fresh: true },
+      ],
+      state: [
+        { name: l("Task Goal", "Task Goal"), detail: l("durable task 仍在任务板上。", "The durable task goal still lives on the task board."), },
+        { name: l("RuntimeTaskRecord", "RuntimeTaskRecord"), detail: l("描述一条正在跑或跑完的执行槽位。", "Describes one running or completed execution slot."), fresh: true },
+        { name: l("output_file", "output_file"), detail: l("完整产物落盘，通知只带 preview。", "The full artifact goes to disk while notifications carry only a preview."), fresh: true },
+      ],
+      lanes: [
+        { name: l("后台执行线", "Background Execution Slot"), detail: l("慢命令在旁路执行，主循环继续前进。", "Slow commands execute on a side path while the main loop keeps moving."), fresh: true },
+      ],
+    },
+    records: [
+      { name: l("Notification", "Notification"), detail: l("结果回流桥梁。", "The bridge back into the main loop."), fresh: true },
+    ],
+    handoff: [
+      l("主循环创建 runtime record", "The loop creates a runtime record"),
+      l("后台槽位执行慢命令", "A background slot runs the slow command"),
+      l("notification + output_file 回到主系统", "notification plus output_file returns to the main system"),
+    ],
+  },
+  s14: {
+    summary: l(
+      "Cron 调度把时间从“外部条件”变成系统内正式的触发源，但执行权仍然交给 runtime 层。",
+      "The cron scheduler makes time a first-class trigger source while still handing execution off to the runtime layer."
+    ),
+    slices: {
+      control: [
+        { name: l("Schedule Matcher", "Schedule Matcher"), detail: l("只负责判断规则是否命中。", "Only decides whether a rule matches."), fresh: true },
+      ],
+      state: [
+        { name: l("ScheduleRecord", "ScheduleRecord"), detail: l("记录何时触发什么。", "Records what should trigger and when."), fresh: true },
+        { name: l("RuntimeTaskRecord", "RuntimeTaskRecord"), detail: l("命中后生成的具体执行实例。", "The concrete runtime instance created after a match."), },
+      ],
+      lanes: [
+        { name: l("时间触发面", "Time Trigger Surface"), detail: l("cron tick 只是触发面，不直接执行业务。", "A cron tick is only a trigger surface, not the business execution itself."), fresh: true },
+      ],
+    },
+    records: [
+      { name: l("Trigger Event", "Trigger Event"), detail: l("一次规则命中。", "One rule-match occurrence."), fresh: true },
+    ],
+    handoff: [
+      l("cron 规则命中", "A cron rule matches"),
+      l("生成 runtime task", "A runtime task is created"),
+      l("后台运行时接管执行", "The background runtime takes over execution"),
+    ],
+  },
+  s15: {
+    summary: l(
+      "这里开始从单执行者迈向长期团队，persistent teammate、roster 和 inbox 成为新的平台骨架。",
+      "This is where the system moves from one executor toward a long-lived team with persistent teammates, a roster, and inboxes."
+    ),
+    slices: {
+      control: [
+        { name: l("Lead Orchestrator", "Lead Orchestrator"), detail: l("维护 roster、分配职责、观察团队状态。", "Maintains the roster, assigns work, and watches team state."), fresh: true },
+      ],
+      state: [
+        { name: l("Team Roster", "Team Roster"), detail: l("记录每个队友的名字、角色和状态。", "Stores each teammate's name, role, and status."), fresh: true },
+        { name: l("Inbox", "Inbox"), detail: l("每个队友独立的消息边界。", "A separate message boundary for each teammate."), fresh: true },
+      ],
+      lanes: [
+        { name: l("Persistent Teammate", "Persistent Teammate"), detail: l("长期存在、可反复接活的执行者。", "A long-lived worker that can take repeated assignments."), fresh: true },
+      ],
+    },
+    records: [
+      { name: l("TeamMember", "TeamMember"), detail: l("长期身份，不是一次性委派结果。", "A long-lived identity, not a one-shot delegation result."), fresh: true },
+      { name: l("MessageEnvelope", "MessageEnvelope"), detail: l("邮箱里的结构化消息。", "A structured message carried through inboxes."), fresh: true },
+    ],
+    handoff: [
+      l("lead 指定职责", "The lead defines responsibility"),
+      l("消息进入队友 inbox", "Messages enter the teammate inbox"),
+      l("队友独立执行并回信", "The teammate runs independently and replies"),
+    ],
+  },
+  s16: {
+    summary: l(
+      "团队协议把协作从自由文本升级成结构化请求流，request_id 和 durable request record 成为新主线。",
+      "Team protocols upgrade collaboration from free-form text into structured request flows centered on request_id and durable request records."
+    ),
+    slices: {
+      control: [
+        { name: l("Protocol Envelope", "Protocol Envelope"), detail: l("type、from、to、request_id、payload 这类固定外壳。", "A fixed envelope with type, from, to, request_id, and payload."), fresh: true },
+        { name: l("Protocol State Machine", "Protocol State Machine"), detail: l("pending / approved / rejected / expired。", "pending / approved / rejected / expired."), fresh: true },
+      ],
+      state: [
+        { name: l("Request Store", "Request Store"), detail: l("把协议请求变成 durable request record。", "Turns protocol requests into durable request records."), fresh: true },
+      ],
+      lanes: [
+        { name: l("协议协作通道", "Protocol Collaboration Channel"), detail: l("审批、关机、交接这类协作都走同一种 request/response 模型。", "Approvals, shutdowns, and handoffs all use the same request/response model."), fresh: true },
+      ],
+    },
+    records: [
+      { name: l("RequestRecord", "RequestRecord"), detail: l("协议工作的真正状态中心。", "The real state center of a protocol workflow."), fresh: true },
+    ],
+    handoff: [
+      l("发出协议请求", "A protocol request is sent"),
+      l("request_id 绑定状态记录", "request_id binds the durable state record"),
+      l("明确响应回写状态机", "An explicit response writes back into the state machine"),
+    ],
+  },
+  s17: {
+    summary: l(
+      "自治章节把队友从“等待派活”推进到“按 claim policy 自己找活并恢复上下文”，平台开始真正自己运转。",
+      "The autonomy chapter moves teammates from waiting for assignments to self-claiming eligible work under a claim policy and resuming with context."
+    ),
+    slices: {
+      control: [
+        { name: l("Idle Poll Loop", "Idle Poll Loop"), detail: l("空闲时按节奏检查 inbox 和 task board。", "Checks inboxes and the task board on a cadence during idle time."), fresh: true },
+        { name: l("Claim Policy", "Claim Policy"), detail: l("只有满足角色与状态条件的任务才允许 auto-claim。", "Only tasks that satisfy role and state conditions may be auto-claimed."), fresh: true },
+      ],
+      state: [
+        { name: l("Claim Events", "Claim Events"), detail: l("记录是谁因什么来源认领了任务。", "Records who claimed a task and from which source."), fresh: true },
+        { name: l("Durable Requests", "Durable Requests"), detail: l("自治队友继续继承上一章的协议请求状态。", "Autonomous teammates still inherit durable protocol request state from the previous chapter."), },
+      ],
+      lanes: [
+        { name: l("Autonomous Worker", "Autonomous Worker"), detail: l("空闲时自己发现可做工作，再恢复执行。", "Discovers eligible work while idle, then resumes execution."), fresh: true },
+      ],
+    },
+    records: [
+      { name: l("Claimable Predicate", "Claimable Predicate"), detail: l("判定任务是否可由当前角色认领。", "Decides whether the current role may claim a task."), fresh: true },
+    ],
+    handoff: [
+      l("队友进入 idle poll", "The teammate enters idle polling"),
+      l("claim policy 选出可认领工作", "The claim policy selects eligible work"),
+      l("身份块重注入后恢复执行", "Identity is re-injected and execution resumes"),
+    ],
+  },
+  s18: {
+    summary: l(
+      "Worktree 章节把执行环境从主目录里拆开，任务继续表达目标，而 worktree 成为独立、可观察、可 closeout 的执行车道。",
+      "The worktree chapter pulls execution environments out of the main directory: tasks still express goals while worktrees become isolated, observable, closeout-capable lanes."
+    ),
+    slices: {
+      control: [
+        { name: l("Task-to-Lane Binding", "Task-to-Lane Binding"), detail: l("系统明确记录哪条任务用哪条执行车道。", "The system records which task is using which execution lane."), fresh: true },
+        { name: l("Closeout Semantics", "Closeout Semantics"), detail: l("收尾时显式决定 keep 还是 remove。", "Closeout explicitly decides whether to keep or remove the lane."), fresh: true },
+      ],
+      state: [
+        { name: l("Worktree Index", "Worktree Index"), detail: l("注册每条隔离车道的路径、分支和 task_id。", "Registers each isolated lane's path, branch, and task_id."), fresh: true },
+        { name: l("TaskRecord.worktree", "TaskRecord.worktree"), detail: l("任务记录里也能直接看到它当前在哪条 lane 上。", "The task record shows which lane it is currently using."), fresh: true },
+        { name: l("Event Log", "Event Log"), detail: l("create / enter / run / closeout 等生命周期事件。", "Lifecycle events such as create, enter, run, and closeout."), fresh: true },
+      ],
+      lanes: [
+        { name: l("Isolated Directory Lane", "Isolated Directory Lane"), detail: l("不同任务默认不共享未提交改动。", "Different tasks do not share uncommitted changes by default."), fresh: true },
+      ],
+    },
+    records: [
+      { name: l("WorktreeRecord", "WorktreeRecord"), detail: l("车道级执行记录。", "The execution record for one lane."), fresh: true },
+      { name: l("Closeout Record", "Closeout Record"), detail: l("保留或回收的显式结果。", "The explicit result of keep versus reclaim."), fresh: true },
+    ],
+    handoff: [
+      l("任务绑定到 worktree lane", "A task binds to a worktree lane"),
+      l("命令在隔离目录里执行", "Commands run inside the isolated directory"),
+      l("closeout 决定 lane 的最终去向", "Closeout decides the lane's final fate"),
+    ],
+  },
+  s19: {
+    summary: l(
+      "最后一章把本地工具、插件和 MCP server 重新统一到同一 capability bus 下，外部能力终于回到原有控制面里。",
+      "The final chapter reunifies native tools, plugins, and MCP servers on one capability bus so external capability returns to the same control plane."
+    ),
+    slices: {
+      control: [
+        { name: l("Capability Router", "Capability Router"), detail: l("先发现能力，再决定本地、插件还是 MCP 路由。", "Discovers capability first, then routes to native, plugin, or MCP."), fresh: true },
+        { name: l("Shared Permission Gate", "Shared Permission Gate"), detail: l("外部能力和本地工具共用同一权限语义。", "External capabilities and native tools share one permission contract."), fresh: true },
+        { name: l("Result Normalizer", "Result Normalizer"), detail: l("远程结果也要转成主循环看得懂的标准 payload。", "Remote results are normalized into a payload the main loop already understands."), fresh: true },
+      ],
+      state: [
+        { name: l("Plugin Manifest", "Plugin Manifest"), detail: l("告诉系统有哪些外部 server 可用。", "Tells the system which external servers are available."), fresh: true },
+        { name: l("Capability View", "Capability View"), detail: l("把 native / plugin / mcp 整理成一个可比较的能力面。", "Collects native, plugin, and MCP capability into one comparable view."), fresh: true },
+      ],
+      lanes: [
+        { name: l("Native Tool", "Native Tool"), detail: l("本地 handler。", "A local handler."), },
+        { name: l("MCP / Plugin Lane", "MCP / Plugin Lane"), detail: l("外部 server 或插件提供的远程能力。", "Remote capability provided by an external server or plugin."), fresh: true },
+      ],
+    },
+    records: [
+      { name: l("Scoped Capability", "Scoped Capability"), detail: l("带 server / source / risk 信息的能力对象。", "A capability object carrying server, source, and risk information."), fresh: true },
+    ],
+    handoff: [
+      l("先做 capability discovery", "Capability discovery happens first"),
+      l("统一 permission + routing", "Routing and permission stay unified"),
+      l("标准化结果再回写主循环", "A normalized result writes back into the main loop"),
+    ],
+  },
+};
diff --git a/web/src/data/execution-flows.ts b/web/src/data/execution-flows.ts
index 72ce54dd0..f3cfe271a 100644
--- a/web/src/data/execution-flows.ts
+++ b/web/src/data/execution-flows.ts
@@ -10,6 +10,148 @@ const COL_CENTER = FLOW_WIDTH / 2;
 const COL_LEFT = 140;
 const COL_RIGHT = FLOW_WIDTH - 140;
 
+const GENERIC_FLOWS: Record<string, FlowDefinition> = {
+  s07: {
+    nodes: [
+      { id: "intent", label: "Model Intent", type: "start", x: COL_CENTER, y: 30 },
+      { id: "normalize", label: "Normalize\nAction", type: "process", x: COL_CENTER, y: 110 },
+      { id: "policy", label: "Permission\nPolicy?", type: "decision", x: COL_CENTER, y: 200 },
+      { id: "ask", label: "Ask User /\nReturn Deny", type: "subprocess", x: COL_LEFT, y: 300 },
+      { id: "execute", label: "Execute Tool", type: "subprocess", x: COL_RIGHT, y: 300 },
+      { id: "append", label: "Append Structured\nPermission Result", type: "process", x: COL_CENTER, y: 410 },
+      { id: "loop", label: "Continue Loop", type: "end", x: COL_CENTER, y: 500 },
+    ],
+    edges: [
+      { from: "intent", to: "normalize" },
+      { from: "normalize", to: "policy" },
+      { from: "policy", to: "ask", label: "deny / ask" },
+      { from: "policy", to: "execute", label: "allow" },
+      { from: "ask", to: "append" },
+      { from: "execute", to: "append" },
+      { from: "append", to: "loop" },
+    ],
+  },
+  s08: {
+    nodes: [
+      { id: "loop", label: "Main Loop", type: "start", x: COL_CENTER, y: 30 },
+      { id: "event", label: "Emit Lifecycle\nEvent", type: "process", x: COL_CENTER, y: 110 },
+      { id: "hook_check", label: "Hooks\nRegistered?", type: "decision", x: COL_CENTER, y: 200 },
+      { id: "dispatch", label: "Dispatch Hook\nEnvelope", type: "subprocess", x: COL_LEFT, y: 300 },
+      { id: "tool", label: "Run Core Tool\nPath", type: "subprocess", x: COL_RIGHT, y: 300 },
+      { id: "side_effect", label: "Audit / Trace /\nPolicy Side Effects", type: "process", x: COL_LEFT, y: 410 },
+      { id: "append", label: "Append Result\nand Continue", type: "end", x: COL_CENTER, y: 500 },
+    ],
+    edges: [
+      { from: "loop", to: "event" },
+      { from: "event", to: "hook_check" },
+      { from: "hook_check", to: "dispatch", label: "yes" },
+      { from: "hook_check", to: "tool", label: "no" },
+      { from: "dispatch", to: "side_effect" },
+      { from: "dispatch", to: "tool", label: "observe" },
+      { from: "side_effect", to: "append" },
+      { from: "tool", to: "append" },
+    ],
+  },
+  s09: {
+    nodes: [
+      { id: "start", label: "New Turn", type: "start", x: COL_CENTER, y: 30 },
+      { id: "load", label: "Load Relevant\nMemory", type: "subprocess", x: COL_CENTER, y: 110 },
+      { id: "assemble", label: "Assemble Prompt\nwith Memory", type: "process", x: COL_CENTER, y: 190 },
+      { id: "tool", label: "Run Work", type: "subprocess", x: COL_LEFT, y: 290 },
+      { id: "extract", label: "Extract Durable\nFacts", type: "process", x: COL_RIGHT, y: 290 },
+      { id: "persist", label: "Persist Memory", type: "subprocess", x: COL_RIGHT, y: 380 },
+      { id: "end", label: "Next Session /\nNext Turn", type: "end", x: COL_CENTER, y: 470 },
+    ],
+    edges: [
+      { from: "start", to: "load" },
+      { from: "load", to: "assemble" },
+      { from: "assemble", to: "tool" },
+      { from: "tool", to: "extract" },
+      { from: "extract", to: "persist" },
+      { from: "persist", to: "end" },
+    ],
+  },
+  s10: {
+    nodes: [
+      { id: "policy", label: "Stable Policy", type: "start", x: COL_CENTER, y: 30 },
+      { id: "runtime", label: "Runtime State", type: "process", x: COL_LEFT, y: 120 },
+      { id: "memory", label: "Memory /\nTask Context", type: "process", x: COL_RIGHT, y: 120 },
+      { id: "assemble", label: "Prompt Section\nAssembly", type: "subprocess", x: COL_CENTER, y: 220 },
+      { id: "model", label: "Model Call", type: "process", x: COL_CENTER, y: 320 },
+      { id: "tool", label: "Tool Loop / Text\nResponse", type: "decision", x: COL_CENTER, y: 410 },
+      { id: "end", label: "Append and\nContinue", type: "end", x: COL_CENTER, y: 500 },
+    ],
+    edges: [
+      { from: "policy", to: "runtime" },
+      { from: "policy", to: "memory" },
+      { from: "runtime", to: "assemble" },
+      { from: "memory", to: "assemble" },
+      { from: "assemble", to: "model" },
+      { from: "model", to: "tool" },
+      { from: "tool", to: "end", label: "visible input" },
+    ],
+  },
+  s11: {
+    nodes: [
+      { id: "tool", label: "Tool Result", type: "start", x: COL_CENTER, y: 30 },
+      { id: "error", label: "Error?", type: "decision", x: COL_CENTER, y: 120 },
+      { id: "append", label: "Append Result", type: "process", x: COL_RIGHT, y: 220 },
+      { id: "classify", label: "Classify Error", type: "subprocess", x: COL_LEFT, y: 220 },
+      { id: "branch", label: "Retry / Fallback /\nAsk User / Stop", type: "decision", x: COL_LEFT, y: 330 },
+      { id: "reason", label: "Write Continuation\nReason", type: "process", x: COL_CENTER, y: 430 },
+      { id: "loop", label: "Continue or Exit", type: "end", x: COL_CENTER, y: 520 },
+    ],
+    edges: [
+      { from: "tool", to: "error" },
+      { from: "error", to: "append", label: "no" },
+      { from: "error", to: "classify", label: "yes" },
+      { from: "classify", to: "branch" },
+      { from: "append", to: "loop" },
+      { from: "branch", to: "reason" },
+      { from: "reason", to: "loop" },
+    ],
+  },
+  s14: {
+    nodes: [
+      { id: "tick", label: "Cron Tick", type: "start", x: COL_CENTER, y: 30 },
+      { id: "match", label: "Rule Match?", type: "decision", x: COL_CENTER, y: 120 },
+      { id: "sleep", label: "Wait for Next\nTick", type: "end", x: COL_RIGHT, y: 120 },
+      { id: "spawn", label: "Create Runtime\nTask", type: "subprocess", x: COL_LEFT, y: 240 },
+      { id: "queue", label: "Queue for\nBackground Runtime", type: "process", x: COL_LEFT, y: 340 },
+      { id: "notify", label: "Notify Runtime /\nWrite Schedule Event", type: "process", x: COL_CENTER, y: 440 },
+      { id: "end", label: "Execution Continues\nElsewhere", type: "end", x: COL_CENTER, y: 530 },
+    ],
+    edges: [
+      { from: "tick", to: "match" },
+      { from: "match", to: "sleep", label: "no" },
+      { from: "match", to: "spawn", label: "yes" },
+      { from: "spawn", to: "queue" },
+      { from: "queue", to: "notify" },
+      { from: "notify", to: "end" },
+    ],
+  },
+  s19: {
+    nodes: [
+      { id: "request", label: "Capability\nRequest", type: "start", x: COL_CENTER, y: 30 },
+      { id: "discover", label: "Discover Native /\nPlugin / MCP", type: "process", x: COL_CENTER, y: 120 },
+      { id: "route", label: "Route to\nCapability", type: "decision", x: COL_CENTER, y: 210 },
+      { id: "native", label: "Native Tool", type: "subprocess", x: COL_LEFT, y: 320 },
+      { id: "external", label: "Plugin or MCP\nServer Call", type: "subprocess", x: COL_RIGHT, y: 320 },
+      { id: "normalize", label: "Normalize Result /\nApply Policy", type: "process", x: COL_CENTER, y: 430 },
+      { id: "append", label: "Append Back to\nMain Loop", type: "end", x: COL_CENTER, y: 520 },
+    ],
+    edges: [
+      { from: "request", to: "discover" },
+      { from: "discover", to: "route" },
+      { from: "route", to: "native", label: "local" },
+      { from: "route", to: "external", label: "plugin / mcp" },
+      { from: "native", to: "normalize" },
+      { from: "external", to: "normalize" },
+      { from: "normalize", to: "append" },
+    ],
+  },
+};
+
 export const EXECUTION_FLOWS: Record<string, FlowDefinition> = {
   s01: {
     nodes: [
@@ -142,14 +284,14 @@ export const EXECUTION_FLOWS: Record<string, FlowDefinition> = {
       { from: "append", to: "compress_check" },
     ],
   },
-  s07: {
+  s12: {
     nodes: [
       { id: "start", label: "User Input", type: "start", x: COL_CENTER, y: 30 },
       { id: "llm", label: "LLM Call", type: "process", x: COL_CENTER, y: 110 },
       { id: "tool_check", label: "tool_use?", type: "decision", x: COL_CENTER, y: 190 },
-      { id: "is_task", label: "task_manager?", type: "decision", x: COL_LEFT, y: 280 },
-      { id: "crud", label: "CRUD Task\n(file-based)", type: "subprocess", x: 60, y: 370 },
-      { id: "dep_check", label: "Check\nDependencies", type: "process", x: 60, y: 450 },
+      { id: "is_task", label: "task tool?", type: "decision", x: COL_LEFT, y: 280 },
+      { id: "crud", label: "Task Board CRUD\n(.tasks)", type: "subprocess", x: 60, y: 370 },
+      { id: "dep_check", label: "Unlock / Respect\nDependencies", type: "process", x: 60, y: 450 },
       { id: "exec", label: "Execute Tool", type: "subprocess", x: COL_LEFT + 80, y: 370 },
       { id: "append", label: "Append Result", type: "process", x: COL_CENTER, y: 530 },
       { id: "end", label: "Output", type: "end", x: COL_RIGHT, y: 280 },
@@ -167,16 +309,16 @@ export const EXECUTION_FLOWS: Record<string, FlowDefinition> = {
       { from: "append", to: "llm" },
     ],
   },
-  s08: {
+  s13: {
     nodes: [
       { id: "start", label: "User Input", type: "start", x: COL_CENTER, y: 30 },
       { id: "llm", label: "LLM Call", type: "process", x: COL_CENTER, y: 110 },
       { id: "tool_check", label: "tool_use?", type: "decision", x: COL_CENTER, y: 190 },
-      { id: "bg_check", label: "Background?", type: "decision", x: COL_LEFT, y: 280 },
-      { id: "bg_spawn", label: "Spawn Thread", type: "subprocess", x: 60, y: 370 },
+      { id: "bg_check", label: "runtime tool?", type: "decision", x: COL_LEFT, y: 280 },
+      { id: "bg_spawn", label: "Spawn Runtime\nTask", type: "subprocess", x: 60, y: 370 },
       { id: "exec", label: "Execute Tool", type: "subprocess", x: COL_LEFT + 80, y: 370 },
       { id: "append", label: "Append Result", type: "process", x: COL_CENTER, y: 450 },
-      { id: "notify", label: "Notification\nQueue", type: "process", x: 60, y: 450 },
+      { id: "notify", label: "Persist Runtime\nRecord + Notify", type: "process", x: 60, y: 450 },
       { id: "end", label: "Output", type: "end", x: COL_RIGHT, y: 280 },
     ],
     edges: [
@@ -184,20 +326,20 @@ export const EXECUTION_FLOWS: Record<string, FlowDefinition> = {
       { from: "llm", to: "tool_check" },
       { from: "tool_check", to: "bg_check", label: "yes" },
       { from: "tool_check", to: "end", label: "no" },
-      { from: "bg_check", to: "bg_spawn", label: "bg" },
-      { from: "bg_check", to: "exec", label: "fg" },
+      { from: "bg_check", to: "bg_spawn", label: "runtime" },
+      { from: "bg_check", to: "exec", label: "sync" },
       { from: "bg_spawn", to: "notify" },
       { from: "exec", to: "append" },
       { from: "append", to: "llm" },
       { from: "notify", to: "llm" },
     ],
   },
-  s09: {
+  s15: {
     nodes: [
       { id: "start", label: "User Input", type: "start", x: COL_CENTER, y: 30 },
       { id: "llm", label: "LLM Call\n(team lead)", type: "process", x: COL_CENTER, y: 110 },
       { id: "tool_check", label: "tool_use?", type: "decision", x: COL_CENTER, y: 200 },
-      { id: "is_team", label: "Team tool?", type: "decision", x: COL_LEFT, y: 290 },
+      { id: "is_team", label: "team tool?", type: "decision", x: COL_LEFT, y: 290 },
       { id: "spawn", label: "Spawn\nTeammate", type: "subprocess", x: 60, y: 390 },
       { id: "msg", label: "Send Message\n(JSONL inbox)", type: "subprocess", x: 60, y: 470 },
       { id: "exec", label: "Execute Tool", type: "subprocess", x: COL_LEFT + 80, y: 390 },
@@ -219,14 +361,14 @@ export const EXECUTION_FLOWS: Record<string, FlowDefinition> = {
       { from: "append", to: "llm" },
     ],
   },
-  s10: {
+  s16: {
     nodes: [
       { id: "start", label: "User Input", type: "start", x: COL_CENTER, y: 30 },
       { id: "llm", label: "LLM Call\n(team lead)", type: "process", x: COL_CENTER, y: 110 },
       { id: "tool_check", label: "tool_use?", type: "decision", x: COL_CENTER, y: 200 },
-      { id: "is_proto", label: "Protocol?", type: "decision", x: COL_LEFT, y: 290 },
-      { id: "shutdown", label: "Shutdown\nRequest", type: "subprocess", x: 60, y: 390 },
-      { id: "fsm", label: "FSM:\npending->approved", type: "process", x: 60, y: 470 },
+      { id: "is_proto", label: "protocol tool?", type: "decision", x: COL_LEFT, y: 290 },
+      { id: "shutdown", label: "Create Durable\nRequest", type: "subprocess", x: 60, y: 390 },
+      { id: "fsm", label: "Request Record:\npending -> resolved", type: "process", x: 60, y: 470 },
       { id: "exec", label: "Execute Tool", type: "subprocess", x: COL_LEFT + 80, y: 390 },
       { id: "append", label: "Append Result", type: "process", x: COL_CENTER, y: 550 },
       { id: "end", label: "Output", type: "end", x: COL_RIGHT, y: 290 },
@@ -237,7 +379,7 @@ export const EXECUTION_FLOWS: Record<string, FlowDefinition> = {
       { from: "llm", to: "tool_check" },
       { from: "tool_check", to: "is_proto", label: "yes" },
       { from: "tool_check", to: "end", label: "no" },
-      { from: "is_proto", to: "shutdown", label: "shutdown" },
+      { from: "is_proto", to: "shutdown", label: "request" },
       { from: "is_proto", to: "exec", label: "other" },
       { from: "shutdown", to: "fsm" },
       { from: "fsm", to: "teammate" },
@@ -246,42 +388,43 @@ export const EXECUTION_FLOWS: Record<string, FlowDefinition> = {
       { from: "append", to: "llm" },
     ],
   },
-  s11: {
+  s17: {
     nodes: [
-      { id: "start", label: "User Input", type: "start", x: COL_CENTER, y: 30 },
-      { id: "inbox", label: "Check Inbox", type: "process", x: COL_CENTER, y: 100 },
-      { id: "llm", label: "LLM Call", type: "process", x: COL_CENTER, y: 180 },
-      { id: "tool_check", label: "tool_use?", type: "decision", x: COL_CENTER, y: 260 },
-      { id: "exec", label: "Execute Tool", type: "subprocess", x: COL_LEFT, y: 340 },
-      { id: "append", label: "Append Result", type: "process", x: COL_LEFT, y: 410 },
-      { id: "end", label: "Output", type: "end", x: COL_RIGHT, y: 340 },
-      { id: "idle", label: "Idle Cycle", type: "process", x: COL_RIGHT, y: 420 },
-      { id: "poll", label: "Poll Tasks\n+ Auto-Claim", type: "subprocess", x: COL_RIGHT, y: 500 },
+      { id: "start", label: "Resume /\nNew Work", type: "start", x: COL_CENTER, y: 30 },
+      { id: "identity", label: "Ensure Identity\nContext", type: "process", x: COL_CENTER, y: 110 },
+      { id: "llm", label: "LLM Work Turn", type: "process", x: COL_CENTER, y: 190 },
+      { id: "tool_check", label: "tool_use?", type: "decision", x: COL_CENTER, y: 270 },
+      { id: "exec", label: "Execute Tool /\nProtocol Action", type: "subprocess", x: COL_LEFT, y: 350 },
+      { id: "append", label: "Append Result\nand Continue", type: "process", x: COL_LEFT, y: 430 },
+      { id: "idle", label: "Enter Idle\nPhase", type: "process", x: COL_RIGHT, y: 350 },
+      { id: "poll", label: "Inbox First,\nThen Claimable Tasks", type: "subprocess", x: COL_RIGHT, y: 430 },
+      { id: "claim", label: "Auto-Claim +\nWrite Claim Event", type: "process", x: COL_RIGHT, y: 520 },
     ],
     edges: [
-      { from: "start", to: "inbox" },
-      { from: "inbox", to: "llm" },
+      { from: "start", to: "identity" },
+      { from: "identity", to: "llm" },
       { from: "llm", to: "tool_check" },
       { from: "tool_check", to: "exec", label: "yes" },
-      { from: "tool_check", to: "end", label: "no" },
+      { from: "tool_check", to: "idle", label: "idle" },
       { from: "exec", to: "append" },
       { from: "append", to: "llm" },
-      { from: "end", to: "idle" },
       { from: "idle", to: "poll" },
-      { from: "poll", to: "inbox" },
+      { from: "poll", to: "claim", label: "claimable task" },
+      { from: "poll", to: "identity", label: "inbox message" },
+      { from: "claim", to: "identity", label: "resume work" },
     ],
   },
-  s12: {
+  s18: {
     nodes: [
       { id: "start", label: "User Input", type: "start", x: COL_CENTER, y: 30 },
       { id: "llm", label: "LLM Call", type: "process", x: COL_CENTER, y: 110 },
       { id: "tool_check", label: "tool_use?", type: "decision", x: COL_CENTER, y: 190 },
       { id: "is_wt", label: "worktree tool?", type: "decision", x: COL_LEFT, y: 280 },
-      { id: "task", label: "Task Board\\n(.tasks)", type: "process", x: 60, y: 360 },
-      { id: "wt_create", label: "Allocate / Enter\\nWorktree", type: "subprocess", x: 60, y: 440 },
+      { id: "task", label: "Task State:\\nbind + worktree_state", type: "process", x: 60, y: 360 },
+      { id: "wt_create", label: "Create / Enter\\nWorktree Lane", type: "subprocess", x: 60, y: 440 },
       { id: "wt_run", label: "Run in\\nIsolated Dir", type: "subprocess", x: COL_LEFT + 80, y: 360 },
-      { id: "wt_close", label: "Closeout:\\nworktree_keep / remove", type: "process", x: COL_LEFT + 80, y: 440 },
-      { id: "events", label: "Emit Lifecycle Events\\n(side-channel)", type: "process", x: COL_RIGHT, y: 420 },
+      { id: "wt_close", label: "worktree_closeout\\nkeep | remove", type: "process", x: COL_LEFT + 80, y: 440 },
+      { id: "events", label: "Emit enter / run /\ncloseout events", type: "process", x: COL_RIGHT, y: 420 },
       { id: "events_read", label: "Optional Read\\nworktree_events", type: "subprocess", x: COL_RIGHT, y: 520 },
       { id: "append", label: "Append Result", type: "process", x: COL_CENTER, y: 530 },
       { id: "end", label: "Output", type: "end", x: COL_RIGHT, y: 280 },
@@ -292,13 +435,13 @@ export const EXECUTION_FLOWS: Record<string, FlowDefinition> = {
       { from: "tool_check", to: "is_wt", label: "yes" },
       { from: "tool_check", to: "end", label: "no" },
       { from: "is_wt", to: "task", label: "task ops" },
-      { from: "is_wt", to: "wt_create", label: "create/bind" },
+      { from: "is_wt", to: "wt_create", label: "create/enter" },
       { from: "is_wt", to: "wt_run", label: "run/status" },
       { from: "task", to: "wt_create", label: "allocate lane" },
       { from: "wt_create", to: "wt_run" },
       { from: "task", to: "append", label: "task result" },
-      { from: "wt_create", to: "events", label: "emit create" },
-      { from: "wt_create", to: "append", label: "create result" },
+      { from: "wt_create", to: "events", label: "emit create/enter" },
+      { from: "wt_create", to: "append", label: "create/enter result" },
       { from: "wt_run", to: "wt_close" },
       { from: "wt_run", to: "append", label: "run/status result" },
       { from: "wt_close", to: "events", label: "emit closeout" },
@@ -311,5 +454,5 @@ export const EXECUTION_FLOWS: Record<string, FlowDefinition> = {
 };
 
 export function getFlowForVersion(version: string): FlowDefinition | null {
-  return EXECUTION_FLOWS[version] ?? null;
+  return GENERIC_FLOWS[version] ?? EXECUTION_FLOWS[version] ?? null;
 }
diff --git a/web/src/data/generated/docs.json b/web/src/data/generated/docs.json
index b0a3f8975..19bb66b8c 100644
--- a/web/src/data/generated/docs.json
+++ b/web/src/data/generated/docs.json
@@ -1,218 +1,974 @@
 [
+  {
+    "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### LangChain comparison track for Stage 1\n\nAfter reading the hand-written `agents/s01-s06` baseline, you can open `agents_langchain/s01_agent_loop.py` through `agents_langchain/s06_context_compact.py` as a framework comparison track. It keeps the original files unchanged, uses OpenAI-style `OPENAI_API_KEY` / `OPENAI_MODEL` configuration, and shows what LangChain owns versus what the surrounding harness still owns. The web UI does not surface this track yet.\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",
-    "content": "# s01: The Agent Loop\n\n`[ s01 ] s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`\n\n> *\"One loop & Bash is all you need\"* -- one tool + one loop = an agent.\n\n## Problem\n\nA language model can reason about code, but it can't *touch* the real world -- can't read files, run tests, or check errors. Without a loop, every tool call requires you to manually copy-paste results back. You become the loop.\n\n## Solution\n\n```\n+--------+      +-------+      +---------+\n|  User  | ---> |  LLM  | ---> |  Tool   |\n| prompt |      |       |      | execute |\n+--------+      +---+---+      +----+----+\n                    ^                |\n                    |   tool_result  |\n                    +----------------+\n                    (loop until stop_reason != \"tool_use\")\n```\n\nOne exit condition controls the entire flow. The loop runs until the model stops calling tools.\n\n## How It Works\n\n1. User prompt becomes the first message.\n\n```python\nmessages.append({\"role\": \"user\", \"content\": query})\n```\n\n2. Send messages + tool definitions to the LLM.\n\n```python\nresponse = client.messages.create(\n    model=MODEL, system=SYSTEM, messages=messages,\n    tools=TOOLS, max_tokens=8000,\n)\n```\n\n3. Append the assistant response. Check `stop_reason` -- if the model didn't call a tool, we're done.\n\n```python\nmessages.append({\"role\": \"assistant\", \"content\": response.content})\nif response.stop_reason != \"tool_use\":\n    return\n```\n\n4. Execute each tool call, collect results, append as a user message. 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,\n            \"content\": output,\n        })\nmessages.append({\"role\": \"user\", \"content\": results})\n```\n\nAssembled into 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\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 -- without changing the loop.\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"
+    "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",
-    "content": "# s02: Tool Use\n\n`s01 > [ s02 ] s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`\n\n> *\"Adding a tool means adding one handler\"* -- the loop stays the same; new tools register into the dispatch map.\n\n## Problem\n\nWith only `bash`, the agent shells out for everything. `cat` truncates unpredictably, `sed` fails on special characters, and every bash call is an unconstrained security surface. Dedicated tools like `read_file` and `write_file` let you enforce path sandboxing at the tool level.\n\nThe key insight: adding tools does not require changing the loop.\n\n## Solution\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\n1. Each tool gets a handler function. Path sandboxing prevents workspace escape.\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. The dispatch map links tool names to handlers.\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. In the loop, look up the handler by name. The loop body itself is unchanged from 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\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"
+    "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",
-    "content": "# s03: TodoWrite\n\n`s01 > s02 > [ s03 ] s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`\n\n> *\"An agent without a plan drifts\"* -- list the steps first, then execute.\n\n## Problem\n\nOn multi-step tasks, the model loses track. It repeats work, skips steps, or wanders off. Long conversations make this worse -- the system prompt fades as tool results fill the context. A 10-step refactoring might complete steps 1-3, then the model starts improvising because it forgot steps 4-10.\n\n## Solution\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\n1. TodoManager stores items with statuses. Only one item can be `in_progress` at a time.\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()\n```\n\n2. The `todo` tool goes into the dispatch map like any other tool.\n\n```python\nTOOL_HANDLERS = {\n    # ...base tools...\n    \"todo\": lambda **kw: TODO.update(kw[\"items\"]),\n}\n```\n\n3. A nag reminder injects a nudge if the model goes 3+ rounds without calling `todo`.\n\n```python\nif rounds_since_todo >= 3 and messages:\n    last = messages[-1]\n    if last[\"role\"] == \"user\" and isinstance(last.get(\"content\"), list):\n        last[\"content\"].insert(0, {\n            \"type\": \"text\",\n            \"text\": \"<reminder>Update your todos.</reminder>\",\n        })\n```\n\nThe \"one in_progress at a time\" constraint forces sequential focus. The nag reminder creates accountability.\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"
+    "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",
-    "content": "# s04: Subagents\n\n`s01 > s02 > s03 > [ s04 ] s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`\n\n> *\"Break big tasks down; each subtask gets a clean context\"* -- subagents use independent messages[], keeping the main conversation clean.\n\n## Problem\n\nAs the agent works, its messages array grows. Every file read, every bash output stays in context permanently. \"What testing framework does this project use?\" might require reading 5 files, but the parent only needs the answer: \"pytest.\"\n\n## Solution\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\n1. The parent gets a `task` tool. The child gets all base tools except `task` (no recursive spawning).\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\n2. The subagent starts with `messages=[]` and runs its own loop. Only the final text returns to the parent.\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    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) is discarded. The parent receives a one-paragraph summary as a normal `tool_result`.\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"
+    "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",
-    "content": "# s05: Skills\n\n`s01 > s02 > s03 > s04 > [ s05 ] s06 | s07 > s08 > s09 > s10 > s11 > s12`\n\n> *\"Load knowledge when you need it, not upfront\"* -- inject via tool_result, not the system prompt.\n\n## Problem\n\nYou want the agent to follow domain-specific workflows: git conventions, testing patterns, code review checklists. Putting everything in the system prompt wastes tokens on unused skills. 10 skills at 2000 tokens each = 20,000 tokens, most of which are irrelevant to any given task.\n\n## Solution\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\nLayer 1: skill *names* in system prompt (cheap). Layer 2: full *body* via tool_result (on demand).\n\n## How It Works\n\n1. Each skill is a directory containing a `SKILL.md` with YAML frontmatter.\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 scans for `SKILL.md` files, uses the directory name as the skill identifier.\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. Layer 1 goes into the system prompt. Layer 2 is just another tool handler.\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) and loads them when relevant (expensive).\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"
+    "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",
-    "content": "# s06: Context Compact\n\n`s01 > s02 > s03 > s04 > s05 > [ s06 ] | s07 > s08 > s09 > s10 > s11 > s12`\n\n> *\"Context will fill up; you need a way to make room\"* -- three-layer compression strategy for infinite sessions.\n\n## Problem\n\nThe context window is finite. A single `read_file` on a 1000-line file costs ~4000 tokens. After reading 30 files and running 20 bash commands, you hit 100,000+ tokens. The agent cannot work on large codebases without compression.\n\n## Solution\n\nThree layers, increasing in aggressiveness:\n\n```\nEvery turn:\n+------------------+\n| Tool call result |\n+------------------+\n        |\n        v\n[Layer 1: micro_compact]        (silent, every turn)\n  Replace tool_result > 3 turns old\n  with \"[Previous: used {tool_name}]\"\n        |\n        v\n[Check: tokens > 50000?]\n   |               |\n   no              yes\n   |               |\n   v               v\ncontinue    [Layer 2: auto_compact]\n              Save transcript to .transcripts/\n              LLM summarizes conversation.\n              Replace all messages with [summary].\n                    |\n                    v\n            [Layer 3: compact tool]\n              Model calls compact explicitly.\n              Same summarization as auto_compact.\n```\n\n## How It Works\n\n1. **Layer 1 -- micro_compact**: Before each LLM call, replace old tool results with placeholders.\n\n```python\ndef micro_compact(messages: list) -> list:\n    tool_results = []\n    for i, msg in enumerate(messages):\n        if msg[\"role\"] == \"user\" and isinstance(msg.get(\"content\"), list):\n            for j, part in enumerate(msg[\"content\"]):\n                if isinstance(part, dict) and part.get(\"type\") == \"tool_result\":\n                    tool_results.append((i, j, part))\n    if len(tool_results) <= KEEP_RECENT:\n        return messages\n    for _, _, part in tool_results[:-KEEP_RECENT]:\n        if len(part.get(\"content\", \"\")) > 100:\n            part[\"content\"] = f\"[Previous: used {tool_name}]\"\n    return messages\n```\n\n2. **Layer 2 -- auto_compact**: When tokens exceed threshold, save full transcript to disk, then ask the LLM to summarize.\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]}],\n        max_tokens=2000,\n    )\n    return [\n        {\"role\": \"user\", \"content\": f\"[Compressed]\\n\\n{response.content[0].text}\"},\n        {\"role\": \"assistant\", \"content\": \"Understood. Continuing.\"},\n    ]\n```\n\n3. **Layer 3 -- manual compact**: The `compact` tool triggers the same summarization on demand.\n\n4. The loop integrates all three:\n\n```python\ndef agent_loop(messages: list):\n    while True:\n        micro_compact(messages)                        # Layer 1\n        if estimate_tokens(messages) > THRESHOLD:\n            messages[:] = auto_compact(messages)       # Layer 2\n        response = client.messages.create(...)\n        # ... tool execution ...\n        if manual_compact:\n            messages[:] = auto_compact(messages)       # Layer 3\n```\n\nTranscripts preserve full history on disk. 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             | Three-layer compression    |\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"
+    "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: Task System",
-    "content": "# s07: Task System\n\n`s01 > s02 > s03 > s04 > s05 > s06 | [ s07 ] s08 > s09 > s10 > s11 > s12`\n\n> *\"Break big goals into small tasks, order them, persist to disk\"* -- a file-based task graph with dependencies, laying the foundation for multi-agent collaboration.\n\n## Problem\n\ns03's TodoManager is a flat checklist in memory: no ordering, no dependencies, no status beyond done-or-not. Real goals have structure -- task B depends on task A, tasks C and D can run in parallel, task E waits for both C and D.\n\nWithout explicit relationships, the agent can't tell what's ready, what's blocked, or what can run concurrently. And because the list lives only in memory, context compression (s06) wipes it clean.\n\n## 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:\n\n- **What's ready?** -- tasks with `pending` status and empty `blockedBy`.\n- **What's blocked?** -- tasks waiting on unfinished dependencies.\n- **What's done?** -- `completed` tasks, whose completion automatically unblocks dependents.\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\nThis task graph becomes the coordination backbone for everything after s07: background execution (s08), multi-agent teams (s09+), and worktree isolation (s12) all read from and write to this same structure.\n\n## How It Works\n\n1. **TaskManager**: one JSON file per task, CRUD with 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\n2. **Dependency resolution**: completing a task clears 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\n3. **Status + dependency wiring**: `update` handles transitions and dependency edges.\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\n4. Four task tools go into the dispatch map.\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 s07 onward, the task graph is the default for multi-step work. s03's Todo remains for quick single-session checklists.\n\n## What Changed From s06\n\n| Component | Before (s06) | After (s07) |\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/s07_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"
+    "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: Background Tasks",
-    "content": "# s08: Background Tasks\n\n`s01 > s02 > s03 > s04 > s05 > s06 | s07 > [ s08 ] s09 > s10 > s11 > s12`\n\n> *\"Run slow operations in the background; the agent keeps thinking\"* -- daemon threads run commands, inject notifications on completion.\n\n## Problem\n\nSome commands take minutes: `npm install`, `pytest`, `docker build`. With a blocking loop, the model sits idle waiting. If the user asks \"install dependencies and while that runs, create the config file,\" the agent does them sequentially, not in parallel.\n\n## Solution\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\n1. BackgroundManager tracks tasks with a thread-safe notification queue.\n\n```python\nclass BackgroundManager:\n    def __init__(self):\n        self.tasks = {}\n        self._notification_queue = []\n        self._lock = threading.Lock()\n```\n\n2. `run()` starts a daemon thread and returns immediately.\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\n3. When the subprocess finishes, its result goes into the notification queue.\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\n4. The agent loop drains notifications before each LLM call.\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\nThe loop stays single-threaded. Only subprocess I/O is parallelized.\n\n## What Changed From s07\n\n| Component      | Before (s07)     | After (s08)                |\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/s08_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"
+    "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: Agent Teams",
-    "content": "# s09: Agent Teams\n\n`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > [ s09 ] s10 > s11 > s12`\n\n> *\"When the task is too big for one, delegate to teammates\"* -- persistent teammates + async mailboxes.\n\n## Problem\n\nSubagents (s04) are disposable: spawn, work, return summary, die. No identity, no memory between invocations. Background tasks (s08) run shell commands but can't make LLM-guided decisions.\n\nReal teamwork needs: (1) persistent agents that outlive a single prompt, (2) identity and lifecycle management, (3) a communication channel between agents.\n\n## Solution\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\n1. TeammateManager maintains config.json with the team roster.\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\n2. `spawn()` creates a teammate and starts its agent loop in a thread.\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\n3. MessageBus: append-only JSONL inboxes. `send()` appends a JSON line; `read_inbox()` reads all and drains.\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\n4. Each teammate checks its inbox before every LLM call, injecting received messages into context.\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## What Changed From s08\n\n| Component      | Before (s08)     | After (s09)                |\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/s09_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"
+    "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: Team Protocols",
-    "content": "# s10: Team Protocols\n\n`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > [ s10 ] s11 > s12`\n\n> *\"Teammates need shared communication rules\"* -- one request-response pattern drives all negotiation.\n\n## Problem\n\nIn s09, teammates work and communicate but lack structured coordination:\n\n**Shutdown**: Killing a thread leaves files half-written and config.json stale. You need a handshake: the lead requests, the teammate approves (finish and exit) or rejects (keep working).\n\n**Plan approval**: When the lead says \"refactor the auth module,\" the teammate starts immediately. For high-risk changes, the lead should review the plan first.\n\nBoth share the same structure: one side sends a request with a unique ID, the other responds referencing that ID.\n\n## Solution\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\n1. The lead initiates shutdown by generating a request_id and sending through the inbox.\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\n2. The teammate receives the request and responds with approve/reject.\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\n3. Plan approval follows the identical pattern. The teammate submits a plan (generating a request_id), the lead reviews (referencing the same request_id).\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\nOne FSM, two applications. The same `pending -> approved | rejected` state machine handles any request-response protocol.\n\n## What Changed From s09\n\n| Component      | Before (s09)     | After (s10)                  |\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/s10_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"
+    "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: Autonomous Agents",
-    "content": "# s11: Autonomous Agents\n\n`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > [ s11 ] s12`\n\n> *\"Teammates scan the board and claim tasks themselves\"* -- no need for the lead to assign each one.\n\n## Problem\n\nIn s09-s10, teammates only work when explicitly told to. The lead must spawn each one with a specific prompt. 10 unclaimed tasks on the board? The lead assigns each one manually. Doesn't scale.\n\nTrue autonomy: teammates scan the task board themselves, claim unclaimed tasks, work on them, then look for more.\n\nOne subtlety: after context compression (s06), the agent might forget who it is. Identity re-injection fixes this.\n\n## Solution\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\n1. The teammate loop has two phases: WORK and IDLE. When the LLM stops calling tools (or calls `idle`), the teammate enters IDLE.\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\n2. The idle phase polls inbox and task board in a loop.\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\n3. Task board scanning: find pending, unowned, unblocked tasks.\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\n4. Identity re-injection: when context is too short (compression happened), insert an identity block.\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## What Changed From s10\n\n| Component      | Before (s10)     | After (s11)                |\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/s11_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"
+    "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": "s12: Worktree + Task Isolation",
-    "content": "# s12: Worktree + Task Isolation\n\n`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > [ s12 ]`\n\n> *\"Each works in its own directory, no interference\"* -- tasks manage goals, worktrees manage directories, bound by ID.\n\n## Problem\n\nBy s11, agents can claim and complete tasks autonomously. But every task runs in one shared directory. Two agents refactoring different modules at the same time will collide: agent A edits `config.py`, agent B edits `config.py`, unstaged changes mix, and neither can roll back cleanly.\n\nThe task board tracks *what to do* but has no opinion about *where to do it*. The fix: give each task its own git worktree directory. Tasks manage goals, worktrees manage execution context. Bind them by task ID.\n\n## Solution\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\n1. **Create a task.** Persist the goal first.\n\n```python\nTASKS.create(\"Implement auth refactor\")\n# -> .tasks/task_1.json  status=pending  worktree=\"\"\n```\n\n2. **Create a worktree and bind to the task.** Passing `task_id` auto-advances the task to `in_progress`.\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:\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\n3. **Run commands in the worktree.** `cwd` points to the isolated directory.\n\n```python\nsubprocess.run(command, shell=True, cwd=worktree_path,\n               capture_output=True, text=True, timeout=300)\n```\n\n4. **Close out.** Two choices:\n   - `worktree_keep(name)` -- preserve the directory for later.\n   - `worktree_remove(name, complete_task=True)` -- remove directory, complete the bound task, emit event. One call handles teardown + completion.\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\n5. **Event stream.** Every lifecycle step emits to `.worktrees/events.jsonl`:\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\nAfter a crash, state reconstructs from `.tasks/` + `.worktrees/index.json` on disk. Conversation memory is volatile; file state is durable.\n\n## What Changed From s11\n\n| Component          | Before (s11)               | After (s12)                                  |\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/s12_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"
+    "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### 阶段 1 的 Deep Agents 轨道\n\n读完手写版 `agents/s01-s06` 以后，可以继续看 `agents_deepagents/s01_agent_loop.py` 到 `agents_deepagents/s06_context_compact.py`。这是一条 Deep Agents 教学轨道：原来的 `agents/*.py` 不变，运行时继续使用 OpenAI 风格的 `OPENAI_API_KEY` / `OPENAI_MODEL`（可选 `OPENAI_BASE_URL`）配置，但能力会按章节逐步开放——`s01` 只保留最小 loop，`s03` 才引入 planning，`s04` 才引入 subagent，`s05` 才引入 skills，`s06` 才引入 context compact。当前 web UI 暂不展示这条轨道。\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 (Agent 循环)",
-    "content": "# s01: The Agent Loop (Agent 循环)\n\n`[ s01 ] s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`\n\n> *\"One loop & Bash is all you need\"* -- 一个工具 + 一个循环 = 一个 Agent。\n\n## 问题\n\n语言模型能推理代码, 但碰不到真实世界 -- 不能读文件、跑测试、看报错。没有循环, 每次工具调用你都得手动把结果粘回去。你自己就是那个循环。\n\n## 解决方案\n\n```\n+--------+      +-------+      +---------+\n|  User  | ---> |  LLM  | ---> |  Tool   |\n| prompt |      |       |      | execute |\n+--------+      +---+---+      +----+----+\n                    ^                |\n                    |   tool_result  |\n                    +----------------+\n                    (loop until stop_reason != \"tool_use\")\n```\n\n一个退出条件控制整个流程。循环持续运行, 直到模型不再调用工具。\n\n## 工作原理\n\n1. 用户 prompt 作为第一条消息。\n\n```python\nmessages.append({\"role\": \"user\", \"content\": query})\n```\n\n2. 将消息和工具定义一起发给 LLM。\n\n```python\nresponse = client.messages.create(\n    model=MODEL, system=SYSTEM, messages=messages,\n    tools=TOOLS, max_tokens=8000,\n)\n```\n\n3. 追加助手响应。检查 `stop_reason` -- 如果模型没有调用工具, 结束。\n\n```python\nmessages.append({\"role\": \"assistant\", \"content\": response.content})\nif response.stop_reason != \"tool_use\":\n    return\n```\n\n4. 执行每个工具调用, 收集结果, 作为 user 消息追加。回到第 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,\n            \"content\": output,\n        })\nmessages.append({\"role\": \"user\", \"content\": results})\n```\n\n组装为一个完整函数:\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\n\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                output = run_bash(block.input[\"command\"])\n                results.append({\n                    \"type\": \"tool_result\",\n                    \"tool_use_id\": block.id,\n                    \"content\": output,\n                })\n        messages.append({\"role\": \"user\", \"content\": results})\n```\n\n不到 30 行, 这就是整个 Agent。后面 11 个章节都在这个循环上叠加机制 -- 循环本身始终不变。\n\n## 变更内容\n\n| 组件          | 之前       | 之后                           |\n|---------------|------------|--------------------------------|\n| Agent loop    | (无)       | `while True` + stop_reason     |\n| Tools         | (无)       | `bash` (单一工具)              |\n| Messages      | (无)       | 累积式消息列表                 |\n| Control flow  | (无)       | `stop_reason != \"tool_use\"`    |\n\n## 试一试\n\n```sh\ncd learn-claude-code\npython agents/s01_agent_loop.py\n```\n\n试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):\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"
+    "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 (工具使用)",
-    "content": "# s02: Tool Use (工具使用)\n\n`s01 > [ s02 ] s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`\n\n> *\"加一个工具, 只加一个 handler\"* -- 循环不用动, 新工具注册进 dispatch map 就行。\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"
+    "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 (待办写入)",
-    "content": "# s03: TodoWrite (待办写入)\n\n`s01 > s02 > [ s03 ] s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`\n\n> *\"没有计划的 agent 走哪算哪\"* -- 先列步骤再动手, 完成率翻倍。\n\n## 问题\n\n多步任务中, 模型会丢失进度 -- 重复做过的事、跳步、跑偏。对话越长越严重: 工具结果不断填满上下文, 系统提示的影响力逐渐被稀释。一个 10 步重构可能做完 1-3 步就开始即兴发挥, 因为 4-10 步已经被挤出注意力了。\n\n## 解决方案\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## 工作原理\n\n1. TodoManager 存储带状态的项目。同一时间只允许一个 `in_progress`。\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()\n```\n\n2. `todo` 工具和其他工具一样加入 dispatch map。\n\n```python\nTOOL_HANDLERS = {\n    # ...base tools...\n    \"todo\": lambda **kw: TODO.update(kw[\"items\"]),\n}\n```\n\n3. nag reminder: 模型连续 3 轮以上不调用 `todo` 时注入提醒。\n\n```python\nif rounds_since_todo >= 3 and messages:\n    last = messages[-1]\n    if last[\"role\"] == \"user\" and isinstance(last.get(\"content\"), list):\n        last[\"content\"].insert(0, {\n            \"type\": \"text\",\n            \"text\": \"<reminder>Update your todos.</reminder>\",\n        })\n```\n\n\"同时只能有一个 in_progress\" 强制顺序聚焦。nag reminder 制造问责压力 -- 你不更新计划, 系统就追着你问。\n\n## 相对 s02 的变更\n\n| 组件           | 之前 (s02)       | 之后 (s03)                     |\n|----------------|------------------|--------------------------------|\n| Tools          | 4                | 5 (+todo)                      |\n| 规划           | 无               | 带状态的 TodoManager           |\n| Nag 注入       | 无               | 3 轮后注入 `<reminder>`        |\n| Agent loop     | 简单分发         | + rounds_since_todo 计数器     |\n\n## 试一试\n\n```sh\ncd learn-claude-code\npython agents/s03_todo_write.py\n```\n\n试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):\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"
+    "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 (Subagent)",
-    "content": "# s04: Subagents (Subagent)\n\n`s01 > s02 > s03 > [ s04 ] s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`\n\n> *\"大任务拆小, 每个小任务干净的上下文\"* -- Subagent 用独立 messages[], 不污染主对话。\n\n## 问题\n\nAgent 工作越久, messages 数组越胖。每次读文件、跑命令的输出都永久留在上下文里。\"这个项目用什么测试框架?\" 可能要读 5 个文件, 但父 Agent 只需要一个词: \"pytest。\"\n\n## 解决方案\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## 工作原理\n\n1. 父 Agent 有一个 `task` 工具。Subagent 拥有除 `task` 外的所有基础工具 (禁止递归生成)。\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\n2. Subagent 以 `messages=[]` 启动, 运行自己的循环。只有最终文本返回给父 Agent。\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    return \"\".join(\n        b.text for b in response.content if hasattr(b, \"text\")\n    ) or \"(no summary)\"\n```\n\nSubagent 可能跑了 30+ 次工具调用, 但整个消息历史直接丢弃。父 Agent 收到的只是一段摘要文本, 作为普通 `tool_result` 返回。\n\n## 相对 s03 的变更\n\n| 组件           | 之前 (s03)       | 之后 (s04)                    |\n|----------------|------------------|-------------------------------|\n| Tools          | 5                | 5 (基础) + task (仅父端)      |\n| 上下文         | 单一共享         | 父 + 子隔离                   |\n| Subagent       | 无               | `run_subagent()` 函数         |\n| 返回值         | 不适用           | 仅摘要文本                    |\n\n## 试一试\n\n```sh\ncd learn-claude-code\npython agents/s04_subagent.py\n```\n\n试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):\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"
+    "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 (Skill 加载)",
-    "content": "# s05: Skills (Skill 加载)\n\n`s01 > s02 > s03 > s04 > [ s05 ] s06 | s07 > s08 > s09 > s10 > s11 > s12`\n\n> *\"用到什么知识, 临时加载什么知识\"* -- 通过 tool_result 注入, 不塞 system prompt。\n\n## 问题\n\n你希望 Agent 遵循特定领域的工作流: git 约定、测试模式、代码审查清单。全塞进系统提示太浪费 -- 10 个 Skill, 每个 2000 token, 就是 20,000 token, 大部分跟当前任务毫无关系。\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第一层: 系统提示中放 Skill 名称 (低成本)。第二层: tool_result 中按需放完整内容。\n\n## 工作原理\n\n1. 每个 Skill 是一个目录, 包含 `SKILL.md` 文件和 YAML frontmatter。\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` 文件, 用目录名作为 Skill 标识。\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. 第一层写入系统提示。第二层不过是 dispatch map 中的又一个工具。\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模型知道有哪些 Skill (便宜), 需要时再加载完整内容 (贵)。\n\n## 相对 s04 的变更\n\n| 组件           | 之前 (s04)       | 之后 (s05)                     |\n|----------------|------------------|--------------------------------|\n| Tools          | 5 (基础 + task)  | 5 (基础 + load_skill)          |\n| 系统提示       | 静态字符串       | + Skill 描述列表               |\n| 知识库         | 无               | skills/\\*/SKILL.md 文件        |\n| 注入方式       | 无               | 两层 (系统提示 + result)       |\n\n## 试一试\n\n```sh\ncd learn-claude-code\npython agents/s05_skill_loading.py\n```\n\n试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):\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"
+    "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 (上下文压缩)",
-    "content": "# s06: Context Compact (上下文压缩)\n\n`s01 > s02 > s03 > s04 > s05 > [ s06 ] | s07 > s08 > s09 > s10 > s11 > s12`\n\n> *\"上下文总会满, 要有办法腾地方\"* -- 三层压缩策略, 换来无限会话。\n\n## 问题\n\n上下文窗口是有限的。读一个 1000 行的文件就吃掉 ~4000 token; 读 30 个文件、跑 20 条命令, 轻松突破 100k token。不压缩, Agent 根本没法在大项目里干活。\n\n## 解决方案\n\n三层压缩, 激进程度递增:\n\n```\nEvery turn:\n+------------------+\n| Tool call result |\n+------------------+\n        |\n        v\n[Layer 1: micro_compact]        (silent, every turn)\n  Replace tool_result > 3 turns old\n  with \"[Previous: used {tool_name}]\"\n        |\n        v\n[Check: tokens > 50000?]\n   |               |\n   no              yes\n   |               |\n   v               v\ncontinue    [Layer 2: auto_compact]\n              Save transcript to .transcripts/\n              LLM summarizes conversation.\n              Replace all messages with [summary].\n                    |\n                    v\n            [Layer 3: compact tool]\n              Model calls compact explicitly.\n              Same summarization as auto_compact.\n```\n\n## 工作原理\n\n1. **第一层 -- micro_compact**: 每次 LLM 调用前, 将旧的 tool result 替换为占位符。\n\n```python\ndef micro_compact(messages: list) -> list:\n    tool_results = []\n    for i, msg in enumerate(messages):\n        if msg[\"role\"] == \"user\" and isinstance(msg.get(\"content\"), list):\n            for j, part in enumerate(msg[\"content\"]):\n                if isinstance(part, dict) and part.get(\"type\") == \"tool_result\":\n                    tool_results.append((i, j, part))\n    if len(tool_results) <= KEEP_RECENT:\n        return messages\n    for _, _, part in tool_results[:-KEEP_RECENT]:\n        if len(part.get(\"content\", \"\")) > 100:\n            part[\"content\"] = f\"[Previous: used {tool_name}]\"\n    return messages\n```\n\n2. **第二层 -- auto_compact**: token 超过阈值时, 保存完整对话到磁盘, 让 LLM 做摘要。\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]}],\n        max_tokens=2000,\n    )\n    return [\n        {\"role\": \"user\", \"content\": f\"[Compressed]\\n\\n{response.content[0].text}\"},\n        {\"role\": \"assistant\", \"content\": \"Understood. Continuing.\"},\n    ]\n```\n\n3. **第三层 -- manual compact**: `compact` 工具按需触发同样的摘要机制。\n\n4. 循环整合三层:\n\n```python\ndef agent_loop(messages: list):\n    while True:\n        micro_compact(messages)                        # Layer 1\n        if estimate_tokens(messages) > THRESHOLD:\n            messages[:] = auto_compact(messages)       # Layer 2\n        response = client.messages.create(...)\n        # ... tool execution ...\n        if manual_compact:\n            messages[:] = auto_compact(messages)       # Layer 3\n```\n\n完整历史通过 transcript 保存在磁盘上。信息没有真正丢失, 只是移出了活跃上下文。\n\n## 相对 s05 的变更\n\n| 组件           | 之前 (s05)       | 之后 (s06)                     |\n|----------------|------------------|--------------------------------|\n| Tools          | 5                | 5 (基础 + compact)             |\n| 上下文管理     | 无               | 三层压缩                       |\n| Micro-compact  | 无               | 旧结果 -> 占位符               |\n| Auto-compact   | 无               | token 阈值触发                 |\n| Transcripts    | 无               | 保存到 .transcripts/           |\n\n## 试一试\n\n```sh\ncd learn-claude-code\npython agents/s06_context_compact.py\n```\n\n试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):\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"
+    "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: Task System (任务系统)",
-    "content": "# s07: Task System (任务系统)\n\n`s01 > s02 > s03 > s04 > s05 > s06 | [ s07 ] s08 > s09 > s10 > s11 > s12`\n\n> *\"大目标要拆成小任务, 排好序, 记在磁盘上\"* -- 文件持久化的任务图, 为多 agent 协作打基础。\n\n## 问题\n\ns03 的 TodoManager 只是内存中的扁平清单: 没有顺序、没有依赖、状态只有做完没做完。真实目标是有结构的 -- 任务 B 依赖任务 A, 任务 C 和 D 可以并行, 任务 E 要等 C 和 D 都完成。\n\n没有显式的关系, Agent 分不清什么能做、什么被卡住、什么能同时跑。而且清单只活在内存里, 上下文压缩 (s06) 一跑就没了。\n\n## 解决方案\n\n把扁平清单升级为持久化到磁盘的**任务图**。每个任务是一个 JSON 文件, 有状态、前置依赖 (`blockedBy`) 和后置依赖 (`blocks`)。任务图随时回答三个问题:\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这个任务图是 s07 之后所有机制的协调骨架: 后台执行 (s08)、多 agent 团队 (s09+)、worktree 隔离 (s12) 都读写这同一个结构。\n\n## 工作原理\n\n1. **TaskManager**: 每个任务一个 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                \"blocks\": [], \"owner\": \"\"}\n        self._save(task)\n        self._next_id += 1\n        return json.dumps(task, indent=2)\n```\n\n2. **依赖解除**: 完成任务时, 自动将其 ID 从其他任务的 `blockedBy` 中移除, 解锁后续任务。\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, 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\n4. 四个任务工具加入 dispatch map。\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从 s07 起, 任务图是多步工作的默认选择。s03 的 Todo 仍可用于单次会话内的快速清单。\n\n## 相对 s06 的变更\n\n| 组件 | 之前 (s06) | 之后 (s07) |\n|---|---|---|\n| Tools | 5 | 8 (`task_create/update/list/get`) |\n| 规划模型 | 扁平清单 (仅内存) | 带依赖关系的任务图 (磁盘) |\n| 关系 | 无 | `blockedBy` + `blocks` 边 |\n| 状态追踪 | 做完没做完 | `pending` -> `in_progress` -> `completed` |\n| 持久化 | 压缩后丢失 | 压缩和重启后存活 |\n\n## 试一试\n\n```sh\ncd learn-claude-code\npython agents/s07_task_system.py\n```\n\n试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):\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"
+    "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: Background Tasks (后台任务)",
-    "content": "# s08: Background Tasks (后台任务)\n\n`s01 > s02 > s03 > s04 > s05 > s06 | s07 > [ s08 ] s09 > s10 > s11 > s12`\n\n> *\"慢操作丢后台, agent 继续想下一步\"* -- 后台线程跑命令, 完成后注入通知。\n\n## 问题\n\n有些命令要跑好几分钟: `npm install`、`pytest`、`docker build`。阻塞式循环下模型只能干等。用户说 \"装依赖, 顺便建个配置文件\", Agent 却只能一个一个来。\n\n## 解决方案\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## 工作原理\n\n1. BackgroundManager 用线程安全的通知队列追踪任务。\n\n```python\nclass BackgroundManager:\n    def __init__(self):\n        self.tasks = {}\n        self._notification_queue = []\n        self._lock = threading.Lock()\n```\n\n2. `run()` 启动守护线程, 立即返回。\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\n3. 子进程完成后, 结果进入通知队列。\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\n4. 每次 LLM 调用前排空通知队列。\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\n循环保持单线程。只有子进程 I/O 被并行化。\n\n## 相对 s07 的变更\n\n| 组件           | 之前 (s07)       | 之后 (s08)                         |\n|----------------|------------------|------------------------------------|\n| Tools          | 8                | 6 (基础 + background_run + check)  |\n| 执行方式       | 仅阻塞           | 阻塞 + 后台线程                    |\n| 通知机制       | 无               | 每轮排空的队列                     |\n| 并发           | 无               | 守护线程                           |\n\n## 试一试\n\n```sh\ncd learn-claude-code\npython agents/s08_background_tasks.py\n```\n\n试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):\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"
+    "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: Agent Teams (Agent 团队)",
-    "content": "# s09: Agent Teams (Agent 团队)\n\n`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > [ s09 ] s10 > s11 > s12`\n\n> *\"任务太大一个人干不完, 要能分给队友\"* -- 持久化队友 + JSONL 邮箱。\n\n## 问题\n\nSubagent (s04) 是一次性的: 生成、干活、返回摘要、消亡。没有身份, 没有跨调用的记忆。Background Tasks (s08) 能跑 shell 命令, 但做不了 LLM 引导的决策。\n\n真正的团队协作需要三样东西: (1) 能跨多轮对话存活的持久 Agent, (2) 身份和生命周期管理, (3) Agent 之间的通信通道。\n\n## 解决方案\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## 工作原理\n\n1. TeammateManager 通过 config.json 维护团队名册。\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\n2. `spawn()` 创建队友并在线程中启动 agent loop。\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\n3. MessageBus: append-only 的 JSONL 收件箱。`send()` 追加一行; `read_inbox()` 读取全部并清空。\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\n4. 每个队友在每次 LLM 调用前检查收件箱, 将消息注入上下文。\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## 相对 s08 的变更\n\n| 组件           | 之前 (s08)       | 之后 (s09)                         |\n|----------------|------------------|------------------------------------|\n| Tools          | 6                | 9 (+spawn/send/read_inbox)         |\n| Agent 数量     | 单一             | 领导 + N 个队友                    |\n| 持久化         | 无               | config.json + JSONL 收件箱         |\n| 线程           | 后台命令         | 每线程完整 agent loop              |\n| 生命周期       | 一次性           | idle -> working -> idle            |\n| 通信           | 无               | message + broadcast                |\n\n## 试一试\n\n```sh\ncd learn-claude-code\npython agents/s09_agent_teams.py\n```\n\n试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):\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. 输入 `/team` 查看团队名册和状态\n5. 输入 `/inbox` 手动检查领导的收件箱\n"
+    "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: Team Protocols (团队协议)",
-    "content": "# s10: Team Protocols (团队协议)\n\n`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > [ s10 ] s11 > s12`\n\n> *\"队友之间要有统一的沟通规矩\"* -- 一个 request-response 模式驱动所有协商。\n\n## 问题\n\ns09 中队友能干活能通信, 但缺少结构化协调:\n\n**关机**: 直接杀线程会留下写了一半的文件和过期的 config.json。需要握手 -- 领导请求, 队友批准 (收尾退出) 或拒绝 (继续干)。\n\n**计划审批**: 领导说 \"重构认证模块\", 队友立刻开干。高风险变更应该先过审。\n\n两者结构一样: 一方发带唯一 ID 的请求, 另一方引用同一 ID 响应。\n\n## 解决方案\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## 工作原理\n\n1. 领导生成 request_id, 通过收件箱发起关机请求。\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\n2. 队友收到请求后, 用 approve/reject 响应。\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\n3. 计划审批遵循完全相同的模式。队友提交计划 (生成 request_id), 领导审查 (引用同一个 request_id)。\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\n一个 FSM, 两种用途。同样的 `pending -> approved | rejected` 状态机可以套用到任何请求-响应协议上。\n\n## 相对 s09 的变更\n\n| 组件           | 之前 (s09)       | 之后 (s10)                           |\n|----------------|------------------|--------------------------------------|\n| Tools          | 9                | 12 (+shutdown_req/resp +plan)        |\n| 关机           | 仅自然退出       | 请求-响应握手                        |\n| 计划门控       | 无               | 提交/审查与审批                      |\n| 关联           | 无               | 每个请求一个 request_id              |\n| FSM            | 无               | pending -> approved/rejected         |\n\n## 试一试\n\n```sh\ncd learn-claude-code\npython agents/s10_team_protocols.py\n```\n\n试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):\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. 输入 `/team` 监控状态\n"
+    "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: Autonomous Agents (Autonomous Agent)",
-    "content": "# s11: Autonomous Agents (Autonomous Agent)\n\n`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > [ s11 ] s12`\n\n> *\"队友自己看看板, 有活就认领\"* -- 不需要领导逐个分配, 自组织。\n\n## 问题\n\ns09-s10 中, 队友只在被明确指派时才动。领导得给每个队友写 prompt, 任务看板上 10 个未认领的任务得手动分配。这扩展不了。\n\n真正的自治: 队友自己扫描任务看板, 认领没人做的任务, 做完再找下一个。\n\n一个细节: Context Compact (s06) 后 Agent 可能忘了自己是谁。身份重注入解决这个问题。\n\n## 解决方案\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## 工作原理\n\n1. 队友循环分两个阶段: WORK 和 IDLE。LLM 停止调用工具 (或调用了 `idle`) 时, 进入 IDLE。\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\n2. 空闲阶段循环轮询收件箱和任务看板。\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\n3. 任务看板扫描: 找 pending 状态、无 owner、未被阻塞的任务。\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\n4. 身份重注入: 上下文过短 (说明发生了压缩) 时, 在开头插入身份块。\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## 相对 s10 的变更\n\n| 组件           | 之前 (s10)       | 之后 (s11)                       |\n|----------------|------------------|----------------------------------|\n| Tools          | 12               | 14 (+idle, +claim_task)          |\n| 自治性         | 领导指派         | 自组织                           |\n| 空闲阶段       | 无               | 轮询收件箱 + 任务看板            |\n| 任务认领       | 仅手动           | 自动认领未分配任务               |\n| 身份           | 系统提示         | + 压缩后重注入                   |\n| 超时           | 无               | 60 秒空闲 -> 自动关机            |\n\n## 试一试\n\n```sh\ncd learn-claude-code\npython agents/s11_autonomous_agents.py\n```\n\n试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):\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. 输入 `/tasks` 查看带 owner 的任务看板\n5. 输入 `/team` 监控谁在工作、谁在空闲\n"
+    "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": "s12: Worktree + Task Isolation (Worktree 任务隔离)",
-    "content": "# s12: Worktree + Task Isolation (Worktree 任务隔离)\n\n`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > [ s12 ]`\n\n> *\"各干各的目录, 互不干扰\"* -- 任务管目标, worktree 管目录, 按 ID 绑定。\n\n## 问题\n\n到 s11, Agent 已经能自主认领和完成任务。但所有任务共享一个目录。两个 Agent 同时重构不同模块 -- A 改 `config.py`, B 也改 `config.py`, 未提交的改动互相污染, 谁也没法干净回滚。\n\n任务板管 \"做什么\" 但不管 \"在哪做\"。解法: 给每个任务一个独立的 git worktree 目录, 用任务 ID 把两边关联起来。\n\n## 解决方案\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## 工作原理\n\n1. **创建任务。** 先把目标持久化。\n\n```python\nTASKS.create(\"Implement auth refactor\")\n# -> .tasks/task_1.json  status=pending  worktree=\"\"\n```\n\n2. **创建 worktree 并绑定任务。** 传入 `task_id` 自动将任务推进到 `in_progress`。\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\n绑定同时写入两侧状态:\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\n3. **在 worktree 中执行命令。** `cwd` 指向隔离目录。\n\n```python\nsubprocess.run(command, shell=True, cwd=worktree_path,\n               capture_output=True, text=True, timeout=300)\n```\n\n4. **收尾。** 两种选择:\n   - `worktree_keep(name)` -- 保留目录供后续使用。\n   - `worktree_remove(name, complete_task=True)` -- 删除目录, 完成绑定任务, 发出事件。一个调用搞定拆除 + 完成。\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\n5. **事件流。** 每个生命周期步骤写入 `.worktrees/events.jsonl`:\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\n事件类型: `worktree.create.before/after/failed`, `worktree.remove.before/after/failed`, `worktree.keep`, `task.completed`。\n\n崩溃后从 `.tasks/` + `.worktrees/index.json` 重建现场。会话记忆是易失的; 磁盘状态是持久的。\n\n## 相对 s11 的变更\n\n| 组件               | 之前 (s11)                 | 之后 (s12)                                   |\n|--------------------|----------------------------|----------------------------------------------|\n| 协调               | 任务板 (owner/status)      | 任务板 + worktree 显式绑定                   |\n| 执行范围           | 共享目录                   | 每个任务独立目录                             |\n| 可恢复性           | 仅任务状态                 | 任务状态 + worktree 索引                     |\n| 收尾               | 任务完成                   | 任务完成 + 显式 keep/remove                  |\n| 生命周期可见性     | 隐式日志                   | `.worktrees/events.jsonl` 显式事件流         |\n\n## 试一试\n\n```sh\ncd learn-claude-code\npython agents/s12_worktree_task_isolation.py\n```\n\n试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):\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"
+    "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 1 の Deep Agents トラック\n\n手書き版の `agents/s01-s06` を読んだ後で、`agents_deepagents/s01_agent_loop.py` から `agents_deepagents/s06_context_compact.py` を Deep Agents トラックとして読めます。既存の `agents/*.py` は変更せず、OpenAI 形式の `OPENAI_API_KEY` / `OPENAI_MODEL`（必要なら `OPENAI_BASE_URL`）を使いながら、能力は章ごとに段階的に開放されます。つまり `s01` は最小 loop のまま、`s03` で planning、`s04` で subagent、`s05` で skills、`s06` で context compact が入ります。現時点では web UI には表示しません。\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",
-    "content": "# s01: The Agent Loop\n\n`[ s01 ] s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`\n\n> *\"One loop & Bash is all you need\"* -- 1つのツール + 1つのループ = エージェント。\n\n## 問題\n\n言語モデルはコードについて推論できるが、現実世界に触れられない。ファイルを読めず、テストを実行できず、エラーを確認できない。ループがなければ、ツール呼び出しのたびにユーザーが手動で結果をコピーペーストする必要がある。つまりユーザー自身がループになる。\n\n## 解決策\n\n```\n+--------+      +-------+      +---------+\n|  User  | ---> |  LLM  | ---> |  Tool   |\n| prompt |      |       |      | execute |\n+--------+      +---+---+      +----+----+\n                    ^                |\n                    |   tool_result  |\n                    +----------------+\n                    (loop until stop_reason != \"tool_use\")\n```\n\n1つの終了条件がフロー全体を制御する。モデルがツール呼び出しを止めるまでループが回り続ける。\n\n## 仕組み\n\n1. ユーザーのプロンプトが最初のメッセージになる。\n\n```python\nmessages.append({\"role\": \"user\", \"content\": query})\n```\n\n2. メッセージとツール定義をLLMに送信する。\n\n```python\nresponse = client.messages.create(\n    model=MODEL, system=SYSTEM, messages=messages,\n    tools=TOOLS, max_tokens=8000,\n)\n```\n\n3. アシスタントのレスポンスを追加し、`stop_reason`を確認する。ツールが呼ばれなければ終了。\n\n```python\nmessages.append({\"role\": \"assistant\", \"content\": response.content})\nif response.stop_reason != \"tool_use\":\n    return\n```\n\n4. 各ツール呼び出しを実行し、結果を収集してuserメッセージとして追加。ステップ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,\n            \"content\": output,\n        })\nmessages.append({\"role\": \"user\", \"content\": results})\n```\n\n1つの関数にまとめると:\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\n\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                output = run_bash(block.input[\"command\"])\n                results.append({\n                    \"type\": \"tool_result\",\n                    \"tool_use_id\": block.id,\n                    \"content\": output,\n                })\n        messages.append({\"role\": \"user\", \"content\": results})\n```\n\nこれでエージェント全体が30行未満に収まる。本コースの残りはすべてこのループの上に積み重なる -- ループ自体は変わらない。\n\n## 変更点\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## 試してみる\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"
+    "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",
-    "content": "# s02: Tool Use\n\n`s01 > [ s02 ] s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`\n\n> *\"ツールを足すなら、ハンドラーを1つ足すだけ\"* -- ループは変わらない。新ツールは dispatch map に登録するだけ。\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"
+    "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",
-    "content": "# s03: TodoWrite\n\n`s01 > s02 > [ s03 ] s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`\n\n> *\"計画のないエージェントは行き当たりばったり\"* -- まずステップを書き出し、それから実行。\n\n## 問題\n\nマルチステップのタスクで、モデルは途中で迷子になる。作業を繰り返したり、ステップを飛ばしたり、脱線したりする。長い会話になるほど悪化する -- ツール結果がコンテキストを埋めるにつれ、システムプロンプトの影響力が薄れる。10ステップのリファクタリングでステップ1-3を完了した後、残りを忘れて即興を始めてしまう。\n\n## 解決策\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## 仕組み\n\n1. TodoManagerはアイテムのリストをステータス付きで保持する。`in_progress`にできるのは同時に1つだけ。\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()\n```\n\n2. `todo`ツールは他のツールと同様にディスパッチマップに追加される。\n\n```python\nTOOL_HANDLERS = {\n    # ...base tools...\n    \"todo\": lambda **kw: TODO.update(kw[\"items\"]),\n}\n```\n\n3. nagリマインダーが、モデルが3ラウンド以上`todo`を呼ばなかった場合にナッジを注入する。\n\n```python\nif rounds_since_todo >= 3 and messages:\n    last = messages[-1]\n    if last[\"role\"] == \"user\" and isinstance(last.get(\"content\"), list):\n        last[\"content\"].insert(0, {\n            \"type\": \"text\",\n            \"text\": \"<reminder>Update your todos.</reminder>\",\n        })\n```\n\n「一度にin_progressは1つだけ」の制約が逐次的な集中を強制し、nagリマインダーが説明責任を生む。\n\n## 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## 試してみる\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"
+    "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",
-    "content": "# s04: Subagents\n\n`s01 > s02 > s03 > [ s04 ] s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`\n\n> *\"大きなタスクを分割し、各サブタスクにクリーンなコンテキストを\"* -- サブエージェントは独立した messages[] を使い、メイン会話を汚さない。\n\n## 問題\n\nエージェントが作業するにつれ、messages配列は膨張し続ける。すべてのファイル読み取り、すべてのbash出力がコンテキストに永久に残る。「このプロジェクトはどのテストフレームワークを使っているか」という質問は5つのファイルを読む必要があるかもしれないが、親に必要なのは「pytest」という答えだけだ。\n\n## 解決策\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## 仕組み\n\n1. 親に`task`ツールを追加する。子は`task`を除くすべての基本ツールを取得する(再帰的な生成は不可)。\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\n2. サブエージェントは`messages=[]`で開始し、自身のループを実行する。最終テキストだけが親に返る。\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    return \"\".join(\n        b.text for b in response.content if hasattr(b, \"text\")\n    ) or \"(no summary)\"\n```\n\n子のメッセージ履歴全体(30回以上のツール呼び出し)は破棄される。親は1段落の要約を通常の`tool_result`として受け取る。\n\n## 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## 試してみる\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"
+    "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",
-    "content": "# s05: Skills\n\n`s01 > s02 > s03 > s04 > [ s05 ] s06 | s07 > s08 > s09 > s10 > s11 > s12`\n\n> *\"必要な知識を、必要な時に読み込む\"* -- system prompt ではなく tool_result で注入。\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"
+    "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",
-    "content": "# s06: Context Compact\n\n`s01 > s02 > s03 > s04 > s05 > [ s06 ] | s07 > s08 > s09 > s10 > s11 > s12`\n\n> *\"コンテキストはいつか溢れる、空ける手段が要る\"* -- 3層圧縮で無限セッションを実現。\n\n## 問題\n\nコンテキストウィンドウは有限だ。1000行のファイルに対する`read_file`1回で約4000トークンを消費する。30ファイルを読み20回のbashコマンドを実行すると、100,000トークン超。圧縮なしでは、エージェントは大規模コードベースで作業できない。\n\n## 解決策\n\n積極性を段階的に上げる3層構成:\n\n```\nEvery turn:\n+------------------+\n| Tool call result |\n+------------------+\n        |\n        v\n[Layer 1: micro_compact]        (silent, every turn)\n  Replace tool_result > 3 turns old\n  with \"[Previous: used {tool_name}]\"\n        |\n        v\n[Check: tokens > 50000?]\n   |               |\n   no              yes\n   |               |\n   v               v\ncontinue    [Layer 2: auto_compact]\n              Save transcript to .transcripts/\n              LLM summarizes conversation.\n              Replace all messages with [summary].\n                    |\n                    v\n            [Layer 3: compact tool]\n              Model calls compact explicitly.\n              Same summarization as auto_compact.\n```\n\n## 仕組み\n\n1. **第1層 -- micro_compact**: 各LLM呼び出しの前に、古いツール結果をプレースホルダーに置換する。\n\n```python\ndef micro_compact(messages: list) -> list:\n    tool_results = []\n    for i, msg in enumerate(messages):\n        if msg[\"role\"] == \"user\" and isinstance(msg.get(\"content\"), list):\n            for j, part in enumerate(msg[\"content\"]):\n                if isinstance(part, dict) and part.get(\"type\") == \"tool_result\":\n                    tool_results.append((i, j, part))\n    if len(tool_results) <= KEEP_RECENT:\n        return messages\n    for _, _, part in tool_results[:-KEEP_RECENT]:\n        if len(part.get(\"content\", \"\")) > 100:\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    # 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]}],\n        max_tokens=2000,\n    )\n    return [\n        {\"role\": \"user\", \"content\": f\"[Compressed]\\n\\n{response.content[0].text}\"},\n        {\"role\": \"assistant\", \"content\": \"Understood. Continuing.\"},\n    ]\n```\n\n3. **第3層 -- manual compact**: `compact`ツールが同じ要約処理をオンデマンドでトリガーする。\n\n4. ループが3層すべてを統合する:\n\n```python\ndef agent_loop(messages: list):\n    while True:\n        micro_compact(messages)                        # Layer 1\n        if estimate_tokens(messages) > THRESHOLD:\n            messages[:] = auto_compact(messages)       # Layer 2\n        response = client.messages.create(...)\n        # ... tool execution ...\n        if manual_compact:\n            messages[:] = auto_compact(messages)       # Layer 3\n```\n\nトランスクリプトがディスク上に完全な履歴を保持する。何も真に失われず、アクティブなコンテキストの外に移動されるだけ。\n\n## s05からの変更点\n\n| Component      | Before (s05)     | After (s06)                |\n|----------------|------------------|----------------------------|\n| Tools          | 5                | 5 (base + compact)         |\n| Context mgmt   | None             | Three-layer compression    |\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"
+    "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: Task System",
-    "content": "# s07: Task System\n\n`s01 > s02 > s03 > s04 > s05 > s06 | [ s07 ] s08 > s09 > s10 > s11 > s12`\n\n> *\"大きな目標を小タスクに分解し、順序付けし、ディスクに記録する\"* -- ファイルベースのタスクグラフ、マルチエージェント協調の基盤。\n\n## 問題\n\ns03のTodoManagerはメモリ上のフラットなチェックリストに過ぎない: 順序なし、依存関係なし、ステータスは完了か未完了のみ。実際の目標には構造がある -- タスクBはタスクAに依存し、タスクCとDは並行実行でき、タスクEはCとDの両方を待つ。\n\n明示的な関係がなければ、エージェントは何が実行可能で、何がブロックされ、何が同時に走れるかを判断できない。しかもリストはメモリ上にしかないため、コンテキスト圧縮(s06)で消える。\n\n## 解決策\n\nフラットなチェックリストをディスクに永続化する**タスクグラフ**に昇格させる。各タスクは1つのJSONファイルで、ステータス・前方依存(`blockedBy`)・後方依存(`blocks`)を持つ。タスクグラフは常に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このタスクグラフは s07 以降の全メカニズムの協調バックボーンとなる: バックグラウンド実行(s08)、マルチエージェントチーム(s09+)、worktree分離(s12)はすべてこの同じ構造を読み書きする。\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                \"blocks\": [], \"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, 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\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\ns07以降、タスクグラフがマルチステップ作業のデフォルト。s03のTodoは軽量な単一セッション用チェックリストとして残る。\n\n## s06からの変更点\n\n| コンポーネント | Before (s06) | After (s07) |\n|---|---|---|\n| Tools | 5 | 8 (`task_create/update/list/get`) |\n| 計画モデル | フラットチェックリスト (メモリ) | 依存関係付きタスクグラフ (ディスク) |\n| 関係 | なし | `blockedBy` + `blocks` エッジ |\n| ステータス追跡 | 完了か未完了 | `pending` -> `in_progress` -> `completed` |\n| 永続性 | 圧縮で消失 | 圧縮・再起動後も存続 |\n\n## 試してみる\n\n```sh\ncd learn-claude-code\npython agents/s07_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"
+    "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: Background Tasks",
-    "content": "# s08: Background Tasks\n\n`s01 > s02 > s03 > s04 > s05 > s06 | s07 > [ s08 ] s09 > s10 > s11 > s12`\n\n> *\"遅い操作はバックグラウンドへ、エージェントは次を考え続ける\"* -- デーモンスレッドがコマンド実行、完了後に通知を注入。\n\n## 問題\n\n一部のコマンドは数分かかる: `npm install`、`pytest`、`docker build`。ブロッキングループでは、モデルはサブプロセスの完了を待って座っている。ユーザーが「依存関係をインストールして、その間にconfigファイルを作って」と言っても、エージェントは並列ではなく逐次的に処理する。\n\n## 解決策\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## 仕組み\n\n1. BackgroundManagerがスレッドセーフな通知キューでタスクを追跡する。\n\n```python\nclass BackgroundManager:\n    def __init__(self):\n        self.tasks = {}\n        self._notification_queue = []\n        self._lock = threading.Lock()\n```\n\n2. `run()`がデーモンスレッドを開始し、即座にリターンする。\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\n3. サブプロセス完了時に、結果を通知キューへ。\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\n4. エージェントループが各LLM呼び出しの前に通知をドレインする。\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\nループはシングルスレッドのまま。サブプロセスI/Oだけが並列化される。\n\n## s07からの変更点\n\n| Component      | Before (s07)     | After (s08)                |\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## 試してみる\n\n```sh\ncd learn-claude-code\npython agents/s08_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"
+    "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: Agent Teams",
-    "content": "# s09: Agent Teams\n\n`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > [ s09 ] s10 > s11 > s12`\n\n> *\"一人で終わらないなら、チームメイトに任せる\"* -- 永続チームメイト + 非同期メールボックス。\n\n## 問題\n\nサブエージェント(s04)は使い捨てだ: 生成し、作業し、要約を返し、消滅する。アイデンティティもなく、呼び出し間の記憶もない。バックグラウンドタスク(s08)はシェルコマンドを実行するが、LLM誘導の意思決定はできない。\n\n本物のチームワークには: (1)単一プロンプトを超えて存続する永続エージェント、(2)アイデンティティとライフサイクル管理、(3)エージェント間の通信チャネルが必要だ。\n\n## 解決策\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## 仕組み\n\n1. TeammateManagerがconfig.jsonでチーム名簿を管理する。\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\n2. `spawn()`がチームメイトを作成し、そのエージェントループをスレッドで開始する。\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\n3. MessageBus: 追記専用のJSONLインボックス。`send()`がJSON行を追記し、`read_inbox()`がすべて読み取ってドレインする。\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\n4. 各チームメイトは各LLM呼び出しの前にインボックスを確認し、受信メッセージをコンテキストに注入する。\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## s08からの変更点\n\n| Component      | Before (s08)     | After (s09)                |\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## 試してみる\n\n```sh\ncd learn-claude-code\npython agents/s09_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. `/team`と入力してステータス付きのチーム名簿を確認する\n5. `/inbox`と入力してリーダーのインボックスを手動確認する\n"
+    "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": "s10: Team Protocols",
-    "content": "# s10: Team Protocols\n\n`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > [ s10 ] s11 > s12`\n\n> *\"チームメイト間には統一の通信ルールが必要\"* -- 1つの request-response パターンが全交渉を駆動。\n\n## 問題\n\ns09ではチームメイトが作業し通信するが、構造化された協調がない:\n\n**シャットダウン**: スレッドを強制終了するとファイルが中途半端に書かれ、config.jsonが不正な状態になる。ハンドシェイクが必要 -- リーダーが要求し、チームメイトが承認(完了して退出)か拒否(作業継続)する。\n\n**プラン承認**: リーダーが「認証モジュールをリファクタリングして」と言うと、チームメイトは即座に開始する。リスクの高い変更では、実行前にリーダーが計画をレビューすべきだ。\n\n両方とも同じ構造: 一方がユニークIDを持つリクエストを送り、他方がそのIDで応答する。\n\n## 解決策\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## 仕組み\n\n1. リーダーがrequest_idを生成し、インボックス経由でシャットダウンを開始する。\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\n2. チームメイトがリクエストを受信し、承認または拒否で応答する。\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\n3. プラン承認も同一パターン。チームメイトがプランを提出(request_idを生成)、リーダーがレビュー(同じrequest_idを参照)。\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\n1つのFSM、2つの応用。同じ`pending -> approved | rejected`状態機械が、あらゆるリクエスト-レスポンスプロトコルに適用できる。\n\n## s09からの変更点\n\n| Component      | Before (s09)     | After (s10)                  |\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## 試してみる\n\n```sh\ncd learn-claude-code\npython agents/s10_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. `/team`と入力してステータスを監視する\n"
+    "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: Autonomous Agents",
-    "content": "# s11: Autonomous Agents\n\n`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > [ s11 ] s12`\n\n> *\"チームメイトが自らボードを見て、仕事を取る\"* -- リーダーが逐一割り振る必要はない。\n\n## 問題\n\ns09-s10では、チームメイトは明示的に指示された時のみ作業する。リーダーは各チームメイトを特定のプロンプトでspawnしなければならない。タスクボードに未割り当てのタスクが10個あっても、リーダーが手動で各タスクを割り当てる。これはスケールしない。\n\n真の自律性とは、チームメイトが自分で作業を見つけること: タスクボードをスキャンし、未確保のタスクを確保し、作業し、完了したら次を探す。\n\nもう1つの問題: コンテキスト圧縮(s06)後にエージェントが自分の正体を忘れる可能性がある。アイデンティティ再注入がこれを解決する。\n\n## 解決策\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## 仕組み\n\n1. チームメイトのループはWORKとIDLEの2フェーズ。LLMがツール呼び出しを止めた時(または`idle`ツールを呼んだ時)、IDLEフェーズに入る。\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\n2. IDLEフェーズがインボックスとタスクボードをポーリングする。\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\n3. タスクボードスキャン: pendingかつ未割り当てかつブロックされていないタスクを探す。\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\n4. アイデンティティ再注入: コンテキストが短すぎる(圧縮が起きた)場合にアイデンティティブロックを挿入する。\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## s10からの変更点\n\n| Component      | Before (s10)     | After (s11)                |\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## 試してみる\n\n```sh\ncd learn-claude-code\npython agents/s11_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. `/tasks`と入力してオーナー付きのタスクボードを確認する\n5. `/team`と入力して誰が作業中でアイドルかを監視する\n"
+    "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": "s12: Worktree + Task Isolation",
-    "content": "# s12: Worktree + Task Isolation\n\n`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > [ s12 ]`\n\n> *\"各自のディレクトリで作業し、互いに干渉しない\"* -- タスクは目標を管理、worktree はディレクトリを管理、IDで紐付け。\n\n## 問題\n\ns11までにエージェントはタスクを自律的に確保して完了できるようになった。しかし全タスクが1つの共有ディレクトリで走る。2つのエージェントが同時に異なるモジュールをリファクタリングすると衝突する: 片方が`config.py`を編集し、もう片方も`config.py`を編集し、未コミットの変更が混ざり合い、どちらもクリーンにロールバックできない。\n\nタスクボードは*何をやるか*を追跡するが、*どこでやるか*には関知しない。解決策: 各タスクに専用のgit worktreeディレクトリを与える。タスクが目標を管理し、worktreeが実行コンテキストを管理する。タスクIDで紐付ける。\n\n## 解決策\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## 仕組み\n\n1. **タスクを作成する。** まず目標を永続化する。\n\n```python\nTASKS.create(\"Implement auth refactor\")\n# -> .tasks/task_1.json  status=pending  worktree=\"\"\n```\n\n2. **worktreeを作成してタスクに紐付ける。** `task_id`を渡すと、タスクが自動的に`in_progress`に遷移する。\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\n紐付けは両側に状態を書き込む:\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\n3. **worktree内でコマンドを実行する。** `cwd`が分離ディレクトリを指す。\n\n```python\nsubprocess.run(command, shell=True, cwd=worktree_path,\n               capture_output=True, text=True, timeout=300)\n```\n\n4. **終了処理。** 2つの選択肢:\n   - `worktree_keep(name)` -- ディレクトリを保持する。\n   - `worktree_remove(name, complete_task=True)` -- ディレクトリを削除し、紐付けられたタスクを完了し、イベントを発行する。1回の呼び出しで後片付けと完了を処理する。\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\n5. **イベントストリーム。** ライフサイクルの各ステップが`.worktrees/events.jsonl`に記録される:\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\n発行されるイベント: `worktree.create.before/after/failed`, `worktree.remove.before/after/failed`, `worktree.keep`, `task.completed`。\n\nクラッシュ後も`.tasks/` + `.worktrees/index.json`から状態を再構築できる。会話メモリは揮発性だが、ファイル状態は永続的だ。\n\n## s11からの変更点\n\n| Component          | Before (s11)               | After (s12)                                  |\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## 試してみる\n\n```sh\ncd learn-claude-code\npython agents/s12_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"
+    "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"
   }
 ]
\ No newline at end of file
diff --git a/web/src/data/generated/versions.json b/web/src/data/generated/versions.json
index 0af62b7b5..a33fca6ac 100644
--- a/web/src/data/generated/versions.json
+++ b/web/src/data/generated/versions.json
@@ -4,38 +4,59 @@
       "id": "s01",
       "filename": "s01_agent_loop.py",
       "title": "The Agent Loop",
-      "subtitle": "Bash is All You Need",
-      "loc": 84,
+      "subtitle": "Minimal Closed Loop",
+      "loc": 130,
       "tools": [
         "bash"
       ],
       "newTools": [
         "bash"
       ],
-      "coreAddition": "Single-tool agent loop",
-      "keyInsight": "The minimal agent kernel is a while loop + one tool",
-      "classes": [],
+      "coreAddition": "LoopState + tool_result feedback",
+      "keyInsight": "An agent is just a loop: send messages, execute tools, feed results back, repeat.",
+      "classes": [
+        {
+          "name": "LoopState",
+          "startLine": 61,
+          "endLine": 67
+        }
+      ],
       "functions": [
         {
           "name": "run_bash",
           "signature": "def run_bash(command: str)",
-          "startLine": 53
+          "startLine": 68
+        },
+        {
+          "name": "extract_text",
+          "signature": "def extract_text(content)",
+          "startLine": 90
+        },
+        {
+          "name": "execute_tool_calls",
+          "signature": "def execute_tool_calls(response_content)",
+          "startLine": 101
+        },
+        {
+          "name": "run_one_turn",
+          "signature": "def run_one_turn(state: LoopState)",
+          "startLine": 118
         },
         {
           "name": "agent_loop",
-          "signature": "def agent_loop(messages: list)",
-          "startLine": 67
+          "signature": "def agent_loop(state: LoopState)",
+          "startLine": 143
         }
       ],
-      "layer": "tools",
-      "source": "#!/usr/bin/env python3\n\"\"\"\ns01_agent_loop.py - The Agent Loop\n\nThe entire secret of an AI coding agent in one pattern:\n\n    while stop_reason == \"tool_use\":\n        response = LLM(messages, tools)\n        execute tools\n        append results\n\n    +----------+      +-------+      +---------+\n    |   User   | ---> |  LLM  | ---> |  Tool   |\n    |  prompt  |      |       |      | execute |\n    +----------+      +---+---+      +----+----+\n                          ^               |\n                          |   tool_result |\n                          +---------------+\n                          (loop continues)\n\nThis is the core loop: feed tool results back to the model\nuntil the model decides to stop. Production agents layer\npolicy, hooks, and lifecycle controls on top.\n\"\"\"\n\nimport os\nimport subprocess\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\n\nSYSTEM = f\"You are a coding agent at {os.getcwd()}. Use bash to solve tasks. Act, don't explain.\"\n\nTOOLS = [{\n    \"name\": \"bash\",\n    \"description\": \"Run a shell command.\",\n    \"input_schema\": {\n        \"type\": \"object\",\n        \"properties\": {\"command\": {\"type\": \"string\"}},\n        \"required\": [\"command\"],\n    },\n}]\n\n\ndef run_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(command, shell=True, cwd=os.getcwd(),\n                           capture_output=True, text=True, timeout=120)\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\n\n# -- The core pattern: a while loop that calls tools until the model stops --\ndef agent_loop(messages: list):\n    while True:\n        response = client.messages.create(\n            model=MODEL, system=SYSTEM, messages=messages,\n            tools=TOOLS, max_tokens=8000,\n        )\n        # Append assistant turn\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n        # If the model didn't call a tool, we're done\n        if response.stop_reason != \"tool_use\":\n            return\n        # Execute each tool call, collect results\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                print(f\"\\033[33m$ {block.input['command']}\\033[0m\")\n                output = run_bash(block.input[\"command\"])\n                print(output[:200])\n                results.append({\"type\": \"tool_result\", \"tool_use_id\": block.id,\n                                \"content\": output})\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms01 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
+      "layer": "core",
+      "source": "#!/usr/bin/env python3\n# Harness: the loop -- keep feeding real tool results back into the model.\n\"\"\"\ns01_agent_loop.py - The Agent Loop\n\nThis file teaches the smallest useful coding-agent pattern:\n\n    user message\n      -> model reply\n      -> if tool_use: execute tools\n      -> write tool_result back to messages\n      -> continue\n\nIt intentionally keeps the loop small, but still makes the loop state explicit\nso later chapters can grow from the same structure.\n\"\"\"\n\nimport os\nimport subprocess\nfrom dataclasses import dataclass\n\ntry:\n    import readline\n    # #143 UTF-8 backspace fix for macOS libedit\n    readline.parse_and_bind('set bind-tty-special-chars off')\n    readline.parse_and_bind('set input-meta on')\n    readline.parse_and_bind('set output-meta on')\n    readline.parse_and_bind('set convert-meta off')\n    readline.parse_and_bind('set enable-meta-keybindings on')\nexcept ImportError:\n    pass\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\n\nSYSTEM = (\n    f\"You are a coding agent at {os.getcwd()}. \"\n    \"Use bash to inspect and change the workspace. Act first, then report clearly.\"\n)\n\nTOOLS = [{\n    \"name\": \"bash\",\n    \"description\": \"Run a shell command in the current workspace.\",\n    \"input_schema\": {\n        \"type\": \"object\",\n        \"properties\": {\"command\": {\"type\": \"string\"}},\n        \"required\": [\"command\"],\n    },\n}]\n\n\n@dataclass\nclass LoopState:\n    # The minimal loop state: history, loop count, and why we continue.\n    messages: list\n    turn_count: int = 1\n    transition_reason: str | None = None\n\n\ndef run_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(item in command for item in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        result = subprocess.run(\n            command,\n            shell=True,\n            cwd=os.getcwd(),\n            capture_output=True,\n            text=True,\n            timeout=120,\n        )\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n    except (FileNotFoundError, OSError) as e:\n        return f\"Error: {e}\"\n\n    output = (result.stdout + result.stderr).strip()\n    return output[:50000] if output else \"(no output)\"\n\n\ndef extract_text(content) -> str:\n    if not isinstance(content, list):\n        return \"\"\n    texts = []\n    for block in content:\n        text = getattr(block, \"text\", None)\n        if text:\n            texts.append(text)\n    return \"\\n\".join(texts).strip()\n\n\ndef execute_tool_calls(response_content) -> list[dict]:\n    results = []\n    for block in response_content:\n        if block.type != \"tool_use\":\n            continue\n        command = block.input[\"command\"]\n        print(f\"\\033[33m$ {command}\\033[0m\")\n        output = run_bash(command)\n        print(output[:200])\n        results.append({\n            \"type\": \"tool_result\",\n            \"tool_use_id\": block.id,\n            \"content\": output,\n        })\n    return results\n\n\ndef run_one_turn(state: LoopState) -> bool:\n    response = client.messages.create(\n        model=MODEL,\n        system=SYSTEM,\n        messages=state.messages,\n        tools=TOOLS,\n        max_tokens=8000,\n    )\n    state.messages.append({\"role\": \"assistant\", \"content\": response.content})\n\n    if response.stop_reason != \"tool_use\":\n        state.transition_reason = None\n        return False\n\n    results = execute_tool_calls(response.content)\n    if not results:\n        state.transition_reason = None\n        return False\n\n    state.messages.append({\"role\": \"user\", \"content\": results})\n    state.turn_count += 1\n    state.transition_reason = \"tool_result\"\n    return True\n\n\ndef agent_loop(state: LoopState) -> None:\n    while run_one_turn(state):\n        pass\n\n\nif __name__ == \"__main__\":\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms01 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n\n        history.append({\"role\": \"user\", \"content\": query})\n        state = LoopState(messages=history)\n        agent_loop(state)\n\n        final_text = extract_text(history[-1][\"content\"])\n        if final_text:\n            print(final_text)\n        print()\n"
     },
     {
       "id": "s02",
       "filename": "s02_tool_use.py",
-      "title": "Tools",
-      "subtitle": "One Handler Per Tool",
-      "loc": 120,
+      "title": "Tool Use",
+      "subtitle": "Route Intent into Action",
+      "loc": 169,
       "tools": [
         "bash",
         "read_file",
@@ -47,50 +68,55 @@
         "write_file",
         "edit_file"
       ],
-      "coreAddition": "Tool dispatch map",
-      "keyInsight": "The loop stays the same; new tools register into the dispatch map",
+      "coreAddition": "Tool specs + dispatch map",
+      "keyInsight": "Adding a tool means adding one handler. The loop never changes.",
       "classes": [],
       "functions": [
         {
           "name": "safe_path",
           "signature": "def safe_path(p: str)",
-          "startLine": 40
+          "startLine": 32
         },
         {
           "name": "run_bash",
           "signature": "def run_bash(command: str)",
-          "startLine": 47
+          "startLine": 39
         },
         {
           "name": "run_read",
           "signature": "def run_read(path: str, limit: int = None)",
-          "startLine": 60
+          "startLine": 52
         },
         {
           "name": "run_write",
           "signature": "def run_write(path: str, content: str)",
-          "startLine": 71
+          "startLine": 63
         },
         {
           "name": "run_edit",
           "signature": "def run_edit(path: str, old_text: str, new_text: str)",
-          "startLine": 81
+          "startLine": 73
+        },
+        {
+          "name": "normalize_messages",
+          "signature": "def normalize_messages(messages: list)",
+          "startLine": 110
         },
         {
           "name": "agent_loop",
           "signature": "def agent_loop(messages: list)",
-          "startLine": 113
+          "startLine": 172
         }
       ],
-      "layer": "tools",
-      "source": "#!/usr/bin/env python3\n\"\"\"\ns02_tool_use.py - Tools\n\nThe agent loop from s01 didn't change. We just added tools to the array\nand a dispatch map to route calls.\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\nKey insight: \"The loop didn't change at all. I just added tools.\"\n\"\"\"\n\nimport os\nimport subprocess\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\n\nSYSTEM = f\"You are a coding agent at {WORKDIR}. Use tools to solve tasks. Act, don't explain.\"\n\n\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\n\ndef run_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(command, shell=True, cwd=WORKDIR,\n                           capture_output=True, text=True, timeout=120)\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\n\ndef run_read(path: str, limit: int = None) -> str:\n    try:\n        text = safe_path(path).read_text()\n        lines = text.splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more lines)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef run_write(path: str, content: str) -> str:\n    try:\n        fp = safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes to {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = safe_path(path)\n        content = fp.read_text()\n        if old_text not in content:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(content.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\n# -- The dispatch map: {tool_name: handler} --\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\"], kw[\"new_text\"]),\n}\n\nTOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n]\n\n\ndef agent_loop(messages: list):\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        if response.stop_reason != \"tool_use\":\n            return\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) if handler else f\"Unknown tool: {block.name}\"\n                print(f\"> {block.name}: {output[:200]}\")\n                results.append({\"type\": \"tool_result\", \"tool_use_id\": block.id, \"content\": output})\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms02 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
+      "layer": "core",
+      "source": "#!/usr/bin/env python3\n# Harness: tool dispatch -- expanding what the model can reach.\n\"\"\"\ns02_tool_use.py - Tool dispatch + message normalization\n\nThe agent loop from s01 didn't change. We added tools to the dispatch map,\nand a normalize_messages() function that cleans up the message list before\neach API call.\n\nKey insight: \"The loop didn't change at all. I just added tools.\"\n\"\"\"\n\nimport os\nimport subprocess\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\n\nSYSTEM = f\"You are a coding agent at {WORKDIR}. Use tools to solve tasks. Act, don't explain.\"\n\n\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\n\ndef run_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(command, shell=True, cwd=WORKDIR,\n                           capture_output=True, text=True, timeout=120)\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\n\ndef run_read(path: str, limit: int = None) -> str:\n    try:\n        text = safe_path(path).read_text()\n        lines = text.splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more lines)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef run_write(path: str, content: str) -> str:\n    try:\n        fp = safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes to {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = safe_path(path)\n        content = fp.read_text()\n        if old_text not in content:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(content.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\n# -- Concurrency safety classification --\n# Read-only tools can safely run in parallel; mutating tools must be serialized.\nCONCURRENCY_SAFE = {\"read_file\"}\nCONCURRENCY_UNSAFE = {\"write_file\", \"edit_file\"}\n\n# -- The dispatch map: {tool_name: handler} --\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\"], kw[\"new_text\"]),\n}\n\nTOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n]\n\n\ndef normalize_messages(messages: list) -> list:\n    \"\"\"Clean up messages before sending to the API.\n\n    Three jobs:\n    1. Strip internal metadata fields the API doesn't understand\n    2. Ensure every tool_use has a matching tool_result (insert placeholder if missing)\n    3. Merge consecutive same-role messages (API requires strict alternation)\n    \"\"\"\n    cleaned = []\n    for msg in messages:\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 not k.startswith(\"_\")}\n                for block in msg[\"content\"]\n                if isinstance(block, dict)\n            ]\n        else:\n            clean[\"content\"] = msg.get(\"content\", \"\")\n        cleaned.append(clean)\n\n    # Collect existing tool_result IDs\n    existing_results = set()\n    for msg in cleaned:\n        if isinstance(msg.get(\"content\"), list):\n            for block in msg[\"content\"]:\n                if isinstance(block, dict) and block.get(\"type\") == \"tool_result\":\n                    existing_results.add(block.get(\"tool_use_id\"))\n\n    # Find orphaned tool_use blocks and insert placeholder results\n    for msg in cleaned:\n        if msg[\"role\"] != \"assistant\" or not isinstance(msg.get(\"content\"), list):\n            continue\n        for block in msg[\"content\"]:\n            if not isinstance(block, dict):\n                continue\n            if block.get(\"type\") == \"tool_use\" and block.get(\"id\") not in existing_results:\n                cleaned.append({\"role\": \"user\", \"content\": [\n                    {\"type\": \"tool_result\", \"tool_use_id\": block[\"id\"],\n                     \"content\": \"(cancelled)\"}\n                ]})\n\n    # Merge consecutive same-role messages\n    if not cleaned:\n        return cleaned\n    merged = [cleaned[0]]\n    for msg in cleaned[1:]:\n        if msg[\"role\"] == merged[-1][\"role\"]:\n            prev = merged[-1]\n            prev_c = prev[\"content\"] if isinstance(prev[\"content\"], list) \\\n                else [{\"type\": \"text\", \"text\": str(prev[\"content\"])}]\n            curr_c = msg[\"content\"] if isinstance(msg[\"content\"], list) \\\n                else [{\"type\": \"text\", \"text\": str(msg[\"content\"])}]\n            prev[\"content\"] = prev_c + curr_c\n        else:\n            merged.append(msg)\n    return merged\n\n\ndef agent_loop(messages: list):\n    while True:\n        response = client.messages.create(\n            model=MODEL, system=SYSTEM,\n            messages=normalize_messages(messages),\n            tools=TOOLS, max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n        if response.stop_reason != \"tool_use\":\n            return\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) if handler else f\"Unknown tool: {block.name}\"\n                print(f\"> {block.name}:\")\n                print(output[:200])\n                results.append({\"type\": \"tool_result\", \"tool_use_id\": block.id, \"content\": output})\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms02 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
     },
     {
       "id": "s03",
       "filename": "s03_todo_write.py",
       "title": "TodoWrite",
-      "subtitle": "Plan Before You Act",
-      "loc": 176,
+      "subtitle": "Session Planning",
+      "loc": 279,
       "tools": [
         "bash",
         "read_file",
@@ -101,56 +127,71 @@
       "newTools": [
         "todo"
       ],
-      "coreAddition": "TodoManager + nag reminder",
-      "keyInsight": "An agent without a plan drifts; list the steps first, then execute",
+      "coreAddition": "PlanningState + reminder loop",
+      "keyInsight": "A visible plan keeps the agent on track when tasks get complex.",
       "classes": [
+        {
+          "name": "PlanItem",
+          "startLine": 36,
+          "endLine": 42
+        },
+        {
+          "name": "PlanningState",
+          "startLine": 43,
+          "endLine": 47
+        },
         {
           "name": "TodoManager",
-          "startLine": 51,
-          "endLine": 87
+          "startLine": 48,
+          "endLine": 113
         }
       ],
       "functions": [
         {
           "name": "safe_path",
-          "signature": "def safe_path(p: str)",
-          "startLine": 92
+          "signature": "def safe_path(path_str: str)",
+          "startLine": 117
         },
         {
           "name": "run_bash",
           "signature": "def run_bash(command: str)",
-          "startLine": 98
+          "startLine": 124
         },
         {
           "name": "run_read",
-          "signature": "def run_read(path: str, limit: int = None)",
-          "startLine": 110
+          "signature": "def run_read(path: str, limit: int | None = None)",
+          "startLine": 144
         },
         {
           "name": "run_write",
           "signature": "def run_write(path: str, content: str)",
-          "startLine": 119
+          "startLine": 154
         },
         {
           "name": "run_edit",
           "signature": "def run_edit(path: str, old_text: str, new_text: str)",
-          "startLine": 128
+          "startLine": 164
+        },
+        {
+          "name": "extract_text",
+          "signature": "def extract_text(content)",
+          "startLine": 262
         },
         {
           "name": "agent_loop",
           "signature": "def agent_loop(messages: list)",
-          "startLine": 163
+          "startLine": 273
         }
       ],
-      "layer": "planning",
-      "source": "#!/usr/bin/env python3\n\"\"\"\ns03_todo_write.py - TodoWrite\n\nThe model tracks its own progress via a TodoManager. A nag reminder\nforces it to keep updating when it forgets.\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>\n\nKey insight: \"The agent can track its own progress -- and I can see it.\"\n\"\"\"\n\nimport os\nimport subprocess\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\n\nSYSTEM = f\"\"\"You are a coding agent at {WORKDIR}.\nUse the todo tool to plan multi-step tasks. Mark in_progress before starting, completed when done.\nPrefer tools over prose.\"\"\"\n\n\n# -- TodoManager: structured state the LLM writes to --\nclass TodoManager:\n    def __init__(self):\n        self.items = []\n\n    def update(self, items: list) -> str:\n        if len(items) > 20:\n            raise ValueError(\"Max 20 todos allowed\")\n        validated = []\n        in_progress_count = 0\n        for i, item in enumerate(items):\n            text = str(item.get(\"text\", \"\")).strip()\n            status = str(item.get(\"status\", \"pending\")).lower()\n            item_id = str(item.get(\"id\", str(i + 1)))\n            if not text:\n                raise ValueError(f\"Item {item_id}: text required\")\n            if status not in (\"pending\", \"in_progress\", \"completed\"):\n                raise ValueError(f\"Item {item_id}: invalid status '{status}'\")\n            if status == \"in_progress\":\n                in_progress_count += 1\n            validated.append({\"id\": item_id, \"text\": text, \"status\": status})\n        if in_progress_count > 1:\n            raise ValueError(\"Only one task can be in_progress at a time\")\n        self.items = validated\n        return self.render()\n\n    def render(self) -> str:\n        if not self.items:\n            return \"No todos.\"\n        lines = []\n        for item in self.items:\n            marker = {\"pending\": \"[ ]\", \"in_progress\": \"[>]\", \"completed\": \"[x]\"}[item[\"status\"]]\n            lines.append(f\"{marker} #{item['id']}: {item['text']}\")\n        done = sum(1 for t in self.items if t[\"status\"] == \"completed\")\n        lines.append(f\"\\n({done}/{len(self.items)} completed)\")\n        return \"\\n\".join(lines)\n\n\nTODO = TodoManager()\n\n\n# -- Tool implementations --\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_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(command, shell=True, cwd=WORKDIR,\n                           capture_output=True, text=True, timeout=120)\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\ndef run_read(path: str, limit: int = None) -> str:\n    try:\n        lines = safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\ndef run_write(path: str, content: str) -> str:\n    try:\n        fp = safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\ndef run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = safe_path(path)\n        content = fp.read_text()\n        if old_text not in content:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(content.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\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\"], kw[\"new_text\"]),\n    \"todo\":       lambda **kw: TODO.update(kw[\"items\"]),\n}\n\nTOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n    {\"name\": \"todo\", \"description\": \"Update task list. Track progress on multi-step tasks.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"items\": {\"type\": \"array\", \"items\": {\"type\": \"object\", \"properties\": {\"id\": {\"type\": \"string\"}, \"text\": {\"type\": \"string\"}, \"status\": {\"type\": \"string\", \"enum\": [\"pending\", \"in_progress\", \"completed\"]}}, \"required\": [\"id\", \"text\", \"status\"]}}}, \"required\": [\"items\"]}},\n]\n\n\n# -- Agent loop with nag reminder injection --\ndef agent_loop(messages: list):\n    rounds_since_todo = 0\n    while True:\n        # Nag reminder is injected below, alongside tool results\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        if response.stop_reason != \"tool_use\":\n            return\n        results = []\n        used_todo = False\n        for block in response.content:\n            if block.type == \"tool_use\":\n                handler = TOOL_HANDLERS.get(block.name)\n                try:\n                    output = handler(**block.input) if handler else f\"Unknown tool: {block.name}\"\n                except Exception as e:\n                    output = f\"Error: {e}\"\n                print(f\"> {block.name}: {str(output)[:200]}\")\n                results.append({\"type\": \"tool_result\", \"tool_use_id\": block.id, \"content\": str(output)})\n                if block.name == \"todo\":\n                    used_todo = True\n        rounds_since_todo = 0 if used_todo else rounds_since_todo + 1\n        if rounds_since_todo >= 3:\n            results.insert(0, {\"type\": \"text\", \"text\": \"<reminder>Update your todos.</reminder>\"})\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms03 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
+      "layer": "core",
+      "source": "#!/usr/bin/env python3\n# Harness: planning -- keep the current session plan outside the model's head.\n\"\"\"\ns03_todo_write.py - Session Planning with TodoWrite\n\nThis chapter is about a lightweight session plan, not a durable task graph.\nThe model can rewrite its current plan, keep one active step in focus, and get\nnudged if it stops refreshing the plan for too many rounds.\n\"\"\"\n\nimport os\nimport subprocess\nfrom dataclasses import dataclass, field\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\nPLAN_REMINDER_INTERVAL = 3\n\nSYSTEM = f\"\"\"You are a coding agent at {WORKDIR}.\nUse the todo tool for multi-step work.\nKeep exactly one step in_progress when a task has multiple steps.\nRefresh the plan as work advances. Prefer tools over prose.\"\"\"\n\n\n@dataclass\nclass PlanItem:\n    content: str\n    status: str = \"pending\"\n    active_form: str = \"\"\n\n\n@dataclass\nclass PlanningState:\n    items: list[PlanItem] = field(default_factory=list)\n    rounds_since_update: int = 0\n\n\nclass TodoManager:\n    def __init__(self):\n        self.state = PlanningState()\n\n    def update(self, items: list) -> str:\n        if len(items) > 12:\n            raise ValueError(\"Keep the session plan short (max 12 items)\")\n\n        normalized = []\n        in_progress_count = 0\n        for index, raw_item in enumerate(items):\n            content = str(raw_item.get(\"content\", \"\")).strip()\n            status = str(raw_item.get(\"status\", \"pending\")).lower()\n            active_form = str(raw_item.get(\"activeForm\", \"\")).strip()\n\n            if not content:\n                raise ValueError(f\"Item {index}: content required\")\n            if status not in {\"pending\", \"in_progress\", \"completed\"}:\n                raise ValueError(f\"Item {index}: invalid status '{status}'\")\n            if status == \"in_progress\":\n                in_progress_count += 1\n\n            normalized.append(PlanItem(\n                content=content,\n                status=status,\n                active_form=active_form,\n            ))\n\n        if in_progress_count > 1:\n            raise ValueError(\"Only one plan item can be in_progress\")\n\n        self.state.items = normalized\n        self.state.rounds_since_update = 0\n        return self.render()\n\n    def note_round_without_update(self) -> None:\n        self.state.rounds_since_update += 1\n\n    def reminder(self) -> str | None:\n        if not self.state.items:\n            return None\n        if self.state.rounds_since_update < PLAN_REMINDER_INTERVAL:\n            return None\n        return \"<reminder>Refresh your current plan before continuing.</reminder>\"\n\n    def render(self) -> str:\n        if not self.state.items:\n            return \"No session plan yet.\"\n\n        lines = []\n        for item in self.state.items:\n            marker = {\n                \"pending\": \"[ ]\",\n                \"in_progress\": \"[>]\",\n                \"completed\": \"[x]\",\n            }[item.status]\n            line = f\"{marker} {item.content}\"\n            if item.status == \"in_progress\" and item.active_form:\n                line += f\" ({item.active_form})\"\n            lines.append(line)\n\n        completed = sum(1 for item in self.state.items if item.status == \"completed\")\n        lines.append(f\"\\n({completed}/{len(self.state.items)} completed)\")\n        return \"\\n\".join(lines)\n\n\nTODO = TodoManager()\n\n\ndef safe_path(path_str: str) -> Path:\n    path = (WORKDIR / path_str).resolve()\n    if not path.is_relative_to(WORKDIR):\n        raise ValueError(f\"Path escapes workspace: {path_str}\")\n    return path\n\n\ndef run_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(item in command for item in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        result = subprocess.run(\n            command,\n            shell=True,\n            cwd=WORKDIR,\n            capture_output=True,\n            text=True,\n            timeout=120,\n        )\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\n    output = (result.stdout + result.stderr).strip()\n    return output[:50000] if output else \"(no output)\"\n\n\ndef run_read(path: str, limit: int | None = None) -> str:\n    try:\n        lines = safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more lines)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as exc:\n        return f\"Error: {exc}\"\n\n\ndef run_write(path: str, content: str) -> str:\n    try:\n        file_path = safe_path(path)\n        file_path.parent.mkdir(parents=True, exist_ok=True)\n        file_path.write_text(content)\n        return f\"Wrote {len(content)} bytes to {path}\"\n    except Exception as exc:\n        return f\"Error: {exc}\"\n\n\ndef run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        file_path = safe_path(path)\n        content = file_path.read_text()\n        if old_text not in content:\n            return f\"Error: Text not found in {path}\"\n        file_path.write_text(content.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as exc:\n        return f\"Error: {exc}\"\n\n\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\"], kw[\"new_text\"]),\n    \"todo\": lambda **kw: TODO.update(kw[\"items\"]),\n}\n\nTOOLS = [\n    {\n        \"name\": \"bash\",\n        \"description\": \"Run a shell command.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\"command\": {\"type\": \"string\"}},\n            \"required\": [\"command\"],\n        },\n    },\n    {\n        \"name\": \"read_file\",\n        \"description\": \"Read file contents.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"path\": {\"type\": \"string\"},\n                \"limit\": {\"type\": \"integer\"},\n            },\n            \"required\": [\"path\"],\n        },\n    },\n    {\n        \"name\": \"write_file\",\n        \"description\": \"Write content to a file.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"path\": {\"type\": \"string\"},\n                \"content\": {\"type\": \"string\"},\n            },\n            \"required\": [\"path\", \"content\"],\n        },\n    },\n    {\n        \"name\": \"edit_file\",\n        \"description\": \"Replace exact text in a file once.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"path\": {\"type\": \"string\"},\n                \"old_text\": {\"type\": \"string\"},\n                \"new_text\": {\"type\": \"string\"},\n            },\n            \"required\": [\"path\", \"old_text\", \"new_text\"],\n        },\n    },\n    {\n        \"name\": \"todo\",\n        \"description\": \"Rewrite the current session plan for multi-step work.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"items\": {\n                    \"type\": \"array\",\n                    \"items\": {\n                        \"type\": \"object\",\n                        \"properties\": {\n                            \"content\": {\"type\": \"string\"},\n                            \"status\": {\n                                \"type\": \"string\",\n                                \"enum\": [\"pending\", \"in_progress\", \"completed\"],\n                            },\n                            \"activeForm\": {\n                                \"type\": \"string\",\n                                \"description\": \"Optional present-continuous label.\",\n                            },\n                        },\n                        \"required\": [\"content\", \"status\"],\n                    },\n                },\n            },\n            \"required\": [\"items\"],\n        },\n    },\n]\n\n\ndef extract_text(content) -> str:\n    if not isinstance(content, list):\n        return \"\"\n    texts = []\n    for block in content:\n        text = getattr(block, \"text\", None)\n        if text:\n            texts.append(text)\n    return \"\\n\".join(texts).strip()\n\n\ndef agent_loop(messages: list) -> None:\n    while True:\n        response = client.messages.create(\n            model=MODEL,\n            system=SYSTEM,\n            messages=messages,\n            tools=TOOLS,\n            max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n\n        if response.stop_reason != \"tool_use\":\n            return\n\n        results = []\n        used_todo = False\n        for block in response.content:\n            if block.type != \"tool_use\":\n                continue\n\n            handler = TOOL_HANDLERS.get(block.name)\n            try:\n                output = handler(**block.input) if handler else f\"Unknown tool: {block.name}\"\n            except Exception as exc:\n                output = f\"Error: {exc}\"\n\n            print(f\"> {block.name}: {str(output)[:200]}\")\n            results.append({\n                \"type\": \"tool_result\",\n                \"tool_use_id\": block.id,\n                \"content\": str(output),\n            })\n            if block.name == \"todo\":\n                used_todo = True\n\n        if used_todo:\n            TODO.state.rounds_since_update = 0\n        else:\n            TODO.note_round_without_update()\n            reminder = TODO.reminder()\n            if reminder:\n                results.insert(0, {\"type\": \"text\", \"text\": reminder})\n\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms03 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n\n        final_text = extract_text(history[-1][\"content\"])\n        if final_text:\n            print(final_text)\n        print()\n"
     },
     {
       "id": "s04",
       "filename": "s04_subagent.py",
-      "title": "Subagents",
-      "subtitle": "Clean Context Per Subtask",
-      "loc": 151,
+      "title": "Subagent",
+      "subtitle": "Fresh Context per Subtask",
+      "loc": 200,
       "tools": [
         "bash",
         "read_file",
@@ -161,184 +202,573 @@
       "newTools": [
         "task"
       ],
-      "coreAddition": "Subagent spawn with isolated messages[]",
-      "keyInsight": "Subagents use independent messages[], keeping the main conversation clean",
-      "classes": [],
+      "coreAddition": "Delegation with isolated message history",
+      "keyInsight": "A subagent is mainly a context boundary, not a process trick.",
+      "classes": [
+        {
+          "name": "AgentTemplate",
+          "startLine": 67,
+          "endLine": 98
+        }
+      ],
       "functions": [
         {
           "name": "safe_path",
           "signature": "def safe_path(p: str)",
-          "startLine": 46
+          "startLine": 99
         },
         {
           "name": "run_bash",
           "signature": "def run_bash(command: str)",
-          "startLine": 52
+          "startLine": 105
         },
         {
           "name": "run_read",
           "signature": "def run_read(path: str, limit: int = None)",
-          "startLine": 64
+          "startLine": 119
         },
         {
           "name": "run_write",
           "signature": "def run_write(path: str, content: str)",
-          "startLine": 73
+          "startLine": 128
         },
         {
           "name": "run_edit",
           "signature": "def run_edit(path: str, old_text: str, new_text: str)",
-          "startLine": 82
+          "startLine": 137
         },
         {
           "name": "run_subagent",
           "signature": "def run_subagent(prompt: str)",
-          "startLine": 115
+          "startLine": 170
         },
         {
           "name": "agent_loop",
           "signature": "def agent_loop(messages: list)",
-          "startLine": 143
+          "startLine": 198
+        }
+      ],
+      "layer": "core",
+      "source": "#!/usr/bin/env python3\n# Harness: context isolation -- protecting the model's clarity of thought.\n\"\"\"\ns04_subagent.py - Subagents\n\nSpawn a child agent with fresh messages=[]. The child works in its own\ncontext, sharing the filesystem, then returns only a summary to the parent.\n\n    Parent agent                     Subagent\n    +------------------+             +------------------+\n    | messages=[...]   |             | messages=[]      |  <-- fresh\n    |                  |  dispatch   |                  |\n    | tool: task       | ---------->| while tool_use:  |\n    |   prompt=\"...\"   |            |   call tools     |\n    |   description=\"\" |            |   append results |\n    |                  |  summary   |                  |\n    |   result = \"...\" | <--------- | return last text |\n    +------------------+             +------------------+\n              |\n    Parent context stays clean.\n    Subagent context is discarded.\n\nKey insight: \"Fresh messages=[] gives context isolation. The parent stays clean.\"\n\nNote: Real Claude Code also uses in-process isolation (not OS-level process\nforking). The child runs in the same process with a fresh message array and\nisolated tool context -- same pattern as this teaching implementation.\n\n    Comparison with real Claude Code:\n    +-------------------+------------------+----------------------------------+\n    | Aspect            | This demo        | Real Claude Code                 |\n    +-------------------+------------------+----------------------------------+\n    | Backend           | in-process only  | 5 backends: in-process, tmux,    |\n    |                   |                  | iTerm2, fork, remote             |\n    | Context isolation | fresh messages=[]| createSubagentContext() isolates  |\n    |                   |                  | ~20 fields (tools, permissions,  |\n    |                   |                  | cwd, env, hooks, etc.)           |\n    | Tool filtering    | manually curated | resolveAgentTools() filters from |\n    |                   |                  | parent pool; allowedTools         |\n    |                   |                  | replaces all allow rules         |\n    | Agent definition  | hardcoded system | .claude/agents/*.md with YAML    |\n    |                   | prompt           | frontmatter (AgentTemplate)      |\n    +-------------------+------------------+----------------------------------+\n\"\"\"\n\nimport os\nimport re\nimport subprocess\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\n\nSYSTEM = f\"You are a coding agent at {WORKDIR}. Use the task tool to delegate exploration or subtasks.\"\nSUBAGENT_SYSTEM = f\"You are a coding subagent at {WORKDIR}. Complete the given task, then summarize your findings.\"\n\n\nclass AgentTemplate:\n    \"\"\"\n    Parse agent definition from markdown frontmatter.\n\n    Real Claude Code loads agent definitions from .claude/agents/*.md.\n    Frontmatter fields: name, tools, disallowedTools, skills, hooks,\n    model, effort, permissionMode, maxTurns, memory, isolation, color,\n    background, initialPrompt, mcpServers.\n    3 sources: built-in, custom (.claude/agents/), plugin-provided.\n    \"\"\"\n    def __init__(self, path):\n        self.path = Path(path)\n        self.name = self.path.stem\n        self.config = {}\n        self.system_prompt = \"\"\n        self._parse()\n\n    def _parse(self):\n        text = self.path.read_text()\n        match = re.match(r\"^---\\s*\\n(.*?)\\n---\\s*\\n(.*)\", text, re.DOTALL)\n        if not match:\n            self.system_prompt = text\n            return\n        for line in match.group(1).splitlines():\n            if \":\" in line:\n                k, _, v = line.partition(\":\")\n                self.config[k.strip()] = v.strip()\n        self.system_prompt = match.group(2).strip()\n        self.name = self.config.get(\"name\", self.name)\n\n\n# -- Tool implementations shared by parent and child --\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_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(command, shell=True, cwd=WORKDIR,\n                           capture_output=True, text=True, timeout=120)\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n    except (FileNotFoundError, OSError) as e:\n        return f\"Error: {e}\"\n\ndef run_read(path: str, limit: int = None) -> str:\n    try:\n        lines = safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\ndef run_write(path: str, content: str) -> str:\n    try:\n        fp = safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\ndef run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = safe_path(path)\n        content = fp.read_text()\n        if old_text not in content:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(content.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\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\"], kw[\"new_text\"]),\n}\n\n# Child gets all base tools except task (no recursive spawning)\nCHILD_TOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n]\n\n\n# -- Subagent: fresh context, filtered tools, summary-only return --\ndef run_subagent(prompt: str) -> str:\n    sub_messages = [{\"role\": \"user\", \"content\": prompt}]  # fresh context\n    for _ in range(30):  # safety limit\n        response = client.messages.create(\n            model=MODEL, system=SUBAGENT_SYSTEM, messages=sub_messages,\n            tools=CHILD_TOOLS, max_tokens=8000,\n        )\n        sub_messages.append({\"role\": \"assistant\", \"content\": response.content})\n        if response.stop_reason != \"tool_use\":\n            break\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                handler = TOOL_HANDLERS.get(block.name)\n                output = handler(**block.input) if handler else f\"Unknown tool: {block.name}\"\n                results.append({\"type\": \"tool_result\", \"tool_use_id\": block.id, \"content\": str(output)[:50000]})\n        sub_messages.append({\"role\": \"user\", \"content\": results})\n    # Only the final text returns to the parent -- child context is discarded\n    return \"\".join(b.text for b in response.content if hasattr(b, \"text\")) or \"(no summary)\"\n\n\n# -- Parent tools: base tools + task dispatcher --\nPARENT_TOOLS = CHILD_TOOLS + [\n    {\"name\": \"task\", \"description\": \"Spawn a subagent with fresh context. It shares the filesystem but not conversation history.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"prompt\": {\"type\": \"string\"}, \"description\": {\"type\": \"string\", \"description\": \"Short description of the task\"}}, \"required\": [\"prompt\"]}},\n]\n\n\ndef agent_loop(messages: list):\n    while True:\n        response = client.messages.create(\n            model=MODEL, system=SYSTEM, messages=messages,\n            tools=PARENT_TOOLS, max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n        if response.stop_reason != \"tool_use\":\n            return\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                if block.name == \"task\":\n                    desc = block.input.get(\"description\", \"subtask\")\n                    prompt = block.input.get(\"prompt\", \"\")\n                    print(f\"> task ({desc}): {prompt[:80]}\")\n                    output = run_subagent(prompt)\n                else:\n                    handler = TOOL_HANDLERS.get(block.name)\n                    output = handler(**block.input) if handler else f\"Unknown tool: {block.name}\"\n                print(f\"  {str(output)[:200]}\")\n                results.append({\"type\": \"tool_result\", \"tool_use_id\": block.id, \"content\": str(output)})\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms04 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
+    },
+    {
+      "id": "s05",
+      "filename": "s05_skill_loading.py",
+      "title": "Skills",
+      "subtitle": "Discover Cheap, Load Deep",
+      "loc": 244,
+      "tools": [
+        "bash",
+        "read_file",
+        "write_file",
+        "edit_file",
+        "load_skill"
+      ],
+      "newTools": [
+        "load_skill"
+      ],
+      "coreAddition": "Skill registry + on-demand injection",
+      "keyInsight": "Discover cheaply, load deeply -- only when needed.",
+      "classes": [
+        {
+          "name": "SkillManifest",
+          "startLine": 36,
+          "endLine": 42
+        },
+        {
+          "name": "SkillDocument",
+          "startLine": 43,
+          "endLine": 47
+        },
+        {
+          "name": "SkillRegistry",
+          "startLine": 48,
+          "endLine": 99
+        }
+      ],
+      "functions": [
+        {
+          "name": "safe_path",
+          "signature": "def safe_path(path_str: str)",
+          "startLine": 110
+        },
+        {
+          "name": "run_bash",
+          "signature": "def run_bash(command: str)",
+          "startLine": 117
+        },
+        {
+          "name": "run_read",
+          "signature": "def run_read(path: str, limit: int | None = None)",
+          "startLine": 137
+        },
+        {
+          "name": "run_write",
+          "signature": "def run_write(path: str, content: str)",
+          "startLine": 147
+        },
+        {
+          "name": "run_edit",
+          "signature": "def run_edit(path: str, old_text: str, new_text: str)",
+          "startLine": 157
+        },
+        {
+          "name": "extract_text",
+          "signature": "def extract_text(content)",
+          "startLine": 236
+        },
+        {
+          "name": "agent_loop",
+          "signature": "def agent_loop(messages: list)",
+          "startLine": 247
+        }
+      ],
+      "layer": "core",
+      "source": "#!/usr/bin/env python3\n# Harness: on-demand knowledge -- discover skills cheaply, load them only when needed.\n\"\"\"\ns05_skill_loading.py - Skills\n\nThis chapter teaches a two-layer skill model:\n\n1. Put a cheap skill catalog in the system prompt.\n2. Load the full skill body only when the model asks for it.\n\nThat keeps the prompt small while still giving the model access to reusable,\ntask-specific guidance.\n\"\"\"\n\nimport os\nimport re\nimport subprocess\nfrom dataclasses import dataclass\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\nSKILLS_DIR = WORKDIR / \"skills\"\n\n\n@dataclass\nclass SkillManifest:\n    name: str\n    description: str\n    path: Path\n\n\n@dataclass\nclass SkillDocument:\n    manifest: SkillManifest\n    body: str\n\n\nclass SkillRegistry:\n    def __init__(self, skills_dir: Path):\n        self.skills_dir = skills_dir\n        self.documents: dict[str, SkillDocument] = {}\n        self._load_all()\n\n    def _load_all(self) -> None:\n        if not self.skills_dir.exists():\n            return\n\n        for path in sorted(self.skills_dir.rglob(\"SKILL.md\")):\n            meta, body = self._parse_frontmatter(path.read_text())\n            name = meta.get(\"name\", path.parent.name)\n            description = meta.get(\"description\", \"No description\")\n            manifest = SkillManifest(name=name, description=description, path=path)\n            self.documents[name] = SkillDocument(manifest=manifest, body=body.strip())\n\n    def _parse_frontmatter(self, text: str) -> tuple[dict, str]:\n        match = re.match(r\"^---\\n(.*?)\\n---\\n(.*)\", text, re.DOTALL)\n        if not match:\n            return {}, text\n\n        meta = {}\n        for line in match.group(1).strip().splitlines():\n            if \":\" not in line:\n                continue\n            key, value = line.split(\":\", 1)\n            meta[key.strip()] = value.strip()\n        return meta, match.group(2)\n\n    def describe_available(self) -> str:\n        if not self.documents:\n            return \"(no skills available)\"\n        lines = []\n        for name in sorted(self.documents):\n            manifest = self.documents[name].manifest\n            lines.append(f\"- {manifest.name}: {manifest.description}\")\n        return \"\\n\".join(lines)\n\n    def load_full_text(self, name: str) -> str:\n        document = self.documents.get(name)\n        if not document:\n            known = \", \".join(sorted(self.documents)) or \"(none)\"\n            return f\"Error: Unknown skill '{name}'. Available skills: {known}\"\n\n        return (\n            f\"<skill name=\\\"{document.manifest.name}\\\">\\n\"\n            f\"{document.body}\\n\"\n            \"</skill>\"\n        )\n\n\nSKILL_REGISTRY = SkillRegistry(SKILLS_DIR)\n\nSYSTEM = f\"\"\"You are a coding agent at {WORKDIR}.\nUse load_skill when a task needs specialized instructions before you act.\n\nSkills available:\n{SKILL_REGISTRY.describe_available()}\n\"\"\"\n\n\ndef safe_path(path_str: str) -> Path:\n    path = (WORKDIR / path_str).resolve()\n    if not path.is_relative_to(WORKDIR):\n        raise ValueError(f\"Path escapes workspace: {path_str}\")\n    return path\n\n\ndef run_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(item in command for item in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        result = subprocess.run(\n            command,\n            shell=True,\n            cwd=WORKDIR,\n            capture_output=True,\n            text=True,\n            timeout=120,\n        )\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\n    output = (result.stdout + result.stderr).strip()\n    return output[:50000] if output else \"(no output)\"\n\n\ndef run_read(path: str, limit: int | None = None) -> str:\n    try:\n        lines = safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more lines)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as exc:\n        return f\"Error: {exc}\"\n\n\ndef run_write(path: str, content: str) -> str:\n    try:\n        file_path = safe_path(path)\n        file_path.parent.mkdir(parents=True, exist_ok=True)\n        file_path.write_text(content)\n        return f\"Wrote {len(content)} bytes to {path}\"\n    except Exception as exc:\n        return f\"Error: {exc}\"\n\n\ndef run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        file_path = safe_path(path)\n        content = file_path.read_text()\n        if old_text not in content:\n            return f\"Error: Text not found in {path}\"\n        file_path.write_text(content.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as exc:\n        return f\"Error: {exc}\"\n\n\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\"], kw[\"new_text\"]),\n    \"load_skill\": lambda **kw: SKILL_REGISTRY.load_full_text(kw[\"name\"]),\n}\n\nTOOLS = [\n    {\n        \"name\": \"bash\",\n        \"description\": \"Run a shell command.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\"command\": {\"type\": \"string\"}},\n            \"required\": [\"command\"],\n        },\n    },\n    {\n        \"name\": \"read_file\",\n        \"description\": \"Read file contents.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"path\": {\"type\": \"string\"},\n                \"limit\": {\"type\": \"integer\"},\n            },\n            \"required\": [\"path\"],\n        },\n    },\n    {\n        \"name\": \"write_file\",\n        \"description\": \"Write content to a file.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"path\": {\"type\": \"string\"},\n                \"content\": {\"type\": \"string\"},\n            },\n            \"required\": [\"path\", \"content\"],\n        },\n    },\n    {\n        \"name\": \"edit_file\",\n        \"description\": \"Replace exact text in a file once.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"path\": {\"type\": \"string\"},\n                \"old_text\": {\"type\": \"string\"},\n                \"new_text\": {\"type\": \"string\"},\n            },\n            \"required\": [\"path\", \"old_text\", \"new_text\"],\n        },\n    },\n    {\n        \"name\": \"load_skill\",\n        \"description\": \"Load the full body of a named skill into the current context.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\"name\": {\"type\": \"string\"}},\n            \"required\": [\"name\"],\n        },\n    },\n]\n\n\ndef extract_text(content) -> str:\n    if not isinstance(content, list):\n        return \"\"\n    texts = []\n    for block in content:\n        text = getattr(block, \"text\", None)\n        if text:\n            texts.append(text)\n    return \"\\n\".join(texts).strip()\n\n\ndef agent_loop(messages: list) -> None:\n    while True:\n        response = client.messages.create(\n            model=MODEL,\n            system=SYSTEM,\n            messages=messages,\n            tools=TOOLS,\n            max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n\n        if response.stop_reason != \"tool_use\":\n            return\n\n        results = []\n        for block in response.content:\n            if block.type != \"tool_use\":\n                continue\n\n            handler = TOOL_HANDLERS.get(block.name)\n            try:\n                output = handler(**block.input) if handler else f\"Unknown tool: {block.name}\"\n            except Exception as exc:\n                output = f\"Error: {exc}\"\n\n            print(f\"> {block.name}: {str(output)[:200]}\")\n            results.append({\n                \"type\": \"tool_result\",\n                \"tool_use_id\": block.id,\n                \"content\": str(output),\n            })\n\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms05 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n\n        final_text = extract_text(history[-1][\"content\"])\n        if final_text:\n            print(final_text)\n        print()\n"
+    },
+    {
+      "id": "s06",
+      "filename": "s06_context_compact.py",
+      "title": "Context Compact",
+      "subtitle": "Keep the Active Context Small",
+      "loc": 308,
+      "tools": [
+        "bash",
+        "read_file",
+        "write_file",
+        "edit_file",
+        "compact"
+      ],
+      "newTools": [
+        "compact"
+      ],
+      "coreAddition": "Persist markers + micro compact + summary compact",
+      "keyInsight": "Compaction isn't deleting history -- it's relocating detail so the agent can keep working.",
+      "classes": [
+        {
+          "name": "CompactState",
+          "startLine": 50,
+          "endLine": 55
+        }
+      ],
+      "functions": [
+        {
+          "name": "estimate_context_size",
+          "signature": "def estimate_context_size(messages: list)",
+          "startLine": 56
+        },
+        {
+          "name": "track_recent_file",
+          "signature": "def track_recent_file(state: CompactState, path: str)",
+          "startLine": 60
+        },
+        {
+          "name": "safe_path",
+          "signature": "def safe_path(path_str: str)",
+          "startLine": 68
+        },
+        {
+          "name": "persist_large_output",
+          "signature": "def persist_large_output(tool_use_id: str, output: str)",
+          "startLine": 75
+        },
+        {
+          "name": "collect_tool_result_blocks",
+          "signature": "def collect_tool_result_blocks(messages: list)",
+          "startLine": 95
+        },
+        {
+          "name": "micro_compact",
+          "signature": "def micro_compact(messages: list)",
+          "startLine": 107
+        },
+        {
+          "name": "write_transcript",
+          "signature": "def write_transcript(messages: list)",
+          "startLine": 120
+        },
+        {
+          "name": "summarize_history",
+          "signature": "def summarize_history(messages: list)",
+          "startLine": 129
+        },
+        {
+          "name": "compact_history",
+          "signature": "def compact_history(messages: list, state: CompactState, focus: str | None = None)",
+          "startLine": 150
+        },
+        {
+          "name": "run_bash",
+          "signature": "def run_bash(command: str, tool_use_id: str)",
+          "startLine": 173
+        },
+        {
+          "name": "run_read",
+          "signature": "def run_read(path: str, tool_use_id: str, state: CompactState, limit: int | None = None)",
+          "startLine": 193
+        },
+        {
+          "name": "run_write",
+          "signature": "def run_write(path: str, content: str)",
+          "startLine": 205
+        },
+        {
+          "name": "run_edit",
+          "signature": "def run_edit(path: str, old_text: str, new_text: str)",
+          "startLine": 215
+        },
+        {
+          "name": "extract_text",
+          "signature": "def extract_text(content)",
+          "startLine": 287
+        },
+        {
+          "name": "execute_tool",
+          "signature": "def execute_tool(block, state: CompactState)",
+          "startLine": 298
+        },
+        {
+          "name": "agent_loop",
+          "signature": "def agent_loop(messages: list, state: CompactState)",
+          "startLine": 312
+        }
+      ],
+      "layer": "core",
+      "source": "#!/usr/bin/env python3\n# Harness: compression -- keep the active context small enough to keep working.\n\"\"\"\ns06_context_compact.py - Context Compact\n\nThis teaching version keeps the compact model intentionally small:\n\n1. Large tool output is persisted to disk and replaced with a preview marker.\n2. Older tool results are micro-compacted into short placeholders.\n3. When the whole conversation gets too large, the agent summarizes it and\n   continues from that summary.\n\nThe goal is not to model every production branch. The goal is to make the\nactive-context idea explicit and teachable.\n\"\"\"\n\nimport json\nimport os\nimport subprocess\nimport time\nfrom dataclasses import dataclass, field\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\n\nSYSTEM = (\n    f\"You are a coding agent at {WORKDIR}. \"\n    \"Keep working step by step, and use compact if the conversation gets too long.\"\n)\n\nCONTEXT_LIMIT = 50000\nKEEP_RECENT_TOOL_RESULTS = 3\nPERSIST_THRESHOLD = 30000\nPREVIEW_CHARS = 2000\nTRANSCRIPT_DIR = WORKDIR / \".transcripts\"\nTOOL_RESULTS_DIR = WORKDIR / \".task_outputs\" / \"tool-results\"\n\n\n@dataclass\nclass CompactState:\n    has_compacted: bool = False\n    last_summary: str = \"\"\n    recent_files: list[str] = field(default_factory=list)\n\n\ndef estimate_context_size(messages: list) -> int:\n    return len(str(messages))\n\n\ndef track_recent_file(state: CompactState, path: str) -> None:\n    if path in state.recent_files:\n        state.recent_files.remove(path)\n    state.recent_files.append(path)\n    if len(state.recent_files) > 5:\n        state.recent_files[:] = state.recent_files[-5:]\n\n\ndef safe_path(path_str: str) -> Path:\n    path = (WORKDIR / path_str).resolve()\n    if not path.is_relative_to(WORKDIR):\n        raise ValueError(f\"Path escapes workspace: {path_str}\")\n    return path\n\n\ndef persist_large_output(tool_use_id: str, output: str) -> str:\n    if len(output) <= PERSIST_THRESHOLD:\n        return output\n\n    TOOL_RESULTS_DIR.mkdir(parents=True, exist_ok=True)\n    stored_path = TOOL_RESULTS_DIR / f\"{tool_use_id}.txt\"\n    if not stored_path.exists():\n        stored_path.write_text(output)\n\n    preview = output[:PREVIEW_CHARS]\n    rel_path = stored_path.relative_to(WORKDIR)\n    return (\n        \"<persisted-output>\\n\"\n        f\"Full output saved to: {rel_path}\\n\"\n        \"Preview:\\n\"\n        f\"{preview}\\n\"\n        \"</persisted-output>\"\n    )\n\n\ndef collect_tool_result_blocks(messages: list) -> list[tuple[int, int, dict]]:\n    blocks = []\n    for message_index, message in enumerate(messages):\n        content = message.get(\"content\")\n        if message.get(\"role\") != \"user\" or not isinstance(content, list):\n            continue\n        for block_index, block in enumerate(content):\n            if isinstance(block, dict) and block.get(\"type\") == \"tool_result\":\n                blocks.append((message_index, block_index, block))\n    return blocks\n\n\ndef micro_compact(messages: list) -> list:\n    tool_results = collect_tool_result_blocks(messages)\n    if len(tool_results) <= KEEP_RECENT_TOOL_RESULTS:\n        return messages\n\n    for _, _, block in tool_results[:-KEEP_RECENT_TOOL_RESULTS]:\n        content = block.get(\"content\", \"\")\n        if not isinstance(content, str) or len(content) <= 120:\n            continue\n        block[\"content\"] = \"[Earlier tool result compacted. Re-run the tool if you need full detail.]\"\n    return messages\n\n\ndef write_transcript(messages: list) -> Path:\n    TRANSCRIPT_DIR.mkdir(parents=True, exist_ok=True)\n    path = TRANSCRIPT_DIR / f\"transcript_{int(time.time())}.jsonl\"\n    with path.open(\"w\") as handle:\n        for message in messages:\n            handle.write(json.dumps(message, default=str) + \"\\n\")\n    return path\n\n\ndef summarize_history(messages: list) -> str:\n    conversation = json.dumps(messages, default=str)[:80000]\n    prompt = (\n        \"Summarize this coding-agent conversation so work can continue.\\n\"\n        \"Preserve:\\n\"\n        \"1. The current goal\\n\"\n        \"2. Important findings and decisions\\n\"\n        \"3. Files read or changed\\n\"\n        \"4. Remaining work\\n\"\n        \"5. User constraints and preferences\\n\"\n        \"Be compact but concrete.\\n\\n\"\n        f\"{conversation}\"\n    )\n    response = client.messages.create(\n        model=MODEL,\n        messages=[{\"role\": \"user\", \"content\": prompt}],\n        max_tokens=2000,\n    )\n    return response.content[0].text.strip()\n\n\ndef compact_history(messages: list, state: CompactState, focus: str | None = None) -> list:\n    transcript_path = write_transcript(messages)\n    print(f\"[transcript saved: {transcript_path}]\")\n\n    summary = summarize_history(messages)\n    if focus:\n        summary += f\"\\n\\nFocus to preserve next: {focus}\"\n    if state.recent_files:\n        recent_lines = \"\\n\".join(f\"- {path}\" for path in state.recent_files)\n        summary += f\"\\n\\nRecent files to reopen if needed:\\n{recent_lines}\"\n\n    state.has_compacted = True\n    state.last_summary = summary\n\n    return [{\n        \"role\": \"user\",\n        \"content\": (\n            \"This conversation was compacted so the agent can continue working.\\n\\n\"\n            f\"{summary}\"\n        ),\n    }]\n\n\ndef run_bash(command: str, tool_use_id: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(item in command for item in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        result = subprocess.run(\n            command,\n            shell=True,\n            cwd=WORKDIR,\n            capture_output=True,\n            text=True,\n            timeout=120,\n        )\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\n    output = (result.stdout + result.stderr).strip() or \"(no output)\"\n    return persist_large_output(tool_use_id, output)\n\n\ndef run_read(path: str, tool_use_id: str, state: CompactState, limit: int | None = None) -> str:\n    try:\n        track_recent_file(state, path)\n        lines = safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more lines)\"]\n        output = \"\\n\".join(lines)\n        return persist_large_output(tool_use_id, output)\n    except Exception as exc:\n        return f\"Error: {exc}\"\n\n\ndef run_write(path: str, content: str) -> str:\n    try:\n        file_path = safe_path(path)\n        file_path.parent.mkdir(parents=True, exist_ok=True)\n        file_path.write_text(content)\n        return f\"Wrote {len(content)} bytes to {path}\"\n    except Exception as exc:\n        return f\"Error: {exc}\"\n\n\ndef run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        file_path = safe_path(path)\n        content = file_path.read_text()\n        if old_text not in content:\n            return f\"Error: Text not found in {path}\"\n        file_path.write_text(content.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as exc:\n        return f\"Error: {exc}\"\n\n\nTOOLS = [\n    {\n        \"name\": \"bash\",\n        \"description\": \"Run a shell command.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\"command\": {\"type\": \"string\"}},\n            \"required\": [\"command\"],\n        },\n    },\n    {\n        \"name\": \"read_file\",\n        \"description\": \"Read file contents.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"path\": {\"type\": \"string\"},\n                \"limit\": {\"type\": \"integer\"},\n            },\n            \"required\": [\"path\"],\n        },\n    },\n    {\n        \"name\": \"write_file\",\n        \"description\": \"Write content to a file.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"path\": {\"type\": \"string\"},\n                \"content\": {\"type\": \"string\"},\n            },\n            \"required\": [\"path\", \"content\"],\n        },\n    },\n    {\n        \"name\": \"edit_file\",\n        \"description\": \"Replace exact text in a file once.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"path\": {\"type\": \"string\"},\n                \"old_text\": {\"type\": \"string\"},\n                \"new_text\": {\"type\": \"string\"},\n            },\n            \"required\": [\"path\", \"old_text\", \"new_text\"],\n        },\n    },\n    {\n        \"name\": \"compact\",\n        \"description\": \"Summarize earlier conversation so work can continue in a smaller context.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"focus\": {\"type\": \"string\"},\n            },\n        },\n    },\n]\n\n\ndef extract_text(content) -> str:\n    if not isinstance(content, list):\n        return \"\"\n    texts = []\n    for block in content:\n        text = getattr(block, \"text\", None)\n        if text:\n            texts.append(text)\n    return \"\\n\".join(texts).strip()\n\n\ndef execute_tool(block, state: CompactState) -> str:\n    if block.name == \"bash\":\n        return run_bash(block.input[\"command\"], block.id)\n    if block.name == \"read_file\":\n        return run_read(block.input[\"path\"], block.id, state, block.input.get(\"limit\"))\n    if block.name == \"write_file\":\n        return run_write(block.input[\"path\"], block.input[\"content\"])\n    if block.name == \"edit_file\":\n        return run_edit(block.input[\"path\"], block.input[\"old_text\"], block.input[\"new_text\"])\n    if block.name == \"compact\":\n        return \"Compacting conversation...\"\n    return f\"Unknown tool: {block.name}\"\n\n\ndef agent_loop(messages: list, state: CompactState) -> None:\n    while True:\n        messages[:] = micro_compact(messages)\n\n        if estimate_context_size(messages) > CONTEXT_LIMIT:\n            print(\"[auto compact]\")\n            messages[:] = compact_history(messages, state)\n\n        response = client.messages.create(\n            model=MODEL,\n            system=SYSTEM,\n            messages=messages,\n            tools=TOOLS,\n            max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n\n        if response.stop_reason != \"tool_use\":\n            return\n\n        results = []\n        manual_compact = False\n        compact_focus = None\n        for block in response.content:\n            if block.type != \"tool_use\":\n                continue\n\n            output = execute_tool(block, state)\n            if block.name == \"compact\":\n                manual_compact = True\n                compact_focus = (block.input or {}).get(\"focus\")\n\n            print(f\"> {block.name}: {str(output)[:200]}\")\n            results.append({\n                \"type\": \"tool_result\",\n                \"tool_use_id\": block.id,\n                \"content\": str(output),\n            })\n\n        messages.append({\"role\": \"user\", \"content\": results})\n\n        if manual_compact:\n            print(\"[manual compact]\")\n            messages[:] = compact_history(messages, state, focus=compact_focus)\n\n\nif __name__ == \"__main__\":\n    history = []\n    compact_state = CompactState()\n\n    while True:\n        try:\n            query = input(\"\\033[36ms06 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history, compact_state)\n\n        final_text = extract_text(history[-1][\"content\"])\n        if final_text:\n            print(final_text)\n        print()\n"
+    },
+    {
+      "id": "s07",
+      "filename": "s07_permission_system.py",
+      "title": "Permission System",
+      "subtitle": "Intent Must Pass Safety",
+      "loc": 308,
+      "tools": [
+        "bash",
+        "read_file",
+        "write_file",
+        "edit_file"
+      ],
+      "newTools": [],
+      "coreAddition": "deny / mode / allow / ask pipeline",
+      "keyInsight": "Safety is a pipeline, not a boolean: deny, check mode, allow, then ask.",
+      "classes": [
+        {
+          "name": "BashSecurityValidator",
+          "startLine": 55,
+          "endLine": 98
+        },
+        {
+          "name": "PermissionManager",
+          "startLine": 127,
+          "endLine": 250
+        }
+      ],
+      "functions": [
+        {
+          "name": "is_workspace_trusted",
+          "signature": "def is_workspace_trusted(workspace: Path = None)",
+          "startLine": 99
+        },
+        {
+          "name": "safe_path",
+          "signature": "def safe_path(p: str)",
+          "startLine": 251
+        },
+        {
+          "name": "run_bash",
+          "signature": "def run_bash(command: str)",
+          "startLine": 258
+        },
+        {
+          "name": "run_read",
+          "signature": "def run_read(path: str, limit: int = None)",
+          "startLine": 268
+        },
+        {
+          "name": "run_write",
+          "signature": "def run_write(path: str, content: str)",
+          "startLine": 278
+        },
+        {
+          "name": "run_edit",
+          "signature": "def run_edit(path: str, old_text: str, new_text: str)",
+          "startLine": 288
+        },
+        {
+          "name": "agent_loop",
+          "signature": "def agent_loop(messages: list, perms: PermissionManager)",
+          "startLine": 322
+        }
+      ],
+      "layer": "hardening",
+      "source": "#!/usr/bin/env python3\n# Harness: safety -- the pipeline between intent and execution.\n\"\"\"\ns07_permission_system.py - Permission System\n\nEvery tool call passes through a permission pipeline before execution.\n\nTeaching pipeline:\n  1. deny rules\n  2. mode check\n  3. allow rules\n  4. ask user\n\nThis version intentionally teaches three modes first:\n  - default\n  - plan\n  - auto\n\nThat is enough to build a real, understandable permission system without\nburying readers under every advanced policy branch on day one.\n\nKey insight: \"Safety is a pipeline, not a boolean.\"\n\"\"\"\n\nimport json\nimport os\nimport re\nimport subprocess\nfrom fnmatch import fnmatch\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\n\n# -- Permission modes --\n# Teaching version starts with three clear modes first.\nMODES = (\"default\", \"plan\", \"auto\")\n\nREAD_ONLY_TOOLS = {\"read_file\", \"bash_readonly\"}\n\n# Tools that modify state\nWRITE_TOOLS = {\"write_file\", \"edit_file\", \"bash\"}\n\n\n# -- Bash security validation --\nclass BashSecurityValidator:\n    \"\"\"\n    Validate bash commands for obviously dangerous patterns.\n\n    The teaching version deliberately keeps this small and easy to read.\n    First catch a few high-risk patterns, then let the permission pipeline\n    decide whether to deny or ask the user.\n    \"\"\"\n\n    VALIDATORS = [\n        (\"shell_metachar\", r\"[;&|`$]\"),       # shell metacharacters\n        (\"sudo\", r\"\\bsudo\\b\"),                 # privilege escalation\n        (\"rm_rf\", r\"\\brm\\s+(-[a-zA-Z]*)?r\"),  # recursive delete\n        (\"cmd_substitution\", r\"\\$\\(\"),          # command substitution\n        (\"ifs_injection\", r\"\\bIFS\\s*=\"),        # IFS manipulation\n    ]\n\n    def validate(self, command: str) -> list:\n        \"\"\"\n        Check a bash command against all validators.\n\n        Returns list of (validator_name, matched_pattern) tuples for failures.\n        An empty list means the command passed all validators.\n        \"\"\"\n        failures = []\n        for name, pattern in self.VALIDATORS:\n            if re.search(pattern, command):\n                failures.append((name, pattern))\n        return failures\n\n    def is_safe(self, command: str) -> bool:\n        \"\"\"Convenience: returns True only if no validators triggered.\"\"\"\n        return len(self.validate(command)) == 0\n\n    def describe_failures(self, command: str) -> str:\n        \"\"\"Human-readable summary of validation failures.\"\"\"\n        failures = self.validate(command)\n        if not failures:\n            return \"No issues detected\"\n        parts = [f\"{name} (pattern: {pattern})\" for name, pattern in failures]\n        return \"Security flags: \" + \", \".join(parts)\n\n\n# -- Workspace trust --\ndef is_workspace_trusted(workspace: Path = None) -> bool:\n    \"\"\"\n    Check if a workspace has been explicitly marked as trusted.\n\n    The teaching version uses a simple marker file. A more complete system\n    can layer richer trust flows on top of the same idea.\n    \"\"\"\n    ws = workspace or WORKDIR\n    trust_marker = ws / \".claude\" / \".claude_trusted\"\n    return trust_marker.exists()\n\n\n# Singleton validator instance used by the permission pipeline\nbash_validator = BashSecurityValidator()\n\n\n# -- Permission rules --\n# Rules are checked in order: first match wins.\n# Format: {\"tool\": \"<tool_name_or_*>\", \"path\": \"<glob_or_*>\", \"behavior\": \"allow|deny|ask\"}\nDEFAULT_RULES = [\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\nclass PermissionManager:\n    \"\"\"\n    Manages permission decisions for tool calls.\n\n    Pipeline: deny_rules -> mode_check -> allow_rules -> ask_user\n\n    The teaching version keeps the decision path short on purpose so readers\n    can implement it themselves before adding more advanced policy layers.\n    \"\"\"\n\n    def __init__(self, mode: str = \"default\", rules: list = None):\n        if mode not in MODES:\n            raise ValueError(f\"Unknown mode: {mode}. Choose from {MODES}\")\n        self.mode = mode\n        self.rules = rules or list(DEFAULT_RULES)\n        # Simple denial tracking helps surface when the agent is repeatedly\n        # asking for actions the system will not allow.\n        self.consecutive_denials = 0\n        self.max_consecutive_denials = 3\n\n    def check(self, tool_name: str, tool_input: dict) -> dict:\n        \"\"\"\n        Returns: {\"behavior\": \"allow\"|\"deny\"|\"ask\", \"reason\": str}\n        \"\"\"\n        # Step 0: Bash security validation (before deny rules)\n        # Teaching version checks early for clarity.\n        if tool_name == \"bash\":\n            command = tool_input.get(\"command\", \"\")\n            failures = bash_validator.validate(command)\n            if failures:\n                # Severe patterns (sudo, rm_rf) get immediate deny\n                severe = {\"sudo\", \"rm_rf\"}\n                severe_hits = [f for f in failures if f[0] in severe]\n                if severe_hits:\n                    desc = bash_validator.describe_failures(command)\n                    return {\"behavior\": \"deny\",\n                            \"reason\": f\"Bash validator: {desc}\"}\n                # Other patterns escalate to ask (user can still approve)\n                desc = bash_validator.describe_failures(command)\n                return {\"behavior\": \"ask\",\n                        \"reason\": f\"Bash validator flagged: {desc}\"}\n\n        # Step 1: Deny rules (bypass-immune, checked first always)\n        for rule in self.rules:\n            if rule[\"behavior\"] != \"deny\":\n                continue\n            if self._matches(rule, tool_name, tool_input):\n                return {\"behavior\": \"deny\",\n                        \"reason\": f\"Blocked by deny rule: {rule}\"}\n\n        # Step 2: Mode-based decisions\n        if self.mode == \"plan\":\n            # Plan mode: deny all write operations, allow reads\n            if tool_name in WRITE_TOOLS:\n                return {\"behavior\": \"deny\",\n                        \"reason\": \"Plan mode: write operations are blocked\"}\n            return {\"behavior\": \"allow\", \"reason\": \"Plan mode: read-only allowed\"}\n\n        if self.mode == \"auto\":\n            # Auto mode: auto-allow read-only tools, ask for writes\n            if tool_name in READ_ONLY_TOOLS or tool_name == \"read_file\":\n                return {\"behavior\": \"allow\",\n                        \"reason\": \"Auto mode: read-only tool auto-approved\"}\n            # Teaching: fall through to allow rules, then ask\n            pass\n\n        # Step 3: Allow rules\n        for rule in self.rules:\n            if rule[\"behavior\"] != \"allow\":\n                continue\n            if self._matches(rule, tool_name, tool_input):\n                self.consecutive_denials = 0\n                return {\"behavior\": \"allow\",\n                        \"reason\": f\"Matched allow rule: {rule}\"}\n\n        # Step 4: Ask user (default behavior for unmatched tools)\n        return {\"behavior\": \"ask\",\n                \"reason\": f\"No rule matched for {tool_name}, asking user\"}\n\n    def ask_user(self, tool_name: str, tool_input: dict) -> bool:\n        \"\"\"Interactive approval prompt. Returns True if approved.\"\"\"\n        preview = json.dumps(tool_input, ensure_ascii=False)[:200]\n        print(f\"\\n  [Permission] {tool_name}: {preview}\")\n        try:\n            answer = input(\"  Allow? (y/n/always): \").strip().lower()\n        except (EOFError, KeyboardInterrupt):\n            return False\n\n        if answer == \"always\":\n            # Add permanent allow rule for this tool\n            self.rules.append({\"tool\": tool_name, \"path\": \"*\", \"behavior\": \"allow\"})\n            self.consecutive_denials = 0\n            return True\n        if answer in (\"y\", \"yes\"):\n            self.consecutive_denials = 0\n            return True\n\n        # Track denials for circuit breaker\n        self.consecutive_denials += 1\n        if self.consecutive_denials >= self.max_consecutive_denials:\n            print(f\"  [{self.consecutive_denials} consecutive denials -- \"\n                  \"consider switching to plan mode]\")\n        return False\n\n    def _matches(self, rule: dict, tool_name: str, tool_input: dict) -> bool:\n        \"\"\"Check if a rule matches the tool call.\"\"\"\n        # Tool name match\n        if rule.get(\"tool\") and rule[\"tool\"] != \"*\":\n            if rule[\"tool\"] != tool_name:\n                return False\n        # Path pattern match\n        if \"path\" in rule and rule[\"path\"] != \"*\":\n            path = tool_input.get(\"path\", \"\")\n            if not fnmatch(path, rule[\"path\"]):\n                return False\n        # Content pattern match (for bash commands)\n        if \"content\" in rule:\n            command = tool_input.get(\"command\", \"\")\n            if not fnmatch(command, rule[\"content\"]):\n                return False\n        return True\n\n\n# -- Tool implementations --\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\n\ndef run_bash(command: str) -> str:\n    try:\n        r = subprocess.run(command, shell=True, cwd=WORKDIR,\n                           capture_output=True, text=True, timeout=120)\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\n\ndef run_read(path: str, limit: int = None) -> str:\n    try:\n        lines = safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef run_write(path: str, content: str) -> str:\n    try:\n        fp = safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = safe_path(path)\n        content = fp.read_text()\n        if old_text not in content:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(content.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\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\"], kw[\"new_text\"]),\n}\n\nTOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n]\n\nSYSTEM = f\"\"\"You are a coding agent at {WORKDIR}. Use tools to solve tasks.\nThe user controls permissions. Some tool calls may be denied.\"\"\"\n\n\ndef agent_loop(messages: list, perms: PermissionManager):\n    \"\"\"\n    The permission-aware agent loop.\n\n    For each tool call:\n      1. LLM requests tool use\n      2. Permission pipeline checks: deny_rules -> mode -> allow_rules -> ask\n      3. If allowed: execute tool, return result\n      4. If denied: return rejection message to LLM\n    \"\"\"\n    while True:\n        response = client.messages.create(\n            model=MODEL, system=SYSTEM, messages=messages,\n            tools=TOOLS, max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n\n        if response.stop_reason != \"tool_use\":\n            return\n\n        results = []\n        for block in response.content:\n            if block.type != \"tool_use\":\n                continue\n\n            # -- Permission check --\n            decision = perms.check(block.name, block.input or {})\n\n            if decision[\"behavior\"] == \"deny\":\n                output = f\"Permission denied: {decision['reason']}\"\n                print(f\"  [DENIED] {block.name}: {decision['reason']}\")\n\n            elif decision[\"behavior\"] == \"ask\":\n                if perms.ask_user(block.name, block.input or {}):\n                    handler = TOOL_HANDLERS.get(block.name)\n                    output = handler(**(block.input or {})) if handler else f\"Unknown: {block.name}\"\n                    print(f\"> {block.name}: {str(output)[:200]}\")\n                else:\n                    output = f\"Permission denied by user for {block.name}\"\n                    print(f\"  [USER DENIED] {block.name}\")\n\n            else:  # allow\n                handler = TOOL_HANDLERS.get(block.name)\n                output = handler(**(block.input or {})) if handler else f\"Unknown: {block.name}\"\n                print(f\"> {block.name}: {str(output)[:200]}\")\n\n            results.append({\n                \"type\": \"tool_result\",\n                \"tool_use_id\": block.id,\n                \"content\": str(output),\n            })\n\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    # Choose permission mode at startup\n    print(\"Permission modes: default, plan, auto\")\n    mode_input = input(\"Mode (default): \").strip().lower() or \"default\"\n    if mode_input not in MODES:\n        mode_input = \"default\"\n\n    perms = PermissionManager(mode=mode_input)\n    print(f\"[Permission mode: {mode_input}]\")\n\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms07 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n\n        # /mode command to switch modes at runtime\n        if query.startswith(\"/mode\"):\n            parts = query.split()\n            if len(parts) == 2 and parts[1] in MODES:\n                perms.mode = parts[1]\n                print(f\"[Switched to {parts[1]} mode]\")\n            else:\n                print(f\"Usage: /mode <{'|'.join(MODES)}>\")\n            continue\n\n        # /rules command to show current rules\n        if query.strip() == \"/rules\":\n            for i, rule in enumerate(perms.rules):\n                print(f\"  {i}: {rule}\")\n            continue\n\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history, perms)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
+    },
+    {
+      "id": "s08",
+      "filename": "s08_hook_system.py",
+      "title": "Hook System",
+      "subtitle": "Extend Without Rewriting the Loop",
+      "loc": 252,
+      "tools": [
+        "bash",
+        "read_file",
+        "write_file",
+        "edit_file"
+      ],
+      "newTools": [],
+      "coreAddition": "Lifecycle events + side-effect hooks",
+      "keyInsight": "The loop owns control flow; hooks only observe, block, or annotate at named moments.",
+      "classes": [
+        {
+          "name": "HookManager",
+          "startLine": 56,
+          "endLine": 177
+        }
+      ],
+      "functions": [
+        {
+          "name": "safe_path",
+          "signature": "def safe_path(p: str)",
+          "startLine": 178
+        },
+        {
+          "name": "run_bash",
+          "signature": "def run_bash(command: str)",
+          "startLine": 185
+        },
+        {
+          "name": "run_read",
+          "signature": "def run_read(path: str, limit: int = None)",
+          "startLine": 198
+        },
+        {
+          "name": "run_write",
+          "signature": "def run_write(path: str, content: str)",
+          "startLine": 208
+        },
+        {
+          "name": "run_edit",
+          "signature": "def run_edit(path: str, old_text: str, new_text: str)",
+          "startLine": 218
+        },
+        {
+          "name": "agent_loop",
+          "signature": "def agent_loop(messages: list, hooks: HookManager)",
+          "startLine": 251
+        }
+      ],
+      "layer": "hardening",
+      "source": "#!/usr/bin/env python3\n# Harness: extensibility -- injecting behavior without touching the loop.\n\"\"\"\ns08_hook_system.py - Hook System\n\nHooks are extension points around the main loop.\nThey let readers add behavior without rewriting the loop itself.\n\nTeaching version:\n  - SessionStart\n  - PreToolUse\n  - PostToolUse\n\nTeaching exit-code contract:\n  - 0 -> continue\n  - 1 -> block\n  - 2 -> inject a message\n\nThis is intentionally simpler than a production system. The goal here is to\nteach the extension pattern clearly before introducing event-specific edge\ncases.\n\nKey insight: \"Extend the agent without touching the loop.\"\n\"\"\"\n\nimport json\nimport os\nimport subprocess\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\n\n# The teaching version keeps only the three clearest events. More complete\n# systems can grow the event surface later.\n\nHOOK_EVENTS = (\"PreToolUse\", \"PostToolUse\", \"SessionStart\")\nHOOK_TIMEOUT = 30  # seconds\n# Real CC timeouts:\n#   TOOL_HOOK_EXECUTION_TIMEOUT_MS = 600000 (10 minutes for tool hooks)\n#   SESSION_END_HOOK_TIMEOUT_MS = 1500 (1.5 seconds for SessionEnd hooks)\n\n# Workspace trust marker. Hooks only run if this file exists (or SDK mode).\nTRUST_MARKER = WORKDIR / \".claude\" / \".claude_trusted\"\n\n\nclass HookManager:\n    \"\"\"\n    Load and execute hooks from .hooks.json configuration.\n\n    The hook manager does three simple jobs:\n    - load hook definitions\n    - run matching commands for an event\n    - aggregate block / message results for the caller\n    \"\"\"\n\n    def __init__(self, config_path: Path = None, sdk_mode: bool = False):\n        self.hooks = {\"PreToolUse\": [], \"PostToolUse\": [], \"SessionStart\": []}\n        self._sdk_mode = sdk_mode\n        config_path = config_path or (WORKDIR / \".hooks.json\")\n        if config_path.exists():\n            try:\n                config = json.loads(config_path.read_text())\n                for event in HOOK_EVENTS:\n                    self.hooks[event] = config.get(\"hooks\", {}).get(event, [])\n                print(f\"[Hooks loaded from {config_path}]\")\n            except Exception as e:\n                print(f\"[Hook config error: {e}]\")\n\n    def _check_workspace_trust(self) -> bool:\n        \"\"\"\n        Check whether the current workspace is trusted.\n\n        The teaching version uses a simple trust marker file.\n        In SDK mode, trust is treated as implicit.\n        \"\"\"\n        if self._sdk_mode:\n            return True\n        return TRUST_MARKER.exists()\n\n    def run_hooks(self, event: str, context: dict = None) -> dict:\n        \"\"\"\n        Execute all hooks for an event.\n\n        Returns: {\"blocked\": bool, \"messages\": list[str]}\n          - blocked: True if any hook returned exit code 1\n          - messages: stderr content from exit-code-2 hooks (to inject)\n        \"\"\"\n        result = {\"blocked\": False, \"messages\": []}\n\n        # Trust gate: refuse to run hooks in untrusted workspaces\n        if not self._check_workspace_trust():\n            return result\n\n        hooks = self.hooks.get(event, [])\n\n        for hook_def in hooks:\n            # Check matcher (tool name filter for PreToolUse/PostToolUse)\n            matcher = hook_def.get(\"matcher\")\n            if matcher and context:\n                tool_name = context.get(\"tool_name\", \"\")\n                if matcher != \"*\" and matcher != tool_name:\n                    continue\n\n            command = hook_def.get(\"command\", \"\")\n            if not command:\n                continue\n\n            # Build environment with hook context\n            env = dict(os.environ)\n            if context:\n                env[\"HOOK_EVENT\"] = event\n                env[\"HOOK_TOOL_NAME\"] = context.get(\"tool_name\", \"\")\n                env[\"HOOK_TOOL_INPUT\"] = json.dumps(\n                    context.get(\"tool_input\", {}), ensure_ascii=False)[:10000]\n                if \"tool_output\" in context:\n                    env[\"HOOK_TOOL_OUTPUT\"] = str(\n                        context[\"tool_output\"])[:10000]\n\n            try:\n                r = subprocess.run(\n                    command, shell=True, cwd=WORKDIR, env=env,\n                    capture_output=True, text=True, timeout=HOOK_TIMEOUT,\n                )\n\n                if r.returncode == 0:\n                    # Continue silently\n                    if r.stdout.strip():\n                        print(f\"  [hook:{event}] {r.stdout.strip()[:100]}\")\n\n                    # Optional structured stdout: small extension point that\n                    # keeps the teaching contract simple.\n                    try:\n                        hook_output = json.loads(r.stdout)\n                        if \"updatedInput\" in hook_output and context:\n                            context[\"tool_input\"] = hook_output[\"updatedInput\"]\n                        if \"additionalContext\" in hook_output:\n                            result[\"messages\"].append(\n                                hook_output[\"additionalContext\"])\n                        if \"permissionDecision\" in hook_output:\n                            result[\"permission_override\"] = (\n                                hook_output[\"permissionDecision\"])\n                    except (json.JSONDecodeError, TypeError):\n                        pass  # stdout was not JSON -- normal for simple hooks\n\n                elif r.returncode == 1:\n                    # Block execution\n                    result[\"blocked\"] = True\n                    reason = r.stderr.strip() or \"Blocked by hook\"\n                    result[\"block_reason\"] = reason\n                    print(f\"  [hook:{event}] BLOCKED: {reason[:200]}\")\n\n                elif r.returncode == 2:\n                    # Inject message\n                    msg = r.stderr.strip()\n                    if msg:\n                        result[\"messages\"].append(msg)\n                        print(f\"  [hook:{event}] INJECT: {msg[:200]}\")\n\n            except subprocess.TimeoutExpired:\n                print(f\"  [hook:{event}] Timeout ({HOOK_TIMEOUT}s)\")\n            except Exception as e:\n                print(f\"  [hook:{event}] Error: {e}\")\n\n        return result\n\n\n# -- Tool implementations (same as s02) --\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\n\ndef run_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(command, shell=True, cwd=WORKDIR,\n                           capture_output=True, text=True, timeout=120)\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\n\ndef run_read(path: str, limit: int = None) -> str:\n    try:\n        lines = safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef run_write(path: str, content: str) -> str:\n    try:\n        fp = safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = safe_path(path)\n        content = fp.read_text()\n        if old_text not in content:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(content.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\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\"], kw[\"new_text\"]),\n}\n\nTOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n]\n\nSYSTEM = f\"You are a coding agent at {WORKDIR}. Use tools to solve tasks.\"\n\n\ndef agent_loop(messages: list, hooks: HookManager):\n    \"\"\"\n    The hook-aware agent loop.\n\n    The teaching version keeps only the clearest integration points:\n    SessionStart, PreToolUse, execute tool, PostToolUse.\n    \"\"\"\n    while True:\n        response = client.messages.create(\n            model=MODEL, system=SYSTEM, messages=messages,\n            tools=TOOLS, max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n\n        if response.stop_reason != \"tool_use\":\n            return\n\n        results = []\n        for block in response.content:\n            if block.type != \"tool_use\":\n                continue\n\n            tool_input = dict(block.input or {})\n            ctx = {\"tool_name\": block.name, \"tool_input\": tool_input}\n\n            # -- PreToolUse hooks --\n            pre_result = hooks.run_hooks(\"PreToolUse\", ctx)\n\n            # Inject hook messages into results\n            for msg in pre_result.get(\"messages\", []):\n                results.append({\n                    \"type\": \"tool_result\", \"tool_use_id\": block.id,\n                    \"content\": f\"[Hook message]: {msg}\",\n                })\n\n            if pre_result.get(\"blocked\"):\n                reason = pre_result.get(\"block_reason\", \"Blocked by hook\")\n                output = f\"Tool blocked by PreToolUse hook: {reason}\"\n                results.append({\n                    \"type\": \"tool_result\", \"tool_use_id\": block.id,\n                    \"content\": output,\n                })\n                continue\n\n            # -- Execute tool --\n            handler = TOOL_HANDLERS.get(block.name)\n            try:\n                output = handler(**tool_input) if handler else f\"Unknown: {block.name}\"\n            except Exception as e:\n                output = f\"Error: {e}\"\n            print(f\"> {block.name}: {str(output)[:200]}\")\n\n            # -- PostToolUse hooks --\n            ctx[\"tool_output\"] = output\n            post_result = hooks.run_hooks(\"PostToolUse\", ctx)\n\n            # Inject post-hook messages\n            for msg in post_result.get(\"messages\", []):\n                output += f\"\\n[Hook note]: {msg}\"\n\n            results.append({\n                \"type\": \"tool_result\", \"tool_use_id\": block.id,\n                \"content\": str(output),\n            })\n\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    hooks = HookManager()\n\n    # Fire SessionStart hooks\n    hooks.run_hooks(\"SessionStart\", {\"tool_name\": \"\", \"tool_input\": {}})\n\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms08 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history, hooks)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
+    },
+    {
+      "id": "s09",
+      "filename": "s09_memory_system.py",
+      "title": "Memory System",
+      "subtitle": "Keep Only What Survives Sessions",
+      "loc": 414,
+      "tools": [
+        "bash",
+        "read_file",
+        "write_file",
+        "edit_file",
+        "save_memory"
+      ],
+      "newTools": [
+        "save_memory"
+      ],
+      "coreAddition": "Typed memory records + reload path",
+      "keyInsight": "Memory gives direction; current observation gives truth.",
+      "classes": [
+        {
+          "name": "MemoryManager",
+          "startLine": 64,
+          "endLine": 189
+        },
+        {
+          "name": "DreamConsolidator",
+          "startLine": 190,
+          "endLine": 345
+        }
+      ],
+      "functions": [
+        {
+          "name": "safe_path",
+          "signature": "def safe_path(p: str)",
+          "startLine": 346
+        },
+        {
+          "name": "run_bash",
+          "signature": "def run_bash(command: str)",
+          "startLine": 353
+        },
+        {
+          "name": "run_read",
+          "signature": "def run_read(path: str, limit: int = None)",
+          "startLine": 366
+        },
+        {
+          "name": "run_write",
+          "signature": "def run_write(path: str, content: str)",
+          "startLine": 376
+        },
+        {
+          "name": "run_edit",
+          "signature": "def run_edit(path: str, old_text: str, new_text: str)",
+          "startLine": 386
+        },
+        {
+          "name": "run_save_memory",
+          "signature": "def run_save_memory(name: str, description: str, mem_type: str, content: str)",
+          "startLine": 402
+        },
+        {
+          "name": "build_system_prompt",
+          "signature": "def build_system_prompt()",
+          "startLine": 450
+        },
+        {
+          "name": "agent_loop",
+          "signature": "def agent_loop(messages: list)",
+          "startLine": 463
         }
       ],
-      "layer": "planning",
-      "source": "#!/usr/bin/env python3\n\"\"\"\ns04_subagent.py - Subagents\n\nSpawn a child agent with fresh messages=[]. The child works in its own\ncontext, sharing the filesystem, then returns only a summary to the parent.\n\n    Parent agent                     Subagent\n    +------------------+             +------------------+\n    | messages=[...]   |             | messages=[]      |  <-- fresh\n    |                  |  dispatch   |                  |\n    | tool: task       | ---------->| while tool_use:  |\n    |   prompt=\"...\"   |            |   call tools     |\n    |   description=\"\" |            |   append results |\n    |                  |  summary   |                  |\n    |   result = \"...\" | <--------- | return last text |\n    +------------------+             +------------------+\n              |\n    Parent context stays clean.\n    Subagent context is discarded.\n\nKey insight: \"Process isolation gives context isolation for free.\"\n\"\"\"\n\nimport os\nimport subprocess\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\n\nSYSTEM = f\"You are a coding agent at {WORKDIR}. Use the task tool to delegate exploration or subtasks.\"\nSUBAGENT_SYSTEM = f\"You are a coding subagent at {WORKDIR}. Complete the given task, then summarize your findings.\"\n\n\n# -- Tool implementations shared by parent and child --\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_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(command, shell=True, cwd=WORKDIR,\n                           capture_output=True, text=True, timeout=120)\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\ndef run_read(path: str, limit: int = None) -> str:\n    try:\n        lines = safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\ndef run_write(path: str, content: str) -> str:\n    try:\n        fp = safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\ndef run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = safe_path(path)\n        content = fp.read_text()\n        if old_text not in content:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(content.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\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\"], kw[\"new_text\"]),\n}\n\n# Child gets all base tools except task (no recursive spawning)\nCHILD_TOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n]\n\n\n# -- Subagent: fresh context, filtered tools, summary-only return --\ndef run_subagent(prompt: str) -> str:\n    sub_messages = [{\"role\": \"user\", \"content\": prompt}]  # fresh context\n    for _ in range(30):  # safety limit\n        response = client.messages.create(\n            model=MODEL, system=SUBAGENT_SYSTEM, messages=sub_messages,\n            tools=CHILD_TOOLS, max_tokens=8000,\n        )\n        sub_messages.append({\"role\": \"assistant\", \"content\": response.content})\n        if response.stop_reason != \"tool_use\":\n            break\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                handler = TOOL_HANDLERS.get(block.name)\n                output = handler(**block.input) if handler else f\"Unknown tool: {block.name}\"\n                results.append({\"type\": \"tool_result\", \"tool_use_id\": block.id, \"content\": str(output)[:50000]})\n        sub_messages.append({\"role\": \"user\", \"content\": results})\n    # Only the final text returns to the parent -- child context is discarded\n    return \"\".join(b.text for b in response.content if hasattr(b, \"text\")) or \"(no summary)\"\n\n\n# -- Parent tools: base tools + task dispatcher --\nPARENT_TOOLS = CHILD_TOOLS + [\n    {\"name\": \"task\", \"description\": \"Spawn a subagent with fresh context. It shares the filesystem but not conversation history.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"prompt\": {\"type\": \"string\"}, \"description\": {\"type\": \"string\", \"description\": \"Short description of the task\"}}, \"required\": [\"prompt\"]}},\n]\n\n\ndef agent_loop(messages: list):\n    while True:\n        response = client.messages.create(\n            model=MODEL, system=SYSTEM, messages=messages,\n            tools=PARENT_TOOLS, max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n        if response.stop_reason != \"tool_use\":\n            return\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                if block.name == \"task\":\n                    desc = block.input.get(\"description\", \"subtask\")\n                    print(f\"> task ({desc}): {block.input['prompt'][:80]}\")\n                    output = run_subagent(block.input[\"prompt\"])\n                else:\n                    handler = TOOL_HANDLERS.get(block.name)\n                    output = handler(**block.input) if handler else f\"Unknown tool: {block.name}\"\n                print(f\"  {str(output)[:200]}\")\n                results.append({\"type\": \"tool_result\", \"tool_use_id\": block.id, \"content\": str(output)})\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms04 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
+      "layer": "hardening",
+      "source": "#!/usr/bin/env python3\n# Harness: persistence -- remembering across the session boundary.\n\"\"\"\ns09_memory_system.py - Memory System\n\nThis teaching version focuses on one core idea:\nsome information should survive the current conversation, but not everything\nbelongs in memory.\n\nUse memory for:\n  - user preferences\n  - repeated user feedback\n  - project facts that are NOT obvious from the current code\n  - pointers to external resources\n\nDo NOT use memory for:\n  - code structure that can be re-read from the repo\n  - temporary task state\n  - secrets\n\nStorage layout:\n  .memory/\n    MEMORY.md\n    prefer_tabs.md\n    review_style.md\n    incident_board.md\n\nEach memory is a small Markdown file with frontmatter.\nThe agent can save a memory through save_memory(), and the memory index\nis rebuilt after each write.\n\nAn optional \"Dream\" pass can later consolidate, deduplicate, and prune\nstored memories. It is useful, but it is not the first thing readers need\nto understand.\n\nKey insight: \"Memory only stores cross-session information that is still\nworth recalling later and is not easy to re-derive from the current repo.\"\n\"\"\"\n\nimport json\nimport os\nimport re\nimport subprocess\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\n\nMEMORY_DIR = WORKDIR / \".memory\"\nMEMORY_INDEX = MEMORY_DIR / \"MEMORY.md\"\nMEMORY_TYPES = (\"user\", \"feedback\", \"project\", \"reference\")\nMAX_INDEX_LINES = 200\n\n\nclass MemoryManager:\n    \"\"\"\n    Load, build, and save persistent memories across sessions.\n\n    The teaching version keeps memory explicit:\n    one Markdown file per memory, plus one compact index file.\n    \"\"\"\n\n    def __init__(self, memory_dir: Path = None):\n        self.memory_dir = memory_dir or MEMORY_DIR\n        self.memories = {}  # name -> {description, type, content}\n\n    def load_all(self):\n        \"\"\"Load MEMORY.md index and all individual memory files.\"\"\"\n        self.memories = {}\n        if not self.memory_dir.exists():\n            return\n\n        # Scan all .md files except MEMORY.md\n        for md_file in sorted(self.memory_dir.glob(\"*.md\")):\n            if md_file.name == \"MEMORY.md\":\n                continue\n            parsed = self._parse_frontmatter(md_file.read_text())\n            if parsed:\n                name = parsed.get(\"name\", md_file.stem)\n                self.memories[name] = {\n                    \"description\": parsed.get(\"description\", \"\"),\n                    \"type\": parsed.get(\"type\", \"project\"),\n                    \"content\": parsed.get(\"content\", \"\"),\n                    \"file\": md_file.name,\n                }\n\n        count = len(self.memories)\n        if count > 0:\n            print(f\"[Memory loaded: {count} memories from {self.memory_dir}]\")\n\n    def load_memory_prompt(self) -> str:\n        \"\"\"Build a memory section for injection into the system prompt.\"\"\"\n        if not self.memories:\n            return \"\"\n\n        sections = []\n        sections.append(\"# Memories (persistent across sessions)\")\n        sections.append(\"\")\n\n        # Group by type for readability\n        for mem_type in MEMORY_TYPES:\n            typed = {k: v for k, v in self.memories.items() if v[\"type\"] == mem_type}\n            if not typed:\n                continue\n            sections.append(f\"## [{mem_type}]\")\n            for name, mem in typed.items():\n                sections.append(f\"### {name}: {mem['description']}\")\n                if mem[\"content\"].strip():\n                    sections.append(mem[\"content\"].strip())\n                sections.append(\"\")\n\n        return \"\\n\".join(sections)\n\n    def save_memory(self, name: str, description: str, mem_type: str, content: str) -> str:\n        \"\"\"\n        Save a memory to disk and update the index.\n\n        Returns a status message.\n        \"\"\"\n        if mem_type not in MEMORY_TYPES:\n            return f\"Error: type must be one of {MEMORY_TYPES}\"\n\n        # Sanitize name for filename\n        safe_name = re.sub(r\"[^a-zA-Z0-9_-]\", \"_\", name.lower())\n        if not safe_name:\n            return \"Error: invalid memory name\"\n\n        self.memory_dir.mkdir(parents=True, exist_ok=True)\n\n        # Write individual memory file with frontmatter\n        frontmatter = (\n            f\"---\\n\"\n            f\"name: {name}\\n\"\n            f\"description: {description}\\n\"\n            f\"type: {mem_type}\\n\"\n            f\"---\\n\"\n            f\"{content}\\n\"\n        )\n        file_name = f\"{safe_name}.md\"\n        file_path = self.memory_dir / file_name\n        file_path.write_text(frontmatter)\n\n        # Update in-memory store\n        self.memories[name] = {\n            \"description\": description,\n            \"type\": mem_type,\n            \"content\": content,\n            \"file\": file_name,\n        }\n\n        # Rebuild MEMORY.md index\n        self._rebuild_index()\n\n        return f\"Saved memory '{name}' [{mem_type}] to {file_path.relative_to(WORKDIR)}\"\n\n    def _rebuild_index(self):\n        \"\"\"Rebuild MEMORY.md from current in-memory state, capped at 200 lines.\"\"\"\n        lines = [\"# Memory Index\", \"\"]\n        for name, mem in self.memories.items():\n            lines.append(f\"- {name}: {mem['description']} [{mem['type']}]\")\n            if len(lines) >= MAX_INDEX_LINES:\n                lines.append(f\"... (truncated at {MAX_INDEX_LINES} lines)\")\n                break\n        self.memory_dir.mkdir(parents=True, exist_ok=True)\n        MEMORY_INDEX.write_text(\"\\n\".join(lines) + \"\\n\")\n\n    def _parse_frontmatter(self, text: str) -> dict | None:\n        \"\"\"Parse --- delimited frontmatter + body content.\"\"\"\n        match = re.match(r\"^---\\s*\\n(.*?)\\n---\\s*\\n(.*)\", text, re.DOTALL)\n        if not match:\n            return None\n        header, body = match.group(1), match.group(2)\n        result = {\"content\": body.strip()}\n        for line in header.splitlines():\n            if \":\" in line:\n                key, _, value = line.partition(\":\")\n                result[key.strip()] = value.strip()\n        return result\n\n\nclass DreamConsolidator:\n    \"\"\"\n    Auto-consolidation of memories between sessions (\"Dream\").\n\n    This is an optional later-stage feature. Its job is to prevent the memory\n    store from growing into a noisy pile by merging, deduplicating, and\n    pruning entries over time.\n    \"\"\"\n\n    COOLDOWN_SECONDS = 86400       # 24 hours between consolidations\n    SCAN_THROTTLE_SECONDS = 600    # 10 minutes between scan attempts\n    MIN_SESSION_COUNT = 5          # need enough data to consolidate\n    LOCK_STALE_SECONDS = 3600      # PID lock considered stale after 1 hour\n\n    PHASES = [\n        \"Orient: scan MEMORY.md index for structure and categories\",\n        \"Gather: read individual memory files for full content\",\n        \"Consolidate: merge related memories, remove stale entries\",\n        \"Prune: enforce 200-line limit on MEMORY.md index\",\n    ]\n\n    def __init__(self, memory_dir: Path = None):\n        self.memory_dir = memory_dir or MEMORY_DIR\n        self.lock_file = self.memory_dir / \".dream_lock\"\n        self.enabled = True\n        self.mode = \"default\"\n        self.last_consolidation_time = 0.0\n        self.last_scan_time = 0.0\n        self.session_count = 0\n\n    def should_consolidate(self) -> tuple[bool, str]:\n        \"\"\"\n        Check 7 gates in sequence. All must pass.\n        Returns (can_run, reason) where reason explains the first failed gate.\n        \"\"\"\n        import time\n\n        now = time.time()\n\n        # Gate 1: enabled flag\n        if not self.enabled:\n            return False, \"Gate 1: consolidation is disabled\"\n\n        # Gate 2: memory directory exists and has memory files\n        if not self.memory_dir.exists():\n            return False, \"Gate 2: memory directory does not exist\"\n        memory_files = list(self.memory_dir.glob(\"*.md\"))\n        # Exclude MEMORY.md itself from the count\n        memory_files = [f for f in memory_files if f.name != \"MEMORY.md\"]\n        if not memory_files:\n            return False, \"Gate 2: no memory files found\"\n\n        # Gate 3: not in plan mode (only consolidate in active modes)\n        if self.mode == \"plan\":\n            return False, \"Gate 3: plan mode does not allow consolidation\"\n\n        # Gate 4: 24-hour cooldown since last consolidation\n        time_since_last = now - self.last_consolidation_time\n        if time_since_last < self.COOLDOWN_SECONDS:\n            remaining = int(self.COOLDOWN_SECONDS - time_since_last)\n            return False, f\"Gate 4: cooldown active, {remaining}s remaining\"\n\n        # Gate 5: 10-minute throttle since last scan attempt\n        time_since_scan = now - self.last_scan_time\n        if time_since_scan < self.SCAN_THROTTLE_SECONDS:\n            remaining = int(self.SCAN_THROTTLE_SECONDS - time_since_scan)\n            return False, f\"Gate 5: scan throttle active, {remaining}s remaining\"\n\n        # Gate 6: need at least 5 sessions worth of data\n        if self.session_count < self.MIN_SESSION_COUNT:\n            return False, f\"Gate 6: only {self.session_count} sessions, need {self.MIN_SESSION_COUNT}\"\n\n        # Gate 7: no active lock file (check PID staleness)\n        if not self._acquire_lock():\n            return False, \"Gate 7: lock held by another process\"\n\n        return True, \"All 7 gates passed\"\n\n    def consolidate(self) -> list[str]:\n        \"\"\"\n        Run the 4-phase consolidation process.\n\n        The teaching version returns phase descriptions to make the flow\n        visible without requiring an extra LLM pass here.\n        \"\"\"\n        import time\n\n        can_run, reason = self.should_consolidate()\n        if not can_run:\n            print(f\"[Dream] Cannot consolidate: {reason}\")\n            return []\n\n        print(\"[Dream] Starting consolidation...\")\n        self.last_scan_time = time.time()\n\n        completed_phases = []\n        for i, phase in enumerate(self.PHASES, 1):\n            print(f\"[Dream] Phase {i}/4: {phase}\")\n            completed_phases.append(phase)\n\n        self.last_consolidation_time = time.time()\n        self._release_lock()\n        print(f\"[Dream] Consolidation complete: {len(completed_phases)} phases executed\")\n        return completed_phases\n\n    def _acquire_lock(self) -> bool:\n        \"\"\"\n        Acquire a PID-based lock file. Returns False if locked by another\n        live process. Stale locks (older than LOCK_STALE_SECONDS) are removed.\n        \"\"\"\n        import time\n\n        if self.lock_file.exists():\n            try:\n                lock_data = self.lock_file.read_text().strip()\n                pid_str, timestamp_str = lock_data.split(\":\", 1)\n                pid = int(pid_str)\n                lock_time = float(timestamp_str)\n\n                # Check if lock is stale\n                if (time.time() - lock_time) > self.LOCK_STALE_SECONDS:\n                    print(f\"[Dream] Removing stale lock from PID {pid}\")\n                    self.lock_file.unlink()\n                else:\n                    # Check if owning process is still alive\n                    try:\n                        os.kill(pid, 0)\n                        return False  # process alive, lock is valid\n                    except OSError:\n                        print(f\"[Dream] Removing lock from dead PID {pid}\")\n                        self.lock_file.unlink()\n            except (ValueError, OSError):\n                # Corrupted lock file, remove it\n                self.lock_file.unlink(missing_ok=True)\n\n        # Write new lock\n        try:\n            self.memory_dir.mkdir(parents=True, exist_ok=True)\n            self.lock_file.write_text(f\"{os.getpid()}:{time.time()}\")\n            return True\n        except OSError:\n            return False\n\n    def _release_lock(self):\n        \"\"\"Release the lock file if we own it.\"\"\"\n        try:\n            if self.lock_file.exists():\n                lock_data = self.lock_file.read_text().strip()\n                pid_str = lock_data.split(\":\")[0]\n                if int(pid_str) == os.getpid():\n                    self.lock_file.unlink()\n        except (ValueError, OSError):\n            pass\n\n\n# -- Tool implementations --\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\n\ndef run_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(command, shell=True, cwd=WORKDIR,\n                           capture_output=True, text=True, timeout=120)\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\n\ndef run_read(path: str, limit: int = None) -> str:\n    try:\n        lines = safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef run_write(path: str, content: str) -> str:\n    try:\n        fp = safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = safe_path(path)\n        content = fp.read_text()\n        if old_text not in content:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(content.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\n# Global memory manager\nmemory_mgr = MemoryManager()\n\n\ndef run_save_memory(name: str, description: str, mem_type: str, content: str) -> str:\n    return memory_mgr.save_memory(name, description, mem_type, content)\n\n\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\"], kw[\"new_text\"]),\n    \"save_memory\":  lambda **kw: run_save_memory(kw[\"name\"], kw[\"description\"], kw[\"type\"], kw[\"content\"]),\n}\n\nTOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n    {\"name\": \"save_memory\", \"description\": \"Save a persistent memory that survives across sessions.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\n         \"name\": {\"type\": \"string\", \"description\": \"Short identifier (e.g. prefer_tabs, db_schema)\"},\n         \"description\": {\"type\": \"string\", \"description\": \"One-line summary of what this memory captures\"},\n         \"type\": {\"type\": \"string\", \"enum\": [\"user\", \"feedback\", \"project\", \"reference\"],\n                  \"description\": \"user=preferences, feedback=corrections, project=non-obvious project conventions or decision reasons, reference=external resource pointers\"},\n         \"content\": {\"type\": \"string\", \"description\": \"Full memory content (multi-line OK)\"},\n     }, \"required\": [\"name\", \"description\", \"type\", \"content\"]}},\n]\n\nMEMORY_GUIDANCE = \"\"\"\nWhen to save memories:\n- User states a preference (\"I like tabs\", \"always use pytest\") -> type: user\n- User corrects you (\"don't do X\", \"that was wrong because...\") -> type: feedback\n- You learn a project fact that is not easy to infer from current code alone\n  (for example: a rule exists because of compliance, or a legacy module must\n  stay untouched for business reasons) -> type: project\n- You learn where an external resource lives (ticket board, dashboard, docs URL)\n  -> type: reference\n\nWhen NOT to save:\n- Anything easily derivable from code (function signatures, file structure, directory layout)\n- Temporary task state (current branch, open PR numbers, current TODOs)\n- Secrets or credentials (API keys, passwords)\n\"\"\"\n\n\ndef build_system_prompt() -> str:\n    \"\"\"Assemble system prompt with memory content included.\"\"\"\n    parts = [f\"You are a coding agent at {WORKDIR}. Use tools to solve tasks.\"]\n\n    # Inject memory content if available\n    memory_section = memory_mgr.load_memory_prompt()\n    if memory_section:\n        parts.append(memory_section)\n\n    parts.append(MEMORY_GUIDANCE)\n    return \"\\n\\n\".join(parts)\n\n\ndef agent_loop(messages: list):\n    \"\"\"\n    Agent loop with memory-aware system prompt.\n\n    The system prompt is rebuilt each call so newly saved memories\n    are visible in the next LLM turn within the same session.\n    \"\"\"\n    while True:\n        system = build_system_prompt()\n        response = client.messages.create(\n            model=MODEL, system=system, messages=messages,\n            tools=TOOLS, max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n\n        if response.stop_reason != \"tool_use\":\n            return\n\n        results = []\n        for block in response.content:\n            if block.type != \"tool_use\":\n                continue\n            handler = TOOL_HANDLERS.get(block.name)\n            try:\n                output = handler(**(block.input or {})) if handler else f\"Unknown: {block.name}\"\n            except Exception as e:\n                output = f\"Error: {e}\"\n            print(f\"> {block.name}: {str(output)[:200]}\")\n            results.append({\n                \"type\": \"tool_result\",\n                \"tool_use_id\": block.id,\n                \"content\": str(output),\n            })\n\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    # Load existing memories at session start\n    memory_mgr.load_all()\n    mem_count = len(memory_mgr.memories)\n    if mem_count:\n        print(f\"[{mem_count} memories loaded into context]\")\n    else:\n        print(\"[No existing memories. The agent can create them with save_memory.]\")\n\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms09 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n\n        # /memories command to list current memories\n        if query.strip() == \"/memories\":\n            if memory_mgr.memories:\n                for name, mem in memory_mgr.memories.items():\n                    print(f\"  [{mem['type']}] {name}: {mem['description']}\")\n            else:\n                print(\"  (no memories)\")\n            continue\n\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
     },
     {
-      "id": "s05",
-      "filename": "s05_skill_loading.py",
-      "title": "Skills",
-      "subtitle": "Load on Demand",
-      "loc": 187,
+      "id": "s10",
+      "filename": "s10_system_prompt.py",
+      "title": "System Prompt",
+      "subtitle": "Build Inputs as a Pipeline",
+      "loc": 305,
       "tools": [
         "bash",
         "read_file",
         "write_file",
-        "edit_file",
-        "load_skill"
-      ],
-      "newTools": [
-        "load_skill"
+        "edit_file"
       ],
-      "coreAddition": "SkillLoader + two-layer injection",
-      "keyInsight": "Inject knowledge via tool_result when needed, not upfront in the system prompt",
+      "newTools": [],
+      "coreAddition": "Prompt sections + dynamic assembly",
+      "keyInsight": "The model sees a constructed input pipeline, not one giant static string.",
       "classes": [
         {
-          "name": "SkillLoader",
-          "startLine": 57,
-          "endLine": 105
+          "name": "SystemPromptBuilder",
+          "startLine": 50,
+          "endLine": 224
         }
       ],
       "functions": [
+        {
+          "name": "build_system_reminder",
+          "signature": "def build_system_reminder(extra: str = None)",
+          "startLine": 225
+        },
         {
           "name": "safe_path",
           "signature": "def safe_path(p: str)",
-          "startLine": 117
+          "startLine": 242
         },
         {
           "name": "run_bash",
           "signature": "def run_bash(command: str)",
-          "startLine": 123
+          "startLine": 249
         },
         {
           "name": "run_read",
           "signature": "def run_read(path: str, limit: int = None)",
-          "startLine": 135
+          "startLine": 262
         },
         {
           "name": "run_write",
           "signature": "def run_write(path: str, content: str)",
-          "startLine": 144
+          "startLine": 272
         },
         {
           "name": "run_edit",
           "signature": "def run_edit(path: str, old_text: str, new_text: str)",
-          "startLine": 153
+          "startLine": 282
         },
         {
           "name": "agent_loop",
           "signature": "def agent_loop(messages: list)",
-          "startLine": 187
+          "startLine": 316
         }
       ],
-      "layer": "planning",
-      "source": "#!/usr/bin/env python3\n\"\"\"\ns05_skill_loading.py - Skills\n\nTwo-layer skill injection that avoids bloating the system prompt:\n\n    Layer 1 (cheap): skill names in system prompt (~100 tokens/skill)\n    Layer 2 (on demand): full skill body in tool_result\n\n    skills/\n      pdf/\n        SKILL.md          <-- frontmatter (name, description) + body\n      code-review/\n        SKILL.md\n\n    System prompt:\n    +--------------------------------------+\n    | You are a coding agent.              |\n    | Skills available:                    |\n    |   - pdf: Process PDF files...        |  <-- Layer 1: metadata only\n    |   - code-review: Review code...      |\n    +--------------------------------------+\n\n    When model calls load_skill(\"pdf\"):\n    +--------------------------------------+\n    | tool_result:                         |\n    | <skill>                              |\n    |   Full PDF processing instructions   |  <-- Layer 2: full body\n    |   Step 1: ...                        |\n    |   Step 2: ...                        |\n    | </skill>                             |\n    +--------------------------------------+\n\nKey insight: \"Don't put everything in the system prompt. Load on demand.\"\n\"\"\"\n\nimport os\nimport re\nimport subprocess\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\nSKILLS_DIR = WORKDIR / \"skills\"\n\n\n# -- SkillLoader: scan skills/<name>/SKILL.md with YAML frontmatter --\nclass SkillLoader:\n    def __init__(self, skills_dir: Path):\n        self.skills_dir = skills_dir\n        self.skills = {}\n        self._load_all()\n\n    def _load_all(self):\n        if not self.skills_dir.exists():\n            return\n        for f in sorted(self.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, \"path\": str(f)}\n\n    def _parse_frontmatter(self, text: str) -> tuple:\n        \"\"\"Parse YAML frontmatter between --- delimiters.\"\"\"\n        match = re.match(r\"^---\\n(.*?)\\n---\\n(.*)\", text, re.DOTALL)\n        if not match:\n            return {}, text\n        meta = {}\n        for line in match.group(1).strip().splitlines():\n            if \":\" in line:\n                key, val = line.split(\":\", 1)\n                meta[key.strip()] = val.strip()\n        return meta, match.group(2).strip()\n\n    def get_descriptions(self) -> str:\n        \"\"\"Layer 1: short descriptions for the system prompt.\"\"\"\n        if not self.skills:\n            return \"(no skills available)\"\n        lines = []\n        for name, skill in self.skills.items():\n            desc = skill[\"meta\"].get(\"description\", \"No description\")\n            tags = skill[\"meta\"].get(\"tags\", \"\")\n            line = f\"  - {name}: {desc}\"\n            if tags:\n                line += f\" [{tags}]\"\n            lines.append(line)\n        return \"\\n\".join(lines)\n\n    def get_content(self, name: str) -> str:\n        \"\"\"Layer 2: full skill body returned in tool_result.\"\"\"\n        skill = self.skills.get(name)\n        if not skill:\n            return f\"Error: Unknown skill '{name}'. Available: {', '.join(self.skills.keys())}\"\n        return f\"<skill name=\\\"{name}\\\">\\n{skill['body']}\\n</skill>\"\n\n\nSKILL_LOADER = SkillLoader(SKILLS_DIR)\n\n# Layer 1: skill metadata injected into system prompt\nSYSTEM = f\"\"\"You are a coding agent at {WORKDIR}.\nUse load_skill to access specialized knowledge before tackling unfamiliar topics.\n\nSkills available:\n{SKILL_LOADER.get_descriptions()}\"\"\"\n\n\n# -- Tool implementations --\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_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(command, shell=True, cwd=WORKDIR,\n                           capture_output=True, text=True, timeout=120)\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\ndef run_read(path: str, limit: int = None) -> str:\n    try:\n        lines = safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\ndef run_write(path: str, content: str) -> str:\n    try:\n        fp = safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\ndef run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = safe_path(path)\n        content = fp.read_text()\n        if old_text not in content:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(content.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\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\"], kw[\"new_text\"]),\n    \"load_skill\": lambda **kw: SKILL_LOADER.get_content(kw[\"name\"]),\n}\n\nTOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n    {\"name\": \"load_skill\", \"description\": \"Load specialized knowledge by name.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\", \"description\": \"Skill name to load\"}}, \"required\": [\"name\"]}},\n]\n\n\ndef agent_loop(messages: list):\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        if response.stop_reason != \"tool_use\":\n            return\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                handler = TOOL_HANDLERS.get(block.name)\n                try:\n                    output = handler(**block.input) if handler else f\"Unknown tool: {block.name}\"\n                except Exception as e:\n                    output = f\"Error: {e}\"\n                print(f\"> {block.name}: {str(output)[:200]}\")\n                results.append({\"type\": \"tool_result\", \"tool_use_id\": block.id, \"content\": str(output)})\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms05 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
+      "layer": "hardening",
+      "source": "#!/usr/bin/env python3\n# Harness: assembly -- the system prompt is a pipeline, not a string.\n\"\"\"\ns10_system_prompt.py - System Prompt Construction\n\nThis chapter teaches one core idea:\nthe system prompt should be assembled from clear sections, not written as one\ngiant hardcoded blob.\n\nTeaching pipeline:\n  1. core instructions\n  2. tool listing\n  3. skill metadata\n  4. memory section\n  5. CLAUDE.md chain\n  6. dynamic context\n\nThe builder keeps stable information separate from information that changes\noften. A simple DYNAMIC_BOUNDARY marker makes that split visible.\n\nPer-turn reminders are even more dynamic. They are better injected as a\nseparate user-role system reminder than mixed blindly into the stable prompt.\n\nKey insight: \"Prompt construction is a pipeline with boundaries, not one\nbig string.\"\n\"\"\"\n\nimport datetime\nimport json\nimport os\nimport re\nimport subprocess\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\n\nDYNAMIC_BOUNDARY = \"=== DYNAMIC_BOUNDARY ===\"\n\n\nclass SystemPromptBuilder:\n    \"\"\"\n    Assemble the system prompt from independent sections.\n\n    The teaching goal here is clarity:\n    each section has one source and one responsibility.\n\n    That makes the prompt easier to reason about, easier to test, and easier\n    to evolve as the agent grows new capabilities.\n    \"\"\"\n\n    def __init__(self, workdir: Path = None, tools: list = None):\n        self.workdir = workdir or WORKDIR\n        self.tools = tools or []\n        self.skills_dir = self.workdir / \"skills\"\n        self.memory_dir = self.workdir / \".memory\"\n\n    # -- Section 1: Core instructions --\n    def _build_core(self) -> str:\n        return (\n            f\"You are a coding agent operating in {self.workdir}.\\n\"\n            \"Use the provided tools to explore, read, write, and edit files.\\n\"\n            \"Always verify before assuming. Prefer reading files over guessing.\"\n        )\n\n    # -- Section 2: Tool listings --\n    def _build_tool_listing(self) -> str:\n        if not self.tools:\n            return \"\"\n        lines = [\"# Available tools\"]\n        for tool in self.tools:\n            props = tool.get(\"input_schema\", {}).get(\"properties\", {})\n            params = \", \".join(props.keys())\n            lines.append(f\"- {tool['name']}({params}): {tool['description']}\")\n        return \"\\n\".join(lines)\n\n    # -- Section 3: Skill metadata (layer 1 from s05 concept) --\n    def _build_skill_listing(self) -> str:\n        if not self.skills_dir.exists():\n            return \"\"\n        skills = []\n        for skill_dir in sorted(self.skills_dir.iterdir()):\n            skill_md = skill_dir / \"SKILL.md\"\n            if not skill_md.exists():\n                continue\n            text = skill_md.read_text()\n            # Parse frontmatter for name + description\n            match = re.match(r\"^---\\s*\\n(.*?)\\n---\", text, re.DOTALL)\n            if not match:\n                continue\n            meta = {}\n            for line in match.group(1).splitlines():\n                if \":\" in line:\n                    k, _, v = line.partition(\":\")\n                    meta[k.strip()] = v.strip()\n            name = meta.get(\"name\", skill_dir.name)\n            desc = meta.get(\"description\", \"\")\n            skills.append(f\"- {name}: {desc}\")\n        if not skills:\n            return \"\"\n        return \"# Available skills\\n\" + \"\\n\".join(skills)\n\n    # -- Section 4: Memory content --\n    def _build_memory_section(self) -> str:\n        if not self.memory_dir.exists():\n            return \"\"\n        memories = []\n        for md_file in sorted(self.memory_dir.glob(\"*.md\")):\n            if md_file.name == \"MEMORY.md\":\n                continue\n            text = md_file.read_text()\n            match = re.match(r\"^---\\s*\\n(.*?)\\n---\\s*\\n(.*)\", text, re.DOTALL)\n            if not match:\n                continue\n            header, body = match.group(1), match.group(2).strip()\n            meta = {}\n            for line in header.splitlines():\n                if \":\" in line:\n                    k, _, v = line.partition(\":\")\n                    meta[k.strip()] = v.strip()\n            name = meta.get(\"name\", md_file.stem)\n            mem_type = meta.get(\"type\", \"project\")\n            desc = meta.get(\"description\", \"\")\n            memories.append(f\"[{mem_type}] {name}: {desc}\\n{body}\")\n        if not memories:\n            return \"\"\n        return \"# Memories (persistent)\\n\\n\" + \"\\n\\n\".join(memories)\n\n    # -- Section 5: CLAUDE.md chain --\n    def _build_claude_md(self) -> str:\n        \"\"\"\n        Load CLAUDE.md files in priority order (all are included):\n        1. ~/.claude/CLAUDE.md (user-global instructions)\n        2. <project-root>/CLAUDE.md (project instructions)\n        3. <current-subdir>/CLAUDE.md (directory-specific instructions)\n        \"\"\"\n        sources = []\n\n        # User-global\n        user_claude = Path.home() / \".claude\" / \"CLAUDE.md\"\n        if user_claude.exists():\n            sources.append((\"user global (~/.claude/CLAUDE.md)\", user_claude.read_text()))\n\n        # Project root\n        project_claude = self.workdir / \"CLAUDE.md\"\n        if project_claude.exists():\n            sources.append((\"project root (CLAUDE.md)\", project_claude.read_text()))\n\n        # Subdirectory -- in real CC, this walks from cwd up to project root\n        # Teaching: check cwd if different from workdir\n        cwd = Path.cwd()\n        if cwd != self.workdir:\n            subdir_claude = cwd / \"CLAUDE.md\"\n            if subdir_claude.exists():\n                sources.append((f\"subdir ({cwd.name}/CLAUDE.md)\", subdir_claude.read_text()))\n\n        if not sources:\n            return \"\"\n        parts = [\"# CLAUDE.md instructions\"]\n        for label, content in sources:\n            parts.append(f\"## From {label}\")\n            parts.append(content.strip())\n        return \"\\n\\n\".join(parts)\n\n    # -- Section 6: Dynamic context --\n    def _build_dynamic_context(self) -> str:\n        lines = [\n            f\"Current date: {datetime.date.today().isoformat()}\",\n            f\"Working directory: {self.workdir}\",\n            f\"Model: {MODEL}\",\n            f\"Platform: {os.uname().sysname}\",\n        ]\n        return \"# Dynamic context\\n\" + \"\\n\".join(lines)\n\n    # -- Assemble all sections --\n    def build(self) -> str:\n        \"\"\"\n        Assemble the full system prompt from all sections.\n\n        Static sections (1-5) are separated from dynamic (6) by\n        the DYNAMIC_BOUNDARY marker. In real CC, the static prefix\n        is cached across turns to save prompt tokens.\n        \"\"\"\n        sections = []\n\n        core = self._build_core()\n        if core:\n            sections.append(core)\n\n        tools = self._build_tool_listing()\n        if tools:\n            sections.append(tools)\n\n        skills = self._build_skill_listing()\n        if skills:\n            sections.append(skills)\n\n        memory = self._build_memory_section()\n        if memory:\n            sections.append(memory)\n\n        claude_md = self._build_claude_md()\n        if claude_md:\n            sections.append(claude_md)\n\n        # Static/dynamic boundary\n        sections.append(DYNAMIC_BOUNDARY)\n\n        dynamic = self._build_dynamic_context()\n        if dynamic:\n            sections.append(dynamic)\n\n        return \"\\n\\n\".join(sections)\n\n\ndef build_system_reminder(extra: str = None) -> dict:\n    \"\"\"\n    Build a system-reminder user message for per-turn dynamic content.\n\n    The teaching version keeps reminders outside the stable system prompt so\n    short-lived context does not get mixed into the long-lived instructions.\n    \"\"\"\n    parts = []\n    if extra:\n        parts.append(extra)\n    if not parts:\n        return None\n    content = \"<system-reminder>\\n\" + \"\\n\".join(parts) + \"\\n</system-reminder>\"\n    return {\"role\": \"user\", \"content\": content}\n\n\n# -- Tool implementations --\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\n\ndef run_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(command, shell=True, cwd=WORKDIR,\n                           capture_output=True, text=True, timeout=120)\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\n\ndef run_read(path: str, limit: int = None) -> str:\n    try:\n        lines = safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef run_write(path: str, content: str) -> str:\n    try:\n        fp = safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = safe_path(path)\n        content = fp.read_text()\n        if old_text not in content:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(content.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\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\"], kw[\"new_text\"]),\n}\n\nTOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n]\n\n# Global prompt builder\nprompt_builder = SystemPromptBuilder(workdir=WORKDIR, tools=TOOLS)\n\n\ndef agent_loop(messages: list):\n    \"\"\"\n    Agent loop with assembled system prompt.\n\n    The system prompt is rebuilt each iteration. In real CC, the static\n    prefix is cached and only the dynamic suffix changes per turn.\n    \"\"\"\n    while True:\n        system = prompt_builder.build()\n        response = client.messages.create(\n            model=MODEL, system=system, messages=messages,\n            tools=TOOLS, max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n\n        if response.stop_reason != \"tool_use\":\n            return\n\n        results = []\n        for block in response.content:\n            if block.type != \"tool_use\":\n                continue\n            handler = TOOL_HANDLERS.get(block.name)\n            try:\n                output = handler(**(block.input or {})) if handler else f\"Unknown: {block.name}\"\n            except Exception as e:\n                output = f\"Error: {e}\"\n            print(f\"> {block.name}: {str(output)[:200]}\")\n            results.append({\n                \"type\": \"tool_result\",\n                \"tool_use_id\": block.id,\n                \"content\": str(output),\n            })\n\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    # Show the assembled prompt at startup for educational purposes\n    full_prompt = prompt_builder.build()\n    section_count = full_prompt.count(\"\\n# \")\n    print(f\"[System prompt assembled: {len(full_prompt)} chars, ~{section_count} sections]\")\n\n    # /prompt command shows the full assembled prompt\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms10 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n\n        if query.strip() == \"/prompt\":\n            print(\"--- System Prompt ---\")\n            print(prompt_builder.build())\n            print(\"--- End ---\")\n            continue\n\n        if query.strip() == \"/sections\":\n            prompt = prompt_builder.build()\n            for line in prompt.splitlines():\n                if line.startswith(\"# \") or line == DYNAMIC_BOUNDARY:\n                    print(f\"  {line}\")\n            continue\n\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
     },
     {
-      "id": "s06",
-      "filename": "s06_context_compact.py",
-      "title": "Compact",
-      "subtitle": "Three-Layer Compression",
-      "loc": 205,
+      "id": "s11",
+      "filename": "s11_error_recovery.py",
+      "title": "Error Recovery",
+      "subtitle": "Recover, Then Continue",
+      "loc": 249,
       "tools": [
         "bash",
         "read_file",
         "write_file",
-        "edit_file",
-        "compact"
-      ],
-      "newTools": [
-        "compact"
+        "edit_file"
       ],
-      "coreAddition": "micro-compact + auto-compact + archival",
-      "keyInsight": "Context will fill up; three-layer compression strategy enables infinite sessions",
+      "newTools": [],
+      "coreAddition": "Continuation reasons + retry branches",
+      "keyInsight": "Most failures aren't true task failure -- they're signals to try a different path.",
       "classes": [],
       "functions": [
         {
           "name": "estimate_tokens",
           "signature": "def estimate_tokens(messages: list)",
-          "startLine": 61
-        },
-        {
-          "name": "micro_compact",
-          "signature": "def micro_compact(messages: list)",
-          "startLine": 67
+          "startLine": 74
         },
         {
           "name": "auto_compact",
           "signature": "def auto_compact(messages: list)",
-          "startLine": 97
+          "startLine": 79
+        },
+        {
+          "name": "backoff_delay",
+          "signature": "def backoff_delay(attempt: int)",
+          "startLine": 111
         },
         {
           "name": "safe_path",
           "signature": "def safe_path(p: str)",
-          "startLine": 124
+          "startLine": 119
         },
         {
           "name": "run_bash",
           "signature": "def run_bash(command: str)",
-          "startLine": 130
+          "startLine": 126
         },
         {
           "name": "run_read",
           "signature": "def run_read(path: str, limit: int = None)",
-          "startLine": 142
+          "startLine": 139
         },
         {
           "name": "run_write",
           "signature": "def run_write(path: str, content: str)",
-          "startLine": 151
+          "startLine": 149
         },
         {
           "name": "run_edit",
           "signature": "def run_edit(path: str, old_text: str, new_text: str)",
-          "startLine": 160
+          "startLine": 159
         },
         {
           "name": "agent_loop",
           "signature": "def agent_loop(messages: list)",
-          "startLine": 194
+          "startLine": 192
         }
       ],
-      "layer": "memory",
-      "source": "#!/usr/bin/env python3\n\"\"\"\ns06_context_compact.py - Compact\n\nThree-layer compression pipeline so the agent can work forever:\n\n    Every turn:\n    +------------------+\n    | Tool call result |\n    +------------------+\n            |\n            v\n    [Layer 1: micro_compact]        (silent, every turn)\n      Replace tool_result content older than last 3\n      with \"[Previous: used {tool_name}]\"\n            |\n            v\n    [Check: tokens > 50000?]\n       |               |\n       no              yes\n       |               |\n       v               v\n    continue    [Layer 2: auto_compact]\n                  Save full transcript to .transcripts/\n                  Ask LLM to summarize conversation.\n                  Replace all messages with [summary].\n                        |\n                        v\n                [Layer 3: compact tool]\n                  Model calls compact -> immediate summarization.\n                  Same as auto, triggered manually.\n\nKey insight: \"The agent can forget strategically and keep working forever.\"\n\"\"\"\n\nimport json\nimport os\nimport subprocess\nimport time\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\n\nSYSTEM = f\"You are a coding agent at {WORKDIR}. Use tools to solve tasks.\"\n\nTHRESHOLD = 50000\nTRANSCRIPT_DIR = WORKDIR / \".transcripts\"\nKEEP_RECENT = 3\n\n\ndef estimate_tokens(messages: list) -> int:\n    \"\"\"Rough token count: ~4 chars per token.\"\"\"\n    return len(str(messages)) // 4\n\n\n# -- Layer 1: micro_compact - replace old tool results with placeholders --\ndef micro_compact(messages: list) -> list:\n    # Collect (msg_index, part_index, tool_result_dict) for all tool_result entries\n    tool_results = []\n    for msg_idx, msg in enumerate(messages):\n        if msg[\"role\"] == \"user\" and isinstance(msg.get(\"content\"), list):\n            for part_idx, part in enumerate(msg[\"content\"]):\n                if isinstance(part, dict) and part.get(\"type\") == \"tool_result\":\n                    tool_results.append((msg_idx, part_idx, part))\n    if len(tool_results) <= KEEP_RECENT:\n        return messages\n    # Find tool_name for each result by matching tool_use_id in prior assistant messages\n    tool_name_map = {}\n    for msg in messages:\n        if msg[\"role\"] == \"assistant\":\n            content = msg.get(\"content\", [])\n            if isinstance(content, list):\n                for block in content:\n                    if hasattr(block, \"type\") and block.type == \"tool_use\":\n                        tool_name_map[block.id] = block.name\n    # Clear old results (keep last KEEP_RECENT)\n    to_clear = tool_results[:-KEEP_RECENT]\n    for _, _, result in to_clear:\n        if isinstance(result.get(\"content\"), str) and len(result[\"content\"]) > 100:\n            tool_id = result.get(\"tool_use_id\", \"\")\n            tool_name = tool_name_map.get(tool_id, \"unknown\")\n            result[\"content\"] = f\"[Previous: used {tool_name}]\"\n    return messages\n\n\n# -- Layer 2: auto_compact - save transcript, summarize, replace messages --\ndef auto_compact(messages: list) -> list:\n    # Save full transcript to disk\n    TRANSCRIPT_DIR.mkdir(exist_ok=True)\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    print(f\"[transcript saved: {transcript_path}]\")\n    # Ask LLM to summarize\n    conversation_text = json.dumps(messages, default=str)[:80000]\n    response = client.messages.create(\n        model=MODEL,\n        messages=[{\"role\": \"user\", \"content\":\n            \"Summarize this conversation for continuity. Include: \"\n            \"1) What was accomplished, 2) Current state, 3) Key decisions made. \"\n            \"Be concise but preserve critical details.\\n\\n\" + conversation_text}],\n        max_tokens=2000,\n    )\n    summary = response.content[0].text\n    # Replace all messages with compressed summary\n    return [\n        {\"role\": \"user\", \"content\": f\"[Conversation compressed. Transcript: {transcript_path}]\\n\\n{summary}\"},\n        {\"role\": \"assistant\", \"content\": \"Understood. I have the context from the summary. Continuing.\"},\n    ]\n\n\n# -- Tool implementations --\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_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(command, shell=True, cwd=WORKDIR,\n                           capture_output=True, text=True, timeout=120)\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\ndef run_read(path: str, limit: int = None) -> str:\n    try:\n        lines = safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\ndef run_write(path: str, content: str) -> str:\n    try:\n        fp = safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\ndef run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = safe_path(path)\n        content = fp.read_text()\n        if old_text not in content:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(content.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\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\"], kw[\"new_text\"]),\n    \"compact\":    lambda **kw: \"Manual compression requested.\",\n}\n\nTOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n    {\"name\": \"compact\", \"description\": \"Trigger manual conversation compression.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"focus\": {\"type\": \"string\", \"description\": \"What to preserve in the summary\"}}}},\n]\n\n\ndef agent_loop(messages: list):\n    while True:\n        # Layer 1: micro_compact before each LLM call\n        micro_compact(messages)\n        # Layer 2: auto_compact if token estimate exceeds threshold\n        if estimate_tokens(messages) > THRESHOLD:\n            print(\"[auto_compact triggered]\")\n            messages[:] = auto_compact(messages)\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        if response.stop_reason != \"tool_use\":\n            return\n        results = []\n        manual_compact = False\n        for block in response.content:\n            if block.type == \"tool_use\":\n                if block.name == \"compact\":\n                    manual_compact = True\n                    output = \"Compressing...\"\n                else:\n                    handler = TOOL_HANDLERS.get(block.name)\n                    try:\n                        output = handler(**block.input) if handler else f\"Unknown tool: {block.name}\"\n                    except Exception as e:\n                        output = f\"Error: {e}\"\n                print(f\"> {block.name}: {str(output)[:200]}\")\n                results.append({\"type\": \"tool_result\", \"tool_use_id\": block.id, \"content\": str(output)})\n        messages.append({\"role\": \"user\", \"content\": results})\n        # Layer 3: manual compact triggered by the compact tool\n        if manual_compact:\n            print(\"[manual compact]\")\n            messages[:] = auto_compact(messages)\n\n\nif __name__ == \"__main__\":\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms06 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
+      "layer": "hardening",
+      "source": "#!/usr/bin/env python3\n# Harness: resilience -- a robust agent recovers instead of crashing.\n\"\"\"\ns11_error_recovery.py - Error Recovery\n\nTeaching demo of three recovery paths:\n\n- continue when output is truncated\n- compact when context grows too large\n- back off when transport errors are temporary\n\n    LLM response\n         |\n         v\n    [Check stop_reason]\n         |\n         +-- \"max_tokens\" ----> [Strategy 1: max_output_tokens recovery]\n         |                       Inject continuation message:\n         |                       \"Output limit hit. Continue directly.\"\n         |                       Retry up to MAX_RECOVERY_ATTEMPTS (3).\n         |                       Counter: max_output_recovery_count\n         |\n         +-- API error -------> [Check error type]\n         |                       |\n         |                       +-- prompt_too_long --> [Strategy 2: compact + retry]\n         |                       |   Trigger auto_compact (LLM summary).\n         |                       |   Replace history with summary.\n         |                       |   Retry the turn.\n         |                       |\n         |                       +-- connection/rate --> [Strategy 3: backoff retry]\n         |                           Exponential backoff: base * 2^attempt + jitter\n         |                           Up to 3 retries.\n         |\n         +-- \"end_turn\" -----> [Normal exit]\n\n    Recovery priority (first match wins):\n    1. max_tokens -> inject continuation, retry\n    2. prompt_too_long -> compact, retry\n    3. connection error -> backoff, retry\n    4. all retries exhausted -> fail gracefully\n\"\"\"\n\nimport json\nimport os\nimport random\nimport subprocess\nimport time\nfrom pathlib import Path\n\nfrom anthropic import Anthropic, APIError\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\n\n# Recovery constants\nMAX_RECOVERY_ATTEMPTS = 3\nBACKOFF_BASE_DELAY = 1.0  # seconds\nBACKOFF_MAX_DELAY = 30.0  # seconds\nTOKEN_THRESHOLD = 50000   # chars / 4 ~ tokens for compact trigger\n\nCONTINUATION_MESSAGE = (\n    \"Output limit hit. Continue directly from where you stopped -- \"\n    \"no recap, no repetition. Pick up mid-sentence if needed.\"\n)\n\n\ndef estimate_tokens(messages: list) -> int:\n    \"\"\"Rough token estimate: ~4 chars per token.\"\"\"\n    return len(json.dumps(messages, default=str)) // 4\n\n\ndef auto_compact(messages: list) -> list:\n    \"\"\"\n    Compress conversation history into a short continuation summary.\n    \"\"\"\n    conversation_text = json.dumps(messages, default=str)[:80000]\n    prompt = (\n        \"Summarize this conversation for continuity. Include:\\n\"\n        \"1) Task overview and success criteria\\n\"\n        \"2) Current state: completed work, files touched\\n\"\n        \"3) Key decisions and failed approaches\\n\"\n        \"4) Remaining next steps\\n\"\n        \"Be concise but preserve critical details.\\n\\n\"\n        + conversation_text\n    )\n    try:\n        response = client.messages.create(\n            model=MODEL,\n            messages=[{\"role\": \"user\", \"content\": prompt}],\n            max_tokens=4000,\n        )\n        summary = response.content[0].text\n    except Exception as e:\n        summary = f\"(compact failed: {e}). Previous context lost.\"\n\n    continuation = (\n        \"This session continues from a previous conversation that was compacted. \"\n        f\"Summary of prior context:\\n\\n{summary}\\n\\n\"\n        \"Continue from where we left off without re-asking the user.\"\n    )\n    return [{\"role\": \"user\", \"content\": continuation}]\n\n\ndef backoff_delay(attempt: int) -> float:\n    \"\"\"Exponential backoff with jitter: base * 2^attempt + random(0, 1).\"\"\"\n    delay = min(BACKOFF_BASE_DELAY * (2 ** attempt), BACKOFF_MAX_DELAY)\n    jitter = random.uniform(0, 1)\n    return delay + jitter\n\n\n# -- Tool implementations --\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\n\ndef run_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(command, shell=True, cwd=WORKDIR,\n                           capture_output=True, text=True, timeout=120)\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\n\ndef run_read(path: str, limit: int = None) -> str:\n    try:\n        lines = safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef run_write(path: str, content: str) -> str:\n    try:\n        fp = safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = safe_path(path)\n        content = fp.read_text()\n        if old_text not in content:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(content.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\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\"], kw[\"new_text\"]),\n}\n\nTOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n]\n\nSYSTEM = f\"You are a coding agent at {WORKDIR}. Use tools to solve tasks.\"\n\n\ndef agent_loop(messages: list):\n    \"\"\"\n    Error-recovering agent loop with three paths:\n\n    1. continue after max_tokens\n    2. compact after prompt-too-long\n    3. back off after transient transport failure\n    \"\"\"\n    max_output_recovery_count = 0\n\n    while True:\n        # -- Attempt the API call with connection retry --\n        response = None\n        for attempt in range(MAX_RECOVERY_ATTEMPTS + 1):\n            try:\n                response = client.messages.create(\n                    model=MODEL, system=SYSTEM, messages=messages,\n                    tools=TOOLS, max_tokens=8000,\n                )\n                break  # success\n\n            except APIError as e:\n                error_body = str(e).lower()\n\n                # Strategy 2: prompt_too_long -> compact and retry\n                if \"overlong_prompt\" in error_body or (\"prompt\" in error_body and \"long\" in error_body):\n                    print(f\"[Recovery] Prompt too long. Compacting... (attempt {attempt + 1})\")\n                    messages[:] = auto_compact(messages)\n                    continue\n\n                # Strategy 3: connection/rate errors -> backoff\n                if attempt < MAX_RECOVERY_ATTEMPTS:\n                    delay = backoff_delay(attempt)\n                    print(f\"[Recovery] API error: {e}. \"\n                          f\"Retrying in {delay:.1f}s (attempt {attempt + 1}/{MAX_RECOVERY_ATTEMPTS})\")\n                    time.sleep(delay)\n                    continue\n\n                # All retries exhausted\n                print(f\"[Error] API call failed after {MAX_RECOVERY_ATTEMPTS} retries: {e}\")\n                return\n\n            except (ConnectionError, TimeoutError, OSError) as e:\n                # Strategy 3: network-level errors -> backoff\n                if attempt < MAX_RECOVERY_ATTEMPTS:\n                    delay = backoff_delay(attempt)\n                    print(f\"[Recovery] Connection error: {e}. \"\n                          f\"Retrying in {delay:.1f}s (attempt {attempt + 1}/{MAX_RECOVERY_ATTEMPTS})\")\n                    time.sleep(delay)\n                    continue\n\n                print(f\"[Error] Connection failed after {MAX_RECOVERY_ATTEMPTS} retries: {e}\")\n                return\n\n        if response is None:\n            print(\"[Error] No response received.\")\n            return\n\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n\n        # -- Strategy 1: max_tokens recovery --\n        if response.stop_reason == \"max_tokens\":\n            max_output_recovery_count += 1\n            if max_output_recovery_count <= MAX_RECOVERY_ATTEMPTS:\n                print(f\"[Recovery] max_tokens hit \"\n                      f\"({max_output_recovery_count}/{MAX_RECOVERY_ATTEMPTS}). \"\n                      \"Injecting continuation...\")\n                messages.append({\"role\": \"user\", \"content\": CONTINUATION_MESSAGE})\n                continue  # retry the loop\n            else:\n                print(f\"[Error] max_tokens recovery exhausted \"\n                      f\"({MAX_RECOVERY_ATTEMPTS} attempts). Stopping.\")\n                return\n\n        # Reset max_tokens counter on successful non-max_tokens response\n        max_output_recovery_count = 0\n\n        # -- Normal end_turn: no tool use requested --\n        if response.stop_reason != \"tool_use\":\n            return\n\n        # -- Process tool calls --\n        results = []\n        for block in response.content:\n            if block.type != \"tool_use\":\n                continue\n            handler = TOOL_HANDLERS.get(block.name)\n            try:\n                output = handler(**(block.input or {})) if handler else f\"Unknown: {block.name}\"\n            except Exception as e:\n                output = f\"Error: {e}\"\n            print(f\"> {block.name}: {str(output)[:200]}\")\n            results.append({\n                \"type\": \"tool_result\",\n                \"tool_use_id\": block.id,\n                \"content\": str(output),\n            })\n\n        messages.append({\"role\": \"user\", \"content\": results})\n\n        # Check if we should auto-compact (proactive, not just reactive)\n        if estimate_tokens(messages) > TOKEN_THRESHOLD:\n            print(\"[Recovery] Token estimate exceeds threshold. Auto-compacting...\")\n            messages[:] = auto_compact(messages)\n\n\nif __name__ == \"__main__\":\n    print(\"[Error recovery enabled: max_tokens / prompt_too_long / connection backoff]\")\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms11 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
     },
     {
-      "id": "s07",
-      "filename": "s07_task_system.py",
-      "title": "Tasks",
-      "subtitle": "Task Graph + Dependencies",
-      "loc": 207,
+      "id": "s12",
+      "filename": "s12_task_system.py",
+      "title": "Task System",
+      "subtitle": "Durable Work Graph",
+      "loc": 227,
       "tools": [
         "bash",
         "read_file",
@@ -355,56 +785,56 @@
         "task_list",
         "task_get"
       ],
-      "coreAddition": "TaskManager with file-based state + dependency graph",
-      "keyInsight": "A file-based task graph with ordering, parallelism, and dependencies -- the coordination backbone for multi-agent work",
+      "coreAddition": "Task records + dependencies + unlock rules",
+      "keyInsight": "Todo lists help a session; durable task graphs coordinate work that outlives it.",
       "classes": [
         {
           "name": "TaskManager",
-          "startLine": 46,
-          "endLine": 125
+          "startLine": 65,
+          "endLine": 152
         }
       ],
       "functions": [
         {
           "name": "safe_path",
           "signature": "def safe_path(p: str)",
-          "startLine": 130
+          "startLine": 157
         },
         {
           "name": "run_bash",
           "signature": "def run_bash(command: str)",
-          "startLine": 136
+          "startLine": 163
         },
         {
           "name": "run_read",
           "signature": "def run_read(path: str, limit: int = None)",
-          "startLine": 148
+          "startLine": 175
         },
         {
           "name": "run_write",
           "signature": "def run_write(path: str, content: str)",
-          "startLine": 157
+          "startLine": 184
         },
         {
           "name": "run_edit",
           "signature": "def run_edit(path: str, old_text: str, new_text: str)",
-          "startLine": 166
+          "startLine": 193
         },
         {
           "name": "agent_loop",
           "signature": "def agent_loop(messages: list)",
-          "startLine": 209
+          "startLine": 236
         }
       ],
-      "layer": "planning",
-      "source": "#!/usr/bin/env python3\n\"\"\"\ns07_task_system.py - Tasks\n\nTasks persist as JSON files in .tasks/ so they survive context compression.\nEach task has a dependency graph (blockedBy/blocks).\n\n    .tasks/\n      task_1.json  {\"id\":1, \"subject\":\"...\", \"status\":\"completed\", ...}\n      task_2.json  {\"id\":2, \"blockedBy\":[1], \"status\":\"pending\", ...}\n      task_3.json  {\"id\":3, \"blockedBy\":[2], \"blocks\":[], ...}\n\n    Dependency resolution:\n    +----------+     +----------+     +----------+\n    | task 1   | --> | task 2   | --> | task 3   |\n    | complete |     | blocked  |     | blocked  |\n    +----------+     +----------+     +----------+\n         |                ^\n         +--- completing task 1 removes it from task 2's blockedBy\n\nKey insight: \"State that survives compression -- because it's outside the conversation.\"\n\"\"\"\n\nimport json\nimport os\nimport subprocess\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\nTASKS_DIR = WORKDIR / \".tasks\"\n\nSYSTEM = f\"You are a coding agent at {WORKDIR}. Use task tools to plan and track work.\"\n\n\n# -- TaskManager: CRUD with dependency graph, persisted as JSON files --\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 _max_id(self) -> int:\n        ids = [int(f.stem.split(\"_\")[1]) for f in self.dir.glob(\"task_*.json\")]\n        return max(ids) if ids else 0\n\n    def _load(self, task_id: int) -> dict:\n        path = self.dir / f\"task_{task_id}.json\"\n        if not path.exists():\n            raise ValueError(f\"Task {task_id} not found\")\n        return json.loads(path.read_text())\n\n    def _save(self, task: dict):\n        path = self.dir / f\"task_{task['id']}.json\"\n        path.write_text(json.dumps(task, indent=2))\n\n    def create(self, subject: str, description: str = \"\") -> str:\n        task = {\n            \"id\": self._next_id, \"subject\": subject, \"description\": description,\n            \"status\": \"pending\", \"blockedBy\": [], \"blocks\": [], \"owner\": \"\",\n        }\n        self._save(task)\n        self._next_id += 1\n        return json.dumps(task, indent=2)\n\n    def get(self, task_id: int) -> str:\n        return json.dumps(self._load(task_id), indent=2)\n\n    def update(self, task_id: int, status: str = None,\n               add_blocked_by: list = None, add_blocks: list = None) -> str:\n        task = self._load(task_id)\n        if status:\n            if status not in (\"pending\", \"in_progress\", \"completed\"):\n                raise ValueError(f\"Invalid status: {status}\")\n            task[\"status\"] = status\n            # When a task is completed, remove it from all other tasks' blockedBy\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 add_blocks:\n            task[\"blocks\"] = list(set(task[\"blocks\"] + add_blocks))\n            # Bidirectional: also update the blocked tasks' blockedBy lists\n            for blocked_id in add_blocks:\n                try:\n                    blocked = self._load(blocked_id)\n                    if task_id not in blocked[\"blockedBy\"]:\n                        blocked[\"blockedBy\"].append(task_id)\n                        self._save(blocked)\n                except ValueError:\n                    pass\n        self._save(task)\n        return json.dumps(task, indent=2)\n\n    def _clear_dependency(self, completed_id: int):\n        \"\"\"Remove completed_id from all other tasks' blockedBy lists.\"\"\"\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    def list_all(self) -> str:\n        tasks = []\n        for f in sorted(self.dir.glob(\"task_*.json\")):\n            tasks.append(json.loads(f.read_text()))\n        if not tasks:\n            return \"No tasks.\"\n        lines = []\n        for t in tasks:\n            marker = {\"pending\": \"[ ]\", \"in_progress\": \"[>]\", \"completed\": \"[x]\"}.get(t[\"status\"], \"[?]\")\n            blocked = f\" (blocked by: {t['blockedBy']})\" if t.get(\"blockedBy\") else \"\"\n            lines.append(f\"{marker} #{t['id']}: {t['subject']}{blocked}\")\n        return \"\\n\".join(lines)\n\n\nTASKS = TaskManager(TASKS_DIR)\n\n\n# -- Base tool implementations --\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_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(command, shell=True, cwd=WORKDIR,\n                           capture_output=True, text=True, timeout=120)\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\ndef run_read(path: str, limit: int = None) -> str:\n    try:\n        lines = safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\ndef run_write(path: str, content: str) -> str:\n    try:\n        fp = safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\ndef run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = safe_path(path)\n        c = fp.read_text()\n        if old_text not in c:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(c.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\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\"], kw[\"new_text\"]),\n    \"task_create\": lambda **kw: TASKS.create(kw[\"subject\"], kw.get(\"description\", \"\")),\n    \"task_update\": lambda **kw: TASKS.update(kw[\"task_id\"], kw.get(\"status\"), kw.get(\"addBlockedBy\"), kw.get(\"addBlocks\")),\n    \"task_list\":   lambda **kw: TASKS.list_all(),\n    \"task_get\":    lambda **kw: TASKS.get(kw[\"task_id\"]),\n}\n\nTOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n    {\"name\": \"task_create\", \"description\": \"Create a new task.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"subject\": {\"type\": \"string\"}, \"description\": {\"type\": \"string\"}}, \"required\": [\"subject\"]}},\n    {\"name\": \"task_update\", \"description\": \"Update a task's status or dependencies.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"task_id\": {\"type\": \"integer\"}, \"status\": {\"type\": \"string\", \"enum\": [\"pending\", \"in_progress\", \"completed\"]}, \"addBlockedBy\": {\"type\": \"array\", \"items\": {\"type\": \"integer\"}}, \"addBlocks\": {\"type\": \"array\", \"items\": {\"type\": \"integer\"}}}, \"required\": [\"task_id\"]}},\n    {\"name\": \"task_list\", \"description\": \"List all tasks with status summary.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n    {\"name\": \"task_get\", \"description\": \"Get full details of a task by ID.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"task_id\": {\"type\": \"integer\"}}, \"required\": [\"task_id\"]}},\n]\n\n\ndef agent_loop(messages: list):\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        if response.stop_reason != \"tool_use\":\n            return\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                handler = TOOL_HANDLERS.get(block.name)\n                try:\n                    output = handler(**block.input) if handler else f\"Unknown tool: {block.name}\"\n                except Exception as e:\n                    output = f\"Error: {e}\"\n                print(f\"> {block.name}: {str(output)[:200]}\")\n                results.append({\"type\": \"tool_result\", \"tool_use_id\": block.id, \"content\": str(output)})\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms07 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
+      "layer": "runtime",
+      "source": "#!/usr/bin/env python3\n# Harness: persistent tasks -- goals that outlive any single conversation.\n\"\"\"\ns12_task_system.py - Tasks\n\nTasks persist as JSON files in .tasks/ so they survive context compression.\nEach task carries a small dependency graph:\n\n- blockedBy: what must finish first\n- blocks: what this task unlocks later\n\n    .tasks/\n      task_1.json  {\"id\":1, \"subject\":\"...\", \"status\":\"completed\", ...}\n      task_2.json  {\"id\":2, \"blockedBy\":[1], \"status\":\"pending\", ...}\n      task_3.json  {\"id\":3, \"blockedBy\":[2], \"blocks\":[], ...}\n\n    Dependency resolution:\n    +----------+     +----------+     +----------+\n    | task 1   | --> | task 2   | --> | task 3   |\n    | complete |     | blocked  |     | blocked  |\n    +----------+     +----------+     +----------+\n         |                ^\n         +--- completing task 1 removes it from task 2's blockedBy\n\nKey idea: task state survives compression because it lives on disk, not only\ninside the conversation.\nThese are durable work-graph tasks, not transient runtime execution slots.\n\nRead this file in this order:\n1. TaskManager: what a TaskRecord looks like on disk.\n2. TOOL_HANDLERS / TOOLS: how task operations enter the same loop as normal tools.\n3. agent_loop: how persistent work state is exposed back to the model.\n\nMost common confusion:\n- a task record is a durable work item\n- it is not a thread, background slot, or worker process\n\nTeaching boundary:\nthis chapter teaches the durable work graph first.\nRuntime execution slots and schedulers arrive later.\n\"\"\"\n\nimport json\nimport os\nimport subprocess\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\nTASKS_DIR = WORKDIR / \".tasks\"\n\nSYSTEM = f\"You are a coding agent at {WORKDIR}. Use task tools to plan and track work.\"\n\n\n# -- TaskManager: CRUD for a persistent task graph --\nclass TaskManager:\n    \"\"\"Persistent TaskRecord store.\n\n    Think \"work graph on disk\", not \"currently running worker\".\n    \"\"\"\n\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 _max_id(self) -> int:\n        ids = [int(f.stem.split(\"_\")[1]) for f in self.dir.glob(\"task_*.json\")]\n        return max(ids) if ids else 0\n\n    def _load(self, task_id: int) -> dict:\n        path = self.dir / f\"task_{task_id}.json\"\n        if not path.exists():\n            raise ValueError(f\"Task {task_id} not found\")\n        return json.loads(path.read_text())\n\n    def _save(self, task: dict):\n        path = self.dir / f\"task_{task['id']}.json\"\n        path.write_text(json.dumps(task, indent=2))\n\n    def create(self, subject: str, description: str = \"\") -> str:\n        task = {\n            \"id\": self._next_id, \"subject\": subject, \"description\": description,\n            \"status\": \"pending\", \"blockedBy\": [], \"blocks\": [], \"owner\": \"\",\n        }\n        self._save(task)\n        self._next_id += 1\n        return json.dumps(task, indent=2)\n\n    def get(self, task_id: int) -> str:\n        return json.dumps(self._load(task_id), indent=2)\n\n    def update(self, task_id: int, status: str = None, owner: str = None,\n               add_blocked_by: list = None, add_blocks: list = None) -> str:\n        task = self._load(task_id)\n        if owner is not None:\n            task[\"owner\"] = owner\n        if status:\n            if status not in (\"pending\", \"in_progress\", \"completed\", \"deleted\"):\n                raise ValueError(f\"Invalid status: {status}\")\n            task[\"status\"] = status\n            # When a task is completed, remove it from all other tasks' blockedBy\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 add_blocks:\n            task[\"blocks\"] = list(set(task[\"blocks\"] + add_blocks))\n            # Bidirectional: also update the blocked tasks' blockedBy lists\n            for blocked_id in add_blocks:\n                try:\n                    blocked = self._load(blocked_id)\n                    if task_id not in blocked[\"blockedBy\"]:\n                        blocked[\"blockedBy\"].append(task_id)\n                        self._save(blocked)\n                except ValueError:\n                    pass\n        self._save(task)\n        return json.dumps(task, indent=2)\n\n    def _clear_dependency(self, completed_id: int):\n        \"\"\"Remove completed_id from all other tasks' blockedBy lists.\"\"\"\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    def list_all(self) -> str:\n        tasks = []\n        for f in sorted(self.dir.glob(\"task_*.json\")):\n            tasks.append(json.loads(f.read_text()))\n        if not tasks:\n            return \"No tasks.\"\n        lines = []\n        for t in tasks:\n            marker = {\"pending\": \"[ ]\", \"in_progress\": \"[>]\", \"completed\": \"[x]\", \"deleted\": \"[-]\"}.get(t[\"status\"], \"[?]\")\n            blocked = f\" (blocked by: {t['blockedBy']})\" if t.get(\"blockedBy\") else \"\"\n            owner = f\" owner={t['owner']}\" if t.get(\"owner\") else \"\"\n            lines.append(f\"{marker} #{t['id']}: {t['subject']}{owner}{blocked}\")\n        return \"\\n\".join(lines)\n\n\nTASKS = TaskManager(TASKS_DIR)\n\n\n# -- Base tool implementations --\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_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(command, shell=True, cwd=WORKDIR,\n                           capture_output=True, text=True, timeout=120)\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\ndef run_read(path: str, limit: int = None) -> str:\n    try:\n        lines = safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\ndef run_write(path: str, content: str) -> str:\n    try:\n        fp = safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\ndef run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = safe_path(path)\n        c = fp.read_text()\n        if old_text not in c:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(c.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\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\"], kw[\"new_text\"]),\n    \"task_create\": lambda **kw: TASKS.create(kw[\"subject\"], kw.get(\"description\", \"\")),\n    \"task_update\": lambda **kw: TASKS.update(kw[\"task_id\"], kw.get(\"status\"), kw.get(\"owner\"), kw.get(\"addBlockedBy\"), kw.get(\"addBlocks\")),\n    \"task_list\":   lambda **kw: TASKS.list_all(),\n    \"task_get\":    lambda **kw: TASKS.get(kw[\"task_id\"]),\n}\n\nTOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n    {\"name\": \"task_create\", \"description\": \"Create a new task.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"subject\": {\"type\": \"string\"}, \"description\": {\"type\": \"string\"}}, \"required\": [\"subject\"]}},\n    {\"name\": \"task_update\", \"description\": \"Update a task's status, owner, or dependencies.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"task_id\": {\"type\": \"integer\"}, \"status\": {\"type\": \"string\", \"enum\": [\"pending\", \"in_progress\", \"completed\", \"deleted\"]}, \"owner\": {\"type\": \"string\", \"description\": \"Set when a teammate claims the task\"}, \"addBlockedBy\": {\"type\": \"array\", \"items\": {\"type\": \"integer\"}}, \"addBlocks\": {\"type\": \"array\", \"items\": {\"type\": \"integer\"}}}, \"required\": [\"task_id\"]}},\n    {\"name\": \"task_list\", \"description\": \"List all tasks with status summary.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n    {\"name\": \"task_get\", \"description\": \"Get full details of a task by ID.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"task_id\": {\"type\": \"integer\"}}, \"required\": [\"task_id\"]}},\n]\n\n\ndef agent_loop(messages: list):\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        if response.stop_reason != \"tool_use\":\n            return\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                handler = TOOL_HANDLERS.get(block.name)\n                try:\n                    output = handler(**block.input) if handler else f\"Unknown tool: {block.name}\"\n                except Exception as e:\n                    output = f\"Error: {e}\"\n                print(f\"> {block.name}: {str(output)[:200]}\")\n                results.append({\"type\": \"tool_result\", \"tool_use_id\": block.id, \"content\": str(output)})\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms12 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
     },
     {
-      "id": "s08",
-      "filename": "s08_background_tasks.py",
+      "id": "s13",
+      "filename": "s13_background_tasks.py",
       "title": "Background Tasks",
-      "subtitle": "Background Threads + Notifications",
-      "loc": 198,
+      "subtitle": "Separate Goal from Running Work",
+      "loc": 287,
       "tools": [
         "bash",
         "read_file",
@@ -417,56 +847,140 @@
         "background_run",
         "check_background"
       ],
-      "coreAddition": "BackgroundManager + notification queue",
-      "keyInsight": "Run slow operations in the background; the agent keeps thinking ahead",
+      "coreAddition": "RuntimeTaskState + async execution slots",
+      "keyInsight": "Background execution is a runtime lane, not a second main loop.",
       "classes": [
+        {
+          "name": "NotificationQueue",
+          "startLine": 56,
+          "endLine": 87
+        },
         {
           "name": "BackgroundManager",
-          "startLine": 49,
-          "endLine": 109
+          "startLine": 88,
+          "endLine": 211
         }
       ],
       "functions": [
         {
           "name": "safe_path",
           "signature": "def safe_path(p: str)",
-          "startLine": 114
+          "startLine": 216
         },
         {
           "name": "run_bash",
           "signature": "def run_bash(command: str)",
-          "startLine": 120
+          "startLine": 222
         },
         {
           "name": "run_read",
           "signature": "def run_read(path: str, limit: int = None)",
-          "startLine": 132
+          "startLine": 234
         },
         {
           "name": "run_write",
           "signature": "def run_write(path: str, content: str)",
-          "startLine": 141
+          "startLine": 243
         },
         {
           "name": "run_edit",
           "signature": "def run_edit(path: str, old_text: str, new_text: str)",
-          "startLine": 150
+          "startLine": 252
         },
         {
           "name": "agent_loop",
           "signature": "def agent_loop(messages: list)",
-          "startLine": 187
+          "startLine": 289
         }
       ],
-      "layer": "concurrency",
-      "source": "#!/usr/bin/env python3\n\"\"\"\ns08_background_tasks.py - Background Tasks\n\nRun commands in background threads. A notification queue is drained\nbefore each LLM call to deliver results.\n\n    Main thread                Background thread\n    +-----------------+        +-----------------+\n    | agent loop      |        | task executes   |\n    | ...             |        | ...             |\n    | [LLM call] <---+------- | enqueue(result) |\n    |  ^drain queue   |        +-----------------+\n    +-----------------+\n\n    Timeline:\n    Agent ----[spawn A]----[spawn B]----[other work]----\n                 |              |\n                 v              v\n              [A runs]      [B runs]        (parallel)\n                 |              |\n                 +-- notification queue --> [results injected]\n\nKey insight: \"Fire and forget -- the agent doesn't block while the command runs.\"\n\"\"\"\n\nimport os\nimport subprocess\nimport threading\nimport uuid\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\n\nSYSTEM = f\"You are a coding agent at {WORKDIR}. Use background_run for long-running commands.\"\n\n\n# -- BackgroundManager: threaded execution + notification queue --\nclass BackgroundManager:\n    def __init__(self):\n        self.tasks = {}  # task_id -> {status, result, command}\n        self._notification_queue = []  # completed task results\n        self._lock = threading.Lock()\n\n    def run(self, command: str) -> str:\n        \"\"\"Start a background thread, return task_id immediately.\"\"\"\n        task_id = str(uuid.uuid4())[:8]\n        self.tasks[task_id] = {\"status\": \"running\", \"result\": None, \"command\": command}\n        thread = threading.Thread(\n            target=self._execute, args=(task_id, command), daemon=True\n        )\n        thread.start()\n        return f\"Background task {task_id} started: {command[:80]}\"\n\n    def _execute(self, task_id: str, command: str):\n        \"\"\"Thread target: run subprocess, capture output, push to queue.\"\"\"\n        try:\n            r = subprocess.run(\n                command, shell=True, cwd=WORKDIR,\n                capture_output=True, text=True, timeout=300\n            )\n            output = (r.stdout + r.stderr).strip()[:50000]\n            status = \"completed\"\n        except subprocess.TimeoutExpired:\n            output = \"Error: Timeout (300s)\"\n            status = \"timeout\"\n        except Exception as e:\n            output = f\"Error: {e}\"\n            status = \"error\"\n        self.tasks[task_id][\"status\"] = status\n        self.tasks[task_id][\"result\"] = output or \"(no output)\"\n        with self._lock:\n            self._notification_queue.append({\n                \"task_id\": task_id,\n                \"status\": status,\n                \"command\": command[:80],\n                \"result\": (output or \"(no output)\")[:500],\n            })\n\n    def check(self, task_id: str = None) -> str:\n        \"\"\"Check status of one task or list all.\"\"\"\n        if task_id:\n            t = self.tasks.get(task_id)\n            if not t:\n                return f\"Error: Unknown task {task_id}\"\n            return f\"[{t['status']}] {t['command'][:60]}\\n{t.get('result') or '(running)'}\"\n        lines = []\n        for tid, t in self.tasks.items():\n            lines.append(f\"{tid}: [{t['status']}] {t['command'][:60]}\")\n        return \"\\n\".join(lines) if lines else \"No background tasks.\"\n\n    def drain_notifications(self) -> list:\n        \"\"\"Return and clear all pending completion notifications.\"\"\"\n        with self._lock:\n            notifs = list(self._notification_queue)\n            self._notification_queue.clear()\n        return notifs\n\n\nBG = BackgroundManager()\n\n\n# -- Tool implementations --\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_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(command, shell=True, cwd=WORKDIR,\n                           capture_output=True, text=True, timeout=120)\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\ndef run_read(path: str, limit: int = None) -> str:\n    try:\n        lines = safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\ndef run_write(path: str, content: str) -> str:\n    try:\n        fp = safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\ndef run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = safe_path(path)\n        c = fp.read_text()\n        if old_text not in c:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(c.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\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\"], kw[\"new_text\"]),\n    \"background_run\":   lambda **kw: BG.run(kw[\"command\"]),\n    \"check_background\": lambda **kw: BG.check(kw.get(\"task_id\")),\n}\n\nTOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command (blocking).\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n    {\"name\": \"background_run\", \"description\": \"Run command in background thread. Returns task_id immediately.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"check_background\", \"description\": \"Check background task status. Omit task_id to list all.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"task_id\": {\"type\": \"string\"}}}},\n]\n\n\ndef agent_loop(messages: list):\n    while True:\n        # Drain background notifications and inject as system message before LLM call\n        notifs = BG.drain_notifications()\n        if notifs and messages:\n            notif_text = \"\\n\".join(\n                f\"[bg:{n['task_id']}] {n['status']}: {n['result']}\" for n in notifs\n            )\n            messages.append({\"role\": \"user\", \"content\": f\"<background-results>\\n{notif_text}\\n</background-results>\"})\n            messages.append({\"role\": \"assistant\", \"content\": \"Noted background results.\"})\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        if response.stop_reason != \"tool_use\":\n            return\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                handler = TOOL_HANDLERS.get(block.name)\n                try:\n                    output = handler(**block.input) if handler else f\"Unknown tool: {block.name}\"\n                except Exception as e:\n                    output = f\"Error: {e}\"\n                print(f\"> {block.name}: {str(output)[:200]}\")\n                results.append({\"type\": \"tool_result\", \"tool_use_id\": block.id, \"content\": str(output)})\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms08 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
+      "layer": "runtime",
+      "source": "#!/usr/bin/env python3\n# Harness: background execution -- the model thinks while the harness waits.\n\"\"\"\ns13_background_tasks.py - Background Tasks\n\nRun slow commands in background threads. Before each LLM call, the loop\ndrains a notification queue and hands finished results back to the model.\n\n    Main thread                Background thread\n    +-----------------+        +-----------------+\n    | agent loop      |        | task executes   |\n    | ...             |        | ...             |\n    | [LLM call] <---+------- | enqueue(result) |\n    |  ^drain queue   |        +-----------------+\n    +-----------------+\n\n    Timeline:\n    Agent ----[spawn A]----[spawn B]----[other work]----\n                 |              |\n                 v              v\n              [A runs]      [B runs]\n                 |              |\n                 +-- notification queue --> [results injected]\n\nBackground tasks here are runtime execution slots, not the durable task-board\nrecords introduced in s12.\n\"\"\"\n\nimport os\nimport json\nimport subprocess\nimport threading\nimport time\nimport uuid\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nRUNTIME_DIR = WORKDIR / \".runtime-tasks\"\nRUNTIME_DIR.mkdir(exist_ok=True)\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\n\nSYSTEM = f\"You are a coding agent at {WORKDIR}. Use background_run for long-running commands.\"\n\nSTALL_THRESHOLD_S = 45  # seconds before a task is considered stalled\n\n\nclass NotificationQueue:\n    \"\"\"\n    Priority-based notification queue with same-key folding.\n\n    Folding means a newer message can replace an older message with the\n    same key, so the context is not flooded with stale updates.\n    \"\"\"\n\n    PRIORITIES = {\"immediate\": 0, \"high\": 1, \"medium\": 2, \"low\": 3}\n\n    def __init__(self):\n        self._queue = []  # list of (priority, key, message)\n        self._lock = threading.Lock()\n\n    def push(self, message: str, priority: str = \"medium\", key: str = None):\n        \"\"\"Add a message to the queue, folding if key matches an existing entry.\"\"\"\n        with self._lock:\n            if key:\n                # Fold: replace existing message with same key\n                self._queue = [(p, k, m) for p, k, m in self._queue if k != key]\n            self._queue.append((self.PRIORITIES.get(priority, 2), key, message))\n            self._queue.sort(key=lambda x: x[0])\n\n    def drain(self) -> list[str]:\n        \"\"\"Return all pending messages in priority order and clear the queue.\"\"\"\n        with self._lock:\n            messages = [m for _, _, m in self._queue]\n            self._queue.clear()\n            return messages\n\n\n# -- BackgroundManager: threaded execution + notification queue --\nclass BackgroundManager:\n    def __init__(self):\n        self.dir = RUNTIME_DIR\n        self.tasks = {}  # task_id -> {status, result, command, started_at}\n        self._notification_queue = []  # completed task results\n        self._lock = threading.Lock()\n\n    def _record_path(self, task_id: str) -> Path:\n        return self.dir / f\"{task_id}.json\"\n\n    def _output_path(self, task_id: str) -> Path:\n        return self.dir / f\"{task_id}.log\"\n\n    def _persist_task(self, task_id: str):\n        record = dict(self.tasks[task_id])\n        self._record_path(task_id).write_text(\n            json.dumps(record, indent=2, ensure_ascii=False)\n        )\n\n    def _preview(self, output: str, limit: int = 500) -> str:\n        compact = \" \".join((output or \"(no output)\").split())\n        return compact[:limit]\n\n    def run(self, command: str) -> str:\n        \"\"\"Start a background thread, return task_id immediately.\"\"\"\n        task_id = str(uuid.uuid4())[:8]\n        output_file = self._output_path(task_id)\n        self.tasks[task_id] = {\n            \"id\": task_id,\n            \"status\": \"running\",\n            \"result\": None,\n            \"command\": command,\n            \"started_at\": time.time(),\n            \"finished_at\": None,\n            \"result_preview\": \"\",\n            \"output_file\": str(output_file.relative_to(WORKDIR)),\n        }\n        self._persist_task(task_id)\n        thread = threading.Thread(\n            target=self._execute, args=(task_id, command), daemon=True\n        )\n        thread.start()\n        return (\n            f\"Background task {task_id} started: {command[:80]} \"\n            f\"(output_file={output_file.relative_to(WORKDIR)})\"\n        )\n\n    def _execute(self, task_id: str, command: str):\n        \"\"\"Thread target: run subprocess, capture output, push to queue.\"\"\"\n        try:\n            r = subprocess.run(\n                command, shell=True, cwd=WORKDIR,\n                capture_output=True, text=True, timeout=300\n            )\n            output = (r.stdout + r.stderr).strip()[:50000]\n            status = \"completed\"\n        except subprocess.TimeoutExpired:\n            output = \"Error: Timeout (300s)\"\n            status = \"timeout\"\n        except Exception as e:\n            output = f\"Error: {e}\"\n            status = \"error\"\n        final_output = output or \"(no output)\"\n        preview = self._preview(final_output)\n        output_path = self._output_path(task_id)\n        output_path.write_text(final_output)\n        self.tasks[task_id][\"status\"] = status\n        self.tasks[task_id][\"result\"] = final_output\n        self.tasks[task_id][\"finished_at\"] = time.time()\n        self.tasks[task_id][\"result_preview\"] = preview\n        self._persist_task(task_id)\n        with self._lock:\n            self._notification_queue.append({\n                \"task_id\": task_id,\n                \"status\": status,\n                \"command\": command[:80],\n                \"preview\": preview,\n                \"output_file\": str(output_path.relative_to(WORKDIR)),\n            })\n\n    def check(self, task_id: str = None) -> str:\n        \"\"\"Check status of one task or list all.\"\"\"\n        if task_id:\n            t = self.tasks.get(task_id)\n            if not t:\n                return f\"Error: Unknown task {task_id}\"\n            visible = {\n                \"id\": t[\"id\"],\n                \"status\": t[\"status\"],\n                \"command\": t[\"command\"],\n                \"result_preview\": t.get(\"result_preview\", \"\"),\n                \"output_file\": t.get(\"output_file\", \"\"),\n            }\n            return json.dumps(visible, indent=2, ensure_ascii=False)\n        lines = []\n        for tid, t in self.tasks.items():\n            lines.append(\n                f\"{tid}: [{t['status']}] {t['command'][:60]} \"\n                f\"-> {t.get('result_preview') or '(running)'}\"\n            )\n        return \"\\n\".join(lines) if lines else \"No background tasks.\"\n\n    def drain_notifications(self) -> list:\n        \"\"\"Return and clear all pending completion notifications.\"\"\"\n        with self._lock:\n            notifs = list(self._notification_queue)\n            self._notification_queue.clear()\n        return notifs\n\n    def detect_stalled(self) -> list[str]:\n        \"\"\"\n        Return task IDs that have been running longer than STALL_THRESHOLD_S.\n        \"\"\"\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\nBG = BackgroundManager()\n\n\n# -- Tool implementations --\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_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(command, shell=True, cwd=WORKDIR,\n                           capture_output=True, text=True, timeout=120)\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\ndef run_read(path: str, limit: int = None) -> str:\n    try:\n        lines = safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\ndef run_write(path: str, content: str) -> str:\n    try:\n        fp = safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\ndef run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = safe_path(path)\n        c = fp.read_text()\n        if old_text not in c:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(c.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\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\"], kw[\"new_text\"]),\n    \"background_run\":   lambda **kw: BG.run(kw[\"command\"]),\n    \"check_background\": lambda **kw: BG.check(kw.get(\"task_id\")),\n}\n\nTOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command (blocking).\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n    {\"name\": \"background_run\", \"description\": \"Run command in background thread. Returns task_id immediately.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"check_background\", \"description\": \"Check background task status. Omit task_id to list all.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"task_id\": {\"type\": \"string\"}}}},\n]\n\n\ndef agent_loop(messages: list):\n    while True:\n        # Drain background notifications and inject as a synthetic user/assistant\n        # transcript pair before the next model call (teaching demo behavior).\n        notifs = BG.drain_notifications()\n        if notifs and messages:\n            notif_text = \"\\n\".join(\n                f\"[bg:{n['task_id']}] {n['status']}: {n['preview']} \"\n                f\"(output_file={n['output_file']})\"\n                for n in notifs\n            )\n            messages.append({\"role\": \"user\", \"content\": f\"<background-results>\\n{notif_text}\\n</background-results>\"})\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        if response.stop_reason != \"tool_use\":\n            return\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                handler = TOOL_HANDLERS.get(block.name)\n                try:\n                    output = handler(**block.input) if handler else f\"Unknown tool: {block.name}\"\n                except Exception as e:\n                    output = f\"Error: {e}\"\n                print(f\"> {block.name}:\")\n                print(str(output)[:200])\n                results.append({\"type\": \"tool_result\", \"tool_use_id\": block.id, \"content\": str(output)})\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms13 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
     },
     {
-      "id": "s09",
-      "filename": "s09_agent_teams.py",
+      "id": "s14",
+      "filename": "s14_cron_scheduler.py",
+      "title": "Cron Scheduler",
+      "subtitle": "Let Time Trigger Work",
+      "loc": 452,
+      "tools": [
+        "bash",
+        "read_file",
+        "write_file",
+        "edit_file",
+        "cron_create",
+        "cron_delete",
+        "cron_list"
+      ],
+      "newTools": [
+        "cron_create",
+        "cron_delete",
+        "cron_list"
+      ],
+      "coreAddition": "Scheduled triggers over runtime tasks",
+      "keyInsight": "Scheduling is not a separate system -- it just feeds the same agent loop from a timer.",
+      "classes": [
+        {
+          "name": "CronLock",
+          "startLine": 87,
+          "endLine": 126
+        },
+        {
+          "name": "CronScheduler",
+          "startLine": 182,
+          "endLine": 393
+        }
+      ],
+      "functions": [
+        {
+          "name": "cron_matches",
+          "signature": "def cron_matches(expr: str, dt: datetime)",
+          "startLine": 127
+        },
+        {
+          "name": "_field_matches",
+          "signature": "def _field_matches(field: str, value: int, lo: int, hi: int)",
+          "startLine": 152
+        },
+        {
+          "name": "safe_path",
+          "signature": "def safe_path(p: str)",
+          "startLine": 398
+        },
+        {
+          "name": "run_bash",
+          "signature": "def run_bash(command: str)",
+          "startLine": 405
+        },
+        {
+          "name": "run_read",
+          "signature": "def run_read(path: str, limit: int = None)",
+          "startLine": 418
+        },
+        {
+          "name": "run_write",
+          "signature": "def run_write(path: str, content: str)",
+          "startLine": 428
+        },
+        {
+          "name": "run_edit",
+          "signature": "def run_edit(path: str, old_text: str, new_text: str)",
+          "startLine": 438
+        },
+        {
+          "name": "agent_loop",
+          "signature": "def agent_loop(messages: list)",
+          "startLine": 488
+        }
+      ],
+      "layer": "runtime",
+      "source": "#!/usr/bin/env python3\n# Harness: time -- the agent schedules its own future work.\n\"\"\"\ns14_cron_scheduler.py - Cron / Scheduled Tasks\n\nThe agent can schedule prompts for future execution using standard cron\nexpressions. When a schedule matches the current time, it pushes a\nnotification back into the main conversation loop.\n\n    Cron expression: 5 fields\n    +-------+-------+-------+-------+-------+\n    | min   | hour  | dom   | month | dow   |\n    | 0-59  | 0-23  | 1-31  | 1-12  | 0-6   |\n    +-------+-------+-------+-------+-------+\n    Examples:\n      \"*/5 * * * *\"   -> every 5 minutes\n      \"0 9 * * 1\"     -> Monday 9:00 AM\n      \"30 14 * * *\"   -> daily 2:30 PM\n\n    Two persistence modes:\n    +--------------------+-------------------------------+\n    | session-only       | In-memory list, lost on exit  |\n    | durable            | .claude/scheduled_tasks.json  |\n    +--------------------+-------------------------------+\n\n    Two trigger modes:\n    +--------------------+-------------------------------+\n    | recurring          | Repeats until deleted or      |\n    |                    | 7-day auto-expiry             |\n    | one-shot           | Fires once, then auto-deleted |\n    +--------------------+-------------------------------+\n\n    Jitter: recurring tasks can avoid exact minute boundaries.\n\n    Architecture:\n    +-------------------------------+\n    |  Background thread            |\n    |  (checks every 1 second)      |\n    |                               |\n    |  for each task:               |\n    |    if cron_matches(now):      |\n    |      enqueue notification     |\n    +-------------------------------+\n              |\n              v\n    [notification_queue]\n              |\n         (drained at top of agent_loop)\n              |\n              v\n    [injected as user messages before LLM call]\n\nKey idea: scheduling remembers future work, then hands it back to the\nsame main loop when the time arrives.\n\"\"\"\n\nimport json\nimport os\nimport subprocess\nimport threading\nimport time\nimport uuid\nfrom datetime import datetime, timedelta\nfrom pathlib import Path\nfrom queue import Queue, Empty\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\n\nSCHEDULED_TASKS_FILE = WORKDIR / \".claude\" / \"scheduled_tasks.json\"\nCRON_LOCK_FILE = WORKDIR / \".claude\" / \"cron.lock\"\nAUTO_EXPIRY_DAYS = 7\nJITTER_MINUTES = [0, 30]  # avoid these exact minutes for recurring tasks\nJITTER_OFFSET_MAX = 4     # offset range in minutes\n# Teaching version: use a simple 1-4 minute offset when needed.\n\n\nclass CronLock:\n    \"\"\"\n    PID-file-based lock to prevent multiple sessions from firing the same cron job.\n    \"\"\"\n\n    def __init__(self, lock_path: Path = None):\n        self._lock_path = lock_path or CRON_LOCK_FILE\n\n    def acquire(self) -> bool:\n        \"\"\"\n        Try to acquire the cron lock. Returns True on success.\n\n        If a lock file exists, check whether the PID inside is still alive.\n        If the process is dead the lock is stale and we can take over.\n        \"\"\"\n        if self._lock_path.exists():\n            try:\n                stored_pid = int(self._lock_path.read_text().strip())\n                # PID liveness probe: send signal 0 (no-op) to check existence\n                os.kill(stored_pid, 0)\n                # Process is alive -- lock is held by another session\n                return False\n            except (ValueError, ProcessLookupError, PermissionError, OSError):\n                # Stale lock (process dead or PID unparseable) -- remove it\n                pass\n        self._lock_path.parent.mkdir(parents=True, exist_ok=True)\n        self._lock_path.write_text(str(os.getpid()))\n        return True\n\n    def release(self):\n        \"\"\"Remove the lock file if it belongs to this process.\"\"\"\n        try:\n            if self._lock_path.exists():\n                stored_pid = int(self._lock_path.read_text().strip())\n                if stored_pid == os.getpid():\n                    self._lock_path.unlink()\n        except (ValueError, OSError):\n            pass\n\n\ndef cron_matches(expr: str, dt: datetime) -> bool:\n    \"\"\"\n    Check if a 5-field cron expression matches a given datetime.\n\n    Fields: minute hour day-of-month month day-of-week\n    Supports: * (any), */N (every N), N (exact), N-M (range), N,M (list)\n\n    No external dependencies -- simple manual matching.\n    \"\"\"\n    fields = expr.strip().split()\n    if len(fields) != 5:\n        return False\n\n    values = [dt.minute, dt.hour, dt.day, dt.month, dt.weekday()]\n    # Python weekday: 0=Monday; cron: 0=Sunday. Convert.\n    cron_dow = (dt.weekday() + 1) % 7\n    values[4] = cron_dow\n    ranges = [(0, 59), (0, 23), (1, 31), (1, 12), (0, 6)]\n\n    for field, value, (lo, hi) in zip(fields, values, ranges):\n        if not _field_matches(field, value, lo, hi):\n            return False\n    return True\n\n\ndef _field_matches(field: str, value: int, lo: int, hi: int) -> bool:\n    \"\"\"Match a single cron field against a value.\"\"\"\n    if field == \"*\":\n        return True\n\n    for part in field.split(\",\"):\n        # Handle step: */N or N-M/S\n        step = 1\n        if \"/\" in part:\n            part, step_str = part.split(\"/\", 1)\n            step = int(step_str)\n\n        if part == \"*\":\n            # */N -- check if value is on the step grid\n            if (value - lo) % step == 0:\n                return True\n        elif \"-\" in part:\n            # Range: N-M\n            start, end = part.split(\"-\", 1)\n            start, end = int(start), int(end)\n            if start <= value <= end and (value - start) % step == 0:\n                return True\n        else:\n            # Exact value\n            if int(part) == value:\n                return True\n\n    return False\n\n\nclass CronScheduler:\n    \"\"\"\n    Manage scheduled tasks with background checking.\n\n    Teaching version keeps only the core pieces: schedule records, a\n    minute checker, optional persistence, and a notification queue.\n    \"\"\"\n\n    def __init__(self):\n        self.tasks = []        # list of task dicts\n        self.queue = Queue()   # notification queue\n        self._stop_event = threading.Event()\n        self._thread = None\n        self._last_check_minute = -1  # avoid double-firing within same minute\n\n    def start(self):\n        \"\"\"Load durable tasks and start the background check thread.\"\"\"\n        self._load_durable()\n        self._thread = threading.Thread(target=self._check_loop, daemon=True)\n        self._thread.start()\n        count = len(self.tasks)\n        if count:\n            print(f\"[Cron] Loaded {count} scheduled tasks\")\n\n    def stop(self):\n        \"\"\"Stop the background thread.\"\"\"\n        self._stop_event.set()\n        if self._thread:\n            self._thread.join(timeout=2)\n\n    def create(self, cron_expr: str, prompt: str,\n               recurring: bool = True, durable: bool = False) -> str:\n        \"\"\"Create a new scheduled task. Returns the task ID.\"\"\"\n        task_id = str(uuid.uuid4())[:8]\n        now = time.time()\n\n        task = {\n            \"id\": task_id,\n            \"cron\": cron_expr,\n            \"prompt\": prompt,\n            \"recurring\": recurring,\n            \"durable\": durable,\n            \"createdAt\": now,\n        }\n\n        # Jitter for recurring tasks: if the cron fires on :00 or :30,\n        # note it so we can offset the check slightly\n        if recurring:\n            task[\"jitter_offset\"] = self._compute_jitter(cron_expr)\n\n        self.tasks.append(task)\n        if durable:\n            self._save_durable()\n\n        mode = \"recurring\" if recurring else \"one-shot\"\n        store = \"durable\" if durable else \"session-only\"\n        return f\"Created task {task_id} ({mode}, {store}): cron={cron_expr}\"\n\n    def delete(self, task_id: str) -> str:\n        \"\"\"Delete a scheduled task by ID.\"\"\"\n        before = len(self.tasks)\n        self.tasks = [t for t in self.tasks if t[\"id\"] != task_id]\n        if len(self.tasks) < before:\n            self._save_durable()\n            return f\"Deleted task {task_id}\"\n        return f\"Task {task_id} not found\"\n\n    def list_tasks(self) -> str:\n        \"\"\"List all scheduled tasks.\"\"\"\n        if not self.tasks:\n            return \"No scheduled tasks.\"\n        lines = []\n        for t in self.tasks:\n            mode = \"recurring\" if t[\"recurring\"] else \"one-shot\"\n            store = \"durable\" if t[\"durable\"] else \"session\"\n            age_hours = (time.time() - t[\"createdAt\"]) / 3600\n            lines.append(\n                f\"  {t['id']}  {t['cron']}  [{mode}/{store}] \"\n                f\"({age_hours:.1f}h old): {t['prompt'][:60]}\"\n            )\n        return \"\\n\".join(lines)\n\n    def drain_notifications(self) -> list[str]:\n        \"\"\"Drain all pending notifications from the queue.\"\"\"\n        notifications = []\n        while True:\n            try:\n                notifications.append(self.queue.get_nowait())\n            except Empty:\n                break\n        return notifications\n\n    def _compute_jitter(self, cron_expr: str) -> int:\n        \"\"\"If cron targets :00 or :30, return a small offset (1-4 minutes).\"\"\"\n        fields = cron_expr.strip().split()\n        if len(fields) < 1:\n            return 0\n        minute_field = fields[0]\n        try:\n            minute_val = int(minute_field)\n            if minute_val in JITTER_MINUTES:\n                # Deterministic jitter based on the expression hash\n                return (hash(cron_expr) % JITTER_OFFSET_MAX) + 1\n        except ValueError:\n            pass\n        return 0\n\n    def _check_loop(self):\n        \"\"\"Background thread: check every second if any task is due.\"\"\"\n        while not self._stop_event.is_set():\n            now = datetime.now()\n            current_minute = now.hour * 60 + now.minute\n\n            # Only check once per minute to avoid double-firing\n            if current_minute != self._last_check_minute:\n                self._last_check_minute = current_minute\n                self._check_tasks(now)\n\n            self._stop_event.wait(timeout=1)\n\n    def _check_tasks(self, now: datetime):\n        \"\"\"Check all tasks against current time, fire matches.\"\"\"\n        expired = []\n        fired_oneshots = []\n\n        for task in self.tasks:\n            # Auto-expiry: recurring tasks older than 7 days\n            age_days = (time.time() - task[\"createdAt\"]) / 86400\n            if task[\"recurring\"] and age_days > AUTO_EXPIRY_DAYS:\n                expired.append(task[\"id\"])\n                continue\n\n            # Apply jitter offset for the match check\n            check_time = now\n            jitter = task.get(\"jitter_offset\", 0)\n            if jitter:\n                check_time = now - timedelta(minutes=jitter)\n\n            if cron_matches(task[\"cron\"], check_time):\n                notification = (\n                    f\"[Scheduled task {task['id']}]: {task['prompt']}\"\n                )\n                self.queue.put(notification)\n                task[\"last_fired\"] = time.time()\n                print(f\"[Cron] Fired: {task['id']}\")\n\n                if not task[\"recurring\"]:\n                    fired_oneshots.append(task[\"id\"])\n\n        # Clean up expired and one-shot tasks\n        if expired or fired_oneshots:\n            remove_ids = set(expired) | set(fired_oneshots)\n            self.tasks = [t for t in self.tasks if t[\"id\"] not in remove_ids]\n            for tid in expired:\n                print(f\"[Cron] Auto-expired: {tid} (older than {AUTO_EXPIRY_DAYS} days)\")\n            for tid in fired_oneshots:\n                print(f\"[Cron] One-shot completed and removed: {tid}\")\n            self._save_durable()\n\n    def _load_durable(self):\n        \"\"\"Load durable tasks from .claude/scheduled_tasks.json.\"\"\"\n        if not SCHEDULED_TASKS_FILE.exists():\n            return\n        try:\n            data = json.loads(SCHEDULED_TASKS_FILE.read_text())\n            # Only load durable tasks\n            self.tasks = [t for t in data if t.get(\"durable\")]\n        except Exception as e:\n            print(f\"[Cron] Error loading tasks: {e}\")\n\n    def detect_missed_tasks(self) -> list[dict]:\n        \"\"\"\n        On startup, check each durable task's last_fired time.\n\n        If a task should have fired while the session was closed (i.e.\n        the gap between last_fired and now contains at least one cron match),\n        flag it as missed. The caller can then let the user decide whether\n        to run or discard each missed task.\n\n        \"\"\"\n        now = datetime.now()\n        missed = []\n        for task in self.tasks:\n            last_fired = task.get(\"last_fired\")\n            if last_fired is None:\n                continue\n            last_dt = datetime.fromtimestamp(last_fired)\n            # Walk forward minute-by-minute from last_fired to now (cap at 24h)\n            check = last_dt + timedelta(minutes=1)\n            cap = min(now, last_dt + timedelta(hours=24))\n            while check <= cap:\n                if cron_matches(task[\"cron\"], check):\n                    missed.append({\n                        \"id\": task[\"id\"],\n                        \"cron\": task[\"cron\"],\n                        \"prompt\": task[\"prompt\"],\n                        \"missed_at\": check.isoformat(),\n                    })\n                    break  # one miss is enough to flag it\n                check += timedelta(minutes=1)\n        return missed\n\n    def _save_durable(self):\n        \"\"\"Save durable tasks to disk.\"\"\"\n        durable = [t for t in self.tasks if t.get(\"durable\")]\n        SCHEDULED_TASKS_FILE.parent.mkdir(parents=True, exist_ok=True)\n        SCHEDULED_TASKS_FILE.write_text(\n            json.dumps(durable, indent=2) + \"\\n\"\n        )\n\n\n# Global scheduler\nscheduler = CronScheduler()\n\n\n# -- Tool implementations --\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\n\ndef run_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(command, shell=True, cwd=WORKDIR,\n                           capture_output=True, text=True, timeout=120)\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\n\ndef run_read(path: str, limit: int = None) -> str:\n    try:\n        lines = safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef run_write(path: str, content: str) -> str:\n    try:\n        fp = safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = safe_path(path)\n        content = fp.read_text()\n        if old_text not in content:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(content.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\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\"], kw[\"new_text\"]),\n    \"cron_create\": lambda **kw: scheduler.create(\n        kw[\"cron\"], kw[\"prompt\"], kw.get(\"recurring\", True), kw.get(\"durable\", False)),\n    \"cron_delete\": lambda **kw: scheduler.delete(kw[\"id\"]),\n    \"cron_list\":   lambda **kw: scheduler.list_tasks(),\n}\n\nTOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n    {\"name\": \"cron_create\", \"description\": \"Schedule a recurring or one-shot task with a cron expression.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\n         \"cron\": {\"type\": \"string\", \"description\": \"5-field cron expression: 'min hour dom month dow'\"},\n         \"prompt\": {\"type\": \"string\", \"description\": \"The prompt to inject when the task fires\"},\n         \"recurring\": {\"type\": \"boolean\", \"description\": \"true=repeat, false=fire once then delete. Default true.\"},\n         \"durable\": {\"type\": \"boolean\", \"description\": \"true=persist to disk, false=session-only. Default false.\"},\n     }, \"required\": [\"cron\", \"prompt\"]}},\n    {\"name\": \"cron_delete\", \"description\": \"Delete a scheduled task by ID.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\n         \"id\": {\"type\": \"string\", \"description\": \"Task ID to delete\"},\n     }, \"required\": [\"id\"]}},\n    {\"name\": \"cron_list\", \"description\": \"List all scheduled tasks.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n]\n\nSYSTEM = f\"You are a coding agent at {WORKDIR}. Use tools to solve tasks.\\n\\nYou can schedule future work with cron_create. Tasks fire automatically and their prompts are injected into the conversation.\"\n\n\ndef agent_loop(messages: list):\n    \"\"\"\n    Cron-aware agent loop.\n\n    Before each LLM call, drain the notification queue and inject any\n    fired task prompts as user messages. This is how the agent \"wakes up\"\n    to handle scheduled work.\n    \"\"\"\n    while True:\n        # Drain scheduled task notifications\n        notifications = scheduler.drain_notifications()\n        for note in notifications:\n            print(f\"[Cron notification] {note[:100]}\")\n            messages.append({\"role\": \"user\", \"content\": note})\n\n        response = client.messages.create(\n            model=MODEL, system=SYSTEM, messages=messages,\n            tools=TOOLS, max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n\n        if response.stop_reason != \"tool_use\":\n            return\n\n        results = []\n        for block in response.content:\n            if block.type != \"tool_use\":\n                continue\n            handler = TOOL_HANDLERS.get(block.name)\n            try:\n                output = handler(**(block.input or {})) if handler else f\"Unknown: {block.name}\"\n            except Exception as e:\n                output = f\"Error: {e}\"\n            print(f\"> {block.name}: {str(output)[:200]}\")\n            results.append({\n                \"type\": \"tool_result\",\n                \"tool_use_id\": block.id,\n                \"content\": str(output),\n            })\n\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    scheduler.start()\n    print(\"[Cron scheduler running. Background checks every second.]\")\n    print(\"[Commands: /cron to list tasks, /test to fire a test notification]\")\n\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms14 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            scheduler.stop()\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            scheduler.stop()\n            break\n\n        if query.strip() == \"/cron\":\n            print(scheduler.list_tasks())\n            continue\n\n        if query.strip() == \"/test\":\n            # Manually enqueue a test notification for demonstration\n            scheduler.queue.put(\"[Scheduled task test-0000]: This is a test notification.\")\n            print(\"[Test notification enqueued. It will be injected on your next message.]\")\n            continue\n\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
+    },
+    {
+      "id": "s15",
+      "filename": "s15_agent_teams.py",
       "title": "Agent Teams",
-      "subtitle": "Teammates + Mailboxes",
-      "loc": 348,
+      "subtitle": "Persistent Specialists",
+      "loc": 350,
       "tools": [
         "alice",
         "bash",
@@ -487,61 +1001,61 @@
         "list_teammates",
         "broadcast"
       ],
-      "coreAddition": "TeammateManager + file-based mailbox",
-      "keyInsight": "When one agent can't finish, delegate to persistent teammates via async mailboxes",
+      "coreAddition": "Team roster + teammate lifecycle",
+      "keyInsight": "Teammates persist beyond one prompt, have identity, and coordinate through durable channels.",
       "classes": [
         {
           "name": "MessageBus",
-          "startLine": 77,
-          "endLine": 118
+          "startLine": 84,
+          "endLine": 125
         },
         {
           "name": "TeammateManager",
-          "startLine": 123,
-          "endLine": 249
+          "startLine": 130,
+          "endLine": 258
         }
       ],
       "functions": [
         {
           "name": "_safe_path",
           "signature": "def _safe_path(p: str)",
-          "startLine": 254
+          "startLine": 263
         },
         {
           "name": "_run_bash",
           "signature": "def _run_bash(command: str)",
-          "startLine": 261
+          "startLine": 270
         },
         {
           "name": "_run_read",
           "signature": "def _run_read(path: str, limit: int = None)",
-          "startLine": 276
+          "startLine": 285
         },
         {
           "name": "_run_write",
           "signature": "def _run_write(path: str, content: str)",
-          "startLine": 286
+          "startLine": 295
         },
         {
           "name": "_run_edit",
           "signature": "def _run_edit(path: str, old_text: str, new_text: str)",
-          "startLine": 296
+          "startLine": 305
         },
         {
           "name": "agent_loop",
           "signature": "def agent_loop(messages: list)",
-          "startLine": 344
+          "startLine": 353
         }
       ],
-      "layer": "collaboration",
-      "source": "#!/usr/bin/env python3\n\"\"\"\ns09_agent_teams.py - Agent Teams\n\nPersistent named agents with file-based JSONL inboxes. Each teammate runs\nits own agent loop in a separate thread. Communication via append-only inboxes.\n\n    Subagent (s04):  spawn -> execute -> return summary -> destroyed\n    Teammate (s09):  spawn -> work -> idle -> work -> ... -> shutdown\n\n    .team/config.json                   .team/inbox/\n    +----------------------------+      +------------------+\n    | {\"team_name\": \"default\",   |      | alice.jsonl      |\n    |  \"members\": [              |      | bob.jsonl        |\n    |    {\"name\":\"alice\",        |      | lead.jsonl       |\n    |     \"role\":\"coder\",        |      +------------------+\n    |     \"status\":\"idle\"}       |\n    |  ]}                        |      send_message(\"alice\", \"fix bug\"):\n    +----------------------------+        open(\"alice.jsonl\", \"a\").write(msg)\n\n                                        read_inbox(\"alice\"):\n    spawn_teammate(\"alice\",\"coder\",...)   msgs = [json.loads(l) for l in ...]\n         |                                open(\"alice.jsonl\", \"w\").close()\n         v                                return msgs  # drain\n    Thread: alice             Thread: bob\n    +------------------+      +------------------+\n    | agent_loop       |      | agent_loop       |\n    | status: working  |      | status: idle     |\n    | ... runs tools   |      | ... waits ...    |\n    | status -> idle   |      |                  |\n    +------------------+      +------------------+\n\n    5 message types (all declared, not all handled here):\n    +-------------------------+-----------------------------------+\n    | message                 | Normal text message               |\n    | broadcast               | Sent to all teammates             |\n    | shutdown_request        | Request graceful shutdown (s10)   |\n    | shutdown_response       | Approve/reject shutdown (s10)     |\n    | plan_approval_response  | Approve/reject plan (s10)         |\n    +-------------------------+-----------------------------------+\n\nKey insight: \"Teammates that can talk to each other.\"\n\"\"\"\n\nimport json\nimport os\nimport subprocess\nimport threading\nimport time\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\nTEAM_DIR = WORKDIR / \".team\"\nINBOX_DIR = TEAM_DIR / \"inbox\"\n\nSYSTEM = f\"You are a team lead at {WORKDIR}. Spawn teammates and communicate via inboxes.\"\n\nVALID_MSG_TYPES = {\n    \"message\",\n    \"broadcast\",\n    \"shutdown_request\",\n    \"shutdown_response\",\n    \"plan_approval_response\",\n}\n\n\n# -- MessageBus: JSONL inbox per teammate --\nclass MessageBus:\n    def __init__(self, inbox_dir: Path):\n        self.dir = inbox_dir\n        self.dir.mkdir(parents=True, exist_ok=True)\n\n    def send(self, sender: str, to: str, content: str,\n             msg_type: str = \"message\", extra: dict = None) -> str:\n        if msg_type not in VALID_MSG_TYPES:\n            return f\"Error: Invalid type '{msg_type}'. Valid: {VALID_MSG_TYPES}\"\n        msg = {\n            \"type\": msg_type,\n            \"from\": sender,\n            \"content\": content,\n            \"timestamp\": time.time(),\n        }\n        if extra:\n            msg.update(extra)\n        inbox_path = self.dir / f\"{to}.jsonl\"\n        with open(inbox_path, \"a\") as f:\n            f.write(json.dumps(msg) + \"\\n\")\n        return f\"Sent {msg_type} to {to}\"\n\n    def read_inbox(self, name: str) -> list:\n        inbox_path = self.dir / f\"{name}.jsonl\"\n        if not inbox_path.exists():\n            return []\n        messages = []\n        for line in inbox_path.read_text().strip().splitlines():\n            if line:\n                messages.append(json.loads(line))\n        inbox_path.write_text(\"\")\n        return messages\n\n    def broadcast(self, sender: str, content: str, teammates: list) -> str:\n        count = 0\n        for name in teammates:\n            if name != sender:\n                self.send(sender, name, content, \"broadcast\")\n                count += 1\n        return f\"Broadcast to {count} teammates\"\n\n\nBUS = MessageBus(INBOX_DIR)\n\n\n# -- TeammateManager: persistent named agents with config.json --\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    def _load_config(self) -> dict:\n        if self.config_path.exists():\n            return json.loads(self.config_path.read_text())\n        return {\"team_name\": \"default\", \"members\": []}\n\n    def _save_config(self):\n        self.config_path.write_text(json.dumps(self.config, indent=2))\n\n    def _find_member(self, name: str) -> dict:\n        for m in self.config[\"members\"]:\n            if m[\"name\"] == name:\n                return m\n        return None\n\n    def spawn(self, name: str, role: str, prompt: str) -> str:\n        member = self._find_member(name)\n        if member:\n            if member[\"status\"] not in (\"idle\", \"shutdown\"):\n                return f\"Error: '{name}' is currently {member['status']}\"\n            member[\"status\"] = \"working\"\n            member[\"role\"] = role\n        else:\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),\n            daemon=True,\n        )\n        self.threads[name] = thread\n        thread.start()\n        return f\"Spawned '{name}' (role: {role})\"\n\n    def _teammate_loop(self, name: str, role: str, prompt: str):\n        sys_prompt = (\n            f\"You are '{name}', role: {role}, at {WORKDIR}. \"\n            f\"Use send_message to communicate. Complete your task.\"\n        )\n        messages = [{\"role\": \"user\", \"content\": prompt}]\n        tools = self._teammate_tools()\n        for _ in range(50):\n            inbox = BUS.read_inbox(name)\n            for msg in inbox:\n                messages.append({\"role\": \"user\", \"content\": json.dumps(msg)})\n            try:\n                response = client.messages.create(\n                    model=MODEL,\n                    system=sys_prompt,\n                    messages=messages,\n                    tools=tools,\n                    max_tokens=8000,\n                )\n            except Exception:\n                break\n            messages.append({\"role\": \"assistant\", \"content\": response.content})\n            if response.stop_reason != \"tool_use\":\n                break\n            results = []\n            for block in response.content:\n                if block.type == \"tool_use\":\n                    output = self._exec(name, block.name, block.input)\n                    print(f\"  [{name}] {block.name}: {str(output)[:120]}\")\n                    results.append({\n                        \"type\": \"tool_result\",\n                        \"tool_use_id\": block.id,\n                        \"content\": str(output),\n                    })\n            messages.append({\"role\": \"user\", \"content\": results})\n        member = self._find_member(name)\n        if member and member[\"status\"] != \"shutdown\":\n            member[\"status\"] = \"idle\"\n            self._save_config()\n\n    def _exec(self, sender: str, tool_name: str, args: dict) -> str:\n        # these base tools are unchanged from s02\n        if tool_name == \"bash\":\n            return _run_bash(args[\"command\"])\n        if tool_name == \"read_file\":\n            return _run_read(args[\"path\"])\n        if tool_name == \"write_file\":\n            return _run_write(args[\"path\"], args[\"content\"])\n        if tool_name == \"edit_file\":\n            return _run_edit(args[\"path\"], args[\"old_text\"], args[\"new_text\"])\n        if tool_name == \"send_message\":\n            return BUS.send(sender, args[\"to\"], args[\"content\"], args.get(\"msg_type\", \"message\"))\n        if tool_name == \"read_inbox\":\n            return json.dumps(BUS.read_inbox(sender), indent=2)\n        return f\"Unknown tool: {tool_name}\"\n\n    def _teammate_tools(self) -> list:\n        # these base tools are unchanged from s02\n        return [\n            {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n            {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}}, \"required\": [\"path\"]}},\n            {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n            {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n            {\"name\": \"send_message\", \"description\": \"Send message to a teammate.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"to\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}, \"msg_type\": {\"type\": \"string\", \"enum\": list(VALID_MSG_TYPES)}}, \"required\": [\"to\", \"content\"]}},\n            {\"name\": \"read_inbox\", \"description\": \"Read and drain your inbox.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n        ]\n\n    def list_all(self) -> str:\n        if not self.config[\"members\"]:\n            return \"No teammates.\"\n        lines = [f\"Team: {self.config['team_name']}\"]\n        for m in self.config[\"members\"]:\n            lines.append(f\"  {m['name']} ({m['role']}): {m['status']}\")\n        return \"\\n\".join(lines)\n\n    def member_names(self) -> list:\n        return [m[\"name\"] for m in self.config[\"members\"]]\n\n\nTEAM = TeammateManager(TEAM_DIR)\n\n\n# -- Base tool implementations (these base tools are unchanged from s02) --\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\n\ndef _run_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(\n            command, shell=True, cwd=WORKDIR,\n            capture_output=True, text=True, timeout=120,\n        )\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\n\ndef _run_read(path: str, limit: int = None) -> str:\n    try:\n        lines = _safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef _run_write(path: str, content: str) -> str:\n    try:\n        fp = _safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef _run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = _safe_path(path)\n        c = fp.read_text()\n        if old_text not in c:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(c.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\n# -- Lead tool dispatch (9 tools) --\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\"], kw[\"new_text\"]),\n    \"spawn_teammate\":  lambda **kw: TEAM.spawn(kw[\"name\"], kw[\"role\"], kw[\"prompt\"]),\n    \"list_teammates\":  lambda **kw: TEAM.list_all(),\n    \"send_message\":    lambda **kw: BUS.send(\"lead\", kw[\"to\"], kw[\"content\"], kw.get(\"msg_type\", \"message\")),\n    \"read_inbox\":      lambda **kw: json.dumps(BUS.read_inbox(\"lead\"), indent=2),\n    \"broadcast\":       lambda **kw: BUS.broadcast(\"lead\", kw[\"content\"], TEAM.member_names()),\n}\n\n# these base tools are unchanged from s02\nTOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n    {\"name\": \"spawn_teammate\", \"description\": \"Spawn a persistent teammate that runs in its own thread.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}, \"role\": {\"type\": \"string\"}, \"prompt\": {\"type\": \"string\"}}, \"required\": [\"name\", \"role\", \"prompt\"]}},\n    {\"name\": \"list_teammates\", \"description\": \"List all teammates with name, role, status.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n    {\"name\": \"send_message\", \"description\": \"Send a message to a teammate's inbox.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"to\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}, \"msg_type\": {\"type\": \"string\", \"enum\": list(VALID_MSG_TYPES)}}, \"required\": [\"to\", \"content\"]}},\n    {\"name\": \"read_inbox\", \"description\": \"Read and drain the lead's inbox.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n    {\"name\": \"broadcast\", \"description\": \"Send a message to all teammates.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"content\": {\"type\": \"string\"}}, \"required\": [\"content\"]}},\n]\n\n\ndef agent_loop(messages: list):\n    while True:\n        inbox = BUS.read_inbox(\"lead\")\n        if inbox:\n            messages.append({\n                \"role\": \"user\",\n                \"content\": f\"<inbox>{json.dumps(inbox, indent=2)}</inbox>\",\n            })\n            messages.append({\n                \"role\": \"assistant\",\n                \"content\": \"Noted inbox messages.\",\n            })\n        response = client.messages.create(\n            model=MODEL,\n            system=SYSTEM,\n            messages=messages,\n            tools=TOOLS,\n            max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n        if response.stop_reason != \"tool_use\":\n            return\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                handler = TOOL_HANDLERS.get(block.name)\n                try:\n                    output = handler(**block.input) if handler else f\"Unknown tool: {block.name}\"\n                except Exception as e:\n                    output = f\"Error: {e}\"\n                print(f\"> {block.name}: {str(output)[:200]}\")\n                results.append({\n                    \"type\": \"tool_result\",\n                    \"tool_use_id\": block.id,\n                    \"content\": str(output),\n                })\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms09 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n        if query.strip() == \"/team\":\n            print(TEAM.list_all())\n            continue\n        if query.strip() == \"/inbox\":\n            print(json.dumps(BUS.read_inbox(\"lead\"), indent=2))\n            continue\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
+      "layer": "platform",
+      "source": "#!/usr/bin/env python3\n# Harness: team mailboxes -- multiple models, coordinated through files.\n\"\"\"\ns15_agent_teams.py - Agent Teams\n\nPersistent named agents with file-based JSONL inboxes. Each teammate runs\nits own agent loop in a separate thread. Communication happens through\nappend-only inbox files.\n\n    Subagent (s04):  spawn -> execute -> return summary -> destroyed\n    Teammate (s15):  spawn -> work -> idle -> work -> ... -> shutdown\n\n    .team/config.json                   .team/inbox/\n    +----------------------------+      +------------------+\n    | {\"team_name\": \"default\",   |      | alice.jsonl      |\n    |  \"members\": [              |      | bob.jsonl        |\n    |    {\"name\":\"alice\",        |      | lead.jsonl       |\n    |     \"role\":\"coder\",        |      +------------------+\n    |     \"status\":\"idle\"}       |\n    |  ]}                        |      send_message(\"alice\", \"fix bug\"):\n    +----------------------------+        open(\"alice.jsonl\", \"a\").write(msg)\n\n                                        read_inbox(\"alice\"):\n    spawn_teammate(\"alice\",\"coder\",...)   msgs = [json.loads(l) for l in ...]\n         |                                open(\"alice.jsonl\", \"w\").close()\n         v                                return msgs  # drain\n    Thread: alice             Thread: bob\n    +------------------+      +------------------+\n    | agent_loop       |      | agent_loop       |\n    | status: working  |      | status: idle     |\n    | ... runs tools   |      | ... waits ...    |\n    | status -> idle   |      |                  |\n    +------------------+      +------------------+\n\nKey idea: teammates have names, inboxes, and independent loops.\n\nRead this file in this order:\n1. MessageBus: how messages are queued and drained.\n2. TeammateManager: what persistent teammate state looks like.\n3. _teammate_loop / TOOL_HANDLERS: how each named teammate keeps re-entering the same tool loop.\n\nMost common confusion:\n- a teammate is not a one-shot subagent\n- an inbox message is not yet a full protocol request\n\nTeaching boundary:\nthis file teaches persistent named workers plus mailboxes.\nApproval protocols and autonomous policies are added in later chapters.\n\"\"\"\n\nimport json\nimport os\nimport subprocess\nimport threading\nimport time\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\nTEAM_DIR = WORKDIR / \".team\"\nINBOX_DIR = TEAM_DIR / \"inbox\"\n\nSYSTEM = f\"You are a team lead at {WORKDIR}. Spawn teammates and communicate via inboxes.\"\n\nVALID_MSG_TYPES = {\n    \"message\",\n    \"broadcast\",\n    \"shutdown_request\",\n    \"shutdown_response\",\n    \"plan_approval\",\n    \"plan_approval_response\",\n}\n\n\n# -- MessageBus: JSONL inbox per teammate --\nclass MessageBus:\n    def __init__(self, inbox_dir: Path):\n        self.dir = inbox_dir\n        self.dir.mkdir(parents=True, exist_ok=True)\n\n    def send(self, sender: str, to: str, content: str,\n             msg_type: str = \"message\", extra: dict = None) -> str:\n        if msg_type not in VALID_MSG_TYPES:\n            return f\"Error: Invalid type '{msg_type}'. Valid: {VALID_MSG_TYPES}\"\n        msg = {\n            \"type\": msg_type,\n            \"from\": sender,\n            \"content\": content,\n            \"timestamp\": time.time(),\n        }\n        if extra:\n            msg.update(extra)\n        inbox_path = self.dir / f\"{to}.jsonl\"\n        with open(inbox_path, \"a\") as f:\n            f.write(json.dumps(msg) + \"\\n\")\n        return f\"Sent {msg_type} to {to}\"\n\n    def read_inbox(self, name: str) -> list:\n        inbox_path = self.dir / f\"{name}.jsonl\"\n        if not inbox_path.exists():\n            return []\n        messages = []\n        for line in inbox_path.read_text().strip().splitlines():\n            if line:\n                messages.append(json.loads(line))\n        inbox_path.write_text(\"\")\n        return messages\n\n    def broadcast(self, sender: str, content: str, teammates: list) -> str:\n        count = 0\n        for name in teammates:\n            if name != sender:\n                self.send(sender, name, content, \"broadcast\")\n                count += 1\n        return f\"Broadcast to {count} teammates\"\n\n\nBUS = MessageBus(INBOX_DIR)\n\n\n# -- TeammateManager: persistent named agents with config.json --\nclass TeammateManager:\n    \"\"\"Persistent teammate registry plus worker-loop launcher.\"\"\"\n\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    def _load_config(self) -> dict:\n        if self.config_path.exists():\n            return json.loads(self.config_path.read_text())\n        return {\"team_name\": \"default\", \"members\": []}\n\n    def _save_config(self):\n        self.config_path.write_text(json.dumps(self.config, indent=2))\n\n    def _find_member(self, name: str) -> dict:\n        for m in self.config[\"members\"]:\n            if m[\"name\"] == name:\n                return m\n        return None\n\n    def spawn(self, name: str, role: str, prompt: str) -> str:\n        member = self._find_member(name)\n        if member:\n            if member[\"status\"] not in (\"idle\", \"shutdown\"):\n                return f\"Error: '{name}' is currently {member['status']}\"\n            member[\"status\"] = \"working\"\n            member[\"role\"] = role\n        else:\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),\n            daemon=True,\n        )\n        self.threads[name] = thread\n        thread.start()\n        return f\"Spawned '{name}' (role: {role})\"\n\n    def _teammate_loop(self, name: str, role: str, prompt: str):\n        sys_prompt = (\n            f\"You are '{name}', role: {role}, at {WORKDIR}. \"\n            f\"Use send_message to communicate. Complete your task.\"\n        )\n        messages = [{\"role\": \"user\", \"content\": prompt}]\n        tools = self._teammate_tools()\n        for _ in range(50):\n            inbox = BUS.read_inbox(name)\n            for msg in inbox:\n                messages.append({\"role\": \"user\", \"content\": json.dumps(msg)})\n            try:\n                response = client.messages.create(\n                    model=MODEL,\n                    system=sys_prompt,\n                    messages=messages,\n                    tools=tools,\n                    max_tokens=8000,\n                )\n            except Exception:\n                break\n            messages.append({\"role\": \"assistant\", \"content\": response.content})\n            if response.stop_reason != \"tool_use\":\n                break\n            results = []\n            for block in response.content:\n                if block.type == \"tool_use\":\n                    output = self._exec(name, block.name, block.input)\n                    print(f\"  [{name}] {block.name}: {str(output)[:120]}\")\n                    results.append({\n                        \"type\": \"tool_result\",\n                        \"tool_use_id\": block.id,\n                        \"content\": str(output),\n                    })\n            messages.append({\"role\": \"user\", \"content\": results})\n        member = self._find_member(name)\n        if member and member[\"status\"] != \"shutdown\":\n            member[\"status\"] = \"idle\"\n            self._save_config()\n\n    def _exec(self, sender: str, tool_name: str, args: dict) -> str:\n        # these base tools are unchanged from s02\n        if tool_name == \"bash\":\n            return _run_bash(args[\"command\"])\n        if tool_name == \"read_file\":\n            return _run_read(args[\"path\"])\n        if tool_name == \"write_file\":\n            return _run_write(args[\"path\"], args[\"content\"])\n        if tool_name == \"edit_file\":\n            return _run_edit(args[\"path\"], args[\"old_text\"], args[\"new_text\"])\n        if tool_name == \"send_message\":\n            return BUS.send(sender, args[\"to\"], args[\"content\"], args.get(\"msg_type\", \"message\"))\n        if tool_name == \"read_inbox\":\n            return json.dumps(BUS.read_inbox(sender), indent=2)\n        return f\"Unknown tool: {tool_name}\"\n\n    def _teammate_tools(self) -> list:\n        # these base tools are unchanged from s02\n        return [\n            {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n            {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}}, \"required\": [\"path\"]}},\n            {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n            {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n            {\"name\": \"send_message\", \"description\": \"Send message to a teammate.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"to\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}, \"msg_type\": {\"type\": \"string\", \"enum\": list(VALID_MSG_TYPES)}}, \"required\": [\"to\", \"content\"]}},\n            {\"name\": \"read_inbox\", \"description\": \"Read and drain your inbox.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n        ]\n\n    def list_all(self) -> str:\n        if not self.config[\"members\"]:\n            return \"No teammates.\"\n        lines = [f\"Team: {self.config['team_name']}\"]\n        for m in self.config[\"members\"]:\n            lines.append(f\"  {m['name']} ({m['role']}): {m['status']}\")\n        return \"\\n\".join(lines)\n\n    def member_names(self) -> list:\n        return [m[\"name\"] for m in self.config[\"members\"]]\n\n\nTEAM = TeammateManager(TEAM_DIR)\n\n\n# -- Base tool implementations (these base tools are unchanged from s02) --\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\n\ndef _run_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(\n            command, shell=True, cwd=WORKDIR,\n            capture_output=True, text=True, timeout=120,\n        )\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\n\ndef _run_read(path: str, limit: int = None) -> str:\n    try:\n        lines = _safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef _run_write(path: str, content: str) -> str:\n    try:\n        fp = _safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef _run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = _safe_path(path)\n        c = fp.read_text()\n        if old_text not in c:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(c.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\n# -- Lead tool dispatch (9 tools) --\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\"], kw[\"new_text\"]),\n    \"spawn_teammate\":  lambda **kw: TEAM.spawn(kw[\"name\"], kw[\"role\"], kw[\"prompt\"]),\n    \"list_teammates\":  lambda **kw: TEAM.list_all(),\n    \"send_message\":    lambda **kw: BUS.send(\"lead\", kw[\"to\"], kw[\"content\"], kw.get(\"msg_type\", \"message\")),\n    \"read_inbox\":      lambda **kw: json.dumps(BUS.read_inbox(\"lead\"), indent=2),\n    \"broadcast\":       lambda **kw: BUS.broadcast(\"lead\", kw[\"content\"], TEAM.member_names()),\n}\n\n# these base tools are unchanged from s02\nTOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n    {\"name\": \"spawn_teammate\", \"description\": \"Spawn a persistent teammate that runs in its own thread.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}, \"role\": {\"type\": \"string\"}, \"prompt\": {\"type\": \"string\"}}, \"required\": [\"name\", \"role\", \"prompt\"]}},\n    {\"name\": \"list_teammates\", \"description\": \"List all teammates with name, role, status.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n    {\"name\": \"send_message\", \"description\": \"Send a message to a teammate's inbox.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"to\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}, \"msg_type\": {\"type\": \"string\", \"enum\": list(VALID_MSG_TYPES)}}, \"required\": [\"to\", \"content\"]}},\n    {\"name\": \"read_inbox\", \"description\": \"Read and drain the lead's inbox.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n    {\"name\": \"broadcast\", \"description\": \"Send a message to all teammates.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"content\": {\"type\": \"string\"}}, \"required\": [\"content\"]}},\n]\n\n\ndef agent_loop(messages: list):\n    while True:\n        inbox = BUS.read_inbox(\"lead\")\n        if inbox:\n            messages.append({\n                \"role\": \"user\",\n                \"content\": f\"<inbox>{json.dumps(inbox, indent=2)}</inbox>\",\n            })\n        response = client.messages.create(\n            model=MODEL,\n            system=SYSTEM,\n            messages=messages,\n            tools=TOOLS,\n            max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n        if response.stop_reason != \"tool_use\":\n            return\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                handler = TOOL_HANDLERS.get(block.name)\n                try:\n                    output = handler(**block.input) if handler else f\"Unknown tool: {block.name}\"\n                except Exception as e:\n                    output = f\"Error: {e}\"\n                print(f\"> {block.name}:\")\n                print(str(output)[:200])\n                results.append({\n                    \"type\": \"tool_result\",\n                    \"tool_use_id\": block.id,\n                    \"content\": str(output),\n                })\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms15 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n        if query.strip() == \"/team\":\n            print(TEAM.list_all())\n            continue\n        if query.strip() == \"/inbox\":\n            print(json.dumps(BUS.read_inbox(\"lead\"), indent=2))\n            continue\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
     },
     {
-      "id": "s10",
-      "filename": "s10_team_protocols.py",
+      "id": "s16",
+      "filename": "s16_team_protocols.py",
       "title": "Team Protocols",
-      "subtitle": "Shared Communication Rules",
-      "loc": 419,
+      "subtitle": "Shared Request-Response Rules",
+      "loc": 482,
       "tools": [
         "bash",
         "read_file",
@@ -561,76 +1075,81 @@
         "plan_approval",
         "shutdown_request"
       ],
-      "coreAddition": "request_id correlation for two protocols",
-      "keyInsight": "One request-response pattern drives all team negotiation",
+      "coreAddition": "Protocol envelopes + request correlation",
+      "keyInsight": "A protocol request is a structured message with an ID; the response must reference the same ID.",
       "classes": [
         {
           "name": "MessageBus",
-          "startLine": 87,
-          "endLine": 128
+          "startLine": 98,
+          "endLine": 139
+        },
+        {
+          "name": "RequestStore",
+          "startLine": 143,
+          "endLine": 181
         },
         {
           "name": "TeammateManager",
-          "startLine": 133,
-          "endLine": 290
+          "startLine": 186,
+          "endLine": 357
         }
       ],
       "functions": [
         {
           "name": "_safe_path",
           "signature": "def _safe_path(p: str)",
-          "startLine": 295
+          "startLine": 362
         },
         {
           "name": "_run_bash",
           "signature": "def _run_bash(command: str)",
-          "startLine": 302
+          "startLine": 369
         },
         {
           "name": "_run_read",
           "signature": "def _run_read(path: str, limit: int = None)",
-          "startLine": 317
+          "startLine": 384
         },
         {
           "name": "_run_write",
           "signature": "def _run_write(path: str, content: str)",
-          "startLine": 327
+          "startLine": 394
         },
         {
           "name": "_run_edit",
           "signature": "def _run_edit(path: str, old_text: str, new_text: str)",
-          "startLine": 337
+          "startLine": 404
         },
         {
           "name": "handle_shutdown_request",
           "signature": "def handle_shutdown_request(teammate: str)",
-          "startLine": 350
+          "startLine": 417
         },
         {
           "name": "handle_plan_review",
           "signature": "def handle_plan_review(request_id: str, approve: bool, feedback: str = \"\")",
-          "startLine": 361
+          "startLine": 435
         },
         {
           "name": "_check_shutdown_status",
           "signature": "def _check_shutdown_status(request_id: str)",
-          "startLine": 375
+          "startLine": 453
         },
         {
           "name": "agent_loop",
           "signature": "def agent_loop(messages: list)",
-          "startLine": 425
+          "startLine": 502
         }
       ],
-      "layer": "collaboration",
-      "source": "#!/usr/bin/env python3\n\"\"\"\ns10_team_protocols.py - Team Protocols\n\nShutdown protocol and plan approval protocol, both using the same\nrequest_id correlation pattern. Builds on s09's team messaging.\n\n    Shutdown FSM: pending -> approved | rejected\n\n    Lead                              Teammate\n    +---------------------+          +---------------------+\n    | shutdown_request     |          |                     |\n    | {                    | -------> | receives request    |\n    |   request_id: abc    |          | decides: approve?   |\n    | }                    |          |                     |\n    +---------------------+          +---------------------+\n                                             |\n    +---------------------+          +-------v-------------+\n    | shutdown_response    | <------- | shutdown_response   |\n    | {                    |          | {                   |\n    |   request_id: abc    |          |   request_id: abc   |\n    |   approve: true      |          |   approve: true     |\n    | }                    |          | }                   |\n    +---------------------+          +---------------------+\n            |\n            v\n    status -> \"shutdown\", thread stops\n\n    Plan approval FSM: pending -> approved | rejected\n\n    Teammate                          Lead\n    +---------------------+          +---------------------+\n    | plan_approval        |          |                     |\n    | submit: {plan:\"...\"}| -------> | reviews plan text   |\n    +---------------------+          | approve/reject?     |\n                                     +---------------------+\n                                             |\n    +---------------------+          +-------v-------------+\n    | plan_approval_resp   | <------- | plan_approval       |\n    | {approve: true}      |          | review: {req_id,    |\n    +---------------------+          |   approve: true}     |\n                                     +---------------------+\n\n    Trackers: {request_id: {\"target|from\": name, \"status\": \"pending|...\"}}\n\nKey insight: \"Same request_id correlation pattern, two domains.\"\n\"\"\"\n\nimport json\nimport os\nimport subprocess\nimport threading\nimport time\nimport uuid\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\nTEAM_DIR = WORKDIR / \".team\"\nINBOX_DIR = TEAM_DIR / \"inbox\"\n\nSYSTEM = f\"You are a team lead at {WORKDIR}. Manage teammates with shutdown and plan approval protocols.\"\n\nVALID_MSG_TYPES = {\n    \"message\",\n    \"broadcast\",\n    \"shutdown_request\",\n    \"shutdown_response\",\n    \"plan_approval_response\",\n}\n\n# -- Request trackers: correlate by request_id --\nshutdown_requests = {}\nplan_requests = {}\n_tracker_lock = threading.Lock()\n\n\n# -- MessageBus: JSONL inbox per teammate --\nclass MessageBus:\n    def __init__(self, inbox_dir: Path):\n        self.dir = inbox_dir\n        self.dir.mkdir(parents=True, exist_ok=True)\n\n    def send(self, sender: str, to: str, content: str,\n             msg_type: str = \"message\", extra: dict = None) -> str:\n        if msg_type not in VALID_MSG_TYPES:\n            return f\"Error: Invalid type '{msg_type}'. Valid: {VALID_MSG_TYPES}\"\n        msg = {\n            \"type\": msg_type,\n            \"from\": sender,\n            \"content\": content,\n            \"timestamp\": time.time(),\n        }\n        if extra:\n            msg.update(extra)\n        inbox_path = self.dir / f\"{to}.jsonl\"\n        with open(inbox_path, \"a\") as f:\n            f.write(json.dumps(msg) + \"\\n\")\n        return f\"Sent {msg_type} to {to}\"\n\n    def read_inbox(self, name: str) -> list:\n        inbox_path = self.dir / f\"{name}.jsonl\"\n        if not inbox_path.exists():\n            return []\n        messages = []\n        for line in inbox_path.read_text().strip().splitlines():\n            if line:\n                messages.append(json.loads(line))\n        inbox_path.write_text(\"\")\n        return messages\n\n    def broadcast(self, sender: str, content: str, teammates: list) -> str:\n        count = 0\n        for name in teammates:\n            if name != sender:\n                self.send(sender, name, content, \"broadcast\")\n                count += 1\n        return f\"Broadcast to {count} teammates\"\n\n\nBUS = MessageBus(INBOX_DIR)\n\n\n# -- TeammateManager with shutdown + plan approval --\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    def _load_config(self) -> dict:\n        if self.config_path.exists():\n            return json.loads(self.config_path.read_text())\n        return {\"team_name\": \"default\", \"members\": []}\n\n    def _save_config(self):\n        self.config_path.write_text(json.dumps(self.config, indent=2))\n\n    def _find_member(self, name: str) -> dict:\n        for m in self.config[\"members\"]:\n            if m[\"name\"] == name:\n                return m\n        return None\n\n    def spawn(self, name: str, role: str, prompt: str) -> str:\n        member = self._find_member(name)\n        if member:\n            if member[\"status\"] not in (\"idle\", \"shutdown\"):\n                return f\"Error: '{name}' is currently {member['status']}\"\n            member[\"status\"] = \"working\"\n            member[\"role\"] = role\n        else:\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),\n            daemon=True,\n        )\n        self.threads[name] = thread\n        thread.start()\n        return f\"Spawned '{name}' (role: {role})\"\n\n    def _teammate_loop(self, name: str, role: str, prompt: str):\n        sys_prompt = (\n            f\"You are '{name}', role: {role}, at {WORKDIR}. \"\n            f\"Submit plans via plan_approval before major work. \"\n            f\"Respond to shutdown_request with shutdown_response.\"\n        )\n        messages = [{\"role\": \"user\", \"content\": prompt}]\n        tools = self._teammate_tools()\n        should_exit = False\n        for _ in range(50):\n            inbox = BUS.read_inbox(name)\n            for msg in inbox:\n                messages.append({\"role\": \"user\", \"content\": json.dumps(msg)})\n            if should_exit:\n                break\n            try:\n                response = client.messages.create(\n                    model=MODEL,\n                    system=sys_prompt,\n                    messages=messages,\n                    tools=tools,\n                    max_tokens=8000,\n                )\n            except Exception:\n                break\n            messages.append({\"role\": \"assistant\", \"content\": response.content})\n            if response.stop_reason != \"tool_use\":\n                break\n            results = []\n            for block in response.content:\n                if block.type == \"tool_use\":\n                    output = self._exec(name, block.name, block.input)\n                    print(f\"  [{name}] {block.name}: {str(output)[:120]}\")\n                    results.append({\n                        \"type\": \"tool_result\",\n                        \"tool_use_id\": block.id,\n                        \"content\": str(output),\n                    })\n                    if block.name == \"shutdown_response\" and block.input.get(\"approve\"):\n                        should_exit = True\n            messages.append({\"role\": \"user\", \"content\": results})\n        member = self._find_member(name)\n        if member:\n            member[\"status\"] = \"shutdown\" if should_exit else \"idle\"\n            self._save_config()\n\n    def _exec(self, sender: str, tool_name: str, args: dict) -> str:\n        # these base tools are unchanged from s02\n        if tool_name == \"bash\":\n            return _run_bash(args[\"command\"])\n        if tool_name == \"read_file\":\n            return _run_read(args[\"path\"])\n        if tool_name == \"write_file\":\n            return _run_write(args[\"path\"], args[\"content\"])\n        if tool_name == \"edit_file\":\n            return _run_edit(args[\"path\"], args[\"old_text\"], args[\"new_text\"])\n        if tool_name == \"send_message\":\n            return BUS.send(sender, args[\"to\"], args[\"content\"], args.get(\"msg_type\", \"message\"))\n        if tool_name == \"read_inbox\":\n            return json.dumps(BUS.read_inbox(sender), indent=2)\n        if tool_name == \"shutdown_response\":\n            req_id = args[\"request_id\"]\n            approve = args[\"approve\"]\n            with _tracker_lock:\n                if req_id in shutdown_requests:\n                    shutdown_requests[req_id][\"status\"] = \"approved\" if approve else \"rejected\"\n            BUS.send(\n                sender, \"lead\", args.get(\"reason\", \"\"),\n                \"shutdown_response\", {\"request_id\": req_id, \"approve\": approve},\n            )\n            return f\"Shutdown {'approved' if approve else 'rejected'}\"\n        if tool_name == \"plan_approval\":\n            plan_text = args.get(\"plan\", \"\")\n            req_id = str(uuid.uuid4())[:8]\n            with _tracker_lock:\n                plan_requests[req_id] = {\"from\": sender, \"plan\": plan_text, \"status\": \"pending\"}\n            BUS.send(\n                sender, \"lead\", plan_text, \"plan_approval_response\",\n                {\"request_id\": req_id, \"plan\": plan_text},\n            )\n            return f\"Plan submitted (request_id={req_id}). Waiting for lead approval.\"\n        return f\"Unknown tool: {tool_name}\"\n\n    def _teammate_tools(self) -> list:\n        # these base tools are unchanged from s02\n        return [\n            {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n            {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}}, \"required\": [\"path\"]}},\n            {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n            {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n            {\"name\": \"send_message\", \"description\": \"Send message to a teammate.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"to\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}, \"msg_type\": {\"type\": \"string\", \"enum\": list(VALID_MSG_TYPES)}}, \"required\": [\"to\", \"content\"]}},\n            {\"name\": \"read_inbox\", \"description\": \"Read and drain your inbox.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n            {\"name\": \"shutdown_response\", \"description\": \"Respond to a shutdown request. Approve to shut down, reject to keep working.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"request_id\": {\"type\": \"string\"}, \"approve\": {\"type\": \"boolean\"}, \"reason\": {\"type\": \"string\"}}, \"required\": [\"request_id\", \"approve\"]}},\n            {\"name\": \"plan_approval\", \"description\": \"Submit a plan for lead approval. Provide plan text.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"plan\": {\"type\": \"string\"}}, \"required\": [\"plan\"]}},\n        ]\n\n    def list_all(self) -> str:\n        if not self.config[\"members\"]:\n            return \"No teammates.\"\n        lines = [f\"Team: {self.config['team_name']}\"]\n        for m in self.config[\"members\"]:\n            lines.append(f\"  {m['name']} ({m['role']}): {m['status']}\")\n        return \"\\n\".join(lines)\n\n    def member_names(self) -> list:\n        return [m[\"name\"] for m in self.config[\"members\"]]\n\n\nTEAM = TeammateManager(TEAM_DIR)\n\n\n# -- Base tool implementations (these base tools are unchanged from s02) --\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\n\ndef _run_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(\n            command, shell=True, cwd=WORKDIR,\n            capture_output=True, text=True, timeout=120,\n        )\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\n\ndef _run_read(path: str, limit: int = None) -> str:\n    try:\n        lines = _safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef _run_write(path: str, content: str) -> str:\n    try:\n        fp = _safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef _run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = _safe_path(path)\n        c = fp.read_text()\n        if old_text not in c:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(c.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\n# -- Lead-specific protocol handlers --\ndef handle_shutdown_request(teammate: str) -> str:\n    req_id = str(uuid.uuid4())[:8]\n    with _tracker_lock:\n        shutdown_requests[req_id] = {\"target\": teammate, \"status\": \"pending\"}\n    BUS.send(\n        \"lead\", teammate, \"Please shut down gracefully.\",\n        \"shutdown_request\", {\"request_id\": req_id},\n    )\n    return f\"Shutdown request {req_id} sent to '{teammate}' (status: pending)\"\n\n\ndef handle_plan_review(request_id: str, approve: bool, feedback: str = \"\") -> str:\n    with _tracker_lock:\n        req = plan_requests.get(request_id)\n    if not req:\n        return f\"Error: Unknown plan request_id '{request_id}'\"\n    with _tracker_lock:\n        req[\"status\"] = \"approved\" if approve else \"rejected\"\n    BUS.send(\n        \"lead\", req[\"from\"], feedback, \"plan_approval_response\",\n        {\"request_id\": request_id, \"approve\": approve, \"feedback\": feedback},\n    )\n    return f\"Plan {req['status']} for '{req['from']}'\"\n\n\ndef _check_shutdown_status(request_id: str) -> str:\n    with _tracker_lock:\n        return json.dumps(shutdown_requests.get(request_id, {\"error\": \"not found\"}))\n\n\n# -- Lead tool dispatch (12 tools) --\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\"], kw[\"new_text\"]),\n    \"spawn_teammate\":    lambda **kw: TEAM.spawn(kw[\"name\"], kw[\"role\"], kw[\"prompt\"]),\n    \"list_teammates\":    lambda **kw: TEAM.list_all(),\n    \"send_message\":      lambda **kw: BUS.send(\"lead\", kw[\"to\"], kw[\"content\"], kw.get(\"msg_type\", \"message\")),\n    \"read_inbox\":        lambda **kw: json.dumps(BUS.read_inbox(\"lead\"), indent=2),\n    \"broadcast\":         lambda **kw: BUS.broadcast(\"lead\", kw[\"content\"], TEAM.member_names()),\n    \"shutdown_request\":  lambda **kw: handle_shutdown_request(kw[\"teammate\"]),\n    \"shutdown_response\": lambda **kw: _check_shutdown_status(kw.get(\"request_id\", \"\")),\n    \"plan_approval\":     lambda **kw: handle_plan_review(kw[\"request_id\"], kw[\"approve\"], kw.get(\"feedback\", \"\")),\n}\n\n# these base tools are unchanged from s02\nTOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n    {\"name\": \"spawn_teammate\", \"description\": \"Spawn a persistent teammate.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}, \"role\": {\"type\": \"string\"}, \"prompt\": {\"type\": \"string\"}}, \"required\": [\"name\", \"role\", \"prompt\"]}},\n    {\"name\": \"list_teammates\", \"description\": \"List all teammates.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n    {\"name\": \"send_message\", \"description\": \"Send a message to a teammate.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"to\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}, \"msg_type\": {\"type\": \"string\", \"enum\": list(VALID_MSG_TYPES)}}, \"required\": [\"to\", \"content\"]}},\n    {\"name\": \"read_inbox\", \"description\": \"Read and drain the lead's inbox.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n    {\"name\": \"broadcast\", \"description\": \"Send a message to all teammates.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"content\": {\"type\": \"string\"}}, \"required\": [\"content\"]}},\n    {\"name\": \"shutdown_request\", \"description\": \"Request a teammate to shut down gracefully. Returns a request_id for tracking.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"teammate\": {\"type\": \"string\"}}, \"required\": [\"teammate\"]}},\n    {\"name\": \"shutdown_response\", \"description\": \"Check the status of a shutdown request by request_id.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"request_id\": {\"type\": \"string\"}}, \"required\": [\"request_id\"]}},\n    {\"name\": \"plan_approval\", \"description\": \"Approve or reject a teammate's plan. Provide request_id + approve + optional feedback.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"request_id\": {\"type\": \"string\"}, \"approve\": {\"type\": \"boolean\"}, \"feedback\": {\"type\": \"string\"}}, \"required\": [\"request_id\", \"approve\"]}},\n]\n\n\ndef agent_loop(messages: list):\n    while True:\n        inbox = BUS.read_inbox(\"lead\")\n        if inbox:\n            messages.append({\n                \"role\": \"user\",\n                \"content\": f\"<inbox>{json.dumps(inbox, indent=2)}</inbox>\",\n            })\n            messages.append({\n                \"role\": \"assistant\",\n                \"content\": \"Noted inbox messages.\",\n            })\n        response = client.messages.create(\n            model=MODEL,\n            system=SYSTEM,\n            messages=messages,\n            tools=TOOLS,\n            max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n        if response.stop_reason != \"tool_use\":\n            return\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                handler = TOOL_HANDLERS.get(block.name)\n                try:\n                    output = handler(**block.input) if handler else f\"Unknown tool: {block.name}\"\n                except Exception as e:\n                    output = f\"Error: {e}\"\n                print(f\"> {block.name}: {str(output)[:200]}\")\n                results.append({\n                    \"type\": \"tool_result\",\n                    \"tool_use_id\": block.id,\n                    \"content\": str(output),\n                })\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms10 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n        if query.strip() == \"/team\":\n            print(TEAM.list_all())\n            continue\n        if query.strip() == \"/inbox\":\n            print(json.dumps(BUS.read_inbox(\"lead\"), indent=2))\n            continue\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
+      "layer": "platform",
+      "source": "#!/usr/bin/env python3\n# Harness: protocols -- structured handshakes between models.\n\"\"\"\ns16_team_protocols.py - Team Protocols\n\nShutdown protocol and plan approval protocol, both using the same\nrequest_id correlation pattern. Builds on s15's mailbox-based team messaging.\n\n    Shutdown FSM: pending -> approved | rejected\n\n    Lead                              Teammate\n    +---------------------+          +---------------------+\n    | shutdown_request     |          |                     |\n    | {                    | -------> | receives request    |\n    |   request_id: abc    |          | decides: approve?   |\n    | }                    |          |                     |\n    +---------------------+          +---------------------+\n                                             |\n    +---------------------+          +-------v-------------+\n    | shutdown_response    | <------- | shutdown_response   |\n    | {                    |          | {                   |\n    |   request_id: abc    |          |   request_id: abc   |\n    |   approve: true      |          |   approve: true     |\n    | }                    |          | }                   |\n    +---------------------+          +---------------------+\n            |\n            v\n    status -> \"shutdown\", thread stops\n\n    Plan approval FSM: pending -> approved | rejected\n\n    Teammate                          Lead\n    +---------------------+          +---------------------+\n    | plan_approval        |          |                     |\n    | submit: {plan:\"...\"}| -------> | reviews plan text   |\n    +---------------------+          | approve/reject?     |\n                                     +---------------------+\n                                             |\n    +---------------------+          +-------v-------------+\n    | plan_approval_response| <------ | plan_approval       |\n    | {approve: true}      |          | review: {req_id,    |\n    +---------------------+          |   approve: true}     |\n                                     +---------------------+\n\n    Request store: .team/requests/{request_id}.json\n\nKey idea: one request/response shape can support multiple kinds of team workflow.\nProtocol requests are structured workflow objects, not normal free-form chat.\n\nRead this file in this order:\n1. MessageBus: how protocol envelopes still travel through the same inbox surface.\n2. Request files under .team/requests: how a request keeps durable status after the message is sent.\n3. Protocol handlers: how shutdown and plan approval reuse the same correlation pattern.\n\nMost common confusion:\n- a protocol request is not a normal teammate chat message\n- a request record is not a task record\n\nTeaching boundary:\nthis file teaches durable handshakes first.\nAutonomous claiming, task selection, and worktree assignment stay in later chapters.\n\"\"\"\n\nimport json\nimport os\nimport subprocess\nimport threading\nimport time\nimport uuid\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\nTEAM_DIR = WORKDIR / \".team\"\nINBOX_DIR = TEAM_DIR / \"inbox\"\nREQUESTS_DIR = TEAM_DIR / \"requests\"\n\nSYSTEM = f\"You are a team lead at {WORKDIR}. Manage teammates with shutdown and plan approval protocols.\"\n\nVALID_MSG_TYPES = {\n    \"message\",\n    \"broadcast\",\n    \"shutdown_request\",\n    \"shutdown_response\",\n    \"plan_approval\",\n    \"plan_approval_response\",\n}\n\n# -- MessageBus: JSONL inbox per teammate --\nclass MessageBus:\n    def __init__(self, inbox_dir: Path):\n        self.dir = inbox_dir\n        self.dir.mkdir(parents=True, exist_ok=True)\n\n    def send(self, sender: str, to: str, content: str,\n             msg_type: str = \"message\", extra: dict = None) -> str:\n        if msg_type not in VALID_MSG_TYPES:\n            return f\"Error: Invalid type '{msg_type}'. Valid: {VALID_MSG_TYPES}\"\n        msg = {\n            \"type\": msg_type,\n            \"from\": sender,\n            \"content\": content,\n            \"timestamp\": time.time(),\n        }\n        if extra:\n            msg.update(extra)\n        inbox_path = self.dir / f\"{to}.jsonl\"\n        with open(inbox_path, \"a\") as f:\n            f.write(json.dumps(msg) + \"\\n\")\n        return f\"Sent {msg_type} to {to}\"\n\n    def read_inbox(self, name: str) -> list:\n        inbox_path = self.dir / f\"{name}.jsonl\"\n        if not inbox_path.exists():\n            return []\n        messages = []\n        for line in inbox_path.read_text().strip().splitlines():\n            if line:\n                messages.append(json.loads(line))\n        inbox_path.write_text(\"\")\n        return messages\n\n    def broadcast(self, sender: str, content: str, teammates: list) -> str:\n        count = 0\n        for name in teammates:\n            if name != sender:\n                self.send(sender, name, content, \"broadcast\")\n                count += 1\n        return f\"Broadcast to {count} teammates\"\n\n\nBUS = MessageBus(INBOX_DIR)\n\n\nclass RequestStore:\n    \"\"\"\n    Durable request records for protocol workflows.\n\n    Protocol state should survive long enough to inspect, resume, or reconcile.\n    This store keeps one JSON file per request_id under .team/requests/.\n    \"\"\"\n\n    def __init__(self, base_dir: Path):\n        self.dir = base_dir\n        self.dir.mkdir(parents=True, exist_ok=True)\n        self._lock = threading.Lock()\n\n    def _path(self, request_id: str) -> Path:\n        return self.dir / f\"{request_id}.json\"\n\n    def create(self, record: dict) -> dict:\n        request_id = record[\"request_id\"]\n        with self._lock:\n            self._path(request_id).write_text(json.dumps(record, indent=2))\n        return record\n\n    def get(self, request_id: str) -> dict | None:\n        path = self._path(request_id)\n        if not path.exists():\n            return None\n        return json.loads(path.read_text())\n\n    def update(self, request_id: str, **changes) -> dict | None:\n        with self._lock:\n            record = self.get(request_id)\n            if not record:\n                return None\n            record.update(changes)\n            record[\"updated_at\"] = time.time()\n            self._path(request_id).write_text(json.dumps(record, indent=2))\n        return record\n\n\nREQUEST_STORE = RequestStore(REQUESTS_DIR)\n\n\n# -- TeammateManager with shutdown + plan approval --\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    def _load_config(self) -> dict:\n        if self.config_path.exists():\n            return json.loads(self.config_path.read_text())\n        return {\"team_name\": \"default\", \"members\": []}\n\n    def _save_config(self):\n        self.config_path.write_text(json.dumps(self.config, indent=2))\n\n    def _find_member(self, name: str) -> dict:\n        for m in self.config[\"members\"]:\n            if m[\"name\"] == name:\n                return m\n        return None\n\n    def spawn(self, name: str, role: str, prompt: str) -> str:\n        member = self._find_member(name)\n        if member:\n            if member[\"status\"] not in (\"idle\", \"shutdown\"):\n                return f\"Error: '{name}' is currently {member['status']}\"\n            member[\"status\"] = \"working\"\n            member[\"role\"] = role\n        else:\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),\n            daemon=True,\n        )\n        self.threads[name] = thread\n        thread.start()\n        return f\"Spawned '{name}' (role: {role})\"\n\n    def _teammate_loop(self, name: str, role: str, prompt: str):\n        sys_prompt = (\n            f\"You are '{name}', role: {role}, at {WORKDIR}. \"\n            f\"Submit plans via plan_approval before major work. \"\n            f\"Respond to shutdown_request with shutdown_response.\"\n        )\n        messages = [{\"role\": \"user\", \"content\": prompt}]\n        tools = self._teammate_tools()\n        should_exit = False\n        for _ in range(50):\n            inbox = BUS.read_inbox(name)\n            for msg in inbox:\n                messages.append({\"role\": \"user\", \"content\": json.dumps(msg)})\n            if should_exit:\n                break\n            try:\n                response = client.messages.create(\n                    model=MODEL,\n                    system=sys_prompt,\n                    messages=messages,\n                    tools=tools,\n                    max_tokens=8000,\n                )\n            except Exception:\n                break\n            messages.append({\"role\": \"assistant\", \"content\": response.content})\n            if response.stop_reason != \"tool_use\":\n                break\n            results = []\n            for block in response.content:\n                if block.type == \"tool_use\":\n                    output = self._exec(name, block.name, block.input)\n                    print(f\"  [{name}] {block.name}: {str(output)[:120]}\")\n                    results.append({\n                        \"type\": \"tool_result\",\n                        \"tool_use_id\": block.id,\n                        \"content\": str(output),\n                    })\n                    if block.name == \"shutdown_response\" and block.input.get(\"approve\"):\n                        should_exit = True\n            messages.append({\"role\": \"user\", \"content\": results})\n        member = self._find_member(name)\n        if member:\n            member[\"status\"] = \"shutdown\" if should_exit else \"idle\"\n            self._save_config()\n\n    def _exec(self, sender: str, tool_name: str, args: dict) -> str:\n        # these base tools are unchanged from s02\n        if tool_name == \"bash\":\n            return _run_bash(args[\"command\"])\n        if tool_name == \"read_file\":\n            return _run_read(args[\"path\"])\n        if tool_name == \"write_file\":\n            return _run_write(args[\"path\"], args[\"content\"])\n        if tool_name == \"edit_file\":\n            return _run_edit(args[\"path\"], args[\"old_text\"], args[\"new_text\"])\n        if tool_name == \"send_message\":\n            return BUS.send(sender, args[\"to\"], args[\"content\"], args.get(\"msg_type\", \"message\"))\n        if tool_name == \"read_inbox\":\n            return json.dumps(BUS.read_inbox(sender), indent=2)\n        if tool_name == \"shutdown_response\":\n            req_id = args[\"request_id\"]\n            approve = args[\"approve\"]\n            updated = REQUEST_STORE.update(\n                req_id,\n                status=\"approved\" if approve else \"rejected\",\n                resolved_by=sender,\n                resolved_at=time.time(),\n                response={\"approve\": approve, \"reason\": args.get(\"reason\", \"\")},\n            )\n            if not updated:\n                return f\"Error: Unknown shutdown request {req_id}\"\n            BUS.send(\n                sender, \"lead\", args.get(\"reason\", \"\"),\n                \"shutdown_response\", {\"request_id\": req_id, \"approve\": approve},\n            )\n            return f\"Shutdown {'approved' if approve else 'rejected'}\"\n        if tool_name == \"plan_approval\":\n            plan_text = args.get(\"plan\", \"\")\n            req_id = str(uuid.uuid4())[:8]\n            REQUEST_STORE.create({\n                \"request_id\": req_id,\n                \"kind\": \"plan_approval\",\n                \"from\": sender,\n                \"to\": \"lead\",\n                \"status\": \"pending\",\n                \"plan\": plan_text,\n                \"created_at\": time.time(),\n                \"updated_at\": time.time(),\n            })\n            BUS.send(\n                sender, \"lead\", plan_text, \"plan_approval\",\n                {\"request_id\": req_id, \"plan\": plan_text},\n            )\n            return f\"Plan submitted (request_id={req_id}). Waiting for lead approval.\"\n        return f\"Unknown tool: {tool_name}\"\n\n    def _teammate_tools(self) -> list:\n        # these base tools are unchanged from s02\n        return [\n            {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n            {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}}, \"required\": [\"path\"]}},\n            {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n            {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n            {\"name\": \"send_message\", \"description\": \"Send message to a teammate.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"to\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}, \"msg_type\": {\"type\": \"string\", \"enum\": list(VALID_MSG_TYPES)}}, \"required\": [\"to\", \"content\"]}},\n            {\"name\": \"read_inbox\", \"description\": \"Read and drain your inbox.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n            {\"name\": \"shutdown_response\", \"description\": \"Respond to a shutdown request. Approve to shut down, reject to keep working.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"request_id\": {\"type\": \"string\"}, \"approve\": {\"type\": \"boolean\"}, \"reason\": {\"type\": \"string\"}}, \"required\": [\"request_id\", \"approve\"]}},\n            {\"name\": \"plan_approval\", \"description\": \"Submit a plan for lead approval. Provide plan text.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"plan\": {\"type\": \"string\"}}, \"required\": [\"plan\"]}},\n        ]\n\n    def list_all(self) -> str:\n        if not self.config[\"members\"]:\n            return \"No teammates.\"\n        lines = [f\"Team: {self.config['team_name']}\"]\n        for m in self.config[\"members\"]:\n            lines.append(f\"  {m['name']} ({m['role']}): {m['status']}\")\n        return \"\\n\".join(lines)\n\n    def member_names(self) -> list:\n        return [m[\"name\"] for m in self.config[\"members\"]]\n\n\nTEAM = TeammateManager(TEAM_DIR)\n\n\n# -- Base tool implementations (these base tools are unchanged from s02) --\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\n\ndef _run_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(\n            command, shell=True, cwd=WORKDIR,\n            capture_output=True, text=True, timeout=120,\n        )\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\n\ndef _run_read(path: str, limit: int = None) -> str:\n    try:\n        lines = _safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef _run_write(path: str, content: str) -> str:\n    try:\n        fp = _safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef _run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = _safe_path(path)\n        c = fp.read_text()\n        if old_text not in c:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(c.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\n# -- Lead-specific protocol handlers --\ndef handle_shutdown_request(teammate: str) -> str:\n    req_id = str(uuid.uuid4())[:8]\n    REQUEST_STORE.create({\n        \"request_id\": req_id,\n        \"kind\": \"shutdown\",\n        \"from\": \"lead\",\n        \"to\": teammate,\n        \"status\": \"pending\",\n        \"created_at\": time.time(),\n        \"updated_at\": time.time(),\n    })\n    BUS.send(\n        \"lead\", teammate, \"Please shut down gracefully.\",\n        \"shutdown_request\", {\"request_id\": req_id},\n    )\n    return f\"Shutdown request {req_id} sent to '{teammate}' (status: pending)\"\n\n\ndef handle_plan_review(request_id: str, approve: bool, feedback: str = \"\") -> str:\n    req = REQUEST_STORE.get(request_id)\n    if not req:\n        return f\"Error: Unknown plan request_id '{request_id}'\"\n    REQUEST_STORE.update(\n        request_id,\n        status=\"approved\" if approve else \"rejected\",\n        reviewed_by=\"lead\",\n        resolved_at=time.time(),\n        feedback=feedback,\n    )\n    BUS.send(\n        \"lead\", req[\"from\"], feedback, \"plan_approval_response\",\n        {\"request_id\": request_id, \"approve\": approve, \"feedback\": feedback},\n    )\n    return f\"Plan {'approved' if approve else 'rejected'} for '{req['from']}'\"\n\n\ndef _check_shutdown_status(request_id: str) -> str:\n    return json.dumps(REQUEST_STORE.get(request_id) or {\"error\": \"not found\"})\n\n\n# -- Lead tool dispatch (12 tools) --\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\"], kw[\"new_text\"]),\n    \"spawn_teammate\":    lambda **kw: TEAM.spawn(kw[\"name\"], kw[\"role\"], kw[\"prompt\"]),\n    \"list_teammates\":    lambda **kw: TEAM.list_all(),\n    \"send_message\":      lambda **kw: BUS.send(\"lead\", kw[\"to\"], kw[\"content\"], kw.get(\"msg_type\", \"message\")),\n    \"read_inbox\":        lambda **kw: json.dumps(BUS.read_inbox(\"lead\"), indent=2),\n    \"broadcast\":         lambda **kw: BUS.broadcast(\"lead\", kw[\"content\"], TEAM.member_names()),\n    \"shutdown_request\":  lambda **kw: handle_shutdown_request(kw[\"teammate\"]),\n    \"shutdown_response\": lambda **kw: _check_shutdown_status(kw.get(\"request_id\", \"\")),\n    \"plan_approval\":     lambda **kw: handle_plan_review(kw[\"request_id\"], kw[\"approve\"], kw.get(\"feedback\", \"\")),\n}\n\n# these base tools are unchanged from s02\nTOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n    {\"name\": \"spawn_teammate\", \"description\": \"Spawn a persistent teammate.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}, \"role\": {\"type\": \"string\"}, \"prompt\": {\"type\": \"string\"}}, \"required\": [\"name\", \"role\", \"prompt\"]}},\n    {\"name\": \"list_teammates\", \"description\": \"List all teammates.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n    {\"name\": \"send_message\", \"description\": \"Send a message to a teammate.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"to\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}, \"msg_type\": {\"type\": \"string\", \"enum\": list(VALID_MSG_TYPES)}}, \"required\": [\"to\", \"content\"]}},\n    {\"name\": \"read_inbox\", \"description\": \"Read and drain the lead's inbox.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n    {\"name\": \"broadcast\", \"description\": \"Send a message to all teammates.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"content\": {\"type\": \"string\"}}, \"required\": [\"content\"]}},\n    {\"name\": \"shutdown_request\", \"description\": \"Request a teammate to shut down gracefully. Returns a request_id for tracking.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"teammate\": {\"type\": \"string\"}}, \"required\": [\"teammate\"]}},\n    {\"name\": \"shutdown_response\", \"description\": \"Check the status of a shutdown request by request_id.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"request_id\": {\"type\": \"string\"}}, \"required\": [\"request_id\"]}},\n    {\"name\": \"plan_approval\", \"description\": \"Approve or reject a teammate's plan. Provide request_id + approve + optional feedback.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"request_id\": {\"type\": \"string\"}, \"approve\": {\"type\": \"boolean\"}, \"feedback\": {\"type\": \"string\"}}, \"required\": [\"request_id\", \"approve\"]}},\n]\n\n\ndef agent_loop(messages: list):\n    while True:\n        inbox = BUS.read_inbox(\"lead\")\n        if inbox:\n            messages.append({\n                \"role\": \"user\",\n                \"content\": f\"<inbox>{json.dumps(inbox, indent=2)}</inbox>\",\n            })\n        response = client.messages.create(\n            model=MODEL,\n            system=SYSTEM,\n            messages=messages,\n            tools=TOOLS,\n            max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n        if response.stop_reason != \"tool_use\":\n            return\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                handler = TOOL_HANDLERS.get(block.name)\n                try:\n                    output = handler(**block.input) if handler else f\"Unknown tool: {block.name}\"\n                except Exception as e:\n                    output = f\"Error: {e}\"\n                print(f\"> {block.name}:\")\n                print(str(output)[:200])\n                results.append({\n                    \"type\": \"tool_result\",\n                    \"tool_use_id\": block.id,\n                    \"content\": str(output),\n                })\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms16 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n        if query.strip() == \"/team\":\n            print(TEAM.list_all())\n            continue\n        if query.strip() == \"/inbox\":\n            print(json.dumps(BUS.read_inbox(\"lead\"), indent=2))\n            continue\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
     },
     {
-      "id": "s11",
-      "filename": "s11_autonomous_agents.py",
+      "id": "s17",
+      "filename": "s17_autonomous_agents.py",
       "title": "Autonomous Agents",
-      "subtitle": "Scan Board, Claim Tasks",
-      "loc": 499,
+      "subtitle": "Self-Claim and Self-Resume",
+      "loc": 603,
       "tools": [
         "bash",
         "read_file",
@@ -651,91 +1170,111 @@
         "idle",
         "claim_task"
       ],
-      "coreAddition": "Task board polling + timeout-based self-governance",
-      "keyInsight": "Teammates scan the board and claim tasks themselves; no need for the lead to assign each one",
+      "coreAddition": "Idle polling + role-aware self-claim + resume context",
+      "keyInsight": "Autonomy is a bounded mechanism -- idle, scan, claim, resume -- not magic.",
       "classes": [
         {
           "name": "MessageBus",
-          "startLine": 80,
-          "endLine": 121
+          "startLine": 84,
+          "endLine": 125
+        },
+        {
+          "name": "RequestStore",
+          "startLine": 129,
+          "endLine": 167
         },
         {
           "name": "TeammateManager",
-          "startLine": 159,
-          "endLine": 368
+          "startLine": 249,
+          "endLine": 480
         }
       ],
       "functions": [
         {
-          "name": "scan_unclaimed_tasks",
-          "signature": "def scan_unclaimed_tasks()",
-          "startLine": 126
+          "name": "_append_claim_event",
+          "signature": "def _append_claim_event(payload: dict)",
+          "startLine": 172
+        },
+        {
+          "name": "_task_allows_role",
+          "signature": "def _task_allows_role(task: dict, role: str | None)",
+          "startLine": 178
+        },
+        {
+          "name": "is_claimable_task",
+          "signature": "def is_claimable_task(task: dict, role: str | None = None)",
+          "startLine": 185
         },
         {
-          "name": "claim_task",
-          "signature": "def claim_task(task_id: int, owner: str)",
-          "startLine": 138
+          "name": "scan_unclaimed_tasks",
+          "signature": "def scan_unclaimed_tasks(role: str | None = None)",
+          "startLine": 194
         },
         {
           "name": "make_identity_block",
           "signature": "def make_identity_block(name: str, role: str, team_name: str)",
-          "startLine": 151
+          "startLine": 234
+        },
+        {
+          "name": "ensure_identity_context",
+          "signature": "def ensure_identity_context(messages: list, name: str, role: str, team_name: str)",
+          "startLine": 241
         },
         {
           "name": "_safe_path",
           "signature": "def _safe_path(p: str)",
-          "startLine": 373
+          "startLine": 485
         },
         {
           "name": "_run_bash",
           "signature": "def _run_bash(command: str)",
-          "startLine": 380
+          "startLine": 492
         },
         {
           "name": "_run_read",
           "signature": "def _run_read(path: str, limit: int = None)",
-          "startLine": 395
+          "startLine": 507
         },
         {
           "name": "_run_write",
           "signature": "def _run_write(path: str, content: str)",
-          "startLine": 405
+          "startLine": 517
         },
         {
           "name": "_run_edit",
           "signature": "def _run_edit(path: str, old_text: str, new_text: str)",
-          "startLine": 415
+          "startLine": 527
         },
         {
           "name": "handle_shutdown_request",
           "signature": "def handle_shutdown_request(teammate: str)",
-          "startLine": 428
+          "startLine": 540
         },
         {
           "name": "handle_plan_review",
           "signature": "def handle_plan_review(request_id: str, approve: bool, feedback: str = \"\")",
-          "startLine": 439
+          "startLine": 558
         },
         {
           "name": "_check_shutdown_status",
           "signature": "def _check_shutdown_status(request_id: str)",
-          "startLine": 453
+          "startLine": 576
         },
         {
           "name": "agent_loop",
           "signature": "def agent_loop(messages: list)",
-          "startLine": 509
+          "startLine": 631
         }
       ],
-      "layer": "collaboration",
-      "source": "#!/usr/bin/env python3\n\"\"\"\ns11_autonomous_agents.py - Autonomous Agents\n\nIdle cycle with task board polling, auto-claiming unclaimed tasks, and\nidentity re-injection after context compression. Builds on s10's protocols.\n\n    Teammate lifecycle:\n    +-------+\n    | spawn |\n    +---+---+\n        |\n        v\n    +-------+  tool_use    +-------+\n    | WORK  | <----------- |  LLM  |\n    +---+---+              +-------+\n        |\n        | stop_reason != tool_use\n        v\n    +--------+\n    | IDLE   | poll every 5s for up to 60s\n    +---+----+\n        |\n        +---> check inbox -> message? -> resume WORK\n        |\n        +---> scan .tasks/ -> unclaimed? -> claim -> resume WORK\n        |\n        +---> timeout (60s) -> shutdown\n\n    Identity re-injection after compression:\n    messages = [identity_block, ...remaining...]\n    \"You are 'coder', role: backend, team: my-team\"\n\nKey insight: \"The agent finds work itself.\"\n\"\"\"\n\nimport json\nimport os\nimport subprocess\nimport threading\nimport time\nimport uuid\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\nTEAM_DIR = WORKDIR / \".team\"\nINBOX_DIR = TEAM_DIR / \"inbox\"\nTASKS_DIR = WORKDIR / \".tasks\"\n\nPOLL_INTERVAL = 5\nIDLE_TIMEOUT = 60\n\nSYSTEM = f\"You are a team lead at {WORKDIR}. Teammates are autonomous -- they find work themselves.\"\n\nVALID_MSG_TYPES = {\n    \"message\",\n    \"broadcast\",\n    \"shutdown_request\",\n    \"shutdown_response\",\n    \"plan_approval_response\",\n}\n\n# -- Request trackers --\nshutdown_requests = {}\nplan_requests = {}\n_tracker_lock = threading.Lock()\n_claim_lock = threading.Lock()\n\n\n# -- MessageBus: JSONL inbox per teammate --\nclass MessageBus:\n    def __init__(self, inbox_dir: Path):\n        self.dir = inbox_dir\n        self.dir.mkdir(parents=True, exist_ok=True)\n\n    def send(self, sender: str, to: str, content: str,\n             msg_type: str = \"message\", extra: dict = None) -> str:\n        if msg_type not in VALID_MSG_TYPES:\n            return f\"Error: Invalid type '{msg_type}'. Valid: {VALID_MSG_TYPES}\"\n        msg = {\n            \"type\": msg_type,\n            \"from\": sender,\n            \"content\": content,\n            \"timestamp\": time.time(),\n        }\n        if extra:\n            msg.update(extra)\n        inbox_path = self.dir / f\"{to}.jsonl\"\n        with open(inbox_path, \"a\") as f:\n            f.write(json.dumps(msg) + \"\\n\")\n        return f\"Sent {msg_type} to {to}\"\n\n    def read_inbox(self, name: str) -> list:\n        inbox_path = self.dir / f\"{name}.jsonl\"\n        if not inbox_path.exists():\n            return []\n        messages = []\n        for line in inbox_path.read_text().strip().splitlines():\n            if line:\n                messages.append(json.loads(line))\n        inbox_path.write_text(\"\")\n        return messages\n\n    def broadcast(self, sender: str, content: str, teammates: list) -> str:\n        count = 0\n        for name in teammates:\n            if name != sender:\n                self.send(sender, name, content, \"broadcast\")\n                count += 1\n        return f\"Broadcast to {count} teammates\"\n\n\nBUS = MessageBus(INBOX_DIR)\n\n\n# -- Task board scanning --\ndef scan_unclaimed_tasks() -> list:\n    TASKS_DIR.mkdir(exist_ok=True)\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\ndef claim_task(task_id: int, owner: str) -> str:\n    with _claim_lock:\n        path = TASKS_DIR / f\"task_{task_id}.json\"\n        if not path.exists():\n            return f\"Error: Task {task_id} not found\"\n        task = json.loads(path.read_text())\n        task[\"owner\"] = owner\n        task[\"status\"] = \"in_progress\"\n        path.write_text(json.dumps(task, indent=2))\n    return f\"Claimed task #{task_id} for {owner}\"\n\n\n# -- Identity re-injection after compression --\ndef make_identity_block(name: str, role: str, team_name: str) -> dict:\n    return {\n        \"role\": \"user\",\n        \"content\": f\"<identity>You are '{name}', role: {role}, team: {team_name}. Continue your work.</identity>\",\n    }\n\n\n# -- Autonomous TeammateManager --\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    def _load_config(self) -> dict:\n        if self.config_path.exists():\n            return json.loads(self.config_path.read_text())\n        return {\"team_name\": \"default\", \"members\": []}\n\n    def _save_config(self):\n        self.config_path.write_text(json.dumps(self.config, indent=2))\n\n    def _find_member(self, name: str) -> dict:\n        for m in self.config[\"members\"]:\n            if m[\"name\"] == name:\n                return m\n        return None\n\n    def _set_status(self, name: str, status: str):\n        member = self._find_member(name)\n        if member:\n            member[\"status\"] = status\n            self._save_config()\n\n    def spawn(self, name: str, role: str, prompt: str) -> str:\n        member = self._find_member(name)\n        if member:\n            if member[\"status\"] not in (\"idle\", \"shutdown\"):\n                return f\"Error: '{name}' is currently {member['status']}\"\n            member[\"status\"] = \"working\"\n            member[\"role\"] = role\n        else:\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._loop,\n            args=(name, role, prompt),\n            daemon=True,\n        )\n        self.threads[name] = thread\n        thread.start()\n        return f\"Spawned '{name}' (role: {role})\"\n\n    def _loop(self, name: str, role: str, prompt: str):\n        team_name = self.config[\"team_name\"]\n        sys_prompt = (\n            f\"You are '{name}', role: {role}, team: {team_name}, at {WORKDIR}. \"\n            f\"Use idle tool when you have no more work. You will auto-claim new tasks.\"\n        )\n        messages = [{\"role\": \"user\", \"content\": prompt}]\n        tools = self._teammate_tools()\n\n        while True:\n            # -- WORK PHASE: standard agent loop --\n            for _ in range(50):\n                inbox = BUS.read_inbox(name)\n                for msg in inbox:\n                    if msg.get(\"type\") == \"shutdown_request\":\n                        self._set_status(name, \"shutdown\")\n                        return\n                    messages.append({\"role\": \"user\", \"content\": json.dumps(msg)})\n                try:\n                    response = client.messages.create(\n                        model=MODEL,\n                        system=sys_prompt,\n                        messages=messages,\n                        tools=tools,\n                        max_tokens=8000,\n                    )\n                except Exception:\n                    self._set_status(name, \"idle\")\n                    return\n                messages.append({\"role\": \"assistant\", \"content\": response.content})\n                if response.stop_reason != \"tool_use\":\n                    break\n                results = []\n                idle_requested = False\n                for block in response.content:\n                    if block.type == \"tool_use\":\n                        if block.name == \"idle\":\n                            idle_requested = True\n                            output = \"Entering idle phase. Will poll for new tasks.\"\n                        else:\n                            output = self._exec(name, block.name, block.input)\n                        print(f\"  [{name}] {block.name}: {str(output)[:120]}\")\n                        results.append({\n                            \"type\": \"tool_result\",\n                            \"tool_use_id\": block.id,\n                            \"content\": str(output),\n                        })\n                messages.append({\"role\": \"user\", \"content\": results})\n                if idle_requested:\n                    break\n\n            # -- IDLE PHASE: poll for inbox messages and unclaimed tasks --\n            self._set_status(name, \"idle\")\n            resume = False\n            polls = IDLE_TIMEOUT // max(POLL_INTERVAL, 1)\n            for _ in range(polls):\n                time.sleep(POLL_INTERVAL)\n                inbox = BUS.read_inbox(name)\n                if inbox:\n                    for msg in inbox:\n                        if msg.get(\"type\") == \"shutdown_request\":\n                            self._set_status(name, \"shutdown\")\n                            return\n                        messages.append({\"role\": \"user\", \"content\": json.dumps(msg)})\n                    resume = True\n                    break\n                unclaimed = scan_unclaimed_tasks()\n                if unclaimed:\n                    task = unclaimed[0]\n                    claim_task(task[\"id\"], name)\n                    task_prompt = (\n                        f\"<auto-claimed>Task #{task['id']}: {task['subject']}\\n\"\n                        f\"{task.get('description', '')}</auto-claimed>\"\n                    )\n                    if len(messages) <= 3:\n                        messages.insert(0, make_identity_block(name, role, team_name))\n                        messages.insert(1, {\"role\": \"assistant\", \"content\": f\"I am {name}. Continuing.\"})\n                    messages.append({\"role\": \"user\", \"content\": task_prompt})\n                    messages.append({\"role\": \"assistant\", \"content\": f\"Claimed task #{task['id']}. Working on it.\"})\n                    resume = True\n                    break\n\n            if not resume:\n                self._set_status(name, \"shutdown\")\n                return\n            self._set_status(name, \"working\")\n\n    def _exec(self, sender: str, tool_name: str, args: dict) -> str:\n        # these base tools are unchanged from s02\n        if tool_name == \"bash\":\n            return _run_bash(args[\"command\"])\n        if tool_name == \"read_file\":\n            return _run_read(args[\"path\"])\n        if tool_name == \"write_file\":\n            return _run_write(args[\"path\"], args[\"content\"])\n        if tool_name == \"edit_file\":\n            return _run_edit(args[\"path\"], args[\"old_text\"], args[\"new_text\"])\n        if tool_name == \"send_message\":\n            return BUS.send(sender, args[\"to\"], args[\"content\"], args.get(\"msg_type\", \"message\"))\n        if tool_name == \"read_inbox\":\n            return json.dumps(BUS.read_inbox(sender), indent=2)\n        if tool_name == \"shutdown_response\":\n            req_id = args[\"request_id\"]\n            with _tracker_lock:\n                if req_id in shutdown_requests:\n                    shutdown_requests[req_id][\"status\"] = \"approved\" if args[\"approve\"] else \"rejected\"\n            BUS.send(\n                sender, \"lead\", args.get(\"reason\", \"\"),\n                \"shutdown_response\", {\"request_id\": req_id, \"approve\": args[\"approve\"]},\n            )\n            return f\"Shutdown {'approved' if args['approve'] else 'rejected'}\"\n        if tool_name == \"plan_approval\":\n            plan_text = args.get(\"plan\", \"\")\n            req_id = str(uuid.uuid4())[:8]\n            with _tracker_lock:\n                plan_requests[req_id] = {\"from\": sender, \"plan\": plan_text, \"status\": \"pending\"}\n            BUS.send(\n                sender, \"lead\", plan_text, \"plan_approval_response\",\n                {\"request_id\": req_id, \"plan\": plan_text},\n            )\n            return f\"Plan submitted (request_id={req_id}). Waiting for approval.\"\n        if tool_name == \"claim_task\":\n            return claim_task(args[\"task_id\"], sender)\n        return f\"Unknown tool: {tool_name}\"\n\n    def _teammate_tools(self) -> list:\n        # these base tools are unchanged from s02\n        return [\n            {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n            {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}}, \"required\": [\"path\"]}},\n            {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n            {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n            {\"name\": \"send_message\", \"description\": \"Send message to a teammate.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"to\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}, \"msg_type\": {\"type\": \"string\", \"enum\": list(VALID_MSG_TYPES)}}, \"required\": [\"to\", \"content\"]}},\n            {\"name\": \"read_inbox\", \"description\": \"Read and drain your inbox.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n            {\"name\": \"shutdown_response\", \"description\": \"Respond to a shutdown request.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"request_id\": {\"type\": \"string\"}, \"approve\": {\"type\": \"boolean\"}, \"reason\": {\"type\": \"string\"}}, \"required\": [\"request_id\", \"approve\"]}},\n            {\"name\": \"plan_approval\", \"description\": \"Submit a plan for lead approval.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"plan\": {\"type\": \"string\"}}, \"required\": [\"plan\"]}},\n            {\"name\": \"idle\", \"description\": \"Signal that you have no more work. Enters idle polling phase.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n            {\"name\": \"claim_task\", \"description\": \"Claim a task from the task board by ID.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"task_id\": {\"type\": \"integer\"}}, \"required\": [\"task_id\"]}},\n        ]\n\n    def list_all(self) -> str:\n        if not self.config[\"members\"]:\n            return \"No teammates.\"\n        lines = [f\"Team: {self.config['team_name']}\"]\n        for m in self.config[\"members\"]:\n            lines.append(f\"  {m['name']} ({m['role']}): {m['status']}\")\n        return \"\\n\".join(lines)\n\n    def member_names(self) -> list:\n        return [m[\"name\"] for m in self.config[\"members\"]]\n\n\nTEAM = TeammateManager(TEAM_DIR)\n\n\n# -- Base tool implementations (these base tools are unchanged from s02) --\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\n\ndef _run_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(\n            command, shell=True, cwd=WORKDIR,\n            capture_output=True, text=True, timeout=120,\n        )\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\n\ndef _run_read(path: str, limit: int = None) -> str:\n    try:\n        lines = _safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef _run_write(path: str, content: str) -> str:\n    try:\n        fp = _safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef _run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = _safe_path(path)\n        c = fp.read_text()\n        if old_text not in c:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(c.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\n# -- Lead-specific protocol handlers --\ndef handle_shutdown_request(teammate: str) -> str:\n    req_id = str(uuid.uuid4())[:8]\n    with _tracker_lock:\n        shutdown_requests[req_id] = {\"target\": teammate, \"status\": \"pending\"}\n    BUS.send(\n        \"lead\", teammate, \"Please shut down gracefully.\",\n        \"shutdown_request\", {\"request_id\": req_id},\n    )\n    return f\"Shutdown request {req_id} sent to '{teammate}'\"\n\n\ndef handle_plan_review(request_id: str, approve: bool, feedback: str = \"\") -> str:\n    with _tracker_lock:\n        req = plan_requests.get(request_id)\n    if not req:\n        return f\"Error: Unknown plan request_id '{request_id}'\"\n    with _tracker_lock:\n        req[\"status\"] = \"approved\" if approve else \"rejected\"\n    BUS.send(\n        \"lead\", req[\"from\"], feedback, \"plan_approval_response\",\n        {\"request_id\": request_id, \"approve\": approve, \"feedback\": feedback},\n    )\n    return f\"Plan {req['status']} for '{req['from']}'\"\n\n\ndef _check_shutdown_status(request_id: str) -> str:\n    with _tracker_lock:\n        return json.dumps(shutdown_requests.get(request_id, {\"error\": \"not found\"}))\n\n\n# -- Lead tool dispatch (14 tools) --\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\"], kw[\"new_text\"]),\n    \"spawn_teammate\":    lambda **kw: TEAM.spawn(kw[\"name\"], kw[\"role\"], kw[\"prompt\"]),\n    \"list_teammates\":    lambda **kw: TEAM.list_all(),\n    \"send_message\":      lambda **kw: BUS.send(\"lead\", kw[\"to\"], kw[\"content\"], kw.get(\"msg_type\", \"message\")),\n    \"read_inbox\":        lambda **kw: json.dumps(BUS.read_inbox(\"lead\"), indent=2),\n    \"broadcast\":         lambda **kw: BUS.broadcast(\"lead\", kw[\"content\"], TEAM.member_names()),\n    \"shutdown_request\":  lambda **kw: handle_shutdown_request(kw[\"teammate\"]),\n    \"shutdown_response\": lambda **kw: _check_shutdown_status(kw.get(\"request_id\", \"\")),\n    \"plan_approval\":     lambda **kw: handle_plan_review(kw[\"request_id\"], kw[\"approve\"], kw.get(\"feedback\", \"\")),\n    \"idle\":              lambda **kw: \"Lead does not idle.\",\n    \"claim_task\":        lambda **kw: claim_task(kw[\"task_id\"], \"lead\"),\n}\n\n# these base tools are unchanged from s02\nTOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n    {\"name\": \"spawn_teammate\", \"description\": \"Spawn an autonomous teammate.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}, \"role\": {\"type\": \"string\"}, \"prompt\": {\"type\": \"string\"}}, \"required\": [\"name\", \"role\", \"prompt\"]}},\n    {\"name\": \"list_teammates\", \"description\": \"List all teammates.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n    {\"name\": \"send_message\", \"description\": \"Send a message to a teammate.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"to\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}, \"msg_type\": {\"type\": \"string\", \"enum\": list(VALID_MSG_TYPES)}}, \"required\": [\"to\", \"content\"]}},\n    {\"name\": \"read_inbox\", \"description\": \"Read and drain the lead's inbox.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n    {\"name\": \"broadcast\", \"description\": \"Send a message to all teammates.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"content\": {\"type\": \"string\"}}, \"required\": [\"content\"]}},\n    {\"name\": \"shutdown_request\", \"description\": \"Request a teammate to shut down.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"teammate\": {\"type\": \"string\"}}, \"required\": [\"teammate\"]}},\n    {\"name\": \"shutdown_response\", \"description\": \"Check shutdown request status.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"request_id\": {\"type\": \"string\"}}, \"required\": [\"request_id\"]}},\n    {\"name\": \"plan_approval\", \"description\": \"Approve or reject a teammate's plan.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"request_id\": {\"type\": \"string\"}, \"approve\": {\"type\": \"boolean\"}, \"feedback\": {\"type\": \"string\"}}, \"required\": [\"request_id\", \"approve\"]}},\n    {\"name\": \"idle\", \"description\": \"Enter idle state (for lead -- rarely used).\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n    {\"name\": \"claim_task\", \"description\": \"Claim a task from the board by ID.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"task_id\": {\"type\": \"integer\"}}, \"required\": [\"task_id\"]}},\n]\n\n\ndef agent_loop(messages: list):\n    while True:\n        inbox = BUS.read_inbox(\"lead\")\n        if inbox:\n            messages.append({\n                \"role\": \"user\",\n                \"content\": f\"<inbox>{json.dumps(inbox, indent=2)}</inbox>\",\n            })\n            messages.append({\n                \"role\": \"assistant\",\n                \"content\": \"Noted inbox messages.\",\n            })\n        response = client.messages.create(\n            model=MODEL,\n            system=SYSTEM,\n            messages=messages,\n            tools=TOOLS,\n            max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n        if response.stop_reason != \"tool_use\":\n            return\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                handler = TOOL_HANDLERS.get(block.name)\n                try:\n                    output = handler(**block.input) if handler else f\"Unknown tool: {block.name}\"\n                except Exception as e:\n                    output = f\"Error: {e}\"\n                print(f\"> {block.name}: {str(output)[:200]}\")\n                results.append({\n                    \"type\": \"tool_result\",\n                    \"tool_use_id\": block.id,\n                    \"content\": str(output),\n                })\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms11 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n        if query.strip() == \"/team\":\n            print(TEAM.list_all())\n            continue\n        if query.strip() == \"/inbox\":\n            print(json.dumps(BUS.read_inbox(\"lead\"), indent=2))\n            continue\n        if query.strip() == \"/tasks\":\n            TASKS_DIR.mkdir(exist_ok=True)\n            for f in sorted(TASKS_DIR.glob(\"task_*.json\")):\n                t = json.loads(f.read_text())\n                marker = {\"pending\": \"[ ]\", \"in_progress\": \"[>]\", \"completed\": \"[x]\"}.get(t[\"status\"], \"[?]\")\n                owner = f\" @{t['owner']}\" if t.get(\"owner\") else \"\"\n                print(f\"  {marker} #{t['id']}: {t['subject']}{owner}\")\n            continue\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
+      "layer": "platform",
+      "source": "#!/usr/bin/env python3\n# Harness: autonomy -- models that find work without being told.\n\"\"\"\ns17_autonomous_agents.py - Autonomous Agents\n\nIdle cycle with task board polling, auto-claiming unclaimed tasks, and\nidentity re-injection after context compression. Builds on task boards,\nteam mailboxes, and protocol support from earlier chapters.\n\n    Teammate lifecycle:\n    +-------+\n    | spawn |\n    +---+---+\n        |\n        v\n    +-------+  tool_use    +-------+\n    | WORK  | <----------- |  LLM  |\n    +---+---+              +-------+\n        |\n        | stop_reason != tool_use\n        v\n    +--------+\n    | IDLE   | poll every 5s for up to 60s\n    +---+----+\n        |\n        +---> check inbox -> message? -> resume WORK\n        |\n        +---> scan .tasks/ -> unclaimed? -> claim -> resume WORK\n        |\n        +---> timeout (60s) -> shutdown\n\n    Identity re-injection after compression:\n    messages = [identity_block, ...remaining...]\n    \"You are 'coder', role: backend, team: my-team\"\n\nKey idea: an idle teammate can safely claim ready work instead of waiting\nfor every assignment from the lead.\nA teammate here is a long-lived worker, not a one-shot subagent that only\nreturns a single summary.\n\"\"\"\n\nimport json\nimport os\nimport subprocess\nimport threading\nimport time\nimport uuid\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\nTEAM_DIR = WORKDIR / \".team\"\nINBOX_DIR = TEAM_DIR / \"inbox\"\nTASKS_DIR = WORKDIR / \".tasks\"\nREQUESTS_DIR = TEAM_DIR / \"requests\"\nCLAIM_EVENTS_PATH = TASKS_DIR / \"claim_events.jsonl\"\n\nPOLL_INTERVAL = 5\nIDLE_TIMEOUT = 60\n\nSYSTEM = f\"You are a team lead at {WORKDIR}. Teammates are autonomous -- they find work themselves.\"\n\nVALID_MSG_TYPES = {\n    \"message\",\n    \"broadcast\",\n    \"shutdown_request\",\n    \"shutdown_response\",\n    \"plan_approval\",\n    \"plan_approval_response\",\n}\n\n_claim_lock = threading.Lock()\n\n\n# -- MessageBus: JSONL inbox per teammate --\nclass MessageBus:\n    def __init__(self, inbox_dir: Path):\n        self.dir = inbox_dir\n        self.dir.mkdir(parents=True, exist_ok=True)\n\n    def send(self, sender: str, to: str, content: str,\n             msg_type: str = \"message\", extra: dict = None) -> str:\n        if msg_type not in VALID_MSG_TYPES:\n            return f\"Error: Invalid type '{msg_type}'. Valid: {VALID_MSG_TYPES}\"\n        msg = {\n            \"type\": msg_type,\n            \"from\": sender,\n            \"content\": content,\n            \"timestamp\": time.time(),\n        }\n        if extra:\n            msg.update(extra)\n        inbox_path = self.dir / f\"{to}.jsonl\"\n        with open(inbox_path, \"a\") as f:\n            f.write(json.dumps(msg) + \"\\n\")\n        return f\"Sent {msg_type} to {to}\"\n\n    def read_inbox(self, name: str) -> list:\n        inbox_path = self.dir / f\"{name}.jsonl\"\n        if not inbox_path.exists():\n            return []\n        messages = []\n        for line in inbox_path.read_text().strip().splitlines():\n            if line:\n                messages.append(json.loads(line))\n        inbox_path.write_text(\"\")\n        return messages\n\n    def broadcast(self, sender: str, content: str, teammates: list) -> str:\n        count = 0\n        for name in teammates:\n            if name != sender:\n                self.send(sender, name, content, \"broadcast\")\n                count += 1\n        return f\"Broadcast to {count} teammates\"\n\n\nBUS = MessageBus(INBOX_DIR)\n\n\nclass RequestStore:\n    \"\"\"\n    Durable protocol request records.\n\n    s17 should not regress from s16 back to in-memory trackers. These request\n    files let autonomous teammates inspect or resume protocol state later.\n    \"\"\"\n\n    def __init__(self, base_dir: Path):\n        self.dir = base_dir\n        self.dir.mkdir(parents=True, exist_ok=True)\n        self._lock = threading.Lock()\n\n    def _path(self, request_id: str) -> Path:\n        return self.dir / f\"{request_id}.json\"\n\n    def create(self, record: dict) -> dict:\n        request_id = record[\"request_id\"]\n        with self._lock:\n            self._path(request_id).write_text(json.dumps(record, indent=2))\n        return record\n\n    def get(self, request_id: str) -> dict | None:\n        path = self._path(request_id)\n        if not path.exists():\n            return None\n        return json.loads(path.read_text())\n\n    def update(self, request_id: str, **changes) -> dict | None:\n        with self._lock:\n            record = self.get(request_id)\n            if not record:\n                return None\n            record.update(changes)\n            record[\"updated_at\"] = time.time()\n            self._path(request_id).write_text(json.dumps(record, indent=2))\n        return record\n\n\nREQUEST_STORE = RequestStore(REQUESTS_DIR)\n\n\n# -- Task board scanning --\ndef _append_claim_event(payload: dict):\n    TASKS_DIR.mkdir(parents=True, exist_ok=True)\n    with CLAIM_EVENTS_PATH.open(\"a\", encoding=\"utf-8\") as f:\n        f.write(json.dumps(payload) + \"\\n\")\n\n\ndef _task_allows_role(task: dict, role: str | None) -> bool:\n    required_role = task.get(\"claim_role\") or task.get(\"required_role\") or \"\"\n    if not required_role:\n        return True\n    return bool(role) and role == required_role\n\n\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\ndef scan_unclaimed_tasks(role: str | None = None) -> list:\n    TASKS_DIR.mkdir(exist_ok=True)\n    unclaimed = []\n    for f in sorted(TASKS_DIR.glob(\"task_*.json\")):\n        task = json.loads(f.read_text())\n        if is_claimable_task(task, role):\n            unclaimed.append(task)\n    return unclaimed\n\n\ndef claim_task(\n    task_id: int,\n    owner: str,\n    role: str | None = None,\n    source: str = \"manual\",\n) -> str:\n    with _claim_lock:\n        path = TASKS_DIR / f\"task_{task_id}.json\"\n        if not path.exists():\n            return f\"Error: Task {task_id} not found\"\n        task = json.loads(path.read_text())\n        if not is_claimable_task(task, role):\n            return f\"Error: Task {task_id} is not claimable for role={role or '(any)'}\"\n        task[\"owner\"] = owner\n        task[\"status\"] = \"in_progress\"\n        task[\"claimed_at\"] = time.time()\n        task[\"claim_source\"] = source\n        path.write_text(json.dumps(task, indent=2))\n    _append_claim_event({\n        \"event\": \"task.claimed\",\n        \"task_id\": task_id,\n        \"owner\": owner,\n        \"role\": role,\n        \"source\": source,\n        \"ts\": time.time(),\n    })\n    return f\"Claimed task #{task_id} for {owner} via {source}\"\n\n\n# -- Identity re-injection after compression --\ndef make_identity_block(name: str, role: str, team_name: str) -> dict:\n    return {\n        \"role\": \"user\",\n        \"content\": f\"<identity>You are '{name}', role: {role}, team: {team_name}. Continue your work.</identity>\",\n    }\n\n\ndef ensure_identity_context(messages: list, name: str, role: str, team_name: str):\n    if messages and \"<identity>\" in str(messages[0].get(\"content\", \"\")):\n        return\n    messages.insert(0, make_identity_block(name, role, team_name))\n    messages.insert(1, {\"role\": \"assistant\", \"content\": f\"I am {name}. Continuing.\"})\n\n\n# -- Autonomous TeammateManager --\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    def _load_config(self) -> dict:\n        if self.config_path.exists():\n            return json.loads(self.config_path.read_text())\n        return {\"team_name\": \"default\", \"members\": []}\n\n    def _save_config(self):\n        self.config_path.write_text(json.dumps(self.config, indent=2))\n\n    def _find_member(self, name: str) -> dict:\n        for m in self.config[\"members\"]:\n            if m[\"name\"] == name:\n                return m\n        return None\n\n    def _set_status(self, name: str, status: str):\n        member = self._find_member(name)\n        if member:\n            member[\"status\"] = status\n            self._save_config()\n\n    def spawn(self, name: str, role: str, prompt: str) -> str:\n        member = self._find_member(name)\n        if member:\n            if member[\"status\"] not in (\"idle\", \"shutdown\"):\n                return f\"Error: '{name}' is currently {member['status']}\"\n            member[\"status\"] = \"working\"\n            member[\"role\"] = role\n        else:\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._loop,\n            args=(name, role, prompt),\n            daemon=True,\n        )\n        self.threads[name] = thread\n        thread.start()\n        return f\"Spawned '{name}' (role: {role})\"\n\n    def _loop(self, name: str, role: str, prompt: str):\n        team_name = self.config[\"team_name\"]\n        sys_prompt = (\n            f\"You are '{name}', role: {role}, team: {team_name}, at {WORKDIR}. \"\n            f\"Use idle tool when you have no more work. You will auto-claim new tasks.\"\n        )\n        messages = [{\"role\": \"user\", \"content\": prompt}]\n        tools = self._teammate_tools()\n\n        while True:\n            # -- WORK PHASE: standard agent loop --\n            for _ in range(50):\n                inbox = BUS.read_inbox(name)\n                for msg in inbox:\n                    if msg.get(\"type\") == \"shutdown_request\":\n                        self._set_status(name, \"shutdown\")\n                        return\n                    messages.append({\"role\": \"user\", \"content\": json.dumps(msg)})\n                try:\n                    response = client.messages.create(\n                        model=MODEL,\n                        system=sys_prompt,\n                        messages=messages,\n                        tools=tools,\n                        max_tokens=8000,\n                    )\n                except Exception:\n                    self._set_status(name, \"idle\")\n                    return\n                messages.append({\"role\": \"assistant\", \"content\": response.content})\n                if response.stop_reason != \"tool_use\":\n                    break\n                results = []\n                idle_requested = False\n                for block in response.content:\n                    if block.type == \"tool_use\":\n                        if block.name == \"idle\":\n                            idle_requested = True\n                            output = \"Entering idle phase. Will poll for new tasks.\"\n                        else:\n                            output = self._exec(name, block.name, block.input)\n                        print(f\"  [{name}] {block.name}: {str(output)[:120]}\")\n                        results.append({\n                            \"type\": \"tool_result\",\n                            \"tool_use_id\": block.id,\n                            \"content\": str(output),\n                        })\n                messages.append({\"role\": \"user\", \"content\": results})\n                if idle_requested:\n                    break\n\n            # -- IDLE PHASE: poll for inbox messages and unclaimed tasks --\n            self._set_status(name, \"idle\")\n            resume = False\n            polls = IDLE_TIMEOUT // max(POLL_INTERVAL, 1)\n            for _ in range(polls):\n                time.sleep(POLL_INTERVAL)\n                inbox = BUS.read_inbox(name)\n                if inbox:\n                    ensure_identity_context(messages, name, role, team_name)\n                    for msg in inbox:\n                        if msg.get(\"type\") == \"shutdown_request\":\n                            self._set_status(name, \"shutdown\")\n                            return\n                        messages.append({\"role\": \"user\", \"content\": json.dumps(msg)})\n                    resume = True\n                    break\n                unclaimed = scan_unclaimed_tasks(role)\n                if unclaimed:\n                    task = unclaimed[0]\n                    claim_result = claim_task(\n                        task[\"id\"], name, role=role, source=\"auto\"\n                    )\n                    if claim_result.startswith(\"Error:\"):\n                        continue\n                    task_prompt = (\n                        f\"<auto-claimed>Task #{task['id']}: {task['subject']}\\n\"\n                        f\"{task.get('description', '')}</auto-claimed>\"\n                    )\n                    ensure_identity_context(messages, name, role, team_name)\n                    messages.append({\"role\": \"user\", \"content\": task_prompt})\n                    messages.append({\"role\": \"assistant\", \"content\": f\"{claim_result}. Working on it.\"})\n                    resume = True\n                    break\n\n            if not resume:\n                self._set_status(name, \"shutdown\")\n                return\n            self._set_status(name, \"working\")\n\n    def _exec(self, sender: str, tool_name: str, args: dict) -> str:\n        # these base tools are unchanged from s02\n        if tool_name == \"bash\":\n            return _run_bash(args[\"command\"])\n        if tool_name == \"read_file\":\n            return _run_read(args[\"path\"])\n        if tool_name == \"write_file\":\n            return _run_write(args[\"path\"], args[\"content\"])\n        if tool_name == \"edit_file\":\n            return _run_edit(args[\"path\"], args[\"old_text\"], args[\"new_text\"])\n        if tool_name == \"send_message\":\n            return BUS.send(sender, args[\"to\"], args[\"content\"], args.get(\"msg_type\", \"message\"))\n        if tool_name == \"read_inbox\":\n            return json.dumps(BUS.read_inbox(sender), indent=2)\n        if tool_name == \"shutdown_response\":\n            req_id = args[\"request_id\"]\n            updated = REQUEST_STORE.update(\n                req_id,\n                status=\"approved\" if args[\"approve\"] else \"rejected\",\n                resolved_by=sender,\n                resolved_at=time.time(),\n                response={\"approve\": args[\"approve\"], \"reason\": args.get(\"reason\", \"\")},\n            )\n            if not updated:\n                return f\"Error: Unknown shutdown request {req_id}\"\n            BUS.send(\n                sender, \"lead\", args.get(\"reason\", \"\"),\n                \"shutdown_response\", {\"request_id\": req_id, \"approve\": args[\"approve\"]},\n            )\n            return f\"Shutdown {'approved' if args['approve'] else 'rejected'}\"\n        if tool_name == \"plan_approval\":\n            plan_text = args.get(\"plan\", \"\")\n            req_id = str(uuid.uuid4())[:8]\n            REQUEST_STORE.create({\n                \"request_id\": req_id,\n                \"kind\": \"plan_approval\",\n                \"from\": sender,\n                \"to\": \"lead\",\n                \"status\": \"pending\",\n                \"plan\": plan_text,\n                \"created_at\": time.time(),\n                \"updated_at\": time.time(),\n            })\n            BUS.send(\n                sender, \"lead\", plan_text, \"plan_approval\",\n                {\"request_id\": req_id, \"plan\": plan_text},\n            )\n            return f\"Plan submitted (request_id={req_id}). Waiting for approval.\"\n        if tool_name == \"claim_task\":\n            return claim_task(\n                args[\"task_id\"],\n                sender,\n                role=self._find_member(sender).get(\"role\") if self._find_member(sender) else None,\n                source=\"manual\",\n            )\n        return f\"Unknown tool: {tool_name}\"\n\n    def _teammate_tools(self) -> list:\n        # these base tools are unchanged from s02\n        return [\n            {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n            {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}}, \"required\": [\"path\"]}},\n            {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n            {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n            {\"name\": \"send_message\", \"description\": \"Send message to a teammate.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"to\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}, \"msg_type\": {\"type\": \"string\", \"enum\": list(VALID_MSG_TYPES)}}, \"required\": [\"to\", \"content\"]}},\n            {\"name\": \"read_inbox\", \"description\": \"Read and drain your inbox.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n            {\"name\": \"shutdown_response\", \"description\": \"Respond to a shutdown request.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"request_id\": {\"type\": \"string\"}, \"approve\": {\"type\": \"boolean\"}, \"reason\": {\"type\": \"string\"}}, \"required\": [\"request_id\", \"approve\"]}},\n            {\"name\": \"plan_approval\", \"description\": \"Submit a plan for lead approval.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"plan\": {\"type\": \"string\"}}, \"required\": [\"plan\"]}},\n            {\"name\": \"idle\", \"description\": \"Signal that you have no more work. Enters idle polling phase.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n            {\"name\": \"claim_task\", \"description\": \"Claim a task from the task board by ID.\",\n             \"input_schema\": {\"type\": \"object\", \"properties\": {\"task_id\": {\"type\": \"integer\"}}, \"required\": [\"task_id\"]}},\n        ]\n\n    def list_all(self) -> str:\n        if not self.config[\"members\"]:\n            return \"No teammates.\"\n        lines = [f\"Team: {self.config['team_name']}\"]\n        for m in self.config[\"members\"]:\n            lines.append(f\"  {m['name']} ({m['role']}): {m['status']}\")\n        return \"\\n\".join(lines)\n\n    def member_names(self) -> list:\n        return [m[\"name\"] for m in self.config[\"members\"]]\n\n\nTEAM = TeammateManager(TEAM_DIR)\n\n\n# -- Base tool implementations (these base tools are unchanged from s02) --\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\n\ndef _run_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(\n            command, shell=True, cwd=WORKDIR,\n            capture_output=True, text=True, timeout=120,\n        )\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\n\ndef _run_read(path: str, limit: int = None) -> str:\n    try:\n        lines = _safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef _run_write(path: str, content: str) -> str:\n    try:\n        fp = _safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef _run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = _safe_path(path)\n        c = fp.read_text()\n        if old_text not in c:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(c.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\n# -- Lead-specific protocol handlers --\ndef handle_shutdown_request(teammate: str) -> str:\n    req_id = str(uuid.uuid4())[:8]\n    REQUEST_STORE.create({\n        \"request_id\": req_id,\n        \"kind\": \"shutdown\",\n        \"from\": \"lead\",\n        \"to\": teammate,\n        \"status\": \"pending\",\n        \"created_at\": time.time(),\n        \"updated_at\": time.time(),\n    })\n    BUS.send(\n        \"lead\", teammate, \"Please shut down gracefully.\",\n        \"shutdown_request\", {\"request_id\": req_id},\n    )\n    return f\"Shutdown request {req_id} sent to '{teammate}'\"\n\n\ndef handle_plan_review(request_id: str, approve: bool, feedback: str = \"\") -> str:\n    req = REQUEST_STORE.get(request_id)\n    if not req:\n        return f\"Error: Unknown plan request_id '{request_id}'\"\n    REQUEST_STORE.update(\n        request_id,\n        status=\"approved\" if approve else \"rejected\",\n        reviewed_by=\"lead\",\n        resolved_at=time.time(),\n        feedback=feedback,\n    )\n    BUS.send(\n        \"lead\", req[\"from\"], feedback, \"plan_approval_response\",\n        {\"request_id\": request_id, \"approve\": approve, \"feedback\": feedback},\n    )\n    return f\"Plan {'approved' if approve else 'rejected'} for '{req['from']}'\"\n\n\ndef _check_shutdown_status(request_id: str) -> str:\n    return json.dumps(REQUEST_STORE.get(request_id) or {\"error\": \"not found\"})\n\n\n# -- Lead tool dispatch (14 tools) --\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\"], kw[\"new_text\"]),\n    \"spawn_teammate\":    lambda **kw: TEAM.spawn(kw[\"name\"], kw[\"role\"], kw[\"prompt\"]),\n    \"list_teammates\":    lambda **kw: TEAM.list_all(),\n    \"send_message\":      lambda **kw: BUS.send(\"lead\", kw[\"to\"], kw[\"content\"], kw.get(\"msg_type\", \"message\")),\n    \"read_inbox\":        lambda **kw: json.dumps(BUS.read_inbox(\"lead\"), indent=2),\n    \"broadcast\":         lambda **kw: BUS.broadcast(\"lead\", kw[\"content\"], TEAM.member_names()),\n    \"shutdown_request\":  lambda **kw: handle_shutdown_request(kw[\"teammate\"]),\n    \"shutdown_response\": lambda **kw: _check_shutdown_status(kw.get(\"request_id\", \"\")),\n    \"plan_approval\":     lambda **kw: handle_plan_review(kw[\"request_id\"], kw[\"approve\"], kw.get(\"feedback\", \"\")),\n    \"idle\":              lambda **kw: \"Lead does not idle.\",\n    \"claim_task\":        lambda **kw: claim_task(kw[\"task_id\"], \"lead\"),\n}\n\n# these base tools are unchanged from s02\nTOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n    {\"name\": \"spawn_teammate\", \"description\": \"Spawn an autonomous teammate.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}, \"role\": {\"type\": \"string\"}, \"prompt\": {\"type\": \"string\"}}, \"required\": [\"name\", \"role\", \"prompt\"]}},\n    {\"name\": \"list_teammates\", \"description\": \"List all teammates.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n    {\"name\": \"send_message\", \"description\": \"Send a message to a teammate.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"to\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}, \"msg_type\": {\"type\": \"string\", \"enum\": list(VALID_MSG_TYPES)}}, \"required\": [\"to\", \"content\"]}},\n    {\"name\": \"read_inbox\", \"description\": \"Read and drain the lead's inbox.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n    {\"name\": \"broadcast\", \"description\": \"Send a message to all teammates.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"content\": {\"type\": \"string\"}}, \"required\": [\"content\"]}},\n    {\"name\": \"shutdown_request\", \"description\": \"Request a teammate to shut down.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"teammate\": {\"type\": \"string\"}}, \"required\": [\"teammate\"]}},\n    {\"name\": \"shutdown_response\", \"description\": \"Check shutdown request status.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"request_id\": {\"type\": \"string\"}}, \"required\": [\"request_id\"]}},\n    {\"name\": \"plan_approval\", \"description\": \"Approve or reject a teammate's plan.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"request_id\": {\"type\": \"string\"}, \"approve\": {\"type\": \"boolean\"}, \"feedback\": {\"type\": \"string\"}}, \"required\": [\"request_id\", \"approve\"]}},\n    {\"name\": \"idle\", \"description\": \"Enter idle state (for lead -- rarely used).\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n    {\"name\": \"claim_task\", \"description\": \"Claim a task from the board by ID.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"task_id\": {\"type\": \"integer\"}}, \"required\": [\"task_id\"]}},\n]\n\n\ndef agent_loop(messages: list):\n    while True:\n        inbox = BUS.read_inbox(\"lead\")\n        if inbox:\n            messages.append({\n                \"role\": \"user\",\n                \"content\": f\"<inbox>{json.dumps(inbox, indent=2)}</inbox>\",\n            })\n            messages.append({\n                \"role\": \"assistant\",\n                \"content\": \"Noted inbox messages.\",\n            })\n        response = client.messages.create(\n            model=MODEL,\n            system=SYSTEM,\n            messages=messages,\n            tools=TOOLS,\n            max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n        if response.stop_reason != \"tool_use\":\n            return\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                handler = TOOL_HANDLERS.get(block.name)\n                try:\n                    output = handler(**block.input) if handler else f\"Unknown tool: {block.name}\"\n                except Exception as e:\n                    output = f\"Error: {e}\"\n                print(f\"> {block.name}: {str(output)[:200]}\")\n                results.append({\n                    \"type\": \"tool_result\",\n                    \"tool_use_id\": block.id,\n                    \"content\": str(output),\n                })\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms17 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n        if query.strip() == \"/team\":\n            print(TEAM.list_all())\n            continue\n        if query.strip() == \"/inbox\":\n            print(json.dumps(BUS.read_inbox(\"lead\"), indent=2))\n            continue\n        if query.strip() == \"/tasks\":\n            TASKS_DIR.mkdir(exist_ok=True)\n            for f in sorted(TASKS_DIR.glob(\"task_*.json\")):\n                t = json.loads(f.read_text())\n                marker = {\"pending\": \"[ ]\", \"in_progress\": \"[>]\", \"completed\": \"[x]\"}.get(t[\"status\"], \"[?]\")\n                owner = f\" @{t['owner']}\" if t.get(\"owner\") else \"\"\n                print(f\"  {marker} #{t['id']}: {t['subject']}{owner}\")\n            continue\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
     },
     {
-      "id": "s12",
-      "filename": "s12_worktree_task_isolation.py",
-      "title": "Worktree + Task Isolation",
-      "subtitle": "Isolate by Directory",
-      "loc": 694,
+      "id": "s18",
+      "filename": "s18_worktree_task_isolation.py",
+      "title": "Worktree Isolation",
+      "subtitle": "Separate Directory, Separate Lane",
+      "loc": 564,
       "tools": [
         "bash",
         "read_file",
@@ -748,8 +1287,10 @@
         "task_bind_worktree",
         "worktree_create",
         "worktree_list",
+        "worktree_enter",
         "worktree_status",
         "worktree_run",
+        "worktree_closeout",
         "worktree_remove",
         "worktree_keep",
         "worktree_events"
@@ -762,70 +1303,159 @@
         "task_bind_worktree",
         "worktree_create",
         "worktree_list",
+        "worktree_enter",
         "worktree_status",
         "worktree_run",
+        "worktree_closeout",
         "worktree_remove",
         "worktree_keep",
         "worktree_events"
       ],
-      "coreAddition": "Composable worktree lifecycle + event stream over a shared task board",
-      "keyInsight": "Each works in its own directory; tasks manage goals, worktrees manage directories, bound by ID",
+      "coreAddition": "Task-worktree state + explicit enter/closeout lifecycle",
+      "keyInsight": "Tasks answer what; worktrees answer where. Keep them separate.",
       "classes": [
         {
           "name": "EventBus",
-          "startLine": 82,
+          "startLine": 89,
           "endLine": 120
         },
         {
           "name": "TaskManager",
           "startLine": 121,
-          "endLine": 218
+          "endLine": 227
         },
         {
           "name": "WorktreeManager",
-          "startLine": 224,
-          "endLine": 472
+          "startLine": 233,
+          "endLine": 474
         }
       ],
       "functions": [
         {
           "name": "detect_repo_root",
           "signature": "def detect_repo_root(cwd: Path)",
-          "startLine": 52
+          "startLine": 66
         },
         {
           "name": "safe_path",
           "signature": "def safe_path(p: str)",
-          "startLine": 477
+          "startLine": 479
         },
         {
           "name": "run_bash",
           "signature": "def run_bash(command: str)",
-          "startLine": 484
+          "startLine": 485
         },
         {
           "name": "run_read",
           "signature": "def run_read(path: str, limit: int = None)",
-          "startLine": 503
+          "startLine": 497
+        },
+        {
+          "name": "run_write",
+          "signature": "def run_write(path: str, content: str)",
+          "startLine": 506
+        },
+        {
+          "name": "run_edit",
+          "signature": "def run_edit(path: str, old_text: str, new_text: str)",
+          "startLine": 515
+        },
+        {
+          "name": "agent_loop",
+          "signature": "def agent_loop(messages: list)",
+          "startLine": 600
+        }
+      ],
+      "layer": "platform",
+      "source": "#!/usr/bin/env python3\n# Harness: directory isolation -- parallel execution lanes that never collide.\n\"\"\"\ns18_worktree_task_isolation.py - Worktree + Task Isolation\n\nDirectory-level isolation for parallel task execution.\nTasks are the control plane and worktrees are the execution plane.\n\n    .tasks/task_12.json\n      {\n        \"id\": 12,\n        \"subject\": \"Implement auth refactor\",\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\nKey insight: \"Isolate by directory, coordinate by task ID.\"\n\nRead this file in this order:\n1. EventBus: how worktree lifecycle stays observable.\n2. TaskManager: how a task binds to an execution lane without becoming the lane itself.\n3. Worktree registry / closeout helpers: how directory state is created, tracked, and cleaned up.\n\nMost common confusion:\n- a worktree is not the task itself\n- a worktree record is not just a path string\n\nTeaching boundary:\nthis file teaches isolated execution lanes first.\nCross-machine execution, merge automation, and enterprise policy glue are intentionally out of scope.\n\"\"\"\n\nimport json\nimport os\nimport re\nimport subprocess\nimport time\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\n\n\ndef detect_repo_root(cwd: Path) -> Path | None:\n    try:\n        r = subprocess.run(\n            [\"git\", \"rev-parse\", \"--show-toplevel\"],\n            cwd=cwd, capture_output=True, text=True, timeout=10,\n        )\n        root = Path(r.stdout.strip())\n        return root if r.returncode == 0 and root.exists() else None\n    except Exception:\n        return None\n\n\nREPO_ROOT = detect_repo_root(WORKDIR) or WORKDIR\n\nSYSTEM = (\n    f\"You are a coding agent at {WORKDIR}. \"\n    \"Use task + worktree tools for multi-task work. \"\n    \"For parallel or risky changes: create tasks, allocate worktree lanes, \"\n    \"run commands in those lanes, then choose keep/remove for closeout.\"\n)\n\n\n# -- EventBus: append-only lifecycle events for observability --\nclass EventBus:\n    def __init__(self, event_log_path: Path):\n        self.path = event_log_path\n        self.path.parent.mkdir(parents=True, exist_ok=True)\n        if not self.path.exists():\n            self.path.write_text(\"\")\n\n    def emit(self, event: str, task_id=None, wt_name=None, error=None, **extra):\n        payload = {\"event\": event, \"ts\": time.time()}\n        if task_id is not None:\n            payload[\"task_id\"] = task_id\n        if wt_name:\n            payload[\"worktree\"] = wt_name\n        if error:\n            payload[\"error\"] = error\n        payload.update(extra)\n        with self.path.open(\"a\", encoding=\"utf-8\") as f:\n            f.write(json.dumps(payload) + \"\\n\")\n\n    def list_recent(self, limit: int = 20) -> str:\n        n = max(1, min(int(limit or 20), 200))\n        lines = self.path.read_text(encoding=\"utf-8\").splitlines()\n        items = []\n        for line in lines[-n:]:\n            try:\n                items.append(json.loads(line))\n            except Exception:\n                items.append({\"event\": \"parse_error\", \"raw\": line})\n        return json.dumps(items, indent=2)\n\n\n# -- TaskManager: persistent task board with optional worktree binding --\nclass TaskManager:\n    def __init__(self, tasks_dir: Path):\n        self.dir = tasks_dir\n        self.dir.mkdir(parents=True, exist_ok=True)\n        self._next_id = self._max_id() + 1\n\n    def _max_id(self) -> int:\n        ids = []\n        for f in self.dir.glob(\"task_*.json\"):\n            try:\n                ids.append(int(f.stem.split(\"_\")[1]))\n            except Exception:\n                pass\n        return max(ids) if ids else 0\n\n    def _path(self, task_id: int) -> Path:\n        return self.dir / f\"task_{task_id}.json\"\n\n    def _load(self, task_id: int) -> dict:\n        path = self._path(task_id)\n        if not path.exists():\n            raise ValueError(f\"Task {task_id} not found\")\n        return json.loads(path.read_text())\n\n    def _save(self, task: dict):\n        self._path(task[\"id\"]).write_text(json.dumps(task, indent=2))\n\n    def create(self, subject: str, description: str = \"\") -> str:\n        task = {\n            \"id\": self._next_id, \"subject\": subject, \"description\": description,\n            \"status\": \"pending\", \"owner\": \"\", \"worktree\": \"\",\n            \"worktree_state\": \"unbound\", \"last_worktree\": \"\",\n            \"closeout\": None, \"blockedBy\": [],\n            \"created_at\": time.time(), \"updated_at\": time.time(),\n        }\n        self._save(task)\n        self._next_id += 1\n        return json.dumps(task, indent=2)\n\n    def get(self, task_id: int) -> str:\n        return json.dumps(self._load(task_id), indent=2)\n\n    def exists(self, task_id: int) -> bool:\n        return self._path(task_id).exists()\n\n    def update(self, task_id: int, status: str = None, owner: str = None) -> str:\n        task = self._load(task_id)\n        if status:\n            if status not in (\"pending\", \"in_progress\", \"completed\", \"deleted\"):\n                raise ValueError(f\"Invalid status: {status}\")\n            task[\"status\"] = status\n        if owner is not None:\n            task[\"owner\"] = owner\n        task[\"updated_at\"] = time.time()\n        self._save(task)\n        return json.dumps(task, indent=2)\n\n    def bind_worktree(self, task_id: int, worktree: str, owner: str = \"\") -> str:\n        task = self._load(task_id)\n        task[\"worktree\"] = worktree\n        task[\"last_worktree\"] = worktree\n        task[\"worktree_state\"] = \"active\"\n        if owner:\n            task[\"owner\"] = owner\n        if task[\"status\"] == \"pending\":\n            task[\"status\"] = \"in_progress\"\n        task[\"updated_at\"] = time.time()\n        self._save(task)\n        return json.dumps(task, indent=2)\n\n    def unbind_worktree(self, task_id: int) -> str:\n        task = self._load(task_id)\n        task[\"worktree\"] = \"\"\n        task[\"worktree_state\"] = \"unbound\"\n        task[\"updated_at\"] = time.time()\n        self._save(task)\n        return json.dumps(task, indent=2)\n\n    def record_closeout(self, task_id: int, action: str, reason: str = \"\", keep_binding: bool = False) -> str:\n        task = self._load(task_id)\n        task[\"closeout\"] = {\n            \"action\": action,\n            \"reason\": reason,\n            \"at\": time.time(),\n        }\n        task[\"worktree_state\"] = action\n        if not keep_binding:\n            task[\"worktree\"] = \"\"\n        task[\"updated_at\"] = time.time()\n        self._save(task)\n        return json.dumps(task, indent=2)\n\n    def list_all(self) -> str:\n        tasks = []\n        for f in sorted(self.dir.glob(\"task_*.json\")):\n            tasks.append(json.loads(f.read_text()))\n        if not tasks:\n            return \"No tasks.\"\n        lines = []\n        for t in tasks:\n            marker = {\"pending\": \"[ ]\", \"in_progress\": \"[>]\", \"completed\": \"[x]\", \"deleted\": \"[-]\"}.get(t[\"status\"], \"[?]\")\n            owner = f\" owner={t['owner']}\" if t.get(\"owner\") else \"\"\n            wt = f\" wt={t['worktree']}\" if t.get(\"worktree\") else \"\"\n            lines.append(f\"{marker} #{t['id']}: {t['subject']}{owner}{wt}\")\n        return \"\\n\".join(lines)\n\n\nTASKS = TaskManager(REPO_ROOT / \".tasks\")\nEVENTS = EventBus(REPO_ROOT / \".worktrees\" / \"events.jsonl\")\n\n\n# -- WorktreeManager: create/list/run/remove git worktrees --\nclass WorktreeManager:\n    def __init__(self, repo_root: Path, tasks: TaskManager, events: EventBus):\n        self.repo_root = repo_root\n        self.tasks = tasks\n        self.events = events\n        self.dir = repo_root / \".worktrees\"\n        self.dir.mkdir(parents=True, exist_ok=True)\n        self.index_path = self.dir / \"index.json\"\n        if not self.index_path.exists():\n            self.index_path.write_text(json.dumps({\"worktrees\": []}, indent=2))\n        self.git_available = self._check_git()\n\n    def _check_git(self) -> bool:\n        try:\n            r = subprocess.run(\n                [\"git\", \"rev-parse\", \"--is-inside-work-tree\"],\n                cwd=self.repo_root, capture_output=True, text=True, timeout=10,\n            )\n            return r.returncode == 0\n        except Exception:\n            return False\n\n    def _run_git(self, args: list[str]) -> str:\n        if not self.git_available:\n            raise RuntimeError(\"Not in a git repository.\")\n        r = subprocess.run(\n            [\"git\", *args], cwd=self.repo_root,\n            capture_output=True, text=True, timeout=120,\n        )\n        if r.returncode != 0:\n            raise RuntimeError((r.stdout + r.stderr).strip() or f\"git {' '.join(args)} failed\")\n        return (r.stdout + r.stderr).strip() or \"(no output)\"\n\n    def _load_index(self) -> dict:\n        return json.loads(self.index_path.read_text())\n\n    def _save_index(self, data: dict):\n        self.index_path.write_text(json.dumps(data, indent=2))\n\n    def _find(self, name: str) -> dict | None:\n        for wt in self._load_index().get(\"worktrees\", []):\n            if wt.get(\"name\") == name:\n                return wt\n        return None\n\n    def _update_entry(self, name: str, **changes) -> dict:\n        idx = self._load_index()\n        updated = None\n        for item in idx.get(\"worktrees\", []):\n            if item.get(\"name\") == name:\n                item.update(changes)\n                updated = item\n                break\n        self._save_index(idx)\n        if not updated:\n            raise ValueError(f\"Worktree '{name}' not found in index\")\n        return updated\n\n    def _validate_name(self, name: str):\n        if not re.fullmatch(r\"[A-Za-z0-9._-]{1,40}\", name or \"\"):\n            raise ValueError(\"Invalid worktree name. Use 1-40 chars: letters, digits, ., _, -\")\n\n    def create(self, name: str, task_id: int = None, base_ref: str = \"HEAD\") -> str:\n        self._validate_name(name)\n        if self._find(name):\n            raise ValueError(f\"Worktree '{name}' already exists\")\n        if task_id is not None and not self.tasks.exists(task_id):\n            raise ValueError(f\"Task {task_id} not found\")\n\n        path = self.dir / name\n        branch = f\"wt/{name}\"\n        self.events.emit(\"worktree.create.before\", task_id=task_id, wt_name=name)\n        try:\n            self._run_git([\"worktree\", \"add\", \"-b\", branch, str(path), base_ref])\n            entry = {\n                \"name\": name, \"path\": str(path), \"branch\": branch,\n                \"task_id\": task_id, \"status\": \"active\", \"created_at\": time.time(),\n            }\n            idx = self._load_index()\n            idx[\"worktrees\"].append(entry)\n            self._save_index(idx)\n            if task_id is not None:\n                self.tasks.bind_worktree(task_id, name)\n            self.events.emit(\"worktree.create.after\", task_id=task_id, wt_name=name)\n            return json.dumps(entry, indent=2)\n        except Exception as e:\n            self.events.emit(\"worktree.create.failed\", task_id=task_id, wt_name=name, error=str(e))\n            raise\n\n    def list_all(self) -> str:\n        wts = self._load_index().get(\"worktrees\", [])\n        if not wts:\n            return \"No worktrees in index.\"\n        lines = []\n        for wt in wts:\n            suffix = f\" task={wt['task_id']}\" if wt.get(\"task_id\") else \"\"\n            lines.append(f\"[{wt.get('status', '?')}] {wt['name']} -> {wt['path']} ({wt.get('branch', '-')}){suffix}\")\n        return \"\\n\".join(lines)\n\n    def status(self, name: str) -> str:\n        wt = self._find(name)\n        if not wt:\n            return f\"Error: Unknown worktree '{name}'\"\n        path = Path(wt[\"path\"])\n        if not path.exists():\n            return f\"Error: Worktree path missing: {path}\"\n        r = subprocess.run(\n            [\"git\", \"status\", \"--short\", \"--branch\"],\n            cwd=path, capture_output=True, text=True, timeout=60,\n        )\n        return (r.stdout + r.stderr).strip() or \"Clean worktree\"\n\n    def enter(self, name: str) -> str:\n        wt = self._find(name)\n        if not wt:\n            return f\"Error: Unknown worktree '{name}'\"\n        path = Path(wt[\"path\"])\n        if not path.exists():\n            return f\"Error: Worktree path missing: {path}\"\n        updated = self._update_entry(name, last_entered_at=time.time())\n        self.events.emit(\"worktree.enter\", task_id=wt.get(\"task_id\"), wt_name=name, path=str(path))\n        return json.dumps(updated, indent=2)\n\n    def run(self, name: str, command: str) -> str:\n        dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n        if any(d in command for d in dangerous):\n            return \"Error: Dangerous command blocked\"\n        wt = self._find(name)\n        if not wt:\n            return f\"Error: Unknown worktree '{name}'\"\n        path = Path(wt[\"path\"])\n        if not path.exists():\n            return f\"Error: Worktree path missing: {path}\"\n        try:\n            self._update_entry(\n                name,\n                last_entered_at=time.time(),\n                last_command_at=time.time(),\n                last_command_preview=command[:120],\n            )\n            self.events.emit(\"worktree.run.before\", task_id=wt.get(\"task_id\"), wt_name=name, command=command[:120])\n            r = subprocess.run(command, shell=True, cwd=path,\n                               capture_output=True, text=True, timeout=300)\n            out = (r.stdout + r.stderr).strip()\n            self.events.emit(\"worktree.run.after\", task_id=wt.get(\"task_id\"), wt_name=name)\n            return out[:50000] if out else \"(no output)\"\n        except subprocess.TimeoutExpired:\n            self.events.emit(\"worktree.run.timeout\", task_id=wt.get(\"task_id\"), wt_name=name)\n            return \"Error: Timeout (300s)\"\n\n    def remove(\n        self,\n        name: str,\n        force: bool = False,\n        complete_task: bool = False,\n        reason: str = \"\",\n    ) -> str:\n        wt = self._find(name)\n        if not wt:\n            return f\"Error: Unknown worktree '{name}'\"\n        task_id = wt.get(\"task_id\")\n        self.events.emit(\"worktree.remove.before\", task_id=task_id, wt_name=name)\n        try:\n            args = [\"worktree\", \"remove\"]\n            if force:\n                args.append(\"--force\")\n            args.append(wt[\"path\"])\n            self._run_git(args)\n            if complete_task and task_id is not None:\n                self.tasks.update(task_id, status=\"completed\")\n                self.events.emit(\"task.completed\", task_id=task_id, wt_name=name)\n            if task_id is not None:\n                self.tasks.record_closeout(task_id, \"removed\", reason, keep_binding=False)\n            self._update_entry(\n                name,\n                status=\"removed\",\n                removed_at=time.time(),\n                closeout={\"action\": \"remove\", \"reason\": reason, \"at\": time.time()},\n            )\n            self.events.emit(\"worktree.remove.after\", task_id=task_id, wt_name=name)\n            return f\"Removed worktree '{name}'\"\n        except Exception as e:\n            self.events.emit(\"worktree.remove.failed\", task_id=task_id, wt_name=name, error=str(e))\n            raise\n\n    def keep(self, name: str) -> str:\n        wt = self._find(name)\n        if not wt:\n            return f\"Error: Unknown worktree '{name}'\"\n        if wt.get(\"task_id\") is not None:\n            self.tasks.record_closeout(wt[\"task_id\"], \"kept\", \"\", keep_binding=True)\n        self._update_entry(\n            name,\n            status=\"kept\",\n            kept_at=time.time(),\n            closeout={\"action\": \"keep\", \"reason\": \"\", \"at\": time.time()},\n        )\n        self.events.emit(\"worktree.keep\", task_id=wt.get(\"task_id\"), wt_name=name)\n        return json.dumps(self._find(name), indent=2)\n\n    def closeout(\n        self,\n        name: str,\n        action: str,\n        reason: str = \"\",\n        force: bool = False,\n        complete_task: bool = False,\n    ) -> str:\n        if action == \"keep\":\n            wt = self._find(name)\n            if not wt:\n                return f\"Error: Unknown worktree '{name}'\"\n            if wt.get(\"task_id\") is not None:\n                self.tasks.record_closeout(\n                    wt[\"task_id\"], \"kept\", reason, keep_binding=True\n                )\n                if complete_task:\n                    self.tasks.update(wt[\"task_id\"], status=\"completed\")\n            self._update_entry(\n                name,\n                status=\"kept\",\n                kept_at=time.time(),\n                closeout={\"action\": \"keep\", \"reason\": reason, \"at\": time.time()},\n            )\n            self.events.emit(\n                \"worktree.closeout.keep\",\n                task_id=wt.get(\"task_id\"),\n                wt_name=name,\n                reason=reason,\n            )\n            return json.dumps(self._find(name), indent=2)\n        if action == \"remove\":\n            self.events.emit(\"worktree.closeout.remove\", wt_name=name, reason=reason)\n            return self.remove(\n                name,\n                force=force,\n                complete_task=complete_task,\n                reason=reason,\n            )\n        raise ValueError(\"action must be 'keep' or 'remove'\")\n\n\nWORKTREES = WorktreeManager(REPO_ROOT, TASKS, EVENTS)\n\n\n# -- Base tools (same as previous sessions, kept minimal) --\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_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(command, shell=True, cwd=WORKDIR,\n                           capture_output=True, text=True, timeout=120)\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\ndef run_read(path: str, limit: int = None) -> str:\n    try:\n        lines = safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\ndef run_write(path: str, content: str) -> str:\n    try:\n        fp = safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\ndef run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = safe_path(path)\n        c = fp.read_text()\n        if old_text not in c:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(c.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\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\"], kw[\"new_text\"]),\n    \"task_create\": lambda **kw: TASKS.create(kw[\"subject\"], kw.get(\"description\", \"\")),\n    \"task_list\": lambda **kw: TASKS.list_all(),\n    \"task_get\": lambda **kw: TASKS.get(kw[\"task_id\"]),\n    \"task_update\": lambda **kw: TASKS.update(kw[\"task_id\"], kw.get(\"status\"), kw.get(\"owner\")),\n    \"task_bind_worktree\": lambda **kw: TASKS.bind_worktree(kw[\"task_id\"], kw[\"worktree\"], kw.get(\"owner\", \"\")),\n    \"worktree_create\": lambda **kw: WORKTREES.create(kw[\"name\"], kw.get(\"task_id\"), kw.get(\"base_ref\", \"HEAD\")),\n    \"worktree_list\": lambda **kw: WORKTREES.list_all(),\n    \"worktree_enter\": lambda **kw: WORKTREES.enter(kw[\"name\"]),\n    \"worktree_status\": lambda **kw: WORKTREES.status(kw[\"name\"]),\n    \"worktree_run\": lambda **kw: WORKTREES.run(kw[\"name\"], kw[\"command\"]),\n    \"worktree_closeout\": lambda **kw: WORKTREES.closeout(\n        kw[\"name\"],\n        kw[\"action\"],\n        kw.get(\"reason\", \"\"),\n        kw.get(\"force\", False),\n        kw.get(\"complete_task\", False),\n    ),\n    \"worktree_keep\": lambda **kw: WORKTREES.keep(kw[\"name\"]),\n    \"worktree_remove\": lambda **kw: WORKTREES.remove(\n        kw[\"name\"],\n        kw.get(\"force\", False),\n        kw.get(\"complete_task\", False),\n        kw.get(\"reason\", \"\"),\n    ),\n    \"worktree_events\": lambda **kw: EVENTS.list_recent(kw.get(\"limit\", 20)),\n}\n\n# Compact tool definitions -- same schema, less vertical space\nTOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command in the current workspace.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"limit\": {\"type\": \"integer\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n    {\"name\": \"task_create\", \"description\": \"Create a new task on the shared task board.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"subject\": {\"type\": \"string\"}, \"description\": {\"type\": \"string\"}}, \"required\": [\"subject\"]}},\n    {\"name\": \"task_list\", \"description\": \"List all tasks with status, owner, and worktree binding.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n    {\"name\": \"task_get\", \"description\": \"Get task details by ID.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"task_id\": {\"type\": \"integer\"}}, \"required\": [\"task_id\"]}},\n    {\"name\": \"task_update\", \"description\": \"Update task status or owner.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"task_id\": {\"type\": \"integer\"}, \"status\": {\"type\": \"string\", \"enum\": [\"pending\", \"in_progress\", \"completed\", \"deleted\"]}, \"owner\": {\"type\": \"string\"}}, \"required\": [\"task_id\"]}},\n    {\"name\": \"task_bind_worktree\", \"description\": \"Bind a task to a worktree name.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"task_id\": {\"type\": \"integer\"}, \"worktree\": {\"type\": \"string\"}, \"owner\": {\"type\": \"string\"}}, \"required\": [\"task_id\", \"worktree\"]}},\n    {\"name\": \"worktree_create\", \"description\": \"Create a git worktree and optionally bind it to a task.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}, \"task_id\": {\"type\": \"integer\"}, \"base_ref\": {\"type\": \"string\"}}, \"required\": [\"name\"]}},\n    {\"name\": \"worktree_list\", \"description\": \"List worktrees tracked in .worktrees/index.json.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {}}},\n    {\"name\": \"worktree_enter\", \"description\": \"Enter or reopen a worktree lane before working in it.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}}, \"required\": [\"name\"]}},\n    {\"name\": \"worktree_status\", \"description\": \"Show git status for one worktree.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}}, \"required\": [\"name\"]}},\n    {\"name\": \"worktree_run\", \"description\": \"Run a shell command in a named worktree directory.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}, \"command\": {\"type\": \"string\"}}, \"required\": [\"name\", \"command\"]}},\n    {\"name\": \"worktree_closeout\", \"description\": \"Close out a lane by keeping it for follow-up or removing it.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}, \"action\": {\"type\": \"string\", \"enum\": [\"keep\", \"remove\"]}, \"reason\": {\"type\": \"string\"}, \"force\": {\"type\": \"boolean\"}, \"complete_task\": {\"type\": \"boolean\"}}, \"required\": [\"name\", \"action\"]}},\n    {\"name\": \"worktree_remove\", \"description\": \"Remove a worktree and optionally mark its bound task completed.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}, \"force\": {\"type\": \"boolean\"}, \"complete_task\": {\"type\": \"boolean\"}, \"reason\": {\"type\": \"string\"}}, \"required\": [\"name\"]}},\n    {\"name\": \"worktree_keep\", \"description\": \"Mark a worktree as kept without removing it.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}}, \"required\": [\"name\"]}},\n    {\"name\": \"worktree_events\", \"description\": \"List recent lifecycle events.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"limit\": {\"type\": \"integer\"}}}},\n]\n\n\ndef agent_loop(messages: list):\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        if response.stop_reason != \"tool_use\":\n            return\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                handler = TOOL_HANDLERS.get(block.name)\n                try:\n                    output = handler(**block.input) if handler else f\"Unknown tool: {block.name}\"\n                except Exception as e:\n                    output = f\"Error: {e}\"\n                print(f\"> {block.name}: {str(output)[:200]}\")\n                results.append({\"type\": \"tool_result\", \"tool_use_id\": block.id, \"content\": str(output)})\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    print(f\"Repo root for s18: {REPO_ROOT}\")\n    if not WORKTREES.git_available:\n        print(\"Note: Not in a git repo. worktree_* tools will return errors.\")\n\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms18 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
+    },
+    {
+      "id": "s19",
+      "filename": "s19_mcp_plugin.py",
+      "title": "MCP & Plugin",
+      "subtitle": "External Capability Bus",
+      "loc": 463,
+      "tools": [
+        "bash",
+        "read_file",
+        "write_file",
+        "edit_file"
+      ],
+      "newTools": [],
+      "coreAddition": "Scoped servers + capability routing",
+      "keyInsight": "External capabilities join the same routing, permission, and result-append path as native tools.",
+      "classes": [
+        {
+          "name": "CapabilityPermissionGate",
+          "startLine": 60,
+          "endLine": 144
+        },
+        {
+          "name": "MCPClient",
+          "startLine": 148,
+          "endLine": 268
+        },
+        {
+          "name": "PluginLoader",
+          "startLine": 269,
+          "endLine": 308
+        },
+        {
+          "name": "MCPToolRouter",
+          "startLine": 309,
+          "endLine": 346
+        }
+      ],
+      "functions": [
+        {
+          "name": "safe_path",
+          "signature": "def safe_path(p: str)",
+          "startLine": 347
+        },
+        {
+          "name": "run_bash",
+          "signature": "def run_bash(command: str)",
+          "startLine": 353
+        },
+        {
+          "name": "run_read",
+          "signature": "def run_read(path: str)",
+          "startLine": 365
         },
         {
           "name": "run_write",
           "signature": "def run_write(path: str, content: str)",
-          "startLine": 513
+          "startLine": 371
         },
         {
           "name": "run_edit",
           "signature": "def run_edit(path: str, old_text: str, new_text: str)",
-          "startLine": 523
+          "startLine": 380
+        },
+        {
+          "name": "build_tool_pool",
+          "signature": "def build_tool_pool()",
+          "startLine": 416
+        },
+        {
+          "name": "handle_tool_call",
+          "signature": "def handle_tool_call(tool_name: str, tool_input: dict)",
+          "startLine": 434
+        },
+        {
+          "name": "normalize_tool_result",
+          "signature": "def normalize_tool_result(tool_name: str, output: str, intent: dict | None = None)",
+          "startLine": 444
         },
         {
           "name": "agent_loop",
           "signature": "def agent_loop(messages: list)",
-          "startLine": 728
+          "startLine": 458
         }
       ],
-      "layer": "collaboration",
-      "source": "#!/usr/bin/env python3\n\"\"\"\ns12_worktree_task_isolation.py - Worktree + Task Isolation\n\nDirectory-level isolation for parallel task execution.\nTasks are the control plane and worktrees are the execution plane.\n\n    .tasks/task_12.json\n      {\n        \"id\": 12,\n        \"subject\": \"Implement auth refactor\",\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\nKey insight: \"Isolate by directory, coordinate by task ID.\"\n\"\"\"\n\nimport json\nimport os\nimport re\nimport subprocess\nimport time\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\n\n\ndef detect_repo_root(cwd: Path) -> Path | None:\n    \"\"\"Return git repo root if cwd is inside a repo, else None.\"\"\"\n    try:\n        r = subprocess.run(\n            [\"git\", \"rev-parse\", \"--show-toplevel\"],\n            cwd=cwd,\n            capture_output=True,\n            text=True,\n            timeout=10,\n        )\n        if r.returncode != 0:\n            return None\n        root = Path(r.stdout.strip())\n        return root if root.exists() else None\n    except Exception:\n        return None\n\n\nREPO_ROOT = detect_repo_root(WORKDIR) or WORKDIR\n\nSYSTEM = (\n    f\"You are a coding agent at {WORKDIR}. \"\n    \"Use task + worktree tools for multi-task work. \"\n    \"For parallel or risky changes: create tasks, allocate worktree lanes, \"\n    \"run commands in those lanes, then choose keep/remove for closeout. \"\n    \"Use worktree_events when you need lifecycle visibility.\"\n)\n\n\n# -- EventBus: append-only lifecycle events for observability --\nclass EventBus:\n    def __init__(self, event_log_path: Path):\n        self.path = event_log_path\n        self.path.parent.mkdir(parents=True, exist_ok=True)\n        if not self.path.exists():\n            self.path.write_text(\"\")\n\n    def emit(\n        self,\n        event: str,\n        task: dict | None = None,\n        worktree: dict | None = None,\n        error: str | None = None,\n    ):\n        payload = {\n            \"event\": event,\n            \"ts\": time.time(),\n            \"task\": task or {},\n            \"worktree\": worktree or {},\n        }\n        if error:\n            payload[\"error\"] = error\n        with self.path.open(\"a\", encoding=\"utf-8\") as f:\n            f.write(json.dumps(payload) + \"\\n\")\n\n    def list_recent(self, limit: int = 20) -> str:\n        n = max(1, min(int(limit or 20), 200))\n        lines = self.path.read_text(encoding=\"utf-8\").splitlines()\n        recent = lines[-n:]\n        items = []\n        for line in recent:\n            try:\n                items.append(json.loads(line))\n            except Exception:\n                items.append({\"event\": \"parse_error\", \"raw\": line})\n        return json.dumps(items, indent=2)\n\n\n# -- TaskManager: persistent task board with optional worktree binding --\nclass TaskManager:\n    def __init__(self, tasks_dir: Path):\n        self.dir = tasks_dir\n        self.dir.mkdir(parents=True, exist_ok=True)\n        self._next_id = self._max_id() + 1\n\n    def _max_id(self) -> int:\n        ids = []\n        for f in self.dir.glob(\"task_*.json\"):\n            try:\n                ids.append(int(f.stem.split(\"_\")[1]))\n            except Exception:\n                pass\n        return max(ids) if ids else 0\n\n    def _path(self, task_id: int) -> Path:\n        return self.dir / f\"task_{task_id}.json\"\n\n    def _load(self, task_id: int) -> dict:\n        path = self._path(task_id)\n        if not path.exists():\n            raise ValueError(f\"Task {task_id} not found\")\n        return json.loads(path.read_text())\n\n    def _save(self, task: dict):\n        self._path(task[\"id\"]).write_text(json.dumps(task, indent=2))\n\n    def create(self, subject: str, description: str = \"\") -> str:\n        task = {\n            \"id\": self._next_id,\n            \"subject\": subject,\n            \"description\": description,\n            \"status\": \"pending\",\n            \"owner\": \"\",\n            \"worktree\": \"\",\n            \"blockedBy\": [],\n            \"created_at\": time.time(),\n            \"updated_at\": time.time(),\n        }\n        self._save(task)\n        self._next_id += 1\n        return json.dumps(task, indent=2)\n\n    def get(self, task_id: int) -> str:\n        return json.dumps(self._load(task_id), indent=2)\n\n    def exists(self, task_id: int) -> bool:\n        return self._path(task_id).exists()\n\n    def update(self, task_id: int, status: str = None, owner: str = None) -> str:\n        task = self._load(task_id)\n        if status:\n            if status not in (\"pending\", \"in_progress\", \"completed\"):\n                raise ValueError(f\"Invalid status: {status}\")\n            task[\"status\"] = status\n        if owner is not None:\n            task[\"owner\"] = owner\n        task[\"updated_at\"] = time.time()\n        self._save(task)\n        return json.dumps(task, indent=2)\n\n    def bind_worktree(self, task_id: int, worktree: str, owner: str = \"\") -> str:\n        task = self._load(task_id)\n        task[\"worktree\"] = worktree\n        if owner:\n            task[\"owner\"] = owner\n        if task[\"status\"] == \"pending\":\n            task[\"status\"] = \"in_progress\"\n        task[\"updated_at\"] = time.time()\n        self._save(task)\n        return json.dumps(task, indent=2)\n\n    def unbind_worktree(self, task_id: int) -> str:\n        task = self._load(task_id)\n        task[\"worktree\"] = \"\"\n        task[\"updated_at\"] = time.time()\n        self._save(task)\n        return json.dumps(task, indent=2)\n\n    def list_all(self) -> str:\n        tasks = []\n        for f in sorted(self.dir.glob(\"task_*.json\")):\n            tasks.append(json.loads(f.read_text()))\n        if not tasks:\n            return \"No tasks.\"\n        lines = []\n        for t in tasks:\n            marker = {\n                \"pending\": \"[ ]\",\n                \"in_progress\": \"[>]\",\n                \"completed\": \"[x]\",\n            }.get(t[\"status\"], \"[?]\")\n            owner = f\" owner={t['owner']}\" if t.get(\"owner\") else \"\"\n            wt = f\" wt={t['worktree']}\" if t.get(\"worktree\") else \"\"\n            lines.append(f\"{marker} #{t['id']}: {t['subject']}{owner}{wt}\")\n        return \"\\n\".join(lines)\n\n\nTASKS = TaskManager(REPO_ROOT / \".tasks\")\nEVENTS = EventBus(REPO_ROOT / \".worktrees\" / \"events.jsonl\")\n\n\n# -- WorktreeManager: create/list/run/remove git worktrees + lifecycle index --\nclass WorktreeManager:\n    def __init__(self, repo_root: Path, tasks: TaskManager, events: EventBus):\n        self.repo_root = repo_root\n        self.tasks = tasks\n        self.events = events\n        self.dir = repo_root / \".worktrees\"\n        self.dir.mkdir(parents=True, exist_ok=True)\n        self.index_path = self.dir / \"index.json\"\n        if not self.index_path.exists():\n            self.index_path.write_text(json.dumps({\"worktrees\": []}, indent=2))\n        self.git_available = self._is_git_repo()\n\n    def _is_git_repo(self) -> bool:\n        try:\n            r = subprocess.run(\n                [\"git\", \"rev-parse\", \"--is-inside-work-tree\"],\n                cwd=self.repo_root,\n                capture_output=True,\n                text=True,\n                timeout=10,\n            )\n            return r.returncode == 0\n        except Exception:\n            return False\n\n    def _run_git(self, args: list[str]) -> str:\n        if not self.git_available:\n            raise RuntimeError(\"Not in a git repository. worktree tools require git.\")\n        r = subprocess.run(\n            [\"git\", *args],\n            cwd=self.repo_root,\n            capture_output=True,\n            text=True,\n            timeout=120,\n        )\n        if r.returncode != 0:\n            msg = (r.stdout + r.stderr).strip()\n            raise RuntimeError(msg or f\"git {' '.join(args)} failed\")\n        return (r.stdout + r.stderr).strip() or \"(no output)\"\n\n    def _load_index(self) -> dict:\n        return json.loads(self.index_path.read_text())\n\n    def _save_index(self, data: dict):\n        self.index_path.write_text(json.dumps(data, indent=2))\n\n    def _find(self, name: str) -> dict | None:\n        idx = self._load_index()\n        for wt in idx.get(\"worktrees\", []):\n            if wt.get(\"name\") == name:\n                return wt\n        return None\n\n    def _validate_name(self, name: str):\n        if not re.fullmatch(r\"[A-Za-z0-9._-]{1,40}\", name or \"\"):\n            raise ValueError(\n                \"Invalid worktree name. Use 1-40 chars: letters, numbers, ., _, -\"\n            )\n\n    def create(self, name: str, task_id: int = None, base_ref: str = \"HEAD\") -> str:\n        self._validate_name(name)\n        if self._find(name):\n            raise ValueError(f\"Worktree '{name}' already exists in index\")\n        if task_id is not None and not self.tasks.exists(task_id):\n            raise ValueError(f\"Task {task_id} not found\")\n\n        path = self.dir / name\n        branch = f\"wt/{name}\"\n        self.events.emit(\n            \"worktree.create.before\",\n            task={\"id\": task_id} if task_id is not None else {},\n            worktree={\"name\": name, \"base_ref\": base_ref},\n        )\n        try:\n            self._run_git([\"worktree\", \"add\", \"-b\", branch, str(path), base_ref])\n\n            entry = {\n                \"name\": name,\n                \"path\": str(path),\n                \"branch\": branch,\n                \"task_id\": task_id,\n                \"status\": \"active\",\n                \"created_at\": time.time(),\n            }\n\n            idx = self._load_index()\n            idx[\"worktrees\"].append(entry)\n            self._save_index(idx)\n\n            if task_id is not None:\n                self.tasks.bind_worktree(task_id, name)\n\n            self.events.emit(\n                \"worktree.create.after\",\n                task={\"id\": task_id} if task_id is not None else {},\n                worktree={\n                    \"name\": name,\n                    \"path\": str(path),\n                    \"branch\": branch,\n                    \"status\": \"active\",\n                },\n            )\n            return json.dumps(entry, indent=2)\n        except Exception as e:\n            self.events.emit(\n                \"worktree.create.failed\",\n                task={\"id\": task_id} if task_id is not None else {},\n                worktree={\"name\": name, \"base_ref\": base_ref},\n                error=str(e),\n            )\n            raise\n\n    def list_all(self) -> str:\n        idx = self._load_index()\n        wts = idx.get(\"worktrees\", [])\n        if not wts:\n            return \"No worktrees in index.\"\n        lines = []\n        for wt in wts:\n            suffix = f\" task={wt['task_id']}\" if wt.get(\"task_id\") else \"\"\n            lines.append(\n                f\"[{wt.get('status', 'unknown')}] {wt['name']} -> \"\n                f\"{wt['path']} ({wt.get('branch', '-')}){suffix}\"\n            )\n        return \"\\n\".join(lines)\n\n    def status(self, name: str) -> str:\n        wt = self._find(name)\n        if not wt:\n            return f\"Error: Unknown worktree '{name}'\"\n        path = Path(wt[\"path\"])\n        if not path.exists():\n            return f\"Error: Worktree path missing: {path}\"\n        r = subprocess.run(\n            [\"git\", \"status\", \"--short\", \"--branch\"],\n            cwd=path,\n            capture_output=True,\n            text=True,\n            timeout=60,\n        )\n        text = (r.stdout + r.stderr).strip()\n        return text or \"Clean worktree\"\n\n    def run(self, name: str, command: str) -> str:\n        dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n        if any(d in command for d in dangerous):\n            return \"Error: Dangerous command blocked\"\n\n        wt = self._find(name)\n        if not wt:\n            return f\"Error: Unknown worktree '{name}'\"\n        path = Path(wt[\"path\"])\n        if not path.exists():\n            return f\"Error: Worktree path missing: {path}\"\n\n        try:\n            r = subprocess.run(\n                command,\n                shell=True,\n                cwd=path,\n                capture_output=True,\n                text=True,\n                timeout=300,\n            )\n            out = (r.stdout + r.stderr).strip()\n            return out[:50000] if out else \"(no output)\"\n        except subprocess.TimeoutExpired:\n            return \"Error: Timeout (300s)\"\n\n    def remove(self, name: str, force: bool = False, complete_task: bool = False) -> str:\n        wt = self._find(name)\n        if not wt:\n            return f\"Error: Unknown worktree '{name}'\"\n\n        self.events.emit(\n            \"worktree.remove.before\",\n            task={\"id\": wt.get(\"task_id\")} if wt.get(\"task_id\") is not None else {},\n            worktree={\"name\": name, \"path\": wt.get(\"path\")},\n        )\n        try:\n            args = [\"worktree\", \"remove\"]\n            if force:\n                args.append(\"--force\")\n            args.append(wt[\"path\"])\n            self._run_git(args)\n\n            if complete_task and wt.get(\"task_id\") is not None:\n                task_id = wt[\"task_id\"]\n                before = json.loads(self.tasks.get(task_id))\n                self.tasks.update(task_id, status=\"completed\")\n                self.tasks.unbind_worktree(task_id)\n                self.events.emit(\n                    \"task.completed\",\n                    task={\n                        \"id\": task_id,\n                        \"subject\": before.get(\"subject\", \"\"),\n                        \"status\": \"completed\",\n                    },\n                    worktree={\"name\": name},\n                )\n\n            idx = self._load_index()\n            for item in idx.get(\"worktrees\", []):\n                if item.get(\"name\") == name:\n                    item[\"status\"] = \"removed\"\n                    item[\"removed_at\"] = time.time()\n            self._save_index(idx)\n\n            self.events.emit(\n                \"worktree.remove.after\",\n                task={\"id\": wt.get(\"task_id\")} if wt.get(\"task_id\") is not None else {},\n                worktree={\"name\": name, \"path\": wt.get(\"path\"), \"status\": \"removed\"},\n            )\n            return f\"Removed worktree '{name}'\"\n        except Exception as e:\n            self.events.emit(\n                \"worktree.remove.failed\",\n                task={\"id\": wt.get(\"task_id\")} if wt.get(\"task_id\") is not None else {},\n                worktree={\"name\": name, \"path\": wt.get(\"path\")},\n                error=str(e),\n            )\n            raise\n\n    def keep(self, name: str) -> str:\n        wt = self._find(name)\n        if not wt:\n            return f\"Error: Unknown worktree '{name}'\"\n\n        idx = self._load_index()\n        kept = None\n        for item in idx.get(\"worktrees\", []):\n            if item.get(\"name\") == name:\n                item[\"status\"] = \"kept\"\n                item[\"kept_at\"] = time.time()\n                kept = item\n        self._save_index(idx)\n\n        self.events.emit(\n            \"worktree.keep\",\n            task={\"id\": wt.get(\"task_id\")} if wt.get(\"task_id\") is not None else {},\n            worktree={\n                \"name\": name,\n                \"path\": wt.get(\"path\"),\n                \"status\": \"kept\",\n            },\n        )\n        return json.dumps(kept, indent=2) if kept else f\"Error: Unknown worktree '{name}'\"\n\n\nWORKTREES = WorktreeManager(REPO_ROOT, TASKS, EVENTS)\n\n\n# -- Base tools (kept minimal, same style as previous sessions) --\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\n\ndef run_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(\n            command,\n            shell=True,\n            cwd=WORKDIR,\n            capture_output=True,\n            text=True,\n            timeout=120,\n        )\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\n\ndef run_read(path: str, limit: int = None) -> str:\n    try:\n        lines = safe_path(path).read_text().splitlines()\n        if limit and limit < len(lines):\n            lines = lines[:limit] + [f\"... ({len(lines) - limit} more)\"]\n        return \"\\n\".join(lines)[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef run_write(path: str, content: str) -> str:\n    try:\n        fp = safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\ndef run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = safe_path(path)\n        c = fp.read_text()\n        if old_text not in c:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(c.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\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\"], kw[\"new_text\"]),\n    \"task_create\": lambda **kw: TASKS.create(kw[\"subject\"], kw.get(\"description\", \"\")),\n    \"task_list\": lambda **kw: TASKS.list_all(),\n    \"task_get\": lambda **kw: TASKS.get(kw[\"task_id\"]),\n    \"task_update\": lambda **kw: TASKS.update(kw[\"task_id\"], kw.get(\"status\"), kw.get(\"owner\")),\n    \"task_bind_worktree\": lambda **kw: TASKS.bind_worktree(kw[\"task_id\"], kw[\"worktree\"], kw.get(\"owner\", \"\")),\n    \"worktree_create\": lambda **kw: WORKTREES.create(kw[\"name\"], kw.get(\"task_id\"), kw.get(\"base_ref\", \"HEAD\")),\n    \"worktree_list\": lambda **kw: WORKTREES.list_all(),\n    \"worktree_status\": lambda **kw: WORKTREES.status(kw[\"name\"]),\n    \"worktree_run\": lambda **kw: WORKTREES.run(kw[\"name\"], kw[\"command\"]),\n    \"worktree_keep\": lambda **kw: WORKTREES.keep(kw[\"name\"]),\n    \"worktree_remove\": lambda **kw: WORKTREES.remove(kw[\"name\"], kw.get(\"force\", False), kw.get(\"complete_task\", False)),\n    \"worktree_events\": lambda **kw: EVENTS.list_recent(kw.get(\"limit\", 20)),\n}\n\nTOOLS = [\n    {\n        \"name\": \"bash\",\n        \"description\": \"Run a shell command in the current workspace (blocking).\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\"command\": {\"type\": \"string\"}},\n            \"required\": [\"command\"],\n        },\n    },\n    {\n        \"name\": \"read_file\",\n        \"description\": \"Read file contents.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"path\": {\"type\": \"string\"},\n                \"limit\": {\"type\": \"integer\"},\n            },\n            \"required\": [\"path\"],\n        },\n    },\n    {\n        \"name\": \"write_file\",\n        \"description\": \"Write content to file.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"path\": {\"type\": \"string\"},\n                \"content\": {\"type\": \"string\"},\n            },\n            \"required\": [\"path\", \"content\"],\n        },\n    },\n    {\n        \"name\": \"edit_file\",\n        \"description\": \"Replace exact text in file.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"path\": {\"type\": \"string\"},\n                \"old_text\": {\"type\": \"string\"},\n                \"new_text\": {\"type\": \"string\"},\n            },\n            \"required\": [\"path\", \"old_text\", \"new_text\"],\n        },\n    },\n    {\n        \"name\": \"task_create\",\n        \"description\": \"Create a new task on the shared task board.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"subject\": {\"type\": \"string\"},\n                \"description\": {\"type\": \"string\"},\n            },\n            \"required\": [\"subject\"],\n        },\n    },\n    {\n        \"name\": \"task_list\",\n        \"description\": \"List all tasks with status, owner, and worktree binding.\",\n        \"input_schema\": {\"type\": \"object\", \"properties\": {}},\n    },\n    {\n        \"name\": \"task_get\",\n        \"description\": \"Get task details by ID.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\"task_id\": {\"type\": \"integer\"}},\n            \"required\": [\"task_id\"],\n        },\n    },\n    {\n        \"name\": \"task_update\",\n        \"description\": \"Update task status or owner.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"task_id\": {\"type\": \"integer\"},\n                \"status\": {\n                    \"type\": \"string\",\n                    \"enum\": [\"pending\", \"in_progress\", \"completed\"],\n                },\n                \"owner\": {\"type\": \"string\"},\n            },\n            \"required\": [\"task_id\"],\n        },\n    },\n    {\n        \"name\": \"task_bind_worktree\",\n        \"description\": \"Bind a task to a worktree name.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"task_id\": {\"type\": \"integer\"},\n                \"worktree\": {\"type\": \"string\"},\n                \"owner\": {\"type\": \"string\"},\n            },\n            \"required\": [\"task_id\", \"worktree\"],\n        },\n    },\n    {\n        \"name\": \"worktree_create\",\n        \"description\": \"Create a git worktree and optionally bind it to a task.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"name\": {\"type\": \"string\"},\n                \"task_id\": {\"type\": \"integer\"},\n                \"base_ref\": {\"type\": \"string\"},\n            },\n            \"required\": [\"name\"],\n        },\n    },\n    {\n        \"name\": \"worktree_list\",\n        \"description\": \"List worktrees tracked in .worktrees/index.json.\",\n        \"input_schema\": {\"type\": \"object\", \"properties\": {}},\n    },\n    {\n        \"name\": \"worktree_status\",\n        \"description\": \"Show git status for one worktree.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\"name\": {\"type\": \"string\"}},\n            \"required\": [\"name\"],\n        },\n    },\n    {\n        \"name\": \"worktree_run\",\n        \"description\": \"Run a shell command in a named worktree directory.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"name\": {\"type\": \"string\"},\n                \"command\": {\"type\": \"string\"},\n            },\n            \"required\": [\"name\", \"command\"],\n        },\n    },\n    {\n        \"name\": \"worktree_remove\",\n        \"description\": \"Remove a worktree and optionally mark its bound task completed.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"name\": {\"type\": \"string\"},\n                \"force\": {\"type\": \"boolean\"},\n                \"complete_task\": {\"type\": \"boolean\"},\n            },\n            \"required\": [\"name\"],\n        },\n    },\n    {\n        \"name\": \"worktree_keep\",\n        \"description\": \"Mark a worktree as kept in lifecycle state without removing it.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\"name\": {\"type\": \"string\"}},\n            \"required\": [\"name\"],\n        },\n    },\n    {\n        \"name\": \"worktree_events\",\n        \"description\": \"List recent worktree/task lifecycle events from .worktrees/events.jsonl.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\"limit\": {\"type\": \"integer\"}},\n        },\n    },\n]\n\n\ndef agent_loop(messages: list):\n    while True:\n        response = client.messages.create(\n            model=MODEL,\n            system=SYSTEM,\n            messages=messages,\n            tools=TOOLS,\n            max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n        if response.stop_reason != \"tool_use\":\n            return\n\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                handler = TOOL_HANDLERS.get(block.name)\n                try:\n                    output = handler(**block.input) if handler else f\"Unknown tool: {block.name}\"\n                except Exception as e:\n                    output = f\"Error: {e}\"\n                print(f\"> {block.name}: {str(output)[:200]}\")\n                results.append(\n                    {\n                        \"type\": \"tool_result\",\n                        \"tool_use_id\": block.id,\n                        \"content\": str(output),\n                    }\n                )\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\nif __name__ == \"__main__\":\n    print(f\"Repo root for s12: {REPO_ROOT}\")\n    if not WORKTREES.git_available:\n        print(\"Note: Not in a git repo. worktree_* tools will return errors.\")\n\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms12 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n"
+      "layer": "platform",
+      "source": "#!/usr/bin/env python3\n# Harness: integration -- tools aren't just in your code.\n\"\"\"\ns19_mcp_plugin.py - MCP & Plugin System\n\nThis teaching chapter focuses on the smallest useful idea:\nexternal processes can expose tools, and your agent can treat them like\nnormal tools after a small amount of normalization.\n\nMinimal path:\n  1. start an MCP server process\n  2. ask it which tools it has\n  3. prefix and register those tools\n  4. route matching calls to that server\n\nPlugins add one more layer: discovery. A tiny manifest tells the agent which\nexternal server to start.\n\nKey insight: \"External tools should enter the same tool pipeline, not form a\ncompletely separate world.\" In practice that means shared permission checks\nand normalized tool_result payloads.\n\nRead this file in this order:\n1. CapabilityPermissionGate: external tools still go through the same control gate.\n2. MCPClient: how one server connection exposes tool specs and tool calls.\n3. PluginLoader: how manifests declare external servers.\n4. MCPToolRouter / build_tool_pool: how native and external tools merge into one pool.\n\nMost common confusion:\n- a plugin manifest is not an MCP server\n- an MCP server is not a single MCP tool\n- external capability does not bypass the native permission path\n\nTeaching boundary:\nthis file teaches the smallest useful stdio MCP path.\nMarketplace details, auth flows, reconnect logic, and non-tool capability layers\nare intentionally left to bridge docs and later extensions.\n\"\"\"\n\nimport json\nimport os\nimport subprocess\nimport threading\nfrom pathlib import Path\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv(override=True)\n\nif os.getenv(\"ANTHROPIC_BASE_URL\"):\n    os.environ.pop(\"ANTHROPIC_AUTH_TOKEN\", None)\n\nWORKDIR = Path.cwd()\nclient = Anthropic(base_url=os.getenv(\"ANTHROPIC_BASE_URL\"))\nMODEL = os.environ[\"MODEL_ID\"]\nPERMISSION_MODES = (\"default\", \"auto\")\n\n\nclass CapabilityPermissionGate:\n    \"\"\"\n    Shared permission gate for native tools and external capabilities.\n\n    The teaching goal is simple: MCP does not bypass the control plane.\n    Native tools and MCP tools both become normalized capability intents first,\n    then pass through the same allow / ask policy.\n    \"\"\"\n\n    READ_PREFIXES = (\"read\", \"list\", \"get\", \"show\", \"search\", \"query\", \"inspect\")\n    HIGH_RISK_PREFIXES = (\"delete\", \"remove\", \"drop\", \"shutdown\")\n\n    def __init__(self, mode: str = \"default\"):\n        self.mode = mode if mode in PERMISSION_MODES else \"default\"\n\n    def normalize(self, tool_name: str, tool_input: dict) -> dict:\n        if tool_name.startswith(\"mcp__\"):\n            _, server_name, actual_tool = tool_name.split(\"__\", 2)\n            source = \"mcp\"\n        else:\n            server_name = None\n            actual_tool = tool_name\n            source = \"native\"\n\n        lowered = actual_tool.lower()\n        if actual_tool == \"read_file\" or lowered.startswith(self.READ_PREFIXES):\n            risk = \"read\"\n        elif actual_tool == \"bash\":\n            command = tool_input.get(\"command\", \"\")\n            risk = \"high\" if any(\n                token in command for token in (\"rm -rf\", \"sudo\", \"shutdown\", \"reboot\")\n            ) else \"write\"\n        elif lowered.startswith(self.HIGH_RISK_PREFIXES):\n            risk = \"high\"\n        else:\n            risk = \"write\"\n\n        return {\n            \"source\": source,\n            \"server\": server_name,\n            \"tool\": actual_tool,\n            \"risk\": risk,\n        }\n\n    def check(self, tool_name: str, tool_input: dict) -> dict:\n        intent = self.normalize(tool_name, tool_input)\n\n        if intent[\"risk\"] == \"read\":\n            return {\"behavior\": \"allow\", \"reason\": \"Read capability\", \"intent\": intent}\n\n        if self.mode == \"auto\" and intent[\"risk\"] != \"high\":\n            return {\n                \"behavior\": \"allow\",\n                \"reason\": \"Auto mode for non-high-risk capability\",\n                \"intent\": intent,\n            }\n\n        if intent[\"risk\"] == \"high\":\n            return {\n                \"behavior\": \"ask\",\n                \"reason\": \"High-risk capability requires confirmation\",\n                \"intent\": intent,\n            }\n\n        return {\n            \"behavior\": \"ask\",\n            \"reason\": \"State-changing capability requires confirmation\",\n            \"intent\": intent,\n        }\n\n    def ask_user(self, intent: dict, tool_input: dict) -> bool:\n        preview = json.dumps(tool_input, ensure_ascii=False)[:200]\n        source = (\n            f\"{intent['source']}:{intent['server']}/{intent['tool']}\"\n            if intent.get(\"server\")\n            else f\"{intent['source']}:{intent['tool']}\"\n        )\n        print(f\"\\n  [Permission] {source} risk={intent['risk']}: {preview}\")\n        try:\n            answer = input(\"  Allow? (y/n): \").strip().lower()\n        except (EOFError, KeyboardInterrupt):\n            return False\n        return answer in (\"y\", \"yes\")\n\n\npermission_gate = CapabilityPermissionGate()\n\n\nclass MCPClient:\n    \"\"\"\n    Minimal MCP client over stdio.\n\n    This is enough to teach the core architecture without dragging readers\n    through every transport, auth flow, or marketplace detail up front.\n    \"\"\"\n\n    def __init__(self, server_name: str, command: str, args: list = None, env: dict = None):\n        self.server_name = server_name\n        self.command = command\n        self.args = args or []\n        self.env = {**os.environ, **(env or {})}\n        self.process = None\n        self._request_id = 0\n        self._tools = []  # cached tool list\n\n    def connect(self):\n        \"\"\"Start the MCP server process.\"\"\"\n        try:\n            self.process = subprocess.Popen(\n                [self.command] + self.args,\n                stdin=subprocess.PIPE,\n                stdout=subprocess.PIPE,\n                stderr=subprocess.PIPE,\n                env=self.env,\n                text=True,\n            )\n            # Send initialize request\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                # Send initialized notification\n                self._send({\"method\": \"notifications/initialized\"})\n                return True\n        except FileNotFoundError:\n            print(f\"[MCP] Server command not found: {self.command}\")\n        except Exception as e:\n            print(f\"[MCP] Connection failed: {e}\")\n        return False\n\n    def list_tools(self) -> list:\n        \"\"\"Fetch available tools from the server.\"\"\"\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: str, arguments: dict) -> str:\n        \"\"\"Execute a tool on the server.\"\"\"\n        self._send({\"method\": \"tools/call\", \"params\": {\n            \"name\": tool_name,\n            \"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        if response and \"error\" in response:\n            return f\"MCP Error: {response['error'].get('message', 'unknown')}\"\n        return \"MCP Error: no response\"\n\n    def get_agent_tools(self) -> list:\n        \"\"\"\n        Convert MCP tools to agent tool format.\n\n        Teaching version uses the same simple prefix idea:\n        mcp__{server_name}__{tool_name}\n        \"\"\"\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\", {\"type\": \"object\", \"properties\": {}}),\n                \"_mcp_server\": self.server_name,\n                \"_mcp_tool\": tool[\"name\"],\n            })\n        return agent_tools\n\n    def disconnect(self):\n        \"\"\"Shut down the server process.\"\"\"\n        if self.process:\n            try:\n                self._send({\"method\": \"shutdown\"})\n                self.process.terminate()\n                self.process.wait(timeout=5)\n            except Exception:\n                self.process.kill()\n            self.process = None\n\n    def _send(self, message: dict):\n        if not self.process or self.process.poll() is not None:\n            return\n        self._request_id += 1\n        envelope = {\"jsonrpc\": \"2.0\", \"id\": self._request_id, **message}\n        line = json.dumps(envelope) + \"\\n\"\n        try:\n            self.process.stdin.write(line)\n            self.process.stdin.flush()\n        except (BrokenPipeError, OSError):\n            pass\n\n    def _recv(self) -> dict | None:\n        if not self.process or self.process.poll() is not None:\n            return None\n        try:\n            line = self.process.stdout.readline()\n            if line:\n                return json.loads(line)\n        except (json.JSONDecodeError, OSError):\n            pass\n        return None\n\n\nclass PluginLoader:\n    \"\"\"\n    Load plugins from .claude-plugin/ directories.\n\n    Teaching version implements the smallest useful plugin flow:\n    read a manifest, discover MCP server configs, and register them.\n    \"\"\"\n\n    def __init__(self, search_dirs: list = None):\n        self.search_dirs = search_dirs or [WORKDIR]\n        self.plugins = {}  # name -> manifest\n\n    def scan(self) -> list:\n        \"\"\"Scan directories for .claude-plugin/plugin.json manifests.\"\"\"\n        found = []\n        for search_dir in self.search_dirs:\n            plugin_dir = Path(search_dir) / \".claude-plugin\"\n            manifest_path = plugin_dir / \"plugin.json\"\n            if manifest_path.exists():\n                try:\n                    manifest = json.loads(manifest_path.read_text())\n                    name = manifest.get(\"name\", plugin_dir.parent.name)\n                    self.plugins[name] = manifest\n                    found.append(name)\n                except (json.JSONDecodeError, OSError) as e:\n                    print(f\"[Plugin] Failed to load {manifest_path}: {e}\")\n        return found\n\n    def get_mcp_servers(self) -> dict:\n        \"\"\"\n        Extract MCP server configs from loaded plugins.\n        Returns {server_name: {command, args, env}}.\n        \"\"\"\n        servers = {}\n        for plugin_name, manifest in self.plugins.items():\n            for server_name, config in manifest.get(\"mcpServers\", {}).items():\n                servers[f\"{plugin_name}__{server_name}\"] = config\n        return servers\n\n\nclass MCPToolRouter:\n    \"\"\"\n    Routes tool calls to the correct MCP server.\n\n    MCP tools are prefixed mcp__{server}__{tool} and live alongside\n    native tools in the same tool pool. The router strips the prefix\n    and dispatches to the right MCPClient.\n    \"\"\"\n\n    def __init__(self):\n        self.clients = {}  # server_name -> MCPClient\n\n    def register_client(self, client: MCPClient):\n        self.clients[client.server_name] = client\n\n    def is_mcp_tool(self, tool_name: str) -> bool:\n        return tool_name.startswith(\"mcp__\")\n\n    def call(self, tool_name: str, arguments: dict) -> str:\n        \"\"\"Route an MCP tool call to the correct server.\"\"\"\n        parts = tool_name.split(\"__\", 2)\n        if len(parts) != 3:\n            return f\"Error: Invalid MCP tool name: {tool_name}\"\n        _, server_name, actual_tool = parts\n        client = self.clients.get(server_name)\n        if not client:\n            return f\"Error: MCP server not found: {server_name}\"\n        return client.call_tool(actual_tool, arguments)\n\n    def get_all_tools(self) -> list:\n        \"\"\"Collect tools from all connected MCP servers.\"\"\"\n        tools = []\n        for client in self.clients.values():\n            tools.extend(client.get_agent_tools())\n        return tools\n\n\n# -- Native tool implementations (same as s02) --\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_bash(command: str) -> str:\n    dangerous = [\"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\", \"> /dev/\"]\n    if any(d in command for d in dangerous):\n        return \"Error: Dangerous command blocked\"\n    try:\n        r = subprocess.run(command, shell=True, cwd=WORKDIR,\n                           capture_output=True, text=True, timeout=120)\n        out = (r.stdout + r.stderr).strip()\n        return out[:50000] if out else \"(no output)\"\n    except subprocess.TimeoutExpired:\n        return \"Error: Timeout (120s)\"\n\ndef run_read(path: str) -> str:\n    try:\n        return safe_path(path).read_text()[:50000]\n    except Exception as e:\n        return f\"Error: {e}\"\n\ndef run_write(path: str, content: str) -> str:\n    try:\n        fp = safe_path(path)\n        fp.parent.mkdir(parents=True, exist_ok=True)\n        fp.write_text(content)\n        return f\"Wrote {len(content)} bytes\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\ndef run_edit(path: str, old_text: str, new_text: str) -> str:\n    try:\n        fp = safe_path(path)\n        content = fp.read_text()\n        if old_text not in content:\n            return f\"Error: Text not found in {path}\"\n        fp.write_text(content.replace(old_text, new_text, 1))\n        return f\"Edited {path}\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n\nNATIVE_HANDLERS = {\n    \"bash\":       lambda **kw: run_bash(kw[\"command\"]),\n    \"read_file\":  lambda **kw: run_read(kw[\"path\"]),\n    \"write_file\": lambda **kw: run_write(kw[\"path\"], kw[\"content\"]),\n    \"edit_file\":  lambda **kw: run_edit(kw[\"path\"], kw[\"old_text\"], kw[\"new_text\"]),\n}\n\nNATIVE_TOOLS = [\n    {\"name\": \"bash\", \"description\": \"Run a shell command.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}},\n    {\"name\": \"read_file\", \"description\": \"Read file contents.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}}, \"required\": [\"path\"]}},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}},\n    {\"name\": \"edit_file\", \"description\": \"Replace exact text in file.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"old_text\": {\"type\": \"string\"}, \"new_text\": {\"type\": \"string\"}}, \"required\": [\"path\", \"old_text\", \"new_text\"]}},\n]\n\n\n# -- MCP Tool Router (global) --\nmcp_router = MCPToolRouter()\nplugin_loader = PluginLoader()\n\n\ndef build_tool_pool() -> list:\n    \"\"\"\n    Assemble the complete tool pool: native + MCP tools.\n\n    Native tools take precedence on name conflicts so the local core remains\n    predictable even after external tools are added.\n    \"\"\"\n    all_tools = list(NATIVE_TOOLS)\n    mcp_tools = mcp_router.get_all_tools()\n\n    native_names = {t[\"name\"] for t in all_tools}\n    for tool in mcp_tools:\n        if tool[\"name\"] not in native_names:\n            all_tools.append(tool)\n\n    return all_tools\n\n\ndef handle_tool_call(tool_name: str, tool_input: dict) -> str:\n    \"\"\"Dispatch to native handler or MCP router.\"\"\"\n    if mcp_router.is_mcp_tool(tool_name):\n        return mcp_router.call(tool_name, tool_input)\n    handler = NATIVE_HANDLERS.get(tool_name)\n    if handler:\n        return handler(**tool_input)\n    return f\"Unknown tool: {tool_name}\"\n\n\ndef normalize_tool_result(tool_name: str, output: str, intent: dict | None = None) -> str:\n    intent = intent or permission_gate.normalize(tool_name, {})\n    status = \"error\" if \"Error:\" in output or \"MCP Error:\" in output else \"ok\"\n    payload = {\n        \"source\": intent[\"source\"],\n        \"server\": intent.get(\"server\"),\n        \"tool\": intent[\"tool\"],\n        \"risk\": intent[\"risk\"],\n        \"status\": status,\n        \"preview\": output[:500],\n    }\n    return json.dumps(payload, indent=2, ensure_ascii=False)\n\n\ndef agent_loop(messages: list):\n    \"\"\"Agent loop with unified native + MCP tool pool.\"\"\"\n    tools = build_tool_pool()\n\n    while True:\n        system = (\n            f\"You are a coding agent at {WORKDIR}. Use tools to solve tasks.\\n\"\n            \"You have both native tools and MCP tools available.\\n\"\n            \"MCP tools are prefixed with mcp__{server}__{tool}.\\n\"\n            \"All capabilities pass through the same permission gate before execution.\"\n        )\n        response = client.messages.create(\n            model=MODEL, system=system, messages=messages,\n            tools=tools, max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n\n        if response.stop_reason != \"tool_use\":\n            return\n\n        results = []\n        for block in response.content:\n            if block.type != \"tool_use\":\n                continue\n            decision = permission_gate.check(block.name, block.input or {})\n            try:\n                if decision[\"behavior\"] == \"deny\":\n                    output = f\"Permission denied: {decision['reason']}\"\n                elif decision[\"behavior\"] == \"ask\" and not permission_gate.ask_user(\n                    decision[\"intent\"], block.input or {}\n                ):\n                    output = f\"Permission denied by user: {decision['reason']}\"\n                else:\n                    output = handle_tool_call(block.name, block.input or {})\n            except Exception as e:\n                output = f\"Error: {e}\"\n            print(f\"> {block.name}: {str(output)[:200]}\")\n            results.append({\n                \"type\": \"tool_result\",\n                \"tool_use_id\": block.id,\n                \"content\": normalize_tool_result(\n                    block.name,\n                    str(output),\n                    decision.get(\"intent\"),\n                ),\n            })\n\n        messages.append({\"role\": \"user\", \"content\": results})\n\n\n# Further upgrades you can add later:\n# - more transports\n# - auth / approval flows\n# - server reconnect and lifecycle management\n# - filtering external tools before they reach the model\n# - richer plugin installation and update handling\n\n\nif __name__ == \"__main__\":\n    # Scan for plugins\n    found = plugin_loader.scan()\n    if found:\n        print(f\"[Plugins loaded: {', '.join(found)}]\")\n        for server_name, config in plugin_loader.get_mcp_servers().items():\n            mcp_client = MCPClient(server_name, config.get(\"command\", \"\"), config.get(\"args\", []))\n            if mcp_client.connect():\n                mcp_client.list_tools()\n                mcp_router.register_client(mcp_client)\n                print(f\"[MCP] Connected to {server_name}\")\n\n    tool_count = len(build_tool_pool())\n    mcp_count = len(mcp_router.get_all_tools())\n    print(f\"[Tool pool: {tool_count} tools ({mcp_count} from MCP)]\")\n\n    history = []\n    while True:\n        try:\n            query = input(\"\\033[36ms19 >> \\033[0m\")\n        except (EOFError, KeyboardInterrupt):\n            break\n        if query.strip().lower() in (\"q\", \"exit\", \"\"):\n            break\n\n        if query.strip() == \"/tools\":\n            for tool in build_tool_pool():\n                prefix = \"[MCP] \" if tool[\"name\"].startswith(\"mcp__\") else \"       \"\n                print(f\"  {prefix}{tool['name']}: {tool.get('description', '')[:60]}\")\n            continue\n\n        if query.strip() == \"/mcp\":\n            if mcp_router.clients:\n                for name, c in mcp_router.clients.items():\n                    tools = c.get_agent_tools()\n                    print(f\"  {name}: {len(tools)} tools\")\n            else:\n                print(\"  (no MCP servers connected)\")\n            continue\n\n        history.append({\"role\": \"user\", \"content\": query})\n        agent_loop(history)\n        response_content = history[-1][\"content\"]\n        if isinstance(response_content, list):\n            for block in response_content:\n                if hasattr(block, \"text\"):\n                    print(block.text)\n        print()\n\n    # Cleanup MCP connections\n    for c in mcp_router.clients.values():\n        c.disconnect()\n"
     }
   ],
   "diffs": [
@@ -837,68 +1467,150 @@
         "safe_path",
         "run_read",
         "run_write",
-        "run_edit"
+        "run_edit",
+        "normalize_messages"
       ],
       "newTools": [
         "read_file",
         "write_file",
         "edit_file"
       ],
-      "locDelta": 36
+      "locDelta": 39
     },
     {
       "from": "s02",
       "to": "s03",
       "newClasses": [
+        "PlanItem",
+        "PlanningState",
         "TodoManager"
       ],
-      "newFunctions": [],
+      "newFunctions": [
+        "extract_text"
+      ],
       "newTools": [
         "todo"
       ],
-      "locDelta": 56
+      "locDelta": 110
     },
     {
       "from": "s03",
       "to": "s04",
-      "newClasses": [],
+      "newClasses": [
+        "AgentTemplate"
+      ],
       "newFunctions": [
         "run_subagent"
       ],
       "newTools": [
         "task"
       ],
-      "locDelta": -25
+      "locDelta": -79
     },
     {
       "from": "s04",
       "to": "s05",
       "newClasses": [
-        "SkillLoader"
+        "SkillManifest",
+        "SkillDocument",
+        "SkillRegistry"
+      ],
+      "newFunctions": [
+        "extract_text"
       ],
-      "newFunctions": [],
       "newTools": [
         "load_skill"
       ],
-      "locDelta": 36
+      "locDelta": 44
     },
     {
       "from": "s05",
       "to": "s06",
-      "newClasses": [],
+      "newClasses": [
+        "CompactState"
+      ],
       "newFunctions": [
-        "estimate_tokens",
+        "estimate_context_size",
+        "track_recent_file",
+        "persist_large_output",
+        "collect_tool_result_blocks",
         "micro_compact",
-        "auto_compact"
+        "write_transcript",
+        "summarize_history",
+        "compact_history",
+        "execute_tool"
       ],
       "newTools": [
         "compact"
       ],
-      "locDelta": 18
+      "locDelta": 64
     },
     {
       "from": "s06",
       "to": "s07",
+      "newClasses": [
+        "BashSecurityValidator",
+        "PermissionManager"
+      ],
+      "newFunctions": [
+        "is_workspace_trusted"
+      ],
+      "newTools": [],
+      "locDelta": 0
+    },
+    {
+      "from": "s07",
+      "to": "s08",
+      "newClasses": [
+        "HookManager"
+      ],
+      "newFunctions": [],
+      "newTools": [],
+      "locDelta": -56
+    },
+    {
+      "from": "s08",
+      "to": "s09",
+      "newClasses": [
+        "MemoryManager",
+        "DreamConsolidator"
+      ],
+      "newFunctions": [
+        "run_save_memory",
+        "build_system_prompt"
+      ],
+      "newTools": [
+        "save_memory"
+      ],
+      "locDelta": 162
+    },
+    {
+      "from": "s09",
+      "to": "s10",
+      "newClasses": [
+        "SystemPromptBuilder"
+      ],
+      "newFunctions": [
+        "build_system_reminder"
+      ],
+      "newTools": [],
+      "locDelta": -109
+    },
+    {
+      "from": "s10",
+      "to": "s11",
+      "newClasses": [],
+      "newFunctions": [
+        "estimate_tokens",
+        "auto_compact",
+        "backoff_delay"
+      ],
+      "newTools": [],
+      "locDelta": -56
+    },
+    {
+      "from": "s11",
+      "to": "s12",
       "newClasses": [
         "TaskManager"
       ],
@@ -909,12 +1621,13 @@
         "task_list",
         "task_get"
       ],
-      "locDelta": 2
+      "locDelta": -22
     },
     {
-      "from": "s07",
-      "to": "s08",
+      "from": "s12",
+      "to": "s13",
       "newClasses": [
+        "NotificationQueue",
         "BackgroundManager"
       ],
       "newFunctions": [],
@@ -922,11 +1635,29 @@
         "background_run",
         "check_background"
       ],
-      "locDelta": -9
+      "locDelta": 60
     },
     {
-      "from": "s08",
-      "to": "s09",
+      "from": "s13",
+      "to": "s14",
+      "newClasses": [
+        "CronLock",
+        "CronScheduler"
+      ],
+      "newFunctions": [
+        "cron_matches",
+        "_field_matches"
+      ],
+      "newTools": [
+        "cron_create",
+        "cron_delete",
+        "cron_list"
+      ],
+      "locDelta": 165
+    },
+    {
+      "from": "s14",
+      "to": "s15",
       "newClasses": [
         "MessageBus",
         "TeammateManager"
@@ -946,12 +1677,14 @@
         "list_teammates",
         "broadcast"
       ],
-      "locDelta": 150
+      "locDelta": -102
     },
     {
-      "from": "s09",
-      "to": "s10",
-      "newClasses": [],
+      "from": "s15",
+      "to": "s16",
+      "newClasses": [
+        "RequestStore"
+      ],
       "newFunctions": [
         "handle_shutdown_request",
         "handle_plan_review",
@@ -962,26 +1695,29 @@
         "plan_approval",
         "shutdown_request"
       ],
-      "locDelta": 71
+      "locDelta": 132
     },
     {
-      "from": "s10",
-      "to": "s11",
+      "from": "s16",
+      "to": "s17",
       "newClasses": [],
       "newFunctions": [
+        "_append_claim_event",
+        "_task_allows_role",
+        "is_claimable_task",
         "scan_unclaimed_tasks",
-        "claim_task",
-        "make_identity_block"
+        "make_identity_block",
+        "ensure_identity_context"
       ],
       "newTools": [
         "idle",
         "claim_task"
       ],
-      "locDelta": 80
+      "locDelta": 121
     },
     {
-      "from": "s11",
-      "to": "s12",
+      "from": "s17",
+      "to": "s18",
       "newClasses": [
         "EventBus",
         "TaskManager",
@@ -1003,13 +1739,32 @@
         "task_bind_worktree",
         "worktree_create",
         "worktree_list",
+        "worktree_enter",
         "worktree_status",
         "worktree_run",
+        "worktree_closeout",
         "worktree_remove",
         "worktree_keep",
         "worktree_events"
       ],
-      "locDelta": 195
+      "locDelta": -39
+    },
+    {
+      "from": "s18",
+      "to": "s19",
+      "newClasses": [
+        "CapabilityPermissionGate",
+        "MCPClient",
+        "PluginLoader",
+        "MCPToolRouter"
+      ],
+      "newFunctions": [
+        "build_tool_pool",
+        "handle_tool_call",
+        "normalize_tool_result"
+      ],
+      "newTools": [],
+      "locDelta": -101
     }
   ]
 }
\ No newline at end of file
diff --git a/web/src/i18n/messages/en.json b/web/src/i18n/messages/en.json
index 6dcb3effb..9fd25bcfd 100644
--- a/web/src/i18n/messages/en.json
+++ b/web/src/i18n/messages/en.json
@@ -1,24 +1,155 @@
 {
-  "meta": { "title": "Learn Claude Code", "description": "Build a nano Claude Code-like agent from 0 to 1, one mechanism at a time" },
-  "nav": { "home": "Home", "timeline": "Timeline", "compare": "Compare", "layers": "Layers", "github": "GitHub" },
-  "home": { "hero_title": "Learn Claude Code", "hero_subtitle": "Build a nano Claude Code-like agent from 0 to 1, one mechanism at a time", "start": "Start Learning", "core_pattern": "The Core Pattern", "core_pattern_desc": "Every AI coding agent shares the same loop: call the model, execute tools, feed results back. Production systems add policy, permissions, and lifecycle layers on top.", "learning_path": "Learning Path", "learning_path_desc": "12 progressive sessions, from a simple loop to isolated autonomous execution", "layers_title": "Architectural Layers", "layers_desc": "Five orthogonal concerns that compose into a complete agent", "loc": "LOC", "learn_more": "Learn More", "versions_in_layer": "versions", "message_flow": "Message Growth", "message_flow_desc": "Watch the messages array grow as the agent loop executes" },
-  "version": { "loc": "lines of code", "tools": "tools", "new": "New", "prev": "Previous", "next": "Next", "view_source": "View Source", "view_diff": "View Diff", "design_decisions": "Design Decisions", "whats_new": "What's New", "tutorial": "Tutorial", "simulator": "Agent Loop Simulator", "execution_flow": "Execution Flow", "architecture": "Architecture", "concept_viz": "Concept Visualization", "alternatives": "Alternatives Considered", "tab_learn": "Learn", "tab_simulate": "Simulate", "tab_code": "Code", "tab_deep_dive": "Deep Dive" },
-  "sim": { "play": "Play", "pause": "Pause", "step": "Step", "reset": "Reset", "speed": "Speed", "step_of": "of" },
-  "timeline": { "title": "Learning Path", "subtitle": "s01 to s12: Progressive Agent Design", "layer_legend": "Layer Legend", "loc_growth": "LOC Growth", "learn_more": "Learn More" },
+  "meta": {
+    "title": "Learn Claude Code",
+    "description": "19 chapters, 4 stages, from zero to a high-completion Claude Code-like agent"
+  },
+  "nav": {
+    "home": "Home",
+    "reference": "Reference",
+    "compare": "Compare",
+    "github": "GitHub"
+  },
+  "reference": {
+    "title": "Reference",
+    "subtitle": "Glossary, architecture maps, and deep dive companion docs.",
+    "foundation_title": "Foundation Documents",
+    "deep_dive_title": "Deep Dive Documents"
+  },
+  "home": {
+    "hero_title": "Learn Claude Code",
+    "hero_subtitle": "19 chapters across 4 stages, from the minimal loop to a multi-agent platform and external capability bus",
+    "start": "Start Learning",
+    "entry_title": "Four Strong Entry Points",
+    "entry_desc": "If this is your first time here, do not jump into random chapters. Decide whether you want the mainline, the stage map, or a chapter jump comparison first.",
+    "entry_start_title": "Start From the Minimal Loop",
+    "entry_start_desc": "Best for first-time readers. Get the smallest agent loop working before you add tools, planning, and context management.",
+    "entry_start_action": "Open s01",
+    "entry_timeline_title": "Follow the Full Mainline",
+    "entry_timeline_desc": "Best if you want the full teaching sequence. You will see how the system grows chapter by chapter.",
+    "entry_timeline_action": "Open Timeline",
+    "entry_layers_title": "Understand the Four Stages First",
+    "entry_layers_desc": "Best if you want to understand why the repository is split into stages before diving into chapter detail.",
+    "entry_layers_action": "Open Stages",
+    "entry_compare_title": "Compare Two Steps When You Get Stuck",
+    "entry_compare_desc": "Best if you are already mid-way through the course and want to see exactly what capability one chapter adds over another.",
+    "entry_compare_action": "Open Compare",
+    "core_pattern": "The Core Pattern",
+    "core_pattern_desc": "Every AI coding agent grows from the same loop: call the model, execute tools, append results. Permissions, memory, tasks, teams, and plugins all extend that same loop rather than replacing it.",
+    "learning_path": "Learning Path",
+    "learning_path_desc": "19 progressive chapters grouped into core loop, system hardening, task runtime, and multi-agent platform stages",
+    "layers_title": "Four Stages",
+    "layers_desc": "The goal is not to dump details, but to teach the system in the order a developer can actually absorb and rebuild it.",
+    "guide_label": "Reading Guide",
+    "guide_start_title": "First Read: Lock In The Core Loop",
+    "guide_start_desc": "If you have not really internalized s01-s06 yet, do not rush into multi-agent or MCP. Build the single-agent loop first.",
+    "guide_middle_title": "Middle Read: Separate The State Layers",
+    "guide_middle_desc": "When task, runtime task, teammate, and worktree begin to blur together, step back and re-check the phase boundaries.",
+    "guide_finish_title": "Late Read: Watch The Platform Boundary",
+    "guide_finish_desc": "From s15 onward, the main question is not just more features. It is how the system boundary expands into multiple workers and external capabilities.",
+    "loc": "LOC",
+    "learn_more": "Learn More",
+    "versions_in_layer": "chapters",
+    "message_flow": "Message Growth",
+    "message_flow_desc": "Watch how messages[] grows during a real agent loop with tool calls and results"
+  },
+  "version": {
+    "loc": "lines of code",
+    "tools": "tools",
+    "new": "New",
+    "prev": "Previous",
+    "next": "Next",
+    "view_source": "View Source",
+    "view_diff": "View Diff",
+    "design_decisions": "Design Decisions",
+    "whats_new": "What's New",
+    "tutorial": "Tutorial",
+    "simulator": "Chapter Simulator",
+    "execution_flow": "Execution Flow",
+    "architecture": "Architecture",
+    "concept_viz": "Concept Visualization",
+    "alternatives": "Alternatives Considered",
+    "tab_learn": "Learn",
+    "tab_simulate": "Simulate",
+    "tab_code": "Code",
+    "tab_deep_dive": "Deep Dive",
+    "guide_label": "Chapter Guide",
+    "guide_addition_title": "Core Structure Added In This Chapter",
+    "guide_addition_empty": "This chapter mainly connects and hardens existing structures rather than introducing one brand-new major module.",
+    "guide_focus_title": "What To Focus On First",
+    "guide_focus_fallback": "Start with the core input, state, and output relationship before you dive into implementation detail.",
+    "guide_confusion_title": "What People Usually Mix Up",
+    "guide_confusion_fallback": "If concepts start to blur, return to the question this mechanism solves and the extra capability it adds over the previous chapter.",
+    "guide_goal_title": "What You Should Be Able To Build Afterward",
+    "guide_goal_fallback": "After this chapter, you should be able to reconnect this mechanism into your own agent system.",
+    "bridge_docs_label": "Bridge Reading",
+    "bridge_docs_title": "Deep Dives -- Optional Reading",
+    "bridge_docs_intro": "These companion pages clarify the concepts most likely to blur in this chapter. Read them when you feel confused, not as prerequisites.",
+    "bridge_docs_open": "Open Note",
+    "bridge_docs_kind_map": "Map",
+    "bridge_docs_kind_mechanism": "Mechanism",
+    "bridge_docs_fallback": "Fallback",
+    "bridge_docs_back": "Back To Learning Path",
+    "bridge_docs_standalone": "Deep Dive",
+    "bridge_docs_fallback_note": "This document is not available in the current locale. Showing fallback:"
+  },
+  "sim": {
+    "play": "Play",
+    "pause": "Pause",
+    "step": "Step",
+    "previous_step": "Previous step",
+    "next_step": "Next step",
+    "autoplay": "Auto-play",
+    "reset": "Reset",
+    "speed": "Speed",
+    "step_of": "of"
+  },
+  "timeline": {
+    "title": "Learning Path",
+    "subtitle": "s01 to s19: build the agent system progressively across 4 stages",
+    "layer_legend": "Stage Legend",
+    "loc_growth": "LOC Growth",
+    "learn_more": "Learn More"
+  },
   "layers": {
-    "title": "Architectural Layers",
-    "subtitle": "Five orthogonal concerns that compose into a complete agent",
-    "tools": "What the agent CAN do. The foundation: tools give the model capabilities to interact with the world.",
-    "planning": "How work is organized. From simple todo lists to dependency-aware task boards shared across agents.",
-    "memory": "Keeping context within limits. Compression strategies that let agents work infinitely without losing coherence.",
-    "concurrency": "Non-blocking execution. Background threads and notification buses for parallel work.",
-    "collaboration": "Multi-agent coordination. Teams, messaging, and autonomous teammates that think for themselves."
+    "title": "Architecture Stages",
+    "subtitle": "Start from the smallest working loop, then add control, durability, background execution, multi-agent coordination, and external capability routing.",
+    "guide_label": "How To Read",
+    "guide_start_title": "If This Is Your First Pass",
+    "guide_start_desc": "Start at the first stage. Do not skip the core loop, because every later capability wraps around it.",
+    "guide_middle_title": "If The Middle Starts To Blur",
+    "guide_middle_desc": "Check which stage a chapter belongs to first. Then ask whether it is adding safety, state, runtime behavior, or platform surface.",
+    "guide_finish_title": "If You Want To Rebuild It Yourself",
+    "guide_finish_desc": "After each stage, you should end up with one real system slice you could implement, not just more vocabulary.",
+    "core": "Core Loop: build the smallest useful single-agent system first, including tools, planning, delegation, skills, and context compaction.",
+    "core_outcome": "After this stage, you should be able to build a working single-agent harness on your own.",
+    "hardening": "System Hardening: move from 'it runs' to 'it runs safely and predictably' with permissions, hooks, memory, prompt assembly, and error recovery.",
+    "hardening_outcome": "After this stage, you should know how to make the agent safer, steadier, and easier to extend.",
+    "runtime": "Task Runtime: turn work from session-local planning into durable, background, and scheduled execution.",
+    "runtime_outcome": "After this stage, you should be able to lift chat-level steps into a durable runtime task system.",
+    "platform": "Multi-Agent Platform: add persistent teammates, protocols, autonomy, isolated execution lanes, and MCP / plugin capability routing.",
+    "platform_outcome": "After this stage, you should be able to grow a single agent into a collaborative platform."
   },
   "compare": {
-    "title": "Compare Versions",
-    "subtitle": "See what changed between any two versions",
-    "select_a": "Version A",
-    "select_b": "Version B",
+    "title": "Learning Path Compare",
+    "subtitle": "Compare what capability is introduced between two chapters, why it appears there, and what you should focus on first.",
+    "learning_jump": "Learning Jump",
+    "selector_title": "Choose the step you want to compare",
+    "selector_note": "This page is designed to explain capability shifts before it throws you into code-level detail.",
+    "select_a": "Chapter A",
+    "select_b": "Chapter B",
+    "select_placeholder": "-- select --",
+    "carry_from_a": "Carry From A",
+    "new_in_b": "New In B",
+    "progression": "Progression",
+    "progression_same_chapter": "You selected the same chapter twice. Useful for rereading one chapter, not for studying a capability jump.",
+    "progression_reverse": "This is a backward-looking comparison. Use it to see which ideas in a later system actually come from earlier chapters.",
+    "progression_direct": "This is the next natural step in the path. It is the best way to study how the system grows chapter by chapter.",
+    "progression_same_layer": "Both chapters stay in the same capability layer, so the focus is on making one idea deeper and more complete.",
+    "progression_cross_layer": "This comparison crosses into a new capability layer, so the important question is how the system boundary changes.",
+    "chapter_distance": "Chapter Distance",
+    "shared_tools_count": "Shared Tools",
+    "new_surface": "New Surface Area",
+    "empty_lead": "No short chapter thesis was extracted for this chapter yet.",
     "loc_delta": "LOC Delta",
     "lines": "lines",
     "new_tools_in_b": "New Tools in B",
@@ -28,49 +159,66 @@
     "only_in": "Only in",
     "shared": "Shared",
     "none": "None",
-    "source_diff": "Source Code Diff",
-    "empty_hint": "Select two versions above to compare them.",
-    "architecture": "Architecture"
+    "source_diff": "Source Diff (Optional)",
+    "source_diff_note": "If you care about implementation detail, read the diff next. If you only care about the mechanism, the learning cards above should be enough.",
+    "empty_hint": "Choose two chapters first, then inspect what capability the upgrade actually adds.",
+    "architecture": "Architecture",
+    "architecture_note": "Read module boundaries and collaboration first, then drop into implementation detail only if you need it."
   },
   "diff": {
     "new_classes": "New Classes",
     "new_tools": "New Tools",
     "new_functions": "New Functions",
-    "loc_delta": "LOC Delta"
+    "loc_delta": "LOC Delta",
+    "view_unified": "Unified",
+    "view_split": "Split"
   },
   "sessions": {
     "s01": "The Agent Loop",
-    "s02": "Tools",
+    "s02": "Tool Use",
     "s03": "TodoWrite",
-    "s04": "Subagents",
+    "s04": "Subagent",
     "s05": "Skills",
-    "s06": "Compact",
-    "s07": "Tasks",
-    "s08": "Background Tasks",
-    "s09": "Agent Teams",
-    "s10": "Team Protocols",
-    "s11": "Autonomous Agents",
-    "s12": "Worktree + Task Isolation"
+    "s06": "Context Compact",
+    "s07": "Permission System",
+    "s08": "Hook System",
+    "s09": "Memory System",
+    "s10": "System Prompt",
+    "s11": "Error Recovery",
+    "s12": "Task System",
+    "s13": "Background Tasks",
+    "s14": "Cron Scheduler",
+    "s15": "Agent Teams",
+    "s16": "Team Protocols",
+    "s17": "Autonomous Agents",
+    "s18": "Worktree Isolation",
+    "s19": "MCP & Plugin"
   },
   "layer_labels": {
-    "tools": "Tools & Execution",
-    "planning": "Planning & Coordination",
-    "memory": "Memory Management",
-    "concurrency": "Concurrency",
-    "collaboration": "Collaboration"
+    "core": "Core Loop",
+    "hardening": "System Hardening",
+    "runtime": "Task Runtime",
+    "platform": "Multi-Agent Platform"
   },
   "viz": {
     "s01": "The Agent While-Loop",
     "s02": "Tool Dispatch Map",
-    "s03": "TodoWrite Nag System",
+    "s03": "TodoWrite Reminder Loop",
     "s04": "Subagent Context Isolation",
     "s05": "On-Demand Skill Loading",
-    "s06": "Three-Layer Context Compression",
-    "s07": "Task Dependency Graph",
-    "s08": "Background Task Lanes",
-    "s09": "Agent Team Mailboxes",
-    "s10": "FSM Team Protocols",
-    "s11": "Autonomous Agent Cycle",
-    "s12": "Worktree Task Isolation"
+    "s06": "Three-Layer Context Compaction",
+    "s07": "Permission Gate",
+    "s08": "Lifecycle Hook Surface",
+    "s09": "Long-Term vs Short-Term Memory",
+    "s10": "Prompt Assembly Pipeline",
+    "s11": "Recovery Branch State Machine",
+    "s12": "Task Dependency Graph",
+    "s13": "Background Task Lanes",
+    "s14": "Cron Trigger Pipeline",
+    "s15": "Agent Team Mailboxes",
+    "s16": "Protocol Sequence Diagram",
+    "s17": "Autonomous Agent Cycle",
+    "s18": "Worktree Task Isolation",
+    "s19": "External Capability Bus"
   }
 }
diff --git a/web/src/i18n/messages/ja.json b/web/src/i18n/messages/ja.json
index 25192d20d..8992c43f2 100644
--- a/web/src/i18n/messages/ja.json
+++ b/web/src/i18n/messages/ja.json
@@ -1,76 +1,224 @@
 {
-  "meta": { "title": "Learn Claude Code", "description": "0 から 1 へ nano Claude Code-like agent を構築し、毎回 1 つの仕組みを追加" },
-  "nav": { "home": "ホーム", "timeline": "学習パス", "compare": "バージョン比較", "layers": "アーキテクチャ層", "github": "GitHub" },
-  "home": { "hero_title": "Learn Claude Code", "hero_subtitle": "0 から 1 へ nano Claude Code-like agent を構築し、毎回 1 つの仕組みを追加", "start": "学習を始める", "core_pattern": "コアパターン", "core_pattern_desc": "すべての AI コーディングエージェントは同じループを共有する：モデルを呼び出し、ツールを実行し、結果を返す。実運用ではこの上にポリシー、権限、ライフサイクル層が重なる。", "learning_path": "学習パス", "learning_path_desc": "12の段階的セッション、シンプルなループから分離された自律実行まで", "layers_title": "アーキテクチャ層", "layers_desc": "5つの直交する関心事が完全なエージェントを構成", "loc": "行", "learn_more": "詳細を見る", "versions_in_layer": "バージョン", "message_flow": "メッセージの増加", "message_flow_desc": "エージェントループ実行時のメッセージ配列の成長を観察" },
-  "version": { "loc": "行のコード", "tools": "ツール", "new": "新規", "prev": "前のバージョン", "next": "次のバージョン", "view_source": "ソースを見る", "view_diff": "差分を見る", "design_decisions": "設計判断", "whats_new": "新機能", "tutorial": "チュートリアル", "simulator": "エージェントループシミュレーター", "execution_flow": "実行フロー", "architecture": "アーキテクチャ", "concept_viz": "コンセプト可視化", "alternatives": "検討された代替案", "tab_learn": "学習", "tab_simulate": "シミュレーション", "tab_code": "ソースコード", "tab_deep_dive": "詳細分析" },
-  "sim": { "play": "再生", "pause": "一時停止", "step": "ステップ", "reset": "リセット", "speed": "速度", "step_of": "/" },
-  "timeline": { "title": "学習パス", "subtitle": "s01からs12へ：段階的エージェント設計", "layer_legend": "レイヤー凡例", "loc_growth": "コード量の推移", "learn_more": "詳細を見る" },
+  "meta": {
+    "title": "Learn Claude Code",
+    "description": "19章・4段階で、0から高完成度の Claude Code-like agent を組み立てる"
+  },
+  "nav": {
+    "home": "ホーム",
+    "reference": "リファレンス",
+    "compare": "比較",
+    "github": "GitHub"
+  },
+  "reference": {
+    "title": "リファレンス",
+    "subtitle": "用語集、アーキテクチャ地図、深掘り補助ドキュメント。",
+    "foundation_title": "基礎ドキュメント",
+    "deep_dive_title": "深掘りドキュメント"
+  },
+  "home": {
+    "hero_title": "Learn Claude Code",
+    "hero_subtitle": "最小ループからマルチエージェント基盤と外部 capability bus まで、19章を4段階で学ぶ",
+    "start": "学習を始める",
+    "entry_title": "最初に選びやすい4つの入口",
+    "entry_desc": "初めて来たなら、いきなり章をばらばらに開かない方がよいです。順番に進むのか、段階で見るのか、差分で見るのかを先に決めます。",
+    "entry_start_title": "最小ループから始める",
+    "entry_start_desc": "初学者向けの最良の入口です。まず最小の agent loop を動かし、その後に tool、planning、context 管理を足します。",
+    "entry_start_action": "s01 を開く",
+    "entry_timeline_title": "主線を順番にたどる",
+    "entry_timeline_desc": "教材の流れを最初から最後まで追いたい人向けです。システムが章ごとにどう育つかを見られます。",
+    "entry_timeline_action": "タイムラインへ",
+    "entry_layers_title": "先に4段階をつかむ",
+    "entry_layers_desc": "章に入る前に、なぜこの教材が段階に分かれているのかを先につかみたい人向けです。",
+    "entry_layers_action": "段階ページへ",
+    "entry_compare_title": "詰まったら2章を比較する",
+    "entry_compare_desc": "学習途中で章の境界がぼやけたときに向いています。ある章が前の章に対して何を増やしたのかを見やすくします。",
+    "entry_compare_action": "比較ページへ",
+    "core_pattern": "コアパターン",
+    "core_pattern_desc": "すべての AI コーディングエージェントは同じループから成長する。モデルを呼び、ツールを実行し、結果を戻す。権限、記憶、タスク、チーム、プラグインはこのループを置き換えるのではなく拡張する。",
+    "learning_path": "学習パス",
+    "learning_path_desc": "19の段階的な章を、コアループ・システム強化・タスクランタイム・マルチエージェント基盤の4段階で構成",
+    "layers_title": "4つの段階",
+    "layers_desc": "細部を一気に詰め込むのではなく、開発者が無理なく再実装できる順序でシステムを学ぶための分解です。",
+    "guide_label": "読み方",
+    "guide_start_title": "最初はコアループを固める",
+    "guide_start_desc": "s01-s06 がまだ身体に入っていないなら、マルチエージェントや MCP へ急がず、まず単一 agent の主ループを固めます。",
+    "guide_middle_title": "中盤では状態の層を分ける",
+    "guide_middle_desc": "task、runtime task、teammate、worktree が混ざり始めたら、段階境界とデータ構造の地図へ一度戻るべきです。",
+    "guide_finish_title": "後半では基盤境界を見る",
+    "guide_finish_desc": "s15 以降は、機能が増えること自体よりも、単一実行者から複数実行レーンと外部能力へどう境界が広がるかが大事です。",
+    "loc": "行",
+    "learn_more": "詳しく見る",
+    "versions_in_layer": "章",
+    "message_flow": "メッセージの増加",
+    "message_flow_desc": "実際の agent ループで messages[] がどのように伸びていくかを観察する"
+  },
+  "version": {
+    "loc": "行のコード",
+    "tools": "ツール",
+    "new": "新規",
+    "prev": "前の章",
+    "next": "次の章",
+    "view_source": "ソースを見る",
+    "view_diff": "差分を見る",
+    "design_decisions": "設計判断",
+    "whats_new": "新しく加わるもの",
+    "tutorial": "チュートリアル",
+    "simulator": "章シミュレーター",
+    "execution_flow": "実行フロー",
+    "architecture": "アーキテクチャ",
+    "concept_viz": "概念可視化",
+    "alternatives": "検討した代替案",
+    "tab_learn": "学習",
+    "tab_simulate": "シミュレーション",
+    "tab_code": "コード",
+    "tab_deep_dive": "深掘り",
+    "guide_label": "章ガイド",
+    "guide_addition_title": "この章で増える中核構造",
+    "guide_addition_empty": "この章は、まったく新しい大きなモジュールを足すというより、既存の構造をつなぎ直して強める章です。",
+    "guide_focus_title": "最初に注目する点",
+    "guide_focus_fallback": "実装の細部へ入る前に、まず入力・状態・出力の関係を見ます。",
+    "guide_confusion_title": "混同しやすい点",
+    "guide_confusion_fallback": "概念がぼやけたら、この仕組みが何を解決し、前章より何の能力を増やしたのかへ戻ります。",
+    "guide_goal_title": "学習後にできるべきこと",
+    "guide_goal_fallback": "この章の後には、この仕組みを自分の agent system へつなぎ戻せる状態を目指します。",
+    "bridge_docs_label": "補助資料",
+    "bridge_docs_title": "深く入る前に見ておく地図",
+    "bridge_docs_intro": "この章で混同しやすい境界や仕組みを補うための橋渡し資料です。",
+    "bridge_docs_open": "資料を開く",
+    "bridge_docs_kind_map": "地図",
+    "bridge_docs_kind_mechanism": "仕組み",
+    "bridge_docs_fallback": "フォールバック",
+    "bridge_docs_back": "学習パスへ戻る",
+    "bridge_docs_standalone": "補助ドキュメント",
+    "bridge_docs_fallback_note": "この言語では未提供のため、次の言語へフォールバックしています:"
+  },
+  "sim": {
+    "play": "再生",
+    "pause": "一時停止",
+    "step": "ステップ",
+    "previous_step": "前のステップ",
+    "next_step": "次のステップ",
+    "autoplay": "自動再生",
+    "reset": "リセット",
+    "speed": "速度",
+    "step_of": "/"
+  },
+  "timeline": {
+    "title": "学習パス",
+    "subtitle": "s01 から s19 まで、4段階で agent システムを積み上げる",
+    "layer_legend": "段階の凡例",
+    "loc_growth": "コード量の成長",
+    "learn_more": "詳しく見る"
+  },
   "layers": {
-    "title": "アーキテクチャ層",
-    "subtitle": "5つの直交する関心事が完全なエージェントを構成",
-    "tools": "エージェントができること。基盤：ツールがモデルに外部世界と対話する能力を与える。",
-    "planning": "作業の組織化。シンプルなToDoリストからエージェント間で共有される依存関係対応タスクボードまで。",
-    "memory": "コンテキスト制限内での記憶保持。圧縮戦略によりエージェントが一貫性を失わずに無限に作業可能。",
-    "concurrency": "ノンブロッキング実行。バックグラウンドスレッドと通知バスによる並列作業。",
-    "collaboration": "マルチエージェント連携。チーム、メッセージング、自律的に考えるチームメイト。"
+    "title": "アーキテクチャ段階",
+    "subtitle": "最小の動くループから始めて、安全性、永続状態、バックグラウンド実行、マルチエージェント協調、外部 capability 連携へと進む。",
+    "guide_label": "読み方",
+    "guide_start_title": "最初に読むなら",
+    "guide_start_desc": "第1段階から始めます。後のすべての能力はコアループの外側に積み上がるため、そこを飛ばさない方がよいです。",
+    "guide_middle_title": "途中でぼやけたら",
+    "guide_middle_desc": "まず今の章がどの段階に属するかを確認し、それが安全性・状態・ランタイム・基盤のどれを足しているのかを見ます。",
+    "guide_finish_title": "自作したいなら",
+    "guide_finish_desc": "各段階の終わりごとに、1つの実装可能なシステムの塊が手元に残るべきで、単なる用語集になってはいけません。",
+    "core": "コアループ: ツール、計画、委譲、スキル、コンテキスト圧縮を含む最小の単一エージェントを作る段階。",
+    "core_outcome": "この段階を終えたら、動く単一 agent harness を自力で書けるはずです。",
+    "hardening": "システム強化: 権限、Hook、記憶、Prompt 組み立て、エラー回復によって「動く」から「安全に予測可能に動く」へ進める段階。",
+    "hardening_outcome": "この段階を終えたら、agent をより安全に、安定的に、拡張しやすくできるはずです。",
+    "runtime": "タスクランタイム: 作業をセッション内の一時的な計画から、永続・バックグラウンド・時間起点の実行へ変える段階。",
+    "runtime_outcome": "この段階を終えたら、会話レベルの手順を永続的なタスク実行系へ持ち上げられるはずです。",
+    "platform": "マルチエージェント基盤: 永続チームメイト、プロトコル、自律動作、分離実行レーン、MCP / Plugin capability routing を加える段階。",
+    "platform_outcome": "この段階を終えたら、単一 agent を協調基盤へ育てられるはずです。"
   },
   "compare": {
-    "title": "バージョン比較",
-    "subtitle": "任意の2つのバージョン間の変更を確認",
-    "select_a": "バージョンA",
-    "select_b": "バージョンB",
-    "loc_delta": "コード量の差分",
+    "title": "学習パス比較",
+    "subtitle": "2つの章のあいだで何の能力が増えるのか、なぜそこで導入されるのか、学習時にどこへ注目すべきかを比べる。",
+    "learning_jump": "学習ジャンプ",
+    "selector_title": "まず比べたい一歩を選ぶ",
+    "selector_note": "このページは、先に能力境界の変化を理解させ、そのあとで必要なら実装詳細へ入る構成です。",
+    "select_a": "章 A",
+    "select_b": "章 B",
+    "select_placeholder": "-- 選択してください --",
+    "carry_from_a": "A から持ち帰るもの",
+    "new_in_b": "B で増えるもの",
+    "progression": "進み方",
+    "progression_same_chapter": "同じ章を選んでいます。章単体の読み直しには向きますが、能力のジャンプを見る比較ではありません。",
+    "progression_reverse": "これは後ろ向きの比較です。後の章の能力が、実はどの早い章から来ているかを見るのに向いています。",
+    "progression_direct": "これは隣り合う一歩です。システムが章ごとに自然に育つ流れを学ぶのに最も向いています。",
+    "progression_same_layer": "両方とも同じ能力レイヤーにあるため、主眼は新概念よりも同じ概念を厚く完成させる点にあります。",
+    "progression_cross_layer": "この比較は新しい能力レイヤーへまたがるため、重要なのはシステム境界がどう変わるかです。",
+    "chapter_distance": "章の距離",
+    "shared_tools_count": "共通ツール",
+    "new_surface": "新しい実装面",
+    "empty_lead": "この章の短い要旨はまだ抽出されていません。",
+    "loc_delta": "コード量差分",
     "lines": "行",
-    "new_tools_in_b": "Bの新規ツール",
-    "new_classes_in_b": "Bの新規クラス",
-    "new_functions_in_b": "Bの新規関数",
+    "new_tools_in_b": "Bで増えるツール",
+    "new_classes_in_b": "Bで増えるクラス",
+    "new_functions_in_b": "Bで増える関数",
     "tool_comparison": "ツール比較",
     "only_in": "のみ",
     "shared": "共通",
     "none": "なし",
-    "source_diff": "ソースコード差分",
-    "empty_hint": "上で2つのバージョンを選択して比較してください。",
-    "architecture": "アーキテクチャ"
+    "source_diff": "ソース差分（任意）",
+    "source_diff_note": "実装の展開まで追いたい場合だけ diff を見れば十分です。機構だけ知りたいなら、その前の学習カードで足ります。",
+    "empty_hint": "先に2つの章を選び、そのアップグレードが実際に何を増やすのか見てください。",
+    "architecture": "アーキテクチャ",
+    "architecture_note": "まずモジュール境界と協調関係を見て、そのあと必要なら実装詳細へ入ります。"
   },
   "diff": {
     "new_classes": "新規クラス",
     "new_tools": "新規ツール",
     "new_functions": "新規関数",
-    "loc_delta": "コード量の差分"
+    "loc_delta": "コード量差分",
+    "view_unified": "統合表示",
+    "view_split": "分割表示"
   },
   "sessions": {
     "s01": "エージェントループ",
-    "s02": "ツール",
-    "s03": "TodoWrite",
+    "s02": "ツール使用",
+    "s03": "Todo 書き込み",
     "s04": "サブエージェント",
     "s05": "スキル",
     "s06": "コンテキスト圧縮",
-    "s07": "タスクシステム",
-    "s08": "バックグラウンドタスク",
-    "s09": "エージェントチーム",
-    "s10": "チームプロトコル",
-    "s11": "自律エージェント",
-    "s12": "Worktree + タスク分離"
+    "s07": "権限システム",
+    "s08": "Hook システム",
+    "s09": "記憶システム",
+    "s10": "システムプロンプト",
+    "s11": "エラー回復",
+    "s12": "タスクシステム",
+    "s13": "バックグラウンドタスク",
+    "s14": "Cron スケジューラ",
+    "s15": "エージェントチーム",
+    "s16": "チームプロトコル",
+    "s17": "自律エージェント",
+    "s18": "Worktree 分離",
+    "s19": "MCP とプラグイン"
   },
   "layer_labels": {
-    "tools": "ツールと実行",
-    "planning": "計画と調整",
-    "memory": "メモリ管理",
-    "concurrency": "並行処理",
-    "collaboration": "コラボレーション"
+    "core": "コアループ",
+    "hardening": "システム強化",
+    "runtime": "タスクランタイム",
+    "platform": "マルチエージェント基盤"
   },
   "viz": {
-    "s01": "エージェント Whileループ",
+    "s01": "Agent 主ループ",
     "s02": "ツールディスパッチマップ",
-    "s03": "TodoWrite リマインドシステム",
-    "s04": "サブエージェント コンテキスト分離",
-    "s05": "オンデマンド スキルローディング",
+    "s03": "Todo 書き込みリマインダーループ",
+    "s04": "サブエージェントのコンテキスト分離",
+    "s05": "オンデマンドスキル読み込み",
     "s06": "3層コンテキスト圧縮",
-    "s07": "タスク依存関係グラフ",
-    "s08": "バックグラウンドタスクレーン",
-    "s09": "エージェントチーム メールボックス",
-    "s10": "FSM チームプロトコル",
-    "s11": "自律エージェントサイクル",
-    "s12": "Worktree タスク分離"
+    "s07": "権限ゲート",
+    "s08": "ライフサイクル Hook 面",
+    "s09": "長期記憶と短期記憶の分離",
+    "s10": "Prompt 組み立てパイプライン",
+    "s11": "回復分岐ステートマシン",
+    "s12": "タスク依存グラフ",
+    "s13": "バックグラウンドタスクレーン",
+    "s14": "Cron トリガーパイプライン",
+    "s15": "エージェントチームのメールボックス",
+    "s16": "プロトコル時系列図",
+    "s17": "自律エージェントサイクル",
+    "s18": "Worktree タスク分離",
+    "s19": "外部 capability bus"
   }
 }
diff --git a/web/src/i18n/messages/zh.json b/web/src/i18n/messages/zh.json
index a8d9f3651..8267965dc 100644
--- a/web/src/i18n/messages/zh.json
+++ b/web/src/i18n/messages/zh.json
@@ -1,24 +1,155 @@
 {
-  "meta": { "title": "Learn Claude Code", "description": "从 0 到 1 构建 nano Claude Code-like agent，每次只加一个机制" },
-  "nav": { "home": "首页", "timeline": "学习路径", "compare": "版本对比", "layers": "架构层", "github": "GitHub" },
-  "home": { "hero_title": "Learn Claude Code", "hero_subtitle": "从 0 到 1 构建 nano Claude Code-like agent，每次只加一个机制", "start": "开始学习", "core_pattern": "核心模式", "core_pattern_desc": "所有 AI 编程 Agent 共享同一个循环：调用模型、执行工具、回传结果。生产级系统会在其上叠加策略、权限和生命周期层。", "learning_path": "学习路径", "learning_path_desc": "12 个渐进式课程，从简单循环到隔离化自治执行", "layers_title": "架构层次", "layers_desc": "五个正交关注点组合成完整的 Agent", "loc": "行", "learn_more": "了解更多", "versions_in_layer": "个版本", "message_flow": "消息增长", "message_flow_desc": "观察 Agent 循环执行时消息数组的增长" },
-  "version": { "loc": "行代码", "tools": "个工具", "new": "新增", "prev": "上一版", "next": "下一版", "view_source": "查看源码", "view_diff": "查看变更", "design_decisions": "设计决策", "whats_new": "新增内容", "tutorial": "教程", "simulator": "Agent 循环模拟器", "execution_flow": "执行流程", "architecture": "架构", "concept_viz": "概念可视化", "alternatives": "替代方案", "tab_learn": "学习", "tab_simulate": "模拟", "tab_code": "源码", "tab_deep_dive": "深入探索" },
-  "sim": { "play": "播放", "pause": "暂停", "step": "单步", "reset": "重置", "speed": "速度", "step_of": "/" },
-  "timeline": { "title": "学习路径", "subtitle": "s01 到 s12：渐进式 Agent 设计", "layer_legend": "层次图例", "loc_growth": "代码量增长", "learn_more": "了解更多" },
+  "meta": {
+    "title": "Learn Claude Code",
+    "description": "19 章节、4 个阶段，带你从 0 到 1 手搓一个结构完整的 Claude Code-like Agent"
+  },
+  "nav": {
+    "home": "首页",
+    "reference": "参考资料",
+    "compare": "版本对比",
+    "github": "GitHub"
+  },
+  "reference": {
+    "title": "参考资料",
+    "subtitle": "术语表、架构地图与深入阅读补充文档。",
+    "foundation_title": "基础文档",
+    "deep_dive_title": "深入阅读"
+  },
+  "home": {
+    "hero_title": "Learn Claude Code",
+    "hero_subtitle": "19 章节、4 个阶段，从最小闭环一路搭到多 Agent 平台与外部能力总线",
+    "start": "开始学习",
+    "entry_title": "四个最推荐的学习入口",
+    "entry_desc": "如果你是第一次进站，不要急着随机点章节。先决定你要按顺序学、按阶段学，还是只看两步之间的能力跃迁。",
+    "entry_start_title": "直接从最小闭环开始",
+    "entry_start_desc": "适合第一次接触这套仓库的读者。先把最小 agent loop 跑通，再往后加工具、规划和上下文管理。",
+    "entry_start_action": "打开 s01",
+    "entry_timeline_title": "按主线顺序一路学",
+    "entry_timeline_desc": "适合想完整跟一遍教学节奏的人。你会按章节顺序看到系统是怎么自然长出来的。",
+    "entry_timeline_action": "打开时间线",
+    "entry_layers_title": "先按四阶段理解全局",
+    "entry_layers_desc": "适合先想弄明白“为什么要这样分阶段”的读者。你会先看到单 agent、加固、任务运行时、多 agent 平台这四层。",
+    "entry_layers_action": "打开阶段页",
+    "entry_compare_title": "卡住时看两章之间差了什么",
+    "entry_compare_desc": "适合已经读到一半，但开始混淆章节边界的读者。它会帮助你看清这一章到底比上一章多了什么能力。",
+    "entry_compare_action": "打开对比页",
+    "core_pattern": "核心模式",
+    "core_pattern_desc": "所有 AI 编程 Agent 的底层都围绕同一个闭环：调用模型、执行工具、回传结果。后面的权限、记忆、任务、团队与插件能力，都是围绕这个闭环继续搭起来的控制层。",
+    "learning_path": "学习路径",
+    "learning_path_desc": "19 个递进章节，按照核心闭环、系统加固、任务运行时、多 Agent 平台四个阶段展开",
+    "layers_title": "四个阶段",
+    "layers_desc": "不是把细节堆满，而是按开发者心智把一个完整 Agent 系统拆成四个逐步成立的阶段",
+    "guide_label": "阅读提示",
+    "guide_start_title": "第一次读：先抓主闭环",
+    "guide_start_desc": "如果你还没真的把 s01-s06 跑通，不要急着钻多 agent 或 MCP。先把单 agent 主闭环建立起来。",
+    "guide_middle_title": "读到中段：先分清状态层",
+    "guide_middle_desc": "当你开始分不清 task、runtime task、teammate、worktree 这些词时，说明你该回头看阶段边界与数据结构地图。",
+    "guide_finish_title": "读到后段：盯住平台边界",
+    "guide_finish_desc": "进入 s15-s19 后，重点不再只是多几个功能，而是系统边界如何从单执行者升级成多执行车道和外部能力总线。",
+    "loc": "行",
+    "learn_more": "了解更多",
+    "versions_in_layer": "个章节",
+    "message_flow": "消息增长",
+    "message_flow_desc": "观察一次真实 Agent 闭环中，messages[] 如何随着工具调用不断增长"
+  },
+  "version": {
+    "loc": "行代码",
+    "tools": "个工具",
+    "new": "新增",
+    "prev": "上一章",
+    "next": "下一章",
+    "view_source": "查看源码",
+    "view_diff": "查看变更",
+    "design_decisions": "设计决策",
+    "whats_new": "新增内容",
+    "tutorial": "教程",
+    "simulator": "章节模拟器",
+    "execution_flow": "执行流程",
+    "architecture": "架构",
+    "concept_viz": "概念可视化",
+    "alternatives": "替代方案",
+    "tab_learn": "学习",
+    "tab_simulate": "模拟",
+    "tab_code": "源码",
+    "tab_deep_dive": "深入探索",
+    "guide_label": "本章导读",
+    "guide_addition_title": "这章新增的核心结构",
+    "guide_addition_empty": "这一章主要是在前一章之上把已有结构串起来，而不是单独引入一个全新的大模块。",
+    "guide_focus_title": "先盯住什么",
+    "guide_focus_fallback": "先把这一章最关键的输入、状态和输出关系看清，不要一开始就钻到实现细枝末节里。",
+    "guide_confusion_title": "最容易混淆什么",
+    "guide_confusion_fallback": "如果概念开始混在一起，就回到“这个机制到底解决什么问题、它和前一章相比多了哪一层能力”。",
+    "guide_goal_title": "学完应该会什么",
+    "guide_goal_fallback": "学完这一章后，你应该能把这里新增的机制独立接回自己的 agent 主系统。",
+    "bridge_docs_label": "桥接资料",
+    "bridge_docs_title": "继续往下前，先补这几张地图",
+    "bridge_docs_intro": "这些资料不是旁枝细节，而是专门用来补当前章节最容易混淆的结构边界和主线机制。",
+    "bridge_docs_open": "打开补充页",
+    "bridge_docs_kind_map": "结构地图",
+    "bridge_docs_kind_mechanism": "机制展开",
+    "bridge_docs_fallback": "内容回退",
+    "bridge_docs_back": "回到学习主线",
+    "bridge_docs_standalone": "桥接文档",
+    "bridge_docs_fallback_note": "当前语言暂无该文档，已自动回退到："
+  },
+  "sim": {
+    "play": "播放",
+    "pause": "暂停",
+    "step": "单步",
+    "previous_step": "上一步",
+    "next_step": "下一步",
+    "autoplay": "自动播放",
+    "reset": "重置",
+    "speed": "速度",
+    "step_of": "/"
+  },
+  "timeline": {
+    "title": "学习路径",
+    "subtitle": "s01 到 s19：按 4 个阶段渐进搭建一个结构完整、接近真实主脉络的 Agent 系统",
+    "layer_legend": "阶段图例",
+    "loc_growth": "代码量增长",
+    "learn_more": "了解更多"
+  },
   "layers": {
-    "title": "架构层次",
-    "subtitle": "五个正交关注点组合成完整的 Agent",
-    "tools": "Agent 能做什么。基础层：工具赋予模型与外部世界交互的能力。",
-    "planning": "如何组织工作。从简单的待办列表到跨 Agent 共享的依赖感知任务板。",
-    "memory": "在上下文限制内保持记忆。压缩策略让 Agent 可以无限工作而不失去连贯性。",
-    "concurrency": "非阻塞执行。后台线程和通知总线实现并行工作。",
-    "collaboration": "多 Agent 协作。团队、消息传递和能独立思考的自主队友。"
+    "title": "架构阶段",
+    "subtitle": "从最小可运行闭环开始，逐步加上安全、持久状态、后台运行、多 Agent 协作与外部能力接入",
+    "guide_label": "怎么读",
+    "guide_start_title": "如果你是第一次学",
+    "guide_start_desc": "从第一阶段开始，不要跳过核心闭环。后面所有能力都是包在这条主循环外面的。",
+    "guide_middle_title": "如果你读到中途开始混",
+    "guide_middle_desc": "先看当前章节属于哪一阶段，再判断它是在补安全、补状态、补运行时，还是在扩平台边界。",
+    "guide_finish_title": "如果你准备自己实现",
+    "guide_finish_desc": "每学完一个阶段，都应该手里多出一块真正成立的系统，而不是只记住一些名词。",
+    "core": "核心闭环：先把单 Agent 最基本的工作回路搭起来，包括工具、计划、委托、技能加载和上下文压缩。",
+    "core_outcome": "学完本阶段，你应该能独立写出一个真正能工作的单 Agent harness。",
+    "hardening": "系统加固：把“能跑”推进到“稳定可控地跑”，重点是权限、Hook、长期记忆、Prompt 装配与错误恢复。",
+    "hardening_outcome": "学完本阶段，你应该知道怎样让 agent 不只是能跑，而是更稳、更安全、更容易扩展。",
+    "runtime": "任务运行时：把工作从一次会话内的临时计划，提升成可持久、可后台、可定时触发的任务执行系统。",
+    "runtime_outcome": "学完本阶段，你应该能把聊天内的步骤，升级成真正可持久推进的任务系统。",
+    "platform": "多 Agent 平台：引入长期存在的队友、协议、自治行为、隔离执行工作区，以及 MCP / Plugin 外部能力总线。",
+    "platform_outcome": "学完本阶段，你应该能把单 agent 升级成多执行者协作的平台。"
   },
   "compare": {
-    "title": "版本对比",
-    "subtitle": "查看任意两个版本之间的变化",
-    "select_a": "版本 A",
-    "select_b": "版本 B",
+    "title": "学习路径对比",
+    "subtitle": "比较两个章节之间新增了什么能力、为什么在这里引入，以及学习时该先盯住哪条主线。",
+    "learning_jump": "学习跃迁",
+    "selector_title": "先决定你要比较哪一步升级",
+    "selector_note": "这页优先帮助你理解能力边界的变化，而不是先把你拖进源码细节里。",
+    "select_a": "章节 A",
+    "select_b": "章节 B",
+    "select_placeholder": "-- 请选择 --",
+    "carry_from_a": "从 A 带走",
+    "new_in_b": "B 新引入",
+    "progression": "推进关系",
+    "progression_same_chapter": "你选中了同一章。适合回看这一章本身的架构与源码，不适合看能力跃迁。",
+    "progression_reverse": "这是一次回看式对比，适合观察哪些能力其实来自更早的章节。",
+    "progression_direct": "这是紧邻的一步升级，最适合按教程顺序学习系统是如何自然长出来的。",
+    "progression_same_layer": "两章仍在同一能力阶段内，重点是看机制如何从“能跑”变成“更稳、更完整”。",
+    "progression_cross_layer": "这次比较跨越了能力阶段，重点是看系统边界怎样被重新定义。",
+    "chapter_distance": "相隔章节",
+    "shared_tools_count": "共有工具",
+    "new_surface": "新增实现面",
+    "empty_lead": "该章节的核心一句话摘要暂未提取出来。",
     "loc_delta": "代码量差异",
     "lines": "行",
     "new_tools_in_b": "B 中新增工具",
@@ -28,49 +159,66 @@
     "only_in": "仅在",
     "shared": "共有",
     "none": "无",
-    "source_diff": "源码差异",
-    "empty_hint": "请在上方选择两个版本进行对比。",
-    "architecture": "架构"
+    "source_diff": "源码差异（选看）",
+    "source_diff_note": "如果你在意实现展开，可以再看源码 diff；如果你只关心机制，前面的学习卡片已经足够。",
+    "empty_hint": "先选两个章节，再看这次升级到底新增了什么能力。",
+    "architecture": "架构视图",
+    "architecture_note": "先看模块边界和协作关系，再决定要不要往下钻实现细节。"
   },
   "diff": {
     "new_classes": "新增类",
     "new_tools": "新增工具",
     "new_functions": "新增函数",
-    "loc_delta": "代码量差异"
+    "loc_delta": "代码量差异",
+    "view_unified": "统一视图",
+    "view_split": "分栏视图"
   },
   "sessions": {
-    "s01": "Agent Loop",
-    "s02": "Tool Use",
-    "s03": "TodoWrite",
-    "s04": "Subagent",
-    "s05": "Skills",
-    "s06": "Context Compact",
-    "s07": "Task System",
-    "s08": "Background Tasks",
-    "s09": "Agent Teams",
-    "s10": "Team Protocols",
-    "s11": "Autonomous Agents",
-    "s12": "Worktree + Task Isolation"
+    "s01": "Agent 循环",
+    "s02": "工具使用",
+    "s03": "待办写入",
+    "s04": "子代理",
+    "s05": "技能系统",
+    "s06": "上下文压缩",
+    "s07": "权限系统",
+    "s08": "Hook 系统",
+    "s09": "记忆系统",
+    "s10": "系统提示词",
+    "s11": "错误恢复",
+    "s12": "任务系统",
+    "s13": "后台任务",
+    "s14": "定时调度",
+    "s15": "Agent 团队",
+    "s16": "团队协议",
+    "s17": "自主代理",
+    "s18": "Worktree 隔离",
+    "s19": "MCP 与插件"
   },
   "layer_labels": {
-    "tools": "工具与执行",
-    "planning": "规划与协调",
-    "memory": "记忆管理",
-    "concurrency": "并发",
-    "collaboration": "协作"
+    "core": "核心闭环",
+    "hardening": "系统加固",
+    "runtime": "任务运行时",
+    "platform": "多 Agent 平台"
   },
   "viz": {
-    "s01": "Agent While-Loop",
-    "s02": "Tool Dispatch Map",
-    "s03": "TodoWrite Nag System",
-    "s04": "Subagent Context Isolation",
-    "s05": "On-Demand Skill Loading",
-    "s06": "Three-Layer Context Compact",
-    "s07": "Task Dependency Graph",
-    "s08": "Background Task Lanes",
-    "s09": "Agent Team Mailboxes",
-    "s10": "FSM Team Protocols",
-    "s11": "Autonomous Agent Cycle",
-    "s12": "Worktree Task Isolation"
+    "s01": "Agent 主循环",
+    "s02": "工具分发映射",
+    "s03": "待办写入提醒系统",
+    "s04": "子代理上下文隔离",
+    "s05": "按需技能加载",
+    "s06": "三层上下文压缩",
+    "s07": "权限判定闸门",
+    "s08": "生命周期 Hook 面板",
+    "s09": "长短期记忆分层",
+    "s10": "Prompt 装配流水线",
+    "s11": "恢复分支状态机",
+    "s12": "任务依赖图",
+    "s13": "后台任务通道",
+    "s14": "定时触发流水线",
+    "s15": "Agent 团队邮箱",
+    "s16": "协议时序图",
+    "s17": "自主代理循环",
+    "s18": "Worktree 任务隔离",
+    "s19": "外部能力总线"
   }
 }
diff --git a/web/src/lib/bridge-docs.ts b/web/src/lib/bridge-docs.ts
new file mode 100644
index 000000000..709855346
--- /dev/null
+++ b/web/src/lib/bridge-docs.ts
@@ -0,0 +1,344 @@
+import { VERSION_ORDER, type VersionId } from "@/lib/constants";
+
+type SupportedLocale = "zh" | "en" | "ja";
+type BridgeKind = "map" | "mechanism";
+
+export interface BridgeDocDescriptor {
+  slug: string;
+  kind: BridgeKind;
+  title: Record<SupportedLocale, string>;
+  summary: Record<SupportedLocale, string>;
+}
+
+export const BRIDGE_DOCS: Record<string, BridgeDocDescriptor> = {
+  "s00-architecture-overview": {
+    slug: "s00-architecture-overview",
+    kind: "map",
+    title: {
+      zh: "系统全景总览",
+      en: "Architecture Overview",
+      ja: "アーキテクチャ全体図",
+    },
+    summary: {
+      zh: "先看系统全貌，再回到当前章节，能更快分清这一层到底属于哪里。",
+      en: "The big-picture map. Come back here whenever you feel lost about where a chapter fits.",
+      ja: "全体像を先に見てから現在の章へ戻るための俯瞰図です。",
+    },
+  },
+  "s00a-query-control-plane": {
+    slug: "s00a-query-control-plane",
+    kind: "mechanism",
+    title: {
+      zh: "查询控制平面",
+      en: "Query Control Plane",
+      ja: "クエリ制御プレーン",
+    },
+    summary: {
+      zh: "把一次请求如何穿过控制平面讲完整，适合权限、Prompt、MCP 这些章节前后补看。",
+      en: "Why the simple loop needs a coordination layer as the system grows. Best read after Stage 1.",
+      ja: "1つの要求が control plane をどう通るかを通しで補う資料です。",
+    },
+  },
+  "s00b-one-request-lifecycle": {
+    slug: "s00b-one-request-lifecycle",
+    kind: "mechanism",
+    title: {
+      zh: "一次请求生命周期",
+      en: "One Request Lifecycle",
+      ja: "1 リクエストのライフサイクル",
+    },
+    summary: {
+      zh: "把一次请求从进入、执行到回写走完一遍，适合主线开始混时回头校正心智。",
+      en: "Traces one request from entry to write-back. Best read after Stage 2 when pieces need connecting.",
+      ja: "1回の要求を入口から write-back まで通して確認する補助資料です。",
+    },
+  },
+  "s00c-query-transition-model": {
+    slug: "s00c-query-transition-model",
+    kind: "mechanism",
+    title: {
+      zh: "Query 续行模型",
+      en: "Query Transition Model",
+      ja: "クエリ遷移モデル",
+    },
+    summary: {
+      zh: "专门讲一条 query 为什么继续下一轮，适合恢复、压缩、预算、hook 开始缠在一起时回看。",
+      en: "Why each continuation needs an explicit reason. Best read alongside s11 (Error Recovery).",
+      ja: "エラー回復・文脈圧縮・予算制御・hook が重なり始めたときに、query がなぜ次のターンへ続くのかを補う資料です。",
+    },
+  },
+  "s00d-chapter-order-rationale": {
+    slug: "s00d-chapter-order-rationale",
+    kind: "map",
+    title: {
+      zh: "为什么这样安排章节顺序",
+      en: "Why This Chapter Order",
+      ja: "なぜこの章順なのか",
+    },
+    summary: {
+      zh: "专门解释为什么课程要按现在这个顺序展开，适合读者刚进入主线或准备自己重排章节时回看。",
+      en: "Explains why the curriculum is ordered this way and what breaks when the sequence is rearranged.",
+      ja: "なぜこの順序で学ぶのか、順番を崩すと何が混乱するのかを整理する資料です。",
+    },
+  },
+  "s00f-code-reading-order": {
+    slug: "s00f-code-reading-order",
+    kind: "map",
+    title: {
+      zh: "本仓库代码阅读顺序",
+      en: "Code Reading Order",
+      ja: "コード読解順",
+    },
+    summary: {
+      zh: "专门告诉你本地 `agents/*.py` 该按什么顺序打开、每章先盯住哪类状态和函数，避免重新乱翻源码。",
+      en: "Shows which local `agents/*.py` files to open first and what state or functions to inspect before the code turns into noise.",
+      ja: "ローカルの `agents/*.py` をどの順で開き、各章でまずどの状態や関数を見るべきかを整理した読解ガイドです。",
+    },
+  },
+  "s00e-reference-module-map": {
+    slug: "s00e-reference-module-map",
+    kind: "map",
+    title: {
+      zh: "参考仓库模块映射图",
+      en: "Reference Module Map",
+      ja: "参照モジュール対応表",
+    },
+    summary: {
+      zh: "把参考仓库里真正重要的模块簇，和当前课程章节一一对齐，专门用来验证章节顺序是否合理。",
+      en: "Maps the reference repo's real module clusters onto the current curriculum to validate the chapter order.",
+      ja: "参照リポジトリの高信号モジュール群と現在の教材章を対応付け、章順の妥当性を確認する地図です。",
+    },
+  },
+  "s02a-tool-control-plane": {
+    slug: "s02a-tool-control-plane",
+    kind: "mechanism",
+    title: {
+      zh: "工具控制平面",
+      en: "Tool Control Plane",
+      ja: "ツール制御プレーン",
+    },
+    summary: {
+      zh: "专门补工具调用怎样进入统一执行面，适合权限、Hook、MCP 等章节一起看。",
+      en: "Why tools become a coordination layer, not just a lookup table. Best read after s02.",
+      ja: "ツール呼び出しが共通の実行面に入る流れを補う資料です。",
+    },
+  },
+  "s02b-tool-execution-runtime": {
+    slug: "s02b-tool-execution-runtime",
+    kind: "mechanism",
+    title: {
+      zh: "工具执行运行时",
+      en: "Tool Execution Runtime",
+      ja: "ツール実行ランタイム",
+    },
+    summary: {
+      zh: "把工具并发、串行、进度消息、结果顺序和 context 合并这层运行时讲清楚。",
+      en: "How multiple tool calls in one turn get executed safely. Best read after s02.",
+      ja: "tool の並列実行と直列実行、progress 更新、結果順序、context 統合をまとめて補う資料です。",
+    },
+  },
+  glossary: {
+    slug: "glossary",
+    kind: "map",
+    title: {
+      zh: "术语表",
+      en: "Glossary",
+      ja: "用語集",
+    },
+    summary: {
+      zh: "术语一多就先回这里，统一名词边界，避免 task、runtime task、teammate 混在一起。",
+      en: "Bookmark this. Come back whenever you hit an unfamiliar term.",
+      ja: "用語が増えて混ざり始めたときに戻る境界整理用の用語集です。",
+    },
+  },
+  "entity-map": {
+    slug: "entity-map",
+    kind: "map",
+    title: {
+      zh: "对象与模块关系图",
+      en: "Entity Map",
+      ja: "エンティティ地図",
+    },
+    summary: {
+      zh: "按对象和模块关系看系统，适合读到中后段时重新校准模块边界。",
+      en: "Use this when concepts start to blur. It tells you which layer each thing belongs to.",
+      ja: "オブジェクトとモジュール関係から全体を再確認する地図です。",
+    },
+  },
+  "data-structures": {
+    slug: "data-structures",
+    kind: "map",
+    title: {
+      zh: "关键数据结构地图",
+      en: "Data Structure Map",
+      ja: "主要データ構造マップ",
+    },
+    summary: {
+      zh: "把核心记录结构放在一起看，适合任务、运行时、多 Agent 章节反复对照。",
+      en: "Every important record in one place. Use when you lose track of where state lives.",
+      ja: "主要な record 構造を横断的に見直すための資料です。",
+    },
+  },
+  "s10a-message-prompt-pipeline": {
+    slug: "s10a-message-prompt-pipeline",
+    kind: "mechanism",
+    title: {
+      zh: "消息与 Prompt 装配流水线",
+      en: "Message-Prompt Pipeline",
+      ja: "メッセージと Prompt の組み立てパイプライン",
+    },
+    summary: {
+      zh: "专门补消息、Prompt 片段和装配顺序，适合 s10 前后深入看。",
+      en: "The full input pipeline beyond system prompt. Best read alongside s10.",
+      ja: "message と prompt 片をどの順に組み立てるかを補う解説です。",
+    },
+  },
+  "s13a-runtime-task-model": {
+    slug: "s13a-runtime-task-model",
+    kind: "mechanism",
+    title: {
+      zh: "运行时任务模型",
+      en: "Runtime Task Model",
+      ja: "ランタイムタスクモデル",
+    },
+    summary: {
+      zh: "把 task goal、runtime record、notification 三层边界一次讲清。",
+      en: "The most common Stage 3 confusion: two meanings of 'task'. Read between s12 and s13.",
+      ja: "作業目標・実行記録・通知の3層境界をまとめて補う資料です。",
+    },
+  },
+  "s19a-mcp-capability-layers": {
+    slug: "s19a-mcp-capability-layers",
+    kind: "mechanism",
+    title: {
+      zh: "MCP 能力层地图",
+      en: "MCP Capability Layers",
+      ja: "MCP 能力層マップ",
+    },
+    summary: {
+      zh: "把本地工具、插件、MCP server 如何接回同一 capability bus 讲完整。",
+      en: "MCP is more than external tools. This shows the full capability stack. Read alongside s19.",
+      ja: "native tool・plugin・MCP server が 1 つの capability bus へ戻る全体像を補います。",
+    },
+  },
+  "team-task-lane-model": {
+    slug: "team-task-lane-model",
+    kind: "map",
+    title: {
+      zh: "队友-任务-车道模型",
+      en: "Teammate-Task-Lane Model",
+      ja: "チームメイト・タスク・レーンモデル",
+    },
+    summary: {
+      zh: "专门拆清队友、协议请求、任务、运行时槽位和 worktree 车道这五层边界。",
+      en: "Five concepts that look similar but live on different layers. Keep open during s15-s18.",
+      ja: "teammate・protocol request・task・runtime slot・worktree lane の 5 層境界を整理します。",
+    },
+  },
+  "teaching-scope": {
+    slug: "teaching-scope",
+    kind: "map",
+    title: {
+      zh: "教学范围与取舍",
+      en: "Teaching Scope",
+      ja: "教材の守備範囲",
+    },
+    summary: {
+      zh: "说明这套教学仓库刻意不讲什么，帮助读者守住主线，不被低价值细节带偏。",
+      en: "What this repo teaches, what it deliberately leaves out, and why.",
+      ja: "この教材が意図的に省いている範囲を示し、主線を守るための資料です。",
+    },
+  },
+};
+
+export const FOUNDATION_DOC_SLUGS = [
+  "s00-architecture-overview",
+  "s00d-chapter-order-rationale",
+  "s00f-code-reading-order",
+  "s00e-reference-module-map",
+  "teaching-scope",
+  "glossary",
+  "data-structures",
+  "entity-map",
+] as const;
+
+export const MECHANISM_DOC_SLUGS = [
+  "s00a-query-control-plane",
+  "s00b-one-request-lifecycle",
+  "s00c-query-transition-model",
+  "s02a-tool-control-plane",
+  "s02b-tool-execution-runtime",
+  "s10a-message-prompt-pipeline",
+  "s13a-runtime-task-model",
+  "team-task-lane-model",
+  "s19a-mcp-capability-layers",
+] as const;
+
+export const RESET_DOC_SLUGS = [
+  "s00a-query-control-plane",
+  "s02b-tool-execution-runtime",
+  "s13a-runtime-task-model",
+  "team-task-lane-model",
+  "s19a-mcp-capability-layers",
+] as const;
+
+export const BRIDGE_DOC_RELATED_VERSIONS: Partial<
+  Record<string, readonly VersionId[]>
+> = {
+  "s00-architecture-overview": ["s01", "s07", "s12", "s15"],
+  "s00d-chapter-order-rationale": ["s01", "s12", "s15"],
+  "s00f-code-reading-order": ["s01", "s07", "s12", "s15"],
+  "s00e-reference-module-map": ["s01", "s07", "s12", "s15", "s18", "s19"],
+  glossary: ["s01", "s09", "s16", "s19"],
+  "entity-map": ["s04", "s12", "s15", "s18", "s19"],
+  "data-structures": ["s03", "s09", "s12", "s13", "s18"],
+  "teaching-scope": ["s01", "s05", "s12", "s19"],
+  "s00a-query-control-plane": ["s07", "s10", "s11", "s19"],
+  "s00b-one-request-lifecycle": ["s04", "s11", "s14"],
+  "s00c-query-transition-model": ["s11", "s17"],
+  "s02a-tool-control-plane": ["s02", "s08", "s19"],
+  "s02b-tool-execution-runtime": ["s02", "s07", "s13", "s19"],
+  "s10a-message-prompt-pipeline": ["s10"],
+  "s13a-runtime-task-model": ["s12", "s13", "s14", "s17"],
+  "team-task-lane-model": ["s15", "s16", "s17", "s18"],
+  "s19a-mcp-capability-layers": ["s19"],
+};
+
+export const CHAPTER_BRIDGE_DOCS: Partial<Record<VersionId, string[]>> = {
+  s01: ["s00-architecture-overview", "s00d-chapter-order-rationale", "s00f-code-reading-order", "s00e-reference-module-map", "glossary"],
+  s02: ["s02a-tool-control-plane", "s02b-tool-execution-runtime"],
+  s03: ["data-structures", "glossary"],
+  s04: ["entity-map", "s00b-one-request-lifecycle"],
+  s05: ["glossary", "teaching-scope"],
+  s06: ["data-structures", "s00b-one-request-lifecycle"],
+  s07: ["s00f-code-reading-order", "s00a-query-control-plane", "s02b-tool-execution-runtime"],
+  s08: ["s02a-tool-control-plane", "entity-map"],
+  s09: ["data-structures", "glossary"],
+  s10: ["s10a-message-prompt-pipeline", "s00a-query-control-plane"],
+  s11: ["s00c-query-transition-model", "s00b-one-request-lifecycle"],
+  s12: ["s00f-code-reading-order", "data-structures", "entity-map"],
+  s13: ["s13a-runtime-task-model", "s02b-tool-execution-runtime"],
+  s14: ["s13a-runtime-task-model", "s00b-one-request-lifecycle"],
+  s15: ["s00f-code-reading-order", "team-task-lane-model", "entity-map"],
+  s16: ["team-task-lane-model", "glossary"],
+  s17: ["team-task-lane-model", "s13a-runtime-task-model"],
+  s18: ["team-task-lane-model", "data-structures"],
+  s19: ["s19a-mcp-capability-layers", "s02b-tool-execution-runtime"],
+};
+
+export function getBridgeDocDescriptors(version: VersionId): BridgeDocDescriptor[] {
+  return (CHAPTER_BRIDGE_DOCS[version] ?? [])
+    .map((slug) => BRIDGE_DOCS[slug])
+    .filter((doc): doc is BridgeDocDescriptor => Boolean(doc));
+}
+
+export function getChaptersForBridgeDoc(slug: string): VersionId[] {
+  const mappedVersions = BRIDGE_DOC_RELATED_VERSIONS[slug] ?? [];
+  const referencedVersions = Object.entries(CHAPTER_BRIDGE_DOCS)
+    .filter(([, slugs]) => slugs?.includes(slug))
+    .map(([version]) => version as VersionId);
+
+  return VERSION_ORDER.filter((version) =>
+    new Set([...mappedVersions, ...referencedVersions]).has(version)
+  );
+}
diff --git a/web/src/lib/chapter-guides.ts b/web/src/lib/chapter-guides.ts
new file mode 100644
index 000000000..94de74477
--- /dev/null
+++ b/web/src/lib/chapter-guides.ts
@@ -0,0 +1,344 @@
+import type { VersionId } from "@/lib/constants";
+
+type SupportedLocale = "zh" | "en" | "ja";
+
+export interface ChapterGuide {
+  focus: string;
+  confusion: string;
+  goal: string;
+}
+
+export const CHAPTER_GUIDES: Record<VersionId, Record<SupportedLocale, ChapterGuide>> = {
+  s01: {
+    zh: {
+      focus: "先盯住 `messages`、`tool_use` 和 `tool_result` 如何闭环回流。",
+      confusion: "不要把“模型会思考”和“系统能行动”混成一回事，真正让它能行动的是 loop。",
+      goal: "手写一个最小但真实可运行的 agent loop。",
+    },
+    en: {
+      focus: "Focus first on how `messages`, `tool_use`, and `tool_result` close the loop.",
+      confusion: "Do not confuse model reasoning with system action. The loop is what turns thought into work.",
+      goal: "Be able to write a minimal but real agent loop by hand.",
+    },
+    ja: {
+      focus: "まず `messages`、`tool_use`、`tool_result` がどう閉ループを作るかを見る。",
+      confusion: "モデルが考えられることと、システムが行動できることを混同しない。行動を成立させるのは loop です。",
+      goal: "最小でも実際に動く agent loop を自力で書けるようになる。",
+    },
+  },
+  s02: {
+    zh: {
+      focus: "先盯住 `ToolSpec`、`dispatch map` 和 `tool_result` 的对应关系。",
+      confusion: "工具 schema 不是执行函数本身；一个是给模型看的说明，一个是代码里的处理器。",
+      goal: "在不改主循环的前提下，自己加一个新工具。",
+    },
+    en: {
+      focus: "Focus on the relationship between `ToolSpec`, the dispatch map, and `tool_result`.",
+      confusion: "A tool schema is not the handler itself. One describes the tool to the model; the other executes it.",
+      goal: "Add a new tool without changing the main loop.",
+    },
+    ja: {
+      focus: "`ToolSpec`、dispatch map、`tool_result` の対応関係を先に見る。",
+      confusion: "schema は実行関数そのものではありません。片方はモデル向けの説明、もう片方は実装側の handler です。",
+      goal: "主ループを変えずに新しいツールを追加できるようになる。",
+    },
+  },
+  s03: {
+    zh: {
+      focus: "先盯住 `TodoItem` / `PlanState` 这类最小计划状态。",
+      confusion: "todo 只是当前会话里的步骤提醒，不是后面那种持久化任务图。",
+      goal: "让 agent 能把一个大目标拆成可跟踪的小步骤。",
+    },
+    en: {
+      focus: "Focus on the smallest planning state, such as `TodoItem` and `PlanState`.",
+      confusion: "A todo here is a session-level reminder, not the later durable task graph.",
+      goal: "Make the agent break a large goal into trackable steps.",
+    },
+    ja: {
+      focus: "`TodoItem` や `PlanState` のような最小の計画状態を見る。",
+      confusion: "ここでの todo は会話内の手順メモであり、後の永続 task graph とは別物です。",
+      goal: "大きな目標を追跡できる小さな手順へ分解できるようにする。",
+    },
+  },
+  s04: {
+    zh: {
+      focus: "先盯住父 `messages` 和子 `messages` 如何隔离。",
+      confusion: "subagent 的关键不是“又开一次模型调用”，而是“给子任务一个干净上下文”。",
+      goal: "做出一个一次性委派、返回摘要的子 agent。",
+    },
+    en: {
+      focus: "Focus on how parent `messages` and child `messages` stay isolated.",
+      confusion: "The key value of a subagent is not another model call. It is a clean context for the subtask.",
+      goal: "Build a one-shot delegated child agent that returns a summary.",
+    },
+    ja: {
+      focus: "親 `messages` と子 `messages` がどう分離されるかを見る。",
+      confusion: "subagent の本質はモデル呼び出しを増やすことではなく、子タスクへきれいな文脈を与えることです。",
+      goal: "一回限りの委譲を行い、要約を返す子 agent を作れるようになる。",
+    },
+  },
+  s05: {
+    zh: {
+      focus: "先盯住技能的“发现层”和“加载层”是怎么分开的。",
+      confusion: "skill 不是一开始全部塞进 prompt 的大说明书，而是按需加载的知识块。",
+      goal: "做出一个低成本发现、高成本按需读取的技能系统。",
+    },
+    en: {
+      focus: "Focus on how skill discovery and skill loading are kept separate.",
+      confusion: "A skill is not a giant prompt blob loaded upfront. It is knowledge loaded only when needed.",
+      goal: "Build a skill system with cheap discovery and on-demand deep loading.",
+    },
+    ja: {
+      focus: "skill の発見層と読み込み層がどう分かれているかを見る。",
+      confusion: "skill は最初から全部 prompt に入れる巨大説明ではなく、必要時だけ読む知識ブロックです。",
+      goal: "軽い発見と必要時だけの深い読み込みを持つ skill system を作る。",
+    },
+  },
+  s06: {
+    zh: {
+      focus: "先盯住 `persisted output`、`micro compact`、`summary compact` 这三层。",
+      confusion: "压缩不是为了删历史，而是把细节移出活跃上下文，同时保住主线。",
+      goal: "做出一个能长期工作、不被上下文撑爆的最小压缩系统。",
+    },
+    en: {
+      focus: "Focus on the three layers: persisted output, micro compact, and summary compact.",
+      confusion: "Compaction is not about deleting history. It is about moving detail out of the active window while keeping continuity.",
+      goal: "Build a minimal compaction system that keeps long sessions usable.",
+    },
+    ja: {
+      focus: "persisted output、micro compact、summary compact の3層を見る。",
+      confusion: "compact は履歴削除ではなく、細部をアクティブ文脈の外へ移しながら主線を保つことです。",
+      goal: "長い作業でも文脈が破綻しない最小 compact system を作る。",
+    },
+  },
+  s07: {
+    zh: {
+      focus: "先盯住 `PermissionRule`、`PermissionDecision` 和整条 allow / ask / deny 管道。",
+      confusion: "权限系统不是单个 if 判断，而是一条在执行前拦截意图的决策链。",
+      goal: "让危险动作先经过清晰的权限决策，再决定是否执行。",
+    },
+    en: {
+      focus: "Focus on `PermissionRule`, `PermissionDecision`, and the full allow / ask / deny pipeline.",
+      confusion: "A permission system is not one `if` statement. It is a decision chain that intercepts intent before execution.",
+      goal: "Put risky actions behind a clear permission pipeline.",
+    },
+    ja: {
+      focus: "`PermissionRule`、`PermissionDecision`、allow / ask / deny の流れを見る。",
+      confusion: "permission system は単一の if ではなく、実行前に意図を止める判断パイプラインです。",
+      goal: "危険な操作を明確な permission pipeline の後ろに置けるようにする。",
+    },
+  },
+  s08: {
+    zh: {
+      focus: "先盯住 `HookEvent`、`HookResult` 和固定触发时机。",
+      confusion: "hook 不是把逻辑塞回主循环，而是让主循环在固定时机对外发出插口。",
+      goal: "不重写主循环，也能在关键时机扩展行为。",
+    },
+    en: {
+      focus: "Focus on `HookEvent`, `HookResult`, and the fixed trigger points.",
+      confusion: "A hook is not random logic stuffed back into the loop. It is an extension point exposed at a fixed moment.",
+      goal: "Extend behavior at key moments without rewriting the loop.",
+    },
+    ja: {
+      focus: "`HookEvent`、`HookResult`、固定の発火タイミングを見る。",
+      confusion: "hook は主ループへ場当たり的にロジックを戻すことではなく、固定時点の拡張口です。",
+      goal: "主ループを書き換えずに重要なタイミングへ拡張を差し込めるようにする。",
+    },
+  },
+  s09: {
+    zh: {
+      focus: "先盯住 `MemoryEntry` 到底保存哪类信息、为什么不是所有上下文都进 memory。",
+      confusion: "memory 不是万能笔记本，它只保存跨会话仍然有价值、又不容易重新推导的信息。",
+      goal: "做出一个小而准的长期记忆层，而不是把上下文原样倾倒进去。",
+    },
+    en: {
+      focus: "Focus on what belongs in `MemoryEntry`, and why not all context should become memory.",
+      confusion: "Memory is not a universal notebook. It only stores knowledge that still matters across sessions and is not cheap to re-derive.",
+      goal: "Build a small, precise long-term memory layer instead of dumping raw context into storage.",
+    },
+    ja: {
+      focus: "`MemoryEntry` に何を入れるべきか、なぜ全部の文脈を memory にしないのかを見る。",
+      confusion: "memory は万能ノートではなく、会話をまたいで意味があり再導出しにくい情報だけを残します。",
+      goal: "文脈を丸ごと捨て込まない、小さく正確な長期記憶層を作る。",
+    },
+  },
+  s10: {
+    zh: {
+      focus: "先盯住 `PromptParts` 和输入组装顺序，而不是只盯一段大 prompt 字符串。",
+      confusion: "模型真正看到的是一条输入管道，不是单个神秘 system prompt 大文本。",
+      goal: "把系统规则、工具说明、动态上下文拆成可管理的输入片段。",
+    },
+    en: {
+      focus: "Focus on `PromptParts` and assembly order rather than one giant prompt string.",
+      confusion: "The model really sees an input pipeline, not one magical system prompt blob.",
+      goal: "Split system rules, tool descriptions, and dynamic context into manageable input parts.",
+    },
+    ja: {
+      focus: "`PromptParts` と組み立て順を見る。巨大な prompt 文字列だけを見ない。",
+      confusion: "モデルが実際に見るのは入力パイプラインであり、魔法の system prompt 1本ではありません。",
+      goal: "ルール、ツール説明、動的文脈を管理しやすい入力片へ分解する。",
+    },
+  },
+  s11: {
+    zh: {
+      focus: "先盯住 `RecoveryState` 和 `TransitionReason`，搞清“为什么继续”。",
+      confusion: "错误恢复不只是 try/except，而是系统知道自己该重试、压缩后重来，还是结束。",
+      goal: "让 agent 在可恢复错误后还能有条理地继续前进。",
+    },
+    en: {
+      focus: "Focus on `RecoveryState` and `TransitionReason`, especially why the system is continuing.",
+      confusion: "Recovery is not just `try/except`. The system must know whether to retry, compact and retry, or stop.",
+      goal: "Make the agent continue coherently after recoverable failures.",
+    },
+    ja: {
+      focus: "`RecoveryState` と `TransitionReason`、特に「なぜ続行するのか」を見る。",
+      confusion: "error recovery は単なる try/except ではなく、再試行・compact 後再試行・終了を区別することです。",
+      goal: "回復可能な失敗の後でも、agent が筋道立てて進めるようにする。",
+    },
+  },
+  s12: {
+    zh: {
+      focus: "先盯住 `TaskRecord`、`blockedBy`、`blocks` 这几项关系字段。",
+      confusion: "task 不再是会话里的步骤提醒，而是一张持久化工作图上的节点。",
+      goal: "做出一个会解锁后续任务的最小任务系统。",
+    },
+    en: {
+      focus: "Focus on `TaskRecord`, `blockedBy`, and `blocks`.",
+      confusion: "A task here is no longer a session reminder. It is a durable node in a work graph.",
+      goal: "Build a minimal task system that can unlock downstream work.",
+    },
+    ja: {
+      focus: "`TaskRecord`、`blockedBy`、`blocks` の関係を見る。",
+      confusion: "ここでの task は会話内メモではなく、永続 work graph のノードです。",
+      goal: "後続タスクを解放できる最小 task system を作る。",
+    },
+  },
+  s13: {
+    zh: {
+      focus: "先盯住 `RuntimeTaskState` 和 `Notification` 的分工。",
+      confusion: "后台任务不是任务板节点，而是当前正在跑的一条执行槽位。",
+      goal: "让慢命令后台运行，并在下一轮把结果带回模型。",
+    },
+    en: {
+      focus: "Focus on the split between `RuntimeTaskState` and `Notification`.",
+      confusion: "A background task is not a task-board node. It is a running execution slot.",
+      goal: "Run slow work in the background and bring the result back on a later turn.",
+    },
+    ja: {
+      focus: "`RuntimeTaskState` と `Notification` が何を分担しているかを見る。",
+      confusion: "バックグラウンドタスクはタスクボード上のノードではなく、いま走っている実行スロットです。",
+      goal: "遅い処理をバックグラウンドへ逃がし、次のターンで結果を主ループへ戻せるようにする。",
+    },
+  },
+  s14: {
+    zh: {
+      focus: "先盯住 `ScheduleRecord`、触发条件和实际执行任务之间的关系。",
+      confusion: "cron 不是任务本身，它只是“何时启动一份工作”的规则。",
+      goal: "让系统在未来某个时间自动触发工作，而不是只能等当前用户发话。",
+    },
+    en: {
+      focus: "Focus on the relationship between `ScheduleRecord`, trigger conditions, and the work that is actually launched.",
+      confusion: "Cron is not the task itself. It is a rule about when work should start.",
+      goal: "Trigger work at future times instead of waiting for the current user turn.",
+    },
+    ja: {
+      focus: "`ScheduleRecord`、発火条件、実際に起動される仕事の関係を見る。",
+      confusion: "cron は task そのものではなく、いつ仕事を始めるかのルールです。",
+      goal: "現在のユーザー発話だけでなく、将来時刻で自動的に仕事を起動できるようにする。",
+    },
+  },
+  s15: {
+    zh: {
+      focus: "先盯住 `TeamMember`、`MessageEnvelope` 和独立 inbox。",
+      confusion: "teammate 不是换了名字的 subagent，关键区别在“是否长期存在、能反复接活”。",
+      goal: "做出一个长期存在、能通过邮箱协作的多 agent 团队雏形。",
+    },
+    en: {
+      focus: "Focus on `TeamMember`, `MessageEnvelope`, and independent inboxes.",
+      confusion: "A teammate is not a renamed subagent. The difference is long-lived identity and repeatable responsibility.",
+      goal: "Build the first version of a long-lived multi-agent team that collaborates through mailboxes.",
+    },
+    ja: {
+      focus: "`TeamMember`、`MessageEnvelope`、独立 inbox を見る。",
+      confusion: "teammate は名前を変えた subagent ではなく、長寿命で繰り返し責務を持つ存在です。",
+      goal: "メールボックス経由で協力する長寿命マルチエージェントチームの雛形を作る。",
+    },
+  },
+  s16: {
+    zh: {
+      focus: "先盯住 `ProtocolEnvelope`、`request_id` 和 `RequestRecord`。",
+      confusion: "协议消息不是普通聊天消息，它必须能被系统追踪和更新状态。",
+      goal: "让团队协作从自由聊天升级成可批准、可拒绝、可跟踪的流程。",
+    },
+    en: {
+      focus: "Focus on `ProtocolEnvelope`, `request_id`, and `RequestRecord`.",
+      confusion: "A protocol message is not ordinary chat. The system must be able to track it and update its state.",
+      goal: "Turn team coordination from free-form chat into an approvable, rejectable, trackable flow.",
+    },
+    ja: {
+      focus: "`ProtocolEnvelope`、`request_id`、`RequestRecord` を見る。",
+      confusion: "protocol message は普通の会話ではなく、システムが追跡して状態更新できる必要があります。",
+      goal: "チーム協調を自由会話から、承認・拒否・追跡可能なフローへ上げる。",
+    },
+  },
+  s17: {
+    zh: {
+      focus: "先盯住 idle 恢复顺序、角色化 claim policy、claim event 和身份重注入这四件事。",
+      confusion: "自治的关键不是“它会不会自己想”，而是系统有没有定义清楚：空闲时先看谁、能认领什么、恢复时补回哪些上下文。",
+      goal: "让长期队友在不靠持续点名的情况下，也能按规则自己接住下一份工作。",
+    },
+    en: {
+      focus: "Focus on idle resume order, role-aware claim policy, claim events, and identity re-injection.",
+      confusion: "Autonomy is not the agent 'thinking on its own'. It is a defined rule for what an idle worker checks, what it may claim, and how it resumes safely.",
+      goal: "Let a long-lived teammate pick up the next piece of work without constant manual delegation.",
+    },
+    ja: {
+      focus: "特定製品らしさより、idle 復帰順序・役割付き claim policy・claim event・identity 再注入を見る。",
+      confusion: "自律性の核心は魔法の知能ではなく、空いた worker が何を先に確認し、何を claim でき、どう安全に再開するかの規則です。",
+      goal: "継続的に指名されなくても、長寿命 teammate が次の仕事を拾えるようにする。",
+    },
+  },
+  s18: {
+    zh: {
+      focus: "先盯住 `worktree_state`、`last_worktree`、`closeout`，再看 `worktree_enter` 和统一 closeout。",
+      confusion: "worktree 不是任务目标，也不是后台任务；它只是任务的独立执行车道，而且车道状态和任务状态不是一回事。",
+      goal: "让多个执行者并行改代码时，任务目标、执行目录和收尾动作都能被显式记录。",
+    },
+    en: {
+      focus: "Focus on `worktree_state`, `last_worktree`, `closeout`, then on explicit `worktree_enter` and unified closeout.",
+      confusion: "A worktree is neither the task goal nor the runtime task. It is the isolated execution lane, and lane state is not the same as task state.",
+      goal: "Make task goals, execution directories, and closeout decisions explicit when multiple workers edit in parallel.",
+    },
+    ja: {
+      focus: "`worktree_state`、`last_worktree`、`closeout` を先に見て、その後 `worktree_enter` と統一 closeout を見る。",
+      confusion: "worktree は task 目標でも runtime task でもなく、独立した実行レーンです。レーン状態と task 状態は別物です。",
+      goal: "複数 worker が並列でコードを触るとき、task 目標・実行ディレクトリ・収束動作を明示的に記録できるようにする。",
+    },
+  },
+  s19: {
+    zh: {
+      focus: "先盯住外部能力如何重新接回统一 router，而不是先掉进 transport 或认证细节。",
+      confusion: "MCP 不只是外部工具目录，但主线入口仍然应该先从 tools-first 去理解。",
+      goal: "把外部能力接进主系统，同时保持权限、路由和结果回流的一致性。",
+    },
+    en: {
+      focus: "Focus on how external capabilities rejoin the same router before diving into transport or auth detail.",
+      confusion: "MCP is more than an external tool catalog, but the cleanest mainline still starts with tools first.",
+      goal: "Connect external capabilities to the main system while keeping routing, permissions, and result flow consistent.",
+    },
+    ja: {
+      focus: "transport や auth の前に、外部 capability が同じ router へどう戻るかを見る。",
+      confusion: "MCP は単なる外部 tool 一覧ではないが、主線理解の入口は tools-first のままでよいです。",
+      goal: "外部 capability を主システムへ接続しつつ、routing・permission・結果回流の一貫性を保つ。",
+    },
+  },
+};
+
+export function getChapterGuide(version: string, locale: string): ChapterGuide | null {
+  const versionGuide = CHAPTER_GUIDES[version as VersionId];
+  if (!versionGuide) return null;
+  if (locale === "zh" || locale === "en" || locale === "ja") {
+    return versionGuide[locale];
+  }
+  return versionGuide.en;
+}
diff --git a/web/src/lib/constants.ts b/web/src/lib/constants.ts
index 0f1fdf7a8..0f039940e 100644
--- a/web/src/lib/constants.ts
+++ b/web/src/lib/constants.ts
@@ -1,37 +1,215 @@
 export const VERSION_ORDER = [
-  "s01", "s02", "s03", "s04", "s05", "s06", "s07", "s08", "s09", "s10", "s11", "s12"
+  "s01",
+  "s02",
+  "s03",
+  "s04",
+  "s05",
+  "s06",
+  "s07",
+  "s08",
+  "s09",
+  "s10",
+  "s11",
+  "s12",
+  "s13",
+  "s14",
+  "s15",
+  "s16",
+  "s17",
+  "s18",
+  "s19",
 ] as const;
 
 export const LEARNING_PATH = VERSION_ORDER;
 
 export type VersionId = typeof LEARNING_PATH[number];
+export type LearningLayer = "core" | "hardening" | "runtime" | "platform";
 
 export const VERSION_META: Record<string, {
   title: string;
   subtitle: string;
   coreAddition: string;
   keyInsight: string;
-  layer: "tools" | "planning" | "memory" | "concurrency" | "collaboration";
+  layer: LearningLayer;
   prevVersion: string | null;
 }> = {
-  s01: { title: "The Agent Loop", subtitle: "Bash is All You Need", coreAddition: "Single-tool agent loop", keyInsight: "The minimal agent kernel is a while loop + one tool", layer: "tools", prevVersion: null },
-  s02: { title: "Tools", subtitle: "One Handler Per Tool", coreAddition: "Tool dispatch map", keyInsight: "The loop stays the same; new tools register into the dispatch map", layer: "tools", prevVersion: "s01" },
-  s03: { title: "TodoWrite", subtitle: "Plan Before You Act", coreAddition: "TodoManager + nag reminder", keyInsight: "An agent without a plan drifts; list the steps first, then execute", layer: "planning", prevVersion: "s02" },
-  s04: { title: "Subagents", subtitle: "Clean Context Per Subtask", coreAddition: "Subagent spawn with isolated messages[]", keyInsight: "Subagents use independent messages[], keeping the main conversation clean", layer: "planning", prevVersion: "s03" },
-  s05: { title: "Skills", subtitle: "Load on Demand", coreAddition: "SkillLoader + two-layer injection", keyInsight: "Inject knowledge via tool_result when needed, not upfront in the system prompt", layer: "planning", prevVersion: "s04" },
-  s06: { title: "Compact", subtitle: "Three-Layer Compression", coreAddition: "micro-compact + auto-compact + archival", keyInsight: "Context will fill up; three-layer compression strategy enables infinite sessions", layer: "memory", prevVersion: "s05" },
-  s07: { title: "Tasks", subtitle: "Task Graph + Dependencies", coreAddition: "TaskManager with file-based state + dependency graph", keyInsight: "A file-based task graph with ordering, parallelism, and dependencies -- the coordination backbone for multi-agent work", layer: "planning", prevVersion: "s06" },
-  s08: { title: "Background Tasks", subtitle: "Background Threads + Notifications", coreAddition: "BackgroundManager + notification queue", keyInsight: "Run slow operations in the background; the agent keeps thinking ahead", layer: "concurrency", prevVersion: "s07" },
-  s09: { title: "Agent Teams", subtitle: "Teammates + Mailboxes", coreAddition: "TeammateManager + file-based mailbox", keyInsight: "When one agent can't finish, delegate to persistent teammates via async mailboxes", layer: "collaboration", prevVersion: "s08" },
-  s10: { title: "Team Protocols", subtitle: "Shared Communication Rules", coreAddition: "request_id correlation for two protocols", keyInsight: "One request-response pattern drives all team negotiation", layer: "collaboration", prevVersion: "s09" },
-  s11: { title: "Autonomous Agents", subtitle: "Scan Board, Claim Tasks", coreAddition: "Task board polling + timeout-based self-governance", keyInsight: "Teammates scan the board and claim tasks themselves; no need for the lead to assign each one", layer: "collaboration", prevVersion: "s10" },
-  s12: { title: "Worktree + Task Isolation", subtitle: "Isolate by Directory", coreAddition: "Composable worktree lifecycle + event stream over a shared task board", keyInsight: "Each works in its own directory; tasks manage goals, worktrees manage directories, bound by ID", layer: "collaboration", prevVersion: "s11" },
+  s01: {
+    title: "The Agent Loop",
+    subtitle: "Minimal Closed Loop",
+    coreAddition: "LoopState + tool_result feedback",
+    keyInsight: "An agent is just a loop: send messages, execute tools, feed results back, repeat.",
+    layer: "core",
+    prevVersion: null,
+  },
+  s02: {
+    title: "Tool Use",
+    subtitle: "Route Intent into Action",
+    coreAddition: "Tool specs + dispatch map",
+    keyInsight: "Adding a tool means adding one handler. The loop never changes.",
+    layer: "core",
+    prevVersion: "s01",
+  },
+  s03: {
+    title: "TodoWrite",
+    subtitle: "Session Planning",
+    coreAddition: "PlanningState + reminder loop",
+    keyInsight: "A visible plan keeps the agent on track when tasks get complex.",
+    layer: "core",
+    prevVersion: "s02",
+  },
+  s04: {
+    title: "Subagent",
+    subtitle: "Fresh Context per Subtask",
+    coreAddition: "Delegation with isolated message history",
+    keyInsight: "A subagent is mainly a context boundary, not a process trick.",
+    layer: "core",
+    prevVersion: "s03",
+  },
+  s05: {
+    title: "Skills",
+    subtitle: "Discover Cheap, Load Deep",
+    coreAddition: "Skill registry + on-demand injection",
+    keyInsight: "Discover cheaply, load deeply -- only when needed.",
+    layer: "core",
+    prevVersion: "s04",
+  },
+  s06: {
+    title: "Context Compact",
+    subtitle: "Keep the Active Context Small",
+    coreAddition: "Persist markers + micro compact + summary compact",
+    keyInsight: "Compaction isn't deleting history -- it's relocating detail so the agent can keep working.",
+    layer: "core",
+    prevVersion: "s05",
+  },
+  s07: {
+    title: "Permission System",
+    subtitle: "Intent Must Pass Safety",
+    coreAddition: "deny / mode / allow / ask pipeline",
+    keyInsight: "Safety is a pipeline, not a boolean: deny, check mode, allow, then ask.",
+    layer: "hardening",
+    prevVersion: "s06",
+  },
+  s08: {
+    title: "Hook System",
+    subtitle: "Extend Without Rewriting the Loop",
+    coreAddition: "Lifecycle events + side-effect hooks",
+    keyInsight: "The loop owns control flow; hooks only observe, block, or annotate at named moments.",
+    layer: "hardening",
+    prevVersion: "s07",
+  },
+  s09: {
+    title: "Memory System",
+    subtitle: "Keep Only What Survives Sessions",
+    coreAddition: "Typed memory records + reload path",
+    keyInsight: "Memory gives direction; current observation gives truth.",
+    layer: "hardening",
+    prevVersion: "s08",
+  },
+  s10: {
+    title: "System Prompt",
+    subtitle: "Build Inputs as a Pipeline",
+    coreAddition: "Prompt sections + dynamic assembly",
+    keyInsight: "The model sees a constructed input pipeline, not one giant static string.",
+    layer: "hardening",
+    prevVersion: "s09",
+  },
+  s11: {
+    title: "Error Recovery",
+    subtitle: "Recover, Then Continue",
+    coreAddition: "Continuation reasons + retry branches",
+    keyInsight: "Most failures aren't true task failure -- they're signals to try a different path.",
+    layer: "hardening",
+    prevVersion: "s10",
+  },
+  s12: {
+    title: "Task System",
+    subtitle: "Durable Work Graph",
+    coreAddition: "Task records + dependencies + unlock rules",
+    keyInsight: "Todo lists help a session; durable task graphs coordinate work that outlives it.",
+    layer: "runtime",
+    prevVersion: "s11",
+  },
+  s13: {
+    title: "Background Tasks",
+    subtitle: "Separate Goal from Running Work",
+    coreAddition: "RuntimeTaskState + async execution slots",
+    keyInsight: "Background execution is a runtime lane, not a second main loop.",
+    layer: "runtime",
+    prevVersion: "s12",
+  },
+  s14: {
+    title: "Cron Scheduler",
+    subtitle: "Let Time Trigger Work",
+    coreAddition: "Scheduled triggers over runtime tasks",
+    keyInsight: "Scheduling is not a separate system -- it just feeds the same agent loop from a timer.",
+    layer: "runtime",
+    prevVersion: "s13",
+  },
+  s15: {
+    title: "Agent Teams",
+    subtitle: "Persistent Specialists",
+    coreAddition: "Team roster + teammate lifecycle",
+    keyInsight: "Teammates persist beyond one prompt, have identity, and coordinate through durable channels.",
+    layer: "platform",
+    prevVersion: "s14",
+  },
+  s16: {
+    title: "Team Protocols",
+    subtitle: "Shared Request-Response Rules",
+    coreAddition: "Protocol envelopes + request correlation",
+    keyInsight: "A protocol request is a structured message with an ID; the response must reference the same ID.",
+    layer: "platform",
+    prevVersion: "s15",
+  },
+  s17: {
+    title: "Autonomous Agents",
+    subtitle: "Self-Claim and Self-Resume",
+    coreAddition: "Idle polling + role-aware self-claim + resume context",
+    keyInsight: "Autonomy is a bounded mechanism -- idle, scan, claim, resume -- not magic.",
+    layer: "platform",
+    prevVersion: "s16",
+  },
+  s18: {
+    title: "Worktree Isolation",
+    subtitle: "Separate Directory, Separate Lane",
+    coreAddition: "Task-worktree state + explicit enter/closeout lifecycle",
+    keyInsight: "Tasks answer what; worktrees answer where. Keep them separate.",
+    layer: "platform",
+    prevVersion: "s17",
+  },
+  s19: {
+    title: "MCP & Plugin",
+    subtitle: "External Capability Bus",
+    coreAddition: "Scoped servers + capability routing",
+    keyInsight: "External capabilities join the same routing, permission, and result-append path as native tools.",
+    layer: "platform",
+    prevVersion: "s18",
+  },
 };
 
 export const LAYERS = [
-  { id: "tools" as const, label: "Tools & Execution", color: "#3B82F6", versions: ["s01", "s02"] },
-  { id: "planning" as const, label: "Planning & Coordination", color: "#10B981", versions: ["s03", "s04", "s05", "s07"] },
-  { id: "memory" as const, label: "Memory Management", color: "#8B5CF6", versions: ["s06"] },
-  { id: "concurrency" as const, label: "Concurrency", color: "#F59E0B", versions: ["s08"] },
-  { id: "collaboration" as const, label: "Collaboration", color: "#EF4444", versions: ["s09", "s10", "s11", "s12"] },
+  {
+    id: "core" as const,
+    label: "Core Single-Agent",
+    color: "#2563EB",
+    versions: ["s01", "s02", "s03", "s04", "s05", "s06"],
+  },
+  {
+    id: "hardening" as const,
+    label: "Production Hardening",
+    color: "#059669",
+    versions: ["s07", "s08", "s09", "s10", "s11"],
+  },
+  {
+    id: "runtime" as const,
+    label: "Task Runtime",
+    color: "#D97706",
+    versions: ["s12", "s13", "s14"],
+  },
+  {
+    id: "platform" as const,
+    label: "Multi-Agent Platform",
+    color: "#DC2626",
+    versions: ["s15", "s16", "s17", "s18", "s19"],
+  },
 ] as const;
diff --git a/web/src/lib/diagram-localization.ts b/web/src/lib/diagram-localization.ts
new file mode 100644
index 000000000..7a9f3e61e
--- /dev/null
+++ b/web/src/lib/diagram-localization.ts
@@ -0,0 +1,828 @@
+export type DiagramLocale = "zh" | "en" | "ja";
+
+type ReplacementPair = readonly [from: string, to: string];
+
+const FLOW_REPLACEMENTS: Record<Exclude<DiagramLocale, "en">, ReplacementPair[]> = {
+  zh: [
+    ["LLM Call", "模型调用"],
+    ["Model Call", "模型调用"],
+    ["User Input", "用户输入"],
+    ["Main Loop", "主循环"],
+    ["Continue Loop", "继续主循环"],
+    ["Continue or Exit", "继续或退出"],
+    ["Model Intent", "模型意图"],
+    ["Normalize", "规范化"],
+    ["Action", "动作"],
+    ["Permission", "权限"],
+    ["Policy?", "策略？"],
+    ["Ask User /", "询问用户 /"],
+    ["Return Deny", "返回拒绝"],
+    ["Append Structured", "追加结构化"],
+    ["Permission Result", "权限结果"],
+    ["Emit Lifecycle", "发出生命周期"],
+    ["Event", "事件"],
+    ["Hooks", "Hook"],
+    ["Registered?", "已注册？"],
+    ["Dispatch Hook", "分发 Hook"],
+    ["Envelope", "信封"],
+    ["Run Core Tool", "运行核心工具"],
+    ["Audit / Trace /", "审计 / 追踪 /"],
+    ["Policy Side Effects", "策略副作用"],
+    ["New Turn", "新一轮"],
+    ["Load Relevant", "加载相关"],
+    ["Assemble Prompt", "组装 Prompt"],
+    ["with Memory", "并注入记忆"],
+    ["Run Work", "执行工作"],
+    ["Extract Durable", "提炼持久"],
+    ["Facts", "事实"],
+    ["Persist Memory", "写入记忆"],
+    ["Next Session /", "下一会话 /"],
+    ["Next Turn", "下一轮"],
+    ["Stable Policy", "稳定策略"],
+    ["Runtime State", "运行时状态"],
+    ["Task Context", "任务上下文"],
+    ["Prompt Section", "Prompt 分段"],
+    ["Assembly", "装配"],
+    ["Tool Loop / Text", "工具循环 / 文本"],
+    ["Response", "响应"],
+    ["Tool Result", "工具结果"],
+    ["Error?", "出错？"],
+    ["Classify Error", "分类错误"],
+    ["Retry / Fallback /", "重试 / 回退 /"],
+    ["Ask User / Stop", "询问用户 / 停止"],
+    ["Write Continuation", "写入续行"],
+    ["Reason", "原因"],
+    ["Cron Tick", "Cron tick"],
+    ["Rule Match?", "规则命中？"],
+    ["Wait for Next", "等待下一次"],
+    ["Create Runtime", "创建运行时"],
+    ["Queue for", "排入"],
+    ["Background Runtime", "后台运行时"],
+    ["Notify Runtime /", "通知运行时 /"],
+    ["Write Schedule Event", "写入调度事件"],
+    ["Execution Continues", "执行继续"],
+    ["Elsewhere", "在其他车道"],
+    ["Capability", "能力"],
+    ["Request", "请求"],
+    ["Discover Native /", "发现原生 /"],
+    ["Plugin / MCP", "插件 / MCP"],
+    ["Route to", "路由到"],
+    ["Native Tool", "原生工具"],
+    ["Plugin or MCP", "插件或 MCP"],
+    ["Server Call", "服务调用"],
+    ["Normalize Result /", "标准化结果 /"],
+    ["Apply Policy", "应用策略"],
+    ["Append Back to", "回写到"],
+    ["Mainline", "主线"],
+    ["Create Todos", "创建待办"],
+    ["Execute Bash", "执行 Bash"],
+    ["Execute Tool", "执行工具"],
+    ["Execute Tool /", "执行工具 /"],
+    ["Protocol Action", "协议动作"],
+    ["Append Result", "追加结果"],
+    ["Append and", "追加并"],
+    ["Continue", "继续"],
+    ["Tool Dispatch", "工具分发"],
+    ["bash / read / write / edit", "bash / read / write / edit"],
+    ["Spawn Subagent", "生成子 Agent"],
+    ["fresh messages[]", "独立 messages[]"],
+    ["Subagent Loop", "子 Agent 循环"],
+    ["Read SKILL.md", "读取 SKILL.md"],
+    ["Inject via", "通过"],
+    ["tool_result", "tool_result"],
+    ["Compress Context", "压缩上下文"],
+    ["Over token", "超过 token"],
+    ["limit?", "上限？"],
+    ["Teammate", "队友"],
+    ["Spawn", "生成"],
+    ["Send Message", "发送消息"],
+    ["JSONL inbox", "JSONL 收件箱"],
+    ["Teammate Agent", "队友 Agent"],
+    ["own loop", "独立循环"],
+    ["Task Board CRUD", "任务板 CRUD"],
+    ["Unlock / Respect", "解锁 / 遵守"],
+    ["Dependencies", "依赖"],
+    ["Inbox First,", "先看收件箱，"],
+    ["Then Claimable Tasks", "再找可认领任务"],
+    ["Auto-Claim +", "自动认领 +"],
+    ["Write Claim Event", "写入认领事件"],
+    ["Enter Idle", "进入空闲"],
+    ["Phase", "阶段"],
+    ["Ensure Identity", "确保身份"],
+    ["Context", "上下文"],
+    ["Resume /", "恢复 /"],
+    ["New Work", "新工作"],
+    ["Create Durable", "创建持久"],
+    ["Request Record:", "请求记录："],
+    ["pending -> resolved", "pending -> resolved"],
+    ["Task State:", "任务状态："],
+    ["bind + worktree_state", "绑定 + worktree_state"],
+    ["Create / Enter", "创建 / 进入"],
+    ["Worktree Lane", "Worktree 车道"],
+    ["Run in", "运行于"],
+    ["Isolated Dir", "隔离目录"],
+    ["Emit enter / run /", "发出 enter / run /"],
+    ["closeout events", "closeout 事件"],
+    ["Optional Read", "可选读取"],
+    ["worktree_events", "worktree_events"],
+    ["worktree_closeout", "worktree_closeout"],
+    ["keep | remove", "保留 | 移除"],
+    ["Output", "输出"],
+    ["yes", "是"],
+    ["no", "否"],
+    ["allow", "允许"],
+    ["deny / ask", "拒绝 / 询问"],
+    ["observe", "观察"],
+    ["visible input", "可见输入"],
+    ["request", "请求"],
+    ["task", "任务"],
+    ["spawn", "生成"],
+    ["runtime", "运行时"],
+    ["sync", "同步"],
+    ["team tool?", "团队工具？"],
+    ["task tool?", "任务工具？"],
+    ["protocol tool?", "协议工具？"],
+    ["runtime tool?", "运行时工具？"],
+    ["worktree tool?", "worktree 工具？"],
+    ["load_skill?", "load_skill?"],
+    ["skill", "技能"],
+    ["other", "其他"],
+    ["claimable task", "可认领任务"],
+    ["inbox message", "收件箱消息"],
+    ["resume work", "恢复工作"],
+    ["task ops", "任务操作"],
+    ["task result", "任务结果"],
+    ["run/status", "运行/状态"],
+    ["run/status result", "运行/状态结果"],
+    ["create/enter", "创建/进入"],
+    ["create/enter result", "创建/进入结果"],
+    ["emit create/enter", "发出 create/enter"],
+    ["emit closeout", "发出 closeout"],
+    ["closeout result", "closeout 结果"],
+    ["optional query", "可选查询"],
+    ["events result", "事件结果"],
+    ["allocate lane", "分配车道"],
+    ["local", "本地"],
+    ["plugin / mcp", "插件 / mcp"],
+    ["idle", "空闲"],
+  ],
+  ja: [
+    ["LLM Call", "モデル呼び出し"],
+    ["Model Call", "モデル呼び出し"],
+    ["User Input", "ユーザー入力"],
+    ["Main Loop", "主ループ"],
+    ["Continue Loop", "ループ継続"],
+    ["Continue or Exit", "継続または終了"],
+    ["Model Intent", "モデル意図"],
+    ["Normalize", "正規化"],
+    ["Action", "操作"],
+    ["Permission", "権限"],
+    ["Policy?", "ポリシー？"],
+    ["Ask User /", "ユーザー確認 /"],
+    ["Return Deny", "拒否を返す"],
+    ["Append Structured", "構造化された"],
+    ["Permission Result", "権限結果を追加"],
+    ["Emit Lifecycle", "ライフサイクル"],
+    ["Event", "イベント"],
+    ["Hooks", "Hook"],
+    ["Registered?", "登録済み？"],
+    ["Dispatch Hook", "Hook を配信"],
+    ["Envelope", "封筒"],
+    ["Run Core Tool", "コアツール実行"],
+    ["Audit / Trace /", "監査 / 追跡 /"],
+    ["Policy Side Effects", "ポリシー副作用"],
+    ["New Turn", "新しいターン"],
+    ["Load Relevant", "関連"],
+    ["Assemble Prompt", "Prompt を組み立て"],
+    ["with Memory", "記憶を注入"],
+    ["Run Work", "作業実行"],
+    ["Extract Durable", "永続"],
+    ["Facts", "事実を抽出"],
+    ["Persist Memory", "記憶を保存"],
+    ["Next Session /", "次回セッション /"],
+    ["Next Turn", "次のターン"],
+    ["Stable Policy", "安定ポリシー"],
+    ["Runtime State", "ランタイム状態"],
+    ["Task Context", "タスク文脈"],
+    ["Prompt Section", "Prompt セクション"],
+    ["Assembly", "組み立て"],
+    ["Tool Loop / Text", "ツールループ / テキスト"],
+    ["Response", "応答"],
+    ["Tool Result", "ツール結果"],
+    ["Error?", "エラー？"],
+    ["Classify Error", "エラー分類"],
+    ["Retry / Fallback /", "再試行 / フォールバック /"],
+    ["Ask User / Stop", "ユーザー確認 / 停止"],
+    ["Write Continuation", "継続理由を"],
+    ["Reason", "記録"],
+    ["Cron Tick", "Cron tick"],
+    ["Rule Match?", "ルール一致？"],
+    ["Wait for Next", "次の"],
+    ["Create Runtime", "ランタイム"],
+    ["Queue for", "へ投入"],
+    ["Background Runtime", "バックグラウンド実行"],
+    ["Notify Runtime /", "ランタイム通知 /"],
+    ["Write Schedule Event", "スケジュールイベント記録"],
+    ["Execution Continues", "実行は"],
+    ["Elsewhere", "別レーンで継続"],
+    ["Capability", "能力"],
+    ["Request", "要求"],
+    ["Discover Native /", "ネイティブ /"],
+    ["Plugin / MCP", "プラグイン / MCP を探索"],
+    ["Route to", "へルーティング"],
+    ["Native Tool", "ネイティブツール"],
+    ["Plugin or MCP", "プラグインまたは MCP"],
+    ["Server Call", "サーバー呼び出し"],
+    ["Normalize Result /", "結果正規化 /"],
+    ["Apply Policy", "ポリシー適用"],
+    ["Append Back to", "主線へ"],
+    ["Mainline", "回写"],
+    ["Create Todos", "Todo 作成"],
+    ["Execute Bash", "Bash 実行"],
+    ["Execute Tool", "ツール実行"],
+    ["Execute Tool /", "ツール実行 /"],
+    ["Protocol Action", "プロトコル操作"],
+    ["Append Result", "結果を追加"],
+    ["Append and", "追加して"],
+    ["Continue", "継続"],
+    ["Tool Dispatch", "ツール分配"],
+    ["Spawn Subagent", "サブエージェント生成"],
+    ["fresh messages[]", "独立 messages[]"],
+    ["Subagent Loop", "サブエージェントループ"],
+    ["Read SKILL.md", "SKILL.md を読む"],
+    ["Inject via", "経由で注入"],
+    ["Compress Context", "文脈圧縮"],
+    ["Over token", "token"],
+    ["limit?", "上限超過？"],
+    ["Teammate", "チームメイト"],
+    ["Spawn", "生成"],
+    ["Send Message", "メッセージ送信"],
+    ["JSONL inbox", "JSONL inbox"],
+    ["Teammate Agent", "チームメイト Agent"],
+    ["own loop", "独自ループ"],
+    ["Task Board CRUD", "タスク板 CRUD"],
+    ["Unlock / Respect", "解除 / 尊重"],
+    ["Dependencies", "依存関係"],
+    ["Inbox First,", "まず inbox、"],
+    ["Then Claimable Tasks", "次に claimable tasks"],
+    ["Auto-Claim +", "自動 claim +"],
+    ["Write Claim Event", "claim event 記録"],
+    ["Enter Idle", "アイドルへ"],
+    ["Phase", "入る"],
+    ["Ensure Identity", "身元"],
+    ["Context", "文脈を確認"],
+    ["Resume /", "再開 /"],
+    ["New Work", "新規作業"],
+    ["Create Durable", "永続"],
+    ["Request Record:", "要求記録："],
+    ["Task State:", "タスク状態："],
+    ["Create / Enter", "作成 / 進入"],
+    ["Worktree Lane", "Worktree レーン"],
+    ["Run in", "で実行"],
+    ["Isolated Dir", "隔離ディレクトリ"],
+    ["Emit enter / run /", "enter / run /"],
+    ["closeout events", "closeout event 発行"],
+    ["Optional Read", "任意読み取り"],
+    ["Output", "出力"],
+    ["yes", "はい"],
+    ["no", "いいえ"],
+    ["allow", "許可"],
+    ["deny / ask", "拒否 / 確認"],
+    ["observe", "観測"],
+    ["visible input", "可視入力"],
+    ["request", "要求"],
+    ["task", "タスク"],
+    ["spawn", "生成"],
+    ["runtime", "ランタイム"],
+    ["sync", "同期"],
+    ["team tool?", "チームツール？"],
+    ["task tool?", "タスクツール？"],
+    ["protocol tool?", "プロトコルツール？"],
+    ["runtime tool?", "ランタイムツール？"],
+    ["worktree tool?", "worktree ツール？"],
+    ["skill", "スキル"],
+    ["other", "その他"],
+    ["idle", "アイドル"],
+  ],
+};
+
+const ARCHITECTURE_REPLACEMENTS: Record<Exclude<DiagramLocale, "en">, ReplacementPair[]> = {
+  zh: [
+    [
+      "Background tasks fully separate the existence of work from one live execution attempt, which is where runtime records become first-class.",
+      "后台任务把“工作目标存在”与“某次执行正在运行”彻底拆开，runtime record 因而第一次成为一等结构。",
+    ],
+    [
+      "Drains background notifications before the next model call.",
+      "下一轮调用模型前，先把后台通知排空并带回主线。",
+    ],
+    [
+      "The durable task goal still lives on the task board.",
+      "持久任务目标仍然留在任务板上。",
+    ],
+    [
+      "Describes one running or completed execution slot.",
+      "描述一条正在运行或已经完成的执行槽位。",
+    ],
+    [
+      "The full artifact goes to disk while notifications carry only a preview.",
+      "完整产物写入磁盘，通知里只带预览摘要。",
+    ],
+    [
+      "Slow commands execute on a side path while the main loop keeps moving.",
+      "慢命令在旁路车道里执行，主循环继续向前推进。",
+    ],
+    [
+      "The bridge back into the main loop.",
+      "把结果重新带回主循环的桥梁。",
+    ],
+    [
+      "The loop creates a runtime record",
+      "主循环先创建 runtime record",
+    ],
+    [
+      "A background slot runs the slow command",
+      "后台槽位执行慢命令",
+    ],
+    [
+      "notification plus output_file returns to the main system",
+      "notification 与 output_file 一起回到主系统",
+    ],
+    ["Notification Drain", "通知排空"],
+    ["Task Goal", "任务目标"],
+    ["Background Execution Slot", "后台执行线"],
+    ["Agent Loop", "Agent 循环"],
+    ["Assistant Content", "Assistant 内容"],
+    ["Dispatch Map", "分发映射"],
+    ["Dispatch Entry", "分发条目"],
+    ["Todo List", "Todo 列表"],
+    ["Parent messages", "父 messages"],
+    ["Child messages", "子 messages"],
+    ["Subtask Request", "子任务请求"],
+    ["Skill Discovery", "技能发现"],
+    ["Skill Load", "技能加载"],
+    ["Skill Registry", "技能注册表"],
+    ["Persisted Output", "持久输出"],
+    ["Summary State", "摘要状态"],
+    ["Micro Compact Record", "微压缩记录"],
+    ["Summary Compact", "摘要压缩"],
+    ["Permission Gate", "权限闸门"],
+    ["Normalized Intent", "规范化意图"],
+    ["Lifecycle Events", "生命周期事件"],
+    ["Hook Registry", "Hook 注册表"],
+    ["Audit Sink", "审计落点"],
+    ["Memory Store", "记忆存储"],
+    ["Prompt Builder", "Prompt 构建器"],
+    ["Runtime Context", "运行时上下文"],
+    ["Section Order", "段落顺序"],
+    ["Recovery Manager", "恢复管理器"],
+    ["Continuation Reason", "续行原因"],
+    ["Retry Bounds", "重试边界"],
+    ["Unlock Rules", "解锁规则"],
+    ["Task Board", "任务板"],
+    ["Dependency Edges", "依赖边"],
+    ["Notification Drain", "通知排空"],
+    ["Task Goal", "任务目标"],
+    ["Schedule Matcher", "调度匹配器"],
+    ["Lead Orchestrator", "主协调者"],
+    ["Team Roster", "团队 roster"],
+    ["Inbox", "收件箱"],
+    ["Persistent Teammate", "持久队友"],
+    ["MessageEnvelope", "消息信封"],
+    ["Protocol Envelope", "协议信封"],
+    ["Protocol State Machine", "协议状态机"],
+    ["Request Store", "请求存储"],
+    ["Idle Poll Loop", "空闲轮询循环"],
+    ["Claim Policy", "认领策略"],
+    ["Claim Events", "认领事件"],
+    ["Autonomous Worker", "自治执行者"],
+    ["Task-to-Lane Binding", "任务到车道绑定"],
+    ["Closeout Semantics", "收尾语义"],
+    ["Worktree Index", "Worktree 索引"],
+    ["Event Log", "事件日志"],
+    ["Isolated Directory Lane", "隔离目录车道"],
+    ["Closeout Record", "收尾记录"],
+    ["Capability Router", "能力路由器"],
+    ["Shared Permission Gate", "共享权限闸门"],
+    ["Result Normalizer", "结果标准化器"],
+    ["Plugin Manifest", "插件清单"],
+    ["Capability View", "能力视图"],
+    ["Native Tool", "原生工具"],
+    ["MCP / Plugin Lane", "MCP / 插件车道"],
+    ["Scoped Capability", "作用域能力"],
+    ["NEW", "新增"],
+  ],
+  ja: [
+    [
+      "The first chapter establishes the smallest closed loop: user input enters messages[], the model decides whether to call a tool, and the result flows back into the same loop.",
+      "最初の章では最小の閉ループを作ります。ユーザー入力が `messages[]` に入り、モデルが tool を呼ぶか判断し、その結果が同じループへ戻ります。",
+    ],
+    [
+      "This chapter upgrades one tool call into a stable multi-tool routing layer while keeping the main loop unchanged.",
+      "この章では 1 回の tool 呼び出しを、主ループを変えずに複数 tool を安定して扱える routing 層へ引き上げます。",
+    ],
+    [
+      "The third chapter makes session planning explicit so the agent gains a dedicated session-planning state.",
+      "第 3 章ではセッション内の計画を明示化し、agent に専用の session-planning state を与えます。",
+    ],
+    [
+      "This chapter isolates subtasks from the parent context and introduces the first explicit multi-loop structure.",
+      "この章では子タスクを親文脈から切り離し、初めて明示的な multi-loop 構造を導入します。",
+    ],
+    [
+      "The skill system splits knowledge into a discovery layer and an on-demand loading layer so the prompt does not start bloated.",
+      "skill system は知識を discovery 層と on-demand loading 層へ分け、prompt が最初から膨らみすぎないようにします。",
+    ],
+    [
+      "Context compaction is where the system first separates the active window from offloaded detail so long sessions stay usable.",
+      "context compact では active window と外へ逃がした detail が初めて分かれ、長いセッションでも使い続けられるようになります。",
+    ],
+    [
+      "From this chapter onward, execution gets a real control-plane gate: model intent must become a permission request before it runs.",
+      "この章から実行前に本物の control-plane gate が入り、model intent は実行前に permission request へ変換されます。",
+    ],
+    [
+      "Hooks give the loop stable sidecar extension points so logging, audit, and tracing separate from the core path.",
+      "hook は loop の周囲に安定した sidecar 拡張点を与え、logging・audit・tracing を主線から分離します。",
+    ],
+    [
+      "Long-term memory layers cross-session facts away from immediate context and introduces a real durable knowledge container.",
+      "long-term memory は会話をまたぐ事実を即時文脈から分離し、本物の durable knowledge container を導入します。",
+    ],
+    [
+      "System input becomes an assembly pipeline here: the model no longer sees one giant mysterious prompt, but a bounded set of input sections.",
+      "ここでは system input が assembly pipeline になり、モデルは巨大で謎めいた prompt 1 本ではなく、境界のある入力 section 群を見るようになります。",
+    ],
+    [
+      "Error recovery formally brings failure into the state machine so the system records why it continues, retries, or stops.",
+      "error recovery は failure を正式に state machine へ取り込み、なぜ続行し、なぜ再試行し、なぜ停止するのかを記録します。",
+    ],
+    [
+      "The task system is where session steps become a durable work graph that can progress real work nodes across turns.",
+      "task system では session step が durable work graph へ昇格し、複数ターンをまたいで本当の work node を進められるようになります。",
+    ],
+    [
+      "The cron scheduler makes time a first-class trigger source while still handing execution off to the runtime layer.",
+      "cron scheduler は時間を first-class な trigger source に引き上げつつ、実行自体は runtime layer に渡します。",
+    ],
+    [
+      "This is where the system moves from one executor toward a long-lived team with persistent teammates, a roster, and inboxes.",
+      "ここでシステムは単一 executor から、persistent teammate・roster・inbox を持つ長期チームへ進みます。",
+    ],
+    [
+      "Team protocols upgrade collaboration from free-form text into structured request flows centered on request_id and durable request records.",
+      "team protocol は協調を自由文から、`request_id` と durable request record を中心にした structured request flow へ引き上げます。",
+    ],
+    [
+      "The autonomy chapter moves teammates from waiting for assignments to self-claiming eligible work under a claim policy and resuming with context.",
+      "autonomy 章では teammate が割り当て待ちから、claim policy の下で自分で仕事を見つけ、context を持って resume する段階へ進みます。",
+    ],
+    [
+      "The worktree chapter pulls execution environments out of the main directory: tasks still express goals while worktrees become isolated, observable, closeout-capable lanes.",
+      "worktree 章では実行環境を main directory から切り離します。task は引き続き goal を表し、worktree は isolated で観測可能な closeout 付き lane になります。",
+    ],
+    [
+      "The final chapter reunifies native tools, plugins, and MCP servers on one capability bus so external capability returns to the same control plane.",
+      "最後の章では native tool・plugin・MCP server を 1 本の capability bus へ再統合し、external capability を同じ control plane へ戻します。",
+    ],
+    [
+      "Each turn calls the model, handles the output, then decides whether to continue.",
+      "各ターンでモデルを呼び、出力を処理し、その後で続けるかどうかを決めます。",
+    ],
+    [
+      "User, assistant, and tool result history accumulates here.",
+      "ユーザー、assistant、tool result の履歴がここへ積み上がります。",
+    ],
+    [
+      "The agent becomes real when tool results return into the next reasoning step.",
+      "agent が本当に動き出すのは、tool result が次の推論へ戻るときです。",
+    ],
+    ["The smallest runnable session state.", "最小で実行可能なセッション状態です。"],
+    ["The model output for the current turn.", "現在のターンでモデルが出した内容です。"],
+    ["User message enters messages[]", "ユーザーメッセージが `messages[]` に入る"],
+    ["Model emits tool_use or text", "モデルが `tool_use` またはテキストを出す"],
+    ["Tool result writes back into the next turn", "tool result が次のターンへ書き戻される"],
+    ["Stable Main Loop", "安定した主ループ"],
+    [
+      "The main loop still only owns model calls and write-back.",
+      "主ループは引き続き、モデル呼び出しと結果の回写だけを担当します。",
+    ],
+    ["ToolSpec Catalog", "ToolSpec カタログ"],
+    ["Describes tool capabilities to the model.", "tool の能力をモデルへ説明します。"],
+    ["Routes a tool call to the correct handler by name.", "tool 名で対応する handler へルーティングします。"],
+    ["Structured tool arguments emitted by the model.", "モデルが出した構造化された tool 引数です。"],
+    ["Schema plus description.", "schema と説明です。"],
+    ["Mapping from tool name to function.", "tool 名から関数への対応表です。"],
+    ["The model selects a tool", "モデルが使う tool を選ぶ"],
+    ["The dispatch map resolves the handler", "dispatch map が handler を解決する"],
+    ["The handler returns a tool_result", "handler が `tool_result` を返す"],
+    ["Plan Before Execution", "実行前に計画する"],
+    ["Break the larger goal into trackable steps before acting.", "大きな目標を、いま追跡できる手順へ分解してから動きます。"],
+    ["Reminder Loop", "リマインダーループ"],
+    ["Each turn revisits the current todo list to avoid drift.", "各ターンで現在の todo を見直し、途中の漂流を防ぎます。"],
+    ["The smallest planning unit inside one session.", "1 セッション内での最小の計画単位です。"],
+    ["Tracks what steps exist and which one is active.", "どんな手順があり、どれが現在アクティブかを記録します。"],
+    ["Session-scoped, not durable.", "セッション内だけで使うもので、永続ではありません。"],
+    ["The goal becomes steps first", "まず目標を手順へ落とす"],
+    ["The current step guides tool choice", "現在の手順が tool 選択を導く"],
+    ["Progress writes back into planning state", "進捗が planning state へ書き戻される"],
+    ["Parent Loop", "親ループ"],
+    ["Keeps the main goal and the integration responsibility.", "主目標と最終統合の責任を保ちます。"],
+    ["Child Loop", "子ループ"],
+    ["Provides a clean context for the subtask.", "子タスクのためのきれいな文脈を与えます。"],
+    ["Delegation Boundary", "委譲境界"],
+    ["Defines when work is delegated versus kept in the parent loop.", "いつ仕事を子へ渡し、いつ親ループに残すかを決めます。"],
+    ["The parent agent's long-lived context.", "親 agent の長く保持される文脈です。"],
+    ["An isolated one-shot context for the delegated subtask.", "委譲された子タスク専用の、一回限りの独立文脈です。"],
+    ["One-shot Subagent", "単発サブエージェント"],
+    ["Exits after returning a summary and does not keep long-lived identity.", "要約を返したら終了し、長期的な identity は持ちません。"],
+    ["The boundary object handed from parent to child.", "親ループから子ループへ渡される境界オブジェクトです。"],
+    ["The parent loop defines a subtask", "親ループが子タスクを定義する"],
+    ["The child loop runs in isolated messages", "子ループが独立した `messages` で動く"],
+    ["A summary returns to the parent loop", "要約が親ループへ戻る"],
+    ["Learns which skills exist through a cheap discovery pass.", "軽い discovery pass で、どんな skill があるかを把握します。"],
+    ["Loads deep instructions only when they are actually needed.", "本当に必要になった時だけ深い説明を読み込みます。"],
+    ["Stores skill names, summaries, and paths.", "skill の名前、概要、パスを保存します。"],
+    ["Keep the Loop Lightweight", "ループを軽く保つ"],
+    ["Skills are injected on demand instead of being permanently fused into the system prompt.", "skill は system prompt に常駐させず、必要な時だけ注入します。"],
+    ["The deep instruction source for a skill.", "skill の深い説明を置く元ファイルです。"],
+    ["Discover the skill entry first", "まず skill の入口を見つける"],
+    ["Read SKILL.md when needed", "必要になった時だけ `SKILL.md` を読む"],
+    ["Feed the loaded result back into the main loop", "読み込んだ結果を主ループへ戻す"],
+    ["Compaction Trigger", "compact 発火条件"],
+    ["Decides when to compact as the token budget grows.", "token budget が増える中で、いつ compact するかを決めます。"],
+    ["Micro and Summary Compaction", "micro / summary compact"],
+    ["Compacts in layers with different levels of loss.", "損失の強さが異なる複数層で compact します。"],
+    ["Active Context", "アクティブ文脈"],
+    ["What the current turn must see directly.", "現在のターンが直接見る必要のある内容です。"],
+    ["Detail moved out of the active window but still readable later.", "active window の外へ移したが、後でまだ読み戻せる detail です。"],
+    ["The retained storyline after compaction.", "compact 後にも残す主線です。"],
+    ["Moves recent detail out of the hot window.", "直近の detail を hot window の外へ移します。"],
+    ["Preserves continuity of the mainline.", "主線の連続性を守ります。"],
+    ["Detail leaves the active window first", "まず detail を active window の外へ出す"],
+    ["The mainline is preserved as a summary", "主線は summary として保たれる"],
+    ["Raw detail is read back only when needed", "生の detail は必要時だけ読み戻す"],
+    ["deny / ask / allow happens before execution.", "`deny / ask / allow` の判断は実行前に行われます。"],
+    ["Mode Control", "モード制御"],
+    ["Modes such as default, plan, and auto affect the whole permission path.", "`default`・`plan`・`auto` などの mode が permission path 全体へ影響します。"],
+    ["Defines which tools or paths are allowed, denied, or sent for confirmation.", "どの tool や path を許可・拒否・確認送りにするかを定めます。"],
+    ["Writes allow / ask / deny back in structured form.", "`allow / ask / deny` を構造化して書き戻します。"],
+    ["The Loop No Longer Reaches Tools Directly", "主ループはもう tool へ直行しない"],
+    ["A tool call passes through the permission layer before actual execution.", "tool call は実行前に permission layer を通過します。"],
+    ["Translates raw tool calls into a policy-checkable object.", "生の tool call を policy 判定可能なオブジェクトへ変換します。"],
+    ["The model proposes an action", "モデルが行動案を出す"],
+    ["The permission layer returns allow / ask / deny", "permission layer が `allow / ask / deny` を返す"],
+    ["That result writes back into the main loop", "その結果が主ループへ書き戻される"],
+    ["The loop emits events at boundaries like pre_tool, post_tool, and on_error.", "loop は `pre_tool`・`post_tool`・`on_error` などの境界で event を出します。"],
+    ["Multiple hooks share one event contract.", "複数の hook が同じ event contract を共有します。"],
+    ["A structured event envelope carrying tool, input, result, error, and more.", "tool・input・result・error などを持つ構造化 event envelope です。"],
+    ["Keep the Mainline Small", "主線を小さく保つ"],
+    ["Side effects attach through hooks instead of invading every handler.", "副作用は各 handler に侵入させず、hook 経由で付けます。"],
+    ["A concrete side-effect sink.", "具体的な副作用の落とし先です。"],
+    ["The loop emits an event", "loop が event を出す"],
+    ["Hooks observe and produce side effects", "hook が観測して副作用を生む"],
+    ["The mainline continues without being rewritten", "主線は書き換えられず、そのまま進む"],
+    ["Memory Load/Write", "memory の読み込み / 書き込み"],
+    ["Load before the model call, then extract and write after the work turn.", "モデル呼び出し前に読み込み、作業ターンの後で抽出して書き戻します。"],
+    ["Carries the live process, not long-term cross-session knowledge.", "現在進行中の処理を運びますが、会話をまたぐ長期知識は持ちません。"],
+    ["Stores only durable facts that still matter across sessions.", "セッションをまたいでも価値のある durable fact だけを保存します。"],
+    ["Long-lived facts such as preferences and project constraints.", "好みや project 制約のような長期 fact です。"],
+    ["Relevant memory is loaded first", "関連 memory を先に読み込む"],
+    ["The main loop completes the current turn", "主ループが現在のターンを完了する"],
+    ["New durable facts are extracted and written back", "新しい durable fact を抽出して書き戻す"],
+    ["Assembles stable policy, runtime state, tools, and memory in a visible order.", "stable policy・runtime state・tool・memory を見える順序で組み立てます。"],
+    ["Each input fragment has its own explicit boundary.", "各入力片には明示的な境界があります。"],
+    ["Runtime fragments such as workspace state, task state, and memory.", "workspace state・task state・memory などの runtime 片です。"],
+    ["Model Input Construction", "モデル入力の構築"],
+    ["The loop constructs the full input before calling the model.", "loop はモデル呼び出し前に完全な入力を組み立てます。"],
+    ["Which fragment is assembled first versus later.", "どの入力片を先に組み、どれを後に組むかです。"],
+    ["Stable policy is assembled first", "stable policy を先に組み立てる"],
+    ["Runtime fragments are injected next", "その後で runtime fragment を注入する"],
+    ["Only then does the final input reach the model", "そこで初めて最終入力がモデルへ届く"],
+    ["Chooses retry, fallback, ask, or stop by failure type.", "failure の種類ごとに retry・fallback・ask・stop を選びます。"],
+    ["Makes the reason for continuation visible state.", "なぜ継続するのかを可視の state にします。"],
+    ["Prevents recovery branches from looping forever.", "recovery branch が無限ループしないようにします。"],
+    ["Failures Still Return to the Loop", "失敗も主ループへ戻る"],
+    ["Failures are not discarded; they write back with recovery semantics.", "失敗は捨てられず、recovery の意味を持ったまま書き戻されます。"],
+    ["The error classification and branch state.", "error の分類と branch state です。"],
+    ["A tool failure is classified first", "tool failure をまず分類する"],
+    ["The recovery layer chooses a branch", "recovery layer が branch を選ぶ"],
+    ["The continuation reason returns to the main loop", "continuation reason が主ループへ戻る"],
+    ["Checks which downstream nodes can start once one task completes.", "1 つの task が完了した後、どの downstream node が開始できるかを調べます。"],
+    ["The durable record surface for all work nodes.", "すべての work node を保持する durable な記録面です。"],
+    ["blockedBy / blocks record who depends on whom.", "`blockedBy / blocks` が誰が誰に依存するかを記録します。"],
+    ["Tasks Layer Away From the Session", "task はセッションの外側へ分かれる"],
+    ["Session-local todo becomes secondary while durable tasks enter the main architecture.", "session-local な todo は脇へ下がり、durable task が主設計へ入ってきます。"],
+    ["Durable fields for goal, status, dependencies, owner, and more.", "goal・status・dependency・owner などを持つ durable record です。"],
+    ["A task node is created", "task node が作られる"],
+    ["Dependency edges decide when work becomes ready", "dependency edge が ready になる時点を決める"],
+    ["Completion unlocks downstream nodes", "完了が downstream node を解放する"],
+    ["Only decides whether a rule matches.", "ルールが一致したかだけを判定します。"],
+    ["Records what should trigger and when.", "何をいつ発火させるかを記録します。"],
+    ["The concrete runtime instance created after a match.", "一致後に生成される具体的な runtime instance です。"],
+    ["Time Trigger Surface", "時間トリガー面"],
+    ["A cron tick is only a trigger surface, not the business execution itself.", "cron tick は trigger surface であり、業務実行そのものではありません。"],
+    ["One rule-match occurrence.", "1 回のルール一致イベントです。"],
+    ["A cron rule matches", "cron rule が一致する"],
+    ["A runtime task is created", "runtime task が作られる"],
+    ["The background runtime takes over execution", "background runtime が実行を引き継ぐ"],
+    ["Maintains the roster, assigns work, and watches team state.", "roster を維持し、役割を割り振り、team state を見守ります。"],
+    ["Stores each teammate's name, role, and status.", "各 teammate の名前・role・status を保存します。"],
+    ["A separate message boundary for each teammate.", "各 teammate ごとに独立した message 境界です。"],
+    ["A long-lived worker that can take repeated assignments.", "繰り返し仕事を受けられる長期 worker です。"],
+    ["A long-lived identity, not a one-shot delegation result.", "単発の委譲結果ではなく、長期 identity です。"],
+    ["A structured message carried through inboxes.", "inbox を流れる構造化メッセージです。"],
+    ["The lead defines responsibility", "lead が責務を定義する"],
+    ["Messages enter the teammate inbox", "メッセージが teammate inbox へ入る"],
+    ["The teammate runs independently and replies", "teammate が独立に動いて返信する"],
+    ["A fixed envelope with type, from, to, request_id, and payload.", "`type`・`from`・`to`・`request_id`・`payload` を持つ固定 envelope です。"],
+    ["Turns protocol requests into durable request records.", "protocol request を durable request record へ変換します。"],
+    ["Protocol Collaboration Channel", "プロトコル協調チャネル"],
+    ["Approvals, shutdowns, and handoffs all use the same request/response model.", "承認・停止・引き継ぎなどを同じ request/response model で扱います。"],
+    ["The real state center of a protocol workflow.", "protocol workflow の本当の状態中心です。"],
+    ["A protocol request is sent", "protocol request が送られる"],
+    ["request_id binds the durable state record", "`request_id` が durable state record を結び付ける"],
+    ["An explicit response writes back into the state machine", "明示的な response が state machine へ書き戻される"],
+    ["Checks inboxes and the task board on a cadence during idle time.", "idle 中に一定間隔で inbox と task board を確認します。"],
+    ["Only tasks that satisfy role and state conditions may be auto-claimed.", "role と state 条件を満たす task だけが auto-claim されます。"],
+    ["Records who claimed a task and from which source.", "誰が、どの source から task を claim したかを記録します。"],
+    ["Autonomous teammates still inherit durable protocol request state from the previous chapter.", "自律 teammate も前章の durable protocol request state を引き継ぎます。"],
+    ["Discovers eligible work while idle, then resumes execution.", "idle 中に着手可能な仕事を見つけ、その後 execution を resume します。"],
+    ["Decides whether the current role may claim a task.", "現在の role が task を claim できるかを判定します。"],
+    ["The teammate enters idle polling", "teammate が idle polling に入る"],
+    ["The claim policy selects eligible work", "claim policy が着手可能な仕事を選ぶ"],
+    ["Identity is re-injected and execution resumes", "identity を再注入して execution を再開する"],
+    ["The system records which task is using which execution lane.", "どの task がどの execution lane を使っているかをシステムが記録します。"],
+    ["Closeout explicitly decides whether to keep or remove the lane.", "closeout は lane を keep するか remove するかを明示的に決めます。"],
+    ["Registers each isolated lane's path, branch, and task_id.", "各 isolated lane の path・branch・task_id を登録します。"],
+    ["The task record shows which lane it is currently using.", "task record から、いまどの lane を使っているかが分かります。"],
+    ["Lifecycle events such as create, enter, run, and closeout.", "`create`・`enter`・`run`・`closeout` などのライフサイクル event です。"],
+    ["Different tasks do not share uncommitted changes by default.", "異なる task は、既定では未コミット変更を共有しません。"],
+    ["The execution record for one lane.", "1 本の lane に対応する execution record です。"],
+    ["The explicit result of keep versus reclaim.", "`keep` するか reclaim するかの明示結果です。"],
+    ["A task binds to a worktree lane", "task が worktree lane に結び付く"],
+    ["Commands run inside the isolated directory", "コマンドが isolated directory 内で走る"],
+    ["Closeout decides the lane's final fate", "closeout が lane の最終的な行き先を決める"],
+    ["Discovers capability first, then routes to native, plugin, or MCP.", "まず capability を発見し、その後で native・plugin・MCP のどこへ送るかを決めます。"],
+    ["External capabilities and native tools share one permission contract.", "external capability と native tool は同じ permission contract を共有します。"],
+    ["Remote results are normalized into a payload the main loop already understands.", "remote result も、主ループが理解できる標準 payload へ正規化されます。"],
+    ["Tells the system which external servers are available.", "どの external server が利用可能かをシステムへ伝えます。"],
+    ["Collects native, plugin, and MCP capability into one comparable view.", "native・plugin・MCP の capability を 1 つの比較可能な view へまとめます。"],
+    ["A local handler.", "ローカル handler です。"],
+    ["Remote capability provided by an external server or plugin.", "external server または plugin が提供する remote capability です。"],
+    ["A capability object carrying server, source, and risk information.", "`server`・`source`・`risk` を持つ capability object です。"],
+    ["Capability discovery happens first", "まず capability discovery を行う"],
+    ["Routing and permission stay unified", "routing と permission を分離せず 1 本に保つ"],
+    ["A normalized result writes back into the main loop", "正規化した結果を主ループへ書き戻す"],
+    [
+      "Background tasks fully separate the existence of work from one live execution attempt, which is where runtime records become first-class.",
+      "background task は「仕事目標が存在すること」と「今この実行が走っていること」を切り分け、runtime record を一等構造へ押し上げます。",
+    ],
+    [
+      "Drains background notifications before the next model call.",
+      "次のモデル呼び出し前に、バックグラウンド通知を回収して主線へ戻します。",
+    ],
+    [
+      "The durable task goal still lives on the task board.",
+      "永続 task goal は task board 側に残り続けます。",
+    ],
+    [
+      "Describes one running or completed execution slot.",
+      "いま走っている、または完了済みの execution slot を表します。",
+    ],
+    [
+      "The full artifact goes to disk while notifications carry only a preview.",
+      "完全な成果物はディスクへ書き出し、notification には preview だけを載せます。",
+    ],
+    [
+      "Slow commands execute on a side path while the main loop keeps moving.",
+      "遅いコマンドは side lane で実行され、その間も主ループは前へ進みます。",
+    ],
+    [
+      "The bridge back into the main loop.",
+      "結果を主ループへ戻す橋渡しです。",
+    ],
+    [
+      "The loop creates a runtime record",
+      "主ループが runtime record を作る",
+    ],
+    [
+      "A background slot runs the slow command",
+      "バックグラウンド slot が遅いコマンドを実行する",
+    ],
+    [
+      "notification plus output_file returns to the main system",
+      "notification と output_file が主システムへ戻る",
+    ],
+    ["Notification Drain", "通知ドレイン"],
+    ["Task Goal", "タスク目標"],
+    ["Background Execution Slot", "バックグラウンド実行スロット"],
+    ["Agent Loop", "Agent ループ"],
+    ["Assistant Content", "Assistant 内容"],
+    ["Dispatch Map", "ディスパッチマップ"],
+    ["Dispatch Entry", "ディスパッチ項目"],
+    ["Todo List", "Todo リスト"],
+    ["Parent messages", "親 messages"],
+    ["Child messages", "子 messages"],
+    ["Subtask Request", "サブタスク要求"],
+    ["Skill Discovery", "スキル探索"],
+    ["Skill Load", "スキル読み込み"],
+    ["Skill Registry", "スキルレジストリ"],
+    ["Persisted Output", "永続出力"],
+    ["Summary State", "要約状態"],
+    ["Micro Compact Record", "マイクロ compact 記録"],
+    ["Summary Compact", "要約 compact"],
+    ["Permission Gate", "権限ゲート"],
+    ["Normalized Intent", "正規化意図"],
+    ["Lifecycle Events", "ライフサイクルイベント"],
+    ["Hook Registry", "Hook レジストリ"],
+    ["Audit Sink", "監査シンク"],
+    ["Memory Store", "Memory ストア"],
+    ["Prompt Builder", "Prompt ビルダー"],
+    ["Runtime Context", "ランタイム文脈"],
+    ["Section Order", "セクション順序"],
+    ["Recovery Manager", "回復マネージャー"],
+    ["Continuation Reason", "継続理由"],
+    ["Retry Bounds", "再試行境界"],
+    ["Unlock Rules", "解放ルール"],
+    ["Task Board", "タスク板"],
+    ["Dependency Edges", "依存エッジ"],
+    ["Notification Drain", "通知ドレイン"],
+    ["Task Goal", "タスク目標"],
+    ["Schedule Matcher", "スケジュール照合器"],
+    ["Lead Orchestrator", "主オーケストレーター"],
+    ["Team Roster", "チーム roster"],
+    ["Inbox", "受信箱"],
+    ["Persistent Teammate", "常駐チームメイト"],
+    ["MessageEnvelope", "メッセージ封筒"],
+    ["Protocol Envelope", "プロトコル封筒"],
+    ["Protocol State Machine", "プロトコル状態機械"],
+    ["Request Store", "要求ストア"],
+    ["Idle Poll Loop", "アイドル輪詢ループ"],
+    ["Claim Policy", "claim ポリシー"],
+    ["Claim Events", "claim イベント"],
+    ["Autonomous Worker", "自律 worker"],
+    ["Task-to-Lane Binding", "task と lane の結合"],
+    ["Closeout Semantics", "closeout 意味論"],
+    ["Worktree Index", "Worktree インデックス"],
+    ["Event Log", "イベントログ"],
+    ["Isolated Directory Lane", "隔離ディレクトリレーン"],
+    ["Closeout Record", "closeout 記録"],
+    ["Capability Router", "capability ルーター"],
+    ["Shared Permission Gate", "共有権限ゲート"],
+    ["Result Normalizer", "結果正規化器"],
+    ["Plugin Manifest", "プラグインマニフェスト"],
+    ["Capability View", "capability view"],
+    ["Native Tool", "ネイティブツール"],
+    ["MCP / Plugin Lane", "MCP / plugin レーン"],
+    ["Scoped Capability", "スコープ付き capability"],
+    ["NEW", "新規"],
+  ],
+};
+
+function applyReplacementPairs(text: string, replacements: ReplacementPair[]): string {
+  return [...replacements]
+    .sort((a, b) => b[0].length - a[0].length)
+    .reduce((result, [from, to]) => result.split(from).join(to), text);
+}
+
+function normalizeMultilineText(text: string): string {
+  return text.replace(/\\n/g, "\n");
+}
+
+export function normalizeDiagramLocale(locale: string): DiagramLocale {
+  if (locale === "zh" || locale === "ja") return locale;
+  return "en";
+}
+
+export function translateFlowText(locale: string, text: string): string {
+  const normalizedLocale = normalizeDiagramLocale(locale);
+  const normalizedText = normalizeMultilineText(text);
+
+  if (normalizedLocale === "en") return normalizedText;
+
+  return applyReplacementPairs(normalizedText, FLOW_REPLACEMENTS[normalizedLocale]);
+}
+
+export function translateArchitectureText(locale: string, text: string): string {
+  const normalizedLocale = normalizeDiagramLocale(locale);
+  const normalizedText = normalizeMultilineText(text);
+
+  if (normalizedLocale === "en") return normalizedText;
+
+  return applyReplacementPairs(
+    normalizedText,
+    ARCHITECTURE_REPLACEMENTS[normalizedLocale]
+  );
+}
+
+export function pickDiagramText<T extends { zh: string; en: string; ja?: string }>(
+  locale: string,
+  value: T
+): string {
+  const normalizedLocale = normalizeDiagramLocale(locale);
+
+  if (normalizedLocale === "zh") return value.zh;
+  if (normalizedLocale === "ja") return value.ja ?? value.en;
+  return value.en;
+}
diff --git a/web/src/lib/session-assets.ts b/web/src/lib/session-assets.ts
new file mode 100644
index 000000000..a7630bc98
--- /dev/null
+++ b/web/src/lib/session-assets.ts
@@ -0,0 +1,35 @@
+export const GENERIC_OVERVIEW_VERSIONS = new Set([
+  "s07",
+  "s08",
+  "s09",
+  "s10",
+  "s11",
+  "s12",
+  "s13",
+  "s14",
+  "s15",
+  "s16",
+  "s17",
+  "s18",
+  "s19",
+]);
+
+export const GENERIC_SCENARIO_VERSIONS = new Set(GENERIC_OVERVIEW_VERSIONS);
+
+export const GENERIC_ANNOTATION_VERSIONS = new Set(GENERIC_OVERVIEW_VERSIONS);
+
+export function resolveLegacySessionAssetVersion(version: string): string {
+  return version;
+}
+
+export function isGenericOverviewVersion(version: string): boolean {
+  return GENERIC_OVERVIEW_VERSIONS.has(version);
+}
+
+export function isGenericScenarioVersion(version: string): boolean {
+  return GENERIC_SCENARIO_VERSIONS.has(version);
+}
+
+export function isGenericAnnotationVersion(version: string): boolean {
+  return GENERIC_ANNOTATION_VERSIONS.has(version);
+}
diff --git a/web/src/lib/stage-checkpoints.ts b/web/src/lib/stage-checkpoints.ts
new file mode 100644
index 000000000..5b9dbb08b
--- /dev/null
+++ b/web/src/lib/stage-checkpoints.ts
@@ -0,0 +1,102 @@
+import type { LearningLayer, VersionId } from "@/lib/constants";
+
+type SupportedLocale = "zh" | "en" | "ja";
+
+export interface StageCheckpoint {
+  layer: LearningLayer;
+  entryVersion: VersionId;
+  endVersion: VersionId;
+  title: Record<SupportedLocale, string>;
+  body: Record<SupportedLocale, string>;
+  rebuild: Record<SupportedLocale, string>;
+}
+
+export const STAGE_CHECKPOINTS: readonly StageCheckpoint[] = [
+  {
+    layer: "core",
+    entryVersion: "s01",
+    endVersion: "s06",
+    title: {
+      zh: "先停在这里，自己重做一遍单 agent 主骨架",
+      en: "Pause here and rebuild the single-agent system from scratch",
+      ja: "ここで一度止まり、単一 agent の背骨を自分で作り直す",
+    },
+    body: {
+      zh: "读完 `s01-s06` 后，最有价值的动作不是立刻跳去权限或团队，而是从空目录里重新做出主循环、工具分发、会话计划、子任务隔离、技能加载和上下文压缩。",
+      en: "You now have a complete single-agent system. The most valuable thing you can do right now is not rush ahead -- it's to open an empty directory and rebuild the loop, tool dispatch, session planning, subtask isolation, skill loading, and context compaction from memory.",
+      ja: "`s01-s06` の後で最も価値が高いのは、そのまま permission や team へ進むことではありません。空のディレクトリから、loop・tool dispatch・session planning・subtask isolation・skill loading・context compaction を作り直すことです。",
+    },
+    rebuild: {
+      zh: "一个能连续工作多轮、能调用工具、能写 todo、能委派子任务、能按需加载技能并且能做最小压缩的单 agent harness。",
+      en: "A single-agent harness that can survive multiple turns, call tools, keep a todo plan, delegate one-shot subtasks, load skills on demand, and compact context at the minimum useful level.",
+      ja: "複数ターン継続でき、tool を呼び、todo plan を持ち、単発 subtask を委譲し、skill を必要時だけ読み込み、最小限の compact を行える単一 agent harness。",
+    },
+  },
+  {
+    layer: "hardening",
+    entryVersion: "s07",
+    endVersion: "s11",
+    title: {
+      zh: "到这里先把控制面补稳，再进入任务系统",
+      en: "Stabilize the control plane before moving to the task runtime",
+      ja: "ここで制御面を安定させてからタスク実行層へ入る",
+    },
+    body: {
+      zh: "读完 `s07-s11` 后，应该先自己补出一条完整的控制面：执行前权限闸门、固定生命周期 Hook、跨会话记忆、输入装配和恢复续行分支。",
+      en: "Your agent now has real safety. Rebuild it with a permission gate before every tool call, lifecycle hooks for extension, cross-session memory, a prompt assembly pipeline, and structured recovery branches.",
+      ja: "`s07-s11` の後は、自分の制御面を一度まとめて作り直すべきです。実行前の permission gate、固定ライフサイクル hook、cross-session memory、入力組み立て、recovery 分岐を 1 本に戻します。",
+    },
+    rebuild: {
+      zh: "一个不只是会跑，而是已经补齐执行闸门、扩展插口、长期记忆、输入装配与恢复续行的稳固单 agent。",
+      en: "A single agent with a real control plane: execution gating, extension hooks, durable memory, input assembly, and recovery branches.",
+      ja: "ただ動くだけでなく、実行前 gate、拡張 hook、長期 memory、入力組み立て、recovery 分岐までそろった安定した single agent。",
+    },
+  },
+  {
+    layer: "runtime",
+    entryVersion: "s12",
+    endVersion: "s14",
+    title: {
+      zh: "到这里先把“工作系统”手搓出来，再看团队层",
+      en: "Build the work runtime before moving into teams",
+      ja: "ここで work runtime を作り切ってから team 層へ進む",
+    },
+    body: {
+      zh: "读完 `s12-s14` 后，读者最该做的是把 `task goal`、`runtime slot`、`notification` 和 `schedule trigger` 四层对象真的分开写出来，而不是只记住它们的名字。",
+      en: "Now build separate structures for task goals, runtime slots, notifications, and schedule triggers. Don't just remember the names -- implement each as a distinct piece.",
+      ja: "`s12-s14` の後で大事なのは、task goal・runtime slot・notification・schedule trigger を名前だけで覚えることではなく、別々の構造として実装し分けることです。",
+    },
+    rebuild: {
+      zh: "一套能记录持久任务、后台运行慢工作、用通知带回结果，并且允许时间触发开工的最小 runtime 系统。",
+      en: "A minimal runtime that can persist task goals, run slow work in the background, return results through notifications, and let time trigger new work.",
+      ja: "永続 task goal を持ち、遅い仕事を background で回し、notification で結果を戻し、時間で新しい仕事を起動できる最小 runtime system。",
+    },
+  },
+  {
+    layer: "platform",
+    entryVersion: "s15",
+    endVersion: "s19",
+    title: {
+      zh: "最后这一段要做的是平台边界，而不是只加很多功能",
+      en: "The final stage: building the platform boundary",
+      ja: "最後の段階で作るのは機能の山ではなくプラットフォーム境界です",
+    },
+    body: {
+      zh: "读完 `s15-s19` 后，最应该回头确认的是五层边界有没有彻底分清：teammate、protocol request、task、worktree lane、external capability。",
+      en: "You've completed the entire course. The key test: can you cleanly separate teammate, protocol request, task, worktree lane, and external capability? If yes, you understand the full design backbone.",
+      ja: "`s15-s19` の後で最も確認すべきなのは、teammate・protocol request・task・worktree lane・external capability の 5 層を本当に分けて保てるかどうかです。",
+    },
+    rebuild: {
+      zh: "一个拥有长期队友、共享协议、自治认领、隔离执行车道，并把原生工具与外部能力接回同一控制面的平台雏形。",
+      en: "An agent platform with persistent teammates, shared protocols, autonomous claiming, isolated execution lanes, and one control plane for native and external capabilities.",
+      ja: "永続 teammate、共有 protocol、自律 claim、分離 execution lane、そして native/external capability を 1 つの control plane へ戻したプラットフォームの骨格。",
+    },
+  },
+] as const;
+
+export function getStageCheckpoint(
+  layer: LearningLayer | null | undefined
+): StageCheckpoint | null {
+  if (!layer) return null;
+  return STAGE_CHECKPOINTS.find((checkpoint) => checkpoint.layer === layer) ?? null;
+}
diff --git a/web/src/lib/version-content.ts b/web/src/lib/version-content.ts
new file mode 100644
index 000000000..498a93d49
--- /dev/null
+++ b/web/src/lib/version-content.ts
@@ -0,0 +1,325 @@
+import { VERSION_META, type VersionId } from "@/lib/constants";
+
+export type LearningLocale = "zh" | "en" | "ja";
+
+type VersionContent = {
+  subtitle: string;
+  coreAddition: string;
+  keyInsight: string;
+};
+
+const VERSION_CONTENT: Record<LearningLocale, Record<VersionId, VersionContent>> = {
+  zh: {
+    s01: {
+      subtitle: "最小闭环",
+      coreAddition: "LoopState + tool_result 回流",
+      keyInsight: "真正的 agent 起点，是把真实工具结果重新喂回模型，而不只是输出一段文本。",
+    },
+    s02: {
+      subtitle: "把意图路由成动作",
+      coreAddition: "工具规格 + 分发映射",
+      keyInsight: "主循环本身不用变复杂；工具能力靠一层清晰的路由面增长。",
+    },
+    s03: {
+      subtitle: "会话级计划",
+      coreAddition: "PlanningState + reminder loop",
+      keyInsight: "对多步骤任务来说，可见计划不是装饰，而是防止会话漂移的稳定器。",
+    },
+    s04: {
+      subtitle: "子任务使用全新上下文",
+      coreAddition: "带隔离消息历史的委派",
+      keyInsight: "把探索性工作移进干净上下文后，父 agent 才能持续盯住主目标。",
+    },
+    s05: {
+      subtitle: "先轻发现，再深加载",
+      coreAddition: "技能注册表 + 按需注入",
+      keyInsight: "专门知识不该一开始全部塞进上下文，而该在需要时被轻量发现、按需展开。",
+    },
+    s06: {
+      subtitle: "保持活跃上下文小而稳",
+      coreAddition: "持久标记 + 微压缩 + 总结压缩",
+      keyInsight: "压缩的目标不是删历史，而是保住连续性和下一步所需的工作记忆。",
+    },
+    s07: {
+      subtitle: "意图先过安全闸门",
+      coreAddition: "deny / mode / allow / ask 管线",
+      keyInsight: "模型产生的执行意图，必须先通过清晰的权限门，再变成真正动作。",
+    },
+    s08: {
+      subtitle: "不改主循环也能扩展",
+      coreAddition: "生命周期事件 + 副作用 Hook",
+      keyInsight: "Hook 让系统围绕主循环生长，而不是不断重写主循环本身。",
+    },
+    s09: {
+      subtitle: "只保存跨会话还成立的东西",
+      coreAddition: "类型化记忆记录 + reload 路径",
+      keyInsight: "只有跨会话、无法从当前工作重新推导的知识，才值得进入 memory。",
+    },
+    s10: {
+      subtitle: "把输入组装成流水线",
+      coreAddition: "Prompt 分段 + 动态装配",
+      keyInsight: "模型看到的不是一坨固定 prompt，而是一条按阶段拼装的输入流水线。",
+    },
+    s11: {
+      subtitle: "先恢复，再继续",
+      coreAddition: "continuation reason + retry 分支",
+      keyInsight: "系统必须清楚自己此刻是在继续、重试，还是处于恢复流程。",
+    },
+    s12: {
+      subtitle: "持久化工作图",
+      coreAddition: "Task 记录 + 依赖 + 解锁规则",
+      keyInsight: "Todo 适合会话内规划，持久任务图才负责跨步骤、跨阶段协调工作。",
+    },
+    s13: {
+      subtitle: "把任务目标和运行槽位分开",
+      coreAddition: "RuntimeTaskState + 异步执行槽位",
+      keyInsight: "持久任务描述要完成什么，运行槽位描述谁在跑、跑到哪里；两者相关但不是一回事。",
+    },
+    s14: {
+      subtitle: "让时间也能触发工作",
+      coreAddition: "基于 runtime task 的定时触发",
+      keyInsight: "当任务能后台运行以后，时间本身也会变成另一种启动入口。",
+    },
+    s15: {
+      subtitle: "长驻的专职队友",
+      coreAddition: "团队 roster + teammate 生命周期",
+      keyInsight: "系统一旦长期运行，就需要有名字、有身份、可持续存在的队友，而不只是一次性子任务。",
+    },
+    s16: {
+      subtitle: "共享请求-响应规则",
+      coreAddition: "协议信封 + 请求关联",
+      keyInsight: "团队只有在协作遵守共同消息模式时，才会变得可理解、可调试、可扩展。",
+    },
+    s17: {
+      subtitle: "自主认领，自主续跑",
+      coreAddition: "空闲轮询 + 角色感知认领 + 恢复上下文",
+      keyInsight: "自主性开始于：队友能安全找到可做的事、认领它，并带着正确身份继续执行。",
+    },
+    s18: {
+      subtitle: "独立目录，独立车道",
+      coreAddition: "task-worktree 状态 + 显式 enter / closeout 生命周期",
+      keyInsight: "task 管目标，worktree 管隔离执行车道和收尾状态；两者不能混成一个概念。",
+    },
+    s19: {
+      subtitle: "外部能力总线",
+      coreAddition: "作用域服务器 + 能力路由",
+      keyInsight: "外部能力系统不该是外挂；它们应和原生工具一起处在同一控制面上。",
+    },
+  },
+  en: {
+    s01: {
+      subtitle: "Minimal Closed Loop",
+      coreAddition: "LoopState + tool_result feedback",
+      keyInsight: "An agent is just a loop: send messages, execute tools, feed results back, repeat.",
+    },
+    s02: {
+      subtitle: "Route Intent into Action",
+      coreAddition: "Tool specs + dispatch map",
+      keyInsight: "Adding a tool means adding one handler. The loop never changes.",
+    },
+    s03: {
+      subtitle: "Session Planning",
+      coreAddition: "PlanningState + reminder loop",
+      keyInsight: "A visible plan keeps the agent on track when tasks get complex.",
+    },
+    s04: {
+      subtitle: "Fresh Context per Subtask",
+      coreAddition: "Delegation with isolated message history",
+      keyInsight: "A subagent is mainly a context boundary, not a process trick.",
+    },
+    s05: {
+      subtitle: "Discover Cheaply, Load Deeply",
+      coreAddition: "Skill registry + on-demand injection",
+      keyInsight: "Discover cheaply, load deeply -- only when needed.",
+    },
+    s06: {
+      subtitle: "Keep Active Context Small and Stable",
+      coreAddition: "Persist markers + micro compact + summary compact",
+      keyInsight: "Compaction isn't deleting history -- it's relocating detail so the agent can keep working.",
+    },
+    s07: {
+      subtitle: "Intent Must Pass a Safety Gate",
+      coreAddition: "deny / mode / allow / ask pipeline",
+      keyInsight: "Safety is a pipeline, not a boolean: deny, check mode, allow, then ask.",
+    },
+    s08: {
+      subtitle: "Extend Without Rewriting the Loop",
+      coreAddition: "Lifecycle events + side-effect hooks",
+      keyInsight: "The loop owns control flow; hooks only observe, block, or annotate at named moments.",
+    },
+    s09: {
+      subtitle: "Keep Only What Survives Sessions",
+      coreAddition: "Typed memory records + reload path",
+      keyInsight: "Memory gives direction; current observation gives truth.",
+    },
+    s10: {
+      subtitle: "Assemble Inputs as a Pipeline",
+      coreAddition: "Prompt sections + dynamic assembly",
+      keyInsight: "The model sees a constructed input pipeline, not one giant static string.",
+    },
+    s11: {
+      subtitle: "Recover, Then Continue",
+      coreAddition: "Continuation reasons + retry branches",
+      keyInsight: "Most failures aren't true task failure -- they're signals to try a different path.",
+    },
+    s12: {
+      subtitle: "Durable Work Graph",
+      coreAddition: "Task records + dependencies + unlock rules",
+      keyInsight: "Todo lists help a session; durable task graphs coordinate work that outlives it.",
+    },
+    s13: {
+      subtitle: "Background Execution Lanes",
+      coreAddition: "RuntimeTaskState + async execution slots",
+      keyInsight: "Background execution is a runtime lane, not a second main loop.",
+    },
+    s14: {
+      subtitle: "Let Time Trigger Work",
+      coreAddition: "Scheduled triggers over runtime tasks",
+      keyInsight: "Scheduling is not a separate system -- it just feeds the same agent loop from a timer.",
+    },
+    s15: {
+      subtitle: "Persistent Specialist Teammates",
+      coreAddition: "Team roster + teammate lifecycle",
+      keyInsight: "Teammates persist beyond one prompt, have identity, and coordinate through durable channels.",
+    },
+    s16: {
+      subtitle: "Shared Request-Response Rules",
+      coreAddition: "Protocol envelopes + request correlation",
+      keyInsight: "A protocol request is a structured message with an ID; the response must reference the same ID.",
+    },
+    s17: {
+      subtitle: "Self-Claim, Self-Resume",
+      coreAddition: "Idle polling + role-aware self-claim + resume context",
+      keyInsight: "Autonomy is a bounded mechanism -- idle, scan, claim, resume -- not magic.",
+    },
+    s18: {
+      subtitle: "Separate Directory, Separate Lane",
+      coreAddition: "Task-worktree state + explicit enter / closeout lifecycle",
+      keyInsight: "Tasks answer what; worktrees answer where. Keep them separate.",
+    },
+    s19: {
+      subtitle: "External Capability Bus",
+      coreAddition: "Scoped servers + capability routing",
+      keyInsight: "External capabilities join the same routing, permission, and result-append path as native tools.",
+    },
+  },
+  ja: {
+    s01: {
+      subtitle: "最小の閉ループ",
+      coreAddition: "LoopState + tool_result の戻し込み",
+      keyInsight: "本当の agent の始まりは、実際のツール結果をモデルへ戻すところにあり、単なる文章出力ではありません。",
+    },
+    s02: {
+      subtitle: "意図を実行へルーティングする",
+      coreAddition: "ツール仕様 + ディスパッチマップ",
+      keyInsight: "主ループを複雑にしなくても、きれいなルーティング層を置けばツール能力は増やせます。",
+    },
+    s03: {
+      subtitle: "セッション計画",
+      coreAddition: "PlanningState + reminder loop",
+      keyInsight: "多段作業では、見える計画は飾りではなく、会話の漂流を防ぐ安定器です。",
+    },
+    s04: {
+      subtitle: "サブタスクごとに新しい文脈を使う",
+      coreAddition: "分離されたメッセージ履歴を持つ委譲",
+      keyInsight: "探索作業をきれいなサブコンテキストへ移して初めて、親 agent は主目標へ集中し続けられます。",
+    },
+    s05: {
+      subtitle: "軽く見つけて、必要時に深く読む",
+      coreAddition: "スキルレジストリ + オンデマンド注入",
+      keyInsight: "専門知識は最初から全部を文脈へ詰め込まず、必要になった時だけ軽く見つけて深く展開するべきです。",
+    },
+    s06: {
+      subtitle: "活性コンテキストを小さく安定させる",
+      coreAddition: "永続マーカー + micro compact + summary compact",
+      keyInsight: "圧縮の目的は履歴を消すことではなく、連続性と次の一歩に必要な作業記憶を守ることです。",
+    },
+    s07: {
+      subtitle: "意図は先に安全ゲートを通る",
+      coreAddition: "deny / mode / allow / ask パイプライン",
+      keyInsight: "モデルが出した実行意図は、明確な権限ゲートを通った後で初めて実動作になるべきです。",
+    },
+    s08: {
+      subtitle: "主ループを書き換えずに拡張する",
+      coreAddition: "ライフサイクルイベント + 副作用 Hook",
+      keyInsight: "Hook は主ループの周囲へ機能を育てるためのもので、主ループ自体を何度も書き換えるためのものではありません。",
+    },
+    s09: {
+      subtitle: "セッションを越えて残るものだけ保存する",
+      coreAddition: "型付き memory record + reload 経路",
+      keyInsight: "現在の作業空間から再導出できない、セッションを越えて有効な知識だけが memory に入る価値があります。",
+    },
+    s10: {
+      subtitle: "入力をパイプラインとして組み立てる",
+      coreAddition: "Prompt セクション + 動的組み立て",
+      keyInsight: "モデルが見るのは巨大な固定 prompt 文字列ではなく、実行時に組み上がる入力パイプラインです。",
+    },
+    s11: {
+      subtitle: "回復してから続行する",
+      coreAddition: "continuation reason + retry 分岐",
+      keyInsight: "完成度の高い agent は、いま続行中なのか、再試行中なのか、回復処理中なのかを自分で区別できなければなりません。",
+    },
+    s12: {
+      subtitle: "永続ワークグラフ",
+      coreAddition: "Task record + 依存 + 解放ルール",
+      keyInsight: "Todo はセッション内計画に向きますが、長い作業の調整を担うのは永続 task graph です。",
+    },
+    s13: {
+      subtitle: "タスク目標と実行スロットを分ける",
+      coreAddition: "RuntimeTaskState + 非同期実行スロット",
+      keyInsight: "永続タスクは何を終えるべきかを表し、実行スロットは誰がどこまで走っているかを表します。両者は関連しますが同一ではありません。",
+    },
+    s14: {
+      subtitle: "時間でも仕事を起動できるようにする",
+      coreAddition: "runtime task 上の定時トリガー",
+      keyInsight: "タスクがバックグラウンド実行できるようになると、時間そのものも起動入口の一つになります。",
+    },
+    s15: {
+      subtitle: "常駐する専門チームメイト",
+      coreAddition: "チーム roster + teammate lifecycle",
+      keyInsight: "長く動くシステムには、その場限りのサブタスクではなく、名前と役割を持って居続けるチームメイトが必要です。",
+    },
+    s16: {
+      subtitle: "共有された request-response 規則",
+      coreAddition: "プロトコル封筒 + request の相関付け",
+      keyInsight: "協調が共通メッセージ規則に従う時、チームは初めて理解しやすく、デバッグしやすく、拡張しやすくなります。",
+    },
+    s17: {
+      subtitle: "自分で引き受け、自分で再開する",
+      coreAddition: "アイドル polling + 役割認識 claim + resume context",
+      keyInsight: "自律性は、チームメイトが実行可能な仕事を安全に見つけ、引き受け、正しい身元文脈で再開できるところから始まります。",
+    },
+    s18: {
+      subtitle: "別ディレクトリ、別レーン",
+      coreAddition: "task-worktree 状態 + 明示的な enter / closeout lifecycle",
+      keyInsight: "task は目標を管理し、worktree は隔離された実行レーンと収束状態を管理します。この二つは混ぜてはいけません。",
+    },
+    s19: {
+      subtitle: "外部 capability bus",
+      coreAddition: "scope 付き server + capability routing",
+      keyInsight: "外部 capability system は後付けの別物ではなく、ネイティブツールと同じ control plane に置くべきです。",
+    },
+  },
+};
+
+export function normalizeLearningLocale(locale: string): LearningLocale {
+  if (locale === "zh" || locale === "ja") return locale;
+  return "en";
+}
+
+export function getVersionContent(version: string, locale: string): VersionContent {
+  const normalizedLocale = normalizeLearningLocale(locale);
+  const content =
+    VERSION_CONTENT[normalizedLocale][version as VersionId] ??
+    VERSION_CONTENT.en[version as VersionId];
+
+  if (content) return content;
+
+  const fallback = VERSION_META[version];
+
+  return {
+    subtitle: fallback?.subtitle ?? "",
+    coreAddition: fallback?.coreAddition ?? "",
+    keyInsight: fallback?.keyInsight ?? "",
+  };
+}
diff --git a/web/src/types/agent-data.ts b/web/src/types/agent-data.ts
index 7cf01a04d..38ae0e46d 100644
--- a/web/src/types/agent-data.ts
+++ b/web/src/types/agent-data.ts
@@ -10,7 +10,7 @@ export interface AgentVersion {
   keyInsight: string;
   classes: { name: string; startLine: number; endLine: number }[];
   functions: { name: string; signature: string; startLine: number }[];
-  layer: "tools" | "planning" | "memory" | "concurrency" | "collaboration";
+  layer: "core" | "hardening" | "runtime" | "platform";
   source: string;
 }
 
@@ -24,9 +24,12 @@ export interface VersionDiff {
 }
 
 export interface DocContent {
-  version: string;
+  version: string | null;
+  slug: string;
   locale: "en" | "zh" | "ja";
   title: string;
+  kind: "chapter" | "bridge";
+  filename: string;
   content: string; // raw markdown
 }