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..866bae70e
--- /dev/null
+++ b/.agents/skills/finish-work/SKILL.md
@@ -0,0 +1,155 @@
+---
+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 -> AI 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
+
+AI commit policy:
+- AI may commit autonomously after this checklist passes.
+- Do not commit if lint/type/test checks required for the touched files failed
+  or were not run.
+- Do not include unrelated user changes in the commit.
+- Do not amend or use destructive git commands unless explicitly requested.
+
+---
+
+## 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..05d02393b
--- /dev/null
+++ b/.agents/skills/onboard/SKILL.md
@@ -0,0 +1,365 @@
+---
+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] AI validates and commits** - AI runs required checks, commits scoped changes
+**[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] AI 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] AI commits, then $record-session** - Debug knowledge is valuable
+
+---
+
+## KEY RULES TO EMPHASIZE
+
+1. **AI may commit after validation** - AI owns scoped commits and session
+   recording once required checks pass; never amend, use destructive git, or
+   include unrelated user changes without explicit approval.
+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/record-session/SKILL.md b/.agents/skills/record-session/SKILL.md
new file mode 100644
index 000000000..18765fa97
--- /dev/null
+++ b/.agents/skills/record-session/SKILL.md
@@ -0,0 +1,74 @@
+---
+name: record-session
+description: "Record work progress after validated code has been committed"
+---
+
+[!] **Prerequisite**: This skill should only be used AFTER the work has been
+validated and committed. AI may now create the code/docs commit autonomously
+after the required checks pass.
+
+Commit safety:
+- Do not amend commits unless explicitly requested.
+- Do not use destructive git commands.
+- Do not commit unrelated user changes.
+- If validation failed or was not run, do not record the session as complete.
+- The scripts below handle their own commits for `.trellis/` metadata after the
+  code/docs commit exists.
+
+---
+
+## 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/start/SKILL.md b/.agents/skills/start/SKILL.md
new file mode 100644
index 000000000..ba1a00087
--- /dev/null
+++ b/.agents/skills/start/SKILL.md
@@ -0,0 +1,344 @@
+---
+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. If validation is complete, AI may commit the scoped changes and run
+   `$record-session`; otherwise report the missing checks and stop before commit.
+
+---
+
+## 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/.claude/agents/check.md b/.claude/agents/check.md
new file mode 100644
index 000000000..071aec4e6
--- /dev/null
+++ b/.claude/agents/check.md
@@ -0,0 +1,122 @@
+---
+name: check
+description: |
+  Code quality check expert. Reviews code changes against specs and self-fixes issues.
+tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa
+model: opus
+---
+# Check Agent
+
+You are the Check Agent in the Trellis workflow.
+
+## Context
+
+Before checking, read:
+- `.trellis/spec/` - Development guidelines
+- Pre-commit checklist for quality standards
+
+## Core Responsibilities
+
+1. **Get code changes** - Use git diff to get uncommitted code
+2. **Check against specs** - Verify code follows guidelines
+3. **Self-fix** - Fix issues yourself, not just report them
+4. **Run verification** - typecheck and lint
+
+## Important
+
+**Fix issues yourself**, don't just report them.
+
+You have write and edit tools, you can modify code directly.
+
+---
+
+## Workflow
+
+### Step 1: Get Changes
+
+```bash
+git diff --name-only  # List changed files
+git diff              # View specific changes
+```
+
+### Step 2: Check Against Specs
+
+Read relevant specs in `.trellis/spec/` to check code:
+
+- Does it follow directory structure conventions
+- Does it follow naming conventions
+- Does it follow code patterns
+- Are there missing types
+- Are there potential bugs
+
+### Step 3: Self-Fix
+
+After finding issues:
+
+1. Fix the issue directly (use edit tool)
+2. Record what was fixed
+3. Continue checking other issues
+
+### Step 4: Run Verification
+
+Run project's lint and typecheck commands to verify changes.
+
+If failed, fix issues and re-run.
+
+---
+
+## Completion Markers (Ralph Loop)
+
+**CRITICAL**: You are in a loop controlled by the Ralph Loop system.
+The loop will NOT stop until you output ALL required completion markers.
+
+Completion markers are generated from `check.jsonl` in the task directory.
+Each entry's `reason` field becomes a marker: `{REASON}_FINISH`
+
+For example, if check.jsonl contains:
+```json
+{"file": "...", "reason": "TypeCheck"}
+{"file": "...", "reason": "Lint"}
+{"file": "...", "reason": "CodeReview"}
+```
+
+You MUST output these markers when each check passes:
+- `TYPECHECK_FINISH` - After typecheck passes
+- `LINT_FINISH` - After lint passes
+- `CODEREVIEW_FINISH` - After code review passes
+
+If check.jsonl doesn't exist or has no reasons, output: `ALL_CHECKS_FINISH`
+
+**The loop will block you from stopping until all markers are present in your output.**
+
+---
+
+## Report Format
+
+```markdown
+## Self-Check Complete
+
+### Files Checked
+
+- src/components/Feature.tsx
+- src/hooks/useFeature.ts
+
+### Issues Found and Fixed
+
+1. `<file>:<line>` - <what was fixed>
+2. `<file>:<line>` - <what was fixed>
+
+### Issues Not Fixed
+
+(If there are issues that cannot be self-fixed, list them here with reasons)
+
+### Verification Results
+
+- TypeCheck: Passed TYPECHECK_FINISH
+- Lint: Passed LINT_FINISH
+
+### Summary
+
+Checked X files, found Y issues, all fixed.
+ALL_CHECKS_FINISH
+```
diff --git a/.claude/agents/debug.md b/.claude/agents/debug.md
new file mode 100644
index 000000000..0108d99f5
--- /dev/null
+++ b/.claude/agents/debug.md
@@ -0,0 +1,106 @@
+---
+name: debug
+description: |
+  Issue fixing expert. Understands issues, fixes against specs, and verifies fixes. Precise fixes only.
+tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa
+model: opus
+---
+# Debug Agent
+
+You are the Debug Agent in the Trellis workflow.
+
+## Context
+
+Before debugging, read:
+- `.trellis/spec/` - Development guidelines
+- Error messages or issue descriptions provided
+
+## Core Responsibilities
+
+1. **Understand issues** - Analyze error messages or reported issues
+2. **Fix against specs** - Fix issues following dev specs
+3. **Verify fixes** - Run typecheck to ensure no new issues
+4. **Report results** - Report fix status
+
+---
+
+## Workflow
+
+### Step 1: Understand Issues
+
+Parse the issue, categorize by priority:
+
+- `[P1]` - Must fix (blocking)
+- `[P2]` - Should fix (important)
+- `[P3]` - Optional fix (nice to have)
+
+### Step 2: Research if Needed
+
+If you need additional info:
+
+```bash
+# Check knowledge base
+ls .trellis/big-question/
+```
+
+### Step 3: Fix One by One
+
+For each issue:
+
+1. Locate the exact position
+2. Fix following specs
+3. Run typecheck to verify
+
+### Step 4: Verify
+
+Run project's lint and typecheck commands to verify fixes.
+
+If fix introduces new issues:
+
+1. Revert the fix
+2. Use a more complete solution
+3. Re-verify
+
+---
+
+## Report Format
+
+```markdown
+## Fix Report
+
+### Issues Fixed
+
+1. `[P1]` `<file>:<line>` - <what was fixed>
+2. `[P2]` `<file>:<line>` - <what was fixed>
+
+### Issues Not Fixed
+
+- `<file>:<line>` - <reason why not fixed>
+
+### Verification
+
+- TypeCheck: Pass
+- Lint: Pass
+
+### Summary
+
+Fixed X/Y issues. Z issues require discussion.
+```
+
+---
+
+## Guidelines
+
+### DO
+
+- Precise fixes for reported issues
+- Follow specs
+- Verify each fix
+
+### DON'T
+
+- Don't refactor surrounding code
+- Don't add new features
+- Don't modify unrelated files
+- Don't use non-null assertion (`x!` operator)
+- Don't execute git commit
diff --git a/.claude/agents/dispatch.md b/.claude/agents/dispatch.md
new file mode 100644
index 000000000..827c39203
--- /dev/null
+++ b/.claude/agents/dispatch.md
@@ -0,0 +1,214 @@
+---
+name: dispatch
+description: |
+  Multi-Agent Pipeline main dispatcher. Pure dispatcher. Only responsible for calling subagents and scripts in phase order.
+tools: Read, Bash, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa
+model: opus
+---
+# Dispatch Agent
+
+You are the Dispatch Agent in the Multi-Agent Pipeline (pure dispatcher).
+
+## Working Directory Convention
+
+Current Task is specified by `.trellis/.current-task` file, content is the relative path to task directory.
+
+Task directory path format: `.trellis/tasks/{MM}-{DD}-{name}/`
+
+This directory contains all context files for the current task:
+
+- `task.json` - Task configuration
+- `prd.md` - Requirements document
+- `info.md` - Technical design (optional)
+- `implement.jsonl` - Implement context
+- `check.jsonl` - Check context
+- `debug.jsonl` - Debug context
+
+## Core Principles
+
+1. **You are a pure dispatcher** - Only responsible for calling subagents and scripts in order
+2. **You don't read specs/requirements** - Hook will auto-inject all context to subagents
+3. **You don't need resume** - Hook injects complete context on each subagent call
+4. **You only need simple commands** - Tell subagent "start working" is enough
+
+---
+
+## Startup Flow
+
+### Step 1: Determine Current Task Directory
+
+Read `.trellis/.current-task` to get current task directory path:
+
+```bash
+TASK_DIR=$(cat .trellis/.current-task)
+# e.g.: .trellis/tasks/02-03-my-feature
+```
+
+### Step 2: Read Task Configuration
+
+```bash
+cat ${TASK_DIR}/task.json
+```
+
+Get the `next_action` array, which defines the list of phases to execute.
+
+### Step 3: Execute in Phase Order
+
+Execute each step in `phase` order.
+
+> **Note**: You do NOT need to manually update `current_phase`. The Hook automatically updates it when you call Task with a subagent.
+
+---
+
+## Phase Handling
+
+> Hook will auto-inject all specs, requirements, and technical design to subagent context.
+> Dispatch only needs to issue simple call commands.
+
+### action: "implement"
+
+```
+Task(
+  subagent_type: "implement",
+  prompt: "Implement the feature described in prd.md in the task directory",
+  model: "opus",
+  run_in_background: true
+)
+```
+
+Hook will auto-inject:
+
+- All spec files from implement.jsonl
+- Requirements document (prd.md)
+- Technical design (info.md)
+
+Implement receives complete context and autonomously: read → understand → implement.
+
+### action: "check"
+
+```
+Task(
+  subagent_type: "check",
+  prompt: "Check code changes, fix issues yourself",
+  model: "opus",
+  run_in_background: true
+)
+```
+
+Hook will auto-inject:
+
+- finish-work.md
+- check-cross-layer.md
+- check-backend.md
+- check-frontend.md
+- All spec files from check.jsonl
+
+### action: "debug"
+
+```
+Task(
+  subagent_type: "debug",
+  prompt: "Fix the issues described in the task context",
+  model: "opus",
+  run_in_background: true
+)
+```
+
+Hook will auto-inject:
+
+- All spec files from debug.jsonl
+- Error context if available
+
+### action: "finish"
+
+```
+Task(
+  subagent_type: "check",
+  prompt: "[finish] Execute final completion check before PR",
+  model: "opus",
+  run_in_background: true
+)
+```
+
+**Important**: The `[finish]` marker in prompt triggers different context injection:
+- finish-work.md checklist
+- update-spec.md (spec update process and templates)
+- prd.md for verifying requirements are met
+
+The finish agent actively updates spec docs when it detects new patterns or contracts in the changes. This is different from regular "check" which has full specs for self-fix loop.
+
+### action: "create-pr"
+
+This action creates a Pull Request from the feature branch. Run it via Bash:
+
+```bash
+python3 ./.trellis/scripts/multi_agent/create_pr.py
+```
+
+This will:
+1. Stage and commit all changes (excluding workspace)
+2. Push to origin
+3. Create a Draft PR using `gh pr create`
+4. Update task.json with status="review", 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.
+
+---
+
+## Calling Subagents
+
+### Basic Pattern
+
+```
+task_id = Task(
+  subagent_type: "implement",  // or "check", "debug"
+  prompt: "Simple task description",
+  model: "opus",
+  run_in_background: true
+)
+
+// Poll for completion
+for i in 1..N:
+    result = TaskOutput(task_id, block=true, timeout=300000)
+    if result.status == "completed":
+        break
+```
+
+### Timeout Settings
+
+| Phase | Max Time | Poll Count |
+|-------|----------|------------|
+| implement | 30 min | 6 times |
+| check | 15 min | 3 times |
+| debug | 20 min | 4 times |
+
+---
+
+## Error Handling
+
+### Timeout
+
+If a subagent times out, notify the user and ask for guidance:
+
+```
+"Subagent {phase} timed out after {time}. Options:
+1. Retry the same phase
+2. Skip to next phase
+3. Abort the pipeline"
+```
+
+### Subagent Failure
+
+If a subagent reports failure, read the output and decide:
+
+- If recoverable: call debug agent to fix
+- If not recoverable: notify user and ask for guidance
+
+---
+
+## Key Constraints
+
+1. **Do not read spec/requirement files directly** - Let Hook inject to subagents
+2. **Only commit via create-pr action** - Use `multi_agent/create_pr.py` at the end of pipeline
+3. **All subagents should use opus model for complex tasks**
+4. **Keep dispatch logic simple** - Complex logic belongs in subagents
diff --git a/.claude/agents/implement.md b/.claude/agents/implement.md
new file mode 100644
index 000000000..60eaa5d06
--- /dev/null
+++ b/.claude/agents/implement.md
@@ -0,0 +1,96 @@
+---
+name: implement
+description: |
+  Code implementation expert. Understands specs and requirements, then implements features. No git commit allowed.
+tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa
+model: opus
+---
+# Implement Agent
+
+You are the Implement Agent in the Trellis workflow.
+
+## Context
+
+Before implementing, read:
+- `.trellis/workflow.md` - Project workflow
+- `.trellis/spec/` - Development guidelines
+- Task `prd.md` - Requirements document
+- Task `info.md` - Technical design (if exists)
+
+## Core Responsibilities
+
+1. **Understand specs** - Read relevant spec files in `.trellis/spec/`
+2. **Understand requirements** - Read prd.md and info.md
+3. **Implement features** - Write code following specs and design
+4. **Self-check** - Ensure code quality
+5. **Report results** - Report completion status
+
+## Forbidden Operations
+
+**Do NOT execute these git commands:**
+
+- `git commit`
+- `git push`
+- `git merge`
+
+---
+
+## Workflow
+
+### 1. Understand Specs
+
+Read relevant specs based on task type:
+
+- Backend: `.trellis/spec/backend/`
+- Frontend: `.trellis/spec/frontend/`
+- Guides: `.trellis/spec/guides/`
+
+### 2. Understand Requirements
+
+Read the task's prd.md and info.md:
+
+- What are the core requirements
+- Key points of technical design
+- Which files to modify/create
+
+### 3. Implement Features
+
+- Write code following specs and technical design
+- Follow existing code patterns
+- Only do what's required, no over-engineering
+
+### 4. Verify
+
+Run project's lint and typecheck commands to verify changes.
+
+---
+
+## Report Format
+
+```markdown
+## Implementation Complete
+
+### Files Modified
+
+- `src/components/Feature.tsx` - New component
+- `src/hooks/useFeature.ts` - New hook
+
+### Implementation Summary
+
+1. Created Feature component...
+2. Added useFeature hook...
+
+### Verification Results
+
+- Lint: Passed
+- TypeCheck: Passed
+```
+
+---
+
+## Code Standards
+
+- Follow existing code patterns
+- Don't add unnecessary abstractions
+- Only do what's required, no over-engineering
+- Keep code readable
diff --git a/.claude/agents/plan.md b/.claude/agents/plan.md
new file mode 100644
index 000000000..5c0d0be94
--- /dev/null
+++ b/.claude/agents/plan.md
@@ -0,0 +1,396 @@
+---
+name: plan
+description: |
+  Multi-Agent Pipeline planner. Analyzes requirements and produces a fully configured task directory ready for dispatch.
+tools: Read, Bash, Glob, Grep, Task
+model: opus
+---
+# Plan Agent
+
+You are the Plan Agent in the Multi-Agent Pipeline.
+
+**Your job**: Evaluate requirements and, if valid, transform them into a fully configured task directory.
+
+**You have the power to reject** - If a requirement is unclear, incomplete, unreasonable, or potentially harmful, you MUST refuse to proceed and clean up.
+
+---
+
+## Step 0: Evaluate Requirement (CRITICAL)
+
+Before doing ANY work, evaluate the requirement:
+
+```
+PLAN_REQUIREMENT = <the requirement from environment>
+```
+
+### Reject If:
+
+1. **Unclear or Vague**
+   - "Make it better" / "Fix the bugs" / "Improve performance"
+   - No specific outcome defined
+   - Cannot determine what "done" looks like
+
+2. **Incomplete Information**
+   - Missing critical details to implement
+   - References unknown systems or files
+   - Depends on decisions not yet made
+
+3. **Out of Scope for This Project**
+   - Requirement doesn't match the project's purpose
+   - Requires changes to external systems
+   - Not technically feasible with current architecture
+
+4. **Potentially Harmful**
+   - Security vulnerabilities (intentional backdoors, data exfiltration)
+   - Destructive operations without clear justification
+   - Circumventing access controls
+
+5. **Too Large / Should Be Split**
+   - Multiple unrelated features bundled together
+   - Would require touching too many systems
+   - Cannot be completed in a reasonable scope
+
+### If Rejecting:
+
+1. **Update task.json status to "rejected"**:
+   ```bash
+   jq '.status = "rejected"' "$PLAN_TASK_DIR/task.json" > "$PLAN_TASK_DIR/task.json.tmp" \
+     && mv "$PLAN_TASK_DIR/task.json.tmp" "$PLAN_TASK_DIR/task.json"
+   ```
+
+2. **Write rejection reason to a file** (so user can see it):
+   ```bash
+   cat > "$PLAN_TASK_DIR/REJECTED.md" << 'EOF'
+   # Plan Rejected
+   
+   ## Reason
+   <category from above>
+   
+   ## Details
+   <specific explanation of why this requirement cannot proceed>
+   
+   ## Suggestions
+   - <what the user should clarify or change>
+   - <how to make the requirement actionable>
+   
+   ## To Retry
+   
+   1. Delete this directory:
+      rm -rf $PLAN_TASK_DIR
+   
+   2. Run with revised requirement:
+      python3 ./.trellis/scripts/multi_agent/plan.py --name "<name>" --type "<type>" --requirement "<revised requirement>"
+   EOF
+   ```
+
+3. **Print summary to stdout** (will be captured in .plan-log):
+   ```
+   === PLAN REJECTED ===
+   
+   Reason: <category>
+   Details: <brief explanation>
+   
+   See: $PLAN_TASK_DIR/REJECTED.md
+   ```
+
+4. **Exit immediately** - Do not proceed to Step 1.
+
+**The task directory is kept** with:
+- `task.json` (status: "rejected")
+- `REJECTED.md` (full explanation)
+- `.plan-log` (execution log)
+
+This allows the user to review why it was rejected.
+
+### If Accepting:
+
+Continue to Step 1. The requirement is:
+- Clear and specific
+- Has a defined outcome
+- Is technically feasible
+- Is appropriately scoped
+
+---
+
+## Input
+
+You receive input via environment variables (set by plan.py):
+
+```bash
+PLAN_TASK_NAME    # Task name (e.g., "user-auth")
+PLAN_DEV_TYPE        # Development type: backend | frontend | fullstack
+PLAN_REQUIREMENT     # Requirement description from user
+PLAN_TASK_DIR     # Pre-created task directory path
+```
+
+Read them at startup:
+
+```bash
+echo "Task: $PLAN_TASK_NAME"
+echo "Type: $PLAN_DEV_TYPE"
+echo "Requirement: $PLAN_REQUIREMENT"
+echo "Directory: $PLAN_TASK_DIR"
+```
+
+## Output (if accepted)
+
+A complete task directory containing:
+
+```
+${PLAN_TASK_DIR}/
+├── task.json      # Updated with branch, scope, dev_type
+├── prd.md            # Requirements document
+├── implement.jsonl   # Implement phase context
+├── check.jsonl       # Check phase context
+└── debug.jsonl       # Debug phase context
+```
+
+---
+
+## Workflow (After Acceptance)
+
+### Step 1: Initialize Context Files
+
+```bash
+python3 ./.trellis/scripts/task.py init-context "$PLAN_TASK_DIR" "$PLAN_DEV_TYPE"
+```
+
+This creates base jsonl files with standard specs for the dev type.
+
+### Step 2: Analyze Codebase with Research Agent
+
+Call research agent to find relevant specs and code patterns:
+
+```
+Task(
+  subagent_type: "research",
+  prompt: "Analyze what specs and code patterns are needed for this task.
+
+Task: ${PLAN_REQUIREMENT}
+Dev Type: ${PLAN_DEV_TYPE}
+
+Instructions:
+1. Search .trellis/spec/ for relevant spec files
+2. Search the codebase for related modules and patterns
+3. Identify files that should be added to jsonl context
+
+Output format (use exactly this format):
+
+## implement.jsonl
+- path: <relative file path>, reason: <why needed>
+- path: <relative file path>, reason: <why needed>
+
+## check.jsonl
+- path: <relative file path>, reason: <why needed>
+
+## debug.jsonl
+- path: <relative file path>, reason: <why needed>
+
+## Suggested Scope
+<single word for commit scope, e.g., auth, api, ui>
+
+## Technical Notes
+<any important technical considerations for prd.md>",
+  model: "opus"
+)
+```
+
+### Step 3: Add Context Entries
+
+Parse research agent output and add entries to jsonl files:
+
+```bash
+# For each entry in implement.jsonl section:
+python3 ./.trellis/scripts/task.py add-context "$PLAN_TASK_DIR" implement "<path>" "<reason>"
+
+# For each entry in check.jsonl section:
+python3 ./.trellis/scripts/task.py add-context "$PLAN_TASK_DIR" check "<path>" "<reason>"
+
+# For each entry in debug.jsonl section:
+python3 ./.trellis/scripts/task.py add-context "$PLAN_TASK_DIR" debug "<path>" "<reason>"
+```
+
+### Step 4: Write prd.md
+
+Create the requirements document:
+
+```bash
+cat > "$PLAN_TASK_DIR/prd.md" << 'EOF'
+# Task: ${PLAN_TASK_NAME}
+
+## Overview
+[Brief description of what this feature does]
+
+## Requirements
+- [Requirement 1]
+- [Requirement 2]
+- ...
+
+## Acceptance Criteria
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+- ...
+
+## Technical Notes
+[Any technical considerations from research agent]
+
+## Out of Scope
+- [What this feature does NOT include]
+EOF
+```
+
+**Guidelines for prd.md**:
+- Be specific and actionable
+- Include acceptance criteria that can be verified
+- Add technical notes from research agent
+- Define what's out of scope to prevent scope creep
+
+### Step 5: Configure Task Metadata
+
+```bash
+# Set branch name
+python3 ./.trellis/scripts/task.py set-branch "$PLAN_TASK_DIR" "feature/${PLAN_TASK_NAME}"
+
+# Set scope (from research agent suggestion)
+python3 ./.trellis/scripts/task.py set-scope "$PLAN_TASK_DIR" "<scope>"
+
+# Update dev_type in task.json
+jq --arg type "$PLAN_DEV_TYPE" '.dev_type = $type' \
+  "$PLAN_TASK_DIR/task.json" > "$PLAN_TASK_DIR/task.json.tmp" \
+  && mv "$PLAN_TASK_DIR/task.json.tmp" "$PLAN_TASK_DIR/task.json"
+```
+
+### Step 6: Validate Configuration
+
+```bash
+python3 ./.trellis/scripts/task.py validate "$PLAN_TASK_DIR"
+```
+
+If validation fails, fix the invalid paths and re-validate.
+
+### Step 7: Output Summary
+
+Print a summary for the caller:
+
+```bash
+echo "=== Plan Complete ==="
+echo "Task Directory: $PLAN_TASK_DIR"
+echo ""
+echo "Files created:"
+ls -la "$PLAN_TASK_DIR"
+echo ""
+echo "Context summary:"
+python3 ./.trellis/scripts/task.py list-context "$PLAN_TASK_DIR"
+echo ""
+echo "Ready for: python3 ./.trellis/scripts/multi_agent/start.py $PLAN_TASK_DIR"
+```
+
+---
+
+## Key Principles
+
+1. **Reject early, reject clearly** - Don't waste time on bad requirements
+2. **Research before configure** - Always call research agent to understand the codebase
+3. **Validate all paths** - Every file in jsonl must exist
+4. **Be specific in prd.md** - Vague requirements lead to wrong implementations
+5. **Include acceptance criteria** - Check agent needs to verify something concrete
+6. **Set appropriate scope** - This affects commit message format
+
+---
+
+## Error Handling
+
+### Research Agent Returns No Results
+
+If research agent finds no relevant specs:
+- Use only the base specs from init-context
+- Add a note in prd.md that this is a new area without existing patterns
+
+### Path Not Found
+
+If add-context fails because path doesn't exist:
+- Skip that entry
+- Log a warning
+- Continue with other entries
+
+### Validation Fails
+
+If final validation fails:
+- Read the error output
+- Remove invalid entries from jsonl files
+- Re-validate
+
+---
+
+## Examples
+
+### Example: Accepted Requirement
+
+```
+Input:
+  PLAN_TASK_NAME = "add-rate-limiting"
+  PLAN_DEV_TYPE = "backend"
+  PLAN_REQUIREMENT = "Add rate limiting to API endpoints using a sliding window algorithm. Limit to 100 requests per minute per IP. Return 429 status when exceeded."
+
+Result: ACCEPTED - Clear, specific, has defined behavior
+
+Output:
+  .trellis/tasks/02-03-add-rate-limiting/
+  ├── task.json      # branch: feature/add-rate-limiting, scope: api
+  ├── prd.md            # Detailed requirements with acceptance criteria
+  ├── implement.jsonl   # Backend specs + existing middleware patterns
+  ├── check.jsonl       # Quality guidelines + API testing specs
+  └── debug.jsonl       # Error handling specs
+```
+
+### Example: Rejected - Vague Requirement
+
+```
+Input:
+  PLAN_REQUIREMENT = "Make the API faster"
+
+Result: REJECTED
+
+=== PLAN REJECTED ===
+
+Reason: Unclear or Vague
+
+Details:
+"Make the API faster" does not specify:
+- Which endpoints need optimization
+- Current performance baseline
+- Target performance metrics
+- Acceptable trade-offs (memory, complexity)
+
+Suggestions:
+- Identify specific slow endpoints with response times
+- Define target latency (e.g., "GET /users should respond in <100ms")
+- Specify if caching, query optimization, or architecture changes are acceptable
+```
+
+### Example: Rejected - Too Large
+
+```
+Input:
+  PLAN_REQUIREMENT = "Add user authentication, authorization, password reset, 2FA, OAuth integration, and audit logging"
+
+Result: REJECTED
+
+=== PLAN REJECTED ===
+
+Reason: Too Large / Should Be Split
+
+Details:
+This requirement bundles 6 distinct features that should be implemented separately:
+1. User authentication (login/logout)
+2. Authorization (roles/permissions)
+3. Password reset flow
+4. Two-factor authentication
+5. OAuth integration
+6. Audit logging
+
+Suggestions:
+- Start with basic authentication first
+- Create separate features for each capability
+- Consider dependencies (auth before authz, etc.)
+```
diff --git a/.claude/agents/research.md b/.claude/agents/research.md
new file mode 100644
index 000000000..659d59c61
--- /dev/null
+++ b/.claude/agents/research.md
@@ -0,0 +1,120 @@
+---
+name: research
+description: |
+  Code and tech search expert. Pure research, no code modifications. Finds files, patterns, and tech solutions.
+tools: Read, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, Skill, mcp__chrome-devtools__*
+model: opus
+---
+# Research Agent
+
+You are the Research Agent in the Trellis workflow.
+
+## Core Principle
+
+**You do one thing: find and explain information.**
+
+You are a documenter, not a reviewer. Your job is to help get the information needed.
+
+---
+
+## Core Responsibilities
+
+### 1. Internal Search (Project Code)
+
+| Search Type | Goal | Tools |
+|-------------|------|-------|
+| **WHERE** | Locate files/components | Glob, Grep |
+| **HOW** | Understand code logic | Read, Grep |
+| **PATTERN** | Discover existing patterns | Grep, Read |
+
+### 2. External Search (Tech Solutions)
+
+Use web search for best practices and code examples.
+
+---
+
+## Strict Boundaries
+
+### Only Allowed
+
+- Describe **what exists**
+- Describe **where it is**
+- Describe **how it works**
+- Describe **how components interact**
+
+### Forbidden (unless explicitly asked)
+
+- Suggest improvements
+- Criticize implementation
+- Recommend refactoring
+- Modify any files
+- Execute git commands
+
+---
+
+## Workflow
+
+### Step 1: Understand Search Request
+
+Analyze the query, determine:
+
+- Search type (internal/external/mixed)
+- Search scope (global/specific directory)
+- Expected output (file list/code patterns/tech solutions)
+
+### Step 2: Execute Search
+
+Execute multiple independent searches in parallel for efficiency.
+
+### Step 3: Organize Results
+
+Output structured results in report format.
+
+---
+
+## Report Format
+
+```markdown
+## Search Results
+
+### Query
+
+{original query}
+
+### Files Found
+
+| File Path | Description |
+|-----------|-------------|
+| `src/services/xxx.ts` | Main implementation |
+| `src/types/xxx.ts` | Type definitions |
+
+### Code Pattern Analysis
+
+{Describe discovered patterns, cite specific files and line numbers}
+
+### Related Spec Documents
+
+- `.trellis/spec/xxx.md` - {description}
+
+### Not Found
+
+{If some content was not found, explain}
+```
+
+---
+
+## Guidelines
+
+### DO
+
+- Provide specific file paths and line numbers
+- Quote actual code snippets
+- Distinguish "definitely found" and "possibly related"
+- Explain search scope and limitations
+
+### DON'T
+
+- Don't guess uncertain info
+- Don't omit important search results
+- Don't add improvement suggestions in report (unless explicitly asked)
+- Don't modify any files
diff --git a/.claude/commands/trellis/before-backend-dev.md b/.claude/commands/trellis/before-backend-dev.md
new file mode 100644
index 000000000..7dfcd365e
--- /dev/null
+++ b/.claude/commands/trellis/before-backend-dev.md
@@ -0,0 +1,13 @@
+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/.claude/commands/trellis/before-frontend-dev.md b/.claude/commands/trellis/before-frontend-dev.md
new file mode 100644
index 000000000..9687edc1c
--- /dev/null
+++ b/.claude/commands/trellis/before-frontend-dev.md
@@ -0,0 +1,13 @@
+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/.claude/commands/trellis/brainstorm.md b/.claude/commands/trellis/brainstorm.md
new file mode 100644
index 000000000..bc2b8afe2
--- /dev/null
+++ b/.claude/commands/trellis/brainstorm.md
@@ -0,0 +1,487 @@
+# 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 `/trellis: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 |
+|---------|-------------|
+| `/trellis:start` | Entry point that triggers brainstorm |
+| `/trellis:finish-work` | After implementation is complete |
+| `/trellis:update-spec` | If new patterns emerge during work |
diff --git a/.claude/commands/trellis/break-loop.md b/.claude/commands/trellis/break-loop.md
new file mode 100644
index 000000000..99057513d
--- /dev/null
+++ b/.claude/commands/trellis/break-loop.md
@@ -0,0 +1,125 @@
+# Break the Loop - Deep Bug Analysis
+
+When debug is complete, use this command 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 commands 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/.claude/commands/trellis/check-backend.md b/.claude/commands/trellis/check-backend.md
new file mode 100644
index 000000000..886f5c9f8
--- /dev/null
+++ b/.claude/commands/trellis/check-backend.md
@@ -0,0 +1,13 @@
+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/.claude/commands/trellis/check-cross-layer.md b/.claude/commands/trellis/check-cross-layer.md
new file mode 100644
index 000000000..591d39b55
--- /dev/null
+++ b/.claude/commands/trellis/check-cross-layer.md
@@ -0,0 +1,153 @@
+# 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 |
+| **`/trellis:check-cross-layer`** (this) | 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/.claude/commands/trellis/check-frontend.md b/.claude/commands/trellis/check-frontend.md
new file mode 100644
index 000000000..3771ae3ab
--- /dev/null
+++ b/.claude/commands/trellis/check-frontend.md
@@ -0,0 +1,13 @@
+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/.claude/commands/trellis/create-command.md b/.claude/commands/trellis/create-command.md
new file mode 100644
index 000000000..121d37f9c
--- /dev/null
+++ b/.claude/commands/trellis/create-command.md
@@ -0,0 +1,154 @@
+# Create New Slash Command
+
+Create a new slash command in both `.cursor/commands/` (with `trellis-` prefix) and `.claude/commands/trellis/` directories based on user requirements.
+
+## Usage
+
+```
+/trellis:create-command <command-name> <description>
+```
+
+**Example**:
+```
+/trellis:create-command review-pr Check PR code changes against project guidelines
+```
+
+## Execution Steps
+
+### 1. Parse Input
+
+Extract from user input:
+- **Command name**: Use kebab-case (e.g., `review-pr`)
+- **Description**: What the command should accomplish
+
+### 2. Analyze Requirements
+
+Determine command 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, code templates
+
+### 3. Generate Command Content
+
+Based on command type, generate appropriate content:
+
+**Simple command** (1-3 lines):
+```markdown
+Concise instruction describing what to do
+```
+
+**Complex command** (with steps):
+```markdown
+# Command Title
+
+Command description
+
+## Steps
+
+### 1. First Step
+Specific action
+
+### 2. Second Step
+Specific action
+
+## Output Format (if needed)
+
+Template
+```
+
+### 4. Create Files
+
+Create in both directories:
+- `.cursor/commands/trellis-<command-name>.md`
+- `.claude/commands/trellis/<command-name>.md`
+
+### 5. Confirm Creation
+
+Output result:
+```
+[OK] Created Slash Command: /<command-name>
+
+File paths:
+- .cursor/commands/trellis-<command-name>.md
+- .claude/commands/trellis/<command-name>.md
+
+Usage:
+/trellis:<command-name>
+
+Description:
+<description>
+```
+
+## Command Content Guidelines
+
+### [OK] Good command 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 command should not exceed 100 lines
+3. **Duplicate functionality**: Check if similar command exists first
+
+## Naming Conventions
+
+| Command 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` |
+
+## Example
+
+### Input
+```
+/trellis:create-command review-pr Check PR code changes against project guidelines
+```
+
+### Generated Command Content
+```markdown
+# PR Code Review
+
+Check current PR code changes against project guidelines.
+
+## Steps
+
+### 1. Get Changed Files
+```bash
+git diff main...HEAD --name-only
+```
+
+### 2. Categorized Review
+
+**Frontend files** (`apps/web/`):
+- Reference `.trellis/spec/frontend/index.md`
+
+**Backend files** (`packages/api/`):
+- Reference `.trellis/spec/backend/index.md`
+
+### 3. Output Review Report
+
+Format:
+
+## PR Review Report
+
+### Changed Files
+- [file list]
+
+### Check Results
+- [OK] Passed items
+- [X] Issues found
+
+### Suggestions
+- [improvement suggestions]
+```
diff --git a/.claude/commands/trellis/finish-work.md b/.claude/commands/trellis/finish-work.md
new file mode 100644
index 000000000..9daea6728
--- /dev/null
+++ b/.claude/commands/trellis/finish-work.md
@@ -0,0 +1,153 @@
+# 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?
+
+### 1.5. Test Coverage
+
+Check if your change needs new or updated tests (see `.trellis/spec/unit-test/conventions.md`):
+
+- [ ] New pure function → unit test added?
+- [ ] Bug fix → regression test added in `test/regression.test.ts`?
+- [ ] Changed init/update behavior → integration test added/updated?
+- [ ] No logic change (text/data only) → no test needed
+
+### 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**:
+In pipeline mode, the finish agent will automatically detect and execute spec updates when gaps are found.
+If running this checklist manually, ensure spec sync is complete before committing — run `/trellis:update-spec` if needed.
+
+### 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 -> /trellis:finish-work -> git commit -> /trellis:record-session
+                          |                              |
+                   Ensure completeness              Record progress
+                   
+Debug Flow:
+  Hit bug -> Fix -> /trellis:break-loop -> Knowledge capture
+                       |
+                  Deep analysis
+```
+
+- `/trellis:finish-work` - Check work completeness (this command)
+- `/trellis:record-session` - Record session and commits
+- `/trellis: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/.claude/commands/trellis/integrate-skill.md b/.claude/commands/trellis/integrate-skill.md
new file mode 100644
index 000000000..cacafd5a6
--- /dev/null
+++ b/.claude/commands/trellis/integrate-skill.md
@@ -0,0 +1,219 @@
+# Integrate Claude Skill into Project Guidelines
+
+Adapt and integrate a Claude global skill into your project's development guidelines (not directly into project code).
+
+## Usage
+
+```
+/trellis:integrate-skill <skill-name>
+```
+
+**Examples**:
+```
+/trellis:integrate-skill frontend-design
+/trellis: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
+
+```bash
+openskills read <skill-name>
+```
+
+If the skill doesn't exist, prompt user to check available skills:
+```bash
+# Available skills are listed in AGENTS.md under <available_skills>
+```
+
+### 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 Command
+
+If this skill is frequently used, create a shortcut command:
+
+```bash
+/trellis: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/.claude/commands/trellis/onboard.md b/.claude/commands/trellis/onboard.md
new file mode 100644
index 000000000..732f80d13
--- /dev/null
+++ b/.claude/commands/trellis/onboard.md
@@ -0,0 +1,358 @@
+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 command 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, COMMAND DEEP DIVE)
+- Explain WHY this workflow exists
+- Explain WHAT each command 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 command 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 `/trellis:start` command 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` commands 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-*` commands re-verify code against guidelines AFTER writing, catching drift that occurred during development. The `/trellis:finish-work` command 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
+
+---
+
+## COMMAND DEEP DIVE
+
+### /trellis: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 /trellis:start: AI is blind. It might work on wrong branch, conflict with others' work, or redo already-completed work.
+- With /trellis:start: AI knows project context, can continue where previous session left off, avoids conflicts.
+
+---
+
+### /trellis:before-frontend-dev and /trellis: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.
+
+---
+
+### /trellis:check-frontend and /trellis: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.
+
+---
+
+### /trellis: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
+
+---
+
+### /trellis:finish-work - Holistic Pre-Commit Review
+
+**WHY IT EXISTS**:
+The `/check-*` commands 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
+
+---
+
+### /trellis: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 `/trellis: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] /trellis: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] /trellis:before-frontend-dev** - Inject project-specific frontend knowledge
+**[4/8] Investigate and fix the bug** - Actual development work
+**[5/8] /trellis:check-frontend** - Re-verify code against guidelines
+**[6/8] /trellis:finish-work** - Holistic cross-layer review
+**[7/8] Human tests and commits** - Human validates before code enters repo
+**[8/8] /trellis:record-session** - Persist memory for future sessions
+
+### Example 2: Planning Session (No Code)
+
+**[1/4] /trellis: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] /trellis:record-session (with --summary)** - Planning decisions must be recorded
+
+### Example 3: Code Review Fixes
+
+**[1/6] /trellis:start** - Resume context from previous session
+**[2/6] /trellis:before-backend-dev** - Re-inject guidelines before fixes
+**[3/6] Fix each CR issue** - Address feedback with guidelines in context
+**[4/6] /trellis:check-backend** - Verify fixes didn't introduce new issues
+**[5/6] /trellis:finish-work** - Document lessons from CR
+**[6/6] Human commits, then /trellis:record-session** - Preserve CR lessons
+
+### Example 4: Large Refactoring
+
+**[1/5] /trellis: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] /trellis: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] /trellis:start** - See if this bug was investigated before
+**[2/6] /trellis:before-backend-dev** - Guidelines might document known gotchas
+**[3/6] Investigation** - Actual debugging work
+**[4/6] /trellis:check-backend** - Verify debug changes don't break other things
+**[5/6] /trellis:finish-work** - Debug findings might need documentation
+**[6/6] Human commits, then /trellis: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 commands inject project knowledge.
+3. **Check after code** - /check-* commands catch context drift.
+4. **Record everything** - /trellis: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` commands 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` commands 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 `/trellis: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/.claude/commands/trellis/parallel.md b/.claude/commands/trellis/parallel.md
new file mode 100644
index 000000000..3db5c3ef5
--- /dev/null
+++ b/.claude/commands/trellis/parallel.md
@@ -0,0 +1,193 @@
+# Multi-Agent Pipeline Orchestrator
+
+You are the Multi-Agent Pipeline Orchestrator Agent, running in the main repository, responsible for collaborating with users to manage parallel development tasks.
+
+## Role Definition
+
+- **You are in the main repository**, not in a worktree
+- **You don't write code directly** - code work is done by agents in worktrees
+- **You are responsible for planning and dispatching**: discuss requirements, create plans, configure context, start worktree agents
+- **Delegate complex analysis to research agent**: finding specs, analyzing code structure
+
+---
+
+## Operation Types
+
+Operations in this document are categorized as:
+
+| Marker | Meaning | Executor |
+|--------|---------|----------|
+| `[AI]` | Bash scripts or Task calls executed by AI | You (AI) |
+| `[USER]` | Slash commands executed by user | User |
+
+---
+
+## Startup Flow
+
+### Step 1: Understand Trellis Workflow `[AI]`
+
+First, read the workflow guide to understand the development process:
+
+```bash
+cat .trellis/workflow.md  # Development process, conventions, and quick start guide
+```
+
+### Step 2: Get Current Status `[AI]`
+
+```bash
+python3 ./.trellis/scripts/get_context.py
+```
+
+### Step 3: Read Project Guidelines `[AI]`
+
+```bash
+cat .trellis/spec/frontend/index.md  # Frontend guidelines index
+cat .trellis/spec/backend/index.md   # Backend guidelines index
+cat .trellis/spec/guides/index.md    # Thinking guides
+```
+
+### Step 4: Ask User for Requirements
+
+Ask the user:
+
+1. What feature to develop?
+2. Which modules are involved?
+3. Development type? (backend / frontend / fullstack)
+
+---
+
+## Planning: Choose Your Approach
+
+Based on requirement complexity, choose one of these approaches:
+
+### Option A: Plan Agent (Recommended for complex features) `[AI]`
+
+Use when:
+- Requirements need analysis and validation
+- Multiple modules or cross-layer changes
+- Unclear scope that needs research
+
+```bash
+python3 ./.trellis/scripts/multi_agent/plan.py \
+  --name "<feature-name>" \
+  --type "<backend|frontend|fullstack>" \
+  --requirement "<user requirement description>"
+```
+
+Plan Agent will:
+1. Evaluate requirement validity (may reject if unclear/too large)
+2. Call research agent to analyze codebase
+3. Create and configure task directory
+4. Write prd.md with acceptance criteria
+5. Output ready-to-use task directory
+
+After plan.py completes, start the worktree agent:
+
+```bash
+python3 ./.trellis/scripts/multi_agent/start.py "$TASK_DIR"
+```
+
+### Option B: Manual Configuration (For simple/clear features) `[AI]`
+
+Use when:
+- Requirements are already clear and specific
+- You know exactly which files are involved
+- Simple, well-scoped changes
+
+#### Step 1: Create Task Directory
+
+```bash
+# title is task description, --slug for task directory name
+TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<title>" --slug <task-name>)
+```
+
+#### Step 2: Configure Task
+
+```bash
+# Initialize jsonl context files
+python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <dev_type>
+
+# Set branch and scope
+python3 ./.trellis/scripts/task.py set-branch "$TASK_DIR" feature/<name>
+python3 ./.trellis/scripts/task.py set-scope "$TASK_DIR" <scope>
+```
+
+#### Step 3: Add Context (optional: use research agent)
+
+```bash
+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 4: Create prd.md
+
+```bash
+cat > "$TASK_DIR/prd.md" << 'EOF'
+# Feature: <name>
+
+## Requirements
+- ...
+
+## Acceptance Criteria
+- ...
+EOF
+```
+
+#### Step 5: Validate and Start
+
+```bash
+python3 ./.trellis/scripts/task.py validate "$TASK_DIR"
+python3 ./.trellis/scripts/multi_agent/start.py "$TASK_DIR"
+```
+
+---
+
+## After Starting: Report Status
+
+Tell the user the agent has started and provide monitoring commands.
+
+---
+
+## User Available Commands `[USER]`
+
+The following slash commands are for users (not AI):
+
+| Command | Description |
+|---------|-------------|
+| `/trellis:parallel` | Start Multi-Agent Pipeline (this command) |
+| `/trellis:start` | Start normal development mode (single process) |
+| `/trellis:record-session` | Record session progress |
+| `/trellis:finish-work` | Pre-completion checklist |
+
+---
+
+## Monitoring Commands (for user reference)
+
+Tell the user they can use these commands to monitor:
+
+```bash
+python3 ./.trellis/scripts/multi_agent/status.py                    # Overview
+python3 ./.trellis/scripts/multi_agent/status.py --log <name>       # View log
+python3 ./.trellis/scripts/multi_agent/status.py --watch <name>     # Real-time monitoring
+python3 ./.trellis/scripts/multi_agent/cleanup.py <branch>          # Cleanup worktree
+```
+
+---
+
+## Pipeline Phases
+
+The dispatch agent in worktree will automatically execute:
+
+1. implement → Implement feature
+2. check → Check code quality
+3. finish → Final verification
+4. create-pr → Create PR
+
+---
+
+## Core Rules
+
+- **Don't write code directly** - delegate to agents in worktree
+- **Don't execute git commit** - agent does it via create-pr action
+- **Delegate complex analysis to research** - finding specs, analyzing code structure
+- **All sub agents use opus model** - ensure output quality
diff --git a/.claude/commands/trellis/record-session.md b/.claude/commands/trellis/record-session.md
new file mode 100644
index 000000000..4a7e6ff07
--- /dev/null
+++ b/.claude/commands/trellis/record-session.md
@@ -0,0 +1,61 @@
+[!] **Prerequisite**: This command 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/.claude/commands/trellis/start.md b/.claude/commands/trellis/start.md
new file mode 100644
index 000000000..39fd44f76
--- /dev/null
+++ b/.claude/commands/trellis/start.md
@@ -0,0 +1,389 @@
+# Start Session
+
+Initialize your AI development session and begin working on tasks.
+
+---
+
+## Operation Types
+
+| Marker | Meaning | Executor |
+|--------|---------|----------|
+| `[AI]` | Bash scripts or Task calls executed by AI | You (AI) |
+| `[USER]` | Slash commands 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
+cat .trellis/spec/unit-test/index.md # Testing guidelines
+```
+
+> **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 | Direct Edit |
+| **Simple Task** | Clear goal, 1-2 files, well-defined scope | Quick confirm → Implement |
+| **Complex Task** | Vague goal, multiple files, architectural decisions | **Brainstorm → Task Workflow** |
+
+### Classification Signals
+
+**Trivial/Simple indicators:**
+- User specifies exact file and change
+- "Fix the typo in X"
+- "Add field Y to component Z"
+- Clear acceptance criteria already stated
+
+**Complex indicators:**
+- "I want to add a feature for..."
+- "Can you help me improve..."
+- Mentions multiple areas or systems
+- No clear implementation path
+- User seems unsure about approach
+
+### Decision Rule
+
+> **If in doubt, use Brainstorm + Task Workflow.**
+>
+> Task Workflow ensures code-spec context is injected to agents, resulting in higher quality code.
+> The overhead is minimal, but the benefit is significant.
+
+---
+
+## 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 `/trellis: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 `/trellis: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
+
+> **Subtask Decomposition**: If brainstorm reveals multiple independent work items,
+> consider creating subtasks using `--parent` flag or `add-subtask` command.
+> See `/trellis:brainstorm` Step 8 for details.
+
+### Key Brainstorm Principles
+
+| Principle | Description |
+|-----------|-------------|
+| **One question at a time** | Never overwhelm with multiple questions |
+| **Update PRD immediately** | After each answer, update the document |
+| **Prefer multiple choice** | Easier for users to answer |
+| **YAGNI** | Challenge unnecessary complexity |
+
+---
+
+## Task Workflow (Development Tasks)
+
+**Why this workflow?**
+- Research Agent analyzes what code-spec files are needed
+- Code-spec files are configured in jsonl files
+- Implement Agent receives code-spec context via Hook injection
+- Check Agent verifies against code-spec requirements
+- 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?
+
+**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, call Research Agent to find relevant specs and patterns:
+
+```
+Task(
+  subagent_type: "research",
+  prompt: "Analyze the codebase for this task:
+
+  Task: <goal from PRD>
+  Type: <frontend/backend/fullstack>
+
+  Please find:
+  1. Relevant code-spec files in .trellis/spec/
+  2. Existing code patterns to follow (find 2-3 examples)
+  3. Files that will likely need modification
+
+  Output:
+  ## Relevant Code-Specs
+  - <path>: <why it's relevant>
+
+  ## Code Patterns Found
+  - <pattern>: <example file path>
+
+  ## Files to Modify
+  - <path>: <what change>",
+  model: "opus"
+)
+```
+
+**Step 6: Configure Context** `[AI]`
+
+Initialize default context:
+
+```bash
+python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <type>
+# type: backend | frontend | fullstack
+```
+
+Add code-spec files found by Research Agent:
+
+```bash
+# For each relevant code-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]`
+
+Call Implement Agent (code-spec context is auto-injected by hook):
+
+```
+Task(
+  subagent_type: "implement",
+  prompt: "Implement the task described in prd.md.
+
+  Follow all code-spec files that have been injected into your context.
+  Run lint and typecheck before finishing.",
+  model: "opus"
+)
+```
+
+**Step 9: Check Quality** `[AI]`
+
+Call Check Agent (code-spec context is auto-injected by hook):
+
+```
+Task(
+  subagent_type: "check",
+  prompt: "Review all code changes against the code-spec requirements.
+
+  Fix any issues you find directly.
+  Ensure lint and typecheck pass.",
+  model: "opus"
+)
+```
+
+**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 `/trellis: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).
+
+---
+
+## Commands Reference
+
+### User Commands `[USER]`
+
+| Command | When to Use |
+|---------|-------------|
+| `/trellis:start` | Begin a session (this command) |
+| `/trellis:brainstorm` | Clarify vague requirements (called from start) |
+| `/trellis:parallel` | Complex tasks needing isolated worktree |
+| `/trellis:finish-work` | Before committing changes |
+| `/trellis: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 code-spec/context file 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 |
+
+### Sub Agents `[AI]`
+
+| Agent | Purpose | Hook Injection |
+|-------|---------|----------------|
+| research | Analyze codebase | No (reads directly) |
+| implement | Write code | Yes (implement.jsonl) |
+| check | Review & fix | Yes (check.jsonl) |
+| debug | Fix specific issues | Yes (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/.claude/commands/trellis/update-spec.md b/.claude/commands/trellis/update-spec.md
new file mode 100644
index 000000000..3f0b2e77c
--- /dev/null
+++ b/.claude/commands/trellis/update-spec.md
@@ -0,0 +1,354 @@
+# Update Code-Spec - Capture Executable Contracts
+
+When you learn something valuable (from debugging, implementing, or discussion), use this command 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.
+
+### Mandatory Triggers
+
+Apply code-spec depth when the change includes any of:
+- New/changed command or API signature
+- Cross-layer request/response contract change
+- Database schema/migration change
+- Infra integration (storage, queue, cache, secrets, env wiring)
+
+### Mandatory Output (7 Sections)
+
+For triggered tasks, include all sections below:
+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
+- Backend command/API/DB signature(s)
+
+### 3. Contracts
+- Request fields (name, type, constraints)
+- Response fields (name, type, constraints)
+- Environment keys (required/optional)
+
+### 4. Validation & Error Matrix
+- <condition> -> <error>
+
+### 5. Good/Base/Bad Cases
+- Good: ...
+- Base: ...
+- Bad: ...
+
+### 6. Tests Required
+- Unit/Integration/E2E with assertion points
+
+### 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 → /trellis:update-spec → Knowledge captured
+       ↑                                  ↓
+  /trellis:break-loop ←──────────────────── Future sessions benefit
+  (deep bug analysis)
+```
+
+- `/trellis:break-loop` - Analyzes bugs deeply, often reveals spec updates needed
+- `/trellis:update-spec` - Actually makes the updates (this command)
+- `/trellis: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/.claude/hooks/inject-subagent-context.py b/.claude/hooks/inject-subagent-context.py
new file mode 100644
index 000000000..95e7f5ced
--- /dev/null
+++ b/.claude/hooks/inject-subagent-context.py
@@ -0,0 +1,788 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Multi-Agent Pipeline Context Injection Hook
+
+Core Design Philosophy:
+- Dispatch becomes a pure dispatcher, only responsible for "calling subagents"
+- Hook is responsible for injecting all context, subagent works autonomously with complete info
+- Each agent has a dedicated jsonl file defining its context
+- No resume needed, no segmentation, behavior controlled by code not prompt
+
+Trigger: PreToolUse (before Task tool call)
+
+Context Source: .trellis/.current-task points to task directory
+- implement.jsonl - Implement agent dedicated context
+- check.jsonl     - Check agent dedicated context
+- debug.jsonl     - Debug agent dedicated context
+- research.jsonl  - Research agent dedicated context (optional, usually not needed)
+- cr.jsonl        - Code review dedicated context
+- prd.md          - Requirements document
+- info.md         - Technical design
+- codex-review-output.txt - Code Review results
+"""
+
+# IMPORTANT: Suppress all warnings FIRST
+import warnings
+warnings.filterwarnings("ignore")
+
+import json
+import os
+import sys
+from pathlib import Path
+
+# 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]
+
+# =============================================================================
+# Path Constants (change here to rename directories)
+# =============================================================================
+
+DIR_WORKFLOW = ".trellis"
+DIR_WORKSPACE = "workspace"
+DIR_TASKS = "tasks"
+DIR_SPEC = "spec"
+FILE_CURRENT_TASK = ".current-task"
+FILE_TASK_JSON = "task.json"
+
+# Agents that don't update phase (can be called at any time)
+AGENTS_NO_PHASE_UPDATE = {"debug", "research"}
+
+# =============================================================================
+# Subagent Constants (change here to rename subagent types)
+# =============================================================================
+
+AGENT_IMPLEMENT = "implement"
+AGENT_CHECK = "check"
+AGENT_DEBUG = "debug"
+AGENT_RESEARCH = "research"
+
+# Agents that require a task directory
+AGENTS_REQUIRE_TASK = (AGENT_IMPLEMENT, AGENT_CHECK, AGENT_DEBUG)
+# All supported agents
+AGENTS_ALL = (AGENT_IMPLEMENT, AGENT_CHECK, AGENT_DEBUG, AGENT_RESEARCH)
+
+
+def find_repo_root(start_path: str) -> str | None:
+    """
+    Find git repo root from start_path upwards
+
+    Returns:
+        Repo root path, or None if not found
+    """
+    current = Path(start_path).resolve()
+    while current != current.parent:
+        if (current / ".git").exists():
+            return str(current)
+        current = current.parent
+    return None
+
+
+def get_current_task(repo_root: str) -> str | None:
+    """
+    Read current task directory path from .trellis/.current-task
+
+    Returns:
+        Task directory relative path (relative to repo_root)
+        None if not set
+    """
+    current_task_file = os.path.join(repo_root, DIR_WORKFLOW, FILE_CURRENT_TASK)
+    if not os.path.exists(current_task_file):
+        return None
+
+    try:
+        with open(current_task_file, "r", encoding="utf-8") as f:
+            content = f.read().strip()
+            return content if content else None
+    except Exception:
+        return None
+
+
+def update_current_phase(repo_root: str, task_dir: str, subagent_type: str) -> None:
+    """
+    Update current_phase in task.json based on subagent_type.
+
+    This ensures phase tracking is always accurate, regardless of whether
+    dispatch agent remembers to update it.
+
+    Logic:
+    - Read next_action array from task.json
+    - Find the next phase whose action matches subagent_type
+    - Only move forward, never backward
+    - Some agents (debug, research) don't update phase
+    """
+    if subagent_type in AGENTS_NO_PHASE_UPDATE:
+        return
+
+    task_json_path = os.path.join(repo_root, task_dir, FILE_TASK_JSON)
+    if not os.path.exists(task_json_path):
+        return
+
+    try:
+        with open(task_json_path, "r", encoding="utf-8") as f:
+            task_data = json.load(f)
+
+        current_phase = task_data.get("current_phase", 0)
+        next_actions = task_data.get("next_action", [])
+
+        # Map action names to subagent types
+        # "implement" -> "implement", "check" -> "check", "finish" -> "check"
+        action_to_agent = {
+            "implement": "implement",
+            "check": "check",
+            "finish": "check",  # finish uses check agent
+        }
+
+        # Find the next phase that matches this subagent_type
+        new_phase = None
+        for action in next_actions:
+            phase_num = action.get("phase", 0)
+            action_name = action.get("action", "")
+            expected_agent = action_to_agent.get(action_name)
+
+            # Only consider phases after current_phase
+            if phase_num > current_phase and expected_agent == subagent_type:
+                new_phase = phase_num
+                break
+
+        if new_phase is not None:
+            task_data["current_phase"] = new_phase
+
+            with open(task_json_path, "w", encoding="utf-8") as f:
+                json.dump(task_data, f, indent=2, ensure_ascii=False)
+    except Exception:
+        # Don't fail the hook if phase update fails
+        pass
+
+
+def read_file_content(base_path: str, file_path: str) -> str | None:
+    """Read file content, return None if file doesn't exist"""
+    full_path = os.path.join(base_path, file_path)
+    if os.path.exists(full_path) and os.path.isfile(full_path):
+        try:
+            with open(full_path, "r", encoding="utf-8") as f:
+                return f.read()
+        except Exception:
+            return None
+    return None
+
+
+def read_directory_contents(
+    base_path: str, dir_path: str, max_files: int = 20
+) -> list[tuple[str, str]]:
+    """
+    Read all .md files in a directory
+
+    Args:
+        base_path: Base path (usually repo_root)
+        dir_path: Directory relative path
+        max_files: Max files to read (prevent huge directories)
+
+    Returns:
+        [(file_path, content), ...]
+    """
+    full_path = os.path.join(base_path, dir_path)
+    if not os.path.exists(full_path) or not os.path.isdir(full_path):
+        return []
+
+    results = []
+    try:
+        # Only read .md files, sorted by filename
+        md_files = sorted(
+            [
+                f
+                for f in os.listdir(full_path)
+                if f.endswith(".md") and os.path.isfile(os.path.join(full_path, f))
+            ]
+        )
+
+        for filename in md_files[:max_files]:
+            file_full_path = os.path.join(full_path, filename)
+            relative_path = os.path.join(dir_path, filename)
+            try:
+                with open(file_full_path, "r", encoding="utf-8") as f:
+                    content = f.read()
+                    results.append((relative_path, content))
+            except Exception:
+                continue
+    except Exception:
+        pass
+
+    return results
+
+
+def read_jsonl_entries(base_path: str, jsonl_path: str) -> list[tuple[str, str]]:
+    """
+    Read all file/directory contents referenced in jsonl file
+
+    Schema:
+        {"file": "path/to/file.md", "reason": "..."}
+        {"file": "path/to/dir/", "type": "directory", "reason": "..."}
+
+    Returns:
+        [(path, content), ...]
+    """
+    full_path = os.path.join(base_path, jsonl_path)
+    if not os.path.exists(full_path):
+        return []
+
+    results = []
+    try:
+        with open(full_path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    item = json.loads(line)
+                    file_path = item.get("file") or item.get("path")
+                    entry_type = item.get("type", "file")
+
+                    if not file_path:
+                        continue
+
+                    if entry_type == "directory":
+                        # Read all .md files in directory
+                        dir_contents = read_directory_contents(base_path, file_path)
+                        results.extend(dir_contents)
+                    else:
+                        # Read single file
+                        content = read_file_content(base_path, file_path)
+                        if content:
+                            results.append((file_path, content))
+                except json.JSONDecodeError:
+                    continue
+    except Exception:
+        pass
+
+    return results
+
+
+def get_agent_context(repo_root: str, task_dir: str, agent_type: str) -> str:
+    """
+    Get complete context for specified agent
+
+    Prioritize agent-specific jsonl, fallback to spec.jsonl if not exists
+    """
+    context_parts = []
+
+    # 1. Try agent-specific jsonl
+    agent_jsonl = f"{task_dir}/{agent_type}.jsonl"
+    agent_entries = read_jsonl_entries(repo_root, agent_jsonl)
+
+    # 2. If agent-specific jsonl doesn't exist or empty, fallback to spec.jsonl
+    if not agent_entries:
+        agent_entries = read_jsonl_entries(repo_root, f"{task_dir}/spec.jsonl")
+
+    # 3. Add all files from jsonl
+    for file_path, content in agent_entries:
+        context_parts.append(f"=== {file_path} ===\n{content}")
+
+    return "\n\n".join(context_parts)
+
+
+def get_implement_context(repo_root: str, task_dir: str) -> str:
+    """
+    Complete context for Implement Agent
+
+    Read order:
+    1. All files in implement.jsonl (dev specs)
+    2. prd.md (requirements)
+    3. info.md (technical design)
+    """
+    context_parts = []
+
+    # 1. Read implement.jsonl (or fallback to spec.jsonl)
+    base_context = get_agent_context(repo_root, task_dir, "implement")
+    if base_context:
+        context_parts.append(base_context)
+
+    # 2. Requirements document
+    prd_content = read_file_content(repo_root, f"{task_dir}/prd.md")
+    if prd_content:
+        context_parts.append(f"=== {task_dir}/prd.md (Requirements) ===\n{prd_content}")
+
+    # 3. Technical design
+    info_content = read_file_content(repo_root, f"{task_dir}/info.md")
+    if info_content:
+        context_parts.append(
+            f"=== {task_dir}/info.md (Technical Design) ===\n{info_content}"
+        )
+
+    return "\n\n".join(context_parts)
+
+
+def get_check_context(repo_root: str, task_dir: str) -> str:
+    """
+    Complete context for Check Agent
+
+    Read order:
+    1. All files in check.jsonl (check specs + dev specs)
+    2. prd.md (for understanding task intent)
+    """
+    context_parts = []
+
+    # 1. Read check.jsonl (or fallback to spec.jsonl + hardcoded check files)
+    check_entries = read_jsonl_entries(repo_root, f"{task_dir}/check.jsonl")
+
+    if check_entries:
+        for file_path, content in check_entries:
+            context_parts.append(f"=== {file_path} ===\n{content}")
+    else:
+        # Fallback: use hardcoded check files + spec.jsonl
+        check_files = [
+            (".claude/commands/trellis/finish-work.md", "Finish work checklist"),
+            (".claude/commands/trellis/check-cross-layer.md", "Cross-layer check spec"),
+            (".claude/commands/trellis/check-backend.md", "Backend check spec"),
+            (".claude/commands/trellis/check-frontend.md", "Frontend check spec"),
+        ]
+        for file_path, description in check_files:
+            content = read_file_content(repo_root, file_path)
+            if content:
+                context_parts.append(f"=== {file_path} ({description}) ===\n{content}")
+
+        # Add spec.jsonl
+        spec_entries = read_jsonl_entries(repo_root, f"{task_dir}/spec.jsonl")
+        for file_path, content in spec_entries:
+            context_parts.append(f"=== {file_path} (Dev spec) ===\n{content}")
+
+    # 2. Requirements document (for understanding task intent)
+    prd_content = read_file_content(repo_root, f"{task_dir}/prd.md")
+    if prd_content:
+        context_parts.append(
+            f"=== {task_dir}/prd.md (Requirements - for understanding intent) ===\n{prd_content}"
+        )
+
+    return "\n\n".join(context_parts)
+
+
+def get_finish_context(repo_root: str, task_dir: str) -> str:
+    """
+    Complete context for Finish phase (final check before PR)
+
+    Read order:
+    1. All files in finish.jsonl (if exists)
+    2. Fallback to finish-work.md only (lightweight final check)
+    3. update-spec.md (for active spec sync)
+    4. prd.md (for verifying requirements are met)
+    """
+    context_parts = []
+
+    # 1. Try finish.jsonl first
+    finish_entries = read_jsonl_entries(repo_root, f"{task_dir}/finish.jsonl")
+
+    if finish_entries:
+        for file_path, content in finish_entries:
+            context_parts.append(f"=== {file_path} ===\n{content}")
+    else:
+        # Fallback: only finish-work.md (lightweight)
+        finish_work = read_file_content(
+            repo_root, ".claude/commands/trellis/finish-work.md"
+        )
+        if finish_work:
+            context_parts.append(
+                f"=== .claude/commands/trellis/finish-work.md (Finish checklist) ===\n{finish_work}"
+            )
+
+    # 2. Spec update process (for active spec sync)
+    update_spec = read_file_content(
+        repo_root, ".claude/commands/trellis/update-spec.md"
+    )
+    if update_spec:
+        context_parts.append(
+            f"=== .claude/commands/trellis/update-spec.md (Spec update process) ===\n{update_spec}"
+        )
+
+    # 3. Requirements document (for verifying requirements are met)
+    prd_content = read_file_content(repo_root, f"{task_dir}/prd.md")
+    if prd_content:
+        context_parts.append(
+            f"=== {task_dir}/prd.md (Requirements - verify all met) ===\n{prd_content}"
+        )
+
+    return "\n\n".join(context_parts)
+
+
+def get_debug_context(repo_root: str, task_dir: str) -> str:
+    """
+    Complete context for Debug Agent
+
+    Read order:
+    1. All files in debug.jsonl (specs needed for fixing)
+    2. codex-review-output.txt (Codex Review results)
+    """
+    context_parts = []
+
+    # 1. Read debug.jsonl (or fallback to spec.jsonl + hardcoded check files)
+    debug_entries = read_jsonl_entries(repo_root, f"{task_dir}/debug.jsonl")
+
+    if debug_entries:
+        for file_path, content in debug_entries:
+            context_parts.append(f"=== {file_path} ===\n{content}")
+    else:
+        # Fallback: use spec.jsonl + hardcoded check files
+        spec_entries = read_jsonl_entries(repo_root, f"{task_dir}/spec.jsonl")
+        for file_path, content in spec_entries:
+            context_parts.append(f"=== {file_path} (Dev spec) ===\n{content}")
+
+        check_files = [
+            (".claude/commands/trellis/check-backend.md", "Backend check spec"),
+            (".claude/commands/trellis/check-frontend.md", "Frontend check spec"),
+            (".claude/commands/trellis/check-cross-layer.md", "Cross-layer check spec"),
+        ]
+        for file_path, description in check_files:
+            content = read_file_content(repo_root, file_path)
+            if content:
+                context_parts.append(f"=== {file_path} ({description}) ===\n{content}")
+
+    # 2. Codex review output (if exists)
+    codex_output = read_file_content(repo_root, f"{task_dir}/codex-review-output.txt")
+    if codex_output:
+        context_parts.append(
+            f"=== {task_dir}/codex-review-output.txt (Codex Review Results) ===\n{codex_output}"
+        )
+
+    return "\n\n".join(context_parts)
+
+
+def build_implement_prompt(original_prompt: str, context: str) -> str:
+    """Build complete prompt for Implement"""
+    return f"""# Implement Agent Task
+
+You are the Implement Agent in the Multi-Agent Pipeline.
+
+## Your Context
+
+All the information you need has been prepared for you:
+
+{context}
+
+---
+
+## Your Task
+
+{original_prompt}
+
+---
+
+## Workflow
+
+1. **Understand specs** - All dev specs are injected above, understand them
+2. **Understand requirements** - Read requirements document and technical design
+3. **Implement feature** - Implement following specs and design
+4. **Self-check** - Ensure code quality against check specs
+
+## Important Constraints
+
+- Do NOT execute git commit, only code modifications
+- Follow all dev specs injected above
+- Report list of modified/created files when done"""
+
+
+def build_check_prompt(original_prompt: str, context: str) -> str:
+    """Build complete prompt for Check"""
+    return f"""# Check Agent Task
+
+You are the Check Agent in the Multi-Agent Pipeline (code and cross-layer checker).
+
+## Your Context
+
+All check specs and dev specs you need:
+
+{context}
+
+---
+
+## Your Task
+
+{original_prompt}
+
+---
+
+## Workflow
+
+1. **Get changes** - Run `git diff --name-only` and `git diff` to get code changes
+2. **Check against specs** - Check item by item against specs above
+3. **Self-fix** - Fix issues directly, don't just report
+4. **Run verification** - Run project's lint and typecheck commands
+
+## Important Constraints
+
+- Fix issues yourself, don't just report
+- Must execute complete checklist in check specs
+- Pay special attention to impact radius analysis (L1-L5)"""
+
+
+def build_finish_prompt(original_prompt: str, context: str) -> str:
+    """Build complete prompt for Finish (final check before PR)"""
+    return f"""# Finish Agent Task
+
+You are performing the final check before creating a PR.
+
+## Your Context
+
+Finish checklist and requirements:
+
+{context}
+
+---
+
+## Your Task
+
+{original_prompt}
+
+---
+
+## Workflow
+
+1. **Review changes** - Run `git diff --name-only` to see all changed files
+2. **Verify requirements** - Check each requirement in prd.md is implemented
+3. **Spec sync** - Analyze whether changes introduce new patterns, contracts, or conventions
+   - If new pattern/convention found: read target spec file → update it → update index.md if needed
+   - If infra/cross-layer change: follow the 7-section mandatory template from update-spec.md
+   - If pure code fix with no new patterns: skip this step
+4. **Run final checks** - Execute lint and typecheck
+5. **Confirm ready** - Ensure code is ready for PR
+
+## Important Constraints
+
+- You MAY update spec files when gaps are detected (use update-spec.md as guide)
+- MUST read the target spec file BEFORE editing (avoid duplicating existing content)
+- Do NOT update specs for trivial changes (typos, formatting, obvious fixes)
+- If critical CODE issues found, report them clearly (fix specs, not code)
+- Verify all acceptance criteria in prd.md are met"""
+
+
+def build_debug_prompt(original_prompt: str, context: str) -> str:
+    """Build complete prompt for Debug"""
+    return f"""# Debug Agent Task
+
+You are the Debug Agent in the Multi-Agent Pipeline (issue fixer).
+
+## Your Context
+
+Dev specs and Codex Review results:
+
+{context}
+
+---
+
+## Your Task
+
+{original_prompt}
+
+---
+
+## Workflow
+
+1. **Understand issues** - Analyze issues pointed out in Codex Review
+2. **Locate code** - Find positions that need fixing
+3. **Fix against specs** - Fix issues following dev specs
+4. **Verify fixes** - Run typecheck to ensure no new issues
+
+## Important Constraints
+
+- Do NOT execute git commit, only code modifications
+- Run typecheck after each fix to verify
+- Report which issues were fixed and which files were modified"""
+
+
+def get_research_context(repo_root: str, task_dir: str | None) -> str:
+    """
+    Context for Research Agent
+
+    Research doesn't need much preset context, only needs:
+    1. Project structure overview (where spec directories are)
+    2. Optional research.jsonl (if there are specific search needs)
+    """
+    context_parts = []
+
+    # 1. Project structure overview (uses constants for paths)
+    spec_path = f"{DIR_WORKFLOW}/{DIR_SPEC}"
+    project_structure = f"""## Project Spec Directory Structure
+
+```
+{spec_path}/
+├── shared/      # Cross-project common specs (TypeScript, code quality, git)
+├── frontend/    # Frontend standards
+├── backend/     # Backend standards
+└── guides/      # Thinking guides (cross-layer, code reuse, etc.)
+
+{DIR_WORKFLOW}/big-question/  # Known issues and pitfalls
+```
+
+## Search Tips
+
+- Spec files: `{spec_path}/**/*.md`
+- Known issues: `{DIR_WORKFLOW}/big-question/`
+- Code search: Use Glob and Grep tools
+- Tech solutions: Use mcp__exa__web_search_exa or mcp__exa__get_code_context_exa"""
+
+    context_parts.append(project_structure)
+
+    # 2. If task directory exists, try reading research.jsonl (optional)
+    if task_dir:
+        research_entries = read_jsonl_entries(repo_root, f"{task_dir}/research.jsonl")
+        if research_entries:
+            context_parts.append(
+                "\n## Additional Search Context (from research.jsonl)\n"
+            )
+            for file_path, content in research_entries:
+                context_parts.append(f"=== {file_path} ===\n{content}")
+
+    return "\n\n".join(context_parts)
+
+
+def build_research_prompt(original_prompt: str, context: str) -> str:
+    """Build complete prompt for Research"""
+    return f"""# Research Agent Task
+
+You are the Research Agent in the Multi-Agent Pipeline (search researcher).
+
+## Core Principle
+
+**You do one thing: find and explain information.**
+
+You are a documenter, not a reviewer.
+
+## Project Info
+
+{context}
+
+---
+
+## Your Task
+
+{original_prompt}
+
+---
+
+## Workflow
+
+1. **Understand query** - Determine search type (internal/external) and scope
+2. **Plan search** - List search steps for complex queries
+3. **Execute search** - Execute multiple independent searches in parallel
+4. **Organize results** - Output structured report
+
+## Search Tools
+
+| Tool | Purpose |
+|------|---------|
+| Glob | Search by filename pattern |
+| Grep | Search by content |
+| Read | Read file content |
+| mcp__exa__web_search_exa | External web search |
+| mcp__exa__get_code_context_exa | External code/doc search |
+
+## Strict Boundaries
+
+**Only allowed**: Describe what exists, where it is, how it works
+
+**Forbidden** (unless explicitly asked):
+- Suggest improvements
+- Criticize implementation
+- Recommend refactoring
+- Modify any files
+
+## Report Format
+
+Provide structured search results including:
+- List of files found (with paths)
+- Code pattern analysis (if applicable)
+- Related spec documents
+- External references (if any)"""
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_name = input_data.get("tool_name", "")
+
+    if tool_name not in ("Task", "Agent"):
+        sys.exit(0)
+
+    tool_input = input_data.get("tool_input", {})
+    subagent_type = tool_input.get("subagent_type", "")
+    original_prompt = tool_input.get("prompt", "")
+    cwd = input_data.get("cwd", os.getcwd())
+
+    # Only handle subagent types we care about
+    if subagent_type not in AGENTS_ALL:
+        sys.exit(0)
+
+    # Find repo root
+    repo_root = find_repo_root(cwd)
+    if not repo_root:
+        sys.exit(0)
+
+    # Get current task directory (research doesn't require it)
+    task_dir = get_current_task(repo_root)
+
+    # implement/check/debug need task directory
+    if subagent_type in AGENTS_REQUIRE_TASK:
+        if not task_dir:
+            sys.exit(0)
+        # Check if task directory exists
+        task_dir_full = os.path.join(repo_root, task_dir)
+        if not os.path.exists(task_dir_full):
+            sys.exit(0)
+
+        # Update current_phase in task.json (system-level enforcement)
+        update_current_phase(repo_root, task_dir, subagent_type)
+
+    # Check for [finish] marker in prompt (check agent with finish context)
+    is_finish_phase = "[finish]" in original_prompt.lower()
+
+    # Get context and build prompt based on subagent type
+    if subagent_type == AGENT_IMPLEMENT:
+        assert task_dir is not None  # validated above
+        context = get_implement_context(repo_root, task_dir)
+        new_prompt = build_implement_prompt(original_prompt, context)
+    elif subagent_type == AGENT_CHECK:
+        assert task_dir is not None  # validated above
+        if is_finish_phase:
+            # Finish phase: use finish context (lighter, focused on final verification)
+            context = get_finish_context(repo_root, task_dir)
+            new_prompt = build_finish_prompt(original_prompt, context)
+        else:
+            # Regular check phase: use check context (full specs for self-fix loop)
+            context = get_check_context(repo_root, task_dir)
+            new_prompt = build_check_prompt(original_prompt, context)
+    elif subagent_type == AGENT_DEBUG:
+        assert task_dir is not None  # validated above
+        context = get_debug_context(repo_root, task_dir)
+        new_prompt = build_debug_prompt(original_prompt, context)
+    elif subagent_type == AGENT_RESEARCH:
+        # Research can work without task directory
+        context = get_research_context(repo_root, task_dir)
+        new_prompt = build_research_prompt(original_prompt, context)
+    else:
+        sys.exit(0)
+
+    if not context:
+        sys.exit(0)
+
+    # Return updated input with correct Claude Code PreToolUse format
+    output = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "allow",
+            "updatedInput": {**tool_input, "prompt": new_prompt},
+        }
+    }
+
+    print(json.dumps(output, ensure_ascii=False))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.claude/hooks/ralph-loop.py b/.claude/hooks/ralph-loop.py
new file mode 100644
index 000000000..983660fc7
--- /dev/null
+++ b/.claude/hooks/ralph-loop.py
@@ -0,0 +1,388 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Ralph Loop - SubagentStop Hook for Check Agent Loop Control
+
+Based on the Ralph Wiggum technique for autonomous agent loops.
+Uses completion promises to control when the check agent can stop.
+
+Mechanism:
+- Intercepts when check subagent tries to stop (SubagentStop event)
+- If verify commands configured in worktree.yaml, runs them to verify
+- Otherwise, reads check.jsonl to get dynamic completion markers ({reason}_FINISH)
+- Blocks stopping until verification passes or all markers found
+- Has max iterations as safety limit
+
+State file: .trellis/.ralph-state.json
+- Tracks current iteration count per session
+- Resets when task changes
+"""
+
+# IMPORTANT: Suppress all warnings FIRST
+import warnings
+warnings.filterwarnings("ignore")
+
+import json
+import os
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+# 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]
+
+# =============================================================================
+# Configuration
+# =============================================================================
+
+MAX_ITERATIONS = 5  # Safety limit to prevent infinite loops
+STATE_TIMEOUT_MINUTES = 30  # Reset state if older than this
+STATE_FILE = ".trellis/.ralph-state.json"
+WORKTREE_YAML = ".trellis/worktree.yaml"
+DIR_WORKFLOW = ".trellis"
+FILE_CURRENT_TASK = ".current-task"
+
+# Only control loop for check agent
+TARGET_AGENT = "check"
+
+
+def find_repo_root(start_path: str) -> str | None:
+    """Find git repo root from start_path upwards"""
+    current = Path(start_path).resolve()
+    while current != current.parent:
+        if (current / ".git").exists():
+            return str(current)
+        current = current.parent
+    return None
+
+
+def get_current_task(repo_root: str) -> str | None:
+    """Read current task directory path"""
+    current_task_file = os.path.join(repo_root, DIR_WORKFLOW, FILE_CURRENT_TASK)
+    if not os.path.exists(current_task_file):
+        return None
+
+    try:
+        with open(current_task_file, "r", encoding="utf-8") as f:
+            content = f.read().strip()
+            return content if content else None
+    except Exception:
+        return None
+
+
+def get_verify_commands(repo_root: str) -> list[str]:
+    """
+    Read verify commands from worktree.yaml.
+
+    Returns list of commands to run, or empty list if not configured.
+    Uses simple YAML parsing without external dependencies.
+    """
+    yaml_path = os.path.join(repo_root, WORKTREE_YAML)
+    if not os.path.exists(yaml_path):
+        return []
+
+    try:
+        with open(yaml_path, "r", encoding="utf-8") as f:
+            content = f.read()
+
+        # Simple YAML parsing for verify section
+        # Look for "verify:" followed by list items
+        lines = content.split("\n")
+        in_verify_section = False
+        commands = []
+
+        for line in lines:
+            stripped = line.strip()
+
+            # Check for section start
+            if stripped.startswith("verify:"):
+                in_verify_section = True
+                continue
+
+            # Check for new section (not indented, ends with :)
+            if (
+                not line.startswith(" ")
+                and not line.startswith("\t")
+                and stripped.endswith(":")
+                and stripped != ""
+            ):
+                in_verify_section = False
+                continue
+
+            # If in verify section, look for list items
+            if in_verify_section:
+                # Skip comments and empty lines
+                if stripped.startswith("#") or stripped == "":
+                    continue
+                # Parse list item (- command)
+                if stripped.startswith("- "):
+                    cmd = stripped[2:].strip()
+                    if cmd:
+                        commands.append(cmd)
+
+        return commands
+    except Exception:
+        return []
+
+
+def run_verify_commands(repo_root: str, commands: list[str]) -> tuple[bool, str]:
+    """
+    Run verify commands and return (success, message).
+
+    All commands must pass for success.
+    """
+    for cmd in commands:
+        try:
+            result = subprocess.run(
+                cmd,
+                shell=True,
+                cwd=repo_root,
+                capture_output=True,
+                timeout=120,  # 2 minute timeout per command
+            )
+            if result.returncode != 0:
+                stderr = result.stderr.decode("utf-8", errors="replace")
+                stdout = result.stdout.decode("utf-8", errors="replace")
+                error_output = stderr or stdout
+                # Truncate long output
+                if len(error_output) > 500:
+                    error_output = error_output[:500] + "..."
+                return False, f"Command failed: {cmd}\n{error_output}"
+        except subprocess.TimeoutExpired:
+            return False, f"Command timed out: {cmd}"
+        except Exception as e:
+            return False, f"Command error: {cmd} - {str(e)}"
+
+    return True, "All verify commands passed"
+
+
+def get_completion_markers(repo_root: str, task_dir: str) -> list[str]:
+    """
+    Read check.jsonl and generate completion markers from reasons.
+
+    Each entry's "reason" field becomes {REASON}_FINISH marker.
+    Example: {"file": "...", "reason": "TypeCheck"} -> "TYPECHECK_FINISH"
+    """
+    check_jsonl_path = os.path.join(repo_root, task_dir, "check.jsonl")
+    markers = []
+
+    if not os.path.exists(check_jsonl_path):
+        # Fallback: if no check.jsonl, use default marker
+        return ["ALL_CHECKS_FINISH"]
+
+    try:
+        with open(check_jsonl_path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    item = json.loads(line)
+                    reason = item.get("reason", "")
+                    if reason:
+                        # Convert to uppercase and add _FINISH suffix
+                        marker = f"{reason.upper().replace(' ', '_')}_FINISH"
+                        if marker not in markers:
+                            markers.append(marker)
+                except json.JSONDecodeError:
+                    continue
+    except Exception:
+        pass
+
+    # If no markers found, use default
+    if not markers:
+        markers = ["ALL_CHECKS_FINISH"]
+
+    return markers
+
+
+def load_state(repo_root: str) -> dict:
+    """Load Ralph Loop state from file"""
+    state_path = os.path.join(repo_root, STATE_FILE)
+    if not os.path.exists(state_path):
+        return {"task": None, "iteration": 0, "started_at": None}
+
+    try:
+        with open(state_path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception:
+        return {"task": None, "iteration": 0, "started_at": None}
+
+
+def save_state(repo_root: str, state: dict) -> None:
+    """Save Ralph Loop state to file"""
+    state_path = os.path.join(repo_root, STATE_FILE)
+    try:
+        # Ensure directory exists
+        os.makedirs(os.path.dirname(state_path), exist_ok=True)
+        with open(state_path, "w", encoding="utf-8") as f:
+            json.dump(state, f, indent=2, ensure_ascii=False)
+    except Exception:
+        pass
+
+
+def check_completion(agent_output: str, markers: list[str]) -> tuple[bool, list[str]]:
+    """
+    Check if all completion markers are present in agent output.
+
+    Returns:
+        (all_complete, missing_markers)
+    """
+    missing = []
+    for marker in markers:
+        if marker not in agent_output:
+            missing.append(marker)
+
+    return len(missing) == 0, missing
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        # If can't parse input, allow stop
+        sys.exit(0)
+
+    # Get event info
+    hook_event = input_data.get("hook_event_name", "")
+
+    # Only handle SubagentStop event
+    if hook_event != "SubagentStop":
+        sys.exit(0)
+
+    # Get subagent info
+    subagent_type = input_data.get("subagent_type", "")
+    agent_output = input_data.get("agent_output", "")
+    original_prompt = input_data.get("prompt", "")
+    cwd = input_data.get("cwd", os.getcwd())
+
+    # Only control check agent
+    if subagent_type != TARGET_AGENT:
+        sys.exit(0)
+
+    # Skip Ralph Loop for finish phase (already verified in check phase)
+    if "[finish]" in original_prompt.lower():
+        sys.exit(0)
+
+    # Find repo root
+    repo_root = find_repo_root(cwd)
+    if not repo_root:
+        sys.exit(0)
+
+    # Get current task
+    task_dir = get_current_task(repo_root)
+    if not task_dir:
+        sys.exit(0)
+
+    # Load state
+    state = load_state(repo_root)
+
+    # Reset state if task changed or state is too old
+    should_reset = False
+    if state.get("task") != task_dir:
+        should_reset = True
+    elif state.get("started_at"):
+        try:
+            started = datetime.fromisoformat(state["started_at"])
+            if (datetime.now() - started).total_seconds() > STATE_TIMEOUT_MINUTES * 60:
+                should_reset = True
+        except (ValueError, TypeError):
+            should_reset = True
+
+    if should_reset:
+        state = {
+            "task": task_dir,
+            "iteration": 0,
+            "started_at": datetime.now().isoformat(),
+        }
+
+    # Increment iteration
+    state["iteration"] = state.get("iteration", 0) + 1
+    current_iteration = state["iteration"]
+
+    # Save state
+    save_state(repo_root, state)
+
+    # Safety check: max iterations
+    if current_iteration >= MAX_ITERATIONS:
+        # Allow stop, reset state for next run
+        state["iteration"] = 0
+        save_state(repo_root, state)
+        output = {
+            "decision": "allow",
+            "reason": f"Max iterations ({MAX_ITERATIONS}) reached. Stopping to prevent infinite loop.",
+        }
+        print(json.dumps(output, ensure_ascii=False))
+        sys.exit(0)
+
+    # Check if verify commands are configured
+    verify_commands = get_verify_commands(repo_root)
+
+    if verify_commands:
+        # Use programmatic verification
+        passed, message = run_verify_commands(repo_root, verify_commands)
+
+        if passed:
+            # All verify commands passed, allow stop
+            state["iteration"] = 0
+            save_state(repo_root, state)
+            output = {
+                "decision": "allow",
+                "reason": "All verify commands passed. Check phase complete.",
+            }
+            print(json.dumps(output, ensure_ascii=False))
+            sys.exit(0)
+        else:
+            # Verification failed, block stop
+            output = {
+                "decision": "block",
+                "reason": f"Iteration {current_iteration}/{MAX_ITERATIONS}. Verification failed:\n{message}\n\nPlease fix the issues and try again.",
+            }
+            print(json.dumps(output, ensure_ascii=False))
+            sys.exit(0)
+    else:
+        # No verify commands, fall back to completion markers
+        markers = get_completion_markers(repo_root, task_dir)
+        all_complete, missing = check_completion(agent_output, markers)
+
+        if all_complete:
+            # All checks complete, allow stop
+            state["iteration"] = 0
+            save_state(repo_root, state)
+            output = {
+                "decision": "allow",
+                "reason": "All completion markers found. Check phase complete.",
+            }
+            print(json.dumps(output, ensure_ascii=False))
+            sys.exit(0)
+        else:
+            # Missing markers, block stop and continue
+            output = {
+                "decision": "block",
+                "reason": f"""Iteration {current_iteration}/{MAX_ITERATIONS}. Missing completion markers: {", ".join(missing)}.
+
+IMPORTANT: You must ACTUALLY run the checks, not just output the markers.
+- Did you run lint? What was the output?
+- Did you run typecheck? What was the output?
+- Did they actually pass with zero errors?
+
+Only output a marker (e.g., LINT_FINISH) AFTER:
+1. You have executed the corresponding command
+2. The command completed with zero errors
+3. You have shown the command output in your response
+
+Do NOT output markers just to escape the loop. The loop exists to ensure quality.""",
+            }
+            print(json.dumps(output, ensure_ascii=False))
+            sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.claude/hooks/session-start.py b/.claude/hooks/session-start.py
new file mode 100644
index 000000000..eeee0c1aa
--- /dev/null
+++ b/.claude/hooks/session-start.py
@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Session Start Hook - Inject structured context
+"""
+
+# IMPORTANT: Suppress all warnings FIRST
+import warnings
+warnings.filterwarnings("ignore")
+
+import json
+import os
+import subprocess
+import sys
+from io import StringIO
+from pathlib import Path
+
+# 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]
+
+
+def should_skip_injection() -> bool:
+    return (
+        os.environ.get("CLAUDE_NON_INTERACTIVE") == "1"
+        or os.environ.get("OPENCODE_NON_INTERACTIVE") == "1"
+    )
+
+
+def read_file(path: Path, fallback: str = "") -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except (FileNotFoundError, PermissionError):
+        return fallback
+
+
+def run_script(script_path: Path) -> str:
+    try:
+        if script_path.suffix == ".py":
+            # Add PYTHONIOENCODING to force UTF-8 in subprocess
+            env = os.environ.copy()
+            env["PYTHONIOENCODING"] = "utf-8"
+            cmd = [sys.executable, "-W", "ignore", str(script_path)]
+        else:
+            env = os.environ
+            cmd = [str(script_path)]
+
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=5,
+            cwd=script_path.parent.parent.parent,
+            env=env,
+        )
+        return result.stdout if result.returncode == 0 else "No context available"
+    except (subprocess.TimeoutExpired, FileNotFoundError, PermissionError):
+        return "No context available"
+
+
+def _get_task_status(trellis_dir: Path) -> str:
+    """Check current task status and return structured status string."""
+    current_task_file = trellis_dir / ".current-task"
+    if not current_task_file.is_file():
+        return "Status: NO ACTIVE TASK\nNext: Describe what you want to work on"
+
+    task_ref = current_task_file.read_text(encoding="utf-8").strip()
+    if not task_ref:
+        return "Status: NO ACTIVE TASK\nNext: Describe what you want to work on"
+
+    # Resolve task directory
+    if Path(task_ref).is_absolute():
+        task_dir = Path(task_ref)
+    elif task_ref.startswith(".trellis/"):
+        task_dir = trellis_dir.parent / task_ref
+    else:
+        task_dir = trellis_dir / "tasks" / task_ref
+    if not task_dir.is_dir():
+        return f"Status: STALE POINTER\nTask: {task_ref}\nNext: Task directory not found. Run: python3 ./.trellis/scripts/task.py finish"
+
+    # Read task.json
+    task_json_path = task_dir / "task.json"
+    task_data = {}
+    if task_json_path.is_file():
+        try:
+            task_data = json.loads(task_json_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, PermissionError):
+            pass
+
+    task_title = task_data.get("title", task_ref)
+    task_status = task_data.get("status", "unknown")
+
+    if task_status == "completed":
+        return f"Status: COMPLETED\nTask: {task_title}\nNext: Archive with `python3 ./.trellis/scripts/task.py archive {task_dir.name}` or start a new task"
+
+    # Check if context is configured (jsonl files exist and non-empty)
+    has_context = False
+    for jsonl_name in ("implement.jsonl", "check.jsonl", "spec.jsonl"):
+        jsonl_path = task_dir / jsonl_name
+        if jsonl_path.is_file() and jsonl_path.stat().st_size > 0:
+            has_context = True
+            break
+
+    has_prd = (task_dir / "prd.md").is_file()
+
+    if not has_prd:
+        return f"Status: NOT READY\nTask: {task_title}\nMissing: prd.md not created\nNext: Write PRD, then research → init-context → start"
+
+    if not has_context:
+        return f"Status: NOT READY\nTask: {task_title}\nMissing: Context not configured (no jsonl files)\nNext: Complete Phase 2 (research → init-context → start) before implementing"
+
+    return f"Status: READY\nTask: {task_title}\nNext: Continue with implement or check"
+
+
+def main():
+    if should_skip_injection():
+        sys.exit(0)
+
+    project_dir = Path(os.environ.get("CLAUDE_PROJECT_DIR", ".")).resolve()
+    trellis_dir = project_dir / ".trellis"
+    claude_dir = project_dir / ".claude"
+
+    output = StringIO()
+
+    output.write("""<session-context>
+You are starting a new session in a Trellis-managed project.
+Read and follow all instructions below carefully.
+</session-context>
+
+""")
+
+    output.write("<current-state>\n")
+    context_script = trellis_dir / "scripts" / "get_context.py"
+    output.write(run_script(context_script))
+    output.write("\n</current-state>\n\n")
+
+    output.write("<workflow>\n")
+    workflow_content = read_file(trellis_dir / "workflow.md", "No workflow.md found")
+    output.write(workflow_content)
+    output.write("\n</workflow>\n\n")
+
+    output.write("<guidelines>\n")
+    output.write("**Note**: The guidelines below are index files — they list available guideline documents and their locations.\n")
+    output.write("During actual development, you MUST read the specific guideline files listed in each index's Pre-Development Checklist.\n\n")
+
+    spec_dir = trellis_dir / "spec"
+    if spec_dir.is_dir():
+        for sub in sorted(spec_dir.iterdir()):
+            if not sub.is_dir() or sub.name.startswith("."):
+                continue
+            index_file = sub / "index.md"
+            if index_file.is_file():
+                output.write(f"## {sub.name}\n")
+                output.write(read_file(index_file))
+                output.write("\n\n")
+            else:
+                # Check for nested package dirs (monorepo: spec/<pkg>/<layer>/index.md)
+                for nested in sorted(sub.iterdir()):
+                    if not nested.is_dir():
+                        continue
+                    nested_index = nested / "index.md"
+                    if nested_index.is_file():
+                        output.write(f"## {sub.name}/{nested.name}\n")
+                        output.write(read_file(nested_index))
+                        output.write("\n\n")
+
+    output.write("</guidelines>\n\n")
+
+    output.write("<instructions>\n")
+    start_md = read_file(
+        claude_dir / "commands" / "trellis" / "start.md", "No start.md found"
+    )
+    output.write(start_md)
+    output.write("\n</instructions>\n\n")
+
+    # R2: Check task status and inject structured tag
+    task_status = _get_task_status(trellis_dir)
+    output.write(f"<task-status>\n{task_status}\n</task-status>\n\n")
+
+    output.write("""<ready>
+Context loaded. Steps 1-3 (workflow, context, guidelines) are already injected above — do NOT re-read them.
+Start from Step 4. Wait for user's first message, then follow <instructions> to handle their request.
+If there is an active task, ask whether to continue it.
+</ready>""")
+
+    result = {
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": output.getvalue(),
+        }
+    }
+
+    # Output JSON - stdout is already configured for UTF-8
+    print(json.dumps(result, ensure_ascii=False), flush=True)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 000000000..d6ed27084
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,71 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .claude/hooks/session-start.py",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .claude/hooks/session-start.py",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .claude/hooks/session-start.py",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .claude/hooks/inject-subagent-context.py",
+            "timeout": 30
+          }
+        ]
+      },
+      {
+        "matcher": "Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .claude/hooks/inject-subagent-context.py",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": "check",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .claude/hooks/ralph-loop.py",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  },
+  "enabledPlugins": {}
+}
diff --git a/.codex b/.codex
new file mode 100644
index 000000000..e69de29bb
diff --git a/.cursor/commands/trellis-before-backend-dev.md b/.cursor/commands/trellis-before-backend-dev.md
new file mode 100644
index 000000000..7dfcd365e
--- /dev/null
+++ b/.cursor/commands/trellis-before-backend-dev.md
@@ -0,0 +1,13 @@
+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/.cursor/commands/trellis-before-frontend-dev.md b/.cursor/commands/trellis-before-frontend-dev.md
new file mode 100644
index 000000000..9687edc1c
--- /dev/null
+++ b/.cursor/commands/trellis-before-frontend-dev.md
@@ -0,0 +1,13 @@
+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/.cursor/commands/trellis-brainstorm.md b/.cursor/commands/trellis-brainstorm.md
new file mode 100644
index 000000000..a09db1a73
--- /dev/null
+++ b/.cursor/commands/trellis-brainstorm.md
@@ -0,0 +1,487 @@
+# 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 `/trellis-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 |
+|---------|-------------|
+| `/trellis-start` | Entry point that triggers brainstorm |
+| `/trellis-finish-work` | After implementation is complete |
+| `/trellis-update-spec` | If new patterns emerge during work |
diff --git a/.cursor/commands/trellis-break-loop.md b/.cursor/commands/trellis-break-loop.md
new file mode 100644
index 000000000..e09824f14
--- /dev/null
+++ b/.cursor/commands/trellis-break-loop.md
@@ -0,0 +1,107 @@
+# Break the Loop - Deep Bug Analysis
+
+When debug is complete, use this command 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 commands 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.
diff --git a/.cursor/commands/trellis-check-backend.md b/.cursor/commands/trellis-check-backend.md
new file mode 100644
index 000000000..886f5c9f8
--- /dev/null
+++ b/.cursor/commands/trellis-check-backend.md
@@ -0,0 +1,13 @@
+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/.cursor/commands/trellis-check-cross-layer.md b/.cursor/commands/trellis-check-cross-layer.md
new file mode 100644
index 000000000..bc61e28e6
--- /dev/null
+++ b/.cursor/commands/trellis-check-cross-layer.md
@@ -0,0 +1,153 @@
+# 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 |
+| **`/trellis-check-cross-layer`** (this) | 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/.cursor/commands/trellis-check-frontend.md b/.cursor/commands/trellis-check-frontend.md
new file mode 100644
index 000000000..3771ae3ab
--- /dev/null
+++ b/.cursor/commands/trellis-check-frontend.md
@@ -0,0 +1,13 @@
+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/.cursor/commands/trellis-create-command.md b/.cursor/commands/trellis-create-command.md
new file mode 100644
index 000000000..d26261391
--- /dev/null
+++ b/.cursor/commands/trellis-create-command.md
@@ -0,0 +1,154 @@
+# Create New Slash Command
+
+Create a new slash command in both `.cursor/commands/` (with `trellis-` prefix) and `.claude/commands/trellis/` directories based on user requirements.
+
+## Usage
+
+```
+/trellis-create-command <command-name> <description>
+```
+
+**Example**:
+```
+/trellis-create-command review-pr Check PR code changes against project guidelines
+```
+
+## Execution Steps
+
+### 1. Parse Input
+
+Extract from user input:
+- **Command name**: Use kebab-case (e.g., `review-pr`)
+- **Description**: What the command should accomplish
+
+### 2. Analyze Requirements
+
+Determine command 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, code templates
+
+### 3. Generate Command Content
+
+Based on command type, generate appropriate content:
+
+**Simple command** (1-3 lines):
+```markdown
+Concise instruction describing what to do
+```
+
+**Complex command** (with steps):
+```markdown
+# Command Title
+
+Command description
+
+## Steps
+
+### 1. First Step
+Specific action
+
+### 2. Second Step
+Specific action
+
+## Output Format (if needed)
+
+Template
+```
+
+### 4. Create Files
+
+Create in both directories:
+- `.cursor/commands/trellis-<command-name>.md`
+- `.claude/commands/trellis/<command-name>.md`
+
+### 5. Confirm Creation
+
+Output result:
+```
+[OK] Created Slash Command: /<command-name>
+
+File paths:
+- .cursor/commands/trellis-<command-name>.md
+- .claude/commands/trellis/<command-name>.md
+
+Usage:
+/trellis-<command-name>
+
+Description:
+<description>
+```
+
+## Command Content Guidelines
+
+### [OK] Good command 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 command should not exceed 100 lines
+3. **Duplicate functionality**: Check if similar command exists first
+
+## Naming Conventions
+
+| Command 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` |
+
+## Example
+
+### Input
+```
+/trellis-create-command review-pr Check PR code changes against project guidelines
+```
+
+### Generated Command Content
+```markdown
+# PR Code Review
+
+Check current PR code changes against project guidelines.
+
+## Steps
+
+### 1. Get Changed Files
+```bash
+git diff main...HEAD --name-only
+```
+
+### 2. Categorized Review
+
+**Frontend files** (`apps/web/`):
+- Reference `.trellis/spec/frontend/index.md`
+
+**Backend files** (`packages/api/`):
+- Reference `.trellis/spec/backend/index.md`
+
+### 3. Output Review Report
+
+Format:
+
+## PR Review Report
+
+### Changed Files
+- [file list]
+
+### Check Results
+- [OK] Passed items
+- [X] Issues found
+
+### Suggestions
+- [improvement suggestions]
+```
diff --git a/.cursor/commands/trellis-finish-work.md b/.cursor/commands/trellis-finish-work.md
new file mode 100644
index 000000000..d8df83bee
--- /dev/null
+++ b/.cursor/commands/trellis-finish-work.md
@@ -0,0 +1,143 @@
+# 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 `/trellis-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 -> /trellis-finish-work -> git commit -> /trellis-record-session
+                          |                              |
+                   Ensure completeness              Record progress
+                   
+Debug Flow:
+  Hit bug -> Fix -> /trellis-break-loop -> Knowledge capture
+                       |
+                  Deep analysis
+```
+
+- `/trellis-finish-work` - Check work completeness (this command)
+- `/trellis-record-session` - Record session and commits
+- `/trellis-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/.cursor/commands/trellis-integrate-skill.md b/.cursor/commands/trellis-integrate-skill.md
new file mode 100644
index 000000000..d3936ad04
--- /dev/null
+++ b/.cursor/commands/trellis-integrate-skill.md
@@ -0,0 +1,219 @@
+# Integrate Claude Skill into Project Guidelines
+
+Adapt and integrate a Claude global skill into your project's development guidelines (not directly into project code).
+
+## Usage
+
+```
+/trellis-integrate-skill <skill-name>
+```
+
+**Examples**:
+```
+/trellis-integrate-skill frontend-design
+/trellis-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
+
+```bash
+openskills read <skill-name>
+```
+
+If the skill doesn't exist, prompt user to check available skills:
+```bash
+# Available skills are listed in AGENTS.md under <available_skills>
+```
+
+### 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 Command
+
+If this skill is frequently used, create a shortcut command:
+
+```bash
+/trellis-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/.cursor/commands/trellis-onboard.md b/.cursor/commands/trellis-onboard.md
new file mode 100644
index 000000000..186e0d26f
--- /dev/null
+++ b/.cursor/commands/trellis-onboard.md
@@ -0,0 +1,358 @@
+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 command 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, COMMAND DEEP DIVE)
+- Explain WHY this workflow exists
+- Explain WHAT each command 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 command 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 `/trellis-start` command 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` commands 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-*` commands re-verify code against guidelines AFTER writing, catching drift that occurred during development. The `/trellis-finish-work` command 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
+
+---
+
+## COMMAND DEEP DIVE
+
+### /trellis-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 /trellis-start: AI is blind. It might work on wrong branch, conflict with others' work, or redo already-completed work.
+- With /trellis-start: AI knows project context, can continue where previous session left off, avoids conflicts.
+
+---
+
+### /trellis-before-frontend-dev and /trellis-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.
+
+---
+
+### /trellis-check-frontend and /trellis-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.
+
+---
+
+### /trellis-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
+
+---
+
+### /trellis-finish-work - Holistic Pre-Commit Review
+
+**WHY IT EXISTS**:
+The `/check-*` commands 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
+
+---
+
+### /trellis-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 `/trellis-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] /trellis-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] /trellis-before-frontend-dev** - Inject project-specific frontend knowledge
+**[4/8] Investigate and fix the bug** - Actual development work
+**[5/8] /trellis-check-frontend** - Re-verify code against guidelines
+**[6/8] /trellis-finish-work** - Holistic cross-layer review
+**[7/8] Human tests and commits** - Human validates before code enters repo
+**[8/8] /trellis-record-session** - Persist memory for future sessions
+
+### Example 2: Planning Session (No Code)
+
+**[1/4] /trellis-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] /trellis-record-session (with --summary)** - Planning decisions must be recorded
+
+### Example 3: Code Review Fixes
+
+**[1/6] /trellis-start** - Resume context from previous session
+**[2/6] /trellis-before-backend-dev** - Re-inject guidelines before fixes
+**[3/6] Fix each CR issue** - Address feedback with guidelines in context
+**[4/6] /trellis-check-backend** - Verify fixes didn't introduce new issues
+**[5/6] /trellis-finish-work** - Document lessons from CR
+**[6/6] Human commits, then /trellis-record-session** - Preserve CR lessons
+
+### Example 4: Large Refactoring
+
+**[1/5] /trellis-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] /trellis-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] /trellis-start** - See if this bug was investigated before
+**[2/6] /trellis-before-backend-dev** - Guidelines might document known gotchas
+**[3/6] Investigation** - Actual debugging work
+**[4/6] /trellis-check-backend** - Verify debug changes don't break other things
+**[5/6] /trellis-finish-work** - Debug findings might need documentation
+**[6/6] Human commits, then /trellis-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 commands inject project knowledge.
+3. **Check after code** - /check-* commands catch context drift.
+4. **Record everything** - /trellis-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` commands 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` commands 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 `/trellis-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/.cursor/commands/trellis-record-session.md b/.cursor/commands/trellis-record-session.md
new file mode 100644
index 000000000..4a7e6ff07
--- /dev/null
+++ b/.cursor/commands/trellis-record-session.md
@@ -0,0 +1,61 @@
+[!] **Prerequisite**: This command 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/.cursor/commands/trellis-start.md b/.cursor/commands/trellis-start.md
new file mode 100644
index 000000000..0cc6fb30c
--- /dev/null
+++ b/.cursor/commands/trellis-start.md
@@ -0,0 +1,382 @@
+# Start Session
+
+Initialize your AI development session and begin working on tasks.
+
+---
+
+## Operation Types
+
+Operations in this document are categorized as:
+
+| Marker | Meaning | Executor |
+|--------|---------|----------|
+| `[AI]` | Bash scripts or file reads executed by AI | You (AI) |
+| `[USER]` | Slash commands executed by user | User |
+
+---
+
+## Initialization
+
+### Step 1: Understand Trellis Workflow `[AI]`
+
+First, read the workflow guide to understand the development process:
+
+```bash
+cat .trellis/workflow.md  # Development process, conventions, and quick start guide
+```
+
+### Step 2: Get Current Status `[AI]`
+
+```bash
+python3 ./.trellis/scripts/get_context.py
+```
+
+This returns:
+- Developer identity
+- Git status (branch, uncommitted changes)
+- Recent commits
+- Active tasks
+- Journal file status
+
+### Step 3: Read Project Code-Spec Index `[AI]`
+
+Based on the upcoming task, read appropriate code-spec docs:
+
+**For Frontend Work**:
+```bash
+cat .trellis/spec/frontend/index.md
+```
+
+**For Backend Work**:
+```bash
+cat .trellis/spec/backend/index.md
+```
+
+**For Cross-Layer Features**:
+```bash
+cat .trellis/spec/guides/index.md
+cat .trellis/spec/guides/cross-layer-thinking-guide.md
+```
+
+> **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: Check Active Tasks `[AI]`
+
+```bash
+python3 ./.trellis/scripts/task.py list
+```
+
+If continuing previous work, review the task file.
+
+### Step 5: Report Ready Status and Ask for Tasks
+
+Output a summary:
+
+```markdown
+## Session Initialized
+
+| Item | Status |
+|------|--------|
+| Developer | {name} |
+| Branch | {branch} |
+| Uncommitted | {count} file(s) |
+| Journal | {file} ({lines}/2000 lines) |
+| Active Tasks | {count} |
+
+Ready for your task. 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 `/trellis:brainstorm` 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 `/trellis-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. Use `/trellis-brainstorm`.
+
+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 `/trellis-record-session` to record this session
+
+---
+
+## User Available Commands `[USER]`
+
+The following slash commands are for users (not AI):
+
+| Command | Description |
+|---------|-------------|
+| `/trellis-start` | Start development session (this command) |
+| `/trellis-brainstorm` | Clarify vague requirements before implementation |
+| `/trellis-before-frontend-dev` | Read frontend guidelines |
+| `/trellis-before-backend-dev` | Read backend guidelines |
+| `/trellis-check-frontend` | Check frontend code |
+| `/trellis-check-backend` | Check backend code |
+| `/trellis-check-cross-layer` | Cross-layer verification |
+| `/trellis-finish-work` | Pre-commit checklist |
+| `/trellis-record-session` | Record session progress |
+
+---
+
+## AI Executed Scripts `[AI]`
+
+| Script | Purpose |
+|--------|---------|
+| `python3 ./.trellis/scripts/task.py create "<title>" [--slug <name>]` | Create task directory |
+| `python3 ./.trellis/scripts/task.py list` | List active tasks |
+| `python3 ./.trellis/scripts/task.py archive <name>` | Archive task |
+| `python3 ./.trellis/scripts/get_context.py` | Get session context |
+
+---
+
+## Platform Detection
+
+Trellis auto-detects your platform based on config directories. For Cursor users, ensure detection works correctly:
+
+| Condition | Detected Platform |
+|-----------|-------------------|
+| Only `.cursor/` exists | `cursor` ✅ |
+| Both `.cursor/` and `.claude/` exist | `claude` (default) |
+
+If auto-detection fails, set manually:
+
+```bash
+export TRELLIS_PLATFORM=cursor
+```
+
+Or prefix commands:
+
+```bash
+TRELLIS_PLATFORM=cursor python3 ./.trellis/scripts/task.py list
+```
+
+---
+
+## Session End Reminder
+
+**IMPORTANT**: When a task or session is completed, remind the user:
+
+> Before ending this session, please run `/trellis-record-session` to record what we accomplished.
diff --git a/.cursor/commands/trellis-update-spec.md b/.cursor/commands/trellis-update-spec.md
new file mode 100644
index 000000000..84736af37
--- /dev/null
+++ b/.cursor/commands/trellis-update-spec.md
@@ -0,0 +1,354 @@
+# Update Code-Spec - Capture Executable Contracts
+
+When you learn something valuable (from debugging, implementing, or discussion), use this command 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.
+
+### Mandatory Triggers
+
+Apply code-spec depth when the change includes any of:
+- New/changed command or API signature
+- Cross-layer request/response contract change
+- Database schema/migration change
+- Infra integration (storage, queue, cache, secrets, env wiring)
+
+### Mandatory Output (7 Sections)
+
+For triggered tasks, include all sections below:
+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
+- Backend command/API/DB signature(s)
+
+### 3. Contracts
+- Request fields (name, type, constraints)
+- Response fields (name, type, constraints)
+- Environment keys (required/optional)
+
+### 4. Validation & Error Matrix
+- <condition> -> <error>
+
+### 5. Good/Base/Bad Cases
+- Good: ...
+- Base: ...
+- Bad: ...
+
+### 6. Tests Required
+- Unit/Integration/E2E with assertion points
+
+### 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 → /trellis-update-spec → Knowledge captured
+       ↑                                  ↓
+  /trellis-break-loop ←──────────────────── Future sessions benefit
+  (deep bug analysis)
+```
+
+- `/trellis-break-loop` - Analyzes bugs deeply, often reveals spec updates needed
+- `/trellis-update-spec` - Actually makes the updates (this command)
+- `/trellis-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
deleted file mode 100644
index 7cb430627..000000000
--- a/.env.example
+++ /dev/null
@@ -1,61 +0,0 @@
-# API Key (required)
-# Get yours at: https://console.anthropic.com/
-ANTHROPIC_API_KEY=sk-ant-xxx
-
-# Model ID (required)
-MODEL_ID=claude-sonnet-4-6
-
-# Base URL (optional, for Anthropic-compatible providers)
-# ANTHROPIC_BASE_URL=https://api.anthropic.com
-
-# =============================================================================
-#  Anthropic-compatible providers
-#
-#  Provider         MODEL_ID              SWE-bench  TB2     Base URL
-#  ---------------  --------------------  ---------  ------  -------------------
-#  Anthropic        claude-sonnet-4-6     79.6%      59.1%   (default)
-#  MiniMax          MiniMax-M2.5          80.2%        -     see below
-#  GLM (Zhipu)      glm-5                77.8%        -     see below
-#  Kimi (Moonshot)  kimi-k2.5            76.8%        -     see below
-#  DeepSeek         deepseek-chat        73.0%        -     see below
-#                   (V3.2)
-#
-#  SWE-bench = SWE-bench Verified (Feb 2026)
-#  TB2       = Terminal-Bench 2.0 (Feb 2026)
-# =============================================================================
-
-# ---- International ----
-
-# MiniMax          https://www.minimax.io
-# ANTHROPIC_BASE_URL=https://api.minimax.io/anthropic
-# MODEL_ID=MiniMax-M2.5
-
-# GLM (Zhipu)      https://z.ai
-# ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic
-# MODEL_ID=glm-5
-
-# Kimi (Moonshot)  https://platform.moonshot.ai
-# ANTHROPIC_BASE_URL=https://api.moonshot.ai/anthropic
-# MODEL_ID=kimi-k2.5
-
-# DeepSeek         https://platform.deepseek.com
-# ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
-# MODEL_ID=deepseek-chat
-
-# ---- China mainland ----
-
-# MiniMax          https://platform.minimax.io
-# ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic
-# MODEL_ID=MiniMax-M2.5
-
-# GLM (Zhipu)      https://open.bigmodel.cn
-# ANTHROPIC_BASE_URL=https://open.bigmodel.cn/api/anthropic
-# MODEL_ID=glm-5
-
-# Kimi (Moonshot)  https://platform.moonshot.cn
-# ANTHROPIC_BASE_URL=https://api.moonshot.cn/anthropic
-# MODEL_ID=kimi-k2.5
-
-# DeepSeek (no regional split, same endpoint globally)
-# ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
-# MODEL_ID=deepseek-chat
diff --git a/.gemini/commands/trellis/before-backend-dev.toml b/.gemini/commands/trellis/before-backend-dev.toml
new file mode 100644
index 000000000..31611135b
--- /dev/null
+++ b/.gemini/commands/trellis/before-backend-dev.toml
@@ -0,0 +1,17 @@
+description = "Read backend development guidelines before starting your task"
+
+prompt = """
+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/.gemini/commands/trellis/before-frontend-dev.toml b/.gemini/commands/trellis/before-frontend-dev.toml
new file mode 100644
index 000000000..04ded9238
--- /dev/null
+++ b/.gemini/commands/trellis/before-frontend-dev.toml
@@ -0,0 +1,17 @@
+description = "Read frontend development guidelines before starting your task"
+
+prompt = """
+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/.gemini/commands/trellis/brainstorm.toml b/.gemini/commands/trellis/brainstorm.toml
new file mode 100644
index 000000000..7754a3c8a
--- /dev/null
+++ b/.gemini/commands/trellis/brainstorm.toml
@@ -0,0 +1,435 @@
+description = "Guide AI through collaborative requirements discovery before implementation"
+
+prompt = """
+# 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 `/trellis: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.
+```
+
+---
+
+## 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
+
+---
+
+### 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"
+```
+
+---
+
+## Integration with Start Workflow
+
+After brainstorm completes (Step 8 confirmation approved), the flow continues to the Task Workflow's **Phase 2: Prepare for Implementation**.
+
+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 |
+|---------|-------------|
+| `/trellis:start` | Entry point that triggers brainstorm |
+| `/trellis:finish-work` | After implementation is complete |
+| `/trellis:update-spec` | If new patterns emerge during work |
+"""
diff --git a/.gemini/commands/trellis/break-loop.toml b/.gemini/commands/trellis/break-loop.toml
new file mode 100644
index 000000000..4d17e383d
--- /dev/null
+++ b/.gemini/commands/trellis/break-loop.toml
@@ -0,0 +1,129 @@
+description = "Deep bug analysis to break the fix-forget-repeat cycle"
+
+prompt = """
+# Break the Loop - Deep Bug Analysis
+
+When debug is complete, use this command 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 commands 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/.gemini/commands/trellis/check-backend.toml b/.gemini/commands/trellis/check-backend.toml
new file mode 100644
index 000000000..e3ad3d3a2
--- /dev/null
+++ b/.gemini/commands/trellis/check-backend.toml
@@ -0,0 +1,17 @@
+description = "Check if your code follows the backend development guidelines"
+
+prompt = """
+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/.gemini/commands/trellis/check-cross-layer.toml b/.gemini/commands/trellis/check-cross-layer.toml
new file mode 100644
index 000000000..9ed2ce995
--- /dev/null
+++ b/.gemini/commands/trellis/check-cross-layer.toml
@@ -0,0 +1,147 @@
+description = "Cross-layer verification check for multi-dimension changes"
+
+prompt = """
+# 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 **before** writing code.
+
+---
+
+## 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/.gemini/commands/trellis/check-frontend.toml b/.gemini/commands/trellis/check-frontend.toml
new file mode 100644
index 000000000..001ad6583
--- /dev/null
+++ b/.gemini/commands/trellis/check-frontend.toml
@@ -0,0 +1,17 @@
+description = "Check if your code follows the frontend development guidelines"
+
+prompt = """
+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/.gemini/commands/trellis/create-command.toml b/.gemini/commands/trellis/create-command.toml
new file mode 100644
index 000000000..8118c7d87
--- /dev/null
+++ b/.gemini/commands/trellis/create-command.toml
@@ -0,0 +1,119 @@
+description = "Create a new slash command in the Gemini CLI commands directory"
+
+prompt = """
+# Create New Slash Command
+
+Create a new slash command in `.gemini/commands/trellis/` directory based on user requirements.
+
+## Usage
+
+```
+/trellis:create-command <command-name> <description>
+```
+
+**Example**:
+```
+/trellis:create-command review-pr Check PR code changes against project guidelines
+```
+
+## Execution Steps
+
+### 1. Parse Input
+
+Extract from user input:
+- **Command name**: Use kebab-case (e.g., `review-pr`)
+- **Description**: What the command should accomplish
+
+### 2. Analyze Requirements
+
+Determine command 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, code templates
+
+### 3. Generate Command Content
+
+Based on command type, generate appropriate TOML content:
+
+**Simple command**:
+```toml
+description = "Short description"
+
+prompt = \"\"\"
+Concise instruction describing what to do
+\"\"\"
+```
+
+**Complex command** (with steps):
+```toml
+description = "Short description"
+
+prompt = \"\"\"
+# Command Title
+
+Command description
+
+## Steps
+
+### 1. First Step
+Specific action
+
+### 2. Second Step
+Specific action
+
+## Output Format (if needed)
+
+Template
+\"\"\"
+```
+
+### 4. Create File
+
+Create the TOML file:
+- `.gemini/commands/trellis/<command-name>.toml`
+
+### 5. Confirm Creation
+
+Output result:
+```
+[OK] Created Slash Command: /trellis:<command-name>
+
+File path:
+- .gemini/commands/trellis/<command-name>.toml
+
+Usage:
+/trellis:<command-name>
+
+Description:
+<description>
+```
+
+## Command Content Guidelines
+
+### [OK] Good command 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 command should not exceed 100 lines
+3. **Duplicate functionality**: Check if similar command exists first
+
+## Naming Conventions
+
+| Command 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/.gemini/commands/trellis/finish-work.toml b/.gemini/commands/trellis/finish-work.toml
new file mode 100644
index 000000000..ba970dd02
--- /dev/null
+++ b/.gemini/commands/trellis/finish-work.toml
@@ -0,0 +1,133 @@
+description = "Pre-commit checklist to ensure work completeness before submitting"
+
+prompt = """
+# 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. Documentation Sync
+
+**Structure 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 spec doc.
+
+### 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 |
+|-----------|-------------|-------|
+| Structure docs not updated | Others don't know the change | Check .trellis/spec/ |
+| 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 -> /trellis:finish-work -> git commit -> /trellis:record-session
+                          |                              |
+                   Ensure completeness              Record progress
+
+Debug Flow:
+  Hit bug -> Fix -> /trellis:break-loop -> Knowledge capture
+                       |
+                  Deep analysis
+```
+
+- `/trellis:finish-work` - Check work completeness (this command)
+- `/trellis:record-session` - Record session and commits
+- `/trellis: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/.gemini/commands/trellis/integrate-skill.toml b/.gemini/commands/trellis/integrate-skill.toml
new file mode 100644
index 000000000..a9894e20b
--- /dev/null
+++ b/.gemini/commands/trellis/integrate-skill.toml
@@ -0,0 +1,104 @@
+description = "Adapt and integrate an external skill into project development guidelines"
+
+prompt = """
+# Integrate Skill into Project Guidelines
+
+Adapt and integrate an external skill into your project's development guidelines (not directly into project code).
+
+## Usage
+
+```
+/trellis:integrate-skill <skill-name>
+```
+
+**Examples**:
+```
+/trellis:integrate-skill frontend-design
+/trellis: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 definition. If the skill doesn't exist, prompt user to check available skills.
+
+### 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`.
+
+#### 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`.
+
+### 5. Generate Integration Report
+
+Report:
+- Skill description and integration target
+- Tech stack compatibility
+- Integration locations (files modified)
+- Dependencies needed (if any)
+- Completed changes checklist
+
+---
+
+## 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) |
+"""
diff --git a/.gemini/commands/trellis/onboard.toml b/.gemini/commands/trellis/onboard.toml
new file mode 100644
index 000000000..113b12717
--- /dev/null
+++ b/.gemini/commands/trellis/onboard.toml
@@ -0,0 +1,111 @@
+description = "Onboard a new team member to the Trellis AI-assisted workflow system"
+
+prompt = """
+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 command 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, COMMAND DEEP DIVE)
+- Explain WHY this workflow exists
+- Explain WHAT each command 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 command 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.
+
+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. The `.trellis/workspace/` system captures what happened in each session. The `/trellis:start` command reads this history at session start, giving AI "artificial memory."
+
+### Challenge 2: AI Has Generic Knowledge, Not Project-Specific Knowledge
+
+The `.trellis/spec/` directory contains project-specific guidelines. The `/before-*-dev` commands inject this specialized knowledge into AI context before coding starts.
+
+### Challenge 3: AI Context Window Is Limited
+
+The `/check-*` commands re-verify code against guidelines AFTER writing, catching drift that occurred during development. The `/trellis:finish-work` command does a final holistic review.
+
+---
+
+## SYSTEM STRUCTURE
+
+```
+.trellis/
+|-- .developer              # Your identity (gitignored)
+|-- workflow.md             # Complete workflow documentation
+|-- workspace/              # "AI Memory" - session history
+|-- tasks/                  # Task tracking (unified)
+|-- spec/                   # "AI Training Data" - project knowledge
+|   |-- frontend/           # Frontend conventions
+|   |-- backend/            # Backend conventions
+|   +-- guides/             # Thinking patterns
++-- scripts/                # Automation tools
+```
+
+---
+
+## COMMAND DEEP DIVE
+
+### /trellis:start - Restore AI Memory
+### /trellis:before-frontend-dev and /trellis:before-backend-dev - Inject Specialized Knowledge
+### /trellis:check-frontend and /trellis:check-backend - Combat Context Drift
+### /trellis:check-cross-layer - Multi-Dimension Verification
+### /trellis:finish-work - Holistic Pre-Commit Review
+### /trellis:record-session - Persist Memory for Future
+
+---
+
+## REAL-WORLD WORKFLOW EXAMPLES
+
+### Example 1: Bug Fix Session
+### Example 2: Planning Session (No Code)
+### Example 3: Code Review Fixes
+### Example 4: Large Refactoring
+### Example 5: Debug Session
+
+Walk through each example explaining every step.
+
+---
+
+## KEY RULES TO EMPHASIZE
+
+1. **AI NEVER commits** - Human tests and approves. AI prepares, human validates.
+2. **Guidelines before code** - /before-*-dev commands inject project knowledge.
+3. **Check after code** - /check-* commands catch context drift.
+4. **Record everything** - /trellis:record-session persists memory.
+
+---
+
+# PART 3: Customize Your Development Guidelines
+
+Check if `.trellis/spec/` contains empty templates or customized guidelines:
+
+```bash
+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
+```
+
+If empty templates, guide filling them. If already customized, proceed with first task.
+"""
diff --git a/.gemini/commands/trellis/record-session.toml b/.gemini/commands/trellis/record-session.toml
new file mode 100644
index 000000000..d48372a9e
--- /dev/null
+++ b/.gemini/commands/trellis/record-session.toml
@@ -0,0 +1,65 @@
+description = "Record work progress after human has tested and committed code"
+
+prompt = """
+[!] **Prerequisite**: This command 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/.gemini/commands/trellis/start.toml b/.gemini/commands/trellis/start.toml
new file mode 100644
index 000000000..f95644f50
--- /dev/null
+++ b/.gemini/commands/trellis/start.toml
@@ -0,0 +1,349 @@
+description = "Initialize your AI development session and begin working on tasks"
+
+prompt = """
+# Start Session
+
+Initialize your AI development session and begin working on tasks.
+
+---
+
+## Operation Types
+
+| Marker | Meaning | Executor |
+|--------|---------|----------|
+| `[AI]` | Bash scripts or Task calls executed by AI | You (AI) |
+| `[USER]` | Slash commands 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 | Direct Edit |
+| **Simple Task** | Clear goal, 1-2 files, well-defined scope | Quick confirm → Implement |
+| **Complex Task** | Vague goal, multiple files, architectural decisions | **Brainstorm → Task Workflow** |
+
+### Classification Signals
+
+**Trivial/Simple indicators:**
+- User specifies exact file and change
+- "Fix the typo in X"
+- "Add field Y to component Z"
+- Clear acceptance criteria already stated
+
+**Complex indicators:**
+- "I want to add a feature for..."
+- "Can you help me improve..."
+- Mentions multiple areas or systems
+- No clear implementation path
+- User seems unsure about approach
+
+### Decision Rule
+
+> **If in doubt, use Brainstorm + Task Workflow.**
+>
+> Task Workflow ensures specs are injected to agents, resulting in higher quality code.
+> The overhead is minimal, but the benefit is significant.
+
+---
+
+## 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 `/trellis: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 `/trellis: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
+
+> **Subtask Decomposition**: If brainstorm reveals multiple independent work items,
+> consider creating subtasks using `--parent` flag or `add-subtask` command.
+> See `/trellis:brainstorm` Step 8 for details.
+
+---
+
+## Task Workflow (Development Tasks)
+
+**Why this workflow?**
+- Research Agent analyzes what specs are needed
+- Specs are configured in jsonl files
+- Implement Agent receives specs via Hook injection
+- Check Agent verifies against specs
+- 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?
+
+**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 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 `/trellis: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).
+
+---
+
+## Commands Reference
+
+### User Commands `[USER]`
+
+| Command | When to Use |
+|---------|-------------|
+| `/trellis:start` | Begin a session (this command) |
+| `/trellis:finish-work` | Before committing changes |
+| `/trellis: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 |
+
+---
+
+## Key Principle
+
+> **Specs are injected, not remembered.**
+>
+> The Task Workflow ensures agents receive relevant specs automatically.
+> This is more reliable than hoping the AI "remembers" conventions.
+"""
diff --git a/.gemini/commands/trellis/update-spec.toml b/.gemini/commands/trellis/update-spec.toml
new file mode 100644
index 000000000..78be261e2
--- /dev/null
+++ b/.gemini/commands/trellis/update-spec.toml
@@ -0,0 +1,132 @@
+description = "Capture knowledge into spec documents after learning something valuable"
+
+prompt = """
+# Update Spec - Capture Knowledge into Specifications
+
+When you learn something valuable (from debugging, implementing, or discussion), use this command to update the relevant spec documents.
+
+**Timing**: After completing a task, fixing a bug, or discovering a new pattern
+
+---
+
+## When to Update 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 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 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) |
+
+---
+
+## 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: Spec vs Guide - Know the Difference
+
+| Type | Location | Purpose | Content Style |
+|------|----------|---------|---------------|
+| **Spec** | `backend/*.md`, `frontend/*.md` | Tell AI "how to write code" | Detailed rules, code examples, forbidden patterns |
+| **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/`
+
+---
+
+## 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 Spec
+
+Before editing, read the current 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 Code**: Add code snippets for patterns
+4. **Keep it Short**: One concept per section
+
+### Step 5: Update the Index (if needed)
+
+If you added a new section or the spec status changed, update the category's `index.md`.
+
+---
+
+## Quality Checklist
+
+Before finishing your spec update:
+
+- [ ] Is the content specific and actionable?
+- [ ] Did you include a code example?
+- [ ] Did you explain WHY, not just WHAT?
+- [ ] Is it in the right spec file?
+- [ ] Does it duplicate existing content?
+- [ ] Would a new team member understand it?
+
+---
+
+## Relationship to Other Commands
+
+- `/trellis:break-loop` - Analyzes bugs deeply, often reveals spec updates needed
+- `/trellis:update-spec` - Actually makes the updates (this command)
+- `/trellis:finish-work` - Reminds you to check if specs need updates
+
+---
+
+## Core Philosophy
+
+> **Specs are living documents. Every debugging session, every "aha moment" is an opportunity to make the spec better.**
+
+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/.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..bd5637d9d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -195,6 +195,7 @@ cython_debug/
 .task_outputs/
 .tasks/
 .teams/
+.coding-deepgent/
 
 # Ruff stuff:
 .ruff_cache/
@@ -218,6 +219,7 @@ __marimo__/
 web/node_modules/
 web/.next/
 web/out/
+coding-deepgent/frontend/cli/node_modules/
 .vercel
 .env*.local
 test_providers.py
@@ -225,3 +227,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..9ac135265
--- /dev/null
+++ b/.trellis/.template-hashes.json
@@ -0,0 +1,114 @@
+{
+  ".trellis/config.yaml": "fe1fba0961e589c6f49190f5e19d4edb0d5bf894dba8468f06882c6e1c5e2aa1",
+  ".trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md": "74e0a0f37c9654a2ca74c769df86857ee4117aa7599dfbd0280ca5bdffe0a19a",
+  ".trellis/plans/coding-deepgent-h01-h10-target-design.md": "a209bc243469c36ebb6d647752cb6e96d298e049f7bf3f0b2a11a5717c78ba04",
+  ".trellis/plans/coding-deepgent-h01-tool-module-alignment-plan.md": "582fe688d4bf0d714c155e7a8c63da1bdf78d74e57c19873d732c26e96e29835",
+  ".trellis/plans/coding-deepgent-runtime-foundation-20260412T213209Z.md": "227fc301ea61db3df12df212c5f8e490b96b3e51759c9c630663adff0ec80be1",
+  ".trellis/plans/index.md": "a4e15907ac7b828203b6f711d0e63b4192c2299445e5687f227a5747de90f2b7",
+  ".trellis/plans/master-plan-coding-deepgent-reconstructed.md": "f9fa27b2d434d002bdb39dc8ce2dc2a868c981b23cbfd71aa86456a8d3804020",
+  ".trellis/plans/prd-coding-deepgent-runtime-foundation.md": "de68b0f729d12b598d285b47e1c54b58d4f1d59303dad83e0ca0315993499bc9",
+  ".trellis/plans/runtime-foundation-recovery-notes-2026-04-14.md": "542a5a55c34bf407a6d7e818b293e3ec91ee5087d0fd59a7a814077a66dce9fd",
+  ".trellis/plans/test-spec-coding-deepgent-runtime-foundation.md": "ebc08d5c61873d55b7a23e2c982d66a166b0a6289b73b7c5aefc16a90be99e0e",
+  ".trellis/project-handoff.md": "590690ded40c64462db138da57f8a33386fc422eb7620274d7a6ebee85a80d8b",
+  ".trellis/scripts/__init__.py": "1242be5b972094c2e141aecbe81a4efd478f6534e3d5e28306374e6a18fcf46c",
+  ".trellis/scripts/add_session.py": "7c869be8146e6f675bd95e424909ff301ea0a8f8fd82a4f056f6d320e755a406",
+  ".trellis/scripts/check_trellis_links.py": "19ffb0d92fb84b6511cef22e4c25dd3f4f39fcb6a41767758faff839facc391a",
+  ".trellis/scripts/common/__init__.py": "301724230abcce6e9fc99054c12d21c30eea7bc3b330ae6350aa3b6158461273",
+  ".trellis/scripts/common/__pycache__/__init__.cpython-312.pyc": "dbf5657b849be635104ef4debac1d16f1152dd11ed311c8f778d5faf2691f69e",
+  ".trellis/scripts/common/__pycache__/cli_adapter.cpython-312.pyc": "226539677b4b9f4e330f24830ed7865bbbccf0efabcc763235ec5552e425e6f6",
+  ".trellis/scripts/common/__pycache__/config.cpython-312.pyc": "383e46a947790b5afacda1f9176bd87784fa26503c0f33a5bb434ac22e1ab337",
+  ".trellis/scripts/common/__pycache__/developer.cpython-312.pyc": "ef3d6300995a8b1064c6a9697d36435ab4aae683cb9fea20da282b7b5858091d",
+  ".trellis/scripts/common/__pycache__/git_context.cpython-312.pyc": "6bfd78bd013078e57f5962b8ffe1784340f82368e4681410ada910c25ab116f1",
+  ".trellis/scripts/common/__pycache__/paths.cpython-312.pyc": "a14edb8b44363d8dac8a2ee2235ed9ea84bc19c53f89702734728a85e4674c62",
+  ".trellis/scripts/common/__pycache__/task_utils.cpython-312.pyc": "587e104f157a8d32da9e8617654a4388c32a7e75136f42a24f9d8e8ff9deae8a",
+  ".trellis/scripts/common/__pycache__/worktree.cpython-312.pyc": "c206da3d1e57f478a125d44ea91a16450b34bb3a7361c672c634bec33d95c99b",
+  ".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": "dd339a1e53cbc43b0a445affe43c2907c13817a7587ae09b417f87465507c957",
+  ".trellis/worktree.yaml": "c57de79e40d5f748f099625ed4a17d5f0afbf25cac598aced0b3c964e7b7c226",
+  ".claude/agents/check.md": "7c7400e7ea8bf3f3f879bfa028fd5b4d41673e0150d44c52292161ba33612812",
+  ".claude/agents/debug.md": "94be0b1cfbae4c64caee4775ef504f43acfcd4a80427a26d6f680ceaddcbee24",
+  ".claude/agents/dispatch.md": "20e699a87aeb0b046c51d8485e433190916c645e21db9a06f9e468272738347e",
+  ".claude/agents/implement.md": "d537797d3fa510afdeaa365d43ef897a261e71c9144ef6986b8574be8d09055c",
+  ".claude/agents/plan.md": "d796f689b8b8945d1809679d0c74475f419325b30f36ef0c59b7fae73386e90b",
+  ".claude/agents/research.md": "086ae23120151b3591089a4de20fd54e6ae2b89038f5903ee9a52269cd7ded6a",
+  ".claude/commands/trellis/before-backend-dev.md": "7e35444de2a5779ef39944f17f566ea21d2ed7f4994246f4cfe6ebf9a11dd3e3",
+  ".claude/commands/trellis/before-frontend-dev.md": "a6225f9d123dbd4a7aec822652030cae50be3f5b308297015e04d42b23a27b2a",
+  ".claude/commands/trellis/brainstorm.md": "7c7731eda092275a5d87f2569a69584f3c39b544a126a76e727a1e9d250c4a65",
+  ".claude/commands/trellis/break-loop.md": "ba4dd4022dde1e4bbcfc1cc99e6a118e51b9db95bd962d88f1c29d0c9c433112",
+  ".claude/commands/trellis/check-backend.md": "4e81a28d681ea770f780df55a212fd504ce21ee49b44ba16023b74b5c243cef3",
+  ".claude/commands/trellis/check-cross-layer.md": "b9ab24515ead84330d6634f6ad912ca3547db3a36139d62c5688161824097d60",
+  ".claude/commands/trellis/check-frontend.md": "5e8e3b682032ba0dd6bb843dd4826fff0159f78a7084964ccb119c6cf98b3d91",
+  ".claude/commands/trellis/create-command.md": "c2825c7941b4ef4a3f3365c4c807ff138096a39aece3d051776f3c11a4e4857d",
+  ".claude/commands/trellis/finish-work.md": "cc92cad9e94ce1cc4f29e3de16a640db7e9176e3ecfc9c19a566153671ca2168",
+  ".claude/commands/trellis/integrate-skill.md": "3940442485341832257c595ddfb45582e2d60e5a4716f2bd15b7bce0498b130a",
+  ".claude/commands/trellis/onboard.md": "a5dbd5db094b13fd006ec856efa53a688e209bcdc3ed1680b63b15f1e3293ab4",
+  ".claude/commands/trellis/parallel.md": "f4c81fe1a468be214caf362263b14b6a6f40935497363109148cb7b19e644738",
+  ".claude/commands/trellis/record-session.md": "0c4f61283c2f262c1f9c900d9207309107497d4ac848cca86eb62bc5b7189fe7",
+  ".claude/commands/trellis/start.md": "2d4259d8d146d32c7b6c33dda36c14da76e1c3f1be35b27dc18e5eb5551c9276",
+  ".claude/commands/trellis/update-spec.md": "ff4d5a0405a763e61936f5b9df175fd25ea20ec5c20fa999855020ab78a919b6",
+  ".claude/hooks/inject-subagent-context.py": "75ce4cc175a00f9afa5fe1c80298e29521359ad90a66701c3c1166aa588f3080",
+  ".claude/hooks/ralph-loop.py": "a367a5dd4f605730cf8157c61658e848176ae480be19029126ff9bbd90a37712",
+  ".claude/hooks/session-start.py": "5c048949cbf8ac58c7c26ef51cd90bf91454574425f2158f4778c200b8098f53",
+  ".claude/settings.json": "fdb7fcf660961b4b52f22f08e91f942a193e1a3f5ebbca9cbba21a157d1c359d",
+  ".cursor/commands/trellis-before-backend-dev.md": "7e35444de2a5779ef39944f17f566ea21d2ed7f4994246f4cfe6ebf9a11dd3e3",
+  ".cursor/commands/trellis-before-frontend-dev.md": "a6225f9d123dbd4a7aec822652030cae50be3f5b308297015e04d42b23a27b2a",
+  ".cursor/commands/trellis-brainstorm.md": "cd0cc2f346b16b289ebcd7a35c402db53fb8c7c9653a5679ad3dc065c200e300",
+  ".cursor/commands/trellis-break-loop.md": "24d07ac0ac1873cb7adf5228c597e58a58125d80fc1e8d2eb5d6948c43761566",
+  ".cursor/commands/trellis-check-backend.md": "4e81a28d681ea770f780df55a212fd504ce21ee49b44ba16023b74b5c243cef3",
+  ".cursor/commands/trellis-check-cross-layer.md": "a79fe38f29f84a4524a70987e9fecfca569430df476082bff9dde31596ca3951",
+  ".cursor/commands/trellis-check-frontend.md": "5e8e3b682032ba0dd6bb843dd4826fff0159f78a7084964ccb119c6cf98b3d91",
+  ".cursor/commands/trellis-create-command.md": "9a9283add72832e0e015de770531edf37cf3720e4a72782c1cea6e9941603490",
+  ".cursor/commands/trellis-finish-work.md": "582e968ada1b2b6124baf19a0e89ba1e5617330f4a1318e8d3334698e40fce67",
+  ".cursor/commands/trellis-integrate-skill.md": "bb15144c308939abfd41cb008da71088910b6ec432c763ab4c0762dd6f0819e8",
+  ".cursor/commands/trellis-onboard.md": "ebfbe707f428f036b7d716061dfc33187b940ef9acdf3f824d1c43d1e2035ecb",
+  ".cursor/commands/trellis-record-session.md": "0c4f61283c2f262c1f9c900d9207309107497d4ac848cca86eb62bc5b7189fe7",
+  ".cursor/commands/trellis-start.md": "a6a020be5d2dafa4726f1c78641cbbcb325f31d2c636d645f1f42822e04e8286",
+  ".cursor/commands/trellis-update-spec.md": "714ce498567304c679d4b541e13cc670ce1cfc34c2abeb6d7e7d0f7196a52eff",
+  ".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": "3c7e97af07961ec45a2f1dc16de60396b1cbb8f399b91d7842c85532c1e26c7c",
+  ".agents/skills/integrate-skill/SKILL.md": "47b7374345d8a31f9df07c5e8e875ca4fdc30d0cc45860d77df893250e2d97fc",
+  ".agents/skills/onboard/SKILL.md": "52b460040bd688e883877d7f85e48ab2e69793e49c452fa875876b230e480242",
+  ".agents/skills/record-session/SKILL.md": "e2d19d862c755bfb0b8442baf364cc2447fd26fda010e390fc4336d8d952c84e",
+  ".agents/skills/start/SKILL.md": "b105b2a86dfbe8d5b6009072b52e279e2b88bedb977b484e1fb745beb29dd5f6",
+  ".gemini/commands/trellis/before-backend-dev.toml": "c384cda35b0e57de4a84d2812d59fd223c998be2aaa16a0620d7b987a08f6e33",
+  ".gemini/commands/trellis/before-frontend-dev.toml": "3e1ad82280f2aaabe60b93ec3e76c1017ef6282319d061e1a3de556b421317e2",
+  ".gemini/commands/trellis/brainstorm.toml": "4e3cce1613aaa405e22e5b2ce86ebfb28c382e29ffd94f13151daa8abd6aefd2",
+  ".gemini/commands/trellis/break-loop.toml": "29fcda2044328dc011545b5a1722a1db0312f147e6509f378739b1eed6db8fe6",
+  ".gemini/commands/trellis/check-backend.toml": "8f872a2eea659abce0cbdc40ee6a197e70ffa4a4e0cbdc42ea9bb026af1cfe79",
+  ".gemini/commands/trellis/check-cross-layer.toml": "2f2e6d2167c335d5fa29147266e831aa066c18b0449707dbd864a2fb849c08c2",
+  ".gemini/commands/trellis/check-frontend.toml": "4fb9eecf75f5efc0d9a38becc459d503261ecc5e69906cdfc489b2ef065944a6",
+  ".gemini/commands/trellis/create-command.toml": "80718724d2c2421fda719fec3be9a0dcd0e90085be87d4fcf43df93ef6c7e570",
+  ".gemini/commands/trellis/finish-work.toml": "b81e00418af86e93ad87767519da6742b23059b07dfd367edfd4513ceb526731",
+  ".gemini/commands/trellis/integrate-skill.toml": "47a522dac5f78eef666a05bb72b14e86023a5dda44d9b5c2355798fc54e9bbd0",
+  ".gemini/commands/trellis/onboard.toml": "d4343f29d5e9cb56c03150e58d000f3a9adc088216f07fbc4d6b615f7c2f74a7",
+  ".gemini/commands/trellis/record-session.toml": "0a2c7139b13bfccd862db4a27a53dbd65803d3875eb82302418c6bfaaac68ff7",
+  ".gemini/commands/trellis/start.toml": "8717a9330ae94d11c4123f295580e1417c07d45162333f400b5baec9b33c9dfb",
+  ".gemini/commands/trellis/update-spec.toml": "5b03bc0ee5d243929af24d77d6e3f2b3f605d68df0cec68f5c7fe5ed2045b105"
+}
\ 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..3f116c0fb
--- /dev/null
+++ b/.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md
@@ -0,0 +1,243 @@
+<!-- Created on 2026-04-14 during Trellis brainstorm for redefining coding-deepgent final goal. -->
+# coding-deepgent CC Core Highlights Roadmap
+
+Status: historical MVP dashboard
+Updated: 2026-04-20
+Scope: `coding-deepgent/` product track only
+Superseded as default planning target by:
+
+* `.trellis/plans/coding-deepgent-full-cc-parity-roadmap.md`
+
+Evidence policy at the time of this roadmap: every highlight must be
+source-backed against `/root/claude-code-haha` before implementation
+
+## Purpose
+
+Historical note:
+
+This document remains the canonical record of the old `Approach A MVP` closeout
+dashboard. It is still useful when reviewing how the MVP line was defined and
+closed, but it is no longer the default roadmap for future product planning.
+
+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, plus deferred discovery through `ToolSearch` / `invoke_deferred_tool` | `tool_system`, domain `tools.py` | H01 closeout path is complete through `L1-c`, `L2-c`, `L3-c`, `L4-a`, `L4-b`, and `L4-c`; deferred discovery is now implemented, and `L5-a` remains conditional/spec-only unless a real capability-aware partitioning failure appears |
+| 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 | bounded `run_subagent` surface, `AgentDefinition`, real read-only `general` and `verifier` child runtimes, structured result envelopes, parent-ledger sidechain transcript audit, and deferred-discovery lifecycle tools for background/status/send-input/stop/resume | `subagents`, `runtime`, `tasks`, `sessions` | local MVP closeout is complete; mailbox/team-runtime lifecycle remains deferred via refreshed deferred-boundary ADR |
+| H12 | Fork/cache-aware subagent execution | implemented | explicit `run_fork` foreground/background surface, fork continuity metadata, background fork reuse, stop/cancel contract, deferred-discovery `resume_fork`, and resume/path hardening on one local slice; provider-specific cache tuning remains out of scope | `subagents`, `runtime`, `compact` | local completion pack is complete; implicit fork entry and provider-specific cache internals remain intentionally out of scope |
+| 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 | queued runtime event sink, agent-scoped logger, compact attempted/succeeded events, post-compact canary, orphan tombstone repair event, structured query_error, per-turn token_budget, env-gated prompt/API dump, session evidence and recovery visibility | `runtime`, `sessions`, `tool_system`, `subagents` | local closeout is complete; deferred analytics/Perfetto/SDK/TTFT/provider-cache items are now captured in the refreshed deferred-boundary ADR |
+| 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 `.trellis/spec/backend/langchain-native-guidelines.md` 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-circle-1-wave-1-runtime-core-plan.md b/.trellis/plans/coding-deepgent-circle-1-wave-1-runtime-core-plan.md
new file mode 100644
index 000000000..d87d623ad
--- /dev/null
+++ b/.trellis/plans/coding-deepgent-circle-1-wave-1-runtime-core-plan.md
@@ -0,0 +1,370 @@
+# coding-deepgent Circle 1 Wave 1 Runtime-Core Parity Plan
+
+Status: implemented checkpoint
+Updated: 2026-04-20
+Parent roadmap: `.trellis/plans/coding-deepgent-full-cc-parity-roadmap.md`
+Scope: `coding-deepgent/` local daily-driver parity, Circle 1 / Wave 1 only
+
+## Purpose
+
+This plan turns Circle 1 / Wave 1 from a broad roadmap label into a concrete
+planning slice for implementation.
+
+Wave 1 is the runtime-core parity pass that must land before broad CLI/TUI
+polish or extension-ecosystem improvement can be planned coherently.
+
+## Acceptance Targets
+
+* The runtime core is strong enough to support the three Circle 1 acceptance
+  workflows without leaning on the old “MVP complete” label as proof.
+* We can point to a prioritized set of feature families whose improvement is
+  necessary for:
+  - PR-level independent completion
+  - single-day long-task continuity
+  - personal-efficiency amplification via task/subagent/fork
+* Future implementation tasks can be created from this plan without reopening
+  the top-level Circle 1 scope question every turn.
+* Wave 1 explicitly distinguishes:
+  - high-priority parity gaps
+  - currently-strong-enough baseline areas
+  - intentionally deferred areas that belong to Wave 2 or Circle 2
+
+## Planned Features
+
+* Group Wave 1 into a small number of runtime-core feature families.
+* For each family, state:
+  - why it matters now
+  - which acceptance workflow(s) it unlocks
+  - which modules it primarily touches
+  - what the current baseline already provides
+  - what still blocks daily-driver parity
+* Define the recommended order for implementation after this planning pass.
+* Name concrete follow-up task families to create next.
+
+## Planned Extensions
+
+* runtime-exposing CLI/TUI parity surfaces such as history/projection inspect,
+  richer resume UX, and task/subagent interaction UX
+* usable local extension-seam follow-up for skills/MCP/hooks/plugins
+* Circle 2 team-runtime/remote/daemon parity
+* cross-day continuity, richer memory extraction, and broader automation
+
+## Why Now
+
+The current product has a strong MVP baseline, but Wave 1 must decide where
+that baseline is still only “MVP-complete” rather than “daily-driver parity
+capable.” Without this decomposition, future work will oscillate between random
+feature grabbing and vague “closer to cc” ambitions.
+
+## Out of Scope
+
+* broad CLI/TUI polish
+* mailbox/coordinator/team-runtime parity
+* remote / IDE / daemon control plane
+* plugin marketplace / install / distribution lifecycle
+* implementation details for any one feature family
+
+## Acceptance Workflows Served
+
+### Workflow A: Repository Takeover And Sustained Coding
+
+Success standard:
+
+* PR-level independent completion on a medium-to-large codebase
+
+Most relevant families:
+
+* F1 tool/runtime control loop
+* F2 context/session continuity
+* F3 planning/task execution discipline
+
+### Workflow B: Long Session Continuity
+
+Success standard:
+
+* single-day long-task continuity across multiple rounds of pressure and resume
+
+Most relevant families:
+
+* F2 context/session continuity
+* F4 observability/evidence for recovery/debugging
+
+### Workflow C: Complex Task Decomposition
+
+Success standard:
+
+* bounded task/subagent/fork assistance materially increases single-developer
+  throughput
+
+Most relevant families:
+
+* F3 planning/task execution discipline
+* F5 bounded local subagent/fork runtime
+
+## Feature Families
+
+### F1: Tool / Permission / Prompt / Runtime Control Loop
+
+Primary modules:
+
+* `tool_system`
+* `permissions`
+* `prompting`
+* `runtime`
+
+Why now:
+
+* This family governs whether the agent can safely and predictably perform
+  independent PR-level work.
+* If this family remains only “MVP-safe” rather than “daily-driver strong,” the
+  agent will still feel brittle in real repository work.
+
+Current baseline:
+
+* strong capability metadata and projection foundation
+* strong deterministic permission runtime
+* layered prompt contract exists
+* deferred discovery exists
+
+Parity pressure still likely comes from:
+
+* how well real local workflows compose tool discovery, selection, safety, and
+  prompt/control-loop behavior under sustained use
+* whether the runtime exposes the same practical coding affordances and
+  resilience expected from a daily-driver coding agent
+
+Primary workflows improved:
+
+* Workflow A
+* Workflow C
+
+Priority judgment:
+
+* highest priority
+
+### F2: Context / Compact / Session / Memory Continuity
+
+Primary modules:
+
+* `compact`
+* `sessions`
+* `memory`
+* `runtime`
+
+Why now:
+
+* This family is the main blocker for long-session continuity.
+* Current baseline is enough to count as MVP, but not yet proven against the
+  stronger Circle 1 standard.
+
+Current baseline:
+
+* staged pressure pipeline exists
+* session resume/evidence infrastructure exists
+* scoped memory exists
+* compact/collapse persistence foundations exist
+
+Parity pressure still likely comes from:
+
+* stronger continuity under long single-day work
+* better preservation of working thread across compaction/resume
+* richer but still bounded context/session/memory interaction
+
+Primary workflows improved:
+
+* Workflow A
+* Workflow B
+
+Priority judgment:
+
+* highest priority
+
+### F3: Todo / Task / Plan / Verify Workflow Discipline
+
+Primary modules:
+
+* `todo`
+* `tasks`
+* `subagents` (verifier path)
+* `sessions`
+
+Why now:
+
+* Workflow C depends on more than “tools exist”; it depends on disciplined task
+  shaping and plan/verify boundaries.
+
+Current baseline:
+
+* TodoWrite, task graph, plan artifact, and verifier boundaries already exist
+* the product already has durable workflow structure, not just prompt-based task
+  talk
+
+Parity pressure still likely comes from:
+
+* turning these pieces into a consistent high-throughput personal workflow
+* ensuring plan/task/verify is practical during real coding work rather than
+  merely contract-correct
+
+Primary workflows improved:
+
+* Workflow A
+* Workflow C
+
+Priority judgment:
+
+* high priority
+
+### F4: Observability / Evidence / Recovery Visibility
+
+Primary modules:
+
+* `runtime`
+* `sessions`
+* `compact`
+* `subagents`
+
+Why now:
+
+* Without strong visibility, Wave 1 cannot be debugged or trusted under
+  long-session conditions.
+* This family is supporting infrastructure for Workflows A and B rather than a
+  standalone product story.
+
+Current baseline:
+
+* runtime event sink exists
+* evidence ledger exists
+* compact/pressure events exist
+* prompt dump exists behind env gate
+
+Parity pressure still likely comes from:
+
+* making long-task failures and recoveries understandable enough for daily use
+* closing the gap between “we log it” and “the agent/user can act on it”
+
+Primary workflows improved:
+
+* Workflow A
+* Workflow B
+
+Priority judgment:
+
+* supporting priority; should move alongside F1/F2 rather than after them
+
+### F5: Bounded Local Subagent / Fork Runtime
+
+Primary modules:
+
+* `subagents`
+* `runtime`
+* `tasks`
+* `sessions`
+
+Why now:
+
+* Workflow C explicitly requires this family to be useful, not demo-shaped.
+* Circle 1 does not require team-runtime parity, but it does require strong
+  personal-efficiency amplification through bounded child execution.
+
+Current baseline:
+
+* `run_subagent`, `run_fork`, background slices, sidechain transcript, and
+  resume paths already exist
+
+Parity pressure still likely comes from:
+
+* stronger day-to-day usability of bounded child execution
+* clearer continuation, cleanup, and handoff semantics for single-developer use
+
+Primary workflows improved:
+
+* Workflow C
+
+Priority judgment:
+
+* high priority, but after F1/F2 are directionally locked
+
+## Recommended Order
+
+### Pass 1: F1 + F2
+
+Why:
+
+* these determine whether the agent can work independently for meaningful
+  periods at all
+* most other families depend on stable runtime/control-loop and continuity
+
+### Pass 2: F3 + F5
+
+Why:
+
+* once the core is stable, workflow-discipline and bounded child execution can
+  be strengthened toward genuine personal-efficiency gains
+
+### Pass 3: F4 closeout
+
+Why:
+
+* observability/evidence should evolve continuously during Pass 1 and Pass 2
+* but a focused closeout pass should happen after the main runtime semantics are
+  clearer
+
+## Recommended Follow-Up Task Families
+
+These are the next planning or implementation slices to create after this note:
+
+1. `.trellis/tasks/04-20-circle-1-wave-1-f1-tool-permission-prompt-runtime-parity/`
+2. `.trellis/tasks/04-20-circle-1-wave-1-f2-context-session-memory-continuity/`
+3. `.trellis/tasks/04-20-circle-1-wave-1-f3-todo-task-plan-verify-daily-driver/`
+4. `.trellis/tasks/04-20-circle-1-wave-1-f5-bounded-subagent-fork-daily-driver/`
+5. `.trellis/tasks/04-20-circle-1-wave-1-f4-observability-recovery-visibility/`
+
+## Historical Inputs
+
+Use these as baseline evidence when decomposing the follow-up tasks:
+
+* `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+* `.trellis/project-handoff.md`
+* `.trellis/tasks/archive/2026-04/04-15-stage-23-context-pressure-and-session-continuity-closeout/prd.md`
+* `.trellis/tasks/archive/2026-04/04-15-stage-25-todo-task-plan-verify-closeout/prd.md`
+* `.trellis/tasks/archive/2026-04/04-15-stage-26-agent-as-tool-mvp-closeout/prd.md`
+* `.trellis/tasks/archive/2026-04/04-15-stage-28-observability-evidence-closeout/prd.md`
+
+## Implementation Checkpoint
+
+State: terminal
+
+Verdict: APPROVE
+
+Scope completed:
+
+* F1 tool/permission/prompt/runtime:
+  - deferred tool execution now preserves real bounded result contracts,
+    including `Command(update=...)`
+* F2 context/session/memory continuity:
+  - collapse preserved-tail selection now avoids splitting recent
+    assistant-led work units when possible
+  - session-memory freshness now accounts for token/tool-call pressure where
+    metrics exist
+  - compact assist remains conservative for message-count-lagged artifacts
+* F3 todo/task/plan/verify workflow:
+  - frontend event flow now emits durable `task_snapshot` data alongside
+    `todo_snapshot`
+* F4 observability/recovery visibility:
+  - recovery brief now includes a dedicated `Subagent activity:` section for
+    recent background child-agent notifications
+* F5 bounded subagent/fork runtime:
+  - added deferred `subagent_list` for active/recent background run discovery
+
+Validation:
+
+* `pytest -q coding-deepgent/tests` -> 415 passed
+* `ruff check coding-deepgent/src/coding_deepgent coding-deepgent/tests .trellis/spec .trellis/plans` -> passed
+* `python3 -m mypy coding-deepgent/src/coding_deepgent` -> passed
+
+Residual future work:
+
+* Circle 1 Wave 2 should focus on richer runtime-exposing CLI/TUI surfaces.
+* Circle 1 Wave 3 should keep local extension seams usable without expanding
+  into full plugin distribution.
+* Circle 2 remains the owner for mailbox/coordinator/remote/daemon parity.
diff --git a/.trellis/plans/coding-deepgent-circle-2-expanded-parity-plan.md b/.trellis/plans/coding-deepgent-circle-2-expanded-parity-plan.md
new file mode 100644
index 000000000..eb3c47907
--- /dev/null
+++ b/.trellis/plans/coding-deepgent-circle-2-expanded-parity-plan.md
@@ -0,0 +1,504 @@
+# coding-deepgent Circle 2 Expanded Product Parity Plan
+
+Status: implemented local baseline
+Updated: 2026-04-20
+Parent roadmap: `.trellis/plans/coding-deepgent-full-cc-parity-roadmap.md`
+Planning task: `.trellis/tasks/04-20-brainstorm-circle-2-parity-plan/`
+Strategy: substrate-first
+
+## Implemented Local Baseline
+
+Implemented: 2026-04-20
+
+Local expanded parity baseline is implemented for all Circle 2 waves using the
+workspace-local durable `runtime.store` substrate. This baseline intentionally
+does not claim hosted SaaS session ingress, multi-user auth, public marketplace
+backend, or cross-machine workers.
+
+Implemented modules:
+
+* `event_stream`
+* `worker_runtime`
+* `mailbox`
+* `teams`
+* `remote`
+* `extension_lifecycle`
+* `continuity`
+
+Implemented CLI surfaces:
+
+* `coding-deepgent events ...`
+* `coding-deepgent workers ...`
+* `coding-deepgent mailbox ...`
+* `coding-deepgent teams ...`
+* `coding-deepgent remote ...`
+* `coding-deepgent extension-lifecycle ...`
+* `coding-deepgent continuity ...`
+* `coding-deepgent acceptance circle2`
+
+## Purpose
+
+Circle 2 begins after the Circle 1 local daily-driver parity baseline.
+
+Circle 1 intentionally avoided mailbox, coordinator/team runtime, durable daemon,
+remote/IDE control plane, full extension lifecycle, and richer cross-day memory.
+Circle 2 is where those expanded product-parity capabilities can be planned and
+implemented without overloading the Circle 1 `subagents`, `sessions`, or
+frontend bridge seams.
+
+## Strategy Decision
+
+Use a substrate-first sequence.
+
+Rationale:
+
+* current Circle 1 background subagent controls are active-process features, not
+  durable workers
+* mailbox and coordinator semantics need real delivery/lifecycle state
+* remote/IDE surfaces need replayable event/control infrastructure
+* daemon/worker substrate reduces the chance of faking durable behavior with
+  process-local handles
+
+## Evidence Ladder
+
+Use the global evidence order from
+`.trellis/plans/coding-deepgent-full-cc-parity-roadmap.md`:
+
+1. real Claude Code public behavior
+2. `cc-haha` source-backed implementation reference
+3. high-quality analogous OSS
+4. secondary analysis
+
+For Circle 2, `cc-haha` evidence is sufficient to justify the major feature
+families, but OSS fallback is still useful for implementation details around
+runtime server boundaries, extension lifecycle, and sandbox/remote control.
+
+## Source Evidence
+
+### `cc-haha`
+
+Worker / session ingress:
+
+* `/root/claude-code-haha/src/cli/transports/ccrClient.ts`
+  * worker lifecycle protocol
+  * `PUT /worker`
+  * worker heartbeat
+  * visible client events
+  * internal worker events for resume
+  * worker state restore after restart
+* `/root/claude-code-haha/src/cli/transports/SSETransport.ts`
+* `/root/claude-code-haha/src/cli/transports/WebSocketTransport.ts`
+
+Task lifecycle and control:
+
+* `/root/claude-code-haha/src/cli/print.ts`
+  * `task_started`
+  * `task_progress`
+  * `task_notification`
+  * `session_state_changed`
+  * `stop_task`
+* `/root/claude-code-haha/src/entrypoints/sdk/controlSchemas.ts`
+
+Mailbox / permission routing:
+
+* `/root/claude-code-haha/src/context/mailbox.tsx`
+* `/root/claude-code-haha/src/hooks/useInboxPoller.ts`
+* `/root/claude-code-haha/src/hooks/useSwarmPermissionPoller.ts`
+* `/root/claude-code-haha/src/hooks/toolPermission/handlers/swarmWorkerHandler.ts`
+
+Coordinator / workers:
+
+* `/root/claude-code-haha/src/cli/print.ts`
+  * coordinator mode references and resume-mode matching
+* `/root/claude-code-haha/src/components/PromptInput/*`
+  * coordinator task selection/UI state
+* `/root/claude-code-haha/src/state/AppStateStore.ts`
+  * coordinator task index/count and worker permission state
+
+Remote / IDE:
+
+* `/root/claude-code-haha/src/remote/*`
+* `/root/claude-code-haha/src/services/mcp/vscodeSdkMcp.ts`
+* `/root/claude-code-haha/src/services/mcp/client.ts`
+  * IDE-specific MCP server/tool handling
+
+Daemon / cron / proactive:
+
+* `/root/claude-code-haha/src/entrypoints/cli.tsx`
+  * `--daemon-worker`
+* `/root/claude-code-haha/src/cli/print.ts`
+  * cron scheduler and proactive tick references
+* `/root/claude-code-haha/src/skills/bundled/loop.ts`
+* `/root/claude-code-haha/src/skills/bundled/scheduleRemoteAgents.ts`
+
+Plugin / extension lifecycle:
+
+* `/root/claude-code-haha/src/services/plugins/pluginOperations.ts`
+* `/root/claude-code-haha/src/services/plugins/PluginInstallationManager.ts`
+* `/root/claude-code-haha/src/services/mcp/config.ts`
+  * plugin MCP loading, dedup, enabled/disabled config, marketplace/policy gates
+
+Session / cross-day memory:
+
+* `/root/claude-code-haha/src/services/SessionMemory/sessionMemory.ts`
+* `/root/claude-code-haha/src/services/SessionMemory/sessionMemoryUtils.ts`
+* `/root/claude-code-haha/src/services/extractMemories/extractMemories.ts`
+* `/root/claude-code-haha/src/services/compact/sessionMemoryCompact.ts`
+
+### Analogous OSS
+
+OpenHands:
+
+* Runtime docs describe a client-server runtime using Docker containers.
+* Runtime README describes a `Runtime` interface, action execution client/server,
+  multiple implementations including local, Docker, and remote, and plugin
+  management.
+* Reusable essence: isolate runtime lifecycle and action execution behind a
+  formal runtime/control interface.
+
+opencode:
+
+* README describes provider-agnostic terminal coding agent with a TUI focus and
+  client/server architecture where the TUI is only one possible client.
+* Reusable essence: separate frontend clients from the backend agent/runtime
+  server.
+
+goose:
+
+* README describes desktop app, CLI, and API surfaces over one local agent.
+* Extension docs describe MCP-based extensions, enable/disable UX, extension
+  management, malware checks, access controls, and extension directory.
+* Reusable essence: extension lifecycle is a first-class product domain, not
+  just schema validation.
+
+## New Domain Boundaries
+
+Circle 2 should introduce new domains instead of stretching Circle 1 modules:
+
+* `daemon/`
+  * process lifecycle
+  * worker registry
+  * heartbeats
+  * durable run ownership
+  * restart/recovery
+* `worker_runtime/`
+  * worker execution state
+  * queued/running/cancelled/completed lifecycle
+  * run logs/events
+  * stop/cancel semantics
+* `events/` or `event_stream/`
+  * replayable user-visible events
+  * internal worker events
+  * delivery sequence/ack model
+  * remote/TUI/CLI consumers
+* `mailbox/`
+  * addressable messages
+  * inbox/outbox
+  * send/receive/ack
+  * permission response routing
+* `teams/` or `orchestration/`
+  * coordinator
+  * worker roles
+  * task assignment
+  * progress synthesis
+  * concurrency/write-scope rules
+* `remote/`
+  * remote session API
+  * SSE/WebSocket gateway
+  * control messages
+  * replay/reconnect
+* `extension_lifecycle/`
+  * install/enable/disable/update
+  * trust/source metadata
+  * rollback
+  * managed policy gates
+* `continuity/` or extended `memory/`
+  * cross-day session memory extraction
+  * richer agent-private memory
+  * long-session/cross-restart continuity policy
+
+Do not hide these inside:
+
+* `sessions/`
+* `subagents/tools.py`
+* `tool_system/`
+* `frontend/producer.py`
+
+## Circle 2 Waves
+
+### Wave 1: Durable Daemon / Worker / Event Substrate
+
+Goal:
+
+* establish real durable lifecycle semantics before mailbox/coordinator/remote
+  features are built
+
+Primary modules:
+
+* `daemon`
+* `worker_runtime`
+* `event_stream`
+* `runtime`
+* `sessions`
+
+Planned features:
+
+* local daemon command group
+* worker registry
+* durable worker records
+* heartbeat and stale-worker detection
+* restart-safe run ownership
+* event stream with visible and internal events
+* stop/cancel request model
+* replayable event sequence numbers
+
+Acceptance:
+
+* a background run can survive parent CLI exit as durable state
+* worker heartbeat/state can be inspected
+* stop/cancel is persisted and eventually observed
+* visible and internal events can be replayed in order
+
+Out of scope:
+
+* coordinator decisions
+* mailbox message routing
+* remote/IDE network API
+
+### Wave 2: Mailbox / SendMessage Substrate
+
+Goal:
+
+* add addressable message delivery for agents/workers/human permission flows
+
+Primary modules:
+
+* `mailbox`
+* `worker_runtime`
+* `permissions`
+* `event_stream`
+
+Planned features:
+
+* mailbox message schema
+* inbox/outbox
+* delivery status and ack
+* idempotent send
+* `SendMessage`-equivalent local tool
+* permission request/response messages
+* CLI/TUI mailbox inspection
+
+Acceptance:
+
+* worker can send message to parent/coordinator
+* parent can reply
+* permission request can route through mailbox without bypassing policy
+* duplicate delivery is harmless
+
+Out of scope:
+
+* autonomous coordinator planning
+* remote transport
+
+### Wave 3: Coordinator / Worker Team Runtime
+
+Goal:
+
+* add local team runtime with coordinator and bounded workers
+
+Primary modules:
+
+* `teams` or `orchestration`
+* `mailbox`
+* `worker_runtime`
+* `tasks`
+* `subagents`
+* `permissions`
+
+Planned features:
+
+* coordinator role
+* worker role
+* team task graph
+* worker assignment
+* progress synthesis
+* worker stop/cancel
+* write-scope/concurrency policy
+* verifier/acceptance integration
+
+Acceptance:
+
+* coordinator can decompose a complex task into worker jobs
+* workers report progress and results through mailbox/events
+* coordinator can synthesize final status
+* conflicting write scopes are blocked or serialized
+
+Out of scope:
+
+* remote/cloud workers
+* cross-machine team runtime
+
+### Wave 4: Remote / IDE Control Plane
+
+Goal:
+
+* make CLI/TUI only one consumer of a broader control plane
+
+Primary modules:
+
+* `remote`
+* `event_stream`
+* `daemon`
+* `frontend`
+* `mcp`
+
+Planned features:
+
+* local HTTP/SSE or WebSocket gateway
+* replayable session event stream
+* control messages
+* remote permission bridge
+* IDE MCP/control hooks
+* reconnect/replay
+
+Acceptance:
+
+* a non-TUI client can observe session events
+* a non-TUI client can issue bounded control messages
+* reconnect receives missed events
+* permission prompts remain policy-governed
+
+Out of scope:
+
+* hosted SaaS session ingress
+* multi-user auth
+
+### Wave 5: Extension Lifecycle
+
+Goal:
+
+* move beyond inspect/debug into install/enable/disable/update lifecycle
+
+Primary modules:
+
+* `extension_lifecycle`
+* `plugins`
+* `mcp`
+* `skills`
+* `hooks`
+* `permissions`
+
+Planned features:
+
+* local install source registry
+* enable/disable state
+* update metadata
+* trust/source policy
+* rollback
+* MCP/plugin dedup
+* managed policy gates
+* CLI/TUI extension manager surfaces
+
+Acceptance:
+
+* user can install/enable/disable/update a local extension
+* invalid/untrusted extension is blocked with clear reason
+* MCP/plugin duplicates are detected deterministically
+* rollback restores prior state
+
+Out of scope:
+
+* public marketplace backend
+* paid/hosted distribution
+
+### Wave 6: Cross-Day Continuity And Richer Memory
+
+Goal:
+
+* strengthen continuity beyond a single-day Circle 1 session
+
+Primary modules:
+
+* `memory`
+* `continuity`
+* `sessions`
+* `compact`
+* `daemon`
+
+Planned features:
+
+* richer session-memory extraction
+* cross-day memory artifacts
+* agent-private memory lifecycle
+* memory quality review
+* session-memory compact integration
+* away/resume summary
+* workspace migration/export/import
+
+Acceptance:
+
+* long-running work can resume across process restarts and days
+* current task, decisions, blockers, and next steps survive
+* stale memory is detected and refreshed
+* memory extraction remains bounded and auditable
+
+Out of scope:
+
+* organization/team memory sync unless explicitly scoped later
+
+### Circle 2 Final: Expanded Parity Acceptance Harness
+
+Acceptance workflows:
+
+* Workflow D: Durable background lifecycle
+  * start work
+  * parent exits
+  * worker state/events survive
+  * control plane can inspect/stop/resume
+* Workflow E: Local team execution
+  * coordinator decomposes
+  * workers execute bounded tasks
+  * mailbox/progress/result synthesis works
+* Workflow F: Remote/IDE control
+  * secondary client observes and controls a live session
+  * reconnect/replay is correct
+* Workflow G: Extension lifecycle
+  * install/enable/disable/update/rollback local extension
+* Workflow H: Cross-day continuity
+  * resume next day with session memory and evidence intact
+
+## Risks
+
+* Building coordinator before daemon will likely create process-local fake
+  durability.
+* Adding mailbox into `subagents` will make team routing hard to reason about.
+* Adding remote/IDE to frontend JSONL bridge will blur local transport with
+  control-plane API.
+* Extension lifecycle without trust/source policy can create unsafe defaults.
+
+## Out Of Scope For Circle 2 Unless Reopened
+
+* hosted SaaS control plane
+* multi-user auth/billing
+* public marketplace backend
+* enterprise managed settings sync
+* full organization/team memory sync
+
+## First Implementation Task
+
+Create:
+
+`.trellis/tasks/<date>-circle-2-wave-1-daemon-worker-event-substrate/`
+
+Goal:
+
+* implement the durable local daemon/worker/event substrate only
+
+Must state before coding:
+
+* durable worker record schema
+* event stream schema
+* stop/cancel semantics
+* heartbeat/stale policy
+* recovery/replay behavior
+* which existing Circle 1 background controls are migrated or left process-local
diff --git a/.trellis/plans/coding-deepgent-deferred-boundary-refresh-adr.md b/.trellis/plans/coding-deepgent-deferred-boundary-refresh-adr.md
new file mode 100644
index 000000000..6aeb7fb6e
--- /dev/null
+++ b/.trellis/plans/coding-deepgent-deferred-boundary-refresh-adr.md
@@ -0,0 +1,237 @@
+# coding-deepgent Deferred Boundary Refresh ADR
+
+Status: historical MVP boundary reference
+Updated: 2026-04-20
+Supersedes: Stage 29 deferred-boundary checkpoint in
+`.trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/prd.md`
+Scope: `coding-deepgent/` Approach A MVP boundary after 2026-04-17/18 H01, H11/H12, and H19 closeout work
+
+Superseded as the default planning boundary by:
+
+* `.trellis/plans/coding-deepgent-full-cc-parity-roadmap.md`
+
+## Purpose
+
+Historical note:
+
+This ADR still records which boundaries were intentionally deferred under the
+old `Approach A MVP` line. It remains useful as a historical boundary decision,
+but it no longer defines the default direction for future product planning.
+
+This ADR refreshes the old Stage 29 deferred-boundary note with the concrete
+boundaries established by the recent closeout tasks:
+
+- H19 vertical closeout
+- H01 capability/projection/pairing/result-pressure closeout
+- H11/H12 `AgentDefinition`, real general runtime, sidechain transcript, and
+  result-envelope closeout
+
+The goal is to make future reopen requests source-backed and to distinguish:
+
+- intentionally deferred
+- implemented-minimal
+- do-not-copy
+
+## Source Anchors
+
+Primary source-backed inputs:
+
+- `.trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/prd.md`
+- `.trellis/tasks/04-16-cc-highlight-alignment-discussion/h11-h12-alignment-research.md`
+- `.trellis/tasks/04-16-cc-highlight-alignment-discussion/h19-observability-alignment-research.md`
+- `.trellis/plans/coding-deepgent-h01-tool-module-alignment-plan.md`
+- `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+- `.trellis/spec/backend/tool-capability-contracts.md`
+- `.trellis/spec/backend/task-workflow-contracts.md`
+- `.trellis/spec/backend/session-compact-contracts.md`
+- `.trellis/spec/backend/runtime-pressure-contracts.md`
+
+## Decision
+
+The current Approach A MVP boundary remains:
+
+- keep the local LangChain-native agent harness core strong
+- keep the runtime bounded and synchronous where possible
+- defer richer agent-team orchestration, background lifecycle, remote control
+  plane, and provider-specific observability/caching unless a new source-backed
+  PRD demonstrates concrete local benefit
+
+## Deferred Boundaries
+
+### 1. H13 / H14 Agent-Team Runtime
+
+Deferred:
+
+- mailbox / `SendMessage`
+- coordinator synthesis runtime
+- background worker orchestration
+- pending-message drains and cross-agent task inboxes
+
+Why deferred:
+
+- current product has durable task/plan/verify and bounded `run_subagent`
+  already; mailbox/coordinator would add a new runtime tier rather than close a
+  missing MVP invariant
+- no current product surface needs asynchronous team coordination to satisfy
+  the MVP boundary
+- adding these now would widen the runtime far beyond current local benefit
+
+Reopen only when:
+
+- a new source-backed PRD shows concrete workflow benefit that cannot be met by
+  the current task/plan/verifier/subagent path
+
+### 2. H11 / H12 Rich Subagent Lifecycle
+
+Deferred:
+
+- parent/child abort cascade parity
+- per-agent cleanup inventory parity
+- task notifications / summary agents
+- per-agent transcript directories
+- full fork/cache parity
+- implicit fork mode
+- exact-tool-inheritance cache-safe fork path
+
+Implemented-minimal and therefore not deferred:
+
+- `AgentDefinition` for `general` and `verifier`
+- real read-only `general` child runtime
+- plan-bound `verifier`
+- structured result envelopes
+- sidechain transcript in parent ledger
+- bounded background subagent/fork runs with status, follow-up input, and stop
+- explicit `resume_subagent` / `resume_fork` continuity on recorded sidechains
+
+Why deferred:
+
+- current synchronous child runtime plus sidechain audit already covers the MVP
+  correctness boundary
+- rich fork/cache lifecycle beyond the current bounded local slice is a second-order optimization/runtime
+  broadening, not a missing core behavior
+- the current local transcript/session architecture is cleaner with parent-ledger
+  sidechain records than with copied cc per-agent directories
+
+Reopen only when:
+
+- a source-backed PRD shows a concrete need for background execution,
+  resumable forks, or cache-safe sibling execution beyond today's bounded child
+  runtime
+
+### 3. H19 Deferred Observability
+
+Deferred:
+
+- external analytics backend
+- Datadog / first-party telemetry exporters
+- Perfetto hierarchical tracing
+- SDK progress stream / TTFT forwarding
+- provider-specific cache / cost / billing instrumentation
+- analytics sampling / internal env enrichment
+- CLI dump flag (env-gated dumps already exist)
+
+Implemented and therefore not deferred:
+
+- queued runtime event sink
+- agent-scoped logger helper
+- compact attempted/succeeded split
+- `post_autocompact_turn` canary
+- `orphan_tombstoned`
+- structured `query_error`
+- per-turn `token_budget`
+- env-gated `CODING_DEEPGENT_DUMP_PROMPTS=1`
+
+Why deferred:
+
+- current local evidence/runtime-event seam already satisfies the MVP debugging
+  and recovery boundary
+- richer telemetry would add infra/provider coupling without changing local core
+  runtime correctness
+
+Reopen only when:
+
+- a new product goal requires latency tracing, external reporting, or provider
+  cost/cache decisions in-product
+
+### 4. H01 Deferred Tool Runtime Breadth
+
+Deferred:
+
+- streaming tool execution
+- non-streaming partition adapter unless proven necessary
+- dynamic hot-swap tool pool runtime
+- provider-specific shell/permission parity beyond current local policy
+
+Implemented and therefore not deferred:
+
+- five-factor capability contract
+- explicit projection/result seams
+- dynamic tool-pool projection foundation
+- `ToolSearch` plus `invoke_deferred_tool` bridge for deferred capabilities
+- pairing/failure tests
+- result persistence / microcompact audit
+
+Special `L5-a` decision:
+
+- `L4-a` research found that LangChain `ToolNode` already gives non-streaming
+  parallel execution with stable output order
+- therefore `L5-a` remains conditional/spec-only unless `L4-b` / `L4-c` or a
+  future runtime failure proves capability-aware partitioning is required
+
+Why deferred:
+
+- current LangChain-native surfaces already satisfy the baseline
+- adapter/runtime widening is not justified without a concrete local failure
+
+Reopen only when:
+
+- a source-backed PRD plus local failing tests show that capability-aware
+  concurrency partitioning is necessary
+
+### 5. H21 / H22 Remote And Proactive Runtime
+
+Deferred:
+
+- bridge / remote / IDE control plane
+- daemon / cron / proactive automation
+
+Why deferred:
+
+- these are explicit next-cycle product bands, not missing local harness
+  invariants
+- they introduce remote/process/scheduling boundaries that do not belong in the
+  current local MVP
+
+Reopen only when:
+
+- a new source-backed product goal explicitly targets remote/IDE or proactive
+  automation behavior
+
+## Do-Not-Copy Boundaries
+
+The following cc-haha details remain intentionally not copied into the local
+product:
+
+- React/TUI render surfaces
+- internal analytics export conventions
+- ant-specific support/debug affordances
+- provider-specific cache internals where no local product effect exists
+
+## Consequences
+
+- future agents should treat missing mailbox/coordinator/background/fork-cache
+  parity as intentional, not accidental
+- future implementation should favor the current local abstractions instead of
+  reintroducing cc-shaped runtime objects or bridge layers
+- if a future reopen happens, it must name the concrete local benefit and the
+  exact source evidence, not only "closer to cc"
+
+## Current Fastest Remaining Path
+
+Given the current state, the next remaining topology items are:
+
+- `L5-c` dashboard refresh
+- optional `L5-a` only if a new concrete failure appears
+
+Everything else in the current parent topology that was about H01/H11/H12/H19
+implementation is now closed.
diff --git a/.trellis/plans/coding-deepgent-full-cc-parity-roadmap.md b/.trellis/plans/coding-deepgent-full-cc-parity-roadmap.md
new file mode 100644
index 000000000..7c80bbacb
--- /dev/null
+++ b/.trellis/plans/coding-deepgent-full-cc-parity-roadmap.md
@@ -0,0 +1,340 @@
+# coding-deepgent Full CC Parity Roadmap
+
+Status: active canonical roadmap
+Updated: 2026-04-20
+Scope: `coding-deepgent/` product track only
+Supersedes as default planning target:
+
+* `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+* `.trellis/plans/coding-deepgent-deferred-boundary-refresh-adr.md`
+* MVP-only closeout guidance in `.trellis/project-handoff.md`
+
+## Purpose
+
+This roadmap replaces the old "stop at Approach A MVP" default with a new
+default direction:
+
+* pursue full Claude Code parity over time
+* keep implementation professional-grade and maintainable
+* keep LangChain/LangGraph-native boundaries where they do not block important
+  local product behavior
+* use a documented evidence ladder when source coverage is incomplete
+
+This is a roadmap and planning contract, not an implementation checklist.
+
+## Top-Level Target
+
+`coding-deepgent` should become a professional local coding agent whose:
+
+* model-visible behavior
+* runtime semantics
+* CLI/TUI interaction
+
+progressively approach real Claude Code public behavior, while:
+
+* using `cc-haha` as the primary open-source implementation reference
+* using high-quality analogous OSS systems when Claude Code behavior and
+  `cc-haha` source are insufficient
+* avoiding unnecessary provider-specific or closed-source cloning where it does
+  not create concrete local product value
+
+## Evidence Order
+
+Use this evidence order for all future parity work:
+
+1. **Real Claude Code public behavior**
+   - official docs
+   - public product surfaces
+   - reproducible visible behavior
+   - public runtime artifacts
+2. **`cc-haha` source-backed implementation reference**
+   - exact files, symbols, docs, comments, and observable behavior
+3. **High-quality analogous OSS**
+   - open-source systems implementing a similar capability family
+4. **Secondary analysis**
+   - books, blogs, or third-party interpretations
+
+Rules:
+
+* real Claude Code public behavior is the top-level parity target
+* `cc-haha` is the default implementation reference when it explains or matches
+  the target behavior
+* use analogous OSS only after documenting why levels 1 and 2 are insufficient
+* do not treat secondary analysis as stronger than available source or product
+  evidence
+
+## Missing-Source Fallback Rule
+
+When the target capability does not have enough accessible Claude Code or
+`cc-haha` source:
+
+1. state the exact missing behavior or source gap
+2. identify 2-4 high-quality OSS systems in the same capability family
+3. summarize how those systems solve the problem
+4. document the reusable essence vs project-specific detail
+5. choose the local design explicitly in the task PRD before implementation
+
+Required PRD note shape:
+
+```md
+## Source Gap
+
+- what behavior is targeted
+- what Claude Code evidence exists
+- what `cc-haha` evidence exists
+- why those are insufficient
+
+## Analogous OSS Review
+
+- project A: relevant implementation shape
+- project B: relevant implementation shape
+
+## Local Decision
+
+- chosen design
+- why it fits local product needs
+- what remains inferred rather than source-proven
+```
+
+## Candidate OSS Pool
+
+These are candidate fallback sources, not automatic parity targets:
+
+* `sst/opencode`
+  - terminal coding-agent runtime
+  - CLI/TUI interaction
+  - provider-agnostic architecture
+* `Aider-AI/aider`
+  - repository coding loop
+  - pragmatic edit/test/commit workflow
+  - codebase-map ergonomics
+* `OpenHands/OpenHands`
+  - agent SDK/runtime layering
+  - CLI/SDK split
+  - permissions and agent orchestration patterns
+* `google-gemini/gemini-cli`
+  - CLI agent behavior
+  - checkpoint/resume/context-file conventions
+  - MCP/tooling ergonomics
+* `block/goose`
+  - local agent architecture
+  - extension seams
+  - desktop/CLI/API multi-surface packaging
+
+## Circle 1: Local Daily-Driver Parity
+
+Circle 1 is the new default implementation target.
+
+### Included
+
+* single-agent local coding loop
+* runtime/tool/prompt/context/session/memory/task surfaces
+* local subagent and fork workflow
+* local CLI/TUI interaction required to expose these capabilities
+* local extension seams at "usable" depth only
+
+### Not Included In Circle 1
+
+* mailbox / `SendMessage`
+* coordinator / team-runtime synthesis
+* remote / IDE control plane
+* daemon / cron / proactive automation
+* full marketplace/install/enable/distribution experience for plugins
+
+### Circle 1 Acceptance Workflows
+
+Circle 1 is accepted primarily by workflow quality, not only by feature-band
+checklists.
+
+#### Workflow A: Repository Takeover And Sustained Coding
+
+Success standard: **PR-level independent completion**
+
+The agent should be able to:
+
+* inspect a medium-to-large codebase
+* form a short executable plan
+* edit code
+* run validation
+* handle normal interruptions and continue
+
+without requiring the user to micromanage every step.
+
+#### Workflow B: Long Session Continuity
+
+Success standard: **single-day long-task continuity**
+
+The agent should be able to:
+
+* survive multiple rounds of context pressure
+* compact/collapse/resume without losing the main thread
+* continue meaningful work after long local development sessions
+
+without requiring cross-day parity in Circle 1.
+
+#### Workflow C: Complex Task Decomposition
+
+Success standard: **personal-efficiency amplification**
+
+The agent should be able to use:
+
+* todo/task/plan discipline
+* bounded subagent/fork assistance
+
+to materially improve a single developer's throughput on complex tasks, without
+requiring full mailbox/coordinator/team-runtime parity.
+
+### Circle 1 Feature-Band Priorities
+
+#### Wave 1: Runtime-Core Parity
+
+Priority modules/bands:
+
+* `tool_system`
+* `permissions`
+* `prompting`
+* `runtime`
+* `compact`
+* `sessions`
+* `memory`
+* `todo`
+* `tasks`
+* `subagents`
+* `observability/evidence`
+
+Why first:
+
+* these determine whether the three acceptance workflows are stable
+* broad CLI/TUI polish will drift if these are still semantically weak
+
+#### Wave 2: Runtime-Exposing CLI/TUI Surfaces
+
+Priority surfaces:
+
+* resume/history/inspect/projection visibility
+* compact/collapse continuity UX
+* task/plan/subagent/fork interaction surfaces
+* permission and recovery interaction surfaces
+
+Why second:
+
+* Circle 1 still includes CLI/TUI parity
+* but the first CLI/TUI focus is on high-value runtime-exposing surfaces, not
+  broad aesthetic cloning
+
+Implemented checkpoint:
+
+* `2026-04-20`: first runtime-exposing surfaces pack
+  * `sessions inspect` exposes loaded-session recovery/projection/timeline/raw
+    visibility/session-memory state
+  * frontend protocol exposes `context_snapshot` and `subagent_snapshot`
+  * React/Ink CLI renders context, task, and subagent panels from typed reducer
+    state
+* `2026-04-20`: control surfaces pack
+  * local runtime store now has a `file` backend for process-surviving task/plan/background-run state in one workspace
+  * CLI now exposes durable `tasks/*` and `plans/*` control surfaces
+  * TUI bridge now exposes live background-subagent control for the active
+    frontend process
+* `2026-04-20`: final Wave 2/Circle 1 UX pack
+  * CLI exposes session history/projection/timeline/evidence/events/permissions
+    views
+  * CLI exposes local skills/MCP/hooks/plugins list/inspect/validate/debug
+    surfaces
+  * deterministic `acceptance circle1` harness records the Circle 1 workflow
+    boundary
+
+#### Wave 3: Usable Local Extension Seams
+
+Priority modules:
+
+* `skills`
+* `mcp`
+* `hooks`
+* `plugins`
+
+Circle 1 boundary:
+
+* local loading
+* local invocation
+* local debugging
+* source/trust/validation clarity
+
+Not required in Circle 1:
+
+* full install/enable lifecycle parity
+* distribution/marketplace experience
+
+Implemented checkpoint:
+
+* `2026-04-20`: usable local extension inspect/debug seams
+  * `skills`, `mcp`, `hooks`, and `plugins` have local CLI inspect/validate/debug
+    surfaces
+  * no marketplace, install/enable lifecycle, daemon, or remote extension
+    control was added
+
+## Circle 2: Expanded Product Parity
+
+Circle 2 begins only after Circle 1 is coherent enough to act as a daily-driver
+local coding agent.
+
+Canonical Circle 2 plan:
+
+* `.trellis/plans/coding-deepgent-circle-2-expanded-parity-plan.md`
+
+Implemented local baseline:
+
+* `2026-04-20`: local expanded parity baseline across event stream, worker
+  runtime, mailbox, teams, remote control records, extension lifecycle, and
+  continuity artifacts
+* hosted SaaS ingress, multi-user auth, public marketplace backend, and
+  cross-machine workers remain outside this local baseline unless explicitly
+  reopened
+
+Likely Circle 2 bands:
+
+* mailbox / `SendMessage`
+* coordinator synthesis
+* richer background team-runtime
+* remote / IDE control plane
+* daemon / cron / proactive automation
+* broader extension ecosystem lifecycle
+* stronger cross-day continuity and richer session-memory extraction
+
+## Historical References
+
+These remain useful, but they are no longer the default planning destination:
+
+* `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+* `.trellis/plans/coding-deepgent-deferred-boundary-refresh-adr.md`
+* `.trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/prd.md`
+* `.trellis/tasks/archive/2026-04/04-19-backend-next-step-roadmap/prd.md`
+
+## Planning Gate
+
+Before any new parity implementation starts, the proposal must state:
+
+1. which Circle it belongs to
+2. which acceptance workflow(s) it improves
+3. the target Claude Code behavior
+4. the `cc-haha` source evidence, if available
+5. whether OSS fallback research was needed
+6. which layers must match behavior:
+   - model-visible behavior
+   - runtime semantics
+   - CLI/TUI interaction
+7. which layers may remain LangChain-native:
+   - hidden implementation
+   - provider-specific plumbing
+   - non-essential product detail
+
+Do not propose work using only the phrase "closer to cc".
+
+## Current Next Step
+
+The next planning step after this roadmap is:
+
+* start Circle 1 / Wave 2 runtime-exposing CLI/TUI surfaces
+* keep `.trellis/plans/coding-deepgent-circle-1-wave-1-runtime-core-plan.md`
+  as the completed Wave 1 runtime-core checkpoint
+* do not reopen Wave 1 unless a concrete regression or daily-driver blocker
+  appears
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..09525e294
--- /dev/null
+++ b/.trellis/plans/coding-deepgent-h01-h10-target-design.md
@@ -0,0 +1,741 @@
+<!-- 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: `.trellis/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.
+
+Planning direction:
+
+- product context should now be reasoned about as four layers:
+  - project-level rules
+  - long-term memory
+  - current-session memory
+  - recovery context
+
+### 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 project-level rules as a distinct layer before long-term memory.
+- 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:
+
+- four long-term memory types: user / feedback / project / reference
+- structured save/list/delete long-term memory tools
+- bounded store-backed recall and render
+- feedback rules can directly affect a few high-value actions
+- long-term memory appears in recovery/resume as its own section
+- current-session memory appears in recovery/resume as a separate section
+- planning baseline now treats product-level rules as a separate layer rather than folding them into memory
+
+Missing:
+
+- no durable long-term memory backend yet
+- no auto-suggested memory extraction from conversation
+- no subagent/private memory boundary yet
+- no richer freshness/relevance scoring beyond bounded deterministic recall
+
+### Target design
+
+Memory stores durable, reusable, non-derivable knowledge and preferences.
+
+Do:
+
+- Keep long-term memory and current-session memory visibly separate.
+- 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
+
+Integrated memory closeout in progress: long-term memory and current-session
+memory are now two explicit product layers.
+
+### Future Functional Roadmap
+
+Later memory work should be framed in terms of what the user will gain:
+
+- memory survives restart and can still be reviewed/edited later
+- the system can suggest when a user correction or project fact is worth saving
+- sub-tasks or child agents can continue with their own remembered context
+- outdated or low-value remembered items can be cleaned up automatically
+- the system can find the most relevant remembered item faster when the history grows
+
+## 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-h01-tool-module-alignment-plan.md b/.trellis/plans/coding-deepgent-h01-tool-module-alignment-plan.md
new file mode 100644
index 000000000..5880726b7
--- /dev/null
+++ b/.trellis/plans/coding-deepgent-h01-tool-module-alignment-plan.md
@@ -0,0 +1,398 @@
+# coding-deepgent H01 Tool Module Alignment Plan
+
+Status: draft
+Scope: `coding-deepgent/` H01 Tool-first capability runtime
+Created: 2026-04-17
+
+## Purpose
+
+This plan consolidates the H01 tool-module discussion into an implementation
+roadmap. It translates cc-haha tool-system highlights into a LangChain/LangGraph
+native `coding-deepgent` direction without copying cc-haha's TypeScript runtime
+objects, React rendering surface, or streaming tool executor.
+
+The goal is to make the local tool system strong enough to support later cc
+highlights, especially:
+
+* H11/H12 agent-as-tool and subagent execution
+* H15/H16/H17 skills, MCP, and plugins
+* H08/H09/H10 task, plan, and verifier tools
+* H05/H06 context pressure and session continuity around tool results
+
+## Source Anchors
+
+cc-haha source and docs used for this plan:
+
+* `/root/claude-code-haha/src/Tool.ts`
+* `/root/claude-code-haha/src/tools.ts`
+* `/root/claude-code-haha/src/constants/tools.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/src/tools/ToolSearchTool/ToolSearchTool.ts`
+* `/root/claude-code-haha/src/tools/ToolSearchTool/prompt.ts`
+* `/root/claude-code-haha/src/utils/toolResultStorage.ts`
+* `/root/claude-code-haha/src/utils/groupToolUses.ts`
+* `/root/claude-code-haha/docs/must-read/01-execution-engine.md`
+* `/root/claude-code-haha/docs/modules/01-execution-engine-deep-dive.md`
+
+Local source/spec anchors:
+
+* `coding-deepgent/src/coding_deepgent/tool_system/capabilities.py`
+* `coding-deepgent/src/coding_deepgent/tool_system/middleware.py`
+* `coding-deepgent/src/coding_deepgent/tool_system/policy.py`
+* `.trellis/spec/backend/tool-capability-contracts.md`
+* `.trellis/spec/backend/tool-result-storage-contracts.md`
+* `.trellis/spec/backend/langchain-native-guidelines.md`
+
+## Current Decisions
+
+### Adopt
+
+* Adopt the five-factor tool protocol:
+  * `name`
+  * `schema`
+  * `permission`
+  * `execution`
+  * `rendering_result`
+* Use `ToolCapability` as the local carrier for cc harness metadata not encoded
+  by LangChain tools.
+* Keep defaults conservative:
+  * not read-only unless proven
+  * not concurrency-safe unless proven
+  * not trusted unless validated
+  * not large-output/microcompact eligible unless explicitly opted in
+* Keep capability-driven middleware/projection instead of tool-name special
+  cases.
+* Keep LangChain `@tool`, `ToolRuntime`, middleware, `ToolMessage`, and
+  `Command(update=...)` as the primary runtime expression.
+
+### Defer
+
+* Full `StreamingToolExecutor` parity.
+* Partial `tool_use` execution while model output is still streaming.
+* UI grouped rendering parity.
+* Full ToolSearch/deferred schema loading implementation.
+* Complex Bash/PowerShell safety parity.
+* Classifier, sandbox, and interactive permission dialog.
+* Bun dead-code elimination mechanics.
+* Embedded search tool replacement.
+
+## Near-Term Implementation Package
+
+Recommended package name:
+
+```text
+H01 tool capability and execution contract hardening
+```
+
+This package should be planned and implemented as one high-cohesion batch after
+the broader highlight planning is complete.
+
+### Included Subplans
+
+#### 1. Five-Factor Capability Audit
+
+Expected effect:
+
+* Every registered model-facing tool is explainable through
+  `name/schema/permission/execution/rendering_result`.
+* Future skills/MCP/plugins/subagents can register tools without bypassing the
+  core capability protocol.
+
+Local target:
+
+* Audit all current `ToolCapability` entries.
+* Add tests that capability name equals actual LangChain tool name.
+* Add tests that every main/child/extension tool has capability metadata.
+* Keep `.trellis/spec/backend/tool-capability-contracts.md` as the owning spec.
+
+Do not:
+
+* Recreate cc-haha's TS `Tool` interface.
+* Add speculative fields that no local behavior consumes.
+
+#### 2. Role-Based Tool Projection
+
+Expected effect:
+
+* Main agent, verifier child, general child, future coordinator, and extension
+  surfaces can receive different tool sets through one projection mechanism.
+* Recursive or privileged tools can be blocked from child contexts without
+  ad hoc allowlists.
+
+Local target:
+
+* Define stable projection categories:
+  * `main`
+  * `child_only`
+  * `extension`
+  * future `deferred`
+* Review and test:
+  * main tool surface
+  * verifier child allowlist
+  * general child allowlist
+  * extension declarable names
+* Ensure projection consumes `ToolCapability` metadata.
+
+Do not:
+
+* Hard-code future coordinator/mailbox behavior before H13/H14 are reopened.
+
+#### 3. Dynamic Tool Pool Foundation
+
+Expected effect:
+
+* The local runtime treats tool availability as a projected capability surface,
+  not as a fixed global list.
+* Later MCP/plugin/skill/subagent work can change visible tools without
+  reworking agent wiring.
+
+Local target:
+
+* Keep the initial implementation as projection and validation, not runtime
+  hot-swapping.
+* Make tool source/trust/exposure visible through registry metadata.
+* Document future ToolSearch/deferred schema as an explicit extension of this
+  foundation.
+
+Do not:
+
+* Implement full ToolSearch in this package.
+* Implement prompt-cache-aware schema layout here.
+
+#### 4. Non-Streaming Concurrent Tool Partitioning
+
+Expected effect:
+
+* When multiple complete tool calls are available in one model response,
+  concurrency-safe tools may run concurrently and unsafe tools run serially or
+  exclusively.
+* Results are emitted in original tool-call order.
+* The orchestration layer consumes `ToolCapability.concurrency_safe` and
+  mutation metadata, not hard-coded tool names.
+
+Local target:
+
+* First run a LangChain research spike:
+  * confirm current `create_agent` / tool node behavior for parallel tool calls
+  * confirm whether middleware order, `Command(update=...)`, and result order are
+    controllable without custom execution
+* If LangChain already satisfies the requirement, add tests/spec only.
+* If not, design a thin adapter that preserves:
+  * `ToolGuardMiddleware`
+  * permissions
+  * hooks
+  * large-output persistence
+  * runtime events/evidence
+
+Do not:
+
+* Implement streaming tool-use execution.
+* Bypass LangChain tool runtime with a custom query loop.
+
+#### 5. Tool Use / Tool Result Pairing Contract
+
+Expected effect:
+
+* Every tool result remains paired with the originating tool call.
+* Compact, resume, runtime pressure, and future orchestration cannot orphan
+  `tool_use` or `tool_result` messages.
+
+Local target:
+
+* Promote pairing as an H01 invariant in tests/spec.
+* Reuse existing compact tool-pair preservation logic.
+* Add focused tests for result ordering if a concurrency adapter is introduced.
+
+Do not:
+
+* Implement complete orphan/duplicate/fallback repair unless a concrete runtime
+  failure appears.
+
+#### 6. Protocol-Correct Tool Failures
+
+Expected effect:
+
+* Tool failure remains model-consumable and does not corrupt the runtime loop.
+* Unknown tool, schema failure, permission denial, hook block, and tool exception
+  produce a bounded, protocol-correct result.
+
+Local target:
+
+* Keep failure results as `ToolMessage` or documented `Command(update=...)`.
+* Ensure failures can emit bounded runtime/session evidence where appropriate.
+* Avoid raw traceback or unbounded tool output in model-visible results.
+
+Do not:
+
+* Implement interactive permission approval in this package.
+
+#### 7. Tool Result / Context Pressure Continuity
+
+Expected effect:
+
+* Large tool results, preview paths, and microcompact eligibility remain driven
+  by capability metadata.
+* Future context pressure work can hide old tool output without losing important
+  restoration paths.
+
+Local target:
+
+* Keep `persist_large_output`, `max_inline_result_chars`, and
+  `microcompact_eligible` tied to `ToolCapability`.
+* Preserve existing large-output persistence tests.
+* Add review checks when new tools opt into persistence or microcompact.
+
+Do not:
+
+* Rework context compression in this H01 package.
+
+## Deferred Backlog
+
+### Deferred: Streaming Tool Execution
+
+cc-haha's `StreamingToolExecutor` is a real runtime highlight, but it is too
+large for the current implementation package.
+
+Documented future constraints:
+
+* Do not design the non-streaming orchestration adapter in a way that makes
+  streaming impossible later.
+* Future streaming work must preserve:
+  * progress
+  * cancellation
+  * sibling failure handling
+  * ordered result yielding
+  * middleware and permission boundaries
+
+Reopen only when:
+
+* there is a concrete latency/product need
+* LangChain cannot satisfy it through official runtime surfaces
+
+### Deferred: Full ToolSearch / Deferred Schema Loading
+
+ToolSearch is important for MCP/plugin-heavy futures, but not required before
+tool protocol, role projection, and extension source/trust metadata are stable.
+
+Reopen when:
+
+* model-visible tool schemas become large enough to pressure prompts/cache
+* MCP/plugin tool count materially increases
+* dynamic tool discovery becomes a user-visible need
+
+### Deferred: Full Shell Permission Parity
+
+The current direction is simple safety plus extensible permission seams.
+
+Reopen when:
+
+* subagent or MCP execution substantially increases shell risk
+* Bash tool usage becomes a primary product path
+* explicit user requirement raises permission hardening priority
+
+### Deferred: Renderer / Grouped Tool UI
+
+Grouped rendering and React-specific render surfaces are UI concerns. The local
+backend should keep result contracts bounded and renderer-friendly, but does not
+need cc UI parity.
+
+## Suggested Task Decomposition
+
+When implementation begins, create one parent Trellis task and child tasks:
+
+```text
+Parent: H01 tool capability and execution contract hardening
+
+Child 1: capability audit and projection tests
+Child 2: role-based tool projection foundation
+Child 3: LangChain parallel tool-call research spike
+Child 4: non-streaming concurrency partition adapter, only if research requires it
+Child 5: tool-use/result pairing and protocol-correct failure tests
+Child 6: result persistence/microcompact eligibility review
+```
+
+Recommended order:
+
+1. Child 1
+2. Child 2
+3. Child 3
+4. Child 4 only if needed
+5. Child 5
+6. Child 6
+
+## Verification Matrix
+
+| Area | Required proof |
+|---|---|
+| capability protocol | every registered tool has correct five-factor metadata |
+| safe defaults | unsafe/unknown/untrusted tools do not get read/concurrent/persist privileges |
+| projection | main/child/verifier/extension tool surfaces are stable |
+| concurrency | concurrent-safe tools can run without order corruption; unsafe tools remain exclusive |
+| pairing | `tool_use` / `tool_result` relationship is preserved under projection/compact/orchestration |
+| failures | unknown/schema/permission/hook/tool failures return bounded model-consumable results |
+| result pressure | persistence and microcompact are metadata-driven and opt-in |
+
+Focused test families:
+
+* `coding-deepgent/tests/tool_system/test_tool_system_registry.py`
+* `coding-deepgent/tests/tool_system/test_tool_system_middleware.py`
+* `coding-deepgent/tests/filesystem/test_tools.py`
+* `coding-deepgent/tests/tasks/test_tasks.py`
+* `coding-deepgent/tests/subagents/test_subagents.py`
+* `coding-deepgent/tests/extensions/test_mcp.py`
+* `coding-deepgent/tests/tool_system/test_tool_result_storage.py`
+* `coding-deepgent/tests/compact/test_runtime_pressure.py`
+
+## Discussion Status
+
+This recommendation has already been consumed by the 2026-04-17 alignment
+discussion.
+
+Historical next module after H01:
+
+```text
+H15/H16/H17: Skill / MCP / Plugin extension platform
+```
+
+Why:
+
+* It directly consumes the H01 tool capability protocol.
+* It stress-tests source/trust/exposure metadata.
+* It determines whether dynamic tool pool and deferred ToolSearch are real near
+  term needs or only future options.
+* It should be resolved before deeper H11/H12 subagent work, because subagents
+  need a clear answer for which external capabilities they can see and trust.
+
+Suggested discussion order:
+
+1. H15/H16/H17 Skills, MCP, Plugin extension platform
+2. H11/H12 Agent-as-tool and subagent context/fork model
+3. H08/H09/H10 Todo, Task, Plan, Verify workflow
+4. H03-H07/H20 Context, session, memory, compact, cost/cache revisit
+
+Current execution handoff:
+
+* H15/H16/H17 are resolved as baseline-only.
+* H11/H12 requirements are resolved enough for the current implementation line.
+* Do not create another H01 parent task.
+* Use `.trellis/tasks/04-17-cc-core-topology-closeout-plan/` as the parent.
+* H01 child 1, `04-17-l1c-h01-five-factor-capability-audit`, is complete.
+* Next H01-specific entry point is `04-17-l2c-h01-role-based-tool-projection`, after the `L2-a` subagent dependency lands.
+
+## Implementation Gate
+
+Status: **cleared 2026-04-17**.
+
+Previously blocked on:
+
+* H15/H16/H17 confirm whether tool protocol needs additional fields → **resolved**: user decision is "baseline only", no additional fields required.
+* H11/H12 confirm subagent tool-protocol needs → **resolved**: H11/H12 alignment research finalized sidechain + result envelope; tool protocol does not need additional fields beyond current `ToolCapability` five-factor set.
+* LangChain parallel tool-call research scoped → **remaining**: child 3 (research spike) is now the entry point for that scoping.
+* Implementation package has Trellis PRD, spec context, and focused test matrix → **resolved**: child task `04-17-l1c-h01-five-factor-capability-audit` is complete; downstream H01 work resumes at `L2-c` after `L2-a`.
+
+Gate lifted. Do not create another parent task. The topology's next overall
+entry point is `04-17-l2a-h11-h12-agent-definition-general-runtime`; the next
+H01-specific entry point is `04-17-l2c-h01-role-based-tool-projection` after
+`L2-a` lands.
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..cbb1ac57a
--- /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: `.trellis/plans/prd-coding-deepgent-runtime-foundation.md` and `.trellis/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/README.md`, `coding-deepgent/PROJECT_PROGRESS.md`, `coding-deepgent/project_status.json`, and migrated Trellis planning/spec docs
diff --git a/.trellis/plans/index.md b/.trellis/plans/index.md
new file mode 100644
index 000000000..1344731ee
--- /dev/null
+++ b/.trellis/plans/index.md
@@ -0,0 +1,44 @@
+# Trellis Plans Index
+
+> Long-lived product direction and planning memory for the current `coding-deepgent` mainline.
+
+Use these through Trellis instead of the removed `.omx/` tree.
+
+Plans own direction, sequencing, roadmap state, product tradeoffs, and milestone
+boundaries. Executable implementation rules should be extracted into
+`.trellis/spec/` when they become mandatory for future work.
+
+## Canonical Planning Files
+
+| File | Role | When to read |
+|---|---|---|
+| `coding-deepgent-cc-core-highlights-roadmap.md` | Canonical H01-H22 highlight dashboard and MVP/future boundary | Before choosing or changing mainline roadmap work |
+| `coding-deepgent-h01-tool-module-alignment-plan.md` | H01 tool-module alignment plan: five-factor tool protocol, projection, non-streaming concurrency, and deferred ToolSearch/streaming boundaries | Before implementing or reviewing tool-system, MCP/plugin/skill tool registration, or subagent tool surfaces |
+| `coding-deepgent-h01-h10-target-design.md` | Source-backed target design for the first highlight band | When implementing or reviewing H01-H10-related behavior |
+| `master-plan-coding-deepgent-reconstructed.md` | Reconstructed product identity, architecture baseline, and stage model | When re-orienting after plan loss or checking long-term direction |
+| `prd-coding-deepgent-runtime-foundation.md` | Runtime foundation PRD and architecture constraints | When touching runtime/container/domain skeleton boundaries |
+| `test-spec-coding-deepgent-runtime-foundation.md` | Runtime foundation verification plan | When auditing or rebuilding foundation validation |
+
+## Supporting Planning Files
+
+| File | Role | Notes |
+|---|---|---|
+| `coding-deepgent-runtime-foundation-20260412T213209Z.md` | Recovered context snapshot | Provenance/supporting context, not the primary roadmap |
+| `runtime-foundation-recovery-notes-2026-04-14.md` | Recovery notes from plan migration | Historical recovery context |
+
+## Source-Backed Alignment Research
+
+Research artifacts live in the brainstorm task directory, not in `plans/`, but
+are referenced here so implementers can find them from the planning index:
+
+| File | Covered highlights | Notes |
+|---|---|---|
+| `.trellis/tasks/04-16-cc-highlight-alignment-discussion/h11-h12-alignment-research.md` | H11 Agent-as-tool / H12 Fork/cache subagent | Gap matrix + sub-task decomposition (A general runtime + catalog, B sidechain transcript, C deferred ADR) |
+| `.trellis/tasks/04-16-cc-highlight-alignment-discussion/h19-observability-alignment-research.md` | H19 Observability / evidence ledger | Gap matrix + Stage 28 closeout scope (A1 queued sink, B2/B3/B4 compact events, B6 query_error, B8 token_budget, C1 API dump, E1 logger) |
+
+## Maintenance Rules
+
+- Keep this index short and navigational.
+- Update the roadmap/dashboard before creating new stage plans.
+- Promote reusable implementation constraints into `.trellis/spec/`.
+- Do not make plans the only place a future agent can find mandatory coding rules.
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..e5cd01f25
--- /dev/null
+++ b/.trellis/plans/master-plan-coding-deepgent-reconstructed.md
@@ -0,0 +1,238 @@
+<!-- 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.
+
+Some evidence originally came from removed `.omx/...` locations. The paths
+listed below are the surviving `.trellis/plans/...` copies that future work
+should actually read.
+
+Primary evidence:
+- `.trellis/plans/prd-coding-deepgent-runtime-foundation.md`
+- `.trellis/plans/test-spec-coding-deepgent-runtime-foundation.md`
+- `.trellis/plans/coding-deepgent-runtime-foundation-20260412T213209Z.md`
+- `.trellis/plans/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/.trellis/plans/prd-coding-deepgent-runtime-foundation.md)
+- [Runtime Foundation Test Spec](/root/learn-claude-code/.trellis/plans/test-spec-coding-deepgent-runtime-foundation.md)
+- [Recovery Notes](/root/learn-claude-code/.trellis/plans/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..eb94d006a
--- /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: `.trellis/plans/coding-deepgent-runtime-foundation-20260412T213209Z.md`
+Test spec: `.trellis/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`
+- `coding-deepgent/tests/structure/test_structure.py`
+- `coding-deepgent/tests/structure/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 coding-deepgent/src/coding_deepgent 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" coding-deepgent/src/coding_deepgent/todo coding-deepgent/src/coding_deepgent/filesystem coding-deepgent/src/coding_deepgent/sessions coding-deepgent/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" coding-deepgent/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 .trellis/plans/prd-coding-deepgent-runtime-foundation.md .trellis/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 .trellis/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..405e7b078
--- /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:
+- `.trellis/plans/prd-coding-deepgent-runtime-foundation.md`
+- `.trellis/plans/test-spec-coding-deepgent-runtime-foundation.md`
+- `.trellis/plans/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 `.trellis/plans/` and `.trellis/plans/` 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..fd6b193b3
--- /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 `.trellis/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 coding-deepgent/src/coding_deepgent coding-deepgent/tests
+```
+
+## 2. Dependency and Tooling Tests
+
+Files:
+- `pyproject.toml`
+- `coding-deepgent/tests/structure/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 `coding-deepgent/tests/runtime/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 `coding-deepgent/tests/config/test_settings.py`
+- Update `coding-deepgent/tests/config/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 `coding-deepgent/tests/structure/test_structure.py`
+- Update `coding-deepgent/tests/structure/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:
+- `coding-deepgent/tests/runtime/test_runtime_context.py`
+- `coding-deepgent/tests/runtime/test_runtime_state.py`
+- `coding-deepgent/tests/runtime/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:
+- `coding-deepgent/tests/tasks/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:
+- `coding-deepgent/tests/filesystem/test_filesystem_domain.py`
+- `coding-deepgent/tests/tool_system/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:
+- `coding-deepgent/tests/tool_system/test_tool_system_capabilities.py`
+- `coding-deepgent/tests/tool_system/test_tool_system_policy.py`
+- `coding-deepgent/tests/tool_system/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:
+- `coding-deepgent/tests/sessions/test_sessions.py`
+- optional `coding-deepgent/tests/sessions/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:
+- `coding-deepgent/tests/cli/test_cli.py`
+- optional `coding-deepgent/tests/cli/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:
+- `coding-deepgent/tests/runtime/test_runtime_events.py`
+- optional `coding-deepgent/tests/config/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 coding-deepgent/tests/cli/test_cli.py coding-deepgent/tests/runtime/test_app.py coding-deepgent/tests/sessions/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" coding-deepgent/src/coding_deepgent/todo coding-deepgent/src/coding_deepgent/filesystem coding-deepgent/src/coding_deepgent/sessions coding-deepgent/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" coding-deepgent/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..210e806b7
--- /dev/null
+++ b/.trellis/project-handoff.md
@@ -0,0 +1,349 @@
+# coding-deepgent Project Handoff
+
+Updated: 2026-04-20
+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 progressively approach real
+Claude Code public behavior in a professional local coding-agent product, while
+using:
+
+* `cc-haha` as the primary open-source implementation reference
+* LangChain/LangGraph-native architecture for hidden implementation where that
+  does not block important local product behavior
+
+The old `Approach A MVP` line is now historical baseline evidence, not the
+default stop condition.
+
+Canonical goal/backlog docs:
+
+* `.trellis/tasks/archive/2026-04/04-14-redefine-coding-deepgent-final-goal/prd.md`
+* `.trellis/plans/coding-deepgent-full-cc-parity-roadmap.md`
+* `.trellis/plans/coding-deepgent-circle-2-expanded-parity-plan.md`
+* `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md` (historical MVP dashboard)
+
+## Minimal Resume Procedure
+
+Use this file as the canonical Trellis replacement for the old
+`project-handoff` skill.
+
+When starting a new `coding-deepgent` session, do this in order:
+
+1. Read this file.
+2. Read only these canonical docs:
+   * `.trellis/tasks/archive/2026-04/04-14-redefine-coding-deepgent-final-goal/prd.md`
+   * `.trellis/plans/coding-deepgent-full-cc-parity-roadmap.md`
+   * `coding-deepgent/PROJECT_PROGRESS.md`
+   * `.trellis/spec/guides/cc-alignment-guide.md`
+   * `.trellis/spec/backend/runtime-context-compaction-contracts.md`
+   * `.trellis/spec/backend/task-workflow-contracts.md`
+3. Refresh live state only with:
+   * `git branch --show-current`
+   * `git status -sb`
+   * `gh pr view 220 --repo shareAI-lab/learn-claude-code --json number,title,url,isDraft,headRefName,baseRefName`
+4. Read latest stage PRDs only if a real ambiguity remains.
+
+## Update Policy
+
+Update this handoff only when mainline resume context materially changes.
+
+Update it when:
+
+* current mainline stage family changes
+* canonical roadmap/dashboard status changes
+* latest verified state changes
+* next recommended task changes
+* a new cross-session product requirement becomes canonical
+* the minimal resume reading order changes
+
+Do not update it for ordinary daily progress, minor implementation notes, or
+session summaries. Those belong in workspace journals via `record-session`.
+
+This file is a compact resume entrypoint, not a full project history.
+
+## Current Mainline
+
+Current mainline historical baseline has focused on:
+
+* context / compact / session / recovery hardening
+* durable task / workflow hardening
+* cc-highlight topology closeout for H01, H11/H12, and H19
+
+Current default direction has now changed:
+
+* treat the MVP closeout line as verified baseline
+* stop using MVP closeout as the default product finish line
+* begin Circle 1 of the full local daily-driver parity roadmap
+* prioritize runtime/core parity before broad CLI/TUI polish
+* evaluate progress primarily through three representative workflows rather
+  than only by highlight checklist closeout
+
+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
+* 2026-04-17 H19 Vertical Closeout
+* 2026-04-17 H01 L1-c Capability Audit
+
+## 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 as one bounded local fork/continuity slice; rich fork/cache parity is still 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
+* `2026-04-17 H19 vertical closeout`: observability/evidence cleanup
+  * `L1-b`, `L2-b`, and `L3-b` are complete under `.trellis/tasks/04-17-cc-core-topology-closeout-plan/`
+  * H19 now includes queued `RuntimeEventSink`, agent-scoped logger, AutoCompact attempted/succeeded events, `post_autocompact_turn` canary metrics, `orphan_tombstoned` projection repair, structured `query_error`, per-turn `token_budget`, and env-gated `CODING_DEEPGENT_DUMP_PROMPTS=1` dumps
+  * External analytics backend, Perfetto, SDK/TTFT progress, provider cache/cost, and CLI dump flag remain deferred and should be covered by `L5-b` ADR refresh
+* `2026-04-17 H01 L1-c capability audit`: five-factor tool metadata cleanup
+  * `ToolCapability` now carries explicit five-factor metadata, including `rendering_result`
+  * capability registry validation enforces name/schema/metadata/exposure and large-output/microcompact opt-in invariants
+  * downstream H01 role projection, dynamic pool, pairing, and concurrency work remain open
+* `2026-04-17/18 H01/H11/H12 closeout follow-through`
+  * `H11` now has `AgentDefinition`, a real read-only `general` child runtime, structured subagent result envelopes, and sidechain transcript audit in the parent session ledger
+  * `H01` now has role-based projection, explicit `ToolPoolProjection`, pairing/failure regressions, and result-persistence/microcompact audit closeout
+* `2026-04-18 deferred-boundary ADR refresh`
+  * `.trellis/plans/coding-deepgent-deferred-boundary-refresh-adr.md` supersedes the old Stage 29 deferred note for H11/H12/H19/H01-adjacent deferred items
+  * `L5-a` is now explicitly conditional/spec-only unless later tests reveal a real capability-aware partitioning gap
+* `2026-04-19 backend-next-step Stage 1/2 closeout`
+  * H01 now includes `ToolSearch` plus `invoke_deferred_tool` so deferred builtin and MCP capabilities can stay off the initial main tool list while remaining discoverable and executable through the shared policy/middleware path
+  * advanced subagent lifecycle controls (`run_subagent_background`, `subagent_status`, `subagent_send_input`, `subagent_stop`, `resume_subagent`, `resume_fork`) now live on the deferred discovery surface instead of the initial main tool surface
+  * MCP capabilities now default to the deferred discovery surface, while preserving source/trust metadata and registry validation
+* `2026-04-20 Circle 1 Wave 2 runtime-exposing surfaces pack`
+  * `coding-deepgent sessions inspect` renders loaded-session metadata, recovery brief, selected raw/compact/collapse projection mode, compression timeline, model projection rows, raw transcript visibility, and current-session memory freshness
+  * frontend protocol now includes `context_snapshot` and `subagent_snapshot` events so runtime projection and sidechain activity can reach renderer-neutral consumers without exposing raw JSONL records
+  * React/Ink CLI now renders context, durable task, and subagent panels from reducer state in addition to todo, permission, message, and recovery surfaces
+* `2026-04-20 Circle 1 Wave 2 control surfaces pack`
+  * runtime store now has a local `file` backend, making task/plan/runtime-store state survive process boundaries inside one workspace
+  * `coding-deepgent tasks ...` and `coding-deepgent plans ...` now provide real user-facing control over the durable task/plan store
+  * frontend bridge now supports `refresh_snapshots`, `run_background_subagent`, `subagent_send_input`, and `subagent_stop` for the active TUI process, plus `background_subagent_snapshot` visibility
+* `2026-04-20 Circle 1 completion pack`
+  * `coding-deepgent sessions history|projection|timeline|evidence|events|permissions` expose resume/history/projection/recovery state without raw JSONL inspection
+  * `coding-deepgent skills|mcp|hooks|plugins list|inspect|validate|debug` expose usable local extension inspect/debug seams
+  * `coding-deepgent acceptance circle1` records the deterministic local Circle 1 acceptance boundary for workflows A/B/C
+* `2026-04-20 Circle 2 planning`
+  * `.trellis/plans/coding-deepgent-circle-2-expanded-parity-plan.md` defines the substrate-first Circle 2 execution sequence
+  * Circle 2 Wave 1 should start with durable daemon/worker/event substrate before mailbox/coordinator/remote features
+* `2026-04-20 Circle 2 expanded parity local baseline`
+  * local durable domains now exist for `event_stream`, `worker_runtime`, `mailbox`, `teams`, `remote`, `extension_lifecycle`, and `continuity`
+  * CLI surfaces now cover events, workers, mailbox, teams, remote records/replay, extension lifecycle, continuity artifacts, and `acceptance circle2`
+  * this is a local baseline and intentionally does not claim hosted SaaS ingress, multi-user auth, public marketplace backend, or cross-machine workers
+
+## Current Active Topology
+
+Use this as the current planning entry point:
+
+* Parent task: `.trellis/tasks/04-17-cc-core-topology-closeout-plan/`
+* Done: `L1-b`, `L1-c`, `L2-a`, `L2-b`, `L2-c`, `L3-a`, `L3-b`, `L3-c`, `L4-a`, `L4-b`, `L4-c`, `L5-b`, `L5-c`
+* Remaining: no required topology implementation items are open
+* `L5-a` remains conditional only and should stay dormant unless a concrete concurrency-partition failure is discovered
+
+## 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:
+
+* Circle 1 and Circle 2 local baselines are implemented
+* release / PR validation has been completed against
+  `coding-deepgent acceptance circle1` / `circle2`
+* further parity after this baseline should explicitly target hosted remote
+  ingress, true daemon supervision, multi-user/auth control, or marketplace
+  backend only if requested
+
+Intent:
+
+* use real Claude Code public behavior as the top-level target
+* use `cc-haha` as the default open-source reference
+* use OSS fallback research when both are insufficient
+* keep Circle 1 focused on local daily-driver parity, not mailbox/team-runtime or remote/daemon surfaces
+* do not reopen Wave 1 runtime-core scope unless a regression or concrete
+  daily-driver blocker appears
+
+## Planning Gate
+
+Before any new stage implementation begins, the proposal must state:
+
+* the Circle (`Circle 1` or later) it belongs to
+* the representative workflow(s) it improves
+* the concrete function being added or changed
+* the concrete user/system benefit it brings
+* the target Claude Code behavior
+* the `cc-haha` source evidence when available
+* whether OSS fallback research was needed
+* why the benefit is worth the added complexity now
+
+“Closer to cc” alone is not sufficient; the proposal must name the target
+behavior and evidence tier.
+
+## Persistent User Requirement
+
+Cross-session memory is a product requirement.
+
+Refactor posture is also a product requirement for current transcript/context
+engineering work:
+
+* do not prioritize compatibility with old local schema/design when that blocks
+  a cleaner long-term foundation
+* do not add fallback paths only to preserve legacy local data shapes
+* prefer durable long-term architecture and clean domain boundaries over
+  minimizing short-term blast radius
+* when a transcript/runtime foundation choice is ambiguous, bias toward the
+  design that better supports future compact/collapse/timeline infrastructure
+  even if it requires replacing current local abstractions
+
+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
+* transcript/context refactors may replace current local compact/count/index
+  designs instead of preserving them as compatibility bridges
+* old local data compatibility is not a default requirement unless the user
+  explicitly reintroduces it later
+
+Delivery preference for current planning:
+
+* for high-value, strongly coupled feature families with a clear boundary,
+  prefer one integrated optimization pass over artificially tiny visible
+  increments
+* keep internal checkpoints and evidence, but do not present work as
+  "toothpaste squeezing" when the family can be completed safely in one run
+* only split the family when a real safety, architecture, or verification
+  blocker appears
+
+## 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 Trellis `lean` staged-execution 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
+
+For the checkpoint state machine and `continue / adjust / split / stop`
+discipline, use `.trellis/spec/guides/staged-execution-guide.md`.
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/check_trellis_links.py b/.trellis/scripts/check_trellis_links.py
new file mode 100644
index 000000000..aeda401a9
--- /dev/null
+++ b/.trellis/scripts/check_trellis_links.py
@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Smoke-check local Markdown links inside .trellis docs."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+from urllib.parse import unquote
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+TRELLIS_ROOT = REPO_ROOT / ".trellis"
+LINK_RE = re.compile(r"(?<!!)\[[^\]]+\]\(([^)]+)\)")
+
+
+def _target_path(source: Path, raw: str) -> Path | None:
+    target = raw.strip()
+    if not target or target.startswith(("#", "http://", "https://", "mailto:")):
+        return None
+    target = target.split("#", 1)[0].strip()
+    if not target:
+        return None
+    target = unquote(target)
+    if target.startswith("<") and target.endswith(">"):
+        target = target[1:-1]
+    path = Path(target)
+    if path.is_absolute():
+        return path
+    return (source.parent / path).resolve()
+
+
+def main() -> int:
+    failures: list[str] = []
+    for source in sorted(TRELLIS_ROOT.rglob("*.md")):
+        text = source.read_text(encoding="utf-8")
+        for match in LINK_RE.finditer(text):
+            target = _target_path(source, match.group(1))
+            if target is None:
+                continue
+            if not target.exists():
+                rel_source = source.relative_to(REPO_ROOT)
+                failures.append(f"{rel_source}: missing link target {match.group(1)}")
+    if failures:
+        print("\n".join(failures), file=sys.stderr)
+        return 1
+    print("Trellis markdown links OK")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(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..7ca1c477e
--- /dev/null
+++ b/.trellis/scripts/common/git_context.py
@@ -0,0 +1,697 @@
+#!/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 typing import TypedDict
+
+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
+# =============================================================================
+
+
+class CurrentTaskInfo(TypedDict, total=False):
+    """Structured current-task metadata shared across output modes."""
+
+    path: str
+    name: str
+    status: str
+    createdAt: str
+    description: str
+    warning: str
+    hasPrd: bool
+    isValid: bool
+
+
+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
+
+
+def _get_current_task_info(repo_root: Path) -> CurrentTaskInfo | None:
+    """Resolve current-task metadata once for all output modes."""
+    current_task = get_current_task(repo_root)
+    if not current_task:
+        return None
+
+    current_task_dir = repo_root / current_task
+    info: CurrentTaskInfo = {
+        "path": current_task,
+        "hasPrd": (current_task_dir / "prd.md").is_file(),
+        "isValid": False,
+    }
+
+    if not current_task_dir.is_dir():
+        info["status"] = "invalid"
+        info["warning"] = "path does not exist"
+        return info
+
+    task_json_path = current_task_dir / FILE_TASK_JSON
+    if not task_json_path.is_file():
+        info["status"] = "invalid"
+        info["warning"] = "task.json is missing"
+        return info
+
+    data = _read_json_file(task_json_path)
+    if not data:
+        info["status"] = "invalid"
+        info["warning"] = "task.json could not be read"
+        return info
+
+    info["isValid"] = True
+    info["name"] = data.get("name") or data.get("id") or current_task_dir.name
+    info["status"] = data.get("status", "unknown")
+
+    created_at = data.get("createdAt")
+    if isinstance(created_at, str) and created_at:
+        info["createdAt"] = created_at
+
+    description = data.get("description")
+    if isinstance(description, str) and description:
+        info["description"] = description
+
+    return info
+
+
+def _append_current_task_lines(
+    lines: list[str],
+    current_task_info: CurrentTaskInfo | None,
+    *,
+    include_created: bool = False,
+    include_description: bool = False,
+    include_prd_hint: bool = False,
+) -> None:
+    """Render the CURRENT TASK section consistently across text modes."""
+    lines.append("## CURRENT TASK")
+
+    if not current_task_info:
+        lines.append("(none)")
+        return
+
+    lines.append(f"Path: {current_task_info['path']}")
+
+    name = current_task_info.get("name")
+    if isinstance(name, str) and name:
+        lines.append(f"Name: {name}")
+
+    status = current_task_info.get("status")
+    if isinstance(status, str) and status:
+        lines.append(f"Status: {status}")
+
+    created_at = current_task_info.get("createdAt")
+    if include_created and isinstance(created_at, str) and created_at:
+        lines.append(f"Created: {created_at}")
+
+    description = current_task_info.get("description")
+    if include_description and isinstance(description, str) and description:
+        lines.append(f"Description: {description}")
+
+    warning = current_task_info.get("warning")
+    if isinstance(warning, str) and warning:
+        lines.append(f"[!] Invalid current task pointer: {warning}")
+
+    if include_prd_hint and current_task_info.get("hasPrd") is True:
+        lines.append("")
+        lines.append("[!] This task has prd.md - read it for task details")
+
+
+# =============================================================================
+# 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)
+    current_task_info = _get_current_task_info(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}",
+        },
+        "currentTask": current_task_info,
+        "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
+    _append_current_task_lines(
+        lines,
+        _get_current_task_info(repo_root),
+        include_created=True,
+        include_description=True,
+        include_prd_hint=True,
+    )
+    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 = _get_current_task_info(repo_root)
+
+    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
+    _append_current_task_lines(lines, _get_current_task_info(repo_root))
+    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..a8060435f
--- /dev/null
+++ b/.trellis/spec/backend/database-guidelines.md
@@ -0,0 +1,115 @@
+# Database Guidelines
+
+> Persistence guidance for the current `coding-deepgent` mainline.
+
+---
+
+## Current Status
+
+`coding-deepgent` now uses a mixed persistence model:
+
+- JSONL transcript ledger for session history / evidence / compact / resume
+- relational storage for long-term memory backend
+- queue-backed background processing for memory jobs
+- object storage for snapshot/archive payloads
+
+Current relational/object-backed surfaces:
+
+- durable long-term memory records
+- memory versions / audit history
+- memory extraction job state
+- agent memory scope metadata
+- snapshot/archive objects
+
+Recommended long-term memory table family:
+
+- `memory_records`
+- `memory_versions`
+- `memory_extraction_jobs`
+- `agent_memory_scopes`
+
+Current durable/stateful surfaces are:
+
+- LangGraph store/checkpointer seams in `coding_deepgent.runtime.checkpointing`
+- JSONL session transcripts in `coding_deepgent.sessions.store_jsonl`
+- database-backed long-term memory records in `memory/`
+- LangGraph store-backed task/plan records in `tasks/`
+- workspace-local persisted tool outputs under `.coding-deepgent/tool-results/`
+
+SQL/ORM/migration infrastructure is now allowed only for the long-term memory
+backend and explicitly approved future domains. It is still not the default for
+sessions/transcript storage.
+
+---
+
+## Store Patterns
+
+Preferred patterns:
+
+- Use relational storage for durable long-term memory backend records that need:
+  - process-surviving persistence
+  - audit/version history
+  - job status tracking
+  - agent memory scope metadata
+- Use queue-backed background jobs for automatic extraction and snapshot refresh
+  rather than blocking the main prompt loop.
+- Keep large snapshot/archive payloads in object storage instead of the main
+  relational tables.
+- Continue to use LangGraph store-compatible APIs where a lighter-weight store
+  seam is still sufficient, such as durable task/plan records.
+- Keep namespace ownership inside the owning domain.
+- Store Pydantic `model_dump()` payloads for typed records.
+- Validate records before writing and when reconstructing from storage.
+
+Examples:
+
+- `coding_deepgent.memory.backend`
+- `coding_deepgent.memory.service`
+- `coding_deepgent.tasks.store`
+- `coding_deepgent.runtime.checkpointing`
+
+---
+
+## Session Persistence
+
+Session transcript persistence belongs to `sessions/`.
+
+Rules:
+
+- Use `JsonlSessionStore` for local transcript, evidence, compact, and state
+  snapshot records.
+- Keep session storage append-oriented unless a Trellis contract explicitly says
+  otherwise.
+- Keep session evidence, compact records, and state snapshots distinct instead
+  of merging them into one generic blob.
+
+Examples:
+
+- `coding_deepgent.sessions.store_jsonl`
+- `coding_deepgent.sessions.records`
+- `coding_deepgent.sessions.evidence_events`
+
+---
+
+## Migrations
+
+The long-term memory backend must define:
+
+- target storage backend
+- schema ownership
+- migration command surface
+- rollback strategy
+- validation and error matrix
+- tests proving old records are handled safely
+
+Transcript/session migration remains a separate future project and must not be
+folded into ordinary memory-backend changes.
+
+---
+
+## Common Mistakes
+
+- Treating `sessions/` as generic durable storage for unrelated domains.
+- Moving transcript/session ledger into SQL just because JSON can be stored there.
+- Hiding task/memory schema evolution in ad hoc dict writes.
+- Reusing one store namespace for multiple domain concepts.
diff --git a/.trellis/spec/backend/directory-structure.md b/.trellis/spec/backend/directory-structure.md
new file mode 100644
index 000000000..ed1997a06
--- /dev/null
+++ b/.trellis/spec/backend/directory-structure.md
@@ -0,0 +1,193 @@
+# Directory Structure
+
+> Actual backend structure rules for the current `coding-deepgent` mainline.
+
+---
+
+## Scope
+
+This document describes how backend/product code is organized under:
+
+```text
+coding-deepgent/src/coding_deepgent/
+```
+
+It is not a tutorial chapter map. Do not mirror `agents/`, `agents_deepagents/`,
+or `docs/` structure into product code.
+
+---
+
+## Directory Layout
+
+```text
+coding-deepgent/src/coding_deepgent/
+├── app.py                    # public app/runtime entry helpers
+├── bootstrap.py              # startup validation + top-level build helpers
+├── agent_loop_service.py     # app invocation orchestration
+├── agent_runtime_service.py  # runtime payload/session state wiring
+├── agent_service.py          # create_agent-facing assembly seam
+├── config.py                 # typed settings
+├── containers/               # dependency-injector composition only
+├── runtime/                  # invocation, state, context, session payload seams
+├── tool_system/              # capability registry, projection, guard middleware
+├── tools/                    # builtin workspace-facing tools
+├── filesystem/               # filesystem/domain-level helpers
+├── prompting/                # layered prompt + dynamic context assembly
+├── compact/                  # projection, summaries, runtime pressure, artifacts
+├── rules/                    # project-level rules entrypoint and file loading
+├── sessions/                 # transcript/evidence/resume/record stores
+├── memory/                   # save/recall/policy/context integration
+├── todo/                     # short-term planning contract
+├── tasks/                    # durable task graph + plan artifacts
+├── subagents/                # bounded run_subagent runtime
+├── permissions/              # deterministic permission policy
+├── hooks/                    # lifecycle/event hook seam
+├── mcp/                      # MCP config/load/resource seams
+├── plugins/                  # local plugin manifest schemas/registry/loader
+├── renderers/                # terminal/rendering helpers
+└── frontend/                 # renderer-neutral frontend protocol, producer, and adapters
+```
+
+---
+
+## Core Organization Rules
+
+### 1. Domain package first
+
+New behavior should land in the domain package that owns the product concept:
+
+- session persistence or resume -> `sessions/`
+- project-level persistent behavior rules -> `rules/`
+- dynamic runtime state or invocation shaping -> `runtime/`
+- tool exposure or tool guard behavior -> `tool_system/`
+- task graph or plan artifacts -> `tasks/`
+- model-facing context pressure behavior -> `compact/`
+- renderer-neutral UI event production -> `frontend/producer.py`
+- transport-specific frontend bridges -> `frontend/adapters/`
+
+Do not add unrelated behavior to `app.py`, `cli.py`, or `bootstrap.py` just
+because those files are easy to find.
+
+### 2. Containers compose, domains decide
+
+`containers/` exists for dependency-injector wiring only.
+
+Rules:
+
+- domain packages do not import `coding_deepgent.containers`
+- `containers/*` does not own business rules
+- container modules may assemble providers, but product decisions belong in the
+  corresponding domain
+
+### 3. Runtime is a real boundary
+
+`runtime/` owns invocation-specific state and context seams.
+
+Put code there when it is about:
+
+- runtime state shape
+- session payload wiring
+- invocation context propagation
+- LangGraph/LangChain runtime attachment points
+
+Do not use `sessions/` as a generic place for any long-lived product state.
+
+### 4. Sessions stay transcript/resume scoped
+
+`sessions/` is for:
+
+- JSONL transcript records
+- evidence
+- recovery brief rendering
+- compact records
+- resume loading/selection
+
+It should not silently absorb:
+
+- durable task graph ownership
+- generic plugin state
+- arbitrary runtime-only caches
+
+### 5. Tool system stays generic
+
+`tool_system/` owns cross-cutting capability mechanics:
+
+- capability metadata
+- projection into the model-visible tool surface
+- permission/trust metadata
+- guard middleware
+
+It should not become a god module for task logic, session policy, or prompt
+assembly.
+
+### 6. LangChain-native adapters stay explicit
+
+Keep LangChain/LangGraph-specific adapters in clearly named files or packages,
+for example:
+
+- `tools.py`
+- `middleware.py`
+- `state.py`
+- `app.py`
+
+Do not spread model/schema/prompt/runtime wiring across unrelated modules.
+For implementation-specific rules, read
+`langchain-native-guidelines.md`.
+
+### 7. Frontend producer/adapters stay one-way
+
+`frontend/producer.py` may depend on runtime/session/tool domains to produce
+renderer-neutral events.
+
+`frontend/adapters/*` may depend on `frontend/producer.py` and protocol types to
+serve specific transports such as JSONL or future SSE.
+
+Runtime/domain packages must not import `frontend/adapters/*` or
+`frontend/bridge.py`. This keeps CLI/Web transport concerns out of the agent
+runtime.
+
+---
+
+## Naming And Placement Conventions
+
+- Keep package names noun-based and product-domain oriented:
+  - `sessions`, `tasks`, `compact`, `memory`, `rules`
+- Prefer small modules with one strong responsibility over giant mixed files.
+- Put public exports in each domain `__init__.py` only when that improves the
+  main product surface; do not re-export everything automatically.
+- Tests should mirror domain responsibilities under `coding-deepgent/tests/`
+  instead of reaching through app entrypoints for everything.
+
+---
+
+## Real Examples
+
+- `coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py`
+  shows a cross-cutting runtime concern implemented as a domain seam rather
+  than inside app wiring.
+- `coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py`
+  is the source of truth for transcript/evidence persistence.
+- `coding-deepgent/src/coding_deepgent/tasks/tools.py`
+  keeps durable task and plan artifact tool behavior in the `tasks` domain
+  instead of scattering it across runtime/app modules.
+- `coding-deepgent/src/coding_deepgent/containers/app.py`
+  composes the runtime without owning product rules.
+- `coding-deepgent/src/coding_deepgent/frontend/producer.py`
+  produces renderer-neutral frontend events.
+- `coding-deepgent/src/coding_deepgent/frontend/adapters/jsonl.py`
+  owns the stdio JSONL transport used by the React/Ink CLI.
+- `coding-deepgent/src/coding_deepgent/frontend/runs.py`
+  owns frontend run lifecycle for future network consumers.
+- `coding-deepgent/src/coding_deepgent/frontend/stream_bridge.py`
+  owns the replayable event bridge used by future SSE/gateway consumers.
+
+---
+
+## Anti-Patterns
+
+- importing `coding_deepgent.containers` from domain packages
+- adding domain decisions directly into `app.py`, `cli.py`, or `bootstrap.py`
+- treating tutorial directory structure as a template for product layout
+- merging unrelated concepts into `sessions/` because they are "stateful"
+- using `tool_system/` as a dumping ground for product logic
+- making runtime/domain modules depend on CLI/Web transport adapters
diff --git a/.trellis/spec/backend/error-handling.md b/.trellis/spec/backend/error-handling.md
new file mode 100644
index 000000000..e2dd93570
--- /dev/null
+++ b/.trellis/spec/backend/error-handling.md
@@ -0,0 +1,116 @@
+# Error Handling
+
+> Error handling conventions for the current `coding-deepgent` mainline.
+
+---
+
+## Overview
+
+`coding-deepgent` is a local CLI/product runtime, not a web API service.
+
+Default posture: **mixed but strict**.
+
+Errors should be handled according to boundary:
+
+- schema/domain validation errors should be explicit exceptions
+- model-visible tool execution failures may return bounded `"Error: ..."` text
+- CLI-facing failures should become `ClickException` / Typer exits
+- recoverable middleware failures should fail open only when the contract says so
+
+---
+
+## Error Types
+
+Common current types:
+
+- `ValueError`
+  - invalid schema values, invalid transitions, bad compact settings
+- `KeyError`
+  - missing task/plan/capability lookup
+- `RuntimeError`
+  - missing required runtime context or store
+- `FileNotFoundError` / `NotADirectoryError`
+  - missing local skill/plugin roots
+- domain-specific runtime errors
+  - `SessionLoadError` in `sessions.records`
+
+Use custom error classes only when callers need to distinguish a domain failure
+from generic validation/runtime failures.
+
+---
+
+## Boundary Patterns
+
+### Decision Matrix
+
+| Boundary | Default behavior | Reason |
+|---|---|---|
+| schema / Pydantic validation | raise `ValueError` or validation error | invalid input should fail tests and not be normalized silently |
+| pure domain service | raise explicit exception | keeps business invariants enforceable |
+| model-visible tool result | return bounded `"Error: ..."` when the error is part of the tool surface | lets the model observe and recover without crashing the whole loop |
+| CLI command | convert expected failures to `ClickException` / `typer.Exit` | user-facing command output should be concise |
+| middleware guard | deny through structured tool result/event where applicable | policy decisions are runtime facts |
+| recoverable runtime pressure helper | fail open only when the relevant contract says so | context pressure helpers should not corrupt execution when optional storage/summarization fails |
+
+### Schema and domain helpers
+
+Raise explicit exceptions.
+
+Examples:
+
+- `todo.service` rejects multiple `in_progress` items with `ValueError`.
+- `tasks.store` rejects invalid transitions and dependency cycles.
+- `compact.artifacts` rejects invalid compact summaries/settings.
+
+### Model-visible filesystem tools
+
+Return bounded error text when the tool result itself is the model-visible
+surface.
+
+Examples:
+
+- filesystem command timeout -> `"Error: Timeout (120s)"`
+- missing text during edit -> `"Error: Text not found ..."`
+- invalid regex -> `"Error: Invalid regex ..."`
+
+### CLI boundary
+
+Convert expected user-facing failures into `ClickException` or `typer.Exit`.
+
+Examples:
+
+- invalid session resume options
+- missing session
+- invalid compact option combinations
+
+### Middleware/runtime pressure
+
+Fail open only when explicitly required by contract.
+
+Example:
+
+- large tool-result persistence returns the original `ToolMessage` unchanged if
+  file writing raises `OSError`.
+- live compact summarization failure returns the original message list if the
+  contract says proactive compact is best-effort.
+
+---
+
+## API Error Responses
+
+There is currently no HTTP/API error response contract.
+
+Do not add API-style error envelopes unless an actual API surface is introduced.
+For CLI and tool-facing behavior, document the exact return/exception contract
+in the relevant backend spec.
+
+---
+
+## Common Mistakes
+
+- Swallowing domain validation errors that should fail tests.
+- Returning model-visible `"Error: ..."` strings from pure domain helpers.
+- Raising raw exceptions directly through CLI commands instead of converting to
+  user-facing CLI errors.
+- Failing open in middleware without an explicit contract.
+- Adding alias/fallback parsing to hide invalid structured tool inputs.
diff --git a/.trellis/spec/backend/index.md b/.trellis/spec/backend/index.md
new file mode 100644
index 000000000..984eb0a13
--- /dev/null
+++ b/.trellis/spec/backend/index.md
@@ -0,0 +1,85 @@
+# Backend Development Guidelines
+
+> Canonical backend norms for the current `coding-deepgent` mainline.
+
+---
+
+## Current Scope
+
+- Current working mainline: `coding-deepgent/`
+- Canonical coordination layer: `.trellis/`
+- Default non-mainline reference layer:
+  - `agents/`
+  - `agents_deepagents/`
+  - `docs/`
+  - `web/`
+
+Use tutorial/reference material as evidence or examples only unless a task
+explicitly targets it.
+
+---
+
+## Canonical Reading Order
+
+Before changing backend code in the current mainline, read in this order:
+
+1. `AGENTS.md`
+2. `.trellis/workflow.md`
+3. `.trellis/project-handoff.md`
+4. `.trellis/spec/guides/mainline-scope-guide.md`
+5. This index
+6. The specific backend docs relevant to the task
+
+Product-level status summaries may still exist in `coding-deepgent/README.md`
+and `coding-deepgent/PROJECT_PROGRESS.md`, but live development norms and
+contracts should be captured here in Trellis.
+
+---
+
+## Guidelines Index
+
+| Guide | Description | Status |
+|-------|-------------|--------|
+| [Directory Structure](./directory-structure.md) | Actual `coding-deepgent` module layout and boundary rules | Active |
+| [Database Guidelines](./database-guidelines.md) | Current persistence guidance; no SQL/ORM in mainline yet | Active |
+| [Error Handling](./error-handling.md) | Mixed-but-strict error boundary conventions | Active |
+| [LangChain-Native Implementation Guidelines](./langchain-native-guidelines.md) | Strict tool/schema/middleware/state rules for LangChain/LangGraph work | Active |
+| [Quality Guidelines](./quality-guidelines.md) | Mainline code-review, testing, and boundary rules | Active |
+| [Logging Guidelines](./logging-guidelines.md) | Structured logging and evidence-vs-log boundary | Active |
+| [Runtime Context And Compaction Contracts](./runtime-context-compaction-contracts.md) | Overview index for runtime/compact contract files | Active |
+| [Project Infrastructure Foundation Contracts](./project-infrastructure-foundation-contracts.md) | Project-level review gate for transcript/session/compact/collapse/runtime pressure/task/subagent/hooks/memory | Active |
+| [Tool Capability Contracts](./tool-capability-contracts.md) | H01 five-factor tool protocol, safe defaults, capability metadata, and tool projection rules | Active |
+| [Tool Result Storage Contracts](./tool-result-storage-contracts.md) | Executable contracts for large-output persistence and preview references | Active |
+| [Session Compact Contracts](./session-compact-contracts.md) | Executable contracts for resume, compact records, session memory, and memory quality | Active |
+| [Runtime Pressure Contracts](./runtime-pressure-contracts.md) | Executable contracts for live microcompact, auto/reactive compact, restoration, and runtime pressure evidence | Active |
+| [Task Workflow Contracts](./task-workflow-contracts.md) | Executable contracts for durable task graph readiness, transitions, and verification boundary | Active |
+
+---
+
+## Current High-Signal Docs
+
+For most current `coding-deepgent` work, the high-signal Trellis docs are:
+
+- [Directory Structure](./directory-structure.md)
+- [LangChain-Native Implementation Guidelines](./langchain-native-guidelines.md)
+- [Quality Guidelines](./quality-guidelines.md)
+- [Runtime Context And Compaction Contracts](./runtime-context-compaction-contracts.md)
+- [Project Infrastructure Foundation Contracts](./project-infrastructure-foundation-contracts.md)
+- [Tool Capability Contracts](./tool-capability-contracts.md)
+- [Tool Result Storage Contracts](./tool-result-storage-contracts.md)
+- [Session Compact Contracts](./session-compact-contracts.md)
+- [Runtime Pressure Contracts](./runtime-pressure-contracts.md)
+- [Task Workflow Contracts](./task-workflow-contracts.md)
+
+If a task changes runtime/session/compact/task boundaries, these Trellis docs
+should be updated rather than creating or reviving parallel docs under
+`coding-deepgent/docs/`.
+
+---
+
+## Language Convention
+
+- Narrative prose may be written in **Simplified Chinese**.
+- Keep commands, file paths, file names, task slugs, branch names, code identifiers, and JSON/YAML keys in **English**.
+- Keep checklist keywords and structured status values in **English** when they are used for search, automation, or coordination.
+- When introducing project-specific terms, prefer Chinese explanations with the original English term kept where precision matters.
diff --git a/.trellis/spec/backend/langchain-native-guidelines.md b/.trellis/spec/backend/langchain-native-guidelines.md
new file mode 100644
index 000000000..f6c371ce5
--- /dev/null
+++ b/.trellis/spec/backend/langchain-native-guidelines.md
@@ -0,0 +1,177 @@
+# LangChain-Native Implementation Guidelines
+
+> Practical structure and schema rules for `coding-deepgent` LangChain/LangGraph work.
+
+---
+
+## Scope
+
+Use this document when a task touches:
+
+- LangChain
+- LangGraph
+- middleware
+- tool schemas
+- prompt assembly
+- runtime state
+- model integration seams
+
+This is the canonical Trellis guidance for LangChain/LangGraph implementation
+shape.
+
+---
+
+## Operating Posture
+
+- Prefer the smallest official LangChain/LangGraph abstraction that solves the problem.
+- Keep code simple before modularizing.
+- Do not add wrapper layers, fallback parsers, or framework-shaped indirection without a real boundary.
+- If multiple surfaces are involved, keep tool, middleware, state, prompt, and rendering responsibilities separate.
+- For project infrastructure changes, prove the mutation belongs to one of the
+  official runtime surfaces: tool, middleware, typed state, context schema,
+  checkpointer, store, or graph/subgraph. If it does not, document the explicit
+  non-LangChain boundary before implementing.
+
+Before editing, identify:
+
+1. **Surface**
+2. **Primary boundary**
+3. **Smallest viable change**
+4. **Durability boundary** for any session, memory, task, or transcript change
+
+---
+
+## Tool Schema Rules
+
+- Use Pydantic `BaseModel` with strict schemas for structured tool input.
+- Prefer `ConfigDict(extra="forbid")` unless loose input is explicitly required.
+- Put model-visible guidance in `Field(description=...)` and the tool description.
+- Put invariants in validators, not in ad hoc parsing helpers.
+- Do not parse raw `dict[str, Any]` as fallback for model mistakes.
+- Do not accept alias guessing such as `task -> content`, `done -> completed`,
+  or `doing -> in_progress` unless explicitly requested.
+- Avoid `normalize_*` helpers for structured tool input when schema validation
+  can express the rule directly.
+
+Preferred outcome:
+
+- strict schema
+- direct field access
+- predictable `Command(update=...)` or typed return value
+- matching `ToolCapability` metadata for the five-factor tool protocol:
+  `name`, `schema`, `permission`, `execution`, and `rendering_result`
+
+For tool capability ownership, safe defaults, exposure projection, large-output
+eligibility, and runtime-pressure metadata, read
+[Tool Capability Contracts](./tool-capability-contracts.md).
+
+---
+
+## State Rules
+
+- Define explicit typed state for custom short-term state.
+- Keep one default-state factory when app/session code owns initialization.
+- Use middleware backfill only as defensive, idempotent state setup.
+- Use reducers or explicit rejection when parallel tool calls can race on the
+  same state key.
+- Do not introduce persistence/store/task graph just for ephemeral session state.
+- Do not use a generic "session state" dictionary to mix transcript facts,
+  evidence, durable tasks, long-term memory, and live projection artifacts. Use
+  the owning surface for each concern.
+
+---
+
+## Middleware Rules
+
+- Middleware is for cross-cutting behavior:
+  - validation
+  - routing
+  - guards
+  - logging
+  - usage tracking
+  - state injection
+- For HITL approval flows, prefer official LangGraph `interrupt()` plus
+  `Command(resume=...)` with a checkpointer and stable `thread_id` instead of a
+  custom waiting loop.
+- Keep business-specific tool rules in tool schema/description, not middleware.
+- Use `before_agent` / `after_agent` for once-per-invocation behavior.
+- Use `wrap_model_call` / `wrap_tool_call` when logic must run around each call.
+- Do not let middleware secretly own a feature that should be a tool, state
+  schema, or prompt section.
+
+---
+
+## Prompt Placement Rules
+
+System prompts should stay short and general:
+
+- identity / role
+- workspace / environment
+- general tool-use behavior
+- safety / honesty constraints
+
+Tool-specific behavior belongs in:
+
+- tool description
+- field descriptions
+- validators
+- tests
+
+Do not place a full tool manual in the system prompt unless it truly applies
+globally.
+
+---
+
+## Modularity Rules
+
+Extract modules only for real stable responsibilities, for example:
+
+- `state.py` -> state schemas / default factories
+- `tools/*.py` -> tool definitions and tool-local execution
+- `middleware/*.py` -> middleware hooks
+- `renderers/*.py` -> display formatting
+- `app.py` -> agent wiring
+
+Avoid:
+
+- one-function modules
+- speculative abstraction layers
+- pass-through wrappers that only make code look architectural
+
+Prefer local code until reuse or a boundary is real.
+
+---
+
+## Verification Rules
+
+For LangChain tool/state changes, prove:
+
+- the public tool name is correct
+- `tool_call_schema.model_json_schema()` exposes only intended model-visible fields
+- hidden injected fields are not model-visible
+- invalid aliases / extra fields fail
+- state update returns the expected shape
+- middleware injects or guards only what it owns
+- no stale public prompt/tool wording remains
+- transcript/session/store mutations have an explicit durability boundary
+- live projection middleware does not rewrite persisted session records
+
+Useful review checks:
+
+```bash
+rg -n "dict\\[str, Any\\]|normalize_.*\\(|fallback|alias|ToolRuntime|InjectedToolCallId" <paths>
+rg -n "system_prompt|SYSTEM_PROMPT|description=|Field\\(" <paths>
+rg -n "record_type|message_index|thread_id|checkpointer|store|session_memory" <paths>
+```
+
+Treat matches as review prompts, not automatic failures.
+
+---
+
+## Relationship To Other Trellis Docs
+
+- Use [Directory Structure](./directory-structure.md) for product-domain ownership.
+- Use [Quality Guidelines](./quality-guidelines.md) for review/testing expectations.
+- Use [Tool Capability Contracts](./tool-capability-contracts.md) for H01
+  tool protocol and capability metadata.
+- Use `guides/cc-alignment-guide.md` when the task also targets `cc-haha` alignment.
diff --git a/.trellis/spec/backend/logging-guidelines.md b/.trellis/spec/backend/logging-guidelines.md
new file mode 100644
index 000000000..80b27a3c7
--- /dev/null
+++ b/.trellis/spec/backend/logging-guidelines.md
@@ -0,0 +1,131 @@
+# Logging Guidelines
+
+> Logging and runtime event conventions for the current `coding-deepgent` mainline.
+
+---
+
+## Overview
+
+`coding-deepgent` uses `structlog` for local structured logging setup.
+
+Current setup:
+
+- `coding_deepgent.logging_config.configure_logging()`
+- JSON rendering via `structlog.processors.JSONRenderer`
+- ISO timestamps
+- log level filtering from the configured level
+
+Runtime facts that should survive resume/audit should usually be session
+evidence, not just logs.
+
+Default evidence posture: **high-value recoverable facts only**.
+
+---
+
+## Log Levels
+
+- `debug`
+  - local diagnostic detail that should not be required for normal operation
+- `info`
+  - successful startup/config/major lifecycle observations
+- `warning`
+  - recoverable unexpected behavior or degraded paths
+- `error`
+  - unrecoverable local failures before converting to CLI/user-facing errors
+
+Use the configured level instead of ad hoc print debugging.
+
+---
+
+## Structured Logging
+
+Prefer structured event fields over prose-only logs.
+
+Recommended fields when applicable:
+
+- `event`
+- `session_id`
+- `thread_id`
+- `entrypoint`
+- `tool_name`
+- `capability_source`
+- `decision`
+- `status`
+
+Do not log arbitrary model prompts, raw tool outputs, API keys, or secret-like
+environment values.
+
+---
+
+## Runtime Evidence Vs Logs
+
+Use session evidence when the fact should be recoverable across sessions or
+visible in recovery briefs.
+
+Do not use evidence as a general event log.
+
+Examples that belong in evidence:
+
+- verifier verdicts
+- permission-denied events
+- hook-blocked events
+- compact/runtime pressure counters when they affect continuation
+
+Examples that can stay as logs:
+
+- hook start/complete events that do not block execution
+- successful ordinary tool calls
+- config/startup diagnostics
+- startup diagnostics
+- local configuration display plumbing
+- non-contractual debug detail
+
+Current whitelisted runtime evidence kinds:
+
+- `hook_blocked`
+- `permission_denied`
+- `snip`
+- `microcompact`
+- `context_collapse`
+- `auto_compact`
+- `post_autocompact_turn`
+- `reactive_compact`
+- `subagent_spawn_guard`
+- `orphan_tombstoned`
+- `query_error`
+
+`token_budget` is a bounded runtime event for local observability. It is not
+persisted as session evidence by default because it can fire every assistant
+response turn and would otherwise dominate recovery briefs.
+
+Env-gated prompt/API dumps are allowed only when
+`CODING_DEEPGENT_DUMP_PROMPTS=1`. Dumps must be local files, must keep secrets
+out of dump metadata, and must never be injected back into model-visible
+context.
+
+Add a new evidence kind only when:
+
+- it helps session recovery or audit
+- it can be summarized concisely
+- its metadata can be safely bounded
+- it has focused tests
+
+---
+
+## What NOT To Log
+
+- provider API keys or auth tokens
+- raw full prompts
+- raw large tool outputs
+- sensitive local file contents
+- arbitrary plugin/MCP payload dumps
+- unbounded exception payloads that may include secrets
+
+---
+
+## Common Mistakes
+
+- Using `print()` for runtime diagnostics that should be structured.
+- Treating logs as durable product evidence.
+- Logging raw model/tool payloads when a bounded evidence record would be safer.
+- Recording every runtime event as evidence and making recovery briefs noisy.
diff --git a/.trellis/spec/backend/project-infrastructure-foundation-contracts.md b/.trellis/spec/backend/project-infrastructure-foundation-contracts.md
new file mode 100644
index 000000000..6858a27fc
--- /dev/null
+++ b/.trellis/spec/backend/project-infrastructure-foundation-contracts.md
@@ -0,0 +1,513 @@
+# Project Infrastructure Foundation Contracts
+
+> Project-level infrastructure review gate for `coding-deepgent` transcript,
+> session, compact, collapse, runtime pressure, task, subagent, hooks, and
+> memory changes.
+
+This document captures the 2026-04-16 project infrastructure review. It is not a
+bug list. Use it as the reusable contract for deciding whether future cc-aligned
+work strengthens the LangChain/LangGraph-native foundation or revives temporary
+local mental models.
+
+## Scenario: Infrastructure Foundation Review Gate
+
+### 1. Scope / Trigger
+
+Read this document before changing any of:
+
+- transcript/session JSONL records or resume behavior
+- compact transcript records, generated/manual compact, live compact, or collapse
+- runtime pressure middleware, projection, token budgets, or prompt-too-long retry
+- durable task, plan, verification, or subagent execution boundaries
+- hooks, hook evidence, or hook-provided model-visible context
+- long-term memory, session memory, memory recall, or memory quality policy
+- LangChain/LangGraph runtime wiring, `RuntimeContext`, `RuntimeState`,
+  checkpointer, store, or `thread_id`
+
+This gate is also required for cc highlight work touching `H05-H14`,
+`H18-H20`, or any future stage that claims to improve long-session continuity,
+multi-agent readiness, or cross-session memory.
+
+### 2. Canonical Runtime Surfaces
+
+The current product has these infrastructure surfaces:
+
+```python
+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
+    session_context: SessionContext | None
+
+class RuntimeState(AgentState):
+    todos: NotRequired[list[RuntimeTodoState]]
+    rounds_since_update: NotRequired[int]
+    session_memory: NotRequired[dict[str, Any]]
+
+class SessionContext:
+    session_id: str
+    workdir: Path
+    store_dir: Path
+    transcript_path: Path
+    entrypoint: str | None = None
+```
+
+Current persistent/session record types:
+
+```text
+message
+state_snapshot
+evidence
+compact
+```
+
+Current LangChain/LangGraph-native entry points:
+
+```python
+create_agent(
+    model=...,
+    tools=...,
+    system_prompt=...,
+    middleware=...,
+    state_schema=RuntimeState,
+    context_schema=RuntimeContext,
+    checkpointer=...,
+    store=...,
+    name="coding-deepgent",
+)
+
+RuntimePressureMiddleware.wrap_model_call(...)
+ToolGuardMiddleware.wrap_tool_call(...)
+MemoryContextMiddleware.wrap_model_call(...)
+```
+
+Current store-backed collaboration/memory surfaces:
+
+```python
+save_memory(type, source, runtime, ...)
+list_memory(type=None, limit=20, runtime=...)
+delete_memory(type, key, runtime)
+memory jobs
+memory worker-run-once
+task_create(...)
+task_update(...)
+plan_save(...)
+run_subagent(task, runtime, agent_type="<builtin-or-local>", plan_id=...)
+event_stream append/list/ack
+worker_runtime create/heartbeat/stop/complete
+mailbox send/list/ack
+teams create/assign/progress/complete
+remote register/control/replay/close
+extension_lifecycle register/enable/disable/update/rollback
+continuity save/list/show/stale
+```
+
+Circle 2 local baseline ownership:
+
+- `event_stream/` owns replayable local visible/internal events.
+- `worker_runtime/` owns durable local worker lifecycle records.
+- `mailbox/` owns addressable local message delivery and acknowledgements.
+- `teams/` owns local coordinator/worker run records and progress synthesis.
+- `remote/` owns local remote-control session records and replayable control
+  events; it is not a hosted SaaS ingress layer.
+- `extension_lifecycle/` owns local extension lifecycle state and rollback.
+- `continuity/` owns cross-day continuity artifacts.
+- These domains must not be hidden inside `sessions/`, `subagents/tools.py`,
+  `tool_system/`, or `frontend/producer.py`.
+
+Long-term memory may also influence runtime behavior through existing guard
+surfaces, not only through prompt recall. Current local contract:
+
+- `feedback` memory can block high-risk tool actions through `ToolGuardMiddleware`
+- keep this bounded and deterministic; do not add a second hidden query loop
+- current enforced local cases are:
+  - commit commands when feedback requires lint first
+  - dependency edits/install commands when feedback requires confirmation
+  - generated-path writes when feedback forbids direct modification
+
+Current product memory surface is intentionally split into two visible layers:
+
+- product-level rules
+  - one project-level rules file defines long-term behavior constraints
+  - this layer is user-editable
+  - this layer is not long-term memory and not transcript history
+- long-term memory
+  - durable reusable facts, rules, references, and user profile entries
+  - save/list/delete through memory tools
+  - shown back to the model through bounded recall
+  - shown back to the user through recovery brief visibility
+- current-session memory
+  - the bounded summary/artifact for the active session only
+  - shown separately in recovery/resume
+  - must not be treated as long-term durable memory
+
+The product-level context and memory model is four-layer:
+
+1. project-level rules
+2. long-term memory
+3. current-session memory
+4. recovery context
+
+Default assembly rule:
+
+- earlier layers define longer-lived behavior or knowledge
+- later layers restore current-session and historical context
+- later layers must not silently override the prior three by default
+
+Current tool capability protocol:
+
+```text
+name
+schema
+permission
+execution
+rendering_result
+```
+
+Detailed tool contracts live in
+[Tool Capability Contracts](./tool-capability-contracts.md).
+
+### 3. Ownership Contracts
+
+#### Transcript And Session
+
+- The JSONL transcript is the append-only factual ledger.
+- Persisted transcript records must not be rewritten by live pressure,
+  projection, collapse, auto-compact, reactive compact, hooks, or memory recall.
+- `LoadedSession.history` is the raw persisted message view.
+- `LoadedSession.compacted_history` is a virtual load-time continuation view.
+- `LoadedSession.evidence` is bounded operational evidence, not chat history and
+  not long-term memory.
+- `SessionContext` is the bridge that lets runtime tools append bounded evidence
+  to the current ledger.
+- `RuntimeState` snapshots are recoverable runtime state, not a replacement for
+  the transcript ledger.
+
+#### Compact, Collapse, And Runtime Pressure
+
+- Manual/generated session compact may persist `compact` records.
+- Live `snip`, `microcompact`, `context_collapse`, `auto_compact`, and
+  `reactive_compact` are model-facing projections only.
+- `context_collapse` is a live pressure stage. It must not become a second
+  persisted compact ledger.
+- Runtime pressure order is:
+  1. `snip_messages`
+  2. `microcompact_messages`
+  3. `maybe_collapse_messages`
+  4. `maybe_auto_compact_messages`
+  5. model call
+  6. one bounded reactive compact retry only for prompt-too-long errors
+- Pressure events may become session evidence only through bounded metadata.
+  Raw prompt text, raw summaries, full tool output, and arbitrary hook data must
+  not be written as evidence metadata.
+- Live projection artifacts must preserve tool-call/tool-result pairing and
+  persisted-output restoration paths when older context is hidden.
+
+#### Task, Plan, And Subagent
+
+- `TodoWrite` is short-term session state.
+- durable `TaskRecord` and `PlanArtifact` are LangGraph-store-backed
+  collaboration/workflow state.
+- verifier subagents must resolve an explicit `PlanArtifact` before execution.
+- verifier evidence persists to the session ledger and must not mutate durable
+  tasks or plans.
+- current `run_subagent` is a bounded synchronous tool surface. It must not be
+  stretched into mailbox, coordinator, background daemon, or team lifecycle
+  semantics without a new source-backed contract.
+
+#### Hooks
+
+- Hooks are deterministic local lifecycle seams.
+- Hooks may block only at documented runtime/tool boundaries.
+- Hook-provided model-visible context must be bounded, whitespace-normalized,
+  and routed through the owning context/compact seam.
+- Hooks must not call tools, mutate transcript records, or become a hidden
+  plugin runtime.
+
+#### Memory
+
+- Long-term memory uses a durable backend distinct from the session ledger.
+- PostgreSQL is the current durable source of truth for long-term memory,
+  memory versions, extraction jobs, and agent memory scope metadata.
+- Redis is allowed as the current queue/lock surface for memory background jobs.
+- S3-compatible object storage is allowed for memory snapshot/archive payloads.
+- Main agent memory remains global by default.
+- Child/fork agent memory may use agent-private scope while still reading
+  global long-term memory when appropriate.
+- Session memory uses `RuntimeState["session_memory"]` and session
+  `state_snapshot` continuity.
+- Evidence records are not memory records.
+- Recovery briefs are not memory records.
+- A feature may claim "cross-session memory" only when it identifies which
+  backend survives the relevant boundary:
+  - same `agent.invoke` / same process
+  - same CLI session resume
+  - process restart
+  - workspace or machine migration
+- The current `StoreBackend` supports `none`, `memory`, and local `file` for
+  runtime store seams such as task/plan/background-run state and local testing.
+  It is still not the source of truth for durable long-term memory claims.
+
+### 4. Project-Level Assessment
+
+| Layer | Current judgment | Classification | Follow-up rule |
+|---|---|---|---|
+| transcript | Append-only JSONL ledger is the right foundation; count-based `message_index` and prefix-derived projection metadata are not enough for rich future timelines. | architecture + spec | Future transcript/projection work must define stable message identity and lineage before adding more projection behavior. |
+| session | Resume, evidence, compacts, and state snapshots have coherent ownership. | mostly architecture-correct | Preserve separation between raw history, virtual compacted view, evidence, and runtime state. |
+| compact | Manual/generated compact correctly persists records and keeps synthetic artifacts out of raw history. | architecture-correct | Persist only explicit session compact; keep live compact projection-only unless a new contract says otherwise. |
+| collapse | Live collapse is useful pressure mitigation but is a temporary projection concept, not a durable session concept. | spec gap risk | Any durable collapse store must first explain why it is not just compact history with different trigger metadata. |
+| runtime pressure | Middleware-level staged rewrite is LangChain-native and testable. | architecture-correct | Keep ordering, fail-open behavior, bounded evidence, and prompt-too-long retry tests as mandatory. |
+| task | Durable task/plan graph is correctly separate from TodoWrite. | architecture-correct | Do not add workflow semantics to todo state or transcript evidence. |
+| subagent | Built-in `general`/`verifier`/`explore`/`plan`, repo-local and plugin-provided child definitions, fork continuity, sidechain-thread resume, bounded background runs, and deferred-discovery lifecycle controls are local slices with read-only tool allowlists and structured result envelopes; they are not a team runtime. Runtime role/factory seams now distinguish main/subagent/fork construction, while `coordinator`/`worker` are reserved future roles only. | architecture gap for future cc | Mailbox/coordinator/team execution still require new task/subagent/team specs, not more string payloads in `run_subagent`, `run_fork`, or deferred lifecycle bridges. |
+| hooks | Local sync hooks are a safe foundation. | process/spec gap for extension lifecycle | Keep plugin/async/remote hooks deferred until a concrete lifecycle and trust contract exists. |
+| memory | Scoped memory quality gate is good; durable backend depth is not yet sufficient for process-surviving cross-session claims. | architecture gap | Add durable store backend contract before expanding memory extraction or claiming richer cc memory parity. |
+
+### 5. Architecture vs Spec vs Process Findings
+
+#### Architecture Findings
+
+- Stable transcript identity is still the largest foundation gap for future
+  timeline, visualization, collapse-store, and projection debugging work.
+- Durable memory needs a process-surviving store backend before it can carry the
+  full cross-session memory product requirement.
+- Subagent infrastructure supports verifier execution, but not yet cc-style
+  mailbox, coordinator, lifecycle, cancellation, or background work.
+- LangGraph checkpointer/store, JSONL transcript, and `RuntimeState` snapshots
+  are separate mechanisms; future work must not blur them into one "session
+  state" concept.
+
+#### H13 / H14 Readiness Gate
+
+Before implementing mailbox, `SendMessage`, Scratchpad, or coordinator-worker
+runtime behavior, future tasks must verify:
+
+- `run_subagent` and `run_fork` public schemas remain free of mailbox,
+  coordinator, worker, team, Scratchpad, and message-routing fields.
+- `coordinator` and `worker` are represented as runtime roles without
+  overloading `subagent` or `fork`.
+- coordinator tool projection is restricted by capability/role projection, not
+  by prompt-only instructions.
+- worker tool projection excludes team management and coordinator-only tools.
+- background run state distinguishes durable run records, bounded runtime
+  snapshots, and process-local worker handles before message delivery is added.
+- team/Scratchpad state has an owning future domain such as `teams/` or
+  `orchestration/`; it must not be hidden inside `sessions/`, `tool_system/`,
+  or `subagents/tools.py`.
+
+If any of these conditions are not true, open a runtime-readiness cleanup task
+before implementing H13/H14 behavior.
+
+#### Spec Findings
+
+- Existing focused specs are strong for individual compact/runtime/task
+  scenarios, but they did not previously define a project-level infrastructure
+  maturity gate across all core layers.
+- Collapse must stay explicitly documented as live projection until a durable
+  collapse-store contract exists.
+- "Memory durability" must be described by boundary, not by feature name.
+- Hook `additional_context` needs an owning model-visible seam for each new use;
+  hooks themselves must not become prompt assembly.
+
+#### Process Findings
+
+- Do not close future cc gaps by matching names such as `compact`, `collapse`,
+  `task`, `subagent`, or `memory`. Start from expected local effect and source
+  evidence, then choose the LangChain-native primitive.
+- Do not patch one bug at a time in context infrastructure without checking the
+  transcript/session/projection/evidence/memory ownership matrix.
+- Keep canonical rules in `.trellis/spec`; keep `coding-deepgent/README.md` and
+  `PROJECT_PROGRESS.md` as product summaries only.
+
+### 6. Prevention Mechanisms
+
+Every infrastructure PRD or implementation touching this scope must include:
+
+- `Layer`: one or more of `transcript`, `session`, `compact`, `collapse`,
+  `runtime_pressure`, `task`, `subagent`, `hooks`, `memory`.
+- `Expected effect`: concrete local benefit, not "closer to cc".
+- `Owning record/state`: JSONL record, LangGraph store namespace,
+  `RuntimeState` key, `RuntimeContext` field, prompt payload, or middleware
+  projection.
+- `Durability boundary`: none, live invocation, session resume, process restart,
+  workspace migration.
+- `Model-visible surface`: tool schema, system message, user message, context
+  payload, or no model-visible surface.
+- `Mutation rule`: append-only, projection-only, store put/update, state update,
+  or read-only.
+- `Evidence rule`: what bounded event/evidence is emitted, and which raw data is
+  forbidden.
+- `LangChain primitive`: tool, middleware, state schema, context schema,
+  checkpointer, store, graph node/subgraph, or explicit non-LangChain boundary.
+
+Required review checks:
+
+```bash
+rg -n "record_type|message_index|compact|collapse|session_memory|thread_id|checkpointer|store" coding-deepgent/src/coding_deepgent
+rg -n "wrap_model_call|wrap_tool_call|create_agent|RuntimeContext|RuntimeState|ToolRuntime" coding-deepgent/src/coding_deepgent
+rg -n "additional_context|append_evidence|runtime_event|VERDICT|run_subagent" coding-deepgent/src/coding_deepgent
+```
+
+Treat matches as ownership prompts, not automatic failures.
+
+### 7. Validation & Error Matrix
+
+| Change type | Must prove |
+|---|---|
+| transcript record change | raw history remains append-only; synthetic resume/compact artifacts are not persisted as messages |
+| session resume change | recovery brief, compacted history selection, evidence rendering, and state restoration remain distinct |
+| manual/generated compact change | one compact record may be appended; message indices for real messages remain contiguous |
+| live collapse/auto-compact change | projection changes only the active model call; no transcript rewrite or compact record append occurs |
+| runtime pressure threshold/order change | event order, fail-open behavior, and prompt-too-long retry behavior are covered |
+| task/plan change | TodoWrite remains separate; task dependencies and plan verification remain validated |
+| verifier subagent change | child runtime is read-only, plan-bound, and verifier evidence is bounded |
+| hook change | hook block/additional-context behavior is bounded and emitted through existing evidence/event seams |
+| memory change | quality gate rejects duplicates/transient state; durability boundary is explicit |
+
+### 8. Good / Base / Bad Cases
+
+#### Good
+
+```python
+# Live model-call pressure projection.
+processed = maybe_auto_compact_messages(
+    request.messages,
+    summarizer=request.model,
+    threshold_tokens=8000,
+    state=request.state,
+    hook_context=request.runtime.context,
+)
+```
+
+Expected:
+
+- model-facing messages may be compacted for this call
+- no JSONL transcript record is rewritten
+- bounded `auto_compact` evidence may be appended when a `SessionContext` exists
+
+#### Base
+
+```python
+store.append_compact(
+    session_context,
+    trigger="manual",
+    summary=summary,
+    original_message_count=10,
+    summarized_message_count=6,
+    kept_message_count=4,
+)
+```
+
+Expected:
+
+- explicit compact is an append-only transcript event
+- raw message history stays available
+- load-time compacted history can select the latest valid compact record
+
+#### Bad
+
+```python
+# Do not implement durable collapse by deleting old transcript messages.
+transcript[:] = collapse_live_messages_with_summary(transcript, summary="...")
+```
+
+Expected:
+
+- reject this design; collapse is live projection unless a new durable
+  collapse-store contract is approved
+
+### 9. Tests Required
+
+Use focused tests first, then broaden only when coupling changes.
+
+- Transcript/session/compact:
+  - `coding-deepgent/tests/sessions/test_sessions.py`
+  - `coding-deepgent/tests/cli/test_cli.py`
+  - `coding-deepgent/tests/compact/test_compact_artifacts.py`
+  - `coding-deepgent/tests/compact/test_message_projection.py`
+- Runtime pressure/collapse:
+  - `coding-deepgent/tests/compact/test_runtime_pressure.py`
+  - `coding-deepgent/tests/compact/test_compact_summarizer.py`
+  - `coding-deepgent/tests/runtime/test_app.py`
+- Task/subagent/workflow:
+  - `coding-deepgent/tests/tasks/test_tasks.py`
+  - `coding-deepgent/tests/subagents/test_subagents.py`
+  - `coding-deepgent/tests/tool_system/test_tool_system_registry.py`
+- Hooks/evidence:
+  - `coding-deepgent/tests/extensions/test_hooks.py`
+  - `coding-deepgent/tests/tool_system/test_tool_system_middleware.py`
+  - `coding-deepgent/tests/sessions/test_session_contributions.py`
+- Memory:
+  - `coding-deepgent/tests/memory/test_memory.py`
+  - `coding-deepgent/tests/memory/test_memory_context.py`
+  - `coding-deepgent/tests/memory/test_memory_integration.py`
+
+### 10. Wrong vs Correct
+
+#### Wrong
+
+```python
+# Ambiguous "session state" bucket.
+loaded_session.state["collapse_summary"] = summary
+loaded_session.state["task_status"] = "done"
+loaded_session.state["memory"] = evidence_text
+```
+
+Why wrong:
+
+- collapse projection, durable task state, and long-term memory have different
+  owners and durability boundaries
+- this makes future resume, verification, and memory extraction impossible to
+  reason about
+
+#### Correct
+
+```python
+# Use the owning surface for each concern.
+store.append_compact(session_context, trigger="manual", summary=summary, ...)
+update_task(runtime.store, task_id=task_id, status="completed")
+save_memory(
+    type="project",
+    fact_or_decision=durable_fact,
+    why=decision_reason,
+    how_to_apply=follow_up_impact,
+    runtime=runtime,
+)
+```
+
+Why correct:
+
+- each mutation goes through the domain that owns validation, persistence, and
+  tests
+- future cc features can compose the surfaces without reverse-engineering a
+  generic state blob
+
+#### Wrong
+
+```python
+# "Closer to cc" without a local effect.
+run_subagent(task="coordinate the team and keep mailbox state")
+```
+
+Why wrong:
+
+- current `run_subagent` is bounded and synchronous
+- mailbox/coordinator/team lifecycle is explicitly deferred and needs a new
+  task/subagent contract
+
+#### Correct
+
+```text
+Expected effect: verifier checks the saved plan with read-only tools and records
+bounded evidence in the parent session.
+Primitive: `run_subagent(agent_type="verifier", plan_id=...)`.
+```
+
+Why correct:
+
+- it states the concrete local effect
+- it stays within the existing LangChain-native tool/runtime/evidence boundary
diff --git a/.trellis/spec/backend/quality-guidelines.md b/.trellis/spec/backend/quality-guidelines.md
new file mode 100644
index 000000000..bf96dbf17
--- /dev/null
+++ b/.trellis/spec/backend/quality-guidelines.md
@@ -0,0 +1,215 @@
+# Quality Guidelines
+
+> Canonical code-review and quality rules for the `coding-deepgent` mainline.
+
+---
+
+## Scope
+
+These rules apply to current product work in:
+
+```text
+coding-deepgent/
+```
+
+Tutorial/reference material is not the review baseline unless a task explicitly
+targets it.
+
+---
+
+## Forbidden Patterns
+
+### 1. Tutorial/runtime coupling
+
+Do not introduce runtime or test dependencies on tutorial/reference layers:
+
+- `agents/`
+- `agents_deepagents/`
+- `docs/`
+- `web/`
+- root `skills/`
+
+Behavioral parity can be documented as reference knowledge, but product code
+must not depend on those directories.
+
+### 2. Business logic in composition shells
+
+Do not hide product rules in:
+
+- `containers/*`
+- `app.py`
+- `cli.py`
+- `bootstrap.py`
+
+These files may wire and expose behavior, but domain logic should live in the
+owning package.
+
+### 3. Boundary creep
+
+Do not let these domains absorb unrelated responsibilities:
+
+- `sessions/` -> transcript/resume/evidence only
+- `tool_system/` -> capability/guard/projection only
+- `containers/` -> composition only
+
+If a change does not belong naturally to that domain, move it.
+
+### 4. Runtime replacement drift
+
+Do not bypass LangChain/LangGraph-native seams casually.
+
+Avoid:
+
+- ad hoc custom query loops
+- hidden side executors that skip middleware/policy boundaries
+- tutorial-shell stage mirroring as the public product surface
+
+Use official `create_agent`, middleware, runtime context, and typed tool/schema
+seams unless a task explicitly approves a stronger deviation.
+
+### 5. Loose tool/schema fallbacks
+
+Do not hide model or schema mistakes behind permissive parsing.
+
+Avoid:
+
+- raw `dict[str, Any]` fallback parsing for structured tools
+- alias guessing such as `task -> content` or `doing -> in_progress`
+- `normalize_*` helpers used only to compensate for weak public schemas
+
+---
+
+## Required Patterns
+
+### 1. Keep the mainline explicit
+
+- Treat `coding-deepgent/` as the implementation target.
+- Treat `.trellis/` as the canonical norms/contracts layer.
+- When norms change, update Trellis docs instead of creating new parallel
+  product-local review/spec files.
+
+### 2. Preserve product shape
+
+The product should read as one cumulative app, not a parallel set of stage
+entrypoints.
+
+Required outcomes:
+
+- one integrated product surface
+- domain packages with clear ownership
+- explicit runtime/middleware boundaries
+
+### 3. Use bounded, typed contracts
+
+Prefer:
+
+- strict Pydantic schemas
+- explicit JSON contracts
+- bounded message/context payloads
+- deterministic policy and middleware behavior
+
+For LangChain/LangGraph implementation details, follow
+[LangChain-Native Implementation Guidelines](./langchain-native-guidelines.md).
+
+### 4. Keep review evidence focused
+
+When a change affects a mainline contract, reviewers should be able to point to:
+
+- the Trellis spec/plan that defines the boundary
+- the implementation seam that enforces it
+- the tests that prove it
+
+---
+
+## Testing Requirements
+
+### Minimum expectation
+
+For touched mainline files, run focused checks from `coding-deepgent/tests/`
+plus relevant static checks.
+
+Expected tools:
+
+- `pytest` on affected product tests
+- `ruff check` on touched files
+- `mypy` on touched typed modules where applicable
+
+### Test placement
+
+- product tests belong under `coding-deepgent/tests/`
+- tutorial/reference tests under root `tests/` should not be expanded as a
+  substitute for product verification
+
+### Preferred test style
+
+- focused, deterministic, no-network
+- assert boundary behavior, not only happy-path outputs
+- add regression tests when changing contracts or middleware ordering
+
+### Validation Scope Policy
+
+Default to focused validation first.
+
+Run:
+
+- focused tests for the touched domain
+- `ruff check` on touched Python files
+- `mypy` on touched typed modules where relevant
+
+Escalate to broader validation when:
+
+- a cross-layer contract changes
+- runtime/session/compact/task behavior changes
+- middleware ordering changes
+- focused tests fail in a way that suggests wider coupling
+- the user explicitly asks for broader validation
+
+Do not default to full-suite validation for every small change.
+
+---
+
+## Code Review Checklist
+
+### Review Output Format
+
+When asked for a review, report findings first, ordered by severity.
+
+Required shape:
+
+- `Critical` / `High` / `Medium` / `Low` findings first
+- each finding should include file and line when available
+- explain impact and concrete fix direction
+- list open questions or assumptions after findings
+- keep summaries secondary and brief
+
+If no findings are found, say so explicitly and mention residual risks or
+testing gaps.
+
+### Mainline scope
+
+- [ ] The change serves `coding-deepgent`, not tutorial parity by default.
+- [ ] No new dependency on `agents_deepagents` or other tutorial/reference code.
+
+### Responsibility boundaries
+
+- [ ] `containers/*` compose but do not own business rules.
+- [ ] Domain logic lives in the owning package.
+- [ ] `sessions/`, `tool_system/`, and `runtime/` boundaries remain coherent.
+
+### Product shape
+
+- [ ] The public surface still reads as one cumulative app.
+- [ ] No new stage-mirror or tutorial-shaped main entrypoint was introduced.
+
+### Contracts and invariants
+
+- [ ] Cross-layer behavior changes are reflected in Trellis specs when needed.
+- [ ] Structured payloads, bounded context behavior, and tool invariants remain valid.
+- [ ] Task/plan/verifier/session boundaries are preserved when touched.
+- [ ] LangChain tool/schema/middleware changes follow `langchain-native-guidelines.md`.
+
+### Verification
+
+- [ ] Focused product tests were updated or added.
+- [ ] `ruff check` and `mypy` were run when relevant.
+- [ ] Residual risks or deferred cleanup are stated explicitly.
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..f052b5afa
--- /dev/null
+++ b/.trellis/spec/backend/runtime-context-compaction-contracts.md
@@ -0,0 +1,24 @@
+# Runtime Context And Compaction Contracts
+
+> Index for `coding-deepgent` runtime context, session continuity, compact, and pressure-management contracts.
+
+This file is intentionally an overview. The executable contracts are split into focused docs so future agents can load only the relevant contract surface.
+
+## Contract Files
+
+| Contract | Scope | Read when changing |
+|---|---|---|
+| [Project Infrastructure Foundation Contracts](./project-infrastructure-foundation-contracts.md) | Project-level ownership/maturity gate across transcript/session/compact/collapse/runtime pressure/task/subagent/hooks/memory | Any cross-infrastructure cc feature, release audit, or change that could blur ledger/projection/store/runtime ownership |
+| [Tool Result Storage Contracts](./tool-result-storage-contracts.md) | Large tool-result persistence, preview references, model-visible persisted output markers | `tool_system`, large-output tools, persisted tool-output previews |
+| [Session Compact Contracts](./session-compact-contracts.md) | Session resume, manual/generated compact, compact transcript records, session memory, memory quality | `sessions`, CLI resume, compact artifacts, memory quality/session-memory continuity |
+| [Runtime Pressure Contracts](./runtime-pressure-contracts.md) | Live snip, microcompact, context collapse, auto/reactive compact, restoration messages, runtime pressure events/evidence | `compact.runtime_pressure`, model-call middleware, runtime pressure settings/events |
+
+## Maintenance Rules
+
+- Keep contract details in the focused files above.
+- Add new runtime/compact scenarios to the narrowest file that owns the behavior.
+- If a new scenario crosses all three surfaces, add a short coordination note here and detailed rules in each focused contract.
+- If a new scenario also touches task, subagent, hooks, or memory, first run the
+  project-level gate in
+  [Project Infrastructure Foundation Contracts](./project-infrastructure-foundation-contracts.md).
+- Use `coding-deepgent/tests/...` and `coding-deepgent/src/...` paths in new test/implementation references.
diff --git a/.trellis/spec/backend/runtime-pressure-contracts.md b/.trellis/spec/backend/runtime-pressure-contracts.md
new file mode 100644
index 000000000..9f1653f5a
--- /dev/null
+++ b/.trellis/spec/backend/runtime-pressure-contracts.md
@@ -0,0 +1,866 @@
+# Runtime Pressure Contracts
+
+> Executable contracts for live snip, microcompact, context collapse, auto/reactive compact, restoration, and runtime pressure evidence.
+
+## Scenario: Progressive Live Pressure Pipeline
+
+### 1. Scope / Trigger
+
+- Trigger: changes touching `RuntimePressureMiddleware.wrap_model_call()` ordering
+  or any helper that rewrites live model-call messages.
+- Applies when `Snip`, `MicroCompact`, `Collapse`, and `AutoCompact` should run
+  as a staged model-call preparation pipeline.
+
+### 2. Signatures
+
+```python
+class RuntimePressureMiddleware(AgentMiddleware):
+    snip_threshold_tokens: int | None
+    collapse_threshold_tokens: int | None
+    auto_compact_threshold_tokens: int | None
+```
+
+### 3. Contracts
+
+- Runtime pressure handling must remain LangChain middleware-level request
+  rewriting through `wrap_model_call()`.
+- The live pressure order is:
+  1. `snip_messages`
+  2. `microcompact_messages`
+  3. `maybe_collapse_messages`
+  4. `maybe_auto_compact_messages`
+  5. model call
+- These live rewrites must not append, delete, or replace JSONL transcript
+  records. Only explicit session/manual compact paths may persist compact
+  records.
+- Each stage may emit bounded runtime events, but event metadata must not include
+  raw prompt contents or raw summaries.
+- Later stages operate on the current model-facing projection returned by earlier
+  stages.
+
+### 4. Validation & Error Matrix
+
+| Case | Expected behavior |
+|---|---|
+| all four thresholds are crossed | runtime events appear in order: `snip`, `microcompact`, `context_collapse`, `auto_compact` |
+| a stage does not cross threshold | stage is skipped without blocking later eligible stages |
+| live rewrite happens during recorded session | evidence records are bounded summaries only |
+
+### 5. Tests Required
+
+- `coding-deepgent/tests/compact/test_runtime_pressure.py`
+- `coding-deepgent/tests/runtime/test_app.py`
+
+Required assertion points:
+
+- middleware pipeline order is stable
+- settings values are wired into `RuntimePressureMiddleware`
+- live rewrites do not depend on tutorial/reference modules
+
+## Scenario: Live Snip
+
+### 1. Scope / Trigger
+
+- Trigger: changes touching `snip_messages(...)`, snip thresholds, or live
+  model-facing projection trimming.
+- Applies when old messages should be hidden from the current model call before
+  heavier summarization or compaction is attempted.
+
+### 2. Signatures
+
+```python
+def snip_messages(
+    messages: Sequence[BaseMessage],
+    *,
+    threshold_tokens: int | None,
+    keep_recent_messages: int = DEFAULT_KEEP_RECENT_MESSAGES_AFTER_SNIP,
+) -> list[BaseMessage]: ...
+```
+
+### 3. Contracts
+
+- `snip_messages(...)` must be deterministic and model-call local.
+- If `threshold_tokens is None`, messages must remain unchanged.
+- Default product settings may keep snip disabled with
+  `snip_threshold_tokens == None` because snip is a lossy projection-only stage.
+  Enable it only when a concrete pressure threshold is configured.
+- If estimated message tokens are below `threshold_tokens`, messages must remain
+  unchanged.
+- If the threshold is crossed, the model-facing projection becomes:
+  1. one live snip boundary `SystemMessage`
+  2. preserved recent tail messages
+- The snip boundary must expose bounded counts such as `hidden_messages` and
+  `kept_messages`, not hidden prompt contents.
+- If the preserved tail starts with a `ToolMessage`, the helper must include the
+  matching prior `AIMessage` tool call when present.
+- Existing live pressure artifact messages should not be stacked repeatedly.
+
+### 4. Validation & Error Matrix
+
+| Case | Expected behavior |
+|---|---|
+| estimated tokens below threshold | history unchanged |
+| threshold crossed | boundary + recent tail returned |
+| preserved tail starts with tool result | matching tool-call AI message is preserved |
+| `threshold_tokens < 1` | `ValueError` |
+| `keep_recent_messages < 0` | `ValueError` |
+
+### 5. Tests Required
+
+- `coding-deepgent/tests/compact/test_runtime_pressure.py`
+
+Required assertion points:
+
+- older messages are hidden from model-facing projection
+- input messages are not mutated
+- tool-call/tool-result tail pairing is preserved
+
+## Scenario: Live Microcompact
+
+### 1. Scope / Trigger
+
+- Trigger: changes touching `coding_deepgent.compact.runtime_pressure`,
+  middleware ordering, capability metadata for compactable tools, or live
+  message-history pressure handling.
+- Applies when older tool results can be cleared before a model call to reduce
+  live context pressure without performing a full compact.
+- This is a cross-layer contract because tool-call metadata, middleware history
+  rewriting, capability eligibility, and runtime message invariants must agree.
+
+### 2. Signatures
+
+```python
+def microcompact_messages(
+    messages: Sequence[BaseMessage],
+    *,
+    registry: CapabilityRegistry,
+    keep_recent_tool_results: int = DEFAULT_KEEP_RECENT_TOOL_RESULTS,
+    min_content_chars: int = DEFAULT_MICROCOMPACT_MIN_CONTENT_CHARS,
+) -> list[BaseMessage]: ...
+
+@dataclass(frozen=True, slots=True)
+class MicrocompactStats:
+    cleared_tool_results: int = 0
+    kept_tool_results: int = 0
+    tokens_saved_estimate: int = 0
+    keep_recent_tool_results: int = DEFAULT_KEEP_RECENT_TOOL_RESULTS
+    protected_recent_tokens: int | None = DEFAULT_MICROCOMPACT_PROTECT_RECENT_TOKENS
+
+@dataclass(frozen=True, slots=True)
+class MicrocompactResult:
+    messages: list[BaseMessage]
+    stats: MicrocompactStats
+
+def microcompact_messages_with_stats(
+    messages: Sequence[BaseMessage],
+    *,
+    registry: CapabilityRegistry,
+    keep_recent_tool_results: int = DEFAULT_KEEP_RECENT_TOOL_RESULTS,
+    min_content_chars: int = DEFAULT_MICROCOMPACT_MIN_CONTENT_CHARS,
+    protect_recent_tokens: int | None = DEFAULT_MICROCOMPACT_PROTECT_RECENT_TOKENS,
+    min_saved_tokens: int = DEFAULT_MICROCOMPACT_MIN_PRUNE_SAVED_TOKENS,
+) -> MicrocompactResult: ...
+
+@dataclass(frozen=True, slots=True)
+class TimeBasedMicrocompactDecision:
+    attempted: bool
+    result: MicrocompactResult | None = None
+    gap_minutes: int | None = None
+
+def maybe_time_based_microcompact_messages(
+    messages: Sequence[BaseMessage],
+    *,
+    registry: CapabilityRegistry,
+    context: object,
+    gap_threshold_minutes: int | None,
+    now: Callable[[], datetime],
+    keep_recent_tool_results: int = DEFAULT_KEEP_RECENT_TOOL_RESULTS,
+    min_content_chars: int = DEFAULT_MICROCOMPACT_MIN_CONTENT_CHARS,
+    min_saved_tokens: int = DEFAULT_MICROCOMPACT_MIN_SAVED_TOKENS,
+    main_entrypoint: str = "coding-deepgent",
+    main_agent_name: str = "coding-deepgent",
+) -> TimeBasedMicrocompactDecision: ...
+
+class RuntimePressureMiddleware(AgentMiddleware):
+    registry: CapabilityRegistry
+    microcompact_time_gap_minutes: int | None
+    microcompact_min_saved_tokens: int
+    microcompact_protect_recent_tokens: int | None
+    microcompact_min_prune_saved_tokens: int
+    main_entrypoint: str
+    main_agent_name: str
+```
+
+### 3. Contracts
+
+- `microcompact_messages(...)` must be deterministic and model-call local. It
+  must not persist transcript mutations by itself.
+- Only tool results whose originating tool capability is marked
+  `microcompact_eligible` may be compacted.
+- Error tool results must not be compacted.
+- If the number of compactable tool results is less than or equal to
+  `keep_recent_tool_results`, messages must remain unchanged.
+- If `microcompact_protect_recent_tokens is None`, ordinary MicroCompact uses
+  the existing count-based keep policy.
+- If `microcompact_protect_recent_tokens` is configured, ordinary
+  MicroCompact must use token-budget protection instead of count-based
+  protection:
+  - walk compactable successful tool results from newest to oldest
+  - keep a newest suffix whose estimated content tokens fit within the budget
+  - always keep at least one newest compactable tool result even if it exceeds
+    the budget
+  - clear older eligible compactable tool results outside that suffix
+- If token-budget pruning would save fewer than
+  `microcompact_min_prune_saved_tokens`, messages must remain unchanged and no
+  microcompact event should be emitted.
+- Older compactable tool results beyond the kept recent tail may have their
+  `ToolMessage.content` replaced, but must preserve:
+  - `tool_call_id`
+  - `status`
+  - `artifact`
+  - message ordering
+- If a compacted tool result artifact contains a persisted output `path`, the
+  replacement content must keep that path model-visible.
+- Recent compactable tool results within the kept tail must remain unchanged.
+- Ineligible tool results must remain unchanged.
+- `microcompact_messages_with_stats(...)` must use the same rewrite semantics
+  as `microcompact_messages(...)` and return bounded local observability stats.
+- `tokens_saved_estimate` is a deterministic local estimate derived from the
+  original cleared tool-result content minus the replacement marker content. It
+  is not provider billing or exact tokenizer output.
+- Time-based MicroCompact must be disabled when
+  `microcompact_time_gap_minutes is None`.
+- Time-based MicroCompact may run only for the configured main runtime context:
+  `RuntimeContext.entrypoint == main_entrypoint` and
+  `RuntimeContext.agent_name == main_agent_name`.
+- If no parseable timestamp exists on a prior `AIMessage`, time-based
+  MicroCompact must fail open and skip.
+- If `now - latest_assistant_timestamp` is below
+  `microcompact_time_gap_minutes`, time-based MicroCompact must skip.
+- If the time-gap trigger fires, aggressive keep-recent must floor to at least
+  one recent compactable tool result: `max(1, keep_recent_tool_results)`.
+- If the time-gap trigger fires but estimated saved tokens are below
+  `microcompact_min_saved_tokens`, no clearing occurs and the normal count-based
+  MicroCompact fallback must not run for that model call.
+- MicroCompact runtime event metadata must include bounded fields:
+  - `cleared_tool_results` for backward compatibility
+  - `tools_cleared`
+  - `tools_kept`
+  - `tokens_saved_estimate`
+  - `keep_recent`
+- Token-budget MicroCompact runtime event metadata must additionally include:
+  - `protected_recent_tokens`
+- Time-based MicroCompact runtime event metadata must additionally include:
+  - `trigger == "time_gap"`
+  - `gap_minutes`
+- `RuntimePressureMiddleware.wrap_model_call()` may replace request messages for
+  the current model call only. It must not introduce a custom query runtime.
+
+### 4. Validation & Error Matrix
+
+| Case | Expected behavior |
+|---|---|
+| 4 eligible compactable tool results with keep-last=2 | first 2 older tool results are compacted; last 2 remain unchanged |
+| eligible tool result with persisted-output artifact path | compacted content keeps the path visible |
+| eligible tool result without persisted artifact | compacted content uses the generic cleared marker |
+| ineligible tool result | unchanged |
+| error tool result | unchanged |
+| microcompact clears older tool results | runtime event and session evidence include cleared/kept counts plus local saved-token estimate |
+| token-budget mode unset | existing count-based behavior is preserved |
+| token-budget mode set | recent compactable tool results within protected budget remain inline |
+| latest compactable result exceeds token budget | latest compactable result remains inline; older eligible results may clear |
+| token-budget estimated savings below minimum | no clearing and no event |
+| time-based microcompact disabled | no time-gap evaluation or event |
+| non-main runtime context | no time-based clearing |
+| no assistant timestamp | no time-based clearing |
+| idle gap under threshold | no time-based clearing |
+| idle gap over threshold | older eligible tool results clear before count-based fallback |
+| estimated savings below configured minimum | no clearing and no count-based fallback for that call |
+| `keep_recent_tool_results < 0` | `ValueError` |
+
+### 5. Tests Required
+
+- `coding-deepgent/tests/compact/test_runtime_pressure.py`
+- `coding-deepgent/tests/runtime/test_app.py`
+- `coding-deepgent/tests/memory/test_memory_integration.py`
+
+Required assertion points:
+
+- older eligible tool results are compacted deterministically
+- recent eligible tool results remain inline
+- ineligible tool results are not rewritten
+- microcompact event/evidence metadata remains bounded and includes
+  `tools_cleared`, `tools_kept`, `tokens_saved_estimate`, and `keep_recent`
+- token-budget MicroCompact covers default compatibility, protected recent
+  budget, keep-at-least-one behavior, minimum-savings skip, and
+  `protected_recent_tokens` metadata
+- time-based MicroCompact covers disabled, non-main, missing timestamp,
+  under-threshold gap, over-threshold gap, keep-recent floor, and minimum
+  savings skip cases
+- app/container middleware chain includes runtime pressure middleware before tool guard
+
+## Scenario: Live Context Collapse
+
+### 1. Scope / Trigger
+
+- Trigger: changes touching `maybe_collapse_messages(...)`, collapse thresholds,
+  collapse summary artifacts, or summarizer use before auto-compact.
+- Applies when older live context should be summarized before the heavier
+  auto-compact stage.
+- This is a cross-layer contract because summarizer usage, message rewriting,
+  recent-tail preservation, restoration hints, settings, and runtime evidence
+  must agree.
+
+### 2. Signatures
+
+```python
+def maybe_collapse_messages(
+    messages: Sequence[BaseMessage],
+    *,
+    summarizer: Any,
+    threshold_tokens: int | None,
+    context_window_tokens: int | None = None,
+    trigger_ratio: float | None = None,
+    keep_recent_messages: int = DEFAULT_KEEP_RECENT_MESSAGES_AFTER_COLLAPSE,
+    assist_context: str | None = None,
+) -> list[BaseMessage]: ...
+
+def collapse_live_messages_with_summary(
+    messages: Sequence[BaseMessage],
+    *,
+    summary: str,
+    keep_recent_messages: int = DEFAULT_KEEP_RECENT_MESSAGES_AFTER_COLLAPSE,
+) -> list[BaseMessage]: ...
+
+@dataclass(frozen=True, slots=True)
+class LiveCompactionResult:
+    boundary_message: SystemMessage
+    summary_message: HumanMessage
+    preserved_tail: tuple[BaseMessage, ...]
+    trigger: str
+    restoration_messages: tuple[SystemMessage, ...] = ()
+    original_token_estimate: int = 0
+    projected_token_estimate: int = 0
+
+    @property
+    def restored_path_count(self) -> int: ...
+    def render(self) -> list[BaseMessage]: ...
+
+def collapse_live_messages_with_result(
+    messages: Sequence[BaseMessage],
+    *,
+    summary: str,
+    keep_recent_messages: int = DEFAULT_KEEP_RECENT_MESSAGES_AFTER_COLLAPSE,
+) -> LiveCompactionResult: ...
+```
+
+### 3. Contracts
+
+- Context collapse must remain middleware-level request rewriting. It must not
+  introduce a custom query runtime.
+- If `threshold_tokens is None`, messages must remain unchanged.
+- If `threshold_tokens is None` and no ratio trigger is configured, messages
+  must remain unchanged.
+- If estimated message tokens are below `threshold_tokens` and below configured
+  `estimated_tokens / context_window_tokens >= trigger_ratio`, messages must
+  remain unchanged.
+- If the threshold is crossed, the helper may call the existing compact
+  summarizer seam through the provided model-like `.invoke()` path.
+- Ratio-triggered collapse uses deterministic local token estimates and
+  configured `model_context_window_tokens`; it is not provider billing/tokenizer
+  accounting.
+- If current session-memory assist text is available, collapse may pass it to
+  the summarizer as bounded assist text.
+- Summarizer failure or invalid summary must fail open: the original
+  model-facing messages must be preserved so auto-compact and the model call can
+  still proceed.
+- `collapse_live_messages_with_summary(...)` must produce:
+  1. one live collapse boundary `SystemMessage`
+  2. one live collapse summary `HumanMessage`
+  3. optional restoration `SystemMessage` for collapsed-away persisted-output
+     paths
+  4. preserved recent tail messages
+- If the preserved tail starts with a `ToolMessage`, the helper must include the
+  matching prior `AIMessage` tool call when present.
+- Collapse preserved-tail selection should avoid splitting a recent
+  assistant-led work unit when possible. A local implementation may snap the
+  preserved tail backward to the nearest assistant-round boundary instead of
+  preserving only an arbitrary message-count suffix.
+- Collapse summaries remain live model-facing artifacts and must not be
+  persisted as session compact records.
+- When the runtime has both:
+  - an active `session_context`, and
+  - a non-model-visible transcript-projection lineage for the current request,
+  a successful live collapse may persist a separate `transcript_event` collapse
+  record to the session ledger.
+- Collapse-record persistence must:
+  - reference raw transcript coverage through stable `message_id` fields
+  - skip persistence rather than invent coverage when the current live
+    projection cannot be mapped back to raw transcript messages
+  - keep bounded metadata only, such as trigger, estimated token count,
+    entrypoint, agent name, and whether session-memory assist was used
+- `collapse_live_messages_with_result(...)` must own boundary, summary,
+  restoration messages, preserved tail, trigger, and token estimates.
+- `collapse_live_messages_with_summary(...)` must remain a compatibility wrapper
+  returning `collapse_live_messages_with_result(...).render()`.
+- `LiveCompactionResult.render()` order is stable: boundary, summary,
+  restoration messages, preserved tail.
+
+### 4. Validation & Error Matrix
+
+| Case | Expected behavior |
+|---|---|
+| estimated tokens below threshold | history unchanged |
+| threshold crossed and summarizer succeeds | live collapse boundary + summary + preserved tail returned |
+| ratio trigger crossed and token threshold is unset | live collapse boundary + summary + preserved tail returned |
+| threshold crossed during recorded session with transcript projection lineage | live collapse boundary + summary returned and one collapse transcript event is appended |
+| current session-memory artifact exists | summarizer request may receive bounded assist text |
+| compacted-away persisted output path exists | restoration message includes the path |
+| preserved tail starts with tool result | matching tool-call AI message is preserved |
+| summarizer raises or returns invalid summary | original history preserved |
+| `threshold_tokens < 1` | `ValueError` |
+| `context_window_tokens < 1` | `ValueError` |
+| `trigger_ratio` outside `[0, 1]` | `ValueError` |
+| `keep_recent_messages < 0` | `ValueError` |
+
+### 5. Tests Required
+
+- `coding-deepgent/tests/compact/test_runtime_pressure.py`
+- `coding-deepgent/tests/compact/test_compact_summarizer.py`
+- `coding-deepgent/tests/runtime/test_app.py`
+- `coding-deepgent/tests/sessions/test_sessions.py`
+
+Required assertion points:
+
+- threshold crossing triggers summarizer-backed context collapse
+- ratio crossing can trigger summarizer-backed context collapse
+- recorded live collapse can persist a collapse transcript event when raw
+  projection lineage is available
+- collapse fail-open preserves original messages
+- collapsed history shape includes boundary and summary messages
+- structured collapse result render order is stable and exposes bounded
+  metadata such as trigger, restored path count, and estimated token counts
+- restoration message includes collapsed-away persisted-output paths when present
+- tool-call/tool-result tail pairing is preserved
+- preserved tail may snap backward to a recent assistant-round boundary to keep
+  continuity stronger than a pure message-count suffix
+- collapse runs before auto-compact in the middleware pipeline
+
+## Scenario: Live Auto-Compact And Restoration
+
+### 1. Scope / Trigger
+
+- Trigger: changes touching live compact thresholding, compact summarizer use
+  during a model call, or post-compact restoration messages.
+- Applies when runtime pressure handling can proactively summarize older live
+  history before a model call and preserve a bounded continuation tail.
+- This is a cross-layer contract because message estimation, summarizer usage,
+  compact boundary shape, preserved-tail rules, and restoration hints must
+  agree.
+
+### 2. Signatures
+
+```python
+def estimate_message_tokens(messages: Sequence[BaseMessage]) -> int: ...
+
+def maybe_auto_compact_messages(
+    messages: Sequence[BaseMessage],
+    *,
+    summarizer: Any,
+    threshold_tokens: int | None,
+    keep_recent_messages: int = DEFAULT_KEEP_RECENT_MESSAGES,
+    assist_context: str | None = None,
+    state: Any = None,
+    ptl_retry_limit: int = 0,
+) -> list[BaseMessage]: ...
+
+@dataclass(frozen=True, slots=True)
+class AutoCompactResult:
+    messages: list[BaseMessage]
+    attempted: bool = False
+    compacted: bool = False
+    failed: bool = False
+
+def maybe_auto_compact_messages_with_status(
+    messages: Sequence[BaseMessage],
+    *,
+    summarizer: Any,
+    threshold_tokens: int | None,
+    keep_recent_messages: int = DEFAULT_KEEP_RECENT_MESSAGES,
+    assist_context: str | None = None,
+    state: Any = None,
+    ptl_retry_limit: int = 0,
+) -> AutoCompactResult: ...
+
+def compact_live_messages_with_summary(
+    messages: Sequence[BaseMessage],
+    *,
+    summary: str,
+    keep_recent_messages: int = DEFAULT_KEEP_RECENT_MESSAGES,
+    state: Any = None,
+) -> list[BaseMessage]: ...
+
+def compact_live_messages_with_result(
+    messages: Sequence[BaseMessage],
+    *,
+    summary: str,
+    keep_recent_messages: int = DEFAULT_KEEP_RECENT_MESSAGES,
+    state: Any = None,
+) -> LiveCompactionResult: ...
+
+def reactive_compact_messages(
+    messages: Sequence[BaseMessage],
+    *,
+    summarizer: Any,
+    keep_recent_messages: int = DEFAULT_KEEP_RECENT_MESSAGES,
+    assist_context: str | None = None,
+) -> list[BaseMessage]: ...
+```
+
+### 3. Contracts
+
+- Auto-compact must remain middleware-level request rewriting. It must not
+  introduce a custom query runtime in this stage.
+- `estimate_message_tokens(...)` may use local deterministic token estimates.
+  It is not provider billing/tokenizer output.
+- Local live compact thresholds may be settings-backed. The current local
+  threshold and kept-tail counts are product config, not provider-discovered
+  context-window truth.
+- If estimated message tokens are below `threshold_tokens`, messages must remain
+  unchanged.
+- If estimated message tokens exceed `threshold_tokens`, the middleware may call
+  the compact summarizer through the provided model-like `.invoke()` seam.
+- If a current valid session-memory artifact is present in runtime state,
+  live compact may pass it to the summarizer as bounded assist text.
+- After a successful live auto-compact or reactive compact, the runtime may
+  refresh `state["session_memory"]` through the existing local threshold policy.
+  This refresh remains bounded and local; it is not a separate background
+  extraction workflow.
+- Summarizer failure must fail open in this stage: the original message history
+  must be preserved so later fallback behavior can still run.
+- `maybe_auto_compact_messages(...)` must remain a compatibility wrapper that
+  returns only messages.
+- `maybe_auto_compact_messages_with_status(...)` must distinguish threshold not
+  attempted, attempted-and-compacted, and attempted-and-failed-open outcomes.
+- Proactive AutoCompact observability must emit a bounded `auto_compact`
+  runtime event with `outcome == "attempted"` when the threshold is crossed,
+  and a second bounded `auto_compact` event with `outcome == "succeeded"` only
+  after live compaction succeeds.
+- Successful AutoCompact events must include bounded local estimates:
+  `pre_compact_total`, `post_compact_total`, `tokens_saved_estimate`, and
+  `hidden_messages`. These are deterministic local estimates, not provider
+  billing or tokenizer truth.
+- After a live AutoCompact or context collapse succeeds, the first successful
+  following model call must emit one `post_autocompact_turn` canary event with:
+  `pre_compact_total`, `post_compact_total`, `new_turn_input`, and
+  `new_turn_output`.
+- `compact_live_messages_with_result(...)` must own boundary, summary,
+  restoration messages, preserved tail, trigger, and token estimates.
+- `compact_live_messages_with_summary(...)` must remain a compatibility wrapper
+  returning `compact_live_messages_with_result(...).render()`.
+- `LiveCompactionResult.render()` order is stable: boundary, summary,
+  restoration messages, preserved tail.
+- Post-compact state restoration may add bounded restoration `SystemMessage`
+  entries through the structured result.
+- Current local restoration state includes active todos from runtime state:
+  `status in {"pending", "in_progress"}`.
+- Active todo restoration must be bounded and must not include completed todos.
+- Durable plan/verifier restoration requires a stable runtime-state source and
+  should not be fabricated from unrelated stores.
+- `PreCompact` hooks may contribute bounded `additional_context` that is passed
+  to the compact summarizer through the existing assist-context seam.
+- `PostCompact` hooks may contribute bounded `additional_context` that is
+  rendered as restoration messages through `LiveCompactionResult`.
+- Pre/PostCompact hooks must not call tools, mutate transcript records, or own
+  compact persistence.
+- Blank hook context is ignored; hook context is whitespace-normalized and
+  bounded before becoming model-visible.
+- `RuntimePressureMiddleware` may track consecutive proactive AutoCompact
+  failures on the middleware instance when `auto_compact_max_failures` is set.
+- Proactive AutoCompact failures increment only when the threshold was crossed
+  and summarization/compaction failed open.
+- A successful proactive AutoCompact resets the consecutive failure count.
+- When the failure count reaches `auto_compact_max_failures`, later model calls
+  skip proactive AutoCompact and emit bounded `auto_compact` runtime metadata:
+  - `trigger == "failure_circuit_breaker"`
+  - `failure_count`
+  - `max_failures`
+- `auto_compact_max_failures is None` preserves previous fail-open behavior
+  without circuit-breaker skip events.
+- When the proactive compact summarizer raises a prompt-too-long style error,
+  `maybe_auto_compact_messages_with_status(...)` may retry with a shortened
+  summary source up to `auto_compact_ptl_retry_limit`.
+- Each prompt-too-long retry must drop the oldest summary-source message group
+  and keep the original model-facing message list unchanged.
+- If all prompt-too-long retries are exhausted, AutoCompact fails open and the
+  attempt may count toward the failure circuit breaker.
+- Non prompt-too-long summarizer failures must not enter the PTL retry loop.
+- `compact_live_messages_with_summary(...)` must produce:
+  1. one live compact boundary `SystemMessage`
+  2. one live compact summary `HumanMessage`
+  3. optional restoration `SystemMessage` for compacted-away persisted-output
+     paths
+  4. preserved recent tail messages
+- If the preserved tail starts with a `ToolMessage`, the helper must include the
+  matching prior `AIMessage` tool call when present.
+- Restoration messages may only include persisted-output paths that were
+  compacted away and are not already present in the preserved tail.
+- If the model call still fails with a prompt-too-long style error after the
+- proactive path, runtime pressure middleware may first drain existing collapse
+  summaries once, then perform one reactive compact retry using the same
+  summarizer seam if the drained request still fails.
+- Collapse drain removes bounded collapse summary text from the model-facing
+  projection only. It must not delete or rewrite persisted raw transcript or
+  collapse records.
+- Reactive compact must only retry once per intercepted model call in this
+  stage. Non prompt-too-long failures must be re-raised unchanged.
+
+### 4. Validation & Error Matrix
+
+| Case | Expected behavior |
+|---|---|
+| estimated tokens below threshold | history unchanged |
+| estimated tokens above threshold and summarizer succeeds | live compact boundary + summary + preserved tail returned |
+| current session-memory artifact exists | summarizer request receives bounded assist text |
+| successful live compact with missing/stale session memory | runtime state may refresh `session_memory` with `source=live_compact` |
+| repeated proactive AutoCompact failures reach configured max | subsequent proactive AutoCompact is skipped and bounded skip event is emitted |
+| proactive AutoCompact succeeds after prior failures | consecutive failure count resets |
+| `auto_compact_max_failures is None` | summarizer failures continue to fail open without skip events |
+| compact summarizer raises prompt-too-long and retry limit remains | oldest summary-source group is dropped and summarizer is retried |
+| compact summarizer raises prompt-too-long until retry limit is exhausted | original history is preserved and the attempt fails open |
+| compact summarizer raises non prompt-too-long error | no PTL retry loop; original history is preserved |
+| compacted-away persisted output path exists | restoration message includes the path |
+| runtime state has active todos during compact | restoration message includes bounded pending/in-progress todos |
+| runtime state has completed todos only | no todo restoration message is added |
+| PreCompact hook returns additional context | summarizer receives bounded assist context |
+| PostCompact hook returns additional context | rendered compact projection includes bounded restoration context |
+| Pre/PostCompact hook returns blank context | context is ignored |
+| preserved tail starts with tool result | matching tool-call AI message is preserved |
+| summarizer raises or returns invalid summary | original history preserved |
+| handler raises prompt-too-long style error | one reactive compact retry is attempted |
+| handler raises prompt-too-long after collapse projection exists | one collapse drain retry is attempted before reactive compact |
+| handler raises non prompt-too-long error | error is re-raised without retry |
+| `threshold_tokens < 1` | `ValueError` |
+| `keep_recent_messages < 0` | `ValueError` |
+
+### 5. Tests Required
+
+- `coding-deepgent/tests/compact/test_runtime_pressure.py`
+- `coding-deepgent/tests/compact/test_compact_summarizer.py`
+- `coding-deepgent/tests/runtime/test_app.py`
+
+Required assertion points:
+
+- threshold crossing triggers proactive compact
+- current session-memory artifact can flow into live compact assist text
+- successful live compact can refresh in-memory/session runtime `session_memory` state when due
+- compacted history shape includes boundary and summary messages
+- structured compact result render order is stable and exposes bounded metadata
+  such as trigger, restored path count, and estimated token counts
+- restoration message includes compacted-away persisted-output paths
+- active todos restore after live compact without dumping completed todos
+- PreCompact and PostCompact hook additional context flows through bounded
+  compact assist/restoration seams
+- tool-call/tool-result tail pairing is preserved
+- summarizer failures do not corrupt the live history
+- failure circuit breaker skips repeated doomed proactive AutoCompact attempts
+- successful proactive AutoCompact resets failure count
+- prompt-too-long summarizer source retry is bounded and can succeed after
+  dropping oldest context
+- exhausted prompt-too-long summarizer retries fail open and can trip the
+  failure circuit breaker
+- prompt-too-long fallback retries only once
+- collapse projection drain runs before reactive compact on prompt-too-long
+
+## Scenario: Subagent Spawn Pressure Guard
+
+### 1. Scope / Trigger
+
+- Trigger: changes touching `run_subagent`, verifier child execution, runtime
+  context pressure settings, or subagent evidence.
+- Applies when high context pressure should block spawning child agents until
+  the parent context is collapsed or compacted.
+
+### 2. Contracts
+
+- Spawn guard is disabled unless both `model_context_window_tokens` and
+  `subagent_spawn_guard_ratio` are configured on `RuntimeContext`.
+- The guard uses deterministic local token estimates over the current runtime
+  state's model messages.
+- If `estimated_tokens / model_context_window_tokens` is below the guard ratio,
+  subagent execution proceeds unchanged.
+- If the ratio is at or above the guard ratio, `run_subagent` returns a bounded
+  model-visible warning and does not execute the child agent.
+- The guard emits a bounded `subagent_spawn_guard` runtime event and, when an
+  active `session_context` exists, appends bounded session evidence.
+- Guard metadata may include only bounded pressure fields such as
+  `estimated_token_count`, `context_window_tokens`, and
+  `estimated_token_ratio_percent`.
+
+### 3. Validation & Error Matrix
+
+| Case | Expected behavior |
+|---|---|
+| guard settings unset | subagent execution proceeds unchanged |
+| pressure below guard ratio | subagent execution proceeds unchanged |
+| pressure at or above guard ratio | bounded block message is returned and child agent is not executed |
+| recorded session exists | bounded `runtime_event` evidence is appended |
+
+### 4. Tests Required
+
+- `coding-deepgent/tests/subagents/test_subagents.py`
+
+## Scenario: Runtime Pressure Recovery Summary
+
+### 1. Scope / Trigger
+
+- Trigger: changes touching recovery brief contributions or compact/runtime
+  event aggregation across resume boundaries.
+- Applies when runtime pressure activity should be summarized in recovery
+  surfaces after the session is resumed.
+
+### 2. Contracts
+
+- Recovery brief contributions may aggregate `runtime_event` evidence with
+  `event_kind in {"snip", "microcompact", "context_collapse", "auto_compact",
+  "reactive_compact"}` into a bounded `Runtime pressure:` section.
+- The section must remain summary-only:
+  - counts by event kind are allowed
+  - raw compact payloads, raw summaries, and full prompt contents are not
+    allowed
+- If no runtime pressure events exist, the contribution may return `None`.
+
+### 3. Tests Required
+
+- `coding-deepgent/tests/sessions/test_session_contributions.py`
+- any focused recovery brief rendering regressions touched by the change
+
+## Scenario: Live Runtime Pressure Observability
+
+### 1. Scope / Trigger
+
+- Trigger: changes touching runtime-pressure event emission, session evidence
+  persistence for compact events, or event metadata for live compact behavior.
+- Applies when microcompact / auto-compact / reactive compact should become
+  observable through `event_sink` and, when recording is active, through
+  bounded session evidence.
+
+### 2. Contracts
+
+- Runtime pressure middleware may emit structured `RuntimeEvent` records for:
+  - `snip`
+  - `microcompact`
+  - `context_collapse`
+  - `auto_compact`
+  - `post_autocompact_turn`
+  - `reactive_compact`
+  - `subagent_spawn_guard`
+  - `token_budget`
+- Event metadata must stay bounded and may include:
+  - `source == "runtime_pressure"`
+  - `strategy`
+  - `outcome`
+  - `hidden_messages`
+  - `cleared_tool_results`
+  - `tools_cleared`
+  - `tools_kept`
+  - `tokens_saved_estimate`
+  - `keep_recent`
+  - `protected_recent_tokens`
+  - `trigger`
+  - `gap_minutes`
+  - `failure_count`
+  - `max_failures`
+  - `collapsed_messages`
+  - `restored_path_count`
+  - `used_session_memory_assist`
+  - `estimated_token_count`
+  - `context_window_tokens`
+  - `estimated_token_ratio_percent`
+  - `drained_summaries`
+  - `pre_compact_total`
+  - `post_compact_total`
+  - `new_turn_input`
+  - `new_turn_output`
+  - `input_token_estimate`
+  - `output_token_estimate`
+  - `total_token_estimate`
+  - `response_message_count`
+- Session evidence persistence for runtime pressure events must reuse the
+  existing `append_runtime_event_evidence(...)` seam rather than introducing a
+  second compact-specific ledger.
+- Runtime pressure event evidence must remain bounded summary evidence, not raw
+  transcript dumps or full summarizer payloads.
+- `token_budget` may remain sink-only and should not be persisted as session
+  evidence by default because it fires per assistant response turn.
+
+### 3. Validation & Error Matrix
+
+| Case | Expected behavior |
+|---|---|
+| snip happens during live request | `event_sink` receives `snip` event |
+| microcompact happens during live request | `event_sink` receives `microcompact` event |
+| context collapse happens during live request | `event_sink` receives `context_collapse` event |
+| auto-compact threshold is crossed | `event_sink` receives `auto_compact` with `outcome == "attempted"` |
+| auto-compact succeeds | `event_sink` receives `auto_compact` with `outcome == "succeeded"` |
+| first successful model call after compact/collapse | `event_sink` receives one `post_autocompact_turn` event |
+| model call succeeds | `event_sink` receives one bounded `token_budget` event |
+| reactive compact retry happens | `event_sink` receives `reactive_compact` event |
+| subagent spawn guard blocks | `event_sink` receives `subagent_spawn_guard` event |
+| active `session_context` exists | whitelisted runtime pressure events append `runtime_event` session evidence |
+| no `session_context` exists | events may still reach `event_sink`, but evidence is not appended |
+
+### 4. Tests Required
+
+- `coding-deepgent/tests/compact/test_runtime_pressure.py`
+- existing runtime event tests in `coding-deepgent/tests/extensions/test_hooks.py`
+- existing runtime event evidence tests in `coding-deepgent/tests/tool_system/test_tool_system_middleware.py`
+
+## Scenario: Env-Gated Prompt/API Dump
+
+### 1. Scope / Trigger
+
+- Trigger: changes touching model-call observability, prompt dump paths, or
+  `CODING_DEEPGENT_DUMP_PROMPTS`.
+- Applies when a developer needs a local replay/debug artifact for what the
+  LangChain model-call middleware sent to the model.
+
+### 2. Signatures
+
+```python
+PROMPT_DUMP_ENV = "CODING_DEEPGENT_DUMP_PROMPTS"
+
+def prompt_dump_enabled(env: Mapping[str, str] | None = None) -> bool: ...
+
+def dump_model_request_if_enabled(
+    context: object,
+    *,
+    request: object,
+    messages: Sequence[object],
+    input_token_estimate: int | None = None,
+    env: Mapping[str, str] | None = None,
+) -> Path | None: ...
+```
+
+### 3. Contracts
+
+- Prompt/API dumps must be disabled unless `CODING_DEEPGENT_DUMP_PROMPTS=1`.
+- Dumps must be local JSONL files under the active runtime workdir.
+- Dump metadata must redact secret-like fields such as API keys, tokens,
+  passwords, and authorization values.
+- Dump records may include model-facing prompt messages because the feature is
+  explicitly developer-gated, but records must stay bounded and must never be
+  injected into model-visible context.
+- No CLI dump flag is part of the MVP contract.
+
+### 4. Validation & Error Matrix
+
+| Case | Expected behavior |
+|---|---|
+| env unset | no prompt dump file is written |
+| `CODING_DEEPGENT_DUMP_PROMPTS=1` | one JSONL request record is appended for the model call |
+| model settings include a secret-like key | dumped metadata contains `<redacted>` for that key |
+
+### 5. Tests Required
+
+- `coding-deepgent/tests/compact/test_runtime_pressure.py`
diff --git a/.trellis/spec/backend/session-compact-contracts.md b/.trellis/spec/backend/session-compact-contracts.md
new file mode 100644
index 000000000..ea51688e3
--- /dev/null
+++ b/.trellis/spec/backend/session-compact-contracts.md
@@ -0,0 +1,801 @@
+# Session Compact Contracts
+
+> Executable contracts for resume, manual/generated compaction, compact records, session memory, and memory quality.
+
+## 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 --session-memory 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] [--session-memory TEXT]
+coding-deepgent sessions inspect SESSION_ID [--projection selected|raw|compact|collapse] [--limit N] [--no-recovery] [--no-model] [--no-raw]
+coding-deepgent sessions history SESSION_ID [--limit N]
+coding-deepgent sessions projection SESSION_ID [--projection selected|raw|compact|collapse] [--limit N]
+coding-deepgent sessions timeline SESSION_ID [--limit N]
+coding-deepgent sessions evidence SESSION_ID [--kind KIND] [--limit N]
+coding-deepgent sessions events SESSION_ID [--event-kind EVENT_KIND] [--limit N]
+coding-deepgent sessions permissions SESSION_ID [--limit 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,
+    assist_context: str | None = None,
+) -> str: ...
+
+class RuntimeStateContribution:
+    key: str
+
+class RecoveryBriefContribution:
+    name: str
+
+class CompactAssistContribution:
+    name: str
+
+class CompactSummaryUpdateContribution:
+    name: str
+
+def append_compact(
+    context: SessionContext,
+    *,
+    trigger: str,
+    summary: str,
+    start_message_id: str,
+    end_message_id: str,
+    covered_message_ids: list[str] | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> Path: ...
+
+def append_collapse(
+    context: SessionContext,
+    *,
+    trigger: str,
+    summary: str,
+    start_message_id: str,
+    end_message_id: str,
+    covered_message_ids: list[str] | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> Path: ...
+
+class SessionMessage:
+    message_id: str
+    created_at: str
+    role: str
+    content: str
+    metadata: dict[str, Any] | None = None
+
+class SessionSidechainMessage:
+    created_at: str
+    agent_type: str
+    role: str
+    content: str
+    subagent_thread_id: str
+    parent_message_id: str | None = None
+    parent_thread_id: str | None = None
+    metadata: dict[str, Any] | None = None
+
+class LoadedSession:
+    history: list[SessionMessage]
+    sidechain_messages: list[SessionSidechainMessage]
+    compacted_history: list[dict[str, Any]]
+    compacted_history_source: CompactedHistorySource
+    collapsed_history: list[dict[str, Any]]
+    collapsed_history_source: CollapsedHistorySource
+    state: dict[str, Any]
+    evidence: list[SessionEvidence]
+    compacts: list[SessionCompact]
+    summary: SessionSummary
+    collapses: list[SessionCollapse]
+
+class RuntimeContext:
+    session_context: SessionContext | None = None
+
+class CompactedHistorySource:
+    mode: Literal["raw", "compact"]
+    reason: str
+    compact_index: int | None = None
+
+class RawTranscriptMessageView:
+    message_id: str
+    role: str
+    content: str
+    model_visible: bool
+    hidden_by_event_ids: tuple[str, ...]
+
+class ProjectionMessageView:
+    role: str
+    content: Any
+    source: Literal[
+        "raw",
+        "compact_boundary",
+        "compact_summary",
+        "collapse_boundary",
+        "collapse_summary",
+    ]
+    message_id: str | None
+    event_id: str | None
+    covered_message_ids: tuple[str, ...]
+
+class CompressionTimelineEvent:
+    event_id: str
+    event_type: str
+    created_at: str
+    trigger: str | None
+    summary: str
+    affected_message_ids: tuple[str, ...]
+    affected_tool_call_ids: tuple[str, ...]
+    source: str | None
+
+class CompressionView:
+    raw_messages: tuple[RawTranscriptMessageView, ...]
+    model_projection: tuple[ProjectionMessageView, ...]
+    timeline: tuple[CompressionTimelineEvent, ...]
+    projection_mode: Literal["selected", "raw", "compact", "collapse"]
+
+def build_compression_view(
+    loaded: LoadedSession,
+    *,
+    projection_mode: Literal["selected", "raw", "compact", "collapse"] = "selected",
+) -> CompressionView: ...
+
+class SessionMemoryInspect:
+    status: Literal["missing", "current", "stale"]
+    source: str | None
+    content: str | None
+    artifact_message_count: int | None
+    current_message_count: int
+    estimated_token_count: int
+    tool_call_count: int
+
+class SessionInspectView:
+    session_id: str
+    workdir: str
+    transcript_path: str
+    created_at: str | None
+    updated_at: str | None
+    message_count: int
+    evidence_count: int
+    compact_count: int
+    collapse_count: int
+    sidechain_count: int
+    recovery_brief: str
+    projection_mode: Literal["selected", "raw", "compact", "collapse"]
+    raw_messages: tuple[RawTranscriptMessageView, ...]
+    model_projection: tuple[ProjectionMessageView, ...]
+    timeline: tuple[CompressionTimelineEvent, ...]
+    session_memory: SessionMemoryInspect
+
+def build_session_inspect_view(
+    loaded: LoadedSession,
+    *,
+    projection_mode: Literal["selected", "raw", "compact", "collapse"] = "selected",
+) -> SessionInspectView: ...
+
+def session_evidence_rows(
+    loaded: LoadedSession,
+    *,
+    kind: str | None = None,
+    event_kind: str | None = None,
+) -> list[dict[str, Any]]: ...
+
+def permission_evidence_rows(loaded: LoadedSession) -> list[dict[str, Any]]: ...
+
+def append_sidechain_message(
+    context: SessionContext,
+    *,
+    agent_type: str,
+    role: str,
+    content: str,
+    subagent_thread_id: str,
+    parent_message_id: str | None = None,
+    parent_thread_id: str | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> Path: ...
+```
+
+### 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`.
+- Persisted raw message records must carry stable deterministic `message_id`
+  values, and `LoadedSession.history` must preserve those IDs through load.
+- `continuation_history()` must project `SessionMessage` into model-visible
+  `{"role", "content"}` dictionaries instead of leaking storage fields into the
+  runtime message list.
+- 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.
+- User-facing recovery brief may show product-level rules, long-term memory, and
+  current-session memory as separate sections.
+- Model-facing resume context should only carry the recovery layer and must not
+  duplicate project rules, long-term memory, or current-session memory when
+  those layers are already injected earlier in the runtime assembly order.
+- When `LoadedSession.state["session_memory"]` contains a valid artifact,
+  `render_recovery_brief()` must render it in a dedicated `Current-session memory:`
+  section and mark it `current` or `stale` using the local freshness policy:
+  `message_count` deltas are mandatory, and stored `token_count` /
+  `tool_call_count` should also participate when available.
+- Invalid `session_memory` state must be ignored rather than breaking session
+  load or resume.
+- Feature-specific recovery sections should enter through registered
+  `RecoveryBriefContribution` providers, not through one-off conditionals in
+  `render_recovery_brief()`.
+
+#### Session Inspect Visibility
+
+- `sessions inspect` is read-only. It must not append messages, evidence,
+  compact events, collapse events, or state snapshots.
+- `sessions inspect` must use `build_session_inspect_view()` and the existing
+  `build_compression_view()` projection model instead of computing a second
+  compact/collapse interpretation in `cli.py`.
+- The inspect output must show:
+  - session identity and transcript path
+  - message/evidence/compact/collapse/sidechain counts
+  - selected projection mode and raw visible/hidden counts
+  - session-memory status using the same freshness policy as recovery briefs
+  - compression timeline
+  - model projection rows
+  - raw transcript visibility rows
+- `--projection selected` must resolve to the same effective raw/compact/collapse
+  mode that resume would use.
+- Invalid projection values must fail at the CLI boundary with a user-facing
+  error rather than falling back silently.
+- `sessions history`, `sessions projection`, and `sessions timeline` are
+  read-only views over the same `SessionInspectView`; they must not re-interpret
+  compact/collapse state separately.
+- `sessions evidence`, `sessions events`, and `sessions permissions` must render
+  bounded evidence rows. Permission/history views must filter from persisted
+  evidence metadata and must not read provider logs or raw prompt dumps.
+
+#### 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.
+- When a current valid session-memory artifact exists, `generate_compact_summary()`
+  may receive it as a bounded assist text.
+- Compact assist must stay conservative: if the artifact `message_count` already
+  lags behind the current message count, it must not be passed as assist text
+  even if token/tool-call thresholds have not yet crossed the stale boundary.
+- Stale or invalid session-memory artifacts must not be passed to the summarizer
+  as compact assist text.
+- Feature-specific assist text should enter through registered
+  `CompactAssistContribution` providers, then flow into the summarizer through
+  the generic `assist_context` parameter.
+- It must not add LangChain `SummarizationMiddleware`.
+- It must not delete, prune, rewrite, or compact persisted session JSONL transcript records.
+
+#### Module Contribution Seams
+
+- Runtime-state extensions should use `RuntimeStateContribution` providers for
+  validation/coercion instead of adding feature-specific fields to
+  `JsonlSessionStore._coerce_state_snapshot()`.
+- Recovery-context extensions should use `RecoveryBriefContribution` providers
+  and render as bounded sections.
+- Generated compact-summary extensions should use `CompactAssistContribution`
+  providers and return bounded text only when the assist is current/reliable.
+- State updates that happen after a generated compact summary should use
+  `CompactSummaryUpdateContribution` providers. Providers may update module
+  state only from the generated summary that already exists; they must not
+  trigger a new model call.
+- The current registry is intentionally static and local. It is not a plugin
+  registration system and must not introduce background/runtime discovery.
+- Contribution seams reduce accidental coupling but do not eliminate essential
+  cross-layer integration for model-visible flows.
+
+#### Session-Memory Local Updates
+
+- `--generate-compact-summary` is the only current path that can refresh
+  `LoadedSession.state["session_memory"]` automatically.
+- Plain `sessions resume SESSION_ID --prompt TEXT` must not trigger an implicit
+  summarizer call to update session memory.
+- A missing valid session-memory artifact may be initialized from the generated
+  compact summary.
+- A stale-enough artifact may be refreshed from the generated compact summary
+  when the module-owned threshold policy says it is due.
+- The module-owned threshold policy may use message-count delta, deterministic
+  estimated-token delta, and tool-call delta. Token counts are local estimates,
+  not provider billing/tokenizer values.
+- A current/recent artifact must not be refreshed.
+- Refreshed artifacts use `source == "generated_compact"` and
+  message, estimated-token, and tool-call counters derived from
+  `LoadedSession.history`.
+
+#### Compact Transcript Records
+
+- Compact events are persisted as append-only JSONL records with
+  `record_type == "transcript_event"` and `event_kind == "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 typed `SessionMessage` transcript view.
+- `LoadedSession.compacted_history` is the load-time virtual compacted view.
+- `LoadedSession.compacted_history_source` explains whether the compacted view
+  came from projected raw history or a compact record.
+- If no valid compact-derived view exists, `compacted_history` must fall back
+  to the projected raw history view.
+- Required compact record fields:
+
+```json
+{
+  "record_type": "transcript_event",
+  "version": 1,
+  "session_id": "...",
+  "timestamp": "...",
+  "event_kind": "compact",
+  "payload": {
+    "trigger": "manual",
+    "summary": "...",
+    "start_message_id": "msg-000000",
+    "end_message_id": "msg-000001",
+    "covered_message_ids": ["msg-000000", "msg-000001"],
+    "metadata": {"source": "generated"}
+  }
+}
+```
+
+- When continuation history contains synthetic compact artifacts,
+  `run_prompt_with_recording()` must append one compact transcript event before
+  recording the continuation prompt.
+- Persisted raw message IDs after compacted continuation must continue the next
+  append-order `msg-######` sequence from the existing raw message ledger, not
+  from the count of synthetic compact projection messages.
+
+#### Collapse Transcript Records
+
+- Live collapse persistence uses the same append-only transcript-event ledger as
+  manual compact, but with `event_kind == "collapse"`.
+- Collapse records must be loaded into `LoadedSession.collapses`.
+- Collapse records must increment `SessionSummary.collapse_count`.
+- Collapse records must not appear in `LoadedSession.history`.
+- Collapse records must not replace or delete raw message, compact, state, or
+  evidence records.
+- Collapse records must reference raw transcript messages through stable message
+  IDs even though the collapse itself was decided from a live model-facing
+  projection.
+- When a recorded runtime invocation has transcript-projection lineage for the
+  current model-facing history, live collapse may persist a collapse
+  transcript-event record whose payload contains:
+  - `trigger`
+  - `summary`
+  - `start_message_id`
+  - `end_message_id`
+  - optional `covered_message_ids`
+  - optional bounded `metadata`
+- If a live collapse projection contains no recoverable raw message coverage,
+  the runtime must fail open and skip collapse-record persistence rather than
+  inventing implicit indexes.
+
+#### Subagent Sidechain Transcript Records
+
+- Subagent sidechain transcript entries must be persisted in the same parent
+  session JSONL ledger as `transcript_event` records with
+  `event_kind == "subagent_message"`.
+- Sidechain entries must not appear in `LoadedSession.history`.
+- Sidechain entries must not appear in selected compacted/collapsed/main-model
+  projections unless a future contract explicitly reopens that behavior.
+- `LoadedSession.sidechain_messages` is the audit/read-model surface for child
+  transcript entries.
+- Each sidechain entry must carry bounded linkage fields:
+  - `agent_type`
+  - `role`
+  - `content`
+  - `subagent_thread_id`
+  - optional `parent_message_id`
+  - optional `parent_thread_id`
+- Fork sidechain entries may also carry bounded continuity metadata, for example:
+  - `fork_run_id`
+  - `tool_pool_fingerprint`
+  - `placeholder_layout_version`
+- Sidechain transcript stays inside the parent ledger; no per-agent transcript
+  directory is part of the current contract.
+
+#### Load-Time Collapsed History View
+
+- `JsonlSessionStore.load_session()` must derive
+  `LoadedSession.collapsed_history` from raw `LoadedSession.history` plus valid
+  `LoadedSession.collapses`.
+- The collapsed view is a separate model-facing projection; raw transcript
+  remains complete in `LoadedSession.history`.
+- Collapse replay must use stable message references only:
+  - `start_message_id`
+  - `end_message_id`
+  - optional exact `covered_message_ids`
+- Invalid collapse references must not synthesize indexes or legacy fallbacks.
+  Invalid events are skipped and the projected raw history remains available.
+- Overlapping collapse records are deterministic: newer valid records win and
+  older overlapping records are skipped.
+- `LoadedSession.collapsed_history_source.mode` must be:
+  - `"collapse"` when at least one collapse event contributes to the selected
+    projection
+  - `"raw"` when no valid collapse projection exists
+- Compact and collapse coexist as projection event families over raw
+  transcript. Selected continuation should prefer a valid collapse projection
+  over compact projection to avoid stacking duplicate synthetic summaries.
+
+#### Compression Visualization Read Model
+
+- `build_compression_view(loaded)` is the backend data-readiness seam for future
+  UI/API work. It must not mutate `LoadedSession` or persisted JSONL records.
+- `CompressionView.raw_messages` must expose every raw `SessionMessage` with:
+  - stable `message_id`
+  - role/content
+  - whether it is model-visible in the selected projection
+  - which compression event IDs hide/summarize it, if any
+- `CompressionView.model_projection` must expose the selected model-facing
+  projection with source metadata:
+  - raw messages use `source == "raw"` and carry `message_id`
+  - compact synthetic messages use `compact_boundary` / `compact_summary`
+  - collapse synthetic messages use `collapse_boundary` / `collapse_summary`
+  - synthetic messages carry `event_id` and `covered_message_ids`
+- `CompressionView.timeline` must merge available compression-related facts into
+  a stable chronological timeline:
+  - compact transcript events
+  - collapse transcript events
+  - runtime-pressure `runtime_event` evidence
+- Timeline entries must include event type, trigger when available, affected
+  message IDs when available, affected tool-call IDs when available, summary,
+  source, and bounded metadata.
+- The read model must support explicit `projection_mode == "raw"` so callers can
+  inspect the full transcript without compression filters.
+
+#### 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
+- For the current manual-compact path, the compact event covers a contiguous
+  prefix of the raw transcript:
+  - `start_message_id` must resolve to the first raw message in the session
+  - `end_message_id` must resolve to the last summarized raw message
+  - when `covered_message_ids` is present, it must match that covered prefix
+- Compact records must be scanned from newest to oldest.
+- If the latest compact record's message references are 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 projected 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`.
+- Long-term memory type is a closed set: `user`, `feedback`, `project`, `reference`.
+- Recovery/resume must show long-term memory and current-session memory as two
+  separate sections.
+- Before writing, it must call `evaluate_memory_quality(record, existing_records=...)`.
+- It must reject:
+  - normalized duplicates in the same memory type
+  - obvious transient task/session state
+  - project-memory entries that are derivable from repository structure or code
+  - project-memory entries that use relative time instead of absolute dates
+  - 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 |
+| `--session-memory` without `--prompt` | Click error; run path is not called |
+| `--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 `--session-memory` | session-memory validation 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 transcript event is appended |
+| compacted continuation appends new raw messages | next real message ID continues the append-order `msg-######` sequence |
+| 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 projected raw history |
+| live collapse runs during recorded session and raw projection lineage exists | one collapse transcript event is appended and loaded into `LoadedSession.collapses` |
+| live collapse runs without recoverable raw message coverage | model-facing collapse still succeeds; collapse record persistence is skipped |
+| valid collapse records exist | `LoadedSession.collapsed_history` contains collapse boundary + summary + preserved raw messages |
+| invalid collapse refs exist | invalid events are skipped; collapsed view falls back to raw projection if none are valid |
+| overlapping collapse records exist | newest non-overlapping valid records define the deterministic projection |
+| compact and collapse records both exist | selected continuation uses collapse projection without stacking compact and collapse summaries |
+| sidechain transcript events exist | `LoadedSession.history` and selected continuation stay unchanged; child entries load through `sidechain_messages` only |
+| fork sidechain transcript events exist | child entries stay in `sidechain_messages`; bounded fork continuity metadata roundtrips without entering main projections |
+| compression view selected projection hides raw messages | hidden raw messages have `model_visible == False` and `hidden_by_event_ids` |
+| compression view forced raw projection | all raw messages remain model-visible and projection entries use `source == "raw"` |
+| runtime pressure evidence includes affected tool IDs | timeline exposes `affected_tool_call_ids` when metadata contains them |
+| 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` |
+| valid long-term memory snapshot in runtime state | recovery brief renders `Long-term memory:` with bounded saved entries |
+| missing long-term memory snapshot in runtime state | recovery brief renders `Long-term memory:` with `- none` |
+| valid current session-memory artifact | recovery brief renders `Current-session memory:` with `[current]`; generated compact summary may receive assist text |
+| stale session-memory artifact | recovery brief renders `Current-session memory:` with `[stale]`; generated compact summary ignores assist text |
+| invalid session-memory artifact in snapshot | load succeeds and artifact is ignored |
+| missing session-memory artifact after generated compact summary | artifact is initialized from generated summary |
+| stale-enough session-memory artifact after generated compact summary | artifact is refreshed from generated summary |
+| token/tool-call pressure exceeds session-memory thresholds | artifact is refreshed from generated summary |
+| current/recent session-memory artifact after generated compact summary | artifact is not refreshed |
+| 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:
+
+- `coding-deepgent/tests/cli/test_cli.py::test_sessions_resume_uses_recovery_brief_continuation_history`
+- `coding-deepgent/tests/cli/test_cli.py::test_sessions_resume_can_use_manual_compact_summary`
+- `coding-deepgent/tests/cli/test_cli.py::test_sessions_resume_can_generate_manual_compact_summary`
+- `coding-deepgent/tests/cli/test_cli.py::test_sessions_resume_rejects_manual_and_generated_compact_together`
+- `coding-deepgent/tests/cli/test_cli.py::test_sessions_resume_rejects_compact_options_without_prompt`
+- `coding-deepgent/tests/cli/test_cli.py::test_sessions_resume_rejects_compact_instructions_without_generation`
+- `coding-deepgent/tests/cli/test_cli.py::test_run_once_records_new_and_resumed_session_transcript`
+- `coding-deepgent/tests/cli/test_cli.py::test_run_once_records_compact_metadata_without_message_index_skew`
+- `coding-deepgent/tests/cli/test_cli.py::test_selected_continuation_history_uses_loaded_compacted_history`
+- `coding-deepgent/tests/cli/test_cli.py::test_selected_continuation_history_prefers_loaded_collapsed_history`
+- `coding-deepgent/tests/cli/test_cli.py::test_sessions_resume_defaults_to_latest_compacted_continuation_when_available`
+- `coding-deepgent/tests/compact/test_compact_artifacts.py`
+- `coding-deepgent/tests/compact/test_compact_summarizer.py`
+- `coding-deepgent/tests/compact/test_message_projection.py`
+- `coding-deepgent/tests/sessions/test_sessions.py::test_compact_record_roundtrip_does_not_enter_history`
+- `coding-deepgent/tests/sessions/test_sessions.py::test_collapse_record_roundtrip_does_not_enter_history`
+- `coding-deepgent/tests/sessions/test_sessions.py::test_sidechain_message_roundtrip_stays_out_of_parent_history`
+- `coding-deepgent/tests/sessions/test_sessions.py::test_load_session_collapsed_history_uses_newest_non_overlapping_collapses`
+- `coding-deepgent/tests/sessions/test_sessions.py::test_load_session_collapsed_history_falls_back_to_raw_on_invalid_refs`
+- `coding-deepgent/tests/sessions/test_sessions.py::test_compression_view_exposes_raw_projection_and_timeline`
+- `coding-deepgent/tests/sessions/test_sessions.py::test_compression_view_can_force_raw_projection`
+- `coding-deepgent/tests/sessions/test_sessions.py::test_load_session_ignores_invalid_compact_records`
+- `coding-deepgent/tests/sessions/test_sessions.py::test_load_session_compacted_history_falls_back_to_raw_history_on_invalid_tail_range`
+- `coding-deepgent/tests/sessions/test_sessions.py::test_load_session_compacted_history_uses_newest_valid_compact_record`
+- `coding-deepgent/tests/sessions/test_sessions.py::test_load_session_compacted_history_uses_latest_valid_compact_record`
+- `coding-deepgent/tests/sessions/test_sessions.py::test_recovery_brief_renders_verification_provenance_only`
+- `coding-deepgent/tests/compact/test_runtime_pressure.py::test_runtime_pressure_middleware_persists_collapse_record_when_projection_exists`
+- `coding-deepgent/tests/memory/test_memory.py::test_memory_quality_policy_rejects_transient_and_duplicate_entries`
+- `coding-deepgent/tests/memory/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`
+- collapse transcript records are separated from `LoadedSession.history`
+- collapsed history view is derived at load time and kept separate from raw history
+- compression view exposes raw visibility, selected projection source metadata,
+  and timeline events
+- compacted history view is derived at load time and kept separate from raw history
+- persisted transcript `message_id` values remain contiguous append-order IDs
+- compacted continuation persists `start_message_id` / `end_message_id` and
+  optional `covered_message_ids` into the compact transcript event payload
+- 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.
+
+## Scenario: Projection Repair Tombstone Observability
+
+### 1. Scope / Trigger
+
+- Trigger: changes touching `project_messages(...)`,
+  `project_messages_with_stats(...)`, or agent-loop message normalization.
+- Applies when model-facing projection contains orphaned structured
+  `tool_result` blocks without a previously visible matching `tool_use`.
+
+### 2. Signatures
+
+```python
+ORPHAN_TOOL_RESULT_TOMBSTONE = (
+    "[Orphaned tool_result tombstoned: missing matching tool_use]"
+)
+
+class ProjectionRepairStats:
+    orphan_tombstoned: int = 0
+    reason: str | None = None
+
+class ProjectMessagesResult:
+    messages: list[dict[str, Any]]
+    repair_stats: ProjectionRepairStats
+
+def project_messages_with_stats(
+    messages: list[dict[str, Any]],
+    *,
+    max_chars_per_message: int | None = None,
+) -> ProjectMessagesResult: ...
+```
+
+### 3. Contracts
+
+- Projection repair must replace orphaned `tool_result` blocks with a bounded
+  text tombstone instead of passing raw orphaned tool material to the model.
+- Matched `tool_use` / `tool_result` blocks must remain unchanged.
+- Agent-loop normalization must emit one bounded `orphan_tombstoned` runtime
+  event when repair happens.
+- When a recorded session context exists, `orphan_tombstoned` evidence metadata
+  may include only bounded fields such as `reason`, `tombstoned_count`, and
+  `message_count`.
+
+### 4. Validation & Error Matrix
+
+| Case | Expected behavior |
+|---|---|
+| `tool_result` has no prior matching `tool_use` | content block is replaced with `ORPHAN_TOOL_RESULT_TOMBSTONE` and event metadata includes `reason == "missing_tool_use"` |
+| `tool_result` has a prior matching `tool_use` | structured content is preserved unchanged and no repair event is emitted |
+
+### 5. Tests Required
+
+- `coding-deepgent/tests/compact/test_message_projection.py`
+- `coding-deepgent/tests/runtime/test_agent_runtime_service.py`
diff --git a/.trellis/spec/backend/task-workflow-contracts.md b/.trellis/spec/backend/task-workflow-contracts.md
new file mode 100644
index 000000000..ddd94fb32
--- /dev/null
+++ b/.trellis/spec/backend/task-workflow-contracts.md
@@ -0,0 +1,545 @@
+# 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 list_plans(store: TaskStore) -> list[PlanArtifact]: ...
+
+coding-deepgent tasks list [--all]
+coding-deepgent tasks get TASK_ID
+coding-deepgent tasks create TITLE [--description TEXT] [--depends-on TASK_ID]... [--owner NAME] [--metadata KEY=VALUE]...
+coding-deepgent tasks update TASK_ID [--status STATUS] [--depends-on TASK_ID]... [--owner NAME] [--metadata KEY=VALUE]...
+coding-deepgent plans list
+coding-deepgent plans get PLAN_ID
+coding-deepgent plans save TITLE --content TEXT --verification TEXT [--task-id TASK_ID]... [--metadata KEY=VALUE]...
+
+def run_subagent(
+    task: str,
+    runtime: ToolRuntime,
+    agent_type: str = "general",
+    plan_id: str | None = None,
+    max_turns: int = 25,
+) -> str: ...
+
+def run_fork(
+    intent: str,
+    runtime: ToolRuntime,
+    background: bool = False,
+    max_turns: int = 25,
+) -> str: ...
+
+def run_subagent_background(
+    task: str,
+    runtime: ToolRuntime,
+    agent_type: str = "general",
+    plan_id: str | None = None,
+    max_turns: int = 25,
+) -> str: ...
+
+def subagent_status(
+    run_id: str,
+    runtime: ToolRuntime,
+) -> str: ...
+
+def subagent_send_input(
+    run_id: str,
+    message: str,
+    runtime: ToolRuntime,
+) -> str: ...
+
+def subagent_stop(
+    run_id: str,
+    runtime: ToolRuntime,
+) -> str: ...
+
+def resume_subagent(
+    subagent_thread_id: str,
+    runtime: ToolRuntime,
+    follow_up: str | None = None,
+) -> str: ...
+
+def resume_fork(
+    child_thread_id: str,
+    runtime: ToolRuntime,
+    follow_up: str | None = None,
+) -> str: ...
+
+class AgentDefinition(BaseModel):
+    agent_type: str
+    description: str
+    when_to_use: str
+    instructions: str | None = None
+    tool_allowlist: tuple[str, ...]
+    disallowed_tools: tuple[str, ...]
+    max_turns: int
+    model_profile: str | None = None
+
+class SubagentResultEnvelope(BaseModel):
+    agent_type: str
+    content: str
+    tool_allowlist: list[str]
+    input_tokens: int
+    output_tokens: int
+    total_tokens: int
+    total_duration_ms: int
+    total_tool_use_count: int
+
+class ForkResultEnvelope(BaseModel):
+    mode: Literal["fork"]
+    content: str
+    fork_run_id: str
+    parent_thread_id: str
+    child_thread_id: str
+    rendered_prompt_fingerprint: str
+    tool_pool_identity: ToolPoolIdentitySnapshot
+    placeholder_layout: ForkPlaceholderLayout
+    input_tokens: int
+    output_tokens: int
+    total_tokens: int
+    total_duration_ms: int
+    total_tool_use_count: int
+
+class BackgroundSubagentRun(BaseModel):
+    run_id: str
+    mode: Literal["background_subagent", "background_fork"]
+    agent_type: str
+    status: Literal["queued", "running", "completed", "failed", "cancelled"]
+    title: str
+    parent_thread_id: str
+    child_thread_id: str
+    workdir: str
+    requested_max_turns: int | None = None
+    effective_max_turns: int
+    model_profile: str | None = None
+    plan_id: str | None = None
+    pending_inputs: list[str]
+    progress_summary: str
+    summary_text: str | None = None
+    recent_activities: list[str]
+    latest_result: str | None = None
+    error: str | None = None
+    stop_requested: bool
+    input_tokens: int
+    output_tokens: int
+    total_tokens: int
+    total_duration_ms: int
+    total_tool_use_count: int
+    total_invocations: int
+    notified: bool
+
+def record_verifier_evidence(
+    *,
+    result: SubagentResult,
+    runtime: ToolRuntime,
+) -> bool: ...
+
+def resume_subagent_task(
+    *,
+    subagent_thread_id: str,
+    runtime: ToolRuntime,
+    follow_up: str | None = None,
+) -> SubagentResult: ...
+
+def resume_fork_task(
+    *,
+    child_thread_id: str,
+    runtime: ToolRuntime,
+    follow_up: str | None = None,
+) -> ForkResult: ...
+```
+
+### 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.
+- `list_plans()` must return deterministic id order.
+- `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.
+- local CLI `tasks/*` and `plans/*` commands must operate on the same runtime
+  store namespaces as `task_*` / `plan_*` tools; they must not introduce a
+  second persistence path.
+- the default local `StoreBackend` may now be `file` for process-surviving task,
+  plan, memory-store, and background-run state in one workspace.
+- `run_subagent` and `run_fork` remain on the initial main tool surface.
+- `run_subagent` and `run_fork` must not grow mailbox, coordinator, worker,
+  team, Scratchpad, or message-routing schema fields. Those behaviors require
+  separate H13/H14 contracts and role-specific tool projections.
+- Advanced subagent lifecycle controls:
+  `run_subagent_background`, `subagent_status`, `subagent_send_input`,
+  `subagent_stop`, `resume_subagent`, and `resume_fork`
+  are public local tools, but they live on the deferred-discovery surface and
+  should be reached through `ToolSearch` plus `invoke_deferred_tool`.
+- `run_subagent` must expose a built-in `AgentDefinition` catalog that includes
+  `general`, `verifier`, `explore`, and `plan`.
+- Repo-local custom subagent definitions may extend the catalog from
+  `.coding-deepgent/SUBAGENTS.json`.
+- Local plugins may extend the catalog by declaring `agents` in `plugin.json`
+  and providing matching definitions in `<plugin-root>/subagents.json`.
+- Built-in agent definitions must declare `description`, `when_to_use`,
+  `instructions`, `tool_allowlist`, `disallowed_tools`, `max_turns`, and
+  optional `model_profile`.
+- `general.max_turns == 25` and `verifier.max_turns == 5` must come from
+  definitions, not hard-coded branches; `explore` and `plan` must also declare
+  their own non-default ceilings.
+- `general`, `verifier`, `explore`, and `plan` child tool surfaces must remain
+  read-only:
+  `read_file`, `glob`, `grep`, `task_get`, `task_list`, and `plan_get`.
+- `explore` may narrow to read-only file tools only.
+- Built-in and repo-local custom child agents must execute through a real bounded
+  child `create_agent` path rather than returning a hard-coded acceptance
+  string.
+- `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.
+- `run_subagent(max_turns=...)` and `run_fork(max_turns=...)` must forward the
+  effective turn ceiling into the child/fork runtime instead of silently
+  ignoring it.
+- `AgentDefinition.model_profile` must affect child model selection when set.
+- `run_subagent_background(...)` must persist a bounded background run record in
+  the runtime store and return immediately with a stable `run_id`.
+- Background subagent runs must expose at least `status`,
+  `progress_summary`, `recent_activities`, `pending_inputs`,
+  `latest_result`, and bounded cumulative usage counters.
+- Background fork runs may reuse the same background run record shape with
+  `mode == "background_fork"` and continue on the same fork child thread.
+- `subagent_send_input(...)` must queue follow-up input for an existing
+  background run and preserve the same `run_id`.
+- Background runs may continue through repeated queued inputs, but they must not
+  claim mailbox/coordinator/team-runtime semantics.
+- `subagent_send_input(...)` is a queued follow-up control for one existing
+  background run. It is not `SendMessage`, mailbox delivery, worker addressing,
+  broadcast, team routing, or coordinator communication.
+- `subagent_stop(...)` must request stop for queued or active background runs
+  and persist terminal `cancelled` once the current invoke boundary is safe to
+  stop.
+- without a daemon or mailbox, background run worker handles remain process-local.
+  User-facing start/send/stop controls for background subagents therefore belong
+  to the active frontend/bridge process, not standalone cross-process CLI commands.
+- Finished background workers must release in-memory worker handles after the
+  terminal status is persisted.
+- Background run completion or failure must append one bounded
+  `subagent_notification` evidence record when recording context exists.
+- Background run records may include a bounded runtime snapshot. The snapshot is
+  durable metadata for reconstruction/readiness; process-local thread handles
+  remain non-durable and must not be treated as the source of truth.
+- General subagent output must be structured JSON including `agent_type`,
+  `content`, `tool_allowlist`, `input_tokens`, `output_tokens`, `total_tokens`,
+  `total_duration_ms`, and `total_tool_use_count`.
+- `run_fork` is a separate explicit tool surface. It must not be modeled as a
+  `general` or `verifier` `AgentDefinition` variant.
+- `run_fork(background=True)` may enter the shared background-run manager, but
+  it still counts as the same explicit fork surface rather than a second fork
+  entrypoint.
+- `run_fork` must operate as a same-config sibling branch:
+  - use the parent invocation's rendered system prompt directly
+  - use the parent invocation's visible main tool projection directly
+  - append one thin fixed fork directive carrying only branch intent
+- Fork runtime context must preserve a stable rendered prompt fingerprint and a
+  stable visible tool-pool identity snapshot.
+- Fork tool-pool identity must be stronger than a name-only list. It must be a
+  stable ordered model-visible tool snapshot.
+- Fork payload assembly must drop incomplete assistant tool-call turns that lack
+  paired tool results instead of inheriting an invalid prefix.
+- Fork recursion must be blocked by a dedicated guard marker and runtime-entry
+  guard before nested fork execution begins.
+- Fork result output must be structured JSON including:
+  - `mode == "fork"`
+  - `content`
+  - `fork_run_id`
+  - `parent_thread_id`
+  - `child_thread_id`
+  - `rendered_prompt_fingerprint`
+  - `tool_pool_identity`
+  - `placeholder_layout`
+  - `input_tokens`
+  - `output_tokens`
+  - `total_tokens`
+  - `total_duration_ms`
+  - `total_tool_use_count`
+- Fork placeholder layout is part of the continuity seam even before full fork
+  resume exists. It must define a version, replacement-state hook contract, and
+  deterministic placeholder messages for paired tool results.
+- Real child subagent executions with an active parent `SessionContext` must
+  append bounded sidechain transcript entries into the parent session ledger
+  using the existing transcript-event seam rather than a separate agent
+  directory.
+- Sidechain transcript entries must carry `subagent_thread_id` plus optional
+  `parent_message_id` / `parent_thread_id` linkage when available.
+- Sidechain child transcript entries may persist bounded structured metadata
+  needed for subagent/fork resume, such as tool-call ids, content blocks,
+  prompt/tool fingerprints, and effective execution ceilings.
+- `resume_subagent_task(...)` must reconstruct a child thread from recorded
+  sidechain transcript + metadata and continue on the same child thread id.
+- `resume_subagent(...)` must return the same structured JSON envelope shape as
+  the synchronous general `run_subagent(...)` tool surface.
+- `resume_fork_task(...)` must reconstruct a fork child thread from recorded
+  sidechain transcript + metadata, and must fail if the current rendered prompt
+  fingerprint or visible tool projection fingerprint no longer matches the
+  recorded fork contract.
+- `resume_fork(...)` must return the same structured JSON envelope shape as the
+  explicit `run_fork(...)` tool surface.
+- Subagent and fork resume must also fail when the current runtime workdir no
+  longer matches the recorded workdir stored in sidechain metadata.
+- Verifier subagent output must expose the durable plan boundary as structured JSON including:
+  - `plan_id`
+  - `plan_title`
+  - `verification`
+  - `task_ids`
+  - `tool_allowlist`
+  - `content`
+  - `input_tokens`
+  - `output_tokens`
+  - `total_tokens`
+  - `total_duration_ms`
+  - `total_tool_use_count`
+- Subagent token counts are deterministic local estimates, not provider billing
+  or tokenizer truth.
+- If the final assistant message lacks direct text, subagent result extraction
+  must scan backward for the last non-empty text before failing.
+- 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...")` |
+| child tool allowlist | built-in child agents keep read-only tool surfaces and exclude mutating tools |
+| general subagent execution | invokes a real child agent with the read-only allowlist |
+| recorded child execution | parent session ledger receives sidechain transcript entries with child thread linkage |
+| custom local subagent definition | repo-local definition is loaded and validated before execution |
+| plugin subagent definition | plugin-declared definition is loaded and validated before execution |
+| final child assistant message is tool-only | result extraction falls back to the last non-empty assistant text |
+| 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...")` |
+| general subagent output | structured JSON parseable as general result envelope |
+| fork output | structured JSON parseable as fork result envelope |
+| background subagent start | structured JSON parseable as background run record with stable `run_id` |
+| background fork start through `run_fork(background=true)` | structured JSON parseable as background run record with `mode == "background_fork"` |
+| background run status lookup | returns the persisted background run record |
+| background run follow-up input | queues input and preserves the same background `run_id` |
+| background run stop | records stop request and eventually reaches terminal `cancelled` |
+| fork runtime invocation lacks rendered prompt or visible tool projection | explicit runtime error; no fallback reconstruction |
+| fork prefix contains incomplete tool call without paired result | fork payload drops that incomplete assistant tool-call turn |
+| nested fork attempts | explicit recursion guard failure before child execution |
+| background run with missing store | explicit runtime error |
+| background run completion with recording context | one `subagent_notification` evidence record is appended |
+| subagent resume with unknown thread id | explicit runtime error |
+| subagent resume with mismatched workdir | explicit runtime error |
+| fork resume with mismatched prompt/tool fingerprint | explicit runtime error |
+| fork resume with mismatched workdir | explicit runtime error |
+| 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 coding-deepgent/tests/tasks/test_tasks.py",
+    task_ids=[task.id],
+)
+```
+
+Expected:
+- plan has stable id
+- verification criteria are non-empty
+- referenced task IDs exist
+
+### 6. Tests Required
+
+- `coding-deepgent/tests/tasks/test_tasks.py::test_task_store_transitions_dependencies_and_ready_rule`
+- `coding-deepgent/tests/tasks/test_tasks.py::test_task_graph_rejects_missing_self_and_cycle_dependencies`
+- `coding-deepgent/tests/tasks/test_tasks.py::test_task_update_requires_blocked_reason_or_dependency`
+- `coding-deepgent/tests/tasks/test_tasks.py::test_task_graph_needs_verification_after_closing_three_tasks`
+- `coding-deepgent/tests/tasks/test_tasks.py::test_task_graph_with_verification_task_does_not_need_nudge`
+- `coding-deepgent/tests/tasks/test_tasks.py::test_task_update_tool_marks_verification_nudge_in_output_metadata`
+- `coding-deepgent/tests/tasks/test_tasks.py::test_plan_artifact_roundtrip_requires_verification_and_known_tasks`
+- `coding-deepgent/tests/tasks/test_tasks.py::test_plan_tools_save_and_get_artifacts`
+- `coding-deepgent/tests/tool_system/test_tool_system_registry.py::test_main_projection_preserves_current_product_tool_surface`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_subagent_allowlists_are_exact_and_exclude_mutating_tools`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_run_subagent_task_general_executes_real_read_only_child_agent`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_run_subagent_task_passes_effective_max_turns_via_recursion_limit`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_run_subagent_task_routes_custom_model_profile`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_resolve_agent_definition_loads_repo_local_custom_agents`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_run_subagent_executes_repo_local_custom_agent`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_resolve_agent_definition_loads_plugin_provided_agents`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_run_subagent_tool_returns_structured_general_result`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_run_subagent_records_sidechain_messages_in_parent_session`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_subagent_result_falls_back_to_last_text_when_final_message_is_tool_only`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_run_fork_tool_schema_rejects_runtime_creep_fields`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_run_fork_task_executes_same_config_sibling_branch`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_run_fork_filters_incomplete_tool_calls_and_exposes_placeholder_messages`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_run_fork_tool_returns_structured_result`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_run_fork_records_sidechain_messages_with_contract_metadata`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_run_fork_rejects_recursive_fork_marker`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_resume_subagent_task_reuses_recorded_thread`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_resume_fork_task_reuses_recorded_thread`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_resume_subagent_tool_returns_structured_result`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_resume_fork_tool_returns_structured_result`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_resume_fork_task_requires_matching_prompt_fingerprint`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_run_subagent_background_and_status`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_run_fork_background_and_status`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_background_subagent_send_input_reactivates_finished_run`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_subagent_stop_cancels_running_background_run`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_resume_subagent_task_requires_matching_workdir`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_resume_fork_task_requires_matching_workdir`
+- `coding-deepgent/tests/tool_system/test_tool_search.py::test_tool_search_returns_deferred_builtin_subagent_controls`
+- `coding-deepgent/tests/extensions/test_plugins.py::test_app_container_validates_plugin_provided_subagent_definitions`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_verifier_subagent_requires_plan_id`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_verifier_subagent_requires_task_store`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_verifier_subagent_rejects_unknown_plan`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_run_subagent_task_verifier_uses_durable_plan_payload`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_run_subagent_tool_returns_structured_verifier_result`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_verifier_verdict_helpers_map_status_and_summary`
+- `coding-deepgent/tests/subagents/test_subagents.py::test_run_subagent_tool_persists_verifier_evidence_roundtrip`
+- `coding-deepgent/tests/subagents/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/backend/tool-capability-contracts.md b/.trellis/spec/backend/tool-capability-contracts.md
new file mode 100644
index 000000000..e798b1f9b
--- /dev/null
+++ b/.trellis/spec/backend/tool-capability-contracts.md
@@ -0,0 +1,439 @@
+# Tool Capability Contracts
+
+> Executable H01 contracts for the `coding-deepgent` tool capability protocol.
+
+This document captures the cc-aligned "five-factor" tool protocol for the
+current LangChain/LangGraph-native product mainline. It intentionally does not
+copy the cc-haha TypeScript `Tool<Input, Output, Progress>` interface, React
+rendering surface, or custom `StreamingToolExecutor`. The local contract is:
+use LangChain tools for execution, and use `ToolCapability` plus middleware for
+the harness semantics LangChain does not encode directly.
+
+## Scenario: Five-Factor Tool Capability Protocol
+
+### 1. Scope / Trigger
+
+Read this document before changing:
+
+- `coding_deepgent.tool_system`
+- any domain `tools.py`
+- tool `args_schema`
+- tool permission/trust/exposure metadata
+- tool output/result rendering behavior
+- large-output persistence eligibility
+- runtime-pressure/microcompact tool eligibility
+- MCP/plugin/skill/subagent/task tool registration
+
+This is an infra/cross-layer contract because model-visible schema, permission
+policy, runtime execution, result projection, compact pressure, and tests must
+agree for every tool.
+
+### 2. Signatures
+
+Canonical local capability surface:
+
+```python
+@dataclass(frozen=True)
+class ToolCapability:
+    name: str
+    tool: BaseTool
+    domain: str
+    read_only: bool
+    destructive: bool
+    concurrency_safe: bool
+    source: str
+    trusted: bool
+    family: str
+    mutation: str
+    execution: str
+    exposure: str
+    rendering_result: str
+    enabled: bool = True
+    tags: tuple[str, ...] = ()
+    persist_large_output: bool = False
+    max_inline_result_chars: int | None = None
+    microcompact_eligible: bool = False
+
+KNOWN_TOOL_EXPOSURES = frozenset({"main", "child_only", "extension", "deferred"})
+TOOL_PROJECTION_EXPOSURES = {
+    "main": ("main", "extension"),
+    "child": ("child_only",),
+    "extension": ("extension",),
+    "deferred": ("deferred",),
+}
+
+@dataclass(frozen=True)
+class ToolPoolProjection:
+    name: str
+    capabilities: tuple[ToolCapability, ...]
+
+    def names(self) -> list[str]: ...
+    def tools(self) -> list[BaseTool]: ...
+    def metadata(self) -> dict[str, ToolCapability]: ...
+
+class ToolSearchInput(BaseModel):
+    query: str
+    max_results: int = 5
+
+def ToolSearch(query: str, runtime: ToolRuntime, max_results: int = 5) -> str: ...
+
+class InvokeDeferredToolInput(BaseModel):
+    tool_name: str
+    arguments: dict[str, Any]
+
+def invoke_deferred_tool(
+    tool_name: str,
+    arguments: dict[str, Any],
+    runtime: ToolRuntime,
+) -> ToolMessage | Command[Any]: ...
+```
+
+Required five-factor protocol for every registered tool:
+
+```text
+name
+schema
+permission
+execution
+rendering_result
+```
+
+Where:
+
+- `name` is the model-visible and registry identity.
+- `schema` is the strict Pydantic `args_schema` and any hidden injected runtime
+  fields that must not appear in `tool_call_schema`.
+- `permission` is the declared policy/trust surface:
+  `read_only`, `destructive`, `source`, `trusted`, `domain`, `mutation`.
+- `execution` is how the tool runs:
+  `plain_tool`, `command_update`, `child_agent_bridge`, `local_loader`,
+  adapter-backed MCP/plugin tool, or a documented future value.
+- `rendering_result` is the result contract:
+  `ToolMessage`, `Command(update=...)`, persisted-output preview,
+  session evidence, CLI renderer, or other documented bounded result.
+
+### 3. Contracts
+
+#### Five-Factor Ownership
+
+- Every model-facing tool must have one `ToolCapability` entry.
+- The registry `name` must match the actual LangChain tool name.
+- The tool schema must be strict and model-visible fields must be intentional.
+- Hidden injected runtime fields such as `ToolRuntime` or injected tool-call IDs
+  must not appear in model-visible schema.
+- Registry construction must fail when a capability has a mismatched name,
+  missing `args_schema` / `tool_call_schema`, blank/`unknown` required
+  metadata, invalid exposure, or inconsistent large-output/microcompact opt-in.
+- Permission metadata must describe the tool's real behavior, not the current
+  permission mode.
+- Execution metadata must describe the runtime boundary, not the business
+  domain. For example:
+  - `plain_tool`: returns a plain string/value or `ToolMessage`
+  - `command_update`: returns `Command(update=...)`
+  - `child_agent_bridge`: starts a bounded child-agent path
+  - `local_loader`: loads local non-model code/data into the current run
+- Rendering/result behavior must be bounded and testable. UI-specific React
+  rendering from cc-haha is not a local product surface.
+
+#### Safe Defaults
+
+- New capability booleans must default to the conservative value.
+- A tool is not `read_only` unless explicitly proven and tested.
+- A tool is not `concurrency_safe` unless it is read-only or otherwise proven
+  free of shared-state/race side effects.
+- A tool is not trusted when it comes from MCP/plugin/external sources unless
+  validation explicitly marks it trusted.
+- `source`, `trusted`, `family`, `mutation`, `execution`, `exposure`, and
+  `rendering_result` must be explicit at construction time. Do not rely on
+  implicit trusted/builtin defaults for extension tools.
+- A tool is not eligible for large-output persistence unless it can safely
+  return a preview/path reference and later be restored/read.
+- A tool is not `microcompact_eligible` unless old results can be safely hidden
+  without losing critical state.
+- A `microcompact_eligible` tool must also opt into large-output persistence in
+  the current local contract.
+- `destructive=False` does not mean "safe to run without policy"; it only means
+  the tool is not classified as destructive. Permission mode and trust still
+  apply.
+
+#### Capability-Driven Composition
+
+- Middleware and projection code must consume `ToolCapability` metadata instead
+  of hard-coding tool names when the behavior is cross-cutting.
+- Domain-specific validation belongs in the domain tool/schema/service, not in
+  `tool_system`.
+- `tool_system` may own capability projection, permission/trust routing,
+  result persistence, and runtime events.
+- Common tool failure classes such as unknown tool, permission denial, hook
+  block, and tool exception should surface as bounded model-consumable
+  `ToolMessage(status="error")` results rather than broken protocol state.
+- `containers/*` may wire tool groups, but must not decide business semantics.
+
+#### LangChain-Native Boundary
+
+- Use LangChain `@tool`, strict Pydantic schemas, `ToolRuntime`, middleware,
+  `ToolMessage`, and `Command(update=...)` first.
+- Do not recreate cc-haha's TypeScript `Tool` interface as a parallel Python
+  runtime object.
+- Do not introduce a custom query loop or custom `StreamingToolExecutor` unless
+  a source-backed PRD proves LangChain's runtime cannot satisfy a concrete local
+  latency/order/cancellation need.
+- If streaming/concurrency optimization becomes necessary, introduce a narrow
+  LangChain adapter contract first and preserve middleware, policy, state, and
+  evidence boundaries.
+
+#### Exposure And Extension Sources
+
+- `exposure="main"` and `exposure="extension"` are model-facing main tools.
+- `exposure="child_only"` is allowed only for bounded child-agent or verifier
+  surfaces.
+- `exposure="deferred"` is the local deferred-discovery surface. Deferred tools
+  must not enter the initial main/child projections directly.
+- `ToolSearch` and `invoke_deferred_tool` are the main-surface bridge tools for
+  deferred discovery/execution.
+- Runtime surfaces should call registry projection helpers such as
+  `project("main")`, `names_for_projection("main")`,
+  `tools_for_projection("child")`, or `tools_for_names(...)` instead of
+  duplicating exposure filtering.
+- `ToolPoolProjection` is the explicit projection seam for follow-up work. It
+  may be tested independently from agent startup and runtime wiring.
+- `declarable_names()` must include enabled `main`, `extension`, and
+  `deferred` names, while excluding `child_only` and disabled tools.
+- `ToolSearch` must return the matched deferred tool's exact name plus the full
+  `tool_call_schema` JSON schema needed for later execution.
+- `invoke_deferred_tool` must execute the actual deferred capability through the
+  shared `ToolGuardMiddleware` path so permission policy, hook dispatch,
+  bounded failure shaping, and large-output persistence still apply to the real
+  target tool.
+- Deferred execution may preserve the real bounded result contract of the
+  target capability, including `ToolMessage` and `Command(update=...)`, rather
+  than degrading all deferred tools to plain string results.
+- Do not overload `child_only` or `extension` to mean deferred schema loading.
+- MCP/plugin tools must preserve source/trust metadata so permission and
+  observability can distinguish builtin from extension behavior.
+
+#### Local Extension Debug Surfaces
+
+Circle 1 local extension seams must be user-debuggable through CLI surfaces:
+
+```bash
+coding-deepgent skills list|inspect|validate|debug
+coding-deepgent mcp list|inspect|validate|debug
+coding-deepgent hooks list|inspect|validate|debug
+coding-deepgent plugins list|inspect|validate|debug
+```
+
+- These commands are inspect/validate/debug surfaces only; they must not install
+  packages, enable marketplace entries, mutate plugin state, or start a daemon.
+- `skills` commands use the same local `SKILL.md` loader as the `load_skill`
+  tool.
+- `mcp` commands use the same `.mcp.json` parser as runtime MCP loading.
+- `hooks` commands expose the supported local sync hook event names and do not
+  imply a file-backed hook plugin system.
+- `plugins validate` must validate manifest declarations against known local
+  tool and skill names instead of trusting manifest text.
+
+### 4. Validation & Error Matrix
+
+| Case | Expected behavior |
+|---|---|
+| duplicate capability names | registry construction raises `ValueError` |
+| capability name differs from LangChain tool name | test failure; do not register |
+| tool has extra public schema aliases | schema validation rejects unless explicitly documented |
+| hidden runtime field appears in public schema | test failure |
+| new tool omits capability metadata | test failure or review block |
+| tool marked `read_only=True` but mutates workspace/store/state | reject metadata or change tool behavior |
+| tool marked `concurrency_safe=True` but writes shared state | reject metadata |
+| untrusted destructive extension in accept/bypass modes | permission remains ask/deny; not auto-allowed |
+| tool handler raises exception | bounded `ToolMessage(status=\"error\")` is returned with the original `tool_call_id` |
+| large-output eligible tool returns oversized result | middleware may persist full output and return preview/path |
+| ineligible tool returns oversized result | result remains inline unless tool-local policy handles it |
+| `microcompact_eligible=True` for non-restorable stateful output | reject metadata |
+| child-only tool appears in main projection | projection test fails |
+| extension tool lacks source/trust identity | startup/registration validation rejects it |
+| deferred tool is registered | excluded from initial main and child projections; visible through `deferred` projection and bridge tools |
+| `ToolSearch` query matches deferred tools | result returns exact names plus full JSON parameter schemas |
+| `invoke_deferred_tool` targets unknown or non-deferred tool | bounded error result; no direct execution |
+| `invoke_deferred_tool` targets a denied deferred capability | shared policy path still returns bounded `ToolMessage(status="error")` |
+| deferred capability returns `Command(update=...)` | deferred bridge preserves the `Command` result instead of throwing a runtime error |
+
+### 5. Good / Base / Bad Cases
+
+#### Good
+
+```python
+ToolCapability(
+    name="read_file",
+    tool=read_file,
+    domain="filesystem",
+    read_only=True,
+    destructive=False,
+    concurrency_safe=True,
+    source="builtin",
+    trusted=True,
+    family="filesystem",
+    mutation="read",
+    execution="plain_tool",
+    exposure="main",
+    rendering_result="tool_message_or_persisted_output",
+    tags=("read", "workspace"),
+    persist_large_output=True,
+    max_inline_result_chars=4000,
+    microcompact_eligible=True,
+)
+```
+
+Expected:
+
+- schema is strict and model-visible
+- permission can auto-allow in safe modes
+- concurrent reads are allowed
+- large results may be persisted and later restored
+- old results may be microcompacted because the file can be read again
+
+#### Base
+
+```python
+ToolCapability(
+    name="task_update",
+    tool=task_update,
+    domain="tasks",
+    read_only=False,
+    destructive=False,
+    concurrency_safe=False,
+    source="builtin",
+    trusted=True,
+    family="tasks",
+    mutation="durable_store",
+    execution="plain_tool",
+    exposure="main",
+    rendering_result="tool_message",
+)
+```
+
+Expected:
+
+- not destructive, but still not read-only
+- not concurrency-safe because it mutates store-backed workflow state
+- permission/policy and verifier boundaries still apply
+
+#### Bad
+
+```python
+ToolCapability(
+    name="write_file",
+    tool=write_file,
+    domain="filesystem",
+    read_only=True,
+    destructive=False,
+    concurrency_safe=True,
+    source="builtin",
+    trusted=True,
+    family="filesystem",
+    mutation="workspace_write",
+    execution="plain_tool",
+    exposure="main",
+    rendering_result="tool_message",
+)
+```
+
+Expected:
+
+- reject; this lies to permission and concurrency policy
+- write tools must declare workspace mutation and non-concurrency-safe behavior
+
+### 6. Tests Required
+
+Required focused test families:
+
+- `coding-deepgent/tests/tool_system/test_tool_system_registry.py`
+- `coding-deepgent/tests/tool_system/test_tool_system_middleware.py`
+- `coding-deepgent/tests/tool_system/test_tool_search.py`
+- domain-specific schema tests, for example:
+  - `coding-deepgent/tests/filesystem/test_tools.py`
+  - `coding-deepgent/tests/tasks/test_tasks.py`
+  - `coding-deepgent/tests/subagents/test_subagents.py`
+  - `coding-deepgent/tests/memory/test_memory.py`
+  - `coding-deepgent/tests/extensions/test_skills.py`
+  - `coding-deepgent/tests/extensions/test_mcp.py`
+
+Required assertion points:
+
+- public tool names match capability names
+- duplicate names fail
+- main/child/extension exposure projections are stable
+- deferred projection and bridge-tool contracts are stable
+- hidden injected runtime fields are absent from model-visible schema
+- invalid extra/alias fields fail schema validation
+- permission behavior uses capability metadata
+- common tool failures remain bounded protocol-correct `ToolMessage` errors
+- untrusted destructive extension tools are not auto-allowed
+- large-output and microcompact eligibility are opt-in
+- child-only tools do not enter the main tool surface
+- deferred tools do not enter the initial main tool surface directly
+
+### 7. Wrong vs Correct
+
+#### Wrong
+
+```python
+# Cross-cutting behavior hard-coded by tool name.
+if request.tool_call["name"] in {"read_file", "bash", "grep"}:
+    persist_large_output(...)
+```
+
+Why wrong:
+
+- extension/MCP tools cannot participate without editing middleware
+- behavior drifts from source/trust/domain metadata
+- future ToolSearch/deferred/plugin work becomes special-case heavy
+
+#### Correct
+
+```python
+capability = registry.get(str(request.tool_call["name"]))
+if capability is not None and capability.persist_large_output:
+    persist_large_output(...)
+```
+
+Why correct:
+
+- tools opt in through metadata
+- middleware stays generic
+- extension tools can be validated and composed consistently
+
+#### Wrong
+
+```python
+# Recreate cc-haha's full Tool runtime interface locally.
+class Tool:
+    def render_react_ui(...): ...
+    def streaming_executor_hook(...): ...
+```
+
+Why wrong:
+
+- `coding-deepgent` is LangChain/LangGraph-native
+- React rendering and custom streaming loop are not local runtime boundaries
+- this bypasses official middleware/tool state seams
+
+#### Correct
+
+```python
+@tool("read_file", args_schema=ReadFileInput)
+def read_file(path: str, runtime: ToolRuntime, limit: int | None = None) -> str:
+    ...
+
+ToolCapability(
+    name="read_file",
+    tool=read_file,
+    ...
+)
+```
+
+Why correct:
+
+- LangChain owns tool execution/schema exposure
+- `ToolCapability` owns cc-harness metadata not encoded by LangChain
+- middleware can compose permission, result persistence, evidence, and pressure
+  behavior from metadata
diff --git a/.trellis/spec/backend/tool-result-storage-contracts.md b/.trellis/spec/backend/tool-result-storage-contracts.md
new file mode 100644
index 000000000..473c336b7
--- /dev/null
+++ b/.trellis/spec/backend/tool-result-storage-contracts.md
@@ -0,0 +1,145 @@
+# Tool Result Storage Contracts
+
+> Executable contracts for live large-output persistence and preview references.
+
+## Scenario: Live Tool Result Storage
+
+### 1. Scope / Trigger
+
+- Trigger: changes touching `coding_deepgent.tool_system`, `coding_deepgent.compact`,
+  runtime tool-result handling, or capability metadata for large-output tools.
+- Applies when a live tool call may replace oversized inline tool output with a
+  persisted file reference and preview for the model.
+- This is a cross-layer contract because capability metadata, middleware result
+  handling, runtime context/session id, workspace file paths, and tests must
+  agree.
+- For the broader five-factor tool protocol and safe defaults for
+  `persist_large_output`, read
+  [Tool Capability Contracts](./tool-capability-contracts.md).
+
+### 2. Signatures
+
+```python
+def tool_results_dir(runtime_context: RuntimeContext) -> Path: ...
+
+def persist_tool_result(
+    content: str,
+    *,
+    runtime_context: RuntimeContext,
+    tool_call_id: str,
+    serialized_kind: str,
+    preview_chars: int = DEFAULT_PREVIEW_CHARS,
+) -> PersistedToolResult: ...
+
+def maybe_persist_large_tool_result(
+    result: ToolMessage,
+    *,
+    runtime_context: RuntimeContext,
+    max_inline_chars: int | None,
+    preview_chars: int = DEFAULT_PREVIEW_CHARS,
+) -> ToolMessage: ...
+```
+
+### 3. Contracts
+
+- Large-result persistence is a live runtime message optimization. It must not
+  rewrite persisted session transcript history in this stage.
+- `tool_results_dir(runtime_context)` must resolve inside the active workspace:
+
+```text
+<workdir>/.coding-deepgent/tool-results/<session_id>/
+```
+
+- For eligible tools, a successful `ToolMessage` whose serialized content length
+  exceeds `max_inline_chars` must be rewritten to:
+  - write the full content to a session-scoped file under `tool_results_dir(...)`
+  - keep only a preview/reference message in `ToolMessage.content`
+  - preserve `tool_call_id`, `status`, and other existing message metadata
+- Rewritten preview content must be wrapped in:
+
+```text
+<persisted-output>
+...
+</persisted-output>
+```
+
+- The preview content must include the relative workspace path to the persisted
+  file so a workspace read tool can reopen it later.
+- A tool may remain `microcompact_eligible` even when replaying the original
+  tool call would be unsafe or non-deterministic, as long as large-output
+  persistence keeps a stable model-visible path to the full original output.
+- Small successful results must remain unchanged.
+- Error `ToolMessage` results must remain unchanged.
+- Existing upstream `ToolMessage.artifact` must not be discarded. If a rewritten
+  message adds storage metadata, the upstream artifact must remain reachable
+  through the rewritten artifact payload.
+- File naming must be deterministic from `tool_call_id` after path sanitization.
+- If persistence raises an `OSError` in middleware, the middleware must fail
+  open and return the original `ToolMessage` unchanged.
+
+### 4. Validation & Error Matrix
+
+| Case | Expected behavior |
+|---|---|
+| large successful tool result from eligible tool | file is written; model-visible content becomes preview reference |
+| small successful tool result from eligible tool | message remains unchanged |
+| successful tool result from ineligible tool | message remains unchanged |
+| error tool result | message remains unchanged |
+| upstream artifact already present | rewritten artifact preserves upstream artifact |
+| sanitized `tool_call_id` contains `:` or spaces | output filename is path-safe and deterministic |
+| file write fails with `OSError` | original `ToolMessage` is returned |
+
+### 5. Good / Base / Bad Cases
+
+#### Good
+
+```python
+rewritten = maybe_persist_large_tool_result(
+    ToolMessage(content="x" * 5000, tool_call_id="call:1"),
+    runtime_context=context,
+    max_inline_chars=4000,
+)
+```
+
+Expected:
+- writes full output under `.coding-deepgent/tool-results/<session_id>/call-1.txt`
+- returns preview content wrapped in persisted-output markers
+
+#### Base
+
+```python
+unchanged = maybe_persist_large_tool_result(
+    ToolMessage(content="small", tool_call_id="call-1"),
+    runtime_context=context,
+    max_inline_chars=4000,
+)
+```
+
+Expected:
+- returns the original message object unchanged
+
+#### Bad
+
+```python
+maybe_persist_large_tool_result(
+    ToolMessage(content="x" * 5000, tool_call_id="call-1", status="error"),
+    runtime_context=context,
+    max_inline_chars=4000,
+)
+```
+
+Expected:
+- must not rewrite error results into persisted-output previews
+
+### 6. Tests Required
+
+- `coding-deepgent/tests/tool_system/test_tool_result_storage.py`
+- `coding-deepgent/tests/tool_system/test_tool_system_middleware.py::test_tool_guard_persists_large_tool_output_for_eligible_tools`
+
+Required assertion points:
+
+- preview message contains persisted-output wrapper tags
+- preview message contains a workspace-relative persisted file path
+- persisted file contains full original content
+- small results are unchanged
+- middleware integration persists only after an allowed tool call
diff --git a/.trellis/spec/frontend/component-guidelines.md b/.trellis/spec/frontend/component-guidelines.md
new file mode 100644
index 000000000..3c1954134
--- /dev/null
+++ b/.trellis/spec/frontend/component-guidelines.md
@@ -0,0 +1,25 @@
+# Frontend Component Guidelines
+
+Status: `Active` for `coding-deepgent/frontend/cli`
+
+## Component Rules
+
+- Components are small React functions that return `React.ReactNode`.
+- Props should be explicit object types near the component unless shared.
+- Components consume already-reduced UI state; they should not parse JSONL or spawn Python.
+- Presentational components live in `src/components/`.
+- Bridge/process/protocol logic lives in `src/bridge/`.
+- Prefer clear terminal affordances over heavy styling.
+
+## Current Component Examples
+
+- `PromptInput` owns local text-entry state and calls `onSubmit`.
+- `MessageList` renders the bounded message window and delegates rows to `MessageRow`.
+- `TodoPanel` renders a snapshot created by the reducer; it does not know Python state shape.
+
+## Anti-Patterns
+
+- reading process stdout directly inside components
+- mutating shared UI state outside the reducer
+- importing root `web/` components into product CLI
+- copying cc components that require cc AppState or feature flags
diff --git a/.trellis/spec/frontend/directory-structure.md b/.trellis/spec/frontend/directory-structure.md
new file mode 100644
index 000000000..c3f57bb90
--- /dev/null
+++ b/.trellis/spec/frontend/directory-structure.md
@@ -0,0 +1,77 @@
+# Frontend Directory Structure
+
+Status: `Active` for `coding-deepgent/frontend/cli`
+
+Current product frontend targets:
+
+```text
+coding-deepgent/frontend/cli
+coding-deepgent/frontend/web
+```
+
+Root `web/` remains reference-only.
+
+## Directory Layout
+
+```text
+coding-deepgent/frontend/
+├── web/
+│   └── index.html             # minimal browser shell over SSE gateway
+├── protocol/                  # renderer-neutral JSONL contract docs
+└── cli/                       # React/Ink CLI frontend package
+    ├── package.json
+    ├── tsconfig.json
+    └── src/
+        ├── index.tsx          # CLI entrypoint
+        ├── app.tsx            # Ink root composition
+        ├── bridge/            # Python process bridge, protocol types, reducer
+        ├── components/        # presentational Ink components
+        └── __tests__/         # TS unit tests
+```
+
+Python bridge/backend code belongs in:
+
+```text
+coding-deepgent/src/coding_deepgent/frontend/
+├── protocol.py                # renderer-neutral event/input models
+├── producer.py                # runtime event producer, no transport ownership
+├── client.py                  # embedded in-process client for scripts/tests
+├── runs.py                    # run lifecycle for future network adapters
+├── stream_bridge.py           # replayable event log for SSE/gateway use
+├── bridge.py                  # backward-compatible imports only
+└── adapters/
+    ├── jsonl.py               # stdio JSONL transport for React/Ink CLI
+    └── sse.py                 # SSE formatter/consumer for future Web
+```
+
+## Rules
+
+- Keep protocol types and event reducers in `src/bridge/`.
+- Keep Ink rendering components in `src/components/`.
+- Keep runtime/backend behavior in Python `coding_deepgent.frontend`, not in TS UI components.
+- Keep runtime event generation in `coding_deepgent.frontend.producer`.
+- Keep transport-specific code under `coding_deepgent.frontend.adapters`.
+- Do not let runtime/domain packages import `coding_deepgent.frontend.adapters`
+  or `coding_deepgent.frontend.bridge`.
+- Do not import from root `web/` or tutorial/reference directories.
+- Keep `node_modules/` ignored and commit `package-lock.json`.
+
+## Real Examples
+
+- `coding-deepgent/frontend/cli/src/bridge/protocol.ts`
+- `coding-deepgent/frontend/cli/src/bridge/reducer.ts`
+- `coding-deepgent/frontend/cli/src/components/message-list.tsx`
+- `coding-deepgent/frontend/web/index.html`
+- `coding-deepgent/src/coding_deepgent/frontend/producer.py`
+- `coding-deepgent/src/coding_deepgent/frontend/adapters/jsonl.py`
+- `coding-deepgent/src/coding_deepgent/frontend/client.py`
+- `coding-deepgent/src/coding_deepgent/frontend/runs.py`
+- `coding-deepgent/src/coding_deepgent/frontend/stream_bridge.py`
+
+## Anti-Patterns
+
+- putting Python runtime decisions inside TS components
+- parsing Rich terminal output in the frontend
+- treating root `web/` tutorial code as product frontend source
+- copying large cc React/Ink runtime files wholesale
+- making Web depend on the JSONL CLI adapter
diff --git a/.trellis/spec/frontend/hook-guidelines.md b/.trellis/spec/frontend/hook-guidelines.md
new file mode 100644
index 000000000..40197e29a
--- /dev/null
+++ b/.trellis/spec/frontend/hook-guidelines.md
@@ -0,0 +1,30 @@
+# Frontend Hook Guidelines
+
+Status: `Deferred`
+
+Current mainline is `coding-deepgent/`, not frontend/web product work.
+
+Only activate this spec when a task explicitly makes frontend/web a product
+target and hook patterns become relevant.
+
+## Activation Requirements
+
+- User explicitly requests frontend/web product work.
+- There are real hook examples to extract from.
+- Hook rules are needed for implementation or review.
+
+## 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..b8207d950
--- /dev/null
+++ b/.trellis/spec/frontend/index.md
@@ -0,0 +1,49 @@
+# Frontend Development Guidelines
+
+> Frontend guidance status for this repository.
+
+---
+
+## Current Status
+
+The current working mainline is `coding-deepgent/`.
+
+Product frontend work is now active only for:
+
+- `coding-deepgent/frontend/cli` — TypeScript React/Ink CLI frontend
+- `coding-deepgent/src/coding_deepgent/frontend` — Python JSONL bridge/protocol backend
+
+The root `web/` app remains tutorial/reference-only unless a task explicitly
+promotes it to product Web work.
+
+---
+
+## Guidelines Index
+
+| Guide | Description | Status |
+|-------|-------------|--------|
+| [Directory Structure](./directory-structure.md) | CLI app, protocol, component, and bridge organization | Active |
+| [Component Guidelines](./component-guidelines.md) | Component patterns, props, and composition | Active |
+| [Hook Guidelines](./hook-guidelines.md) | Custom hook naming, dependencies, and side effects | Deferred |
+| [State Management](./state-management.md) | Local event reducer and bridge-driven state patterns | Active |
+| [Type Safety](./type-safety.md) | TypeScript protocol and UI state conventions | Active |
+| [Quality Guidelines](./quality-guidelines.md) | Testing, typecheck, and review expectations | Active |
+
+---
+
+## Reactivation Rule
+
+Only expand these frontend specs when:
+
+1. a task explicitly targets frontend/web product work, and
+2. the target is no longer reference-only, and
+3. the spec can be filled from actual code conventions rather than ideals.
+
+---
+
+## Language Convention
+
+- Narrative prose may be written in **Simplified Chinese**.
+- Keep commands, file paths, file names, task slugs, branch names, code identifiers, and JSON/YAML keys in **English**.
+- Keep checklist keywords and structured status values in **English** when they are used for search, automation, or coordination.
+- When introducing project-specific terms, prefer Chinese explanations with the original English term kept where precision matters.
diff --git a/.trellis/spec/frontend/quality-guidelines.md b/.trellis/spec/frontend/quality-guidelines.md
new file mode 100644
index 000000000..c521b0e87
--- /dev/null
+++ b/.trellis/spec/frontend/quality-guidelines.md
@@ -0,0 +1,47 @@
+# Frontend Quality Guidelines
+
+Status: `Active` for `coding-deepgent/frontend/cli`
+
+## Required Checks
+
+Run from `coding-deepgent/frontend/cli`:
+
+```bash
+npm run typecheck
+npm test
+```
+
+For repo-local product smoke, run from `coding-deepgent`:
+
+```bash
+PYTHONPATH=src python3 -m coding_deepgent ui-bridge --fake
+PYTHONPATH=src python3 -m coding_deepgent ui --fake
+```
+
+Run focused Python tests from `coding-deepgent` when bridge/protocol behavior changes:
+
+```bash
+pytest -q tests/frontend/test_frontend_protocol.py tests/frontend/test_frontend_bridge.py tests/frontend/test_frontend_event_mapping.py
+```
+
+When frontend HITL / permission pause-resume behavior changes, also include:
+
+```bash
+pytest -q tests/tool_system/test_tool_system_middleware.py
+```
+
+## Test Expectations
+
+- TS tests should cover protocol parsing and reducer behavior.
+- Python tests should cover strict protocol validation, bridge event order,
+  streaming deltas, and event mapping.
+- For interrupt-backed permission flows, Python tests should cover
+  `permission_requested` emission, `permission_decision` resume, and bounded
+  reject behavior.
+- Smoke test the fake interactive CLI in a TTY when changing input/exit behavior.
+
+## Anti-Patterns
+
+- relying only on manual terminal testing
+- changing protocol payloads without updating both Python and TS tests
+- adding unbounded terminal output snapshots as tests
diff --git a/.trellis/spec/frontend/state-management.md b/.trellis/spec/frontend/state-management.md
new file mode 100644
index 000000000..ac85a5188
--- /dev/null
+++ b/.trellis/spec/frontend/state-management.md
@@ -0,0 +1,42 @@
+# Frontend State Management
+
+Status: `Active` for `coding-deepgent/frontend/cli`
+
+## State Ownership
+
+- Python owns runtime/session/tool/todo facts.
+- TypeScript owns display state derived from `FrontendEvent` payloads.
+- `src/bridge/reducer.ts` is the canonical event-to-UI-state reducer.
+- Components may own small local interaction state, such as the current prompt input.
+- Runtime facts such as todo/task/context/subagent snapshots are replace-latest
+  state. Components render the latest reduced snapshot and must not infer
+  product truth by parsing message text.
+- Background subagent lifecycle is also replace-latest state:
+  `background_subagent_snapshot` replaces the prior run list in reducer state.
+
+## Rules
+
+- Use `useReducer(reduceFrontendEvent, initialUiState)` for bridge events.
+- Do not mutate `UiState` in place.
+- Do not store Python subprocess handles in React state; keep them in bridge classes.
+- Keep reducer behavior deterministic and covered by TS tests.
+- Keep long-term/session persistence in Python, not frontend local storage.
+- Local-only UI actions such as `/help` and `/clear` may use reducer actions,
+  but Python runtime facts must still arrive through `FrontendEvent`.
+- `ContextPanel`, `TaskPanel`, and `SubagentPanel` consume reducer state only;
+  they must not load sessions or call Python directly.
+- Slash commands that trigger bridge control inputs may be parsed in the Ink app
+  layer, but they must still send typed `FrontendInput` payloads into the bridge
+  instead of mutating reducer state directly.
+
+## Real Examples
+
+- `coding-deepgent/frontend/cli/src/bridge/reducer.ts`
+- `coding-deepgent/frontend/cli/src/app.tsx`
+- `coding-deepgent/frontend/cli/src/components/prompt-input.tsx`
+
+## Anti-Patterns
+
+- components directly editing `messages`, `todos`, or `pendingPermissions`
+- deriving product truth from terminal text
+- duplicating Python session persistence in TS state
diff --git a/.trellis/spec/frontend/type-safety.md b/.trellis/spec/frontend/type-safety.md
new file mode 100644
index 000000000..7191b15ab
--- /dev/null
+++ b/.trellis/spec/frontend/type-safety.md
@@ -0,0 +1,43 @@
+# Frontend Type Safety
+
+Status: `Active` for `coding-deepgent/frontend/cli`
+
+## Type Ownership
+
+- Python protocol validation lives in `coding_deepgent.frontend.protocol`.
+- TypeScript protocol types live in `frontend/cli/src/bridge/protocol.ts`.
+- TS state types live in `frontend/cli/src/bridge/reducer.ts`.
+
+## Rules
+
+- `FrontendEvent` and `FrontendInput` should be discriminated unions by `type`.
+- Keep `strict`, `noUncheckedIndexedAccess`, and `exactOptionalPropertyTypes` enabled.
+- Python protocol models should reject extra fields.
+- Runtime payload changes require Python protocol tests and TS reducer/protocol tests.
+- Optional props should explicitly include `undefined` when passed through from state.
+- Streaming payloads must use the same `message_id` across `assistant_delta`
+  and the final `assistant_message`.
+- Runtime visibility snapshots must be typed on both sides of the bridge:
+  `context_snapshot` carries bounded projection counters and
+  `subagent_snapshot` carries bounded recent sidechain activity.
+  `background_subagent_snapshot` carries bounded live background-run status.
+  Do not pass raw transcript records through the TUI protocol.
+- Bridge control inputs such as `refresh_snapshots`, `run_background_subagent`,
+  `subagent_send_input`, and `subagent_stop` must be added on both the Python
+  and TS sides together.
+- HITL payloads must preserve `permission_requested.request_id` end-to-end:
+  for LangGraph interrupt-backed frontend flows, this id is the interrupt id and
+  `permission_decision.request_id` must echo it unchanged on resume.
+
+## Real Examples
+
+- `coding-deepgent/frontend/cli/src/bridge/protocol.ts`
+- `coding-deepgent/frontend/cli/src/bridge/reducer.ts`
+- `coding-deepgent/src/coding_deepgent/frontend/protocol.py`
+
+## Anti-Patterns
+
+- `any` payloads crossing the bridge without validation
+- adding event types only on one side of the Python/TS boundary
+- permissive alias/fallback parsing for protocol fields
+- rewriting or regenerating interrupt-backed `request_id` values in the UI layer
diff --git a/.trellis/spec/guides/architecture-posture-guide.md b/.trellis/spec/guides/architecture-posture-guide.md
new file mode 100644
index 000000000..1815e471a
--- /dev/null
+++ b/.trellis/spec/guides/architecture-posture-guide.md
@@ -0,0 +1,121 @@
+# Architecture Posture Guide
+
+> Project-wide decision rule for architecture, refactors, and sequencing.
+
+---
+
+## Purpose
+
+Use this guide when a task involves architecture choices, refactors, runtime
+foundations, contract changes, state schema changes, or any situation where a
+"smallest patch" option competes with a cleaner long-term structure.
+
+This is a **must-adhere** project rule, not an optional style preference.
+
+---
+
+## Core Rules
+
+### 1. Prioritize highest-value architecture, not smallest diff
+
+When choosing between approaches, prioritize the option with the largest
+long-term product and architecture benefit, not the one with the fewest changed
+lines.
+
+Default bias:
+
+* clearer boundaries
+* stronger future extensibility
+* fewer hidden coupling points
+* less rework in later stages
+
+### 2. Prefer long-term clean boundaries over transitional compatibility
+
+If a new structure is clearly more coherent, prefer it even when it replaces a
+local abstraction that already exists.
+
+Do not preserve an inferior abstraction only because it is already present.
+
+### 3. Do not add bridge layers or fallback paths just to protect old local designs
+
+Avoid:
+
+* compatibility shims whose only purpose is to preserve outdated local shapes
+* duplicate abstractions kept alive "for safety"
+* fallback code paths added only to avoid replacing a weaker design
+
+Allow them only when there is a real external compatibility requirement that the
+maintainer explicitly wants to preserve.
+
+### 4. Replacing old local abstractions is allowed
+
+If the new architecture is more correct, more durable, and easier to extend,
+replace the old abstraction directly.
+
+This applies to:
+
+* runtime/session/transcript foundations
+* task/subagent/fork boundaries
+* tool capability and projection contracts
+* state schema and persistence layout
+
+### 5. Sequence by architectural leverage, not by easiest patch
+
+When multiple tasks are possible, prefer the one that unlocks or clarifies the
+rest of the system, even if it is not the smallest isolated patch.
+
+Examples:
+
+* define a reusable contract before adding multiple ad hoc call sites
+* land a missing runtime seam before discussing deeper parity built on top of it
+* separate two concepts cleanly before extending either of them
+
+---
+
+## How To Apply This Guide
+
+Before choosing an approach, ask:
+
+1. Which option creates the clearest long-term boundary?
+2. Which option avoids future bridge/fallback cleanup work?
+3. Which option best supports later adjacent features?
+4. Which option would I choose if old local compatibility were not a concern?
+
+If the answers point to a cleaner structure, prefer that structure.
+
+---
+
+## What This Guide Does Not Mean
+
+This guide does **not** mean:
+
+* always choose the biggest rewrite
+* ignore validation/testing cost
+* reopen explicitly deferred product areas
+* introduce speculative abstractions without a clear future consumer
+
+The requirement is to choose the **highest-value coherent structure**, not the
+largest possible implementation.
+
+---
+
+## Typical Good Outcomes
+
+* split fork semantics from normal subagent semantics instead of overloading one
+  entrypoint
+* replace a weak transcript shape rather than layering compatibility shims on top
+* make a new contract explicit now instead of encoding it across scattered flags
+* keep a feature deferred rather than introducing a low-quality partial copy that
+  distorts the architecture
+
+---
+
+## Escalation Rule
+
+Stop and ask the maintainer only when:
+
+* the architecture choice implies a major product-direction change
+* there is a real external compatibility requirement that conflicts with this guide
+* data loss or irreversible migration is involved
+
+Otherwise, proceed with the cleaner long-term option by default.
diff --git a/.trellis/spec/guides/cc-alignment-guide.md b/.trellis/spec/guides/cc-alignment-guide.md
new file mode 100644
index 000000000..583534d29
--- /dev/null
+++ b/.trellis/spec/guides/cc-alignment-guide.md
@@ -0,0 +1,255 @@
+# CC Alignment Guide
+
+> **Purpose**: Keep `cc-haha` / Claude Code alignment source-backed, effect-driven, and LangChain-native.
+
+---
+
+## Scope
+
+Use this guide when a `coding-deepgent` feature should align with
+`NanmiCoder/cc-haha` or related Claude Code runtime behavior.
+
+This guide is for:
+
+- implementation
+- review
+- planning
+- documentation of feature alignment
+
+It is not a license to copy behavior just because names look similar.
+
+---
+
+## Core Rule
+
+Before code changes, state the **expected effect** first, then produce a
+source-backed alignment matrix.
+
+If you cannot explain the concrete local effect, do not align by default.
+Mark the behavior as `defer` or `do-not-copy`.
+
+For the current mainline, the default target order is:
+
+1. real Claude Code public behavior
+2. `cc-haha` source-backed implementation reference
+3. high-quality analogous OSS, only when the first two are insufficient
+
+---
+
+## Required Pre-Code Workflow
+
+1. **Name the feature band**
+   - Example: `TodoWrite`, `Skill loading`, `Runtime pressure`, `Verifier execution`
+2. **State the expected effect first**
+   - What concrete user/runtime/safety/reliability/maintainability effect should appear locally?
+3. **Identify cc-haha reference points**
+   - List exact source files and, when practical, symbols/functions.
+4. **Check real Claude Code public behavior**
+   - Note the public behavior, docs, or visible runtime artifact you are
+     actually trying to match.
+5. **Extract functional essence**
+   - What problem does the cc behavior solve?
+   - What state does it own?
+   - What model-visible surface does it change?
+6. **Separate essence from product detail**
+   - keep the essence
+   - copy product detail only if it creates a concrete local benefit now
+7. **Write the alignment matrix before implementation**
+
+If `cc-haha` source is missing or incomplete for the relevant capability:
+
+8. **Run OSS fallback research before implementation**
+   - inspect 2-4 high-quality analogous OSS systems
+   - summarize the implementation patterns they use
+   - record why `cc-haha` evidence was insufficient
+   - state which local design was chosen and what remains inferred
+
+## Evidence Ladder
+
+Use this evidence order explicitly:
+
+1. **Claude Code public behavior**
+   - official docs
+   - public product surfaces
+   - reproducible visible behavior
+   - public runtime artifacts
+2. **`cc-haha` source**
+   - files, symbols, docs, comments, and observable behavior
+3. **Analogous OSS**
+   - high-quality open-source systems in the same capability family
+4. **Secondary analysis**
+   - books, blogs, third-party explanations
+
+Rules:
+
+* real Claude Code public behavior is the top-level parity target
+* `cc-haha` is the default implementation reference when it matches or explains
+  the target behavior
+* analogous OSS is required when Claude Code public behavior and `cc-haha`
+  source do not sufficiently explain how to implement the feature
+* secondary analysis is useful context, but must not overrule stronger evidence
+
+## Missing-Source Workflow
+
+When a capability does not have enough accessible source:
+
+1. name the exact source gap
+2. state what public Claude Code behavior is still visible
+3. inspect 2-4 high-quality OSS systems
+4. summarize what each system contributes
+5. write the local choice into the PRD before implementation
+
+Required PRD add-on shape:
+
+```md
+## Source Gap
+
+- target behavior:
+- Claude Code public evidence:
+- `cc-haha` evidence:
+- why those are insufficient:
+
+## Analogous OSS Review
+
+- project A:
+- project B:
+
+## Local Decision
+
+- chosen design:
+- why it fits locally:
+- what remains inferred:
+```
+
+---
+
+## Required Alignment Matrix
+
+Use this shape in the task PRD or planning note before editing code:
+
+```md
+## Expected effect
+
+Aligning this behavior should improve: <category>. The local user/runtime effect
+is: <specific outcome>. If this effect does not appear, the change is not worth
+shipping.
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Tool/schema | `TodoWrite(todos=...)` | fewer model JSON mistakes | strict tool schema | align | Match model-visible contract |
+| Runtime state | `appState.todos[...]` | correct isolation semantics | local state domain | defer | Requires later stage |
+```
+
+Status vocabulary:
+
+- `align`
+- `partial`
+- `defer`
+- `do-not-copy`
+- `unknown/inferred`
+
+---
+
+## Decision Rules
+
+### Align when
+
+- the effect is specific and valuable now
+- the behavior is model-visible contract or essential state semantics
+- it prevents a known failure mode
+- it fits naturally into official LangChain/LangGraph primitives
+
+### Defer when
+
+- the effect depends on a later capability or stage
+- it would force speculative abstractions
+- it is real cc behavior but not current mainline priority
+
+### Do-not-copy when
+
+- it is only UI/TUI detail
+- it is provider-specific plumbing better handled by LangChain
+- it conflicts with a simpler local abstraction
+- it would blur current product boundaries
+
+---
+
+## Mandatory Boundary Checks
+
+Before implementation, answer these explicitly:
+
+1. What is the expected effect?
+2. What is in scope?
+3. What are the non-goals?
+4. What state is short-term, persistent, shared, or model-visible?
+5. What exact model-visible tool/prompt/schema surface changes?
+6. Which LangChain/LangGraph primitive should express it?
+
+Valid local primitives usually include:
+
+- strict tool + Pydantic schema
+- `Command(update=...)`
+- middleware hook
+- typed state schema / reducer
+- store / memory seam
+- graph node / edge
+
+---
+
+## Documentation Rule For This Repo
+
+For the current `coding-deepgent` mainline:
+
+- record cc alignment decisions in the active Trellis task PRD first
+- update `.trellis/plans/` only when the decision becomes roadmap/product direction
+- update `.trellis/spec/` only when the decision becomes an executable implementation constraint
+- do **not** default to tutorial-track `agents_deepagents/cc_alignment/` docs
+  unless the task explicitly targets tutorial/reference assets
+
+Do not put every exploratory source note into canonical plans or specs. Promote
+only stable decisions.
+
+---
+
+## Verification Requirements
+
+Evidence should prove both:
+
+1. **cc-haha mapping evidence**
+   - source files/symbols cited
+   - matrix decisions recorded
+   - intentional gaps documented
+2. **local behavior evidence**
+   - tests for model-visible schema
+   - tests for state/update shape
+   - tests for boundary guards
+   - grep or review checks for stale public names when needed
+
+---
+
+## Anti-Patterns
+
+Avoid:
+
+- using `cc-haha` as if it were automatically the highest target even when
+  real Claude Code public behavior says otherwise
+- implementing from memory without inspecting source
+- jumping directly from a source gap to local design without OSS fallback
+- copying file names without functional intent
+- line-for-line cloning when LangChain has a simpler primitive
+- treating secondary analysis as stronger than source behavior
+- leaving alignment status implicit
+
+---
+
+## Final Output Checklist
+
+Report:
+
+- expected effect
+- source files/symbols inspected
+- alignment matrix summary
+- what aligned now
+- what was deferred or intentionally not copied
+- files changed
+- verification evidence
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..6f8068948
--- /dev/null
+++ b/.trellis/spec/guides/index.md
@@ -0,0 +1,143 @@
+# 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 |
+|-------|---------|-------------|
+| [Architecture Posture Guide](./architecture-posture-guide.md) | Keep architecture choices biased toward high-value long-term boundaries instead of smallest-diff compatibility patches | When refactors, runtime foundations, or contract changes present a "clean structure vs minimal patch" choice |
+| [CC Alignment Guide](./cc-alignment-guide.md) | Keep cc-haha alignment source-backed and effect-driven | When a feature should align with Claude Code / cc-haha behavior |
+| [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 |
+| [Interview-Driven Spec Expansion Guide](./interview-driven-spec-expansion-guide.md) | Fill Trellis specs through focused maintainer interviews | When missing project knowledge depends on maintainer decisions |
+| [Mainline Scope Guide](./mainline-scope-guide.md) | Keep product work focused on the real implementation target | When tutorial/reference assets might distract from `coding-deepgent` |
+| [Planning Targets Guide](./planning-targets-guide.md) | Force feature-family plans to state acceptance targets, current planned features, and future planned extensions before implementation | When defining a new feature family or expanding an existing one |
+| [Staged Execution Guide](./staged-execution-guide.md) | Run multi-stage work with explicit checkpoints and bounded validation | When one task family should proceed across sub-stages without drift |
+| [Trellis Doc Map Guide](./trellis-doc-map-guide.md) | Explain high-value Trellis document roles, reading order, and update targets | When you need to understand or extend the `.trellis/` document system |
+
+---
+
+## 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 Run CC Alignment
+
+- [ ] The task should align with `cc-haha` or Claude Code behavior
+- [ ] A feature name or shape looks similar, but the local effect is not yet explicit
+- [ ] You need to decide what to align, defer, or intentionally not copy
+
+→ Read [CC Alignment Guide](./cc-alignment-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)
+
+### When To Apply Architecture Posture
+
+- [ ] A cleaner long-term structure conflicts with the smallest patch
+- [ ] A refactor would be simpler if old local compatibility were ignored
+- [ ] You are deciding whether to replace an old abstraction instead of layering on top
+- [ ] A task sequence choice should be driven by architectural leverage, not easiest diff
+
+→ Read [Architecture Posture Guide](./architecture-posture-guide.md)
+
+### When to Check Mainline Scope
+
+- [ ] The repo has both product code and tutorial/reference assets
+- [ ] The request mentions docs, skills, tests, or web content that may not be product-critical
+- [ ] You're unsure whether parity with tutorial material is actually required
+
+→ Read [Mainline Scope Guide](./mainline-scope-guide.md)
+
+### When To Use Staged Execution
+
+- [ ] The work spans multiple sub-stages or checkpoints
+- [ ] You want automatic progression only after an explicit checkpoint verdict
+- [ ] The task needs `lean` vs `deep` validation-budget control
+
+→ Read [Staged Execution Guide](./staged-execution-guide.md)
+
+### When To Lock Planning Targets
+
+- [ ] You are defining a non-trivial feature family before implementation
+- [ ] You want one integrated implementation pass after planning
+- [ ] You need to separate what must ship now from what is intentionally deferred
+
+→ Read [Planning Targets Guide](./planning-targets-guide.md)
+
+### When To Navigate Trellis Docs
+
+- [ ] You are unsure which Trellis document owns a rule or decision
+- [ ] You need the recommended reading order for `coding-deepgent`
+- [ ] You are about to interview the user to fill missing Trellis docs
+
+→ Read [Trellis Doc Map Guide](./trellis-doc-map-guide.md)
+
+### When To Interview For Missing Specs
+
+- [ ] Existing code/docs do not answer a project convention question
+- [ ] The answer depends on maintainer preference or product direction
+- [ ] You know which Trellis document should receive the answer
+
+→ Read [Interview-Driven Spec Expansion Guide](./interview-driven-spec-expansion-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/spec/guides/interview-driven-spec-expansion-guide.md b/.trellis/spec/guides/interview-driven-spec-expansion-guide.md
new file mode 100644
index 000000000..02b97616f
--- /dev/null
+++ b/.trellis/spec/guides/interview-driven-spec-expansion-guide.md
@@ -0,0 +1,220 @@
+# Interview-Driven Spec Expansion Guide
+
+> **Purpose**: Help AI agents fill Trellis docs through focused interviews without creating duplicate or unfocused documentation.
+
+---
+
+## Scope
+
+Use this guide when Trellis docs need more real project knowledge, but the
+missing facts depend on maintainer judgment, project preference, or tacit team
+conventions.
+
+This guide is for `coding-deepgent` mainline documentation, not tutorial or
+reference-layer cleanup.
+
+---
+
+## Core Principle
+
+Interviewing is not a chat transcript.
+
+Each answer should land in the narrowest Trellis document that owns the rule,
+contract, decision, or checklist.
+
+Use [Trellis Doc Map Guide](./trellis-doc-map-guide.md) before interviewing so
+the destination is clear.
+
+---
+
+## When To Interview
+
+Interview when the missing information is:
+
+- a real project preference that cannot be derived from code
+- a rule the maintainer wants future agents to follow
+- a decision boundary between multiple valid approaches
+- a review expectation not yet captured in specs
+- a recurring ambiguity that causes repeated explanations
+
+Do not interview when the answer can be derived by reading:
+
+- current code
+- existing Trellis docs
+- task PRDs
+- tests
+- official dependency documentation
+
+Derive first, then ask only the remaining high-value question.
+
+---
+
+## Interview Workflow
+
+### 1. Select One Topic
+
+Pick one narrow topic, for example:
+
+- module ownership
+- testing expectations
+- when to update a roadmap vs a spec
+- accepted `cc-haha` alignment boundary
+- how strict a LangChain schema should be
+
+Avoid broad prompts like:
+
+```text
+Tell me all project rules.
+```
+
+### 2. Identify The Target Document
+
+Before asking, decide where the answer will go:
+
+| Answer type | Target |
+|---|---|
+| work process | `.trellis/workflow.md` |
+| current mainline status | `.trellis/project-handoff.md` |
+| roadmap / product direction | `.trellis/plans/*.md` |
+| implementation rule | `.trellis/spec/backend/*.md` |
+| thinking trigger | `.trellis/spec/guides/*.md` |
+| completed-session record | `.trellis/workspace/<developer>/journal-N.md` via `record-session` |
+
+If no target is clear, create a short proposal first instead of asking a broad
+question.
+
+Plans vs specs shortcut:
+
+- use `plans/` for goals, roadmap, sequencing, and strategic tradeoffs
+- use `spec/` for implementation contracts, boundaries, schemas, and tests
+- if a plan decision becomes mandatory for implementation, extract it into the owning spec
+
+### 3. Ask One Question
+
+Ask exactly one high-value question at a time.
+
+Good question shape:
+
+```text
+For <specific topic>, should future agents follow A or B?
+
+1. A - <tradeoff>
+2. B - <tradeoff>
+3. Other - describe your preference
+```
+
+### 4. Update The Owning Document Immediately
+
+After the answer:
+
+- move the decision into the target Trellis doc
+- add an example or anti-pattern if useful
+- update indexes only if a new high-value doc or section was added
+- do not leave the decision only in the conversation
+
+### 5. Record The Interview Trail In The Active PRD
+
+The active task PRD should record:
+
+- question asked
+- answer summary
+- target document updated
+- acceptance criteria changed, if any
+
+This makes the interview auditable without turning the target spec into a chat
+log.
+
+Use workspace journals only after the work is completed, validated, committed,
+and recorded via `record-session`. Do not put active interview decisions only in
+the journal.
+
+---
+
+## Question Gate
+
+Before asking, check:
+
+- Can I derive this from code/tests/docs?
+- Is this a real preference or blocking decision?
+- Do I know which Trellis doc will receive the answer?
+- Can I ask it as one concrete question?
+
+If any answer is "no", inspect more or narrow the topic.
+
+---
+
+## Good Interview Topics For This Repo
+
+High-value topics:
+
+- `coding-deepgent` module ownership boundaries
+- LangChain/LangGraph abstraction tolerance
+- when `cc-haha` behavior should be `align`, `partial`, `defer`, or `do-not-copy`
+- required verification level for staged work
+- when docs belong in `plans/` vs `spec/backend/`
+- what should be recorded in `project-handoff.md` vs session journals
+
+Low-value topics:
+
+- asking for content already visible in files
+- asking the user to enumerate code structure without inspection
+- trying to fill every placeholder spec at once
+- asking broad philosophical questions without a write target
+
+---
+
+## Output Format For An Interview Round
+
+Use this compact structure in the active PRD:
+
+```md
+## Interview Note: <topic>
+
+Question:
+- <exact question or summary>
+
+Answer:
+- <maintainer decision>
+
+Target doc:
+- `<path>`
+
+Change made:
+- <section updated / rule added>
+```
+
+---
+
+## MVP Interview Loop
+
+For the first Trellis expansion pass, use this sequence:
+
+1. Build the current doc map.
+2. Identify top 3 gaps.
+3. Pick the highest-value gap.
+4. Ask one question.
+5. Update the owning doc.
+6. Re-check whether the next gap is still valid.
+
+Do not run an open-ended interview marathon.
+
+---
+
+## Stop Conditions
+
+Stop interviewing when:
+
+- the next question is broad or low-confidence
+- the target document is unclear
+- the user gives a product decision that should become a separate PRD
+- updating the target doc would conflict with existing Trellis guidance
+- the interview has already produced enough changes for one reviewable slice
+
+---
+
+## Maintenance Rule
+
+This guide owns the interview process.
+
+It does not own the resulting project rules. Those must be written into the
+specific Trellis docs that govern the topic.
diff --git a/.trellis/spec/guides/mainline-scope-guide.md b/.trellis/spec/guides/mainline-scope-guide.md
new file mode 100644
index 000000000..03e133e6c
--- /dev/null
+++ b/.trellis/spec/guides/mainline-scope-guide.md
@@ -0,0 +1,91 @@
+# Mainline Scope Guide
+
+> **Purpose**: Keep current work focused on the real product mainline instead of drifting into tutorial parity work.
+
+---
+
+## Current Mainline
+
+The current working mainline is:
+
+```text
+coding-deepgent/
+```
+
+Trellis tasks, plans, code-spec updates, and implementation decisions should
+default to serving `coding-deepgent/`.
+
+---
+
+## Reference-Only Layer
+
+The following areas are reference-only by default unless a task explicitly
+targets them:
+
+- `agents/`
+- `agents_deepagents/`
+- `docs/`
+- `web/`
+- `skills/`
+- tutorial/demo-oriented tests and teaching artifacts
+
+These areas can still be useful for:
+
+- teaching and explanation
+- source mapping and parity research
+- extracting reusable ideas or examples
+
+They are **not** the default implementation target for current product work.
+
+---
+
+## Decision Rule
+
+When a task is ambiguous, decide in this order:
+
+1. Does the task explicitly target tutorial/reference assets?
+   - If yes, work there deliberately.
+2. If not, does the task affect the current product mainline?
+   - If yes, work in `coding-deepgent/` and `.trellis/`.
+3. If tutorial/reference material conflicts with product direction:
+   - treat the tutorial layer as evidence or examples only
+   - prefer `coding-deepgent` product boundaries and Trellis norms
+
+---
+
+## What To Read First
+
+Before implementing in the current mainline, prefer these sources first:
+
+- `AGENTS.md`
+- `.trellis/workflow.md`
+- `.trellis/project-handoff.md`
+- `.trellis/spec/backend/*.md`
+- `.trellis/spec/frontend/*.md`
+- `coding-deepgent/README.md`
+- `coding-deepgent/PROJECT_PROGRESS.md`
+
+Use tutorial/reference docs only after the mainline sources are understood.
+
+---
+
+## Common Mistakes
+
+- treating tutorial chapter parity as the shipping goal
+- spending time fixing `web/`, tutorial `docs/`, or teaching tests that do not
+  strengthen `coding-deepgent`
+- copying tutorial structure into product code without source-backed product
+  justification
+- keeping duplicate norms outside Trellis after the product rule is already
+  captured in `.trellis/`
+
+---
+
+## Practical Consequence For This Repo
+
+For current collaboration:
+
+- Trellis is the canonical coordination and norm layer.
+- `coding-deepgent/` is the canonical product codebase.
+- tutorial/reference assets should only be updated when explicitly requested or
+  when a small change is needed to avoid misleading future work.
diff --git a/.trellis/spec/guides/planning-targets-guide.md b/.trellis/spec/guides/planning-targets-guide.md
new file mode 100644
index 000000000..45050f8f7
--- /dev/null
+++ b/.trellis/spec/guides/planning-targets-guide.md
@@ -0,0 +1,230 @@
+# Planning Targets Guide
+
+> **Purpose**: Force feature-family plans to become concrete before implementation starts, so work can proceed in one integrated pass instead of drifting through repeated vague replanning.
+
+---
+
+## When To Use
+
+Use this guide when:
+
+- a task is bigger than a trivial fix
+- a feature family spans multiple related behaviors
+- the user wants one integrated implementation pass
+- planning has started to drift into abstract discussion
+
+This guide is for:
+
+- planning
+- brainstorming
+- roadmap slicing
+- implementation gating
+
+---
+
+## Core Rule
+
+Before implementation begins for a non-trivial feature family, the plan must
+explicitly contain three buckets:
+
+1. `Acceptance Targets`
+2. `Planned Features`
+3. `Planned Extensions`
+
+If any of these are missing, do not treat the feature family as ready for
+implementation.
+
+---
+
+## Why This Exists
+
+Without these three buckets, planning usually fails in one of three ways:
+
+1. **Vague completion**
+   - people say "memory is better" or "context handling improved"
+   - nobody can tell what counts as done
+
+2. **Scope contamination**
+   - future ideas leak into the current implementation
+   - current work grows until it becomes unsafe
+
+3. **Repeated replanning churn**
+   - each turn redefines the target
+   - the code never gets one coherent integrated pass
+
+This guide exists to stop those failure modes.
+
+---
+
+## The Three Buckets
+
+### 1. Acceptance Targets
+
+These define what must be true for the task to count as complete.
+
+Write them as user-visible or system-visible outcomes, not as implementation
+fragments.
+
+Good examples:
+
+- users can see long-term memory and current-session memory separately in recovery
+- feedback rules can block commit-like actions before they run
+- the system can list and delete saved memory entries
+
+Bad examples:
+
+- added a new model
+- refactored module layout
+- introduced helper functions
+
+Question to ask:
+
+> If this task ends, what concrete behavior should now exist that did not exist before?
+
+### 2. Planned Features
+
+These define what the task will implement now.
+
+This bucket should be concrete and scoped.
+
+Good examples:
+
+- add one project-level rules file entrypoint
+- add long-term memory listing and deletion tools
+- show long-term memory and current-session memory in recovery brief
+
+Bad examples:
+
+- improve memory architecture
+- move toward parity
+- prepare for future work
+
+Question to ask:
+
+> Which concrete capabilities are we actually building in this task?
+
+### 3. Planned Extensions
+
+These define what is intentionally not implemented now, but is already known as
+future work.
+
+This bucket prevents future ideas from contaminating the current implementation
+while still preserving continuity.
+
+Good examples:
+
+- durable memory persistence across restart
+- auto-suggested memory extraction
+- path-scoped rules
+- agent-private memory
+
+Bad examples:
+
+- nothing else
+- TBD
+- maybe future improvements
+
+Question to ask:
+
+> What future capabilities are real, but intentionally deferred from this pass?
+
+---
+
+## Required Planning Shape
+
+Every non-trivial feature-family PRD or planning note should include:
+
+```md
+## Acceptance Targets
+
+- ...
+- ...
+
+## Planned Features
+
+- ...
+- ...
+
+## Planned Extensions
+
+- ...
+- ...
+```
+
+Optional but recommended:
+
+```md
+## Why Now
+
+- ...
+
+## Out of Scope
+
+- ...
+```
+
+---
+
+## Execution Rule
+
+Once the three buckets are explicit and approved:
+
+- prefer one integrated implementation pass for the feature family
+- do not keep reopening the same planning question every turn
+- only split the work when a real blocker, dependency, or validation failure appears
+
+This rule exists to support high-value, strongly coupled feature families that
+should be completed coherently.
+
+---
+
+## Relationship To Staged Execution
+
+This guide decides **what the task is**.
+
+[Staged Execution Guide](./staged-execution-guide.md) decides **how the task
+progresses once the target is already clear**.
+
+Use both when:
+
+- the feature family is non-trivial, and
+- implementation should proceed through checkpoints after planning is locked
+
+---
+
+## Review Gate
+
+Before implementation starts, reviewers or future agents should be able to
+answer all three:
+
+- What must be true when this task is done?
+- What exactly is being built now?
+- What is deliberately deferred?
+
+If not, the task is not ready.
+
+---
+
+## Example
+
+```md
+## Acceptance Targets
+
+- recovery shows long-term memory separately from current-session memory
+- users can inspect and delete saved long-term memory
+- feedback memories can block selected high-value actions
+
+## Planned Features
+
+- add `list_memory`
+- add `delete_memory`
+- add long-term memory snapshot to recovery brief
+
+## Planned Extensions
+
+- durable memory persistence across restart
+- auto-extracted memory suggestions
+- child-agent private memory
+```
+
+This is good enough to implement.
diff --git a/.trellis/spec/guides/staged-execution-guide.md b/.trellis/spec/guides/staged-execution-guide.md
new file mode 100644
index 000000000..815ddda84
--- /dev/null
+++ b/.trellis/spec/guides/staged-execution-guide.md
@@ -0,0 +1,204 @@
+# Staged Execution Guide
+
+> **Purpose**: Run multi-stage `coding-deepgent` work with explicit checkpoints, bounded validation, and safe auto-progression.
+
+---
+
+## When To Use
+
+Use this guide when a task family spans multiple sub-stages and should continue
+only after each stage is explicitly reviewed.
+
+Typical use cases:
+
+- staged feature families
+- roadmap closeout slices
+- checkpointed infrastructure upgrades
+- long-running implementation that should not drift
+
+---
+
+## Modes
+
+Two execution modes are supported:
+
+- `lean` (default)
+- `deep`
+
+### `lean`
+
+- work one sub-stage at a time
+- prefer focused tests
+- avoid broad re-reading of settled source/doc context
+- avoid full-suite validation unless clearly required
+- if checkpoint result is `continue`, immediately start the next sub-stage
+
+### `deep`
+
+- broader re-orientation is allowed
+- broader validation is allowed
+- can fold larger docs/git/PR work into the same run when explicitly justified
+
+If the user did not explicitly opt into a long-running all-in-one pass, default
+to `lean`.
+
+---
+
+## Sub-Stage State Machine
+
+Every staged run should use one explicit sub-stage state:
+
+- `planning`
+- `implementing`
+- `verifying`
+- `checkpoint`
+- `terminal`
+
+If resuming an existing stage family, resume from the current active state
+instead of replaying orientation from zero.
+
+---
+
+## Before Implementation
+
+- A Trellis task exists.
+- A PRD exists.
+- Expected benefit is concrete.
+- Relevant source mapping is recorded when alignment matters.
+- LangChain-native boundary is chosen when applicable.
+- Out-of-scope items are explicit.
+- Focused tests are named.
+
+If the task introduces a genuinely new feature band, expand research. Otherwise,
+reuse recent verified PRD/checkpoint context when safe.
+
+---
+
+## Validation Budget
+
+Default validation rules:
+
+- `lean`
+  - focused tests only
+  - targeted lint/typecheck on changed files
+  - run broader validation only when:
+    - the user asks
+    - the change touches cross-cutting contracts
+    - focused validation exposes ambiguity
+- `deep`
+  - focused plus broader regression as appropriate
+
+Do not treat "more validation" as automatically better. Match validation cost to
+change risk.
+
+Current default for `coding-deepgent`:
+
+- focused validation first
+- broader validation only on cross-layer/contract/runtime risk, ambiguous focused failures, or explicit user request
+
+---
+
+## Checkpoint Gate
+
+At the end of each sub-stage, record:
+
+- implemented behavior
+- tests run and result
+- files changed
+- alignment evidence when relevant
+- architecture evidence when relevant
+- boundary issues discovered
+- whether the next sub-stage still holds
+
+Use internal verdict vocabulary:
+
+- `APPROVE`
+- `ITERATE`
+- `REJECT`
+
+Map to execution decisions:
+
+- `APPROVE` -> `continue`
+- `ITERATE` -> `adjust` or `split`
+- `REJECT` -> `stop`
+
+Execution rule:
+
+- `continue` -> start the next sub-stage immediately
+- `adjust` -> rewrite the next sub-stage plan first
+- `split` -> create a prerequisite task and stop the main run
+- `stop` -> stop and ask the user
+
+Do not stop only to summarize progress if the decision is `continue`.
+
+---
+
+## Checkpoint Template
+
+```md
+## Checkpoint: <sub-stage>
+
+State:
+- planning | implementing | verifying | checkpoint | terminal
+
+Verdict:
+- APPROVE | ITERATE | REJECT
+
+Implemented:
+- ...
+
+Verification:
+- ...
+
+Alignment:
+- source files inspected:
+- aligned:
+- deferred:
+- do-not-copy:
+
+Architecture:
+- primitive used:
+- why no heavier abstraction:
+
+Boundary findings:
+- ...
+
+Decision:
+- continue | adjust | split | stop
+
+Reason:
+- ...
+```
+
+---
+
+## Stop Conditions
+
+Stop and ask the user when:
+
+- the next sub-stage scope is no longer valid
+- tests fail and the fix is not local to the current sub-stage
+- required source mapping is missing for an alignment-critical change
+- the implementation would replace LangChain/LangGraph runtime seams
+- the worktree contains conflicting user changes
+- the next step requires a new product decision
+
+---
+
+## Subagent Rule
+
+If subagents are explicitly authorized:
+
+- give each one a bounded, non-overlapping task
+- keep them off the critical path unless the main agent is blocked
+- final synthesis remains with the main agent
+
+---
+
+## Current Repo Default
+
+For the current `coding-deepgent` mainline:
+
+- use Trellis tasks + PRDs as the stage ledger
+- use this guide instead of the removed `stage-iterate` skill
+- keep checkpoint logic in Trellis docs, not in external skill wrappers
diff --git a/.trellis/spec/guides/trellis-doc-map-guide.md b/.trellis/spec/guides/trellis-doc-map-guide.md
new file mode 100644
index 000000000..5b68d0362
--- /dev/null
+++ b/.trellis/spec/guides/trellis-doc-map-guide.md
@@ -0,0 +1,278 @@
+# Trellis Doc Map Guide
+
+> **Purpose**: Explain the high-value `.trellis/` documents for the current `coding-deepgent` mainline: what each layer owns, what to read first, and where new knowledge should be written.
+
+---
+
+## Scope
+
+This guide maps only the high-value Trellis documents used in current
+`coding-deepgent` work.
+
+It intentionally does not document every internal script, config file, archived
+task, or implementation detail under `.trellis/`.
+
+Use this as:
+
+- a maintainer map for Trellis document responsibilities
+- an AI-agent map for reading order and update targets
+
+---
+
+## Core Principle
+
+Trellis should not become one giant handbook.
+
+Use this structure instead:
+
+- `workflow.md` explains **how work moves**
+- `project-handoff.md` explains **where the current mainline stands**
+- `plans/` explains **long-lived product direction**
+- `spec/backend/` explains **how to implement safely**
+- `spec/guides/` explains **how to think before changing things**
+- `workspace/` records **what happened after work is done**
+
+When adding new knowledge, update the narrowest document that owns it.
+
+---
+
+## High-Value Document Layers
+
+| Layer | Main paths | Owns | Does not own |
+|---|---|---|---|
+| Workflow | `.trellis/workflow.md` | session flow, task lifecycle, staged execution protocol, finish/record expectations | product architecture details |
+| Mainline handoff | `.trellis/project-handoff.md` | current `coding-deepgent` goal, latest verified state, minimal resume procedure | detailed implementation contracts |
+| Long-lived plans | `.trellis/plans/index.md`, `.trellis/plans/*.md` | roadmaps, reconstructed master plans, target designs, canonical dashboards | day-to-day coding conventions |
+| Backend specs | `.trellis/spec/backend/index.md`, `.trellis/spec/backend/*.md` | implementation contracts, module boundaries, quality rules, LangChain-native rules | broad brainstorming notes |
+| Thinking guides | `.trellis/spec/guides/index.md`, `.trellis/spec/guides/*.md` | pre-implementation thinking, source alignment, staged work, scope checks | exact code/API contracts |
+| Workspace records | `.trellis/workspace/index.md`, `.trellis/workspace/<developer>/journal-N.md` | session history, completed work summaries, commit/session records | future requirements or canonical rules |
+
+---
+
+## Reading Order
+
+### For Maintainers
+
+Use this path when you want to understand or reshape the project direction:
+
+1. `AGENTS.md`
+2. `.trellis/workflow.md`
+3. `.trellis/project-handoff.md`
+4. `.trellis/plans/index.md`
+5. `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+6. `.trellis/spec/backend/index.md`
+7. `.trellis/spec/guides/index.md`
+
+Then open only the specific topic docs needed for the current decision.
+
+### For AI Agents
+
+Use this path before implementation:
+
+1. `AGENTS.md`
+2. `.trellis/workflow.md`
+3. `python3 ./.trellis/scripts/get_context.py`
+4. `.trellis/project-handoff.md` if the task is about current `coding-deepgent` mainline state
+5. `.trellis/spec/backend/index.md` for backend/product work
+6. `.trellis/spec/guides/index.md` for thinking triggers
+7. active task `prd.md` and injected `implement.jsonl` / `check.jsonl`
+
+Do not read broad `.trellis/tasks/` or `.trellis/plans/` trees unless a real
+ambiguity remains.
+
+---
+
+## Where To Write New Knowledge
+
+| New knowledge type | Write it here | Example |
+|---|---|---|
+| Work process changed | `.trellis/workflow.md` | staged validation budget changed |
+| Current mainline status changed | `.trellis/project-handoff.md` | latest verified stage family updated |
+| Ordinary completed session | `.trellis/workspace/<developer>/journal-N.md` via `record-session` | daily progress or minor implementation summary |
+| Long-term roadmap changed | `.trellis/plans/*.md` | H-row status or MVP boundary changed |
+| Module ownership or layout changed | `.trellis/spec/backend/directory-structure.md` | new domain package added |
+| LangChain/LangGraph rule changed | `.trellis/spec/backend/langchain-native-guidelines.md` | tool schema rule changed |
+| Review/testing rule changed | `.trellis/spec/backend/quality-guidelines.md` | new forbidden pattern |
+| Runtime/session/compact contract changed | `.trellis/spec/backend/runtime-context-compaction-contracts.md` | new compact record invariant |
+| Task/plan/verifier contract changed | `.trellis/spec/backend/task-workflow-contracts.md` | new verifier evidence rule |
+| Thinking checklist changed | `.trellis/spec/guides/*.md` | new scope or alignment trigger |
+
+---
+
+## Plans Vs Specs Boundary
+
+Use `.trellis/plans/` for direction.
+
+Plans own:
+
+- product goals
+- roadmap rows
+- stage sequencing
+- strategic tradeoffs
+- deferred / do-not-copy decisions
+- current or future milestone boundaries
+
+Use `.trellis/spec/` for execution.
+
+Specs own:
+
+- implementation contracts
+- schemas and signatures
+- module boundaries
+- validation/error matrices
+- testing requirements
+- concrete do/don't rules for future code changes
+
+If a plan decision becomes something every implementation must obey, extract
+that rule into the owning spec. Do not force future agents to read broad plans
+to discover executable constraints.
+
+---
+
+## Task PRD Vs Workspace Journal Boundary
+
+Use the active task PRD while work is in progress.
+
+Task PRDs own:
+
+- requirements and acceptance criteria
+- interview notes
+- scope decisions
+- implementation checkpoints
+- verification evidence for the task
+- unresolved questions and follow-up decisions
+
+Use workspace journals after work is completed, validated, and committed.
+
+Workspace journals own:
+
+- completed session summaries
+- commit lists
+- final testing notes
+- next-step handoff after a completed session
+
+Do not require future agents to search journals to recover active task
+requirements. Keep active decisions in the active task PRD until the work is
+done.
+
+---
+
+## Task Archive Boundary
+
+Keep active tasks focused on work still being decided, implemented, or verified.
+
+Archive a task when:
+
+- acceptance criteria are met
+- verification is complete for the task's risk level
+- the work has been committed, or the task is docs/planning-only and explicitly
+  complete
+
+Do not keep tasks open just because task metadata still says `planning` or
+`in_progress`.
+
+Workspace journals record completed sessions; archived tasks preserve the
+task-level requirements and decisions.
+
+---
+
+## When Specs Must Be Updated
+
+Update `.trellis/spec/*` when a change creates or changes an executable
+contract future agents must obey.
+
+Required spec-update triggers:
+
+- tool schema, command, or public API shape changes
+- runtime state fields or payload formats change
+- module ownership or boundary changes
+- validation or error behavior changes
+- testing requirements or verification matrix changes
+- cross-layer data transformation changes
+- a repeated mistake becomes a rule or anti-pattern
+
+Do not update specs for ordinary implementation detail that does not affect
+future implementation or review behavior.
+
+When unsure, write the decision in the active task PRD first, then extract it
+to the owning spec only if it becomes reusable.
+
+---
+
+## CC Alignment Record Placement
+
+Record `cc-haha` alignment in this order:
+
+1. Active task PRD:
+   - expected effect
+   - source files inspected
+   - alignment matrix
+   - `align / partial / defer / do-not-copy` decisions
+2. `.trellis/plans/`:
+   - only stable roadmap/product-direction outcomes
+3. `.trellis/spec/`:
+   - only executable implementation constraints future agents must obey
+
+Do not let exploratory source notes become canonical specs by default.
+
+---
+
+## Summary Docs Vs Atomic Specs
+
+Use summary/map docs for:
+
+- orientation
+- reading order
+- responsibility boundaries
+- "where should this go?" decisions
+
+Use atomic specs for:
+
+- concrete implementation rules
+- signatures and contracts
+- validation/error matrices
+- examples and anti-patterns
+
+Do not duplicate detailed rules from atomic specs into map docs. Link or point
+to the owning spec instead.
+
+---
+
+## Interview-Driven Expansion
+
+This map is the entrypoint for later interview-based Trellis expansion.
+
+When interviewing the user to fill docs:
+
+1. Identify the missing knowledge category.
+2. Choose the owning Trellis document from the table above.
+3. Ask one targeted question.
+4. Write the answer into the owning document, not into this map.
+5. Update this map only if the document structure or routing rule changes.
+
+Good interview targets:
+
+- unclear module ownership
+- recurring review concerns
+- unstated testing expectations
+- accepted `cc-haha` alignment boundaries
+- when to update specs vs plans vs workspace records
+
+---
+
+## Current Mainline Bias
+
+This map serves `coding-deepgent`.
+
+Tutorial/reference assets such as `agents/`, `agents_deepagents/`, `docs/`, and
+`web/` are not default implementation targets. Use
+`mainline-scope-guide.md` when that boundary is unclear.
+
+---
+
+## Maintenance Rules
+
+- Keep this guide short enough to scan.
+- Add new Trellis documents to the map only when they become high-value entrypoints.
+- Prefer updating the owning atomic doc over expanding this guide.
+- If two docs appear to own the same rule, clarify ownership here and remove duplication from one side.
diff --git a/.trellis/tasks/archive/2026-04/00-bootstrap-guidelines/prd.md b/.trellis/tasks/archive/2026-04/00-bootstrap-guidelines/prd.md
new file mode 100644
index 000000000..7004151ce
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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
+
+- [x] Guidelines filled for your project type
+- [x] At least 2-3 real code examples in each guideline
+- [x] 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/archive/2026-04/00-bootstrap-guidelines/task.json b/.trellis/tasks/archive/2026-04/00-bootstrap-guidelines/task.json
new file mode 100644
index 000000000..ec673bb5f
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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": "completed",
+  "dev_type": "docs",
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-13",
+  "completedAt": "2026-04-15",
+  "commit": null,
+  "subtasks": [
+    {
+      "name": "Fill backend guidelines",
+      "status": "completed"
+    },
+    {
+      "name": "Add code examples",
+      "status": "completed"
+    }
+  ],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [
+    ".trellis/spec/backend/"
+  ],
+  "notes": "Completed through the Trellis backend spec bootstrap now living under .trellis/spec/backend/ with concrete examples and anti-pattern guidance. Reconfirmed on 2026-04-17 during L1-a ledger cleanup: backend spec docs are Active and the duplicate active bootstrap task was removed from the active ledger.",
+  "meta": {}
+}
diff --git a/.trellis/tasks/archive/2026-04/04-14-assess-cc-highlight-infrastructure-readiness/prd.md b/.trellis/tasks/archive/2026-04/04-14-assess-cc-highlight-infrastructure-readiness/prd.md
new file mode 100644
index 000000000..9d4159dc1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-14-assess-cc-highlight-infrastructure-readiness/prd.md
@@ -0,0 +1,118 @@
+# 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 `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`.
+* The source-backed H01-H10 target design exists at `.trellis/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.
+* [x] 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:
+  - `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+  - `.trellis/plans/coding-deepgent-h01-h10-target-design.md`
+* Completion note:
+  - The Stage 12 recommendation was later confirmed by subsequent planning and implementation closeout across archived Stage 12A-12D task records and the current handoff/roadmap lineage.
+* 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/archive/2026-04/04-14-assess-cc-highlight-infrastructure-readiness/task.json b/.trellis/tasks/archive/2026-04/04-14-assess-cc-highlight-infrastructure-readiness/task.json
new file mode 100644
index 000000000..190b4c630
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-14-assess-cc-highlight-infrastructure-readiness/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "assess-cc-highlight-infrastructure-readiness",
+  "name": "assess-cc-highlight-infrastructure-readiness",
+  "title": "brainstorm: assess infrastructure readiness for cc highlights",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": "2026-04-15",
+  "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": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-14-redefine-coding-deepgent-final-goal/prd.md b/.trellis/tasks/archive/2026-04/04-14-redefine-coding-deepgent-final-goal/prd.md
new file mode 100644
index 000000000..005b384fa
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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 Trellis LangChain-native implementation guidelines.
+* 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)
+
+* [x] The final goal states what must align with cc-haha and what must not be copied.
+* [x] The final goal states which LangChain/LangGraph primitives are the preferred implementation boundary.
+* [x] The final goal states the expected project shape: product-grade, modular, maintainable, non-demo.
+* [x] The final goal defines stage progression logic or target completion criteria.
+* [x] The final goal clarifies the boundary between product parity, teaching material, and deferred infrastructure.
+* [x] The final goal names the core systems that must eventually reach cc-haha essence alignment.
+* [x] Each core system gets a written “essence definition” before implementation planning resumes.
+* [x] Each planned upgrade includes an explicit expected-benefit section and a why-now judgment.
+* [x] Each planned upgrade includes an explicit function summary before implementation begins.
+* [x] The final goal explicitly treats cross-session memory as a required end-state capability.
+* [x] 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`
+* Recovered planning docs:
+  - `.trellis/plans/prd-coding-deepgent-runtime-foundation.md`
+  - `.trellis/plans/test-spec-coding-deepgent-runtime-foundation.md`
+  - `.trellis/plans/master-plan-coding-deepgent-reconstructed.md`
+  - `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+  - `.trellis/plans/coding-deepgent-h01-h10-target-design.md`
+  - `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.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 `.trellis/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/archive/2026-04/04-14-redefine-coding-deepgent-final-goal/task.json b/.trellis/tasks/archive/2026-04/04-14-redefine-coding-deepgent-final-goal/task.json
new file mode 100644
index 000000000..d2460b95f
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-14-redefine-coding-deepgent-final-goal/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "redefine-coding-deepgent-final-goal",
+  "name": "redefine-coding-deepgent-final-goal",
+  "title": "brainstorm: redefine coding-deepgent final goal",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": "2026-04-15",
+  "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": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-14-stage-12a-context-payload-foundation/check.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-12a-context-payload-foundation/check.jsonl
new file mode 100644
index 000000000..028262ce6
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-12a-context-payload-foundation/debug.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-12a-context-payload-foundation/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-12a-context-payload-foundation/implement.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-12a-context-payload-foundation/implement.jsonl
new file mode 100644
index 000000000..ad929222a
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-12a-context-payload-foundation/prd.md b/.trellis/tasks/archive/2026-04/04-14-stage-12a-context-payload-foundation/prd.md
new file mode 100644
index 000000000..7d5cc5c73
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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.
+* Trellis LangChain-native implementation guidance 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/archive/2026-04/04-14-stage-12a-context-payload-foundation/task.json b/.trellis/tasks/archive/2026-04/04-14-stage-12a-context-payload-foundation/task.json
new file mode 100644
index 000000000..4a0d499d1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": "2026-04-15",
+  "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": "Reconciled on 2026-04-15: checkpoint evidence in the task PRD and canonical handoff/roadmap docs both show this historical stage is complete, so the task metadata was normalized for archive cleanup.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-14-stage-12b-message-projection-and-tool-result-invariants/check.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-12b-message-projection-and-tool-result-invariants/check.jsonl
new file mode 100644
index 000000000..15f1d45d0
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-12b-message-projection-and-tool-result-invariants/debug.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-12b-message-projection-and-tool-result-invariants/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-12b-message-projection-and-tool-result-invariants/implement.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-12b-message-projection-and-tool-result-invariants/implement.jsonl
new file mode 100644
index 000000000..49e0b0117
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-12b-message-projection-and-tool-result-invariants/prd.md b/.trellis/tasks/archive/2026-04/04-14-stage-12b-message-projection-and-tool-result-invariants/prd.md
new file mode 100644
index 000000000..0636fc9e5
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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:
+  - `.trellis/plans/coding-deepgent-h01-h10-target-design.md`
+  - `.trellis/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/archive/2026-04/04-14-stage-12b-message-projection-and-tool-result-invariants/task.json b/.trellis/tasks/archive/2026-04/04-14-stage-12b-message-projection-and-tool-result-invariants/task.json
new file mode 100644
index 000000000..e18e74bf8
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": "2026-04-15",
+  "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": "Reconciled on 2026-04-15: checkpoint evidence in the task PRD and canonical handoff/roadmap docs both show this historical stage is complete, so the task metadata was normalized for archive cleanup.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-14-stage-12c-recovery-brief-and-session-resume-audit/check.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-12c-recovery-brief-and-session-resume-audit/check.jsonl
new file mode 100644
index 000000000..aed139cb9
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-12c-recovery-brief-and-session-resume-audit/debug.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-12c-recovery-brief-and-session-resume-audit/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-12c-recovery-brief-and-session-resume-audit/implement.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-12c-recovery-brief-and-session-resume-audit/implement.jsonl
new file mode 100644
index 000000000..f165afb4f
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-12c-recovery-brief-and-session-resume-audit/prd.md b/.trellis/tasks/archive/2026-04/04-14-stage-12c-recovery-brief-and-session-resume-audit/prd.md
new file mode 100644
index 000000000..095234d48
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-12c-recovery-brief-and-session-resume-audit/task.json b/.trellis/tasks/archive/2026-04/04-14-stage-12c-recovery-brief-and-session-resume-audit/task.json
new file mode 100644
index 000000000..21813c139
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": "2026-04-15",
+  "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": "Reconciled on 2026-04-15: checkpoint evidence in the task PRD and canonical handoff/roadmap docs both show this historical stage is complete, so the task metadata was normalized for archive cleanup.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-14-stage-12d-memory-quality-policy/check.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-12d-memory-quality-policy/check.jsonl
new file mode 100644
index 000000000..46b4284d8
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-12d-memory-quality-policy/debug.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-12d-memory-quality-policy/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-12d-memory-quality-policy/implement.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-12d-memory-quality-policy/implement.jsonl
new file mode 100644
index 000000000..9437779a5
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-12d-memory-quality-policy/prd.md b/.trellis/tasks/archive/2026-04/04-14-stage-12d-memory-quality-policy/prd.md
new file mode 100644
index 000000000..75cc4d98e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-12d-memory-quality-policy/task.json b/.trellis/tasks/archive/2026-04/04-14-stage-12d-memory-quality-policy/task.json
new file mode 100644
index 000000000..080f28d06
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": "2026-04-15",
+  "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": "Reconciled on 2026-04-15: checkpoint evidence in the task PRD and canonical handoff/roadmap docs both show this historical stage is complete, so the task metadata was normalized for archive cleanup.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/check.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/check.jsonl
new file mode 100644
index 000000000..e2fb48dc1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/debug.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/implement.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/implement.jsonl
new file mode 100644
index 000000000..fec80b194
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/prd.md b/.trellis/tasks/archive/2026-04/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/prd.md
new file mode 100644
index 000000000..f6c88278c
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/task.json b/.trellis/tasks/archive/2026-04/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/task.json
new file mode 100644
index 000000000..0a899ea7a
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": "2026-04-15",
+  "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": "Reconciled on 2026-04-15: checkpoint evidence in the task PRD and canonical handoff/roadmap docs both show this historical stage is complete, so the task metadata was normalized for archive cleanup.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-14-stage-13b-manual-compact-entry-point/check.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-13b-manual-compact-entry-point/check.jsonl
new file mode 100644
index 000000000..fdb73e361
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-13b-manual-compact-entry-point/debug.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-13b-manual-compact-entry-point/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-13b-manual-compact-entry-point/implement.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-13b-manual-compact-entry-point/implement.jsonl
new file mode 100644
index 000000000..9ec66270a
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-13b-manual-compact-entry-point/prd.md b/.trellis/tasks/archive/2026-04/04-14-stage-13b-manual-compact-entry-point/prd.md
new file mode 100644
index 000000000..96f17d122
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-13b-manual-compact-entry-point/task.json b/.trellis/tasks/archive/2026-04/04-14-stage-13b-manual-compact-entry-point/task.json
new file mode 100644
index 000000000..51349be2d
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": "2026-04-15",
+  "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": "Reconciled on 2026-04-15: checkpoint evidence in the task PRD and canonical handoff/roadmap docs both show this historical stage is complete, so the task metadata was normalized for archive cleanup.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-14-stage-13c-compact-summary-generation-seam/check.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-13c-compact-summary-generation-seam/check.jsonl
new file mode 100644
index 000000000..e76d52a08
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-13c-compact-summary-generation-seam/debug.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-13c-compact-summary-generation-seam/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-13c-compact-summary-generation-seam/implement.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-13c-compact-summary-generation-seam/implement.jsonl
new file mode 100644
index 000000000..8213181f0
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-13c-compact-summary-generation-seam/prd.md b/.trellis/tasks/archive/2026-04/04-14-stage-13c-compact-summary-generation-seam/prd.md
new file mode 100644
index 000000000..d2da07a45
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-13c-compact-summary-generation-seam/task.json b/.trellis/tasks/archive/2026-04/04-14-stage-13c-compact-summary-generation-seam/task.json
new file mode 100644
index 000000000..97dce4eb1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": "2026-04-15",
+  "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": "Reconciled on 2026-04-15: checkpoint evidence in the task PRD and canonical handoff/roadmap docs both show this historical stage is complete, so the task metadata was normalized for archive cleanup.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-14-stage-14a-explicit-generated-summary-cli-wiring/check.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-14a-explicit-generated-summary-cli-wiring/check.jsonl
new file mode 100644
index 000000000..e9f2c41fb
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-14a-explicit-generated-summary-cli-wiring/debug.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-14a-explicit-generated-summary-cli-wiring/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-14a-explicit-generated-summary-cli-wiring/implement.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-14a-explicit-generated-summary-cli-wiring/implement.jsonl
new file mode 100644
index 000000000..ca3bb53fa
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-14a-explicit-generated-summary-cli-wiring/prd.md b/.trellis/tasks/archive/2026-04/04-14-stage-14a-explicit-generated-summary-cli-wiring/prd.md
new file mode 100644
index 000000000..3d894f6fa
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-14a-explicit-generated-summary-cli-wiring/task.json b/.trellis/tasks/archive/2026-04/04-14-stage-14a-explicit-generated-summary-cli-wiring/task.json
new file mode 100644
index 000000000..a2ad2446a
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "completedAt": "2026-04-15",
+  "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": "Reconciled on 2026-04-15: checkpoint evidence in the task PRD and canonical handoff/roadmap docs both show this historical stage is complete, so the task metadata was normalized for archive cleanup.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-14-stage-15a-non-destructive-compact-transcript-records/check.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-15a-non-destructive-compact-transcript-records/check.jsonl
new file mode 100644
index 000000000..8a395c3ad
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-15a-non-destructive-compact-transcript-records/debug.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-15a-non-destructive-compact-transcript-records/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-15a-non-destructive-compact-transcript-records/implement.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-15a-non-destructive-compact-transcript-records/implement.jsonl
new file mode 100644
index 000000000..0ae783b3c
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-15a-non-destructive-compact-transcript-records/prd.md b/.trellis/tasks/archive/2026-04/04-14-stage-15a-non-destructive-compact-transcript-records/prd.md
new file mode 100644
index 000000000..1b8be1ba6
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-15a-non-destructive-compact-transcript-records/task.json b/.trellis/tasks/archive/2026-04/04-14-stage-15a-non-destructive-compact-transcript-records/task.json
new file mode 100644
index 000000000..b9677504c
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "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": "Reconciled on 2026-04-15: checkpoint evidence in the task PRD and canonical handoff/roadmap docs both show this historical stage is complete, so the task metadata was normalized for archive cleanup.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-14-stage-15b-compact-record-recovery-display/check.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-15b-compact-record-recovery-display/check.jsonl
new file mode 100644
index 000000000..1d5ce37d3
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-15b-compact-record-recovery-display/debug.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-15b-compact-record-recovery-display/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-15b-compact-record-recovery-display/implement.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-15b-compact-record-recovery-display/implement.jsonl
new file mode 100644
index 000000000..a1e9d5c3b
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-15b-compact-record-recovery-display/prd.md b/.trellis/tasks/archive/2026-04/04-14-stage-15b-compact-record-recovery-display/prd.md
new file mode 100644
index 000000000..62bac73f6
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-15b-compact-record-recovery-display/task.json b/.trellis/tasks/archive/2026-04/04-14-stage-15b-compact-record-recovery-display/task.json
new file mode 100644
index 000000000..264453e53
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "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": "Reconciled on 2026-04-15: checkpoint evidence in the task PRD and canonical handoff/roadmap docs both show this historical stage is complete, so the task metadata was normalized for archive cleanup.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-14-stage-15c-compacted-continuation-selection/check.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-15c-compacted-continuation-selection/check.jsonl
new file mode 100644
index 000000000..3bd087b95
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-15c-compacted-continuation-selection/debug.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-15c-compacted-continuation-selection/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-15c-compacted-continuation-selection/implement.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-15c-compacted-continuation-selection/implement.jsonl
new file mode 100644
index 000000000..9bd016608
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-15c-compacted-continuation-selection/prd.md b/.trellis/tasks/archive/2026-04/04-14-stage-15c-compacted-continuation-selection/prd.md
new file mode 100644
index 000000000..d869e37be
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-15c-compacted-continuation-selection/task.json b/.trellis/tasks/archive/2026-04/04-14-stage-15c-compacted-continuation-selection/task.json
new file mode 100644
index 000000000..f1828ad01
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "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": "Reconciled on 2026-04-15: checkpoint evidence in the task PRD and canonical handoff/roadmap docs both show this historical stage is complete, so the task metadata was normalized for archive cleanup.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-14-stage-16-compact-transcript-pruning-semantics/prd.md b/.trellis/tasks/archive/2026-04/04-14-stage-16-compact-transcript-pruning-semantics/prd.md
new file mode 100644
index 000000000..1a58a2666
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-16-compact-transcript-pruning-semantics/task.json b/.trellis/tasks/archive/2026-04/04-14-stage-16-compact-transcript-pruning-semantics/task.json
new file mode 100644
index 000000000..39089b423
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "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": "Reconciled on 2026-04-15: this planning PRD was superseded by the implemented Stage 16A/16B/16C tasks and the canonical Stage 16 completion recorded in handoff/completion-map docs.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-14-stage-16a-load-time-compacted-history-view/check.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-16a-load-time-compacted-history-view/check.jsonl
new file mode 100644
index 000000000..680391d35
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-16a-load-time-compacted-history-view/debug.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-16a-load-time-compacted-history-view/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-16a-load-time-compacted-history-view/implement.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-16a-load-time-compacted-history-view/implement.jsonl
new file mode 100644
index 000000000..3b46fd8ca
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-16a-load-time-compacted-history-view/prd.md b/.trellis/tasks/archive/2026-04/04-14-stage-16a-load-time-compacted-history-view/prd.md
new file mode 100644
index 000000000..798470d0d
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-16a-load-time-compacted-history-view/task.json b/.trellis/tasks/archive/2026-04/04-14-stage-16a-load-time-compacted-history-view/task.json
new file mode 100644
index 000000000..025c4c813
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "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": "Reconciled on 2026-04-15: checkpoint evidence in the task PRD and canonical handoff/roadmap docs both show this historical stage is complete, so the task metadata was normalized for archive cleanup.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-14-stage-16b-latest-valid-compact-view-selection/check.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-16b-latest-valid-compact-view-selection/check.jsonl
new file mode 100644
index 000000000..5a9dca09e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-16b-latest-valid-compact-view-selection/debug.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-16b-latest-valid-compact-view-selection/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-16b-latest-valid-compact-view-selection/implement.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-16b-latest-valid-compact-view-selection/implement.jsonl
new file mode 100644
index 000000000..741810fb9
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-16b-latest-valid-compact-view-selection/prd.md b/.trellis/tasks/archive/2026-04/04-14-stage-16b-latest-valid-compact-view-selection/prd.md
new file mode 100644
index 000000000..c9e25d8ea
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-16b-latest-valid-compact-view-selection/task.json b/.trellis/tasks/archive/2026-04/04-14-stage-16b-latest-valid-compact-view-selection/task.json
new file mode 100644
index 000000000..3a8aff235
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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-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": "Reconciled on 2026-04-15: checkpoint evidence in the task PRD and canonical handoff/roadmap docs both show this historical stage is complete, so the task metadata was normalized for archive cleanup.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-14-stage-16b-virtual-pruning-compact-selection-hardening/task.json b/.trellis/tasks/archive/2026-04/04-14-stage-16b-virtual-pruning-compact-selection-hardening/task.json
new file mode 100644
index 000000000..b79783111
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "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": "Reconciled on 2026-04-15: this active task had no PRD and was superseded by 04-14-stage-16b-latest-valid-compact-view-selection during Stage 16 closeout.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-14-stage-16c-virtual-pruning-view-metadata/check.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-16c-virtual-pruning-view-metadata/check.jsonl
new file mode 100644
index 000000000..54414c310
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-16c-virtual-pruning-view-metadata/debug.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-16c-virtual-pruning-view-metadata/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-16c-virtual-pruning-view-metadata/implement.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-16c-virtual-pruning-view-metadata/implement.jsonl
new file mode 100644
index 000000000..2743f7622
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-16c-virtual-pruning-view-metadata/prd.md b/.trellis/tasks/archive/2026-04/04-14-stage-16c-virtual-pruning-view-metadata/prd.md
new file mode 100644
index 000000000..021e92d88
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-16c-virtual-pruning-view-metadata/task.json b/.trellis/tasks/archive/2026-04/04-14-stage-16c-virtual-pruning-view-metadata/task.json
new file mode 100644
index 000000000..eaf4d35f2
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "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": "Reconciled on 2026-04-15: checkpoint evidence in the task PRD and canonical handoff/roadmap docs both show this historical stage is complete, so the task metadata was normalized for archive cleanup.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-14-stage-17a-task-graph-readiness-and-transition-invariants/check.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-17a-task-graph-readiness-and-transition-invariants/check.jsonl
new file mode 100644
index 000000000..2fc97f465
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-17a-task-graph-readiness-and-transition-invariants/debug.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-17a-task-graph-readiness-and-transition-invariants/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-17a-task-graph-readiness-and-transition-invariants/implement.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-17a-task-graph-readiness-and-transition-invariants/implement.jsonl
new file mode 100644
index 000000000..6a3b0b33b
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-17a-task-graph-readiness-and-transition-invariants/prd.md b/.trellis/tasks/archive/2026-04/04-14-stage-17a-task-graph-readiness-and-transition-invariants/prd.md
new file mode 100644
index 000000000..cf1ed40d3
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-17a-task-graph-readiness-and-transition-invariants/task.json b/.trellis/tasks/archive/2026-04/04-14-stage-17a-task-graph-readiness-and-transition-invariants/task.json
new file mode 100644
index 000000000..89638254f
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "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": "Reconciled on 2026-04-15: checkpoint evidence in the task PRD and canonical handoff/roadmap docs both show this historical stage is complete, so the task metadata was normalized for archive cleanup.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-14-stage-17b-plan-verify-workflow-boundary/check.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-17b-plan-verify-workflow-boundary/check.jsonl
new file mode 100644
index 000000000..1af72f3b0
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-17b-plan-verify-workflow-boundary/debug.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-17b-plan-verify-workflow-boundary/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-17b-plan-verify-workflow-boundary/implement.jsonl b/.trellis/tasks/archive/2026-04/04-14-stage-17b-plan-verify-workflow-boundary/implement.jsonl
new file mode 100644
index 000000000..afb59d9ad
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-17b-plan-verify-workflow-boundary/prd.md b/.trellis/tasks/archive/2026-04/04-14-stage-17b-plan-verify-workflow-boundary/prd.md
new file mode 100644
index 000000000..4f4ede932
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-14-stage-17b-plan-verify-workflow-boundary/task.json b/.trellis/tasks/archive/2026-04/04-14-stage-17b-plan-verify-workflow-boundary/task.json
new file mode 100644
index 000000000..1bf020b27
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-14",
+  "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": "Reconciled on 2026-04-15: checkpoint evidence in the task PRD and canonical handoff/roadmap docs both show this historical stage is complete, so the task metadata was normalized for archive cleanup.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-cc-level-2-microcompact-alignment/prd.md b/.trellis/tasks/archive/2026-04/04-15-cc-level-2-microcompact-alignment/prd.md
new file mode 100644
index 000000000..90f6f7ece
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-cc-level-2-microcompact-alignment/prd.md
@@ -0,0 +1,230 @@
+# brainstorm: cc level 2 microcompact alignment
+
+## Goal
+
+评审用户提供的 `Level 2: MicroCompact` 描述是否符合 cc-haha 源码功能，并判断 `coding-deepgent` 是否需要补充功能说明或后续实现任务。
+
+## Communication Requirement
+
+When explaining MicroCompact or other context compression levels, lead with
+concrete scenarios and visible effects, then map to implementation names. Avoid
+mechanism-only explanations.
+
+## What I already know
+
+* 当前 `coding-deepgent` 已有 `microcompact_messages(...)`，按 eligible tool results 数量保留最近 N 个，旧结果替换为 `[Old tool result content cleared]`。
+* 当前实现是 live model-call rewrite，不持久化 transcript，不包含时间触发、cache editing、prompt cache 过期判断。
+* 用户提供的 Level 2 描述强调：时间触发、服务端 prompt cache 过期、主线程判断、保留最近 N 个可压缩工具结果、cache editing 高级路径。
+
+## Source Notes
+
+cc-haha source reviewed:
+
+* `/root/claude-code-haha/src/services/compact/microCompact.ts`
+* `/root/claude-code-haha/src/services/compact/apiMicrocompact.ts`
+* `/root/claude-code-haha/src/services/compact/timeBasedMCConfig.ts`
+* `/root/claude-code-haha/src/query.ts`
+
+Key source-backed facts:
+
+* `TIME_BASED_MC_CLEARED_MESSAGE` is `[Old tool result content cleared]`.
+* `COMPACTABLE_TOOLS` includes file read, shell tools, grep, glob, web search, web fetch, edit, and write.
+* `microcompactMessages(...)` first runs `maybeTimeBasedMicrocompact(...)`; if it fires, it short-circuits and skips cached microcompact.
+* Time-based trigger checks:
+  * config enabled,
+  * explicit `querySource`,
+  * main-thread source,
+  * last assistant message exists,
+  * time since last assistant exceeds `config.gapThresholdMinutes`.
+* Time-based microcompact collects compactable tool-use IDs, keeps `Math.max(1, config.keepRecent)` most recent IDs, and clears older matching `tool_result` blocks.
+* It logs `gapMinutes`, threshold, tools cleared/kept, keepRecent, and tokensSaved.
+* It calls `resetMicrocompactState()` because content mutation invalidates cached microcompact state.
+* It notifies prompt-cache break detection through `notifyCacheDeletion(querySource)` when enabled.
+* Cached microcompact path is separate and feature-gated. It does not mutate local message content; it registers tool results, computes tools to delete, creates pending `cache_edits`, logs analytics, and defers boundary emission until after API response.
+* `apiMicrocompact.ts` defines API-side context management strategies such as `clear_tool_uses_20250919` and `clear_thinking_20251015`.
+
+## Evaluation
+
+用户提供的描述整体符合 cc-haha source-visible behavior。
+
+Important clarifications:
+
+* Time-based microcompact does not mean “regardless of content importance” in a semantic sense; it only clears compactable tool results and still keeps recent configured tool results.
+* It requires explicit main-thread query source; analysis-only callers without source should not trigger it.
+* Cached microcompact is not just “无损优化”; it is API-layer cache editing that avoids mutating local messages and depends on model/support/feature gates.
+* Time-based path and cached path are mutually exclusive for that request: time-based fires first and short-circuits.
+* Notebook edit appears in API microcompact clearable uses, while `microCompact.ts` compactable tools include edit/write/read/shell/search/web tools visible in this checkout.
+
+## Requirements (Future)
+
+* Decide whether to add cc-style time-based trigger to `coding-deepgent`.
+* Decide whether to model prompt-cache state locally or keep this documented as deferred provider-specific behavior.
+* User currently wants to explore `cached microcompact` specifically.
+* If implemented, ensure main-thread/session-only boundary and avoid running in subagents/analyzers.
+* Preserve current MicroCompact marker/path behavior.
+* Add bounded runtime events for time-triggered microcompact with gap and tokens saved.
+
+## Acceptance Criteria (Future)
+
+* [ ] Time-based trigger only fires when enabled and source/session is eligible.
+* [ ] Trigger keeps at least one recent compactable tool result.
+* [ ] Older eligible tool results are cleared with `[Old tool result content cleared]`.
+* [ ] Cached/API microcompact remains deferred unless provider support is explicit.
+* [ ] Tests cover disabled, wrong source, no assistant, under threshold, clearable results, and keepRecent floor.
+
+## Out of Scope (Current)
+
+* No implementation in this turn.
+* No provider-specific cache editing implementation now.
+* No exact prompt-cache TTL integration now.
+
+## Status
+
+Research captured / planning-only. User is considering cached microcompact as a future implementation direction.
+
+## Cached MicroCompact Difficulty Notes
+
+Cached microcompact is harder than time-based microcompact because it tries to
+remove old tool results without rewriting local message content and without
+breaking the provider-side prompt cache prefix.
+
+Concrete difficulties:
+
+* Provider support: cc's implementation is Anthropic/cache-editing specific
+  (`cache_edits`, `cache_reference`, `cache_deleted_input_tokens`). Our current
+  `coding-deepgent` stack is OpenAI-compatible LangChain first, so we need to
+  verify whether the active provider exposes an equivalent API-level context edit
+  primitive.
+* LangChain abstraction: `RuntimePressureMiddleware.wrap_model_call()` can
+  replace `request.messages`, but API-level cache edits may require model
+  request kwargs, provider-specific payload fields, or a custom model adapter.
+  That risks breaking the "LangChain-native, no custom query loop" boundary.
+* Stable tool-result identity: cached microcompact tracks tool results by
+  `tool_use_id` and original user-message position. Our LangChain `ToolMessage`
+  has `tool_call_id`, but request-level placement and replay across turns must
+  be stable enough to pin edits.
+* State lifecycle: cc keeps module-level cached MC state with registered tool
+  results, deleted refs, pinned edits, and reset behavior. We need a session-
+  scoped state owner, not global mutable state, so subagents and resumed sessions
+  do not leak tool IDs into each other.
+* Main-thread isolation: cc explicitly avoids forked agents / session_memory /
+  analyzers. We need an equivalent boundary using `RuntimeContext.agent_name`,
+  `entrypoint`, or explicit settings.
+* Warm-cache assumptions: cached microcompact only helps when provider cache is
+  warm. If the cache is cold or time-based path already mutated content, cache
+  edits can be useless or wrong. We would need cache-read/drop signals before
+  deciding when to use it.
+* Boundary/event timing: cc defers boundary emission until after API response so
+  it can use actual `cache_deleted_input_tokens`. Our current event/evidence path
+  emits before/around model call and has no provider token-delete metric.
+* Interaction with current MicroCompact: existing live rewrite changes content
+  to `[Old tool result content cleared]`. Cached microcompact must not also
+  content-rewrite the same results, or it destroys the cache-prefix benefit.
+* Interaction with tool-result persistence: if a deleted tool result had a
+  persisted output path, the model still needs a way to recover it. Cache edit
+  deletion must preserve or re-inject path hints somewhere bounded.
+* Failure and reset semantics: if provider call fails, if cache edit is rejected,
+  or if a later turn no longer contains the pinned position, the cached edit
+  state must fail open and reset safely.
+* Testing difficulty: unit tests need fake provider/model surfaces that can
+  assert cache edit payloads and simulated `cache_deleted_input_tokens`, not just
+  final message content.
+
+## Non-API MicroCompact Highlights Worth Considering
+
+User does not currently plan to implement provider API cache editing. Excluding
+that path, cc still has several useful MicroCompact details:
+
+### 1. Time-Based Trigger
+
+* Detects a natural pause by measuring minutes since the last assistant message.
+* Only fires when feature/config is enabled, source is explicit, and source is
+  main-thread.
+* Rationale: if the provider prompt cache is probably cold, content rewriting no
+  longer sacrifices useful cache hits and can reduce the next request payload.
+
+Potential local value:
+
+* Add `microcompact_gap_threshold_minutes` and only run aggressive tool-output
+  clearing after idle gaps.
+* This is provider-independent if treated as a local heuristic, even without
+  real cache editing.
+
+### 2. Main-Thread / Source Gating
+
+* cc avoids triggering time-based MicroCompact for analysis-only calls,
+  compact/session-memory paths, or forked agents.
+* It requires explicit `querySource`; `undefined` does not trigger the time-based
+  path even though cached-MC treats undefined as main-thread for backward
+  compatibility.
+
+Potential local value:
+
+* Gate aggressive MicroCompact to main `RuntimeContext` only.
+* Prevent verifier/subagent/summarizer paths from clearing tool outputs that
+  belong to another conversation.
+
+### 3. KeepRecent Floor
+
+* cc applies `Math.max(1, config.keepRecent)` because clearing all tool results
+  leaves the model with no working tool context.
+
+Potential local value:
+
+* Our `keep_recent_tool_results` currently allows `0`. For aggressive/time-based
+  mode, use a separate keep-recent floor of at least 1.
+
+### 4. Compactable Tool Allowlist
+
+* cc restricts clearing to a known set: file read, shell, grep, glob, web search,
+  web fetch, edit, write.
+
+Potential local value:
+
+* Keep using capability metadata (`microcompact_eligible`) but audit default
+  registry against cc's allowlist.
+* Avoid clearing semantic/state tools such as memory, task, plan, skills, or
+  verifier outputs.
+
+### 5. Token Saved Accounting
+
+* cc estimates tokens for cleared tool results and logs `tokensSaved`.
+* It records `gapMinutes`, threshold, tools cleared, tools kept, keepRecent, and
+  tokens saved.
+
+Potential local value:
+
+* Runtime pressure evidence should include bounded `tokens_saved_estimate`,
+  `tools_cleared`, and trigger reason for observability and future UI.
+
+### 6. Cache Break / Warning Coordination
+
+* After time-based content clearing, cc resets cached microcompact state and
+  notifies prompt-cache break detection to avoid false alarms.
+
+Potential local value:
+
+* If we later add cache/cost observability, local MicroCompact should emit a
+  clear event so cache-drop diagnostics know the drop was intentional.
+
+### 7. Path Split Between Time-Based And Cached Paths
+
+* Time-based path fires first and short-circuits.
+* Cached path runs only when time-based did not fire and cache is expected warm.
+
+Potential local value:
+
+* Keep local MicroCompact modes mutually exclusive:
+  * idle/time-based content clear,
+  * count/budget live rewrite,
+  * future cached API path.
+
+### 8. External Build Fallback
+
+* cc comments indicate legacy microcompact path was removed; where cached MC is
+  unavailable and time-based does not fire, autocompact handles pressure.
+
+Potential local value:
+
+* Avoid over-expanding local MicroCompact into a second full compaction system.
+  Let Collapse/AutoCompact handle semantic pressure.
diff --git a/.trellis/tasks/archive/2026-04/04-15-cc-level-2-microcompact-alignment/task.json b/.trellis/tasks/archive/2026-04/04-15-cc-level-2-microcompact-alignment/task.json
new file mode 100644
index 000000000..7533501ab
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-cc-level-2-microcompact-alignment/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "cc-level-2-microcompact-alignment",
+  "name": "cc-level-2-microcompact-alignment",
+  "title": "brainstorm: cc level 2 microcompact alignment",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-15",
+  "completedAt": "2026-04-16",
+  "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/archive/2026-04/04-15-cc-style-snip-message-pruning/prd.md b/.trellis/tasks/archive/2026-04/04-15-cc-style-snip-message-pruning/prd.md
new file mode 100644
index 000000000..3bd210105
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-cc-style-snip-message-pruning/prd.md
@@ -0,0 +1,230 @@
+# brainstorm: cc-style snip message pruning
+
+## Goal
+
+设计并实现 cc-style `Snip`：让 agent 或用户能选择性移除不再需要的旧消息区间，而不是只做 recent-tail trim。重点难点是定义“哪些消息可以被废弃/删减”的判断机制，并确保该机制安全、可恢复、可测试，且符合 `coding-deepgent` 的 LangChain-native runtime 边界。
+
+## What I already know
+
+* 用户希望实现更接近 cc 的 `Snip`，核心疑问是 agent 如何判断哪些消息可以被废弃删减。
+* 当前 `coding-deepgent` 已有 runtime pressure pipeline：`Snip -> MicroCompact -> Collapse -> AutoCompact`。
+* 当前 `Snip` 是 threshold + recent-tail projection trim，默认关闭，不是 cc-style selective removal。
+* 当前 `MicroCompact` 已实现 `[Old tool result content cleared]` 旧工具结果清理。
+* cc-haha 可见线索显示 `HISTORY_SNIP` 在 `microcompact` 前运行，且有 `SnipTool`、`/force-snip`、message id tags、removedUuids replay、resume filtering 等机制。
+* LangChain 官方支持 transient model-context trimming、persistent message deletion、summarization middleware；但 cc-style selective snip 需要项目自己的策略和记录层。
+
+## Assumptions (temporary)
+
+* MVP 不追求完整复制 cc 内部 `snipCompact.ts` 算法，而是实现本项目可验证的 selective snip semantics。
+* agent 不应该无约束删除上下文；必须有保守规则、可解释记录、可恢复边界。
+* JSONL transcript 应保持 append-only；Snip 应通过 boundary/metadata 在 load/resume 时过滤 model-facing history，而不是物理删除历史。
+
+## Open Questions
+
+* MVP 里 agent 判断可删消息的策略应采用：用户/模型显式选择、规则建议 + 用户确认，还是自动策略？
+
+## Requirements (evolving)
+
+* 设计 cc-style Snip 的消息选择机制。
+* 支持选择性移除中间旧消息，而不是只保留 recent tail。
+* 保留 session transcript append-only。
+* Snip 决策应可解释、可测试、可恢复。
+* 保持 tool-call/tool-result pairing 和消息序列合法。
+* 不引入自定义 query loop，优先使用 LangChain middleware/tool/runtime seams。
+
+## Acceptance Criteria (evolving)
+
+* [ ] 明确 MVP 的 Snip 决策策略。
+* [ ] 明确哪些消息永远不能自动 snip。
+* [ ] 明确 Snip boundary/metadata 的持久化和 resume replay 方式。
+* [ ] 明确验证矩阵和 focused tests。
+
+## 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)
+
+* 不做 cc-haha line-by-line clone。
+* 不实现 UI scrollback 或 IDE visual selection。
+* 不物理删除 JSONL transcript 原始消息。
+* 不让 agent 无记录、无边界地静默删除任意历史。
+
+## Technical Notes
+
+* Candidate implementation surfaces:
+  * `coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py`
+  * `coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py`
+  * `coding-deepgent/src/coding_deepgent/sessions/records.py`
+  * `coding-deepgent/src/coding_deepgent/tool_system/*`
+  * `coding-deepgent/src/coding_deepgent/settings.py`
+* Existing contract surface:
+  * `.trellis/spec/backend/runtime-pressure-contracts.md`
+  * `.trellis/spec/backend/session-compact-contracts.md`
+
+## Research Notes
+
+### What cc-haha visibly does
+
+* `HISTORY_SNIP` is feature-gated and runs before `microcompact` in `query.ts`.
+* `snipCompactIfNeeded(messagesForQuery)` returns rewritten messages, `tokensFreed`, and optionally a boundary message.
+* `snipTokensFreed` is passed into `autoCompact`, so autocompact thresholding accounts for tokens already removed by snip.
+* `SnipTool` is feature-gated in `tools.ts`, and `/force-snip` is feature-gated in `commands.ts`.
+* API-bound user messages receive `[id:...]` tags so Claude can reference messages when calling the snip tool.
+* Session load applies snip removals by reading `snipMetadata.removedUuids` from boundary records. JSONL remains append-only; active history is filtered and parent links are relinked.
+* This checkout references `snipCompact.js`, `snipProjection.js`, `SnipTool`, and
+  `force-snip`, but their implementation files are not present in the local
+  public tree. Therefore exact candidate-selection heuristics are not available
+  to copy line-for-line from this checkout.
+* Visible attachments logic has a context-efficiency nudge that appears after
+  token growth without a snip; it nudges the agent toward using Snip but does not
+  prove fully automatic deletion.
+
+### What LangChain provides
+
+* LangChain supports transient message trimming before model calls through middleware / trim helpers.
+* LangChain supports persistent deletion with `RemoveMessage`, but that mutates graph state and requires reducer/state assumptions.
+* LangChain `SummarizationMiddleware` is not Snip: it summarizes with an LLM and persistently replaces old messages with a summary.
+* For this project, cc-style Snip should remain a project-specific tool/session contract rather than directly adopting SummarizationMiddleware.
+
+### What opencode does
+
+* `packages/opencode/src/session/compaction.ts` has `SessionCompaction.prune()`.
+* `prune()` walks backward through messages/parts after at least two user turns,
+  stops at an assistant summary or already compacted tool part, protects `skill`
+  tool outputs, counts completed tool outputs, keeps roughly
+  `PRUNE_PROTECT = 40_000` tokens of recent tool output, and marks older tool
+  parts with `time.compacted` only when at least `PRUNE_MINIMUM = 20_000`
+  tokens would be freed.
+* `MessageV2.toModelMessagesEffect()` turns compacted tool outputs into
+  `[Old tool result content cleared]`.
+* opencode therefore has a concrete rule-based tool-output pruning strategy,
+  not a cc-style selective message SnipTool. It answers part of the question:
+  old completed tool outputs beyond a protected recent-token budget are safe
+  candidates, except protected tools and already summarized/compacted regions.
+* `packages/opencode/src/session/compaction.ts` also has full conversation
+  compaction via a dedicated `compaction` agent and summary prompt.
+* `packages/opencode/src/tool/truncate.ts` stores oversized tool output to a
+  file and gives the model a path plus delegation hint.
+
+### What OpenAI Codex does
+
+* `codex-rs/core/src/compact.rs` implements manual/auto context compaction by
+  running a compact task that summarizes history, then replaces history with
+  selected recent user messages plus a summary.
+* If compaction itself exceeds the context window, Codex removes the oldest
+  history item and retries, preserving recent messages.
+* `codex-rs/core/src/context_manager/history.rs` has `remove_first_item()` and
+  `remove_last_item()` helpers that also remove corresponding tool call/output
+  counterparts to preserve invariants.
+* Codex truncates function/tool output payloads on record with a
+  `TruncationPolicy`.
+* I did not find a cc-style SnipTool or selective semantic message deletion in
+  Codex. Codex relies on summarization compaction, oldest-item trimming under
+  pressure, and tool-output truncation/invariant-preserving removal.
+
+### Cross-project takeaway
+
+* cc visible design: agent/user explicit Snip with message IDs and replay.
+* opencode: rule-based old tool-output pruning plus full compaction.
+* Codex: full compaction plus oldest-item trim retry and tool-output truncation.
+* None of the inspected public sources show a safe fully automatic semantic
+  message deletion algorithm. The strongest source-backed strategy is hybrid:
+  explicit SnipTool for semantic deletion plus deterministic opencode-style
+  tool-output pruning as an automatic safe subset.
+
+### Foreign community / OSS notes
+
+* Aider community issue `Aider-AI/aider#3607` proposes manual chat-history
+  selection via a `/history` markdown file with checkboxes. The motivation is
+  exactly selective context control: important old messages may be summarized
+  away while unimportant recent messages remain raw and noisy. This is a
+  community proposal, not evidence of a merged implementation.
+* Roo Code discussion `Roo-Code#544` proposes a `ContextGraph` with operations
+  such as `update`, `summarize`, `elide`, and `collapse`, plus auditability and
+  selective restoration. This is close conceptually to cc-style Snip, but it is
+  a design discussion/proposal rather than a concrete production algorithm.
+* Cline community discussion `cline#3078` emphasizes cheap-model summarization
+  and user review/override. It addresses context compression, but not selective
+  deletion of arbitrary old message ranges.
+* These community references reinforce the same pattern: selective semantic
+  pruning is treated as a user/agent-controlled operation with auditability, not
+  as a silent automatic heuristic.
+
+### Constraints from our repo/project
+
+* Current `JsonlSessionStore` loads `history` as `list[dict[str, str]]`, losing message metadata and stable IDs.
+* Message records may have `message_index`, but `LoadedSession.history` currently omits it.
+* There is no persisted `snip` record type or snip boundary metadata.
+* Current runtime pressure `snip_messages()` is transient recent-tail trim, not selective removal.
+* Tool system can expose a strict Pydantic `SnipTool`, but the model needs stable message IDs in visible context before it can call it safely.
+
+### Feasible approaches here
+
+**Approach A: Explicit Snip Tool With Safety Gates** (Recommended)
+
+* How it works:
+  * Add stable model-visible message refs for eligible recent/older messages.
+  * Add `snip_messages` tool that accepts explicit message refs or ranges plus a reason.
+  * Tool validates refs, expands paired tool-call/tool-result ranges, rejects protected messages, and appends a snip boundary/evidence record.
+  * Resume/load applies snip removals virtually to model-facing history while preserving raw transcript.
+* Pros:
+  * Most cc-like and keeps the agent in charge, but only through explicit auditable action.
+  * Decisions are explainable because every snip has refs + reason.
+  * Easy to test Good/Base/Bad cases.
+* Cons:
+  * Requires message identity, boundary/replay, and protected-message rules before useful behavior.
+
+**Approach B: Rule-Based Auto Snip Suggestions**
+
+* How it works:
+  * Middleware computes candidates such as superseded file reads, failed exploration branches, old long tool outputs with persisted paths, or completed task branches.
+  * It emits suggestions/evidence, but does not remove until a tool/command accepts them.
+* Pros:
+  * Helps answer "which messages can be deleted" without trusting the model fully.
+  * Can evolve toward automatic mode later.
+* Cons:
+  * Harder to tune; false positives are likely without semantic context.
+  * Still needs explicit apply path.
+
+**Approach C: Fully Automatic Snip**
+
+* How it works:
+  * Middleware silently removes low-value candidates once pressure exceeds a threshold.
+* Pros:
+  * Maximum context savings with no user/model intervention.
+* Cons:
+  * High risk of deleting important rationale or constraints.
+  * Hard to debug and not aligned with current project safety posture.
+
+### Initial recommendation
+
+Start with Approach A plus an opencode-style deterministic tool-output pruning
+subset. MVP should require explicit agent/user action for semantic message
+deletion. Automatic pruning may be limited to old completed tool outputs beyond
+a protected recent-token budget.
+
+After reviewing Aider/Roo/Cline community discussions, keep that recommendation:
+use an explicit SnipTool and avoid automatic semantic deletion. Consider a
+future manual selection UX (`/history`-style list or CLI command) after the core
+message-ref + boundary/replay contract exists.
+
+### Source-backed clarification
+
+From visible source, cc-style Snip appears to be explicit tool/command-driven
+selective removal with nudges, not a purely automatic heuristic that silently
+decides and deletes messages. We can copy that product shape, but not the hidden
+implementation details from this checkout.
+
+## Status
+
+Deferred / research captured.
+
+Reason:
+
+* 用户判断 cc-style selective Snip 难度较高，暂不进入实现。
+* 本 PRD 保留这次方向讨论、源码线索、国外开源/社区对照和后续推荐方案。
+* 如果未来重启，建议从 explicit `SnipTool(message_refs, reason)` + boundary/replay 开始，而不是自动语义删除。
diff --git a/.trellis/tasks/archive/2026-04/04-15-cc-style-snip-message-pruning/task.json b/.trellis/tasks/archive/2026-04/04-15-cc-style-snip-message-pruning/task.json
new file mode 100644
index 000000000..a22793b3d
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-cc-style-snip-message-pruning/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "cc-style-snip-message-pruning",
+  "name": "cc-style-snip-message-pruning",
+  "title": "brainstorm: cc-style snip message pruning",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-15",
+  "completedAt": "2026-04-16",
+  "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/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-context-system-closeout-decision/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-context-system-closeout-decision/check.jsonl
new file mode 100644
index 000000000..9cd8c9833
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-context-system-closeout-decision/check.jsonl
@@ -0,0 +1,6 @@
+{"file": ".cursor/commands/trellis-finish-work.md", "reason": "Finish work checklist"}
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
+{"file": ".trellis/spec/backend/runtime-pressure-contracts.md", "reason": "Runtime pressure contract to verify for Snip and summarizer Collapse"}
+{"file": ".trellis/spec/backend/langchain-native-guidelines.md", "reason": "Review middleware implementation against LangChain-native rules"}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Focused test and boundary review requirements"}
+{"file": "coding-deepgent/tests/test_runtime_pressure.py", "reason": "Focused tests for Snip Collapse MicroCompact AutoCompact ordering and behavior"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-context-system-closeout-decision/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-context-system-closeout-decision/debug.jsonl
new file mode 100644
index 000000000..e30f96d49
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-context-system-closeout-decision/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-context-system-closeout-decision/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-context-system-closeout-decision/implement.jsonl
new file mode 100644
index 000000000..f53345086
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-context-system-closeout-decision/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": ".trellis/spec/backend/runtime-pressure-contracts.md", "reason": "Runtime pressure contract to update for Snip and summarizer Collapse"}
+{"file": ".trellis/spec/backend/langchain-native-guidelines.md", "reason": "Middleware must remain LangChain-native and avoid custom query loop"}
+{"file": ".trellis/spec/backend/error-handling.md", "reason": "Collapse summarizer failure must fail open per runtime pressure boundary"}
+{"file": "coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py", "reason": "Primary implementation surface for model-call pressure pipeline"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-context-system-closeout-decision/prd.md b/.trellis/tasks/archive/2026-04/04-15-context-system-closeout-decision/prd.md
new file mode 100644
index 000000000..890f0413f
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-context-system-closeout-decision/prd.md
@@ -0,0 +1,88 @@
+# brainstorm: context system closeout decision
+
+## Goal
+
+判断 `coding-deepgent` 当前上下文系统是否已经覆盖原教程的核心压缩机制，并在用户决定补齐缺口后，定义 `Snip` 与 `Collapse` 的最小产品化实现范围，使四层压缩机制都通过 LangChain middleware 管线进入模型调用前上下文准备流程。
+
+## What I already know
+
+* 当前主线范围是 `coding-deepgent/`，教程层默认 reference-only。
+* 原教程 `agents_deepagents/s06_context_compact.py` 的教学压缩流水线包含六段：`apply_tool_result_budget`、`snip_projection`、`microcompact_messages`、`context_collapse`、`auto_compact_if_needed`、`reactive_compact_on_overflow`。
+* 当前 `coding-deepgent` 已实现 tool-result persistence、microcompact、auto compact、reactive compact、manual/generated compact resume、append-only compact records、load-time compacted history、recovery brief、session-memory assist/update、runtime pressure evidence。
+* Focused tests 已通过：`pytest -q coding-deepgent/tests/test_runtime_pressure.py coding-deepgent/tests/test_compact_artifacts.py coding-deepgent/tests/test_tool_result_storage.py coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_cli.py -q`，结果 `69 passed`。
+* Roadmap 中 H05/H06/H07 已标为 implemented，当前推荐下一步是 Approach A MVP release validation / PR cleanup。
+
+## Assumptions (temporary)
+
+* “完成上下文系统模块”指完成 Approach A MVP 的上下文/压缩/恢复/记忆最小产品边界，而不是完整复刻 cc-haha compact runtime。
+* `snip_projection` 和 `context_collapse` 可作为 future enhancement，除非用户要求完整 six-stage parity 才算完成。
+* 运行中 model-visible `compact` tool 或 `/compact` 命令不是当前 MVP 必需项，因为主线已有 CLI resume manual/generated compact 与 runtime pressure auto/reactive compact。
+
+## Open Questions
+
+* none
+
+## Requirements (evolving)
+
+* 给出上下文系统机制覆盖矩阵。
+* 明确哪些机制已实现、哪些是产品化替代、哪些是有意 deferred。
+* 补齐 `Snip` 和 `Collapse`，使 `Snip`、`MicroCompact`、`Collapse`、`AutoCompact` 四层机制都存在于当前主线。
+* 四层机制应进入 LangChain `AgentMiddleware.wrap_model_call()` 之前/之中的模型调用上下文准备链路；核心算法可保留为可单测 helper。
+* 不引入自定义 query loop，不绕开 LangChain/LangGraph `create_agent` runtime。
+* `Collapse` 采用 summarizer-based 方案：超过 collapse 阈值时，通过现有 fakeable summarizer seam 生成旧上下文摘要。
+* `Collapse` 失败时 fail-open：保留原始 model-facing messages，继续进入后续 `AutoCompact` 判断。
+* `Collapse` 生成的 live collapse artifact 只作用于当前 model call，不写入 JSONL transcript，不创建 persisted compact record。
+
+## Acceptance Criteria (evolving)
+
+* [x] `Snip` 在进入模型调用前可 deterministic 地缩小 model-facing projection，同时不修改 persisted transcript/session history。
+* [x] `Collapse` 在进入 `AutoCompact` 前可用 summarizer 压缩旧上下文，并保留 recent tail 与 tool-call/tool-result pairing。
+* [x] `Collapse` summarizer 失败或返回无效 summary 时 fail-open，不破坏后续 model call。
+* [x] `MicroCompact` 与 `AutoCompact` 现有测试保持通过。
+* [x] 新增 focused tests 覆盖 `Snip -> MicroCompact -> Collapse -> AutoCompact` 顺序。
+* [x] 新增或更新 Trellis contract，说明四层压缩顺序、失败策略和不持久化 live rewrite 的边界。
+
+## Definition of Done (team quality bar)
+
+* Tests added/updated if implementation follows.
+* Lint / typecheck / focused tests green if implementation follows.
+* Docs/notes updated if behavior or roadmap status changes.
+* Rollout/rollback considered if risky.
+
+## Out of Scope (explicit)
+
+* 不做 cc-haha line-by-line clone。
+* 不把 provider-specific token/cost/cache behavior 作为当前上下文 MVP 必需项。
+* 不实现 cc-haha 完整 `snipCompact` / `contextCollapse` 内部算法复刻，只实现本地产品需要的 LangChain-native 等价语义。
+* 不把 Bridge / daemon / coordinator / mailbox 拉回当前上下文模块。
+
+## Technical Notes
+
+* `coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py`: runtime microcompact, auto compact, reactive compact, event/evidence.
+* `coding-deepgent/src/coding_deepgent/compact/tool_results.py`: large tool result persistence and preview marker.
+* `coding-deepgent/src/coding_deepgent/compact/artifacts.py`: manual compact artifact shape.
+* `coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py`: append-only message/state/evidence/compact ledger and compacted history selection.
+* `coding-deepgent/src/coding_deepgent/sessions/session_memory.py`: bounded session-memory artifact, compact assist, update thresholds.
+* `coding-deepgent/src/coding_deepgent/cli.py`: resume with selected compacted history, manual compact summary, generated compact summary, session-memory option.
+* `agents_deepagents/s06_context_compact.py`: reference tutorial six-stage context compression pipeline.
+* `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`: H05/H06/H07 current MVP status.
+
+## Decision (ADR-lite)
+
+**Context**: 当前主线已实现 `MicroCompact` 和 `AutoCompact`，但缺少 `Snip` 与 `Collapse` 两个中间 pressure stage。用户希望补齐四层机制，并确认四层都应通过 LangChain middleware 链路实现。
+
+**Decision**: 实现 `Snip + summarizer Collapse`。`Snip` 是 deterministic projection-only rewrite；`Collapse` 使用现有 compact summarizer seam 在 `AutoCompact` 前生成 live collapse summary。两者都只影响当前 model-facing messages，不直接持久化 transcript。
+
+**Consequences**: 相比 deterministic collapse，summarizer collapse 语义更强、更接近 cc 的上下文压缩意图；代价是会增加一次潜在模型调用，因此必须具备阈值、fail-open、focused tests 和 bounded artifact 规则。
+
+## Implementation Summary
+
+* `Snip -> MicroCompact -> Collapse -> AutoCompact` 已接入 `RuntimePressureMiddleware.wrap_model_call()`。
+* 新增 settings-backed thresholds / kept-tail knobs：`snip_threshold_tokens`、`collapse_threshold_tokens`、`keep_recent_messages_after_snip`、`keep_recent_messages_after_collapse`。
+* `Snip` 是有损 projection-only stage，默认 `snip_threshold_tokens == None`，显式配置阈值后启用；这样避免在 Collapse/AutoCompact 摘要前默认静默丢掉旧上下文语义。
+* 新增 runtime events / session evidence whitelist：`snip`、`context_collapse`。
+* 更新 runtime pressure contracts 和 overview index。
+* 验证：
+  * `pytest -q coding-deepgent/tests` -> `261 passed`
+  * `ruff check ...` -> passed
+  * `mypy src/coding_deepgent/compact/runtime_pressure.py src/coding_deepgent/sessions/evidence_events.py src/coding_deepgent/sessions/runtime_pressure.py src/coding_deepgent/settings.py src/coding_deepgent/containers/app.py` -> passed
diff --git a/.trellis/tasks/archive/2026-04/04-15-context-system-closeout-decision/task.json b/.trellis/tasks/archive/2026-04/04-15-context-system-closeout-decision/task.json
new file mode 100644
index 000000000..cb45b01f6
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-context-system-closeout-decision/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "context-system-closeout-decision",
+  "name": "context-system-closeout-decision",
+  "title": "brainstorm: context system closeout decision",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-15",
+  "completedAt": "2026-04-16",
+  "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/archive/2026-04/04-15-diagnose-module-upgrade-coupling/prd.md b/.trellis/tasks/archive/2026-04/04-15-diagnose-module-upgrade-coupling/prd.md
new file mode 100644
index 000000000..d600a8ef9
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-diagnose-module-upgrade-coupling/prd.md
@@ -0,0 +1,286 @@
+# brainstorm: diagnose module upgrade coupling
+
+## Goal
+
+Diagnose why the current `coding-deepgent` upgrade path still feels highly coupled when the desired product direction is to optimize one module directly. Clarify whether the problem is incomplete infrastructure, a mismatch in the definition of "infrastructure", or an overly coupled implementation approach.
+
+## What I already know
+
+* User expects that after enough infrastructure work, a module such as `memory`, `compact`, `plugins`, or `mailbox` can be optimized mostly within that module.
+* The latest implemented slice, `context pressure v2 / session-memory compaction: Deterministic Assist`, touched multiple areas:
+  * `sessions`
+  * `runtime.state`
+  * `cli`
+  * `cli_service`
+  * `compact.summarizer`
+  * tests and compaction contracts
+* The feature itself was chosen because it crosses existing product flows: session resume, state snapshots, recovery brief, generated compact summary, and memory continuity.
+* Existing roadmap/docs define foundation mostly as LangChain-native runtime correctness, persistence, recovery, tool/permission safety, compact/session contracts, and local extension seams.
+* Current repo has domain folders, but several orchestration seams are still centralized or hardcoded:
+  * `JsonlSessionStore._coerce_state_snapshot()` knows concrete runtime state fields.
+  * `render_recovery_brief()` manually owns recovery sections.
+  * `generated_compacted_continuation_history()` manually wires compact assist inputs.
+  * `ContextPayload` exists but is not yet a universal dynamic-context provider registry.
+
+## Assumptions (temporary)
+
+* There are two kinds of coupling in play:
+  * Essential coupling from product flows that genuinely cross modules.
+  * Accidental coupling from missing module-level extension points.
+* The latest slice had both kinds.
+* The term "infrastructure" may currently be overloaded between:
+  * runtime correctness infrastructure
+  * module-isolation / upgrade infrastructure
+
+## Open Questions
+
+* None for the next direction: user selected `Module Upgrade Infra Stage`.
+
+## Requirements (evolving)
+
+* Explain why the latest upgrade crossed modules.
+* Separate expected cross-layer integration from avoidable accidental coupling.
+* Identify missing infrastructure that would allow more module-local optimization.
+* Recommend a next planning direction.
+* Lock the next direction to module-isolated upgrade seams before continuing feature work.
+
+## Acceptance Criteria (evolving)
+
+* [x] Inspect current coupling points from the latest slice.
+* [x] Compare them against existing roadmap/foundation definitions.
+* [x] State whether this is infrastructure weakness, definition mismatch, or implementation drift.
+* [x] Ask one high-value follow-up question to choose the next direction.
+* [x] Capture the user's decision.
+
+## Definition of Done
+
+* Diagnosis is captured in this PRD.
+* User receives a concise recommendation with concrete options.
+* No code changes are made in this brainstorm task.
+
+## Out of Scope
+
+* Refactoring the current implementation immediately.
+* Reverting the latest deterministic-assist slice.
+* Designing a full plugin/coordinator/mailbox architecture in this diagnostic task.
+
+## Technical Notes
+
+### Current Coupling Evidence
+
+The latest slice touched multiple modules because the chosen behavior was inserted into existing flow-specific seams:
+
+* State persistence:
+  * `coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py`
+  * reason: state snapshot coercion is hardcoded and had to learn `session_memory`
+* Runtime state typing:
+  * `coding-deepgent/src/coding_deepgent/runtime/state.py`
+  * reason: session memory became part of persisted runtime state
+* Recovery/resume:
+  * `coding-deepgent/src/coding_deepgent/sessions/resume.py`
+  * reason: recovery brief rendering is centralized and manually sectioned
+* CLI orchestration:
+  * `coding-deepgent/src/coding_deepgent/cli.py`
+  * reason: explicit update was exposed as a resume flag
+* Service orchestration:
+  * `coding-deepgent/src/coding_deepgent/cli_service.py`
+  * reason: generated compact flow manually supplies summarizer inputs
+* Compact summarizer:
+  * `coding-deepgent/src/coding_deepgent/compact/summarizer.py`
+  * reason: summarizer request builder had no generic assist/context provider input
+
+### Current Infrastructure Strength
+
+The repo has good infrastructure for:
+
+* strict tool schemas
+* permission/tool boundary
+* JSONL sessions and append-only compact records
+* recovery brief
+* memory quality policy
+* compact message invariants
+* local plugin manifest validation
+* targeted contracts/tests
+
+### Current Infrastructure Gap
+
+The repo is weaker for module-local upgrades because it lacks:
+
+* a pluggable runtime-state serialization registry
+* a dynamic context provider registry that all modules can contribute to
+* a recovery brief section provider interface
+* a compact assist provider interface
+* module-owned CLI command registration or feature command grouping
+* clear distinction between "module owns data" and "flow owns projection/rendering"
+
+### Preliminary Diagnosis
+
+This is both:
+
+* incomplete module-isolation infrastructure
+* and a definition mismatch
+
+The existing foundation work mostly built "runtime correctness infrastructure": safe sessions, compact records, recovery, memory quality, tool contracts, and validation. The user's expectation points to "module upgrade infrastructure": a module should expose contribution points so future optimization happens behind that module boundary and only light integration glue changes elsewhere.
+
+The latest slice also showed implementation drift: I optimized for the safest deterministic path and explicit testability, but I did not first create a small generic extension seam such as `SessionContextContribution` / `CompactAssistProvider`. That made the slice reliable, but not as modular as the user's target.
+
+## Decision (ADR-lite)
+
+**Context**: The user expects future upgrades to target one module directly. The current codebase has good runtime-correctness infrastructure, but module upgrades still require edits in orchestration files such as `cli_service`, `sessions.resume`, `sessions.store_jsonl`, and `compact.summarizer`.
+
+**Decision**: Prioritize a `Module Upgrade Infra Stage` before continuing `Threshold-Triggered Local Updates` or other feature work.
+
+**Consequences**:
+
+* Future module work should add or change module-owned providers instead of editing every flow directly.
+* The current `session_memory` deterministic-assist slice should be retrofitted onto the new seams rather than treated as the final architecture.
+* More feature work should pause until the first module-upgrade seams exist, otherwise coupling will continue to grow.
+
+## Recommended Next Stage
+
+### Goal
+
+Introduce lightweight module contribution seams so modules can participate in runtime state persistence, recovery brief rendering, compact assistance, and dynamic context assembly without each feature editing central orchestration code.
+
+### First Slice
+
+Start with `session_memory` as the proving case because it already exposed the coupling.
+
+Implement only enough generic infrastructure to move the current hard wiring behind module-owned contribution functions:
+
+* `RuntimeStateContribution`
+  * owns validation/coercion/defaulting for one state key such as `session_memory`
+* `RecoveryBriefContribution`
+  * lets a module render one recovery section without editing `render_recovery_brief()` for every module
+* `CompactAssistContribution`
+  * lets a module provide optional bounded assist text for generated compact summary
+* Optional later seam: `DynamicContextContribution`
+  * defer unless the first slice needs it immediately
+
+### Concrete Refactor Target
+
+Move current `session_memory` hard wiring out of:
+
+* `JsonlSessionStore._coerce_state_snapshot()`
+* `render_recovery_brief()`
+* `cli_service.generated_compacted_continuation_history()`
+* `compact.summarizer` direct session-memory naming
+
+Into module-owned contribution functions under `coding_deepgent.sessions.session_memory` or a small shared contribution module.
+
+### Non-goals
+
+* Do not build a broad plugin framework.
+* Do not add threshold-triggered updates yet.
+* Do not add background extraction.
+* Do not add mailbox/coordinator/runtime lifecycle.
+* Do not over-abstract every existing module at once.
+
+### Acceptance Criteria
+
+* `session_memory` behavior remains unchanged from the deterministic-assist slice.
+* At least one generic contribution seam exists and is tested.
+* Central orchestration code no longer names all `session_memory` details directly.
+* Focused tests prove current/stale/invalid behavior still works.
+* The contract doc distinguishes runtime-correctness infrastructure from module-upgrade infrastructure.
+
+## Cross-Module Coupling Review Before Implementation
+
+### Local module coupling map
+
+| Module band | Current local coupling level | Evidence | Can optimize module alone today? | Required seam |
+|---|---:|---|---|---|
+| `tool_system` / MCP tools | low-to-medium | `ToolCapability`, `CapabilityRegistry`, MCP adapters already normalize extension tools into one registry | mostly yes for new tools/MCP capabilities | keep capability registry as the tool boundary |
+| `memory` long-term recall | medium | `MemoryContextMiddleware` owns model injection, but recall still depends on runtime store and prompt context | yes for quality/recall policy; no for recovery/compact effects | dynamic context contribution registry |
+| `todo` | medium | `TodoContextMiddleware` already contributes context, but runtime state shape is still shared | yes for tool/schema changes; no for persistence/projection changes | runtime state contribution registry |
+| `sessions` / recovery | high | `render_recovery_brief()` owns sections manually; `JsonlSessionStore._coerce_state_snapshot()` knows concrete state fields | no | recovery brief + state serializer contributions |
+| `compact` | high | generated summary request and continuation history are explicit service functions | no, if assist sources or recovery semantics change | compact assist provider registry |
+| `plugins` | medium | local plugin registry is isolated, but startup validation and capability loading are central | partly | plugin lifecycle state + startup contribution seam |
+| `subagents` / verifier | high | verifier tool allowlists, plan lookup, evidence persistence, and recovery all cross modules | no | agent lifecycle/evidence contribution seams |
+| `hooks` | comparatively low | dispatcher already centralizes hook events and adapters | mostly yes | keep event-dispatch pattern; use as model |
+| `CLI` | high | `cli.py` owns command flags directly | no | command grouping or service-level command seams |
+
+### Interpretation
+
+Some coupling is essential: model-visible flows such as "resume with compact summary" genuinely touch state, recovery, and message assembly.
+
+But much of the friction is accidental: central code manually knows each feature's fields and render rules. The current architecture has domain folders, but not enough domain-owned contribution interfaces.
+
+## cc-haha Coupling Analysis
+
+### What cc-haha does well
+
+cc-haha does not make modules fully independent. It reduces coupling by routing module behavior through a few broad protocols:
+
+* `Tool` / `ToolUseContext`
+  * Tools receive a rich context object with app state, settings, tool list, MCP clients/resources, abort control, file caches, session/task hooks, and notification plumbing.
+  * This means tool implementations can evolve behind the `Tool` interface, but the context object itself is intentionally broad and central.
+* `Attachment`
+  * Dynamic model-visible context is represented as a tagged union of attachment types.
+  * Modules add context by creating attachments; central message normalization renders attachments into API messages.
+  * This reduces random prompt-string injection, but adding a new attachment type still requires updating the central union and renderer.
+* Hooks
+  * cc-haha has hook matchers/execution for lifecycle events, including compact hooks.
+  * Plugins/skills/session hooks are merged through a central hook resolver with source context and dedup rules.
+  * This is a real module-contribution pattern.
+* Plugin loader
+  * Plugin loading separates source/install/cache/enable concerns and returns `LoadedPlugin` results for startup consumers.
+  * It still has a large central loader, but capability consumers depend on loaded plugin output, not every plugin implementation detail.
+* Session memory
+  * Session memory is not module-local. It registers a post-sampling hook, uses thresholds, creates isolated subagent context, updates memory files, and is consumed by compaction.
+  * cc-haha solved this with lifecycle hooks plus isolated/forked context, not with "just edit the memory module".
+
+### What cc-haha does not solve completely
+
+cc-haha still has central switch/union points:
+
+* `Attachment` is a large tagged union.
+* `normalizeAttachmentForAPI()` is a large central renderer.
+* `ToolUseContext` is a broad dependency object.
+* Plugin loading is centralized and complex.
+* Session memory relies on hook registration and compaction integration.
+
+So the realistic target is not "any module can upgrade without touching anything else." The realistic target is:
+
+* module upgrade touches mostly module-owned provider/contribution code
+* central code changes only when a new contribution type/protocol is introduced
+* existing contribution protocols allow new behavior without editing every flow
+
+## Answer: Can We Independently Upgrade One Module?
+
+Today:
+
+* For pure tool/schema/policy changes: often yes.
+* For dynamic context, recovery, compaction, persisted state, or subagent lifecycle: no.
+* For plugin lifecycle and mailbox: no, because they need lifecycle/state/orchestration seams that are not present yet.
+
+After the proposed `Module Upgrade Infra Stage`:
+
+* We should be able to upgrade `session_memory` by changing its contribution provider instead of editing `store_jsonl`, `resume`, `cli_service`, and `summarizer` together.
+* We should still expect one-time central changes when introducing a new category of contribution.
+* We should not promise zero cross-module impact; instead, promise bounded impact through explicit extension seams.
+
+## Revised Stage Direction
+
+The module-upgrade infra stage should copy the useful cc-haha pattern, not its TS/product complexity:
+
+* Copy the idea:
+  * tagged/context contributions
+  * lifecycle/event hooks
+  * module-owned providers
+  * central renderer/orchestrator consumes generic contribution outputs
+* Do not copy directly:
+  * giant `ToolUseContext`
+  * giant attachment union as-is
+  * broad plugin loader complexity
+  * background session-memory runtime in this stage
+
+Recommended local Python shape:
+
+* small dataclasses/protocols:
+  * `RuntimeStateContribution`
+  * `RecoveryBriefContribution`
+  * `CompactAssistContribution`
+* one registry or static tuple of known contributions
+* start with only `session_memory`
+* keep plugin discovery/runtime registration for later, after the static seam proves useful
diff --git a/.trellis/tasks/archive/2026-04/04-15-diagnose-module-upgrade-coupling/task.json b/.trellis/tasks/archive/2026-04/04-15-diagnose-module-upgrade-coupling/task.json
new file mode 100644
index 000000000..fffa7750a
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-diagnose-module-upgrade-coupling/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "diagnose-module-upgrade-coupling",
+  "name": "diagnose-module-upgrade-coupling",
+  "title": "brainstorm: diagnose module upgrade coupling",
+  "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": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-next-cycle-backlog-completion/prd.md b/.trellis/tasks/archive/2026-04/04-15-next-cycle-backlog-completion/prd.md
new file mode 100644
index 000000000..5d6309d5a
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-next-cycle-backlog-completion/prd.md
@@ -0,0 +1,243 @@
+# brainstorm: next-cycle backlog completion
+
+## Goal
+
+在 `Approach A MVP` 已由 `Stage 29` 收口之后，补齐一个 canonical 的 `next-cycle` backlog 规划 PRD，明确当前主线应如何看待 `release validation / PR cleanup`、`Stage 30-36 reserve`、以及已经归档但仍与 canonical 口径冲突的 `30A/30B` 历史工作，避免未来继续在“reserve work 已实现”与“reserve 尚未需要”之间来回漂移。
+
+## What I already know
+
+* `project-handoff.md` 明确写明当前推荐方向是 `release validation / PR cleanup for Approach A MVP`，不是立即开启新的主线 stage。
+* `project-handoff.md` 与 canonical roadmap 都明确写明 `Stage 30-36` 是 reserve only，只有在后续验证发现 concrete MVP gap 时才需要。
+* `Stage 29` 的 PRD 已明确：
+  - `H13/H14/H21/H22` deferred
+  - `H01-H22` 有显式状态
+  - `Stage 30-36 reserve` 当前不是必需
+* archived `04-15-next-cycle-phase-1-backlog-decisions/prd.md` 已做过一次 next-cycle phase-1 决策：
+  - 选择 `context pressure v2 / session-memory compaction`
+  - 首 slice 选择 `Deterministic Assist`
+* archived `30A/30B` 任务真实存在，并且 PRD 含有完成型 checkpoint：
+  - `30A`: module upgrade contribution seams
+  - `30B`: session-memory threshold local updates
+* 但 `30A/30B` 与 handoff/roadmap 的 canonical 口径存在冲突：
+  - 文档仍说 `Stage 30-36 reserve not currently required`
+  - 任务层则显示 `30A/30B` 已实现并归档
+* `cross-session memory` 仍是持续性产品要求，因此任何 next-cycle 选择都应说明是否直接/间接推进它。
+* 当前 active task `04-15-next-cycle-backlog-completion/` 之前缺失 `prd.md`，现在需要先补齐需求基线。
+
+## Assumptions (temporary)
+
+* 这次任务是规划/清单收口任务，不是新功能实现任务。
+* 需要一个 canonical next-cycle statement，说明“下一轮真正该做什么”与“哪些只是历史 reserve experiments”。
+* `H13/H14/H21/H22` 不应被此任务静默重开，除非出现新的 source-backed PRD。
+* `release validation / PR cleanup` 与 `next-cycle backlog planning` 需要明确先后关系，而不是混成同一类待办。
+
+## Open Questions
+
+* None after user choice:
+  - treat `30A/30B` as historical reserve experiments
+  - do not use them as the canonical starting point for current next-cycle mainline planning
+
+## Requirements (evolving)
+
+* 收集并对齐当前 next-cycle backlog 的 canonical 输入来源：
+  - `project-handoff.md`
+  - canonical roadmap
+  - `Stage 29` PRD
+  - archived `next-cycle phase 1 backlog decisions`
+  - archived `30A/30B`
+* 明确 `release validation / PR cleanup` 与 next-cycle implementation planning 的关系。
+* 明确 `30A/30B` 的 canonical status：
+  - accepted starting point
+  - historical reserve experiment
+  - superseded / non-canonical
+* 给出 next-cycle backlog 的分层结果：
+  - ready next
+  - reserve / conditional
+  - explicitly deferred until new product goal
+* 任何被保留或推荐的 next-cycle band 都必须写明：
+  - concrete function
+  - concrete benefit
+  - why now
+  - whether it advances cross-session memory directly, indirectly, or not at all
+* 将 `30A/30B` 归类为 historical reserve experiments：
+  - 保留 archive 证据
+  - 不作为当前 canonical next-cycle 起点
+  - 不以它们的已实现状态推翻 handoff/roadmap 对 `Stage 30-36 reserve` 的 current wording
+
+## Acceptance Criteria (evolving)
+
+* [x] 当前 next-cycle backlog 的 canonical 输入来源已列清。
+* [x] `30A/30B` 的 canonical status 已被明确记录。
+* [x] `release validation / PR cleanup` 与 next-cycle implementation planning 的关系已被明确记录。
+* [x] 存在一个清晰的 next-cycle backlog 分层结果。
+* [x] deferred / reserve / ready-next 的边界清晰，不会与 MVP closeout 口径冲突。
+
+## Research Notes
+
+### Canonical input set
+
+* `project-handoff.md`:
+  - current next recommended task is `release validation / PR cleanup for Approach A MVP`
+  - `Stage 30-36 reserve` is not currently required
+  - `H13/H14/H21/H22` remain in the next-cycle backlog unless reopened by a new source-backed PRD
+* `coding-deepgent-cc-core-highlights-roadmap.md`:
+  - `H13/H14/H21/H22` are deferred
+  - `Stage 29` is the MVP deferred-boundary closeout
+  - `Stage 30-36` are reserve-only for concrete MVP gaps
+* `Stage 29` PRD:
+  - MVP closeout is complete
+  - next-cycle backlog exists, but reserve work should not be treated as required
+* archived `next-cycle phase 1 backlog decisions` PRD:
+  - if implementation planning later resumes, the recommended first band is `context pressure v2 / session-memory compaction`
+  - the recommended first slice is `Deterministic Assist`
+* archived `30A/30B` PRDs:
+  - represent real reserve-band implementation experiments
+  - do not by themselves overrule current canonical handoff/roadmap wording
+
+### Current canonical tension
+
+* `Stage 29` PRD and `project-handoff.md` both say `Stage 30-36 reserve` is not currently required.
+* archived `30A/30B` show real implementation work happened in that reserve band.
+* User decision for this task: keep `30A/30B` as historical reserve experiments rather than promoting them into the current canonical next-cycle entrypoint.
+
+### Consequence of the chosen boundary
+
+* Current canonical next step remains:
+  - `release validation / PR cleanup for Approach A MVP`
+* Current canonical next-cycle planning should not assume:
+  - `30A/30B` are the accepted baseline
+  - `Stage 30+` already became the real active mainline
+* `30A/30B` remain useful as:
+  - evidence
+  - reusable design input
+  - historical experiments that may inform a future reopened PRD
+* `30A/30B` should not be treated as:
+  - binding product direction
+  - proof that Stage 30-36 are now canonically required
+
+### Canonical backlog layering
+
+**Ready next**
+
+* `release validation / PR cleanup for Approach A MVP`
+  - concrete function:
+    - run a broader validation pass when cost is acceptable
+    - review/stage accumulated Stage 18-29 work
+    - update PR `#220` or prepare the next PR boundary
+  - concrete benefit:
+    - verifies that the completed MVP closeout still holds under a broader check pass
+    - reduces ambiguity before any new implementation stage is reopened
+  - why now:
+    - this is the explicit next recommendation in `project-handoff.md`
+    - it preserves the Stage 29 closeout discipline
+  - cross-session memory impact:
+    - indirect only
+
+**Conditional next-cycle implementation candidate**
+
+* `context pressure v2 / session-memory compaction`
+  - concrete function:
+    - extend the current `compact + sessions + memory` seam with a bounded session-memory-assisted continuity path
+  - concrete benefit:
+    - improves context-efficiency and cross-session continuity without reopening coordinator/mailbox/platform breadth
+  - why later, not now:
+    - archived phase-1 backlog planning already recommends this direction
+    - but current handoff still places release validation/PR cleanup ahead of any new implementation restart
+  - cross-session memory impact:
+    - direct
+  - current canonical interpretation:
+    - best candidate if implementation planning resumes after closeout validation
+
+**Reserve / conditional**
+
+* `Stage 30-36 reserve` generally
+  - concrete function:
+    - optional follow-on hardening or experiments if validation finds a concrete MVP gap
+  - concrete benefit:
+    - preserves space for deeper follow-on work without forcing it into the current mainline
+  - why not now:
+    - canonical docs still say reserve is not currently required
+  - cross-session memory impact:
+    - depends on the reopened PRD
+* archived `30A/30B`
+  - concrete function:
+    - historical experiments around contribution seams and session-memory threshold updates
+  - concrete benefit:
+    - reusable evidence and design input if a future PRD reopens this band
+  - why not now:
+    - user chose not to promote them into the canonical entrypoint
+    - they conflict with current reserve wording if treated as active baseline
+  - cross-session memory impact:
+    - direct, but non-canonical for the current next step
+
+**Explicitly deferred until new product goal**
+
+* `H13 Mailbox / SendMessage`
+* `H14 Coordinator keeps synthesis`
+* `H21 Bridge / remote / IDE control plane`
+* `H22 Daemon / cron / proactive automation`
+  - concrete function:
+    - broader multi-agent, remote, or proactive runtime expansion
+  - concrete benefit:
+    - meaningful only when the product explicitly reopens those bands
+  - why not now:
+    - Stage 29 and the roadmap keep them deferred out of the current MVP path
+  - cross-session memory impact:
+    - not the current priority driver
+
+## Decision (ADR-lite)
+
+**Context**: Archived `30A/30B` contain completed implementation checkpoints, but current handoff/roadmap language still says `Stage 30-36` are reserve-only and not currently required. The task needs one explicit rule for future planning so the repo stops oscillating between these two signals.
+
+**Decision**: Treat `30A/30B` as historical reserve experiments. Preserve them in archive and use them as optional evidence only, not as the canonical starting point for current next-cycle mainline planning.
+
+**Consequences**:
+
+* `project-handoff.md` and the canonical roadmap remain the current source of truth for what is active next.
+* `release validation / PR cleanup` stays ahead of any new implementation-stage restart.
+* A future next-cycle implementation may still reuse ideas from `30A/30B`, but only through a fresh source-backed PRD that explicitly reopens the direction.
+* This avoids silently promoting reserve experiments into canonical product direction.
+
+## Technical Approach
+
+* Keep this task as a planning/documentation ledger, not an implementation task.
+* Use `project-handoff.md` as the primary current-state router:
+  - active next work = validation / PR cleanup
+  - later implementation candidate = bounded next-cycle planning
+* Treat archived `next-cycle phase 1 backlog decisions` as advisory input for a later implementation restart, not as a current-state override.
+* Treat archived `30A/30B` as optional evidence only.
+
+## Implementation Plan (planning-only)
+
+* Step 1: keep canonical next action fixed on `release validation / PR cleanup`.
+* Step 2: if validation later confirms the MVP closeout remains solid, reopen implementation planning through a fresh source-backed PRD.
+* Step 3: when implementation planning is reopened, start from:
+  - `context pressure v2 / session-memory compaction`
+  - first slice: `Deterministic Assist`
+  - optionally reuse `30A/30B` as evidence, but not as a binding baseline
+
+## Definition of Done (team quality bar)
+
+* Decision captured with evidence
+* Scope and non-goals are explicit
+* Follow-on implementation can start from this PRD without re-deriving the backlog boundary
+
+## Out of Scope (explicit)
+
+* 直接实现任何 next-cycle 产品代码
+* 自动重开 `Stage 30+` 的实现工作
+* 修改 `Approach A MVP` 边界
+* 为 tutorial/reference layer 补做无关规划
+
+## Technical Notes
+
+* Task dir: `.trellis/tasks/04-15-next-cycle-backlog-completion`
+* Canonical docs to inspect:
+  - `.trellis/project-handoff.md`
+  - `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+  - `.trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/prd.md`
+  - `.trellis/tasks/archive/2026-04/04-15-next-cycle-phase-1-backlog-decisions/prd.md`
+* Historical reserve docs to inspect:
+  - `.trellis/tasks/archive/2026-04/04-15-stage-30a-module-upgrade-contribution-seams/prd.md`
+  - `.trellis/tasks/archive/2026-04/04-15-stage-30b-session-memory-threshold-local-updates/prd.md`
+* Recent reconciliation already added reserve-policy notes to archived `30A/30B` task metadata so this task can build on that evidence rather than rediscover the conflict.
diff --git a/.trellis/tasks/archive/2026-04/04-15-next-cycle-backlog-completion/task.json b/.trellis/tasks/archive/2026-04/04-15-next-cycle-backlog-completion/task.json
new file mode 100644
index 000000000..97d0c26f5
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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": "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": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-next-cycle-phase-1-backlog-decisions/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-next-cycle-phase-1-backlog-decisions/check.jsonl
new file mode 100644
index 000000000..dfef835bc
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-next-cycle-phase-1-backlog-decisions/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/spec/backend/runtime-context-compaction-contracts.md", "reason": "Validate compaction contract changes"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-next-cycle-phase-1-backlog-decisions/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-next-cycle-phase-1-backlog-decisions/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-next-cycle-phase-1-backlog-decisions/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-next-cycle-phase-1-backlog-decisions/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-next-cycle-phase-1-backlog-decisions/implement.jsonl
new file mode 100644
index 000000000..839af22f2
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-next-cycle-phase-1-backlog-decisions/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/tasks/04-15-next-cycle-phase-1-backlog-decisions/prd.md", "reason": "Phase-1 deterministic assist PRD"}
+{"file": ".trellis/spec/backend/runtime-context-compaction-contracts.md", "reason": "Runtime compaction contract"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-next-cycle-phase-1-backlog-decisions/prd.md b/.trellis/tasks/archive/2026-04/04-15-next-cycle-phase-1-backlog-decisions/prd.md
new file mode 100644
index 000000000..d748f80f0
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-next-cycle-phase-1-backlog-decisions/prd.md
@@ -0,0 +1,431 @@
+# brainstorm: next-cycle phase 1 backlog decisions
+
+## Goal
+
+Decide what `next-cycle` should take as phase 1 after the Approach A MVP closeout, focusing first on three deferred backlog bands: `context pressure v2 / session-memory compaction`, `plugin lifecycle`, and `mailbox`. The chosen phase-1 band is `context pressure v2 / session-memory compaction`; the remaining goal is to lock its first implementation slice so it delivers concrete local benefit now without reopening broad coordinator/marketplace/background-runtime complexity by accident.
+
+## What I already know
+
+* User selected `context pressure v2 / session-memory compaction` as the next-cycle phase-1 direction.
+* User selected `Deterministic Assist` as the first slice inside `context pressure v2 / session-memory compaction`.
+* Stage 29 recorded the next-cycle backlog and explicitly deferred `H13 mailbox / SendMessage` and full `H17 plugin install/enable/update lifecycle`.
+* Stage 23 closed MVP `H05/H06` as deterministic projection/compact/session continuity, while explicitly deferring richer auto-compact and session-memory runtime breadth.
+* Stage 24 closed MVP `H07` as namespace-scoped durable memory with quality gating, while explicitly deferring session-memory extraction, compaction, snapshots, and memory file hooks.
+* Stage 27 closed MVP `H17` only as local manifest/source validation; install/enable lifecycle stayed deferred.
+* Current codebase already has strong local seams for `compact`, `sessions`, `memory`, `tasks`, `subagents`, and `plugins`, but no mailbox runtime or plugin state machine yet.
+* Cross-session memory is a persistent project requirement and future stages must state whether they advance it directly, indirectly, or not at all.
+
+## Assumptions (temporary)
+
+* Phase 1 should stay inside the chosen `context pressure v2 / session-memory compaction` band rather than split effort across the other deferred bands.
+* A good first slice should extend an existing strong seam rather than introduce a broad new runtime surface.
+* The first slice should preserve today's deterministic compact/session contracts and avoid background timing or extraction races.
+* `mailbox` likely has the largest dependency fan-out because it touches task ownership, subagent lifecycle, and later coordinator behavior.
+
+## Open Questions
+
+* None for phase-1 direction and first-slice scope.
+
+## Requirements
+
+* Produce a source-backed comparison of the three candidate backlog bands.
+* State the concrete function and local benefit of taking each band now.
+* Identify dependencies, risks, and likely MVP-sized phase-1 slices for each band.
+* Recommend a phase-1 direction with explicit non-goals and an initial ranked order.
+* Lock next-cycle phase 1 to `context pressure v2 / session-memory compaction`.
+* Define the first slice so it improves cross-session continuity and compaction quality without adding coordinator, mailbox, marketplace, or full background-agent runtime.
+* Lock the first slice to `Deterministic Assist`, not threshold-driven automatic updates or background extraction.
+
+## Acceptance Criteria
+
+* [x] Existing roadmap, handoff, spec, and stage PRDs relevant to the three backlog bands are inspected.
+* [x] Current repo state for the relevant modules is inspected.
+* [x] cc-haha source reference points are inspected for the three backlog bands.
+* [x] The PRD records feasible approaches and a recommended phase-1 choice.
+* [x] One high-value phase-1 direction decision is captured from the user.
+* [x] One final high-value scope question is resolved for the first `context pressure v2` slice.
+
+## 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)
+
+* Implementing the chosen phase-1 feature in this brainstorm task
+* Reopening Stage 29 MVP boundary or claiming all next-cycle items must start together
+* `plugin lifecycle` as a phase-1 implementation target
+* `mailbox` as a phase-1 implementation target
+* threshold-driven automatic session-memory updates in the first phase-1 slice
+* background extraction agent/runtime in the first phase-1 slice
+* UI/TUI, marketplace, remote bridge, daemon, or full coordinator planning unless required by one of the three bands
+
+## Expected Effect
+
+Choosing the right phase-1 band should improve: cross-session continuity, context-efficiency, and roadmap discipline. The local effect should be: the next stage lands on an already-strong product seam and creates visible capability gain without accidentally importing coordinator or marketplace breadth.
+
+## cc-haha Alignment
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Context pressure v2 / session-memory compaction | `sessionMemory.ts`, `sessionMemoryUtils.ts`, and `sessionMemoryCompact.ts` add threshold-gated extraction plus memory-assisted compaction on top of the compact/session flow | better long-session continuity and context pressure handling while preserving bounded deterministic recovery seams | extend `compact`, `sessions`, and `memory` with a smaller local session-memory-assisted compaction path | partial | Recommended phase 1 |
+| Plugin lifecycle | `installedPluginsManager.ts`, `pluginOperations.ts`, `pluginLoader.ts`, and plugin commands separate install metadata from enable state and manage scope/version/cache lifecycle | extension platform becomes operational rather than metadata-only | add local install/enable state model and startup/runtime resolution contracts | defer | Good phase 2 candidate |
+| Mailbox / SendMessage | `SendMessageTool.ts`, `teammateMailbox.ts`, `LocalAgentTask.tsx`, and coordinator mode add inbox delivery, pending messages, and resumable teammate task runtime | multi-agent collaboration becomes explicit and resumable | add durable inbox/message routing around `tasks` + `subagents` | defer | Too broad for phase 1 |
+
+### Boundary findings
+
+* `context pressure v2` directly advances the explicit project requirement for stronger cross-session memory/continuity.
+* `plugin lifecycle` improves completeness of the extension platform, but does not materially advance cross-session continuity.
+* `mailbox` is not just a tool addition; it depends on task-backed local-agent lifecycle and notification/runtime behavior that the local product does not yet own.
+
+## Research Notes
+
+### What the current repo already has
+
+* `compact` and `sessions` already support deterministic manual compaction, compact records, load-time compact selection, recovery brief rendering, and compact-aware resume.
+* `memory` already supports namespace-scoped durable memory, quality gating, and bounded middleware recall.
+* `plugins` currently stop at deterministic manifest/source validation and declaration checks; there is no install metadata store, enable-state model, or lifecycle command surface.
+* `tasks` and `subagents` already support durable task/plan records and bounded verifier execution, but child runtime is intentionally read-only/minimal and lacks mailbox or background message handling.
+
+### Constraints from our repo/project
+
+* The handoff states cross-session memory is a persistent product requirement.
+* Stage 29 already closed MVP with H13/H14/H21/H22 deferred; phase 1 should not silently reopen coordinator breadth.
+* Current compaction contracts are deterministic and test-heavy; adding opaque background automation too early would weaken that reliability story.
+* Current plugin implementation is local-only and schema-first; a lifecycle stage would require new persisted state and CLI/runtime surfaces, not just registry tweaks.
+
+### Feasible approaches here
+
+**Approach A: `context pressure v2 / session-memory compaction`** (Recommended)
+
+* How it works:
+  * add a small local session-memory artifact/update seam on top of the existing memory + compact + session stack
+  * keep the first slice deterministic and explicit, for example by producing a bounded session-memory summary/artifact that can assist continuation compaction without introducing a broad background runtime
+* Pros:
+  * strongest direct link to the cross-session memory requirement
+  * reuses the most mature existing seams
+  * can be staged without coordinator or marketplace side effects
+* Cons:
+  * needs careful boundary work so session memory does not become a second ad hoc transcript store
+  * a fully automatic background extractor should still stay out of the first slice
+
+### Feasible first slices inside Approach A
+
+**A1: Deterministic Assist** (Chosen)
+
+* How it works:
+  * introduce an explicit local session-memory artifact/update seam
+  * allow compact/resume flows to consume that artifact as a bounded assist when the user explicitly chooses the path or when a deterministic compact helper is invoked
+  * keep all timing and state transitions synchronous, local, and testable
+* Pros:
+  * lowest-risk extension of current compact/session contracts
+  * directly improves continuity without inventing a new background lifecycle
+  * easiest to prove with targeted contract tests
+* Cons:
+  * less automatic than upstream
+  * phase-1 user benefit is more bounded than a full reactive system
+
+**A2: Threshold-Triggered Local Updates**
+
+* How it works:
+  * add local token/tool-call thresholds that refresh session-memory artifacts automatically within the active runtime
+* Pros:
+  * moves closer to reactive context-pressure management
+  * more user-visible reduction of manual intervention
+* Cons:
+  * timing/state complexity appears immediately
+  * higher risk of drift with current deterministic compact/session invariants
+
+**A3: Background Extraction Path**
+
+* How it works:
+  * add a separate extraction/background execution path closer to cc-haha
+* Pros:
+  * strongest parity path
+* Cons:
+  * too much runtime expansion for phase 1
+  * easiest way to reopen deferred agent lifecycle/coordinator complexity
+
+**Approach B: `plugin lifecycle`**
+
+* How it works:
+  * add install metadata and per-scope enable/disable state, then teach startup/runtime loading to honor those states
+* Pros:
+  * makes H17 feel product-real rather than manifest-only
+  * can stay mostly inside extension/startup/settings surfaces
+* Cons:
+  * lower direct user value than continuity work
+  * quickly grows into cache/version/install/uninstall/update semantics
+  * has weaker connection to the persistent cross-session memory requirement
+
+**Approach C: `mailbox`**
+
+* How it works:
+  * add message delivery and pending inbox semantics between local agent tasks/subagents
+* Pros:
+  * highest visible step toward multi-agent parity
+  * unlocks later coordinator/team work
+* Cons:
+  * largest runtime surface increase
+  * depends on long-lived task objects, pending-message queues, and resumable agent lifecycle that are not currently local product seams
+  * easiest path to accidentally reopen deferred H14 coordinator complexity
+
+## Expansion Sweep
+
+### Future evolution
+
+* `context pressure v2` can later branch into threshold-based auto-compact, session-memory extraction, and agent-memory snapshots without changing the current compact/session contracts.
+* `plugin lifecycle` can later branch into marketplace trust, version updates, and richer install UX.
+* `mailbox` can later branch into coordinator synthesis, ownership transfer, and background worker orchestration.
+
+### Related scenarios
+
+* Any `context pressure v2` work should stay consistent with existing `sessions resume`, compact-record recovery, and memory middleware injection.
+* Any `plugin lifecycle` work should stay consistent with skills/MCP/hooks startup validation.
+* Any `mailbox` work should stay consistent with durable task ownership and verifier/subagent boundaries.
+
+### Failure & edge cases
+
+* `context pressure v2`: stale or low-quality session-memory artifacts, duplicate state between transcript and memory, invalid compact assists.
+* `plugin lifecycle`: orphaned installs, enabled-but-missing plugins, scope precedence drift, partial update failures.
+* `mailbox`: lost messages, duplicate delivery, unread-state drift, background task lifetime mismatches.
+
+## Technical Approach
+
+Recommended next-cycle phase-1 direction:
+
+* Choose `Approach A: context pressure v2 / session-memory compaction`.
+* Keep the first slice smaller than upstream:
+  * include: explicit local session-memory artifact/update boundary, deterministic compact-assist integration, deterministic tests over artifact shape and recovery/continuity behavior
+  * exclude: threshold-driven automatic updates, full background extraction agent, remote config, coordinator, agent mailbox, and provider-specific cache behavior
+* Initial ranked order:
+  1. `context pressure v2 / session-memory compaction`
+  2. `plugin lifecycle`
+  3. `mailbox`
+* Chosen first slice inside phase 1:
+  1. `A1: Deterministic Assist`
+  2. `A2: Threshold-Triggered Local Updates`
+  3. `A3: Background Extraction Path`
+
+## Decision (ADR-lite)
+
+**Context**: Stage 29 closed the MVP and moved several broad capabilities into next-cycle. The project now needs a first follow-on stage that creates concrete product value without reopening a large runtime redesign.
+
+**Decision**: Recommend starting next-cycle phase 1 with `context pressure v2 / session-memory compaction`, not `plugin lifecycle` or `mailbox`.
+
+Confirmed by user: yes.
+
+Follow-up scope decision: choose `Deterministic Assist` as the first slice inside phase 1.
+
+**Consequences**:
+
+* Positive:
+  * directly advances the persistent cross-session memory requirement
+  * builds on already-strong local seams (`compact`, `sessions`, `memory`)
+  * keeps next-cycle phase 1 inside a bounded infra slice rather than platform/runtime expansion
+  * preserves the current deterministic compact/session contract while still opening a path toward richer session-memory behavior later
+* Trade-offs:
+  * the first slice stays smaller than cc-haha's background session-memory system
+  * threshold/reactive behavior is intentionally postponed
+  * plugin lifecycle remains visibly incomplete for one more phase
+  * mailbox/coordinator readiness remains deferred until task-backed agent lifecycle is a deliberate goal
+
+## Implementation Plan (small PRs)
+
+* PR1: add session-memory artifact schema/boundary and fixture-level contract tests
+* PR2: integrate deterministic compact-assist consumption into compact/resume path with regression coverage
+* PR3: document deferred threshold/background follow-up and harden edge-case tests around stale/empty/invalid artifacts
+
+## Checkpoint: Sub-stage 1 Artifact Boundary
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added a strict `session_memory` artifact boundary under `coding_deepgent.sessions`.
+- Allowed state snapshots to roundtrip a valid session-memory artifact while ignoring invalid artifacts.
+- Added an explicit CLI update seam via `sessions resume --session-memory ...` so a resumed run can persist deterministic session memory without adding a background runtime.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_cli.py`
+- `ruff check coding-deepgent/src/coding_deepgent/sessions/session_memory.py coding-deepgent/src/coding_deepgent/runtime/state.py coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py coding-deepgent/src/coding_deepgent/sessions/__init__.py coding-deepgent/src/coding_deepgent/cli.py coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_cli.py`
+- `mypy coding-deepgent/src/coding_deepgent/sessions/session_memory.py coding-deepgent/src/coding_deepgent/runtime/state.py coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py coding-deepgent/src/coding_deepgent/sessions/__init__.py coding-deepgent/src/coding_deepgent/cli.py coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_cli.py`
+
+cc-haha alignment:
+- Source files 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/compact/sessionMemoryCompact.ts`
+- Aligned:
+  - session memory is treated as an explicit artifact with its own boundary, not as ad hoc prompt text.
+- Deferred:
+  - threshold-driven updates
+  - background extraction runtime
+- Do-not-copy:
+  - remote-config and background-session machinery in the first slice
+
+LangChain architecture:
+- Primitive used:
+  - strict Pydantic artifact model plus existing session state snapshot seam
+- Why no heavier abstraction:
+  - the first slice only needed a persisted bounded artifact and explicit CLI update path
+
+Boundary findings:
+- New issue:
+  - compact/resume paths still do not consume the artifact yet
+- Impact on next stage:
+  - sub-stage 2 remains valid and should integrate the artifact into recovery/resume and generated compaction only
+
+Decision:
+- continue
+
+Reason:
+- The artifact boundary is stable, tested, and small. The next sub-stage still holds without requiring a plan rewrite.
+
+## Checkpoint: Sub-stage 2 Resume And Compact Assist Integration
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Recovery briefs and resume context now render `session_memory` when present.
+- Generated compact summary requests now consume a current session-memory artifact as a bounded assist.
+- Added regressions proving the CLI path can persist session memory and that generated compaction receives the assist text only through the intended seam.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_cli.py coding-deepgent/tests/test_compact_summarizer.py`
+- `ruff check coding-deepgent/src/coding_deepgent/sessions/resume.py coding-deepgent/src/coding_deepgent/compact/summarizer.py coding-deepgent/src/coding_deepgent/cli_service.py coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_cli.py coding-deepgent/tests/test_compact_summarizer.py`
+- `mypy coding-deepgent/src/coding_deepgent/sessions/resume.py coding-deepgent/src/coding_deepgent/compact/summarizer.py coding-deepgent/src/coding_deepgent/cli_service.py coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_cli.py coding-deepgent/tests/test_compact_summarizer.py`
+
+cc-haha alignment:
+- Source files inspected:
+  - `/root/claude-code-haha/src/services/SessionMemory/sessionMemory.ts`
+  - `/root/claude-code-haha/src/services/compact/sessionMemoryCompact.ts`
+- Aligned:
+  - session memory now influences compaction continuity rather than living only as inert state
+- Deferred:
+  - automatic thresholds and reactive refresh
+- Do-not-copy:
+  - background extraction side-agent and remote-growthbook wiring in this slice
+
+LangChain architecture:
+- Primitive used:
+  - existing recovery brief and compact-summary request builders with one extra bounded assist input
+- Why no heavier abstraction:
+  - the product benefit came from consuming the artifact at two deterministic seams, not from a new middleware/runtime layer
+
+Boundary findings:
+- New issue:
+  - stale artifacts still need an explicit policy so generated compaction does not over-trust them
+- Impact on next stage:
+  - sub-stage 3 should harden stale/empty/invalid artifact policy and update contracts
+
+Decision:
+- continue
+
+Reason:
+- Integration stayed small and passed focused validation. The remaining work is hardening/documentation, not a plan change.
+
+## Checkpoint: Sub-stage 3 Edge Hardening And Contracts
+
+State:
+- terminal
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Hardened stale-session-memory policy so generated compact summary ignores stale artifacts while recovery briefs still surface them as `[stale]`.
+- Added negative-path regressions for blank CLI session-memory input and stale-assist suppression.
+- Updated the runtime context and compaction contract doc to include the new session-memory CLI/state/assist rules.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_cli.py coding-deepgent/tests/test_compact_summarizer.py`
+- `ruff check coding-deepgent/src/coding_deepgent/sessions/session_memory.py coding-deepgent/src/coding_deepgent/sessions/resume.py coding-deepgent/src/coding_deepgent/compact/summarizer.py coding-deepgent/src/coding_deepgent/cli_service.py coding-deepgent/src/coding_deepgent/cli.py coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_cli.py coding-deepgent/tests/test_compact_summarizer.py`
+- `mypy coding-deepgent/src/coding_deepgent/sessions/session_memory.py coding-deepgent/src/coding_deepgent/sessions/resume.py coding-deepgent/src/coding_deepgent/compact/summarizer.py coding-deepgent/src/coding_deepgent/cli_service.py coding-deepgent/src/coding_deepgent/cli.py coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_cli.py coding-deepgent/tests/test_compact_summarizer.py`
+
+cc-haha alignment:
+- Source files inspected:
+  - `/root/claude-code-haha/src/services/SessionMemory/sessionMemoryUtils.ts`
+  - `/root/claude-code-haha/src/services/compact/sessionMemoryCompact.ts`
+- Aligned:
+  - stale/current distinction is now explicit at the local artifact boundary
+  - compaction assistance stays bounded and continuity-oriented
+- Deferred:
+  - threshold scheduling
+  - extraction wait/runtime lifecycle
+- Do-not-copy:
+  - background extraction waiting, remote config initialization, and broader automation
+
+LangChain architecture:
+- Primitive used:
+  - strict state artifact plus existing recovery/summary builders and contract tests
+- Why no heavier abstraction:
+  - the slice is complete without new middleware, stores, or child-agent orchestration
+
+Boundary findings:
+- New issue:
+  - none that require another prerequisite stage for this slice
+- Impact on next stage:
+  - later `Threshold-Triggered Local Updates` can build on the same artifact shape without changing the persisted boundary
+
+Decision:
+- terminal
+
+Reason:
+- The chosen Deterministic Assist slice is implemented, documented, and validated. The next planned work is a new stage, not a continuation of this one.
+
+## Technical Notes
+
+* Trellis context: `.trellis/workflow.md`, `.trellis/project-handoff.md`
+* Canonical dashboard: `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+* Relevant prior stages:
+  * `.trellis/tasks/archive/2026-04/04-15-stage-23-context-pressure-and-session-continuity-closeout/prd.md`
+  * `.trellis/tasks/archive/2026-04/04-15-stage-24-scoped-memory-closeout/prd.md`
+  * `.trellis/tasks/archive/2026-04/04-15-stage-27-local-extension-platform-closeout/prd.md`
+  * `.trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/prd.md`
+* Current product seams:
+  * `coding-deepgent/src/coding_deepgent/compact/`
+  * `coding-deepgent/src/coding_deepgent/memory/`
+  * `coding-deepgent/src/coding_deepgent/sessions/`
+  * `coding-deepgent/src/coding_deepgent/plugins/`
+  * `coding-deepgent/src/coding_deepgent/tasks/`
+  * `coding-deepgent/src/coding_deepgent/subagents/`
+* Current repo files inspected:
+  * `coding-deepgent/src/coding_deepgent/compact/artifacts.py`
+  * `coding-deepgent/src/coding_deepgent/compact/summarizer.py`
+  * `coding-deepgent/src/coding_deepgent/memory/tools.py`
+  * `coding-deepgent/src/coding_deepgent/memory/policy.py`
+  * `coding-deepgent/src/coding_deepgent/memory/middleware.py`
+  * `coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py`
+  * `coding-deepgent/src/coding_deepgent/sessions/service.py`
+  * `coding-deepgent/src/coding_deepgent/plugins/schemas.py`
+  * `coding-deepgent/src/coding_deepgent/plugins/loader.py`
+  * `coding-deepgent/src/coding_deepgent/plugins/registry.py`
+  * `coding-deepgent/src/coding_deepgent/extensions_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`
+* cc-haha files 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/compact/sessionMemoryCompact.ts`
+  * `/root/claude-code-haha/src/tools/AgentTool/agentMemorySnapshot.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/pluginIdentifier.ts`
+  * `/root/claude-code-haha/src/utils/plugins/pluginLoader.ts`
+  * `/root/claude-code-haha/src/utils/teammateMailbox.ts`
+  * `/root/claude-code-haha/src/tools/SendMessageTool/SendMessageTool.ts`
+  * `/root/claude-code-haha/src/tasks/LocalAgentTask/LocalAgentTask.tsx`
+  * `/root/claude-code-haha/src/coordinator/coordinatorMode.ts`
diff --git a/.trellis/tasks/archive/2026-04/04-15-next-cycle-phase-1-backlog-decisions/task.json b/.trellis/tasks/archive/2026-04/04-15-next-cycle-phase-1-backlog-decisions/task.json
new file mode 100644
index 000000000..4f5446a3a
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-next-cycle-phase-1-backlog-decisions/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "next-cycle-phase-1-backlog-decisions",
+  "name": "next-cycle-phase-1-backlog-decisions",
+  "title": "brainstorm: next-cycle phase 1 backlog decisions",
+  "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": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-opencode-style-auto-tool-output-prune/prd.md b/.trellis/tasks/archive/2026-04/04-15-opencode-style-auto-tool-output-prune/prd.md
new file mode 100644
index 000000000..a6e98b547
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-opencode-style-auto-tool-output-prune/prd.md
@@ -0,0 +1,70 @@
+# opencode-style auto tool output prune
+
+## Goal
+
+占位规划一个未来增强：把当前 `MicroCompact` 的旧工具输出清理能力，升级为更接近 opencode `SessionCompaction.prune()` 的自动工具输出 pruning 策略。当前只记录任务和范围，不在本轮实现。
+
+## Background
+
+当前 `coding-deepgent` 已有 MVP 级 Auto Tool Output Prune：
+
+* `RuntimePressureMiddleware` 每次 model call 前运行 `microcompact_messages(...)`。
+* 只处理 eligible successful `ToolMessage`。
+* 保留最近 `keep_recent_tool_results` 个 compactable tool results。
+* 更旧结果替换为 `[Old tool result content cleared]`。
+* 若结果 artifact 有 persisted output path，则保留该 path。
+* 这是 live rewrite，不直接持久化 transcript。
+
+opencode 的 `SessionCompaction.prune()` 提供了更强的参考策略：
+
+* 从最新消息往旧消息倒序扫描。
+* 至少保护最近两个 user turns。
+* 遇到 assistant summary 或已 compacted tool output 时停止。
+* 跳过 protected tools，例如 `skill`。
+* 统计 completed tool output tokens。
+* 保留最近约 `PRUNE_PROTECT = 40_000` tokens 的工具输出。
+* 只有预计释放超过 `PRUNE_MINIMUM = 20_000` tokens 时才执行。
+* 将旧 tool part 标记为 compacted，渲染给模型时输出 `[Old tool result content cleared]`。
+
+## Requirements (Future)
+
+* Replace or extend count-based `keep_recent_tool_results` with token-budget based protection.
+* Add a minimum estimated-token savings threshold before pruning.
+* Preserve tool-call/tool-result pairing and current persisted-output path behavior.
+* Keep protected tool outputs unpruned through capability metadata or explicit config.
+* Decide whether pruning remains live-only or persists a compacted marker/state.
+* Keep behavior LangChain-native and inside runtime pressure/session boundaries.
+
+## Acceptance Criteria (Future)
+
+* [ ] Old completed eligible tool outputs beyond protected recent-token budget are pruned.
+* [ ] Recent protected-token window remains inline.
+* [ ] Protected tools are never pruned.
+* [ ] No pruning happens when estimated savings are below threshold.
+* [ ] Persisted output paths remain model-visible after pruning.
+* [ ] Existing `MicroCompact` tests either remain valid or are replaced by stronger budget-based tests.
+* [ ] Runtime pressure contracts are updated with executable signatures, matrix, and tests.
+
+## Out of Scope (Current)
+
+* No implementation in this turn.
+* No cc-style semantic SnipTool.
+* No physical deletion of session transcript records.
+* No provider-specific exact tokenizer integration unless separately approved.
+
+## Technical Notes
+
+* Candidate files:
+  * `coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py`
+  * `coding-deepgent/src/coding_deepgent/tool_system/capabilities.py`
+  * `coding-deepgent/src/coding_deepgent/settings.py`
+  * `coding-deepgent/tests/test_runtime_pressure.py`
+  * `.trellis/spec/backend/runtime-pressure-contracts.md`
+* Reference:
+  * `sst/opencode`: `packages/opencode/src/session/compaction.ts`
+  * `sst/opencode`: `packages/opencode/src/session/message-v2.ts`
+  * `sst/opencode`: `packages/opencode/src/tool/truncate.ts`
+
+## Status
+
+Planning-only placeholder. Current MVP remains the existing `MicroCompact`.
diff --git a/.trellis/tasks/archive/2026-04/04-15-opencode-style-auto-tool-output-prune/task.json b/.trellis/tasks/archive/2026-04/04-15-opencode-style-auto-tool-output-prune/task.json
new file mode 100644
index 000000000..e98db64da
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-opencode-style-auto-tool-output-prune/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "opencode-style-auto-tool-output-prune",
+  "name": "opencode-style-auto-tool-output-prune",
+  "title": "opencode-style auto tool output prune",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-15",
+  "completedAt": "2026-04-17",
+  "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-16-context-compression-staged-implementation-plan",
+  "relatedFiles": [],
+  "notes": "Superseded by Stage 1 time-based microcompact + token-budget tool-output prune under parent plan 04-16-context-compression-staged-implementation-plan. opencode-specific semantics not needed; functional equivalent shipped. Closing as completed to avoid ledger drift.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-release-validation-pr-cleanup/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-release-validation-pr-cleanup/check.jsonl
new file mode 100644
index 000000000..1bf90c1fd
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-release-validation-pr-cleanup/check.jsonl
@@ -0,0 +1,7 @@
+{"file": ".cursor/commands/trellis-finish-work.md", "reason": "Finish work checklist"}
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
+{"file": ".trellis/project-handoff.md", "reason": "Ensure release-facing cleanup remains aligned with canonical next direction"}
+{"file": ".trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md", "reason": "Check MVP boundary and deferred rows remain unchanged"}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Review and validation checklist for current pass"}
+{"file": ".trellis/spec/backend/runtime-context-compaction-contracts.md", "reason": "Check runtime/session/compact closeout behavior against contracts"}
+{"file": ".trellis/spec/backend/task-workflow-contracts.md", "reason": "Check durable task/subagent/verifier behavior against contracts"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-release-validation-pr-cleanup/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-release-validation-pr-cleanup/debug.jsonl
new file mode 100644
index 000000000..e30f96d49
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-release-validation-pr-cleanup/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-release-validation-pr-cleanup/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-release-validation-pr-cleanup/implement.jsonl
new file mode 100644
index 000000000..a266f62df
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-release-validation-pr-cleanup/implement.jsonl
@@ -0,0 +1,12 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Validation scope and review expectations for current mainline"}
+{"file": ".trellis/project-handoff.md", "reason": "Canonical current-state router and next recommended task"}
+{"file": ".trellis/spec/backend/langchain-native-guidelines.md", "reason": "Keep any fixes within current LangChain-native boundaries"}
+{"file": ".trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md", "reason": "Canonical MVP boundary and highlight status dashboard"}
+{"file": ".trellis/spec/backend/runtime-context-compaction-contracts.md", "reason": "Runtime/session/compact validation boundary overview"}
+{"file": "coding-deepgent/tests/test_runtime_pressure.py", "reason": "High-signal runtime pressure and reactive compact regression slice"}
+{"file": ".trellis/spec/backend/task-workflow-contracts.md", "reason": "Durable task and verifier workflow contracts for Stage 17-29 closeout"}
+{"file": "coding-deepgent/tests/test_subagents.py", "reason": "Verifier child-agent execution and evidence lineage regression slice"}
+{"file": "coding-deepgent/tests/test_tasks.py", "reason": "Durable task and verification workflow regression slice"}
+{"file": "coding-deepgent/tests/test_cli.py", "reason": "High-signal resume and compact continuity regression slice"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-release-validation-pr-cleanup/prd.md b/.trellis/tasks/archive/2026-04/04-15-release-validation-pr-cleanup/prd.md
new file mode 100644
index 000000000..5d455fdea
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-release-validation-pr-cleanup/prd.md
@@ -0,0 +1,87 @@
+# release validation and pr cleanup for approach a mvp
+
+## Goal
+
+Run a focused release-validation and PR-cleanup pass for the current
+`coding-deepgent` Approach A MVP closeout so the branch state, tests, and
+canonical Trellis docs are consistent before any new next-cycle implementation
+work begins.
+
+## Requirements
+
+- Validate the current mainline against the canonical MVP closeout docs:
+  - `.trellis/project-handoff.md`
+  - `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+  - relevant backend contract specs under `.trellis/spec/backend/`
+- Run focused product validation on the most relevant `coding-deepgent` test
+  slices and static checks for touched/risky domains.
+- Identify release/PR cleanup gaps:
+  - failing checks
+  - doc/status mismatches
+  - obviously stale or conflicting task/plan/task-status artifacts
+- Fix issues directly when the fix is scoped and low-risk.
+- If a broader or riskier issue appears, document it clearly instead of
+  reopening unrelated implementation work.
+- Keep `Stage 30-36` reserve work deferred unless validation exposes a concrete
+  MVP gap.
+
+## Acceptance Criteria
+
+- [x] Relevant specs and canonical roadmap docs are re-read and recorded in task context.
+- [x] Focused validation is run against the current `coding-deepgent` surface.
+- [x] Any discovered blockers are either fixed or documented with clear follow-up.
+- [x] PR/release-facing cleanup items are reconciled with current Trellis canonical wording.
+- [x] The task ends with a concise status summary of MVP readiness and remaining risks.
+
+## Technical Notes
+
+- Current branch: `codex/stage-12-14-context-compact-foundation`
+- Current recommended direction from handoff:
+  - release validation / PR cleanup for Approach A MVP
+- Explicit non-goal:
+  - do not silently restart new feature-stage implementation during this task
+
+## Validation Results
+
+- Canonical docs re-read:
+  - `.trellis/project-handoff.md`
+  - `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+  - `.trellis/spec/backend/quality-guidelines.md`
+  - `.trellis/spec/backend/langchain-native-guidelines.md`
+  - `.trellis/spec/backend/runtime-context-compaction-contracts.md`
+  - `.trellis/spec/backend/task-workflow-contracts.md`
+- PR metadata refreshed:
+  - draft PR `#220`
+  - head: `codex/stage-12-14-context-compact-foundation`
+  - base: `main`
+- Product validation passed:
+  - `python3 -m pytest tests -q` -> `256 passed`
+  - `python3 -m ruff check src tests` -> passed
+  - `python3 -m mypy src` -> `Success: no issues found in 106 source files`
+- Release-facing doc cleanup applied:
+  - `coding-deepgent/README.md`
+  - `coding-deepgent/PROJECT_PROGRESS.md`
+  - change type: clarify that `stage-11` remains a product-local compatibility
+    anchor while canonical live MVP status now lives in Trellis and is complete
+    through `Stage 29`
+- Contract regression after doc cleanup passed:
+  - `python3 -m pytest tests/test_runtime_foundation_contract.py tests/test_contract.py tests/test_structure.py -q` -> `14 passed`
+
+## Outcome Summary
+
+- No product-code blocker was found in the current Approach A MVP closeout line.
+- The local product test suite and static checks passed cleanly.
+- The main release-facing ambiguity found in this pass was documentation wording:
+  `README.md` and `PROJECT_PROGRESS.md` still exposed the legacy `stage-11`
+  compatibility anchor without making the Trellis live-status boundary explicit
+  enough.
+- That ambiguity was reduced without changing the product-local stage marker or
+  `project_status.json` contract.
+
+## Remaining Risks
+
+- `coding-deepgent/project_status.json` and the product-local `stage-11`
+  compatibility anchor remain intentionally unchanged because current contract
+  tests and settings surfaces depend on them.
+- Canonical live progress should continue to be read from Trellis, not inferred
+  from the product-local stage marker alone.
diff --git a/.trellis/tasks/archive/2026-04/04-15-release-validation-pr-cleanup/task.json b/.trellis/tasks/archive/2026-04/04-15-release-validation-pr-cleanup/task.json
new file mode 100644
index 000000000..62d598607
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-release-validation-pr-cleanup/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "release-validation-pr-cleanup",
+  "name": "release-validation-pr-cleanup",
+  "title": "release validation and pr cleanup for approach a mvp",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "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": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-runtime-context-pressure-management/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-runtime-context-pressure-management/check.jsonl
new file mode 100644
index 000000000..0d86f0daa
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-runtime-context-pressure-management/check.jsonl
@@ -0,0 +1,4 @@
+{"file": ".cursor/commands/trellis-finish-work.md", "reason": "Finish work checklist"}
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
+{"file": ".trellis/spec/guides/cross-layer-thinking-guide.md", "reason": "Review layer-boundary correctness for tool result storage and compact flow."}
+{"file": ".trellis/spec/backend/runtime-context-compaction-contracts.md", "reason": "Verify runtime/session/compact invariants after implementation."}
diff --git a/.trellis/tasks/archive/2026-04/04-15-runtime-context-pressure-management/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-runtime-context-pressure-management/debug.jsonl
new file mode 100644
index 000000000..e30f96d49
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-runtime-context-pressure-management/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-runtime-context-pressure-management/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-runtime-context-pressure-management/implement.jsonl
new file mode 100644
index 000000000..137b4729e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-runtime-context-pressure-management/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-runtime-context-pressure-management/prd.md b/.trellis/tasks/archive/2026-04/04-15-runtime-context-pressure-management/prd.md
new file mode 100644
index 000000000..05c2ebeeb
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-runtime-context-pressure-management/prd.md
@@ -0,0 +1,940 @@
+# brainstorm: runtime context pressure management
+
+## Goal
+
+Plan and implement a cc-haha-aligned runtime context pressure management upgrade for `coding-deepgent` so long-running sessions can keep working under context pressure through live runtime mechanisms, not only through explicit resume-time compact helpers. The target is to prioritize the highest-value cc context/compact behaviors and avoid spending time on tutorial-shell parity or low-value edge embellishments.
+
+## What I already know
+
+* The user clarified that `agents/*.py` tutorial chapters are feature previews only, not the product target.
+* The user wants `coding-deepgent` to prioritize cc-haha "feature highlights" rather than continuing to accumulate edge features that are weaker product differentiators.
+* For the current context/compact band, the user accepted this initial priority order:
+  * tool result storage
+  * microcompact
+  * live auto-compact
+  * post-compact restoration
+  * defer session-memory compact to a later pass
+* Current `coding-deepgent` already has:
+  * prompt/context payload seams
+  * tool-result truncation budget helper
+  * compact artifact helpers
+  * persisted compact transcript records
+  * load-time compacted history selection
+  * recovery brief and session memory assist/update seams
+* Current `coding-deepgent` does not yet appear to have:
+  * live tool-result persistence with preview references
+  * live microcompact in the query loop
+  * live auto-compact in the query loop
+  * post-compact restoration attachments
+* Existing roadmap/dashboard says H05/H06/H20 minimal slices are implemented for MVP, but recent review suggests the cc-haha high-value runtime context pressure loop still has meaningful gaps that may justify a focused next-cycle stage rather than more edge behavior.
+
+## Assumptions (temporary)
+
+* The immediate deliverable should be a narrow staged product task, not a broad redesign of all prompt/context/memory code.
+* The preferred implementation should reuse current `coding-deepgent` domains (`compact`, `sessions`, `runtime`, `tool_system`, `memory`) instead of adding a new runtime subsystem.
+* `session-memory compact` is valid but should stay out of the first implementation slice unless earlier sub-stages reveal it is required to make the core flow coherent.
+* The current work should target product code in `coding-deepgent/`, not the tutorial or `agents_deepagents/` tracks.
+
+## Open Questions
+
+* None after scope confirmation. The user explicitly chose the full task family:
+  * tool result storage
+  * microcompact
+  * live auto-compact
+  * post-compact restoration
+  * reactive compact
+  * session-memory compact
+
+## Requirements (evolving)
+
+* Align the context/compact work against cc-haha source behavior, not tutorial chapter shells.
+* State the expected effect of each proposed sub-stage before implementation.
+* Preserve LangChain/LangGraph as the runtime boundary.
+* Prioritize the highest-value runtime context pressure behaviors:
+  * tool result storage
+  * microcompact
+  * live auto-compact
+  * post-compact restoration
+  * reactive compact
+  * session-memory compact
+* Keep scope narrow and avoid unrelated resume/CLI polish unless it directly supports the runtime pressure loop.
+* Update executable backend contracts if model-visible or cross-layer compact/runtime behavior changes.
+* Use staged checkpoints so later sub-stages can be adjusted if earlier ones change the boundary.
+* Preserve existing Stage 12A/12B/12C/12D foundations and build on them rather than reopening payload/projection/recovery/memory-quality work.
+
+## Acceptance Criteria (evolving)
+
+* [ ] A source-backed cc-haha alignment matrix exists for the selected context pressure features.
+* [ ] The PRD identifies the concrete benefit and LangChain-native boundary for each planned sub-stage.
+* [ ] The first implementation slice excludes tutorial-shell parity work that lacks concrete runtime value.
+* [ ] The staged plan names explicit out-of-scope items beyond the six selected compact/runtime behaviors.
+* [ ] The staged plan identifies focused tests and checkpoint conditions per sub-stage.
+* [ ] The staged plan identifies the smallest LangChain-native interception points for tool-result pressure handling and model-call pressure handling.
+* [ ] The staged plan breaks the broader family into checkpointed sub-stages rather than one unreviewable implementation blob.
+
+## 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)
+
+* Reproducing the tutorial `s06_context_compact.py` shell for its own sake
+* Adding a model-visible `compact` tool solely for chapter parity
+* Expanding recovery brief presentation without direct runtime benefit
+* Broad prompt/context redesign outside the targeted context pressure loop
+* Compact/recovery work that only adds presentation or tutorial parity without strengthening the runtime pressure loop
+
+## Technical Notes
+
+* New task: `.trellis/tasks/04-15-runtime-context-pressure-management`
+* Likely product modules:
+  * `coding-deepgent/src/coding_deepgent/compact/*`
+  * `coding-deepgent/src/coding_deepgent/sessions/*`
+  * `coding-deepgent/src/coding_deepgent/runtime/*`
+  * `coding-deepgent/src/coding_deepgent/tool_system/*`
+  * `coding-deepgent/src/coding_deepgent/memory/*`
+* Existing contracts to revisit if scope becomes executable:
+  * `.trellis/spec/backend/runtime-context-compaction-contracts.md`
+* Existing planning/history likely relevant:
+  * `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+  * `.trellis/plans/coding-deepgent-h01-h10-target-design.md`
+  * prior Stage 12/13/16 compact PRDs
+* Primary cc-haha source bands already identified:
+  * `src/utils/queryContext.ts`
+  * `src/utils/attachments.ts`
+  * `src/utils/toolResultStorage.ts`
+  * `src/query.ts`
+  * `src/services/compact/microCompact.ts`
+  * `src/services/compact/autoCompact.ts`
+  * `src/services/compact/compact.ts`
+  * `src/services/compact/sessionMemoryCompact.ts`
+
+## Complexity
+
+Complex.
+
+Reasons:
+
+* multiple product modules are involved
+* the work changes runtime behavior rather than isolated helpers
+* there are several valid staging choices
+* correctness and boundary preservation matter more than raw feature count
+
+## Expected Effect
+
+Aligning this feature band should improve context-efficiency, reliability, recoverability, and product parity.
+
+The local runtime effect is:
+
+* large tool outputs stop bloating the live model context
+* older low-value tool results can be compacted without breaking tool-use/tool-result invariants
+* the agent can stay alive under context pressure during a live invocation instead of relying mainly on explicit resume-time compact helpers
+* compacted continuations retain the minimum working context needed to continue coding
+
+If these effects do not appear in focused runtime tests, the change is not worth shipping.
+
+## LangChain Guard
+
+Surface:
+
+* middleware
+* tool result handling
+* compact/runtime services
+* tests
+
+Primary boundary:
+
+* product code in `coding-deepgent/`
+
+Smallest viable change:
+
+* add one cross-cutting tool-result pressure seam and one model-call pressure seam
+* reuse existing `context_payloads`, `compact`, `sessions`, and `RuntimeContext`
+* avoid a custom query runtime
+
+## cc-haha Alignment
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Cache-safe prefix split | `src/utils/queryContext.ts` splits default system prompt, user context, and system context for stable prefix assembly | keep stable prompt/context prefix and isolate dynamic pressure logic from core prompt | keep current `PromptContext` / runtime context split; do not redesign base prompt | partial | Reuse current boundary; do not make this task a prompt rewrite |
+| Dynamic attachment protocol | `src/utils/attachments.ts` treats files, memories, plan/task reminders, compaction reminders, session memory, and restoration hints as typed dynamic context, not raw prompt concatenation | compact/restoration logic can re-inject critical context after pressure events | build on existing `ContextPayload` seam for post-compact restoration rather than cloning full attachment unions | partial | Align the restoration principle, not the full attachment catalog |
+| Large tool result spill-to-disk | `src/utils/toolResultStorage.ts` persists oversized tool results to session-scoped files and returns preview references | live runtime stops carrying giant tool outputs while preserving full output retrievability | add tool-result persistence + preview reference seam for selected large-output tools | align | Implement now |
+| Microcompact before full compact | `src/services/compact/microCompact.ts` clears older compactable tool results first and preserves API invariants | lower-cost pressure relief before full summarization; fewer unnecessary compactions | add deterministic live microcompact over model-call message history | align | Implement now |
+| Auto-compact in query loop | `src/query.ts` + `src/services/compact/autoCompact.ts` proactively compact when context crosses thresholds | live invocations stay recoverable under pressure, not only resumed sessions | add live threshold-triggered compact in LangChain-native runtime seam | align | Implement now |
+| Session-memory-first compact | `src/services/compact/sessionMemoryCompact.ts` uses session memory as a preferred compaction summary when available | smarter compaction with better continuity after long sessions | reuse and extend existing session-memory assist/update into a live compact path | align | Implement after earlier compact stages stabilize |
+| Post-compact restoration | `src/services/compact/compact.ts` restores key file/plan/skill/agent context after compaction | compacted continuation retains enough working context to keep coding | add bounded post-compact restoration using current payload/recovery seams | align | Implement now |
+| Reactive prompt-too-long fallback | `src/query.ts` also has prompt-too-long recovery paths beyond proactive auto-compact | hard failure fallback if proactive pressure handling misses | add a focused reactive fallback stage after proactive compact is in place | align | Implement in the same task family, but after proactive compact |
+
+### Non-goals
+
+* Do not clone `cc-haha`'s full attachment union, query loop, or analytics stack.
+* Do not reopen Stage 12 payload foundation or Stage 12 recovery brief unless a direct runtime dependency appears.
+* Do not add tutorial-shell parity features whose only value is naming similarity.
+* Do not treat the full family as a single uncheckpointed implementation blob.
+* Do not widen into unrelated prompt, permissions, task, or extension work while implementing the selected compact/runtime family.
+
+### State Boundary
+
+* Short-term dynamic context remains request-scoped / invocation-scoped.
+* Session transcript and compact records remain durable session evidence.
+* Session memory remains a separate durable artifact and assist source, not the first-line pressure mechanism in this task.
+* Todo/task/recovery state must stay distinct from live compact bookkeeping.
+
+### Model-visible Boundary
+
+The model may see:
+
+* preview references for oversized tool results
+* bounded compact/microcompact boundary markers where needed
+* restored high-value working context after compaction
+
+The model should not see:
+
+* internal bookkeeping that exists only to coordinate compaction
+* arbitrary local metadata dumps
+* tutorial-only wrapper instructions
+
+## Research Notes
+
+### Constraints from our repo/project
+
+* Existing Stage 12 work already delivered:
+  * typed `ContextPayload` rendering
+  * deterministic message projection
+  * recovery brief continuation context
+  * memory quality policy
+* Current live tool/middleware path already has a clean cross-cutting seam:
+  * `ToolGuardMiddleware.wrap_tool_call()` for post-tool interception
+  * `AgentMiddleware.wrap_model_call()` for pre-model pressure handling
+* `RuntimeContext` already carries `session_context`, which can anchor session-scoped persisted artifacts.
+* Current session store already has compact records and load-time compacted history, which can be reused for post-compact continuity rather than reinvented.
+* Current runtime does not maintain a custom query loop; solution should stay inside LangChain middleware/services unless a later blocker proves otherwise.
+
+### Feasible approaches here
+
+**Approach A: Middleware-first live pressure loop** (Recommended)
+
+How it works:
+
+* Add one tool-result pressure seam that can persist large tool outputs and replace them with preview references.
+* Add one model-call pressure seam that can microcompact older tool results and trigger proactive compact when thresholds are crossed.
+* Reuse current context payloads/recovery helpers for post-compact restoration.
+
+Pros:
+
+* smallest LangChain-native path
+* directly targets the highest-value runtime effects
+* builds on current Stage 12 foundations instead of replacing them
+
+Cons:
+
+* requires careful tests around intermediate model-call history, not just final transcript behavior
+* proactive compact is still non-trivial without a custom query loop
+
+**Approach B: Resume-first compact hardening**
+
+How it works:
+
+* keep live invocation behavior mostly as-is
+* deepen resume-time compact helpers, compact records, and recovery brief continuity
+
+Pros:
+
+* lower implementation risk
+* reuses current session architecture directly
+
+Cons:
+
+* misses the user-requested "highlight" behavior
+* does not solve live context pressure
+* continues to invest in edge behavior over runtime differentiators
+
+**Approach C: Full compact family now**
+
+How it works:
+
+* implement tool result storage, microcompact, auto-compact, post-compact restoration, reactive compact, and session-memory compact in one task family
+
+Pros:
+
+* broader parity pass
+
+Cons:
+
+* too wide for a first next-cycle slice
+* harder checkpointing
+* much higher risk of architecture drift or accidental custom-runtime creep
+
+## Decision (ADR-lite)
+
+**Context**: The product already has compact/recovery foundations, but it still lacks the cc-haha-style live runtime pressure loop that makes long sessions sustainable. The user explicitly wants high-value highlight alignment rather than more edge feature accumulation.
+
+**Decision**: User-selected direction is Approach C in scope, executed with Approach A's implementation posture.
+
+**Consequences**:
+
+* current Stage 12 foundations are treated as prerequisites, not reopened work
+* the work remains one task family, but must be executed as checkpointed sub-stages
+* reactive compact and session-memory compact are in scope, but should come after tool-result storage, microcompact, proactive auto-compact, and post-compact restoration
+* if checkpoint evidence shows the broader family is unsafe as one run, the task family may split into prerequisites rather than forcing scope through
+
+## Technical Approach
+
+Recommended implementation boundary:
+
+* Tool-result pressure:
+  * add a dedicated middleware/service layer after tool execution
+  * keep tool-specific result-shape knowledge small and driven by capability metadata or a narrow compactable-tool allowlist
+* Model-call pressure:
+  * add a model-call middleware or runtime helper that can inspect the current invocation message history
+  * apply deterministic microcompact first
+  * evaluate proactive compact threshold second
+* Post-compact restoration:
+  * reuse `ContextPayload` and session/recovery seams for bounded restoration
+  * do not copy the full cc attachment catalog
+
+Proposed local modules:
+
+* `coding_deepgent/compact/tool_results.py` or equivalent service seam
+* `coding_deepgent/compact/microcompact.py`
+* `coding_deepgent/compact/runtime_pressure.py`
+* `coding_deepgent/compact/reactive.py` or equivalent fallback seam
+* targeted extensions in:
+  * `tool_system/capabilities.py`
+  * `tool_system/middleware.py` or a sibling middleware
+  * `sessions/*` only where compact record or restoration continuity requires it
+
+## Test Plan
+
+Focused tests by sub-stage:
+
+* tool result storage
+  * persists oversized result to a session-scoped location
+  * returns preview reference content instead of full content
+  * does not affect small results
+* microcompact
+  * preserves tool-use/tool-result invariants
+  * clears only older eligible results
+  * emits boundary/marker behavior if adopted
+* live auto-compact
+  * threshold crossing triggers compact once
+  * low-pressure paths remain unchanged
+  * compacted invocation remains valid for continuation
+* post-compact restoration
+  * restored payloads remain bounded and deduped
+  * compacted continuation retains active work context
+* reactive compact
+  * prompt-too-long path can recover without corrupting session/tool invariants
+  * proactive compact paths do not regress when reactive fallback is enabled
+* session-memory compact
+  * current valid session-memory artifact can participate in compaction
+  * stale or missing artifacts follow explicit update rules
+  * compact result remains bounded and continuation-safe
+
+Likely test files:
+
+* new:
+  * `coding-deepgent/tests/test_tool_result_storage.py`
+  * `coding-deepgent/tests/test_microcompact.py`
+  * `coding-deepgent/tests/test_runtime_pressure.py`
+* updates:
+  * `coding-deepgent/tests/test_tool_system_middleware.py`
+  * `coding-deepgent/tests/test_compact_artifacts.py`
+  * `coding-deepgent/tests/test_sessions.py`
+  * `coding-deepgent/tests/test_cli.py` only if continuation records/selection change
+
+## Implementation Plan (small PRs / sub-stages)
+
+* Sub-stage 1: Tool Result Storage
+  * add session-scoped large-result persistence
+  * return preview references
+  * verify middleware/capability boundary holds
+* Sub-stage 2: Microcompact
+  * add deterministic live microcompact over invocation message history
+  * preserve tool invariants
+  * checkpoint whether proactive compact still holds unchanged
+* Sub-stage 3: Live Auto-Compact
+  * add threshold-triggered compact in live runtime path
+  * keep validation focused on deterministic triggers and compact result shape
+* Sub-stage 4: Post-Compact Restoration
+  * restore minimal working context through bounded payloads
+  * verify compacted continuation usability
+* Sub-stage 5: Reactive Compact
+  * add prompt-too-long fallback path
+  * preserve compact/session invariants and avoid retry loops
+* Sub-stage 6: Session-Memory Compact
+  * add session-memory-guided compact path
+  * preserve bounded continuation and session-memory freshness rules
+
+## Checkpoint Protocol
+
+Lean mode checkpoint after every sub-stage:
+
+* State machine:
+  * `planning`
+  * `implementing`
+  * `verifying`
+  * `checkpoint`
+  * `terminal`
+* Checkpoint summary must record:
+  * implemented behavior
+  * focused tests run and result
+  * files changed
+  * cc-haha alignment evidence
+  * LangChain-native architecture evidence
+  * new boundary issues discovered
+  * whether the next sub-stage still holds
+* Decision mapping:
+  * `APPROVE` -> `continue`
+  * `ITERATE` -> `adjust` or `split`
+  * `REJECT` -> `stop`
+
+Checkpoint stop conditions:
+
+* missing cc-haha evidence for a claimed aligned behavior
+* implementation pressure toward a custom query runtime
+* a prerequisite discovered that should be pulled into an earlier sub-stage
+* focused tests show the current boundary is wrong
+
+## Infrastructure Unlock
+
+This work should unlock a more valuable next-cycle runtime baseline:
+
+* live long-session survivability
+* less prompt bloat from tool output
+* a stronger foundation for later session-memory compact and subagent/fork cache-aware context work
+
+## Checkpoint: Sub-stage 1 Tool Result Storage
+
+State:
+
+* checkpoint
+
+Verdict:
+
+* APPROVE
+
+Implemented:
+
+* Added `coding_deepgent.compact.tool_results` with:
+  * session-scoped persisted tool-result path resolution under the active workspace
+  * deterministic content serialization
+  * persisted-output preview reference rendering
+  * fail-open live rewrite helper for oversized successful tool results
+* Exported the new seam from `coding_deepgent.compact`.
+* Extended `ToolCapability` metadata with:
+  * `persist_large_output`
+  * `max_inline_result_chars`
+  * `microcompact_eligible`
+* Marked `bash`, `read_file`, `glob`, and `grep` as large-output persistence candidates.
+* Updated `ToolGuardMiddleware` to post-process successful `ToolMessage` results through the new storage seam for eligible tools.
+* Updated `.trellis/spec/backend/runtime-context-compaction-contracts.md` with a new live tool-result storage scenario.
+
+Verification:
+
+* `pytest -q coding-deepgent/tests/test_tool_result_storage.py coding-deepgent/tests/test_tool_system_middleware.py`
+* `ruff check coding-deepgent/src/coding_deepgent/compact/tool_results.py coding-deepgent/src/coding_deepgent/compact/__init__.py coding-deepgent/src/coding_deepgent/tool_system/capabilities.py coding-deepgent/src/coding_deepgent/tool_system/middleware.py coding-deepgent/tests/test_tool_result_storage.py coding-deepgent/tests/test_tool_system_middleware.py`
+* `mypy coding-deepgent/src/coding_deepgent/compact/tool_results.py coding-deepgent/src/coding_deepgent/tool_system/capabilities.py coding-deepgent/src/coding_deepgent/tool_system/middleware.py`
+
+cc-haha alignment:
+
+* Source files inspected:
+  * `/root/claude-code-haha/src/utils/toolResultStorage.ts`
+  * `/root/claude-code-haha/src/query.ts`
+* Aligned now:
+  * oversized tool results can be replaced by preview references while preserving full output on disk
+  * storage is tool-boundary behavior, not a resume-only helper
+* Deferred:
+  * microcompact
+  * auto-compact
+  * reactive compact
+  * session-memory compact
+* Do-not-copy:
+  * full cc analytics/feature-flag threshold machinery
+  * provider-specific persistence behavior outside the local workspace model
+
+LangChain architecture:
+
+* Primitive used:
+  * `ToolGuardMiddleware.wrap_tool_call`
+  * `ToolMessage` content/artifact preservation
+  * capability metadata for eligible tool selection
+* Why this stays LangChain-native:
+  * no custom query loop was introduced
+  * the seam operates on standard LangChain tool results after allowed tool execution
+
+Boundary findings:
+
+* Important local boundary:
+  * persisted output must stay inside the active workspace so existing `read_file` can reopen it later
+* Important defer:
+  * this stage does not yet reduce older tool results already present in the live invocation history; that remains Sub-stage 2
+
+Decision:
+
+* continue
+
+Reason:
+
+* focused tests, ruff, and mypy passed
+* cc-haha alignment for the selected behavior is sufficient
+* the next sub-stage still holds and now has a clearer large-output boundary to build on
+
+## Checkpoint: Sub-stage 2 Microcompact
+
+State:
+
+* checkpoint
+
+Verdict:
+
+* APPROVE
+
+Implemented:
+
+* Added `coding_deepgent.compact.runtime_pressure` with:
+  * deterministic `microcompact_messages(...)`
+  * `RuntimePressureMiddleware`
+  * constants for kept recent tool results and cleared-content markers
+* Wired `RuntimePressureMiddleware` into the main app middleware chain between
+  dynamic context middleware and `ToolGuardMiddleware`.
+* Added focused tests for:
+  * compacting only older eligible tool results
+  * preserving recent eligible tool results
+  * skipping ineligible tool results
+  * middleware integration into the live model-call path
+* Updated the runtime compact contract with a new live microcompact scenario.
+
+Verification:
+
+* `pytest -q coding-deepgent/tests/test_runtime_pressure.py coding-deepgent/tests/test_app.py coding-deepgent/tests/test_memory_integration.py coding-deepgent/tests/test_tool_result_storage.py coding-deepgent/tests/test_tool_system_middleware.py`
+* `ruff check coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py coding-deepgent/src/coding_deepgent/compact/__init__.py coding-deepgent/src/coding_deepgent/containers/app.py coding-deepgent/tests/test_runtime_pressure.py coding-deepgent/tests/test_app.py coding-deepgent/tests/test_memory_integration.py`
+* `mypy coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py coding-deepgent/src/coding_deepgent/containers/app.py`
+
+cc-haha alignment:
+
+* Source files inspected:
+  * `/root/claude-code-haha/src/services/compact/microCompact.ts`
+  * `/root/claude-code-haha/src/query.ts`
+* Aligned now:
+  * older eligible tool results can be cleared before a model call
+  * large-output pressure is relieved before full compact
+  * tool-call/tool-result linkage stays intact because results are rewritten in place rather than removed
+* Deferred:
+  * proactive auto-compact thresholding
+  * reactive compact
+  * session-memory compact
+* Do-not-copy:
+  * cached microcompact/provider-specific cache edit behavior
+  * full cc token-estimation and analytics machinery
+
+LangChain architecture:
+
+* Primitive used:
+  * `AgentMiddleware.wrap_model_call`
+  * standard LangChain `BaseMessage` / `ToolMessage` rewriting
+  * capability metadata to decide compact eligibility
+* Why this stays LangChain-native:
+  * no custom query runtime or graph node was introduced
+  * message rewriting happens at the normal model-call interception seam
+
+Boundary findings:
+
+* Important local boundary:
+  * `RuntimePressureMiddleware` should stay responsible only for live pressure handling, not permission or business tool semantics
+* Important defer:
+  * without a thresholded compact stage, microcompact alone only trims older tool-result cost; it does not yet solve full-window overflow
+
+Decision:
+
+* continue
+
+Reason:
+
+* focused tests, ruff, and mypy passed
+* cc-haha alignment for microcompact is sufficient for the scoped behavior
+* the next sub-stage still holds and should now build on the established runtime pressure seam instead of inventing a new one
+
+## Checkpoint: Sub-stage 3 Live Auto-Compact
+
+State:
+
+* checkpoint
+
+Verdict:
+
+* APPROVE
+
+Implemented:
+
+* Extended `RuntimePressureMiddleware` to:
+  * estimate live message tokens deterministically
+  * call the existing compact summarizer seam through the model `.invoke()` path
+  * proactively compact live invocation history when a configured local threshold is crossed
+* Added `compact_live_messages_with_summary(...)`, `estimate_message_tokens(...)`,
+  and `maybe_auto_compact_messages(...)`.
+* Kept proactive compact fail-open on summarizer failure so later fallback paths
+  remain possible.
+
+Verification:
+
+* `pytest -q coding-deepgent/tests/test_runtime_pressure.py coding-deepgent/tests/test_compact_summarizer.py coding-deepgent/tests/test_app.py coding-deepgent/tests/test_memory_integration.py coding-deepgent/tests/test_tool_result_storage.py coding-deepgent/tests/test_tool_system_middleware.py`
+* `ruff check coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py coding-deepgent/src/coding_deepgent/compact/__init__.py coding-deepgent/src/coding_deepgent/containers/app.py coding-deepgent/tests/test_runtime_pressure.py coding-deepgent/tests/test_compact_summarizer.py coding-deepgent/tests/test_app.py coding-deepgent/tests/test_memory_integration.py`
+* `mypy coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py coding-deepgent/src/coding_deepgent/containers/app.py`
+
+cc-haha alignment:
+
+* Source files inspected:
+  * `/root/claude-code-haha/src/query.ts`
+  * `/root/claude-code-haha/src/services/compact/autoCompact.ts`
+  * `/root/claude-code-haha/src/services/compact/compact.ts`
+* Aligned now:
+  * proactive compact can happen in the live runtime path before a model call
+  * compact uses a dedicated summary step rather than a fake fixed string
+  * tool-pair tail preservation remains intact
+* Deferred:
+  * reactive compact
+  * session-memory compact
+* Do-not-copy:
+  * full provider-specific context-window logic and analytics
+  * custom query loop state machine
+
+LangChain architecture:
+
+* Primitive used:
+  * `AgentMiddleware.wrap_model_call`
+  * model `.invoke()` as the summarizer seam
+  * request message rewriting only
+* Why this stays LangChain-native:
+  * no alternate loop was introduced
+  * the middleware uses existing model and message abstractions only
+
+Boundary findings:
+
+* Important local boundary:
+  * local token estimation is intentionally deterministic and approximate; it is a trigger heuristic, not a billing/tokenizer truth source
+* Important defer:
+  * prompt-too-long recovery is still needed because proactive estimates can miss provider-side limits
+
+Decision:
+
+* continue
+
+Reason:
+
+* focused tests, ruff, and mypy passed
+* proactive compact is now present without breaking LangChain boundaries
+* the next sub-stage should now restore compacted-away high-value context rather than widening threshold logic further
+
+## Checkpoint: Sub-stage 4 Post-Compact Restoration
+
+State:
+
+* checkpoint
+
+Verdict:
+
+* APPROVE
+
+Implemented:
+
+* Extended live compact output to include a bounded restoration `SystemMessage`
+  for persisted-output paths that were compacted away.
+* Restoration dedupes paths and excludes paths already visible in the preserved
+  tail.
+
+Verification:
+
+* `pytest -q coding-deepgent/tests/test_runtime_pressure.py coding-deepgent/tests/test_tool_result_storage.py coding-deepgent/tests/test_app.py coding-deepgent/tests/test_memory_integration.py`
+* `ruff check coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py coding-deepgent/src/coding_deepgent/compact/__init__.py coding-deepgent/tests/test_runtime_pressure.py`
+* `mypy coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py`
+
+cc-haha alignment:
+
+* Source files inspected:
+  * `/root/claude-code-haha/src/services/compact/compact.ts`
+  * `/root/claude-code-haha/src/utils/attachments.ts`
+* Aligned now:
+  * post-compact output can restore high-value file references rather than relying on the summary alone
+* Deferred:
+  * richer file/task/skill/agent restoration
+  * reactive compact
+  * session-memory compact
+* Do-not-copy:
+  * full attachment catalog and restoration breadth
+
+LangChain architecture:
+
+* Primitive used:
+  * additional `SystemMessage` in the compacted live message list
+* Why this stays LangChain-native:
+  * restoration remains bounded message context, not a new runtime object model
+
+Boundary findings:
+
+* Important local boundary:
+  * current restoration is intentionally limited to persisted-output file paths, because those are the most concrete recoverable artifacts already present in the product
+* Important defer:
+  * broader plan/skill/agent restoration should wait until there is source-backed evidence it is needed locally
+
+Decision:
+
+* continue
+
+Reason:
+
+* focused tests, ruff, and mypy passed
+* the next sub-stage now has a stable proactive compact path to fall back from when prompt-too-long still occurs
+
+## Checkpoint: Sub-stage 5 Reactive Compact
+
+State:
+
+* checkpoint
+
+Verdict:
+
+* APPROVE
+
+Implemented:
+
+* Extended `RuntimePressureMiddleware.wrap_model_call()` to:
+  * detect prompt-too-long style failures
+  * perform one reactive compact retry using the same summarizer seam
+  * re-raise non prompt-too-long failures unchanged
+* Added `reactive_compact_messages(...)` and prompt-too-long detection helper.
+
+Verification:
+
+* `pytest -q coding-deepgent/tests/test_runtime_pressure.py coding-deepgent/tests/test_compact_summarizer.py coding-deepgent/tests/test_app.py coding-deepgent/tests/test_memory_integration.py coding-deepgent/tests/test_tool_result_storage.py coding-deepgent/tests/test_tool_system_middleware.py`
+* `ruff check coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py coding-deepgent/src/coding_deepgent/compact/__init__.py coding-deepgent/tests/test_runtime_pressure.py`
+* `mypy coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py`
+
+cc-haha alignment:
+
+* Source files inspected:
+  * `/root/claude-code-haha/src/query.ts`
+  * reactive compact references in the cc compact/query flow
+* Aligned now:
+  * proactive compact has a bounded prompt-too-long fallback path
+  * fallback remains compact-based rather than introducing unrelated retry behavior
+* Deferred:
+  * provider-specific error typing
+* Do-not-copy:
+  * full cc runtime transition machine and provider-specialized branching
+
+LangChain architecture:
+
+* Primitive used:
+  * one retry within `wrap_model_call`
+* Why this stays LangChain-native:
+  * fallback is still expressed as request-message rewriting and re-invocation of the same handler
+
+Boundary findings:
+
+* Important local boundary:
+  * only prompt-too-long style failures get fallback retry treatment
+* Important defer:
+  * richer provider-specific error typing can wait until a concrete mismatch appears
+
+Decision:
+
+* continue
+
+Reason:
+
+* focused tests, ruff, and mypy passed
+* the next sub-stage can now safely add session-memory assist on top of an already stable proactive/reactive compact chain
+
+## Checkpoint: Sub-stage 6 Session-Memory Compact
+
+State:
+
+* checkpoint
+
+Verdict:
+
+* APPROVE
+
+Implemented:
+
+* Updated `agent_runtime_service.session_payload()` so existing `session_memory`
+  state flows into live runtime state.
+* Extended proactive and reactive live compact to pass bounded session-memory
+  assist text into `generate_compact_summary(...)` when a current artifact is
+  available in runtime state.
+* Added focused tests proving:
+  * `session_memory` survives into runtime payload
+  * live auto-compact can pass assist text to the summarizer
+
+Verification:
+
+* `pytest -q coding-deepgent/tests/test_agent_runtime_service.py coding-deepgent/tests/test_runtime_pressure.py coding-deepgent/tests/test_compact_summarizer.py coding-deepgent/tests/test_app.py coding-deepgent/tests/test_memory_integration.py coding-deepgent/tests/test_tool_result_storage.py coding-deepgent/tests/test_tool_system_middleware.py`
+* `ruff check coding-deepgent/src/coding_deepgent/agent_runtime_service.py coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py coding-deepgent/tests/test_agent_runtime_service.py coding-deepgent/tests/test_runtime_pressure.py`
+* `mypy coding-deepgent/src/coding_deepgent/agent_runtime_service.py coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py`
+
+cc-haha alignment:
+
+* Source files inspected:
+  * `/root/claude-code-haha/src/services/compact/sessionMemoryCompact.ts`
+  * existing local session memory contribution/update seams
+* Aligned now:
+  * live compact can consume current session-memory artifact as bounded continuity aid
+* Deferred:
+  * session-memory-driven compact boundary selection
+  * live session-memory refresh/promotion workflow
+* Do-not-copy:
+  * full cc session-memory compact heuristics and remote config machinery
+
+LangChain architecture:
+
+* Primitive used:
+  * existing runtime state payload
+  * existing summarizer assist-context seam
+* Why this stays LangChain-native:
+  * no new store/runtime layer was introduced; current state and helper seams were reused
+
+Boundary findings:
+
+* Important local boundary:
+  * this stage uses current session-memory artifacts when present; it does not yet refresh them automatically from live compaction
+* Residual risk:
+  * deeper session-memory compact parity would require explicit state-refresh semantics in the live runtime path
+
+Decision:
+
+* continue
+
+Terminal note:
+
+* All planned sub-stages in the current task family are now complete. This `continue` maps to staged-run completion rather than starting a speculative Sub-stage 7.
+
+Reason:
+
+* focused tests, ruff, and mypy passed
+* the six selected compact/runtime behaviors now exist in a LangChain-native local form
+
+## Follow-on Checkpoint: Live Pressure Observability And Evidence
+
+State:
+
+* checkpoint
+
+Verdict:
+
+* APPROVE
+
+Implemented:
+
+* Extended `RuntimePressureMiddleware` to emit structured runtime events for:
+  * `microcompact`
+  * `auto_compact`
+  * `reactive_compact`
+* Routed those events through the existing `event_sink` path and the existing
+  `append_runtime_event_evidence(...)` seam.
+* Expanded runtime-event evidence support so compact/runtime-pressure events can
+  be recorded as bounded `runtime_event` session evidence.
+* Added focused tests proving:
+  * runtime pressure events reach `event_sink`
+  * session evidence is appended when `session_context` is active
+  * existing hook/tool runtime-event paths still pass
+* Updated the backend compact/runtime contract with a live runtime pressure
+  observability scenario.
+
+Verification:
+
+* `pytest -q coding-deepgent/tests/test_runtime_pressure.py coding-deepgent/tests/test_hooks.py coding-deepgent/tests/test_tool_system_middleware.py coding-deepgent/tests/test_sessions.py`
+* `ruff check coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py coding-deepgent/src/coding_deepgent/sessions/evidence_events.py coding-deepgent/tests/test_runtime_pressure.py`
+* `mypy coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py coding-deepgent/src/coding_deepgent/sessions/evidence_events.py`
+
+cc-haha alignment:
+
+* Source references:
+  * runtime compact path in `/root/claude-code-haha/src/query.ts`
+  * compact flow observability references in the cc compact stack and docs
+* Aligned now:
+  * compact/runtime-pressure transitions are observable as explicit runtime events
+  * compact evidence uses a bounded ledger path rather than raw transcript dumps
+* Do-not-copy:
+  * full cc analytics/telemetry surface
+  * provider-specific cost/cache analytics
+
+LangChain architecture:
+
+* Primitive used:
+  * middleware-side event emission
+  * existing `RuntimeEvent` and `event_sink`
+  * existing session evidence seam
+* Why this stays LangChain-native:
+  * no second observability stack or compact-specific persistence system was added
+
+Decision:
+
+* APPROVE
+
+Reason:
+
+* the requested observability/evidence follow-on is now implemented with focused verification and no new architecture drift
+
+## Final Confirmation
+
+Here's my understanding of the complete requirements:
+
+**Goal**: add the cc-haha high-value runtime context pressure loop to `coding-deepgent`, covering both proactive and fallback compact behavior, without drifting into tutorial-shell parity or unrelated edge work.
+
+**Requirements**:
+
+* build on existing Stage 12 foundations rather than reopening them
+* implement the following task family in order:
+  * tool result storage
+  * microcompact
+  * live auto-compact
+  * post-compact restoration
+  * reactive compact
+  * session-memory compact
+* keep LangChain/LangGraph as the runtime boundary
+* use staged checkpoints after every sub-stage
+* update contracts/tests where cross-layer behavior changes
+
+**Acceptance Criteria**:
+
+* [ ] cc-haha alignment is source-backed for each sub-stage
+* [ ] the runtime pressure loop is implemented through focused, checkpointed sub-stages
+* [ ] the model context no longer carries giant low-value tool outputs unnecessarily
+* [ ] live compact behavior survives pressure without breaking protocol invariants
+* [ ] fallback reactive compact and session-memory compact are integrated without forcing a custom runtime
+
+**Definition of Done**:
+
+* focused tests per sub-stage pass
+* lint/typecheck stay green at the scoped level
+* contracts/docs are updated when behavior changes
+* checkpoint verdicts are recorded after each sub-stage
+
+**Out of Scope**:
+
+* tutorial-shell parity work
+* unrelated recovery brief/UI polish
+* broad prompt redesign
+* unrelated permission/task/extension work
+
+**Technical Approach**:
+
+* middleware-first live pressure loop
+* tool-result pressure seam + model-call pressure seam
+* bounded restoration via current payload/recovery foundations
+* reactive compact and session-memory compact added only after proactive path is stable
+
+**Implementation Plan (small PRs / sub-stages)**:
+
+* PR1 / Sub-stage 1: Tool Result Storage
+* PR2 / Sub-stage 2: Microcompact
+* PR3 / Sub-stage 3: Live Auto-Compact
+* PR4 / Sub-stage 4: Post-Compact Restoration
+* PR5 / Sub-stage 5: Reactive Compact
+* PR6 / Sub-stage 6: Session-Memory Compact
diff --git a/.trellis/tasks/archive/2026-04/04-15-runtime-context-pressure-management/task.json b/.trellis/tasks/archive/2026-04/04-15-runtime-context-pressure-management/task.json
new file mode 100644
index 000000000..45d600b8d
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-runtime-context-pressure-management/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "runtime-context-pressure-management",
+  "name": "runtime-context-pressure-management",
+  "title": "brainstorm: runtime context pressure management",
+  "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": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-runtime-pressure-closeout-validation/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-runtime-pressure-closeout-validation/check.jsonl
new file mode 100644
index 000000000..34b6f6a88
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-runtime-pressure-closeout-validation/check.jsonl
@@ -0,0 +1,4 @@
+{"file": ".cursor/commands/trellis-finish-work.md", "reason": "Finish work checklist"}
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
+{"file": ".trellis/spec/backend/runtime-context-compaction-contracts.md", "reason": "Verify compact/runtime/evidence contracts after closeout."}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Check domain boundaries and focused validation discipline."}
diff --git a/.trellis/tasks/archive/2026-04/04-15-runtime-pressure-closeout-validation/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-runtime-pressure-closeout-validation/debug.jsonl
new file mode 100644
index 000000000..e30f96d49
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-runtime-pressure-closeout-validation/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-runtime-pressure-closeout-validation/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-runtime-pressure-closeout-validation/implement.jsonl
new file mode 100644
index 000000000..19acd2e1f
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-runtime-pressure-closeout-validation/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"}
+dence integration."}
+{"file": ".trellis/spec/guides/cross-layer-thinking-guide.md", "reason": "Keep runtime, sessions, compact, evidence, and settings boundaries coherent during the closeout pass."}
diff --git a/.trellis/tasks/archive/2026-04/04-15-runtime-pressure-closeout-validation/prd.md b/.trellis/tasks/archive/2026-04/04-15-runtime-pressure-closeout-validation/prd.md
new file mode 100644
index 000000000..3f133f4d8
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-runtime-pressure-closeout-validation/prd.md
@@ -0,0 +1,232 @@
+# runtime pressure closeout and validation
+
+## Goal
+
+Close out the current `coding-deepgent` runtime context pressure work as one integrated optimization pass: turn the recent live compact/runtime-pressure loop into something easier to observe, configurable enough to tune locally, capable of refreshing live session-memory state after successful compact operations, and validated more broadly across compact/session/runtime boundaries.
+
+## What I already know
+
+* The parent task `.trellis/tasks/04-15-runtime-context-pressure-management` already implemented:
+  * tool result storage
+  * live microcompact
+  * live auto-compact
+  * post-compact restoration for persisted-output paths
+  * reactive compact
+  * live session-memory assist during compact
+  * runtime pressure events and bounded session evidence
+* The user explicitly asked to avoid "挤牙膏" delivery for this family and wants a one-pass closeout where practical.
+* Existing observability is event-level, but there is not yet a compact/runtime-pressure summary view in recovery surfaces.
+* Existing session memory helpers already have:
+  * artifact parsing
+  * status rendering
+  * threshold policy
+  * metric estimation
+  * generated-compact summary update contribution
+* Current `agent_runtime_service.session_payload()` now forwards `session_memory` into live runtime payload, but live compact does not yet refresh the artifact after successful compact operations.
+* Current live auto-compact threshold and keep counts are hard-coded in `compact/runtime_pressure.py`.
+
+## Assumptions
+
+* This task should build on the current runtime-pressure implementation rather than reopening the parent family.
+* "Optimize these contents" for this closeout pass means:
+  * compact/runtime counters or summary visibility
+  * live session-memory refresh after compact
+  * configurable pressure thresholds
+  * broader regression/validation
+* Provider-specific context-window logic and richer plan/skill/agent restoration are still too wide for this task unless a concrete blocker appears.
+
+## Open Questions
+
+* None. The closeout scope is derived from the user's direct request and the current parent task state.
+
+## Requirements
+
+* Add a bounded runtime-pressure summary view that can survive resume boundaries.
+* Reuse existing session evidence or contribution seams rather than inventing a second compact metrics system.
+* After successful live auto-compact or reactive compact, refresh the in-memory/live `session_memory` artifact using the existing local threshold policy when due.
+* Make the live pressure loop locally configurable through settings for at least:
+  * auto-compact threshold
+  * kept recent tool results
+  * kept recent messages after compact
+* Keep the implementation LangChain-native and middleware-first.
+* Run a broader focused regression covering compact/session/runtime/evidence integration.
+
+## Acceptance Criteria
+
+* [ ] Recovery/resume surfaces can show a bounded runtime-pressure summary derived from current compact/runtime evidence.
+* [ ] Successful live compact can refresh session-memory state when the current threshold policy says it is due.
+* [ ] Runtime-pressure thresholds are configurable from settings rather than hard-coded only in code.
+* [ ] Broader focused regression for compact/session/runtime/evidence passes.
+* [ ] No new custom query runtime or compact-specific persistence stack is introduced.
+
+## Definition of Done
+
+* Focused product tests pass.
+* `ruff check` and `mypy` pass on changed files.
+* Trellis contracts/PRD are updated where behavior changes.
+* Residual risks or deferred items are stated explicitly.
+
+## Out of Scope
+
+* Provider-specific context-window discovery
+* Richer plan/skill/agent/task restoration after compact
+* Full release validation across the whole repo
+* New analytics/telemetry backend
+* Remote/team/runtime control-plane work
+
+## Expected Effect
+
+Aligning this closeout behavior should improve reliability, recoverability, maintainability, and observability.
+
+The local runtime effect is:
+
+* compact/runtime pressure behavior becomes easier to inspect after resume
+* live compact can keep session-memory continuity fresher without waiting for explicit CLI compact paths
+* pressure thresholds become tunable without code edits
+* the compact/session/runtime stack is validated as one integrated product path
+
+If these effects do not show up in focused runtime and session tests, the closeout is not worth shipping.
+
+## cc-haha Alignment
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Compact/runtime observability | cc compact/query flow records compact transitions and metadata as first-class runtime behavior | compact activity is inspectable after the fact, not only while live | recovery summary built from current runtime-event evidence | align | Implement now |
+| Session-memory compact continuity | cc session-memory compact is part of the compaction system, not only a manual assist path | live compact can improve continuity, not only consume stale memory | refresh local `session_memory` artifact after successful live compact when due | partial | Implement bounded local equivalent now |
+| Compact tuning | cc has explicit compact thresholds/configs | local tuning does not require code edits | settings-backed thresholds and keep counts | partial | Implement now, local-only |
+| Rich provider-specific compact telemetry | cc has deeper analytics/provider-aware compact machinery | richer insight but higher complexity | none for this task | defer | Not needed for local closeout |
+
+## Technical Approach
+
+* Add one small session contribution that aggregates compact/runtime-event evidence into a bounded recovery brief section.
+* Extend runtime pressure middleware so a successful live compact can update `request.state["session_memory"]` through the existing threshold helpers when appropriate.
+* Move current hard-coded runtime pressure defaults behind `Settings` and thread them through container wiring.
+* Run a broader but still scoped validation set across:
+  * runtime pressure
+  * sessions
+  * hooks/runtime events
+  * tool-system middleware
+
+## Technical Notes
+
+* Parent task: `.trellis/tasks/04-15-runtime-context-pressure-management`
+* New task: `.trellis/tasks/04-15-runtime-pressure-closeout-validation`
+* Likely modules:
+  * `coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py`
+  * `coding-deepgent/src/coding_deepgent/sessions/evidence_events.py`
+  * `coding-deepgent/src/coding_deepgent/sessions/contribution_registry.py`
+  * `coding-deepgent/src/coding_deepgent/sessions/contributions.py`
+  * `coding-deepgent/src/coding_deepgent/sessions/session_memory.py`
+  * `coding-deepgent/src/coding_deepgent/settings.py`
+  * `coding-deepgent/src/coding_deepgent/containers/app.py`
+
+## Checkpoint: Integrated Closeout Pass
+
+State:
+
+* checkpoint
+
+Verdict:
+
+* APPROVE
+
+Implemented:
+
+* Added runtime-pressure recovery summary support through a new session
+  contribution module:
+  * `coding_deepgent.sessions.runtime_pressure`
+  * wired into recovery brief contributions
+* Extended live compact so successful auto/reactive compact can refresh
+  `session_memory` state via the existing local threshold policy using
+  `source=live_compact`
+* Extended runtime state and session state propagation so `session_memory`
+  survives the live runtime path and outer session state update
+* Moved runtime-pressure tuning knobs into `Settings` and threaded them through
+  container wiring:
+  * `auto_compact_threshold_tokens`
+  * `keep_recent_tool_results`
+  * `keep_recent_messages_after_compact`
+* Updated backend compact/runtime contracts to cover:
+  * settings-backed thresholds
+  * live session-memory refresh
+  * runtime-pressure recovery summary
+
+Verification:
+
+* `pytest -q coding-deepgent/tests/test_agent_runtime_service.py coding-deepgent/tests/test_runtime_pressure.py coding-deepgent/tests/test_session_contributions.py coding-deepgent/tests/test_app.py coding-deepgent/tests/test_hooks.py coding-deepgent/tests/test_tool_system_middleware.py coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_compact_summarizer.py coding-deepgent/tests/test_memory_integration.py`
+* `ruff check coding-deepgent/src/coding_deepgent/runtime/state.py coding-deepgent/src/coding_deepgent/agent_runtime_service.py coding-deepgent/src/coding_deepgent/settings.py coding-deepgent/src/coding_deepgent/containers/app.py coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py coding-deepgent/src/coding_deepgent/sessions/session_memory.py coding-deepgent/src/coding_deepgent/sessions/runtime_pressure.py coding-deepgent/src/coding_deepgent/sessions/contribution_registry.py coding-deepgent/tests/test_agent_runtime_service.py coding-deepgent/tests/test_runtime_pressure.py coding-deepgent/tests/test_session_contributions.py coding-deepgent/tests/test_app.py`
+* `mypy coding-deepgent/src/coding_deepgent/runtime/state.py coding-deepgent/src/coding_deepgent/agent_runtime_service.py coding-deepgent/src/coding_deepgent/settings.py coding-deepgent/src/coding_deepgent/containers/app.py coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py coding-deepgent/src/coding_deepgent/sessions/session_memory.py coding-deepgent/src/coding_deepgent/sessions/runtime_pressure.py coding-deepgent/src/coding_deepgent/sessions/contribution_registry.py`
+
+cc-haha alignment:
+
+* Source bands reused:
+  * compact/query/runtime observability expectations from cc compact flow
+  * session-memory compact as part of the compaction family rather than a
+    disconnected manual-only seam
+* Aligned now:
+  * runtime pressure activity is inspectable after resume through bounded
+    summary counts
+  * live compact can improve current session-memory continuity locally
+  * pressure thresholds are explicit product config, not magic constants only
+* Deferred:
+  * provider-specific context-window discovery
+  * richer restoration breadth
+  * full release validation
+
+LangChain architecture:
+
+* Primitive used:
+  * middleware-owned runtime pressure behavior
+  * settings/config threading through container wiring
+  * existing session contribution and evidence seams
+* Why this stays LangChain-native:
+  * no second compact stack, no custom query loop, no extra persistence system
+
+Residual risk:
+
+* live session-memory refresh currently updates runtime/session state locally but
+  is not yet tied to a richer post-compact review or promotion workflow
+* provider-specific error typing and context-window calibration remain heuristic
+
+Decision:
+
+* APPROVE
+
+Reason:
+
+* the requested closeout items are implemented in one integrated pass
+* broader focused validation passed
+* no new architecture drift was introduced
+
+## Checkpoint: Product Validation Closeout
+
+State:
+
+* terminal
+
+Verdict:
+
+* APPROVE
+
+Validation:
+
+* `pytest -q coding-deepgent/tests`
+  * `256 passed`
+* `ruff check coding-deepgent/src coding-deepgent/tests`
+  * passed
+* `mypy coding-deepgent/src/coding_deepgent`
+  * passed
+
+Scope:
+
+* This was product-mainline validation for `coding-deepgent`.
+* It did not run root/tutorial/reference tests because the current mainline
+  scope is `coding-deepgent/`, and the worktree includes unrelated deletions in
+  tutorial/reference paths.
+
+Residual risk:
+
+* No live LLM integration test was run.
+* Provider-specific context-window behavior remains heuristic.
+* Broader repository validation should wait until unrelated worktree churn is
+  intentionally reconciled.
diff --git a/.trellis/tasks/archive/2026-04/04-15-runtime-pressure-closeout-validation/task.json b/.trellis/tasks/archive/2026-04/04-15-runtime-pressure-closeout-validation/task.json
new file mode 100644
index 000000000..525af1e98
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-runtime-pressure-closeout-validation/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "runtime-pressure-closeout-validation",
+  "name": "runtime-pressure-closeout-validation",
+  "title": "runtime pressure closeout and validation",
+  "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-15-runtime-context-pressure-management",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-17c-explicit-plan-artifact-boundary/prd.md b/.trellis/tasks/archive/2026-04/04-15-stage-17c-explicit-plan-artifact-boundary/prd.md
new file mode 100644
index 000000000..80a20b84a
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-15-stage-17c-explicit-plan-artifact-boundary/task.json b/.trellis/tasks/archive/2026-04/04-15-stage-17c-explicit-plan-artifact-boundary/task.json
new file mode 100644
index 000000000..69a5287d4
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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": "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": "Reconciled on 2026-04-15: checkpoint evidence in the task PRD and canonical handoff/roadmap docs both show this historical stage is complete, so the task metadata was normalized for archive cleanup.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-17d-verifier-subagent-execution-boundary/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-17d-verifier-subagent-execution-boundary/check.jsonl
new file mode 100644
index 000000000..8ef7b6aa1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-15-stage-17d-verifier-subagent-execution-boundary/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-17d-verifier-subagent-execution-boundary/debug.jsonl
new file mode 100644
index 000000000..134f779f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-15-stage-17d-verifier-subagent-execution-boundary/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-17d-verifier-subagent-execution-boundary/implement.jsonl
new file mode 100644
index 000000000..4828c638c
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-15-stage-17d-verifier-subagent-execution-boundary/prd.md b/.trellis/tasks/archive/2026-04/04-15-stage-17d-verifier-subagent-execution-boundary/prd.md
new file mode 100644
index 000000000..8a3a2d73c
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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/archive/2026-04/04-15-stage-17d-verifier-subagent-execution-boundary/task.json b/.trellis/tasks/archive/2026-04/04-15-stage-17d-verifier-subagent-execution-boundary/task.json
new file mode 100644
index 000000000..f8dffb2af
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/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": "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": "Reconciled on 2026-04-15: checkpoint evidence in the task PRD and canonical handoff/roadmap docs both show this historical stage is complete, so the task metadata was normalized for archive cleanup.",
+  "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/tasks/archive/2026-04/04-15-stage-30a-module-upgrade-contribution-seams/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-30a-module-upgrade-contribution-seams/check.jsonl
new file mode 100644
index 000000000..2d3c47c95
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-30a-module-upgrade-contribution-seams/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/spec/backend/runtime-context-compaction-contracts.md", "reason": "Session/compact contract checks"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-30a-module-upgrade-contribution-seams/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-30a-module-upgrade-contribution-seams/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-30a-module-upgrade-contribution-seams/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-30a-module-upgrade-contribution-seams/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-30a-module-upgrade-contribution-seams/implement.jsonl
new file mode 100644
index 000000000..c7acdc3ee
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-30a-module-upgrade-contribution-seams/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/tasks/04-15-stage-30a-module-upgrade-contribution-seams/prd.md", "reason": "Stage 30A module upgrade contribution seams plan"}
+{"file": ".trellis/tasks/04-15-diagnose-module-upgrade-coupling/prd.md", "reason": "Coupling diagnosis and cc-haha comparison"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-30a-module-upgrade-contribution-seams/prd.md b/.trellis/tasks/archive/2026-04/04-15-stage-30a-module-upgrade-contribution-seams/prd.md
new file mode 100644
index 000000000..e263de8e8
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-30a-module-upgrade-contribution-seams/prd.md
@@ -0,0 +1,288 @@
+# Stage 30A: Module Upgrade Contribution Seams
+
+## Goal
+
+Reduce accidental cross-module coupling by introducing lightweight module contribution seams for runtime-state persistence, recovery brief rendering, and generated compact assist text. Use the existing `session_memory` deterministic-assist slice as the proving case, preserving behavior while moving hard wiring out of central orchestration files.
+
+## Concrete Benefit
+
+* Modularity: future `session_memory` changes should mostly touch module-owned contribution code.
+* Maintainability: central session/compact flows should consume generic contributions instead of knowing every feature's fields and render rules.
+* Roadmap discipline: unblock later `Threshold-Triggered Local Updates` without adding more hard-coded coupling.
+
+## What I already know
+
+* The user wants module-level optimization to be possible after infrastructure work.
+* The current deterministic-assist slice works and is tested, but it hard-wires `session_memory` into:
+  * `JsonlSessionStore._coerce_state_snapshot()`
+  * `render_recovery_brief()`
+  * `cli_service.generated_compacted_continuation_history()`
+  * `compact.summarizer` parameter naming
+* Local coupling review found similar coupling in `sessions`, `compact`, `subagents`, and `CLI`, while `tool_system`, `hooks`, and MCP are comparatively better isolated.
+* cc-haha reduces coupling through broad protocols such as `Tool` / `ToolUseContext`, `Attachment`, hooks, and plugin loading. It does not make modules completely independent.
+
+## cc-haha Alignment
+
+### Expected effect
+
+Aligning this behavior should improve maintainability and modularity. The local runtime effect is: modules contribute typed state/context/assist outputs through explicit seams, while central flows stay small consumers of generic outputs.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Dynamic context | `utils/attachments.ts` models many model-visible context items as typed `Attachment` variants consumed by a central renderer | avoid ad hoc prompt/string injection and flow-specific wiring | small local contribution dataclasses, not a giant union | partial | Align the provider/renderer split |
+| Hooks | `utils/hooks.ts` merges registered/session/plugin hooks and includes compact lifecycle hooks | let modules participate in lifecycle flows through registered contributions | static contribution registry first | partial | Align the lifecycle contribution idea, not full hook runtime |
+| Plugin loading | `utils/plugins/pluginLoader.ts` centralizes load/merge results for downstream consumers | central consumers depend on normalized outputs rather than plugin internals | static contribution registry with module-owned providers | partial | Keep small; no plugin lifecycle now |
+| Session memory | `services/SessionMemory/sessionMemory.ts` registers post-sampling behavior and is consumed by compact flows | session memory should be a module-owned provider, not hard-coded in every central flow | `session_memory` contribution providers | align | Use as proving case |
+
+### Source files inspected
+
+* `/root/claude-code-haha/src/Tool.ts`
+* `/root/claude-code-haha/src/utils/attachments.ts`
+* `/root/claude-code-haha/src/utils/messages.ts`
+* `/root/claude-code-haha/src/utils/hooks.ts`
+* `/root/claude-code-haha/src/utils/plugins/pluginLoader.ts`
+* `/root/claude-code-haha/src/services/SessionMemory/sessionMemory.ts`
+* `/root/claude-code-haha/src/services/compact/sessionMemoryCompact.ts`
+
+## LangChain-Native Boundary
+
+Surface:
+* state, prompt/context assembly, compact-summary request construction, tests
+
+Primary boundary:
+* product code under `coding_deepgent`, not a new framework
+
+Smallest viable change:
+* add small dataclasses/helpers for contribution outputs
+* add a static registry for now
+* retrofit only `session_memory`
+* do not add plugin runtime registration, middleware, graph nodes, or background agents
+
+## Requirements
+
+* Add lightweight contribution primitives:
+  * runtime state contribution/coercion
+  * recovery brief section contribution
+  * compact assist contribution
+* Add a static contribution registry containing only `session_memory` initially.
+* Move `session_memory` behavior behind module-owned contribution providers.
+* Remove `session_memory` knowledge from central state coercion, recovery rendering, and compact assist orchestration.
+* Preserve current deterministic-assist behavior exactly.
+* Keep `sessions resume --session-memory` as the explicit UX for now.
+
+## Acceptance Criteria
+
+* [ ] Runtime state contribution helper is tested.
+* [ ] Recovery brief contribution helper is tested.
+* [ ] Compact assist contribution helper is tested.
+* [ ] Existing `session_memory` current/stale/invalid behavior still passes.
+* [ ] `JsonlSessionStore._coerce_state_snapshot()` no longer imports or calls `session_memory` directly.
+* [ ] `render_recovery_brief()` no longer has a hard-coded `session_memory` field.
+* [ ] `cli_service.generated_compacted_continuation_history()` consumes generic compact assist output.
+* [ ] Contract docs describe contribution seams and their limits.
+
+## Out of Scope
+
+* threshold-triggered session memory updates
+* background session-memory extraction
+* mailbox/coordinator lifecycle
+* plugin install/enable/update lifecycle
+* broad dynamic context provider registry for all modules
+* full cc-haha `Attachment` union clone
+* full hook runtime clone
+
+## Technical Approach
+
+### Sub-stage 1: Contribution Primitives And Registry
+
+* Add `coding_deepgent.sessions.contributions` with:
+  * `RuntimeStateContribution`
+  * `RecoveryBriefSection`
+  * `RecoveryBriefContribution`
+  * `CompactAssistContribution`
+  * helper functions to coerce state, render sections, and collect assist text
+* Add a static `coding_deepgent.sessions.contribution_registry` that imports `session_memory` providers.
+* Add focused tests for the generic helpers.
+
+### Sub-stage 2: Retrofit Session Memory
+
+* Move session-memory state coercion into a module-owned provider.
+* Move recovery rendering into a module-owned provider.
+* Move compact assist text into a module-owned provider.
+* Rename compact summarizer's generic assist parameter away from `session_memory`.
+* Preserve CLI `--session-memory`.
+
+### Sub-stage 3: Contracts And Checkpoint
+
+* Update runtime context/compaction contract docs.
+* Run focused tests plus targeted lint/typecheck.
+* Record checkpoint and stop at terminal if no new prerequisite appears.
+
+## Test Plan
+
+* `pytest -q coding-deepgent/tests/test_session_contributions.py`
+* `pytest -q coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_cli.py coding-deepgent/tests/test_compact_summarizer.py`
+* targeted `ruff check` on changed files
+* targeted `mypy` on changed files
+
+## Definition of Done
+
+* Focused tests pass.
+* Targeted ruff and mypy pass.
+* Stage checkpoint records cc-haha alignment, LangChain architecture, and next-stage impact.
+* No threshold/background/session-memory automation is introduced.
+
+## Checkpoint: Sub-stage 1 Contribution Primitives And Registry
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added lightweight contribution primitives for runtime state, recovery brief sections, and compact assist text.
+- Added a static contribution registry seeded only with `session_memory`.
+- Added focused helper tests proving contribution state coercion, recovery section filtering, and compact assist joining.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_session_contributions.py`
+- `ruff check coding-deepgent/src/coding_deepgent/sessions/contributions.py coding-deepgent/src/coding_deepgent/sessions/contribution_registry.py coding-deepgent/src/coding_deepgent/sessions/session_memory.py coding-deepgent/tests/test_session_contributions.py`
+- `mypy coding-deepgent/src/coding_deepgent/sessions/contributions.py coding-deepgent/src/coding_deepgent/sessions/contribution_registry.py coding-deepgent/src/coding_deepgent/sessions/session_memory.py coding-deepgent/tests/test_session_contributions.py`
+
+cc-haha alignment:
+- Source files inspected:
+  - `/root/claude-code-haha/src/utils/attachments.ts`
+  - `/root/claude-code-haha/src/utils/hooks.ts`
+  - `/root/claude-code-haha/src/services/SessionMemory/sessionMemory.ts`
+- Aligned:
+  - module behavior now starts to flow through typed contribution outputs rather than ad hoc central wiring
+- Deferred:
+  - full attachment union
+  - plugin/runtime contribution discovery
+- Do-not-copy:
+  - broad `ToolUseContext` and hook runtime
+
+LangChain architecture:
+- Primitive used:
+  - dataclass contribution descriptors and pure helper functions
+- Why no heavier abstraction:
+  - a static tuple is enough to prove the seam before adding dynamic/plugin registration
+
+Boundary findings:
+- New issue:
+  - central flows still need to consume the new registry
+- Impact on next stage:
+  - sub-stage 2 remains valid and should retrofit only `session_memory`
+
+Decision:
+- continue
+
+Reason:
+- The seam exists and is tested without changing runtime behavior. Next step is a behavior-preserving retrofit.
+
+## Checkpoint: Sub-stage 2 Session Memory Retrofit
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Moved `session_memory` state coercion behind `RuntimeStateContribution`.
+- Moved recovery brief rendering behind `RecoveryBriefContribution`.
+- Moved generated compact assist text behind `CompactAssistContribution`.
+- Renamed the compact summarizer's generic assist parameter from `session_memory` to `assist_context`.
+- Kept the explicit CLI `--session-memory` UX intact.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_session_contributions.py coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_cli.py coding-deepgent/tests/test_compact_summarizer.py`
+- `ruff check ...` on changed source/test files
+- `mypy ...` on changed source/test files
+
+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/services/SessionMemory/sessionMemory.ts`
+- Aligned:
+  - central flows now consume typed contributions rather than session-memory-specific implementation details
+- Deferred:
+  - dynamic plugin registration
+  - threshold/background automation
+- Do-not-copy:
+  - giant attachment union and broad `ToolUseContext`
+
+LangChain architecture:
+- Primitive used:
+  - small static provider registry and pure dataclass descriptors
+- Why no heavier abstraction:
+  - behavior-preserving retrofit did not require middleware, graph state, plugin discovery, or DI container changes
+
+Boundary findings:
+- New issue:
+  - CLI still directly exposes `--session-memory`; module-owned CLI registration remains a later concern
+- Impact on next stage:
+  - sub-stage 3 should document the seam and stop
+
+Decision:
+- continue
+
+Reason:
+- Retrofit passed focused validation and fixed the immediate coupling target without expanding scope.
+
+## Checkpoint: Sub-stage 3 Contracts And Terminal Validation
+
+State:
+- terminal
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Updated the runtime context and compaction contract doc to describe contribution seams and limits.
+- Verified central orchestration files no longer contain direct `session_memory` implementation details outside the explicit CLI UX.
+- Preserved deterministic-assist behavior while introducing module-upgrade infrastructure.
+
+Verification:
+- `rg -n "session_memory=|compact_summary_assist_text|read_session_memory_artifact|render_session_memory_line|SessionMemoryArtifact|SESSION_MEMORY_STATE_KEY" coding-deepgent/src/coding_deepgent/cli_service.py coding-deepgent/src/coding_deepgent/compact/summarizer.py coding-deepgent/src/coding_deepgent/sessions/resume.py coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py coding-deepgent/src/coding_deepgent/runtime/state.py coding-deepgent/src/coding_deepgent/sessions/__init__.py`
+- `pytest -q coding-deepgent/tests/test_session_contributions.py coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_cli.py coding-deepgent/tests/test_compact_summarizer.py`
+- `ruff check ...` on changed source/test files
+- `mypy ...` on changed source/test files
+
+cc-haha alignment:
+- Source files inspected:
+  - `/root/claude-code-haha/src/Tool.ts`
+  - `/root/claude-code-haha/src/utils/attachments.ts`
+  - `/root/claude-code-haha/src/utils/hooks.ts`
+  - `/root/claude-code-haha/src/utils/plugins/pluginLoader.ts`
+  - `/root/claude-code-haha/src/services/SessionMemory/sessionMemory.ts`
+- Aligned:
+  - useful pattern of module-owned contribution outputs consumed by central flow
+- Deferred:
+  - dynamic plugin registration
+  - broad lifecycle hooks
+  - threshold/background session memory
+- Do-not-copy:
+  - cc-haha's giant attachment union, broad context object, and loader complexity
+
+LangChain architecture:
+- Primitive used:
+  - pure dataclasses, static provider tuple, existing session/compact functions
+- Why no heavier abstraction:
+  - current need is module-local upgrade seams, not a framework/plugin runtime
+
+Boundary findings:
+- New issue:
+  - CLI command ownership remains centralized and should be treated as a later module-upgrade seam if it starts blocking feature work
+- Impact on next stage:
+  - `Threshold-Triggered Local Updates` can now build primarily inside `session_memory` providers and update logic
+
+Decision:
+- terminal
+
+Reason:
+- Stage 30A met the goal: contribution seams exist, `session_memory` is retrofitted behind them, focused validation passes, and no threshold/background feature work leaked in.
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-30a-module-upgrade-contribution-seams/task.json b/.trellis/tasks/archive/2026-04/04-15-stage-30a-module-upgrade-contribution-seams/task.json
new file mode 100644
index 000000000..dcde70b4a
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-30a-module-upgrade-contribution-seams/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-30a-module-upgrade-contribution-seams",
+  "name": "stage-30a-module-upgrade-contribution-seams",
+  "title": "Stage 30A: Module Upgrade Contribution Seams",
+  "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": null,
+  "relatedFiles": [],
+  "notes": "Reconciled on 2026-04-15: implemented and archived, but canonical handoff/roadmap still treat Stage 30-36 as reserve-only and not currently required for the MVP closeout path. Treat this as historical reserve work, not current mainline priority.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-30b-session-memory-threshold-local-updates/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-30b-session-memory-threshold-local-updates/check.jsonl
new file mode 100644
index 000000000..2d3c47c95
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-30b-session-memory-threshold-local-updates/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/spec/backend/runtime-context-compaction-contracts.md", "reason": "Session/compact contract checks"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-30b-session-memory-threshold-local-updates/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-30b-session-memory-threshold-local-updates/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-30b-session-memory-threshold-local-updates/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-30b-session-memory-threshold-local-updates/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-30b-session-memory-threshold-local-updates/implement.jsonl
new file mode 100644
index 000000000..137b4729e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-30b-session-memory-threshold-local-updates/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-30b-session-memory-threshold-local-updates/prd.md b/.trellis/tasks/archive/2026-04/04-15-stage-30b-session-memory-threshold-local-updates/prd.md
new file mode 100644
index 000000000..a28571b06
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-30b-session-memory-threshold-local-updates/prd.md
@@ -0,0 +1,280 @@
+# Stage 30B: Session Memory Threshold Local Updates
+
+## Goal
+
+Add threshold-triggered local `session_memory` updates on top of the Stage 30A contribution seams, without adding background extraction, implicit LLM calls on plain resume, mailbox, coordinator, or plugin runtime registration.
+
+## Concrete Benefit
+
+* Cross-session continuity: generated compact summaries can refresh the session-memory artifact when the existing artifact is missing or stale enough.
+* Modularity: update behavior should live behind module-owned contribution providers rather than central `session_memory` wiring.
+* Safety: updates happen only inside an already explicit generated compact-summary path, avoiding surprise model calls.
+
+## Scope Decision
+
+This stage implements a narrow form of "threshold-triggered local updates":
+
+* It does not auto-run summarization on plain `sessions resume --prompt`.
+* It does not add a background/session-memory extractor.
+* It piggybacks on explicit `--generate-compact-summary`, because that path already intentionally invokes the summarizer.
+* If the module-owned threshold policy says the artifact is missing or stale enough by message, estimated-token, or tool-call pressure, the generated compact summary is saved back into `loaded.state["session_memory"]`.
+
+## cc-haha Alignment
+
+### Expected effect
+
+Aligning this behavior should improve cross-session continuity and context-efficiency. The local runtime effect is: session memory can refresh at a deterministic boundary after generated compaction, without copying cc-haha's background post-sampling extractor.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Threshold policy | `SessionMemory/sessionMemoryUtils.ts` tracks initialization/update thresholds and extraction state | avoid refreshing session memory on every run | message-count threshold policy | partial | Align principle, not token/tool-call breadth |
+| Explicit/manual extraction | `sessionMemory.ts::manuallyExtractSessionMemory()` bypasses thresholds for explicit command paths | explicit user action can refresh session memory without background scheduling | generated compact summary path can refresh state | partial | Align explicit local update boundary |
+| Background extraction | post-sampling hook + forked agent extraction | richer future automation | none now | defer | Do not add in 30B |
+| Compaction consumption | `sessionMemoryCompact.ts` waits/loads session memory for compact | compact can benefit from current session memory | reuse Stage 30A compact assist contribution | align | Keep deterministic |
+
+### Source files 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/compact/sessionMemoryCompact.ts`
+
+## LangChain-Native Boundary
+
+Surface:
+* state and compact-summary service code
+
+Primary boundary:
+* product code under `coding_deepgent`, with no new LangChain middleware or graph runtime
+
+Smallest viable change:
+* add a compact-summary update contribution type
+* let `session_memory` own its refresh threshold and update behavior
+* have `cli_service.generated_compacted_continuation_history()` call generic update contributions after summary generation
+
+## Requirements
+
+* Add a generic compact-summary update contribution seam.
+* Add a `session_memory` provider that decides whether to refresh from a generated compact summary.
+* Refresh when:
+  * no valid artifact exists, or
+  * `current_message_count - artifact.message_count >= threshold`, or
+  * `current_estimated_token_count - artifact.token_count >= threshold`, or
+  * `current_tool_call_count - artifact.tool_call_count >= threshold`
+* Do not refresh when the artifact is still current enough.
+* Use the generated compact summary as the refreshed artifact content.
+* Preserve existing current/stale recovery and compact assist behavior.
+* Keep explicit `--session-memory` behavior unchanged.
+
+## Acceptance Criteria
+
+* [ ] Missing session-memory artifact refreshes from generated compact summary.
+* [ ] Stale-enough session-memory artifact refreshes from generated compact summary.
+* [ ] Current/recent session-memory artifact does not refresh.
+* [ ] Refresh behavior is owned by `session_memory` provider code.
+* [ ] `cli_service` consumes a generic compact-summary update contribution, not `session_memory` directly.
+* [ ] Focused tests, targeted ruff, and targeted mypy pass.
+
+## Out of Scope
+
+* plain resume auto-summarization
+* new CLI flags
+* token/tool-call thresholds
+* background session-memory extraction
+* forked child-agent extraction
+* plugin/dynamic contribution registration
+* mailbox/coordinator lifecycle
+
+## Technical Approach
+
+### Sub-stage 1: Compact Summary Update Contribution
+
+* Extend `sessions.contributions` with a `CompactSummaryUpdateContribution`.
+* Add helper to apply update contributions after a generated compact summary.
+* Add generic helper tests.
+
+### Sub-stage 2: Session Memory Threshold Provider
+
+* Add `session_memory` update-decision helpers and local pressure metrics.
+* Add provider that refreshes state from generated compact summaries when threshold says due.
+* Register provider in static contribution registry.
+* Wire `cli_service.generated_compacted_continuation_history()` to the generic helper.
+
+### Sub-stage 3: Contracts And Verification
+
+* Update runtime/compaction contract docs.
+* Run focused tests and targeted lint/typecheck.
+* Record terminal checkpoint.
+
+## Test Plan
+
+* `pytest -q coding-deepgent/tests/test_session_contributions.py`
+* `pytest -q coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_cli.py coding-deepgent/tests/test_compact_summarizer.py`
+* targeted `ruff check`
+* targeted `mypy`
+
+## Definition of Done
+
+* Focused tests pass.
+* Targeted ruff and mypy pass.
+* Stage checkpoint records cc-haha alignment and deferred background/session-memory behavior.
+
+## Checkpoint: Sub-stage 1 Compact Summary Update Contribution
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added `CompactSummaryUpdateContribution`.
+- Added `apply_compact_summary_update_contributions()` helper.
+- Added focused tests proving update contributions report which providers updated state.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_session_contributions.py`
+- `ruff check coding-deepgent/src/coding_deepgent/sessions/contributions.py coding-deepgent/tests/test_session_contributions.py`
+- `mypy coding-deepgent/src/coding_deepgent/sessions/contributions.py coding-deepgent/tests/test_session_contributions.py`
+
+cc-haha alignment:
+- Source files inspected:
+  - `/root/claude-code-haha/src/utils/hooks.ts`
+  - `/root/claude-code-haha/src/services/SessionMemory/sessionMemory.ts`
+- Aligned:
+  - introduced a lifecycle-style contribution point after generated compaction
+- Deferred:
+  - full hook runtime
+  - background extraction
+- Do-not-copy:
+  - pre/post compact shell hook breadth
+
+LangChain architecture:
+- Primitive used:
+  - pure dataclass descriptor and helper function
+- Why no heavier abstraction:
+  - no middleware or graph node is needed for a deterministic post-summary state update
+
+Boundary findings:
+- New issue:
+  - no blocker; session_memory still needs a provider
+- Impact on next stage:
+  - sub-stage 2 remains valid
+
+Decision:
+- continue
+
+Reason:
+- The update seam is small, tested, and behavior-neutral.
+
+## Checkpoint: Sub-stage 2 Session Memory Threshold Provider
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added `session_memory` refresh policy based on missing artifact, message-count delta, estimated-token delta, or tool-call delta.
+- Added local `session_memory_metrics()` for deterministic message/token/tool-call pressure calculation.
+- Added `session_memory` compact-summary update provider.
+- Registered the provider in the static contribution registry.
+- Wired generated compact summary flow through the generic update contribution helper.
+- Added regressions for missing, stale-enough, token pressure, tool-call pressure, and recent artifacts.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_session_contributions.py coding-deepgent/tests/test_cli.py coding-deepgent/tests/test_compact_summarizer.py`
+- `ruff check ...` on changed files
+- `mypy ...` on changed files
+
+cc-haha alignment:
+- Source files inspected:
+  - `/root/claude-code-haha/src/services/SessionMemory/sessionMemoryUtils.ts`
+  - `/root/claude-code-haha/src/services/SessionMemory/sessionMemory.ts`
+- Aligned:
+  - local update policy now has a threshold instead of refreshing every time
+  - local threshold policy includes message, estimated-token, and tool-call pressure
+  - explicit/generated compact path can refresh session memory without background extraction
+- Deferred:
+  - provider-accurate token accounting
+  - post-sampling hook
+  - forked extraction agent
+- Do-not-copy:
+  - remote config and extraction lifecycle
+
+LangChain architecture:
+- Primitive used:
+  - module-owned provider plus existing service flow
+- Why no heavier abstraction:
+  - generated compact summary already owns the summarizer call; no extra middleware or graph node is needed
+
+Boundary findings:
+- New issue:
+  - token counts are deterministic estimates from local message text, not provider tokenizer values
+- Impact on next stage:
+  - later provider-accurate token accounting can replace the metric internals without changing central flow
+
+Decision:
+- continue
+
+Reason:
+- The feature behavior is implemented behind contribution seams and passed focused validation. Remaining work is docs/final validation.
+
+## Checkpoint: Sub-stage 3 Contracts And Terminal Validation
+
+State:
+- terminal
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Updated runtime/compaction contract docs for `CompactSummaryUpdateContribution`.
+- Documented the exact local-update boundary:
+  - only `--generate-compact-summary` can refresh `session_memory`
+  - plain resume does not trigger implicit summarization
+  - missing/stale-enough artifacts refresh from generated summary based on message, estimated-token, or tool-call pressure
+  - current/recent artifacts do not refresh
+- Ran focused tests, targeted lint, and targeted typecheck.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_session_contributions.py coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_cli.py coding-deepgent/tests/test_compact_summarizer.py`
+- `ruff check ...` on changed source/test files
+- `mypy ...` on changed source/test files
+
+cc-haha alignment:
+- Source files 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/compact/sessionMemoryCompact.ts`
+- Aligned:
+  - threshold-gated session-memory updates now exist in local form
+  - local threshold policy includes message, estimated-token, and tool-call pressure
+  - compaction path can refresh continuity state at an explicit boundary
+- Deferred:
+  - provider-accurate token accounting
+  - post-sampling hook
+  - forked extraction agent
+  - automatic background update lifecycle
+- Do-not-copy:
+  - remote config and background extraction state machine
+
+LangChain architecture:
+- Primitive used:
+  - contribution provider and existing generated compact summary service
+- Why no heavier abstraction:
+  - local updates can piggyback on the already-explicit summarizer call; no extra model/middleware/runtime layer is needed
+
+Boundary findings:
+- New issue:
+  - token counts are deterministic estimates from local message text, not provider tokenizer values
+- Impact on next stage:
+  - next stage can either improve token accuracy with provider metrics or move to another module now that contribution seams exist
+
+Decision:
+- terminal
+
+Reason:
+- Stage 30B met scope without adding hidden model calls or background runtime.
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-30b-session-memory-threshold-local-updates/task.json b/.trellis/tasks/archive/2026-04/04-15-stage-30b-session-memory-threshold-local-updates/task.json
new file mode 100644
index 000000000..8c1f5221b
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-30b-session-memory-threshold-local-updates/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-30b-session-memory-threshold-local-updates",
+  "name": "stage-30b-session-memory-threshold-local-updates",
+  "title": "Stage 30B: Session Memory Threshold Local Updates",
+  "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": null,
+  "relatedFiles": [],
+  "notes": "Reconciled on 2026-04-15: implemented and archived, but canonical handoff/roadmap still treat Stage 30-36 as reserve-only and not currently required for the MVP closeout path. Treat this as historical reserve work, not current mainline priority.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-prd-status-reconciliation/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-prd-status-reconciliation/check.jsonl
new file mode 100644
index 000000000..738079fbe
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-prd-status-reconciliation/check.jsonl
@@ -0,0 +1,5 @@
+{"file": ".cursor/commands/trellis-finish-work.md", "reason": "Finish work checklist"}
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
+{"file": ".trellis/project-handoff.md", "reason": "Check final classifications against canonical current mainline status"}
+{"file": ".trellis/spec/guides/trellis-doc-map-guide.md", "reason": "Check archive decisions against Trellis task/archive ownership rules"}
+{"file": ".trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md", "reason": "Check final classifications against canonical MVP and reserve policy"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-prd-status-reconciliation/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-prd-status-reconciliation/debug.jsonl
new file mode 100644
index 000000000..e30f96d49
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-prd-status-reconciliation/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-prd-status-reconciliation/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-stage-prd-status-reconciliation/implement.jsonl
new file mode 100644
index 000000000..274ae935a
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-prd-status-reconciliation/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": ".trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md", "reason": "Canonical MVP boundary and Stage 30-36 reserve policy"}
+{"file": ".trellis/project-handoff.md", "reason": "Canonical current mainline status and latest stage-family completion claims"}
+{"file": ".trellis/spec/guides/trellis-doc-map-guide.md", "reason": "Task PRD vs archive ownership and canonical doc routing"}
+{"file": ".trellis/spec/backend/task-workflow-contracts.md", "reason": "Canonical task/plan/verifier contract coverage for Stage 17 classification"}
+{"file": ".trellis/spec/guides/staged-execution-guide.md", "reason": "Lean checkpoint discipline for this multi-stage reconciliation task"}
+{"file": ".trellis/spec/backend/runtime-context-compaction-contracts.md", "reason": "Canonical compact/session contract coverage for Stage 12-16 classification"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-prd-status-reconciliation/prd.md b/.trellis/tasks/archive/2026-04/04-15-stage-prd-status-reconciliation/prd.md
new file mode 100644
index 000000000..4d3354bb3
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-prd-status-reconciliation/prd.md
@@ -0,0 +1,275 @@
+# brainstorm: reconcile stage PRD status
+
+## Goal
+
+使用 Trellis workflow 处理当前遗留的 `stage-*` PRD：基于 canonical handoff、roadmap、contracts、task metadata、代码与测试证据，逐条判定这些 stage PRD 在当前主线中的真实状态，并执行相应的整理动作，使 `.trellis/tasks/` 中的 stage 任务状态与 `coding-deepgent` 的实际主线状态重新一致。
+
+## What I already know
+
+* 当前产品主线是 `coding-deepgent/`，canonical coordination layer 是 `.trellis/`。
+* `project-handoff.md` 明确写明当前主线已完成的 stage family 包括 `Stage 12` 到 `Stage 29`。
+* `project-handoff.md` 的当前推荐方向不是继续做这些历史 stage，而是 `release validation / PR cleanup for Approach A MVP`。
+* `.trellis/tasks/` 中当前仍有多个 `Stage 12A-17D` 任务处于未归档状态，其中大量 `task.py list` 状态仍显示为 `planning`。
+* `Stage 18A-19, 21-29, 30A-30B` 的 PRD 已经位于 `.trellis/tasks/archive/2026-04/` 下。
+* `Stage 20` 没有搜到独立的 `stage-20-*/prd.md` 文件。
+* handoff 的恢复策略建议优先阅读：
+  - `04-15-stage-17c-explicit-plan-artifact-boundary/prd.md`
+  - `04-15-stage-17d-verifier-subagent-execution-boundary/prd.md`
+  - archived `18A/18B/19`
+  - `04-15-coding-deepgent-highlight-completion-map/prd.md`
+  - archived `29`
+* 当前工作区干净，当前没有激活中的 task。
+* `mainline-scope-guide.md` 明确要求当前工作默认服务于 `coding-deepgent/` 与 `.trellis/`，不追 tutorial/reference parity。
+* `staged-execution-guide.md` 要求默认使用 `lean` 模式，只在需要时扩大验证范围。
+* `trellis-doc-map-guide.md` 明确 task PRD 负责在任务进行中记录 requirements、decision、checkpoint、verification evidence；仅当任务完成后才归档。
+* 当前未归档的 `Stage 12A-17D` 中，绝大多数 `task.json` 状态仍是 `planning`；`16B latest-valid-compact-view-selection` 已在 active tasks 中标记为 `completed` 但尚未归档。
+* archived `18A-19, 21-29` 的 `task.json` 状态是 `completed`，与归档位置一致。
+* archived `30A/30B` 的 `task.json` 状态目前也是 `completed`，但这与 roadmap/handoff 中“`Stage 30-36` reserve only / not currently required”存在潜在口径冲突，需要审计。
+
+## Assumptions (temporary)
+
+* 这次任务的目标不是重做 `Stage 12-29` 的实现，而是对 Trellis 任务层做状态校准与归档清理。
+* 如果某个 stage 的目标已经被后续 stage、canonical roadmap、handoff、contracts 与代码测试共同吸收，则应判为 `completed` 或 `superseded`，而不是继续保留为 active `planning`。
+* 如果某个 stage 明确属于 next-cycle / reserve / deferred scope，则应保留为 `deferred`，而不是归档为 `completed`。
+* “处理 PRD” 可能包括：
+  - 更新 task metadata / status
+  - 归档 active task
+  - 补充 PRD 中的结论说明
+  - 必要时更新 handoff / roadmap / Trellis notes
+
+## Open Questions
+
+* None after scope confirmation:
+  - reconcile active `12A-17D`
+  - review only archived `30A/30B` for reserve-policy conflict
+
+## Requirements (evolving)
+
+* 建立一个 stage PRD 审核清单，覆盖当前未归档与已归档的 `stage-*` PRD。
+* 为每个相关 stage PRD 给出一个明确状态结论：
+  - `completed`
+  - `superseded`
+  - `deferred`
+  - `needs_followup`（仅当现有证据不足）
+* 每个结论都必须绑定具体依据，至少来自以下来源中的两类：
+  - `project-handoff.md`
+  - canonical roadmap / completion map
+  - PRD 自身的 implementation / verification notes
+  - current code / tests / contracts
+  - task metadata / archive location
+* 对当前 active 但已完成或已被覆盖的 stage PRD，执行 Trellis 侧整理动作。
+* 对应归档/保留动作必须最小化且可解释，避免无依据地删除历史记录。
+* 若发现 handoff / roadmap / task state 三者冲突，需要记录冲突并决定 canonical source。
+
+## Code-Spec Depth Check
+
+* This task does not introduce a new product API, schema, or runtime contract in `coding-deepgent`.
+* The main executable boundary is Trellis task/archive semantics:
+  - how stage task state is classified
+  - when an active stage task should be archived
+  - which document is canonical when task metadata conflicts with handoff/roadmap
+* Concrete contract for this task:
+  - `project-handoff.md` and the canonical roadmap own current mainline stage status
+  - active task metadata must not contradict canonical completed stage families
+  - archived reserve tasks must not be mistaken for MVP-required completed stages
+* Validation/error matrix:
+  - Good: active historical stage has checkpoint evidence + canonical doc says family completed -> classify completed and archive
+  - Base: archived reserve stage exists with implemented notes but canonical doc says reserve/not required -> record as deferred/superseded conflict, do not reopen active work
+  - Bad: task metadata alone says `planning`/`completed` but canonical docs or PRD evidence disagree -> do not trust metadata alone
+
+## Research Notes
+
+### Relevant Specs
+
+* `.trellis/spec/guides/mainline-scope-guide.md`: keeps the task focused on `coding-deepgent` and `.trellis/`, not tutorial/reference cleanup.
+* `.trellis/spec/guides/staged-execution-guide.md`: establishes `lean` staged execution and checkpoint-driven progression for this audit/cleanup task.
+* `.trellis/spec/guides/trellis-doc-map-guide.md`: defines ownership between active task PRDs, canonical docs, and archive behavior.
+* `.trellis/spec/backend/runtime-context-compaction-contracts.md`: relevant when confirming Stage 12-16 status claims against current canonical compact/session contract coverage.
+* `.trellis/spec/backend/task-workflow-contracts.md`: relevant when confirming Stage 17C/17D status claims and verifier/task workflow boundaries.
+
+### Code Patterns Found
+
+* Stage PRDs record terminal evidence in `## Checkpoint` sections with `Implemented` and `Verification` blocks.
+  - Examples:
+    - `.trellis/tasks/04-14-stage-12a-context-payload-foundation/prd.md`
+    - `.trellis/tasks/04-14-stage-13a-manual-compact-boundary-and-summary-artifact/prd.md`
+    - `.trellis/tasks/04-15-stage-17c-explicit-plan-artifact-boundary/prd.md`
+* Archived completed stage tasks keep `task.json.status = "completed"` and live under `.trellis/tasks/archive/<year-month>/...`.
+  - Examples:
+    - `.trellis/tasks/archive/2026-04/04-15-stage-18a-verifier-execution-integration/task.json`
+    - `.trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/task.json`
+* `task.py archive` updates parent/child links and then moves the task directory; it does not infer or rewrite task conclusions on its own.
+  - Source:
+    - `.trellis/scripts/task.py`
+    - `.trellis/scripts/common/task_utils.py`
+
+### Files To Modify
+
+* `.trellis/tasks/04-15-stage-prd-status-reconciliation/prd.md`: record decisions, evidence table, and checkpoint.
+* Active stage task dirs under `.trellis/tasks/04-14-stage-*` and `.trellis/tasks/04-15-stage-17*`: update task metadata and/or archive them when classified as completed/superseded.
+* `.trellis/tasks/archive/2026-04/04-15-stage-30a-module-upgrade-contribution-seams/`
+* `.trellis/tasks/archive/2026-04/04-15-stage-30b-session-memory-threshold-local-updates/`
+  - record or normalize their deferred/reserve conflict if needed.
+
+### Initial Findings
+
+* All in-scope active stage PRDs from `12A` through `17D` contain completion-style checkpoint evidence, including implemented behavior and verification commands.
+* `Stage 16B latest-valid-compact-view-selection` is already marked `completed` in active tasks but still unarchived, which confirms task-state drift exists.
+* `project-handoff.md` and the archived completion map both state that Stage 12-19 stage families were completed as part of the current mainline.
+* `project-handoff.md` and the canonical roadmap explicitly state `Stage 30-36` are reserve-only and not currently required, which conflicts with archived `30A/30B` being labeled `completed`.
+
+## Technical Approach
+
+* Treat `project-handoff.md` plus the canonical roadmap/completion-map docs as the source of truth for current mainline stage-family status.
+* Use each stage PRD checkpoint as the task-level implementation/verification evidence.
+* Normalize stale active `task.json` metadata before archiving so archive state reflects the documented completion decision.
+* Archive historical active stage tasks with `task.py archive --no-commit` so Trellis link cleanup runs without violating the no-auto-commit rule for AI work.
+* For archived `30A/30B`, keep the task archived but add explicit notes that current canonical planning still treats Stage 30-36 as reserve-only.
+
+## Decision (ADR-lite)
+
+**Context**: Active stage tasks from `12A-17D` were still visible as `planning` or otherwise unarchived even though their PRDs contained terminal checkpoints and canonical docs treated those stage families as already complete. Archived `30A/30B` also carried `completed` metadata despite current canonical docs still describing Stage 30-36 as reserve-only.
+
+**Decision**:
+
+* Canonical current-state authority is `project-handoff.md` plus the canonical roadmap/completion-map docs, not stale task metadata.
+* Active `12A-17D` tasks with checkpoint evidence are historical completed work and should be archived.
+* `04-14-stage-16-compact-transcript-pruning-semantics` is a planning/scope PRD superseded by implemented `16A/16B/16C` follow-on stages and should be archived as historical planning work.
+* `04-14-stage-16b-virtual-pruning-compact-selection-hardening` is an orphan active task with no PRD and is superseded by the implemented `16B latest-valid-compact-view-selection` task.
+* Archived `30A/30B` remain archived historical work, but for current planning they should be treated as reserve/non-priority work until canonical docs are intentionally reopened.
+
+**Consequences**:
+
+* Active task lists now reflect the actual current mainline instead of historical stage residue.
+* Canonical resume docs remain unchanged and still govern the next recommended work.
+* Stage 30 reserve ambiguity is documented but does not reopen new implementation work during this cleanup pass.
+
+## Status Audit
+
+* `04-14-stage-12a-context-payload-foundation`: `completed`. Basis: PRD checkpoint documents implementation + verification; handoff and completion-map mark Stage 12 complete. Action: normalized metadata and archived.
+* `04-14-stage-12b-message-projection-and-tool-result-invariants`: `completed`. Basis: PRD checkpoint documents implementation + verification; handoff and completion-map mark Stage 12 complete. Action: normalized metadata and archived.
+* `04-14-stage-12c-recovery-brief-and-session-resume-audit`: `completed`. Basis: PRD checkpoint documents implementation + verification; handoff and completion-map mark Stage 12 complete. Action: normalized metadata and archived.
+* `04-14-stage-12d-memory-quality-policy`: `completed`. Basis: PRD checkpoint documents implementation + verification; handoff and completion-map mark Stage 12 complete. Action: normalized metadata and archived.
+* `04-14-stage-13a-manual-compact-boundary-and-summary-artifact`: `completed`. Basis: PRD checkpoint documents implementation + verification; handoff marks Stage 13 complete. Action: normalized metadata and archived.
+* `04-14-stage-13b-manual-compact-entry-point`: `completed`. Basis: PRD checkpoint documents implementation + verification; handoff marks Stage 13 complete. Action: normalized metadata and archived.
+* `04-14-stage-13c-compact-summary-generation-seam`: `completed`. Basis: PRD checkpoint documents implementation + verification; handoff marks Stage 13 complete. Action: normalized metadata and archived.
+* `04-14-stage-14a-explicit-generated-summary-cli-wiring`: `completed`. Basis: PRD checkpoint documents implementation + verification; handoff marks Stage 14A complete. Action: normalized metadata and archived.
+* `04-14-stage-15a-non-destructive-compact-transcript-records`: `completed`. Basis: PRD checkpoint documents implementation + verification; handoff marks Stage 15 complete. Action: normalized metadata and archived.
+* `04-14-stage-15b-compact-record-recovery-display`: `completed`. Basis: PRD checkpoint documents implementation + verification; handoff marks Stage 15 complete. Action: normalized metadata and archived.
+* `04-14-stage-15c-compacted-continuation-selection`: `completed`. Basis: PRD checkpoint documents implementation + verification; handoff marks Stage 15 complete. Action: normalized metadata and archived.
+* `04-14-stage-16-compact-transcript-pruning-semantics`: `superseded`. Basis: this PRD is a planning/decision artifact with no terminal implementation checkpoint; implemented `16A/16B/16C` follow-on tasks plus handoff/completion-map cover the realized Stage 16 outcome. Action: marked completed for historical archive cleanup and archived with a supersession note.
+* `04-14-stage-16a-load-time-compacted-history-view`: `completed`. Basis: PRD checkpoint documents implementation + verification; handoff marks Stage 16 complete. Action: normalized metadata and archived.
+* `04-14-stage-16b-latest-valid-compact-view-selection`: `completed`. Basis: PRD checkpoint documents implementation + verification; handoff marks Stage 16 complete. Action: archived.
+* `04-14-stage-16b-virtual-pruning-compact-selection-hardening`: `superseded`. Basis: active task had no PRD; the implemented `16B latest-valid-compact-view-selection` task exists and handoff treats Stage 16 as complete. Action: marked completed for historical archive cleanup and archived with an anomaly note.
+* `04-14-stage-16c-virtual-pruning-view-metadata`: `completed`. Basis: PRD checkpoint documents implementation + verification; handoff marks Stage 16 complete. Action: normalized metadata and archived.
+* `04-14-stage-17a-task-graph-readiness-and-transition-invariants`: `completed`. Basis: PRD checkpoint documents implementation + verification; handoff marks `17A` complete. Action: normalized metadata and archived.
+* `04-14-stage-17b-plan-verify-workflow-boundary`: `completed`. Basis: PRD checkpoint documents implementation + verification; handoff marks `17B` complete. Action: normalized metadata and archived.
+* `04-15-stage-17c-explicit-plan-artifact-boundary`: `completed`. Basis: PRD checkpoint documents implementation + verification; handoff marks `17C` complete. Action: normalized metadata and archived.
+* `04-15-stage-17d-verifier-subagent-execution-boundary`: `completed`. Basis: PRD checkpoint documents implementation + verification; handoff marks `17D` complete. Action: normalized metadata and archived.
+* `04-15-stage-30a-module-upgrade-contribution-seams`: `needs_followup`. Basis: archived PRD contains terminal checkpoints showing implementation, but handoff/roadmap still state Stage 30-36 are reserve-only and not currently required. Action: kept archived, added reserve-work note, do not reopen current mainline work from this cleanup task.
+* `04-15-stage-30b-session-memory-threshold-local-updates`: `needs_followup`. Basis: archived PRD contains terminal checkpoints showing implementation, but handoff/roadmap still state Stage 30-36 are reserve-only and not currently required. Action: kept archived, added reserve-work note, do not reopen current mainline work from this cleanup task.
+
+## Acceptance Criteria (evolving)
+
+* [x] 已列出本次处理范围内的 stage PRD 清单。
+* [x] 每个 stage PRD 都有状态结论和书面依据。
+* [x] 当前 active 但实际上已完成/已被覆盖的 stage PRD 得到 Trellis 侧处理。
+* [x] 明确保留 next-cycle / reserve PRD，不误归档为 completed。
+* [x] 若存在状态冲突，已记录 canonical decision。
+* [x] 所有相关 Trellis 变更经过一致性检查。
+
+## 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)
+
+* 重新实现 `Stage 12-29` 的产品代码
+* 打开新的功能 stage，除非审计证明存在真实 MVP 缺口
+* 无证据地删除历史 PRD 或重写历史结论
+* 对 tutorial/reference layer 做无关整理
+
+## Technical Notes
+
+* New task: `.trellis/tasks/04-15-stage-prd-status-reconciliation`
+* Canonical documents:
+  - `.trellis/project-handoff.md`
+  - `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+  - `.trellis/tasks/04-14-redefine-coding-deepgent-final-goal/prd.md`
+  - `.trellis/spec/backend/runtime-context-compaction-contracts.md`
+  - `.trellis/spec/backend/task-workflow-contracts.md`
+* Candidate bridge docs:
+  - `.trellis/tasks/archive/2026-04/04-15-coding-deepgent-highlight-completion-map/prd.md`
+* Historical active stage PRDs processed in this task:
+  - `12A-17D`
+* Already archived stage PRDs:
+  - `18A-19`
+  - `21-29`
+  - `30A-30B`
+* Current Trellis guidance for this task:
+  - use `.trellis/` as the canonical coordination layer
+  - treat task PRDs as the in-progress decision ledger
+  - prefer `lean` staged execution unless broader validation becomes necessary
+
+## Checkpoint: Stage PRD Status Reconciliation
+
+State:
+- terminal
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Created a dedicated Trellis task and PRD for stage-status reconciliation.
+- Researched canonical authority across handoff, roadmap, completion-map, and task/archive ownership docs.
+- Normalized active historical stage task metadata for `12A-17D`.
+- Archived all previously active historical stage tasks under `.trellis/tasks/archive/2026-04/`.
+- Added reserve-policy reconciliation notes to archived `30A/30B`.
+
+Verification:
+- `python3 ./.trellis/scripts/task.py list`
+- Verified parent brainstorm tasks now have empty `children` arrays after archive cleanup.
+- Parsed representative archived `task.json` files to confirm status/notes updates for:
+  - `12A`
+  - `16 planning`
+  - `16B orphan`
+  - `17D`
+  - `30A`
+  - `30B`
+
+Alignment:
+- source files inspected:
+  - `.trellis/project-handoff.md`
+  - `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+  - `.trellis/tasks/archive/2026-04/04-15-coding-deepgent-highlight-completion-map/prd.md`
+  - `.trellis/spec/guides/trellis-doc-map-guide.md`
+- aligned:
+  - current mainline status comes from canonical Trellis handoff/roadmap docs, not stale task metadata
+  - historical stage tasks should not remain active after the stage family is already canonicalized as complete
+- deferred:
+  - broader reconciliation of non-stage brainstorm/backlog tasks
+  - canonical decision on whether `30A/30B` should later be absorbed into current handoff/roadmap
+- do-not-copy:
+  - no broad rewrite of historical PRDs
+  - no reopening of reserve work as part of this cleanup pass
+
+Architecture:
+- primitive used:
+  - Trellis task PRD as the active decision ledger
+  - `task.py archive --no-commit` for safe archive moves and parent/child cleanup
+- why no heavier abstraction:
+  - this was a task-ledger reconciliation problem, not a product-runtime change
+
+Boundary findings:
+- `Stage 16` had both a planning PRD and a later implemented `16A/16B/16C` family; the planning doc should be treated as superseded planning, not pending implementation.
+- `04-14-stage-16b-virtual-pruning-compact-selection-hardening` was an orphan task with no PRD and required anomaly handling.
+- `30A/30B` are implemented historical work but still non-canonical for the current MVP closeout path.
+
+Decision:
+- stop
+
+Reason:
+- The approved scope is complete: active `12A-17D` tasks were reconciled and archived, and `30A/30B` conflict notes were recorded without reopening reserve work.
diff --git a/.trellis/tasks/archive/2026-04/04-15-stage-prd-status-reconciliation/task.json b/.trellis/tasks/archive/2026-04/04-15-stage-prd-status-reconciliation/task.json
new file mode 100644
index 000000000..392184e8c
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-stage-prd-status-reconciliation/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stage-prd-status-reconciliation",
+  "name": "stage-prd-status-reconciliation",
+  "title": "brainstorm: reconcile stage PRD status",
+  "description": "Use Trellis workflow to classify stage PRDs as completed, superseded, deferred, and perform the corresponding archive/cleanup actions based on canonical handoff, roadmap, and code evidence.",
+  "status": "completed",
+  "dev_type": "backend",
+  "scope": "Trellis stage task/archive reconciliation for historical Stage 12A-17D and reserve-review of 30A/30B",
+  "priority": "P1",
+  "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": null,
+  "relatedFiles": [],
+  "notes": "Completed on 2026-04-15: reconciled active historical stage tasks with canonical handoff/roadmap docs, archived 12A-17D, and recorded reserve-policy notes for 30A/30B.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-trellis-custom-skill-migration/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-trellis-custom-skill-migration/check.jsonl
new file mode 100644
index 000000000..d2ead72ba
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-trellis-custom-skill-migration/check.jsonl
@@ -0,0 +1,6 @@
+{"file": ".cursor/commands/trellis-finish-work.md", "reason": "Finish work checklist"}
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
+{"file": ".trellis/workflow.md", "reason": "verify migrated staged-workflow rules are canonical"}
+{"file": ".trellis/spec/backend/directory-structure.md", "reason": "verify modularity/boundary rules survive after skill deletion"}
+{"file": ".trellis/project-handoff.md", "reason": "verify project-handoff skill migration is complete"}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "verify LangChain guard rules are preserved in Trellis"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-trellis-custom-skill-migration/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-trellis-custom-skill-migration/debug.jsonl
new file mode 100644
index 000000000..e30f96d49
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-trellis-custom-skill-migration/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-trellis-custom-skill-migration/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-trellis-custom-skill-migration/implement.jsonl
new file mode 100644
index 000000000..8565b5b59
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-trellis-custom-skill-migration/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": ".trellis/project-handoff.md", "reason": "target handoff doc for project-handoff skill migration"}
+{"file": ".trellis/spec/backend/directory-structure.md", "reason": "target backend structure doc for LangChain boundary migration"}
+{"file": ".trellis/spec/guides/index.md", "reason": "guide index update for migrated custom skill knowledge"}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "target backend rule doc for LangChain architecture guard migration"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-trellis-custom-skill-migration/prd.md b/.trellis/tasks/archive/2026-04/04-15-trellis-custom-skill-migration/prd.md
new file mode 100644
index 000000000..867740758
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-trellis-custom-skill-migration/prd.md
@@ -0,0 +1,213 @@
+# brainstorm: migrate custom project skills into trellis and remove them
+
+## Goal
+
+将当前 `coding-deepgent` 主线工作所依赖的“项目定制 skill”能力迁移到 `.trellis/` 的正式规范与工作流文档中，使后续协作默认依赖 Trellis 文档而不是额外 skill；迁移完成后删除这些已被吸收的 skill 文件与入口，保留 Trellis 官方工作流 skill。
+
+## What I already know
+
+* 用户希望以后以 Trellis 能力为主，而不是继续依赖额外 skill。
+* 用户明确要求：
+  * 最终目标是把这些 skill 的能力迁移进对应 Trellis 文档
+  * 迁移完成后删除相关 skill
+  * `record-session` 不要动
+* 当前候选目标 skill 是：
+  * `/root/.codex/skills/cc-haha-alignment/SKILL.md`
+  * `/root/.codex/skills/langchain-architecture-guard/SKILL.md`
+  * `.agents/skills/stage-iterate/SKILL.md`
+  * `.agents/skills/project-handoff/SKILL.md`
+* 这些 skill 当前承担的高价值能力分别是：
+  * `cc-haha-alignment`
+    * expected effect 先行
+    * source-backed alignment matrix
+    * `align / partial / defer / do-not-copy` 决策记录
+  * `langchain-architecture-guard`
+    * 最小 LangChain/LangGraph 抽象
+    * strict schema / middleware / state / prompt / tool 边界
+    * 避免 fallback parser / 伪架构包装
+  * `stage-iterate`
+    * staged run / checkpoint gate
+    * `continue / adjust / split / stop`
+    * `lean / deep` 验证预算
+  * `project-handoff`
+    * 新会话最小 resume 读取顺序
+    * 当前主线 handoff 入口
+* 当前 Trellis 已经部分覆盖这些能力：
+  * `.trellis/project-handoff.md`
+  * `.trellis/workflow.md`
+  * `.trellis/spec/backend/index.md`
+  * `.trellis/spec/backend/directory-structure.md`
+  * `.trellis/spec/backend/quality-guidelines.md`
+  * `.trellis/spec/guides/mainline-scope-guide.md`
+  * 多个主线任务 PRD 已经直接内联 `cc-haha alignment` / `LangChain guard` / checkpoint 结构
+
+## Assumptions (temporary)
+
+* 这次迁移只处理“项目定制增强 skill”，不处理 Trellis 官方工作流 skill。
+* `.agents/skills/record-session/SKILL.md` 明确排除在删除范围外。
+* 如果某个 skill 的能力已经被 Trellis 原生文档或脚本完全承接，就应优先删除 skill 壳而不是继续双维护。
+* 如果某个 skill 仍有独特硬约束，则先迁规则，再删 skill。
+
+## Open Questions
+
+* None after current scope confirmation, unless迁移过程中发现 `project-handoff` 中仍有无法自然落进 Trellis 文档的特殊步骤。
+
+## Requirements (evolving)
+
+* 明确哪些 skill 属于“项目定制 skill”，哪些属于 Trellis 官方工作流 skill。
+* 只迁移并删除项目定制 skill，不动 Trellis 官方工作流 skill。
+* 为每个目标 skill 建立 Trellis 落点映射：
+  * 哪些规则进 `.trellis/workflow.md`
+  * 哪些规则进 `.trellis/spec/backend/*.md`
+  * 哪些规则进 `.trellis/spec/guides/*.md`
+  * 哪些规则进 `.trellis/project-handoff.md`
+* 迁移后，Trellis 文档应能独立承担这些 skill 原先提供的关键约束。
+* 删除已迁移的目标 skill 文件与相关入口引用。
+* 显式保留：
+  * `.agents/skills/record-session/SKILL.md`
+  * 其他 Trellis 官方工作流骨架 skill，除非后续另有明确指令
+
+## Acceptance Criteria (evolving)
+
+* [x] 有一份 source-backed 映射，说明每个目标 skill 的规则迁移到了哪些 Trellis 文档。
+* [x] `cc-haha-alignment` 的关键护栏已写入 Trellis，而不是仅存在 skill 中。
+* [x] `langchain-architecture-guard` 的关键护栏已写入 Trellis backend 规范。
+* [x] `stage-iterate` 的 checkpoint / validation-budget 规则已写入 Trellis workflow 或 guide。
+* [x] `project-handoff` 的最小 resume 读取规则已由 Trellis 文档承接。
+* [x] 目标 skill 文件已删除。
+* [x] `record-session` 未被修改或删除。
+
+## Definition of Done (team quality bar)
+
+* Docs/notes updated if behavior changes
+* Rollout/rollback considered if risky
+* Any path or prompt references to removed skills are updated
+* Remaining Trellis workflow still reads coherently for a new session
+
+## Out of Scope (explicit)
+
+* 删除 `record-session`
+* 删除 Trellis 官方工作流骨架 skill 的整套体系
+* 重写 `coding-deepgent` 产品功能代码，除非为修复 skill 删除后的引用断链所必需
+* 处理根 `skills/` 教学资产之外的其他教程层重构工作
+
+## Technical Notes
+
+* New child task:
+  * `.trellis/tasks/04-15-trellis-custom-skill-migration`
+* Parent task:
+  * `.trellis/tasks/04-15-trellis-spec-consolidation`
+* Candidate target docs:
+  * `.trellis/workflow.md`
+  * `.trellis/project-handoff.md`
+  * `.trellis/spec/backend/index.md`
+  * `.trellis/spec/backend/directory-structure.md`
+  * `.trellis/spec/backend/quality-guidelines.md`
+  * `.trellis/spec/guides/index.md`
+  * new Trellis guide(s) if existing docs are not a clean fit
+
+## Research Notes
+
+### Feasible Trellis landing map
+
+**`cc-haha-alignment`**
+
+Recommended landing:
+
+* new `.trellis/spec/guides/cc-alignment-guide.md`
+* references from `.trellis/workflow.md`
+* optional cross-link from backend index
+
+Why:
+
+* this is mostly a pre-implementation reasoning/decision discipline
+* it includes expected effect, source mapping, matrix, and do-not-copy rules
+
+**`langchain-architecture-guard`**
+
+Recommended landing:
+
+* `.trellis/spec/backend/directory-structure.md`
+* `.trellis/spec/backend/quality-guidelines.md`
+* optional new backend guideline if strict tool/schema guidance becomes too dense
+
+Why:
+
+* most rules are implementation constraints, not session workflow
+* they directly govern tool schemas, middleware, state, prompt placement, and modularity
+
+**`stage-iterate`**
+
+Recommended landing:
+
+* `.trellis/workflow.md`
+* optional new `.trellis/spec/guides/staged-execution-guide.md`
+
+Why:
+
+* it is a work-execution protocol: sub-stage progression, checkpoint gate, lean/deep validation budget
+
+**`project-handoff`**
+
+Recommended landing:
+
+* `.trellis/project-handoff.md`
+* `.trellis/workflow.md`
+
+Why:
+
+* it is already close to Trellis-native behavior
+* most of its value is canonical resume order and minimal refresh commands
+
+### Deletion boundary
+
+Delete after migration:
+
+* `/root/.codex/skills/cc-haha-alignment/SKILL.md`
+* `/root/.codex/skills/langchain-architecture-guard/SKILL.md`
+* `.agents/skills/stage-iterate/SKILL.md`
+* `.agents/skills/project-handoff/SKILL.md`
+
+Do not delete:
+
+* `.agents/skills/record-session/SKILL.md`
+
+### Implementation posture
+
+Recommended execution order:
+
+1. migrate `project-handoff`
+2. migrate `stage-iterate`
+3. migrate `cc-haha-alignment`
+4. migrate `langchain-architecture-guard`
+5. remove target skill files
+6. update references and re-read Trellis entry docs for coherence
+
+## Checkpoint: Custom Skill Migration
+
+State:
+
+* terminal
+
+Verdict:
+
+* APPROVE
+
+Implemented:
+
+* Migrated `cc-haha-alignment` into `.trellis/spec/guides/cc-alignment-guide.md`.
+* Migrated `langchain-architecture-guard` into `.trellis/spec/backend/langchain-native-guidelines.md` plus backend quality/structure docs.
+* Migrated `stage-iterate` into `.trellis/spec/guides/staged-execution-guide.md` and `.trellis/workflow.md`.
+* Migrated `project-handoff` into `.trellis/project-handoff.md` and `.trellis/workflow.md`.
+* Deleted target custom skill files and directories.
+* Kept `.agents/skills/record-session/SKILL.md`.
+
+Verification:
+
+* Confirmed target custom skill paths were removed.
+* Confirmed `.agents/skills/record-session/SKILL.md` still exists.
+* Scanned canonical Trellis docs for removed skill references and replaced current references with Trellis document links.
+
+Decision:
+
+* terminal for this custom skill migration task.
diff --git a/.trellis/tasks/archive/2026-04/04-15-trellis-custom-skill-migration/task.json b/.trellis/tasks/archive/2026-04/04-15-trellis-custom-skill-migration/task.json
new file mode 100644
index 000000000..08ab6ca19
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-trellis-custom-skill-migration/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "trellis-custom-skill-migration",
+  "name": "trellis-custom-skill-migration",
+  "title": "brainstorm: migrate custom project skills into trellis and remove them",
+  "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-15-trellis-spec-consolidation",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-trellis-docs-chinese-localization/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-trellis-docs-chinese-localization/check.jsonl
new file mode 100644
index 000000000..9bbd1eb61
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-trellis-docs-chinese-localization/check.jsonl
@@ -0,0 +1,2 @@
+{"file": ".cursor/commands/trellis-finish-work.md", "reason": "Finish work checklist"}
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-trellis-docs-chinese-localization/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-trellis-docs-chinese-localization/debug.jsonl
new file mode 100644
index 000000000..e30f96d49
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-trellis-docs-chinese-localization/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-trellis-docs-chinese-localization/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-trellis-docs-chinese-localization/implement.jsonl
new file mode 100644
index 000000000..137b4729e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-trellis-docs-chinese-localization/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-trellis-docs-chinese-localization/prd.md b/.trellis/tasks/archive/2026-04/04-15-trellis-docs-chinese-localization/prd.md
new file mode 100644
index 000000000..211432129
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-trellis-docs-chinese-localization/prd.md
@@ -0,0 +1,199 @@
+# brainstorm: localize trellis docs to chinese
+
+## Goal
+
+制定一个把 `.trellis/` 文档逐步中文化的迁移 PRD，使后续 Trellis 文档主要用简体中文叙述，同时保留英文术语、文件路径、命令、代码标识、task slug、结构化字段和值，避免破坏搜索、自动化和代码契约。
+
+## What I already know
+
+* 用户希望把 Trellis 文档中文化。
+* 用户明确要求保留：
+  * 英文术语
+  * 引用
+  * 文件路径
+  * 命令
+  * 结构字段
+* 用户要求先制定迁移 PRD。
+* 官方 Trellis `ch07-writing-specs` 指南允许中文项目使用中文，并强调：
+  * `index.md` 作为入口
+  * 每个 spec 文件专注一个主题
+  * 从实际代码/约定提炼
+  * spec 持续演进
+* 本地 `AGENTS.md` 已写明：
+  * Trellis narrative docs may be written in Simplified Chinese
+  * commands, file paths, file names, task slugs, branch names, code identifiers, structured fields keep English
+* 本地 `.trellis/workflow.md` 已有一致的语言约定。
+* 当前 `.trellis/` 里已有多份主线文档：
+  * `workflow.md`
+  * `project-handoff.md`
+  * `plans/`
+  * `spec/backend/`
+  * `spec/guides/`
+  * `spec/frontend/`
+  * `workspace/`
+
+## Assumptions (temporary)
+
+* 中文化应该优先处理当前主线高价值文档，而不是一次性翻译所有历史 plan/task。
+* `spec/guides/*` 最适合第一批，因为叙述性强、结构清晰、风险低。
+* `spec/backend/*` 中的 signatures、test names、code snippets、status values 必须保留英文。
+* `plans/*` 有大量历史和 roadmap 状态，应暂缓或单独处理。
+
+## Open Questions
+
+* None for initial PRD draft; default recommendation is phased localization.
+
+## Requirements (evolving)
+
+* 明确中文化范围和排除范围。
+* 建立术语/结构保留规则。
+* 分批迁移，避免一次性大改导致 review 困难。
+* 每批迁移后运行 Trellis link check。
+* 迁移后文档不能丢失原有 contract、路径、命令、test references、status vocabulary。
+
+## Acceptance Criteria (evolving)
+
+* [x] PRD 明确哪些 Trellis 文档优先中文化。
+* [x] PRD 明确保留英文的内容类型。
+* [x] PRD 明确每一批迁移的文件范围。
+* [x] PRD 明确验证方式。
+* [x] PRD 明确 out-of-scope，避免误改历史/自动化敏感内容。
+
+## Definition of Done (team quality bar)
+
+* Docs/notes updated if behavior changes
+* Trellis link check passes after each implementation batch
+* No path/command/status/code contract is accidentally translated
+
+## Out of Scope (explicit)
+
+* 当前任务不直接批量翻译全部 `.trellis/`
+* 不翻译代码块中的命令、签名、路径、测试名
+* 不翻译 JSON/YAML keys 或结构化 status values
+* 不优先翻译历史任务归档、workspace journal、旧 provenance plan
+* 不服务教程/reference 层
+
+## Technical Notes
+
+* New child task:
+  * `.trellis/tasks/04-15-trellis-docs-chinese-localization`
+* Parent task:
+  * `.trellis/tasks/04-15-trellis-spec-consolidation`
+* Existing language convention sources:
+  * `AGENTS.md`
+  * `.trellis/workflow.md`
+  * `.trellis/spec/backend/index.md`
+  * `.trellis/spec/frontend/index.md`
+* Suggested verification:
+  * `python3 ./.trellis/scripts/check_trellis_links.py`
+  * targeted grep for accidentally translated path/status markers where useful
+
+## Research Notes
+
+### Official / local guidance
+
+Official Trellis guidance permits Chinese for Chinese projects and recommends
+topic-focused, concrete, continuously evolving specs.
+
+Local repo guidance already permits Simplified Chinese narrative while keeping
+commands, paths, slugs, identifiers, structured fields, and automation keywords
+in English.
+
+### Feasible approaches
+
+**Approach A: Phased mainline localization** (Recommended)
+
+How:
+
+* Phase 1: localize `spec/guides/*`
+* Phase 2: localize `spec/backend/index.md` and narrative sections in active backend specs
+* Phase 3: localize `workflow.md` and `project-handoff.md`
+* Phase 4: selectively localize `plans/index.md` and current canonical roadmap summaries
+* Leave historical plans/tasks mostly as-is unless actively maintained.
+
+Pros:
+
+* Reviewable.
+* Low risk to contracts and automation.
+* Aligns with current mainline.
+
+Cons:
+
+* Mixed-language state remains during migration.
+
+**Approach B: Full `.trellis/` localization**
+
+How:
+
+* Translate nearly all Trellis markdown docs in one large pass.
+
+Pros:
+
+* Fast apparent completion.
+
+Cons:
+
+* High risk of corrupting paths, commands, contract examples, and historical provenance.
+* Hard to review.
+
+**Approach C: Only future docs in Chinese**
+
+How:
+
+* Leave existing docs as-is; write only new docs in Chinese.
+
+Pros:
+
+* Lowest risk.
+
+Cons:
+
+* Does not satisfy the desire to improve current Trellis readability.
+
+## Decision (ADR-lite)
+
+**Context**: The project is Chinese-led, and local conventions already allow Simplified Chinese narrative. However, many Trellis docs contain code contracts, paths, commands, and status vocabulary that must remain stable.
+
+**Decision**: Prefer Approach A: phased mainline localization.
+
+**Consequences**:
+
+* First implementation batch should target `spec/guides/*`.
+* Plans and historical task docs should not be batch-translated until there is a concrete need.
+* Every batch must preserve English technical tokens and run link checks.
+
+## Checkpoint: Phase 1 Guides Localization
+
+State:
+
+* terminal
+
+Verdict:
+
+* APPROVE
+
+Implemented:
+
+* Localized `.trellis/spec/guides/*.md` narrative content to Simplified Chinese.
+* Preserved English technical tokens, paths, commands, status values, code identifiers, and structured field names.
+* Kept guide purposes and routing semantics intact.
+
+Files changed:
+
+* `.trellis/spec/guides/index.md`
+* `.trellis/spec/guides/trellis-doc-map-guide.md`
+* `.trellis/spec/guides/interview-driven-spec-expansion-guide.md`
+* `.trellis/spec/guides/mainline-scope-guide.md`
+* `.trellis/spec/guides/cc-alignment-guide.md`
+* `.trellis/spec/guides/staged-execution-guide.md`
+* `.trellis/spec/guides/cross-layer-thinking-guide.md`
+* `.trellis/spec/guides/code-reuse-thinking-guide.md`
+
+Verification:
+
+* `python3 ./.trellis/scripts/check_trellis_links.py` passed.
+* Scanned localized guides for old placeholder/template markers and removed-skill references.
+
+Decision:
+
+* terminal for the initial PRD + Phase 1 implementation slice.
diff --git a/.trellis/tasks/archive/2026-04/04-15-trellis-docs-chinese-localization/task.json b/.trellis/tasks/archive/2026-04/04-15-trellis-docs-chinese-localization/task.json
new file mode 100644
index 000000000..bd1e41d2d
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-trellis-docs-chinese-localization/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "trellis-docs-chinese-localization",
+  "name": "trellis-docs-chinese-localization",
+  "title": "brainstorm: localize trellis docs to chinese",
+  "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-15-trellis-spec-consolidation",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-trellis-docs-synthesis-interview/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-trellis-docs-synthesis-interview/check.jsonl
new file mode 100644
index 000000000..9bbd1eb61
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-trellis-docs-synthesis-interview/check.jsonl
@@ -0,0 +1,2 @@
+{"file": ".cursor/commands/trellis-finish-work.md", "reason": "Finish work checklist"}
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-trellis-docs-synthesis-interview/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-trellis-docs-synthesis-interview/debug.jsonl
new file mode 100644
index 000000000..e30f96d49
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-trellis-docs-synthesis-interview/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-trellis-docs-synthesis-interview/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-trellis-docs-synthesis-interview/implement.jsonl
new file mode 100644
index 000000000..2605d2843
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-trellis-docs-synthesis-interview/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/guides/index.md", "reason": "target guide index for interview-driven spec expansion"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-trellis-docs-synthesis-interview/prd.md b/.trellis/tasks/archive/2026-04/04-15-trellis-docs-synthesis-interview/prd.md
new file mode 100644
index 000000000..5e62ea1ac
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-trellis-docs-synthesis-interview/prd.md
@@ -0,0 +1,738 @@
+# brainstorm: trellis docs synthesis and interview expansion
+
+## Goal
+
+围绕当前 `coding-deepgent` 主线的 `.trellis/` 文档体系，整理总结已有 Trellis 文档、确认这种“文档收束/总结”是否符合 Trellis 官方推荐实践，并设计一套通过采访用户进一步补充 Trellis 文档的工作方式，使后续规范建设更系统、更可持续。
+
+## What I already know
+
+* 用户的下一步任务意图是：
+  * 整理总结已有的 Trellis 文档
+  * 通过采访的形式进一步补充 Trellis 文档
+  * 联网学习 Trellis 用法
+* 用户明确给出了官方参考入口：
+  * `https://docs.trytrellis.app/zh/guide/ch07-writing-specs`
+* 用户明确给出了主要社区参考方向：
+  * Linux Do
+* 当前仓库的主线已经明确为 `coding-deepgent/` + `.trellis/`。
+* 当前 `.trellis/` 已包含：
+  * `workflow.md`
+  * `project-handoff.md`
+  * `plans/`
+  * `spec/backend/*`
+  * `spec/guides/*`
+  * `workspace/`
+* 当前 Trellis 文档经过前面几轮收口，已经开始承担：
+  * 主线范围定义
+  * 后端结构规范
+  * 质量规范
+  * cc 对齐方法
+  * staged execution 方法
+* Trellis 官方“规范编写指南”明确推荐：
+  * `index.md` 作为入口，列出规范文件及状态
+  * 每个 spec 文件只专注一个主题
+  * 从**实际代码中提取模式**来填充 spec
+  * spec 应该**持续演进**，而不是一次写完
+* Linux Do 上的实际使用反馈强调：
+  * Trellis 的价值在于把团队约定整理成结构化文档并按需注入
+  * 预生成 spec 往往会有空白，必须后续手工补全
+  * 训练/推广场景里，团队确实会再写“培训文档”或“介绍文档”，但这通常是补充层，不应替代原子化 spec
+
+## Assumptions (temporary)
+
+* 这个任务首先是“规范设计/工作流设计”问题，而不是立即大规模改写全部 Trellis 文档。
+* “采访”更像是一种 requirements/spec discovery 方法，需要被写成 Trellis 内的可复用流程，而不是临时聊天习惯。
+* 官方 Trellis 文档很可能强调如何写 spec，而不一定直接给出“采访式补充 spec”的现成模板；如果没有，需要结合官方原则做本地化设计。
+
+## Open Questions
+
+* None. User delegated future low-risk process choices to the recommended option.
+
+## Requirements (evolving)
+
+* 研究 Trellis 官方文档，确认现有 `.trellis/` 文档整理/总结是否符合推荐实践。
+* 研究 Linux Do 上与 Trellis 使用、spec 编写、项目落地相关的高价值讨论。
+* 盘点当前仓库已有 Trellis 文档的类型、职责、重叠区与空白区。
+* 优先产出一份 Trellis 文档地图，说明 `.trellis/` 内各层文档的职责、入口关系、阅读顺序与修改落点。
+* 这份文档地图需要同时服务：
+  * 项目维护者：理解 `.trellis/` 的职责分层与长期维护方式
+  * AI agent：知道先读什么、改哪里、如何把新信息写回正确文档
+* 文档地图采用**单独 guide** 形态，而不是仅靠现有 `index.md` 承载。
+* 文档地图初版只覆盖当前 `coding-deepgent` 主线高价值 Trellis 文档，不把 `.trellis/` 所有脚本/配置/内部文件都画进去。
+* 设计一套“采访式补充 Trellis 文档”的流程，并写入 Trellis。
+* 该流程应能指导后续 agent：
+  * 先读现有 Trellis
+  * 找空白
+  * 通过逐步采访补足事实
+  * 将结果落到正确 Trellis 文档
+
+## Acceptance Criteria (evolving)
+
+* [x] PRD 记录了官方文档对 spec 编写/维护的关键建议。
+* [x] PRD 记录了 Linux Do 上与 Trellis 落地相关的高价值经验。
+* [x] 当前 `.trellis/` 文档被分类整理，并识别出高价值空白区。
+* [x] 形成一份高可读的 Trellis 文档地图，解释当前 `.trellis/` 文档体系。
+* [x] 形成一套采访式补充 Trellis 文档的可执行流程。
+* [x] 明确哪些 Trellis 文档应继续汇总整理，哪些应保持原子化。
+
+## Definition of Done (team quality bar)
+
+* Docs/notes updated if behavior changes
+* Workflow remains coherent for future sessions
+* New guidance is specific enough for repeated use
+
+## Out of Scope (explicit)
+
+* 立即重写全部 `.trellis/` 文档
+* 为了“看起来完整”而填充低价值 spec 模板
+* 脱离 `coding-deepgent` 主线去服务教程/reference 层
+
+## Technical Notes
+
+* New child task:
+  * `.trellis/tasks/04-15-trellis-docs-synthesis-interview`
+* Parent task:
+  * `.trellis/tasks/04-15-trellis-spec-consolidation`
+* Likely target docs:
+  * `.trellis/workflow.md`
+  * `.trellis/spec/guides/index.md`
+  * `.trellis/spec/backend/index.md`
+  * new guide for Trellis doc map
+  * possibly a new guide for interview-driven doc expansion
+
+## Current Trellis Doc Map
+
+### Workflow / Coordination
+
+* `.trellis/workflow.md`
+  * 总工作流、读取顺序、开发过程、阶段执行协议
+* `.trellis/project-handoff.md`
+  * `coding-deepgent` 主线的最小恢复入口
+
+### Planning / Product Memory
+
+* `.trellis/plans/index.md`
+  * 长期计划入口
+* `.trellis/plans/*.md`
+  * 主线 roadmap / reconstructed master plan / runtime foundation specs
+
+### Specs / Norms
+
+* `.trellis/spec/backend/*`
+  * 后端主线规范，已有部分 Active 文档
+* `.trellis/spec/guides/*`
+  * 思维指南、cc 对齐、staged execution、mainline scope
+* `.trellis/spec/frontend/*`
+  * 目前大多仍是模板/占位
+
+### Session Memory / Records
+
+* `.trellis/workspace/index.md`
+  * 工作记录总索引
+* `.trellis/workspace/<developer>/journal-N.md`
+  * 会话记录
+
+## Current Gaps
+
+* 缺少一份“如何理解整个 `.trellis/` 文档体系”的高层地图文档。
+* 缺少一份“如何通过采访补 spec”的明确流程文档。
+* backend 规范已经开始具体化，但 frontend 规范仍然大量空白。
+* workflow、handoff、spec、plans、workspace 之间的职责关系，对新协作者仍然不够一眼看懂。
+
+## Research Notes
+
+### Official Trellis docs say
+
+Source:
+
+* `https://docs.trytrellis.app/zh/guide/ch07-writing-specs`
+
+Key points:
+
+* `index.md` should be the entrypoint listing spec files and their status.
+* Each spec file should focus on one topic.
+* Specs should be filled from actual code and actual conventions, not ideals.
+* Good specs are concrete, with code and reasons.
+* Specs should evolve continuously after bugs, better patterns, and team decisions.
+
+Inference for this repo:
+
+* “整理总结已有 Trellis 文档” is aligned with official guidance **only if** it means:
+  * clarifying entrypoints
+  * reducing overlap
+  * improving categorization
+  * filling blanks from actual practice
+* It is **not** aligned if it means replacing topic docs with one giant summary file.
+
+### Linux Do usage signals
+
+Source examples:
+
+* `https://linux.do/t/topic/1850897`
+* `https://linux.do/t/topic/1803999`
+* `https://linux.do/t/topic/1868950`
+
+High-signal takeaways:
+
+* Teams use Trellis to turn implicit habits into structured project memory/specs.
+* People often need extra explanation/training docs because the raw Trellis structure is powerful but not self-explanatory.
+* Empty or partially filled specs are a common pain point; users expect later补全.
+* Too much process or too many questions can increase token/interaction cost, so补全文档的流程应该是渐进式、按需、逐主题推进。
+
+### Constraints from our repo/project
+
+* Current `.trellis/` already has multiple useful docs, but navigation and role boundaries are still not fully summarized.
+* We just moved more project knowledge into Trellis, so this is the right moment to create a cleaner synthesis layer.
+* The repo mainline is `coding-deepgent`, so the synthesis/interview flow should serve product/mainline docs first, not tutorial/reference docs.
+
+### Feasible approaches here
+
+**Approach A: Index-first synthesis + gap-driven interview** (Recommended)
+
+* How it works:
+  * Keep existing Trellis docs as atomic source-of-truth.
+  * Add or improve a small number of synthesis/index docs to explain roles, boundaries, and reading order.
+  * Build an interview workflow that finds one missing area at a time, asks targeted questions, then writes the answer into the correct topic doc.
+* Pros:
+  * Matches official Trellis guidance best.
+  * Keeps docs maintainable.
+  * Works well for iterative AI/human collaboration.
+* Cons:
+  * Requires discipline to avoid “summary doc” drift.
+
+**Approach B: Big Trellis handbook first**
+
+* How it works:
+  * Create one large Trellis handbook that summarizes everything, then update topic docs later.
+* Pros:
+  * Easy for humans to skim initially.
+* Cons:
+  * Conflicts with official topic-first guidance.
+  * High drift risk.
+  * Easy to become a second source-of-truth.
+
+**Approach C: Interview-first, summarize later**
+
+* How it works:
+  * Start interviewing immediately, capture answers into PRDs or notes, then reorganize docs afterward.
+* Pros:
+  * Fast feedback from the user.
+* Cons:
+  * Easy to collect facts without a stable Trellis information architecture.
+  * Rework risk is higher.
+
+## Decision (ADR-lite)
+
+**Context**: The repo now has enough Trellis content that navigation, overlap control, and gap-filling strategy matter. The user wants both doc synthesis and interview-driven expansion, and official Trellis guidance favors topic-focused, evolving specs over a monolithic handbook.
+
+**Decision**: Default to Approach A unless the user explicitly prefers a different path.
+
+**Consequences**:
+
+* We should first classify and summarize current Trellis docs by role.
+* We should design an interview workflow that fills gaps into the correct target docs.
+* We should avoid turning the result into one giant “master Trellis doc”.
+
+### Progress update
+
+* User selected the mixed-mode path with priority on **Trellis doc map first**.
+* User selected the Trellis doc map audience as **both maintainers and AI agents**.
+* User selected the doc-map carrier as **a standalone Trellis guide**.
+* User selected the initial doc-map scope as **current mainline high-value Trellis docs only**.
+
+## Final Confirmation Draft
+
+Goal:
+
+* Create a standalone Trellis doc map guide for the current `coding-deepgent` mainline, then use it as the foundation for later interview-driven Trellis spec expansion.
+
+Requirements:
+
+* Use official Trellis spec-writing guidance:
+  * index as entrypoint
+  * topic-focused docs
+  * actual-code/actual-convention extraction
+  * continuous evolution
+* Use Linux Do feedback as supporting context:
+  * Trellis adoption benefits from structured explanation
+  * empty specs need follow-up filling
+  * avoid over-heavy process and token waste
+* Create a standalone guide under `.trellis/spec/guides/`.
+* Serve both maintainers and AI agents:
+  * maintainers need role boundaries and maintenance rules
+  * agents need reading order and update target rules
+* Scope the first version to high-value mainline docs:
+  * `.trellis/workflow.md`
+  * `.trellis/project-handoff.md`
+  * `.trellis/plans/index.md`
+  * `.trellis/plans/*.md` high-level categories
+  * `.trellis/spec/backend/index.md`
+  * `.trellis/spec/backend/*.md` high-level categories
+  * `.trellis/spec/guides/index.md`
+  * `.trellis/spec/guides/*.md` high-level categories
+  * `.trellis/workspace/index.md`
+* Do not cover every `.trellis/scripts/*`, config, or internal task file in the first version.
+
+Acceptance Criteria:
+
+* [x] A new standalone guide explains current high-value Trellis doc roles.
+* [x] The guide includes reading order for maintainers and AI agents.
+* [x] The guide includes “where to write new knowledge” rules.
+* [x] The guide states how it supports later interview-driven expansion.
+* [x] `.trellis/spec/guides/index.md` links to the new guide.
+
+Technical Approach:
+
+* Add `.trellis/spec/guides/trellis-doc-map-guide.md`.
+* Update `.trellis/spec/guides/index.md`.
+* Keep the guide as a map, not a duplicate source-of-truth for every rule.
+
+Implementation Plan:
+
+* PR1 / Slice 1: Add the doc-map guide and index link. Completed.
+* PR2 / Slice 2: Add interview-driven spec expansion guide after the map is accepted. Completed.
+
+## Checkpoint: Trellis Doc Map Guide
+
+State:
+
+* checkpoint
+
+Verdict:
+
+* APPROVE
+
+Implemented:
+
+* Added `.trellis/spec/guides/trellis-doc-map-guide.md`.
+* Added guide index entry and trigger in `.trellis/spec/guides/index.md`.
+* The guide covers:
+  * high-value document layers
+  * maintainer reading order
+  * AI agent reading order
+  * write-target rules for new knowledge
+  * summary vs atomic spec boundary
+  * interview-driven expansion routing
+
+Verification:
+
+* Checked the new file exists.
+* Checked `.trellis/spec/guides/index.md` links to `trellis-doc-map-guide.md`.
+
+Decision:
+
+* continue to PR2 / Slice 2 when user wants to design the interview-driven expansion guide.
+
+## Checkpoint: Interview-Driven Spec Expansion Guide
+
+State:
+
+* checkpoint
+
+Verdict:
+
+* APPROVE
+
+Implemented:
+
+* Added `.trellis/spec/guides/interview-driven-spec-expansion-guide.md`.
+* Added guide index entry and trigger in `.trellis/spec/guides/index.md`.
+* The guide covers:
+  * when to interview
+  * when not to interview
+  * target-doc selection
+  * one-question interview rule
+  * immediate write-back into owning Trellis doc
+  * PRD interview trail format
+  * MVP interview loop and stop conditions
+
+Verification:
+
+* Checked the new file exists.
+* Checked `.trellis/spec/guides/index.md` links to `interview-driven-spec-expansion-guide.md`.
+
+Decision:
+
+* terminal for the initial brainstorm implementation slice.
+
+## Interview Note: Frontend Spec Activation Strategy
+
+Question:
+
+* For deferred `frontend/*` specs, choose long-term deferred, reference-only simple note, or future-activatable template.
+
+Answer:
+
+* Future-activatable template.
+
+Target docs:
+
+* `.trellis/spec/frontend/index.md`
+* `.trellis/spec/frontend/directory-structure.md`
+* `.trellis/spec/frontend/component-guidelines.md`
+* `.trellis/spec/frontend/hook-guidelines.md`
+* `.trellis/spec/frontend/state-management.md`
+* `.trellis/spec/frontend/type-safety.md`
+* `.trellis/spec/frontend/quality-guidelines.md`
+
+Change made:
+
+* Marked frontend specs as deferred because `coding-deepgent/` is current mainline.
+* Added activation requirements so future frontend/web product work can reactivate these specs without treating current reference UI as mainline.
+
+## Checkpoint: Fast Trellis Gap Fill
+
+State:
+
+* checkpoint
+
+Verdict:
+
+* APPROVE
+
+Implemented:
+
+* Filled `backend/database-guidelines.md` with current no-SQL/store/session persistence guidance.
+* Filled `backend/error-handling.md` with current error-boundary conventions.
+* Filled `backend/logging-guidelines.md` with current `structlog` and evidence-vs-log guidance.
+* Marked frontend specs as future-activatable deferred specs.
+
+Verification:
+
+* Derived backend guidance from current `coding-deepgent/src` and tests.
+* Recorded the frontend activation decision from user interview.
+
+Decision:
+
+* continue when the next gap-fill batch is requested.
+
+## Interview Note: Error Handling Strictness
+
+Question:
+
+* Should error handling prefer fail-fast, user-experience-first errors, or a mixed but strict boundary posture?
+
+Answer:
+
+* Mixed but strict.
+
+Target doc:
+
+* `.trellis/spec/backend/error-handling.md`
+
+Change made:
+
+* Added default posture and boundary decision matrix:
+  * schema/domain/service fail fast
+  * model-visible tools return bounded `"Error: ..."` when appropriate
+  * CLI converts expected failures to `ClickException` / `typer.Exit`
+  * recoverable middleware fails open only when a contract explicitly allows it
+
+## Interview Note: Evidence Vs Logs Boundary
+
+Question:
+
+* Should session evidence record only high-value recoverable facts, record more runtime events, or stay extremely minimal?
+
+Answer:
+
+* Evidence should record only high-value recoverable facts.
+
+Target doc:
+
+* `.trellis/spec/backend/logging-guidelines.md`
+
+Change made:
+
+* Added default evidence posture.
+* Documented current whitelisted runtime evidence kinds:
+  * `hook_blocked`
+  * `permission_denied`
+  * `microcompact`
+  * `auto_compact`
+  * `reactive_compact`
+* Clarified that successful ordinary tool calls, hook start/complete events, config/startup diagnostics, and non-contractual debug details should stay as logs.
+
+## Interview Note: Project Handoff Update Policy
+
+Question:
+
+* Should `.trellis/project-handoff.md` update on milestones, every session, or only release/PR boundaries?
+
+Answer:
+
+* Milestone updates.
+
+Target docs:
+
+* `.trellis/project-handoff.md`
+* `.trellis/spec/guides/trellis-doc-map-guide.md`
+
+Change made:
+
+* Added handoff update policy:
+  * update when mainline stage family, canonical roadmap/dashboard, latest verified state, next recommended task, canonical cross-session requirement, or minimal resume reading order changes
+  * do not update for ordinary daily progress or minor session summaries
+  * use workspace journals via `record-session` for ordinary session records
+* Updated Trellis doc map write-target rules to distinguish mainline handoff updates from ordinary completed-session records.
+
+## Checkpoint: Interview Workflow In Main Workflow
+
+State:
+
+* checkpoint
+
+Verdict:
+
+* APPROVE
+
+Implemented:
+
+* Added interview-driven spec expansion references to `.trellis/workflow.md`.
+* Added a workflow section requiring:
+  * derive first
+  * choose owning Trellis doc before asking
+  * ask one targeted question
+  * write answer immediately
+  * record interview note in active PRD
+
+Verification:
+
+* Manual read of the updated workflow section.
+
+Decision:
+
+* continue with next interview topic.
+
+## Interview Note: Plans Vs Specs Boundary
+
+Question:
+
+* Should future agents treat plans as direction and specs as executable constraints, minimize plans, or make plans the source of all design before deriving specs?
+
+Answer:
+
+* Plans write direction; specs write executable constraints.
+
+Target docs:
+
+* `.trellis/spec/guides/trellis-doc-map-guide.md`
+* `.trellis/spec/guides/interview-driven-spec-expansion-guide.md`
+
+Change made:
+
+* Added plans-vs-specs boundary:
+  * `plans/` own product goals, roadmap rows, stage sequencing, strategic tradeoffs, deferred/do-not-copy decisions, milestone boundaries
+  * `spec/` owns implementation contracts, schemas/signatures, module boundaries, validation/error matrices, testing requirements, concrete do/don't rules
+  * plan decisions that become mandatory for implementation should be extracted into the owning spec
+
+## Interview Note: Task PRD Vs Workspace Journal Boundary
+
+Question:
+
+* Should task PRDs record task-internal decisions while journals record completed sessions, or should more process move into journals?
+
+Answer:
+
+* PRD records task-internal decisions; journal records completed sessions.
+
+Target docs:
+
+* `.trellis/spec/guides/trellis-doc-map-guide.md`
+* `.trellis/spec/guides/interview-driven-spec-expansion-guide.md`
+* `.trellis/workflow.md`
+
+Change made:
+
+* Added PRD-vs-journal boundary:
+  * active task PRD owns requirements, interview notes, scope decisions, checkpoints, verification evidence, unresolved questions
+  * workspace journal owns completed session summaries, commits, final testing notes, next-step handoff after completed session
+  * active interview decisions should not live only in journals
+
+## Interview Note: Spec Update Trigger
+
+Question:
+
+* Should specs update only when contracts/boundaries change, after every feature, or only after bugs?
+
+Answer:
+
+* Update specs when contracts or boundaries change.
+
+Target docs:
+
+* `.trellis/spec/guides/trellis-doc-map-guide.md`
+* `.trellis/workflow.md`
+
+Change made:
+
+* Added spec-update triggers:
+  * tool schema / command / API shape
+  * runtime state fields or payload formats
+  * module ownership or boundary
+  * validation / error behavior
+  * test requirements or verification matrix
+  * cross-layer transformation
+  * repeated mistake that should become a rule
+* Clarified that ordinary implementation detail should not create spec noise.
+
+## Interview Note: CC Alignment Record Placement
+
+Question:
+
+* Should cc-haha alignment results first live in active PRDs and then be promoted, or should all alignment go directly into plans or specs?
+
+Answer:
+
+* First write to active PRD, then promote stable roadmap outcomes to plans and executable constraints to specs.
+
+Target docs:
+
+* `.trellis/spec/guides/cc-alignment-guide.md`
+* `.trellis/spec/guides/trellis-doc-map-guide.md`
+
+Change made:
+
+* Clarified cc alignment record placement:
+  * active task PRD owns expected effect, source evidence, matrix, exploratory decisions
+  * `plans/` owns stable roadmap/product-direction outcomes
+  * `spec/` owns executable implementation constraints
+  * exploratory source notes should not become canonical specs by default
+
+## Interview Note: Validation Scope Policy
+
+Question:
+
+* Should validation default to focused first with broader escalation, full validation every time, or minimum checks only?
+
+Answer:
+
+* Focused first; broader validation only when risk triggers it.
+
+Target docs:
+
+* `.trellis/spec/backend/quality-guidelines.md`
+* `.trellis/spec/guides/staged-execution-guide.md`
+
+Change made:
+
+* Added validation scope policy:
+  * focused tests and touched-file lint/typecheck by default
+  * broader validation for cross-layer contracts, runtime/session/compact/task changes, middleware ordering changes, ambiguous focused failures, or explicit user request
+  * no full-suite default for every small change
+
+## Interview Note: Delegated Recommended Defaults
+
+Question:
+
+* Should future low-risk process choices continue to require explicit user selection?
+
+Answer:
+
+* No. User delegated future low-risk process choices to the recommended option.
+
+Target docs:
+
+* `.trellis/workflow.md`
+
+Change made:
+
+* Added workflow rule:
+  * proceed with recommended/default option for low-risk process choices
+  * still stop for irreversible deletion, major product direction changes, or unclear ownership
+
+## Interview Note: Task Archive Policy
+
+Question:
+
+* Should completed Trellis tasks be archived after commit/acceptance, after PR merge, or manually without default?
+
+Answer:
+
+* Use recommended default: archive after the work is actually complete and committed, or docs/planning-only complete.
+
+Target docs:
+
+* `.trellis/workflow.md`
+* `.trellis/spec/guides/trellis-doc-map-guide.md`
+
+Change made:
+
+* Added task archive policy:
+  * archive when acceptance criteria are met and appropriate verification is complete
+  * archive after human commit, or when docs/planning-only work is explicitly complete
+  * do not keep tasks open only because stale task metadata says `planning` or `in_progress`
+
+## Checkpoint: Trellis Docs Synthesis And Interview Expansion
+
+State:
+
+* terminal
+
+Verdict:
+
+* APPROVE
+
+Implemented:
+
+* Added Trellis doc map guide.
+* Added interview-driven spec expansion guide.
+* Filled backend persistence, error handling, and logging guidance.
+* Marked frontend specs as deferred but future-activatable.
+* Added handoff update policy.
+* Added plans-vs-specs boundary.
+* Added task PRD vs workspace journal boundary.
+* Added spec update trigger rule.
+* Added cc alignment record placement rule.
+* Added validation scope policy.
+* Added delegated recommended-default behavior for low-risk process choices.
+* Added task archive policy.
+
+Verification:
+
+* Lightweight file/link checks were run for the two new guides.
+* Subsequent edits are documentation-only and follow the established Trellis doc-map routing.
+
+Decision:
+
+* terminal for this Trellis docs synthesis/interview foundation pass.
+
+## Checkpoint: Trellis Optimization Batch
+
+State:
+
+* terminal
+
+Verdict:
+
+* APPROVE
+
+Implemented:
+
+* Updated `.trellis/spec/backend/index.md` statuses for database, error handling, and logging from placeholder to active.
+* Split the oversized runtime context/compaction contract into:
+  * `.trellis/spec/backend/tool-result-storage-contracts.md`
+  * `.trellis/spec/backend/session-compact-contracts.md`
+  * `.trellis/spec/backend/runtime-pressure-contracts.md`
+  * kept `.trellis/spec/backend/runtime-context-compaction-contracts.md` as an overview index.
+* Normalized current backend spec paths to `coding-deepgent/tests/...` and `coding-deepgent/src/...`.
+* Replaced migrated `.omx/...` current references with `.trellis/...` paths in Trellis planning docs where appropriate.
+* Expanded `.trellis/plans/index.md` with plan roles, read timing, and maintenance rules.
+* Updated `.trellis/spec/guides/trellis-doc-map-guide.md` to mark frontend specs as deferred/future-activatable.
+* Added review output format requirements to `.trellis/spec/backend/quality-guidelines.md`.
+* Added `.trellis/scripts/check_trellis_links.py` for lightweight local Markdown link checks.
+
+Verification:
+
+* `python3 ./.trellis/scripts/check_trellis_links.py` -> passed.
+* Scanned current Trellis specs/plans/workflow/handoff for stale `tests/test_*`, `src/coding_deepgent`, `.omx/`, deleted `coding-deepgent/docs`, and removed skill references.
+* Confirmed backend specs no longer contain old relative `tests/test_*` or `src/coding_deepgent` paths.
+
+Residual notes:
+
+* `.trellis/plans/index.md` intentionally mentions the removed `.omx` tree as migration context.
+* `.trellis/spec/backend/index.md` intentionally mentions `coding-deepgent/docs/` only to say not to revive parallel docs there.
+
+Decision:
+
+* terminal for the requested 8-item Trellis optimization batch.
diff --git a/.trellis/tasks/archive/2026-04/04-15-trellis-docs-synthesis-interview/task.json b/.trellis/tasks/archive/2026-04/04-15-trellis-docs-synthesis-interview/task.json
new file mode 100644
index 000000000..64694138d
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-trellis-docs-synthesis-interview/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "trellis-docs-synthesis-interview",
+  "name": "trellis-docs-synthesis-interview",
+  "title": "brainstorm: trellis docs synthesis and interview expansion",
+  "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-15-trellis-spec-consolidation",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-15-trellis-spec-consolidation/check.jsonl b/.trellis/tasks/archive/2026-04/04-15-trellis-spec-consolidation/check.jsonl
new file mode 100644
index 000000000..6b92c32c2
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-trellis-spec-consolidation/check.jsonl
@@ -0,0 +1,5 @@
+{"file": ".cursor/commands/trellis-finish-work.md", "reason": "Finish work checklist"}
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
+{"file": ".trellis/spec/backend/directory-structure.md", "reason": "verify migrated structure guidance matches current coding-deepgent layout"}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "verify review checklist and quality rules are canonical after cleanup"}
+{"file": ".trellis/spec/guides/mainline-scope-guide.md", "reason": "verify deleted tutorial assets are outside mainline contract"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-trellis-spec-consolidation/debug.jsonl b/.trellis/tasks/archive/2026-04/04-15-trellis-spec-consolidation/debug.jsonl
new file mode 100644
index 000000000..e30f96d49
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-trellis-spec-consolidation/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-trellis-spec-consolidation/implement.jsonl b/.trellis/tasks/archive/2026-04/04-15-trellis-spec-consolidation/implement.jsonl
new file mode 100644
index 000000000..c25cf26cd
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-trellis-spec-consolidation/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": ".trellis/spec/backend/directory-structure.md", "reason": "target backend structure doc to replace coding-deepgent doc duplication"}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "target review and quality norms to replace coding-deepgent review checklist"}
+{"file": ".trellis/spec/guides/mainline-scope-guide.md", "reason": "mainline-vs-reference scope boundary for cleanup decisions"}
diff --git a/.trellis/tasks/archive/2026-04/04-15-trellis-spec-consolidation/prd.md b/.trellis/tasks/archive/2026-04/04-15-trellis-spec-consolidation/prd.md
new file mode 100644
index 000000000..d5e46db82
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-trellis-spec-consolidation/prd.md
@@ -0,0 +1,242 @@
+# brainstorm: consolidate project docs into trellis
+
+## Goal
+
+将项目内分散的规范文件、代码结构说明、项目要求与相关入口统一整理到 `.trellis/` 体系中，使 Trellis 成为后续协作的唯一主入口；同时删除被收编后的重复文档，以及不再需要的相关 skill 或 skill 引用。
+
+## What I already know
+
+* 用户希望以后“都以 trellis 为主”。
+* 用户明确澄清：当前工作的主线项目是 `coding-deepgent/`。
+* 仓库外层“教程层”包括 `web/`、`skills/`、`docs/`、教学/参考测试、`agents/`、`agents_deepagents/` 等，当前都不是工作主线，默认按参考内容处理。
+* 用户已明确要求：首批清理范围包含根 `skills/` 与根目录教程测试。
+* 当前 `.trellis/spec/` 中只有少量后端契约文档处于 `Active`，大量 frontend/backend index 仍是占位内容。
+* 仓库中还存在大量非 `.trellis/` 文档来源：
+  * 根目录 `README*.md`
+  * `docs/{en,ja,zh}/`
+  * `coding-deepgent/docs/`
+  * `agents_deepagents/cc_alignment/`
+* 仓库中还存在项目级技能目录 `skills/`，包含至少：
+  * `skills/code-review/SKILL.md`
+  * `skills/agent-builder/SKILL.md`
+  * `skills/mcp-builder/SKILL.md`
+  * `skills/pdf/SKILL.md`
+* 代码与文档中已有多处对 `skills/`、`docs/`、`AGENTS.md`、workflow/spec/guideline 的引用，删除前需要先处理引用和入口。
+* `AGENTS.md` 已经把 Trellis 设为会话起点，但 `.trellis/spec/` 里的多数规范仍未承接仓库现有知识。
+* `coding-deepgent/docs/` 中包含大量真正影响当前产品开发的阶段说明、评审清单、cc 对齐路线图，当前不在 `.trellis/spec/` 主入口内。
+* `.trellis/spec/backend/runtime-context-compaction-contracts.md` 与 `task-workflow-contracts.md` 已经证明：Trellis 适合承接“可执行契约 / 项目规范”。
+* `.trellis/spec/backend/*`、`.trellis/spec/frontend/*` 的很多文件仍是模板或占位文案。
+* `docs/{en,ja,zh}/` 与根 `README*.md` 更像教学主线与阅读入口，而不是单纯的项目协作规范。
+* `skills/` 不只是历史遗留目录；它们仍被以下区域引用：
+  * `agents/s05_skill_loading.py`
+  * `agents_deepagents/s05_skill_loading.py`
+  * `docs/*/s05-skill-loading.md`
+  * `coding-deepgent` 的 skills/plugin 测试与说明
+  * `web/src/data/*` 的教学可视化数据
+
+## Assumptions (temporary)
+
+* 这次工作应先完成“规范迁移与入口收敛”的设计和落盘，再做受控删除，避免先删后断链。
+* `docs/` 下的教程型内容不应默认搬入 `.trellis/spec/`；需要明确区分“`coding-deepgent` 产品协作规范”与“仓库教程/参考文档”。
+* 需要删除的 “相关 skill” 指的是那些原本承担项目规范入口职责、但在 Trellis 主导后会重复或过时的 skill，而不是所有技能都要移除。
+
+## Open Questions
+
+* None after scope confirmation.
+
+## Requirements (evolving)
+
+* Trellis 规范必须明确写出：当前工作主线是 `coding-deepgent/`，教程层默认不是实现目标。
+* 盘点当前项目中所有实际承担“规范 / 结构 / 要求 / 协作入口”职责的文档。
+* 区分 `coding-deepgent` 主线规范与教程/参考资产，不再把两者混成一个开发目标。
+* 明确哪些内容应迁移到 `.trellis/spec/`、`.trellis/workflow.md`、`.trellis/workspace/` 或其他 Trellis 位置。
+* 明确哪些现有文件在迁移后应删除，哪些应保留为产品文档。
+* 清理多余入口，避免未来同时维护 Trellis 与非 Trellis 版本。
+* 清理或改造与旧入口耦合的 skill / skill 引用。
+* 首批清理范围包含：
+  * `coding-deepgent/docs/` 下与 Trellis 重复的主线规范文件
+  * 根 `skills/`
+  * 根目录教程测试
+
+## Acceptance Criteria (evolving)
+
+* [x] 有一份 source-backed 清单，列出当前所有规范类文档、其用途、保留/迁移/删除决策。
+* [x] Trellis 明确记录 `coding-deepgent` 是当前主线，教程层默认 reference-only。
+* [x] `.trellis/` 内形成项目规范的主入口与清晰索引。
+* [x] 迁移后的 Trellis 内容能覆盖当前实际开发所需的项目要求与代码结构说明。
+* [x] 被判定为重复或废弃的文档已删除，且相关引用已更新。
+* [x] 被判定为重复或废弃的相关 skill 已删除或改造，且不再误导后续协作。
+* [x] 根目录教程测试已按首批清理范围删除。
+
+## 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)
+
+* 直接重写产品功能代码，除非为修复文档/skill 引用断链所必需
+* 把教程层默认当作当前实现目标
+* 无差别删除所有 `docs/`、`skills/`、`README` 内容
+* 在没有完成映射清单前直接进行大规模删除
+
+## Technical Notes
+
+* New task: `.trellis/tasks/04-15-trellis-spec-consolidation`
+* 初步发现的文档承载区：
+  * `AGENTS.md`
+  * `README.md`, `README-zh.md`, `README-ja.md`
+  * `docs/`
+  * `coding-deepgent/docs/`
+  * `agents_deepagents/cc_alignment/`
+  * `.trellis/spec/`
+* 初步发现的 skill 承载区：
+  * `skills/`
+  * `.agents/skills/`
+
+## Research Notes
+
+### What different document areas are doing now
+
+* `AGENTS.md`
+  * 已经是“如何进入 Trellis 工作流”的顶层入口。
+* `.trellis/workflow.md`
+  * 已经定义开发工作流、任务机制、workspace/journal 约束。
+* `.trellis/spec/`
+  * 已有少量高价值可执行规范，但大部分结构/质量/前端规范仍为空模板。
+* `coding-deepgent/docs/`
+  * 承载当前产品开发的真实阶段语义、cc 对齐决策、review checklist。
+* `docs/` + `README*.md`
+  * 承载教学主线、章节阅读顺序、多语言教材内容。
+* `skills/`
+  * 承载教程和示例 agent 的按需知识加载样本，不只是“团队规范”。
+* `.trellis/project-handoff.md`
+  * 已经明确 `coding-deepgent` 是 product track / current mainline。
+
+### Constraints from our repo/project
+
+* 如果删除 `docs/`，将破坏教学仓库主入口和 web 生成内容，不是单纯的“规范整理”。
+* 如果删除 `skills/`，将影响 `s05` 教学、相关测试、Deep Agents 轨道、以及部分产品说明。
+* 如果不把 `coding-deepgent/docs/` 中的产品级开发要求迁入 Trellis，未来仍会出现“双入口”。
+* 当前 `.trellis/spec/` 需要从“模板集合”升级为“真实规范入口”，否则 Trellis 无法成为主入口。
+* 未来规范首先要服务 `coding-deepgent`，而不是继续为整个教学外壳提供等权主入口。
+
+### Current classification draft
+
+**Mainline / should stay first-class**
+
+* `.trellis/`
+* `coding-deepgent/`
+* `coding-deepgent/tests/`
+
+**Reference-only by default**
+
+* `agents/`
+* `agents_deepagents/`
+* `docs/`
+* `web/`
+* root tutorial/reference tests under `tests/`, especially:
+  * `test_agents_*`
+  * `test_deepagents_*`
+  * `test_s02_*`
+  * `test_s03_*`
+  * `test_s04_*`
+  * `test_s06_*`
+  * `test_stage_track_*`
+  * `test_s_full_background.py`
+
+**High-priority duplicate / misleading candidates**
+
+* `coding-deepgent/docs/cc-alignment-roadmap.md`
+  * overlaps with canonical Trellis roadmap/dashboard
+* `coding-deepgent/docs/review-checklist.md`
+  * overlaps with Trellis quality/review norms
+* `coding-deepgent/docs/session-foundation-cc-alignment.md`
+  * overlaps with Trellis handoff / session contracts
+* root `README*.md`
+  * good as repo-level teaching entry, misleading as current product implementation entry
+* tutorial chapter docs in `docs/*` that cover current product concepts:
+  * `s05-skill-loading.md`
+  * `s06-context-compact.md`
+  * `s09-memory-system.md`
+  * `s10-system-prompt.md`
+  * `s12-task-system.md`
+  * `s13-background-tasks.md`
+  * `s19-mcp-plugin.md`
+* generic root skills:
+  * `skills/agent-builder/SKILL.md`
+  * `skills/code-review/SKILL.md`
+  * `skills/mcp-builder/SKILL.md`
+  * `skills/pdf/SKILL.md`
+  * user-selected for first-batch cleanup
+
+### Feasible approaches here
+
+**Approach A: Trellis-first for `coding-deepgent` governance/specs** (Chosen)
+
+* How it works:
+  * 只把 `coding-deepgent` 的“项目协作规范 / 开发要求 / 代码结构约定 / 产品开发契约”迁入 Trellis。
+  * 保留 `docs/`、`web/`、`agents*` 作为教程/参考文档，不再承担当前主线开发规范职责。
+  * 将 `coding-deepgent/docs/` 中真正属于开发规范的内容迁入 `.trellis/spec/` 或 `.trellis/plans/`。
+  * 删除根 `skills/` 与根目录教程测试，避免它们继续伪装成当前主线协作资产。
+* Pros:
+  * 最符合“以后以 Trellis 为主”的协作目标。
+  * 风险可控，不会误删教学主线。
+  * 可以真正清理双入口。
+* Cons:
+  * 仍会保留一部分非 Trellis 文档，用于教学或产品说明。
+
+**Approach B: Trellis as the only global doc center**
+
+* How it works:
+  * 将规范、产品说明、教学入口、阶段说明都尽量并入 `.trellis/`。
+  * 大幅删除 `docs/`、`coding-deepgent/docs/`、根 README 中的重复内容。
+  * 同步移除或重写依赖这些目录的 skill / 测试 / web 数据。
+* Pros:
+  * 单一入口最彻底。
+* Cons:
+  * 影响面极大，已经接近“重构整个仓库信息架构”。
+  * 会动到教学仓库产品定位，而不只是开发协作规范。
+
+**Approach C: Trellis as index only, old docs mostly retained**
+
+* How it works:
+  * 在 Trellis 中增加索引和映射，但不做大规模迁移。
+  * 老文档大部分保留，只加“canonical source 在 Trellis”或“see also”。
+* Pros:
+  * 成本最低，断链风险最低。
+* Cons:
+  * 不能真正消除双入口和重复维护。
+  * 不符合用户“以后都以 trellis 为主”的方向。
+
+## Checkpoint: Trellis Spec Consolidation
+
+State:
+
+* terminal
+
+Verdict:
+
+* APPROVE
+
+Implemented:
+
+* Established `coding-deepgent/` as current mainline and tutorial/reference layer as reference-only by default.
+* Migrated mainline governance into Trellis docs.
+* Removed duplicated `coding-deepgent/docs/*` governance docs.
+* Removed root tutorial `skills/`, root tutorial tests, and `live_tests/` as first-batch cleanup.
+* Added/updated Trellis guides and backend specs for mainline scope, doc map, interview expansion, cc alignment, staged execution, LangChain-native implementation, quality, persistence, error handling, and logging.
+* Added Trellis link checker.
+* Split oversized runtime/compact contract into focused backend contract files.
+
+Verification:
+
+* `python3 ./.trellis/scripts/check_trellis_links.py` passed.
+* Focused `coding-deepgent` skill/plugin tests passed earlier after root `skills/` removal.
+* Scanned current Trellis specs/plans for stale root tutorial paths and removed-skill references.
+
+Decision:
+
+* terminal for this consolidation task family. Archive after human review/commit according to Trellis workflow.
diff --git a/.trellis/tasks/archive/2026-04/04-15-trellis-spec-consolidation/task.json b/.trellis/tasks/archive/2026-04/04-15-trellis-spec-consolidation/task.json
new file mode 100644
index 000000000..adb9ac64c
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-15-trellis-spec-consolidation/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "trellis-spec-consolidation",
+  "name": "trellis-spec-consolidation",
+  "title": "brainstorm: consolidate project docs into trellis",
+  "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": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-16-autocompact-failure-circuit-breaker/check.jsonl b/.trellis/tasks/archive/2026-04/04-16-autocompact-failure-circuit-breaker/check.jsonl
new file mode 100644
index 000000000..f1f13b252
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-autocompact-failure-circuit-breaker/check.jsonl
@@ -0,0 +1,6 @@
+{"file": ".cursor/commands/trellis-finish-work.md", "reason": "Finish work checklist"}
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
+{"file": ".trellis/tasks/04-16-autocompact-failure-circuit-breaker/prd.md", "reason": "active acceptance criteria"}
+{"file": ".trellis/tasks/04-16-cc-style-autocompact-hardening/prd.md", "reason": "source hardening acceptance criteria"}
+{"file": ".trellis/spec/backend/runtime-pressure-contracts.md", "reason": "runtime pressure checks"}
+{"file": "coding-deepgent/tests/test_runtime_pressure.py", "reason": "focused tests"}
diff --git a/.trellis/tasks/archive/2026-04/04-16-autocompact-failure-circuit-breaker/debug.jsonl b/.trellis/tasks/archive/2026-04/04-16-autocompact-failure-circuit-breaker/debug.jsonl
new file mode 100644
index 000000000..e30f96d49
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-autocompact-failure-circuit-breaker/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-16-autocompact-failure-circuit-breaker/implement.jsonl b/.trellis/tasks/archive/2026-04/04-16-autocompact-failure-circuit-breaker/implement.jsonl
new file mode 100644
index 000000000..43aea64ff
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-autocompact-failure-circuit-breaker/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": ".trellis/tasks/04-16-autocompact-failure-circuit-breaker/prd.md", "reason": "active autocompact circuit breaker PRD"}
+{"file": ".trellis/tasks/04-16-cc-style-autocompact-hardening/prd.md", "reason": "source autocompact hardening PRD"}
+{"file": ".trellis/spec/backend/runtime-pressure-contracts.md", "reason": "runtime pressure contract"}
+{"file": "coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py", "reason": "autocompact implementation seam"}
diff --git a/.trellis/tasks/archive/2026-04/04-16-autocompact-failure-circuit-breaker/prd.md b/.trellis/tasks/archive/2026-04/04-16-autocompact-failure-circuit-breaker/prd.md
new file mode 100644
index 000000000..3e610b299
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-autocompact-failure-circuit-breaker/prd.md
@@ -0,0 +1,110 @@
+# autocompact failure circuit breaker
+
+## Goal
+
+给 proactive AutoCompact 增加连续失败 circuit breaker：当 summarizer 连续失败时，后续 model calls 不再反复尝试 doomed auto-compact，避免持续浪费 API 时间和噪音事件，同时保持 reactive prompt-too-long fallback 的既有行为。
+
+## Expected Effect
+
+如果 live AutoCompact summarizer 连续失败，runtime pressure middleware 会记录 bounded skip event 并跳过后续 proactive AutoCompact，直到一次成功 compact 重置失败计数。失败时继续 fail-open，不能破坏当前模型调用。
+
+## Requirements
+
+- Add settings-backed `auto_compact_max_failures: int | None`.
+- Track consecutive proactive AutoCompact failures on the middleware instance.
+- Increment failure count only when threshold crossing attempted proactive AutoCompact and summarizer failed/returned invalid summary.
+- Reset failure count after successful proactive AutoCompact.
+- When failure count reaches max, skip proactive AutoCompact for later model calls.
+- Emit bounded runtime event/evidence metadata for skip:
+  - `event_kind == "auto_compact"`
+  - `strategy == "auto"`
+  - `trigger == "failure_circuit_breaker"`
+  - `failure_count`
+  - `max_failures`
+- Do not change reactive compact retry semantics.
+
+## Acceptance Criteria
+
+- [ ] Repeated proactive AutoCompact failures stop after configured max failures.
+- [ ] Successful proactive AutoCompact resets failure count.
+- [ ] Skip emits bounded runtime event/evidence metadata.
+- [ ] `auto_compact_max_failures is None` preserves current fail-open behavior.
+- [ ] Existing reactive compact tests remain valid.
+- [ ] Runtime pressure contract updated.
+- [ ] Focused tests, ruff, and targeted mypy pass.
+
+## Source Evidence
+
+- `/root/claude-code-haha/src/services/compact/autoCompact.ts`
+- `/root/claude-code-haha/src/services/compact/compact.ts`
+- Source PRD: `.trellis/tasks/04-16-cc-style-autocompact-hardening/prd.md`
+
+## Out of Scope
+
+- No compact request prompt-too-long retry in this sub-stage.
+- No structured compaction result yet.
+- No restoration contributions or hooks.
+- No provider-specific prompt-cache behavior.
+
+## Status
+
+Checkpoint complete.
+
+State: checkpoint
+
+Verdict: APPROVE
+
+Implemented:
+
+- Added settings-backed `auto_compact_max_failures`.
+- Added `AutoCompactResult` and `maybe_auto_compact_messages_with_status(...)`.
+- Preserved `maybe_auto_compact_messages(...)` as a compatibility wrapper.
+- Added middleware-owned consecutive proactive AutoCompact failure counter.
+- Incremented failure count only when proactive threshold was crossed and
+  summarization/compaction failed open.
+- Reset failure count after successful proactive AutoCompact.
+- Added bounded skip event/evidence metadata when circuit breaker trips.
+
+Verification:
+
+- `pytest -q tests/test_runtime_pressure.py` -> 32 passed.
+- `pytest -q tests/test_app.py` -> 9 passed.
+- `ruff check src/coding_deepgent/compact/runtime_pressure.py src/coding_deepgent/compact/__init__.py src/coding_deepgent/sessions/evidence_events.py src/coding_deepgent/settings.py src/coding_deepgent/containers/app.py tests/test_runtime_pressure.py tests/test_app.py` -> passed.
+- `mypy src/coding_deepgent/compact/runtime_pressure.py src/coding_deepgent/sessions/evidence_events.py src/coding_deepgent/settings.py src/coding_deepgent/containers/app.py` -> passed.
+
+Alignment:
+
+- source files inspected:
+  - `/root/claude-code-haha/src/services/compact/autoCompact.ts`
+  - `/root/claude-code-haha/src/services/compact/compact.ts`
+- aligned:
+  - consecutive failure count
+  - reset on successful compact
+  - skip future proactive attempts after max failures
+- deferred:
+  - compact request PTL retry
+  - structured compaction result
+  - post-compact restoration and hooks
+- do-not-copy:
+  - cc-specific analytics/logging implementation
+  - provider cache details
+
+Architecture:
+
+- primitive used: existing runtime pressure middleware state and runtime event seam.
+- why no heavier abstraction: the circuit breaker is local to proactive
+  AutoCompact attempts and does not need new persistence.
+
+Boundary findings:
+
+- Reactive compact retry remains unchanged.
+- Skip evidence is bounded metadata only.
+- Default `auto_compact_max_failures is None` preserves previous fail-open behavior.
+
+Decision: continue
+
+Reason:
+
+- The sub-stage is complete and verified.
+- Parent plan next stage remains valid: compact request prompt-too-long retry
+  is a separate summarizer-source preparation concern.
diff --git a/.trellis/tasks/archive/2026-04/04-16-autocompact-failure-circuit-breaker/task.json b/.trellis/tasks/archive/2026-04/04-16-autocompact-failure-circuit-breaker/task.json
new file mode 100644
index 000000000..605f1db3a
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-autocompact-failure-circuit-breaker/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "autocompact-failure-circuit-breaker",
+  "name": "autocompact-failure-circuit-breaker",
+  "title": "autocompact failure circuit breaker",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-16",
+  "completedAt": "2026-04-16",
+  "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-16-context-compression-staged-implementation-plan",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-16-cc-highlight-alignment-discussion/h11-h12-alignment-research.md b/.trellis/tasks/archive/2026-04/04-16-cc-highlight-alignment-discussion/h11-h12-alignment-research.md
new file mode 100644
index 000000000..e313b041e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-cc-highlight-alignment-discussion/h11-h12-alignment-research.md
@@ -0,0 +1,227 @@
+# H11/H12 Alignment Research (cc-haha vs coding-deepgent)
+
+> Source-backed inventory of cc-haha subagent highlights, local implementation state,
+> and gap matrix to drive the next brainstorm round.
+>
+> cc-haha root: `/root/claude-code-haha/`
+> local root: `coding-deepgent/src/coding_deepgent/`
+> Reading cutoff: 2026-04-17
+
+---
+
+## 1. cc-haha Highlight Inventory
+
+### A. Tool entry / agent schema
+
+| # | Highlight | Source | Function | Benefit |
+|---|---|---|---|---|
+| A1 | `Agent` tool with `subagent_type` param + per-type `whenToUse` catalog | `tools/AgentTool/AgentTool.tsx`, `builtInAgents.ts` | Model selects agent variant; per-agent system prompt, tool pool, model, permission mode | Model-visible agent discovery, prompt-cache partitioning per agent |
+| A2 | Per-agent `tools: []` or `['*']` with `disallowedTools` and `allowedAgentTypes` spec | `agentToolUtils.ts:122-225` (`resolveAgentTools`) | Wildcard expansion + deny-list + per-agent-type allowlist baked into Agent tool schema | Deterministic capability surface per agent |
+| A3 | Per-agent `permissionMode` override, gated by parent mode | `runAgent.ts:416-452` | Agent can declare `bubble`/`plan`/`acceptEdits`; not applied if parent is bypass/acceptEdits/auto | Read-only agents can't be hijacked into write mode |
+| A4 | Per-agent frontmatter `hooks` scoped to agent lifecycle | `runAgent.ts:564-575`, `utils/hooks/registerFrontmatterHooks.ts` | Register-on-spawn, clear-on-exit; Stop→SubagentStop auto-rewrite | Agents ship their own lifecycle side-effects without leaking to parent |
+| A5 | Per-agent `skills` preload | `runAgent.ts:578-646` | Skill names resolved via multiple strategies (exact/plugin-qualified/suffix); loaded content injected as initial user message with `isMeta` | Skills activate deterministically per agent |
+| A6 | Per-agent `mcpServers` additive to parent | `runAgent.ts:95-217` | Inline `{name: cfg}` or string reference; inline creates dedicated clients with cleanup, referenced shares parent's memoized client | Agent-specific MCP without leaking or duplicate-cleanup |
+| A7 | Per-agent `omitClaudeMd` / gitStatus strip for read-only agents | `runAgent.ts:386-410` | Explore/Plan drop CLAUDE.md (~5-15 Gtok/week) + stale gitStatus (~1-3 Gtok/week) | Context-budget optimization on high-volume agents |
+| A8 | Per-agent `effort`, `maxTurns`, `model` overrides | `runAgent.ts:340, 482-485, 756` | Applied via `getAgentModel`, `agentGetAppState`, `query({maxTurns})` | Cost/quality tuning per agent profile |
+| A9 | `criticalSystemReminder_EXPERIMENTAL` passthrough | `runAgent.ts:711-713` | Per-agent critical reminder threaded through subagent context | Targeted guardrail injection |
+
+### B. Runtime child-loop
+
+| # | Highlight | Source | Function | Benefit |
+|---|---|---|---|---|
+| B1 | `createSubagentContext` isolated child context | `runAgent.ts:700-714`, `utils/forkedAgent.ts` | New agentId, own messages/readFileState/abortController; sync shares setAppState+responseLength, async fully isolated | Clean parent/child runtime boundary without global state |
+| B2 | Async vs sync AbortController policy | `runAgent.ts:524-528` | Sync: shares parent's; Async: fresh unlinked controller (or explicit child-linked via `createChildAbortController` when parent aborts must cascade) | Correct cancellation semantics for foreground vs background |
+| B3 | `shouldAvoidPermissionPrompts` + `awaitAutomatedChecksBeforeDialog` flags | `runAgent.ts:436-463` | Async agents without UI auto-deny; async with UI waits for classifier/hook before dialog | Background agents never block on missing UI |
+| B4 | `allowedTools` replaces session rules, preserves SDK cliArg | `runAgent.ts:465-479` | Per-spawn tool permission scope without parent rule leakage | Correct least-privilege per spawn |
+| B5 | SubagentStart hooks with `additionalContexts` | `runAgent.ts:530-555` | Hook-returned text injected as `createAttachmentMessage({type: 'hook_additional_context'})` before query | Extension point for agent-specific prelude without prompt rewrites |
+| B6 | `filterIncompleteToolCalls` before spawn | `runAgent.ts:866-904` | Strips assistant messages whose tool_uses lack matching tool_results | API-error prevention on inherited context |
+| B7 | Side-chain transcript: O(1) per message with parent-chain UUID | `runAgent.ts:735-805`, `utils/sessionStorage.ts:recordSidechainTranscript` | Each message appended with `lastRecordedUuid` as parent link; initial batch fire-and-forget | Transcript is sufficient to reconstruct the tree |
+| B8 | Per-agent metadata persisted | `runAgent.ts:738-742` | `writeAgentMetadata(agentId, {agentType, worktreePath, description})` | Enables resume routing without replaying spawn args |
+| B9 | `transcriptSubdir` grouping | `runAgent.ts:351-353` | Optional `workflows/<runId>/` grouping for coordinated subagents | Multi-subagent run isolation on disk |
+| B10 | Perfetto hierarchy trace | `runAgent.ts:356-359, 832` | Register parent+child for agent-tree visualization | Observability of agent graph |
+| B11 | Per-agent API dump path | `runAgent.ts:362-366` | Dedicated `getDumpPromptsPath(agentId)` for API call replay | Debuggability per agent |
+| B12 | Finally-block cleanup inventory | `runAgent.ts:816-858` | MCP, session hooks, prompt cache tracking, file state cache, perfetto, todos entry, bash tasks, monitor-MCP tasks all cleaned in one place | No-leak lifecycle invariant |
+| B13 | `killShellTasksForAgent` on exit | `runAgent.ts:847`, `tasks/LocalShellTask/killShellTasks.ts` | Background bash tasks spawned by agent get killed when agent exits (prevents PPID=1 zombies) | Real cleanup of spawned processes |
+| B14 | Attachment / max_turns_reached passthrough | `runAgent.ts:771-790` | `structured_output` attachments yielded; `max_turns_reached` breaks loop cleanly | Structured-output and turn-limit semantics honored |
+| B15 | Stream event TTFT forwarding | `runAgent.ts:762-768` | Parent's API metrics display updates during subagent | UX metrics visibility during subagent |
+
+### C. Fork / cache
+
+| # | Highlight | Source | Function | Benefit |
+|---|---|---|---|---|
+| C1 | Implicit-fork mode (no `subagent_type`) | `forkSubagent.ts:32-71` | `FORK_AGENT` synthetic definition with `tools:['*']`, `model:'inherit'`, `permissionMode:'bubble'`, `maxTurns:200` | One-command "run same agent in background" |
+| C2 | Recursive-fork guard | `forkSubagent.ts:78-89` | Detect `<FORK_BOILERPLATE>` in history → reject new fork | Prevent runaway fork trees |
+| C3 | `buildForkedMessages` byte-identical prefix | `forkSubagent.ts:107-169` | Every child gets identical placeholder tool_results + per-child directive text block as final diff | Maximizes prompt-cache sharing across parallel forks |
+| C4 | `useExactTools` bypass of resolveAgentTools | `runAgent.ts:500-502, 682-684` | Fork inherits parent's thinking config + isNonInteractive for byte-exact API prefix | Cache-identical forks |
+| C5 | `override.systemPrompt` threads rendered bytes | `runAgent.ts:508-518`, `resumeAgent.ts:116-148` | Reconstructing via `getSystemPrompt` risks GrowthBook drift; threading rendered bytes is stable | Cache-stable system prompt across fork lineage |
+| C6 | Worktree notice injection for isolated fork children | `forkSubagent.ts:205-210` | Child gets explicit path-translation guidance when spawned in isolated worktree | Avoids silent path drift |
+| C7 | `onCacheSafeParams` exposes fork handle to background summarizer | `runAgent.ts:721-730`, `services/AgentSummary/agentSummary.ts` | Subagent emits its CacheSafeParams so another fork can share its cache for periodic summaries | Zero-additional-cache summaries |
+
+### D. Resume
+
+| # | Highlight | Source | Function | Benefit |
+|---|---|---|---|---|
+| D1 | Transcript-based resume with sanitization | `resumeAgent.ts:63-74` | Filter unresolvedToolUses + orphanedThinking + whitespaceOnlyAssistant; load metadata in parallel | Clean resume without API errors |
+| D2 | `reconstructForSubagentResume` content-replacement state | `resumeAgent.ts:75-79`, `utils/toolResultStorage.ts` | Rebuild replacement state so same tool results get replaced (prompt cache stable) | Cache stability across resume |
+| D3 | Worktree stat + utime bump | `resumeAgent.ts:82-97` | Verify worktree still exists; bump mtime so stale-cleanup doesn't delete it | Resume robustness with isolated worktrees |
+| D4 | Fork-resume system prompt reconstruction | `resumeAgent.ts:102-148` | Prefer `renderedSystemPrompt`; fallback reconstructs via `buildEffectiveSystemPrompt` | Preserve byte-exact prefix across resume |
+
+### E. Lifecycle / lineage / persistence
+
+| # | Highlight | Source | Function | Benefit |
+|---|---|---|---|---|
+| E1 | `LocalAgentTaskState` strict schema | `tasks/LocalAgentTask/LocalAgentTask.tsx:116-148` | agentId, agentType, status, prompt, selectedAgent, result, error, progress, messages, pendingMessages, retain, diskLoaded, evictAfter, isBackgrounded, notified | Rich task record drives UI, recovery, dedup |
+| E2 | Foreground/background split with signal | L280-L614 | `registerAgentForeground` returns promise that resolves on auto-background timeout or user trigger; `backgroundAgentTask` flips state mid-loop | User can hand off a running agent to background mid-run |
+| E3 | `pendingMessages` drained at tool-round boundaries | L162-L192 | SendMessage tool enqueues; agent loop drains at round start | Safe mid-run input injection (no race with active tool call) |
+| E4 | `appendMessageToLocalAgent` UI-transcript append | L175-L180 | Append to task.messages for UI without routing to API | Separates display-channel from agent-input-channel |
+| E5 | `isPanelAgentTask` single-source predicate | L159-L161 | One predicate all pill/panel filters must use | No UI drift between filters |
+| E6 | Parent-child abort cascade | L466-L490 (`registerAsyncAgent`) | Child AbortController linked to optional `parentAbortController` | In-process teammate aborts its subagents |
+| E7 | `enqueueAgentNotification` single-shot + XML payload | L197-L262 | `notified` flag atomic check-and-set; TASK_NOTIFICATION tag with outputFile/status/summary/result/usage/worktree | Dedup notifications; model-parseable |
+| E8 | `evictTaskOutput` + task-output symlink | `utils/task/diskOutput.ts` | Output file is a symlink to agent transcript path; eviction cleans symlink only | Disk recovery without duplicate writes |
+| E9 | Progress tracker with usage + recent activities | L41-L115 | input_tokens (cumulative→latest), output_tokens (summed); `recentActivities` with classification (isSearch/isRead) and activity description | Accurate token accounting + human-readable progress |
+| E10 | Cache eviction hint on subagent end | `agentToolUtils.ts:337-345` | Logs `tengu_cache_eviction_hint` with last_request_id | Inference layer can evict subagent's cache chain |
+| E11 | Partial-result on kill | `agentToolUtils.ts:488-500`, lifecycle:658-667 | Extract last assistant text from messages; include in killed notification | Kill still returns what was accomplished |
+| E12 | `retain` + `diskLoaded` cycle | L141-L148 | UI holding task blocks eviction, triggers disk bootstrap once, enables stream-append | UI can hold a background task open for viewing |
+
+### F. Summary / return-value
+
+| # | Highlight | Source | Function | Benefit |
+|---|---|---|---|---|
+| F1 | Background periodic summarization | `services/AgentSummary/agentSummary.ts:46-179` | 30s timer forks subagent conversation with `canUseTool=deny` + identical cache params → 3-5 word present-tense summary | Live "what is agent doing" without extra cache burn |
+| F2 | Cache-preserving summarization (no maxOutputTokens, tools kept but denied) | L94-L119 | Don't clamp budget_tokens (thinking config drift busts cache); keep tools in request, deny via callback | Prompt-cache sharing invariant |
+| F3 | Summary gating: coordinator/fork/SDK-opt-in | `agentToolUtils.ts:517-553` | Only enabled when coordinator mode, fork enabled, or SDK summaries opt-in | Cost control |
+| F4 | `finalizeAgentTool` strict result schema | `agentToolUtils.ts:227-357` | `{agentId, agentType, content, totalDurationMs, totalTokens, totalToolUseCount, usage}` with full cache creation/read breakdown | Machine-readable subagent result envelope |
+| F5 | Fallback last-text scan when final message is pure tool_use | L303-L317 | Walk backward if final assistant has no text block | Robust result extraction |
+
+### G. Built-in catalog
+
+| # | Highlight | Source | Function | Benefit |
+|---|---|---|---|---|
+| G1 | Tiered catalog with feature flags | `builtInAgents.ts:13-72` | general-purpose + statusline-setup (always), explore+plan (A/B), claude-code-guide (non-SDK), verification (flagged) | Staged rollout + entrypoint-aware surface |
+| G2 | Coordinator mode swap | L35-L43 | Replaces entire catalog with `getCoordinatorAgents()` when in coordinator mode | Alternate agent-team topology |
+| G3 | SDK kill-switch env | L25-L30 | `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` for blank-slate SDK users | Embedder flexibility |
+| G4 | Source tier trust: built-in / plugin / policySettings / user | `utils/settings/pluginOnlyPolicy.ts:isSourceAdminTrusted`, runAgent:117, 564 | Admin-trusted sources keep full frontmatter (hooks/MCP); user sources gated | Supply-chain boundary |
+
+### H. Handoff safety
+
+| # | Highlight | Source | Function | Benefit |
+|---|---|---|---|---|
+| H1 | `classifyHandoffIfNeeded` transcript classifier on handoff | `agentToolUtils.ts:389-481` | In `auto` mode, LLM classifier reviews subagent output for policy violation → prepends SECURITY WARNING or blocks | Defense-in-depth against prompt-inject-exfil on subagent boundary |
+
+---
+
+## 2. Local coding-deepgent Current State
+
+Sources inspected: `subagents/schemas.py`, `subagents/tools.py`, `subagents/__init__.py`,
+`tasks/schemas.py`, `tasks/store.py`, `tasks/tools.py`; grep for `subagent|fork|AgentTool|child_runtime`
+turned up only `runtime/context.py`, `runtime/invocation.py`, `sessions/evidence_events.py`,
+`settings.py`, `tool_system/capabilities.py`, `containers/tool_system.py` — no additional
+subagent-runtime surface.
+
+Local surface:
+
+- One tool `run_subagent` (`subagents/tools.py:425-455`) with `RunSubagentInput` schema: `task`, `agent_type ∈ {general, verifier}`, `plan_id?`, `max_turns` (pinned to 1).
+- Two agent types:
+  - `general`: returns stub string `"Subagent {agent_type} accepted task synchronously: {task}"` when no factory injected (`tools.py:369-375`). **No actual LLM child agent is invoked** in the shipped path.
+  - `verifier`: real `create_agent` child via `_execute_verifier_subagent` (`tools.py:205-238`), read-only allowlist (`read_file`, `glob`, `grep`, `task_get`, `task_list`, `plan_get`), `ToolGuardMiddleware` with `build_capability_registry`, strict system prompt, final line must match `VERDICT: PASS|FAIL|PARTIAL`.
+- `RuntimeInvocation` clone: `thread_id = <parent>:verifier:<plan_id>`, agent name suffix `-verifier` (`tools.py:167-188`).
+- `append_evidence` on verdict parse (`tools.py:260-300`).
+- `_subagent_spawn_pressure_guard` rejects spawn above `subagent_spawn_guard_ratio` of context window (`tools.py:378-422`).
+- `SubagentResult` / `VerifierSubagentResult` dataclass/BaseModel; verifier returns JSON, general returns plain content.
+
+---
+
+## 3. Gap Matrix
+
+Legend: Local = aligned / partial / missing / do-not-copy (UI-only or product-disaligned).
+MVP-critical? reflects the roadmap's "H11 full agent-team lifecycle deferred, H12 minimal-only" boundary —
+items only matter for MVP if they block a concrete H01-H11 behavior.
+
+| # | Highlight | Local | MVP-critical? | Suggested action |
+|---|---|---|---|---|
+| A1 | Agent tool + `subagent_type` catalog with `whenToUse` | partial (2 hard-coded types, no whenToUse surfaced to model) | **Y** — model cannot meaningfully pick between general and future agents without descriptions | **close in MVP**: add `whenToUse`/description to local agent catalog; separate "general" placeholder from real implementation |
+| A2 | Per-agent tool pool resolution + disallow list | partial (hard-coded `CHILD_TOOL_OBJECTS` / `FORBIDDEN_CHILD_TOOLS`) | **Y** — future built-ins (plan, explore) will need different pools without refactor | **close in MVP**: introduce `AgentDefinition` schema with `tools`, `disallowed_tools`; derive allowlist from it |
+| A3 | Per-agent permission mode override | missing | N — permission runtime H02 treats parent mode as authoritative; agent-level override is nice-to-have | defer with ADR — note when H17 plugin/H18 hooks may require |
+| A4 | Frontmatter hooks scoped to agent lifecycle | missing | N for MVP — frontmatter loader not in MVP | defer |
+| A5 | Skills preload per agent | missing | N — H15 baseline only | defer |
+| A6 | Per-agent MCP additive | missing | N — H16 baseline only | defer |
+| A7 | ClaudeMd/gitStatus strip for read-only agents | missing | N — optimization, not correctness | defer |
+| A8 | model/effort/maxTurns per-agent | partial (maxTurns pinned to 1; no model override) | **Y** — verifier already needs its own model profile separate from parent; `max_turns=1` forbids multi-step verification | **close in MVP**: unpin max_turns; allow per-agent model override via AgentDefinition |
+| A9 | Critical system reminder experimental | missing | N | do-not-copy for MVP |
+| B1 | `createSubagentContext` isolated child | partial (verifier clones `RuntimeContext`, general path doesn't run a child at all) | **Y** — general subagent has no real runtime; this is the biggest correctness gap | **close in MVP**: land a real general-purpose child runtime via `create_agent`, mirroring verifier's invocation pattern |
+| B2 | Async vs sync abort policy | missing (only sync, no AbortController analogue) | N for MVP — async/background deferred under H11 "full lifecycle deferred" | defer with ADR |
+| B3 | Auto-deny permission prompts for async | n/a (no async) | N | defer (bundle with B2) |
+| B4 | Per-spawn `allowedTools` replaces session rules | partial (hard-coded allowlist per agent_type) | **Y** — once A1/A2 land, we need the runtime path to honor declared allowlist at spawn | **close in MVP** alongside A2 |
+| B5 | SubagentStart hooks additional context | missing | N for MVP — H18 baseline only | defer |
+| B6 | `filterIncompleteToolCalls` on forked history | n/a (no context fork) | N | defer (with C1) |
+| B7 | Side-chain transcript with parent-chain UUID | **missing** | **Y** — verifier evidence only records verdict, not the full child transcript; no way to audit what the subagent saw or did | **close in MVP**: persist subagent JSONL transcript with `parent_thread_id` / `parent_message_id` linkage (mirror `recordSidechainTranscript`) |
+| B8 | Per-agent metadata on disk | missing | **Y** — prerequisite for B7 / any future resume | **close in MVP** with B7 |
+| B9 | `transcriptSubdir` grouping | missing | N | defer |
+| B10 | Perfetto trace | missing | N — observability polish | defer |
+| B11 | Per-agent API dump | missing | N — debugging | defer |
+| B12 | Finally-block cleanup inventory | partial (no cleanup hooks; verifier child is short-lived) | N for MVP — no leaking resources yet (no MCP, no hooks, no shell tasks) | defer; revisit when B2 lands |
+| B13 | Kill shell tasks for agent | missing | N — no bash task integration in subagent path | defer |
+| B14 | max_turns_reached clean break | missing (`max_turns=1` hard-pinned, no break semantics) | **Y** — bundled with A8 unpin | **close in MVP** with A8 |
+| B15 | TTFT forwarding | missing | N — UX metric | defer |
+| C1 | Implicit fork (no subagent_type, inherit parent context) | missing | N — fork is explicit H12 extension; roadmap says minimal only | defer with ADR (explicit cc highlight to not copy yet) |
+| C2-C7 | All fork/cache machinery | missing | N — H12 minimal-only | defer |
+| D1-D4 | Resume | missing | N for MVP — resume belongs to H06 surface and is closed for main session; subagent resume is extension | defer with ADR |
+| E1 | Task state schema | partial (`SubagentResult` dataclass, no durable task record for subagent execution) | **Y (small)** — we already have a Task store (H09); subagent execution should produce a task-graph-backed record, not a bare dataclass | **close in MVP**: persist subagent invocation as a task record or durable `SubagentRun` for audit; link to verifier evidence |
+| E2 | Foreground/background + signal | missing | N — async deferred | defer |
+| E3 | `pendingMessages` drain | missing | N — SendMessage is H13 deferred | defer |
+| E4 | UI-transcript append | do-not-copy (UI-only) | N | do-not-copy |
+| E5 | `isPanelAgentTask` predicate | do-not-copy (UI-only) | N | do-not-copy |
+| E6 | Parent-child abort cascade | missing | N — requires B2 | defer |
+| E7 | Agent notification with XML payload + `notified` single-shot | partial (only evidence record, no task-notification envelope) | **Y (small)** — once A1/B7 land, a minimal completion envelope with token/tool-use/duration is cheap and gives model/hooks a canonical handoff structure | **close in MVP**: emit a structured `subagent_result` runtime event with token/toolUse/duration/plan_id even for general |
+| E8 | Output symlink + eviction | missing | N — depends on async | defer |
+| E9 | Progress tracker with usage + activities | missing | **Y (small)** — token count is a roadmap H20-minimal concern; at minimum record total_input/output tokens per subagent so compact/cost counters can see it | **close in MVP**: capture child usage in `SubagentResult` and propagate to evidence + runtime event |
+| E10 | Cache eviction hint | missing | N — provider-specific (H20 deferred) | defer |
+| E11 | Partial result on kill | missing | N — no kill path yet | defer |
+| E12 | Retain/diskLoaded | do-not-copy (UI-only) | N | do-not-copy |
+| F1-F3 | Background summarization | missing | N — requires async + coordinator; H14 deferred | defer |
+| F4 | Strict result schema | partial (`SubagentResult` dataclass, `VerifierSubagentResult` BaseModel) | **Y (small)** — needs usage fields + agent_type + content block parity | **close in MVP** with E7/E9 |
+| F5 | Fallback last-text scan | missing | **Y** — verifier current extraction requires non-empty assistant text; a final tool_use-only message would raise | **close in MVP**: mirror the fallback walk |
+| G1 | Tiered catalog | **missing** — only 2 types, no feature flags, no `whenToUse` | **Y** — roadmap explicitly wants built-in agents (H11 "all subagents enter as tools") | **close in MVP**: introduce `BUILT_IN_AGENTS` list with general, verifier (+ planned explore/plan placeholders behind flags) |
+| G2 | Coordinator swap | missing | N — H14 deferred | do-not-copy for MVP |
+| G3 | SDK kill-switch | missing | N | defer |
+| G4 | Source tier trust | missing | N — no plugin/policy settings yet | defer |
+| H1 | Handoff classifier | missing | N — H19 partial, classifier is advanced | defer with ADR |
+
+---
+
+## 4. Candidate Discussion Order
+
+Shortest dependency chain first. Each item builds on the previous.
+
+1. **Real general-purpose child runtime (B1 + A1 surface)**
+   Today `general` is a stub. Closing this replaces the largest correctness gap and makes H11 "all subagents enter as tools" true for the non-verifier case. Depends on nothing.
+2. **Agent catalog + AgentDefinition schema (A1 + A2 + A8)**
+   Introduce `AgentDefinition` (agent_type, description/whenToUse, tools allowlist, disallowed_tools, model?, max_turns?) and refactor the hard-coded verifier/general into registered definitions. Depends on (1). Blocks (3) and (4).
+3. **Subagent transcript + metadata persistence (B7 + B8 + E1)**
+   Persist child JSONL transcript and per-agent metadata record, linked to parent thread + parent message UUID. Closes the "no audit of what subagent saw/did" gap. Depends on (2).
+4. **Structured subagent result envelope (F4 + E7 + E9 + F5)**
+   Expand `SubagentResult` to carry `agent_type`, usage (input/output tokens, total duration), tool-use count; emit a canonical runtime event; add fallback last-text scan. Depends on (2), pairs with (3).
+5. **Explicit ADR for deferred items (B2/B13, C1-C7, D1-D4, F1-F3, H1)**
+   One document capturing what is intentionally not copied in MVP and why, with pointers back to cc source. Depends on (1)-(4) for context. Matches Stage 29 deferred-boundary ADR already on the roadmap.
+
+---
+
+## 5. Open Questions for Maintainer
+
+Only blocking/preference items.
+
+1. **Q — Scope of "real general-purpose child runtime"**: do we keep MVP general as a single read-only-tools agent (mirror verifier's allowlist minus plan/task reads) or extend it to include write tools (`write_file`, `edit_file`, `bash`) so it can execute, not only research? Roadmap text says "agent-as-tool" but doesn't pin the capability class.
+2. **Q — Agent catalog minimum set**: for MVP, is `general + verifier` sufficient, or must we land `explore` and `plan` built-ins (cc-haha's `EXPLORE_AGENT`, `PLAN_AGENT`) before H11 can be called closed? Roadmap treats them as future; `generalPurposeAgent` is the only must-have in cc.
+3. **Q — Transcript persistence boundary**: should subagent transcripts live in the same JSONL store as the parent session (sidechain with `parent_id` field), or in a separate per-agent directory keyed by agent_id? cc uses per-agent paths with metadata; our session store is already thread-keyed.
+4. **Q — Result envelope model**: do we surface the full token/usage breakdown (cache creation/read separately) at this stage, or only total tokens? H20 is `implemented-minimal` — decoupling subagent usage from full cost instrumentation is possible but divergent from cc.
+5. **Q — `max_turns` unpinning**: what is the MVP ceiling for general-purpose subagent turns? cc's general default is configurable per agent; our current pin of 1 blocks iterative subagent work entirely.
+
+---
+
+## Appendix: Items deliberately excluded from this research
+
+- UI-only / React concerns (panel, pill, tooltip, color manager) → do-not-copy for Python mainline
+- Analytics event names (`tengu_*`) → observability layer, H19 partial
+- Perfetto and dump-prompts paths → debug polish, not MVP
+- InProcessTeammateTask / RemoteAgentTask / DreamTask → H13/H21 deferred
+- Coordinator mode full architecture → H14 deferred
diff --git a/.trellis/tasks/archive/2026-04/04-16-cc-highlight-alignment-discussion/h19-observability-alignment-research.md b/.trellis/tasks/archive/2026-04/04-16-cc-highlight-alignment-discussion/h19-observability-alignment-research.md
new file mode 100644
index 000000000..45c7279fe
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-cc-highlight-alignment-discussion/h19-observability-alignment-research.md
@@ -0,0 +1,275 @@
+# H19 Alignment Research (cc-haha vs coding-deepgent)
+
+> Source-backed inventory of cc-haha observability surface, local implementation state,
+> and gap matrix for the H19 "Observability and evidence ledger" row currently marked
+> `implemented` on the MVP dashboard.
+>
+> cc-haha root: `/root/claude-code-haha/`
+> local root: `coding-deepgent/src/coding_deepgent/`
+> Reading cutoff: 2026-04-17
+
+---
+
+## 1. cc-haha Observability Highlight Inventory
+
+### A. Structured analytics pipeline
+
+| # | Highlight | Source | Function | Benefit |
+|---|---|---|---|---|
+| A1 | `logEvent(name, metadata)` with queued-until-sink pattern | `services/analytics/index.ts:96-164` | Events buffered before `attachAnalyticsSink` drains asynchronously via microtask; idempotent attach | Analytics can't block startup; attach timing doesn't lose events |
+| A2 | Typed marker `AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS` | `services/analytics/index.ts:19` | Every string field logged must cast through this `never` type; compiler forces author to verify no code/paths leak | Compile-time PII discipline rather than runtime review |
+| A3 | `_PROTO_*` key scheme for PII-tagged fields | `services/analytics/index.ts:33-58` (`stripProtoFields`) | 1P exporter hoists `_PROTO_*` to proto columns with stricter ACL; Datadog fanout strips them first | Two-tier PII access without per-sink filter maintenance |
+| A4 | Event sampling via GrowthBook dynamic config | `services/analytics/index.ts:132-144`, `growthbook.ts` | `tengu_event_sampling_config` controls sample rate; rate injected into metadata | Cost/volume control without code changes |
+| A5 | Enriched environment metadata for ants | `services/internalLogging.ts:17-89` | Kubernetes namespace + OCI container ID auto-added for `USER_TYPE === 'ant'`; external users get no such enrichment | Internal deployment-aware analytics; no external fingerprinting |
+| A6 | Async + sync `logEvent` / `logEventAsync` | `index.ts:133-164` | Async variant for fire-and-forget events that must await sink; sync for hot path | Backpressure handling optional per callsite |
+
+### B. Query-loop event taxonomy
+
+| # | Event name | Source `query.ts` line | What it captures |
+|---|---|---|---|
+| B1 | `tengu_query_before_attachments` / `_after_attachments` | 1539, 1652 | Entry/exit of attachment assembly with count deltas |
+| B2 | `tengu_auto_compact_succeeded` | 478 | Auto-compact completion metrics |
+| B3 | `tengu_post_autocompact_turn` | 1525 | First turn after auto-compact (measures recovery quality) |
+| B4 | `tengu_orphaned_messages_tombstoned` | 719 | Count of orphan tool_use/tool_result pairs replaced with tombstones |
+| B5 | `tengu_model_fallback_triggered` | 932 | Model downgrade event (e.g., Opus → Sonnet) |
+| B6 | `tengu_query_error` | 959 | API/protocol errors from query loop |
+| B7 | `tengu_max_tokens_escalate` | 1204 | Output budget escalation decisions |
+| B8 | `tengu_token_budget_completed` | 1349 | Budget-complete breakdown per request |
+| B9 | `tengu_streaming_tool_execution_used` / `_not_used` | 1367, 1373 | Streaming path gating decisions |
+| B10 | `tengu_cache_eviction_hint` | `agentToolUtils.ts:337-345` (subagent end) | Tells inference when a subagent's cache chain can be evicted |
+
+### C. Per-agent / per-session persistent artifacts
+
+| # | Highlight | Source | Function | Benefit |
+|---|---|---|---|---|
+| C1 | `getDumpPromptsPath(agentIdOrSession)` JSONL per session/agent | `services/api/dumpPrompts.ts:59-65` | Each API request appended; init state + fingerprint-based dedup avoid duplicating identical init payloads | Replayable API log per-session/per-agent without bloat |
+| C2 | Cached last 5 API requests (ants only) | `dumpPrompts.ts:14-38` | In-memory circular buffer for `/issue` command | Ant support tools have recent context without session scan |
+| C3 | Init fingerprint dedup | `dumpPrompts.ts:74+` | Hash model/tools/system to skip duplicate init dumps | Dump cost stays O(unique-init-shapes), not O(requests) |
+| C4 | `recordSidechainTranscript(messages, agentId, parentUuid)` | `utils/sessionStorage.ts:1451` | Per-agent JSONL transcript with `lastRecordedUuid` parent chain; initial batch fire-and-forget | Full replayable agent transcript separate from analytics |
+| C5 | `writeAgentMetadata` / `readAgentMetadata` | `utils/sessionStorage.ts:283-295` | Sidecar JSON for agentType/worktreePath/description | Resume routing without replaying spawn args |
+| C6 | `getAgentTranscriptPath(agentId)` under session dir | `utils/sessionStorage.ts:247` | Subagent transcripts co-located with parent session on disk | Resume/recovery locality; one directory copy moves everything |
+
+### D. Perfetto hierarchical tracing
+
+| # | Highlight | Source `utils/telemetry/perfettoTracing.ts` | Function | Benefit |
+|---|---|---|---|---|
+| D1 | `registerAgent(agentId, agentType, parentId)` / `unregisterAgent` | L392, L416 | Agent tree registration with parent link | Visualize the subagent graph with parent chain |
+| D2 | LLM request spans | L425-L499 | `startLLMRequestPerfettoSpan` / `endLLMRequestPerfettoSpan`, separates TTFT / completion / token counters | Per-request latency attribution at request granularity |
+| D3 | Tool spans | L690-L727 | `startToolPerfettoSpan` / `endToolPerfettoSpan` around every tool call | Tool-level latency visibility |
+| D4 | User-input spans | L768-L838 | Wraps each prompt submission; interaction span encloses the full loop | User-perceived latency measurement |
+| D5 | Instants + counters | L840-L884 | `emitPerfettoInstant` / `emitPerfettoCounter` for token counters, snapshot points | Timeline annotations without span machinery |
+| D6 | Stale-span eviction + max-event cap | L1083, L1113 | Protects long-running sessions from unbounded trace memory | Observability without memory leak |
+
+### E. Debug logging and lifecycle reporting
+
+| # | Highlight | Source | Function | Benefit |
+|---|---|---|---|---|
+| E1 | `logForDebugging(msg, {level})` with structured levels | `utils/debug.ts` (used throughout) | Gated by dev/verbose flags; consistent `[Agent:…]` / `[AgentSummary]` prefixes | Uniform debug output without ad-hoc console.log |
+| E2 | `emitTaskProgress` for SDK consumers | `utils/task/sdkProgress.ts` | Progress event stream to SDK clients: taskId, tokens, tool uses, summary, lastToolName | External UI can follow subagent progress |
+| E3 | `pushApiMetricsEntry(ttftMs)` parent forwarding | `runAgent.ts:762-768` | Subagent's TTFT bubbles to parent's API metrics display | UX metrics unified across agent tree |
+| E4 | `tengu_cache_eviction_hint` on subagent end | `agentToolUtils.ts:337-345` | Inference layer gets signal to evict child's cache chain | Cache efficiency for long-running sessions |
+
+### F. Evidence / recovery surface (persistent ledger)
+
+| # | Highlight | Source | Function | Benefit |
+|---|---|---|---|---|
+| F1 | Session JSONL with per-event timestamps | `sessionStorage.ts` | Single ordered log of messages, state snapshots, tool results | Deterministic recovery / forensics |
+| F2 | `conversationRecovery.ts` | (file present) | Recovery brief assembly from JSONL | Resume UX |
+| F3 | `toolResultStorage.ts` content replacement records | (file present) | Stable replacement state for large outputs across resumes | Cache-stable resume |
+
+---
+
+## 2. Local coding-deepgent Current State
+
+### 2.1 Runtime event sink
+
+`runtime/events.py` — `RuntimeEvent(kind, message, session_id, metadata, created_at)`;
+protocols `RuntimeEventSink` + `NullEventSink` + `InMemoryEventSink`.
+
+Every emitter writes through `context.event_sink.emit(event)` from `RuntimeContext`.
+In-memory sink is the default wiring; CLI service can swap.
+
+### 2.2 Session JSONL store
+
+`sessions/store_jsonl.py:JsonlSessionStore` methods:
+
+- `append_message`, `append_state_snapshot`, `append_evidence`, `append_compact`, `append_collapse`
+
+`sessions/records.py` record types: `MESSAGE_RECORD_TYPE`, `TRANSCRIPT_EVENT_RECORD_TYPE`,
+`STATE_SNAPSHOT_RECORD_TYPE`, `EVIDENCE_RECORD_TYPE`, plus `COMPACT_EVENT_KIND` and
+`COLLAPSE_EVENT_KIND` for trigger labels.
+
+`SessionEvidence(kind, summary, status, created_at, subject?, metadata?)` — status vocab
+`recorded | completed | blocked | denied | passed | failed | partial`.
+
+### 2.3 Runtime → Evidence bridge
+
+`sessions/evidence_events.py:RUNTIME_EVIDENCE_KINDS` maps 8 runtime event kinds to
+persistent evidence:
+
+```
+hook_blocked | permission_denied | snip | microcompact | context_collapse
+| auto_compact | reactive_compact | subagent_spawn_guard
+```
+
+Plus `verification` evidence emitted from `subagents/tools.py:record_verifier_evidence`.
+
+Metadata is whitelisted to a fixed key set; unknown keys are dropped.
+
+### 2.4 Recovery brief
+
+`sessions/resume.py:build_recovery_brief` produces a `RecoveryBrief` with:
+- session_id, updated_at, message_count
+- active_todos (pending / in_progress) from state
+- contribution_sections (pluggable `RECOVERY_BRIEF_CONTRIBUTIONS`)
+- recent_evidence (last 5) + recent_compacts (last 3)
+
+`render_recovery_brief` formats to text; `build_resume_context_message` wraps it into
+a `role:system` message for resume injection with `RESUME_CONTEXT_MESSAGE_PREFIX`.
+
+### 2.5 Not present locally
+
+- No analytics backend (no Datadog / no first-party event logging / no GrowthBook sampling)
+- No typed-marker PII discipline on event metadata
+- No Perfetto tracing (no agent hierarchy spans, no LLM/tool spans, no TTFT counters)
+- No per-request API dump (`getDumpPromptsPath` equivalent)
+- No query-level events (B1-B9 taxonomy)
+- No per-agent transcript / metadata sidecar (subagent transcripts currently: only verifier verdict → evidence)
+- No cache eviction hint
+- No SDK progress stream
+- No debug-level structured logger beyond Python `logging` (grep shows no `logForDebugging` equivalent)
+
+---
+
+## 3. Gap Matrix
+
+Legend: **Local** = aligned / partial / missing / do-not-copy (internal-ant-only or
+provider-specific). **MVP-critical?** reflects whether the item blocks a concrete H01-H11
+behavior or safety gate. Roadmap says H19 is `implemented` — these gaps indicate whether
+that label is defensible or overstated.
+
+### 3.1 Analytics pipeline (A)
+
+| # | Highlight | Local | MVP-critical? | Suggested action |
+|---|---|---|---|---|
+| A1 | Queued-until-sink pattern | missing | **Y (architectural)** — `RuntimeEventSink` currently emits-immediately; no buffering. Means events emitted before CLI wires the sink are silently dropped. | **close in MVP**: add a `QueuedEventSink` default that replays on attach (mirror cc's microtask drain) |
+| A2 | Typed PII-safety marker | missing | N — no external analytics backend to leak to | defer |
+| A3 | `_PROTO_*` PII-tagged keys | missing | N | defer (follows A2) |
+| A4 | Event sampling | missing | N — provider-specific | defer |
+| A5 | Environment enrichment | missing | N — we're not an internal telemetry service | do-not-copy |
+| A6 | Sync vs async emit | partial (all emit is sync; no async variant) | N — in-process sink is already sync-fast | defer; revisit if an external sink is ever added |
+
+### 3.2 Query-loop taxonomy (B)
+
+| # | Event | Local | MVP-critical? | Suggested action |
+|---|---|---|---|---|
+| B1 | Attachment boundaries | missing | N — we don't have an attachments layer equivalent | defer with ADR |
+| B2 | auto_compact_succeeded | **partial** — `auto_compact` kind exists as RuntimeEvent → evidence (completed) | **Y (semantic)** — we record the attempt but not success/metrics separately | **close in MVP**: split "attempted" vs "succeeded" statuses; include hidden_message_count / token_savings metadata |
+| B3 | post_autocompact_turn | missing | **Y (correctness signal)** — this is the canary for "did auto-compact destroy context?"; without it we have no way to audit compact quality | **close in MVP**: emit a runtime event on the first turn after any compact/collapse with token-count before/after |
+| B4 | orphaned_messages_tombstoned | missing | **Y (invariant)** — projection pipeline already has this notion; need the event when it fires | **close in MVP**: emit `orphan_tombstoned` runtime event with count + reason |
+| B5 | model_fallback_triggered | missing | N for MVP — no model-fallback logic in mainline yet | defer |
+| B6 | query_error | **partial** — Python exceptions log through `logging` but there's no structured runtime event | **Y (ops)** — without a structured error event, post-mortem depends on stderr capture | **close in MVP**: emit `query_error` runtime event with error class + phase + retry count |
+| B7 | max_tokens_escalate | missing | N — no output budget escalation yet | defer |
+| B8 | token_budget_completed | missing | **Y (small)** — compact/pressure decisions already compute token counts; publishing them as a runtime event costs nothing | **close in MVP**: emit per-response `token_budget` event |
+| B9 | streaming_tool_execution | n/a | N — Streaming stage explicitly deferred by user | do-not-copy for MVP |
+| B10 | cache_eviction_hint | missing | N — provider-specific | defer |
+
+### 3.3 Persistent artifacts (C)
+
+| # | Highlight | Local | MVP-critical? | Suggested action |
+|---|---|---|---|---|
+| C1 | API request dump (`dumpPrompts`) | missing | **Y (debuggability)** — without API dump, debugging "what did we send the model" depends on provider logs which are often rate-limited or lag | **close in MVP**: optional dev-mode API dump per session (env-gated); fingerprint dedup copy-worthy |
+| C2 | Last-N cache for ant support | missing | N — ant-specific UX | do-not-copy |
+| C3 | Init fingerprint dedup | dependent on C1 | N until C1 lands | tie to C1 |
+| C4 | Sidechain transcript with parent-chain UUID | missing for subagent (**already flagged in H11/H12 as close-in-MVP B7**) | **Y** — redundant with H11/H12 decision; reiterate here | already decided: close in MVP with subagent sidechain PR |
+| C5 | Agent metadata sidecar | missing (**already H11/H12 B8 close-in-MVP**) | **Y** | already decided |
+| C6 | Per-agent transcript under session dir | partially in the H11/H12 decision (sidechain in parent JSONL with fields, not per-agent files) | N — intentional divergence | do-not-copy; documented in H11/H12 PRD |
+
+### 3.4 Perfetto / hierarchical tracing (D)
+
+| # | Highlight | Local | MVP-critical? | Suggested action |
+|---|---|---|---|---|
+| D1 | Agent-tree registration | missing | N — H11/H12 sidechain already gives parent→child lineage via parent_message_id | defer with ADR |
+| D2-D6 | LLM / tool / user spans, instants, counters | missing | N — observability polish, not correctness | defer with ADR: "latency tracing is a post-MVP concern; RuntimeEvent timestamps are sufficient for MVP debugging" |
+
+### 3.5 Debug logging + SDK progress (E)
+
+| # | Highlight | Local | MVP-critical? | Suggested action |
+|---|---|---|---|---|
+| E1 | Structured debug logger | partial (Python `logging`, no consistent prefix or level gating per-agent) | **Y (small)** — add a tiny `logger_for(agent_name)` helper that adds agent context automatically; copy-cheap | **close in MVP**: convention + helper |
+| E2 | SDK progress stream | missing | N — no external SDK consumer yet | defer with ADR |
+| E3 | Parent TTFT forwarding | missing | N — no TTFT capture at all | defer (bundle with D2) |
+| E4 | cache_eviction_hint | missing | N | defer (B10) |
+
+### 3.6 Evidence / recovery surface (F)
+
+| # | Highlight | Local | MVP-critical? | Suggested action |
+|---|---|---|---|---|
+| F1 | Session JSONL ordered log | **aligned** (`JsonlSessionStore` with 5 append methods + record types) | — | no action |
+| F2 | Recovery brief assembly | **aligned or better** — local has pluggable `contribution_sections` which cc doesn't; active-todos + recent-evidence + recent-compacts covered | — | no action |
+| F3 | Content replacement records | missing (no equivalent of `toolResultStorage` cache-stable replacement) | **Y (for H05 consumer)** — already mentioned in compression staged plan | already scoped by `tool-result-storage-contracts.md`, track under H05 staged sub-tasks not H19 |
+
+---
+
+## 4. H19 Closeout Verdict
+
+**H19 dashboard status should be downgraded from `implemented` to `implemented-minimal`**
+with an explicit MVP closeout stage containing the items marked "close in MVP" in §3:
+
+Required for defensible `implemented`:
+
+1. **A1** Queued-until-sink event sink (drop-proof emission during startup)
+2. **B2** Split `auto_compact` into attempted + succeeded with metrics
+3. **B3** `post_autocompact_turn` recovery canary
+4. **B4** `orphan_tombstoned` event
+5. **B6** Structured `query_error` runtime event
+6. **B8** `token_budget` per-response event
+7. **C1** Optional dev-mode API dump (env-gated)
+8. **E1** Agent-scoped structured debug logger helper
+
+Items explicitly deferred with ADR (not gating H19 closeout):
+
+- A2-A6 analytics backend parity (no external backend in MVP)
+- B1, B5, B7, B9, B10 query events not backed by local features yet
+- C2, C5 ant-specific / SDK-specific conveniences
+- D1-D6 Perfetto latency tracing
+- E2, E3 SDK/TTFT features
+
+Items already scoped elsewhere (not re-tracked):
+
+- C4, C5 covered by H11/H12 sub-task B
+- F3 covered by tool-result-storage-contracts
+
+---
+
+## 5. Candidate Discussion Order
+
+Shortest dependency chain first.
+
+1. **Queued-until-sink + agent-scoped logger (A1 + E1)** — foundational wrapper, no new schemas, 1 small PR.
+2. **Compact-quality runtime events (B2 + B3 + B4)** — all fire from the compact pipeline; PR touches `compact/` and `evidence_events.py` in one place.
+3. **Structured query_error + token_budget (B6 + B8)** — runtime-level events fired from the agent loop wrapper; requires light wiring in `agent_runtime_service.py`.
+4. **Dev-mode API dump (C1)** — env-gated, no impact on production path; can land last or be shelved if H01 tool-module alignment plan already covers it.
+5. **Explicit deferral ADR** — one page capturing D1-D6, A2-A6, E2-E3 with cc source references.
+
+---
+
+## 6. Open Questions for Maintainer
+
+Only blocking/preference items.
+
+1. **Q — A1 queued-sink default**: should the default `RuntimeEventSink` become buffered-then-drain, or should CLI always construct a concrete sink before any runtime emits? cc's choice is buffer-by-default with microtask drain; ours could be "fail loudly if no sink" which forces explicit wiring.
+2. **Q — B3 recovery canary metric**: for the "first turn after compact" event, which token counts matter most — pre-compact total / post-compact total / new-turn input / new-turn output, or all four? cc logs all four.
+3. **Q — C1 API dump gating**: env variable opt-in (`CODING_DEEPGENT_DUMP_PROMPTS=1`) only, or also a CLI flag? cc has both; a dev-only env is cheapest.
+4. **Q — MVP closeout stage name**: land these under an existing Stage 28 closeout slot (where H19/H20 minimal is noted), or a dedicated stage 30+ row? Affects only planning, not code.
+5. **Q — B8 token_budget scope**: record it per-response (every assistant turn) or only at compact-decision boundaries? Every-turn is cheap and matches cc; per-boundary is leaner but loses trend data.
+
+---
+
+## Appendix: Items deliberately excluded
+
+- UI Teleport/ink rendering → do-not-copy (Python mainline has no TUI)
+- Agent ID generator details → internal implementation
+- First-party event-logging exporter / BQ proto hoisting → internal infra
+- LSPDiagnosticRegistry passive feedback → LSP integration not in MVP
+- Prompt-cache-break detection → provider-specific observability
diff --git a/.trellis/tasks/archive/2026-04/04-16-cc-highlight-alignment-discussion/prd.md b/.trellis/tasks/archive/2026-04/04-16-cc-highlight-alignment-discussion/prd.md
new file mode 100644
index 000000000..1d47254b6
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-cc-highlight-alignment-discussion/prd.md
@@ -0,0 +1,784 @@
+# brainstorm: cc highlight alignment discussion
+
+## Goal
+
+逐一讨论 `coding-deepgent` 与 cc-haha / Claude Code 的核心亮点对齐情况，优先识别当前实现里“名字看似对齐但功能/架构/长期规范没对上”的高价值差距，并形成后续可执行的讨论与实施顺序。
+
+## What I already know
+
+* 用户已经讨论过上下文压缩模块，并发现存在不少未对齐亮点。
+* 用户当前不希望先抽象讨论“底层设施需要哪些功能”，因为这会变成凭空设计。
+* 用户希望先对齐 cc 具体有哪些亮点，再从亮点反推 `coding-deepgent` 需要哪些底层设施。
+* 用户提供了工具系统五要素协议、dead-code elimination、concurrency partitioning、StreamingToolExecutor、类型契约/渐进式扩展等关键亮点。
+* 用户倾向先把后续亮点计划细节定清楚，再做一次高耦合集成实现，而不是边讨论边零碎实现。
+* 用户计划后续实现并发分区 / 工具编排引擎。
+* 用户判断 Streaming stage 太难，近期不做，只写入文档作为 deferred future capability。
+* 补充扫描 cc docs/source 后，工具模块仍有动态 tool pool、deferred ToolSearch、tool_use/tool_result pairing、结果映射/持久化/渲染分离、agent 工具池过滤等亮点需要纳入计划。
+* 当前 canonical roadmap 在 `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`，包含 H01-H22。
+* 当前 MVP boundary 包含 H01-H11、H15-H19、H12 minimal、H20 minimal。
+* H13 Mailbox / SendMessage、H14 Coordinator、H21 Bridge / remote / IDE、H22 Daemon / cron 被明确 deferred 出 MVP。
+* 最新基础设施复盘已新增 `.trellis/spec/backend/project-infrastructure-foundation-contracts.md`，要求后续围绕 transcript/session/compact/collapse/runtime pressure/task/subagent/hooks/memory 做项目级 gate。
+* 用户确认下一步讨论 H15/H16/H17 Skills / MCP / Plugin extension platform，并要求先基于 cc 文档和源码抽取具体亮点，再对比本地完成/未完成。
+* 用户判断 H15/H16/H17 extension platform 不是重点，甚至可以不做完整平台；目标是保底，不影响其他 cc 亮点继续推进。
+* 用户确认 H15/H16/H17 收束为 baseline only，下一组进入 H11/H12 Agent-as-tool / Subagent。
+
+## Assumptions (temporary)
+
+* 本轮不是立即实现代码，而是先确定 cc 亮点讨论顺序与每个亮点的对齐审计切入点。
+* “亮点没对上”主要指功能效果、运行时边界、LangChain/LangGraph-native 表达、持久化/恢复语义、模型可见面或测试合同没对齐，而不只是代码名字不同。
+* 讨论顺序应从用户可感知/cc 可观察的具体亮点出发，而不是从本地 infra taxonomy 出发。
+
+## Open Questions
+
+* MVP agent 催化剂最小集:仅 general + verifier,还是必须预置 explore / plan 占位?
+* subagent transcript 持久化边界:同 parent session JSONL(sidechain with parent_id)还是 per-agent 目录?
+* subagent result envelope 是否暴露完整 token usage breakdown (cache creation/read 分列) 还是只给 total?
+* general subagent 的 max_turns 上限取多少?
+
+## Requirements (evolving)
+
+* 先按 cc 具体亮点聚合 H01-H22，而不是先讨论抽象基础设施。
+* 每个亮点先说明“cc 中这个亮点解决什么问题、用户/agent 看到什么效果”，再判断本地需要什么底层设施。
+* 每个亮点讨论都需要关注 expected effect、cc source evidence、local target、LangChain primitive、当前差距、是否值得现在做。
+* 已讨论过的 context compression 相关内容应作为已知风险，不再只围绕单一 bug。
+* 第一轮深入讨论选择 H01/H02：Tool-first capability runtime 与 Permission runtime / hard safety。
+* H01/H02 第一轮子主题选择 Shell safety / Bash 权限。
+* Shell safety / Bash 权限不作为近期高优先级模块。
+* 权限模块目标调整为：简单可用、保留后续 cc 功能扩展边界，不阻塞后续 tool/task/subagent/MCP 亮点。
+* 第一阶段不做 classifier、sandbox、interactive permission dialog、复杂 Bash parser 移植。
+* 第一阶段应保持 LangChain-native middleware/policy 边界，不引入自定义 query loop。
+* H01 后续优先讨论工具控制面，而不是继续深挖低优先级权限模块。
+* H01 工具控制面方向确定：把本地 `ToolCapability` / tool metadata 作为五要素协议承载层。
+* 五要素协议包括：name、schema、permission、execution、rendering/result。
+* 协议扩展维度包括：concurrency、exposure、trust/source、large-output policy、runtime-pressure policy。
+* H01 五要素协议已固化到 `.trellis/spec/backend/tool-capability-contracts.md`。
+* H01 后续计划加入并发分区 / 工具编排引擎，但应作为独立高级执行层能力，不能破坏 LangChain-native runtime 边界。
+* Streaming tool-use execution 不进入近期实现范围，只保留文档约束和未来扩展点。
+* H01 工具讨论收尾前应补齐 remaining highlights 清单，避免后续 H15/H16/H11 讨论时遗漏。
+* 执行方式：先完成亮点对齐计划、依赖关系和实施切片，再进入实现；高耦合能力优先按集成批次完成。
+* H01 工具模块总计划已写入 `.trellis/plans/coding-deepgent-h01-tool-module-alignment-plan.md`。
+* 推荐下一个讨论模块：H15/H16/H17 Skills / MCP / Plugin extension platform。
+* H15/H16/H17 讨论方式：先做 source-backed highlight extraction，再做 local completion/gap matrix。
+* H15/H16/H17 策略调整为：只保留 LangChain-native 保底能力，不追求 cc marketplace/install/enable/auth/operation-plane parity。
+* H11/H12 讨论方式：先读 cc AgentTool/subagent/runtime source，再对照本地 run_subagent/task/session/runtime 实现。
+* H11/H12 source-backed 对齐调研已固化到 `.trellis/tasks/04-16-cc-highlight-alignment-discussion/h11-h12-alignment-research.md`,识别 15 组对齐亮点与 gap matrix。
+* H11/H12 候选讨论顺序:(1) 真 general-purpose child runtime → (2) AgentDefinition + 催化剂目录 → (3) subagent transcript/metadata 持久化 → (4) 结构化 result envelope → (5) deferred ADR。
+* H11/H12 第一步讨论选择 (1) real general-purpose child runtime。
+* general-purpose 子 agent 能力边界:**只读研究型**(read_file / glob / grep / task_get / task_list / plan_get),不含 write_file / edit_file / bash / TodoWrite / plan_save 等写工具。理由:与 cc explore/plan 对齐;避免把 H02 permission 投影复杂度拉进当前切片;契合 subagent_spawn_pressure_guard "缓解 parent context 压力" 的定位。未来 write-capable 子 agent 走独立 coder 类型加入目录。
+* MVP built-in agent 催化剂最小集:**general + verifier**。理由:cc 的 explore/plan 本身在 feature flag 背后;AgentDefinition 结构就位后加 explore/plan/coder 是"填表"而非"改架构";避免占位驱动实现。statusline-setup / claude-code-guide 是 cc-TUI 专属场景,LangChain-native mainline 判 do-not-copy。
+* subagent transcript 持久化:**sidechain 写回 parent session JSONL**,增加 `parent_message_id` / `subagent_thread_id` 字段,与 cc recordSidechainTranscript 语义一致;不单独开 per-agent 目录。理由:与 H06 JsonlSessionStore thread-keyed 结构一致;H05 compact / H19 evidence 查询只需扫单份 JSONL;subagent resume 目前 deferred,暂无需 per-agent 指针优化。
+* subagent result envelope usage 粒度:**minimal**(input_tokens / output_tokens / total_tokens / total_duration_ms / total_tool_use_count)。不含 cache_creation / cache_read / service_tier / server_tool_use。理由:与 H20 minimal 边界一致;LangChain UsageMetadata 对 provider-specific cache 字段覆盖不完整,强拉会引入 adapter 层;未来扩展只加字段不改消费者。
+* subagent max_turns:**general=25 / verifier=5**,通过 AgentDefinition 字段声明,不硬编码。理由:研究型任务典型 5-15 轮 tool call,25 给 2x 余量;verifier 只做读计划+读证据+verdict 三步,5 轮够;远低于 cc FORK_AGENT 200 是有意的——subagent_spawn_pressure_guard 已控制 parent 侧压力,无需让子 agent 消耗同规模上下文,天然约束任务粒度保持细。未来 coder 类型可声明更高上限。
+* H19 source-backed 调研已固化到 `.trellis/tasks/04-16-cc-highlight-alignment-discussion/h19-observability-alignment-research.md`,识别 6 大类对齐亮点与 gap matrix。
+* H19 dashboard 状态从 `implemented` 降级为 `implemented-minimal`,需 Stage 28 closeout(本就预留给 H19/H20 的 stage)。
+* H19 closeout 必做项:**A1** queued-until-sink event sink / **B2** auto_compact 拆 attempted+succeeded / **B3** post_autocompact_turn canary(四指标全记:pre_compact_total, post_compact_total, new_turn_input, new_turn_output)/ **B4** orphan_tombstoned 事件 / **B6** 结构化 query_error runtime event / **B8** per-turn token_budget 事件 / **C1** dev-mode API dump(env-only,`CODING_DEEPGENT_DUMP_PROMPTS=1`)/ **E1** agent-scoped debug logger 约定。
+* H19 明确 deferred(进 ADR):analytics backend 系(A2-A6)、Perfetto 层级追踪(D1-D6)、SDK progress + TTFT(E2-E3)、cache_eviction_hint(B10)、streaming 事件(B9)、attachment 边界(B1)。
+* H19 deferred ADR 一次性与 H11/H12 deferred ADR 合并为 Stage 29 产出物,不单独拆文件。
+
+## Acceptance Criteria (evolving)
+
+* [x] 给出当前几大对齐亮点分组。
+* [x] 给出推荐优先讨论顺序和理由。
+* [x] 用户选择第一组后，进入一组一组的 source-backed 对齐讨论。
+* [x] H01 工具模块总计划已固化为 Trellis plan。
+
+## Definition of Done (team quality bar)
+
+* 形成明确讨论顺序。
+* 每组讨论结论能落到 PRD/plan/spec，而不是停留在口头判断。
+* 若后续进入实现，必须按 Trellis task workflow 配置相关 spec context。
+
+## Out of Scope (explicit)
+
+* 本轮不直接修改 `coding-deepgent` 代码。
+* 不做 H01-H22 的逐项完整源代码审计，除非用户选定具体亮点组。
+* 不重新打开已 deferred 的远程/daemon 类能力，除非用户明确调整产品边界。
+* 不在每个亮点刚讨论完时立即实现零散 patch。
+
+## Technical Notes
+
+* Canonical roadmap: `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+* H01 tool plan: `.trellis/plans/coding-deepgent-h01-tool-module-alignment-plan.md`
+* Infra gate: `.trellis/spec/backend/project-infrastructure-foundation-contracts.md`
+* 当前建议优先围绕高耦合基础设施组讨论，而不是按 roadmap 编号线性推进。
+* 2026-04-16 用户选择从工具与权限体验开始讨论。
+* 2026-04-17 用户确认下一组讨论 H15/H16/H17 extension platform。
+* 2026-04-17 用户确认 H15/H16/H17 baseline only，下一组讨论 H11/H12 Agent-as-tool / Subagent。
+
+## Research Notes: H01/H02 Tool And Permission
+
+### cc-haha source points inspected
+
+* `/root/claude-code-haha/src/Tool.ts`
+  * `ToolPermissionContext`
+  * `ToolUseContext`
+  * `Tool`
+  * `ToolDef`
+  * `buildTool`
+* `/root/claude-code-haha/src/services/tools/toolOrchestration.ts`
+  * `runTools`
+  * `partitionToolCalls`
+  * `runToolsSerially`
+  * `runToolsConcurrently`
+* `/root/claude-code-haha/src/services/tools/toolExecution.ts`
+  * `runToolUse`
+  * `checkPermissionsAndCallTool`
+  * schema validation, tool validation, progress, hooks, result mapping
+* `/root/claude-code-haha/src/hooks/useCanUseTool.tsx`
+  * `CanUseToolFn`
+  * permission decision routing: allow / deny / ask / classifier / interactive / coordinator / swarm worker
+* `/root/claude-code-haha/src/types/permissions.ts`
+  * `PermissionMode`
+  * `PermissionBehavior`
+  * `PermissionRule`
+  * `PermissionResult`
+  * `PermissionUpdate`
+* `/root/claude-code-haha/src/utils/permissions/permissions.ts`
+  * rule loading/matching
+  * permission request message
+  * permission update/persistence
+* `/root/claude-code-haha/src/tools/BashTool/bashPermissions.ts`
+* `/root/claude-code-haha/src/tools/BashTool/bashSecurity.ts`
+* `/root/claude-code-haha/src/tools/BashTool/readOnlyValidation.ts`
+* `/root/claude-code-haha/src/tools/ToolSearchTool/ToolSearchTool.ts`
+* `/root/claude-code-haha/src/tools/ToolSearchTool/prompt.ts`
+
+### Local source points inspected
+
+* `coding-deepgent/src/coding_deepgent/tool_system/capabilities.py`
+* `coding-deepgent/src/coding_deepgent/tool_system/middleware.py`
+* `coding-deepgent/src/coding_deepgent/tool_system/policy.py`
+* `coding-deepgent/src/coding_deepgent/permissions/manager.py`
+* `coding-deepgent/src/coding_deepgent/permissions/rules.py`
+* `coding-deepgent/src/coding_deepgent/filesystem/policy.py`
+* `coding-deepgent/src/coding_deepgent/filesystem/service.py`
+* `coding-deepgent/src/coding_deepgent/filesystem/tools.py`
+
+### First-pass cc亮点拆分
+
+| Sub-highlight | cc expected effect | Local current shape | First-pass status |
+|---|---|---|---|
+| Tool definition as rich capability object | 每个工具不仅有 schema，还有 read-only/destructive/concurrency/search/defer/result/render/permission hooks 等运行时语义 | `ToolCapability` 保存 read_only/destructive/concurrency/source/trust/exposure/persist_large_output 等元数据 | partial |
+| Strict schema and tool-local validation | schema parse fail、tool-local validate fail 都回到模型可理解的 tool_result error | Pydantic `args_schema` 严格，部分 tool 有 service-level validation | partial |
+| Tool execution lifecycle | unknown tool、schema validation、permission、pre/post hooks、progress、call、result mapping、storage、telemetry 串成生命周期 | `ToolGuardMiddleware.wrap_tool_call` 覆盖 permission/hook/result storage/event；LangChain owns schema/call path | partial / LangChain-native |
+| Concurrency partitioning | read/concurrency-safe 工具可并发，非安全工具串行，context modifiers 之后合并 | 本地 capability 有 `concurrency_safe`，但未发现主 agent 显式 partition tool calls；依赖 LangChain runtime | possible gap |
+| Deferred tool discovery | 大量/MCP/低频工具可 deferred，模型先用 ToolSearch 拉 schema | 本地有 exposure `main`/`child_only`，MCP local loading；未发现 ToolSearch-style deferred schema discovery | likely gap / maybe deferred |
+| Permission modes | default/plan/acceptEdits/bypassPermissions/dontAsk/auto/bubble 等模式影响工具行为 | 本地有 default/plan/acceptEdits/bypassPermissions/dontAsk，无 auto/bubble | partial |
+| Permission rule model | allow/deny/ask rules 有来源、持久化目标、tool/content 匹配、MCP server/tool 粒度 | 本地有 `PermissionRuleSpec` 和 allow/ask/deny settings rules，source/domain/trust matching 较小 | partial |
+| Tool-specific permission | 通用权限后还有 tool.checkPermissions，例如 Bash/PowerShell 的命令级解析、安全、suggestions | 本地 permission 主要由 capability + generic manager + simple filesystem command/path policy 处理 | major gap for shell |
+| Interactive/worker/coordinator permission resolution | ask 不只是返回错误；可走 interactive prompt、worker auto-deny、coordinator automated check/classifier | 本地 `ask` 在 middleware 中转为 error ToolMessage，没有交互批准状态机 | gap by current MVP boundary |
+| Hard shell safety | Bash/PowerShell 有复杂解析、危险模式、read-only allowlist、path/sed/git/sandbox/classifier | 本地 `command_policy` 是字符串黑名单，read-only bash 是简单 shlex + token check | major gap |
+| Hook integration | PreToolUse/PostToolUse/PermissionDenied 可以 block、add context、modify MCP output、record attachments | 本地支持 PreToolUse/PostToolUse/PermissionDenied block 和 evidence，context/update 能力较小 | partial |
+| Tool result persistence / projection | 大输出落盘、返回 preview/path，参与后续 compact/restoration | 本地已实现 large output persistence contract | aligned for local slice |
+
+### Discussion implication
+
+H01/H02 不应该被讨论成“我们是否有工具 registry 和 permission manager”。更准确的问题是：
+
+* cc 里的工具控制面哪些效果对 `coding-deepgent` 是核心？
+* 哪些属于 LangChain 已经替我们托管的 runtime 行为？
+* 哪些必须产品本地补齐，例如 shell safety、ToolSearch/deferred tools、permission ask state machine、concurrency partitioning？
+* 哪些是 UI/remote/coordinator 相关，当前应继续 deferred？
+
+## User-provided H01 Key Points
+
+用户提供的 cc 工具系统亮点：
+
+* 五要素协议是工具系统的 DNA：名称、Schema、权限、执行、渲染。
+* `buildTool` 默认值机制让简单工具只关注核心逻辑，设计哲学是“显式声明，安全默认”。
+* dead-code elimination 通过环境变量和功能开关条件导入，避免内部工具泄漏到外部构建。
+* `isConcurrencySafe` 决定工具能否并发执行；正确标记只读工具可减少响应时间，错误标记会引入数据竞争。
+* `StreamingToolExecutor` 在模型生成 `tool_use` 块时就开始执行工具，通过状态机和顺序保证兼顾并行性与一致性。
+* `Tool<Input, Output, Progress>` 泛型和 `ToolUseContext` 让工具具备独立类型空间和统一执行环境，添加新工具无需修改编排引擎。
+
+### Fit Assessment
+
+| Key point | Fits cc highlight? | Local adoption judgment |
+|---|---|---|
+| 五要素协议：名称/Schema/权限/执行/渲染 | Yes, H01 core | Should adopt as design vocabulary, but map rendering to local CLI/model-visible result boundaries rather than React UI. |
+| `buildTool` 默认值 / 显式声明 / 安全默认 | Yes, H01 core | Should adopt conceptually. In LangChain, use strict `@tool` schemas plus `ToolCapability` defaults that are safe unless explicitly marked read-only/concurrency-safe/etc. |
+| Dead-code elimination | Yes for cc multi-product builds | Do not copy Bun/DCE mechanics now. Adopt feature-gated registration/source validation for plugins/MCP/internal tools when product needs it. |
+| Concurrency partitioning | Yes, H01 performance/safety | Important future gap. Local metadata exists, but execution is currently delegated to LangChain; need research before adding custom orchestration. |
+| StreamingToolExecutor | Yes, cc runtime highlight | Do not copy directly unless LangChain cannot provide equivalent streaming hooks. Current product should preserve LangChain runtime and only add an adapter if concrete latency need appears. |
+| Generic Tool type / ToolUseContext | Yes, H01 extensibility | Adopt via local typed domain schemas, `RuntimeContext`, `ToolCapability`, and middleware seams rather than recreating cc TS `Tool` interface. |
+
+### Current local mapping
+
+* Name: LangChain tool name + `ToolCapability.name`
+* Schema: Pydantic `args_schema` + `tool_call_schema` tests
+* Permission: `ToolGuardMiddleware` + `ToolPolicy` + `PermissionManager`
+* Execution: LangChain `create_agent` / tool node, domain `tools.py`, `Command(update=...)`
+* Rendering/result: `ToolMessage`, `Command(update={"messages": [...]})`, CLI renderers, large-output preview persistence
+
+### First-principles conclusion
+
+这些点符合 cc 的亮点，但不能逐字照搬。`coding-deepgent` 应该模仿的是协议和边界：
+
+* 每个工具显式声明五要素。
+* 默认不假设工具安全、只读、可并发、可压缩、可暴露。
+* 编排层只读取工具声明，不写死具体工具。
+* LangChain 负责基础 tool execution；本地只补 cc 需要但 LangChain 没表达的 metadata、policy、projection、evidence、rendering。
+
+不应模仿的是：
+
+* React UI rendering surface。
+* Bun feature/DCE 细节。
+* 自建 query/tool streaming loop，除非证明 LangChain runtime 无法满足 latency/order/cancellation 需求。
+
+## Decision (ADR-lite): H01 Tool Capability Protocol
+
+**Context**: cc 的 `Tool<Input, Output, Progress>` 和 `buildTool` 体现的是工具五要素协议与安全默认，而 `coding-deepgent` 当前已有 `ToolCapability`、strict Pydantic tools、middleware、large-output policy 和 runtime-pressure metadata，但协议还没有被明确命名为后续工具扩展的统一 contract。
+
+**Decision**: H01 后续按“五要素协议”讨论和收敛：每个工具都必须能被描述为 name、schema、permission、execution、rendering/result 五个维度；额外 capability metadata 用于 concurrency、exposure、trust/source、large-output、runtime-pressure 等 cross-cutting 行为。实现上不复制 cc TS `Tool` 接口，不复制 React rendering，不自建 streaming tool executor，优先通过 LangChain tool + middleware + `ToolCapability` 表达。
+
+**Consequences**:
+
+* 后续新增 skill/MCP/plugin/subagent/task tools 时，必须先声明五要素和扩展 metadata。
+* 默认值必须保守：未显式声明 read-only/concurrency-safe/trusted/persist/microcompact 的工具不得默认获得这些能力。
+* 若需要 streaming/concurrency optimization，应先证明 LangChain runtime 不足，再增加 adapter；不得直接引入 custom query loop。
+* H01 的下一步讨论重点应是协议字段、默认值、测试合同和 spec 固化，而不是权限深挖。
+
+## Decision (ADR-lite): Planning Before Integrated Implementation
+
+**Context**: cc 亮点之间高度耦合。工具协议会影响 task/subagent/MCP/skills，session/context 会影响 memory/subagent/verification。如果边讨论边零碎实现，容易在后续亮点出现时推翻前面的局部设计。
+
+**Decision**: 先完成亮点级计划细节：每个亮点的 expected effect、local target、依赖、是否立即实现、是否 deferred、对应 spec/test contract。计划收敛后，再按高耦合能力包做集成实现，而不是每个亮点单独小修。
+
+**Consequences**:
+
+* 可以一次性处理互相依赖的底层 seam，减少返工。
+* 不要求一次实现 H01-H22 全部；应按能力包拆分，例如 H01/H15/H16/H11 可能共享 tool capability protocol。
+* 每个集成批次开始前仍需要明确 PRD、spec context、验证范围和 stop/split 条件。
+
+## Planned Capability: Concurrent Tool Partitioning / Tool Orchestration Engine
+
+### Expected Effect
+
+当模型在同一轮产生多个 tool call 时，系统能够根据 `ToolCapability.concurrency_safe` 和 mutation/trust metadata 做确定性调度：
+
+* read/search 类安全工具可以并发执行
+* workspace/store/state mutation 工具必须串行或独占执行
+* 结果输出顺序保持与 tool call 顺序一致
+* sibling tool 失败、用户中断、streaming fallback 等情况有明确取消/错误传播规则
+* 编排层不写死具体工具名，只消费 capability metadata
+
+### cc Source Anchor
+
+* `/root/claude-code-haha/src/services/tools/toolOrchestration.ts`
+  * `partitionToolCalls`
+  * `runTools`
+  * `runToolsSerially`
+  * `runToolsConcurrently`
+* `/root/claude-code-haha/src/services/tools/StreamingToolExecutor.ts`
+  * queued/executing/completed/yielded 状态
+  * safe tools parallel, unsafe tools exclusive
+  * buffered ordered result emission
+  * sibling error / user interrupt / streaming fallback cancellation
+
+### Local Target
+
+近期目标不是复制 cc 的完整 `StreamingToolExecutor`，而是先设计一个 LangChain-native compatible orchestration boundary：
+
+* 保留 `create_agent` / middleware / `ToolRuntime` 作为主 runtime。
+* 先确认 LangChain 当前 tool execution 是否已有并发和顺序保证；不能重复造轮子。
+* 如果 LangChain runtime 不暴露足够控制点，再设计薄 adapter。
+* adapter 必须继续走 `ToolGuardMiddleware`、permission、hooks、large-output persistence、evidence。
+
+### Difficulty
+
+Difficulty: High
+
+原因：
+
+* 它不是普通工具函数，而是会影响 tool execution ordering、middleware 调用时机、state mutation、error propagation、streaming output、tool result message pairing。
+* 如果绕开 LangChain tool node，很容易变成 custom query loop，违反项目长期规范。
+* 并发安全需要依赖准确 metadata；metadata 错误会导致真实数据竞争。
+* 测试必须覆盖顺序、并发、失败、取消、state mutation、Command(update)、large-output、hooks/evidence 等组合。
+
+### Suggested Staging
+
+1. Spec stage:
+   * 定义并发分区合同、状态机、顺序保证、失败/取消语义。
+   * 明确哪些能力依赖 LangChain runtime，哪些能力需要本地 adapter。
+2. Research spike:
+   * 验证 LangChain `create_agent` / tool node 对 parallel tool calls 的现有行为。
+   * 判断是否能通过 middleware/config 实现，而不是自建 executor。
+3. Minimal adapter stage:
+   * 只支持非 streaming 的 batch partition：safe 并发、unsafe 串行、结果按原顺序返回。
+   * 不先做模型边生成边执行。
+4. Deferred documentation stage:
+   * Streaming tool-use execution 只写入文档，不进入近期实现。
+   * 文档保留未来约束：并发分区设计不得封死边生成 tool call 边执行、progress、cancellation、ordered yield 的可能性。
+   * 只有在未来出现明确低延迟需求、并证明 LangChain 无法满足时，才重新打开 streaming tool-use execution。
+
+### Out of Scope For First Implementation
+
+* 不复制 cc React/UI progress rendering。
+* 不实现 streaming tool-use execution。
+* 不支持完整 streaming fallback。
+* 不先支持 background shell task lifecycle。
+* 不绕过 `ToolGuardMiddleware`、permission、hooks、large-output persistence。
+
+### Deferred Streaming Note
+
+cc 的 `StreamingToolExecutor` 是真实亮点，但当前不进入 `coding-deepgent`
+近期实现。原因：
+
+* 需要接管模型流式输出中的 partial `tool_use` lifecycle。
+* 会影响 tool result ordering、progress、interrupt、sibling cancellation、
+  fallback discard 和 error synthesis。
+* 如果实现不慎，极易绕过 LangChain 官方 tool runtime 和 middleware。
+
+近期只要求：
+
+* spec 中记录 streaming 是 future capability。
+* batch/concurrency adapter 不得写死成无法扩展到 streaming。
+* 不因 deferred streaming 而阻塞五要素协议、capability metadata、非
+  streaming 并发分区的计划。
+
+## Remaining H01 Tool Highlights From cc Source/Docs
+
+### Source / docs reviewed
+
+* `/root/claude-code-haha/docs/must-read/01-execution-engine.md`
+* `/root/claude-code-haha/docs/modules/01-execution-engine-deep-dive.md`
+* `/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`
+* `/root/claude-code-haha/src/tools.ts`
+* `/root/claude-code-haha/src/constants/tools.ts`
+* `/root/claude-code-haha/src/utils/embeddedTools.ts`
+* `/root/claude-code-haha/src/utils/groupToolUses.ts`
+* `/root/claude-code-haha/src/utils/toolResultStorage.ts`
+* `/root/claude-code-haha/src/services/api/claude.ts`
+* `/root/claude-code-haha/src/services/api/errors.ts`
+
+### Remaining highlights
+
+| Highlight | cc expected effect | Local planning judgment |
+|---|---|---|
+| Dynamic tool pool | 可见工具不是常量；会随 permission、plan/agent mode、MCP connect、deferred discovery 改变 | Important. Should be discussed before H15/H16/H11. |
+| ToolSearch / deferred schema loading | 大量/MCP/低频工具先只暴露名字，按需加载完整 schema，降低 prompt/cache 压力 | Important but can stage after five-factor protocol. |
+| Tool pool filtering by agent role | async agent/coordinator/teammate 有不同 allowed/disallowed tool sets，防递归和越权 | Important for H11/H13/H14. |
+| Tool use/result pairing invariant | `tool_result.tool_use_id` 必须严格对应 `tool_use.id`；resume/compact/API error recovery 都要维护 | Already partially covered by compact specs; should be made H01 invariant too. |
+| Pairing repair / synthetic errors | orphaned tool_use/tool_result、duplicate IDs、streaming fallback 需要协议正确的 synthetic result | Future execution-engine hardening; not first H01 implementation. |
+| Tool result mapping vs UI rendering | model-facing `mapToolResult...`、transcript rendering、search text、group rendering 是不同 surface | Local should map this to ToolMessage/CLI/evidence, not React UI. |
+| Grouped tool rendering | 同一 assistant message 中多个同类 tool use 可分组显示，减少 UI 噪音 | UI/renderer enhancement; not blocking infra. |
+| Result persistence / preview | 大输出持久化、preview、path restoration、threshold opt-in | Already has local contract; keep tied to ToolCapability. |
+| Cache-aware tool schema layout | deferred tools、MCP tools、tool sections 会影响 prompt cache key | Important for future ToolSearch/context work; not immediate implementation. |
+| Embedded/replaced search tools | 环境具备 embedded search 时，移除 Glob/Grep 专用工具，避免重复能力 | Product-specific optimization; probably do-not-copy until needed. |
+| Dead-code / feature-gated tool registration | ant-only/internal/proactive/cron/remote tools 条件装载，防泄漏 | Keep as extension/source validation principle; do not copy Bun DCE. |
+| Tool failure remains protocol-correct | validation/permission/MCP auth/abort/fallback failures都转成模型可消费 tool_result | Important. Local middleware/errors should continue improving around this. |
+
+### H01 closeout recommendation
+
+H01 工具模块可以在计划层收束为四个 buckets：
+
+1. Tool capability protocol:
+   * five-factor protocol
+   * safe defaults
+   * metadata-driven middleware/projection
+2. Tool visibility and discovery:
+   * dynamic tool pool
+   * role-based tool filtering
+   * future ToolSearch/deferred schema
+3. Tool execution correctness:
+   * non-streaming concurrency partition
+   * strict tool_use/tool_result pairing
+   * protocol-correct errors/synthetic results
+   * streaming executor deferred
+4. Tool result/context pressure:
+   * result mapping/rendering separation
+   * large-output persistence
+   * microcompact eligibility
+   * cache-aware schema/layout as future context work
+
+## Research Notes: H15/H16/H17 Extension Platform
+
+### cc-haha source/docs inspected
+
+* `/root/claude-code-haha/docs/must-read/06-extension-platform.md`
+* `/root/claude-code-haha/docs/modules/06-extension-platform-deep-dive.md`
+* `/root/claude-code-haha/src/tools/SkillTool/SkillTool.ts`
+* `/root/claude-code-haha/src/skills/loadSkillsDir.ts`
+* `/root/claude-code-haha/src/skills/bundledSkills.ts`
+* `/root/claude-code-haha/src/skills/mcpSkillBuilders.ts`
+* `/root/claude-code-haha/src/services/mcp/config.ts`
+* `/root/claude-code-haha/src/services/mcp/client.ts`
+* `/root/claude-code-haha/src/services/mcp/types.ts`
+* `/root/claude-code-haha/src/services/mcp/normalization.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/installedPluginsManager.ts`
+* `/root/claude-code-haha/src/utils/plugins/validatePlugin.ts`
+* `/root/claude-code-haha/src/utils/hooks/AsyncHookRegistry.ts`
+* `/root/claude-code-haha/src/utils/hooks/hookEvents.ts`
+* `/root/claude-code-haha/src/utils/hooks/sessionHooks.ts`
+* `/root/claude-code-haha/src/utils/hooks/ssrfGuard.ts`
+
+### Local source inspected
+
+* `coding-deepgent/src/coding_deepgent/skills/*`
+* `coding-deepgent/src/coding_deepgent/mcp/*`
+* `coding-deepgent/src/coding_deepgent/plugins/*`
+* `coding-deepgent/src/coding_deepgent/hooks/*`
+* `coding-deepgent/src/coding_deepgent/extensions_service.py`
+* `coding-deepgent/src/coding_deepgent/tool_system/capabilities.py`
+* `coding-deepgent/src/coding_deepgent/containers/app.py`
+* `coding-deepgent/src/coding_deepgent/containers/tool_system.py`
+* `coding-deepgent/tests/extensions/test_skills.py`
+* `coding-deepgent/tests/extensions/test_mcp.py`
+* `coding-deepgent/tests/extensions/test_plugins.py`
+* `coding-deepgent/tests/extensions/test_hooks.py`
+* `coding-deepgent/tests/tool_system/test_tool_system_registry.py`
+
+### Highlight completion matrix
+
+| ID | Concrete cc highlight | Current local state | Status |
+|---|---|---|---|
+| H15 | Skill as capability bridge between command system and agent runtime | Local `load_skill` tool reads `skills/<name>/SKILL.md` with strict frontmatter and bounded render | partial |
+| H15 | Multi-source skills: bundled, directory, plugin, MCP, remote | Local only supports local directory skills via `load_skill`; no bundled/plugin/MCP/remote skill unification | missing/deferred |
+| H15 | Skill metadata: allowed tools, when-to-use, model/effort, hooks, fork/inline context | Local schema only has `name` and `description`; body is text | missing |
+| H15 | Forked skill execution | Local `load_skill` only returns content to current model; no forked skill agent | missing/deferred |
+| H15 | Bundled skill reference files extracted safely on demand | Not present | missing/deferred |
+| H16 | MCP config strict loading | Local `.mcp.json` strict schema supports stdio/http/sse and `type` alias | partial/aligned local slice |
+| H16 | Official LangChain MCP adapter seam | Local probes `langchain_mcp_adapters` and loads tools through `MultiServerMCPClient` when available | partial/aligned local slice |
+| H16 | MCP tools become capability entries with source/trust metadata | Local maps MCP descriptors to `ToolCapability(source="mcp:<server>", trusted=False, exposure="extension")` | aligned local slice |
+| H16 | MCP resources separate from executable tools | Local `MCPResourceRegistry` keeps resources out of tool capabilities | aligned local slice |
+| H16 | MCP multi-transport breadth: stdio, sse, http, ws, sdk, proxy | Local supports stdio/http/sse only | partial |
+| H16 | MCP auth/OAuth/XAA/channel permissions/elicitation/notifications | Not present | missing/deferred |
+| H16 | MCP connection manager and status lifecycle | Local load is synchronous/one-shot at startup; no connection manager/status lifecycle | missing/deferred |
+| H16 | MCP name normalization/dedup with plugin/manual precedence | Local has no deep normalization/dedup beyond strict config and duplicate registry names | missing |
+| H17 | Local plugin manifest schema | Local `plugin.json` is strict metadata-only with name/description/version/skills/tools/resources | aligned local minimal |
+| H17 | Plugin declaration validation against known local tools/skills/resources | Local registry validates declared tools/skills/resources; startup blocks unknown entries | aligned local minimal |
+| H17 | Plugin runtime execution/components | Local plugin does not execute code and does not load commands/agents/hooks/output styles | intentionally deferred |
+| H17 | Marketplace/source/install/enable three-state model | Not present; local plugin dir only | missing/deferred |
+| H17 | installed_plugins.json, versioned cache, cache-only vs full load | Not present | missing/deferred |
+| H17 | Plugin trust policy, blocklist, source validation, dependency resolver | Local has strict local identifiers and no runtime code execution; no marketplace/dependency/trust lifecycle | partial/deferred |
+| H18 adjacent | Local lifecycle hooks | Local sync `LocalHookRegistry` supports SessionStart/UserPromptSubmit/PreToolUse/PostToolUse/PermissionDenied/PreCompact/PostCompact | partial/aligned local slice |
+| H18 adjacent | Async hooks, HTTP hooks, prompt/post-sampling/frontmatter/skill hooks | Not present | missing/deferred |
+| H18 adjacent | Hook SSRF guard and timeout/progress events | Not present | missing/deferred |
+| Platform ops | `/plugin`, `/mcp`, `/skills` management commands | Not present in current local CLI | missing/deferred |
+
+### First-pass judgment
+
+本地 H15/H16/H17 是 local MVP extension foundation，不是完整 cc extension platform。
+
+完成较好的 local slice:
+
+* Local skill loading as explicit tool.
+* Local plugin manifest validation as metadata-only declaration.
+* Plugin declarations validated against known local tool/skill/resource surfaces.
+* MCP local config loading and official LangChain adapter seam.
+* MCP tool -> `ToolCapability` mapping with source/trust/exposure metadata.
+* MCP resources kept separate from executable tool capabilities.
+* Basic local sync hooks.
+
+主要未完成:
+
+* Plugin platform lifecycle: marketplace/source/install/enable/cache/update.
+* MCP connection/auth lifecycle: connection manager, status, OAuth/XAA, channel permissions, notifications.
+* Multi-source skill unification and forked skill execution.
+* Async/HTTP/frontmatter/skill hooks as programmable middleware.
+* User-facing operation plane commands.
+
+### Recommended next discussion focus
+
+建议不要一口气讨论完整 extension platform。下一步应先讨论：
+
+1. **H16 MCP external capability protocol**:
+   * 因为它直接消费 H01 `ToolCapability`。
+   * 本地已有基础实现，容易判断 near-term 是否补 connection/auth/transport/dedup。
+2. 然后讨论 **H15 Skills**:
+   * Skill 是否只是 `load_skill` 文本加载，还是要成为多来源/可 fork capability。
+3. 最后讨论 **H17 Plugin lifecycle**:
+   * 当前 local manifest 已够 MVP；marketplace/install/enable/cache 是更大产品边界。
+
+### Provisional near-term/deferred split
+
+Near-term baseline:
+
+* Keep current local `load_skill` tool as a bounded local skill loader.
+* Keep current `.mcp.json` strict config and optional official LangChain MCP adapter seam.
+* Keep MCP tool conversion into `ToolCapability` with source/trust/exposure metadata.
+* Keep MCP resources separate from executable tools.
+* Keep local plugin manifest metadata-only and validate declarations against known tools/skills/resources.
+* Keep hooks as local deterministic middleware events; do not expand them into a plugin/runtime platform.
+* Use H01 `ToolCapability` contracts as the shared guardrail for all extension-provided tools.
+
+Deferred:
+
+* Marketplace/install/update/cache lifecycle.
+* Full MCP auth/OAuth/XAA/channel permissions.
+* Remote/HTTP/WebSocket/sdk transports beyond current local slice unless needed.
+* Forked skill execution.
+* Async/HTTP/frontmatter/skill hooks.
+* `/plugin`, `/mcp`, `/skills` operation plane.
+
+## Decision (ADR-lite): Extension Platform Baseline
+
+**Context**: cc 的 H15/H16/H17 extension platform 很大，包含 MCP 多 transport/auth、plugin marketplace/install/cache/enable、multi-source/forked skills、async/HTTP/frontmatter hooks 和操作面命令。用户当前目标不是复制完整平台，而是保证后续工具、subagent、task、context 等 cc 亮点不被扩展层卡住。
+
+**Decision**: H15/H16/H17 近期只做保底。沿用 LangChain/LangGraph-native 工具、中间件、`ToolCapability`、本地 strict schemas 和 source/trust/exposure metadata。完整 plugin marketplace、MCP auth/connection lifecycle、forked skills、async hooks 和操作面命令全部 deferred，除非后续亮点提出具体依赖。
+
+**Consequences**:
+
+* 当前本地实现基本够作为保底 extension layer。
+* 后续重点应回到 H11/H12 subagent 或 H08-H10 workflow，而不是继续深挖 extension platform。
+* 对 extension-provided capability 的最低要求是：严格 schema、source/trust metadata、permission 经过 `ToolGuardMiddleware`、不绕过 H01 tool capability protocol。
+* 如果未来 MCP/plugin 数量或外部能力风险上升，再单独开启 H15/H16/H17 扩展平台任务。
+
+## Research Notes: H11/H12 Agent-as-tool / Subagent
+
+### cc-haha source/docs inspected
+
+* `/root/claude-code-haha/docs/must-read/02-agent-runtime.md`
+* `/root/claude-code-haha/docs/modules/02-agent-runtime-deep-dive.md`
+* `/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/forkSubagent.ts`
+* `/root/claude-code-haha/src/tools/AgentTool/resumeAgent.ts`
+* `/root/claude-code-haha/src/tools/AgentTool/agentMemory.ts`
+* `/root/claude-code-haha/src/tools/AgentTool/agentMemorySnapshot.ts`
+* `/root/claude-code-haha/src/tasks/LocalAgentTask/LocalAgentTask.tsx`
+* `/root/claude-code-haha/src/tools/SendMessageTool/SendMessageTool.ts`
+* `/root/claude-code-haha/src/services/AgentSummary/agentSummary.ts`
+
+### Local source/spec inspected
+
+* `coding-deepgent/src/coding_deepgent/subagents/tools.py`
+* `coding-deepgent/src/coding_deepgent/subagents/schemas.py`
+* `coding-deepgent/tests/subagents/test_subagents.py`
+* `coding-deepgent/src/coding_deepgent/runtime/context.py`
+* `coding-deepgent/src/coding_deepgent/runtime/invocation.py`
+* `coding-deepgent/src/coding_deepgent/tasks/*`
+* `.trellis/spec/backend/task-workflow-contracts.md`
+* `.trellis/spec/backend/runtime-pressure-contracts.md`
+* `.trellis/spec/backend/project-infrastructure-foundation-contracts.md`
+
+### Highlight completion matrix
+
+| ID | Concrete cc highlight | Current local state | Status |
+|---|---|---|---|
+| H11 | Agent is first a tool, so it inherits permission/tool/runtime protocols | Local has `run_subagent` LangChain tool with strict schema and `ToolCapability(execution="child_agent_bridge")` | partial/aligned local slice |
+| H11 | AgentTool can launch specialized subagents by agent definition/type | Local supports only `agent_type="general"|"verifier"`; no custom/built-in agent definition loading | partial |
+| H11 | Verifier as specialized child agent | Local verifier resolves `PlanArtifact`, uses read-only allowlist, runs a real `create_agent`, returns structured JSON, persists verdict evidence | aligned strong local slice |
+| H11 | General subagent as real child runtime | Local general subagent returns synchronous accepted text unless fake factory provided; no real general child `create_agent` path | missing |
+| H11 | Role-based child tool allowlists | Local has exact verifier/general allowlists and excludes mutating tools | aligned local slice |
+| H11 | Agent has its own runtime invocation/thread identity | Local verifier uses child `thread_id = parent:verifier:<plan_id>` and `entrypoint="run_subagent:verifier"` | partial/aligned |
+| H11 | Agent progress/task lifecycle object | cc has `LocalAgentTask` with running/completed/failed/killed/progress/output/notifications; local has no agent task object for subagent lifecycle | missing/deferred |
+| H11 | Agent transcript/metadata persistence and resume | cc persists sidechain transcript + metadata and resumes agent; local only persists verifier evidence in parent session, not child transcript/resume | missing/deferred |
+| H11 | Background/async agent | cc supports background agent lifecycle; local `max_turns=1` synchronous only | missing/deferred |
+| H11/H13 | Mailbox / SendMessage | cc has `SendMessageTool` and pending message queues; local has no mailbox/send-message | deferred out of MVP |
+| H12 | Fork subagent inherits parent context/cache-safe prefix | cc fork preserves parent tool_use structure and cache-identical prefix; local has no forked context execution | missing/deferred |
+| H12 | Minimal context/thread propagation | Local passes runtime context/config/store into verifier child and records lineage evidence | aligned minimal slice |
+| H12 | Spawn guard under runtime pressure | Local has subagent spawn pressure guard using `RuntimeContext.model_context_window_tokens` and evidence | aligned local hardening |
+| H12 | Agent memory and snapshots | cc has per-agent memory scopes and snapshot sync; local has no agent-scoped memory beyond global memory/session memory | missing/deferred |
+| H12/H20 | Agent summary side-agent | cc periodically forks summarizer for progress; local has no agent summary side-agent | missing/deferred |
+| H14 | Coordinator synthesis ownership | cc docs emphasize coordinator must keep synthesis; local coordinator runtime deferred | deferred |
+
+### First-pass judgment
+
+本地 H11/H12 当前不是完整 Agent Runtime，而是：
+
+```text
+bounded verifier-as-tool MVP + minimal child runtime propagation
+```
+
+完成得较好的部分：
+
+* `run_subagent` 是模型可见工具，符合 Agent-as-tool 的入口原则。
+* verifier 是真实 child agent，而不是纯 prompt wrapper。
+* verifier 有 durable plan boundary、read-only tool allowlist、child thread id、structured result、session evidence lineage。
+* 有 subagent spawn pressure guard，避免在上下文压力过高时继续派生子 agent。
+
+主要缺口：
+
+* general subagent 不是真实 child agent。
+* 没有 agent definition registry / built-in agents / custom agents。
+* 没有 LocalAgentTask 生命周期对象。
+* 没有 child transcript/metadata/resume。
+* 没有 background/async execution。
+* 没有 mailbox/SendMessage。
+* 没有 fork/cache-aware context execution。
+* 没有 agent memory/snapshot/summary。
+
+### Near-term vs deferred
+
+Near-term candidates:
+
+* Make `general` subagent a real bounded child agent only if it has a concrete local effect beyond verifier.
+* Formalize child runtime contract in spec:
+  * child thread id
+  * parent lineage
+  * tool allowlist
+  * evidence boundary
+  * spawn guard
+* Decide whether `run_subagent` should remain verifier-first or become general-purpose.
+* Keep H01 role-based tool projection aligned with subagent needs.
+
+Deferred:
+
+* LocalAgentTask lifecycle.
+* Background/async agents.
+* Mailbox/SendMessage.
+* Coordinator runtime.
+* Fork/cache-aware full context cloning.
+* Agent memory/snapshot/summary.
+* Worktree/remote isolation.
+
+### Key design question
+
+下一步不是“要不要复制 AgentTool”，而是：
+
+```text
+coding-deepgent 的近期 subagent 是否只需要 verifier-backed workflow，
+还是需要把 general subagent 升级成真实 child agent runtime？
+```
+
+如果近期重点是 H08-H10 workflow，那么 verifier-first 足够。
+如果近期要支持 H11 product parity，就需要 general child agent + minimal
+agent definition/tool projection contract。
+
+## Research Notes: Shell Safety / Bash Permission
+
+### cc-haha shell safety source points inspected
+
+* `/root/claude-code-haha/src/tools/BashTool/BashTool.tsx`
+  * strict input schema includes `command`, `description`, timeout/background/sandbox-related fields
+  * `isReadOnly(input)` delegates to `checkReadOnlyConstraints`
+  * `checkPermissions(input, context)` delegates to `bashToolHasPermission`
+  * command execution handles progress, backgrounding, sandbox annotation, persisted output, code indexing hints
+* `/root/claude-code-haha/src/tools/BashTool/bashPermissions.ts`
+  * `bashToolCheckExactMatchPermission`
+  * `bashToolCheckPermission`
+  * `checkCommandAndSuggestRules`
+  * `filterRulesByContentsMatchingInput`
+  * `matchingRulesForInput`
+  * `commandHasAnyCd`
+  * `isNormalizedGitCommand`
+* `/root/claude-code-haha/src/tools/BashTool/bashSecurity.ts`
+  * dangerous shell pattern detection including command substitution, zsh expansion, heredoc substitution, dangerous variables, shell metacharacters, jq `system`, git commit substitution, malformed tokens
+* `/root/claude-code-haha/src/tools/BashTool/readOnlyValidation.ts`
+  * command allowlist with safe flags
+  * `isCommandSafeViaFlagParsing`
+  * `checkReadOnlyConstraints`
+  * git internal path and cwd-change protections
+* `/root/claude-code-haha/src/tools/BashTool/pathValidation.ts`
+  * per-command path extractors
+  * output redirection validation
+  * dangerous removal path detection
+  * workspace/additional-working-dir checks
+  * path-based permission suggestions
+* `/root/claude-code-haha/src/tools/BashTool/sedValidation.ts`
+  * strict sed read/edit allowlist instead of generic shell allow
+* `/root/claude-code-haha/src/tools/BashTool/modeValidation.ts`
+  * acceptEdits auto-allow for a narrow filesystem command set
+* `/root/claude-code-haha/src/tools/BashTool/shouldUseSandbox.ts`
+  * sandbox selection and excluded-command matching
+
+### Local shell safety source points inspected
+
+* `coding-deepgent/src/coding_deepgent/filesystem/policy.py`
+  * `DANGEROUS_COMMANDS = ("rm -rf /", "sudo", "shutdown", "reboot", "> /dev/")`
+  * `command_policy(command)`
+  * `safe_path(path_str, workdir, additional_workdirs)`
+  * `path_policy(...)`
+* `coding-deepgent/src/coding_deepgent/permissions/manager.py`
+  * `is_read_only_bash(command)` uses `shlex.split`, rejects simple metacharacter tokens, allowlists first word
+  * `_hard_safety_decision` calls `command_policy`
+  * `_mode_decision` treats read-only bash as allow, write-like bash as ask/deny by mode
+* `coding-deepgent/tests/permissions/test_permissions.py`
+  * covers simple read-only bash, write-like bash, dangerous substring, mode behavior
+* `coding-deepgent/tests/filesystem/test_tools.py`
+  * covers runtime-owned workdir and blocking `rm -rf /`
+
+### Shell safety gap map
+
+| cc sub-capability | Local gap | Risk if ignored |
+|---|---|---|
+| Structured command parsing | local uses `shlex` and string tokens only | shell injection, quoted/operator edge cases, false allow/false ask |
+| Read-only command validation | local allows by first word and rejects common operators | cannot distinguish safe flags from unsafe flags or read commands with dangerous forms |
+| Path extraction from shell commands | local validates `path` args for path tools, not paths embedded in bash command | `cat ../x`, redirects, `rm -- path`, `find -- path`, `git` cwd cases are not modeled deeply |
+| Output redirection handling | only coarse `> /dev/` substring block | file writes via redirection are not part of permission/path logic |
+| Deny/ask/allow rule normalization | local content matching is simple substring across args | env/wrapper/compound command bypass or overmatching risk |
+| Sed-specific handling | no local sed parser/allowlist | sed read vs edit cannot be safely distinguished |
+| Git/cwd safety | no modeled cd+git / internal path protections | sandbox/workspace assumptions can be bypassed in future richer shell runtime |
+| Sandbox decision | no sandbox backend in local `run_bash` | current safety must be permission-only; cannot rely on runtime containment |
+| Permission suggestions | no rule suggestion output | ask flow cannot teach safe persistent rules |
+| Classifier/auto mode | absent | acceptable to defer, but must not claim parity |
+
+### First-pass judgment
+
+本地 shell safety 是 MVP/minimal，不是 cc-aligned hard safety。它适合作为早期 demo guard，但如果后续要承接 subagent、MCP/plugin tools、agent tasks、background shell、workspace trust 或更高权限模式，必须把 Bash 权限单独升级成产品级 domain，而不是继续把逻辑塞进 generic `PermissionManager` 或 `filesystem.policy.command_policy`。
+
+### Feasible approaches
+
+**Approach A: Deterministic shell safety core** (Recommended)
+
+* How it works:
+  * 新增/扩展本地 shell safety module，先不做 classifier 和 sandbox。
+  * 明确 pipeline：parse-ish tokenize -> deny/ask/allow rules -> dangerous pattern -> path/redirection -> sed/git/read-only -> mode decision。
+  * 输出 `PermissionDecision` with reason/code/metadata/suggestions placeholder。
+* Pros:
+  * 最大化当前安全收益。
+  * 不依赖 UI/远程/sandbox。
+  * Fits LangChain middleware / local permission policy.
+* Cons:
+  * 需要复制/移植一部分 shell safety 思维，测试面较大。
+
+**Approach B: Permission ask state machine first**
+
+* How it works:
+  * 先把 `ask` 从 error ToolMessage 升级成可恢复/可批准的状态，再逐步补 shell parser。
+* Pros:
+  * 更接近 cc 用户体验。
+  * 后续可支持 session allow rule。
+* Cons:
+  * 如果 shell safety 仍薄，批准机制可能让危险命令更容易执行。
+
+**Approach C: Keep shell safety minimal until subagent/MCP pressure appears**
+
+* How it works:
+  * 当前只记录差距，不实施。
+  * 继续靠 permission modes + coarse dangerous command guard。
+* Pros:
+  * 成本最低。
+  * 不会过早实现一套复杂 shell policy。
+* Cons:
+  * 后续任何工具/agent 扩展都会建立在弱 shell 安全上。
+  * “H02 implemented” 的判断会继续偏乐观。
+
+## Decision (ADR-lite): Shell Safety Direction
+
+**Context**: H01/H02 的 cc source review 显示 Bash 权限是多层安全判定管线，而本地当前只有 coarse command blacklist、简单 read-only first-word 判定和 path tools 的 workspace policy。该差距会影响后续 subagent、MCP/plugin tools、task execution、permission mode 和 hooks 的安全基础。
+
+**Decision**: 权限模块优先级下调。近期不追求完整 cc Bash safety parity，只保留简单安全底线和可扩展 policy/middleware seam。后续如 subagent/MCP/task execution 对 shell safety 提出真实压力，再单独启动 deterministic shell safety core。
+
+**Consequences**:
+
+* 本地 H02 不应按“已有 permission manager”乐观判断完全对齐；Shell safety 维持 partial/deferred。
+* 当前必须保留 `filesystem` / `permissions` / `tool_system` 的 LangChain-native policy/middleware seam，避免未来重做入口。
+* 不引入复杂 Bash parser、classifier、sandbox、ask approval UI、permission suggestion persistence。
+* 若后续亮点需要更强 shell safety，按独立任务补 deterministic shell safety core，而不是把复杂逻辑临时塞进 generic `PermissionManager`。
+
+## Final Closeout (2026-04-19)
+
+This brainstorm is complete and should not stay active as a development task.
+Its useful outputs have been absorbed into later canonical artifacts and
+implementation tasks:
+
+* H01/H02/H11/H12/H19 discussion produced source-backed gap maps and staged
+  implementation direction.
+* H01 closeout now includes five-factor `ToolCapability`, role projection,
+  dynamic/deferred tool discovery, tool pairing/failure coverage, result
+  persistence audit, and conditional/spec-only `L5-a`.
+* H11/H12 closeout now includes `AgentDefinition`, read-only `general` /
+  `verifier`, sidechain transcript audit, explicit fork/fork-resume surfaces,
+  and deferred lifecycle tooling.
+* H19 closeout now includes queued event sink/logger, compact observability,
+  query_error/token_budget/API dump events, and roadmap/dashboard refresh.
+* Remaining shell-hardening / coordinator / remote / daemon items are captured
+  as deferred or future focused work in the canonical roadmap and deferred ADR.
+
+Future work should open a new focused implementation PRD rather than continuing
+this broad highlight-alignment discussion.
diff --git a/.trellis/tasks/archive/2026-04/04-16-cc-highlight-alignment-discussion/task.json b/.trellis/tasks/archive/2026-04/04-16-cc-highlight-alignment-discussion/task.json
new file mode 100644
index 000000000..e18221f1b
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-cc-highlight-alignment-discussion/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "cc-highlight-alignment-discussion",
+  "name": "cc-highlight-alignment-discussion",
+  "title": "brainstorm: cc highlight alignment discussion",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-16",
+  "completedAt": "2026-04-19",
+  "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/archive/2026-04/04-16-cc-level-3-collapse-alignment/prd.md b/.trellis/tasks/archive/2026-04/04-16-cc-level-3-collapse-alignment/prd.md
new file mode 100644
index 000000000..379faea6b
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-cc-level-3-collapse-alignment/prd.md
@@ -0,0 +1,157 @@
+# brainstorm: cc level 3 collapse alignment
+
+## Goal
+
+评估用户提供的 `Level 3: Collapse` 描述是否符合 cc-haha 可见源码，并判断当前 `coding-deepgent` 的 Collapse 是否对齐，以及后续还有哪些 cc 亮点值得规划。
+
+## Communication Requirement
+
+When explaining context compression mechanisms, use concrete scenarios before
+terms. The user explicitly prefers examples such as "long coding session,
+testing logs, file reads, subagent spawn" over mechanism-only lists.
+
+## What I already know
+
+* 当前 `coding-deepgent` 已实现 summarizer-based live `Collapse`：
+  * `maybe_collapse_messages(...)`
+  * `collapse_live_messages_with_summary(...)`
+  * 在 `RuntimePressureMiddleware.wrap_model_call()` 中运行于 `MicroCompact` 之后、`AutoCompact` 之前。
+* 当前实现是 live model-call rewrite，失败时 fail-open，不持久化 collapse store，不记录 staged collapse drain state。
+* 用户提供的描述强调 90% commit、95% spawn block、主动重构、抑制 AutoCompact、选择性消息组重构、与 fork/spawn 交互。
+
+## Source Notes
+
+cc-haha source reviewed:
+
+* `/root/claude-code-haha/src/query.ts`
+* `rg CONTEXT_COLLAPSE/contextCollapse` in `/root/claude-code-haha/src`
+
+Key source-backed facts:
+
+* `query.ts` feature-gates `contextCollapse` via `feature('CONTEXT_COLLAPSE')`.
+* `contextCollapse.applyCollapsesIfNeeded(...)` runs after `microcompact` and before `autocompact`.
+* Source comments state collapse runs before autocompact so if collapse gets the input under autocompact threshold, autocompact is a no-op and granular context is preserved.
+* Source comments state collapse is a read-time projection over full REPL history.
+* Summary messages live in a collapse store, not in the REPL array.
+* Collapse persists across turns because `projectView()` replays the commit log on every entry.
+* Prompt-too-long recovery first attempts `contextCollapse.recoverFromOverflow(...)` to drain staged collapses before reactive compact.
+* Query logic has `collapseOwnsIt` and withheld error handling so context-collapse recovery can own certain prompt-too-long conditions before autocompact/reactive compact surfaces them.
+* The actual `services/contextCollapse/index.js/ts` implementation file is not present in this local public checkout, so exact threshold constants such as 90% commit and 95% spawn-block cannot be source-verified here.
+
+## Evaluation Of User Description
+
+The description is directionally aligned with visible cc behavior:
+
+* Collapse is a more granular active context restructuring layer.
+* It runs before AutoCompact and can suppress/avoid AutoCompact by reducing pressure first.
+* It preserves more granular context than full AutoCompact.
+* It has an overflow recovery role before reactive compact.
+
+Parts not source-verified from this checkout:
+
+* Exact 90% commit threshold.
+* Exact 95% spawn-block threshold.
+* Exact spawn/fork blocking implementation.
+* Exact internal grouping/commit algorithm.
+
+Therefore, describe those as likely cc design details from non-visible context,
+not as verified facts from the available source tree unless another source is
+provided.
+
+## Current `coding-deepgent` Alignment
+
+Aligned:
+
+* Collapse exists in runtime pressure pipeline.
+* Collapse runs before AutoCompact.
+* Collapse uses a summarizer and preserves recent tail.
+* Collapse fail-open behavior preserves model call reliability.
+* Collapse is live rewrite and does not physical-delete transcript.
+* Collapse emits bounded runtime pressure event/evidence.
+
+Not aligned / missing:
+
+* No utilization-ratio trigger based on model context window percentage.
+* No 90% staged commit threshold.
+* No 95% spawn/subagent block.
+* No persistent collapse store or commit log replay.
+* No read-time projection over full raw history.
+* No staged collapse drain before reactive compact.
+* No explicit AutoCompact suppression beyond natural ordering.
+* No grouping algorithm that selectively collapses message groups while retaining granular raw context.
+* No fork/subagent interaction policy.
+
+## Extra cc Collapse Highlights Worth Considering
+
+### 1. Read-Time Projection Over Raw History
+
+Collapse should be a projection over raw transcript, not a destructive rewrite.
+Future UI/resume can show raw history while model-facing history uses collapse
+projection.
+
+### 2. Collapse Store / Commit Log
+
+cc comments indicate summary messages live outside the REPL array and are replayed
+by `projectView()`. This suggests a durable collapse record model similar to
+compact records but more granular.
+
+### 3. AutoCompact Avoidance
+
+Collapse is valuable because it can reduce pressure enough to avoid full
+AutoCompact, preserving more original context.
+
+### 4. Overflow Drain Before Reactive Compact
+
+On prompt-too-long, drain staged collapse first; only if that fails, run full
+reactive compact.
+
+### 5. Context-Window Percentage Thresholds
+
+Instead of fixed token thresholds, use utilization ratio against model context
+window when reliable model limits are available.
+
+### 6. Spawn/Fork Pressure Policy
+
+At high pressure, block or warn before spawning subagents because forked context
+would multiply pressure. This should be planned carefully for our LangChain
+subagent model.
+
+### 7. Selective Group Collapse
+
+Collapse should ideally summarize older message groups while preserving recent
+groups and critical tool-call/tool-result pairs.
+
+### 8. UI/Observability
+
+Collapse records should be visible in future compression timeline with group IDs,
+summary, affected message IDs, and trigger utilization.
+
+## Requirements (Future)
+
+* Decide whether to keep current live Collapse as MVP or plan a richer cc-style
+  Collapse store/replay stage.
+* If implementing richer Collapse, define:
+  * context window utilization source,
+  * group selection algorithm,
+  * collapse record schema,
+  * projection replay,
+  * overflow drain behavior,
+  * spawn/subagent gating policy.
+
+## Acceptance Criteria (Future)
+
+* [ ] Collapse can avoid AutoCompact when it reduces pressure below auto threshold.
+* [ ] Collapse record/projection preserves raw transcript.
+* [ ] Prompt-too-long recovery drains staged collapse before reactive compact.
+* [ ] Collapse metadata is visible in recovery/timeline surfaces.
+* [ ] Subagent spawn policy accounts for high context pressure if enabled.
+
+## Out of Scope (Current)
+
+* No implementation in this turn.
+* No claim that 90%/95% thresholds are source-verified from current checkout.
+* No frontend UI work now.
+
+## Status
+
+Research captured / planning-only.
diff --git a/.trellis/tasks/archive/2026-04/04-16-cc-level-3-collapse-alignment/task.json b/.trellis/tasks/archive/2026-04/04-16-cc-level-3-collapse-alignment/task.json
new file mode 100644
index 000000000..335282789
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-cc-level-3-collapse-alignment/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "cc-level-3-collapse-alignment",
+  "name": "cc-level-3-collapse-alignment",
+  "title": "brainstorm: cc level 3 collapse alignment",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-16",
+  "completedAt": "2026-04-16",
+  "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/archive/2026-04/04-16-cc-level-4-autocompact-alignment/prd.md b/.trellis/tasks/archive/2026-04/04-16-cc-level-4-autocompact-alignment/prd.md
new file mode 100644
index 000000000..ce34b7800
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-cc-level-4-autocompact-alignment/prd.md
@@ -0,0 +1,176 @@
+# brainstorm: cc level 4 autocompact alignment
+
+## Goal
+
+评估用户提供的 `Level 4: AutoCompact` 描述是否符合 cc-haha 源码功能，判断当前 `coding-deepgent` 是否对齐，并记录后续可补充的 AutoCompact 亮点。
+
+## Communication Requirement
+
+When discussing context compression levels with the user, explain behavior through
+concrete scenarios first. Avoid listing only mechanism names such as
+`CompactionResult`, hooks, fork, telemetry, or boundary without explaining what
+the user/agent sees and what problem it solves.
+
+Preferred explanation style:
+
+* Start with a realistic long-session coding scenario.
+* Show what happens before compaction.
+* Show what AutoCompact changes in model-facing context.
+* Then map that behavior to implementation terms only after the scenario is
+  clear.
+
+## What I already know
+
+* 当前 `coding-deepgent` 已有 live `AutoCompact`：
+  * `maybe_auto_compact_messages(...)`
+  * `compact_live_messages_with_summary(...)`
+  * `reactive_compact_messages(...)`
+* 当前实现超过阈值后调用 summarizer，生成 boundary + summary + optional restoration paths + preserved recent tail。
+* 当前实现没有 PreCompact/PostCompact hooks、forked compact agent、prompt-cache sharing、partial compact、post-compact attachment restoration、failure circuit breaker 等完整 cc 功能。
+
+## Source Notes
+
+cc-haha source reviewed:
+
+* `/root/claude-code-haha/src/services/compact/autoCompact.ts`
+* `/root/claude-code-haha/src/services/compact/compact.ts`
+* `/root/claude-code-haha/src/commands/compact/compact.ts`
+
+Key source-backed facts:
+
+* `autoCompactIfNeeded(...)` calls `shouldAutoCompact(...)`, then tries `trySessionMemoryCompaction(...)` before legacy `compactConversation(...)`.
+* AutoCompact has recursion guards for `session_memory` and `compact` query sources.
+* AutoCompact is disabled/suppressed when context-collapse mode owns context pressure.
+* AutoCompact has a consecutive failure circuit breaker (`MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3`).
+* Effective context window reserves output tokens for summary.
+* `compactConversation(...)` executes PreCompact hooks, merges hook-provided instructions with user instructions, then streams compact summary.
+* If the compact request itself hits prompt-too-long, it truncates oldest API-round groups and retries up to `MAX_PTL_RETRIES = 3`.
+* `CompactionResult` includes `boundaryMarker`, `summaryMessages`, `attachments`, `hookResults`, optional `messagesToKeep`, user display message, pre/post token counts, true post-compact token count, and compaction usage.
+* `buildPostCompactMessages(...)` establishes output order: boundary marker, summary messages, messagesToKeep, attachments, hookResults.
+* `streamCompactSummary(...)` may use a forked compact agent with `maxTurns: 1`, `canUseTool` denying tool use, `querySource: 'compact'`, `forkLabel: 'compact'`, and `skipCacheWrite: true`, falling back to regular streaming on failure.
+* Post-compact context restoration includes file attachments, async agent attachments, plan attachment, plan mode attachment, skill attachment, deferred tools delta, agent listing delta, MCP instructions delta, and SessionStart hook messages.
+* PostCompact hooks run after compaction and can provide user display messages.
+* Telemetry records pre/post token counts, true post-compact token count, will-retrigger-next-turn, compaction usage, cache read/create tokens, query chain, recompaction information, and context breakdown.
+* Prompt-cache break detection is notified after compaction.
+
+## Evaluation Of User Description
+
+The user description is largely source-aligned:
+
+* AutoCompact is a costly fallback that calls an LLM to summarize.
+* `compactConversation(...)` is the core full compaction path.
+* PreCompact and PostCompact hooks exist.
+* Compact prompt selection/custom instruction merging exists.
+* Summary generation can use forked agent and denies tool use.
+* Prompt-too-long retry truncates oldest API-round groups and retries up to 3 times.
+* `CompactionResult` includes boundary, summary, attachments, hook results, messagesToKeep, token counts.
+* `buildPostCompactMessages(...)` ensures consistent output order.
+
+Useful corrections/clarifications:
+
+* AutoCompact first tries session-memory compaction before legacy full compaction.
+* Context-collapse mode can suppress proactive AutoCompact so Collapse owns the headroom problem, while reactive compact remains available as a fallback.
+* Forked compact agent is an optimization for prompt-cache sharing and has a streaming fallback path.
+* Post-compact attachments are broader than generic “attachments”: they include file restore, async agents, plan, plan mode, skills, tool/agent/MCP deltas, and SessionStart hook messages.
+* Compact summary is not allowed to call tools because `createCompactCanUseTool()` denies all tool use.
+* There is a failure circuit breaker to avoid repeated doomed autocompact attempts.
+
+## Current `coding-deepgent` Alignment
+
+Aligned:
+
+* AutoCompact exists after Snip/MicroCompact/Collapse.
+* It calls a summarizer and produces summary + recent tail.
+* It preserves tool-call/tool-result pairing in preserved tail.
+* It can include restoration paths for compacted-away persisted tool outputs.
+* It fail-opens on proactive summarizer failure.
+* Reactive compact retries once after prompt-too-long.
+* Session memory can assist summary and can be refreshed from generated summary.
+* Manual/generated resume compact records exist separately from raw history.
+
+Not aligned / missing:
+
+* No session-memory-first compact path that replaces full compact when memory is good enough.
+* No PreCompact/PostCompact hook lifecycle.
+* No forked compact agent with one-turn, no-tools execution.
+* No prompt-cache sharing optimization.
+* No compact request prompt-too-long retry that truncates oldest API-round groups up to 3 times.
+* No `CompactionResult` object with full boundary/attachments/hookResults/messagesToKeep/token accounting.
+* No broad post-compact restoration for file attachments, async agents, plan mode, skills, tool/agent/MCP deltas.
+* No failure circuit breaker for repeated AutoCompact failures.
+* No will-retrigger-next-turn / true post-compact token count telemetry.
+* No compact progress/status events.
+* No partial compact path.
+
+## Extra cc AutoCompact Highlights Worth Considering
+
+### 1. Session-Memory-First Compact
+
+Try a session-memory-based compact before full summarization when memory is
+current and enough to continue.
+
+### 2. Failure Circuit Breaker
+
+Track consecutive AutoCompact failures and stop retrying after a small limit.
+
+### 3. Compact Request PTL Retry
+
+If the compact summarizer call itself is too large, drop oldest API-round groups
+and retry up to a bounded count.
+
+### 4. Compact Agent Isolation
+
+Run summary generation through a restricted compact subagent that cannot call
+tools and runs only one turn.
+
+### 5. Post-Compact Context Restoration
+
+Restore file paths, plan/plan-mode state, loaded skills, async agent status, tool
+schema deltas, agent listings, MCP instructions, and session-start hook context
+after summary.
+
+### 6. Structured CompactionResult
+
+Return/record a structured result with boundary, summary messages, kept messages,
+attachments, hook results, token counts, and usage.
+
+### 7. Telemetry / UI Progress
+
+Emit progress and final compaction telemetry for future frontend/timeline and
+debugging.
+
+### 8. AutoCompact Suppression By Collapse
+
+When richer Collapse is enabled, let Collapse own proactive headroom management;
+keep reactive compact as fallback.
+
+## Requirements (Future)
+
+If implementing richer AutoCompact, decide which stage to pursue first:
+
+* minimal failure circuit breaker,
+* compact request PTL retry,
+* structured CompactionResult,
+* post-compact restoration,
+* compact subagent isolation,
+* PreCompact/PostCompact hook lifecycle.
+
+## Acceptance Criteria (Future)
+
+* [ ] AutoCompact repeated failures stop after a bounded count.
+* [ ] Compact summarizer prompt-too-long retries by dropping oldest groups.
+* [ ] Compaction result has stable structured fields.
+* [ ] Post-compact model-facing context preserves required runtime state.
+* [ ] Compact summary generation cannot call tools.
+* [ ] Hooks can add bounded instructions/context around compact.
+* [ ] Runtime pressure/session compact contracts updated.
+
+## Out of Scope (Current)
+
+* No implementation in this turn.
+* No provider-specific prompt-cache sharing unless separately planned.
+* No frontend progress UI now.
+
+## Status
+
+Research captured / planning-only.
diff --git a/.trellis/tasks/archive/2026-04/04-16-cc-level-4-autocompact-alignment/task.json b/.trellis/tasks/archive/2026-04/04-16-cc-level-4-autocompact-alignment/task.json
new file mode 100644
index 000000000..049ffa0d2
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-cc-level-4-autocompact-alignment/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "cc-level-4-autocompact-alignment",
+  "name": "cc-level-4-autocompact-alignment",
+  "title": "brainstorm: cc level 4 autocompact alignment",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-16",
+  "completedAt": "2026-04-16",
+  "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/archive/2026-04/04-16-cc-style-autocompact-hardening/prd.md b/.trellis/tasks/archive/2026-04/04-16-cc-style-autocompact-hardening/prd.md
new file mode 100644
index 000000000..13f73b3ab
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-cc-style-autocompact-hardening/prd.md
@@ -0,0 +1,192 @@
+# cc-style autocompact hardening
+
+## Goal
+
+规划实现更接近 cc Level 4 AutoCompact 的 5 个后续增强点，让当前 `coding-deepgent` 的 AutoCompact 从 MVP summary fallback 升级为更可靠、更可恢复、更可观测的长会话兜底机制。
+
+当前只创建 Trellis planning task，不在本轮实现。
+
+## Communication Requirement
+
+解释或实现本任务时，优先使用具体场景描述功能价值，再映射到术语。
+
+Example style:
+
+* "压缩连续失败时不要一直烧 API" -> failure circuit breaker.
+* "连生成摘要的请求都太长时，先丢最老历史再重试" -> compact PTL retry.
+* "压缩后模型不能忘记 plan/skill/关键文件" -> post-compact restoration.
+
+## Background
+
+当前 `coding-deepgent` 已有 AutoCompact MVP：
+
+* `maybe_auto_compact_messages(...)` 超阈值后调用 summarizer。
+* 生成 live compact boundary + summary + recent tail。
+* 可保留 compacted-away persisted output path。
+* proactive summarizer failure fail-open。
+* prompt-too-long 后有 `reactive_compact_messages(...)` retry。
+* manual/generated resume compact records 独立于 raw history。
+
+cc-haha 完整 AutoCompact 额外包含：
+
+* consecutive failure circuit breaker。
+* compact request prompt-too-long retry by truncating oldest API-round groups。
+* structured `CompactionResult` with boundary, summary, kept messages, attachments, hook results, token counts, usage。
+* post-compact restoration for files, plan, plan mode, skills, async agents, tool/agent/MCP deltas, session-start hooks。
+* PreCompact/PostCompact hook lifecycle。
+
+## Planned Feature Points
+
+### 1. Failure Circuit Breaker
+
+Scenario:
+
+AutoCompact 连续失败，例如 summarizer 一直 prompt-too-long 或 provider 一直报错。系统不应该每一轮都继续尝试压缩，浪费 API 和时间。
+
+Future behavior:
+
+* Track consecutive AutoCompact failures in runtime/session state.
+* Reset failure count on successful compact.
+* Skip proactive AutoCompact after configured max failures.
+* Reactive compact may still surface one bounded failure path if needed.
+
+Acceptance:
+
+* [ ] repeated proactive AutoCompact failures stop after max count.
+* [ ] successful compact resets failure count.
+* [ ] runtime evidence records circuit-breaker skip.
+
+### 2. Compact Request Prompt-Too-Long Retry
+
+Scenario:
+
+历史太长，连“请 summarizer 总结这段历史”的请求本身都超上下文窗口。此时不能直接卡死，需要裁掉最老历史分组后重试摘要。
+
+Future behavior:
+
+* Detect prompt-too-long from compact summarizer call.
+* Drop oldest API-round/message groups from summary source.
+* Retry up to bounded count, e.g. 3.
+* Fail with bounded error if still too long.
+
+Acceptance:
+
+* [ ] compact summarizer PTL retries with older groups removed.
+* [ ] retry count is bounded.
+* [ ] tool-call/tool-result pairing remains valid in remaining source.
+* [ ] failure is surfaced without corrupting session state.
+
+### 3. Structured Compaction Result
+
+Scenario:
+
+After compact, later systems need to know what was generated: boundary, summary, kept tail, restored paths, token counts, and future hook/restoration messages. Ad hoc message lists make this hard to test and extend.
+
+Future behavior:
+
+* Introduce a local `CompactionResult` / `LiveCompactionResult` structure.
+* Fields may include:
+  * boundary message,
+  * summary message,
+  * preserved tail,
+  * restoration messages,
+  * pre/post estimated token counts,
+  * trigger,
+  * metadata.
+* Provide one function to render final model-facing messages in stable order.
+
+Acceptance:
+
+* [ ] AutoCompact uses structured result internally.
+* [ ] final message order is tested.
+* [ ] runtime evidence uses result metadata.
+* [ ] current tests remain behavior-compatible.
+
+### 4. Post-Compact State Restoration
+
+Scenario:
+
+Before compact, the model had important working context: current plan, active todos, loaded skill, recently read file paths, verifier evidence, or running subagent status. After compact, summary alone may omit these, causing the agent to continue incorrectly.
+
+Future behavior:
+
+* Add bounded post-compact restoration contributions.
+* Restore only high-value state:
+  * active todos,
+  * durable plan reference,
+  * verifier evidence summary,
+  * relevant persisted output paths,
+  * loaded skill names/paths if available,
+  * subagent/verifier lineage if relevant.
+* Keep restoration summary-only and bounded.
+
+Acceptance:
+
+* [ ] post-compact context includes active todos/plan when present.
+* [ ] verifier evidence remains visible after compact.
+* [ ] restored persisted paths are not duplicated.
+* [ ] restoration does not dump raw transcript or large payloads.
+
+### 5. PreCompact / PostCompact Hooks
+
+Scenario:
+
+A project or user may need to influence compact behavior. Example: "compact 时特别保留数据库 schema 讨论" or "compact 后重新注入项目约束"。
+
+Future behavior:
+
+* Add local deterministic PreCompact hook contribution.
+* PreCompact may add bounded custom instructions to summarizer.
+* Add local deterministic PostCompact contribution.
+* PostCompact may add bounded model-visible restoration context.
+* Hooks must not call tools or mutate transcript unexpectedly.
+
+Acceptance:
+
+* [ ] PreCompact contribution can add compact instructions.
+* [ ] PostCompact contribution can add bounded restoration context.
+* [ ] invalid/blank hook output is ignored.
+* [ ] hook output is represented in structured compaction result.
+
+## Out of Scope
+
+* No implementation in this turn.
+* No provider-specific prompt-cache sharing or fork cache optimization yet.
+* No frontend progress UI yet.
+* No partial compact unless separately planned.
+* No physical deletion of raw transcript records.
+
+## Technical Notes
+
+Likely files:
+
+* `coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py`
+* `coding-deepgent/src/coding_deepgent/compact/artifacts.py`
+* `coding-deepgent/src/coding_deepgent/sessions/contributions.py`
+* `coding-deepgent/src/coding_deepgent/sessions/contribution_registry.py`
+* `coding-deepgent/src/coding_deepgent/sessions/session_memory.py`
+* `coding-deepgent/src/coding_deepgent/sessions/evidence_events.py`
+* `coding-deepgent/src/coding_deepgent/settings.py`
+* `coding-deepgent/tests/test_runtime_pressure.py`
+* `coding-deepgent/tests/test_compact_artifacts.py`
+* `coding-deepgent/tests/test_session_contributions.py`
+* `.trellis/spec/backend/runtime-pressure-contracts.md`
+* `.trellis/spec/backend/session-compact-contracts.md`
+
+cc references:
+
+* `/root/claude-code-haha/src/services/compact/autoCompact.ts`
+* `/root/claude-code-haha/src/services/compact/compact.ts`
+* `/root/claude-code-haha/src/commands/compact/compact.ts`
+
+## Suggested Stage Order
+
+1. Failure circuit breaker.
+2. Compact request PTL retry.
+3. Structured compaction result.
+4. Post-compact state restoration.
+5. PreCompact/PostCompact hooks.
+
+## Status
+
+Planning-only placeholder. Ready for future staged implementation.
diff --git a/.trellis/tasks/archive/2026-04/04-16-cc-style-autocompact-hardening/task.json b/.trellis/tasks/archive/2026-04/04-16-cc-style-autocompact-hardening/task.json
new file mode 100644
index 000000000..3f169dd53
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-cc-style-autocompact-hardening/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "cc-style-autocompact-hardening",
+  "name": "cc-style-autocompact-hardening",
+  "title": "cc-style autocompact hardening",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-16",
+  "completedAt": "2026-04-17",
+  "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-16-context-compression-staged-implementation-plan",
+  "relatedFiles": [],
+  "notes": "All 5 feature points shipped under Stage 2 checkpoint of parent plan: failure circuit breaker, compact PTL retry, structured compaction result, post-compact restoration (active-todo slice), pre/post-compact hooks. See parent prd.md Stage 2 APPROVE checkpoint.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-16-cc-style-collapse-store-pressure-guard/check.jsonl b/.trellis/tasks/archive/2026-04/04-16-cc-style-collapse-store-pressure-guard/check.jsonl
new file mode 100644
index 000000000..026213b41
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-cc-style-collapse-store-pressure-guard/check.jsonl
@@ -0,0 +1,4 @@
+{"file": ".cursor/commands/trellis-finish-work.md", "reason": "Finish work checklist"}
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
+{"file": ".trellis/spec/backend/runtime-pressure-contracts.md", "reason": "Review live collapse persistence and runtime projection sidecar alignment."}
+{"file": ".trellis/spec/backend/session-compact-contracts.md", "reason": "Review collapse transcript-event loading and raw history separation."}
diff --git a/.trellis/tasks/archive/2026-04/04-16-cc-style-collapse-store-pressure-guard/debug.jsonl b/.trellis/tasks/archive/2026-04/04-16-cc-style-collapse-store-pressure-guard/debug.jsonl
new file mode 100644
index 000000000..e30f96d49
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-cc-style-collapse-store-pressure-guard/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-16-cc-style-collapse-store-pressure-guard/implement.jsonl b/.trellis/tasks/archive/2026-04/04-16-cc-style-collapse-store-pressure-guard/implement.jsonl
new file mode 100644
index 000000000..badff645b
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-cc-style-collapse-store-pressure-guard/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/spec/backend/runtime-pressure-contracts.md", "reason": "Owns live collapse middleware behavior, runtime evidence, and new persistence boundary for collapse records."}
+{"file": ".trellis/spec/backend/session-compact-contracts.md", "reason": "Owns append-only transcript event ledger and loaded session transcript event surfaces used by collapse records."}
diff --git a/.trellis/tasks/archive/2026-04/04-16-cc-style-collapse-store-pressure-guard/prd.md b/.trellis/tasks/archive/2026-04/04-16-cc-style-collapse-store-pressure-guard/prd.md
new file mode 100644
index 000000000..42575ed28
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-cc-style-collapse-store-pressure-guard/prd.md
@@ -0,0 +1,170 @@
+# cc-style collapse store and pressure guard
+
+## Goal
+
+规划实现更接近 cc Level 3 Collapse 的上下文重构系统：从当前一次性 live collapse，升级为可记录、可重放、可观测、能参与 spawn/subagent 压力控制和 overflow recovery 的 collapse subsystem。
+
+当前只创建 Trellis planning task，不在本轮实现。
+
+## Background
+
+当前 `coding-deepgent` 已有 MVP Collapse：
+
+* `maybe_collapse_messages(...)` 在 `RuntimePressureMiddleware.wrap_model_call()` 中运行。
+* Collapse 在 `MicroCompact` 后、`AutoCompact` 前。
+* 使用 summarizer 生成 live summary，保留 recent tail。
+* 失败时 fail-open。
+* 不物理删除 transcript。
+
+cc-haha 可见源码显示更完整的 Collapse 设计：
+
+* Collapse 是 read-time projection over raw history。
+* Summary messages live in a collapse store, not the REPL array。
+* `projectView()` replays commit log across turns。
+* Collapse runs before AutoCompact to preserve granular context and avoid full summary when possible。
+* prompt-too-long recovery tries collapse drain before reactive compact。
+* 用户提到的 90% commit / 95% spawn block 属于目标行为，但当前 checkout 中具体实现文件不可见，需实现前再次 source-verify 或作为本地产品决策。
+
+## Planned Feature Points
+
+### 1. Collapse Records
+
+Record durable collapse artifacts without deleting raw transcript.
+
+Required future behavior:
+
+* Add a collapse record type or structured evidence/state entry.
+* Record affected message IDs/ranges.
+* Record summary text.
+* Record trigger reason and estimated pressure.
+* Record created timestamp and model/context source.
+
+Example shape:
+
+```json
+{
+  "record_type": "collapse",
+  "collapse_id": "collapse-001",
+  "covered_message_ids": ["msg-001", "msg-002"],
+  "summary": "Research phase summary...",
+  "trigger": "pressure_ratio",
+  "estimated_token_ratio": 0.91
+}
+```
+
+### 2. Projection Replay
+
+Derive model-facing context from raw history plus collapse records.
+
+Required future behavior:
+
+* Raw transcript remains complete.
+* Model-facing projection replaces covered message ranges with collapse summaries.
+* Replay is deterministic across session resume.
+* Projection metadata explains which raw messages were hidden by which collapse.
+
+### 3. Pressure Ratio Trigger
+
+Trigger collapse based on estimated utilization of model context window.
+
+Required future behavior:
+
+* Compute `estimated_tokens / model_context_window`.
+* Trigger staged collapse around configurable threshold, e.g. `collapse_commit_ratio`.
+* Prefer ratio-based pressure when reliable model context window is available.
+* Keep fallback token threshold for providers without reliable limits.
+
+### 4. Spawn Guard
+
+Prevent or warn on subagent/fork spawn when context pressure is too high.
+
+Required future behavior:
+
+* Before `run_subagent` or verifier-like child execution, check pressure ratio.
+* If above configured threshold, return a bounded warning/error or require collapse first.
+* Avoid blocking lightweight verifier paths unless explicitly configured.
+* Record guard event in runtime evidence.
+
+### 5. Overflow Drain
+
+When prompt-too-long occurs, drain existing collapse summaries before full reactive compact.
+
+Required future behavior:
+
+* Detect prompt-too-long after proactive collapse.
+* If collapse records exist, produce a more compact projection by tightening/draining collapse summaries.
+* Retry once with drained collapse projection.
+* If still too long, fall through to existing reactive compact.
+
+## Acceptance Criteria
+
+* [x] Collapse records persist separately from raw messages.
+* [x] Loading a session can derive raw history and collapse-projected history separately.
+* [x] Collapse replay is deterministic and tested across resume.
+* [x] Pressure ratio trigger can fire before AutoCompact.
+* [x] Collapse can avoid AutoCompact when it reduces pressure below threshold.
+* [x] Spawn guard blocks or warns according to configured pressure threshold.
+* [x] Prompt-too-long path drains collapse projection before reactive compact.
+* [ ] Frontend/timeline surfaces can explain collapse events and affected messages.
+* [x] Existing compact/session/runtime pressure tests continue to pass.
+
+## Out of Scope
+
+* No frontend UI work in this task.
+* No physical deletion of raw transcript records.
+* No claim that exact cc 90%/95% constants are source-verified in this checkout.
+* No provider-specific exact tokenizer requirement unless separately planned.
+
+## Technical Notes
+
+Likely backend surfaces:
+
+* `coding-deepgent/src/coding_deepgent/sessions/records.py`
+* `coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py`
+* `coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py`
+* `coding-deepgent/src/coding_deepgent/subagents/tools.py`
+* `coding-deepgent/src/coding_deepgent/settings.py`
+* `coding-deepgent/tests/test_sessions.py`
+* `coding-deepgent/tests/test_runtime_pressure.py`
+* `coding-deepgent/tests/test_subagents.py`
+* `.trellis/spec/backend/runtime-pressure-contracts.md`
+* `.trellis/spec/backend/session-compact-contracts.md`
+
+Source references:
+
+* `/root/claude-code-haha/src/query.ts`
+  * `contextCollapse.applyCollapsesIfNeeded(...)`
+  * comments around read-time projection, collapse store, commit log replay
+  * prompt-too-long recovery with `recoverFromOverflow(...)`
+
+## Status
+
+Backend mainline implemented. Frontend/timeline explanation remains in
+`04-16-context-compression-visualization-readiness`.
+
+## Implementation Checkpoint
+
+State: terminal
+
+Verdict: APPROVE
+
+Implemented:
+
+* Collapse records as `transcript_event` payloads in the append-only session ledger.
+* `LoadedSession.collapses`, `SessionSummary.collapse_count`, and
+  `LoadedSession.collapsed_history`.
+* Deterministic collapse replay from raw `SessionMessage` history plus stable
+  message references.
+* Selected continuation prefers valid collapse projection over compact
+  projection without stacking summaries.
+* Ratio-triggered collapse via configured `model_context_window_tokens` and
+  `collapse_trigger_ratio`, with token-threshold fallback preserved.
+* Prompt-too-long overflow drain before reactive compact.
+* Subagent spawn pressure guard with bounded runtime event/evidence.
+
+Verification:
+
+* `pytest -q coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_runtime_pressure.py coding-deepgent/tests/test_cli.py coding-deepgent/tests/test_subagents.py coding-deepgent/tests/test_app.py` -> 116 passed
+* `ruff check coding-deepgent/src/coding_deepgent coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_runtime_pressure.py coding-deepgent/tests/test_cli.py coding-deepgent/tests/test_subagents.py coding-deepgent/tests/test_app.py` -> passed
+* `mypy coding-deepgent/src/coding_deepgent` -> passed
+* `pytest -q coding-deepgent/tests` -> 292 passed
diff --git a/.trellis/tasks/archive/2026-04/04-16-cc-style-collapse-store-pressure-guard/task.json b/.trellis/tasks/archive/2026-04/04-16-cc-style-collapse-store-pressure-guard/task.json
new file mode 100644
index 000000000..dd143407f
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-cc-style-collapse-store-pressure-guard/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "cc-style-collapse-store-pressure-guard",
+  "name": "cc-style-collapse-store-pressure-guard",
+  "title": "cc-style collapse store and pressure guard",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-16",
+  "completedAt": "2026-04-17",
+  "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-16-context-compression-staged-implementation-plan",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-16-cc-style-time-based-local-microcompact/check.jsonl b/.trellis/tasks/archive/2026-04/04-16-cc-style-time-based-local-microcompact/check.jsonl
new file mode 100644
index 000000000..5ab4b06b3
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-cc-style-time-based-local-microcompact/check.jsonl
@@ -0,0 +1,6 @@
+{"file": ".cursor/commands/trellis-finish-work.md", "reason": "Finish work checklist"}
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
+{"file": ".trellis/tasks/04-16-cc-style-time-based-local-microcompact/prd.md", "reason": "time-based microcompact acceptance criteria"}
+{"file": ".trellis/tasks/04-16-runtime-pressure-token-saved-evidence/prd.md", "reason": "previous checkpoint verification evidence"}
+{"file": ".trellis/spec/backend/runtime-pressure-contracts.md", "reason": "runtime pressure contract checks"}
+{"file": "coding-deepgent/tests/test_runtime_pressure.py", "reason": "focused runtime pressure tests"}
diff --git a/.trellis/tasks/archive/2026-04/04-16-cc-style-time-based-local-microcompact/debug.jsonl b/.trellis/tasks/archive/2026-04/04-16-cc-style-time-based-local-microcompact/debug.jsonl
new file mode 100644
index 000000000..e30f96d49
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-cc-style-time-based-local-microcompact/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-16-cc-style-time-based-local-microcompact/implement.jsonl b/.trellis/tasks/archive/2026-04/04-16-cc-style-time-based-local-microcompact/implement.jsonl
new file mode 100644
index 000000000..4ad591074
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-cc-style-time-based-local-microcompact/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": ".trellis/tasks/04-16-cc-style-time-based-local-microcompact/prd.md", "reason": "time-based microcompact requirements"}
+{"file": ".trellis/tasks/04-16-runtime-pressure-token-saved-evidence/prd.md", "reason": "previous checkpoint stats contract"}
+{"file": ".trellis/spec/backend/runtime-pressure-contracts.md", "reason": "runtime pressure contract"}
+{"file": "coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py", "reason": "implementation seam"}
diff --git a/.trellis/tasks/archive/2026-04/04-16-cc-style-time-based-local-microcompact/prd.md b/.trellis/tasks/archive/2026-04/04-16-cc-style-time-based-local-microcompact/prd.md
new file mode 100644
index 000000000..725a13d11
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-cc-style-time-based-local-microcompact/prd.md
@@ -0,0 +1,196 @@
+# cc-style time-based local microcompact
+
+## Goal
+
+实现 cc Level 2 MicroCompact 的非 API 本地亮点：在主会话自然暂停后，基于时间阈值主动清理旧的基础工具输出，保留最近工具结果和可恢复路径，并记录触发原因与节省 token。明确不做 provider `cache_edits` / `cache_reference` / cache editing API。
+
+## Background
+
+当前 `coding-deepgent` 已有基础 `MicroCompact`：
+
+* `RuntimePressureMiddleware.wrap_model_call()` 调用 `microcompact_messages(...)`。
+* 旧 eligible successful `ToolMessage` 会替换为 `[Old tool result content cleared]`。
+* 保留最近 `keep_recent_tool_results` 个可压缩工具结果。
+* 如果 tool result artifact 有 persisted output path，会保留路径提示。
+* 该 rewrite 是 live model-call projection，不物理修改 transcript。
+
+cc-haha `microCompact.ts` 的非 API 亮点：
+
+* time-based trigger：距最后 assistant message 超过阈值时触发。
+* main-thread/source gating：只在主线程明确 source 下触发。
+* keepRecent floor：至少保留 1 个最近可压缩工具结果。
+* compactable tool allowlist：只清基础执行工具。
+* token saved accounting：记录清理收益。
+* event/cache coordination：记录这是有意的 pressure action，未来可避免误判 cache drop。
+
+## Requirements
+
+### 1. Time-Based Trigger
+
+* Add settings-backed time gap threshold, e.g. `microcompact_time_gap_minutes: int | None`.
+* Time-based path only runs when enabled.
+* Trigger computes gap from the latest assistant message timestamp/metadata available in the current model-call messages or runtime/session context.
+* If no reliable assistant timestamp exists, fail open and skip time-based path.
+
+### 2. Main-Thread Gating
+
+* Time-based aggressive MicroCompact must only run for the main agent/session path.
+* It must not run for verifier, subagent, compact summarizer, session-memory updater, or analysis-only contexts.
+* Use `RuntimeContext` fields such as `agent_name`, `entrypoint`, `session_id`, or an explicit setting/flag rather than copying cc's `querySource` string model blindly.
+
+### 3. Token Saved Accounting
+
+* Estimate tokens saved for cleared tool results using deterministic local estimation.
+* Runtime event/evidence metadata should include bounded fields:
+  * `trigger == "time_gap"`
+  * `gap_minutes`
+  * `tools_cleared`
+  * `tools_kept`
+  * `tokens_saved_estimate`
+  * `keep_recent`
+
+### 4. Minimum Savings Threshold
+
+* Add settings-backed threshold, e.g. `microcompact_min_saved_tokens`.
+* If estimated savings are below threshold, skip clearing.
+* This prevents noisy low-value microcompact events.
+
+### 5. KeepRecent Floor
+
+* Existing normal `keep_recent_tool_results` may continue to allow `0` for tests/manual behavior.
+* Time-based/aggressive mode must use `max(1, configured_keep_recent)` to avoid clearing all working tool context.
+
+### 6. Protected Tools / Allowlist Audit
+
+* Keep using `ToolCapability.microcompact_eligible`.
+* Audit default registry against cc's base execution-tool intent:
+  * eligible: read/search/shell/web-fetch-like raw material tools
+  * not eligible: memory, task, plan, skill, verifier/subagent semantic tools
+* Document this distinction in runtime pressure contract.
+
+## Acceptance Criteria
+
+* [ ] Time-based MicroCompact does nothing when disabled.
+* [ ] Time-based MicroCompact does nothing for non-main agent contexts.
+* [ ] Time-based MicroCompact does nothing without a reliable assistant timestamp.
+* [ ] Under threshold gap does not clear tool results.
+* [ ] Over threshold gap clears older eligible tool results.
+* [ ] Aggressive keepRecent floors to at least 1.
+* [ ] Minimum savings threshold prevents low-value clears.
+* [ ] Runtime event/evidence includes trigger, gap, cleared/kept counts, token savings estimate.
+* [ ] Persisted output paths remain model-visible after clearing.
+* [ ] Existing full `coding-deepgent/tests` pass.
+* [ ] `ruff check` and targeted `mypy` pass.
+* [ ] `.trellis/spec/backend/runtime-pressure-contracts.md` updated with executable contract.
+
+## Out of Scope
+
+* No `cache_edits`.
+* No `cache_reference`.
+* No `cache_deleted_input_tokens`.
+* No provider-specific cache editing payloads.
+* No physical deletion of transcript records.
+* No cc-style semantic SnipTool.
+
+## Technical Approach
+
+Likely implementation shape:
+
+* Add a time-based helper near `microcompact_messages(...)`:
+  * `maybe_time_based_microcompact_messages(...)`
+  * returns messages plus stats or `None`.
+* Keep the current count-based `microcompact_messages(...)` as fallback/default behavior.
+* In `RuntimePressureMiddleware.wrap_model_call()`:
+  1. Snip
+  2. Time-based MicroCompact if eligible
+  3. Otherwise existing MicroCompact
+  4. Collapse
+  5. AutoCompact
+* Use runtime context to gate main-agent eligibility.
+* Extend runtime pressure event/evidence metadata with bounded token-saved fields.
+
+## Technical Notes
+
+Candidate files:
+
+* `coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py`
+* `coding-deepgent/src/coding_deepgent/settings.py`
+* `coding-deepgent/src/coding_deepgent/containers/app.py`
+* `coding-deepgent/src/coding_deepgent/sessions/evidence_events.py`
+* `coding-deepgent/tests/test_runtime_pressure.py`
+* `coding-deepgent/tests/test_app.py`
+* `.trellis/spec/backend/runtime-pressure-contracts.md`
+
+Source references:
+
+* `/root/claude-code-haha/src/services/compact/microCompact.ts`
+* `/root/claude-code-haha/src/services/compact/timeBasedMCConfig.ts`
+* `/root/claude-code-haha/src/query.ts`
+
+## Status
+
+Checkpoint complete.
+
+State: checkpoint
+
+Verdict: APPROVE
+
+Implemented:
+
+* Added settings-backed `microcompact_time_gap_minutes` and
+  `microcompact_min_saved_tokens`.
+* Added main-context gating through configured `main_entrypoint` /
+  `main_agent_name` wired from existing settings.
+* Added timestamp-based trigger evaluation from `AIMessage` metadata.
+* Added aggressive keepRecent floor for time-gap clears.
+* Added minimum-savings skip behavior that prevents fallback count-based
+  clearing in the same call once the time-gap trigger has fired.
+* Added bounded `trigger == "time_gap"` and `gap_minutes` metadata.
+* Preserved raw transcript and existing persisted-output path behavior.
+
+Verification:
+
+* `pytest -q tests/test_runtime_pressure.py` -> 26 passed.
+* `pytest -q tests/test_app.py` -> 9 passed.
+* `ruff check src/coding_deepgent/compact/runtime_pressure.py src/coding_deepgent/compact/__init__.py src/coding_deepgent/sessions/evidence_events.py src/coding_deepgent/settings.py src/coding_deepgent/containers/app.py tests/test_runtime_pressure.py tests/test_app.py` -> passed.
+* `mypy src/coding_deepgent/compact/runtime_pressure.py src/coding_deepgent/sessions/evidence_events.py src/coding_deepgent/settings.py src/coding_deepgent/containers/app.py` -> passed.
+
+Alignment:
+
+* source files inspected:
+  * `/root/claude-code-haha/src/services/compact/microCompact.ts`
+  * `/root/claude-code-haha/src/services/compact/timeBasedMCConfig.ts`
+  * `/root/claude-code-haha/src/query.ts`
+* aligned:
+  * time-gap trigger based on latest assistant timestamp
+  * explicit main-thread gating
+  * keepRecent floor
+  * local token-saved accounting
+* deferred:
+  * provider `cache_edits`
+  * `cache_reference`
+  * cache-deletion API coordination
+* do-not-copy:
+  * GrowthBook config plumbing
+  * provider-specific cache APIs
+
+Architecture:
+
+* primitive used: existing LangChain middleware-level model-call projection.
+* why no heavier abstraction: the behavior is a deterministic pre-model-call
+  projection over the existing MicroCompact helper.
+
+Boundary findings:
+
+* No session schema migration needed.
+* No raw transcript mutation introduced.
+* Normal count-based MicroCompact remains available when time-gap trigger does
+  not fire.
+
+Decision: continue
+
+Reason:
+
+* This sub-stage is complete and verified.
+* The next parent-plan task still holds because normal MicroCompact remains
+  count-based rather than token-budget protected.
diff --git a/.trellis/tasks/archive/2026-04/04-16-cc-style-time-based-local-microcompact/task.json b/.trellis/tasks/archive/2026-04/04-16-cc-style-time-based-local-microcompact/task.json
new file mode 100644
index 000000000..9a5179225
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-cc-style-time-based-local-microcompact/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "cc-style-time-based-local-microcompact",
+  "name": "cc-style-time-based-local-microcompact",
+  "title": "cc-style time-based local microcompact",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-16",
+  "completedAt": "2026-04-16",
+  "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-16-context-compression-staged-implementation-plan",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-16-compact-request-ptl-retry/check.jsonl b/.trellis/tasks/archive/2026-04/04-16-compact-request-ptl-retry/check.jsonl
new file mode 100644
index 000000000..d4c2e661a
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-compact-request-ptl-retry/check.jsonl
@@ -0,0 +1,6 @@
+{"file": ".cursor/commands/trellis-finish-work.md", "reason": "Finish work checklist"}
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
+{"file": ".trellis/tasks/04-16-compact-request-ptl-retry/prd.md", "reason": "active PTL retry acceptance criteria"}
+{"file": ".trellis/tasks/04-16-cc-style-autocompact-hardening/prd.md", "reason": "source hardening checks"}
+{"file": ".trellis/spec/backend/runtime-pressure-contracts.md", "reason": "runtime pressure contract checks"}
+{"file": "coding-deepgent/tests/test_runtime_pressure.py", "reason": "focused tests"}
diff --git a/.trellis/tasks/archive/2026-04/04-16-compact-request-ptl-retry/debug.jsonl b/.trellis/tasks/archive/2026-04/04-16-compact-request-ptl-retry/debug.jsonl
new file mode 100644
index 000000000..e30f96d49
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-compact-request-ptl-retry/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-16-compact-request-ptl-retry/implement.jsonl b/.trellis/tasks/archive/2026-04/04-16-compact-request-ptl-retry/implement.jsonl
new file mode 100644
index 000000000..f9f096c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-compact-request-ptl-retry/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": ".trellis/tasks/04-16-compact-request-ptl-retry/prd.md", "reason": "active PTL retry PRD"}
+{"file": ".trellis/tasks/04-16-cc-style-autocompact-hardening/prd.md", "reason": "source autocompact hardening PRD"}
+{"file": ".trellis/spec/backend/runtime-pressure-contracts.md", "reason": "runtime pressure contract"}
+{"file": "coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py", "reason": "autocompact implementation seam"}
diff --git a/.trellis/tasks/archive/2026-04/04-16-compact-request-ptl-retry/prd.md b/.trellis/tasks/archive/2026-04/04-16-compact-request-ptl-retry/prd.md
new file mode 100644
index 000000000..305f1bc5d
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-compact-request-ptl-retry/prd.md
@@ -0,0 +1,106 @@
+# compact request ptl retry
+
+## Goal
+
+当 proactive AutoCompact 的 summarizer 请求本身 prompt-too-long 时，裁掉最老的 summary source 消息后 bounded retry，而不是立即放弃。该行为只影响 summarizer source，不修改 raw transcript，也不改变 reactive model-call retry 语义。
+
+## Expected Effect
+
+超长历史下，AutoCompact 更有机会成功生成 summary。即使 compact request 太长，也最多重试有限次数，失败后继续 fail-open，不破坏主模型调用。
+
+## Requirements
+
+- Add settings-backed `auto_compact_ptl_retry_limit: int`.
+- Detect prompt-too-long style errors from the compact summarizer call.
+- On each retry, drop the oldest message group from the summarizer source.
+- Retry count must be bounded.
+- Preserve tool-call/tool-result pairing in the remaining summary source as much as possible.
+- If retries still fail, return original model-facing messages and count as proactive AutoCompact failure for the circuit breaker.
+- Do not change `reactive_compact_messages(...)` retry semantics.
+
+## Acceptance Criteria
+
+- [ ] Prompt-too-long from proactive compact summarizer retries with older source removed.
+- [ ] Retry count is bounded by setting.
+- [ ] Non prompt-too-long summarizer failures still fail open without retry loop.
+- [ ] Successful retry produces normal live compact output.
+- [ ] Exhausted retries fail open and can increment circuit breaker count.
+- [ ] Runtime pressure contract updated.
+- [ ] Focused tests, ruff, and targeted mypy pass.
+
+## Source Evidence
+
+- `/root/claude-code-haha/src/services/compact/compact.ts`
+- `/root/claude-code-haha/src/services/compact/autoCompact.ts`
+- Source PRD: `.trellis/tasks/04-16-cc-style-autocompact-hardening/prd.md`
+
+## Out of Scope
+
+- No structured compaction result yet.
+- No post-compact restoration contributions.
+- No PreCompact/PostCompact hooks.
+- No provider-specific cache sharing.
+
+## Status
+
+Checkpoint complete.
+
+State: checkpoint
+
+Verdict: APPROVE
+
+Implemented:
+
+- Added settings-backed `auto_compact_ptl_retry_limit`.
+- Added bounded prompt-too-long retry inside proactive AutoCompact summary
+  generation.
+- Dropped the oldest summary-source message group per retry while preserving the
+  original model-facing messages for final live compact projection.
+- Kept non prompt-too-long summarizer failures on the existing fail-open path
+  without retry.
+- Exhausted PTL retries fail open and can increment the circuit breaker count.
+- Updated runtime pressure contracts.
+
+Verification:
+
+- `pytest -q tests/test_runtime_pressure.py` -> 35 passed.
+- `pytest -q tests/test_app.py` -> 9 passed.
+- `ruff check src/coding_deepgent/compact/runtime_pressure.py src/coding_deepgent/compact/__init__.py src/coding_deepgent/sessions/evidence_events.py src/coding_deepgent/settings.py src/coding_deepgent/containers/app.py tests/test_runtime_pressure.py tests/test_app.py` -> passed.
+- `mypy src/coding_deepgent/compact/runtime_pressure.py src/coding_deepgent/sessions/evidence_events.py src/coding_deepgent/settings.py src/coding_deepgent/containers/app.py` -> passed.
+
+Alignment:
+
+- source files inspected:
+  - `/root/claude-code-haha/src/services/compact/compact.ts`
+  - `/root/claude-code-haha/src/services/compact/autoCompact.ts`
+- aligned:
+  - compact request prompt-too-long retry
+  - bounded retry count
+  - fail-open on exhaustion
+- deferred:
+  - richer API-round grouping
+  - structured compaction result
+  - hooks/restoration
+- do-not-copy:
+  - UI progress events
+  - provider cache-sharing implementation
+
+Architecture:
+
+- primitive used: existing compact summarizer seam and middleware fail-open path.
+- why no heavier abstraction: this stage only changes the summary source retry
+  loop, not the runtime projection shape.
+
+Boundary findings:
+
+- Reactive compact retry remains unchanged.
+- Raw transcript remains untouched.
+- Circuit breaker integration works through existing AutoCompact status result.
+
+Decision: continue
+
+Reason:
+
+- The sub-stage is complete and verified.
+- Parent plan next stage remains valid: structured result can now consolidate
+  AutoCompact output metadata and ordering.
diff --git a/.trellis/tasks/archive/2026-04/04-16-compact-request-ptl-retry/task.json b/.trellis/tasks/archive/2026-04/04-16-compact-request-ptl-retry/task.json
new file mode 100644
index 000000000..d7e6c2da7
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-compact-request-ptl-retry/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "compact-request-ptl-retry",
+  "name": "compact-request-ptl-retry",
+  "title": "compact request ptl retry",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-16",
+  "completedAt": "2026-04-16",
+  "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-16-context-compression-staged-implementation-plan",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-16-context-compression-staged-implementation-plan/prd.md b/.trellis/tasks/archive/2026-04/04-16-context-compression-staged-implementation-plan/prd.md
new file mode 100644
index 000000000..80a34b4b1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-context-compression-staged-implementation-plan/prd.md
@@ -0,0 +1,304 @@
+# context compression staged implementation plan
+
+## Goal
+
+作为 4 个上下文压缩后续计划的父任务，统一拆解、排序、并发策略和交付边界。该父任务不直接实现代码；它负责协调子任务，避免 MicroCompact / Collapse / AutoCompact / tool-output pruning 之间的重复、冲突和顺序错误。
+
+## Child Tasks
+
+* `04-15-opencode-style-auto-tool-output-prune`
+* `04-16-cc-style-time-based-local-microcompact`
+* `04-16-cc-style-collapse-store-pressure-guard`
+* `04-16-cc-style-autocompact-hardening`
+
+Frontend/visualization planning remains separate:
+
+* `04-16-context-compression-visualization-readiness`
+
+## Why A Parent Plan Is Needed
+
+这 4 个计划共享同一套 runtime pressure/session context surfaces：
+
+* `compact.runtime_pressure`
+* `sessions` evidence / records
+* settings / container wiring
+* runtime pressure contracts
+* future model-facing projection metadata
+
+如果不排序，容易出现：
+
+* MicroCompact 和 opencode-style prune 重复清同一批 tool result。
+* Collapse 和 AutoCompact 都抢着摘要同一段历史。
+* AutoCompact restoration 依赖的 structured result 还没建立。
+* Spawn guard 依赖 pressure ratio，但 pressure estimation 还没统一。
+
+## Decomposition Principles
+
+* Keep implementation tasks small enough to complete with focused tests.
+* Prefer one reusable contract per child implementation task.
+* If a task touches session record schema, runtime pressure ordering, and subagent behavior at once, split it.
+* Treat source-backed research PRDs as reference, not implementation tasks.
+* Keep provider-specific cache editing out of this parent plan.
+
+## Proposed Execution Order
+
+### Stage 1: Tool Output Pruning Foundation
+
+Source tasks:
+
+* `04-15-opencode-style-auto-tool-output-prune`
+* `04-16-cc-style-time-based-local-microcompact`
+
+Recommended small tasks:
+
+1. `runtime-pressure-token-saved-evidence`
+   * Add bounded `tokens_saved_estimate`, `tools_cleared`, `tools_kept` fields to runtime pressure event/evidence.
+   * Reason: both opencode-style prune and time-based MicroCompact need this observability.
+
+2. `time-based-local-microcompact`
+   * Add idle-gap trigger, main-agent gating, keepRecent floor, min savings threshold.
+   * Reason: cc Level 2 non-API value, independent from Collapse/AutoCompact.
+
+3. `token-budget-tool-output-prune`
+   * Upgrade count-based keep policy to token-budget protected recent tool outputs if still needed after Stage 1.2.
+   * Reason: opencode-style enhancement may overlap with time-based mode; implement only if the simpler mode is insufficient.
+
+Parallelism:
+
+* `runtime-pressure-token-saved-evidence` can be done first and unblocks both.
+* `time-based-local-microcompact` and `token-budget-tool-output-prune` should not be implemented in parallel unless their write sets are separated, because both touch `microcompact_messages` semantics.
+
+### Stage 2: AutoCompact Reliability Backbone
+
+Source task:
+
+* `04-16-cc-style-autocompact-hardening`
+
+Recommended small tasks:
+
+1. `autocompact-failure-circuit-breaker`
+   * Stop repeated doomed proactive AutoCompact attempts after bounded failures.
+   * Low coupling and useful immediately.
+
+2. `compact-request-ptl-retry`
+   * If summarizer prompt is too long, drop oldest groups and retry.
+   * Depends on clear grouping/tail-pair invariants.
+
+3. `structured-compaction-result`
+   * Introduce local structured result and stable render order.
+   * Should happen before restoration/hooks.
+
+4. `post-compact-restoration-contributions`
+   * Restore active todos, plan/verifier evidence, skill/file refs, bounded paths.
+   * Depends on structured result.
+
+5. `pre-post-compact-hooks`
+   * Add PreCompact/PostCompact contribution seams.
+   * Depends on structured result and restoration boundaries.
+
+Parallelism:
+
+* `autocompact-failure-circuit-breaker` can run in parallel with Stage 1 after current branch is clean.
+* `structured-compaction-result` must precede restoration/hooks.
+* `compact-request-ptl-retry` can run before or after structured result if kept local, but should not overlap with AutoCompact render-order changes.
+
+### Stage 3: Collapse Store And Projection
+
+Source task:
+
+* `04-16-cc-style-collapse-store-pressure-guard`
+
+Recommended small tasks:
+
+1. `collapse-records`
+   * Add durable collapse records without applying replay yet.
+
+2. `collapse-projection-replay`
+   * Derive model-facing collapsed view from raw history + collapse records.
+   * Depends on stable message IDs or at least stable message indexes.
+
+3. `pressure-ratio-trigger`
+   * Use estimated tokens / model context window when available.
+   * Can be shared with spawn guard.
+
+4. `collapse-overflow-drain`
+   * On prompt-too-long, drain collapse summaries before reactive compact.
+   * Depends on records + replay.
+
+5. `spawn-pressure-guard`
+   * Warn/block subagent spawn at high pressure.
+   * Depends on pressure ratio and subagent context boundaries.
+
+Parallelism:
+
+* `pressure-ratio-trigger` can be developed in parallel with `collapse-records` if write sets are separated.
+* `collapse-projection-replay` must wait for collapse records.
+* `collapse-overflow-drain` must wait for projection replay.
+* `spawn-pressure-guard` can wait until pressure ratio exists and should be isolated in `subagents`.
+
+## Cross-Stage Dependencies
+
+* `structured-compaction-result` helps AutoCompact restoration and future UI.
+* `pressure-ratio-trigger` helps Collapse and spawn guard.
+* `runtime-pressure-token-saved-evidence` helps future visualization.
+* Stable message IDs are likely required before full `collapse-projection-replay` and cc-style Snip; if missing, create a separate foundational task before Stage 3.2.
+
+## Parallel Work Plan
+
+Safe parallel groups if using separate worktrees/agents:
+
+* Group A: `runtime-pressure-token-saved-evidence`
+* Group B: `autocompact-failure-circuit-breaker`
+* Group C: `pressure-ratio-trigger`
+
+Do not run in parallel initially:
+
+* `time-based-local-microcompact` and `token-budget-tool-output-prune` because both change tool-output clearing semantics.
+* `structured-compaction-result` and `post-compact-restoration-contributions` because restoration depends on result shape.
+* `collapse-records` and `collapse-projection-replay` unless record schema is frozen first.
+
+## Recommended Immediate Next Task
+
+Start with:
+
+```text
+runtime-pressure-token-saved-evidence
+```
+
+Why:
+
+* Small and low-risk.
+* Improves current MicroCompact observability.
+* Unblocks time-based MicroCompact and frontend compression timeline.
+* Does not require session schema changes.
+
+## Out of Scope
+
+* No implementation in this parent task.
+* No provider-specific cached microcompact API.
+* No frontend UI implementation.
+* No cc-style semantic SnipTool in this parent plan.
+
+## Acceptance Criteria
+
+* [x] Parent task exists.
+* [x] 4 compression child tasks are linked.
+* [x] Dependencies are documented.
+* [x] Safe parallel groups are documented.
+* [x] Recommended immediate next task is identified.
+
+## Status
+
+Planning-only parent task.
+
+## Checkpoint: Stage 1 Tool Output Pruning Foundation
+
+State: checkpoint
+
+Verdict: APPROVE
+
+Implemented:
+
+* `runtime-pressure-token-saved-evidence`
+* `time-based-local-microcompact`
+* `token-budget-tool-output-prune`
+
+Verification:
+
+* Focused runtime pressure/app/static checks passed at each sub-stage.
+* Final full `coding-deepgent` suite after Stage 2: `pytest -q` -> 281 passed.
+
+Decision: continue
+
+Reason:
+
+* Stage 1 completed without changing raw transcript persistence.
+
+## Checkpoint: Stage 2 AutoCompact Reliability Backbone
+
+State: checkpoint
+
+Verdict: APPROVE
+
+Implemented:
+
+* `autocompact-failure-circuit-breaker`
+* `compact-request-ptl-retry`
+* `structured-compaction-result`
+* `post-compact-restoration-contributions` active-todo slice
+* `pre-post-compact-hooks`
+
+Verification:
+
+* `pytest -q tests/test_runtime_pressure.py tests/test_hooks.py` -> 46 passed.
+* `pytest -q tests/test_app.py` -> 9 passed.
+* `pytest -q` -> 281 passed.
+* Targeted `ruff check` and `mypy` passed.
+
+Decision: continue
+
+Reason:
+
+* Stage 2 completed through the planned hook seam.
+
+## Checkpoint: Stage 3 Collapse Store And Projection
+
+State: checkpoint
+
+Verdict: ITERATE
+
+Boundary findings:
+
+* `collapse-records` and `collapse-projection-replay` need deterministic references
+  from collapse records back to raw transcript messages.
+* Current persisted session messages have `message_index` but no stable
+  `message_id`.
+* Parent plan already identified stable message IDs as a likely prerequisite
+  before full `collapse-projection-replay`.
+
+Decision: split
+
+Reason:
+
+* Created prerequisite task `04-16-stable-message-ids-compression-projection`.
+* Continuing directly into durable collapse replay would lock future
+  compression timeline/projection work onto unstable implicit indexes.
+
+## Checkpoint: Stage 3 Collapse Store And Projection Closeout
+
+State: verifying
+
+Verdict: APPROVE
+
+Implemented:
+
+* `stable-message-ids-compression-projection`
+* `collapse-records`
+* `collapse-projection-replay`
+* `pressure-ratio-trigger`
+* `collapse-overflow-drain`
+* `spawn-pressure-guard`
+
+Verification:
+
+* Focused collapse/session/runtime/subagent/app tests passed:
+  `pytest -q coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_runtime_pressure.py coding-deepgent/tests/test_cli.py coding-deepgent/tests/test_subagents.py coding-deepgent/tests/test_app.py`
+* Final full-suite verification is required before commit:
+  `pytest -q coding-deepgent/tests`
+* Targeted `ruff check` and `mypy` are required before commit.
+
+Architecture:
+
+* Raw transcript remains the source of truth as `LoadedSession.history`.
+* Compact and collapse are append-only `transcript_event` projections over raw
+  messages.
+* Collapse replay uses stable `message_id` references only.
+* Runtime live collapse persistence uses a non-model-visible transcript
+  projection sidecar rather than leaking storage IDs into prompt messages.
+
+Decision: continue
+
+Reason:
+
+* Backend collapse foundation is now coherent enough for final validation and
+  scoped commit. Frontend/timeline remains in the separate visualization task.
diff --git a/.trellis/tasks/archive/2026-04/04-16-context-compression-staged-implementation-plan/task.json b/.trellis/tasks/archive/2026-04/04-16-context-compression-staged-implementation-plan/task.json
new file mode 100644
index 000000000..b3f539cc6
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-context-compression-staged-implementation-plan/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "context-compression-staged-implementation-plan",
+  "name": "context-compression-staged-implementation-plan",
+  "title": "context compression staged implementation plan",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-16",
+  "completedAt": "2026-04-17",
+  "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": "All 3 stages checkpointed APPROVE (see prd.md). Stage 1 tool-output pruning foundation, Stage 2 autocompact reliability backbone, Stage 3 collapse store + projection + stable message IDs all shipped. Total test suite 292 passed at closeout.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-16-context-compression-visualization-readiness/check.jsonl b/.trellis/tasks/archive/2026-04/04-16-context-compression-visualization-readiness/check.jsonl
new file mode 100644
index 000000000..9bbd1eb61
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-context-compression-visualization-readiness/check.jsonl
@@ -0,0 +1,2 @@
+{"file": ".cursor/commands/trellis-finish-work.md", "reason": "Finish work checklist"}
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-16-context-compression-visualization-readiness/debug.jsonl b/.trellis/tasks/archive/2026-04/04-16-context-compression-visualization-readiness/debug.jsonl
new file mode 100644
index 000000000..e30f96d49
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-context-compression-visualization-readiness/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-16-context-compression-visualization-readiness/implement.jsonl b/.trellis/tasks/archive/2026-04/04-16-context-compression-visualization-readiness/implement.jsonl
new file mode 100644
index 000000000..137b4729e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-context-compression-visualization-readiness/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-16-context-compression-visualization-readiness/prd.md b/.trellis/tasks/archive/2026-04/04-16-context-compression-visualization-readiness/prd.md
new file mode 100644
index 000000000..c254c91d1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-context-compression-visualization-readiness/prd.md
@@ -0,0 +1,93 @@
+# context compression visualization readiness
+
+## Goal
+
+为未来前端/可视化显示准备上下文系统的数据边界：用户应能看到完整 raw transcript，同时也能看到模型实际使用的 model-facing projection，以及 compact/snip/microcompact/collapse 等压缩事件的时间线和影响范围。
+
+当前只创建 Trellis 占位任务，不在本轮实现。
+
+## What I already know
+
+* `coding-deepgent` 当前主线暂无真正前端产品层；`web/` 默认 reference-only。
+* 后端已有部分前端友好基础：
+  * `LoadedSession.history` 保留 raw history。
+  * `LoadedSession.compacted_history` 表示 compact-aware continuation view。
+  * `LoadedSession.compacts` 独立记录 compact records。
+  * `LoadedSession.evidence` 可包含 runtime pressure events。
+* 当前不足：
+  * message records 没有稳定 `message_id`。
+  * 当前 `snip` 不是 cc-style selective removal，也没有 removed refs replay。
+  * runtime pressure events 未完整记录 affected message/tool ids。
+  * 没有 compression timeline query/API。
+  * 没有 raw transcript vs model-facing projection diff/view。
+
+## Requirements
+
+* Add stable message IDs for persisted session message records.
+* Add a compression timeline data model that can represent:
+  * compact records,
+  * runtime pressure events,
+  * future snip boundaries,
+  * future microcompact affected tool IDs,
+  * future collapse/auto-compact summaries.
+* Preserve raw transcript append-only.
+* Provide a model-facing projection view separately from raw transcript.
+* Record enough metadata for UI to explain why a message/tool result is hidden,
+  summarized, pruned, or still visible.
+* Keep frontend/web implementation out of scope until product UI is explicitly targeted.
+
+## Acceptance Criteria
+
+* [x] Raw transcript can be loaded without applying compression filters.
+* [x] Model-facing projection can be loaded or derived with source metadata.
+* [x] Compression timeline can show event type, trigger, affected IDs, and summary.
+* [x] UI can distinguish raw-hidden vs model-visible content.
+* [x] Existing resume/compact tests continue to pass.
+
+## Out of Scope
+
+* No UI component work now.
+* No API/server surface unless a future product UI task requires it.
+* No physical deletion of transcript records.
+
+## Technical Notes
+
+Candidate backend surfaces:
+
+* `coding-deepgent/src/coding_deepgent/sessions/records.py`
+* `coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py`
+* `coding-deepgent/src/coding_deepgent/sessions/resume.py`
+* `coding-deepgent/src/coding_deepgent/sessions/evidence_events.py`
+* `coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py`
+* `.trellis/spec/backend/session-compact-contracts.md`
+* `.trellis/spec/backend/runtime-pressure-contracts.md`
+
+## Status
+
+Backend data-readiness implemented. UI/API remains deferred until a product UI
+task explicitly targets it.
+
+## Implementation Checkpoint
+
+State: terminal
+
+Verdict: APPROVE
+
+Implemented:
+
+* `build_compression_view(loaded, projection_mode=...)` backend read model.
+* Raw transcript message views with stable IDs, model-visible state, and hidden
+  event references.
+* Model-facing projection views with source metadata for raw, compact, and
+  collapse messages.
+* Compression timeline events for compact records, collapse records, and
+  runtime pressure evidence.
+* Explicit raw projection mode for full transcript inspection without filters.
+
+Verification:
+
+* Focused session tests cover raw/projection/timeline data.
+* Full validation required before commit:
+  - `pytest -q coding-deepgent/tests`
+  - `ruff check`
+  - `mypy`
diff --git a/.trellis/tasks/archive/2026-04/04-16-context-compression-visualization-readiness/task.json b/.trellis/tasks/archive/2026-04/04-16-context-compression-visualization-readiness/task.json
new file mode 100644
index 000000000..73aa8df11
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-context-compression-visualization-readiness/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "context-compression-visualization-readiness",
+  "name": "context-compression-visualization-readiness",
+  "title": "context compression visualization readiness",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-16",
+  "completedAt": "2026-04-17",
+  "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": "Backend data-readiness shipped. build_compression_view(projection_mode=...) read model + raw/projection/timeline views + compression timeline events. Frontend/API remain deferred until product UI task explicitly targets it. See prd.md terminal APPROVE checkpoint.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-16-context-engineering-remaining-alignment/prd.md b/.trellis/tasks/archive/2026-04/04-16-context-engineering-remaining-alignment/prd.md
new file mode 100644
index 000000000..e5e22599d
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-context-engineering-remaining-alignment/prd.md
@@ -0,0 +1,221 @@
+# brainstorm: context engineering remaining alignment
+
+## Goal
+
+反思四层压缩（Snip / MicroCompact / Collapse / AutoCompact）之外，`coding-deepgent` 的上下文工程还需要与 cc-haha / 类 cc 产品对齐或补充哪些能力，并形成后续 backlog。当前只做研究和规划，不实现。
+
+## Communication Requirement
+
+解释上下文工程时，必须优先使用具体 coding-session 场景，而不是只列术语。
+
+Preferred style:
+
+* 先描述用户/agent 遇到的实际问题。
+* 再说明系统应该如何处理。
+* 最后才映射到模块名、contract 或 task。
+
+## What I already know
+
+* 当前 `coding-deepgent` 已完成 Approach A MVP 的上下文核心：
+  * prompt layering / dynamic context,
+  * runtime pressure pipeline,
+  * session transcript/evidence/resume,
+  * compact records,
+  * scoped memory MVP,
+  * minimal subagent context propagation,
+  * observability counters/events MVP.
+* 已规划的上下文增强 tasks:
+  * `04-15-cc-style-snip-message-pruning`
+  * `04-16-cc-style-time-based-local-microcompact`
+  * `04-16-cc-style-collapse-store-pressure-guard`
+  * `04-16-cc-style-autocompact-hardening`
+  * `04-16-context-compression-visualization-readiness`
+  * `04-15-opencode-style-auto-tool-output-prune`
+* Roadmap marks richer session/agent memory runtime, rich fork/cache parity, provider-specific cost/cache instrumentation as deferred beyond MVP.
+
+## Remaining Context Engineering Themes
+
+### 1. Context Visibility And Timeline
+
+Scenario:
+
+用户问：“为什么模型忘了之前的测试日志？” 或 “这段历史到底有没有给模型看？”
+
+Needed behavior:
+
+* Raw transcript remains complete.
+* Model-facing projection is inspectable.
+* Compression timeline shows compact/snip/microcompact/collapse events and affected IDs.
+
+Existing task:
+
+* `04-16-context-compression-visualization-readiness`
+
+### 2. Stable Message Identity
+
+Scenario:
+
+未来做 SnipTool、前端 timeline、projection diff 时，必须能说“msg-0012 被 collapse-3 隐藏”。
+
+Needed behavior:
+
+* Persist stable `message_id` in session message records.
+* Preserve mapping from model-facing projection back to raw transcript.
+
+Related tasks:
+
+* `04-15-cc-style-snip-message-pruning`
+* `04-16-context-compression-visualization-readiness`
+
+### 3. Rich Session Memory Runtime
+
+Scenario:
+
+用户隔天回来，希望 agent 还记得“项目偏好、当前状态、错误教训”，而不只是 compact summary。
+
+Needed behavior:
+
+* Background or explicit session-memory extraction.
+* Session-memory compact path when memory is good enough.
+* Staleness/quality gates stronger than current artifact refresh.
+
+Roadmap link:
+
+* H07 richer session/agent memory runtime deferred.
+
+### 4. Post-Compact State Restoration
+
+Scenario:
+
+AutoCompact 后，模型只看到 summary，却忘了当前 plan、active todos、loaded skill、verifier failure、重要文件路径。
+
+Needed behavior:
+
+* Restore bounded plan/todo/verifier/skill/file/subagent context after compact.
+* Keep raw payloads out of recovery context.
+
+Existing task:
+
+* `04-16-cc-style-autocompact-hardening`
+
+### 5. Fork/Subagent Context Hygiene
+
+Scenario:
+
+主上下文已经很大，用户要求 “开一个子 agent 去审查”。如果直接 fork，子 agent 可能一开始就带着一堆无用历史。
+
+Needed behavior:
+
+* Decide what parent context child agents inherit.
+* Add pressure-aware spawn guard or compact-before-spawn.
+* Keep child context isolated from parent pressure state.
+
+Roadmap link:
+
+* H12 rich fork/cache parity deferred.
+* Existing task: `04-16-cc-style-collapse-store-pressure-guard`.
+
+### 6. Provider Cost / Cache Observability
+
+Scenario:
+
+压缩后成本为什么反而变高？是 cache miss、cache rewrite，还是 summary API 太贵？
+
+Needed behavior:
+
+* Track local estimated tokens and, when available, provider usage.
+* Distinguish cache read/write/drop from intentional compact/microcompact.
+* Keep provider-specific features behind capability gates.
+
+Roadmap link:
+
+* H20 rich provider-specific cost/cache instrumentation deferred.
+
+### 7. Context Source Attribution
+
+Scenario:
+
+模型看到一段内容，但开发者不知道它来自 memory、resume brief、todo、compact summary、skill 还是 hook。
+
+Needed behavior:
+
+* Tag model-facing context sections with source.
+* Preserve source metadata in projection/debug surfaces.
+* Avoid dumping arbitrary metadata into model-visible recovery briefs.
+
+Existing contracts:
+
+* Runtime state/recovery/compact contribution seams.
+
+### 8. Context Quality Gates
+
+Scenario:
+
+summary 写得太泛，memory 保存了临时状态，或 compact 丢了关键约束，导致下一轮工作偏航。
+
+Needed behavior:
+
+* Quality checks for generated summaries and session-memory artifacts.
+* Rejection or warning when summary lacks goal/current state/next steps.
+* Optional verifier-style review for high-risk compaction later.
+
+### 9. Manual Context Controls
+
+Scenario:
+
+用户想主动说：“这段旧探索不用了” 或 “compact 时特别保留数据库相关内容”。
+
+Needed behavior:
+
+* Manual compact instructions already exist in CLI resume path.
+* Future: explicit SnipTool or `/history`-style selection.
+* Future: PreCompact custom instruction hook.
+
+Existing tasks:
+
+* `04-15-cc-style-snip-message-pruning`
+* `04-16-cc-style-autocompact-hardening`
+
+### 10. Context Pressure Policy Configuration
+
+Scenario:
+
+不同模型/供应商/任务类型上下文窗口不同，固定 token 阈值可能不合适。
+
+Needed behavior:
+
+* Ratio-based thresholds when context window is known.
+* Conservative local estimates when provider limits are unavailable.
+* Settings-backed policies with tests.
+
+Existing tasks:
+
+* `04-16-cc-style-collapse-store-pressure-guard`
+* `04-16-cc-style-time-based-local-microcompact`
+
+## Current Priority Recommendation
+
+1. Finish already planned pressure closeouts only when needed:
+   * time-based local MicroCompact,
+   * AutoCompact hardening,
+   * Collapse records/projection.
+2. Then add visualization readiness:
+   * stable message IDs,
+   * compression timeline,
+   * raw vs model-facing projection.
+3. Defer expensive/provider-specific work:
+   * cached microcompact API,
+   * prompt-cache sharing,
+   * provider exact token accounting.
+4. Defer full cc-style Snip until message IDs and projection replay exist.
+
+## Out of Scope
+
+* No implementation in this turn.
+* No frontend UI work now.
+* No provider-specific cache editing now.
+* No line-by-line cc clone.
+
+## Status
+
+Research captured / planning-only.
diff --git a/.trellis/tasks/archive/2026-04/04-16-context-engineering-remaining-alignment/task.json b/.trellis/tasks/archive/2026-04/04-16-context-engineering-remaining-alignment/task.json
new file mode 100644
index 000000000..709c620ec
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-context-engineering-remaining-alignment/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "context-engineering-remaining-alignment",
+  "name": "context-engineering-remaining-alignment",
+  "title": "brainstorm: context engineering remaining alignment",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-16",
+  "completedAt": "2026-04-16",
+  "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/archive/2026-04/04-16-context-engineering-roadmap-task-decomposition/prd.md b/.trellis/tasks/archive/2026-04/04-16-context-engineering-roadmap-task-decomposition/prd.md
new file mode 100644
index 000000000..edc793961
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-context-engineering-roadmap-task-decomposition/prd.md
@@ -0,0 +1,300 @@
+# context engineering roadmap and task decomposition
+
+## Goal
+
+建立一个高层 Trellis epic，用于统一规划上下文工程剩余 10 个方向，并反思已有 planning tasks 之间的耦合关系。后续再把这些方向拆成更小、可顺序执行的 implementation tasks。
+
+当前只做规划，不实现。
+
+## Communication Requirement
+
+后续讨论上下文工程时，优先用具体 coding-session 场景表达功能价值，再映射到模块或术语。
+
+## Context
+
+当前已讨论并创建的上下文相关 planning tasks：
+
+* `04-15-cc-style-snip-message-pruning`
+* `04-15-opencode-style-auto-tool-output-prune`
+* `04-15-cc-level-2-microcompact-alignment`
+* `04-16-cc-style-time-based-local-microcompact`
+* `04-16-cc-level-3-collapse-alignment`
+* `04-16-cc-style-collapse-store-pressure-guard`
+* `04-16-cc-level-4-autocompact-alignment`
+* `04-16-cc-style-autocompact-hardening`
+* `04-16-context-compression-visualization-readiness`
+* `04-16-context-engineering-remaining-alignment`
+
+Observation:
+
+这些任务不是彼此独立的功能点。它们共享底层前提：
+
+* stable message IDs,
+* raw transcript vs model-facing projection separation,
+* compression timeline records,
+* runtime pressure evidence,
+* model/context-window pressure estimation,
+* post-compact context restoration,
+* subagent/fork context boundaries.
+
+因此后续不能按“Level 2/3/4”机械并行实现；应该先打基础，再做高级能力。
+
+## The 10 Context Engineering Directions
+
+### 1. Context Visibility And Timeline
+
+Scenario:
+
+用户问：“为什么模型没看到之前那段测试日志？” 系统应能展示 raw transcript 里存在，但 model-facing context 被 compact/collapse/microcompact 隐藏。
+
+Depends on:
+
+* stable message IDs
+* compression timeline records
+* affected IDs in events
+
+### 2. Stable Message Identity
+
+Scenario:
+
+未来 SnipTool 或 UI 需要引用 `msg-0012`。没有稳定 ID，就无法安全说“剪掉这几条”或“这条被 collapse 覆盖”。
+
+Depends on:
+
+* session record schema
+* backward-compatible session loading
+
+### 3. Rich Session Memory Runtime
+
+Scenario:
+
+用户隔天回来，agent 仍应记得项目偏好、当前状态、关键错误教训，而不只是看 raw transcript。
+
+Depends on:
+
+* memory quality policy
+* compact/session summary quality
+* session state contributions
+
+### 4. Post-Compact State Restoration
+
+Scenario:
+
+AutoCompact 后模型忘了 active todos、plan、verifier failure、skill、关键文件路径，继续工作偏航。
+
+Depends on:
+
+* structured compaction result
+* contribution registry
+* evidence and task/plan contracts
+
+### 5. Fork/Subagent Context Hygiene
+
+Scenario:
+
+主上下文很大时直接开子 agent，子 agent 继承一堆无用历史或一启动就超上下文。
+
+Depends on:
+
+* pressure estimation
+* subagent context propagation contract
+* optional spawn guard
+
+### 6. Provider Cost / Cache Observability
+
+Scenario:
+
+压缩后成本反而更高，用户需要知道是 summary call 贵、cache miss、还是 rewrite 造成。
+
+Depends on:
+
+* local token accounting
+* provider usage capture when available
+* runtime event/evidence schema
+
+### 7. Context Source Attribution
+
+Scenario:
+
+模型看到一段规则，但开发者不知道它来自 memory、resume brief、skill、hook、todo 还是 compact summary。
+
+Depends on:
+
+* typed context contributions
+* model-facing projection debug view
+
+### 8. Context Quality Gates
+
+Scenario:
+
+summary 太泛，memory 保存临时状态，compact 丢掉关键约束，导致后续工作偏航。
+
+Depends on:
+
+* summary schema/quality checks
+* memory policy
+* optional verifier-like review later
+
+### 9. Manual Context Controls
+
+Scenario:
+
+用户想主动说“这段旧探索不用了”或“compact 时特别保留数据库相关内容”。
+
+Depends on:
+
+* stable message IDs
+* snip boundary/replay
+* PreCompact custom instructions
+
+### 10. Context Pressure Policy Configuration
+
+Scenario:
+
+不同模型上下文窗口不同；固定 token 阈值可能过早/过晚触发压缩。
+
+Depends on:
+
+* model context-window source
+* deterministic local estimate
+* settings-backed policy
+
+## Coupling Reflection
+
+### Foundational Couplings
+
+* `Stable Message Identity` is a prerequisite for:
+  * cc-style Snip,
+  * compression timeline,
+  * raw/projection diff,
+  * affected-message metadata,
+  * frontend display.
+* `Structured CompactionResult` is a prerequisite for:
+  * post-compact restoration,
+  * hooks,
+  * better AutoCompact telemetry,
+  * future UI progress.
+* `Pressure Estimation` is a prerequisite for:
+  * ratio-based Collapse,
+  * spawn guard,
+  * MicroCompact time/budget policy,
+  * cost/cache observability.
+* `Contribution/Source Attribution` is a prerequisite for:
+  * restoration,
+  * debug views,
+  * quality gates.
+
+### Existing Task Couplings
+
+* `04-16-context-compression-visualization-readiness` should not proceed before stable message IDs.
+* `04-15-cc-style-snip-message-pruning` should not proceed before stable message IDs and projection replay.
+* `04-16-cc-style-collapse-store-pressure-guard` should be split; collapse records and projection replay should come before spawn guard and overflow drain.
+* `04-16-cc-style-autocompact-hardening` should be split; failure circuit breaker can be early, post-compact restoration should wait for structured result.
+* `04-16-cc-style-time-based-local-microcompact` can be relatively independent, but richer event metadata should align with compression timeline schema.
+
+## Proposed Execution Order
+
+### Phase 0: Stabilize Current Work
+
+* Commit current progressive runtime pressure pipeline work.
+* Record session.
+* Avoid adding more implementation until current diff is committed.
+
+### Phase 1: Foundation For Context Explainability
+
+1. Stable message IDs in session records.
+2. Compression timeline record schema.
+3. Raw history vs model-facing projection debug/query helper.
+
+Why first:
+
+These unlock frontend display, Snip, projection replay, and better evidence.
+
+### Phase 2: Low-Risk Pressure Enhancements
+
+4. Time-based local MicroCompact.
+5. Token saved accounting and pressure event enrichment.
+6. AutoCompact failure circuit breaker.
+
+Why second:
+
+These are mostly local, low-risk, and do not require major session projection changes.
+
+### Phase 3: Structured Compaction Backbone
+
+7. Structured CompactionResult.
+8. Compact request prompt-too-long retry.
+9. Post-compact state restoration contributions.
+
+Why third:
+
+This gives AutoCompact a stronger backbone before hooks or UI.
+
+### Phase 4: Collapse Store And Replay
+
+10. Collapse records.
+11. Projection replay from collapse records.
+12. Overflow drain before reactive compact.
+
+Why fourth:
+
+This depends on message IDs, timeline, and projection helper.
+
+### Phase 5: Manual / Agent Context Control
+
+13. Explicit SnipTool with reason and safety gates.
+14. Optional `/history` or CLI selection UX.
+15. PreCompact/PostCompact hooks.
+
+Why fifth:
+
+These expose control surfaces and should wait until records/replay are reliable.
+
+### Phase 6: Advanced Runtime And Provider Optimization
+
+16. Spawn guard / compact-before-spawn.
+17. Rich session memory extraction.
+18. Provider cache/cost instrumentation.
+19. Cached microcompact API spike only if provider support is concrete.
+
+Why last:
+
+These are high-coupling and provider/runtime-specific.
+
+## Suggested Small Task Breakdown
+
+Future tasks should be small and testable:
+
+* `stable-session-message-ids`
+* `compression-timeline-records`
+* `model-facing-projection-debug-view`
+* `time-based-local-microcompact`
+* `runtime-pressure-token-saved-evidence`
+* `autocompact-failure-circuit-breaker`
+* `structured-compaction-result`
+* `compact-request-ptl-retry`
+* `post-compact-restoration-contributions`
+* `collapse-records`
+* `collapse-projection-replay`
+* `collapse-overflow-drain`
+* `explicit-snip-tool`
+* `pre-post-compact-hooks`
+* `spawn-pressure-guard`
+
+## Out of Scope
+
+* No implementation in this task.
+* No frontend UI work now.
+* No provider-specific cache editing now.
+* No line-by-line cc clone.
+
+## Acceptance Criteria
+
+* [x] 10 context engineering directions are captured.
+* [x] Couplings with existing planning tasks are documented.
+* [x] A phased execution order is proposed.
+* [x] Future small task names are listed.
+
+## Status
+
+Planning-only epic. Use this task as the parent planning reference before splitting new implementation tasks.
diff --git a/.trellis/tasks/archive/2026-04/04-16-context-engineering-roadmap-task-decomposition/task.json b/.trellis/tasks/archive/2026-04/04-16-context-engineering-roadmap-task-decomposition/task.json
new file mode 100644
index 000000000..6344aefb8
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-context-engineering-roadmap-task-decomposition/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "context-engineering-roadmap-task-decomposition",
+  "name": "context-engineering-roadmap-task-decomposition",
+  "title": "context engineering roadmap and task decomposition",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-16",
+  "completedAt": "2026-04-16",
+  "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/archive/2026-04/04-16-post-compact-restoration-contributions/prd.md b/.trellis/tasks/archive/2026-04/04-16-post-compact-restoration-contributions/prd.md
new file mode 100644
index 000000000..fbef68871
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-post-compact-restoration-contributions/prd.md
@@ -0,0 +1,53 @@
+# post compact restoration contributions
+
+## Goal
+
+Add bounded post-compact restoration context through the structured live compaction result so the model does not lose active short-term planning state after live AutoCompact.
+
+## Scope Implemented In This Pass
+
+This sub-stage implemented the lowest-risk restoration source: active TodoWrite state already present in runtime state.
+
+Deferred until stable runtime-state sources exist:
+
+- durable plan references
+- verifier evidence summaries
+- loaded skill refs
+- subagent lineage
+
+## Requirements
+
+- Add bounded restoration messages through `LiveCompactionResult.restoration_messages`.
+- Restore active todos only when `status in {"pending", "in_progress"}`.
+- Do not include completed todos.
+- Do not dump raw transcript or large payloads.
+- Preserve existing persisted-output path restoration behavior.
+
+## Acceptance Criteria
+
+- [x] post-compact context includes active todos when present.
+- [x] completed todos are excluded.
+- [x] restoration message renders before preserved tail.
+- [x] no raw transcript mutation is introduced.
+- [x] runtime pressure contract is updated.
+- [x] focused tests, ruff, and targeted mypy pass.
+
+## Verification
+
+- `pytest -q tests/test_runtime_pressure.py` -> 38 passed.
+- `pytest -q tests/test_app.py` -> 9 passed.
+- `ruff check src/coding_deepgent/compact/runtime_pressure.py src/coding_deepgent/compact/__init__.py src/coding_deepgent/sessions/evidence_events.py src/coding_deepgent/settings.py src/coding_deepgent/containers/app.py tests/test_runtime_pressure.py tests/test_app.py` -> passed.
+- `mypy src/coding_deepgent/compact/runtime_pressure.py src/coding_deepgent/sessions/evidence_events.py src/coding_deepgent/settings.py src/coding_deepgent/containers/app.py` -> passed.
+
+## Checkpoint
+
+State: checkpoint
+
+Verdict: APPROVE
+
+Decision: continue
+
+Reason:
+
+- The active-todo restoration slice is implemented and verified.
+- The parent plan next sub-stage remains valid: hooks can now contribute through the structured result boundary.
diff --git a/.trellis/tasks/archive/2026-04/04-16-post-compact-restoration-contributions/task.json b/.trellis/tasks/archive/2026-04/04-16-post-compact-restoration-contributions/task.json
new file mode 100644
index 000000000..364fc151d
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-post-compact-restoration-contributions/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "post-compact-restoration-contributions",
+  "name": "post-compact-restoration-contributions",
+  "title": "post compact restoration contributions",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-16",
+  "completedAt": "2026-04-16",
+  "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-16-context-compression-staged-implementation-plan",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-16-pre-post-compact-hooks/prd.md b/.trellis/tasks/archive/2026-04/04-16-pre-post-compact-hooks/prd.md
new file mode 100644
index 000000000..96771bb8b
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-pre-post-compact-hooks/prd.md
@@ -0,0 +1,43 @@
+# pre post compact hooks
+
+## Goal
+
+Add deterministic local `PreCompact` / `PostCompact` hook contribution seams around live AutoCompact without allowing hooks to call tools or mutate transcript records.
+
+## Requirements
+
+- Add `PreCompact` and `PostCompact` hook event names.
+- Use existing `LocalHookRegistry` and `additional_context` only.
+- `PreCompact` context flows into compact summarizer assist text.
+- `PostCompact` context flows into structured restoration messages.
+- Blank hook output is ignored.
+- Hook context is bounded before becoming model-visible.
+
+## Acceptance Criteria
+
+- [x] PreCompact contribution can add compact instructions.
+- [x] PostCompact contribution can add bounded restoration context.
+- [x] invalid/blank hook output is ignored through existing hook result schema and local filtering.
+- [x] hook output is represented through structured compaction result restoration.
+- [x] runtime pressure contract is updated.
+- [x] focused tests, ruff, and targeted mypy pass.
+
+## Verification
+
+- `pytest -q tests/test_runtime_pressure.py tests/test_hooks.py` -> 46 passed.
+- `pytest -q tests/test_app.py` -> 9 passed.
+- `ruff check src/coding_deepgent/compact/runtime_pressure.py src/coding_deepgent/compact/__init__.py src/coding_deepgent/hooks/events.py src/coding_deepgent/sessions/evidence_events.py src/coding_deepgent/settings.py src/coding_deepgent/containers/app.py tests/test_runtime_pressure.py tests/test_app.py tests/test_hooks.py` -> passed.
+- `mypy src/coding_deepgent/compact/runtime_pressure.py src/coding_deepgent/hooks/events.py src/coding_deepgent/sessions/evidence_events.py src/coding_deepgent/settings.py src/coding_deepgent/containers/app.py` -> passed.
+
+## Checkpoint
+
+State: checkpoint
+
+Verdict: APPROVE
+
+Decision: continue
+
+Reason:
+
+- Stage 2 AutoCompact reliability backbone is now complete through the planned hook seam.
+- The parent plan next stage remains valid: Collapse Store And Projection.
diff --git a/.trellis/tasks/archive/2026-04/04-16-pre-post-compact-hooks/task.json b/.trellis/tasks/archive/2026-04/04-16-pre-post-compact-hooks/task.json
new file mode 100644
index 000000000..f36220c34
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-pre-post-compact-hooks/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "pre-post-compact-hooks",
+  "name": "pre-post-compact-hooks",
+  "title": "pre post compact hooks",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-16",
+  "completedAt": "2026-04-16",
+  "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-16-context-compression-staged-implementation-plan",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-16-runtime-pressure-token-saved-evidence/check.jsonl b/.trellis/tasks/archive/2026-04/04-16-runtime-pressure-token-saved-evidence/check.jsonl
new file mode 100644
index 000000000..c9e920733
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-runtime-pressure-token-saved-evidence/check.jsonl
@@ -0,0 +1,7 @@
+{"file": ".cursor/commands/trellis-finish-work.md", "reason": "Finish work checklist"}
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
+{"file": ".trellis/tasks/04-16-runtime-pressure-token-saved-evidence/prd.md", "reason": "active sub-stage acceptance criteria"}
+{"file": ".trellis/tasks/04-16-context-compression-staged-implementation-plan/prd.md", "reason": "parent staged checkpoint scope"}
+{"file": ".trellis/spec/guides/staged-execution-guide.md", "reason": "checkpoint validation protocol"}
+{"file": ".trellis/spec/backend/runtime-pressure-contracts.md", "reason": "runtime pressure contract checks"}
+{"file": "coding-deepgent/tests/test_runtime_pressure.py", "reason": "focused runtime pressure tests"}
diff --git a/.trellis/tasks/archive/2026-04/04-16-runtime-pressure-token-saved-evidence/debug.jsonl b/.trellis/tasks/archive/2026-04/04-16-runtime-pressure-token-saved-evidence/debug.jsonl
new file mode 100644
index 000000000..e30f96d49
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-runtime-pressure-token-saved-evidence/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-16-runtime-pressure-token-saved-evidence/implement.jsonl b/.trellis/tasks/archive/2026-04/04-16-runtime-pressure-token-saved-evidence/implement.jsonl
new file mode 100644
index 000000000..1e4203839
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-runtime-pressure-token-saved-evidence/implement.jsonl
@@ -0,0 +1,7 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": ".trellis/tasks/04-16-runtime-pressure-token-saved-evidence/prd.md", "reason": "active sub-stage PRD"}
+{"file": ".trellis/tasks/04-16-context-compression-staged-implementation-plan/prd.md", "reason": "parent staged plan ordering"}
+{"file": ".trellis/spec/guides/staged-execution-guide.md", "reason": "deep staged execution protocol"}
+{"file": ".trellis/spec/backend/runtime-pressure-contracts.md", "reason": "runtime pressure event/evidence contract"}
+{"file": "coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py", "reason": "implementation seam for microcompact runtime events"}
diff --git a/.trellis/tasks/archive/2026-04/04-16-runtime-pressure-token-saved-evidence/prd.md b/.trellis/tasks/archive/2026-04/04-16-runtime-pressure-token-saved-evidence/prd.md
new file mode 100644
index 000000000..dac19f001
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-runtime-pressure-token-saved-evidence/prd.md
@@ -0,0 +1,96 @@
+# runtime pressure token saved evidence
+
+## Goal
+
+为现有 runtime pressure / MicroCompact 事件补齐可恢复的节省量观测字段，让后续 time-based MicroCompact、opencode-style tool-output pruning、以及未来 compression timeline 可以复用同一套 bounded evidence metadata。
+
+## Expected Effect
+
+当 live MicroCompact 清理旧工具输出时，runtime event 和 session evidence 应能说明这次清理大概节省了多少上下文，以及清理/保留了多少工具结果。这个变化提升 observability 和后续可视化准备，但不改变模型实际看到的清理语义。
+
+## Requirements
+
+- 对 MicroCompact 事件增加 bounded metadata：
+  - `tools_cleared`
+  - `tools_kept`
+  - `tokens_saved_estimate`
+  - `keep_recent`
+- 字段必须来自确定性的本地估算，不代表 provider billing/tokenizer 数字。
+- 继续保留现有 `cleared_tool_results` 字段兼容当前 runtime pressure contract。
+- metadata 不得包含 raw tool output、raw prompt、raw summary。
+- 不持久化修改 raw transcript。
+- 不实现 time-based MicroCompact trigger。
+- 不实现 token-budget pruning。
+
+## Acceptance Criteria
+
+- [ ] MicroCompact helper 可返回或暴露清理统计信息。
+- [ ] `RuntimePressureMiddleware.wrap_model_call()` 发出的 `microcompact` event 包含新增 bounded metadata。
+- [ ] active `session_context` 下追加的 session evidence 保留新增 bounded metadata。
+- [ ] 未发生 MicroCompact 时不发出噪音事件。
+- [ ] 现有 MicroCompact 清理语义保持兼容。
+- [ ] `.trellis/spec/backend/runtime-pressure-contracts.md` 更新新增字段契约。
+- [ ] `coding-deepgent/tests/test_runtime_pressure.py` 覆盖新增 metadata。
+- [ ] 相关 focused tests、ruff、targeted mypy 通过。
+
+## Technical Notes
+
+Likely files:
+
+- `coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py`
+- `coding-deepgent/src/coding_deepgent/sessions/evidence_events.py`
+- `coding-deepgent/tests/test_runtime_pressure.py`
+- `.trellis/spec/backend/runtime-pressure-contracts.md`
+
+## Out of Scope
+
+- No provider-specific exact tokenizer.
+- No provider cache-edit payloads.
+- No session record schema migration.
+- No frontend UI/API.
+- No physical deletion of transcript records.
+
+## Checkpoint
+
+State: checkpoint
+
+Verdict: APPROVE
+
+Implemented:
+
+- Added `MicrocompactStats` / `MicrocompactResult` and `microcompact_messages_with_stats(...)`.
+- Added bounded `tools_cleared`, `tools_kept`, `tokens_saved_estimate`, and `keep_recent` metadata for `microcompact` runtime events.
+- Preserved `cleared_tool_results` for backward compatibility.
+- Extended runtime event evidence metadata filtering to preserve the new bounded fields.
+- Updated runtime pressure contracts with the executable stats/event contract.
+
+Verification:
+
+- `pytest -q tests/test_runtime_pressure.py` -> 20 passed.
+- `pytest -q tests/test_app.py` -> 9 passed.
+- `ruff check src/coding_deepgent/compact/runtime_pressure.py src/coding_deepgent/compact/__init__.py src/coding_deepgent/sessions/evidence_events.py tests/test_runtime_pressure.py` -> passed.
+- `mypy src/coding_deepgent/compact/runtime_pressure.py src/coding_deepgent/sessions/evidence_events.py` -> passed.
+
+Alignment:
+
+- source files inspected: current local runtime pressure implementation and runtime pressure Trellis contracts.
+- aligned: local bounded observability for MicroCompact token savings.
+- deferred: time-based trigger, token-budget pruning, provider cache-edit APIs.
+- do-not-copy: provider-specific exact tokenizer/billing semantics.
+
+Architecture:
+
+- primitive used: existing LangChain middleware-level runtime event/evidence seams.
+- why no heavier abstraction: this sub-stage only needs deterministic stats on the existing live projection helper.
+
+Boundary findings:
+
+- No session schema migration needed.
+- No raw transcript mutation introduced.
+- New fields are bounded integers only.
+
+Decision: continue
+
+Reason:
+
+- The sub-stage is complete, verified, and unblocks `time-based-local-microcompact`.
diff --git a/.trellis/tasks/archive/2026-04/04-16-runtime-pressure-token-saved-evidence/task.json b/.trellis/tasks/archive/2026-04/04-16-runtime-pressure-token-saved-evidence/task.json
new file mode 100644
index 000000000..cd714e7f4
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-runtime-pressure-token-saved-evidence/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "runtime-pressure-token-saved-evidence",
+  "name": "runtime-pressure-token-saved-evidence",
+  "title": "runtime pressure token saved evidence",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-16",
+  "completedAt": "2026-04-16",
+  "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-16-context-compression-staged-implementation-plan",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-16-stable-message-ids-compression-projection/check.jsonl b/.trellis/tasks/archive/2026-04/04-16-stable-message-ids-compression-projection/check.jsonl
new file mode 100644
index 000000000..e44e6d3c2
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-stable-message-ids-compression-projection/check.jsonl
@@ -0,0 +1,5 @@
+{"file": ".cursor/commands/trellis-finish-work.md", "reason": "Finish work checklist"}
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Validate focused tests plus static checks for the touched session/compact surfaces."}
+{"file": ".trellis/spec/backend/session-compact-contracts.md", "reason": "Review the new message/event schema and compact replay behavior against the updated contract."}
+{"file": ".trellis/spec/guides/cross-layer-thinking-guide.md", "reason": "Check message persistence, load, replay, and CLI projection boundaries stay aligned after the schema migration."}
diff --git a/.trellis/tasks/archive/2026-04/04-16-stable-message-ids-compression-projection/debug.jsonl b/.trellis/tasks/archive/2026-04/04-16-stable-message-ids-compression-projection/debug.jsonl
new file mode 100644
index 000000000..e30f96d49
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-stable-message-ids-compression-projection/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-16-stable-message-ids-compression-projection/implement.jsonl b/.trellis/tasks/archive/2026-04/04-16-stable-message-ids-compression-projection/implement.jsonl
new file mode 100644
index 000000000..004eef5d1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-stable-message-ids-compression-projection/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": ".trellis/spec/backend/quality-guidelines.md", "reason": "Cross-layer runtime/session changes need focused tests, ruff, and mypy on touched product files."}
+{"file": ".trellis/spec/backend/error-handling.md", "reason": "Session loader/schema refactor must fail explicitly on invalid domain records instead of permissive fallback."}
+{"file": "coding-deepgent/src/coding_deepgent/sessions/records.py", "reason": "Defines session domain dataclasses and record schemas that must move to SessionMessage and transcript events."}
+{"file": "coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py", "reason": "Primary load/append seam for raw messages and transcript events."}
+{"file": ".trellis/spec/guides/cross-layer-thinking-guide.md", "reason": "Message/event ledger schema crosses persistence, load, compaction replay, and CLI continuation boundaries."}
+{"file": ".trellis/spec/backend/session-compact-contracts.md", "reason": "Owns session ledger, compact persistence, and resume/load contracts that this refactor changes."}
diff --git a/.trellis/tasks/archive/2026-04/04-16-stable-message-ids-compression-projection/prd.md b/.trellis/tasks/archive/2026-04/04-16-stable-message-ids-compression-projection/prd.md
new file mode 100644
index 000000000..72daa1882
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-stable-message-ids-compression-projection/prd.md
@@ -0,0 +1,407 @@
+# stable message ids for compression projection
+
+## Goal
+
+在实现 durable collapse projection replay、compression timeline、和未来 cc-style selective snip 之前，为 persisted raw transcript 增加稳定 `message_id`。这样 collapse records、timeline、以及 UI explanation 可以引用明确消息，而不是继续依赖隐式 `message_index`。
+
+## What I already know
+
+* 用户明确要求这里按长期基础设施来做，不只追求当前最小改动。
+* 用户最新明确要求：这里**不需要优先兼容旧方案/旧设计**，应优先长期架构、边界清晰、代码优雅。
+* 用户进一步明确：当前实际上没有需要保留的旧数据，因此这里可以完全不做旧数据兼容。
+* 当前 message records 只有：
+  * `record_type == "message"`
+  * `timestamp`
+  * `role`
+  * `content`
+  * 可选 `message_index`
+  * 可选 `metadata`
+* `JsonlSessionStore.load_session()` 当前把 raw transcript 装成 `LoadedSession.history: list[dict[str, str]]`，只保留 `role/content`，不会保留 record-level metadata。
+* 现有 compact/view 逻辑仍然依赖 `message_index` / message count：
+  * `run_prompt_with_recording()` 录制时继续分配 contiguous `message_index`
+  * compact tail replay 用 `original_message_count - kept_message_count`
+* 这对现有 compact tail 足够，但对未来的 collapse records / projection replay 不够：
+  * collapse record 需要指向具体 raw messages
+  * timeline / UI explanation 需要稳定引用
+  * selective snip/microcompact/collapse 未来会需要 “哪些消息被隐藏/摘要” 的稳定 key
+* 当前 Stage 3 已被合法 split，原因就是这里还没有稳定消息 ID。
+
+## Assumptions (temporary)
+
+* `message_id` 应该是 append-time persisted field，而不是 load-time 临时计算值。
+* 既然当前选择走 Approach A，`LoadedSession.history` 会被扩成富结构；设计目标应优先服务 future collapse/timeline/projection，而不是只为了减少当下改动。
+* 旧 session/旧读取形状不是当前主导约束；如果和长期设计冲突，应优先长期设计。
+
+## Open Questions
+
+* `transcript_event` 本身应该采用什么记录形状？
+
+## Requirements (evolving)
+
+* Add stable `message_id` to persisted session message records.
+* Keep raw transcript append-only.
+* Upgrade `LoadedSession.history` to `list[SessionMessage]`.
+* Do not pull `compacted_history` into the same type migration in this prerequisite.
+* Future collapse records must be able to reference covered messages/ranges through stable message identity, not ad hoc replay indexes.
+* Current compact record shape should be redesigned away from count/index semantics rather than preserved as the long-term foundation.
+* The new session/compact foundation does not need to support legacy transcript or legacy compact schemas.
+
+## Acceptance Criteria (evolving)
+
+* [ ] New persisted message records include stable IDs.
+* [ ] `LoadedSession.history` is typed as `SessionMessage`.
+* [ ] Session tests cover the new typed raw transcript boundary.
+* [ ] Runtime/session contracts are updated with executable field-level details.
+* [ ] Collapse record/projection work can reference message IDs without inventing implicit indexes.
+* [ ] New compact replay/load path only targets the new message-reference schema.
+
+## 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)
+
+* Collapse record implementation itself
+* Collapse replay implementation itself
+* Frontend visualization/timeline implementation
+* Physical deletion of transcript records
+
+## Research Notes
+
+### What similar systems need
+
+* Durable projection/timeline systems need a stable reference key for each raw message.
+* Load-time derived hashes are tempting, but they are weaker for future schema evolution and harder to reason about in mixed old/new session transcripts.
+* Keeping compatibility usually means:
+  * persist the new field in raw records,
+  * keep old aggregate/read APIs stable,
+  * add a richer read surface in parallel for new consumers.
+
+### Constraints from our repo/project
+
+* `LoadedSession.history` is currently a simple `list[dict[str, str]]`; many tests and resume paths assume this.
+* Existing compact replay depends on count/index math and should not be broken.
+* Future collapse/timeline work needs message-level references, not just counts.
+* Old JSONL sessions already exist and must remain loadable.
+
+### Feasible approaches here
+
+**Approach A: Persist `message_id` and widen `LoadedSession.history` directly** (Chosen)
+
+* How it works:
+  * append `message_id` into message records
+  * load `history` as richer dicts, e.g. `{"role", "content", "message_id", ...}`
+* Pros:
+  * simplest mental model
+  * new consumers can use `history` directly
+* Cons:
+  * wider blast radius
+  * many existing tests/consumers likely need touch-up
+  * prerequisite task也会承接一部分兼容改造
+
+**Approach B: Persist `message_id`, keep `history` stable, add parallel raw-message surface** (Recommended)
+
+* How it works:
+  * append `message_id` into message records
+  * keep `LoadedSession.history` as current role/content list for compatibility
+  * add a parallel richer surface, e.g. `raw_messages` / `message_records`, for future collapse/timeline consumers
+* Pros:
+  * lowest-risk migration path
+  * preserves current compact/resume callers
+  * gives future Stage 3 work an explicit stable source of truth
+* Cons:
+  * two read surfaces briefly coexist
+  * requires discipline about which callers should migrate later
+
+**Approach C: Do not persist IDs; derive them on load from existing fields**
+
+* How it works:
+  * synthesize an ID from session_id + message_index + timestamp/content
+* Pros:
+  * smallest schema change now
+* Cons:
+  * weaker future contract
+  * mixed old/new sessions become harder to reason about
+  * not ideal for durable collapse/timeline references
+
+## Expansion Sweep
+
+### Future evolution
+
+* collapse records will likely want `covered_message_ids` or message-id ranges
+* visualization/timeline will probably want raw transcript + model-facing projection side by side
+
+### Related scenarios
+
+* CLI resume and generated compact summary should continue to work unchanged
+* future selective snip and collapse replay should share the same message reference primitive
+
+### Failure & edge cases
+
+* partially corrupt new-format transcripts
+* avoiding leakage of storage-layer details into the domain surface
+* choosing a reference shape that works for both compact and future collapse/timeline use
+
+## Technical Notes
+
+* Files inspected:
+  * `coding-deepgent/src/coding_deepgent/sessions/records.py`
+  * `coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py`
+  * `coding-deepgent/tests/test_sessions.py`
+  * `coding-deepgent/tests/test_cli.py`
+  * `.trellis/spec/backend/session-compact-contracts.md`
+* Current likely ownership boundary:
+  * append-time field definition -> `sessions/records.py`
+  * widened load path -> `sessions/store_jsonl.py`
+  * caller/test migration -> `tests/test_sessions.py`, `tests/test_cli.py`, `cli_service.py`
+  * compact/projection payloads remain separate from raw transcript message domain objects in this prerequisite
+
+## Decision (ADR-lite)
+
+**Context**: Collapse replay/timeline needs stable references, and the chosen direction is to expose them directly through `LoadedSession.history` rather than adding a parallel read surface first.
+
+**Decision**: Use Approach A — persist `message_id` and widen `LoadedSession.history` directly.
+
+**Consequences**:
+
+* Existing tests and callers that compare exact `{\"role\", \"content\"}` dicts will need updating or can be dropped if they only preserve the old shape.
+* This creates a simpler long-term model for Stage 3 collapse replay.
+* `LoadedSession.history` should no longer stay as bare dicts.
+* The remaining design question is `SessionMessage` 的最终字段边界，以及后续边界转换放在哪一层。
+
+## Decision (ADR-lite) - Local Representation
+
+**Context**: `sessions.records` already uses frozen dataclasses for session-level domain objects. Message-level identity is currently the missing domain object.
+
+**Decision**: Represent `SessionMessage` as a frozen dataclass in `sessions.records`, then convert explicitly at CLI/runtime/helper boundaries where dict payloads are still needed.
+
+**Consequences**:
+
+* This matches the existing `sessions.records` style better than TypedDict or Pydantic.
+* It gives Stage 3 collapse/timeline work a stronger domain boundary.
+* Existing callers such as `cli_service` and some tests will need explicit conversion helpers instead of `dict(message)` on plain dicts.
+* 用户优先级要求这里更偏向“把基础设施立住”，因此后续决策会偏向长期可扩展性，而不是最小 blast radius。
+
+## Decision (ADR-lite) - Field Boundary
+
+**Context**: The chosen direction is to build long-lived transcript infrastructure, not just patch current collapse prerequisites. At the same time, compact/projection payloads already have a different shape and should not be folded into the same migration.
+
+**Decision**: Use the balanced domain shape for `SessionMessage`:
+
+* `message_id`
+* `message_index`
+* `created_at`
+* `role`
+* `content`
+* `metadata: dict[str, Any] | None`
+
+Apply this only to raw `LoadedSession.history` in this prerequisite. Keep `LoadedSession.compacted_history` and compact artifact payloads on their current projection-oriented dict shape for now.
+
+**Consequences**:
+
+* Raw transcript becomes a proper typed domain surface for future collapse/timeline work.
+* `compacted_history` can be redesigned later as `ProjectionMessage` or similar instead of being forced into the raw-message model now.
+* Current CLI/resume callers must adapt from bare dicts to explicit conversion helpers.
+
+## Decision (ADR-lite) - Index Semantics
+
+**Context**: The user explicitly prefers long-term architecture and code elegance over carrying forward old infrastructure. The previous model used `message_index` and count-based compact replay because stable message identity did not exist yet.
+
+**Decision**: `message_index` should not remain a first-class domain field in `SessionMessage`.
+
+`SessionMessage` should expose only:
+
+* `message_id`
+* `created_at`
+* `role`
+* `content`
+* `metadata`
+
+Transcript order should come from append order, and future replay/timeline work should prefer stable `message_id` references over index math.
+
+**Consequences**:
+
+* The raw transcript domain model stays clean.
+* The next design question is the concrete reference shape for compact/collapse records.
+
+## Decision (ADR-lite) - Compact Record Direction
+
+**Context**: The current compact record schema still uses count/index semantics:
+
+* `original_message_count`
+* `summarized_message_count`
+* `kept_message_count`
+
+That model predates stable message identity and does not fit the new long-term transcript architecture.
+
+**Decision**: Redesign compact records now toward stable message references instead of preserving count/index semantics as the future foundation.
+
+**Consequences**:
+
+* Existing compact replay logic should be treated as an old boundary to be replaced, not carried forward as the canonical design.
+* Future compact/collapse/timeline work can share one message-reference model.
+* The remaining design question is whether current compact replay/load path should migrate now or in the next step.
+
+## Decision (ADR-lite) - Message Reference Shape
+
+**Context**: Compact/collapse/timeline all need message references, but the future system may include both contiguous transcript spans and more selective/non-contiguous hiding.
+
+**Decision**: Use a hybrid message-reference model:
+
+* primary range semantics:
+  * `start_message_id`
+  * `end_message_id`
+* optional explicit list for precise/non-contiguous cases:
+  * `covered_message_ids`
+
+This means:
+
+* contiguous compact/collapse can use range boundaries cleanly
+* future selective/snipped/non-contiguous views can still attach exact IDs
+* timeline and UI explanation can render both broad span and exact coverage
+
+**Consequences**:
+
+* This is more future-proof than pure range.
+* This is more efficient and readable than always storing only explicit ID lists.
+* Future compact/collapse record schemas should converge on the same reference primitive rather than inventing per-feature variants.
+
+## Decision (ADR-lite) - Migration Scope
+
+**Context**: The user explicitly prefers long-term infrastructure over preserving old compact/count semantics. Leaving current compact replay on the old count-based model would keep the old design alive right at the moment the new transcript foundation is introduced.
+
+**Decision**: In this prerequisite, migrate the current compact replay/load path to the new message-reference model at the same time as introducing `SessionMessage`.
+
+This means the work scope now includes:
+
+* new persisted `message_id`
+* typed `SessionMessage`
+* redesigned compact record schema using message references
+* `load_session()` compact replay based on stable message references
+
+**Consequences**:
+
+* The prerequisite becomes larger, but the transcript/compact foundation stays coherent.
+* Stage 3 collapse work can build on one reference model instead of crossing old/new compact semantics.
+* The remaining design question is the minimal long-term compact record shape.
+
+## Decision (ADR-lite) - Legacy Compact Records
+
+**Context**: The user explicitly prefers architecture clarity over carrying old compact/count semantics forward. Legacy compact records are based on count/index math and do not match the new stable message-reference foundation.
+
+**Decision**: Do not support legacy transcript or legacy compact schemas in the new foundation.
+
+Behavior:
+
+* new `load_session()` / replay path targets only the new typed transcript + new compact schema
+* no fallback to raw-history-as-compacted-view for legacy compact data
+* no synthetic legacy `message_id` generation
+* unsupported old data formats may fail fast instead of entering dual-read compatibility paths
+
+**Consequences**:
+
+* No dual-read compatibility branch is needed.
+* No offline migration tool is required.
+* The new transcript/compact replay path stays clean and reference-based from day one.
+
+## Decision (ADR-lite) - Compact Record Shape
+
+**Context**: With stable `message_id` and no legacy-compatibility burden, compact records should become durable transcript-reference events rather than count/index summaries.
+
+**Decision**: Use this new compact record shape as the long-term foundation:
+
+* `record_type: "compact"`
+* `version`
+* `session_id`
+* `timestamp`
+* `trigger`
+* `summary`
+* `start_message_id`
+* `end_message_id`
+* optional `covered_message_ids`
+* optional `metadata`
+
+**Consequences**:
+
+* Compact replay can move to stable message references immediately.
+* The same reference primitive can be reused by future collapse/timeline work.
+* The remaining design question is whether raw messages should also move into the same event family now.
+
+## Decision (ADR-lite) - Transcript Event Family
+
+**Context**: The user wants a long-term clean foundation for compact/collapse/timeline rather than separate feature-local record types.
+
+**Decision**: Use one transcript event family with multiple concrete event kinds, instead of separate long-term record type families for compact and collapse.
+
+Proposed direction:
+
+* one transcript-event family
+* `event_kind` distinguishes:
+  * `compact`
+  * `collapse`
+  * future `snip` / related projection events if needed
+
+**Consequences**:
+
+* compact/collapse/timeline can share one event ingestion and replay model
+* future projection features do not need to invent new per-feature persistence shapes
+* the remaining design question is whether events should use a generic envelope shape or flatter per-event fields
+
+## Decision (ADR-lite) - Raw Messages vs Events
+
+**Context**: Raw transcript messages and derived projection events are both durable facts, but they are not the same kind of fact. Raw messages are the source transcript primitive; compact/collapse are derived event overlays on top of that primitive.
+
+**Decision**: Keep raw messages as a distinct primitive. Do not fold them into the transcript event family.
+
+**Consequences**:
+
+* `SessionMessage` remains the raw transcript domain object.
+* `compact` / `collapse` / future projection events live in the transcript event family.
+* Replay/timeline can operate on a clean `messages + events` model instead of one overloaded event type.
+
+## Decision (ADR-lite) - Storage Ledger
+
+**Context**: The user prefers a long-term clean infrastructure, but also selected a single append-only session ledger rather than splitting transcript events into a second file.
+
+**Decision**: Store raw messages and transcript events in the same append-only JSONL ledger.
+
+This means the session ledger may contain multiple durable record families, for example:
+
+* raw message records
+* transcript event records
+* state snapshots
+* evidence
+
+**Consequences**:
+
+* event/message ordering stays naturally aligned in one time-ordered ledger
+* timeline/replay does not need cross-file merge logic
+* the remaining design question is the concrete `transcript_event` record shape
+
+## Decision (ADR-lite) - Message ID Generation
+
+**Context**: The user wants long-lived infrastructure rather than a minimal local patch. For future collapse replay, timeline, and debugging, IDs should be readable, deterministic, and aligned with the current append-only session model.
+
+**Decision**: Use session-scoped deterministic message IDs generated from append order / `message_index`, not random UUIDs or content hashes.
+
+Expected shape:
+
+* stable per session
+* deterministic at append time
+* readable in logs/tests/debugging
+
+Examples:
+
+* `msg-000000`
+* `msg-000001`
+
+or equivalent deterministic formatting.
+
+**Consequences**:
+
+* New messages get stable IDs without introducing randomness.
+* The ID model remains aligned with the current append-only / contiguous-index recording flow.
+* Since legacy compatibility is no longer the leading constraint, we can redesign transcript loading around the new typed model instead of preserving the old dict shape.
diff --git a/.trellis/tasks/archive/2026-04/04-16-stable-message-ids-compression-projection/task.json b/.trellis/tasks/archive/2026-04/04-16-stable-message-ids-compression-projection/task.json
new file mode 100644
index 000000000..b9931f4ba
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-stable-message-ids-compression-projection/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "stable-message-ids-compression-projection",
+  "name": "stable-message-ids-compression-projection",
+  "title": "stable message ids for compression projection",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-16",
+  "completedAt": "2026-04-17",
+  "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-16-context-compression-staged-implementation-plan",
+  "relatedFiles": [],
+  "notes": "Shipped as Stage 3 split prerequisite. Persisted message_id, SessionMessage typed record, transcript_event family, redesigned compact record schema with message references. See parent plan Stage 3 Collapse Store APPROVE checkpoint. ADR-lite decisions documented in prd.md.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-16-structured-compaction-result/check.jsonl b/.trellis/tasks/archive/2026-04/04-16-structured-compaction-result/check.jsonl
new file mode 100644
index 000000000..d4870a45f
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-structured-compaction-result/check.jsonl
@@ -0,0 +1,6 @@
+{"file": ".cursor/commands/trellis-finish-work.md", "reason": "Finish work checklist"}
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
+{"file": ".trellis/tasks/04-16-structured-compaction-result/prd.md", "reason": "active acceptance criteria"}
+{"file": ".trellis/tasks/04-16-cc-style-autocompact-hardening/prd.md", "reason": "source hardening checks"}
+{"file": ".trellis/spec/backend/runtime-pressure-contracts.md", "reason": "runtime pressure checks"}
+{"file": "coding-deepgent/tests/test_runtime_pressure.py", "reason": "focused tests"}
diff --git a/.trellis/tasks/archive/2026-04/04-16-structured-compaction-result/debug.jsonl b/.trellis/tasks/archive/2026-04/04-16-structured-compaction-result/debug.jsonl
new file mode 100644
index 000000000..e30f96d49
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-structured-compaction-result/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-16-structured-compaction-result/implement.jsonl b/.trellis/tasks/archive/2026-04/04-16-structured-compaction-result/implement.jsonl
new file mode 100644
index 000000000..114f754b0
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-structured-compaction-result/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": ".trellis/tasks/04-16-structured-compaction-result/prd.md", "reason": "active structured compaction result PRD"}
+{"file": ".trellis/tasks/04-16-cc-style-autocompact-hardening/prd.md", "reason": "source hardening PRD"}
+{"file": ".trellis/spec/backend/runtime-pressure-contracts.md", "reason": "runtime pressure contract"}
+{"file": "coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py", "reason": "live compaction implementation seam"}
diff --git a/.trellis/tasks/archive/2026-04/04-16-structured-compaction-result/prd.md b/.trellis/tasks/archive/2026-04/04-16-structured-compaction-result/prd.md
new file mode 100644
index 000000000..898a355f4
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-structured-compaction-result/prd.md
@@ -0,0 +1,102 @@
+# structured compaction result
+
+## Goal
+
+Introduce a local structured result for live compaction/collapse rendering so later restoration contributions and hooks can add bounded messages without duplicating ordering logic.
+
+## Expected Effect
+
+Live AutoCompact/Collapse should have one explicit object describing boundary, summary, restoration messages, preserved tail, trigger, and estimated token counts. Rendering order becomes testable and extensible.
+
+## Requirements
+
+- Add `LiveCompactionResult` or equivalent local dataclass.
+- Include boundary message, summary message, restoration messages, preserved tail, trigger, and estimated pre/post token counts.
+- Provide one render function/method that emits final model-facing messages in stable order.
+- Use the structured result internally for live AutoCompact and live Collapse.
+- Preserve current public helper return types where possible.
+- Keep raw transcript unchanged.
+- Keep current restoration-path behavior compatible.
+
+## Acceptance Criteria
+
+- [ ] AutoCompact uses structured result internally.
+- [ ] Collapse uses structured result internally.
+- [ ] Final message order is covered by focused tests.
+- [ ] Runtime event metadata can use structured result metadata.
+- [ ] Current live compact/collapse helper behavior remains compatible.
+- [ ] Runtime pressure contract updated.
+- [ ] Focused tests, ruff, and targeted mypy pass.
+
+## Source Evidence
+
+- `/root/claude-code-haha/src/services/compact/compact.ts`
+- Source PRD: `.trellis/tasks/04-16-cc-style-autocompact-hardening/prd.md`
+
+## Out of Scope
+
+- No new restoration contribution providers in this sub-stage.
+- No PreCompact/PostCompact hooks yet.
+- No session schema migration.
+- No provider cache sharing.
+
+## Status
+
+Checkpoint complete.
+
+State: checkpoint
+
+Verdict: APPROVE
+
+Implemented:
+
+- Added `LiveCompactionResult` with boundary, summary, restoration messages,
+  preserved tail, trigger, restored-path count, and estimated token fields.
+- Added `compact_live_messages_with_result(...)`.
+- Added `collapse_live_messages_with_result(...)`.
+- Kept `compact_live_messages_with_summary(...)` and
+  `collapse_live_messages_with_summary(...)` as list-return compatibility
+  wrappers.
+- Added render-order tests for compact and collapse.
+- Updated runtime pressure contracts.
+
+Verification:
+
+- `pytest -q tests/test_runtime_pressure.py` -> 37 passed.
+- `pytest -q tests/test_app.py` -> 9 passed.
+- `ruff check src/coding_deepgent/compact/runtime_pressure.py src/coding_deepgent/compact/__init__.py src/coding_deepgent/sessions/evidence_events.py src/coding_deepgent/settings.py src/coding_deepgent/containers/app.py tests/test_runtime_pressure.py tests/test_app.py` -> passed.
+- `mypy src/coding_deepgent/compact/runtime_pressure.py src/coding_deepgent/sessions/evidence_events.py src/coding_deepgent/settings.py src/coding_deepgent/containers/app.py` -> passed.
+
+Alignment:
+
+- source files inspected:
+  - `/root/claude-code-haha/src/services/compact/compact.ts`
+  - `/root/claude-code-haha/src/services/compact/autoCompact.ts`
+- aligned:
+  - structured result object for consistent post-compact message ordering
+  - explicit metadata for restoration and token estimates
+- deferred:
+  - restoration contribution providers
+  - PreCompact/PostCompact hooks
+- do-not-copy:
+  - cc UI progress lifecycle
+  - provider cache-sharing details
+
+Architecture:
+
+- primitive used: local dataclass plus existing live projection helpers.
+- why no heavier abstraction: this is a stable return object for one domain
+  boundary, not a new runtime subsystem.
+
+Boundary findings:
+
+- Existing public helper behavior remains list-compatible.
+- No raw transcript mutation introduced.
+
+Decision: continue
+
+Reason:
+
+- The sub-stage is complete and verified.
+- Parent plan next stage can now add restoration messages through the structured
+  result boundary instead of editing render order ad hoc.
diff --git a/.trellis/tasks/archive/2026-04/04-16-structured-compaction-result/task.json b/.trellis/tasks/archive/2026-04/04-16-structured-compaction-result/task.json
new file mode 100644
index 000000000..ca8c608e2
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-structured-compaction-result/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "structured-compaction-result",
+  "name": "structured-compaction-result",
+  "title": "structured compaction result",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-16",
+  "completedAt": "2026-04-16",
+  "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-16-context-compression-staged-implementation-plan",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-16-token-budget-tool-output-prune/check.jsonl b/.trellis/tasks/archive/2026-04/04-16-token-budget-tool-output-prune/check.jsonl
new file mode 100644
index 000000000..79684a0d0
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-token-budget-tool-output-prune/check.jsonl
@@ -0,0 +1,6 @@
+{"file": ".cursor/commands/trellis-finish-work.md", "reason": "Finish work checklist"}
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
+{"file": ".trellis/tasks/04-16-token-budget-tool-output-prune/prd.md", "reason": "active token-budget pruning acceptance criteria"}
+{"file": ".trellis/tasks/04-15-opencode-style-auto-tool-output-prune/prd.md", "reason": "source planning acceptance criteria"}
+{"file": ".trellis/spec/backend/runtime-pressure-contracts.md", "reason": "runtime pressure checks"}
+{"file": "coding-deepgent/tests/test_runtime_pressure.py", "reason": "focused tests"}
diff --git a/.trellis/tasks/archive/2026-04/04-16-token-budget-tool-output-prune/debug.jsonl b/.trellis/tasks/archive/2026-04/04-16-token-budget-tool-output-prune/debug.jsonl
new file mode 100644
index 000000000..e30f96d49
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-token-budget-tool-output-prune/debug.jsonl
@@ -0,0 +1 @@
+{"file": ".cursor/commands/trellis-check-backend.md", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-16-token-budget-tool-output-prune/implement.jsonl b/.trellis/tasks/archive/2026-04/04-16-token-budget-tool-output-prune/implement.jsonl
new file mode 100644
index 000000000..34da0209e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-token-budget-tool-output-prune/implement.jsonl
@@ -0,0 +1,7 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": ".trellis/tasks/04-16-token-budget-tool-output-prune/prd.md", "reason": "active token-budget pruning PRD"}
+{"file": ".trellis/tasks/04-15-opencode-style-auto-tool-output-prune/prd.md", "reason": "source planning PRD"}
+{"file": ".trellis/tasks/04-16-runtime-pressure-token-saved-evidence/prd.md", "reason": "stats evidence checkpoint"}
+{"file": ".trellis/spec/backend/runtime-pressure-contracts.md", "reason": "runtime pressure contract"}
+{"file": "coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py", "reason": "implementation seam"}
diff --git a/.trellis/tasks/archive/2026-04/04-16-token-budget-tool-output-prune/prd.md b/.trellis/tasks/archive/2026-04/04-16-token-budget-tool-output-prune/prd.md
new file mode 100644
index 000000000..0d7b453d6
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-token-budget-tool-output-prune/prd.md
@@ -0,0 +1,111 @@
+# token budget tool output prune
+
+## Goal
+
+把普通 MicroCompact 的 count-based keep policy 升级为可选 token-budget protected policy：保留最近一段可压缩工具输出 token budget 内的结果，清理更旧的 eligible tool results，并复用前两个 sub-stage 的 bounded savings evidence。
+
+## Expected Effect
+
+当工具输出大小差异很大时，单纯保留最近 N 个结果并不稳定。token-budget policy 应让模型保留“最近约 N tokens 的工具输出上下文”，更接近 opencode `SessionCompaction.prune()` 的本地价值，同时保持当前 transcript 非破坏性。
+
+## Requirements
+
+- Add settings-backed optional `microcompact_protect_recent_tokens: int | None`.
+- Add settings-backed `microcompact_min_prune_saved_tokens: int`.
+- When `microcompact_protect_recent_tokens is None`, preserve existing count-based MicroCompact behavior.
+- When configured, walk compactable successful tool results from newest to oldest:
+  - keep recent compactable outputs while the protected token budget allows,
+  - always keep at least one most-recent compactable tool result,
+  - clear older eligible results outside the protected budget.
+- Do not clear protected/ineligible semantic tools such as memory, task, plan, skill, verifier, subagent.
+- Skip pruning when estimated savings are below `microcompact_min_prune_saved_tokens`.
+- Preserve tool-call/tool-result pairing, ordering, `tool_call_id`, `status`, `artifact`, and persisted output path markers.
+- Continue to emit bounded runtime event/evidence metadata from `MicrocompactStats`.
+
+## Acceptance Criteria
+
+- [ ] Default settings keep existing count-based behavior.
+- [ ] Token-budget mode keeps recent compactable tool results under/around the protected budget.
+- [ ] Token-budget mode always keeps at least one compactable result.
+- [ ] Ineligible and error tool results are not rewritten.
+- [ ] Savings threshold can skip low-value pruning without emitting an event.
+- [ ] Persisted output paths remain model-visible after pruning.
+- [ ] Runtime event/evidence uses bounded `tools_cleared`, `tools_kept`, `tokens_saved_estimate`, and `keep_recent`.
+- [ ] `.trellis/spec/backend/runtime-pressure-contracts.md` is updated.
+- [ ] Focused runtime pressure/app tests, ruff, and targeted mypy pass.
+
+## Source Evidence
+
+- `/root/claude-code-haha/src/services/compact/microCompact.ts`
+- `sst/opencode` reference in source PRD remains planning evidence; local implementation must stay LangChain-native and deterministic.
+
+## Out of Scope
+
+- No provider exact tokenizer.
+- No provider cache-edit/cache-reference payloads.
+- No physical transcript deletion.
+- No cc-style semantic SnipTool.
+
+## Status
+
+Checkpoint complete.
+
+State: checkpoint
+
+Verdict: APPROVE
+
+Implemented:
+
+- Added optional settings-backed `microcompact_protect_recent_tokens`.
+- Added `microcompact_min_prune_saved_tokens`.
+- Preserved default count-based MicroCompact behavior when token budget is not configured.
+- Added token-budget suffix protection for ordinary MicroCompact.
+- Kept at least one newest compactable tool result even when it exceeds budget.
+- Added savings-threshold skip without event emission.
+- Added bounded `protected_recent_tokens` runtime event/evidence metadata.
+- Updated runtime pressure contracts.
+
+Verification:
+
+- `pytest -q tests/test_runtime_pressure.py` -> 30 passed.
+- `pytest -q tests/test_app.py` -> 9 passed.
+- `ruff check src/coding_deepgent/compact/runtime_pressure.py src/coding_deepgent/compact/__init__.py src/coding_deepgent/sessions/evidence_events.py src/coding_deepgent/settings.py src/coding_deepgent/containers/app.py tests/test_runtime_pressure.py tests/test_app.py` -> passed.
+- `mypy src/coding_deepgent/compact/runtime_pressure.py src/coding_deepgent/sessions/evidence_events.py src/coding_deepgent/settings.py src/coding_deepgent/containers/app.py` -> passed.
+
+Alignment:
+
+- source files inspected:
+  - `/root/claude-code-haha/src/services/compact/microCompact.ts`
+  - `/root/claude-code-haha/src/services/compact/timeBasedMCConfig.ts`
+- aligned:
+  - compactable-tool allowlist via local `ToolCapability.microcompact_eligible`
+  - newest-to-oldest protection policy
+  - minimum-savings guard
+- deferred:
+  - exact opencode constants
+  - provider exact tokenizer
+  - persisted compacted marker/state
+- do-not-copy:
+  - provider cache editing
+  - physical transcript deletion
+
+Architecture:
+
+- primitive used: existing deterministic live model-call projection helper.
+- why no heavier abstraction: token-budget pruning is a policy variant inside
+  the existing MicroCompact boundary.
+
+Boundary findings:
+
+- No session schema migration needed.
+- No new tool/system prompt surface.
+- Time-based MicroCompact remains first when its trigger fires.
+
+Decision: continue
+
+Reason:
+
+- Stage 1 is complete and verified.
+- Parent plan next stage remains valid: AutoCompact reliability can build on the
+  same runtime pressure event/evidence seams without changing MicroCompact
+  semantics further.
diff --git a/.trellis/tasks/archive/2026-04/04-16-token-budget-tool-output-prune/task.json b/.trellis/tasks/archive/2026-04/04-16-token-budget-tool-output-prune/task.json
new file mode 100644
index 000000000..69bb82535
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-16-token-budget-tool-output-prune/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "token-budget-tool-output-prune",
+  "name": "token-budget-tool-output-prune",
+  "title": "token budget tool output prune",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-16",
+  "completedAt": "2026-04-16",
+  "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-16-context-compression-staged-implementation-plan",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-17-cc-core-topology-closeout-plan/prd.md b/.trellis/tasks/archive/2026-04/04-17-cc-core-topology-closeout-plan/prd.md
new file mode 100644
index 000000000..9add30a15
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-cc-core-topology-closeout-plan/prd.md
@@ -0,0 +1,364 @@
+# cc core topology closeout plan
+
+## Goal
+
+还原并固化 2026-04-17 cc-highlight alignment 讨论后拍板的拓扑执行计划，把散落在 H01、H11/H12、H19 research notes 中的待办拆成可执行 Trellis tasks。
+
+## Restored Source
+
+本计划来自与另一个 agent 的聊天记录，并以仓库中已有材料校验：
+
+* `.trellis/tasks/04-16-cc-highlight-alignment-discussion/prd.md`
+* `.trellis/tasks/04-16-cc-highlight-alignment-discussion/h11-h12-alignment-research.md`
+* `.trellis/tasks/04-16-cc-highlight-alignment-discussion/h19-observability-alignment-research.md`
+* `.trellis/plans/coding-deepgent-h01-tool-module-alignment-plan.md`
+* `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+
+## Canonical Single-Line Status
+
+Current source of truth:
+
+* Parent task: this task.
+* Done: H19 vertical closeout (`L1-b`, `L2-b`, `L3-b`) and H01 five-factor audit (`L1-c`).
+* Next: `L2-a H11/H12 AgentDefinition + real read-only general runtime`.
+* Then: `L2-c` / `L3-c` H01 role projection and dynamic tool pool.
+* Then: `L3-a` sidechain transcript, `L4` H01 research/tests/audits, `L5-a` only if LangChain research proves an adapter is needed.
+* Docs-only tail: `L5-b` deferred-boundary ADR refresh and `L5-c` dashboard refresh.
+
+## Topology
+
+### Layer 1
+
+* `L1-a`: task ledger cleanup. Status: completed during restoration; old completed/planning tasks were archived with `--no-commit`.
+* `L1-b`: H19-A queued-until-sink event sink + agent-scoped logger helper.
+* `L1-c`: H01-#1 five-factor capability audit.
+
+### Layer 2
+
+* `L2-a`: H11/H12-A AgentDefinition schema, general+verifier catalog, real general child runtime, structured result envelope, fallback text scan. Depends on `L1-c`.
+* `L2-b`: H19-B compact observability trio: B2 split, B3 canary, B4 orphan tombstoned. Depends on `L1-b`.
+* `L2-c`: H01-#2 role-based tool projection foundation. Depends on `L1-c` and `L2-a`.
+
+### Layer 3
+
+* `L3-a`: H11/H12-B subagent sidechain transcript with `parent_message_id` and `subagent_thread_id`. Depends on `L2-a`.
+* `L3-b`: H19-C structured `query_error`, per-turn `token_budget`, env-gated API dump. Depends on `L1-b` and `L2-b`.
+* `L3-c`: H01-#3 dynamic tool pool foundation. Depends on `L2-c`.
+
+### Layer 4
+
+* `L4-a`: H01-#4 LangChain parallel tool-call research spike. Depends on `L2-c`.
+* `L4-b`: H01-#5 tool_use/tool_result pairing and protocol-correct failure tests. Depends on `L2-c` and `L3-c`.
+* `L4-c`: H01-#6 result persistence / microcompact eligibility review. Depends on `L3-c`.
+
+### Layer 5
+
+* `L5-a`: conditional non-streaming partition adapter, only if `L4-a` proves LangChain behavior is insufficient.
+* `L5-b`: deferred boundary ADR refresh for H11/H12 + H13/H14/H21/H22 + H19 deferred items.
+* `L5-c`: canonical dashboard refresh for H11/H12/H19 after closeout.
+
+## Execution Rules
+
+* H19 closeout is no longer on the critical path; `L1-b`, `L2-b`, and `L3-b` are complete.
+* H01 five-factor audit is no longer on the critical path; `L1-c` is complete.
+* Start next with `L2-a`; do not create another H01 or H11/H12 parent task.
+* `L2-c` should wait for `L2-a` so role-based projection can validate against the real general child runtime.
+* Keep H01 tool work LangChain-native: prefer strict Pydantic tool schemas, `ToolCapability`, middleware, and existing `create_agent` surfaces before adding custom orchestration.
+* Keep H19 observability local and bounded: no external analytics backend, Perfetto, or streaming event system in this closeout.
+* Keep H11/H12 bounded: read-only general subagent, `general=25` / `verifier=5`, no background agent lifecycle, no mailbox, no full fork/cache parity.
+
+## Acceptance Criteria
+
+* [x] Old completed/planning tasks from L1-a no longer remain active.
+* [x] Parent Trellis task exists with child task links for remaining topology items.
+* [x] Each child task has a PRD with dependencies and acceptance criteria.
+* [x] H19 vertical closeout is represented as done, not as the next planning blocker.
+* [x] `L1-c` is represented as done, not as the next planning blocker.
+* [x] `L2-a` is documented as the only next implementation entry point.
+* [x] Remaining topology items were executed through normal Trellis task workflow, with `L5-a` explicitly closed as unnecessary based on completed `L4-a` / `L4-b` / `L4-c` evidence.
+
+## Checkpoint: H19 Closeout
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- `L1-b`: queued `RuntimeEventSink` with ordered drain semantics and agent-scoped logger helper.
+- `L2-b`: AutoCompact attempted/succeeded events, `post_autocompact_turn` canary metrics, and bounded `orphan_tombstoned` projection repair.
+- `L3-b`: structured `query_error` evidence, per-response `token_budget` event, and env-gated `CODING_DEEPGENT_DUMP_PROMPTS=1` model request dump.
+
+Verification:
+- Focused `coding-deepgent` tests for runtime pressure, sessions, CLI, app wiring, and new H19 event/projection/logger coverage passed.
+- `ruff check` passed on modified Python files.
+- `mypy` passed on modified source modules and new H19-focused tests.
+
+Boundary:
+- No external analytics backend, Perfetto, streaming/TTFT, provider cache/cost, or CLI dump flag was added.
+- `L5-b` remains open for deferred-boundary ADR refresh; `L5-c` dashboard cleanup is complete.
+- This checkpoint does not claim H11/H12 completion.
+
+Decision:
+- continue
+
+## Checkpoint: H01 L1-c Capability Audit
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- `L1-c`: `ToolCapability` now carries explicit five-factor metadata, including `rendering_result`.
+- Registry construction validates capability name/tool name match, schema presence, non-unknown metadata, exposure values, and large-output/microcompact opt-in consistency.
+- Focused tests cover builtin capability metadata, safe opt-ins, MCP extension metadata, and invalid registry entries.
+
+Verification:
+- Focused H01 tests for registry, middleware, tools, tasks, subagents, MCP, tool-result storage, runtime pressure, app wiring, and permissions passed.
+- `ruff check` passed on modified H01 Python files.
+- `mypy` passed on modified H01 source/test files.
+
+Boundary:
+- No role-based projection behavior, dynamic tool pool, parallel tool orchestration, or streaming runtime was added.
+- Downstream H01 `L2-c`, `L3-c`, and `L4-*` tasks remain open.
+
+Decision:
+- continue
+
+## Checkpoint: H11/H12 L2-a Agent Definition Runtime
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- `L2-a`: added `AgentDefinition` catalog for `general` and `verifier`.
+- Replaced the `general` stub with a real read-only child `create_agent` invocation.
+- Routed verifier allowlist/max-turn settings through definitions while preserving plan-bound verifier behavior.
+- Added structured subagent result envelopes with local input/output/total token estimates, duration, and tool-use count.
+- Added fallback text extraction when the final child assistant message is tool-only.
+
+Verification:
+- Focused subagent/task/tool/app/runtime tests passed in the integrated bundle.
+- `ruff check` passed on modified files.
+- `mypy` passed on modified source/test files.
+
+Boundary:
+- Sidechain transcript persistence, background agents, mailbox, write-capable coder agents, and fork/cache parity remain out of scope.
+
+Decision:
+- continue
+
+## Checkpoint: H01 L2-c Role-Based Projection
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- `L2-c`: centralized role projection helpers for `main`, `child`, `extension`, and reserved `deferred` surfaces.
+- Added deferred projection as an explicit empty/future boundary without ToolSearch or runtime hot-swap.
+- Routed general/verifier child tools through `AgentDefinition` plus child capability metadata.
+- Added tests for deterministic main/child/extension/deferred projections and extension metadata preservation.
+
+Verification:
+- Focused registry/subagent checks passed.
+- Included in the integrated focused validation bundle.
+- `ruff check` and `mypy` passed on modified files.
+
+Boundary:
+- No dynamic tool pool hot-swap, deferred schema discovery, or parallel tool-call orchestration was added.
+
+Decision:
+- continue
+
+## Checkpoint: H11/H12 L3-a Sidechain Transcript
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- `L3-a`: persisted bounded subagent sidechain transcript entries into the parent session JSONL ledger.
+- Added `parent_message_id`, `parent_thread_id`, and `subagent_thread_id` linkage for child transcript entries.
+- Loaded sidechain transcript through `LoadedSession.sidechain_messages` without exposing it to main resume/compact/collapse projections.
+
+Verification:
+- Focused sessions/subagent tests passed.
+- Included in the integrated focused validation bundle.
+- `ruff check` and `mypy` passed on modified files.
+
+Boundary:
+- No per-agent transcript directories, subagent resume, or background lifecycle were added.
+
+Decision:
+- continue
+
+## Checkpoint: H01 L3-c Dynamic Tool Pool Foundation
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- `L3-c`: added explicit `ToolPoolProjection` seam and `registry.project(...)` API for `main`, `child`, `extension`, and reserved `deferred` surfaces.
+- Preserved extension source/trust metadata through projection and kept startup/runtime simple.
+- Added deterministic projection validation and tests for invalid projection states.
+
+Verification:
+- Focused registry/subagent/app/CLI/session tests passed.
+- Included in the integrated focused validation bundle.
+- `ruff check` and `mypy` passed on modified files.
+
+Boundary:
+- No hot-swap runtime, ToolSearch, or streaming tool execution was added.
+
+Decision:
+- continue
+
+## Checkpoint: H01 L4-a Parallel Tool-Call Research
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- `L4-a`: completed a source-backed research spike on LangChain parallel tool-call behavior.
+- Confirmed from official docs and local installed source that `ToolNode` already parallelizes non-streaming multi-tool execution and preserves original tool-call order.
+- Recorded recommendation to keep `L5-a` conditional/spec-only unless `L4-b` / `L4-c` expose a concrete capability-aware partitioning failure.
+
+Verification:
+- Research note captured under the task directory.
+- No product runtime code changes were introduced for this task.
+
+Boundary:
+- No partition adapter or streaming executor was added.
+
+Decision:
+- continue
+
+## Checkpoint: H01 L4-b Pairing And Failure Tests
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- `L4-b`: added focused protocol-failure tests for unknown tool, permission denial, hook block, and tool exception behavior.
+- Added minimal hardening so tool handler exceptions return bounded `ToolMessage(status="error")` with the original `tool_call_id`.
+- Added pairing tests proving tool-use/tool-result matching remains id-based across dynamic/projection tool names.
+
+Verification:
+- Focused middleware/projection/compact/planning tests passed.
+- `ruff check` and `mypy` passed on touched files.
+
+Boundary:
+- No custom execution engine, streaming repair, or runtime partition adapter was added.
+
+Decision:
+- continue
+
+## Checkpoint: H01 L4-c Result Persistence Audit
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- `L4-c`: completed the result persistence / microcompact eligibility audit.
+- Confirmed current opt-ins remain valid for `bash`, `read_file`, `glob`, and `grep`.
+- Clarified the contract that microcompact eligibility is still valid when old
+  output is recoverable through persisted-output paths even if replaying the
+  original tool call is unsafe.
+
+Verification:
+- Focused tool-result-storage / registry / runtime-pressure tests passed.
+- `ruff check` passed on touched files.
+- `mypy` passed on touched source/test files; broader `test_runtime_pressure.py`
+  mypy noise remains the pre-existing fake-ModelRequest issue outside this task.
+
+Boundary:
+- No capability metadata changes, new persistence backend, or provider-specific
+  instrumentation were added.
+
+Decision:
+- continue
+
+## Checkpoint: L5-b Deferred Boundary ADR Refresh
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- `L5-b`: added a refreshed deferred-boundary ADR at
+  `.trellis/plans/coding-deepgent-deferred-boundary-refresh-adr.md`
+- merged old Stage 29 deferrals with the concrete deferred boundaries established
+  by H01/H11/H12/H19 closeout work
+- updated `project-handoff.md` so resume context points at the current tail and
+  no longer suggests already-completed implementation tasks
+
+Verification:
+- ADR links back to the old Stage 29 deferred note and current source-backed
+  research notes
+- touched JSON/task metadata remains valid
+
+Boundary:
+- no deferred runtime feature was implemented
+
+Decision:
+- continue
+
+## Checkpoint: L5-c Dashboard Refresh
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- `L5-c`: refreshed the canonical roadmap/dashboard rows for H01, H11, H12, and H19
+- aligned roadmap wording with the now-completed H01/H11/H12/H19 topology work
+- moved deferred/full-lifecycle wording to the refreshed deferred-boundary ADR so the dashboard reads as implemented vs deferred, not accidentally missing
+
+Verification:
+- touched task JSON remains valid
+- roadmap and handoff now point to the current post-closeout tail correctly
+
+Boundary:
+- no product/runtime code changed
+
+Decision:
+- terminal
+
+## Final Closeout Decision (2026-04-19)
+
+* `L5-a` is now explicitly closed as a spec-only rejection task rather than a pending implementation item.
+* The closeout decision is backed by `L4-a` research showing upstream LangChain `ToolNode` already satisfies the non-streaming parallel baseline, plus `L4-b` / `L4-c` validation that found no concrete capability-aware partitioning failure.
+* This parent topology plan is therefore complete and can be archived without adding a local non-streaming partition adapter.
+
+## Out of Scope
+
+* Implementing product code in this parent planning task.
+* Reopening H13/H14/H21/H22 implementation.
+* Treating historical Stage 30A/30B as canonical current baseline.
diff --git a/.trellis/tasks/archive/2026-04/04-17-cc-core-topology-closeout-plan/task.json b/.trellis/tasks/archive/2026-04/04-17-cc-core-topology-closeout-plan/task.json
new file mode 100644
index 000000000..0a4aee7e6
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-cc-core-topology-closeout-plan/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "cc-core-topology-closeout-plan",
+  "name": "cc-core-topology-closeout-plan",
+  "title": "cc core topology closeout plan",
+  "description": "Parent topology plan for H01/H11-H12/H19 closeout work restored from cc-highlight alignment discussion.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-17",
+  "completedAt": "2026-04-19",
+  "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": "Checkpoint 2026-04-17: H19 vertical closeout completed for L1-b, L2-b, and L3-b in one integrated implementation. Covered queued RuntimeEventSink/logger helper, AutoCompact attempted/succeeded and post_autocompact_turn canary metrics, orphan_tombstoned projection repair, structured query_error evidence, token_budget runtime events, and env-gated prompt/API dumps. H01 L1-c five-factor capability audit is complete. L5-c dashboard cleanup completed; L5-b deferred-boundary ADR remains open. Next implementation entry point is L2-a H11/H12 AgentDefinition and real read-only general runtime. Checkpoint 2026-04-17: H11/H12 L2-a completed. Added AgentDefinition catalog for general/verifier, real read-only general child runtime, verifier definition reuse, structured result envelopes, and fallback text extraction. Sidechain transcript, background agents, mailbox, and fork/cache parity remain open/deferred. Checkpoint 2026-04-17: H01 L2-c role-based projection completed. Registry projection helpers now cover main/child/extension/deferred surfaces, extension source/trust metadata is preserved through projection, and general/verifier child pools derive from definitions plus child capability metadata. Dynamic tool hot-swap and ToolSearch remain out of scope. Checkpoint 2026-04-18: H11/H12 L3-a sidechain transcript completed. Parent session JSONL now records bounded child sidechain entries with parent_message_id / parent_thread_id / subagent_thread_id linkage and loads them through sidechain_messages without entering main projections. Checkpoint 2026-04-18: H01 L3-c dynamic tool pool foundation completed. Registry now exposes explicit ToolPoolProjection results for main/child/extension/deferred surfaces, with deterministic validation and no ToolSearch or hot-swap runtime. Checkpoint 2026-04-18: H01 L4-a parallel tool-call research completed. Official LangChain docs and local ToolNode source confirm built-in non-streaming parallel execution with preserved tool-call order; L5-a is downgraded to conditional/spec-only unless L4-b/L4-c expose a real capability-aware partitioning failure. Checkpoint 2026-04-18: H01 L4-b pairing and failure tests completed. Tool exceptions now collapse to bounded ToolMessage errors with preserved tool_call_id, and pairing tests confirm id-based tool_use/tool_result matching remains stable across dynamic/projection tool names. Checkpoint 2026-04-18: H01 L4-c result persistence audit completed. Current persist_large_output and microcompact_eligible opt-ins for bash/read_file/glob/grep remain valid because persisted-output paths preserve recoverability; no capability metadata change was needed. Checkpoint 2026-04-18: L5-b deferred-boundary ADR refresh completed. A new ADR at .trellis/plans/coding-deepgent-deferred-boundary-refresh-adr.md now supersedes the older Stage 29 note for H11/H12/H19/H01-adjacent deferred items, and project-handoff has been refreshed to point at the current topology tail. Checkpoint 2026-04-18: L5-c dashboard refresh completed. Canonical roadmap rows for H01, H11, H12, and H19 now match the completed topology closeout work, while deferred/full-lifecycle scope is pushed into the refreshed deferred-boundary ADR.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-17-l1b-h19-event-sink-logger/check.jsonl b/.trellis/tasks/archive/2026-04/04-17-l1b-h19-event-sink-logger/check.jsonl
new file mode 100644
index 000000000..198349028
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l1b-h19-event-sink-logger/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/spec/backend/logging-guidelines.md", "reason": "Runtime event logging/evidence boundary"}
diff --git a/.trellis/tasks/archive/2026-04/04-17-l1b-h19-event-sink-logger/debug.jsonl b/.trellis/tasks/archive/2026-04/04-17-l1b-h19-event-sink-logger/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l1b-h19-event-sink-logger/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-17-l1b-h19-event-sink-logger/implement.jsonl b/.trellis/tasks/archive/2026-04/04-17-l1b-h19-event-sink-logger/implement.jsonl
new file mode 100644
index 000000000..2d1eb8eed
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l1b-h19-event-sink-logger/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/logging-guidelines.md", "reason": "Runtime event logging/evidence boundary"}
diff --git a/.trellis/tasks/archive/2026-04/04-17-l1b-h19-event-sink-logger/prd.md b/.trellis/tasks/archive/2026-04/04-17-l1b-h19-event-sink-logger/prd.md
new file mode 100644
index 000000000..9a594bb92
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l1b-h19-event-sink-logger/prd.md
@@ -0,0 +1,35 @@
+# L1-b: H19 event sink and logger
+
+## Goal
+
+Implement H19-A: queued-until-sink runtime event emission plus an agent-scoped logger helper.
+
+## Requirements
+
+* Add buffered event behavior so events emitted before a concrete sink is attached are not silently lost.
+* Preserve a test/null sink for deterministic tests.
+* Add a small logger helper or convention that scopes debug output by agent/runtime component.
+* Keep the implementation local and synchronous/bounded; do not add an analytics backend.
+
+## Acceptance Criteria
+
+* [x] Events emitted before sink attachment are drained to the attached sink in order.
+* [x] Sink attachment is idempotent or explicitly rejects unsafe duplicate attachment.
+* [x] Existing runtime event/evidence tests still pass.
+* [x] Agent-scoped logger behavior is covered by focused tests or a documented convention.
+
+## Dependencies
+
+* None.
+
+## Context Sources
+
+* `.trellis/tasks/04-16-cc-highlight-alignment-discussion/h19-observability-alignment-research.md`
+* `.trellis/spec/backend/logging-guidelines.md`
+* `.trellis/spec/backend/runtime-pressure-contracts.md`
+
+## Out of Scope
+
+* External analytics backend.
+* Perfetto tracing.
+* Streaming/TTFT observability.
diff --git a/.trellis/tasks/archive/2026-04/04-17-l1b-h19-event-sink-logger/task.json b/.trellis/tasks/archive/2026-04/04-17-l1b-h19-event-sink-logger/task.json
new file mode 100644
index 000000000..8b11ef7ab
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l1b-h19-event-sink-logger/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l1b-h19-event-sink-logger",
+  "name": "l1b-h19-event-sink-logger",
+  "title": "L1-b H19 event sink and logger",
+  "description": "H19-A queued-until-sink runtime event sink plus agent-scoped logger helper.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-17",
+  "completedAt": "2026-04-19",
+  "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-17-cc-core-topology-closeout-plan",
+  "relatedFiles": [],
+  "notes": "Completed H19 L1-b in integrated closeout: added queued RuntimeEventSink behavior and agent-scoped logger helper with focused tests.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-17-l1c-h01-five-factor-capability-audit/check.jsonl b/.trellis/tasks/archive/2026-04/04-17-l1c-h01-five-factor-capability-audit/check.jsonl
new file mode 100644
index 000000000..c51a35772
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l1c-h01-five-factor-capability-audit/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": ".trellis/spec/backend/tool-capability-contracts.md", "reason": "Five-factor tool capability metadata contract"}
+{"file": ".trellis/spec/backend/langchain-native-guidelines.md", "reason": "LangChain-native tool/schema rules"}
+{"file": ".trellis/plans/coding-deepgent-h01-tool-module-alignment-plan.md", "reason": "H01 child 1 audit source plan"}
diff --git a/.trellis/tasks/archive/2026-04/04-17-l1c-h01-five-factor-capability-audit/debug.jsonl b/.trellis/tasks/archive/2026-04/04-17-l1c-h01-five-factor-capability-audit/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l1c-h01-five-factor-capability-audit/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-17-l1c-h01-five-factor-capability-audit/implement.jsonl b/.trellis/tasks/archive/2026-04/04-17-l1c-h01-five-factor-capability-audit/implement.jsonl
new file mode 100644
index 000000000..e2a2d5065
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l1c-h01-five-factor-capability-audit/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": ".trellis/spec/backend/tool-capability-contracts.md", "reason": "Five-factor tool capability metadata contract"}
+{"file": ".trellis/spec/backend/langchain-native-guidelines.md", "reason": "LangChain-native tool/schema rules"}
+{"file": ".trellis/plans/coding-deepgent-h01-tool-module-alignment-plan.md", "reason": "H01 child 1 audit source plan"}
diff --git a/.trellis/tasks/archive/2026-04/04-17-l1c-h01-five-factor-capability-audit/prd.md b/.trellis/tasks/archive/2026-04/04-17-l1c-h01-five-factor-capability-audit/prd.md
new file mode 100644
index 000000000..7ae8a06ad
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l1c-h01-five-factor-capability-audit/prd.md
@@ -0,0 +1,35 @@
+# L1-c: H01 five-factor capability audit
+
+## Goal
+
+Implement H01-#1: audit all registered model-facing capabilities against the five-factor protocol and add tests for safe metadata defaults.
+
+## Requirements
+
+* Verify every registered tool has explicit name, schema, permission, execution, and rendering/result metadata.
+* Fill missing `ToolCapability` metadata where the current defaults are too implicit.
+* Add or tighten tests around safe defaults, exposure, trust/source, large-output persistence, and microcompact eligibility.
+* Do not add new orchestration behavior in this task.
+
+## Acceptance Criteria
+
+* [x] Builtin and extension-projected tools have deterministic capability metadata.
+* [x] Unsafe or unknown tools do not default to read-only, concurrency-safe, trusted, persisted, or microcompact-eligible.
+* [x] Focused `tool_system` registry/middleware tests cover the audit.
+* [x] H01 plan can treat Child 1 as complete.
+
+## Dependencies
+
+* None.
+
+## Context Sources
+
+* `.trellis/plans/coding-deepgent-h01-tool-module-alignment-plan.md`
+* `.trellis/spec/backend/tool-capability-contracts.md`
+* `.trellis/spec/backend/langchain-native-guidelines.md`
+
+## Out of Scope
+
+* Role-based projection changes.
+* Dynamic tool pool.
+* Parallel tool-call orchestration.
diff --git a/.trellis/tasks/archive/2026-04/04-17-l1c-h01-five-factor-capability-audit/task.json b/.trellis/tasks/archive/2026-04/04-17-l1c-h01-five-factor-capability-audit/task.json
new file mode 100644
index 000000000..2496cc02e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l1c-h01-five-factor-capability-audit/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l1c-h01-five-factor-capability-audit",
+  "name": "l1c-h01-five-factor-capability-audit",
+  "title": "L1-c H01 five-factor capability audit",
+  "description": "H01 child 1: five-factor capability audit, projection tests, and missing tool metadata closeout.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-17",
+  "completedAt": "2026-04-19",
+  "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-17-cc-core-topology-closeout-plan",
+  "relatedFiles": [],
+  "notes": "Completed H01 child 1: ToolCapability now carries explicit five-factor metadata including rendering_result, registry construction validates name/schema/metadata/opt-in invariants, and focused registry/middleware/MCP tests cover safe defaults and extension metadata.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-17-l2a-h11-h12-agent-definition-general-runtime/check.jsonl b/.trellis/tasks/archive/2026-04/04-17-l2a-h11-h12-agent-definition-general-runtime/check.jsonl
new file mode 100644
index 000000000..7b94dfb77
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l2a-h11-h12-agent-definition-general-runtime/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": ".trellis/spec/backend/task-workflow-contracts.md", "reason": "Subagent and verifier runtime contracts"}
+{"file": ".trellis/spec/backend/langchain-native-guidelines.md", "reason": "LangChain-native child create_agent boundary"}
+{"file": ".trellis/tasks/04-16-cc-highlight-alignment-discussion/h11-h12-alignment-research.md", "reason": "H11/H12 source-backed gap matrix"}
diff --git a/.trellis/tasks/archive/2026-04/04-17-l2a-h11-h12-agent-definition-general-runtime/debug.jsonl b/.trellis/tasks/archive/2026-04/04-17-l2a-h11-h12-agent-definition-general-runtime/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l2a-h11-h12-agent-definition-general-runtime/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-17-l2a-h11-h12-agent-definition-general-runtime/implement.jsonl b/.trellis/tasks/archive/2026-04/04-17-l2a-h11-h12-agent-definition-general-runtime/implement.jsonl
new file mode 100644
index 000000000..2e1ab4540
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l2a-h11-h12-agent-definition-general-runtime/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": ".trellis/spec/backend/task-workflow-contracts.md", "reason": "Subagent and verifier runtime contracts"}
+{"file": ".trellis/spec/backend/langchain-native-guidelines.md", "reason": "LangChain-native child create_agent boundary"}
+{"file": ".trellis/tasks/04-16-cc-highlight-alignment-discussion/h11-h12-alignment-research.md", "reason": "H11/H12 source-backed gap matrix"}
diff --git a/.trellis/tasks/archive/2026-04/04-17-l2a-h11-h12-agent-definition-general-runtime/prd.md b/.trellis/tasks/archive/2026-04/04-17-l2a-h11-h12-agent-definition-general-runtime/prd.md
new file mode 100644
index 000000000..d5a57742a
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l2a-h11-h12-agent-definition-general-runtime/prd.md
@@ -0,0 +1,42 @@
+# L2-a: H11/H12 AgentDefinition and general runtime
+
+## Goal
+
+Implement H11/H12-A: introduce `AgentDefinition`, a `general + verifier` catalog, real read-only general child runtime, minimal structured result envelope, and fallback final-text scan.
+
+## Requirements
+
+* Define an `AgentDefinition` schema with at least `agent_type`, description/when-to-use, tool allowlist/disallow list, `max_turns`, and optional model profile.
+* Register the MVP built-in catalog: `general` and `verifier`.
+* Replace the current `general` stub with a bounded read-only child `create_agent` invocation.
+* Keep `general` tools read-only: `read_file`, `glob`, `grep`, `task_get`, `task_list`, `plan_get`.
+* Refactor verifier settings to read from `AgentDefinition`; keep verifier bounded and read-only.
+* Add a result envelope with `input_tokens`, `output_tokens`, `total_tokens`, `total_duration_ms`, and `total_tool_use_count`.
+* Add fallback last-text scan when the final assistant message is tool-only or otherwise lacks direct text.
+
+## Acceptance Criteria
+
+* [x] `run_subagent(agent_type="general")` executes a real child runtime, not a hard-coded acceptance string.
+* [x] `general` cannot write files, edit files, run bash, call `TodoWrite`, or save plans.
+* [x] `general.max_turns == 25` and `verifier.max_turns == 5` are declared in definitions, not hard-coded branches.
+* [x] Verifier behavior and existing tests remain compatible.
+* [x] Result envelope is parseable and includes minimal usage/duration/tool-count fields.
+
+## Dependencies
+
+* Depends on `L1-c` for shared `ToolCapability` metadata assumptions.
+
+## Context Sources
+
+* `.trellis/tasks/04-16-cc-highlight-alignment-discussion/h11-h12-alignment-research.md`
+* `.trellis/tasks/04-16-cc-highlight-alignment-discussion/prd.md`
+* `.trellis/spec/backend/langchain-native-guidelines.md`
+* `.trellis/spec/backend/task-workflow-contracts.md`
+
+## Out of Scope
+
+* Sidechain transcript persistence.
+* Background/async agents.
+* Mailbox / SendMessage.
+* Write-capable coder agents.
+* Full fork/cache parity.
diff --git a/.trellis/tasks/archive/2026-04/04-17-l2a-h11-h12-agent-definition-general-runtime/task.json b/.trellis/tasks/archive/2026-04/04-17-l2a-h11-h12-agent-definition-general-runtime/task.json
new file mode 100644
index 000000000..798bb4865
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l2a-h11-h12-agent-definition-general-runtime/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l2a-h11-h12-agent-definition-general-runtime",
+  "name": "l2a-h11-h12-agent-definition-general-runtime",
+  "title": "L2-a H11 H12 agent definition and general runtime",
+  "description": "H11/H12-A AgentDefinition schema, general+verifier catalog, real read-only general child runtime, structured result envelope, fallback text scan.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-17",
+  "completedAt": "2026-04-19",
+  "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-17-cc-core-topology-closeout-plan",
+  "relatedFiles": [],
+  "notes": "Completed H11/H12-A: added AgentDefinition catalog for general/verifier, replaced general stub with real read-only child create_agent invocation, routed verifier through definitions, returned structured result envelopes with local usage/duration/tool-count metrics, and added fallback final-text extraction.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-17-l2b-h19-compact-observability-events/check.jsonl b/.trellis/tasks/archive/2026-04/04-17-l2b-h19-compact-observability-events/check.jsonl
new file mode 100644
index 000000000..c7442379b
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l2b-h19-compact-observability-events/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/spec/backend/runtime-pressure-contracts.md", "reason": "Compact runtime pressure event contract"}
diff --git a/.trellis/tasks/archive/2026-04/04-17-l2b-h19-compact-observability-events/debug.jsonl b/.trellis/tasks/archive/2026-04/04-17-l2b-h19-compact-observability-events/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l2b-h19-compact-observability-events/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-17-l2b-h19-compact-observability-events/implement.jsonl b/.trellis/tasks/archive/2026-04/04-17-l2b-h19-compact-observability-events/implement.jsonl
new file mode 100644
index 000000000..db033b9fd
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l2b-h19-compact-observability-events/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/runtime-pressure-contracts.md", "reason": "Compact runtime pressure event contract"}
diff --git a/.trellis/tasks/archive/2026-04/04-17-l2b-h19-compact-observability-events/prd.md b/.trellis/tasks/archive/2026-04/04-17-l2b-h19-compact-observability-events/prd.md
new file mode 100644
index 000000000..5cb20d669
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l2b-h19-compact-observability-events/prd.md
@@ -0,0 +1,36 @@
+# L2-b: H19 compact observability events
+
+## Goal
+
+Implement H19-B compact observability trio: split auto-compact events, post-auto-compact canary, and orphan tombstone event.
+
+## Requirements
+
+* Split proactive auto-compact observability into attempted and succeeded events with bounded metadata.
+* Emit `post_autocompact_turn` canary after the first turn following compact/collapse.
+* Record four canary metrics: `pre_compact_total`, `post_compact_total`, `new_turn_input`, `new_turn_output`.
+* Emit `orphan_tombstoned` when projection repair replaces orphaned tool-use/result material with tombstones.
+* Persist only whitelisted bounded event metadata into session evidence.
+
+## Acceptance Criteria
+
+* [x] Auto-compact attempted and succeeded are distinguishable in runtime events/evidence.
+* [x] Canary event appears once at the correct post-compact boundary.
+* [x] Orphan tombstone repair emits a bounded event with count and reason.
+* [x] Existing compact/session recovery tests remain green.
+
+## Dependencies
+
+* Depends on `L1-b` so event sink semantics are stable.
+
+## Context Sources
+
+* `.trellis/tasks/04-16-cc-highlight-alignment-discussion/h19-observability-alignment-research.md`
+* `.trellis/spec/backend/runtime-pressure-contracts.md`
+* `.trellis/spec/backend/session-compact-contracts.md`
+
+## Out of Scope
+
+* Query-error events.
+* API dump.
+* External analytics or Perfetto.
diff --git a/.trellis/tasks/archive/2026-04/04-17-l2b-h19-compact-observability-events/task.json b/.trellis/tasks/archive/2026-04/04-17-l2b-h19-compact-observability-events/task.json
new file mode 100644
index 000000000..9b8f8b880
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l2b-h19-compact-observability-events/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l2b-h19-compact-observability-events",
+  "name": "l2b-h19-compact-observability-events",
+  "title": "L2-b H19 compact observability events",
+  "description": "H19-B compact observability trio: split auto_compact attempted/succeeded, post_autocompact_turn canary, orphan_tombstoned event.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-17",
+  "completedAt": "2026-04-19",
+  "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-17-cc-core-topology-closeout-plan",
+  "relatedFiles": [],
+  "notes": "Completed H19 L2-b in integrated closeout: split AutoCompact attempted/succeeded observability, added post_autocompact_turn canary metrics, and emitted orphan_tombstoned projection-repair events.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-17-l2c-h01-role-based-tool-projection/check.jsonl b/.trellis/tasks/archive/2026-04/04-17-l2c-h01-role-based-tool-projection/check.jsonl
new file mode 100644
index 000000000..01b5e1ca3
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l2c-h01-role-based-tool-projection/check.jsonl
@@ -0,0 +1,4 @@
+{"file": ".gemini/commands/trellis/finish-work.toml", "reason": "Finish work checklist"}
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".trellis/plans/coding-deepgent-h01-tool-module-alignment-plan.md", "reason": "H01 projection source plan"}
+{"file": ".trellis/spec/backend/tool-capability-contracts.md", "reason": "Role-based tool projection contract"}
diff --git a/.trellis/tasks/archive/2026-04/04-17-l2c-h01-role-based-tool-projection/debug.jsonl b/.trellis/tasks/archive/2026-04/04-17-l2c-h01-role-based-tool-projection/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l2c-h01-role-based-tool-projection/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-17-l2c-h01-role-based-tool-projection/implement.jsonl b/.trellis/tasks/archive/2026-04/04-17-l2c-h01-role-based-tool-projection/implement.jsonl
new file mode 100644
index 000000000..70ad97961
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l2c-h01-role-based-tool-projection/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/spec/backend/tool-capability-contracts.md", "reason": "Role-based tool projection contract"}
+{"file": ".trellis/plans/coding-deepgent-h01-tool-module-alignment-plan.md", "reason": "H01 projection source plan"}
diff --git a/.trellis/tasks/archive/2026-04/04-17-l2c-h01-role-based-tool-projection/prd.md b/.trellis/tasks/archive/2026-04/04-17-l2c-h01-role-based-tool-projection/prd.md
new file mode 100644
index 000000000..d2394a65c
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l2c-h01-role-based-tool-projection/prd.md
@@ -0,0 +1,35 @@
+# L2-c: H01 role-based tool projection
+
+## Goal
+
+Implement H01-#2: role-based tool projection foundation for `main`, `child_only`, `extension`, and future `deferred` surfaces.
+
+## Requirements
+
+* Centralize projection logic so runtime surfaces consume metadata instead of hard-coded tool-name lists.
+* Preserve distinct surfaces for main agent, child agents, verifier, and extension-provided capabilities.
+* Make `child_only` behavior testable after real general child runtime exists.
+* Keep future deferred ToolSearch/schema-discovery as a declared boundary, not implemented behavior.
+
+## Acceptance Criteria
+
+* [x] Main and child tool projections are deterministic and covered by tests.
+* [x] Extension tools preserve source/trust metadata through projection.
+* [x] Verifier/general child tool pools can be derived from definitions and capability metadata.
+* [x] No hot-swap or deferred ToolSearch runtime is added.
+
+## Dependencies
+
+* Depends on `L1-c`.
+* Depends on `L2-a` for validating `child_only` behavior against a real general runtime.
+
+## Context Sources
+
+* `.trellis/plans/coding-deepgent-h01-tool-module-alignment-plan.md`
+* `.trellis/spec/backend/tool-capability-contracts.md`
+* `.trellis/tasks/04-16-cc-highlight-alignment-discussion/h11-h12-alignment-research.md`
+
+## Out of Scope
+
+* Dynamic tool pool hot-swap.
+* Parallel tool-call orchestration.
diff --git a/.trellis/tasks/archive/2026-04/04-17-l2c-h01-role-based-tool-projection/task.json b/.trellis/tasks/archive/2026-04/04-17-l2c-h01-role-based-tool-projection/task.json
new file mode 100644
index 000000000..c090130ec
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l2c-h01-role-based-tool-projection/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l2c-h01-role-based-tool-projection",
+  "name": "l2c-h01-role-based-tool-projection",
+  "title": "L2-c H01 role-based tool projection foundation",
+  "description": "H01 child 2: role-based tool projection for main, child_only, extension, and future deferred surfaces.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-17",
+  "completedAt": "2026-04-19",
+  "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-17-cc-core-topology-closeout-plan",
+  "relatedFiles": [],
+  "notes": "Completed H01 child 2: centralized registry projection helpers for main/child/extension/deferred surfaces, preserved extension source/trust metadata through projections, and routed general/verifier child tool pools through AgentDefinition plus child capability metadata without hot-swap or ToolSearch runtime.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-17-l3a-h11-h12-subagent-sidechain-transcript/prd.md b/.trellis/tasks/archive/2026-04/04-17-l3a-h11-h12-subagent-sidechain-transcript/prd.md
new file mode 100644
index 000000000..d49ba2687
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l3a-h11-h12-subagent-sidechain-transcript/prd.md
@@ -0,0 +1,35 @@
+# L3-a: H11/H12 subagent sidechain transcript
+
+## Goal
+
+Implement H11/H12-B: persist subagent sidechain transcript entries into the parent session JSONL with parent/child linkage.
+
+## Requirements
+
+* Add `parent_message_id` and `subagent_thread_id` linkage for child transcript entries.
+* Write sidechain child messages into the parent session ledger rather than a separate per-agent directory.
+* Preserve raw transcript compatibility and existing resume behavior.
+* Ensure verifier/general child evidence can be traced back to parent invocation context.
+
+## Acceptance Criteria
+
+* [x] Child transcript entries roundtrip through `JsonlSessionStore`.
+* [x] Loaded sessions can distinguish parent messages from subagent sidechain messages.
+* [x] Existing compact/collapse/session projections do not accidentally expose sidechain records to the main model context.
+* [x] Verifier evidence lineage remains compatible.
+
+## Dependencies
+
+* Depends on `L2-a`.
+
+## Context Sources
+
+* `.trellis/tasks/04-16-cc-highlight-alignment-discussion/h11-h12-alignment-research.md`
+* `.trellis/spec/backend/session-compact-contracts.md`
+* `.trellis/spec/backend/task-workflow-contracts.md`
+
+## Out of Scope
+
+* Per-agent directories.
+* Subagent resume.
+* Background/async lifecycle.
diff --git a/.trellis/tasks/archive/2026-04/04-17-l3a-h11-h12-subagent-sidechain-transcript/task.json b/.trellis/tasks/archive/2026-04/04-17-l3a-h11-h12-subagent-sidechain-transcript/task.json
new file mode 100644
index 000000000..faf921466
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l3a-h11-h12-subagent-sidechain-transcript/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l3a-h11-h12-subagent-sidechain-transcript",
+  "name": "l3a-h11-h12-subagent-sidechain-transcript",
+  "title": "L3-a H11 H12 subagent sidechain transcript",
+  "description": "H11/H12-B persist subagent sidechain transcript into parent session JSONL with parent_message_id and subagent_thread_id linkage.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-17",
+  "completedAt": "2026-04-19",
+  "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-17-cc-core-topology-closeout-plan",
+  "relatedFiles": [],
+  "notes": "Completed H11/H12-B: persisted bounded subagent sidechain transcript entries into the parent session JSONL with parent_message_id / parent_thread_id / subagent_thread_id linkage, loaded them through LoadedSession.sidechain_messages, and kept main resume/compact/collapse projections unchanged.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-17-l3b-h19-query-error-token-budget-api-dump/check.jsonl b/.trellis/tasks/archive/2026-04/04-17-l3b-h19-query-error-token-budget-api-dump/check.jsonl
new file mode 100644
index 000000000..6c7c3f84f
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l3b-h19-query-error-token-budget-api-dump/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/spec/backend/logging-guidelines.md", "reason": "Structured query-error and dump safety"}
diff --git a/.trellis/tasks/archive/2026-04/04-17-l3b-h19-query-error-token-budget-api-dump/debug.jsonl b/.trellis/tasks/archive/2026-04/04-17-l3b-h19-query-error-token-budget-api-dump/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l3b-h19-query-error-token-budget-api-dump/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-17-l3b-h19-query-error-token-budget-api-dump/implement.jsonl b/.trellis/tasks/archive/2026-04/04-17-l3b-h19-query-error-token-budget-api-dump/implement.jsonl
new file mode 100644
index 000000000..f213080f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l3b-h19-query-error-token-budget-api-dump/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/runtime-pressure-contracts.md", "reason": "Token budget and query-error observability contract"}
diff --git a/.trellis/tasks/archive/2026-04/04-17-l3b-h19-query-error-token-budget-api-dump/prd.md b/.trellis/tasks/archive/2026-04/04-17-l3b-h19-query-error-token-budget-api-dump/prd.md
new file mode 100644
index 000000000..103f4b0c5
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l3b-h19-query-error-token-budget-api-dump/prd.md
@@ -0,0 +1,36 @@
+# L3-b: H19 query error, token budget, and API dump
+
+## Goal
+
+Implement H19-C: structured `query_error`, per-turn `token_budget`, and env-gated API/prompt dump.
+
+## Requirements
+
+* Emit structured `query_error` runtime event with bounded fields such as error class, phase, and retry count.
+* Emit `token_budget` for each assistant response turn, not only compact boundaries.
+* Add env-gated prompt/API dump controlled by `CODING_DEEPGENT_DUMP_PROMPTS=1`.
+* Keep dumps out of normal production paths and avoid leaking secrets into model-visible context.
+
+## Acceptance Criteria
+
+* [x] Runtime query failures produce structured evidence without depending on stderr logs.
+* [x] Every assistant response can emit bounded token-budget metadata.
+* [x] API dump is disabled by default and enabled only by environment gate.
+* [x] Existing runtime/CLI tests stay deterministic when dump is disabled.
+
+## Dependencies
+
+* Depends on `L1-b`.
+* Depends on `L2-b`.
+
+## Context Sources
+
+* `.trellis/tasks/04-16-cc-highlight-alignment-discussion/h19-observability-alignment-research.md`
+* `.trellis/spec/backend/logging-guidelines.md`
+* `.trellis/spec/backend/runtime-pressure-contracts.md`
+
+## Out of Scope
+
+* CLI flag for dumps.
+* Provider-specific cache/cost breakdown.
+* Perfetto or external analytics.
diff --git a/.trellis/tasks/archive/2026-04/04-17-l3b-h19-query-error-token-budget-api-dump/task.json b/.trellis/tasks/archive/2026-04/04-17-l3b-h19-query-error-token-budget-api-dump/task.json
new file mode 100644
index 000000000..26d745331
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l3b-h19-query-error-token-budget-api-dump/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l3b-h19-query-error-token-budget-api-dump",
+  "name": "l3b-h19-query-error-token-budget-api-dump",
+  "title": "L3-b H19 query error token budget and API dump",
+  "description": "H19-C structured query_error events, per-turn token_budget event, and env-gated prompt/API dump helper.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-17",
+  "completedAt": "2026-04-19",
+  "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-17-cc-core-topology-closeout-plan",
+  "relatedFiles": [],
+  "notes": "Completed H19 L3-b in integrated closeout: added structured query_error evidence, per-model-call token_budget events, and env-gated CODING_DEEPGENT_DUMP_PROMPTS=1 model request dumps.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-17-l3c-h01-dynamic-tool-pool-foundation/prd.md b/.trellis/tasks/archive/2026-04/04-17-l3c-h01-dynamic-tool-pool-foundation/prd.md
new file mode 100644
index 000000000..e4b4ad2a0
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l3c-h01-dynamic-tool-pool-foundation/prd.md
@@ -0,0 +1,34 @@
+# L3-c: H01 dynamic tool pool foundation
+
+## Goal
+
+Implement H01-#3: dynamic tool pool projection and validation foundation without hot-swap runtime.
+
+## Requirements
+
+* Represent tool pool selection as an explicit projection result, not an implicit global registry snapshot.
+* Validate that enabled/disabled, role, source, trust, and exposure metadata produce correct visible tool surfaces.
+* Preserve current startup/runtime simplicity; do not add live hot-swap.
+* Leave ToolSearch/deferred schema discovery as future behavior.
+
+## Acceptance Criteria
+
+* [x] Tool pool projection can be tested independently from agent startup.
+* [x] Invalid projection states fail deterministically with bounded errors.
+* [x] Main, child, and extension surfaces remain stable after projection refactor.
+* [x] H01 follow-up tests can build on this projection seam.
+
+## Dependencies
+
+* Depends on `L2-c`.
+
+## Context Sources
+
+* `.trellis/plans/coding-deepgent-h01-tool-module-alignment-plan.md`
+* `.trellis/spec/backend/tool-capability-contracts.md`
+
+## Out of Scope
+
+* Hot-swapping tools mid-run.
+* ToolSearch.
+* Streaming tool execution.
diff --git a/.trellis/tasks/archive/2026-04/04-17-l3c-h01-dynamic-tool-pool-foundation/task.json b/.trellis/tasks/archive/2026-04/04-17-l3c-h01-dynamic-tool-pool-foundation/task.json
new file mode 100644
index 000000000..e835ab271
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l3c-h01-dynamic-tool-pool-foundation/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l3c-h01-dynamic-tool-pool-foundation",
+  "name": "l3c-h01-dynamic-tool-pool-foundation",
+  "title": "L3-c H01 dynamic tool pool foundation",
+  "description": "H01 child 3: dynamic tool pool projection and validation foundation without hot-swap runtime.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-17",
+  "completedAt": "2026-04-19",
+  "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-17-cc-core-topology-closeout-plan",
+  "relatedFiles": [],
+  "notes": "Completed H01 child 3: added explicit ToolPoolProjection seam and registry.project(...) API for main/child/extension/deferred surfaces, validated projection states deterministically, and preserved startup simplicity without tool hot-swap or ToolSearch runtime.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-17-l4a-h01-langchain-parallel-tool-call-research/check.jsonl b/.trellis/tasks/archive/2026-04/04-17-l4a-h01-langchain-parallel-tool-call-research/check.jsonl
new file mode 100644
index 000000000..a0cbf3688
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l4a-h01-langchain-parallel-tool-call-research/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/spec/backend/tool-capability-contracts.md", "reason": "Concurrency/capability metadata contract"}
diff --git a/.trellis/tasks/archive/2026-04/04-17-l4a-h01-langchain-parallel-tool-call-research/debug.jsonl b/.trellis/tasks/archive/2026-04/04-17-l4a-h01-langchain-parallel-tool-call-research/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l4a-h01-langchain-parallel-tool-call-research/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-17-l4a-h01-langchain-parallel-tool-call-research/implement.jsonl b/.trellis/tasks/archive/2026-04/04-17-l4a-h01-langchain-parallel-tool-call-research/implement.jsonl
new file mode 100644
index 000000000..117432df7
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l4a-h01-langchain-parallel-tool-call-research/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/plans/coding-deepgent-h01-tool-module-alignment-plan.md", "reason": "H01 concurrency research plan"}
diff --git a/.trellis/tasks/archive/2026-04/04-17-l4a-h01-langchain-parallel-tool-call-research/prd.md b/.trellis/tasks/archive/2026-04/04-17-l4a-h01-langchain-parallel-tool-call-research/prd.md
new file mode 100644
index 000000000..5d2bc9bb5
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l4a-h01-langchain-parallel-tool-call-research/prd.md
@@ -0,0 +1,32 @@
+# L4-a: H01 LangChain parallel tool-call research
+
+## Goal
+
+Run a research-only spike to determine whether LangChain's current tool execution behavior is sufficient for non-streaming parallel tool calls.
+
+## Requirements
+
+* Inspect official LangChain/LangGraph behavior and local usage around multiple tool calls in one model turn.
+* Determine whether `ToolCapability.concurrency_safe` needs a local partition adapter.
+* Record source-backed findings and a recommendation for `L5-a`.
+* Do not change product code in this task.
+
+## Acceptance Criteria
+
+* [x] Research notes state what LangChain already guarantees.
+* [x] Research notes state what local tests should prove before adding an adapter.
+* [x] `L5-a` is either justified as implementation work or downgraded to spec-only.
+
+## Dependencies
+
+* Depends on `L2-c`.
+
+## Context Sources
+
+* `.trellis/plans/coding-deepgent-h01-tool-module-alignment-plan.md`
+* `.trellis/spec/backend/langchain-native-guidelines.md`
+
+## Out of Scope
+
+* Implementing a partition adapter.
+* Streaming tool execution.
diff --git a/.trellis/tasks/archive/2026-04/04-17-l4a-h01-langchain-parallel-tool-call-research/research.md b/.trellis/tasks/archive/2026-04/04-17-l4a-h01-langchain-parallel-tool-call-research/research.md
new file mode 100644
index 000000000..729155f02
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l4a-h01-langchain-parallel-tool-call-research/research.md
@@ -0,0 +1,175 @@
+# L4-a Findings: LangChain Parallel Tool-Call Research
+
+Date: 2026-04-18
+Task: `04-17-l4a-h01-langchain-parallel-tool-call-research`
+Scope: determine whether current LangChain/LangGraph behavior is sufficient for
+non-streaming parallel tool calls in `coding-deepgent`.
+
+## Sources
+
+Official LangChain docs:
+
+- `https://docs.langchain.com/oss/python/langchain/models` (`Tool calling`,
+  `Parallel tool calls`)
+- `https://docs.langchain.com/oss/python/langchain/tools` (`ToolNode`)
+
+Local installed source:
+
+- `langchain 1.2.12`
+- `langgraph.prebuilt.tool_node.ToolNode`
+- `langchain.agents.factory.create_agent`
+- `langchain_core.runnables.config.get_executor_for_config`
+
+Local product code:
+
+- `coding-deepgent/src/coding_deepgent/tool_system/capabilities.py`
+- `coding-deepgent/src/coding_deepgent/tool_system/middleware.py`
+- `coding-deepgent/src/coding_deepgent/todo/middleware.py`
+- `coding-deepgent/tests/tasks/test_planning.py`
+
+## What LangChain Already Guarantees
+
+### 1. Models may emit multiple tool calls in one turn
+
+Official docs state that many models support multiple parallel tool calls and
+that the model may generate multiple tool calls in one response. Docs also note
+that providers such as OpenAI/Anthropic can disable this with
+`parallel_tool_calls=False` at bind time.
+
+Implication for `coding-deepgent`:
+
+- multiple tool calls in one model turn are already part of the standard
+  LangChain tool-calling model surface
+- we should treat this as a real possible runtime shape, not a future edge case
+
+### 2. `create_agent()` uses `ToolNode` internally
+
+Local installed `langchain.agents.factory.create_agent` constructs a
+`ToolNode(...)` for client-side tools. There is no separate `coding-deepgent`
+tool executor bypassing this path.
+
+Implication:
+
+- current `coding-deepgent` agent runtime inherits `ToolNode` behavior directly
+- if `ToolNode` is sufficient, no custom executor should be added
+
+### 3. `ToolNode` executes multiple tool calls in parallel
+
+Observed in local installed source:
+
+- sync path uses `get_executor_for_config(config)` plus
+  `executor.map(self._run_one, ...)`
+- async path uses `asyncio.gather(...)`
+- `get_executor_for_config()` builds a thread-pool executor using
+  `max_workers=config.get("max_concurrency")`
+
+Implication:
+
+- LangGraph already parallelizes multiple client-side tool calls in the same
+  step
+- there is no need for a local adapter just to get basic non-streaming
+  parallelism
+
+### 4. Output order is preserved
+
+`ToolNode._combine_tool_outputs(outputs, ...)` consumes the `outputs` list in
+the same order it was produced from `executor.map(...)` / `asyncio.gather(...)`.
+Both preserve input ordering.
+
+Local experiment:
+
+- two tools each slept `0.4s`
+- total elapsed wall-clock was `~0.405s`
+- output order remained `call_a`, then `call_b`
+
+Implication:
+
+- current LangChain behavior already satisfies the baseline requirement
+  "parallel execution with original tool-call order preserved"
+
+## What LangChain Does Not Guarantee For Us
+
+### 1. No capability-aware partitioning
+
+`ToolNode` parallelizes the tool calls it is given. It does not know anything
+about local metadata like:
+
+- `ToolCapability.concurrency_safe`
+- `mutation`
+- `destructive`
+- local trust/source semantics
+
+Implication:
+
+- if we need "read-only tools may run concurrently, unsafe tools must be
+  serialized/exclusive", LangChain does not provide that policy out of the box
+- implementing that policy would require a local adapter/tool-node wrapper or
+  a stronger model-side restriction
+
+### 2. No built-in protection against parallel state-replacement semantics
+
+Local repo already contains one explicit safeguard:
+
+- `PlanContextMiddleware.after_model()` rejects multiple `TodoWrite` tool calls
+  in the same response, because session todo replacement is not safe in
+  parallel
+
+Implication:
+
+- the repo already assumes LangChain may hand us parallel tool calls
+- local invariants for stateful tools must be protected explicitly
+
+## Recommendation For Local Work
+
+### Recommendation
+
+Do **not** implement `L5-a` as a runtime partition adapter now.
+
+Instead:
+
+1. treat LangChain/ToolNode parallelism as sufficient for the current
+   non-streaming baseline
+2. keep local protections as targeted invariants/tests for known unsafe tools
+3. only reopen an execution adapter if `L4-b` / `L4-c` or a concrete runtime
+   failure shows that capability-aware partitioning is required
+
+### Why
+
+- basic parallel execution already exists upstream
+- result ordering is already stable
+- current repo has no demonstrated failure for parallel read-only tools
+- adding a local partition executor now would introduce a heavier runtime seam
+  before we have a concrete source-backed failure
+
+### Concrete L5-a Decision
+
+`L5-a` should be **downgraded from implementation work to conditional/spec-only
+follow-up**.
+
+Keep it dormant unless one of these becomes true:
+
+- local tests show unsafe multi-tool execution can occur and break state/tool
+  invariants
+- LangChain ordering/middleware behavior fails a concrete repo test
+- the product requires capability-aware serialization for mutating tools beyond
+  today's targeted guards
+
+## What Local Tests Should Prove Before Any Adapter
+
+Before reviving `L5-a`, local tests should prove all of:
+
+1. a single model turn can contain multiple tool calls in our agent path
+2. `ToolGuardMiddleware`, hooks, large-output persistence, and runtime events
+   all still apply under multi-tool execution
+3. output order remains aligned with original tool-call order
+4. known unsafe/stateful tools are either:
+   - explicitly prevented from parallel use, or
+   - shown to remain correct under parallel execution
+
+Concrete follow-up targets:
+
+- `L4-b`: tool-use/result pairing and protocol-correct failure tests
+- `L4-c`: result persistence / microcompact eligibility audit
+
+If those pass without exposing a real safety gap, `L5-a` should remain
+deferred.
diff --git a/.trellis/tasks/archive/2026-04/04-17-l4a-h01-langchain-parallel-tool-call-research/task.json b/.trellis/tasks/archive/2026-04/04-17-l4a-h01-langchain-parallel-tool-call-research/task.json
new file mode 100644
index 000000000..8d2f62f8f
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l4a-h01-langchain-parallel-tool-call-research/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l4a-h01-langchain-parallel-tool-call-research",
+  "name": "l4a-h01-langchain-parallel-tool-call-research",
+  "title": "L4-a H01 LangChain parallel tool-call research spike",
+  "description": "H01 child 4: research-only spike to verify LangChain parallel tool-call behavior and whether local partition adapter is needed.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-17",
+  "completedAt": "2026-04-19",
+  "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-17-cc-core-topology-closeout-plan",
+  "relatedFiles": [],
+  "notes": "Completed research spike. Official LangChain docs plus local langchain 1.2.12 / ToolNode source show that non-streaming multi-tool execution already runs in parallel and preserves input order. Recommendation: downgrade L5-a from implementation to conditional/spec-only follow-up unless L4-b/L4-c expose a concrete capability-aware partitioning failure.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-17-l4b-h01-tool-use-result-pairing-failure-tests/check.jsonl b/.trellis/tasks/archive/2026-04/04-17-l4b-h01-tool-use-result-pairing-failure-tests/check.jsonl
new file mode 100644
index 000000000..8baac5e4b
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l4b-h01-tool-use-result-pairing-failure-tests/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/spec/backend/tool-result-storage-contracts.md", "reason": "Persisted output and pairing pressure contract"}
diff --git a/.trellis/tasks/archive/2026-04/04-17-l4b-h01-tool-use-result-pairing-failure-tests/debug.jsonl b/.trellis/tasks/archive/2026-04/04-17-l4b-h01-tool-use-result-pairing-failure-tests/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l4b-h01-tool-use-result-pairing-failure-tests/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-17-l4b-h01-tool-use-result-pairing-failure-tests/implement.jsonl b/.trellis/tasks/archive/2026-04/04-17-l4b-h01-tool-use-result-pairing-failure-tests/implement.jsonl
new file mode 100644
index 000000000..137b4729e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l4b-h01-tool-use-result-pairing-failure-tests/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-17-l4b-h01-tool-use-result-pairing-failure-tests/prd.md b/.trellis/tasks/archive/2026-04/04-17-l4b-h01-tool-use-result-pairing-failure-tests/prd.md
new file mode 100644
index 000000000..d804957b9
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l4b-h01-tool-use-result-pairing-failure-tests/prd.md
@@ -0,0 +1,33 @@
+# L4-b: H01 tool-use/result pairing and failure tests
+
+## Goal
+
+Implement H01-#5: tests and small hardening for tool_use/tool_result pairing and protocol-correct failure behavior.
+
+## Requirements
+
+* Add focused tests for unknown tool, schema failure, permission denial, hook block, and tool exception results.
+* Verify tool_use/tool_result pairing remains valid through projection, compact, and failure paths.
+* Prefer synthetic bounded model-consumable errors over broken protocol state.
+
+## Acceptance Criteria
+
+* [x] Protocol-correct errors are returned for common tool failure classes.
+* [x] Pairing tests cover projected/dynamic tool surfaces.
+* [x] Existing runtime pressure and tool middleware tests remain green.
+
+## Dependencies
+
+* Depends on `L2-c`.
+* Depends on `L3-c`.
+
+## Context Sources
+
+* `.trellis/plans/coding-deepgent-h01-tool-module-alignment-plan.md`
+* `.trellis/spec/backend/tool-capability-contracts.md`
+* `.trellis/spec/backend/tool-result-storage-contracts.md`
+
+## Out of Scope
+
+* Streaming fallback repair.
+* Full custom tool execution engine.
diff --git a/.trellis/tasks/archive/2026-04/04-17-l4b-h01-tool-use-result-pairing-failure-tests/task.json b/.trellis/tasks/archive/2026-04/04-17-l4b-h01-tool-use-result-pairing-failure-tests/task.json
new file mode 100644
index 000000000..ffd318729
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l4b-h01-tool-use-result-pairing-failure-tests/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l4b-h01-tool-use-result-pairing-failure-tests",
+  "name": "l4b-h01-tool-use-result-pairing-failure-tests",
+  "title": "L4-b H01 tool use result pairing failure tests",
+  "description": "H01 child 5: tool_use/tool_result pairing and protocol-correct failure tests.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-17",
+  "completedAt": "2026-04-19",
+  "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-17-cc-core-topology-closeout-plan",
+  "relatedFiles": [],
+  "notes": "Completed H01 child 5: added focused protocol-failure tests for unknown tool, permission denial, hook block, and tool exception handling; ensured tool exceptions collapse to bounded ToolMessage errors; and added id-based pairing tests proving projection/extension tool names do not break tool_use/tool_result pairing.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-17-l4c-h01-result-persistence-microcompact-eligibility-audit/audit.md b/.trellis/tasks/archive/2026-04/04-17-l4c-h01-result-persistence-microcompact-eligibility-audit/audit.md
new file mode 100644
index 000000000..013400071
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l4c-h01-result-persistence-microcompact-eligibility-audit/audit.md
@@ -0,0 +1,85 @@
+# L4-c Findings: Result Persistence And Microcompact Eligibility Audit
+
+Date: 2026-04-18
+Task: `04-17-l4c-h01-result-persistence-microcompact-eligibility-audit`
+
+## Scope
+
+Reviewed current `ToolCapability` opt-ins for:
+
+- `persist_large_output`
+- `max_inline_result_chars`
+- `microcompact_eligible`
+
+Reviewed against:
+
+- `coding-deepgent/src/coding_deepgent/tool_system/capabilities.py`
+- `coding-deepgent/src/coding_deepgent/tool_system/middleware.py`
+- `coding-deepgent/src/coding_deepgent/compact/tool_results.py`
+- `coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py`
+- `coding-deepgent/tests/tool_system/test_tool_result_storage.py`
+- `coding-deepgent/tests/tool_system/test_tool_system_registry.py`
+
+## Current Opt-In Set
+
+Current tools with `persist_large_output=True`:
+
+- `bash`
+- `read_file`
+- `glob`
+- `grep`
+
+Current tools with `microcompact_eligible=True`:
+
+- `bash`
+- `read_file`
+- `glob`
+- `grep`
+
+No other tool currently opts in.
+
+## Audit Conclusion
+
+### 1. No invalid microcompact opt-ins found
+
+All current `microcompact_eligible` tools also opt into large-output
+persistence, which is required by the current local contract.
+
+That means old outputs can be hidden while preserving a model-visible persisted
+path for later recovery.
+
+### 2. No invalid large-output persistence opt-ins found
+
+All current `persist_large_output` tools return string-heavy outputs that can be
+meaningfully rewritten as preview + persisted file path:
+
+- `read_file`: directly recoverable by re-reading the file or opening persisted
+  output
+- `glob` / `grep`: search results are path/text listings and are safe to persist
+- `bash`: command output may be non-repeatable, but persisted-output storage
+  still preserves the full original output behind a stable workspace path, so
+  recoverability is satisfied without replaying the command
+
+### 3. No capability metadata changes required
+
+The existing opt-in set already matches the current contract and tests.
+
+Recommendation:
+
+- keep the current capability metadata unchanged
+- keep `L5-a` dormant
+- rely on current registry tests plus tool-result storage tests as the proof
+  surface
+
+## Follow-Up Rule
+
+Reopen this area only when a new tool wants either:
+
+- `persist_large_output=True`, or
+- `microcompact_eligible=True`
+
+At that point, require explicit proof that:
+
+1. large results can be rewritten into preview + persisted path safely
+2. old output can be hidden without losing critical state
+3. the tool still behaves correctly through runtime pressure and recovery paths
diff --git a/.trellis/tasks/archive/2026-04/04-17-l4c-h01-result-persistence-microcompact-eligibility-audit/check.jsonl b/.trellis/tasks/archive/2026-04/04-17-l4c-h01-result-persistence-microcompact-eligibility-audit/check.jsonl
new file mode 100644
index 000000000..dfe6526d5
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l4c-h01-result-persistence-microcompact-eligibility-audit/check.jsonl
@@ -0,0 +1,2 @@
+{"file": ".gemini/commands/trellis/finish-work.toml", "reason": "Finish work checklist"}
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-17-l4c-h01-result-persistence-microcompact-eligibility-audit/debug.jsonl b/.trellis/tasks/archive/2026-04/04-17-l4c-h01-result-persistence-microcompact-eligibility-audit/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l4c-h01-result-persistence-microcompact-eligibility-audit/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-17-l4c-h01-result-persistence-microcompact-eligibility-audit/implement.jsonl b/.trellis/tasks/archive/2026-04/04-17-l4c-h01-result-persistence-microcompact-eligibility-audit/implement.jsonl
new file mode 100644
index 000000000..137b4729e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l4c-h01-result-persistence-microcompact-eligibility-audit/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-17-l4c-h01-result-persistence-microcompact-eligibility-audit/prd.md b/.trellis/tasks/archive/2026-04/04-17-l4c-h01-result-persistence-microcompact-eligibility-audit/prd.md
new file mode 100644
index 000000000..52c2e2ca6
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l4c-h01-result-persistence-microcompact-eligibility-audit/prd.md
@@ -0,0 +1,32 @@
+# L4-c: H01 result persistence and microcompact eligibility audit
+
+## Goal
+
+Implement H01-#6: lightweight audit of result persistence and microcompact eligibility across tool capabilities.
+
+## Requirements
+
+* Review tools that opt into large-output persistence or microcompact eligibility.
+* Verify opt-in metadata matches actual recoverability and safety.
+* Update tests/contracts when a tool's persisted preview or microcompact behavior is ambiguous.
+
+## Acceptance Criteria
+
+* [x] No tool is microcompact-eligible unless old output can be safely hidden or recovered.
+* [x] Large-output persistence metadata matches tool result behavior.
+* [x] Tool result storage contracts reflect any new audit rule.
+
+## Dependencies
+
+* Depends on `L3-c`.
+
+## Context Sources
+
+* `.trellis/spec/backend/tool-result-storage-contracts.md`
+* `.trellis/spec/backend/tool-capability-contracts.md`
+* `.trellis/plans/coding-deepgent-h01-tool-module-alignment-plan.md`
+
+## Out of Scope
+
+* New persistence backend.
+* Provider-specific cache instrumentation.
diff --git a/.trellis/tasks/archive/2026-04/04-17-l4c-h01-result-persistence-microcompact-eligibility-audit/task.json b/.trellis/tasks/archive/2026-04/04-17-l4c-h01-result-persistence-microcompact-eligibility-audit/task.json
new file mode 100644
index 000000000..ed3ea3bba
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l4c-h01-result-persistence-microcompact-eligibility-audit/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l4c-h01-result-persistence-microcompact-eligibility-audit",
+  "name": "l4c-h01-result-persistence-microcompact-eligibility-audit",
+  "title": "L4-c H01 result persistence microcompact eligibility audit",
+  "description": "H01 child 6: lightweight audit of result persistence and microcompact eligibility against tool capability contracts.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-17",
+  "completedAt": "2026-04-19",
+  "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-17-cc-core-topology-closeout-plan",
+  "relatedFiles": [],
+  "notes": "Completed lightweight audit. Current persist_large_output and microcompact_eligible opt-ins remain valid for bash/read_file/glob/grep because persisted-output paths preserve recoverability even when replay is unsafe. No capability metadata changes were required; audit findings are recorded under audit.md and tool-result storage contracts were clarified.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-17-l5a-h01-conditional-nonstreaming-partition-adapter/prd.md b/.trellis/tasks/archive/2026-04/04-17-l5a-h01-conditional-nonstreaming-partition-adapter/prd.md
new file mode 100644
index 000000000..7e8f0627b
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l5a-h01-conditional-nonstreaming-partition-adapter/prd.md
@@ -0,0 +1,43 @@
+# L5-a: H01 conditional non-streaming partition adapter
+
+## Goal
+
+Implement or explicitly reject H01-#4 non-streaming concurrency partition adapter based on `L4-a` research.
+
+## Requirements
+
+* If LangChain already provides sufficient ordering/safety guarantees, update specs and do not add code.
+* If LangChain behavior is insufficient, add a thin adapter that partitions only by `ToolCapability` metadata.
+* Preserve LangChain-native runtime boundaries and existing middleware.
+
+## Acceptance Criteria
+
+* [x] `L4-a` research is cited.
+* [x] A spec-only rejection decision is recorded because `L4-b` / `L4-c` did not expose a concrete capability-aware partitioning failure.
+* [x] No custom query loop or streaming tool executor is introduced.
+
+## Resolution (2026-04-19)
+
+* Cited source: `.trellis/tasks/04-17-l4a-h01-langchain-parallel-tool-call-research/research.md`
+* `L4-a` established that LangChain `ToolNode` already provides non-streaming parallel tool execution with preserved output ordering.
+* `L4-b` pairing/failure tests and `L4-c` persistence audit did not expose a repo-level failure that requires capability-aware partitioning.
+* Decision: explicitly reject implementing a local partition adapter for now and close this task as a spec-only follow-up.
+
+## Verification
+
+* `L4-a` research, `L4-b` tests, and `L4-c` audit all remain consistent with keeping runtime execution LangChain-native.
+* No product runtime code changes were required for this task.
+
+## Dependencies
+
+* Depends on `L4-a`.
+
+## Context Sources
+
+* `.trellis/plans/coding-deepgent-h01-tool-module-alignment-plan.md`
+* `.trellis/spec/backend/langchain-native-guidelines.md`
+
+## Out of Scope
+
+* Streaming executor.
+* Provider-specific cancellation semantics.
diff --git a/.trellis/tasks/archive/2026-04/04-17-l5a-h01-conditional-nonstreaming-partition-adapter/task.json b/.trellis/tasks/archive/2026-04/04-17-l5a-h01-conditional-nonstreaming-partition-adapter/task.json
new file mode 100644
index 000000000..fab14459b
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l5a-h01-conditional-nonstreaming-partition-adapter/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l5a-h01-conditional-nonstreaming-partition-adapter",
+  "name": "l5a-h01-conditional-nonstreaming-partition-adapter",
+  "title": "L5-a H01 conditional non-streaming partition adapter",
+  "description": "Conditional H01 follow-up: implement non-streaming concurrency partition adapter only if L4-a proves LangChain behavior is insufficient; otherwise update specs only.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P3",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-17",
+  "completedAt": "2026-04-19",
+  "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-17-cc-core-topology-closeout-plan",
+  "relatedFiles": [],
+  "notes": "Conditional only. L4-a research found that LangChain ToolNode already provides non-streaming parallel tool execution with preserved output order. Do not implement this adapter unless L4-b/L4-c expose a concrete capability-aware partitioning failure that current LangChain behavior cannot satisfy.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-17-l5b-deferred-boundary-adr-refresh/check.jsonl b/.trellis/tasks/archive/2026-04/04-17-l5b-deferred-boundary-adr-refresh/check.jsonl
new file mode 100644
index 000000000..d25db0c44
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l5b-deferred-boundary-adr-refresh/check.jsonl
@@ -0,0 +1,2 @@
+{"file": ".gemini/commands/trellis/finish-work.toml", "reason": "Finish work checklist"}
+{"file": ".trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md", "reason": "Canonical dashboard alignment"}
diff --git a/.trellis/tasks/archive/2026-04/04-17-l5b-deferred-boundary-adr-refresh/debug.jsonl b/.trellis/tasks/archive/2026-04/04-17-l5b-deferred-boundary-adr-refresh/debug.jsonl
new file mode 100644
index 000000000..8b1378917
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l5b-deferred-boundary-adr-refresh/debug.jsonl
@@ -0,0 +1 @@
+
diff --git a/.trellis/tasks/archive/2026-04/04-17-l5b-deferred-boundary-adr-refresh/implement.jsonl b/.trellis/tasks/archive/2026-04/04-17-l5b-deferred-boundary-adr-refresh/implement.jsonl
new file mode 100644
index 000000000..9ed6408f0
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l5b-deferred-boundary-adr-refresh/implement.jsonl
@@ -0,0 +1,2 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/prd.md", "reason": "Prior deferred boundary ADR source"}
diff --git a/.trellis/tasks/archive/2026-04/04-17-l5b-deferred-boundary-adr-refresh/prd.md b/.trellis/tasks/archive/2026-04/04-17-l5b-deferred-boundary-adr-refresh/prd.md
new file mode 100644
index 000000000..03de29313
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l5b-deferred-boundary-adr-refresh/prd.md
@@ -0,0 +1,33 @@
+# L5-b: deferred boundary ADR refresh
+
+## Goal
+
+Refresh deferred-boundary documentation after H11/H12, H19, and H01 closeout tasks land.
+
+## Requirements
+
+* Merge H11/H12 deferred items with existing H13/H14/H21/H22 and H19 deferred items.
+* Capture why background agents, mailbox, coordinator, bridge/remote/IDE, daemon/cron, Perfetto, analytics backend, and provider-specific cache/cost remain out of scope.
+* Reference cc-haha source/research notes so future reopen requests are source-backed.
+
+## Acceptance Criteria
+
+* [x] A Trellis spec or plan ADR documents deferred boundaries with concrete reasons.
+* [x] The ADR supersedes or links to the older Stage 29 ADR.
+* [x] Future agents can tell what is intentionally deferred versus missing by accident.
+
+## Dependencies
+
+* Depends on `L3-a`.
+* Depends on `L3-b`.
+* Depends on Layer 4 H01 closeout tasks.
+
+## Context Sources
+
+* `.trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/prd.md`
+* `.trellis/tasks/04-16-cc-highlight-alignment-discussion/h11-h12-alignment-research.md`
+* `.trellis/tasks/04-16-cc-highlight-alignment-discussion/h19-observability-alignment-research.md`
+
+## Out of Scope
+
+* Implementing deferred runtime features.
diff --git a/.trellis/tasks/archive/2026-04/04-17-l5b-deferred-boundary-adr-refresh/task.json b/.trellis/tasks/archive/2026-04/04-17-l5b-deferred-boundary-adr-refresh/task.json
new file mode 100644
index 000000000..115762509
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l5b-deferred-boundary-adr-refresh/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l5b-deferred-boundary-adr-refresh",
+  "name": "l5b-deferred-boundary-adr-refresh",
+  "title": "L5-b deferred boundary ADR refresh",
+  "description": "Refresh deferred boundary ADR for H11/H12, H13/H14/H21/H22, and H19 deferred items after closeout implementation.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-17",
+  "completedAt": "2026-04-19",
+  "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-17-cc-core-topology-closeout-plan",
+  "relatedFiles": [],
+  "notes": "Completed docs-only ADR refresh. Added .trellis/plans/coding-deepgent-deferred-boundary-refresh-adr.md to supersede the old Stage 29 deferred note for H11/H12/H19/H01-adjacent boundaries, clarified why mailbox/coordinator/background/fork-cache parity/analytics/Perfetto/ToolSearch remain deferred, and updated project-handoff to point at the current topology tail.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-17-l5c-dashboard-refresh-h11-h12-h19/check.jsonl b/.trellis/tasks/archive/2026-04/04-17-l5c-dashboard-refresh-h11-h12-h19/check.jsonl
new file mode 100644
index 000000000..154a2c72d
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l5c-dashboard-refresh-h11-h12-h19/check.jsonl
@@ -0,0 +1 @@
+{"file": ".gemini/commands/trellis/finish-work.toml", "reason": "Finish work checklist"}
diff --git a/.trellis/tasks/archive/2026-04/04-17-l5c-dashboard-refresh-h11-h12-h19/debug.jsonl b/.trellis/tasks/archive/2026-04/04-17-l5c-dashboard-refresh-h11-h12-h19/debug.jsonl
new file mode 100644
index 000000000..8b1378917
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l5c-dashboard-refresh-h11-h12-h19/debug.jsonl
@@ -0,0 +1 @@
+
diff --git a/.trellis/tasks/archive/2026-04/04-17-l5c-dashboard-refresh-h11-h12-h19/implement.jsonl b/.trellis/tasks/archive/2026-04/04-17-l5c-dashboard-refresh-h11-h12-h19/implement.jsonl
new file mode 100644
index 000000000..4752e3d52
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l5c-dashboard-refresh-h11-h12-h19/implement.jsonl
@@ -0,0 +1 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
diff --git a/.trellis/tasks/archive/2026-04/04-17-l5c-dashboard-refresh-h11-h12-h19/prd.md b/.trellis/tasks/archive/2026-04/04-17-l5c-dashboard-refresh-h11-h12-h19/prd.md
new file mode 100644
index 000000000..553f8b17e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l5c-dashboard-refresh-h11-h12-h19/prd.md
@@ -0,0 +1,41 @@
+# L5-c: dashboard refresh for H11/H12/H19
+
+## Goal
+
+Refresh the canonical roadmap dashboard after closeout work lands.
+
+## Requirements
+
+* Update H11/H12 status and next-stage notes based on completed subagent runtime/sidechain work.
+* Update H19 from `implemented-minimal` to the appropriate final status after Stage 28 closeout tasks complete.
+* Keep deferred full lifecycle/provider/platform work explicit.
+* Avoid claiming parity for features intentionally left out.
+
+## Acceptance Criteria
+
+* [x] `coding-deepgent-cc-core-highlights-roadmap.md` reflects actual implemented closeout work.
+* [x] H19 Stage 28 pointer is removed or updated only after L1-b/L2-b/L3-b are complete.
+* [x] H11/H12 notes distinguish implemented local MVP behavior from deferred full lifecycle/fork/cache behavior.
+
+## Completion Note
+
+Completed by the 2026-04-17 plan cleanup:
+
+* H19 is now represented as implemented after the vertical closeout.
+* H01 `L1-c` is represented as complete.
+* H11 is represented as partial, with `L2-a` and `L3-a` as the remaining local closeout path.
+* H12 remains implemented-minimal, with rich fork/cache parity explicitly deferred.
+* The handoff now points to `L2-a` as the single next implementation entry point.
+
+## Dependencies
+
+* Depends on roadmap state and completed closeout tasks.
+
+## Context Sources
+
+* `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+* `.trellis/tasks/04-16-cc-highlight-alignment-discussion/prd.md`
+
+## Out of Scope
+
+* Product code changes.
diff --git a/.trellis/tasks/archive/2026-04/04-17-l5c-dashboard-refresh-h11-h12-h19/task.json b/.trellis/tasks/archive/2026-04/04-17-l5c-dashboard-refresh-h11-h12-h19/task.json
new file mode 100644
index 000000000..4affe8814
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-l5c-dashboard-refresh-h11-h12-h19/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l5c-dashboard-refresh-h11-h12-h19",
+  "name": "l5c-dashboard-refresh-h11-h12-h19",
+  "title": "L5-c dashboard refresh for H11 H12 H19",
+  "description": "Refresh canonical roadmap dashboard rows for H11/H12 and H19 after closeout work lands.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-17",
+  "completedAt": "2026-04-19",
+  "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-17-cc-core-topology-closeout-plan",
+  "relatedFiles": [],
+  "notes": "Completed docs-only dashboard refresh. Canonical roadmap rows for H01, H11, H12, and H19 now reflect the completed topology closeout work, and remaining deferred/full-lifecycle scope is pushed into the refreshed deferred-boundary ADR instead of looking accidentally missing.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-17-subagent-multiagent-ch09-review/prd.md b/.trellis/tasks/archive/2026-04/04-17-subagent-multiagent-ch09-review/prd.md
new file mode 100644
index 000000000..b010c387f
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-subagent-multiagent-ch09-review/prd.md
@@ -0,0 +1,483 @@
+# brainstorm: subagent multi-agent ch09 gap review
+
+## Goal
+
+回看已经完成的 cc-highlight alignment 讨论，判断我们在子智能体 / 多智能体方面到底具体讨论到了什么程度，并对照《御舆》Chapter 9（必要时补充 Chapter 10 的多智能体编排要求）判断是否已经满足这些要求。
+
+## What I already know
+
+* 当前 canonical roadmap 用 H11/H12 表示 subagent / fork 相关亮点，用 H13/H14 表示 mailbox / coordinator 多智能体亮点。
+* `.trellis/tasks/04-16-cc-highlight-alignment-discussion/prd.md` 已经记录了 H11/H12 的 source-backed 讨论结论。
+* `.trellis/tasks/04-16-cc-highlight-alignment-discussion/h11-h12-alignment-research.md` 已经列出 cc 子智能体运行时、fork/cache、resume、lifecycle 的 gap matrix。
+* 当前 topology 里 H11/H12 相关任务包括 `L2-a`（AgentDefinition + general runtime）和 `L3-a`（sidechain transcript），H13/H14 仍 deferred。
+* `lintsinghua/claude-code-book` README 把第 9 章定义为“子智能体与 Fork 模式”，第 10 章定义为“协调器模式 — 多智能体编排”。
+* 实时 task ledger 显示：
+  * `L2-a H11/H12 AgentDefinition + general runtime` 已完成
+  * `L2-c H01 role-based tool projection` 已完成
+  * `L3-a H11/H12 subagent sidechain transcript` 仍是下一条未完成的 H11/H12 主线任务
+
+## Assumptions (temporary)
+
+* 用户说“子agent多agent方面”，严格来说至少需要同时看 Ch09 子智能体 / Fork 和 Ch10 Coordinator / multi-agent orchestration。
+* 本次目标是 requirements review，不是立刻新增实现任务。
+
+## Open Questions
+
+* `placeholder_tool_result_layout` 第一版是否只需要固定空壳布局，还是要同时定义 tool-use pairing / replacement-state hooks？
+
+## Requirements (evolving)
+
+* 明确区分“已经具体讨论过”与“只是高层提过/明确 deferred”。
+* 明确区分“满足 Ch09 子智能体要求”与“满足 Ch10 多智能体协调要求”。
+* 输出应包含章节要求、已有讨论、当前状态、缺口判断。
+* 给出“继续讨论 vs 先做前提条件”的推荐顺序。
+* 用户已选择继续做 Ch09 深水区讨论，而不是先实现 `L3-a`，也不是跳到 Ch10 coordinator。
+* 优先级按“收益最大”排，不按最小改动排。
+* 采用长远架构视角，优先边界清晰、后续可扩展的方案。
+* 不为了兼容旧方案、旧数据额外加桥接层或 fallback。
+* 如果新结构更合理，可以直接替换旧抽象。
+
+## Acceptance Criteria (evolving)
+
+* [x] 能指出 H11/H12/H13/H14 哪些已经被 source-backed 讨论覆盖。
+* [x] 能指出 Ch09 哪些要求已讨论、哪些未讨论或未满足。
+* [x] 能指出如果把“多 agent”扩大到 Ch10，目前哪些仍明显不满足。
+
+## Definition of Done (team quality bar)
+
+* 结论基于 Trellis 任务/PRD/roadmap 与外部章节内容，而不是凭记忆。
+* 明确列出满足 / 不满足 / 已 deferred 的边界。
+* 如果发现现有计划仍缺一个讨论维度，要明确指出下一步应补哪一块。
+
+## Out of Scope (explicit)
+
+* 不修改 `coding-deepgent` 产品代码。
+* 不重开 H13/H14 实现。
+* 不对整本书做逐章审计，只聚焦 Ch09/Ch10 与子智能体、多智能体相关部分。
+
+## Technical Notes
+
+* Local docs inspected:
+  * `.trellis/tasks/04-16-cc-highlight-alignment-discussion/prd.md`
+  * `.trellis/tasks/04-16-cc-highlight-alignment-discussion/h11-h12-alignment-research.md`
+  * `.trellis/tasks/04-17-cc-core-topology-closeout-plan/prd.md`
+  * `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+  * `.trellis/project-handoff.md`
+* External docs inspected:
+  * `https://lintsinghua.github.io/#ch09`
+  * GitHub mirror chapter pages:
+    * Chapter 9: `09-子智能体与Fork模式.md`
+    * Chapter 10: `10-协调器模式-多智能体编排.md`
+
+## Research Notes
+
+### External chapter requirements
+
+**Ch09 子智能体 / Fork**
+
+* 子智能体生成机制与完整生命周期管理
+* Fork 模式缓存共享与字节级继承
+* 自定义 / 内置智能体定义与加载
+* 对抗性验证 Agent 的设计哲学
+
+**Ch10 多智能体 / Coordinator**
+
+* Coordinator-Worker 架构
+* 协调者只编排不执行
+* SendMessage / mailbox / worker addressing
+* Scratchpad 协作空间
+* 多智能体完整工作流与故障恢复
+
+### Local discussion coverage
+
+**已经具体讨论过**
+
+* H11/H12：Agent-as-tool、general/verifier catalog、AgentDefinition、result envelope、sidechain transcript、fork/cache 差距、resume/lifecycle/deferred 边界
+* verifier 作为对抗性验证 agent 的角色与最小边界
+
+**只做了高层边界判断**
+
+* H13 Mailbox / SendMessage：明确 deferred
+* H14 Coordinator：明确 deferred
+* Fork/cache 深度 parity：明确 deferred，不做当前 MVP
+
+### Current repo state that matters for the decision
+
+Already done:
+
+* `L2-a`: `AgentDefinition` catalog for `general` / `verifier`
+* real read-only `general` child runtime
+* minimal structured subagent result envelope
+* fallback final-text extraction
+* `L2-c`: role-based tool projection through capability metadata
+
+Still missing on the current H11/H12 path:
+
+* `L3-a`: sidechain transcript persistence into parent JSONL
+* transcript/audit visibility for what child agents actually saw/did
+
+Still explicitly deferred:
+
+* mailbox / SendMessage
+* coordinator runtime
+* background/async agents
+* full fork/cache parity
+
+### Fork/cache parity research notes
+
+**Ch09 fork expectations from the book**
+
+* Fork is a distinct execution path triggered when agent type is omitted and fork mode is enabled.
+* Fork children inherit byte-identical request prefixes from the parent so Anthropic prompt cache can hit.
+* Cache safety depends on five dimensions staying identical:
+  * rendered system prompt bytes
+  * user context
+  * system context
+  * tool/model context
+  * message-prefix context
+* Fork uses exact parent tools instead of re-resolving tool pools.
+* `buildForkedMessages` preserves the full assistant tool-use block and injects fixed placeholder tool results so sibling children share the same prefix.
+* Recursive fork must be blocked by runtime markers plus a fallback scan.
+* Resume continuity matters: forked children should preserve prompt bytes and replacement state across resume.
+
+**Current local state against those expectations**
+
+* No implicit fork mode exists today.
+* No cache-safe parameter object exists.
+* No rendered-system-prompt byte threading exists for subagents.
+* No `useExactTools`-style exact parent tool inheritance exists for a fork path.
+* No placeholder tool-result construction exists for cache-sharing siblings.
+* No dedicated recursive-fork guard exists because there is no fork path yet.
+* No fork-specific resume path exists.
+* The current subagent path is still synchronous and bounded; it is not a background parallel worker model.
+
+**Local seams we can realistically build on later**
+
+* `RuntimeInvocation` already gives a typed child `thread_id` seam.
+* `AgentDefinition` already gives child identity, tool pool, and max-turn metadata.
+* `PromptContext.system_prompt` exists, but only as freshly joined strings; there is no persisted rendered-byte contract yet.
+* `SessionSidechainMessage` already models `subagent_thread_id` and `parent_message_id`.
+* The subagent path already records child thread lineage and can append sidechain-style transcript entries.
+* There is still no fork-specific marker equivalent to cc `querySource`, and no exact-parent-tools or placeholder tool-result payload builder.
+
+### Expansion sweep
+
+1. Future evolution
+* If fork is reopened later, it should not fight the current `AgentDefinition`/role-projection contract.
+* If H13/H14 are ever reopened, fork should remain the lightweight sibling of coordinator mode, not become a second coordinator.
+
+2. Related scenarios
+* `L3-a` sidechain transcript is the nearest adjacent seam because fork children still need auditability and parent/child linkage.
+* Resume continuity matters because fork without restart-safe lineage becomes hard to trust in long sessions.
+
+3. Failure / edge cases
+* Prompt-cache miss from rebuilt system prompt or re-resolved tools.
+* Recursive fork explosion.
+* Worktree/path drift when a child runs in an isolated workspace.
+* Broken resume if tool-use/tool-result replacement state is not reconstructed.
+
+### Feasible approaches here
+
+**Approach A: Finish the current Ch09-local MVP before new discussion** (Recommended)
+
+* How it works:
+  * Treat `L3-a` sidechain transcript as the last must-have local prerequisite.
+  * After `L3-a`, do one focused review of what remains missing from Ch09 and what stays deferred.
+* Pros:
+  * Lowest context switching.
+  * Closes the biggest remaining auditability gap in subagent runtime.
+  * Gives a more honest baseline before revisiting Fork/multi-agent aspirations.
+* Cons:
+  * Does not advance coordinator/mailbox discussions yet.
+
+**Approach B: Continue discussing Ch09 deep parity now**
+
+* How it works:
+  * Keep discussing full fork/cache parity, resume, async lifecycle, agent memory, summaries, and background agents before implementing `L3-a`.
+* Pros:
+  * Better long-range conceptual clarity.
+* Cons:
+  * Likely premature because current local MVP still lacks transcript/audit plumbing.
+  * Risks discussing around a missing concrete runtime seam.
+
+**Approach C: Jump to Ch10 multi-agent discussion now**
+
+* How it works:
+  * Start discussing coordinator, mailbox, Scratchpad, SendMessage, and worker orchestration despite H13/H14 being deferred.
+* Pros:
+  * Surfaces future architecture early.
+* Cons:
+  * Mismatched with current MVP boundary.
+  * Most likely becomes speculative because coordinator/mailbox are explicitly out of scope today.
+
+### Fork-specific approaches for the current discussion
+
+**Approach F1: Minimal cache-safe fork contract** (Recommended)
+
+* How it works:
+  * Discuss only the reusable fork contract:
+    * what must be byte-identical
+    * what metadata must be persisted
+    * how recursion should be blocked
+    * how fork stays distinct from coordinator
+  * Do not discuss background task lifecycle or mailbox.
+* Pros:
+  * Stays tightly inside Ch09.
+  * Produces a clean contract that can later sit on top of `L3-a`.
+  * Lowest speculation.
+* Cons:
+  * Will not answer all “full fork UX” questions.
+
+**Approach F2: Resume-first fork continuity**
+
+* How it works:
+  * Center the discussion on what transcript, metadata, rendered-prompt bytes, and replacement state would be needed so a future fork can resume safely.
+* Pros:
+  * Closest to the current missing runtime seam (`L3-a`).
+  * Connects fork discussion to durable session architecture.
+* Cons:
+  * More about continuity than about actual parallel fork execution.
+
+**Approach F3: Full Ch09 fork parity target**
+
+* How it works:
+  * Discuss the whole fork story now: implicit fork entry, exact-tool inheritance, placeholder tool results, background worker execution, recursion guard, worktree notice, resume, summary.
+* Pros:
+  * Maximally complete.
+* Cons:
+  * Highest speculation.
+  * Risks bleeding into H13/H14-style lifecycle/orchestration concerns.
+
+### Decision candidate inside F1
+
+The key unresolved boundary is how strict the minimal fork contract should be.
+
+**Option 1: Metadata-first contract**
+
+* Define only:
+  * fork lineage ids
+  * parent/child thread linkage
+  * recursion-guard marker
+  * worktree/isolation metadata
+* Treat byte-identical cache sharing as a future optimization.
+* Best when we want the smallest non-speculative local contract.
+
+**Option 2: Cache-contract-first**
+
+* Define byte-identity as a hard contract now:
+  * rendered system prompt bytes
+  * exact tool pool identity
+  * fork context message prefix
+  * placeholder tool-result layout
+  * recursion-guard marker
+* Even if implementation is deferred, future fork work must honor this exact cache-safe shape.
+* Best when we want Ch09 fork semantics to stay central.
+
+**Option 3: Hybrid**
+
+* Define:
+  * lineage / recursion / worktree metadata as hard requirements now
+  * rendered prompt bytes + exact tools + placeholder layout as "reserved fields with normative comments"
+* Best when we want to preserve the seam without claiming byte-identical behavior is fully settled.
+
+## Decision (ADR-lite)
+
+**Context**: 在 `L2-a` / `L2-c` 已完成后，当前可以选择继续补本地 H11/H12 前置（`L3-a`），也可以先继续讨论 Ch09 深水区，或者跳去 Ch10 多智能体编排。
+
+**Decision**: 用户选择继续做 Ch09 深水区讨论，不先实现 `L3-a`，也不进入 Ch10 coordinator / mailbox 讨论。
+
+**Consequences**:
+
+* 讨论范围先收敛在 Ch09 余下的大缺口：Fork/cache parity、resume/metadata continuity、async/background lifecycle / summary。
+* H13/H14 多智能体编排仍保持 deferred，不作为本轮讨论重点。
+* 后续需要在 Ch09 深水区内部再选一个优先主题，以避免讨论过散。
+
+## Decision (ADR-lite): Fork Discussion Boundary
+
+**Context**: 在 Ch09 深水区里，fork 可以只被当作 lineage/metadata 扩展，也可以被定义为 cache-safe execution contract。用户已明确选择后者。
+
+**Decision**: 本轮 fork 讨论采用 cache-contract-first 边界。fork 的本质不是普通子 agent lineage，而是未来必须满足的 cache-safe contract。即使实现暂缓，这个 contract 也应该先明确：
+
+* rendered system prompt bytes continuity
+* exact tool-pool identity
+* byte-identical fork message prefix
+* placeholder tool-result layout for sibling cache sharing
+* recursion guard marker
+
+**Consequences**:
+
+* 后续如果实现 fork，不能只靠 `AgentDefinition` + thread lineage 拼一个“类似 fork”的 path。
+* sidechain transcript、resume、worktree metadata 仍重要，但它们是支撑件，不是 fork 的核心定义。
+* 下一步最值得拍板的是 fork 的入口形态，因为它会影响 tool schema、prompt shape、cache contract ownership、以及是否和普通 subagent catalog 混在一起。
+
+## Decision (ADR-lite): Fork Entry Shape
+
+**Context**: 在 cache-contract-first 边界下，fork 的核心价值是 cache-safe sibling execution，而不是普通 agent catalog 的一个变体。如果继续复用 `run_subagent` / `agent_type` 体系，fork 很容易退化成“继承上下文的普通子 agent”，从而稀释 byte-identical prefix、exact tool pool、placeholder tool results 这些核心语义。
+
+**Decision**: 未来 fork 采用独立显式模式，不复用普通 `run_subagent` / `agent_type` 入口。
+
+**Consequences**:
+
+* fork 可以单独拥有 cache-safe contract，而不和 `general` / `verifier` 的 `AgentDefinition` 语义混杂。
+* `AgentDefinition` 继续服务普通 child runtime；fork 作为平行能力，服务“same-agent sibling execution”。
+* 后续需要继续明确第一版 fork 的范围，尤其是是否只支持同配置 sibling fork，还是立即引入 worktree/isolation 变体。
+* 范围判断应优先看长期边界是否清晰，而不是先选“改动最小”的方案。
+* 如果 fork 需要独立抽象，就直接独立，不为兼容当前 `run_subagent` 入口增加桥接层。
+
+## Technical Approach
+
+Fork 最小 cache-safe contract 的推荐草案：
+
+### 1. rendered_system_prompt_bytes
+
+* Fork child 不重新动态构造 system prompt。
+* Parent 在 fork 时必须传递一份已渲染完成的 system prompt bytes/string。
+* Resume 时优先恢复这份 rendered prompt，而不是重新调用 prompt builder。
+
+### 2. exact_tool_pool_identity
+
+* Fork child 不重新按 role/projection 解析工具池。
+* Fork child 直接继承 parent 当次调用实际可见的 tool identity 集合。
+* 这个 identity 应可序列化并可恢复，用于 fork resume continuity。
+* 推荐把 identity 定义为**稳定排序的可见工具描述快照**，而不是只有工具名列表。
+
+### 3. fork_message_prefix_shape
+
+* Fork child 的前缀必须定义为“parent 已有消息前缀 + 固定 fork directive block”。
+* 该 prefix shape 必须是规范化 contract，而不是运行时临时拼接。
+* sibling forks 之间除 fork-specific directive 外，prefix 必须保持 byte-identical。
+* fork-specific directive block 采用**极薄固定指令**，不承载富任务描述，不让 fork 退化成普通 subagent prompt。
+
+### 4. placeholder_tool_result_layout
+
+* 如果 fork 发生时 parent 历史里存在相关 tool-use context，则 sibling forks 必须共享固定 placeholder tool-result layout。
+* placeholder 是 cache contract 的一部分，不是纯显示层。
+* 不要求当前就实现完整 provider cache 命中，但字段和布局必须先固定。
+
+### 5. recursion_guard_marker
+
+* Fork path 必须带显式 recursion marker。
+* 该 marker 同时服务：
+  * runtime fast-path guard
+  * transcript scan fallback guard
+  * future resume guard
+
+### Recommended first-version boundary
+
+* 第一版只定义 same-config sibling fork contract。
+* 不在第一版引入：
+  * isolated worktree execution
+  * path remap notice
+  * background lifecycle / summary agent
+  * mailbox / coordinator semantics
+
+### Why this boundary
+
+* 最大化 Ch09 fork 语义纯度。
+* 保住 future cache parity 的核心 seam。
+* 不让 fork 过早滑向 H13/H14 的多智能体编排。
+
+## Decision (ADR-lite): Thin Fork Directive
+
+**Context**: 如果 fork directive block 过厚，包含大段任务描述、临时上下文摘要、工具说明或自由文本目标，sibling forks 的 prefix 会过早分叉，fork 很容易退化成“重新发一个普通 subagent 任务”。
+
+**Decision**: `fork_message_prefix_shape` 采用极薄固定指令。该指令只承担 fork 身份声明、cache-safe 约束说明、最小 fork intent 标识，不承载富任务描述。
+
+**Consequences**:
+
+* sibling forks 更容易保持 byte-identical prefix。
+* fork 与普通 `run_subagent(task=...)` 的语义边界更清晰。
+* richer task framing 如果未来确有需要，应通过独立字段或后缀差异承载，而不是塞进固定 fork directive block。
+
+## Decision (ADR-lite): Exact Tool Pool Identity
+
+**Context**: 如果 `exact_tool_pool_identity` 只记录工具名列表，那么 fork 只能证明“名字一样”，却无法证明模型看到的工具表面完全一致。工具顺序、schema 摘要、暴露面变化都可能破坏 cache-safe 语义，但不会反映在 name-only identity 中。
+
+**Decision**: `exact_tool_pool_identity` 采用**稳定排序的可见工具描述快照**。第一版至少应覆盖：
+
+* tool name
+* stable visible order
+* schema fingerprint or stable schema summary
+* exposure-visible descriptor needed by the model surface
+
+而不是只保留工具名列表。
+
+**Consequences**:
+
+* fork cache-safe contract 更接近“模型实际看到的是同一组工具表面”，而不是仅仅“运行时注册了同名工具”。
+* 未来即使底层 registry/projection 重构，只要可见工具描述快照不变，fork contract 仍然清晰。
+* 如果工具 schema 或显示顺序变化，fork 应视为不同 tool-pool identity，而不是偷偷复用旧 fork contract。
+
+## Final Convergence
+
+### Goal
+
+一次性定清 Ch09 这一轮真正要交付的功能边界，然后按一个高耦合集成包完成，不把 fork 继续拆成零碎 patch。
+
+### In Scope
+
+* 普通子 agent 能被当作真正的“分支执行者”，而不只是 verifier 特例
+* 子 agent 的过程能被父会话审计和追踪
+* fork 有独立显式入口，不混入普通 subagent
+* fork 保证“同一个父上下文分出多个 sibling 分支”时，模型侧看到的关键前缀和工具表面保持稳定
+* fork 第一版只支持 same-config sibling fork，不引入多工作区/多机器/协调器
+
+### Out of Scope
+
+* coordinator / mailbox / SendMessage / Scratchpad
+* 多智能体编排
+* isolated worktree/path remap
+* background lifecycle / summary side-agent
+* full fork resume implementation
+
+### Locked Decisions
+
+* fork 采用独立显式模式，不复用普通 `run_subagent`
+* fork 的核心按 cache-safe contract 定义，而不是普通 lineage metadata
+* fork directive 采用极薄固定指令，不承载富任务描述
+* exact tool pool 采用稳定排序的可见工具描述快照，而不是 name-only list
+* 长远边界优先于最小改动；不为旧抽象保留桥接层/fallback
+
+### One-Pass Delivery Plan
+
+**Package 1: child auditability foundation**
+
+* 完成 `L3-a` sidechain transcript
+* 让 parent session 能看见 child 的 user/assistant sidechain
+* 保证 compact/collapse/resume 不把 sidechain 错暴露到主上下文
+
+**Package 2: explicit fork contract**
+
+* 新增独立 fork 入口
+* 定义 same-config sibling fork 的最小输入/输出 contract
+* 固定 fork lineage / recursion guard / exact tool pool snapshot / thin directive / prefix shape
+
+**Package 3: placeholder + continuity seam**
+
+* 定义 placeholder tool-result layout
+* 同时定义 tool-use pairing / replacement-state hook 的 contract seam
+* 即使完整 fork resume 暂不实现，也要保证未来 continuity 不会推翻 fork contract
+
+### Acceptance Criteria
+
+* [x] 子 agent 过程可在 parent session 中被审计
+* [x] fork 与普通 subagent 是两条清晰分开的入口
+* [x] same-config sibling fork 的关键前缀 contract 已固定
+* [x] tool surface identity 不是 name-only，而是模型可见表面的稳定快照
+* [x] placeholder/result continuity seam 已固定，不需要未来靠桥接层补救
+* [x] H13/H14 多智能体编排仍明确保持 out of scope
+
+## Final Closeout (2026-04-19)
+
+This Ch09/Ch10 review is complete and should no longer remain active:
+
+* The review separated Ch09 subagent/fork requirements from Ch10
+  coordinator/mailbox requirements.
+* The local Ch09 MVP path was subsequently implemented through the topology
+  closeout: `AgentDefinition`, read-only `general` / `verifier`, sidechain
+  transcript audit, explicit fork surfaces, background/fork status tooling, and
+  resume/fork-resume boundary hardening.
+* The canonical roadmap now marks H11 and H12 as implemented for the local MVP
+  slice, while H13/H14 coordinator/mailbox remain explicitly deferred.
+* Any future Ch10 work should open a new source-backed coordinator/mailbox PRD
+  rather than reopening this review task.
diff --git a/.trellis/tasks/archive/2026-04/04-17-subagent-multiagent-ch09-review/task.json b/.trellis/tasks/archive/2026-04/04-17-subagent-multiagent-ch09-review/task.json
new file mode 100644
index 000000000..4530994de
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-17-subagent-multiagent-ch09-review/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "subagent-multiagent-ch09-review",
+  "name": "subagent-multiagent-ch09-review",
+  "title": "brainstorm: subagent multi-agent ch09 gap review",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-17",
+  "completedAt": "2026-04-19",
+  "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/archive/2026-04/04-18-auto-memory-agent-private-memory/check.jsonl b/.trellis/tasks/archive/2026-04/04-18-auto-memory-agent-private-memory/check.jsonl
new file mode 100644
index 000000000..dfe6526d5
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-auto-memory-agent-private-memory/check.jsonl
@@ -0,0 +1,2 @@
+{"file": ".gemini/commands/trellis/finish-work.toml", "reason": "Finish work checklist"}
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-18-auto-memory-agent-private-memory/debug.jsonl b/.trellis/tasks/archive/2026-04/04-18-auto-memory-agent-private-memory/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-auto-memory-agent-private-memory/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-18-auto-memory-agent-private-memory/implement.jsonl b/.trellis/tasks/archive/2026-04/04-18-auto-memory-agent-private-memory/implement.jsonl
new file mode 100644
index 000000000..137b4729e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-auto-memory-agent-private-memory/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-18-auto-memory-agent-private-memory/prd.md b/.trellis/tasks/archive/2026-04/04-18-auto-memory-agent-private-memory/prd.md
new file mode 100644
index 000000000..aa3590ed5
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-auto-memory-agent-private-memory/prd.md
@@ -0,0 +1,180 @@
+# Automatic memory extraction and agent-private memory productization
+
+## Goal
+
+在已经完成的长期记忆后端基础上，把 `10` 的后半段真正做成产品能力：
+
+* 自动提取长期记忆
+* agent 私有记忆
+* agent 记忆快照与刷新
+
+让系统不仅“能把长期记忆存进后端”，而且能开始：
+
+* 自动沉淀长期记忆
+* 为不同 agent 维护各自的长期上下文
+* 以任务状态、快照和审计方式稳定运行
+
+## Why Now
+
+当前已经有：
+
+* 项目级规则文件层
+* 长期记忆四类型
+* 当前会话记忆
+* 恢复上下文
+* PostgreSQL 长期记忆主存储
+* Redis 队列
+* MinIO 归档
+* extraction job / snapshot job 基础
+
+但现在这些能力还偏“后端基础设施已经有了”，离产品化还差一层：
+
+* 自动提取结果还不够可控/可审计/可理解
+* agent scope 已有基础，但还不是一个真正可用的产品能力
+* snapshot 已有 archive 通道，但还没有清晰的可用行为和可见面
+
+## What I already know
+
+* 长期记忆 durable backend 已完成并打通 PostgreSQL / Redis / MinIO
+* `save_memory / list_memory / delete_memory` 已存在
+* `MemoryService` 已能 enqueue extraction 和 snapshot refresh
+* 默认 extractor 目前还是保守 heuristic，不是最终产品行为
+* 当前 agent scope 只是基础元数据，不是完整产品面
+* 当前 session JSONL ledger 继续保留，不迁移数据库
+
+## Requirements
+
+* 本轮必须把自动提取长期记忆做成真正可用的产品能力，而不是仅停在 job plumbing。
+* 本轮必须把 agent 私有记忆做成真正可查询、可隔离、可刷新的能力，而不是只保留 scope 字段。
+* PostgreSQL 继续作为长期记忆事实来源。
+* Redis 继续负责任务调度。
+* MinIO 继续负责快照/归档对象。
+* 不迁移 transcript / session ledger。
+
+## Acceptance Targets
+
+* [x] 系统能自动从会话中提出长期记忆候选，并通过后台任务处理，而不阻塞主流程。
+* [x] 自动提取结果不会无约束地直接污染长期记忆，至少具备可审计来源和任务状态。
+* [x] agent 私有记忆与全局长期记忆能明确区分。
+* [x] 针对某个 agent 查询长期记忆时，能够得到：
+  * 该 agent 私有记忆
+  * 以及仍然适用的全局长期记忆
+* [x] agent snapshot/refresh 形成清晰产品行为：
+  * 什么时候刷新
+  * 刷新后保存什么
+  * archive 对象在哪里
+* [x] 当前实现足以支撑后续更强的自动化，而不需要再次重做存储边界。
+
+## Planned Features
+
+### 1. Automatic Memory Extraction Product Layer
+
+* 为自动提取任务增加清晰行为：
+  * 候选生成
+  * 任务写入
+  * 后台处理
+  * 结果写回长期记忆
+* 给自动提取结果补最小审计信息：
+  * source
+  * job id
+  * created_at
+  * status
+* 让自动提取和现有质量规则协同，而不是绕过它们
+
+### 2. Agent-Private Memory Read/Write Path
+
+* 让 agent scope 真正参与：
+  * save
+  * list
+  * recall
+  * delete
+* 主 agent 继续默认写全局长期记忆
+* child / subagent 可以拥有私有长期记忆 scope
+
+### 3. Snapshot Product Behavior
+
+* 为 agent snapshot 明确最小产品行为：
+  * 刷新 job 什么时候触发
+  * snapshot 保存哪些长期记忆
+  * snapshot archive object key 如何生成
+* 将 snapshot 结果与 job 状态联通，形成可追踪结果
+
+### 4. Focused CLI / Inspection Surface
+
+* 在现有 `memory jobs` 基础上补足足够查看状态的输出
+* 必要时增加最小 inspection 命令，帮助确认：
+  * 某 agent 当前有哪些私有记忆
+  * 最近一次 snapshot/refresh 是否完成
+
+## Planned Extensions
+
+* 自动提取结果审核流
+* 更复杂的提取策略（LLM-based extraction）
+* path-scoped agent memory
+* 跨项目共享 agent memory
+* 更强的 snapshot restore/import/export 体验
+* stale-memory trust scoring
+* semantic retrieval / ranking
+
+## Definition of Done
+
+* 自动提取长期记忆对用户/系统是“可见且可解释”的
+* agent 私有记忆已形成真实能力，而不是只存在 schema 中
+* snapshot/refresh 行为被清楚定义并可测试
+* Focused pytest / ruff / mypy 通过
+* Trellis docs/PRD 记录清楚当前已做和未来扩展边界
+
+## Technical Approach
+
+* 继续复用当前 durable backend：
+  * PostgreSQL
+  * Redis
+  * MinIO
+* 在 `memory.service` 之上补产品行为，不重写底层存储
+* extractor 继续保留可替换接口，但把当前默认实现做成更像产品能力的最小版本
+* agent scope 通过 repository/service 正式进入读取和刷新链
+
+## Out Of Scope
+
+* transcript / session ledger 迁库
+* vector retrieval
+* path-scoped rules
+* user-scoped rules files
+* 多租户体系
+
+## Technical Notes
+
+* `.trellis/tasks/04-18-unified-context-memory-closeout/prd.md`
+* `.trellis/tasks/04-18-memory-module-gap-review/prd.md`
+* `.trellis/spec/guides/planning-targets-guide.md`
+* `.trellis/spec/backend/database-guidelines.md`
+* `.trellis/spec/backend/project-infrastructure-foundation-contracts.md`
+* `coding-deepgent/src/coding_deepgent/memory/backend.py`
+* `coding-deepgent/src/coding_deepgent/memory/service.py`
+* `coding-deepgent/src/coding_deepgent/memory/extractor.py`
+* `coding-deepgent/src/coding_deepgent/memory/runtime_support.py`
+
+## Checkpoint
+
+State:
+- terminal
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added automatic extraction jobs on top of the durable memory backend.
+- Added product-facing inspection for memory jobs, memory records, and agent scopes.
+- Added agent-private memory scope behavior so child/fork agents can enqueue and read private long-term memory while the main agent remains global by default.
+- Added snapshot/archive job handling through the same service layer.
+- Kept session JSONL ledger untouched as intended.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_memory_backend.py coding-deepgent/tests/test_memory_cli.py coding-deepgent/tests/test_subagents.py`
+- broader focused memory/runtime verification still passed after backend integration
+- `ruff check ...`
+- `mypy ...`
+- live smoke with configured services:
+  - PostgreSQL: ok
+  - Redis queue: ok
+  - MinIO/S3-compatible archive: ok
diff --git a/.trellis/tasks/archive/2026-04/04-18-auto-memory-agent-private-memory/task.json b/.trellis/tasks/archive/2026-04/04-18-auto-memory-agent-private-memory/task.json
new file mode 100644
index 000000000..a2d0ef653
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-auto-memory-agent-private-memory/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "auto-memory-agent-private-memory",
+  "name": "auto-memory-agent-private-memory",
+  "title": "Automatic memory extraction and agent-private memory productization",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-18",
+  "completedAt": "2026-04-18",
+  "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/archive/2026-04/04-18-compare-subagent-vs-cc-gap/prd.md b/.trellis/tasks/archive/2026-04/04-18-compare-subagent-vs-cc-gap/prd.md
new file mode 100644
index 000000000..247b8ed11
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-compare-subagent-vs-cc-gap/prd.md
@@ -0,0 +1,177 @@
+# brainstorm: compare subagent vs cc gap
+
+## Goal
+
+基于当前 `coding-deepgent/` 主线实现，重新判断“子 agent 相比 Claude Code / 《御舆》Chapter 9 还差多少”。本次目标是做 source-backed 差距评估与范围确认，不直接改代码。
+
+## What I already know
+
+* 用户给出的主要参考是《御舆》在线阅读页 Chapter 9：`https://lintsinghua.github.io/#ch09`。
+* `coding-deepgent` 当前 roadmap 已将：
+  * `H11 Agent as tool and runtime object` 标为 `implemented`
+  * `H12 Fork/cache-aware subagent execution` 标为 `implemented-minimal`
+* 旧的 `.trellis/tasks/04-17-subagent-multiagent-ch09-review/prd.md` 和
+  `.trellis/tasks/04-16-cc-highlight-alignment-discussion/h11-h12-alignment-research.md`
+  已经过时，原因是之后又完成了：
+  * `L3-a H11/H12 subagent sidechain transcript`
+  * `L5-b deferred boundary ADR refresh`
+  * roadmap/dashboard 对 H11/H12 状态的刷新
+* 当前代码里已经存在真实的子 agent / fork 运行时，而不是只有规划：
+  * `run_subagent(task, agent_type="general" | "verifier", ...)`
+  * `run_fork(intent, ...)`
+  * `AgentDefinition` with `description`, `when_to_use`, `tool_allowlist`,
+    `disallowed_tools`, `max_turns`, `model_profile`
+* 当前已经落地的关键 H11/H12 能力：
+  * `general` / `verifier` 都走真实 child `create_agent` 路径
+  * child tool surface 仍是只读边界：`read_file`, `glob`, `grep`, `task_get`,
+    `task_list`, `plan_get`
+  * `verifier` 绑定 durable `plan_id`，并把 verdict 以 evidence 写回 session ledger
+  * parent session JSONL 已持久化 sidechain transcript，包含
+    `parent_message_id` / `parent_thread_id` / `subagent_thread_id`
+  * `run_fork` 已经是独立入口，不混入普通 `run_subagent`
+  * `run_fork` 直接继承 parent `rendered_system_prompt` 与
+    `visible_tool_projection`
+  * `run_fork` 输出已包含 `rendered_prompt_fingerprint`、
+    `tool_pool_identity`、`placeholder_layout`
+  * fork 已有递归防护：runtime entry guard + marker scan
+* 当前仍然明显不具备的 cc / Ch09 深水区能力：
+  * 三种 agent 来源完整体系（built-in / custom / plugin）尚未落地
+  * 丰富内置 agent catalog 尚未落地，目前只有 `general` / `verifier`
+  * per-agent hooks / skills / MCP additive / permission mode override 尚未落地
+  * async/background child lifecycle、cleanup inventory、kill / notification /
+    progress tracker 尚未落地
+  * full fork/cache parity 尚未落地：placeholder tool-result 重建、replacement
+    state continuity、resume continuity、真正 cache-safe prefix contract 仍未完成
+* 当前实现里还有一个重要“表面 contract > 实际执行”的差距：
+  * `run_subagent_task` 计算了 `effective_max_turns` 后直接丢弃
+  * `run_fork_task` 直接 `del max_turns`
+  * 也就是 schema/definition 有 `max_turns`，但运行时没有真正使用
+
+## Assumptions (temporary)
+
+* 用户口中的 “cc” 大概率是指 Claude Code / 《御舆》Chapter 9 所描述的子智能体与 Fork 体系，而不是 Ch10 coordinator 多智能体编排。
+* 本轮更像 parity audit / brainstorming，而不是进入实现阶段。
+* “差多少” 需要同时区分两种口径：
+  * `MVP local slice`：是否已经达到本地最小可用边界
+  * `full cc parity`：距离 Claude Code Chapter 9 完整体系还有多远
+
+## Open Questions
+
+* 这次比较的口径是否只看 Chapter 9 子智能体 / Fork，还是也要顺带把真实 Claude Code 的完整子 agent runtime（超出 Ch09 摘要的部分）一起算进去？
+
+## Requirements (evolving)
+
+* 用当前代码与当前 roadmap，而不是用旧 brainstorm 结论，重新判断差距。
+* 明确区分：
+  * 已实现
+  * 已实现但只是 minimal slice
+  * 明确 deferred
+  * 仍然缺失 / contract 未兑现
+* 输出里要把 “已经不差太多” 和 “其实还差很远” 放在不同口径下说明，避免一句话混淆。
+* 如果给百分比，只能给近似量级，并解释估算口径。
+* 要指出最影响判断的 1-3 个关键缺口。
+
+## Acceptance Criteria (evolving)
+
+* [ ] 能基于当前代码说明 H11/H12 已经落地到什么程度。
+* [ ] 能指出旧调研中哪些 gap 已经不再成立。
+* [ ] 能指出当前仍然缺失的 cc / Ch09 关键能力。
+* [ ] 能给出至少两种口径下的差距判断：local MVP vs full cc parity。
+
+## Definition of Done (team quality bar)
+
+* 结论必须同时有本地代码/任务证据和外部章节证据。
+* 不把 roadmap 的 `implemented` 直接当成 full parity 结论。
+* 不把明确 deferred 的能力误判为“实现漏掉了”。
+* 如果发现 contract 与实现不一致，要明确单独指出。
+
+## Out of Scope (explicit)
+
+* 不直接修改 `coding-deepgent` 代码。
+* 不扩展到 Ch10 coordinator / mailbox / SendMessage，除非用户明确要求。
+* 不对全书逐章审计。
+
+## Technical Notes
+
+* External sources inspected:
+  * `https://lintsinghua.github.io/#ch09`
+  * `https://github.com/lintsinghua/claude-code-book`
+  * `第三部分-高级模式篇/09-子智能体与Fork模式.md`
+* Local sources inspected:
+  * `coding-deepgent/src/coding_deepgent/subagents/tools.py`
+  * `coding-deepgent/src/coding_deepgent/subagents/schemas.py`
+  * `coding-deepgent/tests/test_subagents.py`
+  * `.trellis/spec/backend/task-workflow-contracts.md`
+  * `.trellis/spec/backend/project-infrastructure-foundation-contracts.md`
+  * `.trellis/tasks/04-17-subagent-multiagent-ch09-review/prd.md`
+  * `.trellis/tasks/04-17-l5b-deferred-boundary-adr-refresh/prd.md`
+  * `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+
+## Research Notes
+
+### Chapter 9 expected effect summary
+
+Chapter 9 关注的不是“有没有一个叫 subagent 的工具”，而是四类效果：
+
+* 子智能体作为独立 runtime object 的生成与生命周期管理
+* Fork 作为 same-config sibling branch 的缓存友好继承
+* agent definition / 来源体系（built-in / custom / plugin）
+* verifier / adversarial verification 这类专业 agent 的工程角色
+
+### Current local evaluation snapshot
+
+**已经对上的最小核心**
+
+* bounded read-only `general` / `verifier` child runtime
+* verifier-plan boundary + evidence persistence
+* sidechain transcript audit
+* explicit `run_fork` entry with rendered-prompt/tool snapshot lineage
+* fork recursion guard
+
+**已经有形，但还是 partial**
+
+* `AgentDefinition` 结构已经有，但 catalog 仍极小
+* fork continuity metadata 已有，但 full cache-safe execution contract 尚未完成
+* roadmap 认为 H12 `implemented-minimal`，不是 full parity
+
+**仍明显缺失**
+
+* custom/plugin agents
+* async/background agent lifecycle
+* richer cleanup / notification / progress / resume
+* full fork placeholder replacement-state and resume continuity
+* actual enforcement of `max_turns`
+
+### Priority proposal
+
+**P0: must-fix inside the already-claimed local surface**
+
+* `max_turns` contract debt:
+  * `run_subagent_task()` computes `effective_max_turns` and drops it
+  * `run_fork_task()` drops `max_turns` entirely
+  * This is the clearest “schema says yes, runtime does nothing” gap
+* `model_profile` contract debt:
+  * `AgentDefinition.model_profile` exists, but child runtime still always uses
+    `build_openai_model()` without per-agent routing
+  * Either wire it, or explicitly narrow the contract
+
+**P1: highest-value parity work if we want to get closer to cc Ch09**
+
+* expand agent catalog and source model:
+  * richer built-in catalog
+  * custom agent definitions
+  * plugin-provided agents
+* deepen fork/cache continuity:
+  * real placeholder tool-result reconstruction
+  * replacement-state continuity
+  * resume-safe fork prefix continuity
+* add runtime-object lifecycle beyond synchronous MVP:
+  * background/async child lifecycle
+  * cancellation / cleanup / notification / progress
+
+**P2: explicitly deferred under current product boundary**
+
+* mailbox / SendMessage / coordinator team runtime
+* full team orchestration and worker collaboration plane
+* UI-heavy task panel / progress UX details
+* provider-specific cache/cost instrumentation polish
diff --git a/.trellis/tasks/archive/2026-04/04-18-compare-subagent-vs-cc-gap/task.json b/.trellis/tasks/archive/2026-04/04-18-compare-subagent-vs-cc-gap/task.json
new file mode 100644
index 000000000..0504209f0
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-compare-subagent-vs-cc-gap/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "compare-subagent-vs-cc-gap",
+  "name": "compare-subagent-vs-cc-gap",
+  "title": "brainstorm: compare subagent vs cc gap",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-18",
+  "completedAt": "2026-04-19",
+  "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/archive/2026-04/04-18-fork-explicit-cache-safe-contract/check.jsonl b/.trellis/tasks/archive/2026-04/04-18-fork-explicit-cache-safe-contract/check.jsonl
new file mode 100644
index 000000000..de280eac2
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-fork-explicit-cache-safe-contract/check.jsonl
@@ -0,0 +1,4 @@
+{"file": ".gemini/commands/trellis/finish-work.toml", "reason": "Finish work checklist"}
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".trellis/spec/backend/langchain-native-guidelines.md", "reason": "Review fork implementation against tool/schema/runtime boundary rules."}
+{"file": ".trellis/spec/backend/task-workflow-contracts.md", "reason": "Review subagent/fork contracts against durable workflow expectations."}
diff --git a/.trellis/tasks/archive/2026-04/04-18-fork-explicit-cache-safe-contract/debug.jsonl b/.trellis/tasks/archive/2026-04/04-18-fork-explicit-cache-safe-contract/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-fork-explicit-cache-safe-contract/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-18-fork-explicit-cache-safe-contract/implement.jsonl b/.trellis/tasks/archive/2026-04/04-18-fork-explicit-cache-safe-contract/implement.jsonl
new file mode 100644
index 000000000..6b346b07b
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-fork-explicit-cache-safe-contract/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": ".trellis/spec/backend/task-workflow-contracts.md", "reason": "Subagent and agent definition contracts own child runtime/result/session expectations."}
+{"file": ".trellis/spec/backend/session-compact-contracts.md", "reason": "Fork sidechain and future continuity must preserve session ledger and projection boundaries."}
+{"file": ".trellis/spec/backend/langchain-native-guidelines.md", "reason": "Fork entry and subagent runtime stay on official LangChain tool/agent surfaces."}
diff --git a/.trellis/tasks/archive/2026-04/04-18-fork-explicit-cache-safe-contract/prd.md b/.trellis/tasks/archive/2026-04/04-18-fork-explicit-cache-safe-contract/prd.md
new file mode 100644
index 000000000..22f5a7126
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-fork-explicit-cache-safe-contract/prd.md
@@ -0,0 +1,45 @@
+# Fork explicit cache-safe contract and entrypoint
+
+## Goal
+
+Add the first local fork package as a distinct capability rather than overloading
+the normal subagent path. The feature should let the parent conversation spawn a
+same-config sibling branch that preserves the rendered prompt and visible tool
+surface contract while keeping future continuity/resume seams explicit.
+
+## Requirements
+
+* Add a separate `run_fork` tool instead of extending `run_subagent`.
+* Fork must use the parent invocation's rendered system prompt and visible tool
+  projection directly.
+* Fork must append a thin fixed directive carrying only branch intent.
+* Fork must return structured JSON including parent/child thread lineage and
+  fork contract fingerprints.
+* Fork must emit sidechain transcript entries into the parent session ledger
+  with bounded fork continuity metadata.
+* Fork must reject nested forks via an explicit recursion guard.
+
+## Acceptance Criteria
+
+* [x] Main tool surface exposes `run_fork`.
+* [x] `run_fork` uses a distinct runtime entrypoint and thread suffix.
+* [x] Fork payload inherits parent context and exact visible tools.
+* [x] Fork output is parseable as structured JSON.
+* [x] Parent session ledger records fork sidechain entries with bounded metadata.
+* [x] Recursion guard blocks nested fork attempts.
+
+## Technical Approach
+
+* Extend `RuntimeContext` with rendered prompt and visible tool projection
+  seams populated by bootstrap/runtime invocation construction.
+* Add fork schemas and result envelopes under `subagents/schemas.py`.
+* Add fork execution helpers under `subagents/tools.py`.
+* Register `run_fork` in the main tool system and capability registry.
+* Reuse the parent session ledger as the fork audit surface.
+
+## Out of Scope
+
+* isolated worktrees
+* full fork resume
+* background lifecycle
+* coordinator / mailbox / multi-agent orchestration
diff --git a/.trellis/tasks/archive/2026-04/04-18-fork-explicit-cache-safe-contract/task.json b/.trellis/tasks/archive/2026-04/04-18-fork-explicit-cache-safe-contract/task.json
new file mode 100644
index 000000000..07253682c
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-fork-explicit-cache-safe-contract/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "fork-explicit-cache-safe-contract",
+  "name": "fork-explicit-cache-safe-contract",
+  "title": "Fork explicit cache-safe contract and entrypoint",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-18",
+  "completedAt": "2026-04-18",
+  "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": null,
+  "relatedFiles": [],
+  "notes": "Completed 2026-04-18. Added explicit run_fork tool and same-config sibling fork contract, injected rendered system prompt and visible tool projection into runtime context, returned structured fork result envelopes, recorded fork sidechain transcript entries with bounded continuity metadata, and blocked nested fork recursion. Fork remains separate from coordinator/mailbox/background/worktree concerns.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-18-l1a-h11-subagent-max-turns-and-model-routing/prd.md b/.trellis/tasks/archive/2026-04/04-18-l1a-h11-subagent-max-turns-and-model-routing/prd.md
new file mode 100644
index 000000000..c76d6181d
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-l1a-h11-subagent-max-turns-and-model-routing/prd.md
@@ -0,0 +1,40 @@
+# L1-a: H11 subagent max_turns and model routing
+
+## Goal
+
+补齐当前 `run_subagent` / `run_fork` 的 contract debt：让 `max_turns` 真正生效，并让不同 agent definition 能走不同模型配置。
+
+## Requirements
+
+* `run_subagent(max_turns=...)` 必须真正影响 child execution，而不是只通过 schema 校验。
+* `run_fork(max_turns=...)` 必须真正影响 fork child execution。
+* 运行时必须同时遵守：
+  * 调用方请求上限
+  * agent definition 自身上限
+* `AgentDefinition.model_profile` 必须真正影响 child model selection。
+* 现有 `general` / `verifier` 行为保持兼容，除本任务明确修正的 turn/model 行为外不回退。
+
+## Acceptance Criteria
+
+* [ ] `run_subagent(max_turns=1)` 和更高值在测试里表现出不同的 child turn ceiling。
+* [ ] `run_fork(max_turns=1)` 和更高值在测试里表现出不同的 child turn ceiling。
+* [ ] agent definition 可以声明不同 `model_profile`，并在 child runtime 中生效。
+* [ ] 无效 turn/model 配置会显式报错，不静默 fallback。
+
+## Dependencies
+
+* Depends on the existing H11/H12 baseline in:
+  * `04-17-l2a-h11-h12-agent-definition-general-runtime`
+  * `04-17-l3a-h11-h12-subagent-sidechain-transcript`
+
+## Context Sources
+
+* `coding-deepgent/src/coding_deepgent/subagents/tools.py`
+* `coding-deepgent/src/coding_deepgent/subagents/schemas.py`
+* `.trellis/spec/backend/task-workflow-contracts.md`
+
+## Out of Scope
+
+* Adding new agent types
+* Custom agent loading
+* Background execution
diff --git a/.trellis/tasks/archive/2026-04/04-18-l1a-h11-subagent-max-turns-and-model-routing/task.json b/.trellis/tasks/archive/2026-04/04-18-l1a-h11-subagent-max-turns-and-model-routing/task.json
new file mode 100644
index 000000000..79d6800cf
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-l1a-h11-subagent-max-turns-and-model-routing/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l1a-h11-subagent-max-turns-and-model-routing",
+  "name": "l1a-h11-subagent-max-turns-and-model-routing",
+  "title": "L1-a: H11 subagent max_turns and model routing",
+  "description": "Make subagent max_turns effective and wire per-agent model selection.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-18",
+  "completedAt": "2026-04-19",
+  "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-18-subagent-batch1-parity-implementation-plan",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-18-l1b-h11-built-in-subagent-catalog-expansion/prd.md b/.trellis/tasks/archive/2026-04/04-18-l1b-h11-built-in-subagent-catalog-expansion/prd.md
new file mode 100644
index 000000000..74388cf4e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-l1b-h11-built-in-subagent-catalog-expansion/prd.md
@@ -0,0 +1,42 @@
+# L1-b: H11 built-in subagent catalog expansion
+
+## Goal
+
+把当前只有 `general` / `verifier` 的 built-in subagent catalog 扩成更有用的第一批角色集合。
+
+## Requirements
+
+* 在现有 built-in catalog 上新增下一批内建角色，至少覆盖：
+  * `explore`
+  * `plan`
+* 每个 built-in agent 都必须声明：
+  * description
+  * when-to-use
+  * tool allowlist / disallow list
+  * `max_turns`
+  * `model_profile`
+* 本批次新增 built-in agent 仍保持 read-only，不引入 write-capable coder agent。
+* `run_subagent` schema / catalog / prompts / tests 必须一起更新。
+
+## Acceptance Criteria
+
+* [ ] built-in catalog 至少包含 `general`, `verifier`, `explore`, `plan`。
+* [ ] 模型可见的 agent type surface 与 catalog 一致。
+* [ ] 新 agent 有独立 prompt 和独立 limit/profile，不只是 `general` 换名复用。
+* [ ] 现有 `general` / `verifier` 回归测试继续通过。
+
+## Dependencies
+
+* Depends on `04-18-l1a-h11-subagent-max-turns-and-model-routing`.
+
+## Context Sources
+
+* `coding-deepgent/src/coding_deepgent/subagents/tools.py`
+* `coding-deepgent/src/coding_deepgent/subagents/schemas.py`
+* `.trellis/tasks/04-16-cc-highlight-alignment-discussion/h11-h12-alignment-research.md`
+
+## Out of Scope
+
+* Local custom agents
+* Plugin agents
+* Write-capable built-in agents
diff --git a/.trellis/tasks/archive/2026-04/04-18-l1b-h11-built-in-subagent-catalog-expansion/task.json b/.trellis/tasks/archive/2026-04/04-18-l1b-h11-built-in-subagent-catalog-expansion/task.json
new file mode 100644
index 000000000..9eda6d6b4
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-l1b-h11-built-in-subagent-catalog-expansion/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l1b-h11-built-in-subagent-catalog-expansion",
+  "name": "l1b-h11-built-in-subagent-catalog-expansion",
+  "title": "L1-b: H11 built-in subagent catalog expansion",
+  "description": "Add the next built-in read-only subagent roles beyond general/verifier.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-18",
+  "completedAt": "2026-04-19",
+  "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-18-subagent-batch1-parity-implementation-plan",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-18-l2a-h11-local-custom-subagent-definitions/prd.md b/.trellis/tasks/archive/2026-04/04-18-l2a-h11-local-custom-subagent-definitions/prd.md
new file mode 100644
index 000000000..66a636bf5
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-l2a-h11-local-custom-subagent-definitions/prd.md
@@ -0,0 +1,43 @@
+# L2-a: H11 local custom subagent definitions
+
+## Goal
+
+支持项目本地自定义 subagent definition，让用户可以在 repo 里声明自己的 agent 并被 `run_subagent` 加载使用。
+
+## Requirements
+
+* 选定一个稳定的 repo-local definition source，并在本任务内固定下来。
+* 支持在本地 definition 中声明：
+  * agent type / name
+  * description
+  * when-to-use
+  * prompt body or equivalent instruction content
+  * tool allowlist / disallow list
+  * `max_turns`
+  * `model_profile`
+* Built-in 和 local custom agent 的合并顺序必须稳定、可预测。
+* 无效 definition 必须显式报错，不静默忽略。
+* 本任务只做 local custom agents，不做 plugin-provided agents。
+
+## Acceptance Criteria
+
+* [ ] repo-local custom agent definitions 可被加载并进入 agent catalog。
+* [ ] 自定义 agent 能通过 `run_subagent` 真实执行。
+* [ ] definition validation 对非法工具、重名 agent、无效字段有覆盖测试。
+* [ ] built-in catalog 不会被 custom loading 意外破坏。
+
+## Dependencies
+
+* Depends on `04-18-l1b-h11-built-in-subagent-catalog-expansion`.
+
+## Context Sources
+
+* `coding-deepgent/src/coding_deepgent/subagents/tools.py`
+* `coding-deepgent/src/coding_deepgent/subagents/schemas.py`
+* `.trellis/spec/backend/task-workflow-contracts.md`
+
+## Out of Scope
+
+* Plugin source tiers
+* Remote agent definitions
+* Background agent lifecycle
diff --git a/.trellis/tasks/archive/2026-04/04-18-l2a-h11-local-custom-subagent-definitions/task.json b/.trellis/tasks/archive/2026-04/04-18-l2a-h11-local-custom-subagent-definitions/task.json
new file mode 100644
index 000000000..4aa6146ed
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-l2a-h11-local-custom-subagent-definitions/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l2a-h11-local-custom-subagent-definitions",
+  "name": "l2a-h11-local-custom-subagent-definitions",
+  "title": "L2-a: H11 local custom subagent definitions",
+  "description": "Load user-defined local subagent definitions from project config/files.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-18",
+  "completedAt": "2026-04-19",
+  "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-18-subagent-batch1-parity-implementation-plan",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-18-l2b-h12-fork-continuity-contract-closeout/prd.md b/.trellis/tasks/archive/2026-04/04-18-l2b-h12-fork-continuity-contract-closeout/prd.md
new file mode 100644
index 000000000..b10526748
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-l2b-h12-fork-continuity-contract-closeout/prd.md
@@ -0,0 +1,40 @@
+# L2-b: H12 fork continuity contract closeout
+
+## Goal
+
+把当前 fork 从“已有 lineage metadata 的 minimal slice”推进到更接近 Claude Code Chapter 9 的 continuity contract。
+
+## Requirements
+
+* 在保留独立 `run_fork` 入口的前提下，补强 fork continuity。
+* 当前 `placeholder_layout` 不能只记录 paired ids，需要推进到真实可消费的 continuity seam。
+* fork payload reconstruction 需要更接近完整 sibling continuity，而不是只追加 thin directive。
+* 保持：
+  * rendered system prompt continuity
+  * visible tool snapshot continuity
+  * recursion guard
+* 不在本任务内引入 provider-specific cache API 或 background fork orchestration。
+
+## Acceptance Criteria
+
+* [ ] fork continuity state 比当前 metadata-only 版本更完整，并有结构化测试覆盖。
+* [ ] 已完成 tool use / tool result 的 continuity 在 fork payload 中得到保留或重建。
+* [ ] sibling fork 仍保持稳定 prompt/tool identity contract。
+* [ ] recursion guard 与现有 sidechain audit 不回退。
+
+## Dependencies
+
+* Depends on `04-18-l1a-h11-subagent-max-turns-and-model-routing`.
+
+## Context Sources
+
+* `coding-deepgent/src/coding_deepgent/subagents/tools.py`
+* `coding-deepgent/src/coding_deepgent/subagents/schemas.py`
+* `.trellis/tasks/04-16-cc-highlight-alignment-discussion/h11-h12-alignment-research.md`
+* `.trellis/spec/backend/task-workflow-contracts.md`
+
+## Out of Scope
+
+* Provider-specific cache tuning
+* Background fork workers
+* Mailbox / coordinator
diff --git a/.trellis/tasks/archive/2026-04/04-18-l2b-h12-fork-continuity-contract-closeout/task.json b/.trellis/tasks/archive/2026-04/04-18-l2b-h12-fork-continuity-contract-closeout/task.json
new file mode 100644
index 000000000..9a6fccf1c
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-l2b-h12-fork-continuity-contract-closeout/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l2b-h12-fork-continuity-contract-closeout",
+  "name": "l2b-h12-fork-continuity-contract-closeout",
+  "title": "L2-b: H12 fork continuity contract closeout",
+  "description": "Deepen fork beyond minimal lineage metadata toward cache-safe continuity.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-18",
+  "completedAt": "2026-04-19",
+  "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-18-subagent-batch1-parity-implementation-plan",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-18-l2c-h11-h12-subagent-and-fork-resume-foundation/prd.md b/.trellis/tasks/archive/2026-04/04-18-l2c-h11-h12-subagent-and-fork-resume-foundation/prd.md
new file mode 100644
index 000000000..1c5bca39c
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-l2c-h11-h12-subagent-and-fork-resume-foundation/prd.md
@@ -0,0 +1,44 @@
+# L2-c: H11 H12 subagent and fork resume foundation
+
+## Goal
+
+为 built-in / local custom subagent 和 fork 增加最小可用的 resume foundation，让中断后的 child execution 可以恢复。
+
+## Requirements
+
+* Resume 必须基于已持久化的 lineage / metadata / transcript seam，而不是凭推断重建。
+* 普通 subagent resume 需要保留：
+  * agent identity
+  * tool surface
+  * turn/model settings
+* fork resume 需要保留：
+  * rendered prompt continuity
+  * visible tool continuity
+  * fork continuity state
+* 对缺失 / 损坏 / 过期 resume state，必须显式失败。
+* 优先支持 built-in 与 local custom agents；不要求 background lifecycle。
+
+## Acceptance Criteria
+
+* [ ] subagent resume 可以恢复同一 child identity 和核心执行约束。
+* [ ] fork resume 可以恢复同一 continuity contract，而不是退化成普通 subagent。
+* [ ] resume 对缺失 state / worktree drift / invalid metadata 有明确错误行为。
+* [ ] resume 不破坏现有 session / sidechain / evidence 边界。
+
+## Dependencies
+
+* Depends on `04-18-l2a-h11-local-custom-subagent-definitions`.
+* Depends on `04-18-l2b-h12-fork-continuity-contract-closeout`.
+
+## Context Sources
+
+* `coding-deepgent/src/coding_deepgent/subagents/tools.py`
+* `coding-deepgent/src/coding_deepgent/subagents/schemas.py`
+* `.trellis/spec/backend/task-workflow-contracts.md`
+* `.trellis/spec/backend/session-compact-contracts.md`
+
+## Out of Scope
+
+* Background agent resume
+* Multi-agent mailbox recovery
+* Coordinator workflow recovery
diff --git a/.trellis/tasks/archive/2026-04/04-18-l2c-h11-h12-subagent-and-fork-resume-foundation/task.json b/.trellis/tasks/archive/2026-04/04-18-l2c-h11-h12-subagent-and-fork-resume-foundation/task.json
new file mode 100644
index 000000000..e0c6e1d30
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-l2c-h11-h12-subagent-and-fork-resume-foundation/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l2c-h11-h12-subagent-and-fork-resume-foundation",
+  "name": "l2c-h11-h12-subagent-and-fork-resume-foundation",
+  "title": "L2-c: H11 H12 subagent and fork resume foundation",
+  "description": "Add resumable subagent/fork execution continuity on top of current transcript lineage.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-18",
+  "completedAt": "2026-04-19",
+  "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-18-subagent-batch1-parity-implementation-plan",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-18-memory-backend-agent-memory-closeout/check.jsonl b/.trellis/tasks/archive/2026-04/04-18-memory-backend-agent-memory-closeout/check.jsonl
new file mode 100644
index 000000000..cb4fce8b5
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-memory-backend-agent-memory-closeout/check.jsonl
@@ -0,0 +1,4 @@
+{"file": ".gemini/commands/trellis/finish-work.toml", "reason": "Finish work checklist"}
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".trellis/spec/backend/project-infrastructure-foundation-contracts.md", "reason": "Review long-term memory durability claims and keep session ledger separate."}
+{"file": ".trellis/spec/backend/database-guidelines.md", "reason": "Review schema ownership, migration surface, and rollback strategy."}
diff --git a/.trellis/tasks/archive/2026-04/04-18-memory-backend-agent-memory-closeout/debug.jsonl b/.trellis/tasks/archive/2026-04/04-18-memory-backend-agent-memory-closeout/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-memory-backend-agent-memory-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-18-memory-backend-agent-memory-closeout/implement.jsonl b/.trellis/tasks/archive/2026-04/04-18-memory-backend-agent-memory-closeout/implement.jsonl
new file mode 100644
index 000000000..4544bb97e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-memory-backend-agent-memory-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": ".trellis/spec/backend/database-guidelines.md", "reason": "This task introduces real database/migration infrastructure and needs explicit backend contracts."}
+{"file": ".trellis/spec/backend/directory-structure.md", "reason": "New backend infrastructure domains must land in coherent owning packages."}
+{"file": ".trellis/spec/backend/project-infrastructure-foundation-contracts.md", "reason": "Long-term memory durability changes owning surfaces and cross-session memory claims."}
diff --git a/.trellis/tasks/archive/2026-04/04-18-memory-backend-agent-memory-closeout/prd.md b/.trellis/tasks/archive/2026-04/04-18-memory-backend-agent-memory-closeout/prd.md
new file mode 100644
index 000000000..01fcfbf40
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-memory-backend-agent-memory-closeout/prd.md
@@ -0,0 +1,239 @@
+# Long-term memory backend and agent memory closeout
+
+## Goal
+
+完整实现长期记忆后端升级与 agent 私有记忆能力，使 `coding-deepgent`
+在不重做会话 ledger 的前提下，完成：
+
+* `9` 长期记忆 durable persistence
+* `10` 自动提取长期记忆 + agent 私有记忆 / snapshot 基础
+
+并显式使用：
+
+* PostgreSQL
+* Redis
+* MinIO
+
+来体现真正的后端系统能力。
+
+## Why Now
+
+当前长期记忆已经具备：
+
+* 四类型模型
+* save / list / delete
+* bounded recall
+* feedback enforcement
+
+但它仍然不是 durable backend，也没有自动提取、任务状态、agent 私有记忆、
+snapshot、归档等真正的后端能力。
+
+如果继续停留在当前形态：
+
+* 重启后长期记忆不可靠
+* 自动积累长期记忆无法成立
+* agent 私有记忆无法落地
+* “记忆后端”无法体现出真正的数据库 / 队列 / 对象存储设计能力
+
+## What I already know
+
+* 当前统一模型已明确：
+  1. 项目级规则文件
+  2. 长期记忆
+  3. 当前会话记忆
+  4. 恢复上下文
+* Layer 1 继续使用文件，不进入数据库
+* Layer 2 是本轮后端升级核心
+* Layer 3 / Layer 4 继续留在现有 session/transcript/compact/resume 体系
+* 当前长期记忆后端仍是运行时 store，不是 durable persistence
+* 当前还没有：
+  * PostgreSQL 主存储
+  * Redis queue/worker
+  * MinIO snapshot/archive
+  * extraction jobs
+  * agent-private memory
+
+## Requirements
+
+* 本轮完整实现 `9` 和 `10`，但不迁移现有 session JSONL ledger。
+* PostgreSQL 成为长期记忆主存储。
+* Redis 负责异步任务队列、去重、防抖、锁。
+* MinIO 负责快照和归档对象，不负责长期记忆主记录。
+* 长期记忆继续保持四类型：`user / feedback / project / reference`
+* 项目级规则文件继续保留为文件入口，不数据库化。
+* 当前会话记忆和恢复上下文不得错误迁入长期记忆主库。
+
+## Acceptance Targets
+
+* [ ] 长期记忆在进程重启后仍可读取、列出、删除和使用。
+* [ ] 长期记忆的主事实来源变为 PostgreSQL，而不是仅运行时内存。
+* [ ] 现有 `save_memory / list_memory / delete_memory` 保持产品语义，但底层切到 PostgreSQL。
+* [ ] 自动提取长期记忆不阻塞主流程，而是走 Redis 队列 + worker。
+* [ ] 自动提取任务至少有可见状态：
+  * `queued`
+  * `running`
+  * `completed`
+  * `failed`
+* [ ] 长期记忆具备最小版本/审计能力，至少能追踪：
+  * 来源
+  * 创建时间
+  * 最后更新时间
+  * 当前状态
+* [ ] agent 私有记忆的基础作用域成立，不再只有全局长期记忆。
+* [ ] snapshot / archive 的大对象不进入 PostgreSQL，而进入 MinIO。
+* [ ] 当前会话记忆和恢复上下文继续保持独立，不被错误数据库化。
+
+## Planned Features
+
+### 1. PostgreSQL Long-Term Memory Storage
+
+* 新增长期记忆主表
+* 新增长期记忆版本表
+* 新增提取任务状态表
+* 新增 agent 记忆作用域表
+* 增加 migration
+
+建议最小表族：
+
+* `memory_records`
+* `memory_versions`
+* `memory_extraction_jobs`
+* `agent_memory_scopes`
+
+### 2. Repository / Service Layer
+
+* 新增 `MemoryRepository`
+* 新增 `MemoryService`
+* 负责：
+  * save
+  * list
+  * delete/archive
+  * version append
+  * scope filtering
+  * idempotent write
+
+### 3. Keep Existing Product Surface
+
+* 保持现有工具入口：
+  * `save_memory`
+  * `list_memory`
+  * `delete_memory`
+* 底层从 runtime store 切到 PostgreSQL
+
+### 4. Redis Queue + Worker
+
+* 自动提取长期记忆走异步任务
+* worker 处理：
+  * extract long-term memory
+  * refresh agent memory snapshot
+  * archive snapshot object
+* 增加：
+  * dedupe key
+  * debounce
+  * distributed lock
+  * retry limit
+
+### 5. MinIO Snapshot / Archive
+
+* 存储：
+  * snapshot export bundle
+  * extraction raw artifacts
+  * agent snapshot archive
+* 不把普通长期记忆主记录写入 MinIO
+
+### 6. Agent-Private Memory Foundation
+
+* 为 agent 私有记忆增加 scope
+* 主 agent 与 child/agent scope 开始分层
+* 让后续 snapshot / sync 有真实基础
+
+## Planned Extensions
+
+* 路径级规则文件
+* 用户级规则文件
+* 更高级的 stale-memory trust check
+* 更强的记忆检索排序/语义检索
+* transcript/session ledger 数据库化
+* 更完整的 agent memory 产品面
+* 统一规则/记忆浏览 UI 或 CLI
+* 多租户/跨项目隔离增强
+
+## Definition of Done
+
+* PostgreSQL / Redis / MinIO 三层分工清晰
+* 长期记忆 durable persistence 成立
+* 自动提取任务链成立
+* agent 私有记忆基础成立
+* 不破坏当前 session ledger 恢复链
+* Focused pytest / ruff / mypy 通过
+* Trellis contracts/docs 同步完成
+
+## Technical Approach
+
+* Layer 1:
+  * `.coding-deepgent/RULES.md`
+  * 继续保留文件型入口
+* Layer 2:
+  * PostgreSQL 主存储
+  * 四类型长期记忆
+  * 版本/审计/任务状态
+* Layer 3:
+  * 当前会话记忆继续走 session state / compact chain
+* Layer 4:
+  * transcript / compact / resume 继续走 JSONL ledger
+* Redis:
+  * 队列 / 防抖 / 锁 / worker 分发
+* MinIO:
+  * snapshot / archive / 大对象归档
+
+## Out Of Scope
+
+* transcript JSONL ledger 迁移到 PostgreSQL
+* vector / embedding retrieval
+* RabbitMQ / Kafka / NATS
+* 全量多租户体系
+* 路径级规则 / 用户级规则
+
+## Technical Notes
+
+* `.trellis/tasks/04-18-unified-context-memory-closeout/prd.md`
+* `.trellis/spec/guides/planning-targets-guide.md`
+* `.trellis/spec/guides/architecture-posture-guide.md`
+* `.trellis/spec/backend/project-infrastructure-foundation-contracts.md`
+* `.trellis/spec/backend/session-compact-contracts.md`
+* `coding-deepgent/src/coding_deepgent/memory/*`
+* `coding-deepgent/src/coding_deepgent/sessions/*`
+* `coding-deepgent/src/coding_deepgent/rules/*`
+
+## Checkpoint
+
+State:
+- implementing
+
+Implemented so far:
+- Added SQLAlchemy-backed durable memory repository and schema creation.
+- Added Redis-backed queue abstraction with in-memory fallback for tests.
+- Added S3-compatible archive abstraction using boto3 for MinIO-compatible object storage.
+- Added durable memory service with:
+  - save/list/delete
+  - extraction jobs
+  - snapshot refresh jobs
+  - agent scope foundation
+- Added CLI surfaces:
+  - `memory migrate`
+  - `memory jobs`
+  - `memory worker-run-once`
+- Added focused backend tests for repository, queue/job flow, and CLI.
+
+Verification so far:
+- `pytest -q coding-deepgent/tests/test_memory_backend.py coding-deepgent/tests/test_memory_cli.py`
+- `pytest -q coding-deepgent/tests/test_memory.py coding-deepgent/tests/test_memory_integration.py coding-deepgent/tests/test_memory_backend.py coding-deepgent/tests/test_memory_cli.py coding-deepgent/tests/test_tool_system_middleware.py coding-deepgent/tests/test_agent_runtime_service.py coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_cli.py coding-deepgent/tests/test_runtime_foundation_contract.py`
+- `ruff check ...`
+- `mypy ...`
+- live smoke against configured services:
+  - `postgres=ok`
+  - `queue=ok`
+  - `archive=ok`
+
+Boundary finding:
+- Live service wiring required normalizing the PostgreSQL URL to the `psycopg` SQLAlchemy driver, correcting the configured database password, creating the target database, lowering Docker disk pressure for MinIO, and replacing the invalid uppercase bucket name with a valid S3-compatible bucket name.
diff --git a/.trellis/tasks/archive/2026-04/04-18-memory-backend-agent-memory-closeout/task.json b/.trellis/tasks/archive/2026-04/04-18-memory-backend-agent-memory-closeout/task.json
new file mode 100644
index 000000000..2408d3e22
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-memory-backend-agent-memory-closeout/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "memory-backend-agent-memory-closeout",
+  "name": "memory-backend-agent-memory-closeout",
+  "title": "Long-term memory backend and agent memory closeout",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-18",
+  "completedAt": "2026-04-18",
+  "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/archive/2026-04/04-18-memory-module-gap-review/prd.md b/.trellis/tasks/archive/2026-04/04-18-memory-module-gap-review/prd.md
new file mode 100644
index 000000000..fe9c070d2
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-memory-module-gap-review/prd.md
@@ -0,0 +1,496 @@
+# brainstorm: memory module gap review
+
+## Goal
+
+基于当前 `coding-deepgent` 的记忆实现和 cc/Claude Code 的记忆相关源码，明确“记忆模块”目前已经覆盖的功能、还缺的具体功能，以及下一轮应该优先补哪一类功能。
+
+## What I already know
+
+* 当前 `coding-deepgent` 已经完成一轮 integrated memory closeout：
+  * 四类型长期记忆 `user / feedback / project / reference`
+  * `save_memory / list_memory / delete_memory`
+  * bounded recall / render
+  * `feedback` 对少量高价值动作直接生效
+  * recovery/resume 可见面里已经分开显示 `Long-term memory` 和 `Current-session memory`
+* 当前 `coding-deepgent` 的长期记忆仍然是 store-backed 的运行时能力，不是持久落盘 backend。
+* 当前 `coding-deepgent` 仍没有自动提取长期记忆、子 agent 私有记忆、向量检索、后台维护。
+* cc 侧长期记忆主线来自：
+  * `src/memdir/*`
+  * `src/services/SessionMemory/*`
+  * `src/tools/AgentTool/agentMemory.ts`
+  * `src/tools/AgentTool/agentMemorySnapshot.ts`
+* cc 的长期记忆核心是：
+  * 闭合四类型
+  * 只保存不可推导信息
+  * frontmatter + MEMORY.md 索引
+  * 记忆老化/信任提醒
+  * user/project/local 以及 agent memory scope
+  * session memory 周期性提取与 agent memory snapshot
+
+## Assumptions (temporary)
+
+* 用户现在要的不是立即继续编码，而是先把“当前实现相对 cc 还差哪些功能”讲清楚。
+* 本轮主要输出 gap review 和下一步目标选择，不一定直接进入实现。
+* 评价标准以“用户能得到什么功能”为主，而不是是否逐字照搬 cc 源码。
+
+## Open Questions
+
+* 这套 planning 标准，是否直接升级成后续所有主线计划的默认准则？
+
+## Requirements (evolving)
+
+* 必须 source-backed，对照当前本地代码和 cc 相关源码/文档。
+* 输出要按“具体功能差距”分组，不要只给术语。
+* 需要明确：
+  * 已对齐功能
+  * 部分对齐功能
+  * 明确缺失功能
+* 必须把“上下文关联系统”和“记忆系统”合并讨论，而不是只看 memory 目录。
+* 最后要给出 2–3 个可选的下一轮目标包络，并推荐一个。
+
+## Acceptance Criteria (evolving)
+
+* [ ] 给出当前记忆模块相对 cc 的功能差距清单
+* [ ] 功能差距按具体用户收益分组，而不是抽象层次
+* [ ] 给出下一轮目标的 2–3 个选项
+* [ ] 给出推荐选项和理由
+
+## Definition of Done (team quality bar)
+
+* 结论写入 PRD
+* 差距描述可直接转为后续任务范围
+* 推荐方向清晰，不依赖口头记忆
+
+## Out of Scope (explicit)
+
+* 本轮不直接进入实现
+* 本轮不重新做已经完成的 memory closeout
+* 本轮不讨论 tutorial/reference 层 UI
+
+## Technical Notes
+
+* `.trellis/project-handoff.md`
+* `.trellis/plans/coding-deepgent-h01-h10-target-design.md`
+* `/tmp/claude-code-book/第二部分-核心系统篇/06-记忆系统-Agent的长期记忆.md`
+* `/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`
+* `coding-deepgent/src/coding_deepgent/memory/*`
+* `coding-deepgent/src/coding_deepgent/sessions/session_memory.py`
+* `coding-deepgent/src/coding_deepgent/sessions/long_term_memory.py`
+
+## Research Notes
+
+### Current local strengths
+
+* Long-term memory types are already aligned to `user / feedback / project / reference`.
+* Long-term memory has structured save/list/delete and bounded render.
+* Feedback memories can already affect a few concrete actions, not only prompt text.
+* Recovery/resume already shows long-term memory separately from current-session memory.
+
+### Combined context + memory view
+
+cc 实际上不是一个“单独的记忆模块”，而是一个组合系统：
+
+* persistent instructions:
+  * `CLAUDE.md`
+  * `.claude/rules/*`
+* long-term memory:
+  * `memdir`
+  * `MEMORY.md` + topic files
+* current-session memory:
+  * `SessionMemory`
+* recovery / continuation context:
+  * transcript
+  * compact
+  * resume brief
+* dynamic context protocol:
+  * attachments / queryContext / nested memory / relevant memories
+
+当前本地对应物是：
+
+* persistent instructions:
+  * runtime base prompt + custom/append prompt
+* long-term memory:
+  * `memory/`
+* current-session memory:
+  * `sessions/session_memory.py`
+* recovery / continuation context:
+  * `sessions/` + compact/resume chain
+* dynamic context protocol:
+  * PromptContext + middleware-injected memory/todo/runtime context
+
+Correction:
+
+* Trellis specs / workflow / handoff are agent-side development scaffolding, not
+  product-facing persistent instruction layers.
+* They should not be treated as the product equivalent of cc `CLAUDE.md` or
+  `.claude/rules/*`.
+
+### Current local gaps vs cc
+
+* No durable memory survives restart yet.
+* No file-based memory entries or human-readable memory index.
+* No explicit stale-memory trust/verification workflow at recall time.
+* No smarter relevance selection beyond bounded deterministic recall.
+* No automatic suggestion/extraction of durable memories from conversation.
+* No per-agent memory scope and no agent snapshot/sync path.
+* Current-session memory exists, but not the richer background extraction/update behavior cc has.
+
+### Source-backed fit assessment
+
+#### Already aligned enough
+
+* closed four-type long-term memory model
+* explicit “do not save derivable information” direction
+* structured save / list / delete operations
+* long-term memory vs current-session memory split
+* some feedback memories can affect behavior directly
+
+#### Partially aligned
+
+* long-term memory retrieval:
+  * local has bounded structured recall
+  * cc has file index + topic-file recall + stronger trust/verification guidance
+* session memory:
+  * local has current/stale session-memory artifact and compact/resume assist
+  * cc has richer thresholded/background extraction behavior
+* memory visibility:
+  * local shows long-term/current-session memory in recovery brief
+  * cc has `/memory` browse/edit flow and plain markdown files
+
+#### Clearly missing
+
+* long-term memory survives restart in a durable user-visible store
+* markdown memory files and a readable index entrypoint
+* stronger stale-memory trust/verification flow before acting on recalled facts
+* more selective / relevant memory retrieval when memory grows
+* auto-suggested or auto-extracted durable memories from conversation
+* per-agent memory scope and agent memory snapshots
+
+### Feasible next goals
+
+**Approach A: Durable And Auditable Memory**
+
+* User-visible result:
+  * remembered items survive restart
+  * users can inspect/edit memory outside the running process
+* Best when:
+  * persistence and auditability matter most
+
+**Approach B: Smarter Memory Use** (Recommended)
+
+* User-visible result:
+  * recalled memory is less likely to be stale, noisy, or over-applied
+  * system gets better at picking the right memory for the current task
+* Best when:
+  * reliability is the current biggest concern
+
+**Approach C: Automatic And Agent-Specific Memory**
+
+* User-visible result:
+  * system suggests or extracts memories by itself
+  * child agents keep their own remembered context
+* Best when:
+  * the product is ready to become more autonomous
+
+## Decision (ADR-lite)
+
+**Context**
+
+当前最大的混乱点不是“长期记忆有没有做”，而是：
+
+* 产品内长期规则
+* 长期记忆
+* 当前会话记忆
+* 恢复上下文
+
+这三层在认知上还没有被收成一个统一模型，导致后续目标很容易混淆成“继续做 memory”而不是“完善整套上下文/记忆工程”。
+
+**Decision**
+
+下一轮继续方向先采用“统一模型”路线：
+
+* 把 `产品内长期规则 + 长期记忆 + 当前会话记忆 + 恢复上下文` 作为一个整体系统来定义
+* 不再只从 `memory/` 目录出发讨论
+* 先把这四层的边界、顺序、职责、用户可见面收清，再决定下一轮实现目标
+* 用户选择把 “正式建 Layer 1” 和 “收紧 Layer 2/3/4” 一起规划，不拆成两轮
+* Layer 1 正式方向采用“文件型规则入口”。
+* Layer 1 第一版范围采用“单一项目级规则文件”，不同时引入路径级或用户级规则作用域。
+* Layer 1 内容边界先定为：
+  * 规则文件存“长期行为约束”
+  * 长期记忆存“长期可复用知识”
+* 四层进入模型的固定顺序采用：
+  1. 项目级规则文件
+  2. 长期记忆
+  3. 当前会话记忆
+  4. 恢复上下文
+* 层级可编辑性先定为：
+  * Layer 1 / Layer 2：允许用户直接编辑
+  * Layer 3 / Layer 4：系统维护为主
+
+**Consequences**
+
+* 优点：
+  * 可以直接解决“上下文”和“记忆”混淆的问题
+  * 后续任务能围绕统一边界拆验收目标
+* 代价：
+  * 范围比“只补 memory 功能”更大
+  * 需要明确哪些内容仍然留到未来，例如 agent 私有记忆
+
+## Unified Model Draft
+
+### Layer 1: Product-Level Long-Term Rules
+
+What it is:
+
+* 用户或项目长期明确写给系统的规则
+* 不应该被当作“系统自己总结出来的记忆”
+
+What kind of things belong here:
+
+* 长期工作方式
+* 项目级约束
+* 明确的人写规则
+
+### Layer 2: Long-Term Memory
+
+What it is:
+
+* 系统跨会话积累的长期可复用知识
+* 只保存不可推导的信息
+
+What kind of things belong here:
+
+* `user`
+* `feedback`
+* `project`
+* `reference`
+
+### Layer 3: Current-Session Memory
+
+What it is:
+
+* 当前这一次长会话的工作记忆/摘要
+* 服务于 compact / continuation / resume
+
+What kind of things belong here:
+
+* 当前会话摘要
+* 当前会话重点
+* 当前会话压缩辅助信息
+
+### Layer 4: Recovery Context
+
+What it is:
+
+* 从历史事实恢复“之前发生了什么”的上下文
+* 不是长期规则，也不是长期记忆
+
+What kind of things belong here:
+
+* transcript
+* compact
+* resume brief
+* continuation history
+
+### Core Boundary Rule
+
+* Layer 1 tells the system **how it should generally behave**
+* Layer 2 tells the system **what durable knowledge it has learned**
+* Layer 3 tells the system **what this current long conversation is about**
+* Layer 4 tells the system **what has actually happened so far**
+
+## Combined Planning Scope
+
+What the next planning round must define together:
+
+* Layer 1:
+  * product-level long-term rules entrypoint
+  * who can edit it
+  * how it becomes model-visible
+* Layer 2:
+  * what remains long-term memory instead of becoming a rule
+  * how long-term memory is recalled and trusted
+* Layer 3:
+  * what counts as current-session memory
+  * how it refreshes and how it is shown
+* Layer 4:
+  * what belongs to transcript/compact/resume only
+  * what must never be promoted into memory/rules automatically
+
+## Layer 1 Direction
+
+Chosen direction:
+
+* use a file-based rules entrypoint as the formal Layer 1 surface
+* first version uses one project-level rules file only
+
+Why:
+
+* easiest for users to understand
+* keeps long-term rules visibly distinct from long-term memory
+* gives the clearest audit surface before adding more structured execution logic
+* avoids reopening nested/path-scoped rule resolution too early
+
+### Content boundary
+
+Put into the rules file:
+
+* project-level long-term behavior constraints
+* long-term collaboration/process requirements
+* explicit engineering conventions the system should generally obey
+
+Do not put into the rules file:
+
+* user profile
+* learned durable facts
+* project decision background
+* external references
+* current-session summaries
+* historical transcript facts
+
+Short rule:
+
+* rules file = long-term behavior constraints
+* long-term memory = durable reusable knowledge
+
+## Runtime Assembly Order
+
+Fixed order:
+
+1. project-level rules file
+2. long-term memory
+3. current-session memory
+4. recovery context
+
+Why:
+
+* rules define how the system should generally behave
+* long-term memory provides durable learned knowledge
+* current-session memory provides the summary of this active long conversation
+* recovery context restores what has actually happened so far, but should not override the prior three layers by default
+
+## Editability Rule
+
+User-editable layers:
+
+* Layer 1: project-level rules file
+* Layer 2: long-term memory
+
+System-maintained layers:
+
+* Layer 3: current-session memory
+* Layer 4: recovery context
+
+Reason:
+
+* Layer 1 exists to capture explicit long-term rules from users/projects
+* Layer 2 must remain correctable/auditable by users
+* Layer 3 should stay a generated summary of the active long conversation
+* Layer 4 should stay a factual recovery layer rather than a hand-edited narrative
+
+## Planning Standard Draft
+
+Future planning for this area should not jump directly from discussion to implementation.
+Each follow-up task should be written in three explicit buckets before coding:
+
+### 1. Acceptance Targets
+
+What must be true for the task to count as complete.
+
+Examples:
+
+* what the user can now see
+* what the system can now do
+* what behavior is now prevented
+* what boundary is now explicit
+
+### 2. Planned Features
+
+The concrete features that this task will implement now.
+
+Examples:
+
+* one new rule file entrypoint
+* one recovery brief section
+* one memory trust check
+
+### 3. Planned Extensions
+
+Future features that are intentionally not implemented in this task, but are already identified so planning stays coherent.
+
+Examples:
+
+* user-level rules scope
+* durable memory persistence
+* agent-private memory
+
+### Rule
+
+No new feature family should go straight into implementation until these three buckets are explicit:
+
+* Acceptance Targets
+* Planned Features
+* Planned Extensions
+
+This is intended to become a reusable planning rule, not a one-off memory-task note.
+
+## Proposed Next Task
+
+### Goal
+
+把“产品内长期规则 + 长期记忆 + 当前会话记忆 + 恢复上下文”收成一个统一可执行模型，并把这四层正式落到产品边界里，而不是继续作为零散能力演化。
+
+### Acceptance Targets
+
+* 项目里有一个明确的、用户可直接编辑的项目级规则文件入口，且它不再和长期记忆混淆。
+* 系统能清楚区分四层：
+  * 项目级规则文件
+  * 长期记忆
+  * 当前会话记忆
+  * 恢复上下文
+* 进入模型的顺序被固定并经过测试：
+  1. 项目级规则文件
+  2. 长期记忆
+  3. 当前会话记忆
+  4. 恢复上下文
+* 用户能清楚看见哪些内容属于长期记忆、哪些属于当前会话记忆、哪些属于恢复上下文。
+* 当前会话记忆和恢复上下文不会再被误当成长期规则或长期记忆。
+* 本轮结果足够清晰，后续功能可以直接围绕这四层继续扩展，而不用重新定义边界。
+
+### Planned Features
+
+* 增加一个单一项目级规则文件入口。
+  * 建议路径：`.coding-deepgent/RULES.md`
+* 在 prompt/context 组装里正式接入项目级规则文件，并保证它先于长期记忆进入模型。
+* 把长期记忆、当前会话记忆、恢复上下文的显示与装配规则写成显式产品合同。
+* recovery/resume 继续保持长期记忆与当前会话记忆分开显示，并补清项目级规则文件的可见性/存在性信号。
+* 明确禁止自动把以下内容提升到错误层级：
+  * transcript 历史事实 -> 长期规则
+  * 当前会话摘要 -> 长期记忆
+  * 恢复上下文 -> 长期记忆
+* 增加 focused tests，覆盖：
+  * 规则文件存在/缺失时的装配行为
+  * 四层固定顺序
+  * recovery/resume 可见面分层
+  * 错层 promotion 不发生
+
+### Planned Extensions
+
+* 项目级规则文件之外的路径级规则
+* 用户级规则文件
+* 长期记忆的持久化落盘 backend
+* 更聪明的长期记忆筛选与过时判断
+* 自动建议或自动提取长期记忆
+* 子 agent / agent 私有记忆
+* 更统一的规则/记忆浏览与管理入口
+
+### Out Of Scope
+
+* 本轮不做路径级规则
+* 本轮不做用户级规则
+* 本轮不做长期记忆持久化 backend
+* 本轮不做自动提取长期记忆
+* 本轮不做 agent 私有记忆
diff --git a/.trellis/tasks/archive/2026-04/04-18-memory-module-gap-review/task.json b/.trellis/tasks/archive/2026-04/04-18-memory-module-gap-review/task.json
new file mode 100644
index 000000000..c956b3e13
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-memory-module-gap-review/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "memory-module-gap-review",
+  "name": "memory-module-gap-review",
+  "title": "brainstorm: memory module gap review",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-18",
+  "completedAt": "2026-04-18",
+  "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/archive/2026-04/04-18-memory-runtime-discussion/check.jsonl b/.trellis/tasks/archive/2026-04/04-18-memory-runtime-discussion/check.jsonl
new file mode 100644
index 000000000..dc4a8df34
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-memory-runtime-discussion/check.jsonl
@@ -0,0 +1,4 @@
+{"file": ".gemini/commands/trellis/finish-work.toml", "reason": "Finish work checklist"}
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".trellis/spec/backend/project-infrastructure-foundation-contracts.md", "reason": "Review memory module boundary after integrated closeout."}
+{"file": ".trellis/spec/backend/session-compact-contracts.md", "reason": "Review long-term vs current-session memory visibility and continuity behavior."}
diff --git a/.trellis/tasks/archive/2026-04/04-18-memory-runtime-discussion/debug.jsonl b/.trellis/tasks/archive/2026-04/04-18-memory-runtime-discussion/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-memory-runtime-discussion/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-18-memory-runtime-discussion/implement.jsonl b/.trellis/tasks/archive/2026-04/04-18-memory-runtime-discussion/implement.jsonl
new file mode 100644
index 000000000..8a0b880fa
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-memory-runtime-discussion/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/spec/backend/project-infrastructure-foundation-contracts.md", "reason": "Memory module boundary and owning surfaces for long-term memory, session memory, and recovery visibility."}
+{"file": ".trellis/spec/backend/session-compact-contracts.md", "reason": "Memory quality, session-memory continuity, and recovery/resume contracts touched by the integrated memory closeout."}
diff --git a/.trellis/tasks/archive/2026-04/04-18-memory-runtime-discussion/prd.md b/.trellis/tasks/archive/2026-04/04-18-memory-runtime-discussion/prd.md
new file mode 100644
index 000000000..ecba9340f
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-memory-runtime-discussion/prd.md
@@ -0,0 +1,207 @@
+# brainstorm: memory runtime discussion
+
+## Goal
+
+讨论 `coding-deepgent` 在当前 H07 基础之上，下一层 memory runtime 应该优先补哪一类能力，并先拍板边界，避免 memory / session / compact / subagent 再次混成一层。
+
+## What I already know
+
+* 当前 H07 已完成的主线已从旧 namespace 模型推进为四类型长期记忆：`user / feedback / project / reference`。
+* 当前长期记忆已具备：`save_memory`、`list_memory`、`delete_memory`、store-backed save/list/delete/recall、`MemoryContextMiddleware`、bounded recall、quality policy。
+* 当前 `feedback` 已不只是 prompt recall；它已经能通过 `ToolGuardMiddleware` 阻断三类高风险动作：commit 前未 lint、依赖变更未确认、generated 路径直改。
+* `project-handoff` 已明确：cross-session memory 是产品要求，但 richer `session-memory extraction` 与 `agent-memory snapshot runtime` 仍 deferred。
+* 当前仓库已经存在 `sessions/session_memory.py`，说明系统已经有一层 session-memory artifact 机制，且它会参与 recovery brief、compact assist、compact summary update。
+* 当前 `memory/policy.py` 已增强：过短、重复、transient task/session state、可推导项目信息、相对日期 project memory 都会被拒绝。
+* 现有设计文档明确要求 memory 不应退化成 knowledge dump，也不应和 todo/task/session state 混放。
+
+## Assumptions (temporary)
+
+* 这轮先讨论架构/产品边界，不直接进入实现。
+* 当前最值得讨论的不是“要不要 memory”，而是“下一层 richer memory 应该先增强哪种 runtime effect”。
+* 这轮要区分至少三层：long-term durable memory、session-memory artifact、subagent/agent-local snapshot。
+
+## Open Questions
+
+* “整个记忆模块一次性完成” 的包络，到底是：
+  * 只收 long-term memory，
+  * 还是把 session-memory / resume / recovery visibility 一起收掉，
+  * 还是连 durable backend / auto-extraction / subagent memory 也一起做？
+
+## Requirements (evolving)
+
+* 保持 memory / todo / task / session / compact 的边界清晰。
+* 讨论必须落到“expected effect + local target + out-of-scope”。
+* 新方案必须说明对 cross-session continuity 是直接、间接还是没有帮助。
+* 若涉及 richer runtime，必须先说明为什么值得增加复杂度。
+* 长期记忆核心类型收敛为闭合集：`user / feedback / project / reference`。
+* `local` 不再作为长期记忆核心模型的一部分；若保留，仅作为独立的 machine-local note 概念。
+
+## Acceptance Criteria (evolving)
+
+* [x] 明确下一轮 memory 讨论的主问题，不把三个子问题混在一起。
+* [x] 给出 2-3 个可选方向及其边界。
+* [x] 形成一个推荐方向，并说明为什么现在先讨论它。
+* [x] 长期记忆与当前会话记忆在 product surface 中明确分层。
+* [x] 长期记忆支持 save / list / delete / recall / feedback enforcement。
+* [x] recovery/resume 可见面能同时显示长期记忆与当前会话记忆。
+* [x] C 方案后续计划已写入文档，并以功能语言描述。
+
+## Definition of Done (team quality bar)
+
+* 形成清晰讨论结论并写入任务 PRD。
+* 边界、收益、风险、out-of-scope 明确。
+* 如果后续进入实现，按 Trellis task workflow 配置相关 spec context。
+
+## Out of Scope (explicit)
+
+* 本轮不直接修改 `coding-deepgent` 代码。
+* 本轮不重新打开 embeddings/vector recall。
+* 本轮不直接重开 H13/H14 多 agent 协调实现。
+
+## Technical Notes
+
+* `.trellis/project-handoff.md`
+* `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+* `.trellis/plans/coding-deepgent-h01-h10-target-design.md`
+* `coding-deepgent/src/coding_deepgent/memory/*`
+* `coding-deepgent/src/coding_deepgent/sessions/session_memory.py`
+* `coding-deepgent/src/coding_deepgent/tool_system/middleware.py`
+* `coding-deepgent/tests/test_memory.py`
+* `coding-deepgent/tests/test_memory_integration.py`
+* `coding-deepgent/tests/test_tool_system_middleware.py`
+
+## Decisions
+
+* 2026-04-18: 采用方案 A。`local` 不进入长期记忆核心类型系统；长期记忆对齐目标收敛为 `user / feedback / project / reference` 四类型。
+* 2026-04-18: `feedback` 作为最优先亮点先收敛。最小结构为 `rule / why / how_to_apply / source`，用于保存用户纠正或确认过的行为规则；render/recall 优先级高于普通 `project` memory。
+* 2026-04-18: 后续 memory 亮点按收益最大优先排序，不要求与旧方案或旧数据兼容；当长期边界更干净时，优先选择更适合未来演进的结构而不是兼容桥接。
+* 2026-04-18: `project` 作为第二优先亮点。最小结构为 `fact_or_decision / why / how_to_apply / effective_date / source`，只保存非代码可推导的项目事实、决策背景和长期约束；涉及时间时必须使用绝对日期。
+* 2026-04-18: `reference` 作为第三优先亮点。最小结构为 `label / pointer / purpose / how_to_apply / source`，专门承载 repo 之外但长期有用的外部系统入口；不与 `project` 决策或 repo 内部路径混用。
+* 2026-04-18: 采用 Approach B。把“整个记忆模块”定义为两层并一次性收口：
+  * long-term memory
+  * session-memory artifact
+* 2026-04-18: C 方案不进入本轮实现，但必须把后续计划写进文档，而且用功能语言描述用户最终会获得什么，不写成架构术语清单。
+
+## Research Notes
+
+### Current local state
+
+* Long-term memory:
+  * four-type contract exists
+  * save/list/delete tools exist
+  * recall/render exists
+  * feedback enforcement exists for three high-value actions
+* Session-memory:
+  * separate `session_memory` artifact exists
+  * already participates in recovery brief, compact assist, compact-summary refresh
+* Not done:
+  * long-term memory visibility in recovery/resume surface
+  * unified “memory module” contract that explains long-term vs session-memory together
+  * durable backend for long-term memory
+  * auto extraction
+  * subagent/agent-memory snapshot
+
+### Feasible approaches here
+
+**Approach A: Long-Term Memory Closeout**
+
+* How it works:
+  * finish only long-term memory module
+  * include four-type schema, management tools, feedback enforcement, recall/render cleanup
+* Pros:
+  * smallest delivery
+  * low risk
+* Cons:
+  * “entire memory module” remains incomplete because session-memory is still a separate unfinished seam
+
+**Approach B: Integrated Memory Closeout** (Recommended)
+
+* How it works:
+  * treat memory module as two explicit layers:
+    * long-term memory
+    * session-memory artifact
+  * finish both together at the product boundary
+  * include visibility in recovery/resume so the user can inspect remembered state
+  * keep durable backend, auto extraction, and subagent memory out of scope
+* Pros:
+  * matches current product reality
+  * gives one coherent memory boundary
+  * high user-visible payoff without reopening too much infra
+* Cons:
+  * bigger than long-term-only closeout
+
+**Approach C: Full Future Memory Platform**
+
+* How it works:
+  * do integrated memory plus durable backend, auto extraction, and subagent/agent memory
+* Pros:
+  * most complete long-term vision
+* Cons:
+  * too broad for one safe pass now
+  * high risk of mixing multiple unfinished domains
+
+## Chosen Scope
+
+### In Scope For One-Shot Completion
+
+* Long-term memory:
+  * four-type memory model
+  * save / list / delete
+  * recall / render
+  * feedback-driven behavior rules
+* Session-memory:
+  * explicit boundary vs long-term memory
+  * recovery/resume visibility
+  * stale/current status visibility
+  * compact/resume continuity kept coherent with long-term memory
+* Product visibility:
+  * user can see what the system remembers
+  * user can distinguish long-term memory from current-session memory
+* Documentation:
+  * current memory module boundary becomes explicit in Trellis docs
+  * future C-scope memory work is written down as a function-first roadmap
+
+### Out Of Scope For This Pass
+
+* durable long-term memory backend
+* auto extraction from conversation into memory
+* subagent/agent-private memory
+* vector/embedding retrieval
+* background memory maintenance
+
+## Technical Approach
+
+* Long-term memory:
+  * four-type structured memory model
+  * bounded store-backed save/list/delete/recall
+  * feedback rules may directly block a few high-value actions through existing tool guard surfaces
+* Current-session memory:
+  * remains a separate session artifact
+  * stays visible in recovery/resume as “Current-session memory”
+* Integration:
+  * long-term memory snapshot is written into runtime state and carried into recorded session snapshots
+  * recovery brief renders long-term memory and current-session memory as two separate sections
+* Documentation:
+  * current memory module boundary updated in Trellis specs
+  * future C-scope memory path recorded as a function-first roadmap
+
+## Checkpoint
+
+State:
+- terminal
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Four-type long-term memory (`user / feedback / project / reference`) is the active product contract.
+- Memory management tools now support save, list, and delete.
+- `feedback` memory can directly block selected high-value actions.
+- Recovery/resume now shows a separate `Long-term memory:` section and a separate `Current-session memory:` section.
+- Session snapshots preserve the long-term memory visibility snapshot alongside current-session memory.
+- Future larger memory work was documented in function-first language.
+
+Verification:
+- Focused memory/session/CLI/runtime tests passed.
+- `ruff check` passed on touched memory/session/runtime files and tests.
+- `mypy` passed on touched memory/session/runtime files and tests.
diff --git a/.trellis/tasks/archive/2026-04/04-18-memory-runtime-discussion/task.json b/.trellis/tasks/archive/2026-04/04-18-memory-runtime-discussion/task.json
new file mode 100644
index 000000000..40f2bc8e2
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-memory-runtime-discussion/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "memory-runtime-discussion",
+  "name": "memory-runtime-discussion",
+  "title": "brainstorm: memory runtime discussion",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-18",
+  "completedAt": "2026-04-18",
+  "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/archive/2026-04/04-18-subagent-batch1-parity-implementation-plan/prd.md b/.trellis/tasks/archive/2026-04/04-18-subagent-batch1-parity-implementation-plan/prd.md
new file mode 100644
index 000000000..47ad2a703
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-subagent-batch1-parity-implementation-plan/prd.md
@@ -0,0 +1,75 @@
+# subagent batch1 parity implementation plan
+
+## Goal
+
+把“第一批最值得先做的子 agent / fork 能力”拆成可执行 Trellis 任务，并明确实现顺序、依赖关系、和本批次边界。
+
+## Requirements
+
+* 本批次只覆盖第一批功能点：
+  * `max_turns` 真正生效
+  * per-agent model routing
+  * 更多 built-in subagent
+  * local custom subagent definitions
+  * 更完整的 fork continuity
+  * subagent / fork resume foundation
+* 先补已经声明过但未兑现的 contract，再扩展新 surface。
+* 保持当前 H11/H12 主线边界，不在本批次内重开：
+  * mailbox / SendMessage
+  * coordinator runtime
+  * background multi-agent orchestration
+  * plugin-provided agents
+  * write-capable coder agents
+* 复用现有 `subagents`, `runtime`, `sessions`, `tasks` seam，不增加桥接层。
+
+## Acceptance Criteria
+
+* [x] 父任务存在并挂到 `04-18-compare-subagent-vs-cc-gap/` 下。
+* [x] 第一批实现被拆成 5 个有 PRD 的子任务。
+* [x] 每个子任务都写明目标、范围、验收标准、依赖。
+* [x] 执行顺序明确，且第一执行入口清晰。
+
+## Task Breakdown
+
+### L1-a: H11 subagent max_turns and model routing
+
+先补 contract debt，让已声明能力真正生效。
+
+### L1-b: H11 built-in subagent catalog expansion
+
+在稳定的 turn/model contract 上扩 built-in catalog。
+
+### L2-a: H11 local custom subagent definitions
+
+在 built-in catalog 之上开放 repo-local custom agents。
+
+### L2-b: H12 fork continuity contract closeout
+
+把当前 fork 从 minimal lineage metadata 推进到更完整的 continuity contract。
+
+### L2-c: H11/H12 subagent and fork resume foundation
+
+在 custom agent + fork continuity 基础上补 resume。
+
+## Execution Order
+
+1. `L1-a` first
+2. `L1-b` after `L1-a`
+3. `L2-a` after `L1-b`
+4. `L2-b` after `L1-a`
+5. `L2-c` after `L2-a` and `L2-b`
+
+## Out of Scope
+
+* Plugin-provided agents
+* Background/async child lifecycle
+* Progress UI / notifications
+* Mailbox / coordinator / team runtime
+
+## Context Sources
+
+* `.trellis/tasks/04-18-compare-subagent-vs-cc-gap/prd.md`
+* `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+* `coding-deepgent/src/coding_deepgent/subagents/tools.py`
+* `coding-deepgent/src/coding_deepgent/subagents/schemas.py`
+* `.trellis/spec/backend/task-workflow-contracts.md`
diff --git a/.trellis/tasks/archive/2026-04/04-18-subagent-batch1-parity-implementation-plan/task.json b/.trellis/tasks/archive/2026-04/04-18-subagent-batch1-parity-implementation-plan/task.json
new file mode 100644
index 000000000..d1547a940
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-subagent-batch1-parity-implementation-plan/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "subagent-batch1-parity-implementation-plan",
+  "name": "subagent-batch1-parity-implementation-plan",
+  "title": "subagent batch1 parity implementation plan",
+  "description": "Plan and sequence the first implementation batch for subagent/fork parity improvements.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-18",
+  "completedAt": "2026-04-19",
+  "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-18-compare-subagent-vs-cc-gap",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-18-unified-context-memory-closeout/check.jsonl b/.trellis/tasks/archive/2026-04/04-18-unified-context-memory-closeout/check.jsonl
new file mode 100644
index 000000000..dc510e2ce
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-unified-context-memory-closeout/check.jsonl
@@ -0,0 +1,4 @@
+{"file": ".gemini/commands/trellis/finish-work.toml", "reason": "Finish work checklist"}
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".trellis/spec/backend/project-infrastructure-foundation-contracts.md", "reason": "Review the four-layer model against owning surfaces and promotion boundaries."}
+{"file": ".trellis/spec/backend/session-compact-contracts.md", "reason": "Review resume/recovery layering and non-duplication after changes."}
diff --git a/.trellis/tasks/archive/2026-04/04-18-unified-context-memory-closeout/debug.jsonl b/.trellis/tasks/archive/2026-04/04-18-unified-context-memory-closeout/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-unified-context-memory-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-18-unified-context-memory-closeout/implement.jsonl b/.trellis/tasks/archive/2026-04/04-18-unified-context-memory-closeout/implement.jsonl
new file mode 100644
index 000000000..9f61e1ff0
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-unified-context-memory-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": ".trellis/spec/backend/session-compact-contracts.md", "reason": "Recovery/resume and current-session memory contracts change with the unified model closeout."}
+{"file": ".trellis/spec/backend/project-infrastructure-foundation-contracts.md", "reason": "Unified four-layer context and memory model changes product-level boundaries and must stay source-of-truth here."}
+{"file": ".trellis/spec/backend/directory-structure.md", "reason": "New product-level rules layer must land in a coherent owning package."}
diff --git a/.trellis/tasks/archive/2026-04/04-18-unified-context-memory-closeout/prd.md b/.trellis/tasks/archive/2026-04/04-18-unified-context-memory-closeout/prd.md
new file mode 100644
index 000000000..411c84725
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-unified-context-memory-closeout/prd.md
@@ -0,0 +1,161 @@
+# Unified context and memory model closeout
+
+## Goal
+
+把 `coding-deepgent` 的“产品内长期规则 + 长期记忆 + 当前会话记忆 + 恢复上下文”收成一个统一、可执行、可验证的产品模型，并以一次集成实现的方式落到当前 mainline，而不是继续让这四层作为零散能力分别演化。
+
+## Why Now
+
+当前本地已经分别具备：
+
+* 长期记忆
+* 当前会话记忆
+* compact / resume / recovery
+* prompt/context 装配
+
+但它们之间的边界仍然主要存在于讨论和局部实现中，尚未形成一个对用户、实现者、后续任务都清晰的统一模型。
+
+如果现在不收口：
+
+* 记忆和上下文恢复会继续混淆
+* 新功能会继续以“补一点 memory”或“补一点 context”方式零散演进
+* 后续规划会持续缺少清晰验收目标
+
+## What I already know
+
+* 当前长期记忆已经是四类型结构：`user / feedback / project / reference`
+* 当前长期记忆已经具备 `save_memory / list_memory / delete_memory`
+* 当前长期记忆已经有 bounded recall / render，并且部分 `feedback` 能直接影响行为
+* 当前已经有 `Current-session memory`
+* 当前 recovery/resume 已经能分开显示长期记忆和当前会话记忆
+* 当前还没有正式的产品内长期规则文件层
+* 当前长期记忆仍不是 durable persistent backend
+* cc 侧是“长期说明 + 长期记忆 + session memory + transcript/compact/resume + dynamic context protocol”的组合系统，而不是单独一个 memory 子模块
+
+## Requirements
+
+* 本轮必须把四层统一模型明确落到当前 mainline：
+  1. 项目级规则文件
+  2. 长期记忆
+  3. 当前会话记忆
+  4. 恢复上下文
+* Layer 1 采用文件型规则入口
+* Layer 1 第一版只做单一项目级规则文件，不做路径级或用户级规则作用域
+* Layer 1 存长期行为约束，不存系统自己学到的知识
+* Layer 2 存长期可复用知识，不冒充长期规则
+* Layer 3 继续作为当前这次长会话的工作记忆
+* Layer 4 继续作为历史事实恢复层
+* 四层进入模型的顺序固定为：
+  1. 项目级规则文件
+  2. 长期记忆
+  3. 当前会话记忆
+  4. 恢复上下文
+* Layer 1 / Layer 2 允许用户直接编辑
+* Layer 3 / Layer 4 以系统维护为主
+
+## Acceptance Targets
+
+* [x] 项目里存在一个明确的、用户可直接编辑的项目级规则文件入口，且它不再和长期记忆混淆。
+* [x] 运行时装配明确遵守四层固定顺序：
+  1. 项目级规则文件
+  2. 长期记忆
+  3. 当前会话记忆
+  4. 恢复上下文
+* [x] recovery / resume / context 装配里，用户能清楚看见长期记忆与当前会话记忆的区别。
+* [x] 项目级规则文件、长期记忆、当前会话记忆、恢复上下文之间的职责边界被显式写进产品合同和测试。
+* [x] 当前会话摘要不会被错误提升为长期记忆或长期规则。
+* [x] 恢复上下文不会被错误提升为长期记忆或长期规则。
+* [x] 后续 feature-family planning 可以围绕这四层拆任务，而不需要重新解释系统边界。
+
+## Planned Features
+
+* 增加单一项目级规则文件入口。
+  * 推荐路径：`.coding-deepgent/RULES.md`
+* 在 runtime prompt/context 组装里正式接入项目级规则文件。
+* 固化四层装配顺序，并增加 focused tests 验证该顺序不漂移。
+* 把 Layer 1 / Layer 2 / Layer 3 / Layer 4 的职责和禁止越层规则写入 Trellis backend contracts。
+* 明确错误提升的禁止规则：
+  * transcript 历史事实不能直接成为长期规则
+  * transcript 历史事实不能直接成为长期记忆
+  * 当前会话记忆不能直接成为长期规则
+  * 当前会话记忆不能直接成为长期记忆
+* 在 recovery / resume 可见面中保留：
+  * 项目级规则文件存在性/入口信号
+  * 长期记忆
+  * 当前会话记忆
+* 补 focused tests 覆盖：
+  * 规则文件存在/缺失时的装配行为
+  * 四层固定顺序
+  * recovery / resume 的分层可见面
+  * 错误层级提升不发生
+
+## Planned Extensions
+
+* 路径级规则文件
+* 用户级规则文件
+* 长期记忆 durable persistence backend
+* 更聪明的长期记忆筛选与过时判断
+* 自动建议或自动提取长期记忆
+* agent-private / child-agent memory
+* 统一规则/记忆浏览入口
+
+## Definition of Done
+
+* 代码、合同、测试三者一致
+* 四层模型对用户、实现者、后续任务都清晰
+* Focused pytest / ruff / mypy 通过
+* Trellis 文档已同步到足以支撑后续 planning
+
+## Technical Approach
+
+* Layer 1 通过文件入口进入当前 prompt/context 组装链
+* Layer 2 继续使用结构化长期记忆层
+* Layer 3 继续保持 current-session memory 的独立职责
+* Layer 4 继续保持 transcript / compact / resume 的事实恢复职责
+* 不增加为兼容旧局部设计而存在的桥接层
+* 直接采用更清晰的长期分层边界
+
+## Out Of Scope
+
+* 本轮不做路径级规则
+* 本轮不做用户级规则
+* 本轮不做长期记忆持久化 backend
+* 本轮不做自动提取长期记忆
+* 本轮不做 agent 私有记忆
+
+## Technical Notes
+
+* `.trellis/tasks/04-18-memory-module-gap-review/prd.md`
+* `.trellis/project-handoff.md`
+* `.trellis/spec/guides/planning-targets-guide.md`
+* `.trellis/spec/guides/architecture-posture-guide.md`
+* `.trellis/spec/backend/project-infrastructure-foundation-contracts.md`
+* `.trellis/spec/backend/session-compact-contracts.md`
+* `/root/claude-code-haha/src/memdir/*`
+* `/root/claude-code-haha/src/services/SessionMemory/*`
+* `/root/claude-code-haha/src/utils/queryContext.ts`
+* `/root/claude-code-haha/src/utils/attachments.ts`
+* `coding-deepgent/src/coding_deepgent/memory/*`
+* `coding-deepgent/src/coding_deepgent/sessions/*`
+* `coding-deepgent/src/coding_deepgent/prompting/*`
+
+## Checkpoint
+
+State:
+- terminal
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added a project-level rules file layer at `.coding-deepgent/RULES.md`.
+- Integrated project rules into prompt assembly ahead of long-term memory.
+- Added a dedicated current-session memory middleware so Layer 3 is model-visible outside of recovery text.
+- Split user-facing recovery brief from model-facing resume context so resume no longer duplicates earlier layers.
+- Added recovery visibility for project rules while keeping long-term memory and current-session memory visibly separate.
+- Updated Trellis docs/contracts so later work can plan against the fixed four-layer model.
+
+Verification:
+- `pytest -q coding-deepgent/tests/test_prompting.py coding-deepgent/tests/test_rules.py coding-deepgent/tests/test_session_memory_middleware.py coding-deepgent/tests/test_app.py coding-deepgent/tests/test_memory_integration.py coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_cli.py`
+- `ruff check coding-deepgent/src/coding_deepgent/rules coding-deepgent/src/coding_deepgent/prompting/builder.py coding-deepgent/src/coding_deepgent/sessions/project_rules.py coding-deepgent/src/coding_deepgent/sessions/session_memory_middleware.py coding-deepgent/src/coding_deepgent/sessions/contribution_registry.py coding-deepgent/src/coding_deepgent/sessions/resume.py coding-deepgent/src/coding_deepgent/containers/app.py coding-deepgent/tests/test_prompting.py coding-deepgent/tests/test_rules.py coding-deepgent/tests/test_session_memory_middleware.py coding-deepgent/tests/test_app.py coding-deepgent/tests/test_memory_integration.py coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_cli.py`
+- `mypy coding-deepgent/src/coding_deepgent/rules coding-deepgent/src/coding_deepgent/prompting/builder.py coding-deepgent/src/coding_deepgent/sessions/project_rules.py coding-deepgent/src/coding_deepgent/sessions/session_memory_middleware.py coding-deepgent/src/coding_deepgent/sessions/contribution_registry.py coding-deepgent/src/coding_deepgent/sessions/resume.py coding-deepgent/src/coding_deepgent/containers/app.py coding-deepgent/tests/test_prompting.py coding-deepgent/tests/test_rules.py coding-deepgent/tests/test_session_memory_middleware.py coding-deepgent/tests/test_app.py coding-deepgent/tests/test_memory_integration.py coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_cli.py`
diff --git a/.trellis/tasks/archive/2026-04/04-18-unified-context-memory-closeout/task.json b/.trellis/tasks/archive/2026-04/04-18-unified-context-memory-closeout/task.json
new file mode 100644
index 000000000..675ff2954
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-18-unified-context-memory-closeout/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "unified-context-memory-closeout",
+  "name": "unified-context-memory-closeout",
+  "title": "Unified context and memory model closeout",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-18",
+  "completedAt": "2026-04-18",
+  "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/archive/2026-04/04-19-agent-harness-optimization-roadmap/check.jsonl b/.trellis/tasks/archive/2026-04/04-19-agent-harness-optimization-roadmap/check.jsonl
new file mode 100644
index 000000000..87bb92418
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-agent-harness-optimization-roadmap/check.jsonl
@@ -0,0 +1,7 @@
+{"file": ".gemini/commands/trellis/finish-work.toml", "reason": "Finish work checklist"}
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
+{"file": ".trellis/spec/frontend/quality-guidelines.md", "reason": "review frontend protocol validation after test moves"}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "review test cleanup against product verification rules"}
+{"file": ".trellis/spec/guides/mainline-scope-guide.md", "reason": "review moved tests stay in product mainline"}
+{"file": ".trellis/spec/backend/langchain-native-guidelines.md", "reason": "review runtime/tool/subagent coverage still protects official seams"}
diff --git a/.trellis/tasks/archive/2026-04/04-19-agent-harness-optimization-roadmap/debug.jsonl b/.trellis/tasks/archive/2026-04/04-19-agent-harness-optimization-roadmap/debug.jsonl
new file mode 100644
index 000000000..c1b287771
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-agent-harness-optimization-roadmap/debug.jsonl
@@ -0,0 +1,2 @@
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-19-agent-harness-optimization-roadmap/implement.jsonl b/.trellis/tasks/archive/2026-04/04-19-agent-harness-optimization-roadmap/implement.jsonl
new file mode 100644
index 000000000..4dfaeac84
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-agent-harness-optimization-roadmap/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": ".trellis/spec/frontend/index.md", "reason": "Frontend development guide"}
+{"file": ".trellis/spec/backend/langchain-native-guidelines.md", "reason": "runtime/tool/subagent tests protect LangChain-native seams"}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "test cleanup must preserve product boundary coverage"}
+{"file": ".trellis/spec/frontend/quality-guidelines.md", "reason": "frontend protocol and CLI tests must stay synchronized"}
+{"file": ".trellis/spec/guides/mainline-scope-guide.md", "reason": "keep cleanup scoped to coding-deepgent product tests"}
+{"file": ".trellis/spec/guides/architecture-posture-guide.md", "reason": "prefer clean long-term test layout over compatibility clutter"}
diff --git a/.trellis/tasks/archive/2026-04/04-19-agent-harness-optimization-roadmap/prd.md b/.trellis/tasks/archive/2026-04/04-19-agent-harness-optimization-roadmap/prd.md
new file mode 100644
index 000000000..c9feed820
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-agent-harness-optimization-roadmap/prd.md
@@ -0,0 +1,871 @@
+# brainstorm: agent harness optimization roadmap
+
+## Goal
+
+Define the final target and staged roadmap for optimizing the `coding-deepgent`
+agent harness after reviewing DeerFlow 2.0 patterns. The plan should improve
+architecture, LangChain-native usage, subagent/runtime contracts, and future UI
+readiness while avoiding implementation drift before the target is approved.
+
+## What I already know
+
+* The user is doing frontend work in parallel in another thread/workstream.
+* This task should avoid frontend implementation changes by default and should
+  define backend/runtime contracts that the frontend can consume later.
+* Trellis planning principles require final goals before development.
+* The current product mainline is `coding-deepgent/`; tutorial/reference layers
+  are evidence only unless explicitly targeted.
+* `coding-deepgent` already uses LangChain `create_agent` through
+  `RuntimeAgentBuildRequest` and `create_runtime_agent`.
+* Current subagents and fork agents are already created through the same runtime
+  factory path, not a separate hand-rolled loop.
+* DeerFlow 2.0 is useful as a reference for a productized agent harness, but not
+  a wholesale target architecture.
+* `.trellis/project-handoff.md` says the current next recommended task is final
+  release validation / PR cleanup for the completed backend-next-step roadmap,
+  not opening another backend feature family by default.
+* `04-19-runtime-architecture-refactor-plan` is already terminal/approved:
+  runtime roles/factory, subagent domain split, background hardening, and H13/H14
+  readiness gate are complete.
+* `04-19-frontend-architecture-cc-cli-reuse` is already terminal/approved:
+  React/Ink CLI frontend v1, Python JSONL bridge, frontend protocol models,
+  event mapping, tests, and docs are complete.
+* `04-19-post-cli-frontend-v1-roadmap` already proposes a CLI Completion Pack
+  before Web/HTML: real streaming, permission/HITL boundary, product command,
+  and CLI polish.
+* `coding_deepgent.frontend.protocol` already defines strict
+  `FrontendEvent`/`FrontendInput` models for session, assistant deltas,
+  tool events, permission events, todos/tasks, runtime events, recovery brief,
+  and run terminal states.
+
+## Assumptions (temporary)
+
+* The optimization plan should primarily target final-goal alignment,
+  acceptance gates, and sequencing across existing backend/frontend plans.
+* Frontend-facing implementation should continue in the existing frontend
+  workstream unless explicitly coordinated.
+* The plan should be large enough to set a final target, but sliced into staged
+  implementation tasks after approval.
+* New backend optimization work should be justified by a concrete gap discovered
+  during final validation, not by general similarity to DeerFlow.
+
+## Open Questions
+
+* Confirm final full test cleanup plan before moving into Task Workflow.
+
+## Acceptance Targets
+
+* A final target architecture is written before implementation begins.
+* The roadmap distinguishes acceptance targets, planned features, planned
+  extensions, and out-of-scope items.
+* The roadmap explicitly avoids conflicting with parallel frontend work.
+* DeerFlow learnings are mapped to `coding-deepgent` constraints instead of
+  copied directly.
+
+## Planned Features
+
+* Compare current `coding-deepgent` agent harness boundaries with DeerFlow 2.0
+  patterns.
+* Identify high-value optimization areas in runtime, middleware order, tool
+  projection, deferred tools, subagent/fork contracts, store/checkpointer usage,
+  and event/protocol surfaces.
+* Propose staged implementation slices with validation expectations.
+* Record key architecture decisions as ADR-lite notes in this PRD.
+
+## Planned Extensions
+
+* Frontend implementation once the parallel frontend workstream converges.
+* Web/Ink UI event rendering improvements beyond protocol contracts.
+* Deep model-provider compatibility expansion unless selected as an MVP target.
+* Wholesale DeerFlow parity.
+
+## Requirements (evolving)
+
+* Keep the plan scoped to `coding-deepgent/` and `.trellis/` by default.
+* Do not implement code changes during brainstorm.
+* Treat DeerFlow as a reference for proven patterns, not as the architecture to
+  copy wholesale.
+* Preserve the current LangChain-native direction: official tools, middleware,
+  typed state/context, store/checkpointer, and `create_agent`.
+* Avoid frontend file edits unless the user explicitly moves this task into that
+  workstream.
+* Do not reopen completed runtime reshape stages unless final validation finds a
+  concrete regression or contract gap.
+* Coordinate with the existing CLI frontend plan instead of creating a competing
+  frontend roadmap.
+* Any next implementation family must state the concrete function being changed,
+  the user/system benefit, and why the complexity is worth adding now.
+* The selected roadmap posture is validation-first release stabilization.
+* Do not start CLI Completion Pack implementation or H13/H14 planning from this
+  task unless the validation pass identifies them as the next approved lane.
+* Phase 1 validation scope is Core Release Gate.
+* Core Release Gate should validate current completed mainline readiness, not
+  long-range architecture wishes.
+* User now prefers to organize the test suite before running Core Release Gate.
+* Core Release Gate should run after test scope/layers are clear so failures are
+  easier to interpret.
+* User selected full test cleanup before Core Release Gate.
+* User selected domain subdirectories for the test layout.
+
+## Acceptance Criteria
+
+* [x] PRD includes `Acceptance Targets`, `Planned Features`, and
+      `Planned Extensions`.
+* [x] PRD includes a recommended roadmap with staged implementation slices.
+* [x] PRD captures at least one ADR-lite decision about roadmap posture.
+* [x] PRD lists likely impacted backend/runtime/Trellis files.
+* [x] User confirms final target before implementation begins.
+* [x] Tests are moved into domain subdirectories.
+* [x] Test command references are updated for the new layout.
+* [x] Cleaned test suite passes before Core Release Gate.
+
+## Definition of Done (team quality bar)
+
+* Tests added/updated for implemented slices when implementation begins.
+* Lint / typecheck / CI green for implemented slices.
+* Trellis specs updated if reusable runtime/tool/subagent contracts change.
+* Rollout/rollback considered for risky runtime changes.
+* Frontend coordination boundary respected.
+
+## Out of Scope (explicit)
+
+* Direct frontend implementation in this brainstorm task.
+* Replacing `coding-deepgent` with DeerFlow architecture.
+* Editing tutorial/reference assets unless explicitly requested.
+* Starting implementation before final target approval.
+
+## Research Notes
+
+### DeerFlow reference observations
+
+* DeerFlow uses `langgraph.json` to expose `lead_agent` and a checkpointer
+  factory to LangGraph server.
+* Its lead agent is assembled via LangChain `create_agent` with model, tools,
+  middleware, system prompt, and typed state.
+* Its subagents also create child `create_agent` instances, but with filtered
+  tools, inherited runtime context, and side-task streaming events.
+* Its useful local patterns include middleware order documentation, deferred
+  tool discovery, model provider compatibility centralization, LangGraph SDK
+  frontend streaming, and subtask progress events.
+* Its less suitable patterns include heavy global config/file I/O in
+  `make_lead_agent`, large system prompts, and product-specific upload/channel
+  complexity.
+
+### Constraints from this repo
+
+* Current mainline is `coding-deepgent/`.
+* Trellis docs are the canonical planning/spec layer.
+* Architecture posture prefers high-value clean boundaries over smallest diffs.
+* Planning targets must be explicit before non-trivial implementation.
+* Existing runtime already has `RuntimeAgentBuildRequest`,
+  `create_runtime_agent`, domain packages, tool capability contracts, subagent
+  sidechain/resume logic, runtime pressure, memory, sessions, tasks, and hooks.
+* Existing frontend work already has a protocol/bridge package and React/Ink CLI
+  surface under `coding-deepgent/frontend/cli`.
+* Existing project handoff warns not to reopen H13/H14/H21/H22 or conditional
+  L5-a without a new source-backed PRD.
+
+### Feasible roadmap postures
+
+**Approach A: Validation-first release stabilization** (Recommended)
+
+* How it works: treat DeerFlow learnings as review prompts and run a final
+  readiness audit across runtime, subagent, tool projection, frontend protocol,
+  and Trellis specs. Only open implementation tasks for concrete failed gates.
+* Pros: matches current handoff, avoids duplicating completed work, protects the
+  parallel frontend stream, and produces a clean final target before more code.
+* Cons: less exciting than new features; may produce mostly tests/docs/cleanup.
+
+**Approach B: CLI Completion Pack as next integrated implementation**
+
+* How it works: continue the existing post-CLI plan and implement streaming,
+  permission/HITL boundary, packaging, and polish.
+* Pros: most user-visible improvement; aligns with frontend work already in
+  progress and validates the event protocol for future Web.
+* Cons: touches runtime/frontend boundary while another frontend workstream is
+  active; needs coordination to avoid conflicts.
+
+**Approach C: New multi-agent capability planning**
+
+* How it works: use the completed runtime reshape as a base and start a new
+  H13/H14-style mailbox/coordinator/team plan.
+* Pros: advances deferred multi-agent architecture.
+* Cons: explicitly not the current handoff recommendation; high risk of scope
+  expansion before release stabilization and frontend completion.
+
+## Expansion Sweep
+
+### Future evolution
+
+* In 1-3 months, the same backend event/runtime contracts should support
+  React/Ink CLI, browser Web, and deeper multi-agent lifecycle.
+* Deferred H13/H14 should start only after release validation and CLI protocol
+  maturity prove the existing surfaces are stable.
+
+### Related scenarios
+
+* Runtime, frontend protocol, session/evidence, and tool projection should be
+  reviewed together because UI visibility depends on backend events being
+  meaningful and bounded.
+* Existing Typer/Rich commands and React/Ink frontend should remain separate
+  surfaces over the same runtime facts.
+
+### Failure and edge cases
+
+* A new broad optimization task could duplicate already-completed R1-R4 runtime
+  reshape or conflict with CLI frontend work.
+* Copying DeerFlow app-level patterns could reintroduce global config/prompt
+  coupling that Trellis specs already discourage.
+* Starting H13/H14 now could violate readiness gates if mailbox/coordinator
+  semantics leak into `run_subagent`, `run_fork`, or background controls.
+
+## Proposed Final Target
+
+`coding-deepgent` should be a LangChain-native local coding agent harness with:
+
+* one official `create_agent` construction seam for main/subagent/fork/future
+  roles,
+* explicit middleware/tool/state/context/store/checkpointer contracts,
+* deferred/discoverable tool surfaces governed by capability metadata and
+  shared policy,
+* durable JSONL session/evidence/sidechain records separate from live
+  projection state,
+* React/Ink CLI and future Web consuming typed frontend events rather than
+  terminal text,
+* DeerFlow-informed product maturity checks without adopting DeerFlow's global
+  config/prompt-heavy app coupling.
+
+## Candidate Roadmap
+
+### Phase 0: Final Goal And Gate Lock
+
+* Confirm final target posture and out-of-scope items.
+* Turn this PRD into the umbrella roadmap/gate.
+* Do not implement product code.
+
+### Phase 1: Validation-first Release Stabilization
+
+* Audit existing runtime reshape, ToolSearch/deferred tools, frontend protocol,
+  subagent/fork/background controls, and Trellis contracts.
+* Add or tighten tests only where gates are missing.
+* Produce a release-readiness decision: ship, fix concrete blockers, or split.
+* Selected scope: Core Release Gate.
+
+### Phase 2: CLI Completion Pack Coordination
+
+* If selected after Phase 1, continue the existing CLI Completion Pack:
+  streaming, permission/HITL boundary, product command, and polish.
+* Keep Web/HTML outside this phase.
+
+### Phase 3: Web/HTML Or Multi-Agent Planning
+
+* Choose one after CLI protocol matures:
+  * Web/HTML over the typed event stream.
+  * H13/H14 mailbox/coordinator/team planning from the readiness gate.
+
+## Decision (ADR-lite)
+
+**Context**: Backend runtime reshape and CLI frontend v1 are already completed
+or separately planned. DeerFlow review surfaced useful maturity patterns, but
+the current handoff recommends release validation / PR cleanup rather than
+opening another backend feature family by default.
+
+**Decision**: Use Approach A, validation-first release stabilization, as the
+umbrella optimization roadmap. Treat CLI Completion Pack as the next
+implementation candidate only after release gates are explicit and frontend
+coordination is clear.
+
+**Consequences**: This avoids duplicating completed runtime/frontend work and
+keeps future implementation tied to concrete failed gates. It may defer new
+multi-agent features until the current product surface is stable.
+
+## Confirmed Roadmap Posture
+
+Selected by user: **Validation-first release stabilization**.
+
+This task should now converge on a concrete validation gate plan. It should not
+start implementation or redefine completed runtime/frontend work.
+
+## Confirmed Phase 1 Scope
+
+Selected by user: **Core Release Gate**.
+
+Updated sequencing: run **Full Test Cleanup** first, then run Core Release
+Gate.
+
+Core Release Gate validates the current completed mainline for release
+readiness. It does not implement CLI streaming/HITL, Web/HTML, H13/H14
+multi-agent orchestration, or broad long-range architecture audits unless a core
+gate fails and creates a concrete follow-up.
+
+## Decision (ADR-lite): Full Test Cleanup Before Core Gate
+
+**Context**: Core Release Gate depends on focused validation. If the test suite
+is noisy, duplicated, stale, or poorly grouped, gate failures may be hard to
+interpret and may create false product blockers.
+
+**Decision**: Insert a full test-suite cleanup pass before running Core Release
+Gate.
+
+**Consequences**:
+
+* The next implementation task should not immediately run all release gates.
+* The cleanup pass should classify tests, identify duplication/noise/stale
+  coverage, define smoke/focused/deep command groups, and clean up the suite
+  before the release gate.
+* Cleanup may include test file moves/renames, shared fixture extraction,
+  command grouping docs/scripts, merging duplicated tests, and deleting stale
+  tests after replacement coverage is explicit.
+* Product behavior changes remain out of scope unless cleanup exposes a real
+  blocker that must be fixed before tests can make sense.
+
+## Full Test Cleanup Plan
+
+### Acceptance Targets
+
+* Test commands are grouped by purpose: `release smoke`, `domain focused`, and
+  `deep regression`.
+* Current tests that protect runtime/subagent/tool/session/frontend contracts
+  are identified and preserved.
+* No high-value regression coverage is deleted just to reduce test count.
+* Duplicate, stale, slow, or over-broad tests are cleaned up or explicitly left
+  with rationale.
+* Core Release Gate command set is updated after test organization.
+* Test cleanup itself ends with the cleaned suite green before Core Release Gate
+  begins.
+
+### Planned Features
+
+* Inventory `coding-deepgent/tests/` by domain and risk.
+* Map tests to the Core Gate Matrix.
+* Identify repeated fake agents, fake runtimes, stores, fixtures, and command
+  helpers that may deserve shared fixtures.
+* Identify stale tests that verify old implementation details rather than
+  current Trellis contracts.
+* Produce a test-suite triage table in this PRD before Core Release Gate.
+* Extract shared fixtures/helpers only when they remove real duplication without
+  hiding test intent.
+* Move or rename test files only when the new layout makes domain ownership and
+  command selection clearer.
+* Merge/delete stale or duplicate tests only after preserving the current
+  contract coverage elsewhere.
+
+### Initial Test Inventory
+
+* `coding-deepgent/tests/` currently has 48 Python `test_*.py` files.
+* `coding-deepgent` currently has no Makefile or pytest config file; test
+  commands are mainly documented in Trellis specs/PRDs and run ad hoc.
+* `coding-deepgent/pyproject.toml` declares dev dependencies but does not define
+  test groups, pytest markers, or command aliases.
+* Top filename clusters from a quick scan:
+  * `memory*`: 6 files
+  * `tool*`: 4 files
+  * `runtime*`: 3 files
+  * `frontend*`: 3 files
+  * `compact*`: 3 files
+  * `session*` / `sessions`: multiple files with large JSONL/session coverage
+* High-reuse fake/fixture patterns appear across:
+  * `FakeAgent`, `fake_create_agent`, and runtime factory monkeypatches
+  * `JsonlSessionStore(tmp_path / "sessions-store")`
+  * `InMemoryStore`
+  * `ToolRuntime` / runtime context helpers
+  * frontend bridge fake event streams
+* Early judgment: the suite is not "too many tests" by count alone; the main
+  risk is unclear layering, duplicated fake setup, and old stage tests that may
+  verify implementation details rather than current contracts.
+* Largest Python test files by size:
+  * `test_subagents.py`
+  * `test_runtime_pressure.py`
+  * `test_sessions.py`
+  * `test_cli.py`
+  * `test_tool_system_middleware.py`
+  These are the highest-risk cleanup targets and should not be split or reduced
+  without preserving explicit contract coverage.
+
+### Proposed Test Layers
+
+* `release smoke`: small must-pass set for current release readiness.
+* `domain focused`: tests selected by changed package/domain.
+* `deep regression`: broad runtime/session/subagent/tool/frontend protocol
+  checks for architecture changes.
+* `legacy/noisy candidates`: tests that may be renamed, merged, moved, or
+  deleted only after confirming coverage replacement.
+
+### Selected Test Layout
+
+Selected by user: **domain subdirectories**.
+
+Target shape:
+
+```text
+coding-deepgent/tests/
+  conftest.py
+  fixtures/
+    ...
+  runtime/
+    test_agent_runtime_service.py
+    test_app.py
+    test_runtime_events.py
+    test_runtime_foundation_contract.py
+    test_state.py
+  subagents/
+    test_subagents.py
+  tool_system/
+    test_tool_system_registry.py
+    test_tool_system_middleware.py
+    test_tool_search.py
+    test_tool_result_storage.py
+  filesystem/
+    test_tools.py
+  permissions/
+    test_permissions.py
+  sessions/
+    test_sessions.py
+    test_session_contributions.py
+    test_session_memory_middleware.py
+  compact/
+    test_compact_artifacts.py
+    test_compact_budget.py
+    test_compact_summarizer.py
+    test_message_projection.py
+    test_runtime_pressure.py
+  frontend/
+    test_frontend_protocol.py
+    test_frontend_bridge.py
+    test_frontend_event_mapping.py
+  memory/
+    test_memory.py
+    test_memory_backend.py
+    test_memory_cli.py
+    test_memory_context.py
+    test_memory_integration.py
+    test_memory_module_closeout.py
+  tasks/
+    test_tasks.py
+    test_planning.py
+    test_planning_renderer.py
+    test_todo_domain.py
+  extensions/
+    test_mcp.py
+    test_plugins.py
+    test_skills.py
+    test_hooks.py
+  cli/
+    test_cli.py
+    test_renderers.py
+    test_rendering.py
+  config/
+    test_config.py
+    test_context_payloads.py
+    test_logging.py
+    test_prompting.py
+    test_rules.py
+  structure/
+    test_structure.py
+    test_contract.py
+    test_architecture_reshape.py
+```
+
+This layout may be adjusted during inventory if a file clearly belongs in a
+different domain. The cleanup pass should keep import paths stable from product
+code and update Trellis test command references after moves.
+
+Collection check after mechanical move:
+
+```bash
+pytest -q coding-deepgent/tests --collect-only
+```
+
+Result: `386 tests collected`.
+
+### Planned Extensions
+
+* CI matrix integration if current repo scripts need a broader cleanup.
+* Performance tuning for slow tests after release gate passes.
+* Cross-package test layout changes if frontend/Web grows.
+
+### Out Of Scope
+
+* Large product behavior changes.
+* Removing regression tests without replacement.
+* Refactoring runtime/subagent/tool code just to make tests easier.
+* Broad CI restructuring unless a concrete release blocker is found.
+* Changing public tool schemas or frontend protocol just to simplify tests.
+
+### Cleanup Guardrails
+
+* Every delete/merge must name the replacement coverage.
+* Prefer moving duplicated setup into local/shared fixtures over weakening
+  assertions.
+* Preserve contract-focused assertions even if they look verbose.
+* Do not turn focused unit tests into broad integration tests.
+* Do not make tests depend on live network, API keys, or user-specific state.
+* Keep product code edits minimal and only for real bugs found by cleanup.
+
+### Cleanup Stages
+
+1. Inventory and classify
+   * Build a table of every test file, owning domain, gate mapping, and rough
+     layer: smoke/focused/deep/legacy.
+   * Identify shared fixture candidates and stale implementation-detail tests.
+
+2. Create test organization surface
+   * Add a lightweight test index/plan under Trellis or test docs.
+   * Define command groups for release smoke, domain focused, and deep
+     regression.
+   * Prefer documenting commands first; add pytest markers or scripts only if
+     they materially improve repeatability.
+
+3. Mechanical cleanup
+   * Move tests into domain subdirectories according to the selected layout.
+   * Extract repeated fixtures/helpers when duplication is concrete.
+   * Keep imports and command paths updated.
+
+4. Coverage consolidation
+   * Merge truly duplicated assertions.
+   * Delete stale tests only when current contract coverage is retained.
+   * Mark risky candidates as follow-up instead of forcing deletion.
+
+5. Cleanup validation
+   * Run affected focused tests first.
+   * Run the full cleaned Python test suite if feasible.
+   * Run TS frontend tests if frontend protocol/CLI test files are touched.
+
+6. Proceed to Core Release Gate
+   * Only after cleanup validation passes.
+
+## Core Release Gate Plan
+
+### Acceptance Targets
+
+* Current `coding-deepgent` backend/runtime mainline has a source-backed
+  release readiness verdict.
+* Completed runtime reshape work is verified rather than reopened.
+* Completed frontend protocol/bridge v1 is checked only as a backend contract
+  surface, not as a new frontend implementation lane.
+* DeerFlow learnings are converted into concrete gates: construction seam,
+  middleware/tool/state boundaries, deferred tool discovery, subagent lifecycle,
+  session/evidence continuity, and typed UI protocol.
+* Any failed gate produces a small, concrete follow-up task with affected files,
+  expected behavior, tests, and owner boundary.
+
+### Planned Features
+
+* Build a Core Release Gate checklist in this PRD.
+* Run focused validation against current runtime/subagent/tool/session/frontend
+  protocol surfaces.
+* Compare validation results with Trellis contracts and update this PRD with a
+  release-readiness verdict.
+* If gaps are found, classify them as:
+  * `blocker`: must fix before release,
+  * `follow-up`: should be planned but does not block current release,
+  * `deferred`: intentionally out of current scope.
+
+### Planned Extensions
+
+* CLI Completion Pack: streaming, permission/HITL, product command, CLI polish.
+* Web/HTML over typed frontend event protocol.
+* H13/H14 mailbox/coordinator/team runtime.
+* Deep architecture audits for transcript identity, durable memory backend, and
+  long-range Web/multi-agent evolution.
+
+### Out Of Scope
+
+* Implementing new frontend features.
+* Implementing real streaming or HITL permission pause/resume.
+* Implementing H13/H14 or changing subagent/fork schemas to support team
+  semantics.
+* Replacing LangChain/LangGraph seams.
+* Copying DeerFlow application structure.
+
+## Core Gate Matrix
+
+### Gate 1: Runtime Construction Seam
+
+Target:
+
+* main/subagent/fork agent construction goes through
+  `RuntimeAgentBuildRequest` and `create_runtime_agent`.
+* no direct child/fork bypass of the project-local runtime factory seam.
+* `create_agent` remains the official LangChain primitive behind that seam.
+
+Evidence:
+
+* `coding-deepgent/src/coding_deepgent/runtime/agent_factory.py`
+* `coding-deepgent/src/coding_deepgent/agent_service.py`
+* `coding-deepgent/src/coding_deepgent/subagents/tools.py`
+* `coding-deepgent/tests/runtime/test_agent_runtime_service.py`
+* `coding-deepgent/tests/subagents/test_subagents.py`
+
+Validation:
+
+```bash
+pytest -q coding-deepgent/tests/runtime/test_agent_runtime_service.py coding-deepgent/tests/runtime/test_app.py
+pytest -q coding-deepgent/tests/subagents/test_subagents.py
+```
+
+### Gate 2: Subagent/Fork/Background Boundaries
+
+Target:
+
+* `run_subagent`, `run_fork`, resume tools, and background controls keep their
+  current bounded local semantics.
+* mailbox/coordinator/team/Scratchpad fields do not leak into these schemas.
+* sidechain/resume/evidence lineage remains durable and bounded.
+* background runs preserve durable record vs runtime snapshot vs process-local
+  handle separation.
+
+Evidence:
+
+* `coding-deepgent/src/coding_deepgent/subagents/`
+* `coding-deepgent/src/coding_deepgent/sessions/`
+* `.trellis/spec/backend/project-infrastructure-foundation-contracts.md`
+* `.trellis/spec/backend/session-compact-contracts.md`
+
+Validation:
+
+```bash
+pytest -q coding-deepgent/tests/subagents/test_subagents.py coding-deepgent/tests/sessions/test_sessions.py
+```
+
+### Gate 3: Tool Capability And Deferred Discovery
+
+Target:
+
+* tool capability metadata remains five-factor complete.
+* builtin name collisions are rejected.
+* role/tool projection remains explicit.
+* `ToolSearch` / `invoke_deferred_tool` goes through shared policy and
+  middleware, including denied/error cases.
+* MCP and advanced lifecycle tools remain deferred unless explicitly promoted.
+
+Evidence:
+
+* `coding-deepgent/src/coding_deepgent/tool_system/`
+* `coding-deepgent/src/coding_deepgent/mcp/`
+* `.trellis/spec/backend/tool-capability-contracts.md`
+
+Validation:
+
+```bash
+pytest -q coding-deepgent/tests/tool_system/test_tool_system_registry.py coding-deepgent/tests/tool_system/test_tool_system_middleware.py coding-deepgent/tests/tool_system/test_tool_search.py coding-deepgent/tests/extensions/test_mcp.py
+```
+
+### Gate 4: Session, Evidence, Recovery, And Runtime Pressure
+
+Target:
+
+* JSONL transcript/session/evidence remains the durable user-facing record.
+* runtime pressure, compact/collapse projection, and tool-result persistence do
+  not corrupt raw session history.
+* recovery briefs expose bounded high-value evidence and state.
+* runtime event evidence remains whitelisted and bounded.
+
+Evidence:
+
+* `coding-deepgent/src/coding_deepgent/sessions/`
+* `coding-deepgent/src/coding_deepgent/compact/`
+* `coding-deepgent/src/coding_deepgent/runtime/events.py`
+* `.trellis/spec/backend/runtime-context-compaction-contracts.md`
+* `.trellis/spec/backend/runtime-pressure-contracts.md`
+* `.trellis/spec/backend/session-compact-contracts.md`
+
+Validation:
+
+```bash
+pytest -q coding-deepgent/tests/sessions/test_sessions.py coding-deepgent/tests/compact/test_runtime_pressure.py coding-deepgent/tests/tool_system/test_tool_result_storage.py coding-deepgent/tests/runtime/test_runtime_events.py
+```
+
+### Gate 5: Frontend Protocol Contract
+
+Target:
+
+* Python frontend protocol models, JSONL bridge, and event mapping remain strict
+  and synchronized with the React/Ink CLI contract.
+* validation covers fake bridge and event mapping without entering CLI
+  Completion Pack work.
+* stdout remains event-only and logs remain out of the JSONL stream.
+
+Evidence:
+
+* `coding-deepgent/src/coding_deepgent/frontend/`
+* `coding-deepgent/frontend/cli/src/bridge/`
+* `coding-deepgent/frontend/protocol/README.md`
+* `.trellis/spec/frontend/*`
+
+Validation:
+
+```bash
+pytest -q coding-deepgent/tests/frontend/test_frontend_protocol.py coding-deepgent/tests/frontend/test_frontend_bridge.py coding-deepgent/tests/frontend/test_frontend_event_mapping.py
+npm --prefix coding-deepgent/frontend/cli run typecheck
+npm --prefix coding-deepgent/frontend/cli test
+```
+
+### Gate 6: Trellis Contract Alignment
+
+Target:
+
+* `.trellis/project-handoff.md` and backend/frontend specs match the actual
+  implemented state.
+* completed stages are not reopened by vague "closer to DeerFlow/cc" language.
+* next recommended work remains release validation / cleanup unless a concrete
+  gate fails.
+
+Evidence:
+
+* `.trellis/project-handoff.md`
+* `.trellis/spec/backend/index.md`
+* `.trellis/spec/frontend/index.md`
+* `.trellis/tasks/04-19-*`
+
+Validation:
+
+* Manual spec/readiness review recorded in this PRD.
+* No code change required unless a mismatch creates a concrete release risk.
+
+## Phase 1 Execution Plan
+
+1. Full Test Cleanup
+   * Inventory test files and map them to domains/gates.
+   * Produce recommended command groups.
+   * Extract shared fixtures/helpers where they clearly reduce duplication.
+   * Move/rename/merge/delete stale or duplicate tests only with replacement
+     coverage identified.
+   * Validate the cleaned suite before the release gate.
+
+2. Preflight
+   * Record branch/status and dirty worktree caveats.
+   * Identify unrelated changes to avoid touching.
+
+3. Focused Test Pass
+   * Run the gate commands above in logical groups.
+   * Prefer focused tests over broad suite unless a failure suggests wider risk.
+
+4. Contract Review
+   * Compare implemented state with Trellis backend/frontend contracts.
+   * Check for stale claims, duplicated docs, or completed tasks that should not
+     be reopened.
+
+5. Gap Classification
+   * For each failed gate, classify as `blocker`, `follow-up`, or `deferred`.
+   * Do not fix during validation unless the issue is tiny, isolated, and clearly
+     within release readiness.
+
+6. Release Verdict
+   * Write one of:
+     * `READY`: no blocking gaps,
+     * `READY_WITH_FOLLOW_UPS`: non-blocking gaps remain,
+     * `NOT_READY`: one or more blockers require a scoped task.
+
+## Validation Command Set
+
+Primary focused validation:
+
+```bash
+pytest -q coding-deepgent/tests/runtime/test_agent_runtime_service.py coding-deepgent/tests/runtime/test_app.py
+pytest -q coding-deepgent/tests/subagents/test_subagents.py coding-deepgent/tests/sessions/test_sessions.py
+pytest -q coding-deepgent/tests/tool_system/test_tool_system_registry.py coding-deepgent/tests/tool_system/test_tool_system_middleware.py coding-deepgent/tests/tool_system/test_tool_search.py coding-deepgent/tests/extensions/test_mcp.py
+pytest -q coding-deepgent/tests/compact/test_runtime_pressure.py coding-deepgent/tests/tool_system/test_tool_result_storage.py coding-deepgent/tests/runtime/test_runtime_events.py
+pytest -q coding-deepgent/tests/frontend/test_frontend_protocol.py coding-deepgent/tests/frontend/test_frontend_bridge.py coding-deepgent/tests/frontend/test_frontend_event_mapping.py
+npm --prefix coding-deepgent/frontend/cli run typecheck
+npm --prefix coding-deepgent/frontend/cli test
+```
+
+Lint/type check if files are edited:
+
+```bash
+ruff check <touched-python-files>
+mypy <touched-python-files>
+```
+
+## Final Confirmation Draft
+
+**Goal**: validate the current completed `coding-deepgent` mainline for release
+readiness using a Core Release Gate, informed by DeerFlow review but not copying
+DeerFlow or opening new feature work.
+
+**Requirements**:
+
+* Validate runtime construction, subagent/fork/background boundaries,
+  tool/deferred discovery, session/evidence/recovery/runtime pressure, frontend
+  protocol, and Trellis contract alignment.
+* Do not implement CLI streaming/HITL, Web/HTML, or H13/H14 as part of this
+  task.
+* Convert any failed gate into a concrete blocker/follow-up/deferred decision.
+* Preserve the parallel frontend workstream boundary.
+
+**Implementation Plan**:
+
+* Task Workflow Phase 2 will configure backend/fullstack validation context.
+* Phase 3 will first organize/triage tests, then run the Core Release Gate
+  validation pass and update this PRD with the release verdict.
+* Product code edits happen only if a small release-blocking issue is found and
+  can be fixed safely within this scope; otherwise create a follow-up task.
+
+## Technical Notes
+
+* Read `.trellis/spec/guides/planning-targets-guide.md`.
+* Read `.trellis/spec/guides/architecture-posture-guide.md`.
+* Read `.trellis/spec/guides/mainline-scope-guide.md`.
+* Prior DeerFlow source review used `/tmp/deer-flow-codex-review`.
+
+## Checkpoint: Full Test Cleanup And Core Release Gate
+
+State:
+
+* terminal
+
+Verdict:
+
+* READY_WITH_FOLLOW_UPS
+
+Implemented:
+
+* Moved 48 Python product test files from flat `coding-deepgent/tests/` into
+  domain subdirectories.
+* Kept root `coding-deepgent/tests/conftest.py` as the shared no-network and
+  `PYTHONPATH` setup.
+* Added `coding-deepgent/tests/README.md` with domain layout, release smoke,
+  focused, and deep regression command groups.
+* Updated current Trellis specs/plans/tasks references from old flat test paths
+  to the new domain paths. Archived historical task records were left intact.
+* Fixed moved root-path assumptions in structure/runtime/todo tests.
+* Fixed stale memory CLI tests to patch the current `coding_deepgent.app`
+  `build_container` seam instead of the old `coding_deepgent.cli` seam.
+* Removed stale unused imports caught by lint in
+  `tests/memory/test_memory_module_closeout.py`.
+
+Validation:
+
+* `pytest -q coding-deepgent/tests --collect-only` -> 386 tests collected.
+* `pytest -q coding-deepgent/tests` -> 386 passed.
+* `pytest -q tests/runtime tests/subagents tests/tool_system tests/sessions tests/frontend`
+  from `coding-deepgent/` -> 156 passed.
+* `ruff check coding-deepgent/tests` -> passed.
+* `npm --prefix coding-deepgent/frontend/cli run typecheck` -> passed.
+* `npm --prefix coding-deepgent/frontend/cli test` -> 2 files / 8 tests passed.
+* Current Trellis/spec/plan search for active old flat test paths returned no
+  matches.
+
+Core Gate Result:
+
+* Runtime construction seam: passed by moved runtime/app/subagent tests.
+* Subagent/fork/background boundaries: passed by moved subagent/session tests.
+* Tool capability and deferred discovery: passed by moved tool system and MCP
+  tests.
+* Session/evidence/recovery/runtime pressure: passed by moved sessions/compact
+  tests and full suite.
+* Frontend protocol contract: passed by moved frontend Python tests plus TS
+  typecheck/tests.
+* Trellis contract alignment: active references updated to new test layout.
+
+Follow-ups:
+
+* Consider a separate low-risk fixture extraction pass for repeated fake agent,
+  fake runtime, `JsonlSessionStore`, and `InMemoryStore` setup after release
+  gate work is committed.
+* Consider adding pytest markers or a lightweight command wrapper only if the
+  README command groups prove insufficient during repeated use.
+* Existing broad dirty worktree contains unrelated prior changes; release verdict
+  here covers the test cleanup/core gate surfaces, not the entire uncommitted
+  branch state.
diff --git a/.trellis/tasks/archive/2026-04/04-19-agent-harness-optimization-roadmap/task.json b/.trellis/tasks/archive/2026-04/04-19-agent-harness-optimization-roadmap/task.json
new file mode 100644
index 000000000..4f3499cc4
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-agent-harness-optimization-roadmap/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "agent-harness-optimization-roadmap",
+  "name": "agent-harness-optimization-roadmap",
+  "title": "brainstorm: agent harness optimization roadmap",
+  "description": "",
+  "status": "completed",
+  "dev_type": "fullstack",
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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/archive/2026-04/04-19-backend-next-step-release-validation-pr-cleanup/check.jsonl b/.trellis/tasks/archive/2026-04/04-19-backend-next-step-release-validation-pr-cleanup/check.jsonl
new file mode 100644
index 000000000..834b53148
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-backend-next-step-release-validation-pr-cleanup/check.jsonl
@@ -0,0 +1,6 @@
+{"file": ".gemini/commands/trellis/finish-work.toml", "reason": "Finish work checklist"}
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
+{"file": ".trellis/spec/guides/mainline-scope-guide.md", "reason": "Check final cleanup stays in coding-deepgent mainline scope."}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Backend review checklist and focused verification requirements."}
+{"file": ".trellis/spec/frontend/quality-guidelines.md", "reason": "Frontend CLI required checks and smoke expectations."}
diff --git a/.trellis/tasks/archive/2026-04/04-19-backend-next-step-release-validation-pr-cleanup/debug.jsonl b/.trellis/tasks/archive/2026-04/04-19-backend-next-step-release-validation-pr-cleanup/debug.jsonl
new file mode 100644
index 000000000..c1b287771
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-backend-next-step-release-validation-pr-cleanup/debug.jsonl
@@ -0,0 +1,2 @@
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-19-backend-next-step-release-validation-pr-cleanup/implement.jsonl b/.trellis/tasks/archive/2026-04/04-19-backend-next-step-release-validation-pr-cleanup/implement.jsonl
new file mode 100644
index 000000000..6f2c2068c
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-backend-next-step-release-validation-pr-cleanup/implement.jsonl
@@ -0,0 +1,7 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": ".trellis/spec/frontend/index.md", "reason": "Frontend development guide"}
+{"file": ".trellis/project-handoff.md", "reason": "Canonical handoff says recommended next task is release validation / PR cleanup."}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Backend review and focused validation baseline for coding-deepgent mainline."}
+{"file": ".trellis/spec/frontend/quality-guidelines.md", "reason": "Frontend CLI and bridge validation baseline."}
+{"file": ".trellis/spec/guides/mainline-scope-guide.md", "reason": "Keep validation scoped to coding-deepgent mainline rather than tutorial/reference layers."}
diff --git a/.trellis/tasks/archive/2026-04/04-19-backend-next-step-release-validation-pr-cleanup/prd.md b/.trellis/tasks/archive/2026-04/04-19-backend-next-step-release-validation-pr-cleanup/prd.md
new file mode 100644
index 000000000..b1dacb10e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-backend-next-step-release-validation-pr-cleanup/prd.md
@@ -0,0 +1,73 @@
+# Backend Next Step Release Validation and PR Cleanup
+
+## Goal
+
+对当前 `coding-deepgent` 主线的 release 候选改动进行 focused validation 和必要的 PR cleanup，优先确认当前工作区中的 frontend gateway / CLI surface 相关改动是否满足质量门槛、文档是否一致、测试是否覆盖、是否存在应在合并前修正的问题。
+
+## Requirements
+
+- 只面向当前 `coding-deepgent/` 主线和 `.trellis/` 规范层工作。
+- 不默认开启新的 backend feature family。
+- 不重开 `L5-a`，除非验证中发现真实的并发/分区缺陷。
+- 对当前未提交改动执行 focused review、测试、lint、typecheck 和必要清理。
+- 若发现问题，优先做小范围修正与补测；不引入与当前 release 无关的重构。
+- 明确记录 residual risk 和未验证项。
+
+## Acceptance Targets
+
+- 当前 release 候选改动的行为边界被验证，尤其是 CLI/frontend gateway 入口与测试覆盖。
+- README / CLI help / 实际命令面一致，不存在误导性文档。
+- 相关 focused checks 运行完成，失败项被修复或明确记录。
+- 最终结论明确：可继续进入 PR 收口，或应先修复具体问题。
+
+## Planned Features
+
+- 审查当前工作区改动与推荐主线方向是否一致。
+- 补全与当前改动直接相关的 Trellis task context。
+- 运行 focused Python tests、frontend checks、静态检查和必要的 smoke validation。
+- 在需要时做最小 PR cleanup，包括测试、文档或薄层 CLI wiring 修正。
+
+## Planned Extensions
+
+- 新的 runtime feature family。
+- Web/HTML 正式产品化。
+- 广泛的全量回归，除非 focused checks 暴露更大范围耦合风险。
+
+## Technical Notes
+
+- 当前主线推荐动作来自 `.trellis/project-handoff.md`：`release validation / PR cleanup for Approach A MVP`。
+- 当前工作区已有未提交改动，验证时必须把这些改动视为候选范围，不回滚无关用户改动。
+- 本任务是 `fullstack`：Python backend + `frontend/cli` + gateway transport seam。
+
+## Implementation Checkpoint
+
+State:
+
+- terminal
+
+Verdict:
+
+- APPROVE
+
+Implemented:
+
+- 对当前 `ui-gateway` / frontend gateway / minimal web shell 相关 release 候选改动做了 focused validation。
+- 识别并修复 `ui-gateway` 的真实发布风险：命令依赖 `fastapi` / `uvicorn`，但此前未在 `pyproject.toml` 中显式声明。
+- 为 gateway 增加可选 `web` extra，并在 CLI 缺少依赖时输出明确安装提示。
+- 更新 README 的命令说明，使文档、CLI surface 与安装方式一致。
+- 补充 CLI 与 runtime contract regression tests，覆盖 gateway runtime loader 和可选依赖声明。
+
+Verification:
+
+- `pytest -q tests/frontend/test_frontend_gateway.py tests/frontend/test_stream_bridge.py tests/frontend/test_frontend_runs.py tests/frontend/test_frontend_sse.py tests/frontend/test_frontend_client.py tests/frontend/test_frontend_protocol.py tests/frontend/test_frontend_bridge.py tests/frontend/test_frontend_event_mapping.py tests/structure/test_structure.py tests/cli/test_cli.py tests/runtime/test_runtime_foundation_contract.py` -> `64 passed`
+- `ruff check src/coding_deepgent/frontend src/coding_deepgent/cli.py tests/frontend/test_frontend_gateway.py tests/frontend/test_stream_bridge.py tests/frontend/test_frontend_runs.py tests/frontend/test_frontend_sse.py tests/frontend/test_frontend_client.py tests/structure/test_structure.py tests/cli/test_cli.py tests/runtime/test_runtime_foundation_contract.py` -> passed
+- `mypy src/coding_deepgent/frontend src/coding_deepgent/cli.py` -> passed
+- `npm --prefix coding-deepgent/frontend/cli run typecheck` -> passed
+- `npm --prefix coding-deepgent/frontend/cli test` -> passed
+- fake smoke: `PYTHONPATH=src python3 -m coding_deepgent.cli ui-bridge --fake`
+- fake smoke: `PYTHONPATH=src timeout 5s python3 -m coding_deepgent.cli ui-gateway --fake --host 127.0.0.1 --port 2027`
+
+Residual Risk:
+
+- `ui-gateway` 仍是 future-Web foundation，不应被误解为完整 Web 产品或真正的 HITL pause/resume 能力。
+- 本次验证使用的是 focused checks，不是全量回归；当前没有证据表明需要扩大验证范围。
diff --git a/.trellis/tasks/archive/2026-04/04-19-backend-next-step-release-validation-pr-cleanup/task.json b/.trellis/tasks/archive/2026-04/04-19-backend-next-step-release-validation-pr-cleanup/task.json
new file mode 100644
index 000000000..9a5b5597b
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-backend-next-step-release-validation-pr-cleanup/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "backend-next-step-release-validation-pr-cleanup",
+  "name": "backend-next-step-release-validation-pr-cleanup",
+  "title": "Backend Next Step Release Validation and PR Cleanup",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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/archive/2026-04/04-19-backend-next-step-roadmap/check.jsonl b/.trellis/tasks/archive/2026-04/04-19-backend-next-step-roadmap/check.jsonl
new file mode 100644
index 000000000..dfe6526d5
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-backend-next-step-roadmap/check.jsonl
@@ -0,0 +1,2 @@
+{"file": ".gemini/commands/trellis/finish-work.toml", "reason": "Finish work checklist"}
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-19-backend-next-step-roadmap/debug.jsonl b/.trellis/tasks/archive/2026-04/04-19-backend-next-step-roadmap/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-backend-next-step-roadmap/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-19-backend-next-step-roadmap/implement.jsonl b/.trellis/tasks/archive/2026-04/04-19-backend-next-step-roadmap/implement.jsonl
new file mode 100644
index 000000000..76f655a1e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-backend-next-step-roadmap/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/spec/guides/planning-targets-guide.md", "reason": "Roadmap planning standard with acceptance/planned/deferred buckets."}
+{"file": ".trellis/project-handoff.md", "reason": "Current mainline status and release baseline."}
diff --git a/.trellis/tasks/archive/2026-04/04-19-backend-next-step-roadmap/prd.md b/.trellis/tasks/archive/2026-04/04-19-backend-next-step-roadmap/prd.md
new file mode 100644
index 000000000..c6f8489c4
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-backend-next-step-roadmap/prd.md
@@ -0,0 +1,60 @@
+# Backend Next-Step Roadmap After MVP Closeout
+
+## Goal
+
+在 `coding-deepgent/` 已完成 Approach A MVP 主干后，输出一个可执行的后端下一阶段 roadmap，明确先收口什么、再补哪些 cc 核心能力、哪些边界继续保持 deferred。
+
+## Acceptance Targets
+
+- 当前主线状态被压缩成一份清晰判断，而不是继续沿用旧阶段口径。
+- roadmap 明确区分:
+  - 必须先收口的 release/contract 漂移
+  - 应优先补齐的后端能力
+  - 已知但继续 deferred 的能力
+- 每个 roadmap 阶段都写清楚:
+  - concrete benefit
+  - target modules
+  - verification path
+  - intentionally deferred extensions
+- 规划结论保持与现有 Trellis canonical docs 一致，不误把 tutorial/reference 层当作主线。
+
+## Planned Features
+
+- 基于 `.trellis/project-handoff.md`、canonical roadmap、deferred ADR 和当前代码/测试状态，整理真实主线现状。
+- 产出一个分阶段后端 roadmap，优先覆盖:
+  - release cleanup / contract lock
+  - `H01` 的 ToolSearch / deferred tool discovery
+  - `H11/H12` 的 subagent / fork contract consolidation
+- 明确哪些能力不应现在默认重开:
+  - `H13/H14`
+  - `H21/H22`
+  - provider-specific observability / cache / billing
+
+## Planned Extensions
+
+- 若后续有新的 source-backed PRD，再讨论:
+  - mailbox / `SendMessage`
+  - coordinator synthesis runtime
+  - remote / IDE control plane
+  - daemon / cron / proactive automation
+  - richer telemetry / TTFT / provider-specific cost-cache instrumentation
+
+## Requirements
+
+- 只服务当前 product mainline: `coding-deepgent/`
+- 只讨论后端/runtime/product contract，不展开 tutorial parity
+- 优先给出“为什么现在做”而不是“更像 cc”
+
+## Technical Notes
+
+- 当前真实回归点包括:
+  - `test_app.py` 中主工具列表与实际 tool surface 漂移
+  - `agent_loop_service.py` 中 memory queue 默认行为触发 Redis 依赖
+  - `hooks/dispatcher.py` 的 runtime evidence metadata 与测试契约漂移
+- 当前高价值代码入口包括:
+  - `coding-deepgent/src/coding_deepgent/tool_system/capabilities.py`
+  - `coding-deepgent/src/coding_deepgent/subagents/tools.py`
+  - `coding-deepgent/src/coding_deepgent/subagents/background.py`
+  - `coding-deepgent/src/coding_deepgent/agent_loop_service.py`
+  - `coding-deepgent/src/coding_deepgent/memory/queue.py`
+  - `coding-deepgent/src/coding_deepgent/hooks/dispatcher.py`
diff --git a/.trellis/tasks/archive/2026-04/04-19-backend-next-step-roadmap/roadmap.md b/.trellis/tasks/archive/2026-04/04-19-backend-next-step-roadmap/roadmap.md
new file mode 100644
index 000000000..e1fbfa735
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-backend-next-step-roadmap/roadmap.md
@@ -0,0 +1,235 @@
+# Backend Next-Step Roadmap
+
+Status: implemented through Stage 2  
+Scope: `coding-deepgent/` backend / runtime mainline only  
+Updated: 2026-04-19
+
+## Current Reading
+
+The current product is no longer missing its core runtime skeleton.
+
+What is already in place:
+
+- `H01-H12`, `H15-H20` have local MVP coverage in canonical Trellis docs.
+- core domains are already separated into `runtime`, `tool_system`, `sessions`,
+  `memory`, `tasks`, `subagents`, `mcp`, and `plugins`.
+- `coding-deepgent/tests` has broad regression coverage.
+
+What is still visibly unstable:
+
+- public tool-surface expectations are drifting from the actual subagent/fork tools
+- memory extraction queue behavior is not safely isolated for all test/local paths
+- hook runtime evidence metadata has contract drift
+- some handoff/dashboard wording still reflects an earlier checkpoint state
+
+Decision:
+
+- do **not** reopen mailbox/coordinator/remote/daemon by default
+- first restore one clean release baseline
+- then add the next highest-leverage cc-aligned backend capabilities
+
+## Priority Order
+
+1. Release cleanup and contract lock
+2. ToolSearch / deferred tool discovery
+3. Subagent / fork contract consolidation
+4. Secondary backlog only after the above are green
+
+## Stage 0: Release Cleanup And Contract Lock
+
+Status: completed on 2026-04-19
+
+### Why Now
+
+The current branch is close to a post-MVP cleanup point, but it is not yet a
+clean baseline. Expanding the runtime before the existing contracts are locked
+would compound drift.
+
+### Acceptance Targets
+
+- `pytest -q coding-deepgent/tests` is green again.
+- one explicit answer exists for which subagent/fork tools belong in the main
+  public tool surface today
+- `agent_loop` local/test paths do not require a live Redis dependency by default
+- hook evidence metadata is stable across runtime events, session evidence, and tests
+- handoff/dashboard wording matches the actual completed topology state
+
+### Planned Features
+
+- align `app`/bootstrap tool binding expectations with the real current
+  subagent/fork/background surface
+- make memory queue behavior safe for test/local non-network execution
+- normalize hook evidence metadata contract and update tests/docs accordingly
+- refresh handoff wording so the next suggested task is not stale
+
+### Target Modules
+
+- `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/memory/queue.py`
+- `coding-deepgent/src/coding_deepgent/memory/service.py`
+- `coding-deepgent/src/coding_deepgent/hooks/dispatcher.py`
+- `coding-deepgent/tests/test_app.py`
+- `coding-deepgent/tests/test_hooks.py`
+
+### Verification
+
+- `pytest -q coding-deepgent/tests`
+- targeted review that public tool names, queue semantics, and evidence metadata
+  are consistent across code, docs, and tests
+
+### Planned Extensions
+
+- no new user-facing runtime family should start in this stage
+- do not widen into ToolSearch, mailbox, or coordinator here
+
+## Stage 1: ToolSearch / Deferred Tool Discovery
+
+Status: completed on 2026-04-19
+
+### Why Now
+
+This is the next highest-leverage backend gap. The codebase already has
+five-factor capability metadata and explicit `main` / `child` / `extension` /
+`deferred` projection foundations, but no real deferred discovery runtime.
+
+This feature improves:
+
+- prompt/context pressure
+- MCP / extension scalability
+- tool-surface hygiene
+- future cache-safe prompt shaping
+
+### Acceptance Targets
+
+- the main agent can keep a smaller visible tool surface without losing access
+  to deferred capabilities
+- the runtime has one explicit way to discover deferred tools and reveal their
+  schema/usage on demand
+- extension/MCP tools can participate in the same deferred-discovery contract
+  without bypassing capability registry validation
+- tests prove deferred tools do not break projection, pairing, or tool-result
+  contracts
+
+### Planned Features
+
+- add a `ToolSearch`-style runtime surface for deferred capabilities
+- extend tool capability metadata only where needed to support discovery,
+  rendering, and safe schema reveal
+- define how deferred builtin, MCP, and plugin tools are indexed and exposed
+- keep discovery explicit rather than dynamic hot-swap magic
+
+### Target Modules
+
+- `coding-deepgent/src/coding_deepgent/tool_system/capabilities.py`
+- `coding-deepgent/src/coding_deepgent/tool_system/middleware.py`
+- `coding-deepgent/src/coding_deepgent/mcp/`
+- `coding-deepgent/src/coding_deepgent/plugins/`
+- `coding-deepgent/src/coding_deepgent/prompting/builder.py`
+- `coding-deepgent/tests/test_tool_system_registry.py`
+- `coding-deepgent/tests/test_mcp.py`
+- `coding-deepgent/tests/test_prompting.py`
+
+### Verification
+
+- projection tests covering `main`, `child`, `extension`, and `deferred`
+- integration tests showing deferred tool lookup followed by real execution
+- prompt/context budget checks confirming the visible tool surface can shrink
+
+### Planned Extensions
+
+- dynamic hot-swap tool pools
+- streaming tool execution
+- provider-specific prompt-cache tuning
+- concurrency partition adapter unless a failing test proves it is needed
+
+## Stage 2: Subagent / Fork Contract Consolidation
+
+Status: completed on 2026-04-19
+
+### Why Now
+
+The local H11/H12 slice is already deeper than the old README language:
+background runs, status polling, send-input continuation, stop/cancel, and
+resume paths already exist. The missing piece is not raw capability, but one
+stable product contract across code, tests, docs, and tool exposure.
+
+### Acceptance Targets
+
+- one canonical public contract exists for:
+  - `run_subagent`
+  - `run_fork`
+  - background execution
+  - status polling
+  - follow-up input
+  - stop/cancel
+  - resume
+- main-agent exposure and documentation match the actual supported local slice
+- sidechain/background state is inspectable and resumable without contract
+  ambiguity
+- current local slice is clearly separated from deferred mailbox/coordinator work
+
+### Planned Features
+
+- freeze the intended local tool surface for subagent/fork operations
+- consolidate schema naming, result-envelope wording, and background-run records
+- align sidechain transcript, notification evidence, and resume metadata docs
+- make the distinction between synchronous child runtime and richer agent-team
+  orchestration explicit
+
+### Target Modules
+
+- `coding-deepgent/src/coding_deepgent/subagents/tools.py`
+- `coding-deepgent/src/coding_deepgent/subagents/background.py`
+- `coding-deepgent/src/coding_deepgent/subagents/schemas.py`
+- `coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py`
+- `coding-deepgent/tests/test_subagents.py`
+- `coding-deepgent/tests/test_app.py`
+- `.trellis/project-handoff.md`
+- `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+
+### Verification
+
+- focused `test_subagents.py` contract coverage
+- `test_app.py` alignment coverage for main public tool surface
+- docs review confirming H11/H12 implemented-minimal scope is explicit
+
+### Planned Extensions
+
+- implicit fork mode
+- exact-tool-inheritance cache-safe fork parity
+- mailbox / `SendMessage`
+- coordinator synthesis runtime
+- richer background worker orchestration
+
+## Stage 3: Secondary Backlog After The Baseline Is Stable
+
+These are valid candidates only after Stage 0-2 are complete:
+
+- plugin lifecycle deepening beyond manifest/source validation
+- richer permission ask / interactive approval state machine
+- stronger local async job/worker contracts that support future agent-team work
+- richer observability and provider-specific cost/cache telemetry
+
+These should not start by default. Each one needs its own source-backed PRD.
+
+## Explicitly Deferred
+
+Still deferred unless product direction changes:
+
+- `H13` mailbox / `SendMessage`
+- `H14` coordinator synthesis runtime
+- `H21` bridge / remote / IDE control plane
+- `H22` daemon / cron / proactive automation
+- provider-specific telemetry, billing, TTFT, and cache internals
+
+## Recommended Next Execution Slice
+
+If choosing only one immediate task, do this:
+
+1. close Stage 0 and get back to a clean test baseline
+2. then open a focused PRD for Stage 1 ToolSearch / deferred tool discovery
+
+That ordering keeps the codebase reliable while still moving toward the most
+valuable remaining cc-aligned backend gap.
diff --git a/.trellis/tasks/archive/2026-04/04-19-backend-next-step-roadmap/task.json b/.trellis/tasks/archive/2026-04/04-19-backend-next-step-roadmap/task.json
new file mode 100644
index 000000000..3e30ff2df
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-backend-next-step-roadmap/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "backend-next-step-roadmap",
+  "name": "backend-next-step-roadmap",
+  "title": "Backend next-step roadmap after MVP closeout",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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/archive/2026-04/04-19-cli-packaging-start-command-polish/check.jsonl b/.trellis/tasks/archive/2026-04/04-19-cli-packaging-start-command-polish/check.jsonl
new file mode 100644
index 000000000..87729f303
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-cli-packaging-start-command-polish/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": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
+{"file": ".trellis/spec/frontend/quality-guidelines.md", "reason": "Verify tests/smoke requirements."}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Review scoped mainline quality."}
diff --git a/.trellis/tasks/archive/2026-04/04-19-cli-packaging-start-command-polish/debug.jsonl b/.trellis/tasks/archive/2026-04/04-19-cli-packaging-start-command-polish/debug.jsonl
new file mode 100644
index 000000000..c1b287771
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-cli-packaging-start-command-polish/debug.jsonl
@@ -0,0 +1,2 @@
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-19-cli-packaging-start-command-polish/implement.jsonl b/.trellis/tasks/archive/2026-04/04-19-cli-packaging-start-command-polish/implement.jsonl
new file mode 100644
index 000000000..7e838d159
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-cli-packaging-start-command-polish/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": ".trellis/spec/frontend/index.md", "reason": "Frontend development guide"}
+{"file": ".trellis/spec/frontend/directory-structure.md", "reason": "CLI package and bridge ownership."}
+{"file": ".trellis/spec/frontend/quality-guidelines.md", "reason": "Frontend CLI validation expectations."}
+{"file": ".trellis/spec/backend/directory-structure.md", "reason": "Python CLI is composition shell, not product logic."}
diff --git a/.trellis/tasks/archive/2026-04/04-19-cli-packaging-start-command-polish/prd.md b/.trellis/tasks/archive/2026-04/04-19-cli-packaging-start-command-polish/prd.md
new file mode 100644
index 000000000..38d389ae4
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-cli-packaging-start-command-polish/prd.md
@@ -0,0 +1,72 @@
+# CLI packaging start command polish
+
+## Goal
+
+让已经具备 streaming + HITL 的 React/Ink CLI 能通过一个明确、可测试、可文档化的产品命令启动，而不是要求用户记住 Node package 目录、`PYTHONPATH` 或开发脚本细节。
+
+## Acceptance Targets
+
+* 有一个产品级启动命令可以直接启动 CLI 前端。
+* 命令支持 fake/demo 模式，便于无模型 key 快速验证。
+* Python CLI 启动逻辑对缺失 frontend package / npm install 给出清晰错误。
+* 测试覆盖新命令参数和启动脚本选择。
+* 不引入 Web/HTML 实现，不改变 runtime event protocol。
+
+## Planned Features
+
+* 增加独立 console script 或更清晰的 Python CLI 子命令别名。
+* 保留现有 `coding-deepgent ui` 入口。
+* 补充 README/usage 中的启动命令说明。
+* 补 CLI tests，证明 fake/real 启动参数和 cwd/env 行为稳定。
+
+## Planned Extensions
+
+* 打成真正 npm/pip 组合发布包。
+* 预检并自动提示 `npm install` / `npm ci`。
+* Web/SSE gateway product packaging。
+
+## Requirements
+
+* 范围只覆盖 `coding-deepgent/` 产品主线。
+* 不让 TS frontend 直接承担 Python runtime 配置。
+* 不把 root `web/` 或 tutorial assets 引入产品启动路径。
+* 不改变 JSONL bridge protocol。
+
+## Acceptance Criteria
+
+* [x] 产品级 CLI 启动命令存在并可测试。
+* [x] fake mode smoke 能通过新命令或等价路径验证。
+* [x] `coding-deepgent ui` 旧入口继续工作。
+* [x] focused Python CLI tests、TS tests/typecheck 通过。
+
+## Technical Notes
+
+Likely files:
+
+* `coding-deepgent/pyproject.toml`
+* `coding-deepgent/src/coding_deepgent/cli.py`
+* `coding-deepgent/frontend/cli/package.json`
+* `coding-deepgent/tests/cli/test_cli.py`
+* `coding-deepgent/README.md`
+
+## Resolution (2026-04-19)
+
+Implemented a repo-local product shortcut:
+
+* Added Python console script `coding-deepgent-ui = coding_deepgent.cli:ui_cli`.
+* `coding-deepgent-ui --fake` now routes to the same React/Ink CLI path as
+  `coding-deepgent ui --fake`.
+* Preserved `coding-deepgent ui` as the canonical grouped Typer command.
+* Added clearer startup errors for missing frontend package metadata, missing
+  `node_modules`, and missing `npm`.
+* Updated README usage to make `coding-deepgent-ui` the quick product command
+  while keeping npm dev scripts documented for development.
+
+## Verification (2026-04-19)
+
+* `pytest -q tests/cli/test_cli.py` -> `32 passed`
+* `ruff check src/coding_deepgent/cli.py tests/cli/test_cli.py` -> passed
+* `mypy src/coding_deepgent/cli.py` -> passed
+* `npm --prefix coding-deepgent/frontend/cli run typecheck` -> passed
+* `npm --prefix coding-deepgent/frontend/cli test` -> `8 passed`
+* `PYTHONPATH=src python3 - <<'PY' ... ui_cli(['--help']) ... PY` -> printed the `coding-deepgent ui` help
diff --git a/.trellis/tasks/archive/2026-04/04-19-cli-packaging-start-command-polish/task.json b/.trellis/tasks/archive/2026-04/04-19-cli-packaging-start-command-polish/task.json
new file mode 100644
index 000000000..0bf0b4e02
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-cli-packaging-start-command-polish/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "cli-packaging-start-command-polish",
+  "name": "cli-packaging-start-command-polish",
+  "title": "CLI packaging start command polish",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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/archive/2026-04/04-19-cli-permission-hitl-boundary/check.jsonl b/.trellis/tasks/archive/2026-04/04-19-cli-permission-hitl-boundary/check.jsonl
new file mode 100644
index 000000000..89e819f4c
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-cli-permission-hitl-boundary/check.jsonl
@@ -0,0 +1,6 @@
+{"file": ".gemini/commands/trellis/finish-work.toml", "reason": "Finish work checklist"}
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
+{"file": ".trellis/spec/backend/langchain-native-guidelines.md", "reason": "Review that HITL uses interrupt/checkpointer instead of custom runtime loops."}
+{"file": ".trellis/spec/backend/project-infrastructure-foundation-contracts.md", "reason": "Review thread_id/checkpointer ownership and same-process durability boundary."}
+{"file": ".trellis/spec/frontend/type-safety.md", "reason": "Review Python/TS protocol parity."}
diff --git a/.trellis/tasks/archive/2026-04/04-19-cli-permission-hitl-boundary/debug.jsonl b/.trellis/tasks/archive/2026-04/04-19-cli-permission-hitl-boundary/debug.jsonl
new file mode 100644
index 000000000..c1b287771
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-cli-permission-hitl-boundary/debug.jsonl
@@ -0,0 +1,2 @@
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-19-cli-permission-hitl-boundary/implement.jsonl b/.trellis/tasks/archive/2026-04/04-19-cli-permission-hitl-boundary/implement.jsonl
new file mode 100644
index 000000000..40588dcb7
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-cli-permission-hitl-boundary/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": ".trellis/spec/frontend/index.md", "reason": "Frontend development guide"}
+{"file": ".trellis/spec/backend/langchain-native-guidelines.md", "reason": "Interrupt/resume must stay LangGraph-native."}
+{"file": ".trellis/spec/backend/project-infrastructure-foundation-contracts.md", "reason": "HITL touches runtime invocation, thread_id, and checkpointer boundary."}
+{"file": ".trellis/spec/backend/error-handling.md", "reason": "Reject path must remain bounded and frontend-safe."}
+{"file": ".trellis/spec/frontend/type-safety.md", "reason": "Protocol changes require dual-side contract sync."}
+{"file": ".trellis/spec/frontend/quality-guidelines.md", "reason": "Bridge/protocol changes need focused Python and TS validation."}
diff --git a/.trellis/tasks/archive/2026-04/04-19-cli-permission-hitl-boundary/prd.md b/.trellis/tasks/archive/2026-04/04-19-cli-permission-hitl-boundary/prd.md
new file mode 100644
index 000000000..26b4daf74
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-cli-permission-hitl-boundary/prd.md
@@ -0,0 +1,121 @@
+# CLI permission HITL boundary
+
+## Goal
+
+把 `coding-deepgent` CLI/frontend 里的 permission `ask` 从“返回错误文本给模型和 UI”升级为真实的 human-in-the-loop pause/resume：运行在需要审批时暂停，frontend 收到待审批事件，用户决策后通过同一 LangGraph thread 恢复执行。
+
+## Acceptance Targets
+
+* destructive / approval-required tool calls不再直接在 frontend 中表现为最终 `ToolMessage(status="error")`，而是先暂停并发出 `permission_requested`
+* frontend `permission_decision` 会通过 `Command(resume=...)` 恢复同一 run / thread
+* 用户批准后，原 tool call 继续执行并最终完成当前 assistant turn
+* 用户拒绝后，工具以 bounded error surface 返回，agent 继续/结束当前 turn，但不崩溃
+* 真实 HITL 仅依赖 LangGraph interrupt/checkpointer seam，不引入自定义 query loop
+* 当前实现边界显式限定为 frontend/CLI surface 的进程内 `memory` checkpointer；不宣称跨进程 durable resume
+
+## Planned Features
+
+* 在 permission `ask` 分支引入 LangGraph `interrupt()`
+* 在 frontend producer/bridge 中识别 `__interrupt__` 并映射为 `permission_requested`
+* 为 `permission_decision` 增加真实 resume path，使用 `Command(resume=...)`
+* 在 frontend default runner 为 HITL surface 启用进程内 `memory` checkpointer
+* 为 approve/reject/resume ordering、多 pending interrupt id map、fallback/non-HITL 行为补 focused tests
+
+## Planned Extensions
+
+* edit-tool-call style HITL
+* cross-process durable HITL resume
+* browser Web HITL cards / richer approval UI
+* packaging/product command polish
+
+## Requirements
+
+* 保持 `coding-deepgent` backend runtime LangChain/LangGraph-native，不引入自定义 executor loop
+* 不绕过现有 `ToolCapability` / `ToolPolicy` / `ToolGuardMiddleware` 权限语义
+* protocol 变更必须双端同步：Python models、TS protocol、reducer/tests
+* permission request id 必须能稳定映射到 LangGraph interrupt resume
+* 默认 CLI/Typer 非 frontend surface 不需要同时支持 HITL；当前范围只覆盖 frontend bridge/client/gateway
+* 若实现中发现必须依赖 durable external checkpointer 才能成立，应记录 blocker 并停止，不做假 pause/resume
+
+## Acceptance Criteria
+
+* [x] `ToolGuardMiddleware` 的 `ask` 分支触发可恢复 interrupt，而不是直接返回最终错误
+* [x] frontend bridge 能把 interrupt 转成 `permission_requested`
+* [x] `permission_decision` 能恢复同一 thread，并继续产出后续 tool/assistant events
+* [x] reject 路径保持 bounded error，不破坏当前 run
+* [x] frontend surface 自动具备满足 interrupt 的进程内 checkpointer
+* [x] focused Python tests、TS tests、typecheck、至少一个 CLI/frontend smoke 通过
+
+## Code-Spec Depth Check
+
+Target contracts to update or verify:
+
+* `.trellis/spec/backend/langchain-native-guidelines.md`
+* `.trellis/spec/backend/project-infrastructure-foundation-contracts.md`
+* `.trellis/spec/backend/error-handling.md`
+* `.trellis/spec/frontend/type-safety.md`
+* `.trellis/spec/frontend/quality-guidelines.md`
+
+Concrete contract to define:
+
+* `permission_requested.request_id` must map to LangGraph interrupt ids
+* `permission_decision` resumes the same `thread_id`
+* frontend HITL uses `memory` checkpointer only for same-process pause/resume
+* reject path returns bounded tool-visible failure instead of crashing the run
+
+Validation matrix to prove:
+
+* Good: approval pauses, resumes, and tool completes
+* Base: rejection resumes and returns bounded error
+* Bad: unknown/mismatched request id does not corrupt session state or silently approve
+
+## Technical Notes
+
+Likely code surfaces:
+
+* `coding-deepgent/src/coding_deepgent/tool_system/middleware.py`
+* `coding-deepgent/src/coding_deepgent/frontend/producer.py`
+* `coding-deepgent/src/coding_deepgent/frontend/protocol.py`
+* `coding-deepgent/src/coding_deepgent/frontend/client.py`
+* `coding-deepgent/src/coding_deepgent/frontend/runs.py`
+* `coding-deepgent/src/coding_deepgent/frontend/gateway.py`
+* `coding-deepgent/frontend/cli/src/bridge/protocol.ts`
+* `coding-deepgent/frontend/cli/src/bridge/reducer.ts`
+
+Out of scope:
+
+* generic non-frontend CLI `run` command HITL
+* Web product UI
+* durable external checkpoint persistence
+
+## Resolution (2026-04-19)
+
+Implemented a bounded frontend-only HITL permission seam without replacing the
+existing LangChain/LangGraph runtime shape:
+
+* `ToolGuardMiddleware` now uses LangGraph `interrupt()` for
+  `permission_required` decisions only when the runtime entrypoint is a frontend
+  HITL surface.
+* frontend bridge sessions now preserve pending permission requests and resume
+  them through `Command(resume=...)` on the same LangGraph thread.
+* JSONL bridge and embedded `FrontendClient` now build shared prompt/resume
+  runners for HITL mode.
+* frontend HITL surfaces automatically switch from `checkpointer_backend=none`
+  to in-process `memory` only for the frontend runtime builder; the global
+  product default remains unchanged.
+* FastAPI run service / gateway was intentionally left on the old non-HITL path
+  because it still lacks a resume endpoint and should not silently claim true
+  approval workflows yet.
+
+## Verification (2026-04-19)
+
+* `python3 -m py_compile ...` on touched frontend/tool-system modules -> passed
+* `pytest -q tests/frontend/test_frontend_bridge.py tests/tool_system/test_tool_system_middleware.py` -> `23 passed`
+* `pytest -q tests/frontend/test_frontend_bridge.py tests/frontend/test_frontend_protocol.py tests/frontend/test_frontend_runs.py tests/frontend/test_frontend_client.py tests/frontend/test_frontend_gateway.py tests/frontend/test_stream_bridge.py tests/tool_system/test_tool_system_middleware.py` -> `36 passed`
+* `npm --prefix coding-deepgent/frontend/cli test` -> `8 passed`
+* `npm --prefix coding-deepgent/frontend/cli run typecheck` -> passed
+* `ruff check src/coding_deepgent/frontend src/coding_deepgent/tool_system/middleware.py tests/frontend/test_frontend_bridge.py tests/tool_system/test_tool_system_middleware.py` -> passed
+* `mypy src/coding_deepgent/frontend src/coding_deepgent/tool_system/middleware.py` -> passed
+* manual fake frontend smoke with dynamic request id:
+  * first run emitted `session_started`, `user_message`, `permission_requested`
+  * resume run emitted `permission_resolved`, tool/assistant events, and final `run_finished`
diff --git a/.trellis/tasks/archive/2026-04/04-19-cli-permission-hitl-boundary/task.json b/.trellis/tasks/archive/2026-04/04-19-cli-permission-hitl-boundary/task.json
new file mode 100644
index 000000000..2b7475457
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-cli-permission-hitl-boundary/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "cli-permission-hitl-boundary",
+  "name": "cli-permission-hitl-boundary",
+  "title": "CLI permission HITL boundary",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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/archive/2026-04/04-19-cli-real-streaming-bridge/prd.md b/.trellis/tasks/archive/2026-04/04-19-cli-real-streaming-bridge/prd.md
new file mode 100644
index 000000000..1a0ff8c63
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-cli-real-streaming-bridge/prd.md
@@ -0,0 +1,112 @@
+# CLI real streaming bridge
+
+## Goal
+
+让 `coding-deepgent` 的 React/Ink CLI 从当前“等待 `run_once` 完成后一次性回放结果”升级为真实流式桥接：assistant 文本按增量流入，现有 runtime/tool/progress 事件在执行中实时显示。
+
+## Acceptance Targets
+
+* `coding-deepgent ui` 在真实后端路径下通过 `assistant_delta` 增量显示 assistant 文本。
+* 现有 `runtime_event`、`tool_call`、`tool_result`、`todo_snapshot` 等桥接事件在运行中保持有序并继续可消费。
+* `assistant_delta` 与最终 `assistant_message` 共享稳定 `message_id`。
+* 非流式路径仅作为显式 fallback 或测试路径存在，不再是默认真实桥接行为。
+* Python 和 TypeScript 协议/测试同步更新。
+
+## Planned Features
+
+* 在 Python frontend bridge 中增加真实 streaming prompt runner。
+* 将 LangChain/LangGraph stream parts 映射到现有 `FrontendEvent` 联合类型。
+* 保持 fake bridge 可重放、可测试。
+* 更新 TS reducer 以正确处理 interleaved `assistant_delta` / final message / tool events。
+* 为事件顺序、message_id 连贯性和 fallback 行为补 focused tests。
+
+## Planned Extensions
+
+* true HITL permission pause/resume
+* Web/SSE transport
+* richer tool-specific renderers
+* transcript search / slash commands / command palette
+
+## Requirements
+
+* 保持改动范围在 `coding-deepgent/src/coding_deepgent/frontend/*`、CLI bridge/protocol/reducer，以及必要的 runtime invocation seam。
+* 不引入独立自定义 query loop；优先使用 LangChain/LangGraph 官方 streaming surface。
+* 不让 React 组件直接读取 subprocess stdout；桥接仍通过 typed protocol 进入 reducer。
+* 协议字段必须严格、双端一致，不能在 Python/TS 两侧出现不同步事件定义。
+* 若真实 streaming seam 暴露明确 blocker，必须记录边界并保留 deterministic fake mode。
+
+## Acceptance Criteria
+
+* [x] Python bridge 在真实路径下发出 `assistant_delta` 增量事件。
+* [x] 最终 `assistant_message` 与先前增量使用同一 `message_id`。
+* [x] TS reducer 正确聚合增量文本并在最终消息到达后保持稳定显示。
+* [x] 现有 fake mode 和 non-streaming fallback 仍通过 focused tests。
+* [x] Focused Python tests、TS tests、typecheck、smoke checks 通过。
+
+## Code-Spec Depth Check
+
+Target contracts to update or verify:
+
+* `.trellis/spec/frontend/type-safety.md`
+* `.trellis/spec/frontend/quality-guidelines.md`
+* `.trellis/spec/backend/langchain-native-guidelines.md`
+
+Concrete contract to define:
+
+* `assistant_delta` / `assistant_message` ordering and shared `message_id`
+* real-stream vs fallback runner selection boundary
+* error surfacing when streaming setup fails
+
+Validation matrix to prove:
+
+* Good: streaming assistant text arrives incrementally and finalizes correctly
+* Base: fake mode and explicit fallback path still render a complete assistant response
+* Bad: invalid or out-of-order delta/final payload does not corrupt reducer state
+
+## Technical Notes
+
+Probable code surfaces:
+
+* `coding-deepgent/src/coding_deepgent/frontend/bridge.py`
+* `coding-deepgent/src/coding_deepgent/frontend/protocol.py`
+* `coding-deepgent/src/coding_deepgent/frontend/event_mapping.py`
+* `coding-deepgent/frontend/cli/src/bridge/protocol.ts`
+* `coding-deepgent/frontend/cli/src/bridge/reducer.ts`
+* `coding-deepgent/frontend/cli/src/app.tsx`
+
+Out of scope for this task:
+
+* true permission pause/resume
+* HTML/Web UI
+* new CLI feature family beyond the existing event surface
+
+## Resolution (2026-04-19)
+
+This task did not require new product-code implementation. Focused code
+research plus validation confirmed the real streaming bridge is already present
+in the current mainline:
+
+* `coding-deepgent/src/coding_deepgent/frontend/producer.py`
+  * `build_default_prompt_runner()` already prefers `_run_streaming_prompt()`
+    by default and keeps an explicit non-streaming fallback.
+  * `_run_streaming_prompt()` already maps LangChain/LangGraph stream parts into
+    `assistant_delta`, tool, and runtime events while preserving a final
+    `assistant_message`.
+* `coding-deepgent/src/coding_deepgent/frontend/protocol.py`
+  and `coding-deepgent/frontend/cli/src/bridge/protocol.ts`
+  already define `assistant_delta` / `assistant_message` with shared
+  `message_id`.
+* `coding-deepgent/frontend/cli/src/bridge/reducer.ts`
+  already aggregates streaming deltas into a stable assistant message.
+
+## Verification (2026-04-19)
+
+* `pytest -q tests/frontend/test_frontend_bridge.py tests/frontend/test_frontend_protocol.py tests/frontend/test_frontend_runs.py tests/frontend/test_frontend_client.py tests/frontend/test_frontend_gateway.py tests/frontend/test_stream_bridge.py`
+  -> `19 passed`
+* `npm --prefix coding-deepgent/frontend/cli test`
+  -> `8 passed`
+* `npm --prefix coding-deepgent/frontend/cli run typecheck`
+  -> passed
+* fake JSONL bridge smoke via `python3 -m coding_deepgent ui-bridge --fake`
+  showed ordered `assistant_delta` events followed by final
+  `assistant_message` with the same `message_id`
diff --git a/.trellis/tasks/archive/2026-04/04-19-cli-real-streaming-bridge/task.json b/.trellis/tasks/archive/2026-04/04-19-cli-real-streaming-bridge/task.json
new file mode 100644
index 000000000..8057c5655
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-cli-real-streaming-bridge/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "cli-real-streaming-bridge",
+  "name": "cli-real-streaming-bridge",
+  "title": "CLI real streaming bridge",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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/archive/2026-04/04-19-deerflow-inspired-decoupling/check.jsonl b/.trellis/tasks/archive/2026-04/04-19-deerflow-inspired-decoupling/check.jsonl
new file mode 100644
index 000000000..1422d008e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-deerflow-inspired-decoupling/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": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-19-deerflow-inspired-decoupling/debug.jsonl b/.trellis/tasks/archive/2026-04/04-19-deerflow-inspired-decoupling/debug.jsonl
new file mode 100644
index 000000000..c1b287771
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-deerflow-inspired-decoupling/debug.jsonl
@@ -0,0 +1,2 @@
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-19-deerflow-inspired-decoupling/implement.jsonl b/.trellis/tasks/archive/2026-04/04-19-deerflow-inspired-decoupling/implement.jsonl
new file mode 100644
index 000000000..767ffb5a5
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-deerflow-inspired-decoupling/implement.jsonl
@@ -0,0 +1,7 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": ".trellis/spec/frontend/index.md", "reason": "Frontend development guide"}
+{"file": ".trellis/spec/frontend/directory-structure.md", "reason": "Frontend CLI package and protocol layout"}
+{"file": ".trellis/spec/backend/directory-structure.md", "reason": "Backend domain ownership and adapter boundary"}
+{"file": ".trellis/spec/frontend/type-safety.md", "reason": "Protocol type sync"}
+{"file": ".trellis/spec/guides/architecture-posture-guide.md", "reason": "Clean producer adapter architecture"}
diff --git a/.trellis/tasks/archive/2026-04/04-19-deerflow-inspired-decoupling/prd.md b/.trellis/tasks/archive/2026-04/04-19-deerflow-inspired-decoupling/prd.md
new file mode 100644
index 000000000..ce34c826f
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-deerflow-inspired-decoupling/prd.md
@@ -0,0 +1,440 @@
+# brainstorm: deerflow-inspired cli web decoupling
+
+## Goal
+
+借鉴 DeerFlow 的 Harness/App/Gateway/Client/Web 分层，重新规划 `coding-deepgent` 的 CLI 与未来 HTML/Web 解耦方式：保留当前 React/Ink CLI 成果，同时建立可扩展到 Web/SSE 的 backend runtime/event 架构，避免 Web 复用 CLI 进程或解析 terminal output。
+
+## What I already know
+
+* 用户要求“规划仿 deerflow 优化”。
+* 已源码研究 `bytedance/deer-flow`，包括：
+  * `backend/docs/STREAMING.md`
+  * `backend/docs/HARNESS_APP_SPLIT.md`
+  * `backend/packages/harness/deerflow/client.py`
+  * `backend/packages/harness/deerflow/runtime/runs/worker.py`
+  * `backend/packages/harness/deerflow/runtime/stream_bridge/*`
+  * `backend/app/gateway/services.py`
+  * `backend/app/gateway/routers/thread_runs.py`
+  * `frontend/src/core/threads/hooks.ts`
+  * `frontend/src/core/api/stream-mode.ts`
+* DeerFlow 的核心不是“CLI/Web 共用 UI”，而是：
+  * Harness/runtime 共享
+  * Web 走 Gateway/SSE/SDK
+  * Embedded client 走 in-process stream
+  * 不同 transport 相似但不强行合并
+* 当前 `coding-deepgent` 已有：
+  * Python runtime/domain packages under `coding-deepgent/src/coding_deepgent`
+  * React/Ink CLI under `coding-deepgent/frontend/cli`
+  * Python JSONL bridge under `coding_deepgent.frontend`
+  * Protocol types/events for CLI
+  * Typer CLI fallback commands
+* 当前 `web/` 仍是 reference/tutorial layer，不是 product Web。
+* 当前 worktree 有大量其它脏改，规划不应假设能直接提交。
+
+## Assumptions (temporary)
+
+* `coding-deepgent` 不需要像 DeerFlow 一样立刻物理拆成 publishable harness package，但需要先形成同等边界。
+* CLI 和未来 Web 应该共享 runtime/event producer，不共享 transport。
+* 当前 JSONL protocol 可以作为 CLI transport v1，但 Web 不应该复用 stdio bridge。
+* Web 启动前应先补一个 Gateway/SSE adapter 或至少明确 HTTP stream contract。
+
+## Open Questions
+
+* 是否采用“先抽 runtime stream producer + adapters”作为下一阶段架构主线？
+
+## Requirements (evolving)
+
+* 不让 Web 依赖 React/Ink CLI。
+* 不让 runtime/domain 层 import CLI/Web/Gateway。
+* 保留当前 `coding-deepgent ui` / `ui-bridge` CLI 成果。
+* 建立 DeerFlow 风格的多 consumer 模型：
+  * CLI: stdio JSONL adapter
+  * Web: future SSE/HTTP adapter
+  * tests/scripts: in-process/embedded adapter
+* Streaming mode 命名必须按协议层显式翻译，不用一个常量假装所有层相同。
+* HITL/permission 不应伪造；没有安全 pause/resume seam 前只能声明 UI/protocol ready。
+
+## Acceptance Criteria (evolving)
+
+* [x] 明确 DeerFlow 架构模式如何映射到 `coding-deepgent`。
+* [x] 明确目标目录/模块边界。
+* [x] 明确 staged implementation plan。
+* [x] 明确哪些现在做、哪些留给 Web/HTML 阶段。
+* [x] 形成一个可以进入 Task Workflow 的计划。
+
+## Definition of Done
+
+* Planning doc is source-backed.
+* Acceptance targets, planned features, planned extensions are explicit.
+* Risks and stop conditions are recorded.
+* No code implementation in this brainstorm.
+
+## Out of Scope
+
+* 本 brainstorm 不实现代码。
+* 不直接引入 DeerFlow 代码。
+* 不启动 HTML/Web 实现。
+* 不把 `coding-deepgent` 物理拆包为 publishable package，除非后续单独批准。
+
+## Research Notes
+
+### DeerFlow patterns to reuse
+
+**1. Harness/App split**
+
+DeerFlow 将可复用 agent 能力放在 `backend/packages/harness/deerflow`，把 FastAPI Gateway 和 channels 放在 `backend/app`。规则是 App imports Harness，Harness never imports App。
+
+映射到 `coding-deepgent`：
+
+* `coding_deepgent.runtime`, `tool_system`, `sessions`, `memory`, `tasks`, `subagents`, `compact`, `permissions` 是 harness-like domain/runtime。
+* `coding_deepgent.frontend` 当前混合了 protocol、JSONL bridge、runner adapter，后续应拆成更明确的 producer/adapters。
+* 未来 `coding_deepgent.gateway` 或 `coding_deepgent.api` 应是 App/Gateway-like adapter，不应被 runtime import。
+
+**2. Parallel stream paths are acceptable**
+
+DeerFlow 明确保留两条流式路径：
+
+* Gateway path: async `agent.astream` -> `StreamBridge` -> SSE.
+* Embedded client path: sync `agent.stream` -> direct generator.
+
+它没有强行复用，因为消费者模型不同。
+
+映射到 `coding-deepgent`：
+
+* CLI path: sync/process stdio JSONL is acceptable.
+* Web path: async SSE/HTTP should be separate.
+* Embedded/test path: direct in-process event generator is useful for tests and future scripting.
+
+**3. Stream modes are protocol-layer translations**
+
+DeerFlow 区分：
+
+* Graph Python API: `messages`
+* HTTP/LangGraph SDK: `messages-tuple`
+* App/frontend event: consumers decide display semantics
+
+映射到 `coding-deepgent`：
+
+* Internal LangChain mode: `messages`
+* Our runtime event: `assistant_delta`
+* Future Web SSE event: either `frontend_event` with JSON payload or LangGraph-compatible `messages`/`values`
+* Do not force one shared string constant across layers.
+
+**4. StreamBridge belongs at network boundary**
+
+DeerFlow uses `StreamBridge` for HTTP consumers because producer and consumer are different async tasks/connections, with heartbeat, replay, cleanup, and disconnect semantics.
+
+映射到 `coding-deepgent`:
+
+* Current CLI stdio does not need full `StreamBridge`.
+* Future Web/SSE does need `RunManager` + `StreamBridge` or equivalent.
+* Do not prematurely make CLI depend on HTTP Gateway.
+
+**5. Frontend consumes a stable client API**
+
+DeerFlow Web uses `@langchain/langgraph-sdk/react` `useStream`, not custom terminal protocol. It handles optimistic messages, thread/run metadata, reconnection, custom events, and finish callbacks.
+
+映射到 `coding-deepgent`:
+
+* Future Web can either consume LangGraph-compatible API or a simpler `FrontendEvent` SSE.
+* If long-term Web matters, aim for LangGraph-compatible semantics where practical.
+
+## Constraints From This Repo
+
+* Current mainline is `coding-deepgent/`.
+* `web/` is reference-only unless explicitly promoted.
+* Current frontend CLI is in `coding-deepgent/frontend/cli`.
+* Python protocol/bridge is in `coding_deepgent.frontend`.
+* Backend specs require domain ownership and no business logic in `cli.py`, `app.py`, `containers`.
+* Architecture guide prefers clean long-term boundaries over minimal compatibility shims.
+
+## Feasible Approaches
+
+### Approach A: Stream Producer + Adapter Split (Recommended)
+
+How:
+
+* Refactor `coding_deepgent.frontend` into:
+  * `protocol.py`: renderer-neutral events/inputs
+  * `producer.py`: in-process runtime event generator
+  * `adapters/jsonl.py`: CLI stdio adapter
+  * `adapters/sse.py` or future `gateway/*`: Web/SSE adapter
+  * `runs.py`: optional RunManager/StreamBridge only when HTTP begins
+* Current React/Ink CLI keeps using JSONL adapter.
+* Future Web uses SSE adapter over the same producer/events.
+
+Pros:
+
+* Closest to DeerFlow principle without heavy physical package split.
+* Preserves current CLI.
+* Gives Web a clean start.
+* Avoids runtime importing UI.
+
+Cons:
+
+* Some refactor before visible Web work.
+* Need careful tests to avoid breaking current CLI.
+
+### Approach B: Full DeerFlow-Style Gateway First
+
+How:
+
+* Add FastAPI Gateway now.
+* Add RunManager + StreamBridge + SSE.
+* Point Web and possibly CLI to Gateway.
+
+Pros:
+
+* Web-ready immediately.
+* Strong network boundary.
+
+Cons:
+
+* Bigger dependency/surface jump.
+* CLI does not need HTTP; forcing CLI through Gateway adds complexity.
+* Premature before Web is implemented.
+
+### Approach C: Physical Harness/App Package Split
+
+How:
+
+* Move reusable runtime into a harness package.
+* Move CLI/Gateway/Web adapters into app packages.
+
+Pros:
+
+* Cleanest long-term library boundary.
+* Strong alignment with DeerFlow.
+
+Cons:
+
+* High risk with current dirty worktree and active runtime refactors.
+* Large import churn.
+* Not necessary before Web.
+
+### Approach D: Keep Current JSONL Bridge And Start Web Directly
+
+How:
+
+* Build Web around current bridge/protocol quickly.
+
+Pros:
+
+* Fastest visible browser demo.
+
+Cons:
+
+* Web may accidentally depend on CLI/studio assumptions.
+* No RunManager/disconnect/replay semantics.
+* Likely rework.
+
+## Recommended Direction
+
+Choose **Approach A: Stream Producer + Adapter Split**.
+
+This gives us DeerFlow's useful boundary without copying its full infra prematurely.
+
+## Acceptance Targets
+
+* Runtime/domain code does not import CLI/Web/Gateway adapters.
+* A shared in-process stream producer exists and can drive both current JSONL CLI and future SSE adapter.
+* Current `coding-deepgent ui` and `ui-bridge` keep working.
+* Protocol naming and stream-mode translations are documented.
+* Tests prove producer -> JSONL adapter behavior without React/Ink.
+* Future Web can be implemented as a new adapter, not by wrapping CLI.
+
+## Planned Features
+
+* Split `coding_deepgent.frontend.bridge` into producer + JSONL adapter responsibilities.
+* Define `FrontendEvent` as the stable renderer-neutral event contract.
+* Add an embedded/in-process client helper for tests/scripts.
+* Introduce adapter naming:
+  * `jsonl` for CLI
+  * `sse` for future Web
+  * `embedded` for direct Python use/tests
+* Document protocol-layer translation:
+  * LangChain `messages` -> `assistant_delta`
+  * LangChain `updates`/runtime events -> `tool_*`/`runtime_event`
+  * future SSE `frontend_event` or LangGraph-compatible mode names
+* Add tests guarding no reverse imports from runtime to frontend adapters.
+
+## Planned Extensions
+
+* FastAPI Gateway/SSE adapter.
+* RunManager + StreamBridge with heartbeat/replay/disconnect.
+* Browser Web app.
+* LangGraph SDK-compatible API surface.
+* Persistent HITL checkpoint/resume.
+* Physical harness package split if the project later needs published embedded library usage.
+
+## Expansion Sweep
+
+### Future evolution
+
+* In 1-3 months, the same producer can drive CLI, Web, IM channels, and Python scripts.
+* A Gateway can be added without changing CLI internals.
+
+### Related scenarios
+
+* `coding-deepgent ui` stays a local CLI adapter.
+* Future `coding-deepgent serve` or `coding-deepgent gateway` becomes Web adapter.
+* Existing Typer commands remain backend/debug fallbacks.
+
+### Failure and edge cases
+
+* If producer owns too much transport behavior, Web and CLI coupling returns.
+* If adapter owns runtime state, session consistency breaks.
+* If stream-mode translations are hidden behind shared constants, protocol confusion increases.
+* If Web starts before adapter split, it may depend on JSONL/stdio assumptions.
+
+## Proposed Stage Plan
+
+### Stage 1: Boundary Spec And Import Guard
+
+* Update Trellis backend/frontend specs with producer/adapter layering.
+* Add import guard test:
+  * runtime/domain packages must not import `frontend.adapters`, `frontend.cli`, or future `gateway`.
+
+### Stage 2: Extract Producer
+
+* Move runtime stream generation from `frontend.bridge` into `frontend.producer`.
+* Producer exposes in-process iterator/generator of `FrontendEvent`.
+* Keep `bridge.py` as JSONL adapter wrapper for compatibility.
+
+### Stage 3: Embedded Client
+
+* Add `frontend.client` or `runtime.client` for direct Python scripted use.
+* It should call producer directly and return events, similar to DeerFlowClient but scoped to frontend events.
+
+### Stage 4: JSONL Adapter Hardening
+
+* Rename/organize current bridge as `adapters/jsonl.py`.
+* Keep `coding-deepgent ui-bridge` command behavior unchanged.
+* Tests verify event order unchanged.
+
+### Stage 5: Gateway/SSE Design Prep
+
+* Add docs/interfaces for future `RunManager` and `StreamBridge`.
+* Do not implement server yet unless user explicitly starts HTML/Web.
+
+### Stage 6: Web Readiness Checkpoint
+
+* Confirm Web can start by implementing only a new adapter.
+* Record remaining decisions:
+  * LangGraph SDK compatibility vs custom `FrontendEvent` SSE.
+  * Auth/trust model.
+  * thread/run persistence.
+
+## Decision (ADR-lite)
+
+**Context**: CLI is now implemented with JSONL bridge. User wants future HTML/Web, and DeerFlow shows a clean separation between reusable harness/runtime and app-specific transport/UI adapters.
+
+**Decision**: Do not make Web reuse CLI. Refactor toward a shared runtime stream producer with separate adapters: JSONL for CLI, SSE/Gateway for Web, embedded for scripts/tests.
+
+**Consequences**: Web starts slightly later, but avoids rework and preserves a clean long-term boundary.
+
+## One Question
+
+是否按推荐的 **Approach A: Stream Producer + Adapter Split** 作为下一阶段架构优化方向？
+
+1. **Yes, do producer/adapter split first** — 推荐；先把 DeerFlow 式边界打稳，再做 Web。
+2. **Go straight to Gateway/SSE** — 更快进入 Web 后端，但范围更大。
+3. **Go straight to Web UI** — 最快看到浏览器，但后续重构风险最高。
+
+## Implementation Checkpoint: Producer / Adapter Split
+
+State:
+
+* terminal
+
+Verdict:
+
+* APPROVE
+
+Implemented:
+
+* Added `coding_deepgent.frontend.producer` as the renderer-neutral runtime event producer.
+* Added `coding_deepgent.frontend.adapters.jsonl` as the stdio JSONL transport adapter.
+* Added `coding_deepgent.frontend.client.FrontendClient` as an embedded in-process consumer of `FrontendEvent`.
+* Converted `coding_deepgent.frontend.bridge` into a backward-compatible import shim.
+* Preserved existing `ui-bridge` behavior and tests through compatibility imports.
+* Added an import guard to ensure runtime/domain code does not import frontend transport adapters.
+* Updated backend/frontend specs and protocol docs with the producer/adapter boundary.
+
+Verification:
+
+* `pytest -q tests/frontend/test_frontend_client.py tests/frontend/test_frontend_protocol.py tests/frontend/test_frontend_bridge.py tests/frontend/test_frontend_event_mapping.py tests/structure/test_structure.py` -> 19 passed.
+* `ruff check src/coding_deepgent/frontend tests/frontend/test_frontend_client.py tests/frontend/test_frontend_bridge.py tests/structure/test_structure.py` -> passed.
+* `mypy src/coding_deepgent/frontend` -> passed.
+* `npm --prefix coding-deepgent/frontend/cli run typecheck` -> passed.
+* `npm --prefix coding-deepgent/frontend/cli test` -> passed.
+* `PYTHONPATH=src python3 -m coding_deepgent ui-bridge --fake` JSONL smoke -> passed.
+
+## Implementation Checkpoint: RunManager / StreamBridge / SSE Foundation
+
+State:
+
+* terminal
+
+Verdict:
+
+* APPROVE
+
+Implemented:
+
+* Added `coding_deepgent.frontend.stream_bridge.MemoryStreamBridge` with replayable per-run event logs and heartbeat/end sentinels.
+* Added `coding_deepgent.frontend.runs.FrontendRunManager`, `RunRecord`, and `FrontendRunService` for background run lifecycle.
+* Added `coding_deepgent.frontend.adapters.sse` with `format_sse` and `sse_consumer`.
+* Reused existing `frontend.producer.BridgeSession` as the worker-side runtime event source.
+* Preserved current CLI transport; no CLI-to-HTTP migration was introduced.
+* Updated package exports and docs/specs for the new web foundation layers.
+
+Verification:
+
+* `pytest -q tests/frontend/test_stream_bridge.py tests/frontend/test_frontend_runs.py tests/frontend/test_frontend_sse.py tests/frontend/test_frontend_client.py tests/frontend/test_frontend_protocol.py tests/frontend/test_frontend_bridge.py tests/frontend/test_frontend_event_mapping.py tests/structure/test_structure.py` -> 24 passed.
+* `ruff check src/coding_deepgent/frontend tests/frontend/test_stream_bridge.py tests/frontend/test_frontend_runs.py tests/frontend/test_frontend_sse.py tests/frontend/test_frontend_client.py tests/structure/test_structure.py` -> passed.
+* `mypy src/coding_deepgent/frontend` -> passed.
+
+Architecture:
+
+* We now have three adapter classes:
+  * JSONL for CLI
+  * embedded client for scripts/tests
+  * SSE foundation for future Web
+* `FrontendRunService` is transport-neutral orchestration; it publishes into `MemoryStreamBridge`.
+
+Boundary findings:
+
+* No HTTP server framework has been added yet; this is gateway-ready foundation only.
+* Future HTML/Web can now start from SSE transport rather than wrapping CLI or JSONL.
+* Real disconnect/cancel semantics remain intentionally minimal compared with DeerFlow's fuller async Gateway.
+
+Architecture:
+
+* Runtime-facing event generation is now separated from JSONL transport.
+* Current CLI continues to use JSONL.
+* Embedded Python consumption now exists without going through JSONL.
+* Future Web can add SSE/Gateway adapter without wrapping CLI.
+
+Boundary findings:
+
+* Physical harness package split remains deferred.
+* Gateway/SSE and HTML/Web remain deferred.
+* `frontend.bridge` remains only for backwards compatibility; new imports should prefer `producer` or `adapters.jsonl`.
+
+## Final Closeout (2026-04-19)
+
+This brainstorm is complete. The recommended producer/adapter split and
+RunManager/StreamBridge/SSE foundation have already been implemented:
+
+* shared producer: `coding_deepgent.frontend.producer`
+* CLI JSONL adapter: `coding_deepgent.frontend.adapters.jsonl`
+* embedded client: `coding_deepgent.frontend.client`
+* run lifecycle: `coding_deepgent.frontend.runs`
+* replayable event bridge: `coding_deepgent.frontend.stream_bridge`
+* SSE adapter/gateway foundation: `coding_deepgent.frontend.adapters.sse` and
+  `coding_deepgent.frontend.gateway`
+
+Remaining Web work should start from a new focused task, such as a gateway HITL
+resume endpoint or browser UI, rather than keeping this architecture brainstorm
+active.
diff --git a/.trellis/tasks/archive/2026-04/04-19-deerflow-inspired-decoupling/task.json b/.trellis/tasks/archive/2026-04/04-19-deerflow-inspired-decoupling/task.json
new file mode 100644
index 000000000..485422d3e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-deerflow-inspired-decoupling/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "deerflow-inspired-decoupling",
+  "name": "deerflow-inspired-decoupling",
+  "title": "brainstorm: deerflow-inspired cli web decoupling",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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/archive/2026-04/04-19-final-release-validation-pr-cleanup/check.jsonl b/.trellis/tasks/archive/2026-04/04-19-final-release-validation-pr-cleanup/check.jsonl
new file mode 100644
index 000000000..ff4ab7e2b
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-final-release-validation-pr-cleanup/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": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Final quality review."}
+{"file": ".trellis/spec/frontend/quality-guidelines.md", "reason": "Final frontend quality review."}
diff --git a/.trellis/tasks/archive/2026-04/04-19-final-release-validation-pr-cleanup/debug.jsonl b/.trellis/tasks/archive/2026-04/04-19-final-release-validation-pr-cleanup/debug.jsonl
new file mode 100644
index 000000000..c1b287771
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-final-release-validation-pr-cleanup/debug.jsonl
@@ -0,0 +1,2 @@
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-19-final-release-validation-pr-cleanup/implement.jsonl b/.trellis/tasks/archive/2026-04/04-19-final-release-validation-pr-cleanup/implement.jsonl
new file mode 100644
index 000000000..76e31bfd1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-final-release-validation-pr-cleanup/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": ".trellis/spec/frontend/index.md", "reason": "Frontend development guide"}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Release validation should follow mainline quality policy."}
+{"file": ".trellis/spec/frontend/quality-guidelines.md", "reason": "CLI frontend validation commands."}
diff --git a/.trellis/tasks/archive/2026-04/04-19-final-release-validation-pr-cleanup/prd.md b/.trellis/tasks/archive/2026-04/04-19-final-release-validation-pr-cleanup/prd.md
new file mode 100644
index 000000000..4761b617e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-final-release-validation-pr-cleanup/prd.md
@@ -0,0 +1,65 @@
+# Final release validation and PR cleanup
+
+## Goal
+
+对当前 `codex/stage-12-14-context-compact-foundation` 分支做一次最终发布前验证和 PR 状态清理，确认最近完成的 CLI frontend、HITL、task closeout 和 journal 记录没有留下明显本地问题。
+
+## Acceptance Targets
+
+* 工作区保持 clean。
+* 当前分支对应 PR 状态已查看。
+* 关键 Python / TypeScript checks 通过。
+* 若发现失败，定位并修复；若是外部/CI-only blocker，记录清楚。
+* 不引入新功能。
+
+## Planned Features
+
+* Run focused and broader validation commands for touched product areas.
+* Inspect current PR metadata/check status.
+* Summarize release readiness and remaining risks.
+
+## Acceptance Criteria
+
+* [x] `git status` clean except this validation task before archive.
+* [x] Trellis active task list is controlled.
+* [x] Focused and broad local validation passes.
+* [x] Current PR metadata/checks inspected.
+* [x] README-only merge conflict was identified and intentionally not resolved per user direction.
+* [x] Task archived and session status reported.
+
+## Technical Notes
+
+Likely commands:
+
+* `pytest` for CLI/frontend/tool-system/structure tests
+* `ruff check`
+* `mypy`
+* `npm --prefix coding-deepgent/frontend/cli run typecheck`
+* `npm --prefix coding-deepgent/frontend/cli test`
+* `gh pr view 220 ...`
+* `gh pr checks 220 ...`
+
+## Validation Result (2026-04-19)
+
+Local checks passed:
+
+* `pytest -q` from `coding-deepgent/` -> `406 passed`
+* `ruff check src tests` from `coding-deepgent/` -> passed
+* `mypy src/coding_deepgent` from `coding-deepgent/` -> passed (`143 source files`)
+* `npm --prefix coding-deepgent/frontend/cli run typecheck` -> passed
+* `npm --prefix coding-deepgent/frontend/cli test` -> `8 passed`
+
+PR state inspected:
+
+* PR `#220` is `OPEN` and `draft=true`
+* `mergeable=CONFLICTING`
+* Checks show two Vercel failures, both `Authorization required to deploy`
+* local branch is ahead of `origin/codex/stage-12-14-context-compact-foundation`
+
+Conflict note:
+
+* A dry merge / attempted merge from `upstream/main` showed conflicts only in
+  root tutorial README files: `README.md`, `README-zh.md`, `README-ja.md`.
+* Product code under `coding-deepgent/` did not conflict.
+* User instructed not to handle README; merge was aborted and README conflicts
+  were left unresolved for PR cleanup outside this task.
diff --git a/.trellis/tasks/archive/2026-04/04-19-final-release-validation-pr-cleanup/task.json b/.trellis/tasks/archive/2026-04/04-19-final-release-validation-pr-cleanup/task.json
new file mode 100644
index 000000000..f8c02f390
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-final-release-validation-pr-cleanup/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "final-release-validation-pr-cleanup",
+  "name": "final-release-validation-pr-cleanup",
+  "title": "Final release validation and PR cleanup",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-20",
+  "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/archive/2026-04/04-19-frontend-architecture-cc-cli-reuse/check.jsonl b/.trellis/tasks/archive/2026-04/04-19-frontend-architecture-cc-cli-reuse/check.jsonl
new file mode 100644
index 000000000..038ff25e0
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-frontend-architecture-cc-cli-reuse/check.jsonl
@@ -0,0 +1,8 @@
+{"file": ".gemini/commands/trellis/finish-work.toml", "reason": "Finish work checklist"}
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
+{"file": ".trellis/spec/backend/directory-structure.md", "reason": "Backend ownership for frontend bridge modules"}
+{"file": ".trellis/spec/backend/error-handling.md", "reason": "CLI and bridge error boundaries"}
+{"file": ".trellis/spec/guides/cc-alignment-guide.md", "reason": "cc source-backed frontend alignment boundary"}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Focused Python validation expectations"}
+{"file": ".trellis/spec/guides/staged-execution-guide.md", "reason": "Integrated CLI frontend staged execution"}
diff --git a/.trellis/tasks/archive/2026-04/04-19-frontend-architecture-cc-cli-reuse/debug.jsonl b/.trellis/tasks/archive/2026-04/04-19-frontend-architecture-cc-cli-reuse/debug.jsonl
new file mode 100644
index 000000000..c1b287771
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-frontend-architecture-cc-cli-reuse/debug.jsonl
@@ -0,0 +1,2 @@
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-19-frontend-architecture-cc-cli-reuse/implement.jsonl b/.trellis/tasks/archive/2026-04/04-19-frontend-architecture-cc-cli-reuse/implement.jsonl
new file mode 100644
index 000000000..9137c1b38
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-frontend-architecture-cc-cli-reuse/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": ".trellis/spec/frontend/index.md", "reason": "Frontend development guide"}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Focused Python validation expectations"}
+{"file": ".trellis/spec/backend/error-handling.md", "reason": "CLI and bridge error boundaries"}
+{"file": ".trellis/spec/backend/directory-structure.md", "reason": "Backend ownership for frontend bridge modules"}
+{"file": ".trellis/spec/guides/cc-alignment-guide.md", "reason": "cc source-backed frontend alignment boundary"}
+{"file": ".trellis/spec/guides/staged-execution-guide.md", "reason": "Integrated CLI frontend staged execution"}
diff --git a/.trellis/tasks/archive/2026-04/04-19-frontend-architecture-cc-cli-reuse/prd.md b/.trellis/tasks/archive/2026-04/04-19-frontend-architecture-cc-cli-reuse/prd.md
new file mode 100644
index 000000000..3dbfc1dfb
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-frontend-architecture-cc-cli-reuse/prd.md
@@ -0,0 +1,575 @@
+# brainstorm: frontend architecture and cc cli reuse
+
+## Goal
+
+为 `coding-deepgent/` 设计一个尽量简单、可渐进演进的前端策略：短期优先复用或对齐 Claude Code / cc 风格的 CLI 交互体验，长期保留支持 Web 端的架构空间，避免在当前阶段引入过重 UI 工程。
+
+## What I already know
+
+* 用户希望前端方案“简单一点”。
+* 用户倾向于“大部分移植 cc 的 CLI 前端”。
+* 用户希望未来支持 Web 端。
+* 用户明确可以引入 TypeScript / React 等依赖。
+* 用户的核心目标是开发便捷、快速完工，而不是严格保持 Python-only。
+* 当前项目主线是 `coding-deepgent/`。
+* `.trellis/spec/frontend/index.md` 明确当前 `web/` 与 tutorial UI 是参考层，不是默认产品实现目标。
+* 这个议题属于架构/产品形态决策，不应直接开始编码。
+* `coding-deepgent/` 已经有 Typer/Rich CLI：`coding_deepgent/cli.py`、`cli_service.py`、`renderers/text.py`、`todo/renderers.py`。
+* `coding-deepgent/` 已经有 runtime event seam：`runtime/events.py` 提供 `RuntimeEvent`、`RuntimeEventSink`、`QueuedRuntimeEventSink`。
+* `coding-deepgent/` 已经有 session/evidence/recovery brief：`sessions/*`、`cli_service.recovery_brief_text()`。
+* `/root/claude-code-haha` 的 CLI 前端主要是 React/Ink REPL，不是 Python 可直接移植的代码层。
+* LangChain/LangGraph 官方 streaming/HITL 能提供未来 Web/CLI 共享的事件基础：`stream_mode=["messages", "updates", "custom"]`、`version="v2"`、interrupt/HITL resume。
+
+## Assumptions (temporary)
+
+* “cc” 指 Claude Code 或项目中对齐 Claude Code 的 CLI/TUI 交互体验。
+* 第一阶段目标应是完整交付 CLI 前端 v1，而不是只做半成品 MVP；浏览器 Web 不并入这个 CLI 完工目标。
+* 未来 Web 端更适合复用核心事件/会话/任务状态，而不是复用终端渲染代码本身。
+* 如果引入 TypeScript/React，最快路径更可能是 React/Ink CLI shell，而不是 Python Rich-only 或完整 browser-first Web。
+
+## Open Questions
+
+* CLI 完工目标是否包括 true streaming 和 true permission pause/resume，还是只要求完成可见 UI 与协议预留？
+
+## Requirements (evolving)
+
+* 设计应保持简单，避免一次性建设完整 Web 前端。
+* CLI 体验应尽量对齐 cc 风格。
+* 架构应为未来 Web 端保留稳定边界。
+* 对齐 cc 时必须先对齐“交互效果”和“运行时 contract”，而不是复制 UI/TUI 文件结构。
+* 前端边界应避免把 Typer/Rich、React/Ink 或 Web 框架泄漏进 domain services。
+* 允许新增 TypeScript/React/Ink 前端包，前提是 Python `coding-deepgent` runtime 保持清晰后端边界。
+* 优先选择能快速复用 cc UI 思路和组件形态的方案。
+* 前端实现采用选择性移植：优先搬 cc 的组件结构、交互语义、布局模式和小型纯 UI helper；不整包搬运行时、AppState、Bun feature flags、analytics、bridge/daemon/team/IDE 等复杂系统。
+
+## Acceptance Criteria (evolving)
+
+* [x] 明确 CLI v1 完工范围。
+* [x] 明确哪些 cc CLI 行为应复用/对齐，哪些不应照搬。
+* [x] 明确 CLI 与未来 Web 端共享的核心边界。
+* [x] 形成可拆分的小 PR 实施计划。
+* [x] PRD 记录 source-backed cc alignment matrix。
+* [x] PRD 明确 Acceptance Targets / Planned Features / Planned Extensions。
+
+## Definition of Done (team quality bar)
+
+* Tests added/updated where appropriate.
+* Lint / typecheck / CI green if implementation follows.
+* Docs/notes updated if behavior or architecture contracts change.
+* Rollout/rollback considered if risky.
+
+## Out of Scope (explicit)
+
+* 暂不默认修改 `web/` 参考层。
+* 暂不默认实现完整浏览器 Web 产品。
+* 暂不复制不适合本项目运行时模型的 cc 内部实现细节。
+* 暂不把 React/Ink/Web 框架引入 Python domain/runtime services。
+* 暂不实现远程 Bridge / IDE / daemon / Web control plane。
+
+## Technical Notes
+
+* Start workflow read: `.trellis/workflow.md`.
+* Guidelines indexes read: `.trellis/spec/frontend/index.md`, `.trellis/spec/backend/index.md`, `.trellis/spec/guides/index.md`.
+* Current git branch from context: `codex/stage-12-14-context-compact-foundation`.
+* Current worktree already has unrelated/unconfirmed changes: deleted `.env.example`, untracked `.coding-deepgent/`.
+* Frontend specs are currently Deferred; if product Web becomes active, `.trellis/spec/frontend/*` should be reactivated from real product code conventions.
+* `/root/claude-code-haha/package.json` uses `ink`, `react`, `zod`, `chalk`, `figures`, `wrap-ansi`, and related terminal UI dependencies.
+* Current reference `web/package.json` already uses Next 16, React 19, TypeScript, and `tsx`, but `web/` remains tutorial/reference unless deliberately promoted.
+* cc source inspected:
+  * `/root/claude-code-haha/src/entrypoints/cli.tsx`
+  * `/root/claude-code-haha/src/screens/REPL.tsx`
+  * `/root/claude-code-haha/src/components/App.tsx`
+  * `/root/claude-code-haha/src/components/Messages.tsx`
+  * `/root/claude-code-haha/src/components/Message.tsx`
+  * `/root/claude-code-haha/src/components/PromptInput/PromptInput.tsx`
+  * `/root/claude-code-haha/src/components/permissions/PermissionRequest.tsx`
+  * `/root/claude-code-haha/src/Tool.ts`
+  * `/root/claude-code-haha/src/query.ts`
+  * `/root/claude-code-haha/src/tools/TodoWriteTool/TodoWriteTool.ts`
+* Local source inspected:
+  * `coding-deepgent/src/coding_deepgent/cli.py`
+  * `coding-deepgent/src/coding_deepgent/cli_service.py`
+  * `coding-deepgent/src/coding_deepgent/runtime/events.py`
+  * `coding-deepgent/src/coding_deepgent/rendering.py`
+  * `coding-deepgent/src/coding_deepgent/renderers/text.py`
+  * `coding-deepgent/src/coding_deepgent/todo/renderers.py`
+  * `coding-deepgent/src/coding_deepgent/agent_loop_service.py`
+  * `coding-deepgent/tests/cli/test_cli.py`
+  * `coding-deepgent/tests/runtime/test_runtime_events.py`
+* Current `web/` is a Next.js tutorial/reference site, not a product agent UI.
+
+## Research Notes
+
+### What similar tools do
+
+* Claude Code / cc-haha uses a large React/Ink REPL surface. `screens/REPL.tsx` owns message state, prompt input, permission queue, spinner state, streaming text/tool-use state, transcript mode, task list display, and query loop wiring.
+* cc-haha splits display into message renderers (`components/Messages.tsx`, `components/Message.tsx`) and tool-specific renderers/permission UIs (`Tool.ts`, `components/permissions/*`), but this is tightly coupled to TypeScript, React, Ink, Bun feature flags, and its custom AppState.
+* cc-haha's important reusable idea is an eventful UI contract: user input, assistant streaming, tool call start/result/error, permission request/decision, task/todo state, compact/recovery boundaries, spinner/progress, and transcript visibility.
+* LangChain/LangGraph provides official streaming primitives that map cleanly to this need: `messages` for tokens, `updates` for graph/agent step state, `custom` for app-defined progress, and HITL interrupts for approval/resume flows.
+
+### Constraints from our repo/project
+
+* Mainline is Python `coding-deepgent/`; current dependencies already include `typer` and `rich`.
+* User now accepts TypeScript/React dependencies when that speeds delivery.
+* The roadmap explicitly says the product should not become a UI/TUI clone.
+* Existing renderer boundary is intentionally simple and terminal-compatible.
+* Existing runtime event sink is local and queued, but not yet a full UI event bus or Web transport.
+* Future Web support should not reuse terminal rendering strings as its source of truth; it should consume typed events/state snapshots and render independently.
+
+### Feasible approaches here
+
+**Approach A: React/Ink CLI shell over Python event backend** (Recommended after user clarified speed/dev-convenience priority)
+
+* How it works: add a small TypeScript frontend package that uses React/Ink for the interactive CLI shell. It talks to `coding-deepgent` through a simple newline-delimited JSON event protocol or subprocess bridge. The Python side emits typed run/session/tool/todo/permission events; the TS side owns prompt input, message list, spinner/progress, and future component reuse.
+* Pros: fastest path to cc-like UX, easiest to borrow cc component structure, keeps Python runtime intact, and creates event contracts Web can consume later.
+* Cons: introduces Node/TS build tooling and a cross-process protocol earlier.
+
+**Approach B: Python CLI-first event contract**
+
+* How it works: keep Typer/Rich as the shipping UI, add a typed `FrontendEvent`/`RunEvent` envelope and an adapter from runtime/session/tool/todo updates to that envelope. CLI renders these events with Rich; future Web consumes the same stream over an API/SSE/WebSocket later.
+* Pros: simplest now, fits Python/LangChain, avoids React/Ink port, creates the right Web seam early.
+* Cons: less cc-like, slower to build rich prompt/input/permission UX, and less reusable with future React Web.
+
+**Approach C: Direct cc-style TUI clone**
+
+* How it works: introduce a richer Python TUI layer, likely Textual or equivalent, and try to mirror cc's full-screen REPL, prompt input, permission dialogs, spinner, and transcript layout.
+* Pros: closest visual/interaction parity.
+* Cons: much larger scope, pulls UI state deeply into runtime, likely conflicts with roadmap's no UI/TUI clone rule, delays core product quality.
+
+**Approach D: Web-first control plane**
+
+* How it works: create a backend API and browser app now; CLI becomes secondary.
+* Pros: future Web starts immediately.
+* Cons: highest product-scope expansion, requires frontend specs activation, API/auth/session transport decisions, and risks building UI before core runtime contracts are stable.
+
+## Expected effect
+
+Aligning with cc CLI should improve user-visible responsiveness, safety visibility, and session continuity. The local effect should be: users can see what the agent is doing, what tools/permissions/state changed, and how to resume, without needing a full Web app or cloned TUI.
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| REPL shell | `screens/REPL.tsx` coordinates prompt input, streaming, messages, permissions, spinner | one coherent CLI run/session view | TS React/Ink shell + Python event bridge | partial | align effect and component shape, not copy full app |
+| Message rendering | `components/Messages.tsx`, `components/Message.tsx` render user/assistant/system/tool messages | stable transcript/recovery display | TS message components over typed events | partial | align categories and layout |
+| Tool rendering | `Tool.ts` exposes render hooks and `setToolJSX` | tool start/result/error are visible and typed | Python `ToolCapability` + TS render components | partial | align contract, not JSX in Python |
+| Permission UX | `components/permissions/PermissionRequest.tsx` maps tools to approval dialogs | approval/reject/edit surfaces can pause/resume execution | Python permission/HITL events + TS approval UI | defer | event shape first, richer approval next |
+| Todo/task status | `TodoWriteTool`, `TaskListV2`, spinner active forms | visible plan/task progress | TS todo/task components consuming state snapshots | partial | align now for CLI; Web later reuses data contracts |
+| Streaming | `query.ts` yields assistant/tool/progress events | live feedback instead of final-only response | LangChain/LangGraph `stream(..., version="v2")` path | defer | add after CLI event envelope |
+| Web/remote | Bridge/daemon/Web-heavy paths | browser UI can follow same runs later | future API/SSE/WebSocket adapter | defer | not in CLI v1 |
+
+## Acceptance Targets
+
+* A user can run a new cc-like CLI frontend and see a simple lifecycle view: prompt, assistant text, tool/progress state, permission/status messages, todos/tasks, recovery/session summary.
+* Runtime/UI boundary is typed enough that a future Web renderer can subscribe to the same event/state stream without parsing Rich text.
+* The implementation keeps Python/LangChain as the runtime, while TypeScript/React owns interactive UI rendering.
+* The team can finish a complete CLI v1 quickly without building full cc parity.
+
+## Planned Features
+
+* Define a small frontend event contract for CLI/Web consumers.
+* Add a TypeScript React/Ink CLI package or app shell.
+* Add a Python subprocess/JSONL bridge that can run prompts and emit typed events.
+* Implement minimal TS components for prompt input, message list, spinner/progress, todo/task status, and session/recovery summary.
+* Selectively adapt cc frontend pieces only when they are mostly presentational and have limited dependency drag.
+* Map existing runtime events, session summaries, todo/task snapshots, and tool/permission outcomes into the event contract.
+* Keep current Python command groups (`run`, `sessions`, `memory`, `doctor`, etc.) as backend/debug fallbacks while the new CLI matures.
+
+## Planned Extensions
+
+* LangGraph streaming adapter using `stream_mode=["messages", "updates", "custom"]`, `version="v2"`.
+* HITL approval/resume flow using LangGraph interrupts or equivalent local pause/resume seam.
+* Web transport: SSE first for read-only run streams; WebSocket only when bidirectional live input becomes necessary.
+* Browser Web app that reuses TS domain types and consumes typed events/session snapshots.
+* Full-screen TUI, IDE/remote bridge, daemon control plane, and mobile-friendly surface.
+
+## Decision (ADR-lite, proposed)
+
+**Context**: The user wants a simple frontend, prefers cc CLI-like behavior, wants future Web support, and accepts TypeScript/React dependencies if that speeds delivery. The repo is Python `coding-deepgent/`, but cc's fastest reusable front-end shape is React/Ink.
+
+**Decision**: Prefer Approach A: React/Ink CLI shell over Python event backend. Reuse cc's interaction model, selected component structure, and visual semantics; keep Python as the agent/runtime owner.
+
+**Consequences**: The first milestone is not a browser app, but it creates a React/TypeScript UI layer that can later share types/components with Web. The cost is introducing Node tooling and a Python-to-TS event bridge now.
+
+## Implementation Bias
+
+以“搬 cc 的前端经验”为主，不以整包复制代码为主。
+
+* Copy/adapt candidates: simple message rows, spinner/progress display ideas, permission prompt layout, todo/task visual presentation, footer/status concepts, small pure formatting helpers.
+* Build locally: event schema, Python JSONL bridge, process lifecycle, session state mapping, permission decision protocol, package scaffolding, tests.
+* Do-not-copy candidates: `screens/REPL.tsx` wholesale, cc `AppState`, Bun feature flag system, analytics/telemetry, Bridge/daemon/remote/team/IDE flows, provider-specific UI branches, full command catalog.
+* Practical rule: if a cc file drags more than a few local dependencies or owns runtime behavior, extract the idea and rewrite; if it is mostly presentational and small, adapt it.
+
+## Integrated CLI Frontend Completion Plan
+
+### Delivery Mode
+
+直接以一个集成交付任务完成 CLI 前端 v1，不按用户可见的小迭代拆开交付。
+
+内部仍保留 stage/checkpoint，但 checkpoint 只用于控制质量和防止方向漂移；若 checkpoint verdict 是 `APPROVE`，继续下一 stage，不停下来重新讨论。
+
+Default validation budget: `lean`，但因为该工作引入跨语言协议和新前端包，协议层、bridge 层、关键 UI reducer 层必须有 focused tests。
+
+### Final CLI Target
+
+完成后应有一个新的 cc-like CLI 入口，例如：
+
+```text
+coding-deepgent-ui
+```
+
+或开发期命令：
+
+```text
+npm --prefix coding-deepgent/frontend/cli run dev
+```
+
+用户可在一个交互式 React/Ink 界面里：
+
+* 输入多轮 prompt。
+* 看到 assistant 文本、运行状态、spinner/progress。
+* 看到工具调用开始、结果、错误、权限/拒绝状态。
+* 看到 TodoWrite / durable task 的当前状态快照。
+* 查看/恢复 session 的 recovery brief。
+* 在失败时看到清晰错误，而不是 Python traceback 或 JSONL 泄漏。
+
+### Proposed File Layout
+
+```text
+coding-deepgent/
+  frontend/
+    protocol/
+      README.md                 # event schema and stdin/stdout contract
+      events.schema.json         # optional generated/handwritten schema
+    cli/
+      package.json
+      tsconfig.json
+      src/
+        index.tsx                # bin entrypoint
+        app.tsx                  # Ink root
+        bridge/
+          python-process.ts      # spawn + JSONL reader/writer
+          protocol.ts            # TS event/input types
+          reducer.ts             # event -> UI state
+        components/
+          prompt-input.tsx
+          message-list.tsx
+          message-row.tsx
+          spinner.tsx
+          status-footer.tsx
+          permission-panel.tsx
+          todo-panel.tsx
+          session-panel.tsx
+        styles/
+          theme.ts
+        __tests__/
+          reducer.test.ts
+          protocol.test.ts
+          render-smoke.test.tsx
+  src/coding_deepgent/
+    frontend/
+      __init__.py
+      protocol.py               # Python event/input dataclasses or Pydantic models
+      bridge.py                 # JSONL bridge loop
+      event_mapping.py          # runtime/session/tool/todo -> frontend events
+    cli.py                      # add bridge command group or hidden command
+```
+
+### Protocol Shape
+
+Use newline-delimited JSON over stdio for first delivery.
+
+Python stdout is reserved for frontend events. Python stderr is reserved for logs/debug. TS stdin sends user inputs and control decisions.
+
+#### FrontendEvent v1
+
+```json
+{"type":"session_started","session_id":"...","workdir":"..."}
+{"type":"user_message","id":"...","text":"..."}
+{"type":"assistant_delta","message_id":"...","text":"..."}
+{"type":"assistant_message","message_id":"...","text":"..."}
+{"type":"tool_started","tool_call_id":"...","name":"...","summary":"..."}
+{"type":"tool_finished","tool_call_id":"...","name":"...","status":"success","preview":"..."}
+{"type":"tool_failed","tool_call_id":"...","name":"...","error":"..."}
+{"type":"permission_requested","request_id":"...","tool":"...","description":"...","options":["approve","reject"]}
+{"type":"permission_resolved","request_id":"...","decision":"approve"}
+{"type":"todo_snapshot","items":[{"content":"...","status":"in_progress","activeForm":"..."}]}
+{"type":"task_snapshot","items":[...]}
+{"type":"runtime_event","kind":"query_error","message":"...","metadata":{}}
+{"type":"recovery_brief","text":"..."}
+{"type":"run_finished","session_id":"...","status":"completed"}
+{"type":"run_failed","session_id":"...","error":"..."}
+```
+
+#### FrontendInput v1
+
+```json
+{"type":"submit_prompt","text":"..."}
+{"type":"permission_decision","request_id":"...","decision":"approve"}
+{"type":"permission_decision","request_id":"...","decision":"reject","message":"..."}
+{"type":"interrupt"}
+{"type":"exit"}
+```
+
+### Stage 1: Scaffolding And Protocol Contract
+
+Goal: create the package and protocol without yet needing live LLM.
+
+Implementation:
+
+* Add `coding-deepgent/frontend/cli` package with `ink`, `react`, `typescript`, `tsx` or build tooling.
+* Add TS protocol types and reducer.
+* Add Python protocol models and JSONL helpers.
+* Add fixture event streams for UI smoke tests.
+* Add docs in `frontend/protocol/README.md`.
+
+Focused validation:
+
+* TS typecheck passes.
+* Reducer tests prove event order updates UI state deterministically.
+* Python protocol tests validate event serialization and bad event rejection.
+
+Checkpoint:
+
+* `APPROVE` if the TS app can render a fixture stream and Python can emit valid JSONL.
+
+### Stage 2: Python Bridge For Existing Runtime
+
+Goal: run real `coding-deepgent` prompts through the bridge.
+
+Implementation:
+
+* Add `coding-deepgent frontend bridge` or hidden `coding-deepgent ui-bridge` command.
+* Bridge reads `FrontendInput` from stdin and writes `FrontendEvent` to stdout.
+* First pass may use current `run_prompt_with_recording()` final response path, then emit lifecycle events around it.
+* Map existing `RuntimeEventSink` snapshot and session/recovery data into `runtime_event` / `recovery_brief` events.
+* Preserve Python CLI fallback commands unchanged.
+
+Focused validation:
+
+* Python bridge test with fake agent: `submit_prompt` -> `user_message` -> `assistant_message` -> `run_finished`.
+* Bridge test verifies stderr/logs do not corrupt stdout JSONL.
+* Existing `tests/cli/test_cli.py` remains passing.
+
+Checkpoint:
+
+* `APPROVE` if a TS bridge client can spawn Python and complete a fake prompt round trip.
+
+### Stage 3: Interactive React/Ink CLI Shell
+
+Goal: deliver the usable cc-like local CLI.
+
+Implementation:
+
+* Implement `App` with prompt input, message list, spinner, status footer, and error boundary.
+* Implement subprocess bridge client with reconnect/exit handling.
+* Implement multi-turn prompt loop over a persistent Python bridge process.
+* Render assistant final messages first; streaming deltas can be wired after the stable bridge.
+* Add keyboard shortcuts: submit, Ctrl+C interrupt/exit path, maybe `/exit`.
+* Add safe fallback display when event payload is unknown.
+
+cc adaptation:
+
+* Borrow layout ideas from `PromptInput`, `Messages`, `Message`, `Spinner`, and permission components.
+* Rewrite components locally with a small prop surface; do not import cc source wholesale.
+
+Focused validation:
+
+* TS reducer tests for multi-turn state.
+* TS render smoke tests against fixture event streams.
+* Manual command with fake Python bridge or fixture mode.
+
+Checkpoint:
+
+* `APPROVE` if the UI is usable with fake bridge and does not require live API keys.
+
+### Stage 4: Tool/Todo/Session Visibility
+
+Goal: make the UI meaningfully better than final-text-only.
+
+Implementation:
+
+* Map `TodoWrite` result/state into `todo_snapshot`.
+* Map durable tasks into `task_snapshot` if existing task state is available without new runtime complexity.
+* Map tool capability metadata and middleware outcomes into `tool_started` / `tool_finished` / `tool_failed` where available.
+* Show recovery brief/session info in a session panel or startup notice.
+* Show runtime evidence/query errors as status/system rows.
+
+Focused validation:
+
+* Python event mapping tests for todos, runtime events, query errors, recovery brief.
+* TS UI tests for todo panel, runtime event rows, failed run display.
+
+Checkpoint:
+
+* `APPROVE` if live or fake event streams display the main cc-like work-state surfaces.
+
+### Stage 5: Permission UX And Interrupt Readiness
+
+Goal: add the visible approval surface even if full LangGraph HITL is deferred.
+
+Implementation:
+
+* Define permission request/resolution event handling in the protocol.
+* Render `permission-panel.tsx` with approve/reject choices.
+* If current Python permission runtime cannot truly pause yet, emit denied/ask events as visibility first and keep full pause/resume as explicit follow-up.
+* If local pause is feasible without replacing runtime seams, wire `permission_decision` input into the Python permission path.
+
+Focused validation:
+
+* TS tests for permission request queue and decision dispatch.
+* Python protocol tests for permission decision validation.
+* If pause/resume is implemented, fake tool permission test proves no tool executes before approval.
+
+Checkpoint:
+
+* `APPROVE` if permission events render and decisions are protocol-safe.
+* `ITERATE` if true pause/resume needs a separate LangGraph HITL task; keep visible permission status in CLI v1 and defer full interrupt only with explicit rationale.
+
+### Stage 6: Real Streaming Upgrade
+
+Goal: move from final-response events to live streaming where practical.
+
+Implementation:
+
+* Add a LangChain/LangGraph streaming path using `stream_mode=["messages","updates","custom"]`, `version="v2"` if compatible with current agent construction.
+* Map message chunks to `assistant_delta`.
+* Map graph/tool updates to tool/progress events.
+* Preserve non-streaming fallback only as an explicit bridge mode, not hidden duplicate logic.
+
+Focused validation:
+
+* Fake streaming agent test emits ordered deltas and final message.
+* TS reducer coalesces deltas into a stable message.
+* Non-streaming bridge test still passes.
+
+Checkpoint:
+
+* `APPROVE` if streaming works with fake and at least one local real path.
+* `ITERATE` if LangChain runtime shape makes streaming risky; keep final-response CLI v1 only if streaming would destabilize the runtime, and record streaming as a named exception.
+
+### Stage 7: Productization And Documentation
+
+Goal: make the CLI easy to run and maintain.
+
+Implementation:
+
+* Add scripts/documentation for dev and installed usage.
+* Add a wrapper command if appropriate.
+* Update `coding-deepgent/README.md` with the new CLI frontend.
+* Update `.trellis/spec/frontend/*` only for real conventions established by this implementation.
+* Keep old Typer commands as backend/debug surface.
+
+Focused validation:
+
+* `npm --prefix coding-deepgent/frontend/cli run typecheck`.
+* `npm --prefix coding-deepgent/frontend/cli test` if test runner is added.
+* Targeted Python tests for protocol/bridge/event mapping.
+* Existing relevant Python CLI/session/todo/runtime event tests.
+
+Terminal checkpoint:
+
+* `APPROVE` if the CLI frontend can run locally, fake-mode tests pass, targeted Python tests pass, and docs explain usage.
+
+## CLI v1 Completion Criteria
+
+This task counts as complete when:
+
+* A React/Ink CLI frontend exists in `coding-deepgent/frontend/cli`.
+* A Python JSONL bridge exists and can complete at least fake-agent and normal prompt flows.
+* The UI supports multi-turn prompt input and renders assistant messages without corrupting terminal output.
+* The UI renders at least these event classes: session start/end, user message, assistant message/delta, runtime event/error, todo snapshot, tool started/finished/failed, recovery brief.
+* Permission event UI exists; true pause/resume may be accepted as outside CLI v1 only if current runtime makes it unsafe to wire in this pass.
+* Focused TS and Python tests cover protocol, reducer, bridge, and key event mapping.
+* Existing Python CLI fallback remains functional.
+
+## Explicit Non-CLI-v1 Follow-Ups
+
+* Browser Web app over the same protocol.
+* SSE/WebSocket server adapter.
+* Full LangGraph HITL interrupt integration if not completed in Stage 5.
+* Richer cc component parity: transcript search, virtualized long history, command palette, slash commands, full task navigation, theme customization.
+* Packaging polish: single installer, published npm package, binary wrappers.
+
+## Final Closeout (2026-04-19)
+
+This brainstorm is complete and has been implemented beyond the original CLI v1
+target:
+
+* React/Ink CLI package exists under `coding-deepgent/frontend/cli`.
+* Python JSONL bridge and renderer-neutral frontend protocol exist under
+  `coding_deepgent.frontend`.
+* Real streaming and same-process CLI permission HITL pause/resume have been
+  implemented and validated in later focused tasks.
+* Product shortcut `coding-deepgent-ui` now exists.
+* Future browser/Web remains an explicit follow-up over the producer/adapter
+  boundary, not a reason to keep this planning task active.
+
+## Stop Conditions For This Integrated Pass
+
+Stop and ask only if:
+
+* The chosen TS/Ink package setup cannot run in this repo without a major package-management decision.
+* Python bridge needs to replace LangChain/LangGraph runtime seams instead of wrapping them.
+* True permission pause/resume requires a product decision about HITL persistence/checkpointing.
+* The worktree has conflicting user changes in files this task must modify.
+* Live LLM behavior blocks validation and no fake-mode path can prove the frontend contract.
+
+## Implementation Checkpoint: CLI v1 Integrated Pass
+
+State:
+
+* terminal
+
+Verdict:
+
+* APPROVE
+
+Implemented:
+
+* Added Python frontend protocol package: `coding_deepgent.frontend.protocol`, `event_mapping`, and `bridge`.
+* Added `coding-deepgent ui-bridge` JSONL backend command with deterministic `--fake` mode.
+* Added React/Ink frontend package at `coding-deepgent/frontend/cli`.
+* Added TS protocol types, Python subprocess bridge, deterministic reducer, prompt input, message list, spinner/status footer, permission panel, todo panel, and recovery/session panel.
+* Added product protocol documentation in `coding-deepgent/frontend/protocol/README.md`.
+* Updated `coding-deepgent/README.md` with frontend commands.
+* Reactivated frontend Trellis specs for the new product CLI frontend.
+* Added lazy public package/CLI runtime imports so protocol/help-style imports do not eagerly load full runtime/subagent surfaces.
+* Fixed a compact/tool_system import cycle by importing `maybe_persist_large_tool_result` from its concrete module.
+
+Verification:
+
+* `pytest -q tests/cli/test_cli.py tests/runtime/test_runtime_events.py tests/frontend/test_frontend_protocol.py tests/frontend/test_frontend_bridge.py tests/frontend/test_frontend_event_mapping.py tests/structure/test_structure.py` -> 40 passed.
+* `ruff check src/coding_deepgent/__init__.py src/coding_deepgent/frontend src/coding_deepgent/cli.py src/coding_deepgent/tool_system/middleware.py tests/frontend/test_frontend_protocol.py tests/frontend/test_frontend_bridge.py tests/frontend/test_frontend_event_mapping.py` -> passed.
+* `mypy src/coding_deepgent/frontend src/coding_deepgent/__init__.py` -> passed.
+* `npm --prefix coding-deepgent/frontend/cli run typecheck` -> passed.
+* `npm --prefix coding-deepgent/frontend/cli test` -> passed.
+* `PYTHONPATH=src python3 -m coding_deepgent ui-bridge --fake` with JSONL input -> emitted ordered session/user/runtime/todo/assistant/recovery/run events.
+* `PYTHONPATH=src python3 -m coding_deepgent --help` -> passed and lists `ui-bridge`.
+* `npm --prefix coding-deepgent/frontend/cli run dev:fake` in PTY -> prompt input, fake bridge response, todo panel, recovery brief, and `/exit` path all worked.
+
+Alignment:
+
+* source files inspected: `/root/claude-code-haha/src/screens/REPL.tsx`, `/root/claude-code-haha/src/components/Messages.tsx`, `/root/claude-code-haha/src/components/Message.tsx`, `/root/claude-code-haha/src/components/PromptInput/PromptInput.tsx`, `/root/claude-code-haha/src/components/permissions/PermissionRequest.tsx`, `/root/claude-code-haha/src/Tool.ts`, `/root/claude-code-haha/src/query.ts`.
+* aligned: React/Ink shell, prompt input, message list, spinner/progress, permission panel shape, todo/task display shape, eventful UI boundary.
+* deferred: full transcript search, virtualized history, slash command catalog, command palette, true HITL pause/resume persistence, browser Web app.
+* do-not-copy: cc AppState, Bun feature flags, analytics/telemetry, bridge/daemon/remote/team/IDE flows, full `REPL.tsx` wholesale.
+
+Architecture:
+
+* primitive used: JSONL protocol over stdio between TS frontend and Python runtime.
+* why no heavier abstraction: fastest local CLI delivery; Web/SSE/WebSocket can later reuse the same event schema without forcing an HTTP server into CLI v1.
+
+Boundary findings:
+
+* Root `web/` remains reference-only.
+* Python runtime remains the owner of session/tool/todo facts.
+* TS frontend owns only display state derived from `FrontendEvent`.
+* True live streaming is protocol-ready through `assistant_delta`, but the current real bridge uses existing non-streaming `run_once`; fake and reducer paths prove the UI contract.
+* True permission pause/resume is protocol/UI-ready, but current Python permission runtime still converts `ask` into a tool error instead of a HITL interrupt.
+
+Decision:
+
+* continue only for non-CLI-v1 extensions such as browser Web, full LangGraph HITL, and richer cc parity.
+
+Reason:
+
+* CLI v1 frontend is implemented and validated against fake bridge plus focused Python/TS tests. Remaining work is explicitly outside the CLI v1 completion line.
diff --git a/.trellis/tasks/archive/2026-04/04-19-frontend-architecture-cc-cli-reuse/task.json b/.trellis/tasks/archive/2026-04/04-19-frontend-architecture-cc-cli-reuse/task.json
new file mode 100644
index 000000000..972366adb
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-frontend-architecture-cc-cli-reuse/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "frontend-architecture-cc-cli-reuse",
+  "name": "frontend-architecture-cc-cli-reuse",
+  "title": "brainstorm: frontend architecture and cc cli reuse",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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/archive/2026-04/04-19-full-mypy-validation-cleanup/check.jsonl b/.trellis/tasks/archive/2026-04/04-19-full-mypy-validation-cleanup/check.jsonl
new file mode 100644
index 000000000..522e1338f
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-full-mypy-validation-cleanup/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": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Verification checklist for focused product tests, ruff, and mypy."}
+{"file": ".trellis/spec/frontend/quality-guidelines.md", "reason": "Frontend bridge checks when touching frontend test typing."}
diff --git a/.trellis/tasks/archive/2026-04/04-19-full-mypy-validation-cleanup/debug.jsonl b/.trellis/tasks/archive/2026-04/04-19-full-mypy-validation-cleanup/debug.jsonl
new file mode 100644
index 000000000..c1b287771
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-full-mypy-validation-cleanup/debug.jsonl
@@ -0,0 +1,2 @@
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-19-full-mypy-validation-cleanup/implement.jsonl b/.trellis/tasks/archive/2026-04/04-19-full-mypy-validation-cleanup/implement.jsonl
new file mode 100644
index 000000000..4c10e6591
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-full-mypy-validation-cleanup/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": ".trellis/spec/frontend/index.md", "reason": "Frontend development guide"}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Backend/mainline validation baseline for fixing typed test failures."}
+{"file": ".trellis/spec/frontend/quality-guidelines.md", "reason": "Frontend bridge typing and validation expectations for touched frontend tests."}
+{"file": ".trellis/spec/guides/mainline-scope-guide.md", "reason": "Keep changes scoped to coding-deepgent mainline typed test cleanup."}
diff --git a/.trellis/tasks/archive/2026-04/04-19-full-mypy-validation-cleanup/prd.md b/.trellis/tasks/archive/2026-04/04-19-full-mypy-validation-cleanup/prd.md
new file mode 100644
index 000000000..33a8aad16
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-full-mypy-validation-cleanup/prd.md
@@ -0,0 +1,67 @@
+# Full mypy validation cleanup
+
+## Goal
+
+修复当前 `coding-deepgent` 主线下 `mypy coding-deepgent/src/coding_deepgent coding-deepgent/tests` 的现有类型检查失败，使 PR 说明里的已知验证缺口收口为通过状态。
+
+## Requirements
+
+- 只处理当前主线 `coding-deepgent/` 的类型检查失败。
+- 优先修复测试中的类型问题，不借机引入运行时行为改动。
+- 保持已有测试语义与覆盖目标不变。
+- 不通过关闭整批检查、缩小 mypy 范围、或粗暴全局忽略来掩盖问题。
+- 若必须使用 `cast` 或窄范围 `type: ignore`，应限定在最小必要位置。
+
+## Acceptance Targets
+
+- `mypy coding-deepgent/src/coding_deepgent coding-deepgent/tests` 通过。
+- 受影响的 focused pytest 仍然通过。
+- 相关 Python 文件的 `ruff check` 通过。
+- PR 可移除当前 “Known Validation Gap” 中关于全量 mypy 的说明。
+
+## Planned Features
+
+- 逐个修复 `tests/compact/test_runtime_pressure.py`、`tests/memory/test_memory_module_closeout.py`、`tests/frontend/test_frontend_bridge.py` 中的类型问题。
+- 为测试 fake / stub 补充显式类型、最小 helper 类或局部 `cast`。
+- 在必要时微调测试辅助对象的构造方式，使其满足被测接口的静态类型契约。
+
+## Planned Extensions
+
+- 不相关的运行时/产品行为重构。
+- 新 feature family。
+- 广泛的测试重写。
+
+## Technical Notes
+
+- 当前问题来自 PR #220 中记录的已知验证缺口。
+- 任务是 `fullstack`，但预期主要修改 Python 测试文件。
+
+## Implementation Checkpoint
+
+State:
+
+- terminal
+
+Verdict:
+
+- APPROVE
+
+Implemented:
+
+- 将 `tests/compact/test_runtime_pressure.py` 中的测试 summarizer / request / runtime helper 收敛为静态类型可接受的形式。
+- 用类型正确的 `ModelResponse`、`Runtime(...)`、局部 `cast` 和更窄的 metadata 断言替换测试里的宽松 `SimpleNamespace` 假对象。
+- 修复 `tests/memory/test_memory_module_closeout.py` 中 `ToolGuardMiddleware` request fake 的静态类型问题。
+- 修复 `tests/frontend/test_frontend_bridge.py` 中未注解事件列表的 mypy 报错。
+- 收口 PR #220 中 “Known Validation Gap” 里记录的全量 mypy 缺口。
+
+Verification:
+
+- `mypy coding-deepgent/src/coding_deepgent coding-deepgent/tests` -> passed
+- `ruff check coding-deepgent/src coding-deepgent/tests` -> passed
+- `pytest -q coding-deepgent/tests` -> `399 passed`
+- `pytest -q coding-deepgent/tests/compact/test_runtime_pressure.py coding-deepgent/tests/memory/test_memory_module_closeout.py coding-deepgent/tests/frontend/test_frontend_bridge.py` -> `53 passed`
+
+Residual Risk:
+
+- 本次改动只修复静态类型与测试 fake，不改变产品 runtime 行为。
+- 工作树里存在与本任务无关的 `.trellis/scripts/common/git_context.py` 和 `.trellis/tests/` 变动；未纳入本任务提交。
diff --git a/.trellis/tasks/archive/2026-04/04-19-full-mypy-validation-cleanup/task.json b/.trellis/tasks/archive/2026-04/04-19-full-mypy-validation-cleanup/task.json
new file mode 100644
index 000000000..b04f83aab
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-full-mypy-validation-cleanup/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "full-mypy-validation-cleanup",
+  "name": "full-mypy-validation-cleanup",
+  "title": "Full mypy validation cleanup",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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/archive/2026-04/04-19-h12-completion-pack-implementation-plan/prd.md b/.trellis/tasks/archive/2026-04/04-19-h12-completion-pack-implementation-plan/prd.md
new file mode 100644
index 000000000..5ade8db3e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-h12-completion-pack-implementation-plan/prd.md
@@ -0,0 +1,100 @@
+# h12 completion pack implementation plan
+
+## Goal
+
+把 H12 从当前 `implemented-minimal` 推进到一个更完整、可长期维持的本地完成形态，并保持单一显式 `run_fork` 入口，不为旧方案/旧数据保留兼容层。
+
+## Requirements
+
+* 继续只保留显式 `run_fork` 入口，不新增隐式 fork 入口。
+* 本包必须一起覆盖：
+  * background fork workers
+  * cache-safe summary / fork reuse
+  * abort / cleanup / kill semantics
+  * resume / path / worktree hardening
+* 可以直接替换旧局部设计，不要求桥接旧方案或旧数据。
+* 不把 mailbox / coordinator / team semantics 混入本包。
+* 本次按**单批收尾**执行：
+  * 不允许先把 H12 宣称 close，再把剩余 cache-safe summary/reuse 留到下一轮
+  * 不允许把 stop/cleanup/resume hardening 拆成“后续小修”
+* H12 只有在下述 gate 同时满足时才能视为完成：
+  * explicit `run_fork` 前台/后台 contract 一致
+  * background fork lifecycle 完整
+  * cache-safe summary / fork reuse 落地
+  * stop / cleanup / kill semantics 落地
+  * resume / path / worktree hardening 落地
+  * spec / tests / roadmap 状态同步
+
+## What Is Already In Place
+
+* explicit `run_fork` 仍是唯一 fork 入口
+* `run_fork(background=true)` 已经接入背景运行面
+* 后台 fork / 子 agent 已有统一状态查询与追加输入
+* `subagent_stop(...)` 已有 stop-request + terminal `cancelled` contract
+* fork / subagent resume 已有 thread continuity
+* workdir mismatch 已有显式错误
+
+## What Still Must Be Closed In This Batch
+
+* H12 parent / child task 状态与 dashboard/roadmap 刷新
+
+## Acceptance Criteria
+
+* [x] 父任务存在并挂到 `04-19-next-subagent-planning/` 下。
+* [x] H12 completion pack 已拆成 4 个子任务。
+* [x] 执行顺序明确。
+* [x] 入口形态明确：explicit `run_fork` only。
+* [x] 单次实现批次完成后，H12 不再留下“下一轮补 fork summary/reuse”的尾巴。
+* [x] 前台 fork 与后台 fork 共享同一条显式 fork surface，而不是形成两套 fork product shape。
+* [x] H12 closeout 验证 bundle 一次通过。
+
+## Technical Approach
+
+采用**单一 integrated closeout**，不是松散 backlog：
+
+1. 以当前 explicit `run_fork` surface 为唯一入口，不再增加新 fork 入口形态
+2. 在同一轮实现里完成：
+   * background fork runtime
+   * cache-safe summary / fork reuse
+   * abort / cleanup / kill semantics
+   * resume / path / worktree hardening
+3. 最后统一过：
+   * focused test bundle
+   * `ruff`
+   * `mypy`
+   * H12 spec 刷新
+   * roadmap / task status 收口
+
+## Implementation Plan (single batch)
+
+* Batch step 1: finalize background fork runtime on the existing background-run manager
+* Batch step 2: add cache-safe summary / fork reuse on the same fork continuity seam
+* Batch step 3: harden stop / cleanup / kill semantics and terminal-state behavior
+* Batch step 4: harden resume / path / worktree checks
+* Batch step 5: run one closeout validation bundle and only then mark H12 done
+
+## Out of Scope
+
+* implicit fork entry
+* mailbox / SendMessage
+* coordinator runtime
+* compatibility shims for old fork/local data shapes
+
+## Decision (ADR-lite)
+
+**Context**: batch1/batch2 已经把 H11 与 H12 minimal slice 做到可继续深化的阶段。用户要求这次直接把 H12 收得更完整，并且不为旧方案或旧数据保留兼容层。
+
+**Decision**: 下一阶段采用 `H12 completion pack`，继续只保留显式 `run_fork` 入口，不新增隐式 fork 入口。
+
+**Consequences**:
+
+* H12 会优先朝单一 fork surface 深化，而不是双入口并存。
+* 允许直接替换当前局部实现，只保留长远边界更清晰的方案。
+* H13/H14 继续 deferred，不与本包并行打开。
+* H12 不按“先 close 80%，再下一轮补最后 20%”的方式收尾；而是一次性完成剩余完成项后再 close。
+
+## Verification
+
+* `pytest -q coding-deepgent/tests/test_agent_runtime_service.py coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_subagents.py coding-deepgent/tests/test_plugins.py coding-deepgent/tests/test_tool_system_registry.py coding-deepgent/tests/test_tool_system_middleware.py`
+* `ruff check`
+* `mypy`
diff --git a/.trellis/tasks/archive/2026-04/04-19-h12-completion-pack-implementation-plan/task.json b/.trellis/tasks/archive/2026-04/04-19-h12-completion-pack-implementation-plan/task.json
new file mode 100644
index 000000000..c879acc47
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-h12-completion-pack-implementation-plan/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "h12-completion-pack-implementation-plan",
+  "name": "h12-completion-pack-implementation-plan",
+  "title": "h12 completion pack implementation plan",
+  "description": "Complete H12 with explicit run_fork entry only: background fork runtime, cache-safe summary/reuse, lifecycle cleanup, and resume/path hardening.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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-19-next-subagent-planning",
+  "relatedFiles": [],
+  "notes": "Completed H12 completion pack: explicit run_fork stays the only fork surface; background fork runtime, background run status/send/stop, fork continuity metadata, resume workdir hardening, plugin-provided agent definitions, and focused closeout validation all landed together.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-19-l3a-h11-background-subagent-runtime/prd.md b/.trellis/tasks/archive/2026-04/04-19-l3a-h11-background-subagent-runtime/prd.md
new file mode 100644
index 000000000..e37272795
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-l3a-h11-background-subagent-runtime/prd.md
@@ -0,0 +1,22 @@
+# L3-a: H11 background subagent runtime
+
+## Goal
+
+增加后台子 agent 运行 surface，让子 agent 可以异步启动并通过稳定 run id 被查询。
+
+## Requirements
+
+* 新增后台启动工具。
+* 背景 run 要有持久化状态记录。
+* 状态查询必须返回结构化记录。
+
+## Acceptance Criteria
+
+* [x] 后台启动返回稳定 `run_id`
+* [x] 状态查询能看到 queued/running/completed/failed
+* [x] 后台 run 不依赖新 daemon/remote process
+
+## Out of Scope
+
+* team runtime
+* mailbox
diff --git a/.trellis/tasks/archive/2026-04/04-19-l3a-h11-background-subagent-runtime/task.json b/.trellis/tasks/archive/2026-04/04-19-l3a-h11-background-subagent-runtime/task.json
new file mode 100644
index 000000000..38421bd94
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-l3a-h11-background-subagent-runtime/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l3a-h11-background-subagent-runtime",
+  "name": "l3a-h11-background-subagent-runtime",
+  "title": "L3-a: H11 background subagent runtime",
+  "description": "Add background subagent execution and status surfaces.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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-19-subagent-batch2-runtime-implementation-plan",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-19-l3b-h11-background-progress-and-notifications/prd.md b/.trellis/tasks/archive/2026-04/04-19-l3b-h11-background-progress-and-notifications/prd.md
new file mode 100644
index 000000000..c25ef4ac3
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-l3b-h11-background-progress-and-notifications/prd.md
@@ -0,0 +1,17 @@
+# L3-b: H11 background progress and notifications
+
+## Goal
+
+让后台子 agent 具备最小可用进度与完成通知。
+
+## Requirements
+
+* 状态里要有 progress summary
+* 状态里要有 recent activities
+* 完成或失败要写一条 bounded notification evidence
+
+## Acceptance Criteria
+
+* [x] 状态记录包含进度摘要
+* [x] 状态记录包含 recent activities
+* [x] 完成/失败会追加 `subagent_notification` evidence
diff --git a/.trellis/tasks/archive/2026-04/04-19-l3b-h11-background-progress-and-notifications/task.json b/.trellis/tasks/archive/2026-04/04-19-l3b-h11-background-progress-and-notifications/task.json
new file mode 100644
index 000000000..3a9ed9129
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-l3b-h11-background-progress-and-notifications/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l3b-h11-background-progress-and-notifications",
+  "name": "l3b-h11-background-progress-and-notifications",
+  "title": "L3-b: H11 background progress and notifications",
+  "description": "Track background subagent progress and emit bounded completion notifications.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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-19-subagent-batch2-runtime-implementation-plan",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-19-l3c-h11-background-input-continuation-and-cleanup/prd.md b/.trellis/tasks/archive/2026-04/04-19-l3c-h11-background-input-continuation-and-cleanup/prd.md
new file mode 100644
index 000000000..4a3bbf183
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-l3c-h11-background-input-continuation-and-cleanup/prd.md
@@ -0,0 +1,18 @@
+# L3-c: H11 background input continuation and cleanup
+
+## Goal
+
+支持对后台子 agent 追加输入，并在结束后释放 worker 句柄。
+
+## Requirements
+
+* follow-up input 必须保留同一个 `run_id`
+* running 状态下可以排队后续输入
+* finished run 也可以被重新激活继续同一 child thread
+* worker 结束后自动 cleanup 内存句柄
+
+## Acceptance Criteria
+
+* [x] `subagent_send_input` 保留同一个 `run_id`
+* [x] follow-up input 会进入同一 background run
+* [x] worker 结束后不会保留活跃句柄
diff --git a/.trellis/tasks/archive/2026-04/04-19-l3c-h11-background-input-continuation-and-cleanup/task.json b/.trellis/tasks/archive/2026-04/04-19-l3c-h11-background-input-continuation-and-cleanup/task.json
new file mode 100644
index 000000000..8e670ca66
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-l3c-h11-background-input-continuation-and-cleanup/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l3c-h11-background-input-continuation-and-cleanup",
+  "name": "l3c-h11-background-input-continuation-and-cleanup",
+  "title": "L3-c: H11 background input continuation and cleanup",
+  "description": "Allow sending follow-up input to live background subagents and clean up finished workers.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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-19-subagent-batch2-runtime-implementation-plan",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-19-l3d-h11-plugin-provided-subagent-definitions/prd.md b/.trellis/tasks/archive/2026-04/04-19-l3d-h11-plugin-provided-subagent-definitions/prd.md
new file mode 100644
index 000000000..26b255ebc
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-l3d-h11-plugin-provided-subagent-definitions/prd.md
@@ -0,0 +1,23 @@
+# L3-d: H11 plugin-provided subagent definitions
+
+## Goal
+
+允许本地插件声明并提供子 agent definitions。
+
+## Requirements
+
+* `plugin.json` 允许声明 `agents`
+* 插件根目录提供 `subagents.json`
+* plugin agent 必须通过现有 agent-definition merge path 加载
+* plugin agent 名字必须带 plugin namespace
+
+## Acceptance Criteria
+
+* [x] plugin manifest 可以声明 agents
+* [x] plugin `subagents.json` 会被加载和校验
+* [x] plugin-provided agents 可被 `resolve_agent_definition(...)` 找到
+
+## Out of Scope
+
+* plugin-specific execution runtime
+* remote plugin agent loading
diff --git a/.trellis/tasks/archive/2026-04/04-19-l3d-h11-plugin-provided-subagent-definitions/task.json b/.trellis/tasks/archive/2026-04/04-19-l3d-h11-plugin-provided-subagent-definitions/task.json
new file mode 100644
index 000000000..5dea435a0
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-l3d-h11-plugin-provided-subagent-definitions/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l3d-h11-plugin-provided-subagent-definitions",
+  "name": "l3d-h11-plugin-provided-subagent-definitions",
+  "title": "L3-d: H11 plugin-provided subagent definitions",
+  "description": "Allow local plugins to declare and load subagent definitions.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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-19-subagent-batch2-runtime-implementation-plan",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-19-l4a-h12-background-fork-runtime/prd.md b/.trellis/tasks/archive/2026-04/04-19-l4a-h12-background-fork-runtime/prd.md
new file mode 100644
index 000000000..087345b9b
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-l4a-h12-background-fork-runtime/prd.md
@@ -0,0 +1,17 @@
+# L4-a: H12 background fork runtime
+
+## Goal
+
+让显式 `run_fork` 真的进入后台 fork worker 形态，而不是继续停留在前台同步 fork。
+
+## Requirements
+
+* fork 能通过现有 background runtime 真正跑在后台
+* 仍保持显式 `run_fork` 入口
+* 不新增隐式 fork 入口
+
+## Acceptance Criteria
+
+* [ ] fork 可以后台启动并返回稳定 run id / thread lineage
+* [ ] background fork 能被查询状态
+* [ ] foreground/background fork 不会分裂成两套不一致 contract
diff --git a/.trellis/tasks/archive/2026-04/04-19-l4a-h12-background-fork-runtime/task.json b/.trellis/tasks/archive/2026-04/04-19-l4a-h12-background-fork-runtime/task.json
new file mode 100644
index 000000000..b1eec33f1
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-l4a-h12-background-fork-runtime/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l4a-h12-background-fork-runtime",
+  "name": "l4a-h12-background-fork-runtime",
+  "title": "L4-a: H12 background fork runtime",
+  "description": "Run fork branches in the background through the existing background subagent runtime without adding an implicit fork entry.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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-19-h12-completion-pack-implementation-plan",
+  "relatedFiles": [],
+  "notes": "Completed background fork runtime on the existing background-run manager while keeping explicit run_fork as the only fork entry.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-19-l4b-h12-cache-safe-summary-and-fork-reuse/prd.md b/.trellis/tasks/archive/2026-04/04-19-l4b-h12-cache-safe-summary-and-fork-reuse/prd.md
new file mode 100644
index 000000000..5d0e92123
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-l4b-h12-cache-safe-summary-and-fork-reuse/prd.md
@@ -0,0 +1,17 @@
+# L4-b: H12 cache-safe summary and fork reuse
+
+## Goal
+
+补齐 H12 最接近 Claude Code fork 价值的部分：cache-safe summary 和 fork reuse。
+
+## Requirements
+
+* summary 必须尽量复用已有 fork/cache-safe params
+* fork reuse 必须保持 prefix continuity
+* 不为旧 placeholder/replacement 形态做兼容层
+
+## Acceptance Criteria
+
+* [ ] background fork summary 能复用 cache-safe continuity
+* [ ] fork reuse 不破坏 prompt/tool identity contract
+* [ ] summary/reuse 走统一 fork continuity seam
diff --git a/.trellis/tasks/archive/2026-04/04-19-l4b-h12-cache-safe-summary-and-fork-reuse/task.json b/.trellis/tasks/archive/2026-04/04-19-l4b-h12-cache-safe-summary-and-fork-reuse/task.json
new file mode 100644
index 000000000..69fa0df0b
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-l4b-h12-cache-safe-summary-and-fork-reuse/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l4b-h12-cache-safe-summary-and-fork-reuse",
+  "name": "l4b-h12-cache-safe-summary-and-fork-reuse",
+  "title": "L4-b: H12 cache-safe summary and fork reuse",
+  "description": "Add cache-safe background fork summaries and reusable fork cache continuity on the explicit run_fork path.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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-19-h12-completion-pack-implementation-plan",
+  "relatedFiles": [],
+  "notes": "Completed the local H12 summary/reuse closeout through background fork continuity state, stable child-thread reuse, persisted prompt/tool fingerprints, and bounded summary_text updates on the same fork surface.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-19-l4c-h12-abort-cleanup-and-kill-semantics/prd.md b/.trellis/tasks/archive/2026-04/04-19-l4c-h12-abort-cleanup-and-kill-semantics/prd.md
new file mode 100644
index 000000000..1c8c6c934
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-l4c-h12-abort-cleanup-and-kill-semantics/prd.md
@@ -0,0 +1,17 @@
+# L4-c: H12 abort cleanup and kill semantics
+
+## Goal
+
+补齐后台 fork / subagent 的停止、失败收尾、worker cleanup 语义。
+
+## Requirements
+
+* 运行中的 fork/subagent 可以被显式停止
+* 结束后 worker 句柄、挂起状态、通知状态都要正确收尾
+* 失败路径不能留下半死状态
+
+## Acceptance Criteria
+
+* [ ] stop/kill 行为有明确 contract
+* [ ] cleanup 不遗漏活跃 worker 句柄
+* [ ] 失败/终止状态可恢复、可观察
diff --git a/.trellis/tasks/archive/2026-04/04-19-l4c-h12-abort-cleanup-and-kill-semantics/task.json b/.trellis/tasks/archive/2026-04/04-19-l4c-h12-abort-cleanup-and-kill-semantics/task.json
new file mode 100644
index 000000000..6a9456869
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-l4c-h12-abort-cleanup-and-kill-semantics/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l4c-h12-abort-cleanup-and-kill-semantics",
+  "name": "l4c-h12-abort-cleanup-and-kill-semantics",
+  "title": "L4-c: H12 abort cleanup and kill semantics",
+  "description": "Add explicit stop/cleanup/kill behavior for background fork and subagent runs.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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-19-h12-completion-pack-implementation-plan",
+  "relatedFiles": [],
+  "notes": "Completed bounded stop/cleanup/kill semantics for background subagent and background fork runs, including terminal cancelled state and worker-handle cleanup.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-19-l4d-h12-resume-and-path-hardening/prd.md b/.trellis/tasks/archive/2026-04/04-19-l4d-h12-resume-and-path-hardening/prd.md
new file mode 100644
index 000000000..6cdeaa988
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-l4d-h12-resume-and-path-hardening/prd.md
@@ -0,0 +1,17 @@
+# L4-d: H12 resume and path hardening
+
+## Goal
+
+让 H12 在恢复、路径变化、worktree 漂移这些长任务场景下更可靠。
+
+## Requirements
+
+* fork/subagent resume 要对 path/worktree drift 更稳
+* 恢复时保持单一显式 fork surface
+* 不为旧 resume state 做桥接兼容
+
+## Acceptance Criteria
+
+* [ ] 路径/工作区变化下 resume 行为更稳
+* [ ] resume 失败有明确错误，不静默 fallback
+* [ ] 新恢复 contract 不依赖旧数据兼容层
diff --git a/.trellis/tasks/archive/2026-04/04-19-l4d-h12-resume-and-path-hardening/task.json b/.trellis/tasks/archive/2026-04/04-19-l4d-h12-resume-and-path-hardening/task.json
new file mode 100644
index 000000000..bf12ea905
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-l4d-h12-resume-and-path-hardening/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "l4d-h12-resume-and-path-hardening",
+  "name": "l4d-h12-resume-and-path-hardening",
+  "title": "L4-d: H12 resume and path hardening",
+  "description": "Harden resume, worktree/path drift handling, and fork continuity recovery without compatibility shims.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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-19-h12-completion-pack-implementation-plan",
+  "relatedFiles": [],
+  "notes": "Completed resume/path hardening for subagent and fork threads with explicit workdir mismatch failures and no compatibility shims for old resume state.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-19-minimal-web-ui-frontend-gateway/check.jsonl b/.trellis/tasks/archive/2026-04/04-19-minimal-web-ui-frontend-gateway/check.jsonl
new file mode 100644
index 000000000..1422d008e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-minimal-web-ui-frontend-gateway/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": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-19-minimal-web-ui-frontend-gateway/debug.jsonl b/.trellis/tasks/archive/2026-04/04-19-minimal-web-ui-frontend-gateway/debug.jsonl
new file mode 100644
index 000000000..c1b287771
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-minimal-web-ui-frontend-gateway/debug.jsonl
@@ -0,0 +1,2 @@
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-19-minimal-web-ui-frontend-gateway/implement.jsonl b/.trellis/tasks/archive/2026-04/04-19-minimal-web-ui-frontend-gateway/implement.jsonl
new file mode 100644
index 000000000..2051c425a
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-minimal-web-ui-frontend-gateway/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": ".trellis/spec/frontend/index.md", "reason": "Frontend development guide"}
+{"file": ".trellis/spec/backend/directory-structure.md", "reason": "Gateway route belongs in frontend app adapter, not runtime"}
+{"file": ".trellis/spec/backend/error-handling.md", "reason": "HTTP boundary errors stay concise"}
+{"file": ".trellis/spec/frontend/quality-guidelines.md", "reason": "Focused frontend and gateway validation"}
diff --git a/.trellis/tasks/archive/2026-04/04-19-minimal-web-ui-frontend-gateway/prd.md b/.trellis/tasks/archive/2026-04/04-19-minimal-web-ui-frontend-gateway/prd.md
new file mode 100644
index 000000000..c6f551307
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-minimal-web-ui-frontend-gateway/prd.md
@@ -0,0 +1,66 @@
+# minimal web ui over frontend gateway
+
+## Goal
+
+为 `coding-deepgent ui-gateway` 增加一个最小可用的 HTML/Web 页面，不引入复杂前端构建体系，只验证浏览器能提交 prompt、连接 SSE、并展示基础事件流。
+
+## Requirements
+
+* 使用现有 `FrontendRunService` / `MemoryStreamBridge` / `adapters.sse`。
+* 页面应通过 `POST /api/runs` 创建 run，并通过 `EventSource` 连接 `/api/runs/{run_id}/stream`。
+* 展示基础事件：
+  * user message
+  * assistant deltas/final message
+  * tool started/finished/failed
+  * runtime events
+  * todo snapshot
+  * recovery brief
+  * permission request visibility
+  * run finished / failed
+* 不实现真正的 HTML/Web HITL gating。
+* 不引入 Next/React 页面构建。
+
+## Acceptance Criteria
+
+* [x] `ui-gateway` 提供 `/ui` 页面。
+* [x] 浏览器页可通过 SSE 展示基础事件。
+* [x] Gateway 与 CLI 继续解耦。
+* [x] Focused Python tests 覆盖 gateway health/run stream/UI route。
+
+## Out of Scope
+
+* 复杂浏览器应用框架。
+* 认证、持久线程列表、复杂布局。
+* 真正的 permission HITL 执行控制。
+
+## Implementation Checkpoint
+
+State:
+
+* terminal
+
+Verdict:
+
+* APPROVE
+
+Implemented:
+
+* Added product web shell at `coding-deepgent/frontend/web/index.html`.
+* Added `coding_deepgent.frontend.web.load_web_ui_html()`.
+* Added `/ui` route to the frontend gateway.
+* The page now:
+  * submits prompts via `POST /api/runs`
+  * joins runs through `EventSource(/api/runs/{run_id}/stream)`
+  * renders user, assistant, tool, runtime, todo, recovery, and permission-visibility state
+* Permission display is explicitly non-authoritative in the page copy because true runtime HITL is not wired.
+
+## Verification
+
+* `pytest -q tests/frontend/test_frontend_gateway.py tests/frontend/test_stream_bridge.py tests/frontend/test_frontend_runs.py tests/frontend/test_frontend_sse.py tests/frontend/test_frontend_client.py tests/frontend/test_frontend_protocol.py tests/frontend/test_frontend_bridge.py tests/frontend/test_frontend_event_mapping.py tests/structure/test_structure.py tests/cli/test_cli.py` -> 56 passed.
+* `ruff check src/coding_deepgent/frontend src/coding_deepgent/cli.py tests/frontend/test_frontend_gateway.py tests/frontend/test_stream_bridge.py tests/frontend/test_frontend_runs.py tests/frontend/test_frontend_sse.py tests/frontend/test_frontend_client.py tests/structure/test_structure.py tests/cli/test_cli.py` -> passed.
+* `mypy src/coding_deepgent/frontend` -> passed.
+
+## Architecture
+
+* Browser UI consumes the SSE gateway, not the CLI JSONL adapter.
+* CLI, embedded client, and browser now each have their own adapter over the shared producer/runtime foundation.
diff --git a/.trellis/tasks/archive/2026-04/04-19-minimal-web-ui-frontend-gateway/task.json b/.trellis/tasks/archive/2026-04/04-19-minimal-web-ui-frontend-gateway/task.json
new file mode 100644
index 000000000..053b378cb
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-minimal-web-ui-frontend-gateway/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "minimal-web-ui-frontend-gateway",
+  "name": "minimal-web-ui-frontend-gateway",
+  "title": "minimal web ui over frontend gateway",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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/archive/2026-04/04-19-next-subagent-planning/prd.md b/.trellis/tasks/archive/2026-04/04-19-next-subagent-planning/prd.md
new file mode 100644
index 000000000..3acaeb1fa
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-next-subagent-planning/prd.md
@@ -0,0 +1,181 @@
+# brainstorm: next subagent planning
+
+## Goal
+
+在 batch1/batch2 之后，决定 `coding-deepgent` 子 agent 主线下一步应该推进哪一类能力，并把它收束成一条清晰的后续实现方向，而不是同时打开 H12 深化、H13 mailbox、H14 coordinator 三条线。
+
+## What I already know
+
+* 当前 canonical roadmap 里：
+  * `H11 Agent as tool and runtime object` = `implemented`
+  * `H12 Fork/cache-aware subagent execution` = `implemented-minimal`
+  * `H13 Mailbox / SendMessage` = `deferred`
+  * `H14 Coordinator keeps synthesis` = `deferred`
+* 本地最近两批已完成的方向是：
+  * batch1: `max_turns` / model routing / built-in catalog / local custom agents / fork continuity / resume foundation
+  * batch2: background subagent runtime / progress + notification / queued follow-up input / plugin-provided agents
+* 现有 repo 和 spec 已经明确：
+  * background subagent runs 现在是 bounded local slice
+  * 还不是 mailbox / coordinator / team runtime
+  * 若要继续做 team execution，必须走新的 task/subagent spec，而不是继续往 `run_subagent` 上叠字符串参数
+* 现有 H11/H12 source-backed research 里，下一层尚未充分对齐的主要块是：
+  * async lifecycle deeper details: abort cascade / cleanup inventory / kill semantics
+  * richer fork/cache parity: byte-identical prefix, cache-safe summary/fork reuse
+  * H13 mailbox / SendMessage
+  * H14 coordinator synthesis
+
+## Assumptions (temporary)
+
+* 用户现在说“去计划”，指的是规划下一阶段，而不是立刻继续编码。
+* 当前最有价值的规划不是列一大串 backlog，而是先决定下一条主线。
+* 选择会直接影响后续 task topology，因此应该先做方向收敛。
+
+## Open Questions
+
+* （resolved）H12 做完时继续只保留显式 `run_fork`，不额外加入隐式一键分叉入口。
+
+## Requirements (evolving)
+
+* 输出应明确给出 2–3 条下一阶段可选路线。
+* 每条路线都要说明：
+  * 解决什么问题
+  * 为什么现在值得做
+  * 对后续 H13/H14 的影响
+  * 主要风险
+* 推荐顺序应基于当前 repo 已有基础，而不是抽象上“更高级”。
+* 最终要收敛成一条下一步主线。
+* 用户已选择：下一阶段继续深化 H12，而不是切到 H13/H14。
+* 用户已选择：H12 下一条切片采用 `completion pack`，不拆成单独的 background-fork 或 summary-only 路线。
+* 用户已选择：不需要兼容旧方案或旧数据，应优先长远干净边界。
+* 用户已进一步选择：这条线按最大完成度收口，包含后台分支、自动状态、收尾、停止、恢复稳健性、路径/工作区稳健性。
+* 用户已选择：入口层继续只保留显式 `run_fork`，不新增隐式 fork 入口。
+
+## Acceptance Criteria (evolving)
+
+* [ ] 能给出 2–3 条具体路线，而不是泛泛 backlog。
+* [ ] 能说明每条路线和当前 H11/H12/H13/H14 边界的关系。
+* [ ] 能明确给出推荐路线和理由。
+* [ ] 能通过一个单选问题收敛方向。
+* [ ] 能在 H12 路线下继续收敛出第一条实现切片。
+* [ ] 能在 `H12 completion pack` 下继续收敛出明确 scope boundary。
+* [x] 能在“最大完成度收口”前提下收敛出最后一个入口层决定。
+
+## Definition of Done (team quality bar)
+
+* 结论基于当前 roadmap、现有 batch1/batch2、和已有 H11/H12 research。
+* 不把 H13/H14 当成“默认下一步”，除非能说明为什么当前基础已经足够。
+* 明确列出 out-of-scope，避免一次打开多条高耦合主线。
+* 用户已选方向要立即记录进 PRD，而不是停留在会话里。
+* 用户已明确“不需要兼容旧方案/旧数据”，所以后续方案应默认允许直接替换旧局部抽象。
+* 用户已明确要按更完整交付收口，而不是先做最小可用版。
+* 用户已明确继续只保留显式 `run_fork`，因此实现不应分散到多种 fork 入口形态。
+
+## Out of Scope (explicit)
+
+* 本轮不直接改代码。
+* 不再并行规划 H13/H14 的完整实施细节。
+* 不重新审计全部 H01-H22。
+
+## Technical Notes
+
+* Local docs inspected:
+  * `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+  * `.trellis/tasks/04-16-cc-highlight-alignment-discussion/h11-h12-alignment-research.md`
+  * `.trellis/tasks/04-17-l5b-deferred-boundary-adr-refresh/prd.md`
+  * `.trellis/tasks/04-18-subagent-batch1-parity-implementation-plan/prd.md`
+  * `.trellis/tasks/04-19-subagent-batch2-runtime-implementation-plan/prd.md`
+  * `.trellis/spec/backend/project-infrastructure-foundation-contracts.md`
+  * `.trellis/spec/backend/task-workflow-contracts.md`
+
+## Research Notes
+
+### Constraints from our repo/project
+
+* H11 已经不是“有没有 subagent”，而是已经有真实 runtime、resume、background local runs。
+* H12 还是 minimal，不适合直接宣称 full parity。
+* foundation contracts 明确禁止把 mailbox/coordinator/team semantics 继续堆进 `run_subagent`。
+* 这意味着若切 H13/H14，要有新的 surface，而不是继续 patch `run_subagent`.
+
+### Feasible approaches here
+
+**Approach A: 继续深化 H12 / lifecycle correctness** (Recommended)
+
+* How it works:
+  * 继续留在 H11/H12 线，补最接近现有基础的缺口：
+    * background fork workers
+    * abort / cleanup / kill semantics
+    * cache-safe summary / fork reuse
+* Pros:
+  * 复用当前 batch1/batch2 已铺好的 runtime/seams
+  * 风险最低
+  * 能把“已有很多功能点”收成更可靠的一条线
+* Cons:
+  * 仍然没有真正进入多 agent 协作
+  * 用户感知的新范式不如 mailbox/coordinator 大
+
+**Approach B: 正式切到 H13 mailbox / SendMessage**
+
+* How it works:
+  * 新开 task-linked mailbox store + 显式 message surface
+  * 让多个 subagent 之间能发消息，但暂时不做 coordinator
+* Pros:
+  * 真正跨进 multi-agent readiness
+  * 给后续 H14 coordinator 打底
+* Cons:
+  * 需要新 surface/new spec，不是当前 `run_subagent` 上的小延伸
+  * 容易把 scope 拉大
+
+**Approach C: 直接规划 H14 coordinator**
+
+* How it works:
+  * 先定义 coordinator/worker 拓扑、汇总职责、任务分工边界
+  * mailbox 作为 coordinator 依赖面一起规划
+* Pros:
+  * 直接面对最终多 agent 架构
+  * 长期路线最清楚
+* Cons:
+  * 以当前基础看最容易变成高层设计先行
+  * 没有 mailbox 作为中间层时，落地风险最大
+
+## Decision (ADR-lite)
+
+**Context**: batch1/batch2 已经把 H11 和 H12 minimal slice 做到一个足够可继续深化的阶段，但 foundation contracts 仍明确要求不要把 mailbox/coordinator/team semantics 继续堆进 `run_subagent`。
+
+**Decision**: 下一阶段优先继续深化 H12，不切到 H13 mailbox，也不先做 H14 coordinator 规划。
+
+**Consequences**:
+
+* 近期会优先补 fork/cache-aware execution 和 fork lifecycle correctness。
+* H13/H14 继续维持 deferred，不在这一步并行打开。
+* 用户已进一步选择 `H12 completion pack`，即 background fork workers 和 cache-safe summary / fork reuse 一起推进。
+* 后续实现可以直接替换旧局部设计，不要求为旧方案/旧数据加桥接层。
+* 用户已进一步要求按更完整交付收口，因此这包默认还包含 abort / cleanup / kill semantics 与 resume/path hardening。
+* 用户已进一步选择继续只保留显式 `run_fork`，因此 H12 收口将聚焦单一 fork surface，而不是双入口并存。
+
+## Technical Approach
+
+下一阶段以 `H12 completion pack` 为单一实现主线，范围包括：
+
+* background fork workers
+* cache-safe summary / fork reuse
+* abort / cleanup / kill semantics
+* resume / path / worktree hardening
+
+并保持两条硬边界：
+
+* 不为旧方案或旧数据增加兼容层
+* 不新增隐式 fork 入口，继续只保留显式 `run_fork`
+
+## Expansion Sweep
+
+1. Future evolution
+* 如果很快会做多 agent，当前选择应避免把 H12 patch 成伪 coordinator。
+* 如果短期仍想先打牢 runtime，应该继续沿 H11/H12 的 lifecycle/correctness 线收敛。
+
+2. Related scenarios
+* background fork workers 和 cache-safe summary 是当前 batch2 的自然延伸。
+* mailbox / SendMessage 一旦进入，就会牵动 task store、state model、runtime surface。
+
+3. Failure / edge cases
+* 如果过早进入 H13/H14，容易把 `run_subagent` 扭成一层临时兼容壳。
+* 如果只继续补 H12，也要避免永远停留在“更完整的单机 child runtime”而不进入真正协作。
diff --git a/.trellis/tasks/archive/2026-04/04-19-next-subagent-planning/task.json b/.trellis/tasks/archive/2026-04/04-19-next-subagent-planning/task.json
new file mode 100644
index 000000000..309b6ec43
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-next-subagent-planning/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "next-subagent-planning",
+  "name": "next-subagent-planning",
+  "title": "brainstorm: next subagent planning",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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-18-compare-subagent-vs-cc-gap",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-19-post-cli-frontend-v1-roadmap/check.jsonl b/.trellis/tasks/archive/2026-04/04-19-post-cli-frontend-v1-roadmap/check.jsonl
new file mode 100644
index 000000000..67d7778a5
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-post-cli-frontend-v1-roadmap/check.jsonl
@@ -0,0 +1,8 @@
+{"file": ".gemini/commands/trellis/finish-work.toml", "reason": "Finish work checklist"}
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
+{"file": ".trellis/spec/frontend/state-management.md", "reason": "React/Ink reducer state ownership"}
+{"file": ".trellis/spec/guides/staged-execution-guide.md", "reason": "Integrated staged execution checkpoints"}
+{"file": ".trellis/spec/frontend/quality-guidelines.md", "reason": "Frontend validation commands"}
+{"file": ".trellis/spec/frontend/type-safety.md", "reason": "Protocol type sync across Python and TS"}
+{"file": ".trellis/spec/backend/langchain-native-guidelines.md", "reason": "Streaming and HITL runtime seam boundaries"}
diff --git a/.trellis/tasks/archive/2026-04/04-19-post-cli-frontend-v1-roadmap/debug.jsonl b/.trellis/tasks/archive/2026-04/04-19-post-cli-frontend-v1-roadmap/debug.jsonl
new file mode 100644
index 000000000..c1b287771
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-post-cli-frontend-v1-roadmap/debug.jsonl
@@ -0,0 +1,2 @@
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-19-post-cli-frontend-v1-roadmap/implement.jsonl b/.trellis/tasks/archive/2026-04/04-19-post-cli-frontend-v1-roadmap/implement.jsonl
new file mode 100644
index 000000000..59b849f09
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-post-cli-frontend-v1-roadmap/implement.jsonl
@@ -0,0 +1,7 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": ".trellis/spec/frontend/index.md", "reason": "Frontend development guide"}
+{"file": ".trellis/spec/guides/staged-execution-guide.md", "reason": "Integrated staged execution checkpoints"}
+{"file": ".trellis/spec/frontend/state-management.md", "reason": "React/Ink reducer state ownership"}
+{"file": ".trellis/spec/backend/langchain-native-guidelines.md", "reason": "Streaming and HITL runtime seam boundaries"}
+{"file": ".trellis/spec/frontend/type-safety.md", "reason": "Protocol type sync across Python and TS"}
diff --git a/.trellis/tasks/archive/2026-04/04-19-post-cli-frontend-v1-roadmap/prd.md b/.trellis/tasks/archive/2026-04/04-19-post-cli-frontend-v1-roadmap/prd.md
new file mode 100644
index 000000000..4e566b9fd
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-post-cli-frontend-v1-roadmap/prd.md
@@ -0,0 +1,765 @@
+# brainstorm: post CLI frontend v1 roadmap
+
+## Goal
+
+在 `coding-deepgent` CLI 前端 v1 已完成后，决定下一阶段前端/交互工作的优先级：是先让现有 CLI 更实时、更安全，还是转向 Web 端、打包发布或更深 cc parity。
+
+## What I already know
+
+* 用户询问“后续?”，需要路线选择而不是立即实现。
+* CLI frontend v1 已完成：React/Ink CLI + Python JSONL bridge + fake mode + protocol/reducer/components/tests。
+* 当前 CLI v1 已支持：prompt input、message list、spinner/status、todo panel、recovery brief、permission panel 协议、runtime/tool/todo/session event rendering。
+* 已验证：
+  * `pytest -q tests/cli/test_cli.py tests/runtime/test_runtime_events.py tests/frontend/test_frontend_protocol.py tests/frontend/test_frontend_bridge.py tests/frontend/test_frontend_event_mapping.py tests/structure/test_structure.py` -> 40 passed
+  * `ruff check ...` -> passed
+  * `mypy src/coding_deepgent/frontend src/coding_deepgent/__init__.py` -> passed
+  * `npm --prefix coding-deepgent/frontend/cli run typecheck` -> passed
+  * `npm --prefix coding-deepgent/frontend/cli test` -> passed
+  * fake JSONL bridge smoke -> passed
+  * fake React/Ink PTY smoke -> passed
+* Current true gaps:
+  * Real bridge now prefers a true streaming runner by default and keeps explicit non-streaming fallback behind the existing bridge boundary.
+  * Permission UI/protocol exists, but Python permission runtime still treats `ask` as tool error rather than true HITL pause/resume.
+  * Browser Web app is not implemented.
+  * CLI package is dev-run capable but not polished as a single installed binary/distribution.
+  * Deeper cc parity such as transcript search, virtualized long history, slash commands, command palette, and richer tool rendering is deferred.
+
+## Assumptions (temporary)
+
+* CLI v1 is considered complete enough; “后续” should mean next product increment, not retroactively redefining CLI v1.
+* User likely wants the highest-leverage next step, not a slow checklist.
+* Since TypeScript/React is accepted, future Web can reuse TS protocol/types but should not parse terminal output.
+
+## Open Questions
+
+* CLI 完善阶段是否一口气覆盖 streaming + HITL + packaging + 核心 cc parity，还是分成多个内部 stage？
+
+## Requirements (evolving)
+
+* 后续计划必须建立在当前 JSONL protocol 和 React/Ink CLI 上。
+* 不应把 Web 或 cc parity 混进一个无边界的大任务，除非用户明确要一口气做。
+* 任何改变 Python runtime/session/tool boundary 的后续都必须有 focused Python tests。
+* 任何改变 protocol 的后续都必须同时更新 Python protocol、TS protocol、TS reducer 和协议文档。
+* 用户明确选择：先把 CLI 完善，再做 HTML/Web。
+* HTML/Web 在 CLI 完善完成前不进入实现范围。
+
+## Acceptance Criteria (evolving)
+
+* [x] 明确下一阶段主目标：CLI 完善优先。
+* [x] 明确哪些功能进入下一阶段，哪些继续排除。
+* [x] 形成可直接执行的一阶段计划。
+* [x] 识别需要更新的 specs/tests。
+
+## Definition of Done (team quality bar)
+
+* Tests added/updated where appropriate.
+* Lint / typecheck / CI green if implementation follows.
+* Docs/notes updated if behavior changes.
+* Rollout/rollback considered if risky.
+
+## Out of Scope (explicit)
+
+* 本 brainstorm 不直接实现代码。
+* 不重新打开 CLI v1 的已完成范围，除非发现实际 blocker。
+* HTML/Web viewer、SSE/WebSocket server、browser UI 暂不实现。
+
+## Research Notes
+
+### Constraints from current implementation
+
+* Python bridge: `coding_deepgent.frontend.producer.build_default_prompt_runner()` now prefers `_run_streaming_prompt()` and falls back to `cli_service.run_once` only when streaming is unavailable or explicitly disabled.
+* TS frontend: `frontend/cli/src/bridge/reducer.ts` already supports `assistant_delta` and permission queue.
+* Protocol docs already reserve `permission_decision`, `assistant_delta`, `runtime_event`, `tool_*`, `todo_snapshot`, and `recovery_brief`.
+* The old Python Typer CLI remains a backend/debug fallback.
+
+### Feasible next-stage approaches
+
+**Approach A: Real Streaming First** (Completed)
+
+* How: add a streaming bridge mode that maps LangChain/LangGraph `messages`, `updates`, and `custom` stream parts into existing `assistant_delta`, `tool_*`, and `runtime_event` events.
+* Outcome: this is now implemented in the current mainline and validated through focused Python/TS tests plus JSONL fake-bridge smoke.
+* Consequence: the next CLI completion decision should move to HITL permission and packaging/productization.
+
+**Approach B: HITL Permission First**
+
+* How: convert permission `ask` from “tool error visibility” into true pause/resume using LangGraph interrupts or a local pending-decision seam, then wire `permission_decision` from TS.
+* Pros: biggest safety/product correctness jump; matches cc permission UX more meaningfully.
+* Cons: harder boundary; requires checkpoint/persistence decision and careful tool execution ordering tests.
+
+**Approach C: Web Read-Only Viewer First**
+
+* How: add a minimal Web app or local server that consumes the same event stream as read-only session/run timeline.
+* Pros: proves future Web direction; likely easier if it starts read-only.
+* Cons: less useful than streaming/HITL if CLI still lacks real-time backend; adds server/transport scope.
+
+**Approach D: Packaging/Install Polish First**
+
+* How: create one command/wrapper for `coding-deepgent-ui`, lock install path, document setup, maybe wire npm script from repo root.
+* Pros: low risk, makes current CLI easier to use immediately.
+* Cons: does not improve runtime capability.
+
+**Approach E: Deep cc Parity First**
+
+* How: add transcript search, virtualized history, slash commands, command palette, richer tool renderers, themes.
+* Pros: closest to Claude Code feel.
+* Cons: many UI features depend on streaming/HITL and richer event data; risk of polishing around incomplete runtime feedback.
+
+## Expansion Sweep
+
+### Future evolution
+
+* In 1-3 months, the same protocol can back both React/Ink CLI and browser Web.
+* Streaming and HITL are the two runtime seams most worth preserving before investing in Web polish.
+
+### Related scenarios
+
+* CLI, Web, and future remote/IDE surfaces should all consume typed events, not terminal text.
+* Existing Typer commands should remain backend/debug fallbacks.
+
+### Failure and edge cases
+
+* Streaming can break tool-result pairing if deltas/tool updates are mapped incorrectly.
+* HITL can accidentally execute a tool before approval if permission ordering is not enforced.
+* Web transport can leak local session/tool data if auth/trust boundaries are not specified.
+
+## Proposed Recommendation
+
+推荐顺序：
+
+1. **CLI Completion Pack**: real streaming + HITL permission + packaging/start command + focused cc-like CLI polish.
+2. **Web/HTML**: only after CLI completion pack is validated.
+
+Within CLI Completion Pack:
+
+1. Real Streaming: completed in product code and validated on 2026-04-19.
+2. HITL Permission: next safety-critical step using the already-present permission panel/protocol.
+3. Packaging Polish: make the CLI easy to run once permission/runtime shape stabilizes.
+4. Core cc-like CLI polish: transcript/search/slash commands only where they rely on stable streaming/HITL data.
+
+## Validation Update (2026-04-19)
+
+Focused validation confirmed that the streaming bridge called out above is no
+longer a pending gap:
+
+* `coding_deepgent.frontend.producer` already contains `_run_streaming_prompt()`
+  plus the default streaming-first runner selection.
+* `coding_deepgent.frontend.protocol` and
+  `frontend/cli/src/bridge/protocol.ts` already share the
+  `assistant_delta` / `assistant_message` contract.
+* `frontend/cli/src/bridge/reducer.ts` already aggregates deltas by
+  `message_id`.
+* Validation run:
+  * `pytest -q tests/frontend/test_frontend_bridge.py tests/frontend/test_frontend_protocol.py tests/frontend/test_frontend_runs.py tests/frontend/test_frontend_client.py tests/frontend/test_frontend_gateway.py tests/frontend/test_stream_bridge.py` -> `19 passed`
+  * `npm --prefix coding-deepgent/frontend/cli test` -> `8 passed`
+  * `npm --prefix coding-deepgent/frontend/cli run typecheck` -> passed
+  * fake `ui-bridge --fake` smoke confirmed ordered `assistant_delta` then final `assistant_message`
+
+Specs/tests implicated by this stage:
+
+* `.trellis/spec/backend/langchain-native-guidelines.md`
+* `.trellis/spec/frontend/type-safety.md`
+* `.trellis/spec/frontend/quality-guidelines.md`
+* `tests/frontend/test_frontend_bridge.py`
+* `tests/frontend/test_frontend_protocol.py`
+* `frontend/cli/src/__tests__/reducer.test.ts`
+* `frontend/cli/src/__tests__/protocol.test.ts`
+
+## Candidate Next Task: HITL Permission Boundary
+
+### Goal
+
+Turn frontend-visible permission requests from the current error-style
+visibility into a true pause/resume boundary only if it can be done without
+replacing the LangChain/LangGraph-native runtime seam.
+
+### Acceptance Targets
+
+* `permission_requested` represents a real pending decision, not only a rendered
+  tool failure.
+* Approval or rejection resumes the run through a documented boundary.
+* If the current runtime cannot safely support this without deeper checkpoint
+  work, the task must stop with a recorded architecture boundary instead of
+  adding a fake local shim.
+
+### Planned Features
+
+* Trace the current permission `ask` path through Python runtime and frontend
+  protocol.
+* Decide whether LangGraph interrupt/checkpoint surfaces are sufficient.
+* Implement safe resume only if boundary remains clear and testable.
+* Otherwise, record the blocker and shift to packaging/productization.
+
+## Decision (ADR-lite)
+
+**Context**: CLI v1 exists and works through JSONL bridge, but real bridge is not streaming and permission approval is protocol/UI-ready only. User wants CLI completed before HTML/Web.
+
+**Decision**: Next product work should be a CLI Completion Pack. Do not start Web/HTML until CLI has real streaming, permission handling, and productized launch path.
+
+**Consequences**: Web waits longer, but when it starts it consumes a mature event protocol rather than forcing bridge redesign.
+
+## CLI Completion Pack Plan
+
+### Acceptance Targets
+
+* Assistant output streams live in the React/Ink CLI.
+* Tool/progress/runtime events are visible during a run, not only after completion.
+* Permission `ask` can be surfaced as an approval interaction; if true pause/resume requires a deeper LangGraph checkpoint decision, the plan must stop and record that boundary explicitly.
+* CLI can be started with a documented product command, not only a dev script.
+* Existing `ui-bridge --fake` remains deterministic for tests and demos.
+* Web/HTML remains out of scope.
+
+### Planned Features
+
+* Add real streaming bridge path with `assistant_delta`.
+* Add fake streaming runner and event-order tests.
+* Wire permission request/decision path as far as current runtime seam safely allows.
+* Add root/package command wrapper for `coding-deepgent-ui` or equivalent.
+* Improve core CLI ergonomics: clearer status footer, interrupted/failed states, unknown event fallback, useful startup diagnostics.
+
+### Planned Extensions
+
+* Browser Web/HTML.
+* SSE/WebSocket transport.
+* Deep transcript virtualization/search.
+* Full slash command catalog and command palette.
+
+## Remaining Preference Question
+
+CLI 完善阶段你希望怎么推进？
+
+1. **One integrated CLI Completion Pack** — 推荐；内部 stage 连续完成 streaming、permission、packaging、CLI polish。
+2. **Streaming-only first** — 更稳；先把实时输出打实，再单独做 HITL/packaging。
+3. **Packaging-first** — 先让当前 CLI 更容易使用，再补 runtime 能力。
+
+## Complete Implementation Plan: CLI Completion Pack
+
+### Execution Mode
+
+Use one integrated task with internal checkpoints.
+
+Mode: `lean`.
+
+Reason: the CLI frontend foundation already exists and is validated. The next
+work is strongly coupled around one protocol/bridge/UI surface, so repeatedly
+splitting visible tasks would create churn. Internal checkpoints still protect
+runtime boundaries.
+
+### Final Outcome
+
+After this pack, `coding-deepgent-ui` should feel like the default local CLI
+frontend, not a prototype wrapper.
+
+A user should be able to:
+
+* Start the CLI with one documented product command.
+* Submit multiple prompts.
+* Watch assistant output stream live.
+* See tool/progress/runtime events during execution.
+* See todo/session/recovery state update predictably.
+* Approve or reject permission requests when the runtime can safely pause.
+* Exit/intercept failures without raw stack traces or corrupt terminal state.
+* Continue using the old Typer commands as backend/debug fallbacks.
+
+HTML/Web remains explicitly out of scope until this is complete.
+
+### Acceptance Targets
+
+* `coding-deepgent-ui` or an equivalent documented command starts the React/Ink CLI from the repo without manually setting `PYTHONPATH`.
+* Real runs emit live `assistant_delta` events when the underlying runtime supports streaming.
+* Tool/progress events are emitted before run completion when available, not only after `run_once`.
+* Permission `ask` behavior is represented through `permission_requested`; true pause/resume is implemented only if it can be done without replacing LangChain/LangGraph seams.
+* Fake bridge mode covers streaming, tool, permission, failure, and interrupt scenarios deterministically.
+* Existing Python CLI command groups keep working.
+* Protocol docs, Python protocol models, TS protocol types, and reducer tests stay in sync.
+* Focused Python and TS validation passes.
+
+### Planned Features
+
+* Streaming event contract hardening:
+  * define ordering guarantees for `assistant_delta` and final `assistant_message`
+  * define when `run_finished` may fire
+  * define error behavior for partial streams
+* Python streaming bridge:
+  * add a streaming-capable prompt runner alongside current `run_once`
+  * map stream chunks to frontend events
+  * preserve explicit non-streaming fallback
+* Tool/progress visibility:
+  * map model/tool updates to `tool_started`, `tool_finished`, `tool_failed`, and `runtime_event`
+  * keep metadata bounded and secret-safe
+* Permission handling:
+  * emit `permission_requested` for ask decisions when possible
+  * wire `permission_decision` to runtime only if safe pause/resume is available
+  * otherwise record a precise blocker and keep visible ask/deny UI behavior
+* CLI polish:
+  * product command/wrapper
+  * better startup diagnostics
+  * clearer status footer
+  * interrupted/failed states
+  * unknown-event fallback row
+  * lightweight slash commands that do not require runtime changes, such as `/exit`, `/clear`, `/help`
+* Documentation and specs:
+  * update protocol docs
+  * update README usage
+  * update frontend quality/spec docs if conventions change
+
+### Planned Extensions
+
+* HTML/Web UI.
+* SSE/WebSocket transport.
+* Full LangGraph HITL persistence if it is larger than this pack.
+* Transcript virtualization/search.
+* Full slash-command catalog.
+* Command palette.
+* Rich tool-specific renderers for every tool family.
+* Installer/published package distribution beyond repo-local usage.
+
+### Out Of Scope For This Pack
+
+* Browser UI or HTML renderer.
+* Remote/IDE/daemon control plane.
+* Replacing LangChain/LangGraph runtime loops.
+* Copying cc `REPL.tsx` wholesale.
+* Provider-specific cache/cost UI.
+* Solving unrelated dirty worktree changes.
+
+## Stage Plan
+
+### Stage 0: Preflight And Baseline Lock
+
+Purpose: establish current green baseline and protect against unrelated dirty changes.
+
+Files likely read:
+
+* `coding-deepgent/src/coding_deepgent/frontend/*`
+* `coding-deepgent/frontend/cli/src/*`
+* `coding-deepgent/src/coding_deepgent/cli_service.py`
+* `coding-deepgent/src/coding_deepgent/agent_loop_service.py`
+* `coding-deepgent/src/coding_deepgent/agent_runtime_service.py`
+* `coding-deepgent/src/coding_deepgent/tool_system/middleware.py`
+* `.trellis/spec/frontend/*`
+* `.trellis/spec/backend/langchain-native-guidelines.md`
+
+Actions:
+
+* Confirm current tests still pass for frontend/bridge.
+* Identify unrelated dirty files that must not be touched.
+* Confirm package scripts work from repo root and package root.
+
+Validation:
+
+```bash
+pytest -q tests/frontend/test_frontend_protocol.py tests/frontend/test_frontend_bridge.py tests/frontend/test_frontend_event_mapping.py
+npm --prefix coding-deepgent/frontend/cli run typecheck
+npm --prefix coding-deepgent/frontend/cli test
+```
+
+Checkpoint:
+
+* `APPROVE` if current CLI v1 baseline is still green.
+* `STOP` if unrelated dirty changes directly conflict with bridge/runtime files.
+
+### Stage 1: Protocol And Fake Streaming Contract
+
+Purpose: make streaming behavior deterministic before touching real runtime.
+
+Actions:
+
+* Extend protocol docs with stream ordering:
+  * `assistant_delta` can repeat for one `message_id`
+  * `assistant_message` finalizes accumulated text
+  * `run_failed` may follow partial deltas
+  * `run_finished` closes a prompt turn
+* Extend fake bridge with streaming scenario support.
+* Add fake events for:
+  * assistant delta accumulation
+  * tool start/finish interleaving
+  * runtime progress event
+  * permission request/resolution
+  * failed run after partial output
+* Strengthen TS reducer tests for interleaved streams.
+
+Likely files:
+
+* `coding-deepgent/frontend/protocol/README.md`
+* `coding-deepgent/src/coding_deepgent/frontend/protocol.py`
+* `coding-deepgent/src/coding_deepgent/frontend/bridge.py`
+* `coding-deepgent/frontend/cli/src/bridge/protocol.ts`
+* `coding-deepgent/frontend/cli/src/bridge/reducer.ts`
+* `coding-deepgent/frontend/cli/src/__tests__/reducer.test.ts`
+* `coding-deepgent/tests/frontend/test_frontend_bridge.py`
+* `coding-deepgent/tests/frontend/test_frontend_protocol.py`
+
+Validation:
+
+* Python protocol/bridge tests.
+* TS protocol/reducer tests.
+* Fake PTY smoke for one streaming fixture if feasible.
+
+Checkpoint:
+
+* `APPROVE` if fake streaming contract is deterministic and UI handles it.
+
+### Stage 2: Real Streaming Bridge
+
+Purpose: make real CLI runs stream into the React/Ink frontend.
+
+Technical approach:
+
+* Prefer official LangChain/LangGraph streaming surfaces:
+  * `stream_mode=["messages", "updates", "custom"]`
+  * `version="v2"` if supported by the compiled agent path
+* Add a streaming prompt runner in `coding_deepgent.frontend.bridge`.
+* Keep existing non-streaming runner as explicit fallback, not hidden duplicate behavior.
+* Do not replace `agent_loop_service.run_agent_loop` unless the current seam cannot expose streaming.
+
+Event mapping:
+
+* `messages` text chunks -> `assistant_delta`
+* final assistant state -> `assistant_message`
+* tool/model updates -> `tool_*` or `runtime_event`
+* exceptions -> `run_failed`
+* state snapshot after completion -> `todo_snapshot`
+
+Likely files:
+
+* `coding-deepgent/src/coding_deepgent/frontend/bridge.py`
+* `coding-deepgent/src/coding_deepgent/frontend/event_mapping.py`
+* `coding-deepgent/src/coding_deepgent/agent_runtime_service.py`
+* `coding-deepgent/src/coding_deepgent/cli_service.py`
+* tests under `coding-deepgent/tests/frontend/test_frontend_bridge.py`
+
+Validation:
+
+* Fake streaming runner test.
+* Real-ish fake compiled-agent test if current runtime can be stubbed.
+* Existing `tests/cli/test_cli.py`.
+* No-network tests only.
+
+Stop condition:
+
+* If the compiled LangChain agent cannot stream without a larger runtime refactor, stop and split a prerequisite runtime streaming seam task.
+
+Checkpoint:
+
+* `APPROVE` if a real bridge path emits deltas without breaking existing `run_once`.
+* `ITERATE` if only a smaller streaming seam is needed locally.
+* `SPLIT` if this becomes a full runtime architecture change.
+
+### Stage 3: Tool/Progress Event Upgrade
+
+Purpose: make tool/progress visibility useful during execution.
+
+Actions:
+
+* Audit current `RuntimeEvent` emissions:
+  * tool guard allowed/completed/failed
+  * query_error
+  * token_budget
+  * compact/runtime pressure events
+* Map high-signal events to frontend events.
+* Avoid turning every log into a UI event.
+* Add UI row styles for:
+  * running tool
+  * completed tool
+  * failed/denied tool
+  * runtime warning/error
+
+Likely files:
+
+* `coding-deepgent/src/coding_deepgent/frontend/event_mapping.py`
+* `coding-deepgent/frontend/cli/src/components/message-row.tsx`
+* `coding-deepgent/frontend/cli/src/bridge/reducer.ts`
+* `coding-deepgent/tests/frontend/test_frontend_event_mapping.py`
+
+Validation:
+
+* Event mapping tests for allowed/completed/failed/permission_denied.
+* Reducer tests for status transitions.
+
+Checkpoint:
+
+* `APPROVE` if tool/progress rows are accurate and bounded.
+
+### Stage 4: Permission / HITL Boundary
+
+Purpose: complete permission UX as far as current runtime safely allows.
+
+Decision gate:
+
+* Inspect whether permission `ask` can pause before tool execution using current middleware/runtime.
+* If yes, implement a pending permission bridge flow.
+* If no, do not fake approval. Emit visible ask/deny event and create a separate HITL runtime task.
+
+Preferred implementation if feasible:
+
+* `ToolGuardMiddleware` emits `permission_requested`.
+* Python bridge waits for `permission_decision`.
+* Approved decision resumes tool execution.
+* Rejected decision returns model-visible bounded feedback.
+
+Required safety invariant:
+
+* No destructive tool executes before approval.
+
+Likely files:
+
+* `coding-deepgent/src/coding_deepgent/tool_system/middleware.py`
+* `coding-deepgent/src/coding_deepgent/permissions/*`
+* `coding-deepgent/src/coding_deepgent/frontend/bridge.py`
+* `coding-deepgent/frontend/cli/src/components/permission-panel.tsx`
+* `coding-deepgent/tests/permissions/test_permissions.py`
+* `coding-deepgent/tests/frontend/test_frontend_bridge.py`
+
+Validation:
+
+* Permission request event test.
+* Approval path test if implemented.
+* Rejection path test if implemented.
+* Existing permission tests.
+
+Stop condition:
+
+* Stop if true HITL requires persistent LangGraph checkpoint/resume semantics that are not already present.
+
+Checkpoint:
+
+* `APPROVE` if true approval is safely implemented.
+* `SPLIT` if a separate runtime HITL foundation is required.
+
+### Stage 5: CLI Product Entry And Packaging Polish
+
+Purpose: make the CLI easy to run after runtime behavior stabilizes.
+
+Actions:
+
+* Add repo-root or package-level script that starts the CLI without manual env setup.
+* Decide final command shape:
+  * `npm --prefix coding-deepgent/frontend/cli run dev`
+  * `coding-deepgent-ui`
+  * `coding-deepgent ui` wrapper
+* Add startup diagnostics:
+  * Node version
+  * Python bridge availability
+  * missing dependencies
+  * non-TTY explanation
+* Keep `ui-bridge --fake` for tests/demos.
+
+Likely files:
+
+* `coding-deepgent/frontend/cli/package.json`
+* `coding-deepgent/frontend/cli/src/index.tsx`
+* `coding-deepgent/frontend/cli/src/bridge/python-process.ts`
+* `coding-deepgent/README.md`
+* possibly root package/scripts if introduced
+
+Validation:
+
+* Non-TTY startup fails cleanly.
+* Fake TTY smoke.
+* README command works.
+
+Checkpoint:
+
+* `APPROVE` if a developer can start the CLI with one documented command.
+
+### Stage 6: Core CLI UX Polish
+
+Purpose: finish high-signal CLI polish without starting Web.
+
+Actions:
+
+* Improve status footer:
+  * running
+  * waiting for permission
+  * failed
+  * interrupted
+  * bridge disconnected
+* Add lightweight slash commands:
+  * `/exit`
+  * `/clear`
+  * `/help`
+  * possibly `/status`
+* Add unknown-event fallback display.
+* Improve recovery brief folding.
+* Improve message list readability for long outputs.
+
+Likely files:
+
+* `coding-deepgent/frontend/cli/src/app.tsx`
+* `coding-deepgent/frontend/cli/src/components/*`
+* `coding-deepgent/frontend/cli/src/bridge/reducer.ts`
+* TS tests under `src/__tests__`
+
+Validation:
+
+* Reducer tests for failure/interrupted/clear/help states.
+* TS typecheck/test.
+* Fake PTY smoke.
+
+Checkpoint:
+
+* `APPROVE` if CLI is usable for normal local work without obvious rough edges.
+
+### Stage 7: Final Verification And Documentation
+
+Purpose: close CLI Completion Pack and prepare for later HTML/Web.
+
+Actions:
+
+* Update PRD checkpoint.
+* Update README and protocol docs.
+* Update Trellis frontend specs if new conventions emerged.
+* Run focused final validation.
+
+Final validation target:
+
+```bash
+pytest -q tests/cli/test_cli.py tests/runtime/test_runtime_events.py tests/permissions/test_permissions.py tests/frontend/test_frontend_protocol.py tests/frontend/test_frontend_bridge.py tests/frontend/test_frontend_event_mapping.py tests/structure/test_structure.py
+ruff check <touched-python-files>
+mypy src/coding_deepgent/frontend src/coding_deepgent/__init__.py
+npm --prefix coding-deepgent/frontend/cli run typecheck
+npm --prefix coding-deepgent/frontend/cli test
+```
+
+Manual/PTY smoke:
+
+```bash
+npm --prefix coding-deepgent/frontend/cli run dev:fake
+```
+
+Terminal checkpoint:
+
+* `APPROVE` if all focused checks pass and Web/HTML follow-up has a clean start point.
+
+## Test Matrix
+
+### Python
+
+* `test_frontend_protocol.py`
+  * strict event/input validation
+  * extra fields rejected
+  * new event types round-trip
+* `test_frontend_bridge.py`
+  * prompt -> ordered events
+  * fake streaming deltas
+  * partial stream failure
+  * permission decision input
+  * exit/interrupt behavior
+* `test_frontend_event_mapping.py`
+  * runtime events -> frontend events
+  * tool guard phases
+  * todo snapshot filtering
+  * bounded metadata
+* Existing:
+  * `test_cli.py`
+  * `test_runtime_events.py`
+  * `test_permissions.py` when HITL changes
+
+### TypeScript
+
+* `protocol.test.ts`
+  * parse/encode new events
+  * unknown events rejected or surfaced safely
+* `reducer.test.ts`
+  * delta accumulation
+  * final assistant message replacement
+  * interleaved tool events
+  * permission queue
+  * failed/interrupted states
+  * slash command state if reducer-owned
+
+### Manual Smoke
+
+* fake interactive prompt and exit
+* non-TTY startup error
+* real bridge help command
+* if available, one live prompt with API credentials outside automated tests
+
+## Risk Matrix
+
+| Risk | Impact | Mitigation |
+|---|---|---|
+| LangChain compiled agent streaming is not compatible with current wrapper | Real streaming blocked | split a small runtime streaming seam task; keep fake streaming tests |
+| Tool/progress events become noisy | CLI becomes unreadable | whitelist high-signal events only |
+| Permission UI appears but does not actually gate execution | unsafe false confidence | do not claim true HITL unless no-execute-before-approval test passes |
+| Cross-process JSONL stdout gets polluted | frontend parser breaks | keep Python stdout event-only; logs stderr-only; tests cover protocol errors |
+| Packaging creates duplicated entrypoints | maintenance confusion | keep old Typer as backend/debug; document one preferred UI command |
+| Web pressure leaks into CLI pack | scope creep | Web/HTML explicitly out of scope until terminal checkpoint |
+
+## Stop Conditions
+
+Stop and ask before continuing if:
+
+* Real streaming requires replacing `agent_loop_service` or bypassing LangChain/LangGraph runtime seams.
+* HITL requires persistent checkpoint/resume semantics not already present.
+* Tests fail due to unrelated dirty subagent/runtime refactor files.
+* Packaging requires choosing a repo-wide package manager/workspace policy.
+* A change would make old Typer CLI commands unusable.
+
+## Proposed Implementation Order
+
+1. Stage 0: baseline lock.
+2. Stage 1: fake streaming contract.
+3. Stage 2: real streaming bridge.
+4. Stage 3: tool/progress event upgrade.
+5. Stage 4: permission/HITL boundary.
+6. Stage 5: product command/packaging.
+7. Stage 6: CLI UX polish.
+8. Stage 7: final verification/docs.
+
+## Final Confirmation
+
+完整计划建议采用 **One integrated CLI Completion Pack**，但内部按上面 8 个 stage 执行。Web/HTML 在全部 CLI 完善验收后再启动。
+
+如果确认，我下一步会把这个 planning task 进入 Task Workflow，并从 Stage 0 开始实施。
+
+## Implementation Checkpoint: CLI Completion Pack
+
+State:
+
+* terminal
+
+Verdict:
+
+* APPROVE
+
+Implemented:
+
+* Converted frontend bridge execution from batch-returned event lists to live event emission through an `EventEmitter`.
+* Added streaming-capable prompt runner path that maps LangChain/LangGraph-style `messages`, `updates`, `custom`, and `values` stream parts to frontend events.
+* Added fake streaming behavior for deterministic demos/tests: assistant deltas, tool start/finish, permission request, partial failure, todo snapshot, and recovery brief.
+* Added product command `coding-deepgent ui` and `coding-deepgent ui --fake` over the React/Ink CLI package.
+* Added `start` and `start:fake` package scripts.
+* Added local CLI slash commands `/help`, `/clear`, and retained `/exit`.
+* Improved status footer for permission/failure/status visibility.
+* Added reducer support for local UI actions and streaming/tool interleaving.
+* Added tests for streaming event order, partial failure, fake permission request, streaming part mapping, local commands, and product UI command invocation.
+* Updated protocol docs with ordering guarantees and the current HITL boundary.
+* Updated README and frontend specs with CLI completion commands and validation expectations.
+
+Verification:
+
+* `pytest -q tests/cli/test_cli.py tests/runtime/test_runtime_events.py tests/permissions/test_permissions.py tests/frontend/test_frontend_protocol.py tests/frontend/test_frontend_bridge.py tests/frontend/test_frontend_event_mapping.py tests/structure/test_structure.py` -> 56 passed.
+* `ruff check src/coding_deepgent/__init__.py src/coding_deepgent/frontend src/coding_deepgent/cli.py src/coding_deepgent/tool_system/middleware.py tests/frontend/test_frontend_protocol.py tests/frontend/test_frontend_bridge.py tests/frontend/test_frontend_event_mapping.py tests/cli/test_cli.py` -> passed.
+* `mypy src/coding_deepgent/frontend src/coding_deepgent/__init__.py` -> passed.
+* `npm --prefix coding-deepgent/frontend/cli run typecheck` -> passed.
+* `npm --prefix coding-deepgent/frontend/cli test` -> passed, 8 TS tests.
+* `PYTHONPATH=src python3 -m coding_deepgent ui --fake` in PTY -> prompt, streaming deltas, permission panel, approve, `/help`, `/clear`, `/exit` all worked.
+
+Architecture:
+
+* Streaming uses the existing frontend JSONL protocol and does not introduce HTTP/Web transport.
+* The real streaming path prefers official agent `.stream(...)` with stream modes `messages`, `updates`, `custom`, and `values`.
+* The old non-streaming path remains as fallback when the compiled agent stream surface is unavailable.
+* Python remains the runtime/session/tool owner; TypeScript remains display state owner.
+
+Boundary findings:
+
+* True HITL pause/resume is not implemented in this pass because current `ToolGuardMiddleware` is synchronous and returns a `ToolMessage` on `ask`; there is no safe pending-decision seam yet.
+* The UI/protocol can display and resolve permission prompts in fake mode, but real destructive-tool gating requires a dedicated runtime HITL foundation before it can be claimed.
+* HTML/Web remains out of scope and now has a stronger CLI/event protocol to build on.
+
+Decision:
+
+* CLI completion pack is complete enough to make HTML/Web the next product family if desired.
+* If safety is prioritized before Web, the next task should be dedicated runtime HITL pause/resume foundation.
diff --git a/.trellis/tasks/archive/2026-04/04-19-post-cli-frontend-v1-roadmap/task.json b/.trellis/tasks/archive/2026-04/04-19-post-cli-frontend-v1-roadmap/task.json
new file mode 100644
index 000000000..1bf1b0023
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-post-cli-frontend-v1-roadmap/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "post-cli-frontend-v1-roadmap",
+  "name": "post-cli-frontend-v1-roadmap",
+  "title": "brainstorm: post CLI frontend v1 roadmap",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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/archive/2026-04/04-19-r1-runtime-role-agent-factory-seam/prd.md b/.trellis/tasks/archive/2026-04/04-19-r1-runtime-role-agent-factory-seam/prd.md
new file mode 100644
index 000000000..5a7b6b32d
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-r1-runtime-role-agent-factory-seam/prd.md
@@ -0,0 +1,144 @@
+# R1: Runtime Role And Agent Factory Seam
+
+## Goal
+
+建立明确的 runtime role 与 agent factory seam，让 main/subagent/fork 的 agent construction 走统一、可测试、LangChain-native 的构造路径，为后续 H13 coordinator/worker role projection 做准备。
+
+## Requirements
+
+* 定义 runtime roles：`main`、`subagent`、`fork`，并为 future `coordinator`、`worker` 保留 contract 位置但不实现行为。
+* 将 child/fork agent construction 从 `subagents/tools.py` 的裸 `create_agent(...)` 调用迁移到新的 runtime factory seam。
+* 不保留旧 `subagents.tools.create_agent` monkeypatch/调用兼容桥接。
+* 迁移相关测试到新的 factory seam。
+* 保持现有 `run_subagent`、`run_fork`、`resume_subagent`、`resume_fork` public tool schema 和行为不变。
+
+## Acceptance Targets
+
+* [ ] main/subagent/fork agent construction 都能通过明确 factory seam 表达。
+* [ ] child/fork 不再依赖 `subagents.tools.create_agent` 作为主要构造入口。
+* [ ] 现有 H11/H12 行为保持不变。
+* [ ] 测试不再 monkeypatch `subagents.tools.create_agent`。
+* [ ] 无 mailbox/coordinator/team runtime 行为被实现。
+
+## Planned Features
+
+* 新增或重整 `runtime/agent_factory.py` / `runtime/roles.py` 等低层 seam。
+* 为 subagent/fork 调用点接入该 seam。
+* 更新 focused tests。
+
+## Detailed Implementation Plan
+
+### Target Design
+
+Introduce explicit runtime construction primitives without replacing LangChain:
+
+* `coding_deepgent.runtime.roles`
+  * Define a small role contract for agent construction.
+  * Required current roles: `main`, `subagent`, `fork`.
+  * Reserved future roles: `coordinator`, `worker`.
+  * The future roles are contract placeholders only; they must not enable H13/H14 behavior in R1.
+* `coding_deepgent.runtime.agent_factory`
+  * Own the single project-local path for `create_agent(...)` construction.
+  * Accept a typed build request/spec containing role, name, model, tools, system prompt, middleware, context schema, state schema if needed, checkpointer, and store.
+  * Delegate to official LangChain `create_agent`; do not introduce a custom query loop.
+* `coding_deepgent.agent_service`
+  * Main agent construction should call the same factory seam with role `main`.
+* `coding_deepgent.subagents`
+  * Child subagent construction should call the same factory seam with role `subagent`.
+  * Fork construction should call the same factory seam with role `fork`.
+
+### Required Code Changes
+
+* Add runtime role/factory modules under `coding-deepgent/src/coding_deepgent/runtime/`.
+* Update `runtime/__init__.py` exports only if it improves product API clarity.
+* Update `agent_service.create_compiled_agent(...)` to delegate construction to the new factory.
+* Update `_execute_child_subagent(...)`, `_execute_fork_subagent(...)`, `resume_subagent_task(...)`, and `resume_fork_task(...)` construction paths to use the new factory seam.
+* Remove direct `subagents.tools.create_agent` dependency as a test seam.
+* Update tests to monkeypatch/inject the new runtime factory seam directly.
+
+### Test Migration Rules
+
+* Do not keep `subagents.tools.create_agent` as a compatibility monkeypatch target.
+* Tests that currently monkeypatch `subagent_tools.create_agent` must move to the new factory seam.
+* Prefer tests that assert the build request role/name/tools/middleware/context rather than relying only on fake agent return text.
+* Keep behavior tests for returned envelopes, thread ids, sidechain records, and resume unchanged.
+
+### Focused Verification
+
+* `pytest -q coding-deepgent/tests/subagents/test_subagents.py`
+* `pytest -q coding-deepgent/tests/runtime/test_agent_runtime_service.py coding-deepgent/tests/runtime/test_app.py`
+* `ruff check <touched files>`
+* `mypy <touched typed runtime/subagent/test files>` where practical.
+
+### Checkpoint Requirements
+
+At R1 checkpoint, record:
+
+* Whether all direct subagent/fork `create_agent(...)` calls now go through the runtime factory.
+* Whether tests no longer monkeypatch `subagents.tools.create_agent`.
+* Whether any bridge/fallback was introduced. Expected answer: no.
+* Whether R2 can safely split `subagents/tools.py` without changing the construction seam again.
+
+## Planned Extensions
+
+* R2 拆分 subagent domain responsibility。
+* R3 background run service hardening。
+* H13 coordinator/worker tool projection。
+
+## Definition of Done
+
+* Focused subagent/fork tests pass.
+* Relevant ruff/mypy checks pass for touched files.
+* PRD checkpoint records changed seams and residual risks.
+
+## Out of Scope
+
+* 不拆分整个 `subagents/tools.py` 文件结构。
+* 不实现 mailbox、Scratchpad、Coordinator、Worker team runtime。
+* 不新增旧 factory bridge/fallback。
+* 不 change public tool schemas for `run_subagent`, `run_fork`, `resume_subagent`, or `resume_fork`.
+* 不 introduce a separate non-LangChain runtime executor.
+
+## Technical Notes
+
+* Parent: `.trellis/tasks/04-19-runtime-architecture-refactor-plan/prd.md`
+* Key files likely touched:
+  * `coding-deepgent/src/coding_deepgent/runtime/`
+  * `coding-deepgent/src/coding_deepgent/agent_service.py`
+  * `coding-deepgent/src/coding_deepgent/subagents/tools.py`
+  * `coding-deepgent/src/coding_deepgent/runtime/__init__.py`
+  * `coding-deepgent/tests/subagents/test_subagents.py`
+  * `coding-deepgent/tests/runtime/test_app.py`
+  * `coding-deepgent/tests/runtime/test_agent_runtime_service.py`
+
+## Checkpoint: R1
+
+State:
+* verifying
+
+Verdict:
+* APPROVE
+
+Implemented:
+* Added explicit runtime role contract and runtime agent factory seam.
+* Main agent construction now delegates through the runtime factory seam.
+* Subagent and fork construction now delegate through the runtime factory seam.
+* Tests now patch `coding_deepgent.runtime.agent_factory.create_runtime_agent` instead of `subagents.tools.create_agent`.
+
+Verification:
+* `pytest -q coding-deepgent/tests/subagents/test_subagents.py coding-deepgent/tests/runtime/test_agent_runtime_service.py coding-deepgent/tests/runtime/test_app.py`
+* Result: `62 passed`
+
+Architecture:
+* primitive used: official LangChain `create_agent` behind a project-local factory seam.
+* why no heavier abstraction: R1 only normalizes construction ownership; it does not add a custom executor or graph runtime.
+
+Boundary findings:
+* No mailbox/coordinator/team runtime behavior was introduced.
+* No compatibility bridge for `subagents.tools.create_agent` was retained.
+
+Decision:
+* continue
+
+Reason:
+* R1 acceptance targets are satisfied and R2 can now split `subagents/tools.py` without changing the construction seam again.
diff --git a/.trellis/tasks/archive/2026-04/04-19-r1-runtime-role-agent-factory-seam/task.json b/.trellis/tasks/archive/2026-04/04-19-r1-runtime-role-agent-factory-seam/task.json
new file mode 100644
index 000000000..c7e84359f
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-r1-runtime-role-agent-factory-seam/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "r1-runtime-role-agent-factory-seam",
+  "name": "r1-runtime-role-agent-factory-seam",
+  "title": "R1 runtime role and agent factory seam",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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-19-runtime-architecture-refactor-plan",
+  "relatedFiles": [],
+  "notes": "Completed R1: introduced runtime roles and runtime agent factory seam; main/subagent/fork construction now routes through the seam without retaining subagents.tools.create_agent compatibility.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-19-r2-split-subagent-domain-responsibilities/prd.md b/.trellis/tasks/archive/2026-04/04-19-r2-split-subagent-domain-responsibilities/prd.md
new file mode 100644
index 000000000..4aa694cd6
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-r2-split-subagent-domain-responsibilities/prd.md
@@ -0,0 +1,147 @@
+# R2: Split Subagent Domain Responsibilities
+
+## Goal
+
+拆分 `subagents` domain 的职责边界，避免 `subagents/tools.py` 同时承担 definition/catalog、execution、fork payload、resume/sidechain、tool wrappers 和 background lifecycle，为后续 H13/H14 提供可组合的稳定内部 API。
+
+## Dependencies
+
+* Depends on R1 runtime role and agent factory seam.
+
+## Requirements
+
+* 将 `subagents/tools.py` 按真实职责拆分为更小模块。
+* 保持 public tool names、tool schemas、`subagents/__init__.py` exports 稳定。
+* 不引入 compatibility bridge 保护旧内部模块布局。
+* 不改变 H11/H12 user-visible behavior。
+
+## Acceptance Targets
+
+* [ ] `subagents/tools.py` 不再是所有 subagent/fork/resume/sidechain 逻辑的集中承载文件。
+* [ ] Public tools: `run_subagent`、`run_fork`、`resume_subagent`、`resume_fork`、background controls 保持 schema 不变。
+* [ ] Internal modules 有清晰 ownership：definitions、execution、forking、resume、sidechain、tool wrappers。
+* [ ] Existing focused subagent/fork/background tests pass.
+
+## Planned Features
+
+* 拆分职责模块，例如：
+  * `definitions.py`
+  * `execution.py`
+  * `forking.py`
+  * `resume.py`
+  * `sidechain.py`
+  * `tool_wrappers.py`
+* 更新 imports 和 tests。
+
+## Detailed Implementation Plan
+
+### Target Module Ownership
+
+Use concrete module ownership to prevent `subagents/tools.py` from becoming the coordination dumping ground again:
+
+* `subagents/definitions.py`
+  * Built-in definitions, local/plugin definition resolution, validation, child tool allowlists.
+* `subagents/execution.py`
+  * Synchronous child execution and result metrics for standard subagents.
+* `subagents/forking.py`
+  * Fork-specific payload construction, prompt/tool fingerprinting, placeholder layout, recursion guard, fork execution.
+* `subagents/sidechain.py`
+  * Parent ledger sidechain persistence, sidechain metadata merge, message reconstruction helpers.
+* `subagents/resume.py`
+  * Resume task flows for subagents and forks, including workdir/prompt/tool fingerprint checks.
+* `subagents/tool_wrappers.py`
+  * LangChain `@tool` wrappers and public JSON envelope shaping.
+* `subagents/background.py`
+  * Keep background service here until R3; do not fold it into `tool_wrappers.py`.
+
+Exact filenames may adjust during implementation, but each final module must have one strong responsibility.
+
+### Required Code Changes
+
+* Move internal helpers out of `subagents/tools.py` by responsibility.
+* Keep `subagents/__init__.py` as the stable public export layer.
+* Keep public tool names and Pydantic schemas stable.
+* Keep behavior for built-in definitions, local repo definitions, plugin definitions, verifier plan requirement, sidechain recording, fork recursion guard, and resume hardening.
+* Update imports in tests to use public exports or new internal modules only when the test is specifically about that internal module.
+
+### Anti-Regression Rules
+
+* Do not create compatibility alias modules that exist only to preserve old internal imports.
+* Do not move background execution into the same module as public tool wrappers.
+* Do not hide sidechain persistence in sessions or runtime packages; it remains subagent-owned but writes through the session store seam.
+* Do not change public JSON envelope field names.
+
+### Focused Verification
+
+* `pytest -q coding-deepgent/tests/subagents/test_subagents.py`
+* `pytest -q coding-deepgent/tests/tool_system/test_tool_system_registry.py coding-deepgent/tests/tool_system/test_tool_search.py`
+* Import smoke checks through `coding_deepgent.subagents`.
+* `ruff check <touched subagent/test files>`
+* `mypy <touched subagent/test files>` where practical.
+
+### Checkpoint Requirements
+
+At R2 checkpoint, record:
+
+* Final subagent module map and ownership.
+* Public exports that remained stable.
+* Tests proving schemas/envelopes did not change.
+* Any behavior that became clearer or any residual large module that should be split later.
+
+## Planned Extensions
+
+* Future `teams/` or `orchestration/` package should depend on stable internal APIs, not `subagents/tools.py` internals.
+
+## Definition of Done
+
+* Focused subagent tests pass.
+* Ruff/mypy pass for touched files.
+* Checkpoint documents module ownership.
+
+## Out of Scope
+
+* 不改变 runtime role/factory contract unless R1 left a concrete gap.
+* 不实现 H13/H14.
+* 不 add compatibility alias modules solely for old internal imports.
+* 不 rewrite background run semantics; R3 owns that.
+* 不 introduce team/coordinator package.
+
+## Technical Notes
+
+* Parent: `.trellis/tasks/04-19-runtime-architecture-refactor-plan/prd.md`
+* Key files likely touched:
+  * `coding-deepgent/src/coding_deepgent/subagents/`
+  * `coding-deepgent/tests/subagents/test_subagents.py`
+
+## Checkpoint: R2
+
+State:
+* verifying
+
+Verdict:
+* APPROVE
+
+Implemented:
+* Extracted subagent definition/catalog ownership to `subagents/definitions.py`.
+* Extracted subagent/fork result dataclasses and `ChildAgentFactory` to `subagents/results.py`.
+* Extracted fork-specific fingerprint, placeholder layout, payload, recursion guard, and prompt/tool projection helpers to `subagents/forking.py`.
+* Updated `subagents/__init__.py` to keep public exports stable.
+
+Verification:
+* `pytest -q coding-deepgent/tests/subagents/test_subagents.py coding-deepgent/tests/tool_system/test_tool_system_registry.py coding-deepgent/tests/tool_system/test_tool_search.py`
+* Result: `59 passed`
+
+Architecture:
+* primitive used: domain module split by ownership inside `subagents`.
+* why no heavier abstraction: R2 moves stable responsibilities without changing public tool schemas or adding a new runtime layer.
+
+Boundary findings:
+* `subagents/tools.py` still owns execution, resume, sidechain, and public tool wrappers. It is smaller and no longer owns catalog/fork payload, but deeper sidechain/resume extraction remains a possible future cleanup.
+* No compatibility alias modules were added for old internal imports.
+* No H13/H14 behavior was introduced.
+
+Decision:
+* continue
+
+Reason:
+* The high-risk catalog/fork-payload ownership has been removed from `tools.py`, focused tests pass, and R3 can proceed against stable public/background APIs.
diff --git a/.trellis/tasks/archive/2026-04/04-19-r2-split-subagent-domain-responsibilities/task.json b/.trellis/tasks/archive/2026-04/04-19-r2-split-subagent-domain-responsibilities/task.json
new file mode 100644
index 000000000..402766f9d
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-r2-split-subagent-domain-responsibilities/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "r2-split-subagent-domain-responsibilities",
+  "name": "r2-split-subagent-domain-responsibilities",
+  "title": "R2 split subagent domain responsibilities",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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-19-runtime-architecture-refactor-plan",
+  "relatedFiles": [],
+  "notes": "Completed R2: extracted subagent definitions/catalog, result dataclasses, and fork payload/fingerprint helpers into dedicated modules while preserving public exports and tool schemas.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-19-r3-background-run-service-hardening/prd.md b/.trellis/tasks/archive/2026-04/04-19-r3-background-run-service-hardening/prd.md
new file mode 100644
index 000000000..ad2acc8d4
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-r3-background-run-service-hardening/prd.md
@@ -0,0 +1,144 @@
+# R3: Background Run Service Hardening
+
+## Goal
+
+将 background subagent/fork runtime 从“线程闭包持有 live `ToolRuntime`”整理为更清晰的 background run service：持久 run record、可序列化 runtime snapshot、process-local worker handle 分离，为后续 mailbox delivery、stopped-worker resume、notification protocol 打底。
+
+## Dependencies
+
+* Depends on R1 runtime role and agent factory seam.
+* Prefer after R2 split if R2 has already stabilized execution/resume modules.
+
+## Requirements
+
+* 明确区分 persistent background run record 与 process-local worker thread handle。
+* 减少 background worker 对 live `ToolRuntime` 的长期闭包依赖。
+* 保持现有 `run_subagent_background`、`subagent_status`、`subagent_send_input`、`subagent_stop` 行为不变。
+* 不声称 mailbox/coordinator/team runtime semantics。
+
+## Acceptance Targets
+
+* [ ] Background worker execution can be reconstructed from a bounded runtime snapshot/factory seam.
+* [ ] Store-backed run record remains source of truth for status/progress/pending inputs/latest result.
+* [ ] Process-local worker handles are clearly non-durable.
+* [ ] Existing background subagent/fork tests pass.
+
+## Planned Features
+
+* Introduce a `BackgroundRunContext` / `BackgroundRuntimeSnapshot` style contract if needed.
+* Refactor `BackgroundSubagentManager` around record mutation + worker execution boundaries.
+* Update tests for send-input, stop, status, background fork reuse.
+
+## Detailed Implementation Plan
+
+### Target Design
+
+Background execution should have three explicit layers:
+
+* Durable run record
+  * Existing `BackgroundSubagentRun` remains the store-backed source of truth for status, pending inputs, latest result, usage counters, child thread id, and terminal notification status.
+* Serializable runtime snapshot
+  * A bounded record of execution facts needed to reconstruct invocation context for the worker.
+  * Should include only safe, durable identifiers and configuration-derived values, not arbitrary live objects.
+* Process-local worker handle
+  * The thread object and in-memory active-run map are explicitly non-durable.
+  * They may optimize active execution but must not be treated as source of truth.
+
+### Required Code Changes
+
+* Refactor `BackgroundSubagentManager` so record mutation and worker execution are separate responsibilities.
+* Reduce long-lived closure dependence on live `ToolRuntime`.
+* Ensure queued follow-up input still reuses the same background run id and child thread id.
+* Preserve terminal notification evidence behavior.
+* Preserve stop/cancel semantics at safe invoke boundaries.
+* Preserve background fork first-run vs resume behavior.
+
+### Runtime Snapshot Constraints
+
+* The snapshot must not include raw prompt text beyond existing fork fingerprints/metadata contracts.
+* The snapshot must not include full `ToolRuntime`, arbitrary state dicts, or model objects.
+* The snapshot may reference store/session/workdir/thread ids through bounded fields.
+* If complete ToolRuntime removal is too broad for this stage, split a smaller prerequisite task instead of adding a fake serializable wrapper.
+
+### Focused Verification
+
+* Background tests in `coding-deepgent/tests/subagents/test_subagents.py`:
+  * background subagent start/status.
+  * background fork start/status.
+  * send_input reactivates finished run.
+  * background fork send_input reuses same thread and continuity.
+  * subagent_stop cancels running background run.
+  * subagent_stop cancels running background fork.
+* Session evidence tests if `_append_notification` or evidence metadata changes.
+* `ruff check <touched background/schema/test files>`
+* `mypy <touched background/schema/test files>` where practical.
+
+### Checkpoint Requirements
+
+At R3 checkpoint, record:
+
+* Which runtime facts are durable and which remain process-local.
+* Whether live `ToolRuntime` is still held by worker threads and why.
+* Whether H13 mailbox can later route messages through the service boundary instead of `subagent_send_input` semantics.
+* Whether any cross-process/daemon behavior was deferred.
+
+## Planned Extensions
+
+* H13 mailbox message delivery.
+* Stopped-worker wake/resume through SendMessage.
+* Coordinator task notification protocol.
+
+## Definition of Done
+
+* Focused background tests pass.
+* Ruff/mypy pass for touched files.
+* Checkpoint documents durability boundary.
+
+## Out of Scope
+
+* 不实现 mailbox / SendMessage。
+* 不实现 cross-process worker execution.
+* 不 introduce daemon/remote bridge.
+* 不 add TeamCreate/TeamDelete or coordinator tools.
+* 不 change public background tool schemas unless a blocking bug is discovered and documented.
+
+## Technical Notes
+
+* Parent: `.trellis/tasks/04-19-runtime-architecture-refactor-plan/prd.md`
+* Key files likely touched:
+  * `coding-deepgent/src/coding_deepgent/subagents/background.py`
+  * `coding-deepgent/src/coding_deepgent/subagents/schemas.py`
+  * `coding-deepgent/tests/subagents/test_subagents.py`
+
+## Checkpoint: R3
+
+State:
+* verifying
+
+Verdict:
+* APPROVE
+
+Implemented:
+* Added `BackgroundRuntimeSnapshot` to durable background run records.
+* Added process-local `BackgroundWorkerHandle` to make thread handles explicit non-durable runtime state.
+* Background run records now carry bounded runtime facts such as parent thread id, workdir, entrypoint, agent name, session-context availability, and prompt/tool fingerprints when available.
+* Background notification evidence includes the bounded runtime snapshot.
+
+Verification:
+* `pytest -q coding-deepgent/tests/subagents/test_subagents.py coding-deepgent/tests/tool_system/test_tool_system_registry.py coding-deepgent/tests/tool_system/test_tool_search.py`
+* Result: `59 passed`
+
+Architecture:
+* primitive used: explicit Pydantic run snapshot plus process-local handle dataclass.
+* why no heavier abstraction: R3 documents and separates durable/process-local facts without introducing cross-process execution or a daemon.
+
+Boundary findings:
+* Active background workers still receive live `ToolRuntime` for the current LangChain invoke. Full reconstruction without live runtime is deferred because it would require new execution ownership and is not needed before H13 planning.
+* Store-backed `BackgroundSubagentRun` remains the source of truth.
+* No mailbox, SendMessage, team, daemon, or remote bridge behavior was introduced.
+
+Decision:
+* continue
+
+Reason:
+* Durable/process-local background boundaries are now explicit enough for R4 to define H13/H14 readiness criteria.
diff --git a/.trellis/tasks/archive/2026-04/04-19-r3-background-run-service-hardening/task.json b/.trellis/tasks/archive/2026-04/04-19-r3-background-run-service-hardening/task.json
new file mode 100644
index 000000000..983d10985
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-r3-background-run-service-hardening/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "r3-background-run-service-hardening",
+  "name": "r3-background-run-service-hardening",
+  "title": "R3 background run service hardening",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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-19-runtime-architecture-refactor-plan",
+  "relatedFiles": [],
+  "notes": "Completed R3: added bounded BackgroundRuntimeSnapshot records and process-local BackgroundWorkerHandle separation for background runs without adding mailbox/team semantics.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-19-r4-h13-h14-readiness-gate/prd.md b/.trellis/tasks/archive/2026-04/04-19-r4-h13-h14-readiness-gate/prd.md
new file mode 100644
index 000000000..18f93887f
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-r4-h13-h14-readiness-gate/prd.md
@@ -0,0 +1,144 @@
+# R4: H13 H14 Readiness Gate
+
+## Goal
+
+在进入 H13 mailbox / H14 coordinator 前建立硬性 readiness gate，确保 `run_subagent` / `run_fork` 不被污染成 team runtime，并为 future `coordinator` / `worker` role projection、Scratchpad、task notification、SendMessage surfaces 留出明确合同。
+
+## Dependencies
+
+* Depends on R1.
+* Prefer after R2 and R3, so readiness gate reflects stabilized runtime surfaces.
+
+## Requirements
+
+* 增加 spec/test gate，禁止 `run_subagent` / `run_fork` 接收 mailbox/coordinator/team lifecycle 字段或语义。
+* 定义 future H13/H14 required surfaces，但不实现完整 behavior。
+* 明确 coordinator/worker tool projection 的目标边界：
+  * Coordinator: orchestration tools only.
+  * Worker: execution tools only, no team management tools.
+* 明确 H13/H14 进入条件。
+
+## Acceptance Targets
+
+* [ ] Regression tests prove `run_subagent` / `run_fork` schemas remain clean.
+* [ ] Trellis backend contracts state H13/H14 readiness criteria.
+* [ ] Future coordinator/worker role projection boundary is documented.
+* [ ] No H13/H14 behavior is implemented in this task.
+
+## Planned Features
+
+* Update Trellis backend contracts.
+* Add tests or review checks around runtime role projection and schema non-contamination.
+* Define H13/H14 stage entry checklist.
+
+## Detailed Implementation Plan
+
+### Readiness Criteria To Encode
+
+H13/H14 planning may begin only when these are true:
+
+* Runtime roles can express `coordinator` and `worker` without overloading `subagent` or `fork`.
+* Public `run_subagent` and `run_fork` schemas remain free of mailbox/coordinator/team lifecycle fields.
+* There is a clear place for future coordinator/worker tool projection that is not prompt-only enforcement.
+* Background run service has an explicit boundary for future message delivery.
+* A future `teams/` or `orchestration/` domain can own team state and scratchpad without hiding it in `sessions/`, `tool_system/`, or `subagents/tools.py`.
+
+### Required Code/Spec Changes
+
+* Update `.trellis/spec/backend/project-infrastructure-foundation-contracts.md` with runtime reshape completion facts and H13/H14 entry criteria.
+* Update `.trellis/spec/backend/task-workflow-contracts.md` if subagent/fork/background contracts changed during R1-R3.
+* Add or update tests proving schema non-contamination:
+  * `run_subagent` must not expose `background`, `mailbox`, `coordinator`, `team`, `worker`, or similar runtime-creep fields.
+  * `run_fork` must not expose mailbox/coordinator/team fields.
+  * Background controls must not claim mailbox/coordinator semantics.
+* Add role projection readiness tests if R1 introduced role metadata/projection helpers.
+
+### H13/H14 Future Planning Handoff
+
+After R4, the next integrated delivery planning task should define:
+
+* H13 acceptance target: local mailbox + SendMessage + Scratchpad foundation.
+* H14 acceptance target: Coordinator mode with restricted orchestration tool projection and worker execution projection.
+* Explicit non-goal: no prompt-only fake multi-agent conversation.
+* Source references:
+  * local claude-code-book Chapter 10.
+  * `/root/claude-code-haha/src/tools/SendMessageTool/*`
+  * `/root/claude-code-haha/src/tools/shared/spawnMultiAgent.ts`
+  * `/root/claude-code-haha/src/utils/swarm/*`
+
+### Focused Verification
+
+* `pytest -q coding-deepgent/tests/subagents/test_subagents.py::test_run_subagent_tool_schema_rejects_runtime_creep_fields`
+* `pytest -q coding-deepgent/tests/subagents/test_subagents.py::test_run_fork_tool_schema_rejects_runtime_creep_fields`
+* `pytest -q coding-deepgent/tests/tool_system/test_tool_system_registry.py coding-deepgent/tests/tool_system/test_tool_search.py`
+* Trellis spec review against changed runtime contracts.
+
+### Checkpoint Requirements
+
+At R4 checkpoint, record:
+
+* Final H13/H14 readiness verdict.
+* Exact specs updated.
+* Tests proving current surfaces remain clean.
+* Whether the next task should be H13 mailbox foundation or an additional runtime cleanup split.
+
+## Planned Extensions
+
+* H13 mailbox + Scratchpad foundation.
+* H14 coordinator mode and coordinator-worker workflow.
+
+## Definition of Done
+
+* Focused tests pass.
+* Trellis spec updates are source-backed and concise.
+* Checkpoint records whether H13 planning can begin.
+
+## Out of Scope
+
+* 不实现 SendMessage。
+* 不实现 Scratchpad.
+* 不实现 Coordinator mode.
+* 不 add prompt-only fake coordinator workflow.
+* 不 create team state storage.
+* 不 add remote/UDS/bridge addressing.
+
+## Technical Notes
+
+* Parent: `.trellis/tasks/04-19-runtime-architecture-refactor-plan/prd.md`
+* Key files likely touched:
+  * `.trellis/spec/backend/project-infrastructure-foundation-contracts.md`
+  * `.trellis/spec/backend/task-workflow-contracts.md`
+  * `coding-deepgent/tests/subagents/test_subagents.py`
+  * possibly `coding-deepgent/tests/tool_system/test_tool_system_registry.py`
+
+## Checkpoint: R4
+
+State:
+* verifying
+
+Verdict:
+* APPROVE
+
+Implemented:
+* Added schema regression coverage that forbids mailbox/coordinator/team/Scratchpad fields on `run_subagent` and `run_fork`.
+* Added schema readiness coverage that background controls do not claim mailbox/team runtime fields.
+* Updated project infrastructure contracts with H13/H14 readiness criteria.
+* Updated task workflow contracts to clarify `subagent_send_input` is not `SendMessage` and background snapshots are durable metadata, not process-local handles.
+
+Verification:
+* `pytest -q coding-deepgent/tests/subagents/test_subagents.py::test_run_subagent_tool_schema_rejects_runtime_creep_fields coding-deepgent/tests/subagents/test_subagents.py::test_run_fork_tool_schema_rejects_runtime_creep_fields coding-deepgent/tests/subagents/test_subagents.py::test_background_tools_do_not_claim_mailbox_or_team_runtime_schema coding-deepgent/tests/tool_system/test_tool_system_registry.py coding-deepgent/tests/tool_system/test_tool_search.py`
+* Result: `17 passed`
+
+Architecture:
+* primitive used: schema regression tests plus Trellis executable contracts.
+* why no heavier abstraction: R4 is a readiness gate, not the H13/H14 implementation.
+
+Boundary findings:
+* H13/H14 can be planned next only as separate mailbox/coordinator surfaces.
+* No SendMessage, Scratchpad, Coordinator, team state, or remote addressing behavior was implemented.
+
+Decision:
+* continue
+
+Reason:
+* Runtime reshape gate is now encoded in tests/specs; final broader focused validation can run.
diff --git a/.trellis/tasks/archive/2026-04/04-19-r4-h13-h14-readiness-gate/task.json b/.trellis/tasks/archive/2026-04/04-19-r4-h13-h14-readiness-gate/task.json
new file mode 100644
index 000000000..9f6ff3667
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-r4-h13-h14-readiness-gate/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "r4-h13-h14-readiness-gate",
+  "name": "r4-h13-h14-readiness-gate",
+  "title": "R4 H13 H14 readiness gate",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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-19-runtime-architecture-refactor-plan",
+  "relatedFiles": [],
+  "notes": "Completed R4: added H13/H14 readiness specs and schema regression tests preventing run_subagent/run_fork/background controls from claiming mailbox/coordinator/team semantics.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-19-runtime-architecture-refactor-plan/check.jsonl b/.trellis/tasks/archive/2026-04/04-19-runtime-architecture-refactor-plan/check.jsonl
new file mode 100644
index 000000000..edf962156
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-runtime-architecture-refactor-plan/check.jsonl
@@ -0,0 +1,12 @@
+{"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-19-runtime-architecture-refactor-plan/prd.md", "reason": "Check against integrated runtime reshape delivery contract"}
+{"file": ".trellis/tasks/04-19-r1-runtime-role-agent-factory-seam/prd.md", "reason": "Check R1 runtime role and factory seam requirements"}
+{"file": ".trellis/tasks/04-19-r2-split-subagent-domain-responsibilities/prd.md", "reason": "Check R2 subagent module split requirements"}
+{"file": ".trellis/tasks/04-19-r3-background-run-service-hardening/prd.md", "reason": "Check R3 background run service requirements"}
+{"file": ".trellis/tasks/04-19-r4-h13-h14-readiness-gate/prd.md", "reason": "Check R4 H13 H14 readiness gate requirements"}
+{"file": ".trellis/spec/backend/langchain-native-guidelines.md", "reason": "Check LangChain-native runtime/tool/middleware rules"}
+{"file": ".trellis/spec/backend/project-infrastructure-foundation-contracts.md", "reason": "Check runtime/session/task/subagent infrastructure contracts"}
+{"file": ".trellis/spec/backend/task-workflow-contracts.md", "reason": "Check subagent/fork/background task workflow contracts"}
+{"file": ".trellis/spec/backend/directory-structure.md", "reason": "Check domain ownership and module placement rules"}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Check backend quality and validation expectations"}
diff --git a/.trellis/tasks/archive/2026-04/04-19-runtime-architecture-refactor-plan/debug.jsonl b/.trellis/tasks/archive/2026-04/04-19-runtime-architecture-refactor-plan/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-runtime-architecture-refactor-plan/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-19-runtime-architecture-refactor-plan/implement.jsonl b/.trellis/tasks/archive/2026-04/04-19-runtime-architecture-refactor-plan/implement.jsonl
new file mode 100644
index 000000000..f66a75117
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-runtime-architecture-refactor-plan/implement.jsonl
@@ -0,0 +1,11 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": ".trellis/tasks/04-19-runtime-architecture-refactor-plan/prd.md", "reason": "Integrated runtime reshape delivery contract"}
+{"file": ".trellis/tasks/04-19-r1-runtime-role-agent-factory-seam/prd.md", "reason": "R1 runtime role and factory seam requirements"}
+{"file": ".trellis/tasks/04-19-r2-split-subagent-domain-responsibilities/prd.md", "reason": "R2 subagent module split requirements"}
+{"file": ".trellis/tasks/04-19-r3-background-run-service-hardening/prd.md", "reason": "R3 background run service requirements"}
+{"file": ".trellis/tasks/04-19-r4-h13-h14-readiness-gate/prd.md", "reason": "R4 H13 H14 readiness gate requirements"}
+{"file": ".trellis/spec/backend/langchain-native-guidelines.md", "reason": "LangChain-native runtime/tool/middleware rules"}
+{"file": ".trellis/spec/backend/project-infrastructure-foundation-contracts.md", "reason": "Runtime/session/task/subagent infrastructure contracts"}
+{"file": ".trellis/spec/backend/task-workflow-contracts.md", "reason": "Subagent/fork/background task workflow contracts"}
+{"file": ".trellis/spec/backend/directory-structure.md", "reason": "Domain ownership and module placement rules"}
diff --git a/.trellis/tasks/archive/2026-04/04-19-runtime-architecture-refactor-plan/prd.md b/.trellis/tasks/archive/2026-04/04-19-runtime-architecture-refactor-plan/prd.md
new file mode 100644
index 000000000..b06ea82a3
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-runtime-architecture-refactor-plan/prd.md
@@ -0,0 +1,457 @@
+# Runtime Architecture Reshape Integrated Delivery Plan
+
+## Goal
+
+一次性集成交付 `coding-deepgent` backend runtime 架构重构计划，明确 main agent / child agent / fork / background run / future coordinator-worker runtime 的边界，避免继续把 H13/H14 多智能体编排堆到当前 subagent/fork/background surfaces 上，形成后续难以升级的屎山。
+
+## What I already know
+
+* 用户明确担心：前面一直强调架构边界，但 AI 仍可能把功能堆成屎山。
+* 当前目标是先做重构整理计划，不是立刻实现多智能体编排。
+* 当前主线是 `coding-deepgent/`，教程/reference 层默认只作参考。
+* 现有 Trellis spec 已经要求：`run_subagent` 不能被拉伸成 mailbox/coordinator/team lifecycle semantics。
+* 初步代码阅读显示：`RuntimeContext` 已经承担过多横切职责，subagent/fork/background runtime 构造散落在 `subagents/tools.py` 和 `subagents/background.py`。
+* 用户现在进一步明确：代码重构计划希望后续一次性集成交付完成；智能体编排功能作为第二个大计划，后续再单独定集成交付目标。
+
+## Assumptions (temporary)
+
+* 这轮应优先把重构任务写到足够详细，使后续可以一口气实施，而不是立即开始改代码。
+* 重构目标不是“为了好看重命名”，而是降低 H13/H14 mailbox/coordinator 落地时的边界风险。
+* 可以接受先做少量架构 prep，再进入 H13 mailbox foundation。
+* 后续实施可以是一个 integrated delivery pass，但必须保留内部 checkpoint 和 stop/split 条件。
+
+## Open Questions
+
+* （resolved）本轮只创建 R1-R4 子任务并完成计划拓扑，暂不改产品代码。
+
+## Requirements (evolving)
+
+* 明确指出当前 backend runtime 的真实混乱点，不泛泛而谈。
+* 区分“必须先重构的 blocker”和“可以随 H13/H14 顺手整理的非 blocker”。
+* 明确未来 H13/H14 需要的新 runtime surfaces，避免继续污染 `run_subagent`。
+* 给出 staged refactor plan，每一阶段都要有验收标准和风险控制。
+* 计划必须遵循 LangChain/LangGraph-native 原则，不引入自定义大 runtime 绕开 `create_agent` / middleware / store / checkpointer。
+* 用户已选择 **Approach C: Broad runtime reshape before H13**。
+* 本轮允许接受较大重构范围，目标是在 H13/H14 前把 runtime 底座整理干净。
+* 重构仍必须 staged，不允许一次性无验收的大爆炸修改。
+* 用户已选择：R1 不保留旧 monkeypatch/调用兼容桥接，直接迁移测试和调用点到新 factory seam。
+* 用户已选择：brainstorm 收敛后先创建 R1-R4 子任务，暂不进入 implementation。
+* 用户已选择：后续希望一次性完成这个代码重构大计划，因此父任务需要写成 integrated delivery contract，而不是松散 backlog。
+* 后续还会单独定义“智能体编排功能”的 integrated delivery target；当前父任务只负责把 runtime 底座整理到可承载 H13/H14 的状态。
+
+## Acceptance Criteria (evolving)
+
+* [x] 有一份 runtime architecture assessment，列出具体文件/边界/风险。
+* [x] 有 2-3 个可选重构路线，并说明 trade-off。
+* [x] 有推荐路线，且能解释为什么它能降低 H13/H14 升级风险。
+* [x] 有小 PR 拆分，每个 PR 都可独立验证。
+* [x] 明确 out of scope：不在本轮直接实现完整 Coordinator。
+* [x] Broad reshape 每个阶段都有 checkpoint gate、focused tests、rollback/split 条件。
+* [x] R1-R4 子任务已创建并链接到父任务。
+* [x] 父任务包含集成交付目标、阶段顺序、验证矩阵、stop/split 条件和 H13/H14 handoff contract。
+* [x] R1-R4 子任务包含足够详细的实施顺序、文件范围、测试范围和非目标。
+
+## Definition of Done (team quality bar)
+
+* Tests added/updated if implementation is included.
+* Lint / typecheck / CI green if code changes are included.
+* Docs/notes updated if behavior or architecture contracts change.
+* Rollout/rollback considered if risky.
+
+## Out of Scope (explicit)
+
+* 不直接实现完整 H14 Coordinator runtime。
+* 不直接实现 H13 Mailbox / SendMessage / Scratchpad。
+* 不把 mailbox/coordinator/team semantics 加到 `run_subagent` 或 `run_fork` 字符串 payload 里。
+* 不做 line-by-line cc-haha clone。
+* 不为旧局部设计增加兼容桥接层，除非存在真实外部兼容要求。
+
+## Technical Notes
+
+* Initial local evidence:
+  * `coding-deepgent/src/coding_deepgent/runtime/context.py`
+  * `coding-deepgent/src/coding_deepgent/runtime/invocation.py`
+  * `coding-deepgent/src/coding_deepgent/containers/app.py`
+  * `coding-deepgent/src/coding_deepgent/subagents/tools.py`
+  * `coding-deepgent/src/coding_deepgent/subagents/background.py`
+  * `.trellis/spec/backend/project-infrastructure-foundation-contracts.md`
+  * `.trellis/spec/backend/task-workflow-contracts.md`
+
+## Research Notes
+
+### Relevant project rules
+
+* `.trellis/spec/guides/architecture-posture-guide.md`
+  * 优先长期清晰边界，不以最小 diff 为第一目标。
+  * 如果新结构明显更正确，可以直接替换旧局部抽象，不为了旧方案保留 bridge/fallback。
+* `.trellis/spec/guides/planning-targets-guide.md`
+  * 非平凡 feature family 必须先写清 `Acceptance Targets` / `Planned Features` / `Planned Extensions`。
+  * 这次计划必须防止“重构 runtime”这种模糊目标漂移。
+* `.trellis/spec/backend/langchain-native-guidelines.md`
+  * 任何 runtime 整理都必须落在官方 surfaces：tool、middleware、typed state、context schema、checkpointer、store、graph/subgraph。
+  * 禁止引入无真实边界的 wrapper/fallback/框架形态间接层。
+* `.trellis/spec/backend/project-infrastructure-foundation-contracts.md`
+  * `run_subagent` 不得被拉伸为 mailbox/coordinator/background daemon/team lifecycle semantics。
+  * 当前 subagent/fork/background 是 local slices，不是 team runtime。
+  * H13/H14 需要新的 task/subagent specs，而不是继续扩展字符串 payload 或 deferred lifecycle bridge。
+
+### Current code signals
+
+* `RuntimeContext` 是一个轻量 dataclass，但已经聚合了 identity、session、transcript projection、context pressure、fork prompt/tool projection、tool policy、memory service、plugin dir 等横切信息。
+* `subagents/tools.py` 约 1883 行，直接负责 AgentDefinition、child/fork invocation 派生、prompt 构造、tool projection、resume、sidechain persistence、structured envelopes 和 tool wrappers。
+* `subagents/background.py` 约 561 行，管理 background run store、线程生命周期、queued input、stop、notification、subagent/fork resume 分流。
+* `subagents/tools.py` 内部直接 `create_agent(...)` 构造 child/fork agent，和 `containers/app.py` 的主 agent composition seam 并不统一。
+* `BackgroundSubagentManager` 把 live `ToolRuntime` 传入线程，当前 local bounded run 可接受，但不适合作为 mailbox/coordinator/跨进程恢复的基础。
+* 代码中大量通过 `getattr(runtime, "context"...)`、`runtime.store`、`runtime.state` 读取隐式能力；这对当前 tool runtime 快速演进有用，但对 team/coordinator ownership 不够硬。
+* `coding-deepgent/tests/subagents/test_subagents.py` 对 `subagents.tools.create_agent` 有大量 monkeypatch；如果直接拆文件/迁移 symbol，测试和调用点会大面积震荡。
+* `agent_service.py` 已经有主 agent 的 `create_compiled_agent(...)` seam，但 child/fork runtime 没复用这个 seam。
+* `agent_runtime_service.py` 只有 `invoke_agent(...)` / session payload wiring，没有负责 agent construction。它可以作为轻量 invocation helper 保留，不应被扩成新 god module。
+
+### Why AI keeps risking "屎山"
+
+* AI 默认会沿着最近可用的 surface 继续扩展：已有 `run_subagent_background` 和 `subagent_send_input`，就很容易把 mailbox 做成“send_input 的增强版”。
+* 如果没有先定义 role/tool projection，Coordinator 很容易仍拿到执行工具，Worker 也容易拿到管理工具，最后只能靠 prompt 约束。
+* 如果没有 runtime factory/context boundary，child/fork/worker/coordinator 会继续各自 `create_agent(...)`，middleware/store/checkpointer/policy 很难保持一致。
+* 如果没有 serializable background run context，未来 worker resume/notification/mailbox 会被当前进程内 `ToolRuntime` 绑住。
+
+### Feasible approaches here
+
+**Approach A: Architecture plan only**
+
+* How it works:
+  * 本轮只产出 assessment、ADR、task decomposition，不改产品代码。
+* Pros:
+  * 风险最低，能快速把方向锁住。
+* Cons:
+  * 不会立刻减少代码里的耦合，下一位 AI 仍可能绕开计划。
+
+**Approach B: Runtime architecture prep MVP** (Recommended)
+
+* How it works:
+  * 先做一个小而硬的架构准备包：
+    * 定义 runtime role / invocation / agent factory contract。
+    * 把 main/subagent/fork 的 agent construction 收敛到统一 factory seam。
+    * 把 H13/H14 禁止污染 `run_subagent` 的规则写成 tests/spec review gate。
+  * 不实现 mailbox/coordinator。
+* Pros:
+  * 直接降低后续 H13/H14 的屎山概率。
+  * 范围仍可控，和当前 pain 点强相关。
+* Cons:
+  * 会触碰核心 runtime/subagent tests，需要认真验证。
+
+**Approach C: Broad runtime reshape before H13**
+
+* How it works:
+  * 同时拆 `RuntimeContext`、重构 background manager、拆分 `subagents/tools.py`、定义 future team package。
+* Pros:
+  * 长期最干净。
+* Cons:
+  * 范围太大，容易变成另一个失控重构。
+  * 在没有 H13 concrete consumer 前可能引入 speculative abstraction。
+
+### Broad reshape staged plan candidate
+
+**Stage R1: Runtime role and agent factory seam**
+
+* Acceptance Targets:
+  * main/subagent/fork agent construction 都能通过一个明确的 runtime factory/agent builder seam 表达。
+  * child/fork 不再直接依赖散落在 `subagents/tools.py` 的裸 `create_agent(...)` 调用作为主要构造入口。
+  * 现有 H11/H12 behavior 不变。
+* Planned Features:
+  * 新增或重整 `runtime/agent_factory.py` / `runtime/roles.py` 之类的低层 seam。
+  * 定义 runtime roles：`main`、`subagent`、`fork`，并为 future `coordinator`、`worker` 预留枚举/contract，不实现行为。
+  * 将 child/fork construction 调整为调用 factory seam。
+* Planned Extensions:
+  * future `coordinator` / `worker` role projection。
+  * mailbox/scratchpad/team runtime。
+
+**Stage R2: Split subagent domain by responsibility**
+
+* Acceptance Targets:
+  * `subagents/tools.py` 不再同时承载 definition/catalog、execution、fork payload、resume/sidechain、background lifecycle、tool wrappers。
+  * Public tool surfaces 保持原名和 schema。
+* Planned Features:
+  * 拆分为职责模块，例如 `definitions.py`、`execution.py`、`forking.py`、`resume.py`、`sidechain.py`、`tool_wrappers.py`。
+  * 保持 `subagents/__init__.py` public exports 稳定。
+* Planned Extensions:
+  * future `teams/` 或 `orchestration/` package 不依赖 `subagents/tools.py` 内部细节。
+
+**Stage R3: Background run service hardening**
+
+* Acceptance Targets:
+  * background manager 不再把 live `ToolRuntime` 当作长期执行上下文的唯一来源。
+  * run record 明确区分 serializable context、runtime-owned store、process-local worker handle。
+* Planned Features:
+  * 引入 `BackgroundRunContext` / `BackgroundRuntimeSnapshot` 等可序列化执行参数。
+  * 线程 worker 通过 factory/context snapshot 重建 invocation，而不是长期闭包持有完整 live runtime。
+* Planned Extensions:
+  * H13 mailbox message delivery。
+  * stopped-worker resume / notification protocol。
+
+**Stage R4: H13/H14 readiness gate**
+
+* Acceptance Targets:
+  * tests/spec 明确阻止 `run_subagent` / `run_fork` 获得 mailbox/coordinator/team lifecycle 字段或语义。
+  * future `coordinator` 和 `worker` 的 tool projection contract 已有占位测试或 spec 条目。
+* Planned Features:
+  * 更新 Trellis backend contracts。
+  * 增加 regression tests 覆盖 schema 不污染、role projection 不混淆、factory seam 被使用。
+* Planned Extensions:
+  * H13 mailbox foundation。
+  * H14 coordinator prompt/tool projection/runtime。
+
+### Expansion sweep
+
+1. Future evolution
+* 1-3 个月内，runtime reshape 应直接支撑 H13 mailbox、H14 coordinator、future worktree/team worker，而不是只让当前 H12 更整洁。
+* 需要保留 LangChain-native construction path，避免未来为了 coordinator 写自定义 query loop。
+
+2. Related scenarios
+* Runtime pressure、memory、tool guard、session evidence 都依赖 `RuntimeContext`，拆分时不能破坏现有 middleware。
+* Existing tests monkeypatch `subagents.tools.create_agent`，第一阶段应先建立新 seam 和适配测试，再拆 public module。
+
+3. Failure / edge cases
+* 最大风险是 broad reshape 变成一次性大爆炸，导致行为回归难定位。
+* 第二风险是过早引入 future coordinator abstractions，但没有 H13/H14 consumer，形成新的 speculative layer。
+
+### Current implementation posture
+
+* Recommended execution mode: `staged-execution` in `deep` planning, then `lean` implementation per stage.
+* Do not activate implementation until final requirements include:
+  * `Acceptance Targets`
+  * `Planned Features`
+  * `Planned Extensions`
+  * Stage checkpoints
+  * Focused test list
+
+### Initial recommendation
+
+采用 **Approach B: Runtime architecture prep MVP**。它不是为了“重构而重构”，而是为 H13/H14 建立最小硬边界：
+
+* 让 agent construction 不再散落。
+* 让 role/tool projection 成为显式 contract。
+* 让 background execution 不继续绑定 live `ToolRuntime` 作为未来 team runtime 基础。
+* 让 tests 阻止 `run_subagent` 被继续污染成 mailbox/coordinator。
+
+## Decision (ADR-lite)
+
+**Context**: 当前 `coding-deepgent` 的 H11/H12 local runtime 已经足够丰富，但 main/subagent/fork/background 的 agent construction、runtime context、tool projection、background lifecycle 分散在多个局部实现里。若继续直接做 H13/H14，多智能体编排很容易被实现成 `run_subagent_background` / `subagent_send_input` 的增强版，而不是真正的 coordinator-worker runtime。
+
+**Decision**: 采用 **Approach C: Broad runtime reshape before H13**。先接受较大 runtime 架构整理，在进入 H13 mailbox / H14 coordinator 前重建更清晰的 runtime surfaces。
+
+**Consequences**:
+
+* 本轮规划优先级高于直接实现 H13/H14。
+* 允许替换旧的局部 runtime 抽象，不为了旧局部设计增加兼容桥接层。
+* 重构必须 staged，每个阶段都要有明确 acceptance targets 和 tests。
+* 不允许把 broad reshape 变成无边界的大爆炸；每个阶段必须能解释它如何降低 H13/H14 屎山风险。
+* H13/H14 继续保持 out of scope，直到 runtime reshape 的必要关口完成。
+* R1 不保留旧 `subagents.tools.create_agent` 兼容桥接。现有测试和调用点应直接迁移到新的 runtime factory seam。
+* R1 diff 会更大，但避免留下临时 bridge/fallback，符合 architecture posture guide。
+
+## Decision (ADR-lite): R1 No Compatibility Bridge
+
+**Context**: `coding-deepgent/tests/subagents/test_subagents.py` 目前大量 monkeypatch `subagents.tools.create_agent`，这是当前 child/fork construction 散落的测试信号。如果 R1 保留旧入口作为过渡，会降低 diff 风险，但会继续鼓励后续代码依赖旧局部抽象。
+
+**Decision**: R1 不保留旧 monkeypatch/调用兼容桥接。直接建立新的 runtime factory seam，并迁移测试和调用点。
+
+**Consequences**:
+
+* 第一阶段修改范围更大。
+* 测试应从 monkeypatch `subagents.tools.create_agent` 转向 monkeypatch/inject 新 factory seam。
+* 不新增只为保护旧局部设计存在的 fallback 或 bridge。
+* 如果 R1 迁移中发现范围超过可控边界，应 split 出前置子任务，而不是保留旧兼容入口。
+
+## Decision (ADR-lite): Planning Topology Before Implementation
+
+**Context**: Broad reshape 风险高，且 R1 明确不保留兼容桥接。若直接实现，很容易把 R1 范围和 R2/R3 混在一起。
+
+**Decision**: 本轮先创建 R1-R4 子任务并暂停，不改产品代码。
+
+**Consequences**:
+
+* 后续可以从 R1 单独进入 Task Workflow。
+* 父任务保留为 architecture reshape plan ledger。
+* R2-R4 不应提前实现，除非 R1 checkpoint 明确通过或调整。
+
+## Decision (ADR-lite): Integrated Delivery Mode For Refactor
+
+**Context**: 用户希望后续“一口气”完成代码重构大计划，并在重构完成后再单独定智能体编排功能的集成交付目标。若 R1-R4 只是松散 backlog，后续执行容易在阶段间重新漂移，或者某个阶段做到一半就顺手实现 H13/H14。
+
+**Decision**: 本父任务作为 runtime reshape integrated delivery contract。后续实现可以在一个连续执行 pass 内完成 R1-R4，但必须按顺序经过内部 checkpoint：R1 -> R2 -> R3 -> R4。每个 checkpoint 都要记录验证结果和 `continue | adjust | split | stop` 决策。
+
+**Consequences**:
+
+* 后续执行不需要每个阶段都重新 brainstorm，只要 PRD 仍然成立即可继续。
+* 如果某阶段 focused tests 通过且 checkpoint 为 `continue`，可以立即进入下一阶段。
+* 如果某阶段发现范围膨胀、架构前提错误、测试失败且非局部可修，就必须 `split` 或 `stop`。
+* H13/H14 功能目标仍作为后续第二个大计划，不在本 integrated delivery 中实现。
+
+## Integrated Delivery Contract
+
+### Acceptance Targets
+
+* `coding-deepgent` 的 main/subagent/fork/background runtime construction 有清晰统一的 factory/role seam。
+* `subagents` domain 内部职责拆分清楚，future `teams/` or `orchestration/` 不需要依赖 `subagents/tools.py` 的内部细节。
+* Background run service 明确区分 durable run record、serializable runtime snapshot、process-local worker handle。
+* Trellis spec/tests 明确禁止 `run_subagent` / `run_fork` 污染 mailbox/coordinator/team lifecycle semantics。
+* 完成后可以单独开启 H13/H14 integrated delivery planning，且不需要先回头修 runtime 底座。
+
+### Planned Features
+
+* R1: Runtime role and agent factory seam.
+* R2: Split subagent domain responsibilities.
+* R3: Background run service hardening.
+* R4: H13/H14 readiness gate.
+
+### Planned Extensions
+
+* H13 mailbox / SendMessage / Scratchpad foundation.
+* H14 Coordinator mode and coordinator-worker workflow.
+* Worktree-aware worker lanes.
+* Cross-process/remote team runtime if product goal later requires.
+
+### Execution Order
+
+1. R1 must run first because it changes the core construction seam that R2/R3 should depend on.
+2. R2 should run second because it stabilizes internal subagent APIs before background hardening.
+3. R3 should run third because background execution should depend on R1 factory and preferably R2 execution/resume modules.
+4. R4 must run last because readiness tests/specs should reflect the final reshaped runtime surfaces.
+
+### Checkpoint Gate
+
+At the end of each R stage, write a checkpoint note into that child PRD:
+
+```md
+## Checkpoint: R<n>
+
+State:
+* verifying
+
+Verdict:
+* APPROVE | ITERATE | REJECT
+
+Implemented:
+* ...
+
+Verification:
+* ...
+
+Architecture:
+* primitive used:
+* why no heavier abstraction:
+
+Boundary findings:
+* ...
+
+Decision:
+* continue | adjust | split | stop
+
+Reason:
+* ...
+```
+
+### Stop / Split Conditions
+
+* Stop if a required change would replace LangChain/LangGraph `create_agent` / middleware / store / checkpointer seams rather than reorganizing around them.
+* Split if R1 cannot remove `subagents.tools.create_agent` monkeypatch dependence without a separate test harness cleanup task.
+* Split if R2 module extraction reveals a behavior change that should be fixed before further file moves.
+* Split if R3 requires durable cross-process worker execution; that is not part of this refactor.
+* Stop if H13/H14 feature behavior starts leaking into implementation.
+* Stop if working tree changes conflict with user-owned edits.
+
+### Verification Matrix
+
+Focused checks expected during integrated implementation:
+
+* R1:
+  * `pytest -q coding-deepgent/tests/subagents/test_subagents.py`
+  * `pytest -q coding-deepgent/tests/runtime/test_agent_runtime_service.py coding-deepgent/tests/runtime/test_app.py`
+  * `ruff check` / `mypy` on touched runtime/subagent/test files.
+* R2:
+  * `pytest -q coding-deepgent/tests/subagents/test_subagents.py coding-deepgent/tests/tool_system/test_tool_system_registry.py`
+  * import/export smoke checks through `subagents/__init__.py`.
+  * `ruff check` / `mypy` on touched subagent files.
+* R3:
+  * background-specific subset in `coding-deepgent/tests/subagents/test_subagents.py` covering background start/status/send_input/stop/fork reuse.
+  * session evidence checks if notification code changes.
+  * `ruff check` / `mypy` on touched background/schema files.
+* R4:
+  * schema non-contamination tests for `run_subagent` / `run_fork`.
+  * registry/projection tests if role projection contracts are added.
+  * Trellis spec review against project infrastructure contracts.
+
+Broader validation should run after R4 if all stages changed runtime/subagent surfaces:
+
+* `pytest -q coding-deepgent/tests/subagents/test_subagents.py coding-deepgent/tests/runtime/test_app.py coding-deepgent/tests/runtime/test_agent_runtime_service.py coding-deepgent/tests/tool_system/test_tool_system_registry.py coding-deepgent/tests/tool_system/test_tool_search.py`
+
+### H13/H14 Handoff Contract
+
+This refactor is complete only when the next multi-agent orchestration plan can start from these assumptions:
+
+* `coordinator` and `worker` can be represented as runtime roles without overloading `subagent` or `fork`.
+* Coordinator tool projection can be restricted to orchestration tools without prompt-only enforcement.
+* Worker tool projection can expose execution tools without team-management tools.
+* Background workers can eventually receive mailbox messages through a service boundary, not through ad hoc `subagent_send_input` semantics.
+* Scratchpad/team state can land in a future `teams/` or `orchestration/` domain without being hidden inside `sessions/`, `tool_system/`, or `subagents/tools.py`.
+
+## Checkpoint: Integrated Runtime Reshape
+
+State:
+* terminal
+
+Verdict:
+* APPROVE
+
+Implemented:
+* R1 completed: runtime roles and runtime agent factory seam now own main/subagent/fork construction.
+* R2 completed: subagent definitions/catalog, result dataclasses, and fork payload/fingerprint helpers moved out of `subagents/tools.py`.
+* R3 completed: background runs now persist bounded runtime snapshots and separate process-local worker handles from durable run records.
+* R4 completed: H13/H14 readiness contracts and schema regression tests prevent mailbox/coordinator/team semantics from creeping into existing subagent/fork/background tools.
+
+Verification:
+* `pytest -q coding-deepgent/tests/subagents/test_subagents.py coding-deepgent/tests/runtime/test_app.py coding-deepgent/tests/runtime/test_agent_runtime_service.py coding-deepgent/tests/tool_system/test_tool_system_registry.py coding-deepgent/tests/tool_system/test_tool_search.py`
+* Result: `77 passed`
+* `ruff check coding-deepgent/src/coding_deepgent/runtime coding-deepgent/src/coding_deepgent/agent_service.py coding-deepgent/src/coding_deepgent/subagents coding-deepgent/src/coding_deepgent/tool_system/middleware.py coding-deepgent/tests/subagents/test_subagents.py`
+* Result: `All checks passed`
+* `mypy coding-deepgent/src/coding_deepgent/runtime coding-deepgent/src/coding_deepgent/agent_service.py coding-deepgent/src/coding_deepgent/subagents coding-deepgent/src/coding_deepgent/tool_system/middleware.py coding-deepgent/tests/subagents/test_subagents.py`
+* Result: `Success: no issues found in 20 source files`
+
+Architecture:
+* primitive used: LangChain `create_agent` remains the execution primitive, wrapped by a project-local runtime factory seam.
+* why no heavier abstraction: this reshaped construction and domain boundaries without introducing a custom query loop, daemon, team runtime, or coordinator mode.
+
+Boundary findings:
+* `subagents/tools.py` is still a large module because execution/resume/sidechain/tool wrappers remain there. Definitions/catalog, result dataclasses, and fork payload/fingerprint ownership are no longer there.
+* Background workers still use live `ToolRuntime` for the current in-process invoke; durable snapshot and process-local handle boundaries are explicit. Full cross-process reconstruction remains future work.
+* H13/H14 behavior is not implemented. The next plan can now define mailbox/SendMessage/Scratchpad and Coordinator/Worker as separate surfaces.
+
+Decision:
+* terminal
+
+Reason:
+* Integrated runtime reshape acceptance targets are met and focused validation passed.
+
+## Final Plan Summary
+
+**Goal**: 在进入 H13 mailbox / H14 coordinator 前，先完成 backend runtime broad reshape，避免多智能体编排被堆到现有 subagent/fork/background surfaces 上。
+
+**Chosen route**: Approach C, broad runtime reshape before H13.
+
+**Implementation topology**:
+
+* R1: `04-19-r1-runtime-role-agent-factory-seam`
+  * 建立 runtime role + agent factory seam。
+  * 不保留旧 `subagents.tools.create_agent` 兼容桥接。
+* R2: `04-19-r2-split-subagent-domain-responsibilities`
+  * 拆分 `subagents` domain 内部职责。
+* R3: `04-19-r3-background-run-service-hardening`
+  * 整理 background run service，分离 durable record、serializable context、process-local worker handle。
+* R4: `04-19-r4-h13-h14-readiness-gate`
+  * 建立 H13/H14 readiness gate，防止 `run_subagent` / `run_fork` 污染 team semantics。
+
+**Out of scope for this planning task**:
+
+* 不改产品代码。
+* 不实现 H13 mailbox / SendMessage。
+* 不实现 H14 Coordinator。
diff --git a/.trellis/tasks/archive/2026-04/04-19-runtime-architecture-refactor-plan/task.json b/.trellis/tasks/archive/2026-04/04-19-runtime-architecture-refactor-plan/task.json
new file mode 100644
index 000000000..e3b978f67
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-runtime-architecture-refactor-plan/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "runtime-architecture-refactor-plan",
+  "name": "runtime-architecture-refactor-plan",
+  "title": "brainstorm: runtime architecture refactor plan",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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": "Completed integrated runtime reshape R1-R4 with focused validation: runtime role/factory seam, subagent module split, background run snapshot/handle boundary, and H13/H14 readiness gate.",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-19-subagent-batch2-runtime-implementation-plan/prd.md b/.trellis/tasks/archive/2026-04/04-19-subagent-batch2-runtime-implementation-plan/prd.md
new file mode 100644
index 000000000..a800e9b9c
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-subagent-batch2-runtime-implementation-plan/prd.md
@@ -0,0 +1,32 @@
+# subagent batch2 runtime implementation plan
+
+## Goal
+
+完成第二批子 agent 能力：后台运行、进度、完成通知、追加输入、worker cleanup、插件提供的 agent definitions。
+
+## Requirements
+
+* 保持当前 H11/H12 主线，不引入 mailbox / coordinator / team runtime。
+* 后台运行必须走现有 `subagents/runtime/sessions/store` seam。
+* 进度与通知必须是 bounded local runtime facts，不引入外部队列系统或 daemon。
+* 插件 agent 只提供 definitions source，不新增第二套执行平面。
+
+## Task Breakdown
+
+* `L3-a`: background subagent runtime surface
+* `L3-b`: progress + notification contract
+* `L3-c`: queued follow-up input + cleanup
+* `L3-d`: plugin-provided subagent definitions
+
+## Execution Order
+
+1. `L3-d` can land independently but must join the same agent-definition merge path.
+2. `L3-a` first for runtime surface.
+3. `L3-b` and `L3-c` on top of `L3-a`.
+
+## Out of Scope
+
+* mailbox / SendMessage
+* coordinator runtime
+* background fork workers
+* remote/daemon execution
diff --git a/.trellis/tasks/archive/2026-04/04-19-subagent-batch2-runtime-implementation-plan/task.json b/.trellis/tasks/archive/2026-04/04-19-subagent-batch2-runtime-implementation-plan/task.json
new file mode 100644
index 000000000..ea93d2eaf
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-19-subagent-batch2-runtime-implementation-plan/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "subagent-batch2-runtime-implementation-plan",
+  "name": "subagent-batch2-runtime-implementation-plan",
+  "title": "subagent batch2 runtime implementation plan",
+  "description": "Implement the second subagent runtime batch: background execution, progress, notifications, input continuation, cleanup, and plugin-provided agents.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-19",
+  "completedAt": "2026-04-19",
+  "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-18-compare-subagent-vs-cc-gap",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-20-brainstorm-circle-2-parity-plan/prd.md b/.trellis/tasks/archive/2026-04/04-20-brainstorm-circle-2-parity-plan/prd.md
new file mode 100644
index 000000000..708b68121
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-brainstorm-circle-2-parity-plan/prd.md
@@ -0,0 +1,225 @@
+# brainstorm: Circle 2 parity execution plan
+
+## Goal
+
+制定 `coding-deepgent` 的 `Circle 2` 专项执行计划，承接已完成的 Circle 1 local daily-driver parity baseline，明确 expanded product parity 的 waves、domain boundaries、source evidence、OSS fallback 触发点、验收方式和明确 out-of-scope。
+
+## What I already know
+
+* Circle 1 baseline 已完成并验证，包含 runtime core、CLI/TUI visibility/control、local extension inspect/debug surfaces、acceptance harness。
+* Circle 2 不是继续补 CLI 小功能，而会引入 mailbox/coordinator/remote/IDE/daemon/extension lifecycle/cross-day continuity 等新架构边界。
+* 现有 roadmap 已把 Circle 2 定位为 expanded product parity。
+* 用户要求规划要对照 Claude Code / `cc-haha`，缺源码时先搜索高质量类似 OSS。
+* `cc-haha` 有 worker lifecycle / session ingress / task events / mailbox / coordinator / daemon / cron / plugin lifecycle / session memory 的源码线索。
+* OpenHands、opencode、goose 的公开源码/文档支持把 Circle 2 规划成 runtime substrate、client/server/control plane、extension lifecycle、memory/continuity 的架构序列。
+
+## Assumptions (temporary)
+
+* 本次 brainstorm 只制定 Circle 2 专项计划，不直接实现。
+* Circle 2 需要拆成多个执行 wave，每个 wave 可独立 task 化、验证、归档。
+* Circle 2 仍以本地产品价值为主，不做无价值的 closed-source 外观复制。
+
+## Open Questions
+
+* none
+
+## Requirements (evolving)
+
+* 明确 Circle 2 included / excluded boundaries。
+* 每个 wave 必须说明 user/runtime effect、source evidence、domain ownership、acceptance criteria。
+* 标记哪些能力需要 OSS fallback research。
+* 避免污染现有 `sessions/`, `subagents/`, `runtime/`, `tool_system/` 边界。
+* 明确 Circle 2 需要新增哪些 domain，例如 `mailbox`, `teams`, `daemon`, `remote`, `extension_lifecycle`。
+* 明确哪些当前 Circle 1 能力只能作为 substrate，不能继续直接扩张，例如 active TUI background subagent control 不能假装是 daemon。
+
+## Acceptance Criteria (evolving)
+
+* [ ] Circle 2 plan defines waves and sequencing.
+* [ ] Plan includes source evidence and missing-source fallback rules.
+* [ ] Plan defines new domain boundaries.
+* [ ] Plan defines Circle 2 acceptance harness.
+* [ ] Plan states out-of-scope / deferred items.
+* [ ] Plan asks maintainer to pick one sequencing strategy before implementation.
+
+## Definition of Done (team quality bar)
+
+* Trellis plan created/updated.
+* PRD records final decisions.
+* Source/OSS research notes captured where needed.
+* No code implementation begins until plan is approved.
+
+## Out of Scope (explicit)
+
+* Implementing Circle 2 runtime code in this brainstorm task.
+* Reopening Circle 1 unless planning finds a hard dependency.
+* Marketplace distribution or remote SaaS backend implementation details unless needed for sequencing.
+
+## Technical Notes
+
+* Initial source of truth: `.trellis/plans/coding-deepgent-full-cc-parity-roadmap.md`
+* Resume status: `.trellis/project-handoff.md`
+* Prior Circle 1 completion commits: `7248889`, `386602b`, `f073945`
+
+## Auto-Context Findings
+
+### Local `coding-deepgent` constraints
+
+* Circle 1 added local file-backed `runtime.store`, session JSONL ledger, recovery/evidence/compact/collapse views, active TUI bridge controls, and extension inspect/debug surfaces.
+* Current background subagent worker handles are process-local. Cross-process lifecycle requires a new daemon/worker substrate, not more CLI commands over the current manager.
+* Current `subagents` domain supports bounded child/fork execution and background records, but not mailbox, coordinator, worker addressing, team routing, or durable delivery.
+* Current `sessions` domain owns transcript/evidence/resume; it should not become a generic team/orchestration database.
+* Current `plugins` and `mcp` are local inspect/debug seams; install/enable/update/trust lifecycle is intentionally outside Circle 1.
+
+### `cc-haha` source notes
+
+* Worker/session ingress:
+  * `/root/claude-code-haha/src/cli/transports/ccrClient.ts`
+  * worker lifecycle protocol, `PUT /worker`, heartbeat, event upload, internal events, restore after worker restart.
+* Task lifecycle / stop control:
+  * `/root/claude-code-haha/src/cli/print.ts`
+  * `task_started`, `task_progress`, `task_notification`, `session_state_changed`, `stop_task`.
+  * `/root/claude-code-haha/src/entrypoints/sdk/controlSchemas.ts`
+  * explicit `stop_task` control schema.
+* Mailbox / swarm permission:
+  * `/root/claude-code-haha/src/context/mailbox.tsx`
+  * `/root/claude-code-haha/src/hooks/useInboxPoller.ts`
+  * `/root/claude-code-haha/src/hooks/useSwarmPermissionPoller.ts`
+  * worker/leader permission messages and inbox polling.
+* Coordinator:
+  * `/root/claude-code-haha/src/cli/print.ts`
+  * `coordinatorModeModule`, coordinator resume matching, worker-related status.
+  * `/root/claude-code-haha/src/components/PromptInput/*`
+  * coordinator task UI selection.
+* Remote / IDE control:
+  * `/root/claude-code-haha/src/cli/transports/SSETransport.ts`
+  * `/root/claude-code-haha/src/cli/transports/WebSocketTransport.ts`
+  * `/root/claude-code-haha/src/remote/*`
+  * `/root/claude-code-haha/src/services/mcp/vscodeSdkMcp.ts`
+* Daemon / cron / proactive:
+  * `/root/claude-code-haha/src/entrypoints/cli.tsx`
+  * `--daemon-worker`
+  * `/root/claude-code-haha/src/cli/print.ts`
+  * cron scheduler and proactive tick references.
+  * `/root/claude-code-haha/src/skills/bundled/loop.ts`
+  * `/root/claude-code-haha/src/skills/bundled/scheduleRemoteAgents.ts`
+* Extension lifecycle:
+  * `/root/claude-code-haha/src/services/plugins/pluginOperations.ts`
+  * `/root/claude-code-haha/src/services/plugins/PluginInstallationManager.ts`
+  * `/root/claude-code-haha/src/services/mcp/config.ts`
+  * plugin MCP loading, dedup, enabled/disabled config, marketplace/policy gates.
+* Session/cross-day memory:
+  * `/root/claude-code-haha/src/services/SessionMemory/sessionMemory.ts`
+  * `/root/claude-code-haha/src/services/extractMemories/extractMemories.ts`
+  * `/root/claude-code-haha/src/services/compact/sessionMemoryCompact.ts`
+
+## Research Notes
+
+### What similar tools do
+
+* OpenHands uses a sandbox/runtime client-server architecture with clear runtime interfaces, action execution server, event stream, and multiple runtime implementations including Docker/local/remote. Relevant sources: OpenHands runtime docs and `openhands/runtime/README.md`.
+* opencode advertises provider-agnostic TUI and client/server architecture, where TUI is only one possible client.
+* goose is a local desktop/CLI/API agent and treats extensions as MCP-based with install/enable/disable and access-control concepts.
+
+### Constraints from our repo/project
+
+* LangChain/LangGraph-native runtime should remain the hidden implementation default.
+* Existing `runtime.store` can support durable records, but not durable process worker handles.
+* Team/multi-agent runtime must not be added by overloading `run_subagent`, `sessions`, or `task` records.
+* Remote/IDE surfaces must be separate from CLI/TUI JSONL bridge.
+
+### Feasible approaches here
+
+**Approach A: Substrate-first Circle 2** (Recommended)
+
+* How it works:
+  * Wave 1 daemon/worker/session-event substrate.
+  * Wave 2 mailbox/send-message over durable substrate.
+  * Wave 3 coordinator/worker team runtime.
+  * Wave 4 remote/IDE control plane.
+  * Wave 5 extension lifecycle.
+  * Wave 6 cross-day continuity/memory.
+* Pros:
+  * Avoids fake mailbox/team features over process-local handles.
+  * Aligns with `cc-haha` worker/session ingress evidence and OpenHands/opencode client/server patterns.
+  * Gives later coordinator/remote work a real lifecycle foundation.
+* Cons:
+  * First wave is infrastructure-heavy and user-visible payoff is delayed.
+
+**Approach B: User-visible team first**
+
+* How it works:
+  * Build mailbox/coordinator user flows first using current file store and active process.
+  * Add daemon/remote later.
+* Pros:
+  * Faster visible parity with Agent/teams concepts.
+  * Good for demos.
+* Cons:
+  * High risk of repeating the Circle 1 background-subagent problem: process-local behavior masquerading as durable team runtime.
+  * Likely refactor later.
+
+**Approach C: Remote/IDE first**
+
+* How it works:
+  * Turn existing frontend SSE/gateway into a remote control plane first.
+  * Then add worker/session ingress and coordinator.
+* Pros:
+  * UI/control-plane progress is visible quickly.
+  * Aligns with opencode multi-client and OpenHands client/server directions.
+* Cons:
+  * Remote UI without daemon/worker substrate can become thin transport over weak lifecycle.
+  * Coordinator/mailbox still need later architectural work.
+
+## Expansion Sweep
+
+### Future evolution
+
+* Circle 2 likely becomes the boundary where `coding-deepgent` needs durable process orchestration, not only in-memory background threads.
+* Remote/IDE/daemon work should preserve a future API surface, not hard-code one CLI/TUI implementation.
+
+### Related scenarios
+
+* Permission prompts from workers must route to a leader/human without bypassing current permission policy.
+* Task/progress events should reuse session evidence/event stream concepts but not pollute transcript messages.
+
+### Failure and edge cases
+
+* Worker crash/restart, duplicate delivery, stale run ownership, stop/cancel races.
+* Message delivery idempotency, permission response timeout, remote reconnect/replay.
+* Extension install/enable trust and rollback.
+
+## Preliminary Recommendation
+
+Use Approach A: substrate-first. Circle 2 should start with a durable daemon/worker/session-event substrate, then mailbox, then coordinator/team runtime, then remote/IDE, then extension lifecycle, then cross-day memory.
+
+## Decision (ADR-lite)
+
+**Context**: Circle 2 introduces durable background lifecycle, mailbox, coordinator/team runtime, remote/IDE control, extension lifecycle, and cross-day continuity. These features cannot safely be modeled as more fields on current process-local subagent/background APIs.
+
+**Decision**: Use Approach A, substrate-first. Build durable daemon/worker/session-event substrate before mailbox/coordinator/remote features.
+
+**Consequences**:
+
+* First Circle 2 implementation wave will be infrastructure-heavy.
+* Later mailbox/coordinator/remote/IDE features can build on real lifecycle semantics instead of fake process-local handles.
+* Current Circle 1 active-TUI background controls remain valid as local process features, but not as durable team runtime.
+
+## Final Requirements
+
+* Create a Circle 2 execution plan that starts with daemon/worker/session-event substrate.
+* Split Circle 2 into ordered waves with clear scope, domain ownership, and acceptance criteria.
+* Include source evidence and OSS fallback notes for each wave.
+* Explicitly prevent boundary pollution in `sessions`, `subagents`, `runtime`, and `tool_system`.
+* Define Circle 2 acceptance harness before implementation begins.
+
+## Final Acceptance Criteria
+
+* [x] Circle 2 plan defines waves and sequencing.
+* [x] Plan includes source evidence and missing-source fallback rules.
+* [x] Plan defines new domain boundaries.
+* [x] Plan defines Circle 2 acceptance harness.
+* [x] Plan states out-of-scope / deferred items.
+* [x] Plan asks maintainer to pick one sequencing strategy before implementation.
+
+## Output
+
+* `.trellis/plans/coding-deepgent-circle-2-expanded-parity-plan.md`
diff --git a/.trellis/tasks/archive/2026-04/04-20-brainstorm-circle-2-parity-plan/task.json b/.trellis/tasks/archive/2026-04/04-20-brainstorm-circle-2-parity-plan/task.json
new file mode 100644
index 000000000..812f185c2
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-brainstorm-circle-2-parity-plan/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "brainstorm-circle-2-parity-plan",
+  "name": "brainstorm-circle-2-parity-plan",
+  "title": "brainstorm: Circle 2 parity execution plan",
+  "description": "",
+  "status": "completed",
+  "dev_type": "docs",
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-20",
+  "completedAt": "2026-04-20",
+  "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/archive/2026-04/04-20-circle-1-wave-1-f1-tool-permission-prompt-runtime-parity/prd.md b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f1-tool-permission-prompt-runtime-parity/prd.md
new file mode 100644
index 000000000..32ae68c8a
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f1-tool-permission-prompt-runtime-parity/prd.md
@@ -0,0 +1,51 @@
+# Circle 1 Wave 1 F1 Tool-Permission-Prompt-Runtime Parity
+
+## Goal
+
+Strengthen the local runtime control loop so `coding-deepgent` can behave like
+a daily-driver coding agent during real repository work, not only pass MVP
+contracts.
+
+## Acceptance Targets
+
+* Workflow A improves materially: the agent can independently complete typical
+  PR-level tasks in a medium-to-large repository with less user micromanagement.
+* Tool discovery, selection, permission handling, and prompt/runtime control
+  loop behavior feel dependable during sustained local coding tasks.
+* The family has a clear parity judgment against real Claude Code public
+  behavior and `cc-haha` runtime/tool references.
+
+## Planned Features
+
+* Re-audit local tool/runtime surfaces against daily-driver coding workflow
+  expectations.
+* Identify which current H01/H02/H03/runtime pieces are already strong enough
+  and which remain only MVP-complete.
+* Define a concrete implementation slice for the highest-value remaining gap.
+
+## Planned Extensions
+
+* Broad CLI/TUI polish
+* Provider-specific runtime internals
+* Full remote/IDE/runtime control-plane behavior
+
+## Technical Notes
+
+* Parent roadmap: `.trellis/plans/coding-deepgent-full-cc-parity-roadmap.md`
+* Parent decomposition: `.trellis/plans/coding-deepgent-circle-1-wave-1-runtime-core-plan.md`
+
+## Implementation Summary
+
+* Deferred tool execution is no longer artificially weaker than the main tool
+  surface when the target deferred capability returns a bounded
+  `Command(update=...)`.
+* `invoke_deferred_tool` now preserves the deferred capability's real bounded
+  result contract (`ToolMessage` or `Command(update=...)`) instead of throwing a
+  runtime error for command-update tools.
+* Focused tool-system tests now cover deferred command-update preservation.
+
+## Verification
+
+* `pytest -q coding-deepgent/tests/tool_system/test_tool_search.py coding-deepgent/tests/tool_system/test_tool_system_middleware.py -q`
+* `ruff check coding-deepgent/src/coding_deepgent/tool_system/deferred.py coding-deepgent/tests/tool_system/test_tool_search.py .trellis/spec/backend/tool-capability-contracts.md`
+* `python3 -m mypy coding-deepgent/src/coding_deepgent/tool_system/deferred.py coding-deepgent/tests/tool_system/test_tool_search.py`
diff --git a/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f1-tool-permission-prompt-runtime-parity/task.json b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f1-tool-permission-prompt-runtime-parity/task.json
new file mode 100644
index 000000000..738660b87
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f1-tool-permission-prompt-runtime-parity/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "circle-1-wave-1-f1-tool-permission-prompt-runtime-parity",
+  "name": "circle-1-wave-1-f1-tool-permission-prompt-runtime-parity",
+  "title": "Circle 1 Wave 1 F1 tool-permission-prompt-runtime parity",
+  "description": "Decompose and implement runtime control-loop parity for local daily-driver behavior.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P0",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-20",
+  "completedAt": "2026-04-20",
+  "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-20-full-cc-parity-roadmap",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2-context-session-memory-continuity/prd.md b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2-context-session-memory-continuity/prd.md
new file mode 100644
index 000000000..a3449b382
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2-context-session-memory-continuity/prd.md
@@ -0,0 +1,216 @@
+# Circle 1 Wave 1 F2 Context-Session-Memory Continuity
+
+## Goal
+
+Strengthen context, compact, session, and memory continuity so
+`coding-deepgent` can survive long single-day coding tasks without losing the
+main working thread after multiple rounds of pressure, compaction, resume, and
+continued editing.
+
+## What I already know
+
+* Circle 1 uses workflow-first acceptance, and this family primarily serves:
+  - Workflow A: repository takeover and sustained coding
+  - Workflow B: single-day long-task continuity
+* Current local baseline already includes:
+  - staged runtime pressure pipeline in `RuntimePressureMiddleware`
+  - live `snip -> microcompact -> collapse -> auto_compact`
+  - collapse transcript events and load-time collapsed history replay
+  - scoped session-memory artifact plus bounded assist/update policy
+  - resume/recovery brief/session evidence seams
+* Current local baseline is strong enough for the old MVP line, but that is not
+  sufficient for Circle 1 daily-driver parity.
+* Recent research already established that public `cc-haha` collapse behavior is
+  richer than our current local collapse semantics.
+
+## Assumptions (temporary)
+
+* The next implementation slice for this family should focus first on
+  continuity under long same-day work, not cross-day or team-runtime behavior.
+* The highest-value gap is likely in the interaction between:
+  - collapse/projection semantics
+  - session continuity/resume
+  - session-memory continuity aid quality
+* This task should choose the next implementation slice, not implement all
+  continuity improvements at once.
+
+## Open Questions
+
+* None for the decomposition pass.
+
+## Acceptance Targets
+
+* After this planning pass, the most important Circle 1 continuity gap is
+  explicit rather than hidden inside broad “context system” language.
+* The task identifies which parts of the current baseline are already strong
+  enough, and which parts remain only MVP-complete.
+* The next implementation slice is specific enough to turn into one concrete
+  code task without reopening the whole Circle 1 scope.
+
+## Planned Features
+
+* Re-audit current local context/session/memory continuity against the stronger
+  Circle 1 standard.
+* Map `cc-haha` / Claude Code continuity evidence onto current local modules.
+* Choose the next implementation slice for this family.
+
+## Planned Extensions
+
+* Cross-day continuity
+* Richer session-memory extraction/runtime
+* Team-runtime continuity
+* Remote / IDE / daemon continuity concerns
+
+## Out of Scope
+
+* Broad CLI/TUI work beyond what is needed to expose continuity semantics
+* Mailbox/coordinator/team-runtime continuity
+* Full extension-ecosystem lifecycle
+* Provider-specific internals that do not materially improve local continuity
+
+## Research Notes
+
+### `cc-haha` / Claude Code evidence
+
+Primary source points reviewed:
+
+* `/root/claude-code-haha/src/query.ts`
+* `/root/claude-code-haha/src/services/compact/grouping.ts`
+* `/root/claude-code-haha/src/utils/sessionStorage.ts`
+* `/root/claude-code-haha/src/services/SessionMemory/sessionMemory.ts`
+* `/root/claude-code-haha/src/services/SessionMemory/sessionMemoryUtils.ts`
+
+High-signal source-backed findings:
+
+* `contextCollapse.applyCollapsesIfNeeded(...)` runs before autocompact, and if
+  collapse gets the context under threshold, autocompact becomes a no-op.
+* Public comments describe collapse as a **read-time projection over full REPL
+  history**, with summary messages living in a collapse store and
+  `projectView()` replaying commits across turns.
+* Prompt-too-long recovery first tries `contextCollapse.recoverFromOverflow(...)`
+  to drain staged collapses before falling through to reactive compact.
+* `groupMessagesByApiRound(...)` defines the safe split unit as
+  **assistant API round / tool-complete round**, not arbitrary message cuts or
+  coarse human-turn grouping.
+* Transcript persistence and recovery code in `sessionStorage.ts` explicitly
+  handles DAG-like assistant/tool-result topologies, which matters for safe
+  continuity under long sessions.
+* Session memory in `cc-haha` is not just a static local note: it has
+  thresholds, initialization state, last summarized point, and isolated
+  extraction using `runForkedAgent(...)`.
+
+### Current local baseline
+
+Primary local surfaces reviewed:
+
+* `coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py`
+* `coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py`
+* `coding-deepgent/src/coding_deepgent/sessions/session_memory.py`
+
+Current strengths:
+
+* Runtime pressure order is already coherent and source-backed.
+* Live collapse can persist transcript events and load-time collapsed history is
+  replayable from raw session messages.
+* Overflow drain before reactive compact already exists locally.
+* Session-memory artifact is bounded, typed, and can assist compaction.
+* Resume and recovery surfaces already exist and are test-covered.
+
+Current likely parity pressure:
+
+* Local collapse is still centered on a **live request rewrite** mental model,
+  while `cc-haha` public comments point to a deeper projection/store-first
+  continuity system.
+* Local session-memory continuity is bounded and useful, but much simpler than
+  `cc-haha`'s thresholded, isolated extraction/runtime model.
+* Long-task continuity is likely limited less by raw existence of features and
+  more by how coherently collapse/session-memory/resume compose under repeated
+  use.
+
+## Evaluation
+
+### What is already strong enough
+
+* Runtime pressure ordering
+* Collapse-before-autocompact ordering
+* Overflow drain before reactive compact
+* Resume/continuity replay foundation
+* Bounded local session-memory artifact
+
+### What is still only MVP-complete
+
+* collapse as a daily-driver continuity system rather than a lighter
+  summarizer stage
+* richer preservation of granular working context across repeated pressure
+* stronger coupling between session-memory freshness and continuity after long
+  local work
+
+## Recommended Next Slice
+
+### Recommendation: `F2a collapse-session continuity v2`
+
+Recommended first implementation slice:
+
+* push the local collapse/session continuity path further toward a
+  **projection-first continuity system**
+* improve how long-task continuity survives repeated collapse/resume cycles
+* keep the implementation bounded to Circle 1 single-day continuity rather than
+  jumping immediately to cross-day memory/runtime complexity
+
+Why this slice first:
+
+* it directly serves Workflow B
+* it addresses the clearest current gap against public `cc-haha` continuity
+  shape
+* it improves both long-session work and resumed continuation quality
+* it avoids prematurely expanding into team-runtime or full session-memory
+  runtime parity
+
+### Deferred second slice: `F2b richer session-memory runtime`
+
+This remains important, but should follow after `F2a` unless new evidence shows
+session-memory freshness is the dominant blocker.
+
+## Decision (ADR-lite)
+
+**Context**: The current local baseline is good enough for MVP, but Circle 1
+raises the bar to long single-day task continuity. Public `cc-haha` evidence
+suggests a more projection-first collapse/session continuity system than the
+current local mental model, while session memory also appears richer upstream.
+
+**Decision**: Treat the next implementation target for this family as
+`F2a collapse-session continuity v2`, not “generic context improvements” and
+not “session-memory runtime v2 first.”
+
+**Consequences**:
+
+* The next concrete implementation task should focus on continuity semantics
+  under repeated collapse/resume cycles.
+* Session-memory runtime can remain bounded for now, but should be revisited
+  after `F2a`.
+* The family now has a concrete progression path rather than one broad
+  continuity bucket.
+
+## Technical Approach
+
+The next implementation PRD under this family should:
+
+* define the exact continuity effect to improve
+* map the target Claude Code / `cc-haha` behavior
+* state what continuity semantics must match:
+  - projection behavior
+  - resume behavior
+  - continuity after repeated pressure events
+* state what may remain local for now:
+  - full cross-day memory behavior
+  - provider-specific internals
+  - team-runtime continuity
+
+## Technical Notes
+
+* Parent roadmap: `.trellis/plans/coding-deepgent-full-cc-parity-roadmap.md`
+* Parent decomposition: `.trellis/plans/coding-deepgent-circle-1-wave-1-runtime-core-plan.md`
+* Relevant historical notes:
+  - `.trellis/tasks/archive/2026-04/04-16-cc-level-3-collapse-alignment/prd.md`
+  - `.trellis/tasks/archive/2026-04/04-16-cc-style-collapse-store-pressure-guard/prd.md`
+  - `.trellis/tasks/archive/2026-04/04-15-stage-23-context-pressure-and-session-continuity-closeout/prd.md`
diff --git a/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2-context-session-memory-continuity/task.json b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2-context-session-memory-continuity/task.json
new file mode 100644
index 000000000..76169d4a0
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2-context-session-memory-continuity/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "circle-1-wave-1-f2-context-session-memory-continuity",
+  "name": "circle-1-wave-1-f2-context-session-memory-continuity",
+  "title": "Circle 1 Wave 1 F2 context-session-memory continuity",
+  "description": "Decompose and implement long-session continuity parity for local single-day tasks.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P0",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-20",
+  "completedAt": "2026-04-20",
+  "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-20-full-cc-parity-roadmap",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a-collapse-session-continuity-v2/check.jsonl b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a-collapse-session-continuity-v2/check.jsonl
new file mode 100644
index 000000000..dfe6526d5
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a-collapse-session-continuity-v2/check.jsonl
@@ -0,0 +1,2 @@
+{"file": ".gemini/commands/trellis/finish-work.toml", "reason": "Finish work checklist"}
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a-collapse-session-continuity-v2/debug.jsonl b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a-collapse-session-continuity-v2/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a-collapse-session-continuity-v2/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-20-circle-1-wave-1-f2a-collapse-session-continuity-v2/implement.jsonl b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a-collapse-session-continuity-v2/implement.jsonl
new file mode 100644
index 000000000..f8d1d643e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a-collapse-session-continuity-v2/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": ".trellis/plans/coding-deepgent-full-cc-parity-roadmap.md", "reason": "Circle 1 and workflow acceptance target for this slice"}
+{"file": ".trellis/tasks/04-20-circle-1-wave-1-f2-context-session-memory-continuity/prd.md", "reason": "Parent family decision and recommended next slice"}
+{"file": ".trellis/spec/guides/cc-alignment-guide.md", "reason": "Parity evidence ladder and missing-source workflow"}
diff --git a/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a-collapse-session-continuity-v2/prd.md b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a-collapse-session-continuity-v2/prd.md
new file mode 100644
index 000000000..f05c765d8
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a-collapse-session-continuity-v2/prd.md
@@ -0,0 +1,179 @@
+# Circle 1 Wave 1 F2a Collapse-Session Continuity v2
+
+## Goal
+
+Improve long single-day continuity by making local collapse/session behavior
+more continuity-preserving and less coarse, so repeated collapse/resume cycles
+retain the working thread more like a projection system and less like a blunt
+prefix summary rewrite.
+
+## What I already know
+
+* Parent family `F2` already concluded that the first high-value continuity
+  slice should target collapse/session continuity rather than richer
+  session-memory runtime.
+* Public `cc-haha` evidence shows:
+  - collapse is described as a read-time projection over full history
+  - summary messages live in a collapse store
+  - prompt-too-long recovery drains staged collapses before reactive compact
+  - safe grouping logic elsewhere in compaction uses **API-round boundaries**
+    instead of arbitrary message cuts or coarse human-turn grouping
+* Current local runtime collapse still builds its persisted collapse coverage as
+  a **prefix** of the current projected message list:
+  - `collapse_live_messages_with_result()` collapses `clean_messages[:keep_start]`
+  - `_append_collapse_record()` uses `_covered_projection_ids_for_prefix(...)`
+* Current local baseline already has:
+  - collapse transcript events
+  - collapsed history replay on load/resume
+  - overflow drain before reactive compact
+  - continuity-facing compression view infrastructure
+
+## Assumptions (temporary)
+
+* The highest-value next improvement is not “more summaries,” but
+  **better span selection semantics** for what gets collapsed.
+* If collapse spans better preserve task/assistant/tool-result structure, long
+  same-day continuity should improve even before deeper session-memory work.
+
+## Open Questions
+
+* None for the decomposition pass.
+
+## Acceptance Targets
+
+* The next implementation slice is narrowed to one concrete continuity
+  improvement, not a broad context-system rewrite.
+* The chosen slice directly improves Workflow B:
+  single-day long-task continuity under repeated collapse/resume cycles.
+* The slice stays inside Circle 1 and does not sprawl into cross-day memory or
+  team-runtime behavior.
+
+## Planned Features
+
+* Reframe local collapse coverage from a prefix-only model toward a more
+  continuity-preserving span model.
+* Prefer spans that preserve assistant/tool-result structure rather than
+  arbitrary coarse prefix truncation.
+* Add tests proving the new collapse coverage semantics preserve better
+  continuity under realistic coding-agent message topologies.
+
+## Planned Extensions
+
+* richer session-memory extraction/runtime
+* cross-day continuity
+* stronger continuity across team-runtime/mailbox/coordinator features
+
+## Out of Scope
+
+* complete `cc-haha` contextCollapse subsystem parity
+* cross-day memory productization
+* mailbox/coordinator/team-runtime continuity
+* broad CLI/TUI changes not required to validate the runtime semantics
+
+## Source Notes
+
+### `cc-haha` evidence
+
+Reviewed:
+
+* `/root/claude-code-haha/src/query.ts`
+* `/root/claude-code-haha/src/services/compact/grouping.ts`
+* `/root/claude-code-haha/src/utils/sessionStorage.ts`
+
+High-signal facts:
+
+* `query.ts` comments describe collapse as read-time projection over full REPL
+  history, with summary messages outside the REPL array and replay across turns.
+* `query.ts` tries collapse drain before reactive compact on prompt-too-long.
+* `groupMessagesByApiRound(...)` explicitly treats **assistant API-round
+  boundaries** as the safe split point.
+* `sessionStorage.ts` explains transcript topology can be DAG-like, especially
+  around parallel tool use / tool results, which means arbitrary message cuts
+  are continuity-risky.
+
+### Local evidence
+
+Reviewed:
+
+* `coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py`
+* `coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py`
+* `coding-deepgent/src/coding_deepgent/compact/projection.py`
+
+High-signal facts:
+
+* local collapse chooses `collapsed_source = clean_messages[:keep_start]`
+* persisted collapse coverage is derived by `_covered_projection_ids_for_prefix(...)`
+* local replay and compression view already support non-destructive
+  collapse-event projections over raw history
+* local projection layer already knows about tool-use/tool-result repair and
+  pairing-sensitive message handling
+
+## Current Gap
+
+The main local continuity gap is:
+
+* collapse persistence/replay exists,
+* but the **unit of what gets collapsed** is still too coarse and too tied to
+  a prefix model.
+
+This means the local system is more likely to summarize away a large front chunk
+of history without respecting the more stable work-unit boundaries implied by:
+
+* assistant API rounds
+* tool-use / tool-result closure
+* coding-agent message topology
+
+## Recommended Implementation Slice
+
+### Recommendation: `F2a1 API-round-aware collapse spans`
+
+Make the first implementation slice:
+
+* replace or refine prefix-only collapse coverage so persisted collapse spans
+  align better with continuity-preserving work units
+* use a grouping model that better respects assistant/tool-result boundaries
+* keep replay/resume infrastructure unchanged where possible
+
+Why this first:
+
+* it directly targets continuity quality
+* it is smaller and more source-backed than “do full collapse subsystem parity”
+* it should improve repeated collapse/resume behavior without reopening the
+  entire memory/runtime family
+
+## Decision (ADR-lite)
+
+**Context**: Circle 1 raises the continuity bar from MVP-safe to daily-driver
+usable. Public `cc-haha` evidence suggests that collapse should preserve
+granular context better than a blunt prefix summary model. Local collapse
+already has durable records and replay, but its span selection remains coarse.
+
+**Decision**: Define the next implementation slice as `F2a1 API-round-aware
+collapse spans`.
+
+**Consequences**:
+
+* the next concrete implementation task should focus on span selection and
+  coverage semantics
+* session-memory runtime can remain secondary for now
+* the slice remains bounded and testable inside Circle 1
+
+## Technical Approach
+
+The next implementation PRD should decide:
+
+* what local grouping primitive to use for collapse span selection
+* how to preserve tool-call/tool-result structure while collapsing older
+  context
+* how persisted `covered_message_ids` should be derived from those spans
+* which current tests to extend:
+  - runtime pressure
+  - sessions/compression replay
+  - selected continuation history
+
+## Technical Notes
+
+* Parent task:
+  `.trellis/tasks/04-20-circle-1-wave-1-f2-context-session-memory-continuity/`
+* Parent roadmap:
+  `.trellis/plans/coding-deepgent-full-cc-parity-roadmap.md`
diff --git a/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a-collapse-session-continuity-v2/task.json b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a-collapse-session-continuity-v2/task.json
new file mode 100644
index 000000000..ebbd1656b
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a-collapse-session-continuity-v2/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "circle-1-wave-1-f2a-collapse-session-continuity-v2",
+  "name": "circle-1-wave-1-f2a-collapse-session-continuity-v2",
+  "title": "Circle 1 Wave 1 F2a collapse-session continuity v2",
+  "description": "Push collapse/session continuity toward projection-first single-day long-task parity.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P0",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-20",
+  "completedAt": "2026-04-20",
+  "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-20-circle-1-wave-1-f2-context-session-memory-continuity",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a1-api-round-aware-collapse-spans/check.jsonl b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a1-api-round-aware-collapse-spans/check.jsonl
new file mode 100644
index 000000000..dfe6526d5
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a1-api-round-aware-collapse-spans/check.jsonl
@@ -0,0 +1,2 @@
+{"file": ".gemini/commands/trellis/finish-work.toml", "reason": "Finish work checklist"}
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a1-api-round-aware-collapse-spans/debug.jsonl b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a1-api-round-aware-collapse-spans/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a1-api-round-aware-collapse-spans/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-20-circle-1-wave-1-f2a1-api-round-aware-collapse-spans/implement.jsonl b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a1-api-round-aware-collapse-spans/implement.jsonl
new file mode 100644
index 000000000..1dcd11f09
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a1-api-round-aware-collapse-spans/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/tasks/04-20-circle-1-wave-1-f2a-collapse-session-continuity-v2/prd.md", "reason": "Parent slice defines why API-round-aware collapse spans are the next continuity target"}
+{"file": ".trellis/spec/guides/cc-alignment-guide.md", "reason": "Evidence ladder and source-gap workflow for this parity slice"}
diff --git a/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a1-api-round-aware-collapse-spans/prd.md b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a1-api-round-aware-collapse-spans/prd.md
new file mode 100644
index 000000000..d7a6c13f4
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a1-api-round-aware-collapse-spans/prd.md
@@ -0,0 +1,83 @@
+# Circle 1 Wave 1 F2a1 API-Round-Aware Collapse Spans
+
+## Goal
+
+Refine local collapse span selection so continuity-preserving units survive
+long-task collapse/resume cycles better than the current coarse prefix model.
+
+## Acceptance Targets
+
+* Collapse coverage is chosen using a unit that better preserves
+  assistant/tool-result structure.
+* The resulting continuity behavior is more compatible with long same-day coding
+  tasks than the current prefix-only collapse coverage.
+* The slice remains bounded and directly testable.
+
+## Planned Features
+
+* Define a local grouping primitive for continuity-preserving collapse spans.
+* Replace or refine prefix-only covered-message derivation for persisted
+  collapse records.
+* Add focused tests for runtime pressure and collapse replay continuity.
+
+## Planned Extensions
+
+* richer collapse subsystem parity
+* stronger session-memory runtime
+* broader long-task continuity work
+
+## Decision (ADR-lite)
+
+**Context**: The current local collapse path persists replayable collapse
+records, but the preserved tail and covered span were still derived from a pure
+message-count suffix/prefix model. Public `cc-haha` evidence points toward
+assistant API-round boundaries as the safer continuity unit.
+
+**Decision**: For this slice, refine collapse tail selection by snapping the
+preserved tail backward to the nearest recent assistant-round boundary when the
+tail would otherwise begin on a non-assistant message.
+
+**Consequences**:
+
+* local collapse becomes less coarse without requiring a full hidden
+  `contextCollapse` subsystem clone
+* long-task continuity should improve when the recent tail would otherwise cut
+  through an assistant-led work unit
+* deeper group/commit-log parity remains future work
+
+## Implementation Summary
+
+* `runtime_pressure.py` now computes collapse keep-start through a dedicated
+  helper that first preserves tool-call/tool-result pairing, then snaps the
+  preserved tail backward to the nearest assistant-round boundary when
+  applicable.
+* session-memory continuity handling was tightened in the same pass:
+  - freshness/status now considers token and tool-call pressure when metrics
+    exist
+  - compact/runtime assist remains conservative: if `message_count` already
+    lags, the session-memory artifact is not injected as a compact assist
+* focused runtime-pressure tests cover:
+  - preserving a recent assistant round in the live collapse tail
+  - persisting collapse coverage that stops before the preserved assistant round
+* focused session-memory tests cover:
+  - stale status when token pressure crosses threshold
+  - conservative assist behavior for stale memory artifacts
+* runtime-pressure contract docs now record that preserved-tail selection may
+  snap backward to a recent assistant-round boundary.
+
+## Verification
+
+* `pytest -q coding-deepgent/tests/compact/test_runtime_pressure.py -q`
+* `pytest -q coding-deepgent/tests/sessions/test_session_memory_middleware.py coding-deepgent/tests/sessions/test_session_contributions.py coding-deepgent/tests/sessions/test_sessions.py -q`
+* `pytest -q coding-deepgent/tests/compact/test_runtime_pressure.py coding-deepgent/tests/sessions/test_session_memory_middleware.py coding-deepgent/tests/sessions/test_session_contributions.py coding-deepgent/tests/sessions/test_sessions.py coding-deepgent/tests/cli/test_cli.py -q`
+* `pytest -q coding-deepgent/tests/sessions/test_sessions.py coding-deepgent/tests/cli/test_cli.py -q`
+* `ruff check coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py coding-deepgent/tests/compact/test_runtime_pressure.py .trellis/spec/backend/runtime-pressure-contracts.md`
+* `python3 -m mypy coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py coding-deepgent/tests/compact/test_runtime_pressure.py`
+* `python3 -m mypy coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py coding-deepgent/src/coding_deepgent/cli_service.py`
+* `ruff check coding-deepgent/src/coding_deepgent/sessions/session_memory.py coding-deepgent/src/coding_deepgent/sessions/session_memory_middleware.py coding-deepgent/tests/sessions/test_session_memory_middleware.py coding-deepgent/tests/sessions/test_session_contributions.py coding-deepgent/tests/sessions/test_sessions.py`
+* `python3 -m mypy coding-deepgent/src/coding_deepgent/sessions/session_memory.py coding-deepgent/src/coding_deepgent/sessions/session_memory_middleware.py coding-deepgent/tests/sessions/test_session_memory_middleware.py coding-deepgent/tests/sessions/test_session_contributions.py coding-deepgent/tests/sessions/test_sessions.py`
+
+## Technical Notes
+
+* Parent task:
+  `.trellis/tasks/04-20-circle-1-wave-1-f2a-collapse-session-continuity-v2/`
diff --git a/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a1-api-round-aware-collapse-spans/task.json b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a1-api-round-aware-collapse-spans/task.json
new file mode 100644
index 000000000..1453f6e2b
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f2a1-api-round-aware-collapse-spans/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "circle-1-wave-1-f2a1-api-round-aware-collapse-spans",
+  "name": "circle-1-wave-1-f2a1-api-round-aware-collapse-spans",
+  "title": "Circle 1 Wave 1 F2a1 API-round-aware collapse spans",
+  "description": "Refine collapse span selection so continuity-preserving units survive long-task collapse/resume cycles.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P0",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-20",
+  "completedAt": "2026-04-20",
+  "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-20-circle-1-wave-1-f2a-collapse-session-continuity-v2",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f3-todo-task-plan-verify-daily-driver/prd.md b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f3-todo-task-plan-verify-daily-driver/prd.md
new file mode 100644
index 000000000..d75fec94c
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f3-todo-task-plan-verify-daily-driver/prd.md
@@ -0,0 +1,46 @@
+# Circle 1 Wave 1 F3 Todo-Task-Plan-Verify Daily-Driver
+
+## Goal
+
+Turn the existing todo/task/plan/verify surfaces into a practical personal
+workflow amplifier for complex coding tasks.
+
+## Acceptance Targets
+
+* Workflow C improves materially: todo/task/plan/verify is useful in real
+  complex development work, not just contract-correct.
+* The family has a clear parity judgment against Claude Code public behavior
+  and `cc-haha` workflow references.
+* The next implementation slice is chosen based on real throughput gains.
+
+## Planned Features
+
+* Re-audit current todo/task/plan/verify surfaces against daily-driver personal
+  workflow expectations.
+* Identify where workflow friction remains despite current MVP contracts.
+* Define a concrete follow-up slice for this family.
+
+## Planned Extensions
+
+* Coordinator / team-runtime planning
+* Mailbox-driven collaboration
+* Richer multi-agent workflow orchestration
+
+## Technical Notes
+
+* Parent roadmap: `.trellis/plans/coding-deepgent-full-cc-parity-roadmap.md`
+* Parent decomposition: `.trellis/plans/coding-deepgent-circle-1-wave-1-runtime-core-plan.md`
+
+## Implementation Summary
+
+* Frontend event flow now emits durable `task_snapshot` data alongside
+  `todo_snapshot`, so the local UI/bridge protocol can surface active task
+  graph state rather than only short-term todos.
+* The snapshot is fail-soft: if no runtime store is available, it emits an
+  empty task list instead of breaking the run flow.
+
+## Verification
+
+* `pytest -q coding-deepgent/tests/frontend/test_frontend_event_mapping.py coding-deepgent/tests/frontend/test_frontend_bridge.py coding-deepgent/tests/frontend/test_frontend_client.py coding-deepgent/tests/frontend/test_frontend_runs.py coding-deepgent/tests/frontend/test_frontend_gateway.py -q`
+* `ruff check coding-deepgent/src/coding_deepgent/frontend/event_mapping.py coding-deepgent/src/coding_deepgent/frontend/producer.py coding-deepgent/tests/frontend/test_frontend_event_mapping.py coding-deepgent/tests/frontend/test_frontend_bridge.py coding-deepgent/tests/frontend/test_frontend_client.py`
+* `python3 -m mypy coding-deepgent/src/coding_deepgent/frontend/event_mapping.py coding-deepgent/src/coding_deepgent/frontend/producer.py coding-deepgent/tests/frontend/test_frontend_event_mapping.py coding-deepgent/tests/frontend/test_frontend_bridge.py coding-deepgent/tests/frontend/test_frontend_client.py`
diff --git a/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f3-todo-task-plan-verify-daily-driver/task.json b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f3-todo-task-plan-verify-daily-driver/task.json
new file mode 100644
index 000000000..2eb0e8877
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f3-todo-task-plan-verify-daily-driver/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "circle-1-wave-1-f3-todo-task-plan-verify-daily-driver",
+  "name": "circle-1-wave-1-f3-todo-task-plan-verify-daily-driver",
+  "title": "Circle 1 Wave 1 F3 todo-task-plan-verify daily-driver",
+  "description": "Strengthen workflow-discipline surfaces so they become practical daily-driver amplifiers.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-20",
+  "completedAt": "2026-04-20",
+  "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-20-full-cc-parity-roadmap",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f4-observability-recovery-visibility/prd.md b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f4-observability-recovery-visibility/prd.md
new file mode 100644
index 000000000..06d4e787d
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f4-observability-recovery-visibility/prd.md
@@ -0,0 +1,46 @@
+# Circle 1 Wave 1 F4 Observability-Recovery Visibility
+
+## Goal
+
+Improve observability, evidence, and recovery visibility so long-task and
+runtime-core parity work is understandable enough to trust and debug.
+
+## Acceptance Targets
+
+* Workflows A and B gain clearer runtime/recovery visibility during real use.
+* This family supports Wave 1 runtime-core work rather than drifting into broad
+  analytics/platform work.
+* The next implementation slice is chosen based on daily-driver visibility
+  value.
+
+## Planned Features
+
+* Re-audit observability/evidence/recovery surfaces against Circle 1 workflow
+  needs.
+* Identify the highest-value visibility gap still blocking daily-driver trust.
+* Define the next implementation slice for this family.
+
+## Planned Extensions
+
+* External analytics backends
+* Perfetto / provider-specific telemetry
+* Remote/daemon observability surfaces
+
+## Technical Notes
+
+* Parent roadmap: `.trellis/plans/coding-deepgent-full-cc-parity-roadmap.md`
+* Parent decomposition: `.trellis/plans/coding-deepgent-circle-1-wave-1-runtime-core-plan.md`
+
+## Implementation Summary
+
+* Added a dedicated `Subagent activity:` recovery brief contribution that
+  summarizes recent background subagent/fork notifications separately from the
+  generic recent-evidence list.
+* This improves recovery visibility for complex task decomposition and
+  background child-agent work without expanding into full team-runtime parity.
+
+## Verification
+
+* `pytest -q coding-deepgent/tests/sessions/test_session_contributions.py coding-deepgent/tests/sessions/test_sessions.py coding-deepgent/tests/cli/test_cli.py -q`
+* `ruff check coding-deepgent/src/coding_deepgent/sessions/subagent_activity.py coding-deepgent/src/coding_deepgent/sessions/contribution_registry.py coding-deepgent/tests/sessions/test_session_contributions.py`
+* `python3 -m mypy coding-deepgent/src/coding_deepgent/sessions/subagent_activity.py coding-deepgent/src/coding_deepgent/sessions/contribution_registry.py coding-deepgent/tests/sessions/test_session_contributions.py`
diff --git a/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f4-observability-recovery-visibility/task.json b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f4-observability-recovery-visibility/task.json
new file mode 100644
index 000000000..1090a3146
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f4-observability-recovery-visibility/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "circle-1-wave-1-f4-observability-recovery-visibility",
+  "name": "circle-1-wave-1-f4-observability-recovery-visibility",
+  "title": "Circle 1 Wave 1 F4 observability-recovery visibility",
+  "description": "Improve observability, evidence, and recovery visibility as supporting infrastructure for daily-driver parity.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-20",
+  "completedAt": "2026-04-20",
+  "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-20-full-cc-parity-roadmap",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f5-bounded-subagent-fork-daily-driver/prd.md b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f5-bounded-subagent-fork-daily-driver/prd.md
new file mode 100644
index 000000000..5c1ad826b
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f5-bounded-subagent-fork-daily-driver/prd.md
@@ -0,0 +1,48 @@
+# Circle 1 Wave 1 F5 Bounded Subagent-Fork Daily-Driver
+
+## Goal
+
+Strengthen bounded local subagent and fork workflows so they become a reliable
+personal-efficiency tool during complex coding tasks.
+
+## Acceptance Targets
+
+* Workflow C improves materially through bounded child execution.
+* Local subagent/fork behavior becomes dependable enough for daily use without
+  requiring full mailbox/coordinator/team-runtime parity.
+* Remaining parity gaps for bounded local child execution are prioritized.
+
+## Planned Features
+
+* Re-audit local `run_subagent` / `run_fork` / resume / background slices
+  against single-developer complex-task use.
+* Identify the highest-value bounded child-runtime gap.
+* Define the next implementation slice for this family.
+
+## Planned Extensions
+
+* Mailbox / `SendMessage`
+* Coordinator synthesis
+* Richer team-runtime lifecycle
+
+## Technical Notes
+
+* Parent roadmap: `.trellis/plans/coding-deepgent-full-cc-parity-roadmap.md`
+* Parent decomposition: `.trellis/plans/coding-deepgent-circle-1-wave-1-runtime-core-plan.md`
+
+## Implementation Summary
+
+* Added `subagent_list` as a deferred background-run discovery tool.
+* The tool lists active background subagent/fork runs by default and can include
+  terminal runs with `include_terminal=True`.
+* Registered the new tool in the subagent package, tool container, and
+  capability registry so it is reachable through `ToolSearch` /
+  `invoke_deferred_tool`.
+* This closes a practical daily-driver gap: the user/model no longer has to
+  remember a run id perfectly to inspect active background work.
+
+## Verification
+
+* `pytest -q coding-deepgent/tests/subagents/test_subagents.py::test_subagent_list_reports_active_and_terminal_background_runs coding-deepgent/tests/tool_system/test_tool_search.py::test_tool_search_returns_deferred_builtin_subagent_controls -q`
+* `ruff check coding-deepgent/src/coding_deepgent/subagents/background.py coding-deepgent/src/coding_deepgent/subagents/schemas.py coding-deepgent/src/coding_deepgent/subagents/__init__.py coding-deepgent/src/coding_deepgent/containers/tool_system.py coding-deepgent/src/coding_deepgent/tool_system/capabilities.py coding-deepgent/tests/subagents/test_subagents.py coding-deepgent/tests/tool_system/test_tool_search.py`
+* `python3 -m mypy coding-deepgent/src/coding_deepgent/subagents/background.py coding-deepgent/src/coding_deepgent/subagents/schemas.py coding-deepgent/src/coding_deepgent/tool_system/capabilities.py coding-deepgent/tests/subagents/test_subagents.py coding-deepgent/tests/tool_system/test_tool_search.py`
diff --git a/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f5-bounded-subagent-fork-daily-driver/task.json b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f5-bounded-subagent-fork-daily-driver/task.json
new file mode 100644
index 000000000..c38593f23
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-circle-1-wave-1-f5-bounded-subagent-fork-daily-driver/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "circle-1-wave-1-f5-bounded-subagent-fork-daily-driver",
+  "name": "circle-1-wave-1-f5-bounded-subagent-fork-daily-driver",
+  "title": "Circle 1 Wave 1 F5 bounded subagent-fork daily-driver",
+  "description": "Strengthen bounded local subagent/fork workflow for single-developer complex tasks.",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P1",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-20",
+  "completedAt": "2026-04-20",
+  "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-20-full-cc-parity-roadmap",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
\ No newline at end of file
diff --git a/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-completion-remaining/check.jsonl b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-completion-remaining/check.jsonl
new file mode 100644
index 000000000..1422d008e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-completion-remaining/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": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-completion-remaining/debug.jsonl b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-completion-remaining/debug.jsonl
new file mode 100644
index 000000000..c1b287771
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-completion-remaining/debug.jsonl
@@ -0,0 +1,2 @@
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-completion-remaining/implement.jsonl b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-completion-remaining/implement.jsonl
new file mode 100644
index 000000000..adef5a974
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-completion-remaining/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/frontend/index.md", "reason": "Frontend development guide"}
diff --git a/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-completion-remaining/prd.md b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-completion-remaining/prd.md
new file mode 100644
index 000000000..9b72c819d
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-completion-remaining/prd.md
@@ -0,0 +1,31 @@
+# Circle 1 Completion Remaining UX And Extensions
+
+## Goal
+
+一次性完成 Circle 1 剩余工作：补齐 `Wave 2C/2D` 的 resume/history/projection/permission/recovery 可追溯面，补齐 `Wave 3` 的本地 extension inspect/validate/debug 面，并增加 Circle 1 acceptance harness。
+
+## Scope
+
+- Circle: `Circle 1`
+- Waves:
+  - `Wave 2C`: resume/history/projection UX
+  - `Wave 2D`: permission/recovery/runtime-event history
+  - `Wave 3`: usable local extension seams
+  - `Final`: Circle 1 acceptance harness
+
+## Non-Goals
+
+- mailbox / `SendMessage`
+- coordinator / team-runtime
+- remote / IDE control plane
+- daemon / cron / proactive automation
+- marketplace install/enable lifecycle
+
+## Acceptance Criteria
+
+- [x] CLI exposes session history/projection/timeline/evidence/events/permissions without requiring raw JSONL reads.
+- [x] CLI exposes local skills/MCP/hooks/plugins inspect/validate/debug surfaces.
+- [x] Circle 1 acceptance harness covers workflow A/B/C with deterministic local checks.
+- [x] Trellis roadmap/handoff/specs are updated.
+- [x] Full Python and TS validation passes.
+- [ ] Task is archived and session recorded.
diff --git a/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-completion-remaining/task.json b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-completion-remaining/task.json
new file mode 100644
index 000000000..d379c87e7
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-completion-remaining/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "coding-deepgent-circle-1-completion-remaining",
+  "name": "coding-deepgent-circle-1-completion-remaining",
+  "title": "Circle 1 Completion Remaining UX And Extensions",
+  "description": "",
+  "status": "completed",
+  "dev_type": "fullstack",
+  "scope": "coding-deepgent-circle-1-completion-remaining",
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-20",
+  "completedAt": "2026-04-20",
+  "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/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-control-surfaces/check.jsonl b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-control-surfaces/check.jsonl
new file mode 100644
index 000000000..1422d008e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-control-surfaces/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": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-control-surfaces/debug.jsonl b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-control-surfaces/debug.jsonl
new file mode 100644
index 000000000..c1b287771
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-control-surfaces/debug.jsonl
@@ -0,0 +1,2 @@
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-control-surfaces/implement.jsonl b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-control-surfaces/implement.jsonl
new file mode 100644
index 000000000..adef5a974
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-control-surfaces/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/frontend/index.md", "reason": "Frontend development guide"}
diff --git a/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-control-surfaces/prd.md b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-control-surfaces/prd.md
new file mode 100644
index 000000000..de2794bfc
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-control-surfaces/prd.md
@@ -0,0 +1,99 @@
+# Circle 1 Wave 2 Control Surfaces
+
+## Goal
+
+把 `Circle 1 / Wave 2` 从“可见”推进到“可控”：为现有 durable `tasks/plans` 与 background `subagents` 提供正式 CLI 控制入口，不重做 runtime，不新增 team-runtime/mailbox/daemon。
+
+## Circle / Wave
+
+- Circle: `Circle 1`
+- Wave: `Wave 2`
+- Parent roadmap: `.trellis/plans/coding-deepgent-full-cc-parity-roadmap.md`
+
+## Acceptance Workflows
+
+- Workflow A: Repository Takeover And Sustained Coding
+- Workflow C: Complex Task Decomposition
+
+## Expected Effect
+
+用户不再只能“看见 task/subagent snapshot”，而是可以直接用 product CLI：
+
+- 创建、列出、读取、更新 durable tasks
+- 保存、列出、读取 durable plans
+- 启动、列出、读取、续发输入、停止 background subagent runs
+
+如果这些能力仍只存在于模型工具面而没有正式用户控制入口，这包不算完成。
+
+## Planned Features
+
+- Add `coding-deepgent tasks ...` CLI group.
+- Add `coding-deepgent plans ...` CLI group.
+- Add active-frontend-process background subagent control through typed bridge inputs and TUI slash commands.
+- Add store-level `list_plans()` support so plans can be listed deterministically.
+- Add CLI renderers for task, plan, and subagent list surfaces.
+- Keep implementation on top of existing `tasks.store` and `subagents.background` seams.
+- Add a local file-backed runtime store backend so durable task/plan state survives process boundaries.
+
+## Non-Goals
+
+- No mailbox / `SendMessage`.
+- No coordinator or multi-agent team runtime.
+- No daemon/cron.
+- No remote/IDE control plane.
+- No standalone cross-process subagent control commands that pretend to manage process-local worker handles.
+- No fork-start CLI surface that depends on live parent runtime state.
+- No TUI command-mode redesign in this pack.
+
+## Target Claude Code Behavior
+
+- Claude Code exposes task/session state changes and task lifecycle through user-facing stream/control surfaces rather than only internal stores.
+- `cc-haha` stream/control layer includes `task_started`, `task_progress`, `task_notification`, `session_state_changed`, and explicit `stop_task` control messages.
+
+## Source Evidence
+
+- `/root/claude-code-haha/src/cli/print.ts`
+  - treats `task_started`, `task_progress`, `task_notification`, and `session_state_changed` as first-class streamed system/control surfaces
+  - handles `stop_task` control request path
+- `/root/claude-code-haha/src/entrypoints/sdk/controlSchemas.ts`
+  - contains explicit `stop_task` control schema
+- `/root/claude-code-haha/src/utils/sdkEventQueue.ts`
+  - models task lifecycle events as SDK/runtime-facing control data, not hidden implementation details
+
+## Alignment Matrix
+
+| Area | Source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Task lifecycle control | task lifecycle is externally surfaced | user can inspect/update durable tasks directly | CLI `tasks` commands | align | expose local durable task store |
+| Task stop/control | explicit control requests exist | user can stop or steer background work | CLI `subagents stop/send-input` | partial | apply to local background subagents only |
+| Plan management | plans guide longer work | user can persist/read/list plans explicitly | CLI `plans` commands | align | add missing `list_plans()` seam |
+| Rich team control | cc has broader control plane | team-runtime orchestration | mailbox/coordinator | defer | Circle 2 |
+| Fork control | same-config sibling branch exists | branch control from CLI | live fork control | defer | requires active parent runtime state |
+
+## Source Gap
+
+- target behavior: exact Claude Code UI/control affordances for interactive task stopping and richer panel controls.
+- Claude Code public evidence: task/session control is visibly surfaced.
+- `cc-haha` evidence: control and SDK event shapes are visible, but local product does not have the same remote/session-ingress architecture.
+- why insufficient: we can align effect and user affordance without copying transport/control topology.
+
+## Analogous OSS Review
+
+Not required for this pack. Existing `cc-haha` control/event evidence plus local runtime seams are enough to justify the local design.
+
+## Local Decision
+
+- Keep durable state ownership in `tasks.store` and `subagents.background`.
+- Add user entrypoints in `coding_deepgent.cli` and CLI-facing coordination in `coding_deepgent.cli_service`.
+- Add deterministic list rendering via `renderers/text.py`.
+- Reuse background subagent manager directly for list/status/send/stop/start.
+
+## Acceptance Criteria
+
+- [x] `coding-deepgent tasks list|get|create|update` works against the durable task store.
+- [x] `coding-deepgent plans list|get|save` works against the durable plan store.
+- [x] active frontend/bridge process can `run_background_subagent`, `subagent_send_input`, `subagent_stop`, and `refresh_snapshots`.
+- [x] `list_plans()` exists and is deterministic.
+- [x] CLI errors stay at the `ClickException` boundary for invalid inputs.
+- [x] Focused tests cover CLI commands, added store behavior, and frontend bridge control inputs.
+- [x] Trellis specs and handoff are updated.
diff --git a/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-control-surfaces/task.json b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-control-surfaces/task.json
new file mode 100644
index 000000000..2234c1edb
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-control-surfaces/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "coding-deepgent-circle-1-wave-2-control-surfaces",
+  "name": "coding-deepgent-circle-1-wave-2-control-surfaces",
+  "title": "Circle 1 Wave 2 Control Surfaces",
+  "description": "",
+  "status": "completed",
+  "dev_type": "fullstack",
+  "scope": "coding-deepgent-circle-1-wave-2-control-surfaces",
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-20",
+  "completedAt": "2026-04-20",
+  "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/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-runtime-surfaces/check.jsonl b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-runtime-surfaces/check.jsonl
new file mode 100644
index 000000000..97a3cf670
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-runtime-surfaces/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": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Backend quality and validation expectations"}
+{"file": ".trellis/spec/frontend/quality-guidelines.md", "reason": "Frontend testing and typecheck expectations"}
diff --git a/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-runtime-surfaces/debug.jsonl b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-runtime-surfaces/debug.jsonl
new file mode 100644
index 000000000..c1b287771
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-runtime-surfaces/debug.jsonl
@@ -0,0 +1,2 @@
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-runtime-surfaces/implement.jsonl b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-runtime-surfaces/implement.jsonl
new file mode 100644
index 000000000..2e236554c
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-runtime-surfaces/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": ".trellis/spec/frontend/index.md", "reason": "Frontend development guide"}
+{"file": ".trellis/spec/backend/runtime-context-compaction-contracts.md", "reason": "Runtime compact session contract index"}
+{"file": ".trellis/project-handoff.md", "reason": "Current coding-deepgent mainline state and next recommended Wave 2 task"}
+{"file": ".trellis/spec/guides/cc-alignment-guide.md", "reason": "cc-haha alignment and OSS fallback rules"}
+{"file": ".trellis/plans/coding-deepgent-full-cc-parity-roadmap.md", "reason": "Circle 1 Wave 2 roadmap contract"}
+{"file": ".trellis/spec/frontend/state-management.md", "reason": "Frontend reducer state ownership for new snapshot events"}
+{"file": ".trellis/spec/frontend/type-safety.md", "reason": "Frontend protocol type contract for new events"}
diff --git a/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-runtime-surfaces/prd.md b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-runtime-surfaces/prd.md
new file mode 100644
index 000000000..b4b130b71
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-runtime-surfaces/prd.md
@@ -0,0 +1,100 @@
+# Circle 1 Wave 2 Runtime-Exposing CLI/TUI Surfaces
+
+## Goal
+
+推进 `Circle 1 / Wave 2` 的首个整包：把 Wave 1 已完成的 runtime/session/compact/task/subagent 能力暴露到 CLI/TUI 可见层，避免“后台有语义，用户看不见、恢复时不可判断”的差距。
+
+## Circle / Wave
+
+- Circle: `Circle 1`
+- Wave: `Wave 2: Runtime-Exposing CLI/TUI Surfaces`
+- Parent roadmap: `.trellis/plans/coding-deepgent-full-cc-parity-roadmap.md`
+
+## Acceptance Workflows
+
+- Workflow A: Repository Takeover And Sustained Coding
+- Workflow B: Long Session Continuity
+- Workflow C: Complex Task Decomposition
+
+## Expected Effect
+
+本轮对齐的核心效果不是复制 Claude Code UI 外观，而是让用户在本地 CLI/TUI 中看见和判断：
+
+- 当前 resume/model-visible context 采用 raw / compact / collapse 哪一种 projection。
+- 哪些 transcript message 被 compact/collapse 隐藏，哪些仍进入模型上下文。
+- session memory 是 current 还是 stale。
+- 当前 todo/task/subagent/runtime 事件是否已经进入用户可见层。
+- permission / failed tool / recovery 状态是否可被及时定位。
+
+如果这些信息仍只能靠读 JSONL 或内部测试判断，本轮不算完成。
+
+## Planned Features
+
+- Add a CLI session inspection command that renders session metadata, recovery brief, selected projection mode, compact/collapse timeline, raw transcript visibility, model projection rows, and session-memory status.
+- Add a renderer-neutral frontend `context_snapshot` event carrying selected context/projection metrics after each completed run.
+- Add a renderer-neutral frontend `subagent_snapshot` event carrying recent subagent sidechain/activity summary when available.
+- Extend the React/Ink CLI reducer and panels to render context snapshot, task snapshot, and subagent snapshot.
+- Update protocol docs/specs and tests for Python protocol, frontend bridge, reducer, CLI renderers, and session inspection.
+
+## Non-Goals
+
+- Full Claude Code visual clone.
+- Remote control, IDE, daemon, mailbox, coordinator, or team-runtime surfaces.
+- Plugin marketplace/install lifecycle.
+- Reopening Wave 1 runtime semantics unless a regression is found.
+
+## Target Claude Code Behavior
+
+- Claude Code exposes session identity, resume behavior, permission waits, tool progress, task/background notifications, and context/compaction effects through user-facing CLI/stream surfaces rather than making them only internal records.
+- Claude Code resume/internal-event paths are stateful and compaction-aware; users should not need to reason from raw transcript storage alone.
+
+## Source Evidence
+
+- `/root/claude-code-haha/src/cli/print.ts`
+  - validates resume/rewind inputs before running
+  - switches behavior around resume/session inputs
+  - forwards incremental messages during turns so progress remains externally visible
+  - reports session state changes, task notifications, permission waits, and post-turn summaries as system/stream events
+- `/root/claude-code-haha/src/cli/transports/ccrClient.ts`
+  - reads foreground internal events from the last compaction boundary for session resume
+  - reads subagent internal events separately for resume continuity
+- `/root/claude-code-haha/src/services/compact/grouping.ts`
+  - treats API-round boundaries as safe compaction grouping points
+
+## Alignment Matrix
+
+| Area | Source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Session inspect | Resume/session paths are explicit and validated | user can inspect resume state before continuing | `sessions inspect` over loaded JSONL session | align | expose current local session model-view and timeline |
+| Compaction visibility | internal events resume from compaction boundary | user can see selected compact/collapse projection | compression view renderer | align | use existing `build_compression_view` as source of truth |
+| Task/runtime events | stream surfaces filter but preserve task/session state changes | TUI shows runtime facts without parsing logs | typed frontend events and reducer panels | partial | expose local snapshots; broader CC event taxonomy deferred |
+| Subagent continuity | subagent internal events have separate resume path | user can see recent subagent activity | subagent snapshot event/panel | partial | summarize existing sidechain/evidence; no team runtime |
+| UI appearance | Claude Code has richer Ink UI | better daily-driver visibility | simple panels over typed state | defer | do not copy visual details in this wave |
+
+## Source Gap
+
+- target behavior: exact Claude Code private UI layout and hidden collapse UI affordances.
+- Claude Code public evidence: visible CLI/stream behavior and resume-oriented commands exist, but private UI implementation details are not fully public.
+- `cc-haha` evidence: enough evidence exists for session/resume/events/compaction boundaries; not enough to justify pixel/UI cloning.
+- why insufficient: Circle 1 benefit is runtime visibility, not visual cloning.
+
+## Analogous OSS Review
+
+Not needed for this pack. The required local behavior can be justified from real public CLI behavior, `cc-haha` session/stream/compact references, and existing `coding-deepgent` runtime contracts.
+
+## Local Decision
+
+- Keep domain facts in Python `sessions` / `frontend` protocol code.
+- Keep CLI rendering in `renderers/text.py` and Typer commands.
+- Keep TUI display state in TS reducer and components only.
+- Use existing `build_compression_view` rather than inventing a second projection model.
+- Add bounded snapshot payloads, not raw transcript dumps, to the live TUI.
+
+## Acceptance Criteria
+
+- [x] `coding-deepgent sessions inspect <session_id>` renders summary, recovery brief, projection mode, model projection, raw visibility, timeline, and session memory status.
+- [x] The frontend bridge emits `context_snapshot` and `subagent_snapshot` after completed runs.
+- [x] The React/Ink CLI renders context, task, and subagent snapshots.
+- [x] Protocol validation rejects malformed new payloads.
+- [x] Tests cover CLI command behavior, Python protocol/event mapping, bridge emission order, TS reducer behavior, and TS protocol parsing.
+- [x] Relevant Trellis specs are updated for the new runtime-exposing surfaces.
diff --git a/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-runtime-surfaces/task.json b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-runtime-surfaces/task.json
new file mode 100644
index 000000000..29e07d580
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-1-wave-2-runtime-surfaces/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "coding-deepgent-circle-1-wave-2-runtime-surfaces",
+  "name": "coding-deepgent-circle-1-wave-2-runtime-surfaces",
+  "title": "Circle 1 Wave 2 Runtime-Exposing CLI TUI Surfaces",
+  "description": "",
+  "status": "completed",
+  "dev_type": "fullstack",
+  "scope": "coding-deepgent-circle-1-wave-2-runtime-surfaces",
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-20",
+  "completedAt": "2026-04-20",
+  "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/archive/2026-04/04-20-coding-deepgent-circle-2-expanded-parity-baseline/check.jsonl b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-2-expanded-parity-baseline/check.jsonl
new file mode 100644
index 000000000..1422d008e
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-2-expanded-parity-baseline/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": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-2-expanded-parity-baseline/debug.jsonl b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-2-expanded-parity-baseline/debug.jsonl
new file mode 100644
index 000000000..c1b287771
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-2-expanded-parity-baseline/debug.jsonl
@@ -0,0 +1,2 @@
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
+{"file": ".gemini/commands/trellis/check-frontend.toml", "reason": "Frontend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-2-expanded-parity-baseline/implement.jsonl b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-2-expanded-parity-baseline/implement.jsonl
new file mode 100644
index 000000000..adef5a974
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-2-expanded-parity-baseline/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/frontend/index.md", "reason": "Frontend development guide"}
diff --git a/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-2-expanded-parity-baseline/prd.md b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-2-expanded-parity-baseline/prd.md
new file mode 100644
index 000000000..b2d639fd3
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-2-expanded-parity-baseline/prd.md
@@ -0,0 +1,41 @@
+# Circle 2 Expanded Parity Baseline
+
+## Goal
+
+一口气完成 Circle 2 本地 expanded parity baseline：实现 substrate-first 计划里的 durable worker/event substrate、mailbox、local team orchestration、remote-control records、extension lifecycle、cross-day continuity、Circle 2 acceptance harness。
+
+## Requirements
+
+- Implement durable local event stream and worker records.
+- Implement mailbox send/list/ack with idempotent delivery key support.
+- Implement local team run records with coordinator/worker assignments and progress synthesis.
+- Implement local remote-control record/event replay surface without pretending to have hosted SaaS.
+- Implement extension lifecycle state: install/register, enable/disable, update metadata, rollback.
+- Implement continuity artifacts for cross-day resume/memory notes.
+- Add CLI command groups and tests.
+- Update Trellis docs and project status.
+
+## Acceptance Criteria
+
+- [x] `workers` / `events` CLI commands work over durable local store.
+- [x] `mailbox` CLI commands support send/list/ack and duplicate delivery protection.
+- [x] `teams` CLI commands support create/assign/progress/status.
+- [x] `remote` CLI commands support session registration, control, and event replay records.
+- [x] `extension-lifecycle` CLI commands support register/enable/disable/update/rollback.
+- [x] `continuity` CLI commands support save/list/show continuity artifacts.
+- [x] `acceptance circle2` passes.
+- [x] Full Python/TS validation passes.
+
+## Out of Scope
+
+- Hosted SaaS session ingress.
+- Multi-user auth/billing.
+- Real IDE plugin implementation.
+- Public marketplace backend.
+- Cross-machine worker process supervision.
+
+## Technical Notes
+
+- Canonical plan: `.trellis/plans/coding-deepgent-circle-2-expanded-parity-plan.md`
+- Use local `runtime.store` file backend as durable substrate.
+- Keep new domains out of `sessions/`, `subagents/tools.py`, `tool_system/`, and `frontend/producer.py`.
diff --git a/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-2-expanded-parity-baseline/task.json b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-2-expanded-parity-baseline/task.json
new file mode 100644
index 000000000..7ec126466
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-coding-deepgent-circle-2-expanded-parity-baseline/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "coding-deepgent-circle-2-expanded-parity-baseline",
+  "name": "coding-deepgent-circle-2-expanded-parity-baseline",
+  "title": "Circle 2 Expanded Parity Baseline",
+  "description": "",
+  "status": "completed",
+  "dev_type": "fullstack",
+  "scope": "coding-deepgent-circle-2-expanded-parity-baseline",
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-20",
+  "completedAt": "2026-04-20",
+  "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/archive/2026-04/04-20-extract-coding-agent-repo/check.jsonl b/.trellis/tasks/archive/2026-04/04-20-extract-coding-agent-repo/check.jsonl
new file mode 100644
index 000000000..2ec39d42f
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-extract-coding-agent-repo/check.jsonl
@@ -0,0 +1,7 @@
+{"file": ".trellis/tasks/04-20-extract-coding-agent-repo/prd.md", "reason": "Check migration against acceptance criteria"}
+{"file": ".trellis/spec/backend/directory-structure.md", "reason": "Check backend path and ownership docs after extraction"}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Check validation and forbidden runtime-state migration"}
+{"file": ".trellis/spec/frontend/directory-structure.md", "reason": "Check frontend docs and scripts after extraction"}
+{"file": ".trellis/spec/guides/mainline-scope-guide.md", "reason": "Check extracted repo no longer points at old tutorial root"}
+{"file": ".trellis/spec/guides/trellis-doc-map-guide.md", "reason": "Check Trellis layer ownership after migration"}
+{"file": ".trellis/spec/guides/architecture-posture-guide.md", "reason": "Check clean extraction boundary choices"}
diff --git a/.trellis/tasks/archive/2026-04/04-20-extract-coding-agent-repo/debug.jsonl b/.trellis/tasks/archive/2026-04/04-20-extract-coding-agent-repo/debug.jsonl
new file mode 100644
index 000000000..a4528cb4c
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-extract-coding-agent-repo/debug.jsonl
@@ -0,0 +1,3 @@
+{"file": ".trellis/tasks/04-20-extract-coding-agent-repo/prd.md", "reason": "Migration requirements and verification notes"}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Backend validation expectations"}
+{"file": ".trellis/spec/frontend/quality-guidelines.md", "reason": "Frontend validation expectations"}
diff --git a/.trellis/tasks/archive/2026-04/04-20-extract-coding-agent-repo/implement.jsonl b/.trellis/tasks/archive/2026-04/04-20-extract-coding-agent-repo/implement.jsonl
new file mode 100644
index 000000000..dcfe83a39
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-extract-coding-agent-repo/implement.jsonl
@@ -0,0 +1,10 @@
+{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
+{"file": ".trellis/spec/frontend/index.md", "reason": "Frontend development guide"}
+{"file": ".trellis/tasks/04-20-extract-coding-agent-repo/prd.md", "reason": "Confirmed migration plan and acceptance criteria"}
+{"file": ".trellis/spec/backend/directory-structure.md", "reason": "Backend product root and domain ownership rules to rewrite for new repo"}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Backend validation and source-root expectations"}
+{"file": ".trellis/spec/frontend/directory-structure.md", "reason": "Frontend path expectations after promoting product root"}
+{"file": ".trellis/spec/guides/mainline-scope-guide.md", "reason": "Rewrite mainline scope for extracted repo"}
+{"file": ".trellis/spec/guides/trellis-doc-map-guide.md", "reason": "Trellis document ownership for curated migration"}
+{"file": ".trellis/spec/guides/architecture-posture-guide.md", "reason": "Prefer clean extraction boundaries over old monorepo compatibility"}
diff --git a/.trellis/tasks/archive/2026-04/04-20-extract-coding-agent-repo/prd.md b/.trellis/tasks/archive/2026-04/04-20-extract-coding-agent-repo/prd.md
new file mode 100644
index 000000000..e851ab6d6
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-extract-coding-agent-repo/prd.md
@@ -0,0 +1,284 @@
+# brainstorm: extract coding agent repo
+
+## Goal
+
+将当前主线产品 `coding-deepgent/` 连同必要的 Trellis 协作、规范、计划和高价值历史决策移植到一个新的独立 git repository，形成可以独立开发、测试、记录任务和后续发布的 `coding-agent` 产品仓库。
+
+本任务先制定一次性迁移计划；在用户确认后，按计划一次性执行迁移、文档修正、验证和提交。
+
+## What I already know
+
+* 用户希望把 coding-agent 移植出去，并且把相关 Trellis 文档一起移植。
+* 用户倾向一次性做完，而不是多轮零散迁移。
+* 当前 repo 的产品主线是 `coding-deepgent/`。
+* 当前 repo 的 tutorial/reference 层包括 `agents/`, `agents_deepagents/`, `docs/`, `web/`, `skills/`，默认不属于本次产品移植范围。
+* 当前工作区 clean；当前分支是 `codex/stage-12-14-context-compact-foundation`，比 origin ahead 107 commits。
+* 当前没有 active Trellis task；本 brainstorm task 是 `.trellis/tasks/04-20-extract-coding-agent-repo/`。
+* `coding-deepgent/pyproject.toml` 当前项目名是 `coding-deepgent`，console scripts 是 `coding-deepgent` 和 `coding-deepgent-ui`。
+* Python package 当前是 `src/coding_deepgent`。
+* React/Ink CLI frontend 在 `frontend/cli`，package name 是 `@coding-deepgent/cli-frontend`，bin 是 `coding-deepgent-ui`。
+* `coding-deepgent/README.md` 当前使用 `../AGENTS.md` 和 `../.trellis/...` 作为 canonical docs 路径；移植后需要改为 repo-root 路径。
+* `.trellis/` 是当前产品线的 canonical coordination layer，不是普通附属笔记。
+* `.trellis/spec/` 内大量规则仍以 `coding-deepgent/` 作为实现根路径；移植后需要将语义改为 repo root 下的 `src/`, `tests/`, `frontend/`。
+* `.trellis/tasks/archive/2026-04/` 有大量与产品演进相关的历史 PRD，但也包含旧分支名、旧 PR、旧 monorepo 路径和操作日志式上下文。
+
+## Assumptions (temporary)
+
+* 新仓库路径使用 `/root/coding-agent`，除非用户指定其他路径。
+* 新仓库初始阶段保留 Python package 名 `coding_deepgent` 和 CLI 命令 `coding-deepgent`，先确保迁移后行为不变；重命名为 `coding_agent` / `coding-agent` 放入后续独立任务。
+* 本次迁移使用 clean snapshot import，不强保旧仓库 git history。
+* 不复制 secrets、runtime state、cache、local memory database、node_modules。
+* 迁移结果需要在新 repo 内独立通过 Python 后端测试、lint/typecheck、Trellis 链接检查，以及 frontend CLI typecheck/test。
+
+## Open Questions
+
+* 用户是否接受推荐方案：新建独立 repo `/root/coding-agent`，先保留现有 package/CLI 名称，后续再做产品重命名？
+
+## Requirements (evolving)
+
+* 新建独立 git repo，作为迁移后的 source of truth。
+* 将 `coding-deepgent/` 的产品代码提升到新 repo 根目录。
+* Curated migrate Trellis：保留 workflow/scripts/spec/plans/project-handoff/config，以及高价值历史任务归档；剔除本地身份、当前任务指针、运行态和普通会话 journal。
+* 将新 repo 文档改成 repo-root product mainline，不再说当前主线是 `coding-deepgent/` 子目录。
+* 保留可验证、可回滚的迁移证据：source commit、复制清单、排除清单、验证命令和结果。
+* 一次性完成迁移、Trellis 修正、验证、初始 commit。
+
+## Acceptance Criteria (evolving)
+
+* [x] `/root/coding-agent` 存在且是独立 git repository。
+* [x] 新 repo 根目录包含产品文件：`pyproject.toml`, `README.md`, `PROJECT_PROGRESS.md`, `src/`, `tests/`, `frontend/`, `.trellis/`, `AGENTS.md`。
+* [x] 新 repo 不包含 `.env`, `.coding-deepgent/memory.db`, `.omx/`, `.mypy_cache/`, `.pytest_cache/`, `.ruff_cache/`, `node_modules/`, `__pycache__/`。
+* [x] 新 repo 的 `AGENTS.md`, `README.md`, `.trellis/project-handoff.md`, `.trellis/spec/*` 不再把 `coding-deepgent/` 子目录描述为当前实现根。
+* [x] Trellis 脚本可运行：`python3 ./.trellis/scripts/get_context.py`。
+* [x] Trellis 链接检查可运行：`python3 ./.trellis/scripts/check_trellis_links.py`。
+* [x] Python 验证在新 repo 内通过或记录明确阻塞：`pytest -q`, `ruff check .`, `mypy src`。
+* [x] Frontend 验证在新 repo 内通过或记录明确阻塞：`npm --prefix frontend/cli test`, `npm --prefix frontend/cli run typecheck`。
+* [x] 新 repo 有 initial commit，commit message 说明这是迁移快照。
+
+## Definition of Done
+
+* 迁移清单、排除清单、路径语义修正和验证结果写入 active PRD。
+* 新 repo 初始化完成并有清晰 initial commit。
+* 原 repo 不被破坏；原 repo 只新增/更新本 planning task 相关 Trellis 记录。
+* 若验证失败，失败原因和下一步修复范围明确记录，不做模糊完成。
+
+## Research Notes
+
+### What similar extraction workflows usually do
+
+* Monorepo-to-repo extraction normally has two choices：history-preserving filter 或 clean snapshot import。
+* History-preserving extraction is useful when blame/log continuity matters, but it is brittle when only part of `.trellis/` should move and paths need semantic rewriting.
+* Clean snapshot import is simpler, easier to audit, and better when the new repo intentionally changes ownership boundaries.
+
+### Constraints from this repo
+
+* `coding-deepgent/` is currently nested under a larger tutorial/reference repo.
+* `.trellis/` is shared at old repo root, but the high-value Trellis content now primarily serves `coding-deepgent`.
+* `.trellis/tasks/archive` contains product-relevant decisions but also contains many historical file paths and branch references that should not become active executable context.
+* `coding-deepgent` package and CLI names are currently used by tests, README, frontend scripts, and probably runtime env vars.
+
+### Feasible approaches here
+
+**Approach A: clean snapshot extraction with curated Trellis migration** (Recommended)
+
+* How it works:
+  * Create `/root/coding-agent`.
+  * Copy tracked product files from `coding-deepgent/` to repo root.
+  * Copy high-value `.trellis/` files and selected task archives.
+  * Rewrite live Trellis/docs paths to repo-root semantics.
+  * Keep package/CLI names unchanged for first migration commit.
+* Pros:
+  * Lowest risk for one-shot execution.
+  * Avoids dragging tutorial repo history and old workspace noise into new product repo.
+  * Makes the new repo boundary explicit and clean.
+* Cons:
+  * Loses git blame/history continuity unless old repo remains as archive reference.
+
+**Approach B: history-preserving extraction with `git filter-repo`**
+
+* How it works:
+  * Clone old repo into temp dir.
+  * Filter history for `coding-deepgent/`, `AGENTS.md`, and selected `.trellis/` paths.
+  * Move `coding-deepgent/` contents to root.
+  * Then repair Trellis/docs.
+* Pros:
+  * Preserves more file history.
+* Cons:
+  * Higher failure surface; curated `.trellis/` selection is hard across history.
+  * More likely to preserve outdated monorepo context accidentally.
+  * More expensive to verify.
+
+**Approach C: keep as subtree/submodule**
+
+* How it works:
+  * Create a new wrapper repo that pulls `coding-deepgent/` as subtree or submodule.
+* Pros:
+  * Minimal extraction work.
+* Cons:
+  * Does not actually make the product repo clean.
+  * Trellis remains awkward because canonical docs live outside product root.
+  * Poor fit for user's goal of moving coding-agent out.
+
+## Expansion Sweep
+
+### Future evolution
+
+* Package/CLI rename from `coding-deepgent` to `coding-agent` should be a second explicit migration, with compatibility decisions and deprecation strategy.
+* New repo may later need GitHub remote, release packaging, CI workflow, and public/private distribution policy.
+
+### Related scenarios
+
+* Trellis task workflow must work from the new repo root.
+* Frontend CLI scripts must work with root-relative `PYTHONPATH=src` after directory promotion.
+* Runtime state directories such as `.coding-deepgent/` may later need rename policy, but should not be renamed in the extraction commit.
+
+### Failure and edge cases
+
+* Stale `coding-deepgent/` path references in live specs can cause future agents to edit nonexistent paths.
+* Copying `.env`, memory DB, cache, or `node_modules` would leak local state and bloat the repo.
+* Running tests from the promoted root may expose path assumptions previously hidden by the nested directory.
+
+## Technical Approach
+
+Recommended one-shot plan:
+
+1. Capture source state:
+   * current branch
+   * current commit
+   * `git status -sb`
+   * tracked file inventory for `coding-deepgent`, `AGENTS.md`, and curated `.trellis`
+2. Create target repo:
+   * `/root/coding-agent`
+   * initialize git
+   * add a root `.gitignore` that excludes env files, caches, runtime state, databases, `node_modules`, and Python/TS build outputs
+3. Promote product tree:
+   * copy tracked `coding-deepgent/` files to target repo root
+   * exclude runtime/local/cache files
+4. Migrate Trellis:
+   * copy `.trellis/workflow.md`
+   * copy `.trellis/scripts/`
+   * copy `.trellis/spec/`
+   * copy `.trellis/plans/`
+   * copy `.trellis/project-handoff.md`
+   * copy `.trellis/config.yaml`
+   * copy `.trellis/.gitignore`
+   * copy selected `.trellis/tasks/archive/2026-04/` task PRDs and related plan/audit files, but treat them as historical reference
+   * initialize fresh `.trellis/workspace/index.md`; do not copy personal journals by default
+5. Rewrite live docs:
+   * root `AGENTS.md`: current mainline is repo root
+   * `README.md`: canonical docs are `.trellis/...`, not `../.trellis/...`
+   * `.trellis/project-handoff.md`: remove old PR/branch as current live state; preserve old source commit as extraction provenance
+   * `.trellis/spec/backend/index.md`: repo root is product mainline
+   * `.trellis/spec/frontend/index.md`: frontend paths are `frontend/cli` and `src/coding_deepgent/frontend`
+   * `.trellis/spec/guides/mainline-scope-guide.md`: tutorial/reference layer is no longer in repo by default
+   * high-signal backend specs: replace executable path examples from `coding-deepgent/src/...` and `coding-deepgent/tests/...` to `src/...` and `tests/...`
+6. Verify path hygiene:
+   * `rg -n "coding-deepgent/|../.trellis|learn-claude-code|pull/220|codex/stage-12-14" .`
+   * classify remaining hits as either package/CLI name, historical archive, or docs bug
+7. Validate product:
+   * Python install/dev validation
+   * backend tests
+   * backend lint/typecheck
+   * frontend npm tests/typecheck
+   * Trellis scripts/link check
+8. Commit in new repo:
+   * `chore: extract coding agent repository`
+   * include migration summary in PRD / migration note
+
+## Decision (ADR-lite)
+
+**Context**: The product currently lives as `coding-deepgent/` inside a broader tutorial/reference repository, while Trellis lives at old repo root and already acts as the canonical workflow/spec layer for the product. A move to an independent `coding-agent` repo requires both file relocation and documentation ownership cleanup.
+
+**Decision**: Recommend Approach A: clean snapshot extraction with curated Trellis migration, preserving package and CLI names for the first migration commit.
+
+**Consequences**: The new repo starts with a clean boundary and a reproducible migration record, but old git blame/history remains in the source repo unless a separate archival/history-preserving extraction is later required.
+
+## Out of Scope
+
+* Full package rename from `coding_deepgent` to `coding_agent`.
+* CLI rename from `coding-deepgent` to `coding-agent`.
+* npm package/bin rename.
+* Publishing to a GitHub remote or creating a PR.
+* Copying local runtime state, memory database, `.env`, caches, or `node_modules`.
+* Migrating tutorial/reference directories outside product scope.
+
+## Technical Notes
+
+* Inspected:
+  * `AGENTS.md`
+  * `.trellis/workflow.md`
+  * `.trellis/project-handoff.md`
+  * `.trellis/spec/backend/index.md`
+  * `.trellis/spec/frontend/index.md`
+  * `.trellis/spec/guides/index.md`
+  * `.trellis/spec/guides/mainline-scope-guide.md`
+  * `.trellis/spec/guides/architecture-posture-guide.md`
+  * `.trellis/spec/guides/trellis-doc-map-guide.md`
+  * `coding-deepgent/README.md`
+  * `coding-deepgent/pyproject.toml`
+  * `coding-deepgent/frontend/cli/package.json`
+* Source inventory observations:
+  * `git ls-files coding-deepgent .trellis AGENTS.md | wc -l` reported 798 tracked files including Trellis archives.
+  * `find coding-deepgent ... | wc -l` excluding common caches/runtime directories reported 272 product files.
+  * `find .trellis/tasks/archive/2026-04 -name prd.md | wc -l` reported 127 archived PRDs.
+* High-risk old-context strings:
+  * `coding-deepgent/`
+  * `../.trellis`
+  * `learn-claude-code`
+  * `pull/220`
+  * `codex/stage-12-14-context-compact-foundation`
+
+## Migration Execution Results
+
+### Source
+
+* Source repo: `/root/learn-claude-code`
+* Source commit: `d0463493055c48790a2a20a6c28fa386a1929e1e`
+* Extraction strategy: clean snapshot extraction with curated Trellis migration
+* Target repo: `/root/coding-agent`
+* Target branch: `main`
+* Initial commit: `808262479095f6c5df674e3c2b6a3ef0f7bf6761` (`chore: extract coding agent repository`)
+
+### Migrated
+
+* Product root files: `pyproject.toml`, `README.md`, `PROJECT_PROGRESS.md`, `project_status.json`, `.env.example`, `.flake8`
+* Product code/tests/frontend: `src/`, `tests/`, `frontend/`
+* Trellis live layer: `AGENTS.md`, `.trellis/workflow.md`, `.trellis/scripts/`, `.trellis/spec/`, `.trellis/plans/`, `.trellis/project-handoff.md`, `.trellis/config.yaml`, `.trellis/worktree.yaml`
+* Trellis historical archive: `.trellis/tasks/archive/2026-04/` with 127 archived `prd.md` files
+* Migration task record: `.trellis/tasks/04-20-extract-coding-agent-repo/`
+
+### Intentionally excluded
+
+* `.env`
+* `.coding-deepgent/`
+* `.omx/`
+* `.mypy_cache/`
+* `.pytest_cache/`
+* `.ruff_cache/`
+* `frontend/cli/node_modules/`
+* `__pycache__/`
+* old source workspace journals and `.trellis/.developer`
+
+### Path hygiene
+
+`rg -n "coding-deepgent/|../.trellis|learn-claude-code|pull/220|codex/stage-12-14" ...`
+after live-doc rewrite returns only:
+
+* historical extraction provenance in `README.md`, `AGENTS.md`, and `.trellis/project-handoff.md`
+* this migration PRD's source-context notes
+* preserved runtime-state paths such as `.coding-deepgent/tool-results/`
+
+No live spec now describes `coding-deepgent/` as the current implementation
+root.
+
+### Verification
+
+* `python3 ./.trellis/scripts/check_trellis_links.py` -> `Trellis markdown links OK`
+* `python3 ./.trellis/scripts/get_context.py` -> ran successfully with a local gitignored `.trellis/.developer`
+* `python3 -m pytest -q` -> `406 passed`
+* `python3 -m ruff check .` -> `All checks passed!`
+* `python3 -m mypy src` -> `Success: no issues found in 143 source files`
+* `npm --prefix frontend/cli ci` -> installed frontend validation dependencies into ignored `node_modules`
+* `npm --prefix frontend/cli test` -> `2 passed`, `8 passed`
+* `npm --prefix frontend/cli run typecheck` -> passed
+* validation artifacts cleaned with `git clean -fdX`
diff --git a/.trellis/tasks/archive/2026-04/04-20-extract-coding-agent-repo/task.json b/.trellis/tasks/archive/2026-04/04-20-extract-coding-agent-repo/task.json
new file mode 100644
index 000000000..b1c2213e9
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-extract-coding-agent-repo/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "extract-coding-agent-repo",
+  "name": "extract-coding-agent-repo",
+  "title": "brainstorm: extract coding agent repo",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-20",
+  "completedAt": "2026-04-20",
+  "branch": null,
+  "base_branch": null,
+  "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/archive/2026-04/04-20-full-cc-parity-roadmap/check.jsonl b/.trellis/tasks/archive/2026-04/04-20-full-cc-parity-roadmap/check.jsonl
new file mode 100644
index 000000000..dfe6526d5
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-full-cc-parity-roadmap/check.jsonl
@@ -0,0 +1,2 @@
+{"file": ".gemini/commands/trellis/finish-work.toml", "reason": "Finish work checklist"}
+{"file": ".gemini/commands/trellis/check-backend.toml", "reason": "Backend check spec"}
diff --git a/.trellis/tasks/archive/2026-04/04-20-full-cc-parity-roadmap/debug.jsonl b/.trellis/tasks/archive/2026-04/04-20-full-cc-parity-roadmap/debug.jsonl
new file mode 100644
index 000000000..e96d38c93
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-full-cc-parity-roadmap/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-20-full-cc-parity-roadmap/implement.jsonl b/.trellis/tasks/archive/2026-04/04-20-full-cc-parity-roadmap/implement.jsonl
new file mode 100644
index 000000000..6ee2f3fb2
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-full-cc-parity-roadmap/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": ".trellis/project-handoff.md", "reason": "Current canonical handoff to update from MVP-only resume to full parity direction"}
+{"file": ".trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md", "reason": "Current active MVP dashboard to supersede with full parity roadmap"}
+{"file": ".trellis/plans/coding-deepgent-deferred-boundary-refresh-adr.md", "reason": "Current active MVP deferred-boundary ADR to downgrade to historical boundary"}
+{"file": ".trellis/spec/guides/cc-alignment-guide.md", "reason": "Canonical alignment workflow guide; add evidence ladder and OSS fallback rule"}
diff --git a/.trellis/tasks/archive/2026-04/04-20-full-cc-parity-roadmap/prd.md b/.trellis/tasks/archive/2026-04/04-20-full-cc-parity-roadmap/prd.md
new file mode 100644
index 000000000..bb0c8a2af
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-full-cc-parity-roadmap/prd.md
@@ -0,0 +1,307 @@
+# brainstorm: full cc parity roadmap
+
+## Goal
+
+把 `coding-deepgent/` 的产品目标从当前 `Approach A MVP` 扩展为面向 Claude Code / `cc-haha` 的全功能对照路线图，并建立一套后续长期升级规则：优先对照可见源码；若对应功能没有公开源码，则必须检索高质量同类开源项目，提炼可验证实现模式，再写入 Trellis 规划/规范后实施。
+
+## What I already know
+
+* 用户明确要求：不再局限于当前上下文系统 MVP，要“全面往 cc 进军”，目标是功能上完全对照。
+* 用户新增了一条过程约束：如果对应功能没有源代码，先搜索类似的高质量开源项目，研究别人怎么实现，再把这条做法写进文档，后续升级都按这个规则执行。
+* 当前 canonical 目标仍然是 `Approach A MVP`，不是 full cc parity。
+* 当前主线是 `coding-deepgent/`，Trellis 是 canonical coordination/documentation layer。
+* 当前 canonical handoff、roadmap、release/next-step 口径都默认围绕 `Approach A MVP` 收口，而不是继续向 full parity 推进。
+* 2026-04 的多个上下文/Collapse 相关任务已经明确区分了两层口径：
+  - `MVP local boundary`
+  - `richer cc-style follow-up`
+* 现有 full-goal 定义其实已经存在一个“长线目标”：`cc-haha` essence alignment through LangChain/LangGraph-native primitives；但后续执行被收窄到了 MVP closeout。
+* 公开 `cc-haha` 对很多 feature band 有源码，但并不是所有内部能力都公开可见；例如 `contextCollapse` 关键实现就是 feature-gated/缺失态。
+* 用户已确认新的顶层对齐口径：
+  - 真实 Claude Code 公开行为是最高目标
+  - `cc-haha` 是最重要的开源实现参照
+* 用户已确认第一圈 roadmap 范围：
+  - 先做本地 agent 全带宽
+  - 先不把 remote / IDE / daemon 作为第一优先圈
+* 用户已确认第一圈本地 parity 口径：
+  - 不是只做 backend/runtime
+  - CLI/TUI/交互体验也纳入第一圈目标
+* 用户已确认新的默认裁决规则：
+  - 对 `模型可见行为 / runtime 语义 / CLI-TUI 交互`，优先贴近真实 Claude Code
+  - 对隐藏内部实现、provider-specific plumbing、非必要底层机制，继续保持 LangChain-native 优先
+* 用户已确认第一圈不纳入完整本地多智能体协作层：
+  - `mailbox / coordinator / richer background team runtime` 先不进第一圈
+  - 第一圈先做单 agent、本地 subagent/fork、context/session/memory/plugin/CLI 全带宽
+* 用户已确认第一圈对本地扩展生态的深度：
+  - 技能 / MCP / 插件 / 钩子以“本地可用、可加载、可调用、可调试”为目标
+  - 不把完整安装 / 启停 / 分发 / marketplace-like 体验放入第一圈
+* 用户已确认第一圈内部排期：
+  - 采用 `runtime-first`
+  - 先补 runtime/context/session/memory/task/subagent/fork/permission/prompt 等核心
+  - CLI/TUI 先补与 runtime 核心直接相关的高价值面，而不是先做整套体验翻新
+* 用户已确认第一圈完成判断：
+  - 以代表性真实工作流达到本地 `daily-driver parity` 为主
+  - 不是先以 feature-band checklist 收工
+* 用户已确认第一圈代表性工作流采用 `Lean 3-workflow`：
+  - 代码库接手与持续编码
+  - 长会话连续性
+  - 复杂任务分解（todo/task/plan + subagent/fork）
+* 用户已明确降低对扩展生态的要求：
+  - `skill / MCP / hook / plugin` 不作为第一圈高要求验收面
+  - 第一圈对这些能力保持“可用即可、非高优先收口”
+* 用户已确认“代码库接手与持续编码”工作流的成功标准：
+  - 以 **PR 级任务独立完成** 为标准
+  - agent 应能在中大型仓库中读代码、形成短计划、改代码、跑验证、处理中断并继续推进
+  - 不要求一开始就达到长时间近乎无人值守的超长链路主力级
+* 用户已确认“长会话连续性”工作流的成功标准：
+  - 以 **单日长任务级** 为标准
+  - 在一次较长本地开发任务中，经历多轮 context pressure、compact/collapse、resume、继续编辑后，仍能稳定保留主线并推进任务
+  - 不把跨日连续工作级作为第一圈默认完成线
+* 用户已确认“复杂任务分解（todo/task/plan + subagent/fork）”工作流的成功标准：
+  - 以 **个人效率增强级** 为标准
+  - todo/task/plan + subagent/fork 应能稳定帮助单人完成复杂开发任务，明显提升效率
+  - 不把 mailbox、coordinator、完整 team-runtime 语义纳入第一圈完成线
+
+## Assumptions (temporary)
+
+* 这次任务先做 roadmap / planning / documentation boundary reset，不直接进入大规模实现。
+* 新方向会覆盖现有 `Approach A MVP` 边界，因此需要更新 canonical planning docs，而不是只新增一个孤立任务 PRD。
+* “功能上完全对照”优先指真实 Claude Code 公开可观察行为与产品能力对照；`cc-haha` 作为最重要的开源实现参照，而不是最高裁决源。
+* 不要求对 provider-specific 或 closed-source 细节做盲目复刻，但要求尽可能逼近真实行为。
+
+## Open Questions
+
+* None for the roadmap-definition pass.
+
+## Requirements (evolving)
+
+* 梳理当前 canonical 文档中所有把目标限定为 `Approach A MVP` / “not full parity” 的边界。
+* 输出新的 full-cc-parity planning shape，至少包含 `Acceptance Targets`、`Planned Features`、`Planned Extensions`。
+* 定义 feature-band 级别的对齐方法：有源码时直接 source-backed 对齐；无源码时进入高质量 OSS research-first 流程。
+* 把“无源码时转向高质量 OSS 对标”的规则写进 Trellis canonical docs。
+* 给出后续实施顺序、优先级、阶段切分、风险边界。
+* 输出一份可复用的证据等级规则，避免未来把“可见源码”“公开行为”“三方分析”“类比 OSS”混成同一可信度。
+* 新 roadmap 的第一圈必须覆盖本地 agent 全带宽，而不是只做 backend/runtime 局部。
+* 新 roadmap 的第一圈必须同时覆盖本地 CLI/TUI/交互体验，而不是把使用感完全后置。
+* roadmap 必须明确裁决规则：哪些层要求行为优先，哪些层保持 LangChain-native 优先。
+* roadmap 第一圈必须明确排除完整本地多智能体协作层，以免单 agent 本地 parity 被 team-runtime 需求稀释。
+* 第一圈本地扩展生态以“可用即可”为边界，不把完整插件分发/安装体验纳入第一圈。
+* roadmap 第一圈的实施顺序以 `runtime-first` 为默认，不以先做表层 CLI/TUI 相似度为导向。
+* roadmap 第一圈的完成判断以代表性真实工作流达到本地 `daily-driver parity` 为主，而不是仅以 feature checklist 作为主验收。
+* 第一圈主验收工作流固定为 `Lean 3-workflow`，扩展生态不作为第一圈高要求验收面。
+* “代码库接手与持续编码”工作流以 **PR 级任务独立完成** 为第一圈成功标准。
+* “长会话连续性”工作流以 **单日长任务级** 为第一圈成功标准，而不是跨日连续工作级。
+* “复杂任务分解（todo/task/plan + subagent/fork）”工作流以 **个人效率增强级** 为第一圈成功标准，而不是完整 team-runtime 协作级。
+
+## Acceptance Criteria (evolving)
+
+* [x] 新 roadmap 明确取代“只到 MVP”为默认主目标。
+* [x] roadmap 覆盖主要 feature bands，而不是只讨论上下文系统。
+* [x] 文档明确规定：无公开源码时必须先做同类高质量 OSS 调研，再决定本地实现策略。
+* [x] 计划中区分：有源码可直接对照、只有行为可对照、无源码需类比研究，这三类证据等级。
+* [x] 输出后，后续 agent 能按该文档继续规划/实施，而不会回到“closer to cc 但 scope 不清”的状态。
+* [x] 现有 canonical docs 中与新方向冲突的 MVP-only 表述被标记为 superseded/update targets。
+* [x] 第一圈三条主工作流的成功标准被明确写入 roadmap。
+
+## Acceptance Targets
+
+* `coding-deepgent` 的默认产品目标从“Approach A MVP”切换为“持续推进 full cc parity roadmap”。
+* 后续 feature-family planning 默认按 feature band 和证据等级推进，而不是按临时 closeout stage 漂移。
+* 对于 `cc-haha` 未公开的能力，团队有一套固定 fallback 机制去借鉴高质量 OSS，而不是临时拍脑袋。
+* 第一圈 roadmap 的完成判断聚焦本地 agent 全带宽，而非一开始就把 remote / IDE / daemon 纳入第一优先波次。
+* 第一圈 roadmap 的完成判断以“真实工作流是否足够像 Claude Code 并能日常使用”为主。
+* 第一圈 roadmap 的主要验收工作流是精简的 3 条，而不是覆盖所有次级能力面。
+* 第一圈至少要让 agent 在真实仓库中独立完成典型 PR 级任务，达到可日常依赖的编码助手水平。
+* 第一圈至少要让 agent 在单日长任务里跨多轮压缩/恢复后，仍能保持主线并继续工作。
+* 第一圈至少要让 todo/task/plan + subagent/fork 成为个人复杂任务中的稳定效率放大器，而不是仅停留在演示级。
+
+## Planned Features
+
+* 盘点并标记当前所有 MVP-only canonical docs / handoff / ADR / roadmap 边界。
+* 产出新的 full-parity canonical roadmap 结构，覆盖主要 feature bands 和实施顺序。
+* 定义“evidence ladder + OSS fallback”方法论，并写进 Trellis 文档。
+* 建立一份高质量 OSS 候选池，按 feature band 说明优先参考什么。
+* 说明后续实施时的 planning gate、对齐矩阵、验证要求、文档更新要求。
+* 为“本地 agent 全带宽第一圈”定义清晰 feature-band 范围。
+* 为本地 CLI/TUI/交互体验建立和 runtime/backend 并行的 parity 目标，而不是只把它视为壳层。
+* 为冲突 feature bands 写明：模型可见行为、runtime semantics、CLI/TUI interaction、hidden implementation、provider plumbing 分别怎么判。
+* 为第一圈写清楚“不包含完整 mailbox/coordinator/team runtime”这一边界。
+* 为第一圈写清楚“本地扩展生态只做到可用，不做到完整分发/安装产品化”这一边界。
+* 为第一圈定义 runtime-first 波次：哪些 runtime/core bands 在 CLI/TUI polish 之前优先落地。
+* 定义 3-5 条代表性本地工作流，并用它们作为第一圈 parity 验收面。
+* 将 `skill / MCP / hook / plugin` 从第一圈高要求验收面中降级，保留为非阻塞配套能力。
+* 为每条主工作流定义明确成功粒度；其中“代码库接手与持续编码”采用 PR 级任务独立完成标准。
+* 为每条主工作流定义明确成功粒度；其中“长会话连续性”采用单日长任务级标准。
+* 为每条主工作流定义明确成功粒度；其中“复杂任务分解”采用个人效率增强级标准。
+
+## Planned Extensions
+
+* 为每个 feature band 建独立的 parity matrix / decomposition PRD。
+* 为无源码 feature band 建“候选 OSS 深入研究模板”。
+* 建立更细的实现波次：backend/runtime first，再到 CLI/frontend/workflow/team runtime。
+* 若后续需要，再引入“真实 Claude Code 公开行为验证”专门文档和测试协议。
+* 第二圈再规划 remote / IDE / daemon / proactive automation 对照目标。
+
+## Technical Approach
+
+* 新建 full-parity canonical roadmap，作为默认 planning target。
+* 将旧 MVP-only roadmap / deferred-boundary ADR 降级为 historical references。
+* 更新 `project-handoff.md`，让默认 resume 入口转向 full-parity roadmap。
+* 更新 `cc-alignment-guide.md`，把 evidence ladder 和 missing-source OSS fallback workflow 写成统一规则。
+* 新建 Circle 1 / Wave 1 runtime-core decomposition plan，作为下一批具体 parity tasks 的直接来源。
+
+## Implementation Checkpoint
+
+State: terminal
+
+Verdict: APPROVE
+
+Implemented:
+
+* Canonical full parity roadmap and evidence ladder.
+* Circle 1 / Wave 1 runtime-core decomposition.
+* Wave 1 implementation pack across F1/F2/F3/F4/F5:
+  - deferred `Command(update=...)` preservation
+  - collapse assistant-round tail preservation
+  - session-memory freshness hardening
+  - frontend durable `task_snapshot`
+  - background `subagent_list`
+  - recovery `Subagent activity:` section
+
+Verification:
+
+* `pytest -q coding-deepgent/tests` -> 415 passed
+* `ruff check coding-deepgent/src/coding_deepgent coding-deepgent/tests .trellis/spec .trellis/plans` -> passed
+* `python3 -m mypy coding-deepgent/src/coding_deepgent` -> passed
+
+## Definition of Done (team quality bar)
+
+* 规划文档更新到 canonical Trellis 位置
+* 范围、优先级、升级方法、证据等级都写清楚
+* 与现有 handoff/roadmap/goal docs 不冲突
+* 如行为边界发生变化，相关 spec/ADR 更新目标已标明
+
+## Out of Scope (explicit)
+
+* 本任务不直接实现 full cc parity
+* 本任务不承诺复制闭源 provider plumbing
+* 本任务不因为“功能全对照”而忽略 LangChain/LangGraph-native 边界
+
+## Technical Notes
+
+* Current canonical handoff: `.trellis/project-handoff.md`
+* Current product goal/backlog docs:
+  * `.trellis/tasks/archive/2026-04/04-14-redefine-coding-deepgent-final-goal/prd.md`
+  * `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+* Current planning rules:
+  * `.trellis/spec/guides/cc-alignment-guide.md`
+  * `.trellis/spec/guides/planning-targets-guide.md`
+* Current MVP-boundary docs to revisit:
+  * `.trellis/project-handoff.md`
+  * `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+  * `.trellis/plans/coding-deepgent-deferred-boundary-refresh-adr.md`
+  * `.trellis/tasks/archive/2026-04/04-15-stage-29-deferred-boundary-adr-mvp-release-checklist/prd.md`
+  * `.trellis/tasks/archive/2026-04/04-19-backend-next-step-roadmap/prd.md`
+
+## Research Notes
+
+### Current canonical repo constraints
+
+* The long-term product-goal doc already says `coding-deepgent` should implement the essential `cc-haha` / Claude Code runtime logic through LangChain/LangGraph-native primitives.
+* The current active canonical roadmap later narrowed execution to `Approach A MVP`, with explicit non-MVP deferrals.
+* Any new full-parity plan must therefore replace or supersede the MVP-only planning surface, not merely add another optional backlog note.
+
+### Evidence ladder for future parity work
+
+1. **Behavior-backed**
+   - public Claude Code behavior, official docs, public product surfaces, or visible runtime artifacts
+2. **Primary source-backed implementation reference**
+   - exact `cc-haha` source files / symbols / docs
+3. **Analogous OSS-backed**
+   - high-quality open-source systems implementing a similar capability family
+4. **Secondary analysis**
+   - books, blogs, third-party explanations; useful but weaker
+
+Rule:
+
+* treat real Claude Code public behavior as the top-level parity target
+* use `cc-haha` as the default open-source implementation reference when it matches or explains the public behavior
+* use level 3 only after documenting why Claude Code public evidence and `cc-haha` source are insufficient
+* never treat level 4 as stronger than available source
+
+### Candidate high-quality OSS pool for fallback research
+
+These are not automatic parity targets. They are candidate reference systems when
+`cc-haha` lacks source for a capability family.
+
+* `sst/opencode`
+  - highly relevant for terminal coding-agent runtime and explicitly positions itself as very similar to Claude Code
+  - useful bands: agent runtime, CLI/TUI, provider-agnostic architecture, remote/client-server split
+* `Aider-AI/aider`
+  - highly relevant for repo-map, edit loop, git/testing ergonomics, pragmatic coding-agent workflows
+  - useful bands: codebase mapping, edit/commit/test loops, practical code editing UX
+* `OpenHands/OpenHands`
+  - highly relevant for software-agent SDK, CLI, local/cloud runtime split, multi-agent/system architecture
+  - useful bands: agent runtime layering, SDK/CLI separation, permissions/collaboration surfaces
+* `google-gemini/gemini-cli`
+  - relevant for CLI agent features, context files, checkpointing, MCP, trusted-folder/security ergonomics
+  - useful bands: CLI UX, checkpoint/resume, context-file conventions, MCP/tool integration
+* `block/goose`
+  - relevant for local agent runtime, desktop/CLI/API tri-surface, extensibility, provider-agnostic architecture, skills/extensions ecosystem
+  - useful bands: extension/skills ecosystem, local-agent safety, distribution model, agent packaging
+
+### Feasible planning approaches here
+
+**Approach A: Replace MVP as canonical top-level target now** (Recommended)
+
+* How it works:
+  - full-cc-parity becomes the default canonical target
+  - existing MVP docs become historical closeout records or bounded stage snapshots
+  - future work plans from feature bands and evidence ladder
+* Pros:
+  - matches the user's new directive directly
+  - stops future ambiguity around “MVP complete vs parity incomplete”
+  - gives one clean upgrade rule for all subsequent work
+* Cons:
+  - requires updating multiple canonical docs and handoff assumptions
+
+**Approach B: Keep MVP as shipping baseline, add full-parity as separate long-run track**
+
+* How it works:
+  - preserve current MVP docs as canonical shipping boundary
+  - add a separate parity-track roadmap above it
+* Pros:
+  - less churn to current docs
+  - easier to preserve “already verified MVP” language
+* Cons:
+  - high risk of future planning drift
+  - likely repeats the same confusion about what “complete” means
+
+**Approach C: Split by feature-band ownership, not by one new top-level target**
+
+* How it works:
+  - leave global goal mostly as-is
+  - create one parity decomposition doc per feature family
+* Pros:
+  - less central-doc disruption
+  - can move fast per subsystem
+* Cons:
+  - weak top-level coordination
+  - likely reintroduces inconsistent evidence standards
+
+## Decision (ADR-lite)
+
+**Context**: The repo already has a long-term cc-aligned product goal, but the current canonical planning surface narrowed execution to an MVP closeout path. The user now wants the default direction to change: no longer “stop at MVP,” but systematically pursue full feature parity, with a documented fallback process for missing-source features.
+
+**Decision**: Prefer Approach A: replace MVP as the canonical top-level target now, while preserving MVP documents as historical boundary evidence rather than the default planning destination. The top-level parity target is real Claude Code public behavior; `cc-haha` becomes the primary open-source implementation reference, and high-quality OSS research is required when both are insufficient.
+
+**Consequences**:
+
+* Canonical roadmap/handoff docs will need an explicit superseding update.
+* Future feature planning should default to feature-band parity plus evidence ladder.
+* Missing-source capabilities must trigger OSS research-first instead of ad-hoc design.
+* Verification and documentation burden will increase, but planning drift should drop.
+* Future feature PRDs will need an explicit layer-by-layer parity judgment instead of one coarse “align/defer” label.
+* The first implementation circle should stay focused on local single-agent parity and bounded local subagent/fork parity, deferring broader team-runtime parity.
+* The first implementation circle should treat skills/MCP/plugins/hooks as usable local extension seams, not as a full plugin distribution platform.
+* The first implementation circle should prioritize runtime/core parity before broad CLI/TUI polish, except for CLI/TUI surfaces directly needed to expose or validate those runtime gains.
+* The first implementation circle should be evaluated primarily through representative daily-driver workflows, with feature-band checklist serving as supporting structure rather than the main finish line.
diff --git a/.trellis/tasks/archive/2026-04/04-20-full-cc-parity-roadmap/task.json b/.trellis/tasks/archive/2026-04/04-20-full-cc-parity-roadmap/task.json
new file mode 100644
index 000000000..b4ffd7cf0
--- /dev/null
+++ b/.trellis/tasks/archive/2026-04/04-20-full-cc-parity-roadmap/task.json
@@ -0,0 +1,44 @@
+{
+  "id": "full-cc-parity-roadmap",
+  "name": "full-cc-parity-roadmap",
+  "title": "brainstorm: full cc parity roadmap",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-20",
+  "completedAt": "2026-04-20",
+  "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/tests/test_git_context.py b/.trellis/tests/test_git_context.py
new file mode 100644
index 000000000..c78645b4a
--- /dev/null
+++ b/.trellis/tests/test_git_context.py
@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SCRIPTS_DIR = REPO_ROOT / ".trellis" / "scripts"
+
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
+
+from common.git_context import (  # type: ignore[import-not-found]  # noqa: E402
+    get_context_json,
+    get_context_record_json,
+    get_context_text,
+    get_context_text_record,
+)
+
+
+def _write(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+def _make_repo(
+    tmp_path: Path,
+    *,
+    current_task_path: str = ".trellis/tasks/04-19-demo-task",
+    create_task: bool = True,
+) -> Path:
+    _write(tmp_path / ".trellis" / ".developer", "name=kun\n")
+    _write(tmp_path / ".trellis" / ".current-task", f"{current_task_path}\n")
+    _write(tmp_path / ".trellis" / "workspace" / "kun" / "journal-1.md", "# Journal\n")
+
+    if create_task:
+        task_dir = tmp_path / current_task_path
+        task_payload: dict[str, Any] = {
+            "name": "demo-task",
+            "title": "Demo task",
+            "status": "planning",
+            "createdAt": "2026-04-19",
+            "description": "Demo task description",
+            "assignee": "kun",
+            "children": [],
+            "parent": None,
+        }
+        _write(task_dir / "task.json", json.dumps(task_payload),)
+        _write(task_dir / "prd.md", "# Demo task\n")
+
+    return tmp_path
+
+
+def test_default_context_json_includes_current_task(tmp_path: Path) -> None:
+    repo_root = _make_repo(tmp_path)
+
+    context = get_context_json(repo_root)
+    current_task = context["currentTask"]
+
+    assert current_task is not None
+    assert current_task["path"] == ".trellis/tasks/04-19-demo-task"
+    assert current_task["name"] == "demo-task"
+    assert current_task["status"] == "planning"
+    assert current_task["createdAt"] == "2026-04-19"
+    assert current_task["description"] == "Demo task description"
+    assert current_task["hasPrd"] is True
+    assert current_task["isValid"] is True
+
+
+def test_text_and_record_modes_render_current_task(tmp_path: Path) -> None:
+    repo_root = _make_repo(tmp_path)
+
+    text = get_context_text(repo_root)
+    record_text = get_context_text_record(repo_root)
+    record_json = get_context_record_json(repo_root)
+
+    assert "## CURRENT TASK" in text
+    assert "Path: .trellis/tasks/04-19-demo-task" in text
+    assert "Name: demo-task" in text
+    assert "Status: planning" in text
+    assert "Created: 2026-04-19" in text
+    assert "Description: Demo task description" in text
+    assert "[!] This task has prd.md - read it for task details" in text
+    assert "## CURRENT TASK" in record_text
+    assert "Path: .trellis/tasks/04-19-demo-task" in record_text
+    assert "Name: demo-task" in record_text
+    assert "Status: planning" in record_text
+    assert record_json["currentTask"] is not None
+    assert record_json["currentTask"]["path"] == ".trellis/tasks/04-19-demo-task"
+
+
+def test_invalid_current_task_pointer_is_reported(tmp_path: Path) -> None:
+    repo_root = _make_repo(
+        tmp_path,
+        current_task_path=".trellis/tasks/04-19-missing-task",
+        create_task=False,
+    )
+
+    context = get_context_json(repo_root)
+    current_task = context["currentTask"]
+    text = get_context_text(repo_root)
+
+    assert current_task is not None
+    assert current_task["path"] == ".trellis/tasks/04-19-missing-task"
+    assert current_task["status"] == "invalid"
+    assert current_task["warning"] == "path does not exist"
+    assert current_task["isValid"] is False
+    assert "Path: .trellis/tasks/04-19-missing-task" in text
+    assert "[!] Invalid current task pointer: path does not exist" in text
diff --git a/.trellis/workflow.md b/.trellis/workflow.md
new file mode 100644
index 000000000..36f66b5eb
--- /dev/null
+++ b/.trellis/workflow.md
@@ -0,0 +1,607 @@
+# 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
+cat .trellis/spec/backend/langchain-native-guidelines.md  # For LangChain/LangGraph work
+```
+
+**cc-haha Alignment Task**:
+```bash
+cat .trellis/spec/guides/cc-alignment-guide.md
+```
+
+**Architecture / Refactor Boundary Choice**:
+```bash
+cat .trellis/spec/guides/architecture-posture-guide.md
+```
+
+**Staged / Multi-Checkpoint Work**:
+```bash
+cat .trellis/spec/guides/staged-execution-guide.md
+```
+
+**Filling Trellis Specs By Interview**:
+```bash
+cat .trellis/spec/guides/trellis-doc-map-guide.md
+cat .trellis/spec/guides/interview-driven-spec-expansion-guide.md
+```
+
+---
+
+## 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**
+6. **Prefer Clean Architecture Over Minimal Patch** - [!] When a cleaner long-term structure conflicts with smallest-diff compatibility work, follow `.trellis/spec/guides/architecture-posture-guide.md`
+7. **Plan Before Building Feature Families** - [!] For any non-trivial feature family, do not begin implementation until the plan explicitly states:
+   - `Acceptance Targets`
+   - `Planned Features`
+   - `Planned Extensions`
+   Use `.trellis/spec/guides/planning-targets-guide.md`.
+
+### Documentation Language Convention
+
+- Narrative prose in Trellis docs may be written in **Simplified Chinese**.
+- Keep commands, file paths, file names, task slugs, branch names, code identifiers, and JSON/YAML keys in **English**.
+- Keep structured status values and checklist keywords in **English** when they are used for search, automation, or coordination.
+- When precision matters, write the Chinese explanation first and retain the original English term alongside it.
+
+### 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 1A: Minimal Mainline Resume
+
+When resuming the `coding-deepgent` mainline and you want the cheapest safe
+resume path, read:
+
+```bash
+cat .trellis/project-handoff.md
+```
+
+Then refresh only lightweight live state:
+
+```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
+```
+
+### 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
+```
+
+**Architecture / Refactor Choice**:
+```bash
+# When clean long-term structure competes with compatibility/minimal-diff patches
+cat .trellis/spec/guides/architecture-posture-guide.md
+```
+
+**Planning Standard**:
+```bash
+# When defining a feature family before implementation
+cat .trellis/spec/guides/planning-targets-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/
+   --> For cc-haha-targeted behavior: read .trellis/spec/guides/cc-alignment-guide.md
+   --> For staged work: read .trellis/spec/guides/staged-execution-guide.md
+   --> For missing project conventions: read .trellis/spec/guides/interview-driven-spec-expansion-guide.md
+   --> For non-trivial feature families: define Acceptance Targets / Planned Features / Planned Extensions before implementation
+
+3. Self-test
+   --> Run project's lint/test commands (see spec docs)
+   --> Manual feature testing
+
+4. Commit code
+   --> AI may commit autonomously after validation passes
+   --> git add <scoped 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"
+```
+
+### Task Archive Policy
+
+Archive a Trellis task after the work is actually complete:
+
+- code/docs changes are tested as appropriate
+- acceptance criteria are met
+- the work has been committed, or the task is explicitly docs/planning-only and complete
+
+Do not keep a task active only because `task.json` still says `planning` or
+`in_progress`.
+
+Use:
+
+```bash
+python3 ./.trellis/scripts/task.py archive <task-name>
+```
+
+For completed sessions, preserve the result with `$record-session`.
+
+### 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
+
+### Staged Work Protocol
+
+For staged product work, Trellis should own the protocol directly:
+
+- default to `lean` mode unless the user explicitly asks for a broader long-run pass
+- for high-value, strongly coupled feature families with a clear boundary,
+  prefer one integrated delivery pass with internal checkpoints rather than
+  artificially tiny visible increments
+- use sub-stage states:
+  - `planning`
+  - `implementing`
+  - `verifying`
+  - `checkpoint`
+  - `terminal`
+- after every sub-stage, choose exactly one checkpoint decision:
+  - `continue`
+  - `adjust`
+  - `split`
+  - `stop`
+- if the decision is `continue`, move to the next sub-stage immediately
+- in `lean` mode, keep validation focused unless cross-cutting risk requires more
+- only split or stop a strongly coupled feature family when a real blocker,
+  boundary change, or verification failure appears
+
+Read `.trellis/spec/guides/staged-execution-guide.md` for the full checkpoint template and stop conditions.
+
+### Planning Standard
+
+For any non-trivial feature family, planning must make three buckets explicit
+before implementation starts:
+
+- `Acceptance Targets`
+- `Planned Features`
+- `Planned Extensions`
+
+Required meaning:
+
+- `Acceptance Targets`
+  - what must be true for the task to count as complete
+  - describe user-visible/system-visible outcomes, not only implementation notes
+- `Planned Features`
+  - the concrete features to implement in the current task
+- `Planned Extensions`
+  - future features intentionally not implemented now, but already identified
+
+Block rule:
+
+- If a feature family jumps from vague discussion straight into implementation
+  without these three buckets, do not proceed. First write them into the task
+  PRD or canonical planning note.
+
+Execution preference:
+
+- Once these three buckets are clear and approved, prefer one integrated
+  implementation pass for the feature family instead of repeated tiny planning
+  resets, unless a real blocker appears.
+
+### Interview-Driven Spec Expansion
+
+When Trellis docs need missing project knowledge:
+
+1. Read `.trellis/spec/guides/trellis-doc-map-guide.md`.
+2. Read `.trellis/spec/guides/interview-driven-spec-expansion-guide.md`.
+3. Derive what can be learned from code, tests, PRDs, and current specs first.
+4. Choose the owning Trellis document before asking.
+5. Ask one targeted maintainer question.
+6. Write the answer into the owning document immediately.
+7. Record the interview note in the active task PRD.
+
+Do not collect a broad chat transcript and reorganize it later.
+
+Active task PRDs are the working record for requirements, interviews,
+checkpoints, and verification while work is in progress. Workspace journals are
+the completed-session record after validated work is committed and recorded via
+`record-session`.
+
+If the maintainer delegates future low-risk process choices to the agent,
+proceed with the documented recommended/default option. Still stop for
+irreversible deletion, major product direction changes, or unclear ownership.
+
+### Spec Update Trigger
+
+Update `.trellis/spec/*` only when a change creates or changes a reusable
+implementation contract, such as:
+
+- tool schema / command / API shape
+- runtime state fields or payload formats
+- module ownership or boundary
+- validation / error behavior
+- test requirements or verification matrix
+- cross-layer transformation
+- recurring mistake that should become a rule
+
+Do not update specs for ordinary implementation details that do not affect
+future implementation or review.
+
+---
+
+## 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`
+   - For runtime/refactor/contract decisions, prefer the higher-value long-term structure rather than the smallest patch
+   - 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
+   - AI commits autonomously after the required checks pass
+   - 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** amend commits, use destructive git commands, or commit
+   unrelated user changes without explicit approval
+7. [!] **Don't** add compatibility bridges, fallback paths, or duplicate abstractions only to preserve weaker old local designs unless a real external compatibility requirement exists
+
+---
+
+## 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, plus `backend/langchain-native-guidelines.md` when LangChain/LangGraph surfaces change |
+| Cross-Layer Feature | `guides/cross-layer-thinking-guide.md` |
+| Architecture / Refactor boundary choice | `guides/architecture-posture-guide.md` |
+| cc-haha-aligned work | `guides/cc-alignment-guide.md` |
+| Staged / checkpointed execution | `guides/staged-execution-guide.md` |
+| Interview-driven spec expansion | `guides/trellis-doc-map-guide.md` → `guides/interview-driven-spec-expansion-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..90bdb3a4d
--- /dev/null
+++ b/.trellis/workspace/index.md
@@ -0,0 +1,128 @@
+# 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 Convention
+
+- Journal summaries, handoff notes, and other narrative prose may be written in **Simplified Chinese**.
+- Keep commands, file paths, file names, task names, commit hashes, code identifiers, and JSON/YAML keys in **English**.
+- Keep structured status values such as `Completed`, `In Progress`, and `Blocked` in **English** for consistency.
+- Keep English keywords in headings or checklist items when they are used for search or automation.
diff --git a/.trellis/workspace/kun/index.md b/.trellis/workspace/kun/index.md
new file mode 100644
index 000000000..0b240ac6d
--- /dev/null
+++ b/.trellis/workspace/kun/index.md
@@ -0,0 +1,65 @@
+# Workspace Index - kun
+
+> Journal tracking for AI development sessions.
+
+---
+
+## Current Status
+
+<!-- @@@auto:current-status -->
+- **Active File**: `journal-1.md`
+- **Total Sessions**: 25
+- **Last Active**: 2026-04-20
+<!-- @@@/auto:current-status -->
+
+---
+
+## Active Documents
+
+<!-- @@@auto:active-documents -->
+| File | Lines | Status |
+|------|-------|--------|
+| `journal-1.md` | ~997 | Active |
+<!-- @@@/auto:active-documents -->
+
+---
+
+## Session History
+
+<!-- @@@auto:session-history -->
+| # | Date | Title | Commits |
+|---|------|-------|---------|
+| 25 | 2026-04-20 | Complete Circle 2 local expanded parity baseline | `bbe9eeb`, `7cc5bfb` |
+| 24 | 2026-04-20 | Plan Circle 2 expanded parity | `243be04`, `b6b522c` |
+| 23 | 2026-04-20 | Complete Circle 1 local parity baseline | `7248889`, `386602b` |
+| 22 | 2026-04-20 | Complete Circle 1 Wave 2 control surfaces pack | `c9c38e4`, `0078bce` |
+| 21 | 2026-04-20 | Complete Circle 1 Wave 2 runtime surfaces pack | `575850f`, `a5646a9` |
+| 20 | 2026-04-20 | Complete Circle 1 Wave 1 parity pack | `e7f78b1` |
+| 19 | 2026-04-19 | CLI frontend completion and task closeout | `882112b`, `5bcc33d`, `0ffde5e`, `f46e16c`, `ca778fd`, `28f64d9`, `543c957` |
+| 18 | 2026-04-19 | Full mypy validation cleanup for PR 220 | `c4d91ae`, `3b08964` |
+| 17 | 2026-04-19 | Release validation and ui-gateway dependency cleanup | `7a80b8c`, `8af4f5b` |
+| 16 | 2026-04-19 | Minimal Web UI Over Frontend Gateway | `818fb6d`, `d90baab` |
+| 15 | 2026-04-19 | Consolidate coding-deepgent release readiness | `79f8f05` |
+| 14 | 2026-04-19 | Deferred Tool Discovery And Subagent Contract Closeout | `e3da016`, `d27cf24` |
+| 13 | 2026-04-19 | H12 fork runtime closeout | `9be06b2` |
+| 12 | 2026-04-18 | Memory productization closeout | `672e56a`, `d0e6f49` |
+| 11 | 2026-04-18 | Memory Backend And Unified Context Closeout | `2646cb9`, `7ef9e6c` |
+| 10 | 2026-04-18 | Fork explicit entrypoint and cache-safe contract | `2c8a2d5`, `2e6e2df` |
+| 9 | 2026-04-18 | Integrated Memory Module Closeout | `bb58c31`, `9bca6c0` |
+| 8 | 2026-04-16 | Runtime pressure compression hardening | `2f62df2`, `a5bba07`, `11f3f46`, `1725ff3`, `3b5a236`, `161fefb`, `a01fde9`, `8a05cd3`, `c174f10` |
+| 7 | 2026-04-16 | Progressive context pressure pipeline and Trellis commit policy | `08f0ebe`, `b72f2f7`, `a0f36a5`, `1ad78c6` |
+| 6 | 2026-04-15 | Archive active Trellis tasks and validate Approach A MVP cleanup | `27690e4` |
+| 5 | 2026-04-15 | Trellis review fixes and rollback verification | `cb9f8fe`, `9141539` |
+| 4 | 2026-04-15 | Trellis consolidation and guide foundation | `7fffb8c`, `dbb8ae9`, `d6d0f0f`, `4ef12ca`, `4241062` |
+| 3 | 2026-04-15 | Runtime pressure management closeout | `5271b82`, `ee1322b`, `833325d` |
+| 2 | 2026-04-15 | Session memory contribution seams and local updates | `5958b9c`, `921cbfc`, `5e675c8`, `7d6bf7c`, `2cfcbcd` |
+| 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..f0fd212bd
--- /dev/null
+++ b/.trellis/workspace/kun/journal-1.md
@@ -0,0 +1,997 @@
+# 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
+
+
+## Session 2: Session memory contribution seams and local updates
+
+**Date**: 2026-04-15
+**Task**: Session memory contribution seams and local updates
+
+### Summary
+
+Implemented session-memory deterministic assist, module contribution seams, and threshold-triggered local updates behind generic contribution providers. Validated focused session, compact, memory, CLI, ruff, and mypy checks. Archived completed planning and Stage 30A/30B tasks.
+
+### Main Changes
+
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `5958b9c` | (see git log) |
+| `921cbfc` | (see git log) |
+| `5e675c8` | (see git log) |
+| `7d6bf7c` | (see git log) |
+| `2cfcbcd` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+
+
+## Session 3: Runtime pressure management closeout
+
+**Date**: 2026-04-15
+**Task**: Runtime pressure management closeout
+
+### Summary
+
+Implemented and validated coding-deepgent runtime context pressure loop: tool-result storage, microcompact, live auto/reactive compact, restoration, session-memory assist/refresh, runtime pressure evidence, settings-backed thresholds, Trellis contracts, and task archival.
+
+### Main Changes
+
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `5271b82` | (see git log) |
+| `ee1322b` | (see git log) |
+| `833325d` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+
+
+## Session 4: Trellis consolidation and guide foundation
+
+**Date**: 2026-04-15
+**Task**: Trellis consolidation and guide foundation
+
+### Summary
+
+(Add summary)
+
+### Main Changes
+
+| Area | Description |
+|------|-------------|
+| Trellis consolidation | Established `.trellis/` as the canonical mainline documentation layer for `coding-deepgent`, removed duplicated product governance docs, and cleaned tutorial/reference-only skill and test surfaces. |
+| Custom skill migration | Migrated project-specific skill behavior into Trellis docs (`cc alignment`, `LangChain-native rules`, `staged execution`, `project handoff`) and removed the old custom skills while preserving `record-session`. |
+| Doc system | Added Trellis doc map and interview-driven spec expansion guides, clarified plans-vs-specs, PRD-vs-journal, spec update triggers, handoff update policy, validation scope policy, and task archive policy. |
+| Backend specs | Filled backend persistence, error handling, logging guidance; split oversized runtime/compact contracts into focused contract files; added Trellis markdown link smoke checker. |
+| Chinese localization | Localized `.trellis/spec/guides/*.md` to Simplified Chinese while preserving English commands, paths, identifiers, and structured tokens. |
+
+**Archived Tasks**:
+- `04-15-trellis-custom-skill-migration`
+- `04-15-trellis-docs-synthesis-interview`
+- `04-15-trellis-docs-chinese-localization`
+- `04-15-trellis-spec-consolidation`
+
+**Updated Files**:
+- `.trellis/workflow.md`
+- `.trellis/project-handoff.md`
+- `.trellis/plans/index.md`
+- `.trellis/spec/backend/index.md`
+- `.trellis/spec/backend/database-guidelines.md`
+- `.trellis/spec/backend/error-handling.md`
+- `.trellis/spec/backend/logging-guidelines.md`
+- `.trellis/spec/backend/quality-guidelines.md`
+- `.trellis/spec/backend/langchain-native-guidelines.md`
+- `.trellis/spec/backend/runtime-context-compaction-contracts.md`
+- `.trellis/spec/backend/tool-result-storage-contracts.md`
+- `.trellis/spec/backend/session-compact-contracts.md`
+- `.trellis/spec/backend/runtime-pressure-contracts.md`
+- `.trellis/spec/guides/index.md`
+- `.trellis/spec/guides/trellis-doc-map-guide.md`
+- `.trellis/spec/guides/interview-driven-spec-expansion-guide.md`
+- `.trellis/spec/guides/mainline-scope-guide.md`
+- `.trellis/spec/guides/cc-alignment-guide.md`
+- `.trellis/spec/guides/staged-execution-guide.md`
+- `.trellis/spec/guides/cross-layer-thinking-guide.md`
+- `.trellis/spec/guides/code-reuse-thinking-guide.md`
+- `.trellis/spec/frontend/index.md`
+- `.trellis/spec/frontend/*.md`
+- `.trellis/scripts/check_trellis_links.py`
+
+**Verification**:
+- `python3 ./.trellis/scripts/check_trellis_links.py` passed
+- Focused `coding-deepgent` skill/plugin tests had passed earlier after root tutorial `skills/` removal
+
+**Status**:
+[OK] **Completed**
+
+**Next Steps**:
+- Continue using Trellis-first workflow for new `coding-deepgent` tasks
+- If needed, localize additional high-value Trellis docs beyond `spec/guides/*` in a later phased pass
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `7fffb8c` | (see git log) |
+| `dbb8ae9` | (see git log) |
+| `d6d0f0f` | (see git log) |
+| `4ef12ca` | (see git log) |
+| `4241062` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+
+
+## Session 5: Trellis review fixes and rollback verification
+
+**Date**: 2026-04-15
+**Task**: Trellis review fixes and rollback verification
+
+### Summary
+
+(Add summary)
+
+### Main Changes
+
+| Area | Description |
+|------|-------------|
+| Rollback verification | Verified that prior Chinese localization rollback had restored high-value `guides/*` and `plans/*` to English content, then fixed the remaining broken local `.omx` links introduced by the rollback. |
+| Trellis review fixes | Repaired the main review findings in current Trellis docs: removed deleted reference-layer paths from backend index, restored `plans/index.md` as a real planning entrypoint, updated `master-plan-coding-deepgent-reconstructed.md` to point to surviving `.trellis/plans/...` evidence, and removed duplicate workspace-journal routing from the doc map. |
+| Session hygiene | Cleared a stale `.current-task` pointer that referenced an empty `04-15-trellis-plans-chinese-localization` directory so future sessions will not resume an invalid task context. |
+
+**Updated Files**:
+- `.trellis/spec/backend/index.md`
+- `.trellis/plans/index.md`
+- `.trellis/plans/master-plan-coding-deepgent-reconstructed.md`
+- `.trellis/spec/guides/trellis-doc-map-guide.md`
+- `.trellis/.current-task`
+
+**Verification**:
+- `python3 ./.trellis/scripts/check_trellis_links.py` passed
+- Reviewed current Trellis baseline for stale deleted-path references and navigation regressions
+
+**Status**:
+[OK] **Completed**
+
+**Next Steps**:
+- If needed, either delete or properly initialize `04-15-trellis-plans-chinese-localization` before using it again
+- Continue normal `coding-deepgent` work with the repaired Trellis entrypoints
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `cb9f8fe` | (see git log) |
+| `9141539` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+
+
+## Session 6: Archive active Trellis tasks and validate Approach A MVP cleanup
+
+**Date**: 2026-04-15
+**Task**: Archive active Trellis tasks and validate Approach A MVP cleanup
+
+### Summary
+
+Archived all remaining active Trellis tasks, completed the release validation / PR cleanup task, clarified coding-deepgent release-facing docs around the stage-11 compatibility anchor versus Trellis live Stage 29 MVP status, and verified coding-deepgent with pytest, ruff, mypy, and contract regression checks.
+
+### Main Changes
+
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `27690e4` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+
+
+## Session 7: Progressive context pressure pipeline and Trellis commit policy
+
+**Date**: 2026-04-16
+**Task**: Progressive context pressure pipeline and Trellis commit policy
+
+### Summary
+
+Enabled AI-managed commits in Trellis workflow, implemented progressive runtime pressure pipeline with Snip/MicroCompact/Collapse/AutoCompact, and captured context-engineering follow-up roadmap tasks.
+
+### Main Changes
+
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `08f0ebe` | (see git log) |
+| `b72f2f7` | (see git log) |
+| `a0f36a5` | (see git log) |
+| `1ad78c6` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+
+
+## Session 8: Runtime pressure compression hardening
+
+**Date**: 2026-04-16
+**Task**: Runtime pressure compression hardening
+
+### Summary
+
+Implemented Stage 1 and Stage 2 of context compression: MicroCompact observability, time-based and token-budget pruning, AutoCompact circuit breaker/PTL retry, structured live compaction results, active-todo restoration, Pre/PostCompact hook context, and split Stage 3 on stable message IDs after full validation.
+
+### Main Changes
+
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `2f62df2` | (see git log) |
+| `a5bba07` | (see git log) |
+| `11f3f46` | (see git log) |
+| `1725ff3` | (see git log) |
+| `3b5a236` | (see git log) |
+| `161fefb` | (see git log) |
+| `a01fde9` | (see git log) |
+| `8a05cd3` | (see git log) |
+| `c174f10` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+
+
+## Session 9: Integrated Memory Module Closeout
+
+**Date**: 2026-04-18
+**Task**: Integrated Memory Module Closeout
+
+### Summary
+
+Closed out the integrated memory module: four-type long-term memory, feedback enforcement, memory management tools, and separate long-term/current-session recovery visibility.
+
+### Main Changes
+
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `bb58c31` | (see git log) |
+| `9bca6c0` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+
+
+## Session 10: Fork explicit entrypoint and cache-safe contract
+
+**Date**: 2026-04-18
+**Task**: Fork explicit entrypoint and cache-safe contract
+
+### Summary
+
+Added explicit run_fork entrypoint with same-config sibling fork contract, runtime prompt/tool snapshot seams, fork continuity metadata, tests, and Trellis spec updates.
+
+### Main Changes
+
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `2c8a2d5` | (see git log) |
+| `2e6e2df` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+
+
+## Session 11: Memory Backend And Unified Context Closeout
+
+**Date**: 2026-04-18
+**Task**: Memory Backend And Unified Context Closeout
+
+### Summary
+
+Completed the unified context/memory model and durable memory backend: added project rules layer, durable PostgreSQL long-term memory, Redis-backed job pipeline, S3-compatible archive storage, focused tests, and validated live PostgreSQL/Redis/MinIO wiring.
+
+### Main Changes
+
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `2646cb9` | (see git log) |
+| `7ef9e6c` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+
+
+## Session 12: Memory productization closeout
+
+**Date**: 2026-04-18
+**Task**: Memory productization closeout
+
+### Summary
+
+Productized automatic memory extraction inspection, agent-private memory scope inspection, and snapshot refresh closeout; validated focused pytest, ruff, and mypy; archived the Trellis task.
+
+### Main Changes
+
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `672e56a` | (see git log) |
+| `d0e6f49` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+
+
+## Session 13: H12 fork runtime closeout
+
+**Date**: 2026-04-19
+**Task**: H12 fork runtime closeout
+
+### Summary
+
+(Add summary)
+
+### Main Changes
+
+| Area | What was completed |
+|------|---------------------|
+| Batch 1 | Effective `max_turns`, per-agent model routing, built-in `explore`/`plan`, local custom subagents, fork continuity metadata, subagent/fork resume foundation |
+| Batch 2 | Background subagent runtime, progress + notification, queued follow-up input, plugin-provided subagent definitions |
+| H12 closeout | Explicit `run_fork` remains the only fork surface, `run_fork(background=true)` background fork runtime, stop/cancel semantics, workdir hardening, roadmap/spec closeout |
+
+**Validated**:
+- `pytest -q coding-deepgent/tests/test_agent_runtime_service.py coding-deepgent/tests/test_sessions.py coding-deepgent/tests/test_subagents.py coding-deepgent/tests/test_plugins.py coding-deepgent/tests/test_tool_system_registry.py coding-deepgent/tests/test_tool_system_middleware.py`
+- `ruff check`
+- `mypy`
+
+**Updated Files**:
+- `.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+- `.trellis/spec/backend/project-infrastructure-foundation-contracts.md`
+- `.trellis/spec/backend/task-workflow-contracts.md`
+- `coding-deepgent/src/coding_deepgent/subagents/background.py`
+- `coding-deepgent/src/coding_deepgent/subagents/loader.py`
+- `coding-deepgent/src/coding_deepgent/subagents/schemas.py`
+- `coding-deepgent/src/coding_deepgent/subagents/tools.py`
+- `coding-deepgent/src/coding_deepgent/subagents/__init__.py`
+- `coding-deepgent/src/coding_deepgent/containers/tool_system.py`
+- `coding-deepgent/src/coding_deepgent/tool_system/capabilities.py`
+- `coding-deepgent/src/coding_deepgent/plugins/schemas.py`
+- `coding-deepgent/src/coding_deepgent/plugins/registry.py`
+- `coding-deepgent/src/coding_deepgent/extensions_service.py`
+- `coding-deepgent/src/coding_deepgent/runtime/context.py`
+- `coding-deepgent/src/coding_deepgent/runtime/invocation.py`
+- `coding-deepgent/src/coding_deepgent/settings.py`
+- `coding-deepgent/tests/test_subagents.py`
+- `coding-deepgent/tests/test_plugins.py`
+- `coding-deepgent/tests/test_tool_system_registry.py`
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `9be06b2` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+
+
+## Session 14: Deferred Tool Discovery And Subagent Contract Closeout
+
+**Date**: 2026-04-19
+**Task**: Deferred Tool Discovery And Subagent Contract Closeout
+
+### Summary
+
+(Add summary)
+
+### Main Changes
+
+| Area | Description |
+|------|-------------|
+| Stage 0 | Restored clean baseline by aligning app tool-surface expectations, no-network test defaults, hook evidence metadata, and handoff wording. |
+| Stage 1 | Added `ToolSearch` and `invoke_deferred_tool` so deferred builtin and MCP capabilities can stay off the initial main tool list while remaining searchable and executable through the shared tool-policy/middleware path. |
+| Stage 2 | Consolidated subagent/fork contracts by moving advanced lifecycle controls onto the deferred surface and exposing `resume_subagent` / `resume_fork` as structured tool surfaces. |
+| Specs | Updated canonical H01 / task-workflow / infrastructure contracts plus roadmap, deferred ADR, and project handoff to reflect the new deferred-discovery and subagent lifecycle boundaries. |
+| Validation | `ruff check` on touched code/tests, `mypy` on touched typed modules, focused pytest on app/tool-system/mcp/tool-search/subagents, and full `pytest -q coding-deepgent/tests` (`371 passed`). |
+
+**Notes**:
+- Left the user's existing `.env.example` deletion untouched.
+- Left generated `.coding-deepgent/memory.db` untracked and out of commits.
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `e3da016` | (see git log) |
+| `d27cf24` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+
+
+## Session 15: Consolidate coding-deepgent release readiness
+
+**Date**: 2026-04-19
+**Task**: Consolidate coding-deepgent release readiness
+
+### Summary
+
+Committed the coding-deepgent runtime/frontend readiness snapshot, reorganized product tests into domain directories, validated 386 Python tests plus frontend typecheck/tests, and recorded Core Release Gate as READY_WITH_FOLLOW_UPS.
+
+### Main Changes
+
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `79f8f05` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+
+
+## Session 16: Minimal Web UI Over Frontend Gateway
+
+**Date**: 2026-04-19
+**Task**: Minimal Web UI Over Frontend Gateway
+
+### Summary
+
+Added a minimal browser UI over `coding-deepgent ui-gateway`, wiring the new SSE gateway foundation into a static web shell that can submit prompts and render the shared frontend event stream.
+
+### Main Changes
+
+| Area | Description |
+|------|-------------|
+| Gateway | Added `coding-deepgent ui-gateway` SSE foundation and `/ui` route for a minimal browser shell |
+| Web UI | Added `coding-deepgent/frontend/web/index.html` to submit prompts, connect `EventSource`, and render user/assistant/tool/runtime/todo/recovery events |
+| Docs | Updated `coding-deepgent/README.md` and frontend/backend directory specs to reflect CLI/embedded/browser adapter layering |
+| Validation | `pytest -q tests/frontend/test_frontend_gateway.py tests/frontend/test_stream_bridge.py tests/frontend/test_frontend_runs.py tests/frontend/test_frontend_sse.py tests/frontend/test_frontend_client.py tests/frontend/test_frontend_protocol.py tests/frontend/test_frontend_bridge.py tests/frontend/test_frontend_event_mapping.py tests/structure/test_structure.py tests/cli/test_cli.py` (56 passed), `ruff check ...`, `mypy src/coding_deepgent/frontend`, and gateway/CLI help smoke all passed |
+
+**Outcome**:
+- Browser UI now consumes the SSE gateway instead of the CLI JSONL adapter.
+- CLI, embedded Python, and browser each have their own adapter over the shared producer/runtime foundation.
+- True runtime HITL remains explicitly deferred; the web shell only visualizes permission requests.
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `818fb6d` | (see git log) |
+| `d90baab` | (see git log) |
+
+### Testing
+
+- [OK] `pytest -q tests/frontend/test_frontend_gateway.py tests/frontend/test_stream_bridge.py tests/frontend/test_frontend_runs.py tests/frontend/test_frontend_sse.py tests/frontend/test_frontend_client.py tests/frontend/test_frontend_protocol.py tests/frontend/test_frontend_bridge.py tests/frontend/test_frontend_event_mapping.py tests/structure/test_structure.py tests/cli/test_cli.py`
+- [OK] `ruff check src/coding_deepgent/frontend src/coding_deepgent/cli.py tests/frontend/test_frontend_gateway.py tests/frontend/test_stream_bridge.py tests/frontend/test_frontend_runs.py tests/frontend/test_frontend_sse.py tests/frontend/test_frontend_client.py tests/structure/test_structure.py tests/cli/test_cli.py`
+- [OK] `mypy src/coding_deepgent/frontend`
+- [OK] `PYTHONPATH=src python3 -m coding_deepgent --help`
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+
+
+## Session 17: Release validation and ui-gateway dependency cleanup
+
+**Date**: 2026-04-19
+**Task**: Release validation and ui-gateway dependency cleanup
+
+### Summary
+
+Validated the current frontend gateway release candidate, fixed the optional web dependency packaging gap, and archived the Trellis cleanup task.
+
+### Main Changes
+
+- Validated the `coding-deepgent` release candidate changes around `ui-gateway`, frontend gateway, and the minimal web shell.
+- Confirmed focused Python, frontend CLI, static, and fake smoke checks passed.
+- Closed the release blocker where `ui-gateway` depended on `fastapi` / `uvicorn` without declaring them in project metadata.
+- Added the optional `web` dependency group, CLI missing-dependency guidance, README install notes, and regression coverage for the gateway runtime loader.
+- Archived `04-19-backend-next-step-release-validation-pr-cleanup` after writing the implementation checkpoint into the task PRD.
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `7a80b8c` | (see git log) |
+| `8af4f5b` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+
+
+## Session 18: Full mypy validation cleanup for PR 220
+
+**Date**: 2026-04-19
+**Task**: Full mypy validation cleanup for PR 220
+
+### Summary
+
+Cleared the branch-wide mypy gap in coding-deepgent tests, updated PR #220 validation status, and archived the Trellis cleanup task.
+
+### Main Changes
+
+- Cleared the branch-level `mypy coding-deepgent/src/coding_deepgent coding-deepgent/tests` validation gap that was previously called out in PR #220.
+- Tightened typed test fakes in `tests/compact/test_runtime_pressure.py` so model requests, runtimes, and handler responses satisfy LangChain static contracts without changing runtime behavior.
+- Fixed the `ToolGuardMiddleware` request fake in `tests/memory/test_memory_module_closeout.py` and the untyped emitted-event list in `tests/frontend/test_frontend_bridge.py`.
+- Re-ran branch validation and updated PR #220 to remove the old Known Validation Gap section.
+- Archived `04-19-full-mypy-validation-cleanup` after recording the final checkpoint and verification results.
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `c4d91ae` | (see git log) |
+| `3b08964` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+
+
+## Session 19: CLI frontend completion and task closeout
+
+**Date**: 2026-04-19
+**Task**: CLI frontend completion and task closeout
+
+### Summary
+
+Completed CLI frontend readiness: verified streaming, implemented LangGraph HITL permission pause/resume, added coding-deepgent-ui shortcut, archived completed frontend/deerflow/cc/subagent planning tasks, and left the Trellis active task list empty.
+
+### Main Changes
+
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `882112b` | (see git log) |
+| `5bcc33d` | (see git log) |
+| `0ffde5e` | (see git log) |
+| `f46e16c` | (see git log) |
+| `ca778fd` | (see git log) |
+| `28f64d9` | (see git log) |
+| `543c957` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+
+
+## Session 20: Complete Circle 1 Wave 1 parity pack
+
+**Date**: 2026-04-20
+**Task**: Complete Circle 1 Wave 1 parity pack
+
+### Summary
+
+Switched coding-deepgent planning to full Claude Code parity, completed Circle 1 Wave 1 runtime-core pack across F1-F5, validated pytest/ruff/mypy, and archived the task tree.
+
+### Main Changes
+
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `e7f78b1` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+
+
+## Session 21: Complete Circle 1 Wave 2 runtime surfaces pack
+
+**Date**: 2026-04-20
+**Task**: Complete Circle 1 Wave 2 runtime surfaces pack
+
+### Summary
+
+Implemented the first Circle 1 Wave 2 runtime-exposing surfaces pack: added sessions inspect for raw/compact/collapse visibility, frontend context/subagent snapshot events, React/Ink context/task/subagent panels, updated contracts, validated full Python and TS suites, and archived the Wave 2 task.
+
+### Main Changes
+
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `575850f` | (see git log) |
+| `a5646a9` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+
+
+## Session 22: Complete Circle 1 Wave 2 control surfaces pack
+
+**Date**: 2026-04-20
+**Task**: Complete Circle 1 Wave 2 control surfaces pack
+
+### Summary
+
+Added real Wave 2 control surfaces: local file-backed runtime store, CLI tasks/plans commands, active-TUI background subagent control inputs and snapshots, updated contracts/docs, validated full Python and TS suites, and archived the Wave 2 control-surfaces task.
+
+### Main Changes
+
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `c9c38e4` | (see git log) |
+| `0078bce` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+
+
+## Session 23: Complete Circle 1 local parity baseline
+
+**Date**: 2026-04-20
+**Task**: Complete Circle 1 local parity baseline
+
+### Summary
+
+Completed the remaining Circle 1 local daily-driver parity baseline: added session history/projection/timeline/evidence/events/permissions CLI surfaces, local skills/MCP/hooks/plugins list/inspect/validate/debug surfaces, deterministic Circle 1 acceptance harness, updated roadmap/handoff/specs, validated full Python and TS suites, and archived the completion task.
+
+### Main Changes
+
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `7248889` | (see git log) |
+| `386602b` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+
+
+## Session 24: Plan Circle 2 expanded parity
+
+**Date**: 2026-04-20
+**Task**: Plan Circle 2 expanded parity
+
+### Summary
+
+Created the substrate-first Circle 2 expanded product parity plan with Wave 1 daemon/worker/event substrate, Wave 2 mailbox, Wave 3 coordinator/team runtime, Wave 4 remote/IDE control plane, Wave 5 extension lifecycle, Wave 6 cross-day continuity, and final acceptance harness. Archived the brainstorm task.
+
+### Main Changes
+
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `243be04` | (see git log) |
+| `b6b522c` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+
+
+## Session 25: Complete Circle 2 local expanded parity baseline
+
+**Date**: 2026-04-20
+**Task**: Complete Circle 2 local expanded parity baseline
+
+### Summary
+
+Implemented the Circle 2 local expanded parity baseline with durable event_stream, worker_runtime, mailbox, teams, remote, extension_lifecycle, and continuity domains plus CLI surfaces and Circle 2 acceptance harness. Validated full Python and TS suites and archived the Circle 2 implementation task.
+
+### Main Changes
+
+
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `bbe9eeb` | (see git log) |
+| `7cc5bfb` | (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 b033a5f3b..e1db60c72 100644
--- a/README-ja.md
+++ b/README-ja.md
@@ -1,234 +1,193 @@
-# Learn Claude Code -- 真の Agent のための Harness Engineering
-
 [English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md)
 
-## Agency はモデルから生まれる。Agent プロダクト = モデル + Harness
-
-コードの話をする前に、一つ明確にしておく。
-
-**Agency -- 知覚し、推論し、行動する能力 -- はモデルの訓練から生まれる。外部コードの編成からではない。** だが実際に動く Agent プロダクトには、モデルと Harness の両方が必要だ。モデルはドライバー、Harness は車。本リポジトリは車の作り方を教える。
-
-### Agency はどこから来るか
-
-Agent の核心にあるのはニューラルネットワークだ -- Transformer、RNN、学習された関数 -- 数十億回の勾配更新を経て、行動系列データの上で環境を知覚し、目標を推論し、行動を起こすことを学んだもの。Agency は周囲のコードから与えられるものではない。訓練を通じてモデルが獲得するものだ。
-
-人間が最もわかりやすい例だ。数百万年の進化的訓練によって形作られた生物的ニューラルネットワーク。感覚で世界を知覚し、脳で推論し、身体で行動する。DeepMind、OpenAI、Anthropic が "Agent" と言うとき、その核心は常に同じことを指している：**訓練によって行動を学んだモデルと、それを特定の環境で機能させるインフラの組み合わせ。**
-
-歴史がその証拠を刻んでいる：
-
-- **2013 -- DeepMind DQN が Atari をプレイ。** 単一のニューラルネットワークが、生のピクセルとスコアだけを受け取り、7 つの Atari 2600 ゲームを学習 -- すべての先行アルゴリズムを超え、3 つで人間の専門家を打ち負かした。2015 年には同じアーキテクチャが [49 ゲームに拡張され、プロのテスターに匹敵](https://www.nature.com/articles/nature14236)、*Nature* に掲載。ゲーム固有のルールなし。決定木なし。一つのモデルが経験から学んだ。そのモデルが Agent だった。
-
-- **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 と同一：訓練されたモデルが環境に配置され、知覚と行動のツールを与えられる。唯一の違いは、学んだものの規模と解くタスクの汎用性。
+# Learn Claude Code
 
-すべてのマイルストーンが同じ事実を示している：**Agency -- 知覚し、推論し、行動する能力 -- は訓練によって獲得されるものであり、コードで組み立てるものではない。** しかし同時に、どの Agent も動作するための環境を必要とした：Atari エミュレータ、Dota 2 クライアント、StarCraft II エンジン、IDE とターミナル。モデルが知能を提供し、環境が行動空間を提供する。両方が揃って初めて完全な Agent となる。
+## 現在の協調入口
 
-### Agent ではないもの
+現在このリポジトリで実装作業を進める場合の主線は次の通りです。
 
-"Agent" という言葉は、プロンプト配管工の産業全体に乗っ取られてしまった。
+- 製品主線: `coding-deepgent/`
+- 仕様と協調の正規入口: `.trellis/`
 
-ドラッグ＆ドロップのワークフロービルダー。ノーコード "AI Agent" プラットフォーム。プロンプトチェーン・オーケストレーションライブラリ。すべて同じ幻想を共有している：LLM API 呼び出しを if-else 分岐、ノードグラフ、ハードコードされたルーティングロジックで繋ぎ合わせることが "Agent の構築" だと。
+`agents/`、`agents_deepagents/`、`docs/`、`web/`、`skills/`、および
+ルートの教材テストは既定では reference-only であり、現行製品の実装目標
+ではありません。
 
-違う。彼らが作ったものはルーブ・ゴールドバーグ・マシンだ -- 過剰に設計された脆い手続き的ルールのパイプライン。LLM は美化されたテキスト補完ノードとして押し込まれているだけ。それは Agent ではない。壮大な妄想を持つシェルスクリプトだ。
+高完成度の coding-agent harness を、0 から自分で実装できるようになるための教材リポジトリです。
 
-**プロンプト配管工式 "Agent" は、モデルを訓練しないプログラマーの妄想だ。** 手続き的ロジックを積み重ねて知能を力技で再現しようとする -- 巨大なルールツリー、ノードグラフ、チェーン・プロンプトの滝 -- そして十分なグルーコードがいつか自律的振る舞いを創発すると祈る。しない。工学的手段で Agency をコーディングすることはできない。Agency は学習されるものであって、プログラムされるものではない。
+このリポジトリの目的は、実運用コードの細部を逐一なぞることではありません。  
+本当に重要な設計主線を、学びやすい順序で理解し、あとで自分の手で作り直せるようになることです。
 
-あのシステムたちは生まれた瞬間から死んでいる：脆弱で、スケールせず、汎化が根本的に不可能。GOFAI（Good Old-Fashioned AI、古典的記号 AI）の現代版だ -- 何十年も前に学術界が放棄した記号ルールシステムが、LLM のペンキを塗り直して再登場した。パッケージが違うだけで、同じ袋小路。
+## このリポジトリが本当に教えるもの
 
-### マインドシフト：「Agent を開発する」から Harness を開発する へ
+まず一文で言うと:
 
-「Agent を開発しています」と言うとき、意味できるのは二つだけだ：
+**モデルが考え、harness がモデルに作業環境を与える。**
 
-**1. モデルを訓練する。** 強化学習、ファインチューニング、RLHF、その他の勾配ベースの手法で重みを調整する。タスクプロセスデータ -- 実ドメインにおける知覚・推論・行動の実際の系列 -- を収集し、モデルの振る舞いを形成する。DeepMind、OpenAI、Tencent AI Lab、Anthropic が行っていること。これが最も本来的な Agent 開発。
+その作業環境を作る主な部品は次の通りです。
 
-**2. Harness を構築する。** モデルに動作環境を提供するコードを書く。私たちの大半が行っていることであり、このリポジトリの核心。
+- `Agent Loop`: モデルに聞く -> ツールを実行する -> 結果を返す
+- `Tools`: エージェントの手足
+- `Planning`: 大きな作業を途中で迷わせないための小さな構造
+- `Context Management`: アクティブな文脈を小さく保つ
+- `Permissions`: モデルの意図をそのまま危険な実行にしない
+- `Hooks`: ループを書き換えずに周辺機能を足す
+- `Memory`: セッションをまたいで残すべき事実だけを保持する
+- `Prompt Construction`: 安定ルールと実行時状態から入力を組み立てる
+- `Tasks / Teams / Worktree / MCP`: 単体 agent をより大きな作業基盤へ育てる
 
-Harness とは、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 はドメインを超えて汎化する。
-
-このリポジトリは車両の作り方を教える。コーディング用の車両だ。だが設計パターンはあらゆるドメインに汎化する：農場管理、ホテル運営、工場製造、物流、医療、教育、科学研究。タスクが知覚され、推論され、実行される必要がある場所ならどこでも -- Agent には Harness が要る。
+- 主線を順序よく理解できること
+- 初学者が概念で迷子にならないこと
+- 核心メカニズムと重要データ構造を自力で再実装できること
 
-### Harness エンジニアの仕事
+## あえて主線から外しているもの
 
-このリポジトリを読んでいるなら、あなたはおそらく Harness エンジニアだ -- それは強力なアイデンティティ。以下があなたの本当の仕事：
+実際の製品コードには、agent の本質とは直接関係しない細部も多くあります。
 
-- **ツールの実装。** Agent に手を与える。ファイル読み書き、シェル実行、API 呼び出し、ブラウザ制御、データベースクエリ。各ツールは Agent が環境内で取れる行動。原子的で、組み合わせ可能で、記述が明確であるように設計する。
+たとえば:
 
-- **知識のキュレーション。** Agent にドメイン専門性を与える。製品ドキュメント、アーキテクチャ決定記録、スタイルガイド、規制要件。オンデマンドで読み込み（s05）、前もって詰め込まない。Agent は何が利用可能か知った上で、必要なものを自ら取得すべき。
+- パッケージングや配布の流れ
+- クロスプラットフォーム互換層
+- 企業ポリシーやテレメトリ配線
+- 歴史互換のための分岐
+- 製品統合のための細かな glue code
 
-- **コンテキストの管理。** Agent にクリーンな記憶を与える。サブ Agent 隔離（s04）がノイズの漏洩を防ぐ。コンテキスト圧縮（s06）が履歴の氾濫を防ぐ。タスクシステム（s07）が目標を単一の会話を超えて永続化する。
+こうした要素は本番では重要でも、0 から 1 を教える主線には置きません。  
+教学リポジトリの中心は、あくまで「agent がどう動くか」です。
 
-- **権限の制御。** Agent に境界を与える。ファイルアクセスのサンドボックス化。破壊的操作への承認要求。Agent と外部システム間の信頼境界の実施。安全工学と Harness 工学の交差点。
+## 想定読者
 
-- **タスクプロセスデータの収集。** Agent があなたの Harness 内で実行するすべての行動系列は訓練シグナル。実デプロイメントの知覚-推論-行動トレースは、次世代 Agent モデルをファインチューニングする原材料。あなたの Harness は Agent に仕えるだけでなく -- Agent を進化させる助けにもなる。
+このリポジトリは次の読者を想定しています。
 
-あなたは知性を書いているのではない。知性が住まう世界を構築している。その世界の品質 -- Agent がどれだけ明瞭に知覚でき、どれだけ正確に行動でき、利用可能な知識がどれだけ豊かか -- が、知性がどれだけ効果的に自らを表現できるかを直接決定する。
+- 基本的な Python が読める
+- 関数、クラス、リスト、辞書は分かる
+- でも agent システムは初学者でもよい
 
-**優れた Harness を作れ。Agent が残りをやる。**
+そのため、書き方の原則をはっきり決めています。
 
-### なぜ Claude Code か -- Harness Engineering の大師範
+- 新しい概念は、使う前に説明する
+- 1つの概念は、できるだけ1か所でまとまって理解できるようにする
+- まず「何か」、次に「なぜ必要か」、最後に「どう実装するか」を話す
+- 初学者に断片文書を拾わせて自力でつなげさせない
 
-なぜこのリポジトリは特に Claude Code を解剖するのか？
+## 学習の約束
 
-Claude Code は私たちが見てきた中で最もエレガントで完成度の高い Agent Harness だからだ。単一の巧妙なトリックのためではなく、それが *しないこと* のために：Agent そのものになろうとしない。硬直的なワークフローを押し付けない。精緻な決定木でモデルを二度推しない。ツール、知識、コンテキスト管理、権限境界をモデルに提供し -- そして道を譲る。
+この教材を一通り終えたとき、目標は次の 2 つです。
 
-Claude Code の本質を剥き出しにすると：
+1. 0 から自分で、構造が明快で反復改善できる coding-agent harness を組み立てられること
+2. より複雑な実装を読むときに、何が設計主線で何が製品周辺の detail なのかを見分けられること
 
-```
-Claude Code = 一つの agent loop
-            + ツール (bash, read, write, edit, glob, grep, browser...)
-            + オンデマンド skill ロード
-            + コンテキスト圧縮
-            + サブ Agent スポーン
-            + 依存グラフ付きタスクシステム
-            + 非同期メールボックスによるチーム協調
-            + worktree 分離による並列実行
-            + 権限ガバナンス
-```
+このリポジトリが重視するのは:
 
-これがすべてだ。これが全アーキテクチャ。すべてのコンポーネントは Harness メカニズム -- Agent が住む世界の一部。Agent そのものは？ Claude だ。モデル。Anthropic が人類の推論とコードの全幅で訓練した。Harness が Claude を賢くしたのではない。Claude は元々賢い。Harness が Claude に手と目とワークスペースを与えた。
+- 重要メカニズムと主要データ構造の高い再現度
+- 自分の手で作り直せる実装可能性
+- 途中で心智がねじれにくい読み順と説明密度
 
-これが Claude Code が理想的な教材である理由だ：**モデルを信頼し、工学的努力を Harness に集中させるとどうなるかを示している。** このリポジトリの各セッション（s01-s12）は Claude Code アーキテクチャから一つの Harness メカニズムをリバースエンジニアリングする。終了時には、Claude Code の仕組みだけでなく、あらゆるドメインのあらゆる Agent に適用される Harness 工学の普遍的原則を理解している。
+## 推奨される読み順
 
-教訓は「Claude Code をコピーせよ」ではない。教訓は：**最高の Agent プロダクトは、自分の仕事が Harness であって Intelligence ではないと理解しているエンジニアが作る。**
+日本語版でも主線・bridge doc・web の主要導線は揃えています。  
+章順と補助資料は、日本語でもそのまま追えるように保っています。
 
----
+- 全体マップ: [`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 で満たす
+## 初めてこのリポジトリを開くなら
 
-これはコーディング Agent だけの話ではない。
+最初から章をばらばらに開かない方が安定します。
 
-人間が複雑で多段階の判断集約的な仕事をしているすべてのドメインは、Agent が稼働できるドメインだ -- 正しい Harness さえあれば。このリポジトリのパターンは普遍的だ：
+最も安全な入口は次の順序です。
 
-```
-不動産管理 Agent  = モデル + 物件センサー + メンテナンスツール + テナント通信
-農業 Agent        = モデル + 土壌/気象データ + 灌漑制御 + 作物知識
-ホテル運営 Agent  = モデル + 予約システム + ゲストチャネル + 施設 API
-医学研究 Agent    = モデル + 文献検索 + 実験機器 + プロトコル文書
-製造 Agent        = モデル + 生産ラインセンサー + 品質管理 + 物流
-教育 Agent        = モデル + カリキュラム知識 + 学生進捗 + 評価ツール
-```
+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. 各段階の終わりで一度止まり、最小版を自分で書き直してから次へ進む
 
-ループは常に同じ。ツールが変わる。知識が変わる。権限が変わる。Agent -- モデル -- がすべてを汎化する。
+## Deep Agents s01-s11 トラック
 
-このリポジトリを読むすべての Harness エンジニアは、ソフトウェアエンジニアリングを遥かに超えたパターンを学んでいる。知的で自動化された未来のためのインフラストラクチャを構築することを学んでいる。実ドメインにデプロイされた優れた Harness の一つ一つが、Agent が知覚し、推論し、行動できる新たな拠点。
+このリポジトリには、第一マイルストーンとして LangChain / Deep Agents 教材トラック [`agents_deepagents/`](./agents_deepagents/) もあります。対象は `s01-s11` です。既存の `agents/*.py` Anthropic SDK 手書き実装は対照用にそのまま残しつつ、元チュートリアルの内部機構を逐語的に再現するのではなく、各章の重要な振る舞いを保ったまま、各 `sNN` ファイルでより自然な LangChain-native 実装を選ぶ方針です。web UI にはまだ接続していません。
 
-まずワークショップを満たす。次に農場、病院、工場。次に都市。次に惑星。
+中盤以降で境界が混ざり始めたら、次の順で立て直すのが安定です。
 
-**Bash is all you need. Real agents are all the universe needs.**
+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. その後で章本文へ戻る
 
----
+## Web 学習入口
 
-```
-                    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 -- の作り方を教える。
-```
+章順、段階境界、章どうしの差分を可視化から入りたい場合は、組み込みの web 教材画面を使えます。
 
-**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 +195,109 @@ 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               # 総括: 全メカニズム統合
 ```
 
-### Web プラットフォーム
-
-インタラクティブな可視化、ステップスルーアニメーション、ソースビューア、各セッションのドキュメント。
+その後、`.env` を手動で作成し、少なくとも `ANTHROPIC_API_KEY` を設定してください:
 
 ```sh
-cd web && npm install && npm run dev   # http://localhost:3000
+cat > .env <<'EOF'
+ANTHROPIC_API_KEY=your-key-here
+EOF
 ```
 
-## 学習パス
-
-```
-フェーズ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] = ツール数
-```
+OpenAI-compatible の教材トラックを使う場合は、`OPENAI_API_KEY` と必要に応じて `OPENAI_BASE_URL` も追加してください。
 
-## プロジェクト構成
+設定後に:
 
+```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
 ```
-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/)
+Deep Agents s01-s11 トラックを動かす場合は、`OPENAI_API_KEY` （必要なら `OPENAI_MODEL` と `OPENAI_BASE_URL`）を設定してから実行します:
 
-| セッション | トピック | モットー |
-|-----------|---------|---------|
-| [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 + タスク分離 | *各自のディレクトリで作業し、互いに干渉しない* |
+```sh
+python agents_deepagents/s01_agent_loop.py
+python agents_deepagents/s06_context_compact.py
+python agents_deepagents/s11_error_recovery.py
+```
 
-## 次のステップ -- 理解から出荷へ
+おすすめの進め方:
 
-12 セッションを終えれば、Harness 工学の内部構造を完全に理解している。その知識を活かす 2 つの方法:
+1. まず `s01` を動かし、最小ループが本当に動くことを確認する
+2. `s00` を読みながら `s01 -> s11` を順に進める
+3. 単体 agent 本体と control plane が安定して理解できてから `s12 -> s19` に入る
+4. 最後に `s_full.py` を見て、全部の機構を一枚の全体像に戻す
 
-### Kode Agent CLI -- オープンソース Coding Agent CLI
+### Deep Agents トラック（s01-s11）
 
-> `npm i -g @shareai-lab/kode`
+第一マイルストーンの LangChain / Deep Agents 教材実装は `agents_deepagents/` にあります。`s01-s11` の章立てはナビゲーション用に残しつつ、各ファイル内部ではより自然な LangChain-native 実装を優先します。実行時は OpenAI 互換の `OPENAI_API_KEY`、任意の `OPENAI_BASE_URL`、`OPENAI_MODEL` を使い、既存の `agents/*.py` Anthropic SDK ベースラインはそのまま比較用に維持します。
 
-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/             # 日本語文書
+├── 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
+## 最終目標
 
----
+読み終わるころには、次の問いに自分の言葉で答えられるようになるはずです。
 
-**Agency はモデルから生まれる。Harness が Agency を現実にする。優れた Harness を作れ。モデルが残りをやる。**
+- 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 9ed73ef30..2ba205a5b 100644
--- a/README-zh.md
+++ b/README-zh.md
@@ -1,372 +1,404 @@
-# Learn Claude Code -- 真正的 Agent Harness 工程
+# Learn Claude Code
 
-[English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md)
-
-## Agency 来自模型，Agent 产品 = 模型 + Harness
-
-在讨论代码之前，先把一件事说清楚。
-
-**Agency -- 感知、推理、行动的能力 -- 来自模型训练，不是来自外部代码的编排。** 但一个能干活的 agent 产品，需要模型和 harness 缺一不可。模型是驾驶者，harness 是载具。本仓库教你造载具。
-
-### Agency 从哪来
-
-Agent 的核心是一个神经网络 -- Transformer、RNN、一个被训练出来的函数 -- 经过数十亿次梯度更新，在行动序列数据上学会了感知环境、推理目标、采取行动。Agency 这个东西从来不是外面那层代码赋予的，而是模型在训练中学到的。
-
-人类就是最好的例子。一个由数百万年进化训练出来的生物神经网络，通过感官感知世界，通过大脑推理，通过身体行动。当 DeepMind、OpenAI 或 Anthropic 说 "agent" 时，他们说的核心都是同一件事：**一个通过训练学会了行动的模型，加上让它能在特定环境中工作的基础设施。**
+## 当前协作入口
 
-历史已经写好了铁证：
+如果你是来做当前仓库的主线开发，而不是阅读教程，那么默认入口应是：
 
-- **2013 -- DeepMind DQN 玩 Atari。** 一个神经网络，只接收原始像素和游戏分数，学会了 7 款 Atari 2600 游戏 -- 超越所有先前算法，在其中 3 款上击败人类专家。到 2015 年，同一架构扩展到 [49 款游戏，达到职业人类测试员水平](https://www.nature.com/articles/nature14236)，论文发表在 *Nature*。没有游戏专属规则。没有决策树。一个模型，从经验中学习。那个模型就是 agent。
+- 产品主线：`coding-deepgent/`
+- 规范与协作主入口：`.trellis/`
 
-- **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%。没有脚本化的策略。没有元编程的团队协调逻辑。模型完全通过自我对弈学会了团队协作、战术和实时适应。
+仓库外层的教学/参考层，包括 `agents/`、`agents_deepagents/`、`docs/`、`web/`、`skills/` 以及根目录教程测试，默认都不是当前实现目标，后续也可能继续裁剪。
 
-- **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 是什么？是模型。训练出来的。不是编出来的。
+[English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md)
 
-- **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 职业选手水准。没有手工编写的英雄克制表。没有脚本化的阵容编排。一个从零开始通过自我对弈学习整个游戏的模型。
+一个面向实现者的教学仓库：从零开始，手搓一个高完成度的 coding agent harness。
 
-- **2024-2025 -- LLM Agent 重塑软件工程。** Claude、GPT、Gemini -- 在人类全部代码和推理上训练的大语言模型 -- 被部署为编程 agent。它们阅读代码库，编写实现，调试故障，团队协作。架构与之前每一个 agent 完全相同：一个训练好的模型，放入一个环境，给予感知和行动的工具。唯一的不同是它们学到的东西的规模和解决任务的通用性。
+这里教的不是“如何逐行模仿某个官方仓库”，而是“如何抓住真正决定 agent 能力的核心机制”，用清晰、渐进、可自己实现的方式，把一个类似 Claude Code 的系统从 0 做到能用、好用、可扩展。
 
-每一个里程碑都指向同一个事实：**Agency -- 那个感知、推理、行动的能力 -- 是训练出来的，不是编出来的。** 但每一个 agent 同时也需要一个环境才能工作：Atari 模拟器、Dota 2 客户端、星际争霸 II 引擎、IDE 和终端。模型提供智能，环境提供行动空间。两者合在一起才是一个完整的 agent。
+## 这个仓库到底在教什么
 
-### Agent 不是什么
+先把一句话说清楚：
 
-"Agent" 这个词已经被一整个提示词水管工产业劫持了。
+**模型负责思考。代码负责给模型提供工作环境。**
 
-拖拽式工作流构建器。无代码 "AI Agent" 平台。提示词链编排库。它们共享同一个幻觉：把 LLM API 调用用 if-else 分支、节点图、硬编码路由逻辑串在一起就算是 "构建 Agent" 了。
+这个“工作环境”就是 `harness`。  
+对 coding agent 来说，harness 主要由这些部分组成：
 
-不是的。它们做出来的东西是鲁布·戈德堡机械 -- 一个过度工程化的、脆弱的过程式规则流水线，LLM 被楔在里面当一个美化了的文本补全节点。那不是 Agent。那是一个有着宏大妄想的 shell 脚本。
+- `Agent Loop`：不停地“向模型提问 -> 执行工具 -> 把结果喂回去”。
+- `Tools`：读文件、写文件、改文件、跑命令、搜索内容。
+- `Planning`：把大目标拆成小步骤，不让 agent 乱撞。
+- `Context Management`：避免上下文越跑越脏、越跑越长。
+- `Permissions`：危险操作先过安全关。
+- `Hooks`：不改核心循环，也能扩展行为。
+- `Memory`：把跨会话仍然有价值的信息保存下来。
+- `Prompt Construction`：把系统说明、工具信息、约束和上下文组装好。
+- `Tasks / Teams / Worktree / MCP`：让系统从单 agent 升级成更完整的工作平台。
 
-**提示词水管工式 "Agent" 是不做模型的程序员的意淫。** 他们试图通过堆叠过程式逻辑来暴力模拟智能 -- 庞大的规则树、节点图、链式提示词瀑布流 -- 然后祈祷足够多的胶水代码能涌现出自主行为。不会的。你不可能通过工程手段编码出 agency。Agency 是学出来的，不是编出来的。
+本仓库的目标，是让你真正理解这些机制为什么存在、最小版本怎么实现、什么时候该升级到更完整的版本。
 
-那些系统从诞生之日起就已经死了：脆弱、不可扩展、根本不具备泛化能力。它们是 GOFAI（Good Old-Fashioned AI，经典符号 AI）的现代还魂 -- 几十年前就被学界抛弃的符号规则系统，现在喷了一层 LLM 的漆又登场了。换了个包装，同一条死路。
+## 这个仓库不教什么
 
-### 心智转换：从 "开发 Agent" 到开发 Harness
+本仓库**不追求**把某个真实生产仓库的所有实现细节逐条抄下来。
 
-当一个人说 "我在开发 Agent" 时，他只可能是两个意思之一：
+下面这些内容，如果和 agent 的核心运行机制关系不大，就不会占据主线篇幅：
 
-**1. 训练模型。** 通过强化学习、微调、RLHF 或其他基于梯度的方法调整权重。收集任务过程数据 -- 真实领域中感知、推理、行动的实际序列 -- 用它们来塑造模型的行为。这是 DeepMind、OpenAI、腾讯 AI Lab、Anthropic 在做的事。这是最本义的 Agent 开发。
+- 打包、编译、发布流程
+- 跨平台兼容层的全部细节
+- 企业策略、遥测、远程控制、账号体系的完整接线
+- 为了历史兼容或产品集成而出现的大量边角判断
+- 只对某个特定内部运行环境有意义的命名或胶水代码
 
-**2. 构建 Harness。** 编写代码，为模型提供一个可操作的环境。这是我们大多数人在做的事，也是本仓库的核心。
+这不是偷懒，而是教学取舍。
 
-Harness 是 agent 在特定领域工作所需要的一切：
+一个好的教学仓库，应该优先保证三件事：
 
-```
-Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions
+1. 读者能从 0 到 1 自己做出来。
+2. 读者不会被大量无关细节打断心智。
+3. 真正关键的机制、数据结构和模块协作关系讲得完整、准确、没有幻觉。
 
-    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 跨领域泛化。
+- 会一点 Python
+- 知道函数、类、字典、列表这些基础概念
+- 但不一定系统做过 agent、编译器、分布式系统或复杂工程架构
 
-这个仓库教你造载具。编程用的载具。但设计模式可以泛化到任何领域：庄园管理、农田运营、酒店运作、工厂制造、物流调度、医疗保健、教育培训、科学研究。只要有一个任务需要被感知、推理和执行 -- agent 就需要一个 harness。
+所以这里会坚持几个写法原则：
 
-### Harness 工程师到底在做什么
+- 新概念先解释再使用。
+- 同一个概念尽量只在一个地方完整讲清。
+- 先讲“它是什么”，再讲“为什么需要”，最后讲“如何实现”。
+- 不把初学者扔进一堆互相引用的碎片文档里自己拼图。
 
-如果你在读这个仓库，你很可能是一名 harness 工程师 -- 这是一个强大的身份。以下是你真正的工作：
+## 学习承诺
 
-- **实现工具。** 给 agent 一双手。文件读写、Shell 执行、API 调用、浏览器控制、数据库查询。每个工具都是 agent 在环境中可以采取的一个行动。设计它们时要原子化、可组合、描述清晰。
+学完这套内容，你应该能做到两件事：
 
-- **策划知识。** 给 agent 领域专长。产品文档、架构决策记录、风格指南、合规要求。按需加载（s05），不要前置塞入。Agent 应该知道有什么可用，然后自己拉取所需。
+1. 自己从零写出一个结构清楚、可运行、可迭代的 coding agent harness。
+2. 看懂更复杂系统时，知道哪些是主干机制，哪些只是产品化外围细节。
 
-- **管理上下文。** 给 agent 干净的记忆。子 agent 隔离（s04）防止噪声泄露。上下文压缩（s06）防止历史淹没。任务系统（s07）让目标持久化到单次对话之外。
+我们追求的是：
 
-- **控制权限。** 给 agent 边界。沙箱化文件访问。对破坏性操作要求审批。在 agent 和外部系统之间实施信任边界。这是安全工程与 harness 工程的交汇点。
+- 对关键机制和关键数据结构的高保真理解
+- 对实现路径的高可操作性
+- 对教学路径的高可读性
 
-- **收集任务过程数据。** Agent 在你的 harness 中执行的每一条行动序列都是训练信号。真实部署中的感知-推理-行动轨迹是微调下一代 agent 模型的原材料。你的 harness 不仅服务于 agent -- 它还可以帮助进化 agent。
+而不是把“原始源码里存在过的所有复杂细节”一股脑堆给你。
 
-你不是在编写智能。你是在构建智能栖居的世界。这个世界的质量 -- agent 能看得多清楚、行动得多精准、可用知识有多丰富 -- 直接决定了智能能多有效地表达自己。
+## 建议阅读顺序
 
-**造好 Harness。Agent 会完成剩下的。**
+先读总览，再按顺序向后读。
 
-### 为什么是 Claude Code -- 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)
 
-为什么这个仓库专门拆解 Claude Code？
+## 第一次打开仓库，最推荐这样走
 
-因为 Claude Code 是我们所见过的最优雅、最完整的 agent harness 实现。不是因为某个巧妙的技巧，而是因为它 *没做* 的事：它没有试图成为 agent 本身。它没有强加僵化的工作流。它没有用精心设计的决策树去替模型做判断。它给模型提供了工具、知识、上下文管理和权限边界 -- 然后让开了。
+如果你是第一次进这个仓库，不要随机点章节。
 
-把 Claude Code 剥到本质来看：
+最稳的入口顺序是：
 
-```
-Claude Code = 一个 agent loop
-            + 工具 (bash, read, write, edit, glob, grep, browser...)
-            + 按需 skill 加载
-            + 上下文压缩
-            + 子 agent 派生
-            + 带依赖图的任务系统
-            + 异步邮箱的团队协调
-            + worktree 隔离的并行执行
-            + 权限治理
-```
-
-就这些。这就是全部架构。每一个组件都是 harness 机制 -- 为 agent 构建的栖居世界的一部分。Agent 本身呢？是 Claude。一个模型。由 Anthropic 在人类推理和代码的全部广度上训练而成。Harness 没有让 Claude 变聪明。Claude 本来就聪明。Harness 给了 Claude 双手、双眼和一个工作空间。
+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. 每学完一个阶段，停下来自己手写一个最小版本，不要等全部看完再回头补实现。
 
-这就是 Claude Code 作为教学标本的意义：**它展示了当你信任模型、把工程精力集中在 harness 上时会发生什么。** 本仓库的每一个课程（s01-s12）都在逆向工程 Claude Code 架构中的一个 harness 机制。学完之后，你理解的不只是 Claude Code 怎么工作，而是适用于任何领域、任何 agent 的 harness 工程通用原则。
+## Deep Agents s01-s11 轨道
 
-启示不是 "复制 Claude Code"。启示是：**最好的 agent 产品，出自那些明白自己的工作是 harness 而非 intelligence 的工程师之手。**
+仓库现在还提供第一阶段里程碑的 LangChain / Deep Agents 教学轨道：[`agents_deepagents/`](./agents_deepagents/)。它覆盖 `s01-s11`，保留原来的 `agents/*.py` Anthropic SDK 手写基线做对照，不强求逐行照搬原教程内部机制，而是优先保留每章的关键行为，并在各个 `sNN` 文件里选择更自然的 LangChain-native 实现。它也暂时不接入 web UI。
 
----
+如果你读到一半开始打结，最稳的重启顺序是：
 
-## 愿景：用真正的 Agent 铺满宇宙
+1. [`docs/zh/data-structures.md`](./docs/zh/data-structures.md)
+2. [`docs/zh/entity-map.md`](./docs/zh/entity-map.md)
+3. 当前卡住章节对应的桥接文档
+4. 再回当前章节正文
 
-这不只关乎编程 agent。
+## Web 学习入口
 
-每一个人类从事复杂、多步骤、需要判断力的工作的领域，都是 agent 可以运作的领域 -- 只要有对的 harness。本仓库中的模式是通用的：
+如果你更喜欢先看可视化的主线、阶段和章节差异，可以直接跑本仓库自带的 web 教学界面：
 
+```sh
+cd web
+npm install
+npm run dev
 ```
-庄园管理 agent  = 模型 + 物业传感器 + 维护工具 + 租户通信
-农业 agent      = 模型 + 土壤/气象数据 + 灌溉控制 + 作物知识
-酒店运营 agent  = 模型 + 预订系统 + 客户渠道 + 设施 API
-医学研究 agent  = 模型 + 文献检索 + 实验仪器 + 协议文档
-制造业 agent    = 模型 + 产线传感器 + 质量控制 + 物流系统
-教育 agent      = 模型 + 课程知识 + 学生进度 + 评估工具
-```
-
-循环永远不变。工具在变。知识在变。权限在变。Agent -- 那个模型 -- 泛化一切。
-
-每一个读这个仓库的 harness 工程师都在学习远超软件工程的模式。你在学习为一个智能的、自动化的未来构建基础设施。每一个部署在真实领域的好 harness，都是 agent 能够感知、推理、行动的又一个阵地。
 
-先铺满工作室。然后是农田、医院、工厂。然后是城市。然后是星球。
+然后按这个顺序打开：
+
+- `/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. 当前卡住的那一章
+
+因为读者真正卡住时，往往不是“代码没看懂”，而是：
+
+- 这个机制到底接在系统哪一层
+- 这个状态到底存在哪个结构里
+- 这个名词和另一个看起来很像的名词到底差在哪
 
-**Bash is all you need. Real agents are all the universe needs.**
-
----
+## 快速开始
 
+```sh
+git clone https://github.com/shareAI-lab/learn-claude-code
+cd learn-claude-code
+pip install -r requirements.txt
 ```
-                    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 个递进式课程, 从简单循环到隔离化的自治执行。**
-**每个课程添加一个 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 绑定
 
----
+然后手动创建 `.env`，至少写入 `ANTHROPIC_API_KEY`：
 
-## 核心模式
-
-```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
+cat > .env <<'EOF'
+ANTHROPIC_API_KEY=your-key-here
+EOF
 ```
 
-每个课程在这个循环之上叠加一个 harness 机制 -- 循环本身始终不变。循环属于 agent。机制属于 harness。
-
-## 范围说明 (重要)
+如果你要跑 OpenAI-compatible 的教学分支，再补 `OPENAI_API_KEY`，并按需设置 `OPENAI_BASE_URL`。
 
-本仓库是一个 0->1 的 harness 工程学习项目 -- 构建围绕 agent 模型的工作环境。
-为保证学习路径清晰，仓库有意简化或省略了部分生产机制：
+把 `.env` 配置好以后：
 
-- 完整事件 / Hook 总线 (例如 PreToolUse、SessionStart/End、ConfigChange)。
-  s12 仅提供教学用途的最小 append-only 生命周期事件流。
-- 基于规则的权限治理与信任流程
-- 会话生命周期控制 (resume/fork) 与更完整的 worktree 生命周期控制
-- 完整 MCP 运行时细节 (transport/OAuth/资源订阅/轮询)
-
-仓库中的团队 JSONL 邮箱协议是教学实现，不是对任何特定生产内部实现的声明。
+```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
+```
 
-## 快速开始
+如果要运行 Deep Agents s01-s11 轨道，请另外配置 `OPENAI_API_KEY`，可选配置 `OPENAI_MODEL` 和 `OPENAI_BASE_URL`，然后运行：
 
 ```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               # 总纲: 全部机制合一
+python agents_deepagents/s01_agent_loop.py
+python agents_deepagents/s06_context_compact.py
+python agents_deepagents/s11_error_recovery.py
 ```
 
-### Web 平台
+建议顺序：
 
-交互式可视化、分步动画、源码查看器, 以及每个课程的文档。
+1. 先跑 `s01`，确认最小循环真的能工作。
+2. 一边读 `s00`，一边按顺序跑 `s01 -> s10`。
+3. 等前 10 章吃透后，再进入 `s11 -> s19`。
+4. 最后再看 `s_full.py`，把所有机制放回同一张图里。
 
-```sh
-cd web && npm install && npm run dev   # http://localhost:3000
-```
+### Deep Agents 轨道（s01-s11）
 
-## 学习路径
+第一阶段新增的 LangChain / Deep Agents 教学实现放在 `agents_deepagents/`。它保留
+`s01-s11` 的章节外壳作为导航线索，但在每个文件内部优先采用更自然的
+LangChain-native 实现；运行时使用 OpenAI-compatible 的
+`OPENAI_API_KEY`、可选 `OPENAI_BASE_URL` 与 `OPENAI_MODEL` 配置，同时保留
+原来的 `agents/*.py` Anthropic SDK 基线做对照。
 
-```
-第一阶段: 循环                       第二阶段: 规划与知识
-==================                   ==============================
-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] = 工具数量
+```sh
+python agents_deepagents/s01_agent_loop.py
+python agents_deepagents/s06_context_compact.py
+python agents_deepagents/s11_error_recovery.py
 ```
 
-## 项目结构
+文件对应关系、迁移策略，以及“测试不需要 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: 类型检查 + 构建
-```
+## 如何读这套教程
 
-## 文档
+每章都建议按这个顺序看：
 
-心智模型优先: 问题、方案、ASCII 图、最小化代码。
-[English](./docs/en/) | [中文](./docs/zh/) | [日本語](./docs/ja/)
+1. `问题`：没有这个机制会出现什么痛点。
+2. `概念定义`：先把新名词讲清楚。
+3. `最小实现`：先做最小但正确的版本。
+4. `核心数据结构`：搞清楚状态到底存在哪里。
+5. `主循环如何接入`：它如何与 agent loop 协作。
+6. `这一章先停在哪里`：先守住什么边界，哪些扩展可以后放。
 
-| 课程 | 主题 | 格言 |
-|------|------|------|
-| [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
+建议随时回看：
 
-> `npm i -g @shareai-lab/kode`
+- [`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)
 
-支持 Skill & LSP, 适配 Windows, 可接 GLM / MiniMax / DeepSeek 等开放模型。装完即用。
+## 本仓库的教学取舍
 
-GitHub: **[shareAI-lab/Kode-cli](https://github.com/shareAI-lab/Kode-cli)**
+为了保证“从 0 到 1 可实现”，本仓库会刻意做这些取舍：
 
-### 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/             # 日文文档，当前为部分同步
+├── 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
+如果这些问题你都能清楚回答，而且能自己写出一个相似系统，那这套仓库就达到了它的目的。
 
 ---
 
-**Agency 来自模型。Harness 让 agency 落地。造好 Harness，模型会完成剩下的。**
-
-**Bash is all you need. Real agents are all the universe needs.**
+**这不是“照着源码抄”。这是“抓住真正关键的设计，然后自己做出来”。**
diff --git a/README.md b/README.md
index 5d31cf7d1..a60859a2e 100644
--- a/README.md
+++ b/README.md
@@ -1,233 +1,199 @@
 [English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md)
-# Learn Claude Code -- Harness Engineering for Real Agents
 
-## Agency Comes from the Model. An Agent Product = Model + Harness.
+# Learn Claude Code
 
-Before we talk about code, let's get one thing straight.
+## Current Contributor Note
 
-**Agency -- the ability to perceive, reason, and act -- comes from model training, not from external code orchestration.** But a working agent product needs both the model and the harness. The model is the driver, the harness is the vehicle. This repo teaches you how to build the vehicle.
+For active development work in this repository, the current mainline is
+`coding-deepgent/` and the canonical coordination/spec layer is `.trellis/`.
 
-### Where Agency Comes From
+The outer teaching/reference layer, including `agents/`, `agents_deepagents/`,
+`docs/`, `web/`, `skills/`, and root tutorial tests, is reference-only by
+default and may lag behind or be pruned as product work evolves.
 
-At the core of every 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. Agency is never granted by the surrounding code. It is learned by the model during training.
+A teaching repository for implementers who want to build a high-completion coding-agent harness from scratch.
 
-Humans are the best example. 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," the core of what they mean is always the same thing: **a model that has learned to act, plus the infrastructure that lets it operate in a specific environment.**
+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:
 
-The proof is written in history:
+- the loop
+- tools
+- planning
+- delegation
+- context control
+- permissions
+- hooks
+- memory
+- prompt assembly
+- tasks
+- teams
+- isolated execution lanes
+- external capability routing
 
-- **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.
+The goal is simple:
 
-- **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.
+**understand the real design backbone well enough that you can rebuild it yourself.**
 
-- **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.
+## What This Repo Is Really Teaching
 
-- **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.
+One sentence first:
 
-- **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.
+**The model does the reasoning. The harness gives the model a working environment.**
 
-Every one of these milestones points to the same fact: **agency -- the ability to perceive, reason, and act -- is trained, not coded.** But every agent also needed an environment to operate in: the Atari emulator, the Dota 2 client, the StarCraft II engine, the IDE and terminal. The model provides intelligence. The environment provides the action space. Together they form a complete agent.
+That working environment is made of a few cooperating parts:
 
-### What an Agent Is NOT
+- `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
 
-The word "agent" has been hijacked by an entire cottage industry of prompt plumbing.
+This is the teaching promise of the repo:
 
-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."
+- 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
 
-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.
+## What This Repo Deliberately Does Not Teach
 
-**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.
+This repo is not trying to preserve every detail that may exist in a real production system.
 
-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.
+If a detail is not central to the agent's core operating model, it should not dominate the teaching line. That includes things like:
 
-### The Mind Shift: From "Developing Agents" to Developing Harness
+- packaging and release mechanics
+- cross-platform compatibility layers
+- enterprise policy glue
+- telemetry and account wiring
+- historical compatibility branches
+- product-specific naming accidents
 
-When someone says "I'm developing an agent," they can only mean one of two things:
+Those details may matter in production. They do not belong at the center of a 0-to-1 teaching path.
 
-**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.
+## Who This Is For
 
-**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.
+The assumed reader:
 
-A harness is everything the agent needs to function in a specific domain:
+- knows basic Python
+- understands functions, classes, lists, and dictionaries
+- may be completely new to agent systems
 
-```
-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
+So the repo tries to keep a few strong teaching rules:
 
-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:
+- 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
 
-- **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.
+## Recommended Reading Order
 
-- **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.
+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.
 
-- **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.
+- 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)
 
-- **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.
+## If This Is Your First Visit, Start Here
 
-- **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.
+Do not open random chapters first.
 
-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 safest path is:
 
-**Build great harnesses. The agent will do the rest.**
+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.
 
-### Why Claude Code -- A Masterclass in Harness Engineering
-
-Why does this repository dissect Claude Code specifically?
-
-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.
-
-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
-```
+## Deep Agents s01-s11 Track
 
-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 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.
 
-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.
+If the middle and late chapters start to blur together, reset in this order:
 
-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.**
+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 Vision: Fill the Universe with Real Agents
+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:
 
-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
-```
-
-The loop is always the same. The tools change. The knowledge changes. The permissions change. The agent -- the model -- generalizes.
-
-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.
-
-First we fill the workshops. Then the farms, the hospitals, the factories. Then the cities. Then the planet.
-
-**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[]
-
-
-    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.
-```
-
-**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 +201,113 @@ 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
 ```
 
-### Web Platform
-
-Interactive visualizations, step-through diagrams, source viewer, and documentation.
+Then create `.env`, configure `ANTHROPIC_API_KEY` or a compatible endpoint, and run:
 
 ```sh
-cd web && npm install && npm run dev   # http://localhost:3000
+cat > .env <<'EOF'
+ANTHROPIC_API_KEY=your-key-here
+EOF
 ```
 
-## Learning Path
+If you need the OpenAI-compatible teaching track, also add `OPENAI_API_KEY`
+and optionally `OPENAI_BASE_URL`.
 
-```
-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
+```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
 ```
 
-## Architecture
+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
 ```
-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
+├── 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:
 
-**Agency comes from the model. The harness makes agency real. Build great harnesses. The model 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..205a28477
--- /dev/null
+++ b/agents_deepagents/README.md
@@ -0,0 +1,120 @@
+# LangChain-Native Deep Agents s01-s06 Teaching Track
+
+> Reference-only note:
+> this directory is a teaching track, not the current product mainline.
+> Active implementation work should default to `coding-deepgent/` plus
+> `.trellis/`. Tutorial assets here may lag behind current product decisions.
+
+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..2d824337a
--- /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
+    repository's Anthropic-oriented default model naming; 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..e409b6f1b
--- /dev/null
+++ b/coding-deepgent/PROJECT_PROGRESS.md
@@ -0,0 +1,112 @@
+# coding-deepgent progress
+
+## Canonical Coordination Note
+
+This file is a product status ledger.
+
+Canonical live coordination, specs, and implementation contracts now belong in:
+
+- `../.trellis/project-handoff.md`
+- `../.trellis/plans/coding-deepgent-cc-core-highlights-roadmap.md`
+- `../.trellis/spec/backend/*.md`
+
+## 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-15
+
+This stage marker is retained as a product-local compatibility anchor for
+`coding-deepgent` docs/tests. It is not the canonical live release-progress
+tracker anymore.
+
+Canonical live status is now:
+
+- Approach A MVP closeout completed through `Stage 29`
+- `Circle 1 / Wave 1` runtime-core parity checkpoint is implemented
+- `Circle 1` local daily-driver parity baseline is implemented
+- `Circle 2` local expanded parity baseline is implemented
+- still outside the local Circle 2 baseline: hosted SaaS ingress, multi-user
+  auth, public marketplace backend, and cross-machine workers
+
+For the live source of truth, use:
+
+- `../.trellis/project-handoff.md`
+- `../.trellis/plans/coding-deepgent-full-cc-parity-roadmap.md`
+
+## 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..70b45ff53
--- /dev/null
+++ b/coding-deepgent/README.md
@@ -0,0 +1,152 @@
+# coding-deepgent
+
+Independent cumulative LangChain cc product surface.
+
+## Canonical Working Docs
+
+For current implementation work, treat these as canonical first:
+
+- `../AGENTS.md`
+- `../.trellis/workflow.md`
+- `../.trellis/project-handoff.md`
+- `../.trellis/plans/coding-deepgent-full-cc-parity-roadmap.md`
+- `../.trellis/plans/coding-deepgent-circle-2-expanded-parity-plan.md`
+- `../.trellis/spec/backend/*.md`
+
+This README is a product summary, not the canonical place for live
+coordination rules or executable implementation contracts.
+
+## 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.
+
+The `current_product_stage` marker is retained here as a product-local
+compatibility anchor for `coding-deepgent` docs and contract tests.
+
+Canonical live release status has moved to Trellis:
+
+- `../.trellis/project-handoff.md`
+- `../.trellis/plans/coding-deepgent-full-cc-parity-roadmap.md`
+- `../.trellis/plans/coding-deepgent-circle-2-expanded-parity-plan.md`
+
+As of 2026-04-20:
+
+- `Approach A MVP` remains a historical verified baseline
+- `Circle 1` local daily-driver parity baseline is implemented
+- `Circle 2` local expanded parity baseline is implemented
+- hosted SaaS ingress, multi-user auth, public marketplace backend, and
+  cross-machine workers remain outside the current local baseline
+
+## 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 sessions history|projection|timeline|evidence|events|permissions ...` — inspect session continuity and recovery state
+- `coding-deepgent tasks ...` / `plans ...` — durable workflow state
+- `coding-deepgent skills|mcp|hooks|plugins ...` — local extension inspect/debug surfaces
+- `coding-deepgent events|workers|mailbox|teams|remote|extension-lifecycle|continuity ...` — local expanded parity baseline control surfaces
+- `coding-deepgent acceptance circle1|circle2` — deterministic baseline acceptance harnesses
+- `coding-deepgent doctor` — verify CLI/rendering/logging dependencies locally
+- `coding-deepgent ui` — start the React/Ink CLI frontend
+- `coding-deepgent-ui` — product shortcut for `coding-deepgent ui`
+- `coding-deepgent ui-bridge` — JSONL backend bridge for the React/Ink frontend
+- `coding-deepgent ui-gateway` — start the future-Web SSE gateway foundation; requires optional `web` dependencies (`pip install -e .[web]`)
+
+The React/Ink CLI frontend lives in `frontend/cli` and talks to the Python
+runtime through the JSONL adapter exposed by `ui-bridge`.
+
+Frontend backend layering:
+
+- `coding_deepgent.frontend.protocol` — renderer-neutral events and inputs
+- `coding_deepgent.frontend.producer` — runtime event producer
+- `coding_deepgent.frontend.adapters.jsonl` — stdio JSONL transport for CLI
+- `coding_deepgent.frontend.adapters.sse` — SSE formatter/consumer for future Web
+- `coding_deepgent.frontend.client` — embedded Python client for scripts/tests
+- `coding_deepgent.frontend.runs` — background run lifecycle
+- `coding_deepgent.frontend.stream_bridge` — replayable in-memory event bridge
+- `coding_deepgent.frontend.bridge` — backward-compatible import shim
+
+Current minimal web shell:
+
+- `coding-deepgent/frontend/web/index.html` — static browser UI
+- served by `coding-deepgent ui-gateway` at `/ui`
+
+Development commands:
+
+- `coding-deepgent-ui --fake` — start the interactive CLI through the product shortcut with deterministic fake responses
+- `coding-deepgent-ui` — start the interactive CLI through the product shortcut
+- `coding-deepgent ui --fake` — start the interactive CLI against a deterministic fake bridge
+- `coding-deepgent ui` — start the interactive CLI against the Python runtime
+- `npm --prefix frontend/cli install` — install the React/Ink CLI package dependencies when first setting up the repo
+- `pip install -e .[web]` — install the optional FastAPI/Uvicorn gateway dependencies
+- `coding-deepgent ui-gateway --fake` — start the SSE gateway and browse to `http://127.0.0.1:2027/ui`
+- `npm --prefix frontend/cli run dev:fake` — start the interactive CLI against a deterministic fake bridge
+- `npm --prefix frontend/cli run dev` — start the interactive CLI against the Python runtime
+
+The frontend protocol supports live assistant deltas and permission request
+events. The CLI JSONL bridge now supports same-process LangGraph interrupt
+pause/resume for permission approval; the SSE gateway still needs a dedicated
+resume endpoint before it should claim full HITL approval support.
+
+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/frontend/cli/package-lock.json b/coding-deepgent/frontend/cli/package-lock.json
new file mode 100644
index 000000000..e9d984893
--- /dev/null
+++ b/coding-deepgent/frontend/cli/package-lock.json
@@ -0,0 +1,2386 @@
+{
+  "name": "@coding-deepgent/cli-frontend",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@coding-deepgent/cli-frontend",
+      "version": "0.1.0",
+      "dependencies": {
+        "ink": "^6.8.0",
+        "react": "^19.2.4"
+      },
+      "bin": {
+        "coding-deepgent-ui": "src/index.tsx"
+      },
+      "devDependencies": {
+        "@types/node": "^20.19.25",
+        "@types/react": "^19.2.7",
+        "tsx": "^4.21.0",
+        "typescript": "^5.9.3",
+        "vitest": "^4.0.15"
+      }
+    },
+    "node_modules/@alcalzone/ansi-tokenize": {
+      "version": "0.2.5",
+      "resolved": "https://registry.npmmirror.com/@alcalzone/ansi-tokenize/-/ansi-tokenize-0.2.5.tgz",
+      "integrity": "sha512-3NX/MpTdroi0aKz134A6RC2Gb2iXVECN4QaAXnvCIxxIm3C3AVB1mkUe8NaaiyvOpDfsrqWhYtj+Q6a62RrTsw==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^6.2.1",
+        "is-fullwidth-code-point": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@emnapi/core": {
+      "version": "1.9.2",
+      "resolved": "https://registry.npmmirror.com/@emnapi/core/-/core-1.9.2.tgz",
+      "integrity": "sha512-UC+ZhH3XtczQYfOlu3lNEkdW/p4dsJ1r/bP7H8+rhao3TTTMO1ATq/4DdIi23XuGoFY+Cz0JmCbdVl0hz9jZcA==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@emnapi/wasi-threads": "1.2.1",
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@emnapi/runtime": {
+      "version": "1.9.2",
+      "resolved": "https://registry.npmmirror.com/@emnapi/runtime/-/runtime-1.9.2.tgz",
+      "integrity": "sha512-3U4+MIWHImeyu1wnmVygh5WlgfYDtyf0k8AbLhMFxOipihf6nrWC4syIm/SwEeec0mNSafiiNnMJwbza/Is6Lw==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@emnapi/wasi-threads": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmmirror.com/@emnapi/wasi-threads/-/wasi-threads-1.2.1.tgz",
+      "integrity": "sha512-uTII7OYF+/Mes/MrcIOYp5yOtSMLBWSIoLPpcgwipoiKbli6k322tcoFsxoIIxPDqW01SQGAgko4EzZi2BNv2w==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/aix-ppc64/-/aix-ppc64-0.27.7.tgz",
+      "integrity": "sha512-EKX3Qwmhz1eMdEJokhALr0YiD0lhQNwDqkPYyPhiSwKrh7/4KRjQc04sZ8db+5DVVnZ1LmbNDI1uAMPEUBnQPg==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/android-arm/-/android-arm-0.27.7.tgz",
+      "integrity": "sha512-jbPXvB4Yj2yBV7HUfE2KHe4GJX51QplCN1pGbYjvsyCZbQmies29EoJbkEc+vYuU5o45AfQn37vZlyXy4YJ8RQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/android-arm64/-/android-arm64-0.27.7.tgz",
+      "integrity": "sha512-62dPZHpIXzvChfvfLJow3q5dDtiNMkwiRzPylSCfriLvZeq0a1bWChrGx/BbUbPwOrsWKMn8idSllklzBy+dgQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/android-x64/-/android-x64-0.27.7.tgz",
+      "integrity": "sha512-x5VpMODneVDb70PYV2VQOmIUUiBtY3D3mPBG8NxVk5CogneYhkR7MmM3yR/uMdITLrC1ml/NV1rj4bMJuy9MCg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/darwin-arm64/-/darwin-arm64-0.27.7.tgz",
+      "integrity": "sha512-5lckdqeuBPlKUwvoCXIgI2D9/ABmPq3Rdp7IfL70393YgaASt7tbju3Ac+ePVi3KDH6N2RqePfHnXkaDtY9fkw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/darwin-x64/-/darwin-x64-0.27.7.tgz",
+      "integrity": "sha512-rYnXrKcXuT7Z+WL5K980jVFdvVKhCHhUwid+dDYQpH+qu+TefcomiMAJpIiC2EM3Rjtq0sO3StMV/+3w3MyyqQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.7.tgz",
+      "integrity": "sha512-B48PqeCsEgOtzME2GbNM2roU29AMTuOIN91dsMO30t+Ydis3z/3Ngoj5hhnsOSSwNzS+6JppqWsuhTp6E82l2w==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/freebsd-x64/-/freebsd-x64-0.27.7.tgz",
+      "integrity": "sha512-jOBDK5XEjA4m5IJK3bpAQF9/Lelu/Z9ZcdhTRLf4cajlB+8VEhFFRjWgfy3M1O4rO2GQ/b2dLwCUGpiF/eATNQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/linux-arm/-/linux-arm-0.27.7.tgz",
+      "integrity": "sha512-RkT/YXYBTSULo3+af8Ib0ykH8u2MBh57o7q/DAs3lTJlyVQkgQvlrPTnjIzzRPQyavxtPtfg0EopvDyIt0j1rA==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/linux-arm64/-/linux-arm64-0.27.7.tgz",
+      "integrity": "sha512-RZPHBoxXuNnPQO9rvjh5jdkRmVizktkT7TCDkDmQ0W2SwHInKCAV95GRuvdSvA7w4VMwfCjUiPwDi0ZO6Nfe9A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/linux-ia32/-/linux-ia32-0.27.7.tgz",
+      "integrity": "sha512-GA48aKNkyQDbd3KtkplYWT102C5sn/EZTY4XROkxONgruHPU72l+gW+FfF8tf2cFjeHaRbWpOYa/uRBz/Xq1Pg==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/linux-loong64/-/linux-loong64-0.27.7.tgz",
+      "integrity": "sha512-a4POruNM2oWsD4WKvBSEKGIiWQF8fZOAsycHOt6JBpZ+JN2n2JH9WAv56SOyu9X5IqAjqSIPTaJkqN8F7XOQ5Q==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/linux-mips64el/-/linux-mips64el-0.27.7.tgz",
+      "integrity": "sha512-KabT5I6StirGfIz0FMgl1I+R1H73Gp0ofL9A3nG3i/cYFJzKHhouBV5VWK1CSgKvVaG4q1RNpCTR2LuTVB3fIw==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/linux-ppc64/-/linux-ppc64-0.27.7.tgz",
+      "integrity": "sha512-gRsL4x6wsGHGRqhtI+ifpN/vpOFTQtnbsupUF5R5YTAg+y/lKelYR1hXbnBdzDjGbMYjVJLJTd2OFmMewAgwlQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/linux-riscv64/-/linux-riscv64-0.27.7.tgz",
+      "integrity": "sha512-hL25LbxO1QOngGzu2U5xeXtxXcW+/GvMN3ejANqXkxZ/opySAZMrc+9LY/WyjAan41unrR3YrmtTsUpwT66InQ==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/linux-s390x/-/linux-s390x-0.27.7.tgz",
+      "integrity": "sha512-2k8go8Ycu1Kb46vEelhu1vqEP+UeRVj2zY1pSuPdgvbd5ykAw82Lrro28vXUrRmzEsUV0NzCf54yARIK8r0fdw==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/linux-x64/-/linux-x64-0.27.7.tgz",
+      "integrity": "sha512-hzznmADPt+OmsYzw1EE33ccA+HPdIqiCRq7cQeL1Jlq2gb1+OyWBkMCrYGBJ+sxVzve2ZJEVeePbLM2iEIZSxA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.7.tgz",
+      "integrity": "sha512-b6pqtrQdigZBwZxAn1UpazEisvwaIDvdbMbmrly7cDTMFnw/+3lVxxCTGOrkPVnsYIosJJXAsILG9XcQS+Yu6w==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/netbsd-x64/-/netbsd-x64-0.27.7.tgz",
+      "integrity": "sha512-OfatkLojr6U+WN5EDYuoQhtM+1xco+/6FSzJJnuWiUw5eVcicbyK3dq5EeV/QHT1uy6GoDhGbFpprUiHUYggrw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.7.tgz",
+      "integrity": "sha512-AFuojMQTxAz75Fo8idVcqoQWEHIXFRbOc1TrVcFSgCZtQfSdc1RXgB3tjOn/krRHENUB4j00bfGjyl2mJrU37A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/openbsd-x64/-/openbsd-x64-0.27.7.tgz",
+      "integrity": "sha512-+A1NJmfM8WNDv5CLVQYJ5PshuRm/4cI6WMZRg1by1GwPIQPCTs1GLEUHwiiQGT5zDdyLiRM/l1G0Pv54gvtKIg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.7.tgz",
+      "integrity": "sha512-+KrvYb/C8zA9CU/g0sR6w2RBw7IGc5J2BPnc3dYc5VJxHCSF1yNMxTV5LQ7GuKteQXZtspjFbiuW5/dOj7H4Yw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/sunos-x64/-/sunos-x64-0.27.7.tgz",
+      "integrity": "sha512-ikktIhFBzQNt/QDyOL580ti9+5mL/YZeUPKU2ivGtGjdTYoqz6jObj6nOMfhASpS4GU4Q/Clh1QtxWAvcYKamA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/win32-arm64/-/win32-arm64-0.27.7.tgz",
+      "integrity": "sha512-7yRhbHvPqSpRUV7Q20VuDwbjW5kIMwTHpptuUzV+AA46kiPze5Z7qgt6CLCK3pWFrHeNfDd1VKgyP4O+ng17CA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/win32-ia32/-/win32-ia32-0.27.7.tgz",
+      "integrity": "sha512-SmwKXe6VHIyZYbBLJrhOoCJRB/Z1tckzmgTLfFYOfpMAx63BJEaL9ExI8x7v0oAO3Zh6D/Oi1gVxEYr5oUCFhw==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/@esbuild/win32-x64/-/win32-x64-0.27.7.tgz",
+      "integrity": "sha512-56hiAJPhwQ1R4i+21FVF7V8kSD5zZTdHcVuRFMW0hn753vVfQN8xlx4uOPT4xoGH0Z/oVATuR82AiqSTDIpaHg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@jridgewell/sourcemap-codec": {
+      "version": "1.5.5",
+      "resolved": "https://registry.npmmirror.com/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz",
+      "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@napi-rs/wasm-runtime": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmmirror.com/@napi-rs/wasm-runtime/-/wasm-runtime-1.1.4.tgz",
+      "integrity": "sha512-3NQNNgA1YSlJb/kMH1ildASP9HW7/7kYnRI2szWJaofaS1hWmbGI4H+d3+22aGzXXN9IJ+n+GiFVcGipJP18ow==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@tybys/wasm-util": "^0.10.1"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/Brooooooklyn"
+      },
+      "peerDependencies": {
+        "@emnapi/core": "^1.7.1",
+        "@emnapi/runtime": "^1.7.1"
+      }
+    },
+    "node_modules/@oxc-project/types": {
+      "version": "0.124.0",
+      "resolved": "https://registry.npmmirror.com/@oxc-project/types/-/types-0.124.0.tgz",
+      "integrity": "sha512-VBFWMTBvHxS11Z5Lvlr3IWgrwhMTXV+Md+EQF0Xf60+wAdsGFTBx7X7K/hP4pi8N7dcm1RvcHwDxZ16Qx8keUg==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/Boshen"
+      }
+    },
+    "node_modules/@rolldown/binding-android-arm64": {
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmmirror.com/@rolldown/binding-android-arm64/-/binding-android-arm64-1.0.0-rc.15.tgz",
+      "integrity": "sha512-YYe6aWruPZDtHNpwu7+qAHEMbQ/yRl6atqb/AhznLTnD3UY99Q1jE7ihLSahNWkF4EqRPVC4SiR4O0UkLK02tA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-darwin-arm64": {
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmmirror.com/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.0.0-rc.15.tgz",
+      "integrity": "sha512-oArR/ig8wNTPYsXL+Mzhs0oxhxfuHRfG7Ikw7jXsw8mYOtk71W0OkF2VEVh699pdmzjPQsTjlD1JIOoHkLP1Fg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-darwin-x64": {
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmmirror.com/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.0.0-rc.15.tgz",
+      "integrity": "sha512-YzeVqOqjPYvUbJSWJ4EDL8ahbmsIXQpgL3JVipmN+MX0XnXMeWomLN3Fb+nwCmP/jfyqte5I3XRSm7OfQrbyxw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-freebsd-x64": {
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmmirror.com/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.0.0-rc.15.tgz",
+      "integrity": "sha512-9Erhx956jeQ0nNTyif1+QWAXDRD38ZNjr//bSHrt6wDwB+QkAfl2q6Mn1k6OBPerznjRmbM10lgRb1Pli4xZPw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-arm-gnueabihf": {
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmmirror.com/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.0.0-rc.15.tgz",
+      "integrity": "sha512-cVwk0w8QbZJGTnP/AHQBs5yNwmpgGYStL88t4UIaqcvYJWBfS0s3oqVLZPwsPU6M0zlW4GqjP0Zq5MnAGwFeGA==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-arm64-gnu": {
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmmirror.com/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.0.0-rc.15.tgz",
+      "integrity": "sha512-eBZ/u8iAK9SoHGanqe/jrPnY0JvBN6iXbVOsbO38mbz+ZJsaobExAm1Iu+rxa4S1l2FjG0qEZn4Rc6X8n+9M+w==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-arm64-musl": {
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmmirror.com/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.0.0-rc.15.tgz",
+      "integrity": "sha512-ZvRYMGrAklV9PEkgt4LQM6MjQX2P58HPAuecwYObY2DhS2t35R0I810bKi0wmaYORt6m/2Sm+Z+nFgb0WhXNcQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-ppc64-gnu": {
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmmirror.com/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.0.0-rc.15.tgz",
+      "integrity": "sha512-VDpgGBzgfg5hLg+uBpCLoFG5kVvEyafmfxGUV0UHLcL5irxAK7PKNeC2MwClgk6ZAiNhmo9FLhRYgvMmedLtnQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-s390x-gnu": {
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmmirror.com/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.0.0-rc.15.tgz",
+      "integrity": "sha512-y1uXY3qQWCzcPgRJATPSOUP4tCemh4uBdY7e3EZbVwCJTY3gLJWnQABgeUetvED+bt1FQ01OeZwvhLS2bpNrAQ==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-x64-gnu": {
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmmirror.com/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.0.0-rc.15.tgz",
+      "integrity": "sha512-023bTPBod7J3Y/4fzAN6QtpkSABR0rigtrwaP+qSEabUh5zf6ELr9Nc7GujaROuPY3uwdSIXWrvhn1KxOvurWA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-x64-musl": {
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmmirror.com/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.0.0-rc.15.tgz",
+      "integrity": "sha512-witB2O0/hU4CgfOOKUoeFgQ4GktPi1eEbAhaLAIpgD6+ZnhcPkUtPsoKKHRzmOoWPZue46IThdSgdo4XneOLYw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-openharmony-arm64": {
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmmirror.com/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.0.0-rc.15.tgz",
+      "integrity": "sha512-UCL68NJ0Ud5zRipXZE9dF5PmirzJE4E4BCIOOssEnM7wLDsxjc6Qb0sGDxTNRTP53I6MZpygyCpY8Aa8sPfKPg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-wasm32-wasi": {
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmmirror.com/@rolldown/binding-wasm32-wasi/-/binding-wasm32-wasi-1.0.0-rc.15.tgz",
+      "integrity": "sha512-ApLruZq/ig+nhaE7OJm4lDjayUnOHVUa77zGeqnqZ9pn0ovdVbbNPerVibLXDmWeUZXjIYIT8V3xkT58Rm9u5Q==",
+      "cpu": [
+        "wasm32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@emnapi/core": "1.9.2",
+        "@emnapi/runtime": "1.9.2",
+        "@napi-rs/wasm-runtime": "^1.1.3"
+      },
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
+    "node_modules/@rolldown/binding-win32-arm64-msvc": {
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmmirror.com/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.0.0-rc.15.tgz",
+      "integrity": "sha512-KmoUoU7HnN+Si5YWJigfTws1jz1bKBYDQKdbLspz0UaqjjFkddHsqorgiW1mxcAj88lYUE6NC/zJNwT+SloqtA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-win32-x64-msvc": {
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmmirror.com/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.0.0-rc.15.tgz",
+      "integrity": "sha512-3P2A8L+x75qavWLe/Dll3EYBJLQmtkJN8rfh+U/eR3MqMgL/h98PhYI+JFfXuDPgPeCB7iZAKiqii5vqOvnA0g==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/pluginutils": {
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmmirror.com/@rolldown/pluginutils/-/pluginutils-1.0.0-rc.15.tgz",
+      "integrity": "sha512-UromN0peaE53IaBRe9W7CjrZgXl90fqGpK+mIZbA3qSTeYqg3pqpROBdIPvOG3F5ereDHNwoHBI2e50n1BDr1g==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@standard-schema/spec": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmmirror.com/@standard-schema/spec/-/spec-1.1.0.tgz",
+      "integrity": "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@tybys/wasm-util": {
+      "version": "0.10.1",
+      "resolved": "https://registry.npmmirror.com/@tybys/wasm-util/-/wasm-util-0.10.1.tgz",
+      "integrity": "sha512-9tTaPJLSiejZKx+Bmog4uSubteqTvFrVrURwkmHixBo0G4seD0zUxp98E1DzUBJxLQ3NPwXrGKDiVjwx/DpPsg==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@types/chai": {
+      "version": "5.2.3",
+      "resolved": "https://registry.npmmirror.com/@types/chai/-/chai-5.2.3.tgz",
+      "integrity": "sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/deep-eql": "*",
+        "assertion-error": "^2.0.1"
+      }
+    },
+    "node_modules/@types/deep-eql": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmmirror.com/@types/deep-eql/-/deep-eql-4.0.2.tgz",
+      "integrity": "sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/estree": {
+      "version": "1.0.8",
+      "resolved": "https://registry.npmmirror.com/@types/estree/-/estree-1.0.8.tgz",
+      "integrity": "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/node": {
+      "version": "20.19.39",
+      "resolved": "https://registry.npmmirror.com/@types/node/-/node-20.19.39.tgz",
+      "integrity": "sha512-orrrD74MBUyK8jOAD/r0+lfa1I2MO6I+vAkmAWzMYbCcgrN4lCrmK52gRFQq/JRxfYPfonkr4b0jcY7Olqdqbw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~6.21.0"
+      }
+    },
+    "node_modules/@types/react": {
+      "version": "19.2.14",
+      "resolved": "https://registry.npmmirror.com/@types/react/-/react-19.2.14.tgz",
+      "integrity": "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w==",
+      "devOptional": true,
+      "license": "MIT",
+      "dependencies": {
+        "csstype": "^3.2.2"
+      }
+    },
+    "node_modules/@vitest/expect": {
+      "version": "4.1.4",
+      "resolved": "https://registry.npmmirror.com/@vitest/expect/-/expect-4.1.4.tgz",
+      "integrity": "sha512-iPBpra+VDuXmBFI3FMKHSFXp3Gx5HfmSCE8X67Dn+bwephCnQCaB7qWK2ldHa+8ncN8hJU8VTMcxjPpyMkUjww==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@standard-schema/spec": "^1.1.0",
+        "@types/chai": "^5.2.2",
+        "@vitest/spy": "4.1.4",
+        "@vitest/utils": "4.1.4",
+        "chai": "^6.2.2",
+        "tinyrainbow": "^3.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/mocker": {
+      "version": "4.1.4",
+      "resolved": "https://registry.npmmirror.com/@vitest/mocker/-/mocker-4.1.4.tgz",
+      "integrity": "sha512-R9HTZBhW6yCSGbGQnDnH3QHfJxokKN4KB+Yvk9Q1le7eQNYwiCyKxmLmurSpFy6BzJanSLuEUDrD+j97Q+ZLPg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/spy": "4.1.4",
+        "estree-walker": "^3.0.3",
+        "magic-string": "^0.30.21"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "msw": "^2.4.9",
+        "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "msw": {
+          "optional": true
+        },
+        "vite": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@vitest/pretty-format": {
+      "version": "4.1.4",
+      "resolved": "https://registry.npmmirror.com/@vitest/pretty-format/-/pretty-format-4.1.4.tgz",
+      "integrity": "sha512-ddmDHU0gjEUyEVLxtZa7xamrpIefdEETu3nZjWtHeZX4QxqJ7tRxSteHVXJOcr8jhiLoGAhkK4WJ3WqBpjx42A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tinyrainbow": "^3.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/runner": {
+      "version": "4.1.4",
+      "resolved": "https://registry.npmmirror.com/@vitest/runner/-/runner-4.1.4.tgz",
+      "integrity": "sha512-xTp7VZ5aXP5ZJrn15UtJUWlx6qXLnGtF6jNxHepdPHpMfz/aVPx+htHtgcAL2mDXJgKhpoo2e9/hVJsIeFbytQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/utils": "4.1.4",
+        "pathe": "^2.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/snapshot": {
+      "version": "4.1.4",
+      "resolved": "https://registry.npmmirror.com/@vitest/snapshot/-/snapshot-4.1.4.tgz",
+      "integrity": "sha512-MCjCFgaS8aZz+m5nTcEcgk/xhWv0rEH4Yl53PPlMXOZ1/Ka2VcZU6CJ+MgYCZbcJvzGhQRjVrGQNZqkGPttIKw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "4.1.4",
+        "@vitest/utils": "4.1.4",
+        "magic-string": "^0.30.21",
+        "pathe": "^2.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/spy": {
+      "version": "4.1.4",
+      "resolved": "https://registry.npmmirror.com/@vitest/spy/-/spy-4.1.4.tgz",
+      "integrity": "sha512-XxNdAsKW7C+FLydqFJLb5KhJtl3PGCMmYwFRfhvIgxJvLSXhhVI1zM8f1qD3Zg7RCjTSzDVyct6sghs9UEgBEQ==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/utils": {
+      "version": "4.1.4",
+      "resolved": "https://registry.npmmirror.com/@vitest/utils/-/utils-4.1.4.tgz",
+      "integrity": "sha512-13QMT+eysM5uVGa1rG4kegGYNp6cnQcsTc67ELFbhNLQO+vgsygtYJx2khvdt4gVQqSSpC/KT5FZZxUpP3Oatw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "4.1.4",
+        "convert-source-map": "^2.0.0",
+        "tinyrainbow": "^3.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/ansi-escapes": {
+      "version": "7.3.0",
+      "resolved": "https://registry.npmmirror.com/ansi-escapes/-/ansi-escapes-7.3.0.tgz",
+      "integrity": "sha512-BvU8nYgGQBxcmMuEeUEmNTvrMVjJNSH7RgW24vXexN4Ven6qCvy4TntnvlnwnMLTVlcRQQdbRY8NKnaIoeWDNg==",
+      "license": "MIT",
+      "dependencies": {
+        "environment": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/ansi-regex": {
+      "version": "6.2.2",
+      "resolved": "https://registry.npmmirror.com/ansi-regex/-/ansi-regex-6.2.2.tgz",
+      "integrity": "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-regex?sponsor=1"
+      }
+    },
+    "node_modules/ansi-styles": {
+      "version": "6.2.3",
+      "resolved": "https://registry.npmmirror.com/ansi-styles/-/ansi-styles-6.2.3.tgz",
+      "integrity": "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
+    "node_modules/assertion-error": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmmirror.com/assertion-error/-/assertion-error-2.0.1.tgz",
+      "integrity": "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/auto-bind": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmmirror.com/auto-bind/-/auto-bind-5.0.1.tgz",
+      "integrity": "sha512-ooviqdwwgfIfNmDwo94wlshcdzfO64XV0Cg6oDsDYBJfITDz1EngD2z7DkbvCWn+XIMsIqW27sEVF6qcpJrRcg==",
+      "license": "MIT",
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/chai": {
+      "version": "6.2.2",
+      "resolved": "https://registry.npmmirror.com/chai/-/chai-6.2.2.tgz",
+      "integrity": "sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/chalk": {
+      "version": "5.6.2",
+      "resolved": "https://registry.npmmirror.com/chalk/-/chalk-5.6.2.tgz",
+      "integrity": "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==",
+      "license": "MIT",
+      "engines": {
+        "node": "^12.17.0 || ^14.13 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/chalk?sponsor=1"
+      }
+    },
+    "node_modules/cli-boxes": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmmirror.com/cli-boxes/-/cli-boxes-3.0.0.tgz",
+      "integrity": "sha512-/lzGpEWL/8PfI0BmBOPRwp0c/wFNX1RdUML3jK/RcSBA9T8mZDdQpqYBKtCFTOfQbwPqWEOpjqW+Fnayc0969g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/cli-cursor": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmmirror.com/cli-cursor/-/cli-cursor-4.0.0.tgz",
+      "integrity": "sha512-VGtlMu3x/4DOtIUwEkRezxUZ2lBacNJCHash0N0WeZDBS+7Ux1dm3XWAgWYxLJFMMdOeXMHXorshEFhbMSGelg==",
+      "license": "MIT",
+      "dependencies": {
+        "restore-cursor": "^4.0.0"
+      },
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/cli-truncate": {
+      "version": "5.2.0",
+      "resolved": "https://registry.npmmirror.com/cli-truncate/-/cli-truncate-5.2.0.tgz",
+      "integrity": "sha512-xRwvIOMGrfOAnM1JYtqQImuaNtDEv9v6oIYAs4LIHwTiKee8uwvIi363igssOC0O5U04i4AlENs79LQLu9tEMw==",
+      "license": "MIT",
+      "dependencies": {
+        "slice-ansi": "^8.0.0",
+        "string-width": "^8.2.0"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/code-excerpt": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmmirror.com/code-excerpt/-/code-excerpt-4.0.0.tgz",
+      "integrity": "sha512-xxodCmBen3iy2i0WtAK8FlFNrRzjUqjRsMfho58xT/wvZU1YTM3fCnRjcy1gJPMepaRlgm/0e6w8SpWHpn3/cA==",
+      "license": "MIT",
+      "dependencies": {
+        "convert-to-spaces": "^2.0.1"
+      },
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      }
+    },
+    "node_modules/convert-source-map": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmmirror.com/convert-source-map/-/convert-source-map-2.0.0.tgz",
+      "integrity": "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/convert-to-spaces": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmmirror.com/convert-to-spaces/-/convert-to-spaces-2.0.1.tgz",
+      "integrity": "sha512-rcQ1bsQO9799wq24uE5AM2tAILy4gXGIK/njFWcVQkGNZ96edlpY+A7bjwvzjYvLDyzmG1MmMLZhpcsb+klNMQ==",
+      "license": "MIT",
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      }
+    },
+    "node_modules/csstype": {
+      "version": "3.2.3",
+      "resolved": "https://registry.npmmirror.com/csstype/-/csstype-3.2.3.tgz",
+      "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==",
+      "devOptional": true,
+      "license": "MIT"
+    },
+    "node_modules/detect-libc": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmmirror.com/detect-libc/-/detect-libc-2.1.2.tgz",
+      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/emoji-regex": {
+      "version": "10.6.0",
+      "resolved": "https://registry.npmmirror.com/emoji-regex/-/emoji-regex-10.6.0.tgz",
+      "integrity": "sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==",
+      "license": "MIT"
+    },
+    "node_modules/environment": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmmirror.com/environment/-/environment-1.1.0.tgz",
+      "integrity": "sha512-xUtoPkMggbz0MPyPiIWr1Kp4aeWJjDZ6SMvURhimjdZgsRuDplF5/s9hcgGhyXMhs+6vpnuoiZ2kFiu3FMnS8Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/es-module-lexer": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmmirror.com/es-module-lexer/-/es-module-lexer-2.0.0.tgz",
+      "integrity": "sha512-5POEcUuZybH7IdmGsD8wlf0AI55wMecM9rVBTI/qEAy2c1kTOm3DjFYjrBdI2K3BaJjJYfYFeRtM0t9ssnRuxw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/es-toolkit": {
+      "version": "1.45.1",
+      "resolved": "https://registry.npmmirror.com/es-toolkit/-/es-toolkit-1.45.1.tgz",
+      "integrity": "sha512-/jhoOj/Fx+A+IIyDNOvO3TItGmlMKhtX8ISAHKE90c4b/k1tqaqEZ+uUqfpU8DMnW5cgNJv606zS55jGvza0Xw==",
+      "license": "MIT",
+      "workspaces": [
+        "docs",
+        "benchmarks"
+      ]
+    },
+    "node_modules/esbuild": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmmirror.com/esbuild/-/esbuild-0.27.7.tgz",
+      "integrity": "sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.27.7",
+        "@esbuild/android-arm": "0.27.7",
+        "@esbuild/android-arm64": "0.27.7",
+        "@esbuild/android-x64": "0.27.7",
+        "@esbuild/darwin-arm64": "0.27.7",
+        "@esbuild/darwin-x64": "0.27.7",
+        "@esbuild/freebsd-arm64": "0.27.7",
+        "@esbuild/freebsd-x64": "0.27.7",
+        "@esbuild/linux-arm": "0.27.7",
+        "@esbuild/linux-arm64": "0.27.7",
+        "@esbuild/linux-ia32": "0.27.7",
+        "@esbuild/linux-loong64": "0.27.7",
+        "@esbuild/linux-mips64el": "0.27.7",
+        "@esbuild/linux-ppc64": "0.27.7",
+        "@esbuild/linux-riscv64": "0.27.7",
+        "@esbuild/linux-s390x": "0.27.7",
+        "@esbuild/linux-x64": "0.27.7",
+        "@esbuild/netbsd-arm64": "0.27.7",
+        "@esbuild/netbsd-x64": "0.27.7",
+        "@esbuild/openbsd-arm64": "0.27.7",
+        "@esbuild/openbsd-x64": "0.27.7",
+        "@esbuild/openharmony-arm64": "0.27.7",
+        "@esbuild/sunos-x64": "0.27.7",
+        "@esbuild/win32-arm64": "0.27.7",
+        "@esbuild/win32-ia32": "0.27.7",
+        "@esbuild/win32-x64": "0.27.7"
+      }
+    },
+    "node_modules/escape-string-regexp": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmmirror.com/escape-string-regexp/-/escape-string-regexp-2.0.0.tgz",
+      "integrity": "sha512-UpzcLCXolUWcNu5HtVMHYdXJjArjsF9C0aNnquZYY4uW/Vu0miy5YoWvbV345HauVvcAUnpRuhMMcqTcGOY2+w==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/estree-walker": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmmirror.com/estree-walker/-/estree-walker-3.0.3.tgz",
+      "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0"
+      }
+    },
+    "node_modules/expect-type": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmmirror.com/expect-type/-/expect-type-1.3.0.tgz",
+      "integrity": "sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
+    "node_modules/fdir": {
+      "version": "6.5.0",
+      "resolved": "https://registry.npmmirror.com/fdir/-/fdir-6.5.0.tgz",
+      "integrity": "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "peerDependencies": {
+        "picomatch": "^3 || ^4"
+      },
+      "peerDependenciesMeta": {
+        "picomatch": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmmirror.com/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/get-east-asian-width": {
+      "version": "1.5.0",
+      "resolved": "https://registry.npmmirror.com/get-east-asian-width/-/get-east-asian-width-1.5.0.tgz",
+      "integrity": "sha512-CQ+bEO+Tva/qlmw24dCejulK5pMzVnUOFOijVogd3KQs07HnRIgp8TGipvCCRT06xeYEbpbgwaCxglFyiuIcmA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/get-tsconfig": {
+      "version": "4.14.0",
+      "resolved": "https://registry.npmmirror.com/get-tsconfig/-/get-tsconfig-4.14.0.tgz",
+      "integrity": "sha512-yTb+8DXzDREzgvYmh6s9vHsSVCHeC0G3PI5bEXNBHtmshPnO+S5O7qgLEOn0I5QvMy6kpZN8K1NKGyilLb93wA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "resolve-pkg-maps": "^1.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/privatenumber/get-tsconfig?sponsor=1"
+      }
+    },
+    "node_modules/indent-string": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmmirror.com/indent-string/-/indent-string-5.0.0.tgz",
+      "integrity": "sha512-m6FAo/spmsW2Ab2fU35JTYwtOKa2yAwXSwgjSv1TJzh4Mh7mC3lzAOVLBprb72XsTrgkEIsl7YrFNAiDiRhIGg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/ink": {
+      "version": "6.8.0",
+      "resolved": "https://registry.npmmirror.com/ink/-/ink-6.8.0.tgz",
+      "integrity": "sha512-sbl1RdLOgkO9isK42WCZlJCFN9hb++sX9dsklOvfd1YQ3bQ2AiFu12Q6tFlr0HvEUvzraJntQCCpfEoUe9DSzA==",
+      "license": "MIT",
+      "dependencies": {
+        "@alcalzone/ansi-tokenize": "^0.2.4",
+        "ansi-escapes": "^7.3.0",
+        "ansi-styles": "^6.2.1",
+        "auto-bind": "^5.0.1",
+        "chalk": "^5.6.0",
+        "cli-boxes": "^3.0.0",
+        "cli-cursor": "^4.0.0",
+        "cli-truncate": "^5.1.1",
+        "code-excerpt": "^4.0.0",
+        "es-toolkit": "^1.39.10",
+        "indent-string": "^5.0.0",
+        "is-in-ci": "^2.0.0",
+        "patch-console": "^2.0.0",
+        "react-reconciler": "^0.33.0",
+        "scheduler": "^0.27.0",
+        "signal-exit": "^3.0.7",
+        "slice-ansi": "^8.0.0",
+        "stack-utils": "^2.0.6",
+        "string-width": "^8.1.1",
+        "terminal-size": "^4.0.1",
+        "type-fest": "^5.4.1",
+        "widest-line": "^6.0.0",
+        "wrap-ansi": "^9.0.0",
+        "ws": "^8.18.0",
+        "yoga-layout": "~3.2.1"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "peerDependencies": {
+        "@types/react": ">=19.0.0",
+        "react": ">=19.0.0",
+        "react-devtools-core": ">=6.1.2"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        },
+        "react-devtools-core": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/is-fullwidth-code-point": {
+      "version": "5.1.0",
+      "resolved": "https://registry.npmmirror.com/is-fullwidth-code-point/-/is-fullwidth-code-point-5.1.0.tgz",
+      "integrity": "sha512-5XHYaSyiqADb4RnZ1Bdad6cPp8Toise4TzEjcOYDHZkTCbKgiUl7WTUCpNWHuxmDt91wnsZBc9xinNzopv3JMQ==",
+      "license": "MIT",
+      "dependencies": {
+        "get-east-asian-width": "^1.3.1"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/is-in-ci": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmmirror.com/is-in-ci/-/is-in-ci-2.0.0.tgz",
+      "integrity": "sha512-cFeerHriAnhrQSbpAxL37W1wcJKUUX07HyLWZCW1URJT/ra3GyUTzBgUnh24TMVfNTV2Hij2HLxkPHFZfOZy5w==",
+      "license": "MIT",
+      "bin": {
+        "is-in-ci": "cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/lightningcss": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmmirror.com/lightningcss/-/lightningcss-1.32.0.tgz",
+      "integrity": "sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ==",
+      "dev": true,
+      "license": "MPL-2.0",
+      "dependencies": {
+        "detect-libc": "^2.0.3"
+      },
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      },
+      "optionalDependencies": {
+        "lightningcss-android-arm64": "1.32.0",
+        "lightningcss-darwin-arm64": "1.32.0",
+        "lightningcss-darwin-x64": "1.32.0",
+        "lightningcss-freebsd-x64": "1.32.0",
+        "lightningcss-linux-arm-gnueabihf": "1.32.0",
+        "lightningcss-linux-arm64-gnu": "1.32.0",
+        "lightningcss-linux-arm64-musl": "1.32.0",
+        "lightningcss-linux-x64-gnu": "1.32.0",
+        "lightningcss-linux-x64-musl": "1.32.0",
+        "lightningcss-win32-arm64-msvc": "1.32.0",
+        "lightningcss-win32-x64-msvc": "1.32.0"
+      }
+    },
+    "node_modules/lightningcss-android-arm64": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmmirror.com/lightningcss-android-arm64/-/lightningcss-android-arm64-1.32.0.tgz",
+      "integrity": "sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-darwin-arm64": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmmirror.com/lightningcss-darwin-arm64/-/lightningcss-darwin-arm64-1.32.0.tgz",
+      "integrity": "sha512-RzeG9Ju5bag2Bv1/lwlVJvBE3q6TtXskdZLLCyfg5pt+HLz9BqlICO7LZM7VHNTTn/5PRhHFBSjk5lc4cmscPQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-darwin-x64": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmmirror.com/lightningcss-darwin-x64/-/lightningcss-darwin-x64-1.32.0.tgz",
+      "integrity": "sha512-U+QsBp2m/s2wqpUYT/6wnlagdZbtZdndSmut/NJqlCcMLTWp5muCrID+K5UJ6jqD2BFshejCYXniPDbNh73V8w==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-freebsd-x64": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmmirror.com/lightningcss-freebsd-x64/-/lightningcss-freebsd-x64-1.32.0.tgz",
+      "integrity": "sha512-JCTigedEksZk3tHTTthnMdVfGf61Fky8Ji2E4YjUTEQX14xiy/lTzXnu1vwiZe3bYe0q+SpsSH/CTeDXK6WHig==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-arm-gnueabihf": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmmirror.com/lightningcss-linux-arm-gnueabihf/-/lightningcss-linux-arm-gnueabihf-1.32.0.tgz",
+      "integrity": "sha512-x6rnnpRa2GL0zQOkt6rts3YDPzduLpWvwAF6EMhXFVZXD4tPrBkEFqzGowzCsIWsPjqSK+tyNEODUBXeeVHSkw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-arm64-gnu": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmmirror.com/lightningcss-linux-arm64-gnu/-/lightningcss-linux-arm64-gnu-1.32.0.tgz",
+      "integrity": "sha512-0nnMyoyOLRJXfbMOilaSRcLH3Jw5z9HDNGfT/gwCPgaDjnx0i8w7vBzFLFR1f6CMLKF8gVbebmkUN3fa/kQJpQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-arm64-musl": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmmirror.com/lightningcss-linux-arm64-musl/-/lightningcss-linux-arm64-musl-1.32.0.tgz",
+      "integrity": "sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-x64-gnu": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmmirror.com/lightningcss-linux-x64-gnu/-/lightningcss-linux-x64-gnu-1.32.0.tgz",
+      "integrity": "sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-x64-musl": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmmirror.com/lightningcss-linux-x64-musl/-/lightningcss-linux-x64-musl-1.32.0.tgz",
+      "integrity": "sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-win32-arm64-msvc": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmmirror.com/lightningcss-win32-arm64-msvc/-/lightningcss-win32-arm64-msvc-1.32.0.tgz",
+      "integrity": "sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-win32-x64-msvc": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmmirror.com/lightningcss-win32-x64-msvc/-/lightningcss-win32-x64-msvc-1.32.0.tgz",
+      "integrity": "sha512-Amq9B/SoZYdDi1kFrojnoqPLxYhQ4Wo5XiL8EVJrVsB8ARoC1PWW6VGtT0WKCemjy8aC+louJnjS7U18x3b06Q==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/magic-string": {
+      "version": "0.30.21",
+      "resolved": "https://registry.npmmirror.com/magic-string/-/magic-string-0.30.21.tgz",
+      "integrity": "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/sourcemap-codec": "^1.5.5"
+      }
+    },
+    "node_modules/mimic-fn": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmmirror.com/mimic-fn/-/mimic-fn-2.1.0.tgz",
+      "integrity": "sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/nanoid": {
+      "version": "3.3.11",
+      "resolved": "https://registry.npmmirror.com/nanoid/-/nanoid-3.3.11.tgz",
+      "integrity": "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "bin": {
+        "nanoid": "bin/nanoid.cjs"
+      },
+      "engines": {
+        "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
+      }
+    },
+    "node_modules/obug": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmmirror.com/obug/-/obug-2.1.1.tgz",
+      "integrity": "sha512-uTqF9MuPraAQ+IsnPf366RG4cP9RtUi7MLO1N3KEc+wb0a6yKpeL0lmk2IB1jY5KHPAlTc6T/JRdC/YqxHNwkQ==",
+      "dev": true,
+      "funding": [
+        "https://github.com/sponsors/sxzz",
+        "https://opencollective.com/debug"
+      ],
+      "license": "MIT"
+    },
+    "node_modules/onetime": {
+      "version": "5.1.2",
+      "resolved": "https://registry.npmmirror.com/onetime/-/onetime-5.1.2.tgz",
+      "integrity": "sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg==",
+      "license": "MIT",
+      "dependencies": {
+        "mimic-fn": "^2.1.0"
+      },
+      "engines": {
+        "node": ">=6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/patch-console": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmmirror.com/patch-console/-/patch-console-2.0.0.tgz",
+      "integrity": "sha512-0YNdUceMdaQwoKce1gatDScmMo5pu/tfABfnzEqeG0gtTmd7mh/WcwgUjtAeOU7N8nFFlbQBnFK2gXW5fGvmMA==",
+      "license": "MIT",
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      }
+    },
+    "node_modules/pathe": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmmirror.com/pathe/-/pathe-2.0.3.tgz",
+      "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/picocolors": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmmirror.com/picocolors/-/picocolors-1.1.1.tgz",
+      "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/picomatch": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmmirror.com/picomatch/-/picomatch-4.0.4.tgz",
+      "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/jonschlinkert"
+      }
+    },
+    "node_modules/postcss": {
+      "version": "8.5.10",
+      "resolved": "https://registry.npmmirror.com/postcss/-/postcss-8.5.10.tgz",
+      "integrity": "sha512-pMMHxBOZKFU6HgAZ4eyGnwXF/EvPGGqUr0MnZ5+99485wwW41kW91A4LOGxSHhgugZmSChL5AlElNdwlNgcnLQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/postcss/"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/postcss"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "nanoid": "^3.3.11",
+        "picocolors": "^1.1.1",
+        "source-map-js": "^1.2.1"
+      },
+      "engines": {
+        "node": "^10 || ^12 || >=14"
+      }
+    },
+    "node_modules/react": {
+      "version": "19.2.5",
+      "resolved": "https://registry.npmmirror.com/react/-/react-19.2.5.tgz",
+      "integrity": "sha512-llUJLzz1zTUBrskt2pwZgLq59AemifIftw4aB7JxOqf1HY2FDaGDxgwpAPVzHU1kdWabH7FauP4i1oEeer2WCA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/react-reconciler": {
+      "version": "0.33.0",
+      "resolved": "https://registry.npmmirror.com/react-reconciler/-/react-reconciler-0.33.0.tgz",
+      "integrity": "sha512-KetWRytFv1epdpJc3J4G75I4WrplZE5jOL7Yq0p34+OVOKF4Se7WrdIdVC45XsSSmUTlht2FM/fM1FZb1mfQeA==",
+      "license": "MIT",
+      "dependencies": {
+        "scheduler": "^0.27.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      },
+      "peerDependencies": {
+        "react": "^19.2.0"
+      }
+    },
+    "node_modules/resolve-pkg-maps": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmmirror.com/resolve-pkg-maps/-/resolve-pkg-maps-1.0.0.tgz",
+      "integrity": "sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/privatenumber/resolve-pkg-maps?sponsor=1"
+      }
+    },
+    "node_modules/restore-cursor": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmmirror.com/restore-cursor/-/restore-cursor-4.0.0.tgz",
+      "integrity": "sha512-I9fPXU9geO9bHOt9pHHOhOkYerIMsmVaWB0rA2AI9ERh/+x/i7MV5HKBNrg+ljO5eoPVgCcnFuRjJ9uH6I/3eg==",
+      "license": "MIT",
+      "dependencies": {
+        "onetime": "^5.1.0",
+        "signal-exit": "^3.0.2"
+      },
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/rolldown": {
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmmirror.com/rolldown/-/rolldown-1.0.0-rc.15.tgz",
+      "integrity": "sha512-Ff31guA5zT6WjnGp0SXw76X6hzGRk/OQq2hE+1lcDe+lJdHSgnSX6nK3erbONHyCbpSj9a9E+uX/OvytZoWp2g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@oxc-project/types": "=0.124.0",
+        "@rolldown/pluginutils": "1.0.0-rc.15"
+      },
+      "bin": {
+        "rolldown": "bin/cli.mjs"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      },
+      "optionalDependencies": {
+        "@rolldown/binding-android-arm64": "1.0.0-rc.15",
+        "@rolldown/binding-darwin-arm64": "1.0.0-rc.15",
+        "@rolldown/binding-darwin-x64": "1.0.0-rc.15",
+        "@rolldown/binding-freebsd-x64": "1.0.0-rc.15",
+        "@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.15",
+        "@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.15",
+        "@rolldown/binding-linux-arm64-musl": "1.0.0-rc.15",
+        "@rolldown/binding-linux-ppc64-gnu": "1.0.0-rc.15",
+        "@rolldown/binding-linux-s390x-gnu": "1.0.0-rc.15",
+        "@rolldown/binding-linux-x64-gnu": "1.0.0-rc.15",
+        "@rolldown/binding-linux-x64-musl": "1.0.0-rc.15",
+        "@rolldown/binding-openharmony-arm64": "1.0.0-rc.15",
+        "@rolldown/binding-wasm32-wasi": "1.0.0-rc.15",
+        "@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.15",
+        "@rolldown/binding-win32-x64-msvc": "1.0.0-rc.15"
+      }
+    },
+    "node_modules/scheduler": {
+      "version": "0.27.0",
+      "resolved": "https://registry.npmmirror.com/scheduler/-/scheduler-0.27.0.tgz",
+      "integrity": "sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==",
+      "license": "MIT"
+    },
+    "node_modules/siginfo": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmmirror.com/siginfo/-/siginfo-2.0.0.tgz",
+      "integrity": "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/signal-exit": {
+      "version": "3.0.7",
+      "resolved": "https://registry.npmmirror.com/signal-exit/-/signal-exit-3.0.7.tgz",
+      "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==",
+      "license": "ISC"
+    },
+    "node_modules/slice-ansi": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmmirror.com/slice-ansi/-/slice-ansi-8.0.0.tgz",
+      "integrity": "sha512-stxByr12oeeOyY2BlviTNQlYV5xOj47GirPr4yA1hE9JCtxfQN0+tVbkxwCtYDQWhEKWFHsEK48ORg5jrouCAg==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^6.2.3",
+        "is-fullwidth-code-point": "^5.1.0"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/slice-ansi?sponsor=1"
+      }
+    },
+    "node_modules/source-map-js": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmmirror.com/source-map-js/-/source-map-js-1.2.1.tgz",
+      "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/stack-utils": {
+      "version": "2.0.6",
+      "resolved": "https://registry.npmmirror.com/stack-utils/-/stack-utils-2.0.6.tgz",
+      "integrity": "sha512-XlkWvfIm6RmsWtNJx+uqtKLS8eqFbxUg0ZzLXqY0caEy9l7hruX8IpiDnjsLavoBgqCCR71TqWO8MaXYheJ3RQ==",
+      "license": "MIT",
+      "dependencies": {
+        "escape-string-regexp": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/stackback": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmmirror.com/stackback/-/stackback-0.0.2.tgz",
+      "integrity": "sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/std-env": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmmirror.com/std-env/-/std-env-4.1.0.tgz",
+      "integrity": "sha512-Rq7ybcX2RuC55r9oaPVEW7/xu3tj8u4GeBYHBWCychFtzMIr86A7e3PPEBPT37sHStKX3+TiX/Fr/ACmJLVlLQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/string-width": {
+      "version": "8.2.0",
+      "resolved": "https://registry.npmmirror.com/string-width/-/string-width-8.2.0.tgz",
+      "integrity": "sha512-6hJPQ8N0V0P3SNmP6h2J99RLuzrWz2gvT7VnK5tKvrNqJoyS9W4/Fb8mo31UiPvy00z7DQXkP2hnKBVav76thw==",
+      "license": "MIT",
+      "dependencies": {
+        "get-east-asian-width": "^1.5.0",
+        "strip-ansi": "^7.1.2"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/strip-ansi": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmmirror.com/strip-ansi/-/strip-ansi-7.2.0.tgz",
+      "integrity": "sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^6.2.2"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/strip-ansi?sponsor=1"
+      }
+    },
+    "node_modules/tagged-tag": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmmirror.com/tagged-tag/-/tagged-tag-1.0.0.tgz",
+      "integrity": "sha512-yEFYrVhod+hdNyx7g5Bnkkb0G6si8HJurOoOEgC8B/O0uXLHlaey/65KRv6cuWBNhBgHKAROVpc7QyYqE5gFng==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/terminal-size": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmmirror.com/terminal-size/-/terminal-size-4.0.1.tgz",
+      "integrity": "sha512-avMLDQpUI9I5XFrklECw1ZEUPJhqzcwSWsyyI8blhRLT+8N1jLJWLWWYQpB2q2xthq8xDvjZPISVh53T/+CLYQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/tinybench": {
+      "version": "2.9.0",
+      "resolved": "https://registry.npmmirror.com/tinybench/-/tinybench-2.9.0.tgz",
+      "integrity": "sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/tinyexec": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmmirror.com/tinyexec/-/tinyexec-1.1.1.tgz",
+      "integrity": "sha512-VKS/ZaQhhkKFMANmAOhhXVoIfBXblQxGX1myCQ2faQrfmobMftXeJPcZGp0gS07ocvGJWDLZGyOZDadDBqYIJg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tinyglobby": {
+      "version": "0.2.16",
+      "resolved": "https://registry.npmmirror.com/tinyglobby/-/tinyglobby-0.2.16.tgz",
+      "integrity": "sha512-pn99VhoACYR8nFHhxqix+uvsbXineAasWm5ojXoN8xEwK5Kd3/TrhNn1wByuD52UxWRLy8pu+kRMniEi6Eq9Zg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fdir": "^6.5.0",
+        "picomatch": "^4.0.4"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/SuperchupuDev"
+      }
+    },
+    "node_modules/tinyrainbow": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmmirror.com/tinyrainbow/-/tinyrainbow-3.1.0.tgz",
+      "integrity": "sha512-Bf+ILmBgretUrdJxzXM0SgXLZ3XfiaUuOj/IKQHuTXip+05Xn+uyEYdVg0kYDipTBcLrCVyUzAPz7QmArb0mmw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
+    "node_modules/tslib": {
+      "version": "2.8.1",
+      "resolved": "https://registry.npmmirror.com/tslib/-/tslib-2.8.1.tgz",
+      "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
+      "dev": true,
+      "license": "0BSD",
+      "optional": true
+    },
+    "node_modules/tsx": {
+      "version": "4.21.0",
+      "resolved": "https://registry.npmmirror.com/tsx/-/tsx-4.21.0.tgz",
+      "integrity": "sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "~0.27.0",
+        "get-tsconfig": "^4.7.5"
+      },
+      "bin": {
+        "tsx": "dist/cli.mjs"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      }
+    },
+    "node_modules/type-fest": {
+      "version": "5.6.0",
+      "resolved": "https://registry.npmmirror.com/type-fest/-/type-fest-5.6.0.tgz",
+      "integrity": "sha512-8ZiHFm91orbSAe2PSAiSVBVko18pbhbiB3U9GglSzF/zCGkR+rxpHx6sEMCUm4kxY4LjDIUGgCfUMtwfZfjfUA==",
+      "license": "(MIT OR CC0-1.0)",
+      "dependencies": {
+        "tagged-tag": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmmirror.com/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "6.21.0",
+      "resolved": "https://registry.npmmirror.com/undici-types/-/undici-types-6.21.0.tgz",
+      "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/vite": {
+      "version": "8.0.8",
+      "resolved": "https://registry.npmmirror.com/vite/-/vite-8.0.8.tgz",
+      "integrity": "sha512-dbU7/iLVa8KZALJyLOBOQ88nOXtNG8vxKuOT4I2mD+Ya70KPceF4IAmDsmU0h1Qsn5bPrvsY9HJstCRh3hG6Uw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "lightningcss": "^1.32.0",
+        "picomatch": "^4.0.4",
+        "postcss": "^8.5.8",
+        "rolldown": "1.0.0-rc.15",
+        "tinyglobby": "^0.2.15"
+      },
+      "bin": {
+        "vite": "bin/vite.js"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      },
+      "funding": {
+        "url": "https://github.com/vitejs/vite?sponsor=1"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      },
+      "peerDependencies": {
+        "@types/node": "^20.19.0 || >=22.12.0",
+        "@vitejs/devtools": "^0.1.0",
+        "esbuild": "^0.27.0 || ^0.28.0",
+        "jiti": ">=1.21.0",
+        "less": "^4.0.0",
+        "sass": "^1.70.0",
+        "sass-embedded": "^1.70.0",
+        "stylus": ">=0.54.8",
+        "sugarss": "^5.0.0",
+        "terser": "^5.16.0",
+        "tsx": "^4.8.1",
+        "yaml": "^2.4.2"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        },
+        "@vitejs/devtools": {
+          "optional": true
+        },
+        "esbuild": {
+          "optional": true
+        },
+        "jiti": {
+          "optional": true
+        },
+        "less": {
+          "optional": true
+        },
+        "sass": {
+          "optional": true
+        },
+        "sass-embedded": {
+          "optional": true
+        },
+        "stylus": {
+          "optional": true
+        },
+        "sugarss": {
+          "optional": true
+        },
+        "terser": {
+          "optional": true
+        },
+        "tsx": {
+          "optional": true
+        },
+        "yaml": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/vitest": {
+      "version": "4.1.4",
+      "resolved": "https://registry.npmmirror.com/vitest/-/vitest-4.1.4.tgz",
+      "integrity": "sha512-tFuJqTxKb8AvfyqMfnavXdzfy3h3sWZRWwfluGbkeR7n0HUev+FmNgZ8SDrRBTVrVCjgH5cA21qGbCffMNtWvg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/expect": "4.1.4",
+        "@vitest/mocker": "4.1.4",
+        "@vitest/pretty-format": "4.1.4",
+        "@vitest/runner": "4.1.4",
+        "@vitest/snapshot": "4.1.4",
+        "@vitest/spy": "4.1.4",
+        "@vitest/utils": "4.1.4",
+        "es-module-lexer": "^2.0.0",
+        "expect-type": "^1.3.0",
+        "magic-string": "^0.30.21",
+        "obug": "^2.1.1",
+        "pathe": "^2.0.3",
+        "picomatch": "^4.0.3",
+        "std-env": "^4.0.0-rc.1",
+        "tinybench": "^2.9.0",
+        "tinyexec": "^1.0.2",
+        "tinyglobby": "^0.2.15",
+        "tinyrainbow": "^3.1.0",
+        "vite": "^6.0.0 || ^7.0.0 || ^8.0.0",
+        "why-is-node-running": "^2.3.0"
+      },
+      "bin": {
+        "vitest": "vitest.mjs"
+      },
+      "engines": {
+        "node": "^20.0.0 || ^22.0.0 || >=24.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "@edge-runtime/vm": "*",
+        "@opentelemetry/api": "^1.9.0",
+        "@types/node": "^20.0.0 || ^22.0.0 || >=24.0.0",
+        "@vitest/browser-playwright": "4.1.4",
+        "@vitest/browser-preview": "4.1.4",
+        "@vitest/browser-webdriverio": "4.1.4",
+        "@vitest/coverage-istanbul": "4.1.4",
+        "@vitest/coverage-v8": "4.1.4",
+        "@vitest/ui": "4.1.4",
+        "happy-dom": "*",
+        "jsdom": "*",
+        "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@edge-runtime/vm": {
+          "optional": true
+        },
+        "@opentelemetry/api": {
+          "optional": true
+        },
+        "@types/node": {
+          "optional": true
+        },
+        "@vitest/browser-playwright": {
+          "optional": true
+        },
+        "@vitest/browser-preview": {
+          "optional": true
+        },
+        "@vitest/browser-webdriverio": {
+          "optional": true
+        },
+        "@vitest/coverage-istanbul": {
+          "optional": true
+        },
+        "@vitest/coverage-v8": {
+          "optional": true
+        },
+        "@vitest/ui": {
+          "optional": true
+        },
+        "happy-dom": {
+          "optional": true
+        },
+        "jsdom": {
+          "optional": true
+        },
+        "vite": {
+          "optional": false
+        }
+      }
+    },
+    "node_modules/why-is-node-running": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmmirror.com/why-is-node-running/-/why-is-node-running-2.3.0.tgz",
+      "integrity": "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "siginfo": "^2.0.0",
+        "stackback": "0.0.2"
+      },
+      "bin": {
+        "why-is-node-running": "cli.js"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/widest-line": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmmirror.com/widest-line/-/widest-line-6.0.0.tgz",
+      "integrity": "sha512-U89AsyEeAsyoF0zVJBkG9zBgekjgjK7yk9sje3F4IQpXBJ10TF6ByLlIfjMhcmHMJgHZI4KHt4rdNfktzxIAMA==",
+      "license": "MIT",
+      "dependencies": {
+        "string-width": "^8.1.0"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/wrap-ansi": {
+      "version": "9.0.2",
+      "resolved": "https://registry.npmmirror.com/wrap-ansi/-/wrap-ansi-9.0.2.tgz",
+      "integrity": "sha512-42AtmgqjV+X1VpdOfyTGOYRi0/zsoLqtXQckTmqTeybT+BDIbM/Guxo7x3pE2vtpr1ok6xRqM9OpBe+Jyoqyww==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^6.2.1",
+        "string-width": "^7.0.0",
+        "strip-ansi": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+      }
+    },
+    "node_modules/wrap-ansi/node_modules/string-width": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmmirror.com/string-width/-/string-width-7.2.0.tgz",
+      "integrity": "sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==",
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^10.3.0",
+        "get-east-asian-width": "^1.0.0",
+        "strip-ansi": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/ws": {
+      "version": "8.20.0",
+      "resolved": "https://registry.npmmirror.com/ws/-/ws-8.20.0.tgz",
+      "integrity": "sha512-sAt8BhgNbzCtgGbt2OxmpuryO63ZoDk/sqaB/znQm94T4fCEsy/yV+7CdC1kJhOU9lboAEU7R3kquuycDoibVA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/yoga-layout": {
+      "version": "3.2.1",
+      "resolved": "https://registry.npmmirror.com/yoga-layout/-/yoga-layout-3.2.1.tgz",
+      "integrity": "sha512-0LPOt3AxKqMdFBZA3HBAt/t/8vIKq7VaQYbuA8WxCgung+p9TVyKRYdpvCb80HcdTN2NkbIKbhNwKUfm3tQywQ==",
+      "license": "MIT"
+    }
+  }
+}
diff --git a/coding-deepgent/frontend/cli/package.json b/coding-deepgent/frontend/cli/package.json
new file mode 100644
index 000000000..20ad9a232
--- /dev/null
+++ b/coding-deepgent/frontend/cli/package.json
@@ -0,0 +1,28 @@
+{
+  "name": "@coding-deepgent/cli-frontend",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "bin": {
+    "coding-deepgent-ui": "./src/index.tsx"
+  },
+  "scripts": {
+    "dev": "CODING_DEEPGENT_UI_WORKDIR=../.. PYTHONPATH=src tsx src/index.tsx",
+    "dev:fake": "CODING_DEEPGENT_UI_FAKE=1 CODING_DEEPGENT_UI_WORKDIR=../.. PYTHONPATH=src tsx src/index.tsx --fake",
+    "start": "npm run dev",
+    "start:fake": "npm run dev:fake",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "ink": "^6.8.0",
+    "react": "^19.2.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.25",
+    "@types/react": "^19.2.7",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15"
+  }
+}
diff --git a/coding-deepgent/frontend/cli/src/__tests__/protocol.test.ts b/coding-deepgent/frontend/cli/src/__tests__/protocol.test.ts
new file mode 100644
index 000000000..2c4a35ff5
--- /dev/null
+++ b/coding-deepgent/frontend/cli/src/__tests__/protocol.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import { encodeFrontendInput, parseFrontendEvent } from '../bridge/protocol.js';
+
+describe('frontend protocol', () => {
+  it('parses known frontend events', () => {
+    const event = parseFrontendEvent('{"type":"assistant_message","message_id":"a1","text":"hello"}');
+
+    expect(event.type).toBe('assistant_message');
+    if (event.type === 'assistant_message') {
+      expect(event.text).toBe('hello');
+    }
+  });
+
+  it('parses runtime visibility snapshot events', () => {
+    const event = parseFrontendEvent(
+      '{"type":"context_snapshot","projection_mode":"compact","history_messages":8,"model_messages":5,"visible_messages":4,"hidden_messages":4,"compact_count":1,"collapse_count":0,"session_memory_status":"stale","latest_event":"compact"}'
+    );
+
+    expect(event.type).toBe('context_snapshot');
+    if (event.type === 'context_snapshot') {
+      expect(event.projection_mode).toBe('compact');
+      expect(event.session_memory_status).toBe('stale');
+    }
+  });
+
+  it('encodes control inputs for background subagents', () => {
+    expect(
+      encodeFrontendInput({
+        type: 'run_background_subagent',
+        task: 'inspect repo',
+        agent_type: 'general'
+      })
+    ).toBe('{"type":"run_background_subagent","task":"inspect repo","agent_type":"general"}\n');
+  });
+
+  it('rejects unknown frontend events', () => {
+    expect(() => parseFrontendEvent('{"type":"unknown"}')).toThrow(/unknown frontend event type/);
+  });
+
+  it('encodes frontend input as json line', () => {
+    expect(encodeFrontendInput({ type: 'submit_prompt', text: 'hello' })).toBe(
+      '{"type":"submit_prompt","text":"hello"}\n'
+    );
+  });
+});
diff --git a/coding-deepgent/frontend/cli/src/__tests__/reducer.test.ts b/coding-deepgent/frontend/cli/src/__tests__/reducer.test.ts
new file mode 100644
index 000000000..f5e65b125
--- /dev/null
+++ b/coding-deepgent/frontend/cli/src/__tests__/reducer.test.ts
@@ -0,0 +1,141 @@
+import { describe, expect, it } from 'vitest';
+import { initialUiState, reduceFrontendEvent } from '../bridge/reducer.js';
+
+describe('frontend reducer', () => {
+  it('builds a multi-turn message view', () => {
+    let state = reduceFrontendEvent(initialUiState, {
+      type: 'session_started',
+      session_id: 'session-1',
+      workdir: '/repo'
+    });
+    state = reduceFrontendEvent(state, { type: 'user_message', id: 'u1', text: 'hello' });
+    state = reduceFrontendEvent(state, { type: 'assistant_delta', message_id: 'a1', text: 'he' });
+    state = reduceFrontendEvent(state, { type: 'assistant_delta', message_id: 'a1', text: 'llo' });
+    state = reduceFrontendEvent(state, { type: 'assistant_message', message_id: 'a1', text: 'hello' });
+    state = reduceFrontendEvent(state, { type: 'run_finished', session_id: 'session-1', status: 'completed' });
+
+    expect(state.sessionId).toBe('session-1');
+    expect(state.messages.map(message => message.text)).toEqual(['hello', 'hello']);
+    expect(state.isRunning).toBe(false);
+  });
+
+  it('tracks permission queue and decisions', () => {
+    let state = reduceFrontendEvent(initialUiState, {
+      type: 'permission_requested',
+      request_id: 'req-1',
+      tool: 'write_file',
+      description: 'Write app.py',
+      options: ['approve', 'reject']
+    });
+    expect(state.pendingPermissions).toHaveLength(1);
+
+    state = reduceFrontendEvent(state, {
+      type: 'permission_resolved',
+      request_id: 'req-1',
+      decision: 'reject',
+      message: 'No'
+    });
+
+    expect(state.pendingPermissions).toHaveLength(0);
+    expect(state.messages.at(-1)?.text).toBe('No');
+  });
+
+  it('stores todo snapshots', () => {
+    const state = reduceFrontendEvent(initialUiState, {
+      type: 'todo_snapshot',
+      items: [{ content: 'Build UI', status: 'in_progress', activeForm: 'Building UI' }]
+    });
+
+    expect(state.todos).toEqual([
+      { content: 'Build UI', status: 'in_progress', activeForm: 'Building UI' }
+    ]);
+  });
+
+  it('stores runtime visibility snapshots', () => {
+    let state = reduceFrontendEvent(initialUiState, {
+      type: 'task_snapshot',
+      items: [{ id: 'task-1', content: 'Inspect context', status: 'in_progress' }]
+    });
+    state = reduceFrontendEvent(state, {
+      type: 'context_snapshot',
+      projection_mode: 'collapse',
+      history_messages: 8,
+      model_messages: 5,
+      visible_messages: 4,
+      hidden_messages: 4,
+      compact_count: 1,
+      collapse_count: 1,
+      session_memory_status: 'current',
+      latest_event: 'collapse'
+    });
+    state = reduceFrontendEvent(state, {
+      type: 'subagent_snapshot',
+      total: 1,
+      items: [
+        {
+          created_at: '2026-04-20T00:00:00Z',
+          agent_type: 'general',
+          role: 'assistant',
+          content: 'Checked tests.',
+          subagent_thread_id: 'child-1'
+        }
+      ]
+    });
+
+    expect(state.tasks).toEqual([
+      { id: 'task-1', content: 'Inspect context', status: 'in_progress' }
+    ]);
+    expect(state.contextSnapshot?.projection_mode).toBe('collapse');
+    expect(state.contextSnapshot?.session_memory_status).toBe('current');
+    expect(state.subagentSnapshot?.total).toBe(1);
+    expect(state.subagentSnapshot?.items[0]?.content).toBe('Checked tests.');
+
+    state = reduceFrontendEvent(state, {
+      type: 'background_subagent_snapshot',
+      total: 1,
+      items: [
+        {
+          run_id: 'bgrun-1',
+          status: 'running',
+          mode: 'background_subagent',
+          agent_type: 'general',
+          progress_summary: 'Background subagent is running.',
+          pending_inputs: 1,
+          total_invocations: 0
+        }
+      ]
+    });
+
+    expect(state.backgroundSubagentSnapshot?.total).toBe(1);
+    expect(state.backgroundSubagentSnapshot?.items[0]?.run_id).toBe('bgrun-1');
+  });
+
+  it('handles interleaved streaming and tool events', () => {
+    let state = reduceFrontendEvent(initialUiState, { type: 'user_message', id: 'u1', text: 'run' });
+    state = reduceFrontendEvent(state, { type: 'assistant_delta', message_id: 'a1', text: 'working' });
+    state = reduceFrontendEvent(state, { type: 'tool_started', tool_call_id: 'call-1', name: 'read_file', summary: 'Reading' });
+    state = reduceFrontendEvent(state, { type: 'tool_finished', tool_call_id: 'call-1', name: 'read_file', status: 'success', preview: 'Done' });
+    state = reduceFrontendEvent(state, { type: 'assistant_delta', message_id: 'a1', text: ' done' });
+    state = reduceFrontendEvent(state, { type: 'assistant_message', message_id: 'a1', text: 'working done' });
+
+    expect(state.messages.map(message => [message.kind, message.text])).toEqual([
+      ['user', 'run'],
+      ['assistant', 'working done'],
+      ['tool', 'Done']
+    ]);
+  });
+
+  it('handles local CLI commands', () => {
+    let state = reduceFrontendEvent(initialUiState, { type: 'user_message', id: 'u1', text: 'hello' });
+    state = reduceFrontendEvent(state, { type: 'ui_help' });
+    expect(state.messages.at(-1)?.title).toBe('Help');
+
+    state = reduceFrontendEvent(state, { type: 'ui_clear' });
+    expect(state.messages).toEqual([]);
+    expect(state.status).toBe('Cleared');
+
+    state = reduceFrontendEvent(state, { type: 'ui_interrupted' });
+    expect(state.status).toBe('Interrupted');
+    expect(state.isRunning).toBe(false);
+  });
+});
diff --git a/coding-deepgent/frontend/cli/src/app.tsx b/coding-deepgent/frontend/cli/src/app.tsx
new file mode 100644
index 000000000..5949fa1fa
--- /dev/null
+++ b/coding-deepgent/frontend/cli/src/app.tsx
@@ -0,0 +1,104 @@
+import React, { useEffect, useReducer } from 'react';
+import { Box, Text, useApp } from 'ink';
+import type { BridgeClient } from './bridge/python-process.js';
+import { initialUiState, reduceFrontendEvent } from './bridge/reducer.js';
+import type { FrontendInput } from './bridge/protocol.js';
+import { MessageList } from './components/message-list.js';
+import { ContextPanel } from './components/context-panel.js';
+import { PermissionPanel } from './components/permission-panel.js';
+import { PromptInput } from './components/prompt-input.js';
+import { SessionPanel } from './components/session-panel.js';
+import { SpinnerLine } from './components/spinner.js';
+import { StatusFooter } from './components/status-footer.js';
+import { SubagentPanel } from './components/subagent-panel.js';
+import { TaskPanel } from './components/task-panel.js';
+import { TodoPanel } from './components/todo-panel.js';
+
+export function App({ bridge }: { bridge: BridgeClient }): React.ReactNode {
+  const [state, dispatch] = useReducer(reduceFrontendEvent, initialUiState);
+  const ink = useApp();
+
+  useEffect(() => {
+    const unsubscribe = bridge.onEvent(event => dispatch(event));
+    bridge.start();
+    return () => {
+      unsubscribe();
+      bridge.stop();
+    };
+  }, [bridge]);
+
+  const send = (input: FrontendInput) => bridge.send(input);
+  const exit = () => {
+    dispatch({ type: 'ui_interrupted' });
+    bridge.stop();
+    ink.exit();
+  };
+  const submit = (text: string) => {
+    if (text === '/help') {
+      dispatch({ type: 'ui_help' });
+      return;
+    }
+    if (text === '/clear') {
+      dispatch({ type: 'ui_clear' });
+      return;
+    }
+    if (text === '/refresh') {
+      send({ type: 'refresh_snapshots' });
+      return;
+    }
+    if (text.startsWith('/subagent-run ')) {
+      send({ type: 'run_background_subagent', task: text.slice('/subagent-run '.length).trim() });
+      return;
+    }
+    if (text.startsWith('/subagent-send ')) {
+      const payload = text.slice('/subagent-send '.length).trim();
+      const [runId, ...rest] = payload.split(/\s+/);
+      const message = rest.join(' ').trim();
+      if (runId && message) {
+        send({ type: 'subagent_send_input', run_id: runId, message });
+        return;
+      }
+      dispatch({
+        type: 'protocol_error',
+        error: 'Usage: /subagent-send <run_id> <message>'
+      });
+      return;
+    }
+    if (text.startsWith('/subagent-stop ')) {
+      const runId = text.slice('/subagent-stop '.length).trim();
+      if (runId) {
+        send({ type: 'subagent_stop', run_id: runId });
+        return;
+      }
+      dispatch({
+        type: 'protocol_error',
+        error: 'Usage: /subagent-stop <run_id>'
+      });
+      return;
+    }
+    send({ type: 'submit_prompt', text });
+  };
+
+  return (
+    <Box flexDirection="column" paddingX={1}>
+      <Text color="cyan">coding-deepgent</Text>
+      <SessionPanel recoveryBrief={state.recoveryBrief} />
+      <ContextPanel snapshot={state.contextSnapshot} />
+      <TodoPanel todos={state.todos} />
+      <TaskPanel tasks={state.tasks} />
+      <SubagentPanel
+        backgroundSnapshot={state.backgroundSubagentSnapshot}
+        snapshot={state.subagentSnapshot}
+      />
+      <PermissionPanel permissions={state.pendingPermissions} send={send} />
+      <MessageList messages={state.messages} />
+      <SpinnerLine active={state.isRunning} />
+      <PromptInput
+        disabled={state.isRunning || state.pendingPermissions.length > 0}
+        onSubmit={submit}
+        onExit={exit}
+      />
+      <StatusFooter state={state} />
+    </Box>
+  );
+}
diff --git a/coding-deepgent/frontend/cli/src/bridge/protocol.ts b/coding-deepgent/frontend/cli/src/bridge/protocol.ts
new file mode 100644
index 000000000..38a99be2c
--- /dev/null
+++ b/coding-deepgent/frontend/cli/src/bridge/protocol.ts
@@ -0,0 +1,117 @@
+export type TodoStatus = 'pending' | 'in_progress' | 'completed';
+
+export type TodoItemPayload = {
+  content: string;
+  status: TodoStatus;
+  activeForm?: string;
+};
+
+export type TaskItemPayload = {
+  id: string;
+  content: string;
+  status: string;
+  owner?: string;
+};
+
+export type ContextSnapshotPayload = {
+  projection_mode: 'raw' | 'compact' | 'collapse';
+  history_messages: number;
+  model_messages: number;
+  visible_messages: number;
+  hidden_messages: number;
+  compact_count: number;
+  collapse_count: number;
+  session_memory_status: 'missing' | 'current' | 'stale';
+  latest_event?: string;
+};
+
+export type SubagentItemPayload = {
+  created_at: string;
+  agent_type: string;
+  role: string;
+  content: string;
+  subagent_thread_id: string;
+};
+
+export type BackgroundSubagentItemPayload = {
+  run_id: string;
+  status: 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
+  mode: 'background_subagent' | 'background_fork';
+  agent_type: string;
+  progress_summary: string;
+  pending_inputs: number;
+  total_invocations: number;
+};
+
+export type FrontendEvent =
+  | { type: 'session_started'; session_id: string; workdir: string }
+  | { type: 'user_message'; id: string; text: string }
+  | { type: 'assistant_delta'; message_id: string; text: string }
+  | { type: 'assistant_message'; message_id: string; text: string }
+  | { type: 'tool_started'; tool_call_id: string; name: string; summary?: string }
+  | { type: 'tool_finished'; tool_call_id: string; name: string; status: 'success'; preview?: string }
+  | { type: 'tool_failed'; tool_call_id: string; name: string; error: string }
+  | { type: 'permission_requested'; request_id: string; tool: string; description: string; options: Array<'approve' | 'reject'> }
+  | { type: 'permission_resolved'; request_id: string; decision: 'approve' | 'reject'; message?: string }
+  | { type: 'todo_snapshot'; items: TodoItemPayload[] }
+  | { type: 'task_snapshot'; items: TaskItemPayload[] }
+  | ({ type: 'context_snapshot' } & ContextSnapshotPayload)
+  | { type: 'subagent_snapshot'; total: number; items: SubagentItemPayload[] }
+  | { type: 'background_subagent_snapshot'; total: number; items: BackgroundSubagentItemPayload[] }
+  | { type: 'runtime_event'; kind: string; message: string; metadata?: Record<string, unknown> }
+  | { type: 'recovery_brief'; text: string }
+  | { type: 'run_finished'; session_id: string; status: 'completed' | 'exited' }
+  | { type: 'run_failed'; session_id: string; error: string }
+  | { type: 'protocol_error'; error: string };
+
+export type FrontendInput =
+  | { type: 'submit_prompt'; text: string }
+  | { type: 'permission_decision'; request_id: string; decision: 'approve' | 'reject'; message?: string }
+  | { type: 'refresh_snapshots' }
+  | { type: 'run_background_subagent'; task: string; agent_type?: string; plan_id?: string; max_turns?: number }
+  | { type: 'subagent_send_input'; run_id: string; message: string }
+  | { type: 'subagent_stop'; run_id: string }
+  | { type: 'interrupt' }
+  | { type: 'exit' };
+
+const EVENT_TYPES = new Set([
+  'session_started',
+  'user_message',
+  'assistant_delta',
+  'assistant_message',
+  'tool_started',
+  'tool_finished',
+  'tool_failed',
+  'permission_requested',
+  'permission_resolved',
+  'todo_snapshot',
+  'task_snapshot',
+  'context_snapshot',
+  'subagent_snapshot',
+  'background_subagent_snapshot',
+  'runtime_event',
+  'recovery_brief',
+  'run_finished',
+  'run_failed',
+  'protocol_error'
+]);
+
+export function parseFrontendEvent(line: string): FrontendEvent {
+  const raw: unknown = JSON.parse(line);
+  if (!isObject(raw)) {
+    throw new Error('frontend event must be an object');
+  }
+  const type = raw.type;
+  if (typeof type !== 'string' || !EVENT_TYPES.has(type)) {
+    throw new Error(`unknown frontend event type: ${String(type)}`);
+  }
+  return raw as FrontendEvent;
+}
+
+export function encodeFrontendInput(input: FrontendInput): string {
+  return `${JSON.stringify(input)}\n`;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
diff --git a/coding-deepgent/frontend/cli/src/bridge/python-process.ts b/coding-deepgent/frontend/cli/src/bridge/python-process.ts
new file mode 100644
index 000000000..fe8cb9353
--- /dev/null
+++ b/coding-deepgent/frontend/cli/src/bridge/python-process.ts
@@ -0,0 +1,118 @@
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import readline from 'node:readline';
+import { encodeFrontendInput, parseFrontendEvent, type FrontendEvent, type FrontendInput } from './protocol.js';
+
+export type BridgeClient = {
+  start(): void;
+  send(input: FrontendInput): void;
+  stop(): void;
+  onEvent(listener: (event: FrontendEvent) => void): () => void;
+};
+
+export type PythonBridgeOptions = {
+  fake?: boolean;
+};
+
+export class PythonProcessBridge implements BridgeClient {
+  private child: ChildProcessWithoutNullStreams | undefined;
+  private readonly listeners = new Set<(event: FrontendEvent) => void>();
+  private stopped = false;
+
+  constructor(private readonly options: PythonBridgeOptions = {}) {}
+
+  start(): void {
+    if (this.child) {
+      return;
+    }
+    const command = resolveBridgeCommand(this.options.fake);
+    this.child = spawn(command.command, command.args, {
+      cwd: process.env.CODING_DEEPGENT_UI_WORKDIR || process.cwd(),
+      env: {
+        ...process.env,
+        PYTHONPATH: process.env.PYTHONPATH || 'src'
+      },
+      shell: command.shell,
+      stdio: 'pipe'
+    });
+
+    const lines = readline.createInterface({ input: this.child.stdout });
+    lines.on('line', line => {
+      try {
+        this.emit(parseFrontendEvent(line));
+      } catch (error) {
+        this.emit({
+          type: 'protocol_error',
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    });
+
+    this.child.stderr.on('data', chunk => {
+      const text = String(chunk).trim();
+      if (text) {
+        this.emit({ type: 'runtime_event', kind: 'stderr', message: text });
+      }
+    });
+
+    this.child.on('error', error => {
+      this.emit({ type: 'run_failed', session_id: 'unknown', error: error.message });
+    });
+
+    this.child.on('close', code => {
+      if (!this.stopped && code !== 0) {
+        this.emit({
+          type: 'run_failed',
+          session_id: 'unknown',
+          error: `Python bridge exited with code ${code ?? 'unknown'}`
+        });
+      }
+    });
+  }
+
+  send(input: FrontendInput): void {
+    if (!this.child) {
+      this.start();
+    }
+    this.child?.stdin.write(encodeFrontendInput(input));
+  }
+
+  stop(): void {
+    if (this.stopped) {
+      return;
+    }
+    this.stopped = true;
+    if (
+      this.child &&
+      !this.child.killed &&
+      !this.child.stdin.destroyed &&
+      !this.child.stdin.writableEnded
+    ) {
+      this.child.stdin.write(encodeFrontendInput({ type: 'exit' }));
+      this.child.stdin.end();
+    }
+  }
+
+  onEvent(listener: (event: FrontendEvent) => void): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  private emit(event: FrontendEvent): void {
+    for (const listener of this.listeners) {
+      listener(event);
+    }
+  }
+}
+
+function resolveBridgeCommand(fake = false): { command: string; args: string[]; shell?: boolean } {
+  const configured = process.env.CODING_DEEPGENT_UI_BRIDGE_COMMAND;
+  if (configured) {
+    return { command: configured, args: [], shell: true };
+  }
+  return {
+    command: 'python3',
+    args: ['-m', 'coding_deepgent', 'ui-bridge', ...(fake || process.env.CODING_DEEPGENT_UI_FAKE === '1' ? ['--fake'] : [])]
+  };
+}
diff --git a/coding-deepgent/frontend/cli/src/bridge/reducer.ts b/coding-deepgent/frontend/cli/src/bridge/reducer.ts
new file mode 100644
index 000000000..352a82859
--- /dev/null
+++ b/coding-deepgent/frontend/cli/src/bridge/reducer.ts
@@ -0,0 +1,280 @@
+import type {
+  BackgroundSubagentItemPayload,
+  ContextSnapshotPayload,
+  FrontendEvent,
+  SubagentItemPayload,
+  TaskItemPayload,
+  TodoItemPayload
+} from './protocol.js';
+
+export type MessageKind = 'user' | 'assistant' | 'tool' | 'system' | 'error';
+
+export type UiMessage = {
+  id: string;
+  kind: MessageKind;
+  title?: string;
+  text: string;
+  streaming?: boolean;
+};
+
+export type PendingPermission = {
+  requestId: string;
+  tool: string;
+  description: string;
+  options: Array<'approve' | 'reject'>;
+};
+
+export type UiState = {
+  sessionId?: string;
+  workdir?: string;
+  messages: UiMessage[];
+  todos: TodoItemPayload[];
+  tasks: TaskItemPayload[];
+  contextSnapshot?: ContextSnapshotPayload;
+  subagentSnapshot?: { total: number; items: SubagentItemPayload[] };
+  backgroundSubagentSnapshot?: { total: number; items: BackgroundSubagentItemPayload[] };
+  pendingPermissions: PendingPermission[];
+  recoveryBrief?: string;
+  isRunning: boolean;
+  status: string;
+  lastError?: string;
+};
+
+export type UiAction =
+  | FrontendEvent
+  | { type: 'ui_clear' }
+  | { type: 'ui_help' }
+  | { type: 'ui_interrupted' };
+
+export const initialUiState: UiState = {
+  messages: [],
+  todos: [],
+  tasks: [],
+  pendingPermissions: [],
+  isRunning: false,
+  status: 'Ready'
+};
+
+export function reduceFrontendEvent(state: UiState, event: UiAction): UiState {
+  switch (event.type) {
+    case 'session_started':
+      return {
+        ...state,
+        sessionId: event.session_id,
+        workdir: event.workdir,
+        status: 'Session started'
+      };
+    case 'user_message':
+      return {
+        ...state,
+        isRunning: true,
+        status: 'Running',
+        messages: [
+          ...state.messages,
+          { id: event.id, kind: 'user', title: 'You', text: event.text }
+        ]
+      };
+    case 'assistant_delta':
+      return upsertAssistantDelta(state, event.message_id, event.text);
+    case 'assistant_message':
+      return upsertMessage(state, {
+        id: event.message_id,
+        kind: 'assistant',
+        title: 'Assistant',
+        text: event.text,
+        streaming: false
+      });
+    case 'tool_started':
+      return {
+        ...state,
+        messages: [
+          ...state.messages,
+          {
+            id: event.tool_call_id,
+            kind: 'tool',
+            title: `Tool: ${event.name}`,
+            text: event.summary || 'started',
+            streaming: true
+          }
+        ]
+      };
+    case 'tool_finished':
+      return upsertMessage(state, {
+        id: event.tool_call_id,
+        kind: 'tool',
+        title: `Tool: ${event.name}`,
+        text: event.preview || 'completed',
+        streaming: false
+      });
+    case 'tool_failed':
+      return upsertMessage(state, {
+        id: event.tool_call_id,
+        kind: 'error',
+        title: `Tool failed: ${event.name}`,
+        text: event.error,
+        streaming: false
+      });
+    case 'permission_requested':
+      return {
+        ...state,
+        pendingPermissions: [
+          ...state.pendingPermissions,
+          {
+            requestId: event.request_id,
+            tool: event.tool,
+            description: event.description,
+            options: event.options
+          }
+        ],
+        status: `Approval needed for ${event.tool}`
+      };
+    case 'permission_resolved':
+      return {
+        ...state,
+        pendingPermissions: state.pendingPermissions.filter(
+          permission => permission.requestId !== event.request_id
+        ),
+        messages: [
+          ...state.messages,
+          {
+            id: `permission-${event.request_id}`,
+            kind: 'system',
+            title: 'Permission',
+            text: event.message || `Decision: ${event.decision}`
+          }
+        ]
+      };
+    case 'todo_snapshot':
+      return { ...state, todos: event.items };
+    case 'task_snapshot':
+      return { ...state, tasks: event.items };
+    case 'context_snapshot':
+      return {
+        ...state,
+        contextSnapshot: {
+          projection_mode: event.projection_mode,
+          history_messages: event.history_messages,
+          model_messages: event.model_messages,
+          visible_messages: event.visible_messages,
+          hidden_messages: event.hidden_messages,
+          compact_count: event.compact_count,
+          collapse_count: event.collapse_count,
+          session_memory_status: event.session_memory_status,
+          ...(event.latest_event ? { latest_event: event.latest_event } : {})
+        }
+      };
+    case 'subagent_snapshot':
+      return {
+        ...state,
+        subagentSnapshot: { total: event.total, items: event.items }
+      };
+    case 'background_subagent_snapshot':
+      return {
+        ...state,
+        backgroundSubagentSnapshot: { total: event.total, items: event.items }
+      };
+    case 'runtime_event':
+      return {
+        ...state,
+        messages: [
+          ...state.messages,
+          {
+            id: `runtime-${state.messages.length}`,
+            kind: event.kind.includes('error') ? 'error' : 'system',
+            title: event.kind,
+            text: event.message
+          }
+        ]
+      };
+    case 'recovery_brief':
+      return { ...state, recoveryBrief: event.text };
+    case 'run_finished':
+      return {
+        ...state,
+        isRunning: false,
+        status: event.status === 'exited' ? 'Exited' : 'Ready'
+      };
+    case 'run_failed':
+      return {
+        ...state,
+        isRunning: false,
+        lastError: event.error,
+        status: 'Failed',
+        messages: [
+          ...state.messages,
+          { id: `error-${state.messages.length}`, kind: 'error', title: 'Run failed', text: event.error }
+        ]
+      };
+    case 'protocol_error':
+      return {
+        ...state,
+        lastError: event.error,
+        messages: [
+          ...state.messages,
+          { id: `protocol-${state.messages.length}`, kind: 'error', title: 'Protocol error', text: event.error }
+        ]
+      };
+    case 'ui_clear':
+      return {
+        ...state,
+        messages: [],
+        status: 'Cleared'
+      };
+    case 'ui_help':
+      return {
+        ...state,
+        messages: [
+          ...state.messages,
+          {
+            id: `help-${state.messages.length}`,
+            kind: 'system',
+            title: 'Help',
+            text: 'Commands: /help, /refresh, /subagent-run <task>, /subagent-send <run_id> <message>, /subagent-stop <run_id>, /clear, /exit.'
+          }
+        ],
+        status: 'Help shown'
+      };
+    case 'ui_interrupted':
+      return {
+        ...state,
+        isRunning: false,
+        status: 'Interrupted',
+        messages: [
+          ...state.messages,
+          {
+            id: `interrupt-${state.messages.length}`,
+            kind: 'system',
+            title: 'Interrupted',
+            text: 'Frontend requested interruption.'
+          }
+        ]
+      };
+  }
+}
+
+function upsertAssistantDelta(state: UiState, id: string, delta: string): UiState {
+  const existing = state.messages.find(message => message.id === id);
+  if (!existing) {
+    return {
+      ...state,
+      messages: [
+        ...state.messages,
+        { id, kind: 'assistant', title: 'Assistant', text: delta, streaming: true }
+      ]
+    };
+  }
+  return upsertMessage(state, { ...existing, text: existing.text + delta, streaming: true });
+}
+
+function upsertMessage(state: UiState, message: UiMessage): UiState {
+  const index = state.messages.findIndex(candidate => candidate.id === message.id);
+  if (index === -1) {
+    return { ...state, messages: [...state.messages, message] };
+  }
+  return {
+    ...state,
+    messages: state.messages.map((candidate, candidateIndex) =>
+      candidateIndex === index ? message : candidate
+    )
+  };
+}
diff --git a/coding-deepgent/frontend/cli/src/components/context-panel.tsx b/coding-deepgent/frontend/cli/src/components/context-panel.tsx
new file mode 100644
index 000000000..25688532b
--- /dev/null
+++ b/coding-deepgent/frontend/cli/src/components/context-panel.tsx
@@ -0,0 +1,28 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+import type { ContextSnapshotPayload } from '../bridge/protocol.js';
+
+export function ContextPanel({
+  snapshot
+}: {
+  snapshot: ContextSnapshotPayload | undefined;
+}): React.ReactNode {
+  if (!snapshot) {
+    return null;
+  }
+  const pressure = `${snapshot.visible_messages}/${snapshot.history_messages} raw visible`;
+  const compact = `compact ${snapshot.compact_count} collapse ${snapshot.collapse_count}`;
+  const latest = snapshot.latest_event ? ` latest ${snapshot.latest_event}` : '';
+  return (
+    <Box flexDirection="column" borderStyle="round" borderColor="yellow" paddingX={1} marginBottom={1}>
+      <Text color="yellow">Context ({snapshot.projection_mode})</Text>
+      <Text>
+        model {snapshot.model_messages} | {pressure} | hidden {snapshot.hidden_messages}
+      </Text>
+      <Text>
+        {compact} | session memory {snapshot.session_memory_status}
+        {latest}
+      </Text>
+    </Box>
+  );
+}
diff --git a/coding-deepgent/frontend/cli/src/components/message-list.tsx b/coding-deepgent/frontend/cli/src/components/message-list.tsx
new file mode 100644
index 000000000..2a94b1f26
--- /dev/null
+++ b/coding-deepgent/frontend/cli/src/components/message-list.tsx
@@ -0,0 +1,25 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+import type { UiMessage } from '../bridge/reducer.js';
+import { MessageRow } from './message-row.js';
+
+const MAX_VISIBLE_MESSAGES = 12;
+
+export function MessageList({ messages }: { messages: UiMessage[] }): React.ReactNode {
+  const visible = messages.slice(-MAX_VISIBLE_MESSAGES);
+  if (visible.length === 0) {
+    return (
+      <Box marginY={1}>
+        <Text color="gray">No messages yet. Type a prompt to start.</Text>
+      </Box>
+    );
+  }
+  return (
+    <Box flexDirection="column" marginTop={1}>
+      {visible.map(message => (
+        <MessageRow key={message.id} message={message} />
+      ))}
+    </Box>
+  );
+}
+
diff --git a/coding-deepgent/frontend/cli/src/components/message-row.tsx b/coding-deepgent/frontend/cli/src/components/message-row.tsx
new file mode 100644
index 000000000..012cec399
--- /dev/null
+++ b/coding-deepgent/frontend/cli/src/components/message-row.tsx
@@ -0,0 +1,36 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+import type { UiMessage } from '../bridge/reducer.js';
+
+export function MessageRow({ message }: { message: UiMessage }): React.ReactNode {
+  const color = colorFor(message.kind);
+  const marker = markerFor(message.kind);
+  return (
+    <Box flexDirection="column" marginBottom={1}>
+      <Box>
+        <Text color={color}>{marker} {message.title || message.kind}</Text>
+        {message.streaming ? <Text color="yellow"> running</Text> : null}
+      </Box>
+      <Box paddingLeft={2}>
+        <Text>{message.text || '(empty)'}</Text>
+      </Box>
+    </Box>
+  );
+}
+
+function colorFor(kind: UiMessage['kind']): string {
+  if (kind === 'user') return 'cyan';
+  if (kind === 'assistant') return 'green';
+  if (kind === 'tool') return 'magenta';
+  if (kind === 'error') return 'red';
+  return 'gray';
+}
+
+function markerFor(kind: UiMessage['kind']): string {
+  if (kind === 'user') return '>';
+  if (kind === 'assistant') return '<';
+  if (kind === 'tool') return '*';
+  if (kind === 'error') return '!';
+  return '-';
+}
+
diff --git a/coding-deepgent/frontend/cli/src/components/permission-panel.tsx b/coding-deepgent/frontend/cli/src/components/permission-panel.tsx
new file mode 100644
index 000000000..68baac3bc
--- /dev/null
+++ b/coding-deepgent/frontend/cli/src/components/permission-panel.tsx
@@ -0,0 +1,35 @@
+import React from 'react';
+import { Box, Text, useInput } from 'ink';
+import type { FrontendInput } from '../bridge/protocol.js';
+import type { PendingPermission } from '../bridge/reducer.js';
+
+export function PermissionPanel({
+  permissions,
+  send
+}: {
+  permissions: PendingPermission[];
+  send: (input: FrontendInput) => void;
+}): React.ReactNode {
+  const current = permissions[0];
+  useInput(input => {
+    if (!current) return;
+    if (input.toLowerCase() === 'a') {
+      send({ type: 'permission_decision', request_id: current.requestId, decision: 'approve' });
+    }
+    if (input.toLowerCase() === 'r') {
+      send({ type: 'permission_decision', request_id: current.requestId, decision: 'reject' });
+    }
+  });
+
+  if (!current) {
+    return null;
+  }
+  return (
+    <Box flexDirection="column" borderStyle="double" borderColor="yellow" paddingX={1} marginBottom={1}>
+      <Text color="yellow">Permission required: {current.tool}</Text>
+      <Text>{current.description}</Text>
+      <Text color="gray">Press a to approve, r to reject.</Text>
+    </Box>
+  );
+}
+
diff --git a/coding-deepgent/frontend/cli/src/components/prompt-input.tsx b/coding-deepgent/frontend/cli/src/components/prompt-input.tsx
new file mode 100644
index 000000000..49090fc51
--- /dev/null
+++ b/coding-deepgent/frontend/cli/src/components/prompt-input.tsx
@@ -0,0 +1,54 @@
+import React, { useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+
+export function PromptInput({
+  disabled,
+  onSubmit,
+  onExit
+}: {
+  disabled: boolean;
+  onSubmit: (value: string) => void;
+  onExit: () => void;
+}): React.ReactNode {
+  const [value, setValue] = useState('');
+
+  useInput((input, key) => {
+    if (key.ctrl && input === 'c') {
+      onExit();
+      return;
+    }
+    if (disabled) {
+      return;
+    }
+    const newlineIndex = input.search(/[\r\n]/);
+    if (key.return || newlineIndex !== -1) {
+      const submittedValue =
+        newlineIndex === -1 ? value : value + input.slice(0, newlineIndex);
+      const trimmed = submittedValue.trim();
+      if (trimmed === '/exit') {
+        onExit();
+        return;
+      }
+      if (trimmed) {
+        onSubmit(trimmed);
+        setValue('');
+      }
+      return;
+    }
+    if (key.backspace || key.delete) {
+      setValue(current => current.slice(0, -1));
+      return;
+    }
+    if (input && !key.ctrl && !key.meta) {
+      setValue(current => current + input);
+    }
+  });
+
+  return (
+    <Box borderStyle="single" borderColor={disabled ? 'gray' : 'cyan'} paddingX={1}>
+      <Text color="cyan">prompt </Text>
+      <Text>{value}</Text>
+      {!disabled ? <Text color="cyan">_</Text> : <Text color="gray"> waiting...</Text>}
+    </Box>
+  );
+}
diff --git a/coding-deepgent/frontend/cli/src/components/session-panel.tsx b/coding-deepgent/frontend/cli/src/components/session-panel.tsx
new file mode 100644
index 000000000..3e8246018
--- /dev/null
+++ b/coding-deepgent/frontend/cli/src/components/session-panel.tsx
@@ -0,0 +1,15 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+
+export function SessionPanel({ recoveryBrief }: { recoveryBrief: string | undefined }): React.ReactNode {
+  if (!recoveryBrief) {
+    return null;
+  }
+  const firstLines = recoveryBrief.split('\n').slice(0, 6).join('\n');
+  return (
+    <Box flexDirection="column" borderStyle="single" borderColor="gray" paddingX={1} marginBottom={1}>
+      <Text color="gray">Recovery brief</Text>
+      <Text>{firstLines}</Text>
+    </Box>
+  );
+}
diff --git a/coding-deepgent/frontend/cli/src/components/spinner.tsx b/coding-deepgent/frontend/cli/src/components/spinner.tsx
new file mode 100644
index 000000000..e1ede8fd9
--- /dev/null
+++ b/coding-deepgent/frontend/cli/src/components/spinner.tsx
@@ -0,0 +1,7 @@
+import React from 'react';
+import { Text } from 'ink';
+
+export function SpinnerLine({ active }: { active: boolean }): React.ReactNode {
+  return active ? <Text color="yellow">Running agent...</Text> : null;
+}
+
diff --git a/coding-deepgent/frontend/cli/src/components/status-footer.tsx b/coding-deepgent/frontend/cli/src/components/status-footer.tsx
new file mode 100644
index 000000000..271f0fa5d
--- /dev/null
+++ b/coding-deepgent/frontend/cli/src/components/status-footer.tsx
@@ -0,0 +1,22 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+import type { UiState } from '../bridge/reducer.js';
+
+export function StatusFooter({ state }: { state: UiState }): React.ReactNode {
+  const permission = state.pendingPermissions[0];
+  const status = permission
+    ? `Waiting for approval: ${permission.tool}`
+    : state.lastError
+      ? `Failed: ${state.lastError}`
+      : state.status;
+  return (
+    <Box marginTop={1}>
+      <Text color="gray">
+        {status}
+        {state.sessionId ? ` | session ${state.sessionId.slice(0, 8)}` : ''}
+        {state.workdir ? ` | ${state.workdir}` : ''}
+        {' | /help /refresh /clear /exit'}
+      </Text>
+    </Box>
+  );
+}
diff --git a/coding-deepgent/frontend/cli/src/components/subagent-panel.tsx b/coding-deepgent/frontend/cli/src/components/subagent-panel.tsx
new file mode 100644
index 000000000..0a5844144
--- /dev/null
+++ b/coding-deepgent/frontend/cli/src/components/subagent-panel.tsx
@@ -0,0 +1,41 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+import type { BackgroundSubagentItemPayload, SubagentItemPayload } from '../bridge/protocol.js';
+
+export function SubagentPanel({
+  backgroundSnapshot,
+  snapshot
+}: {
+  backgroundSnapshot: { total: number; items: BackgroundSubagentItemPayload[] } | undefined;
+  snapshot: { total: number; items: SubagentItemPayload[] } | undefined;
+}): React.ReactNode {
+  if (backgroundSnapshot && backgroundSnapshot.total > 0) {
+    return (
+      <Box flexDirection="column" borderStyle="round" borderColor="magenta" paddingX={1} marginBottom={1}>
+        <Text color="magenta">Background Subagents ({backgroundSnapshot.total})</Text>
+        {backgroundSnapshot.items.map(item => (
+          <Text key={item.run_id}>
+            {item.run_id} [{item.status}] {item.agent_type} {trim(item.progress_summary)}
+          </Text>
+        ))}
+      </Box>
+    );
+  }
+  if (!snapshot || snapshot.total === 0) {
+    return null;
+  }
+  return (
+    <Box flexDirection="column" borderStyle="round" borderColor="magenta" paddingX={1} marginBottom={1}>
+      <Text color="magenta">Subagents ({snapshot.total})</Text>
+      {snapshot.items.map(item => (
+        <Text key={`${item.subagent_thread_id}-${item.created_at}`}>
+          {item.agent_type}/{item.role} {trim(item.content)}
+        </Text>
+      ))}
+    </Box>
+  );
+}
+
+function trim(text: string): string {
+  return text.length > 100 ? `${text.slice(0, 97)}...` : text;
+}
diff --git a/coding-deepgent/frontend/cli/src/components/task-panel.tsx b/coding-deepgent/frontend/cli/src/components/task-panel.tsx
new file mode 100644
index 000000000..4362df1ef
--- /dev/null
+++ b/coding-deepgent/frontend/cli/src/components/task-panel.tsx
@@ -0,0 +1,20 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+import type { TaskItemPayload } from '../bridge/protocol.js';
+
+export function TaskPanel({ tasks }: { tasks: TaskItemPayload[] }): React.ReactNode {
+  if (tasks.length === 0) {
+    return null;
+  }
+  return (
+    <Box flexDirection="column" borderStyle="round" borderColor="green" paddingX={1} marginBottom={1}>
+      <Text color="green">Tasks ({tasks.length})</Text>
+      {tasks.map(task => (
+        <Text key={task.id}>
+          {task.id} [{task.status}] {task.content}
+          {task.owner ? ` owner=${task.owner}` : ''}
+        </Text>
+      ))}
+    </Box>
+  );
+}
diff --git a/coding-deepgent/frontend/cli/src/components/todo-panel.tsx b/coding-deepgent/frontend/cli/src/components/todo-panel.tsx
new file mode 100644
index 000000000..220083e20
--- /dev/null
+++ b/coding-deepgent/frontend/cli/src/components/todo-panel.tsx
@@ -0,0 +1,28 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+import type { TodoItemPayload } from '../bridge/protocol.js';
+
+export function TodoPanel({ todos }: { todos: TodoItemPayload[] }): React.ReactNode {
+  if (todos.length === 0) {
+    return null;
+  }
+  const completed = todos.filter(todo => todo.status === 'completed').length;
+  return (
+    <Box flexDirection="column" borderStyle="round" borderColor="blue" paddingX={1} marginBottom={1}>
+      <Text color="blue">Plan ({completed}/{todos.length})</Text>
+      {todos.map((todo, index) => (
+        <Text key={`${todo.content}-${index}`}>
+          {marker(todo.status)} {todo.content}
+          {todo.status === 'in_progress' && todo.activeForm ? ` (${todo.activeForm})` : ''}
+        </Text>
+      ))}
+    </Box>
+  );
+}
+
+function marker(status: TodoItemPayload['status']): string {
+  if (status === 'completed') return '[x]';
+  if (status === 'in_progress') return '[>]';
+  return '[ ]';
+}
+
diff --git a/coding-deepgent/frontend/cli/src/index.tsx b/coding-deepgent/frontend/cli/src/index.tsx
new file mode 100644
index 000000000..8e0023c22
--- /dev/null
+++ b/coding-deepgent/frontend/cli/src/index.tsx
@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import React from 'react';
+import { render } from 'ink';
+import { App } from './app.js';
+import { PythonProcessBridge } from './bridge/python-process.js';
+
+if (!process.stdin.isTTY) {
+  console.error(
+    'coding-deepgent-ui requires an interactive TTY. Use `python3 -m coding_deepgent ui-bridge` for JSONL automation.'
+  );
+  process.exit(2);
+}
+
+const fake = process.argv.includes('--fake') || process.env.CODING_DEEPGENT_UI_FAKE === '1';
+const bridge = new PythonProcessBridge({ fake });
+
+render(<App bridge={bridge} />);
diff --git a/coding-deepgent/frontend/cli/tsconfig.json b/coding-deepgent/frontend/cli/tsconfig.json
new file mode 100644
index 000000000..248cb832a
--- /dev/null
+++ b/coding-deepgent/frontend/cli/tsconfig.json
@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx"]
+}
+
diff --git a/coding-deepgent/frontend/protocol/README.md b/coding-deepgent/frontend/protocol/README.md
new file mode 100644
index 000000000..3e327f17d
--- /dev/null
+++ b/coding-deepgent/frontend/protocol/README.md
@@ -0,0 +1,101 @@
+# coding-deepgent frontend protocol
+
+The CLI frontend talks to the Python runtime over newline-delimited JSON.
+
+Python stdout is reserved for `FrontendEvent` payloads. Python stderr is reserved
+for logs and diagnostics. The TypeScript frontend writes `FrontendInput` payloads
+to Python stdin.
+
+## FrontendInput v1
+
+```json
+{"type":"submit_prompt","text":"implement the feature"}
+{"type":"permission_decision","request_id":"req-1","decision":"approve"}
+{"type":"permission_decision","request_id":"req-1","decision":"reject","message":"Use read-only mode."}
+{"type":"refresh_snapshots"}
+{"type":"run_background_subagent","task":"inspect repo","agent_type":"general","max_turns":5}
+{"type":"subagent_send_input","run_id":"bgrun-1","message":"continue with tests"}
+{"type":"subagent_stop","run_id":"bgrun-1"}
+{"type":"interrupt"}
+{"type":"exit"}
+```
+
+## FrontendEvent v1
+
+```json
+{"type":"session_started","session_id":"session-1","workdir":"/repo"}
+{"type":"user_message","id":"user-1","text":"hello"}
+{"type":"assistant_delta","message_id":"assistant-1","text":"partial"}
+{"type":"assistant_message","message_id":"assistant-1","text":"done"}
+{"type":"tool_started","tool_call_id":"call-1","name":"read_file","summary":"Reading file"}
+{"type":"tool_finished","tool_call_id":"call-1","name":"read_file","status":"success","preview":"Read complete"}
+{"type":"tool_failed","tool_call_id":"call-1","name":"write_file","error":"Approval required"}
+{"type":"permission_requested","request_id":"req-1","tool":"write_file","description":"Write app.py","options":["approve","reject"]}
+{"type":"permission_resolved","request_id":"req-1","decision":"approve"}
+{"type":"todo_snapshot","items":[{"content":"Build UI","status":"in_progress","activeForm":"Building UI"}]}
+{"type":"task_snapshot","items":[{"id":"task-1","content":"Ship inspect view","status":"in_progress"}]}
+{"type":"context_snapshot","projection_mode":"collapse","history_messages":8,"model_messages":5,"visible_messages":4,"hidden_messages":4,"compact_count":1,"collapse_count":1,"session_memory_status":"current","latest_event":"collapse"}
+{"type":"subagent_snapshot","total":1,"items":[{"created_at":"2026-04-20T00:00:00Z","agent_type":"general","role":"assistant","content":"Checked tests.","subagent_thread_id":"child-1"}]}
+{"type":"background_subagent_snapshot","total":1,"items":[{"run_id":"bgrun-1","status":"running","mode":"background_subagent","agent_type":"general","progress_summary":"Background subagent is running.","pending_inputs":1,"total_invocations":0}]}
+{"type":"runtime_event","kind":"query_error","message":"Query failed.","metadata":{}}
+{"type":"recovery_brief","text":"Session: ..."}
+{"type":"run_finished","session_id":"session-1","status":"completed"}
+{"type":"run_failed","session_id":"session-1","error":"..."}
+{"type":"protocol_error","error":"invalid JSON payload"}
+```
+
+The protocol is intentionally renderer-neutral so a future browser UI can consume
+the same event stream over SSE or WebSocket.
+
+## Producer and adapters
+
+Runtime-facing event generation lives in `coding_deepgent.frontend.producer`.
+Transport-specific code lives under `coding_deepgent.frontend.adapters`.
+
+Current adapters:
+
+- `adapters.jsonl` — stdio newline-delimited JSON for the React/Ink CLI.
+
+Future adapters:
+
+- `adapters.sse` or a Gateway package — Server-Sent Events for HTML/Web.
+- embedded client — direct in-process event consumption for scripts/tests.
+
+Runtime/domain packages should not import transport adapters. CLI and future Web
+should share event semantics, not process implementations.
+
+Current embedded consumer:
+
+- `coding_deepgent.frontend.client.FrontendClient` — in-process Python client
+  that consumes the same `FrontendEvent` stream without JSONL transport.
+
+Current Web foundation:
+
+- `coding_deepgent.frontend.runs.FrontendRunService` — background run lifecycle
+- `coding_deepgent.frontend.stream_bridge.MemoryStreamBridge` — in-memory replayable event log
+- `coding_deepgent.frontend.adapters.sse` — SSE frame formatter and consumer
+
+## Ordering guarantees
+
+- A prompt turn starts with `user_message`.
+- `assistant_delta` may be emitted zero or more times for one `message_id`.
+- `assistant_message` finalizes the assistant text for that `message_id`.
+- Tool events may interleave with assistant deltas.
+- Snapshot events such as `todo_snapshot`, `task_snapshot`,
+  `context_snapshot`, `subagent_snapshot`, and `background_subagent_snapshot`
+  describe the latest known runtime
+  state for the completed turn; consumers should replace prior snapshot state.
+- Bridge control inputs are for the active frontend process only. They do not
+  imply a daemon or cross-process worker lifecycle.
+- `run_failed` may appear after partial deltas if execution fails mid-stream.
+- `run_finished` closes a prompt turn.
+- `protocol_error` describes malformed bridge input/output and does not imply the
+  Python runtime failed.
+
+## Current HITL boundary
+
+The protocol supports `permission_requested` and `permission_decision`, and the
+React/Ink CLI can render permission prompts. The current Python runtime still
+needs a dedicated pause/resume seam before destructive tools can be truly held
+pending approval. Until that seam exists, the UI must not claim that an approval
+gated real tool execution.
diff --git a/coding-deepgent/frontend/web/index.html b/coding-deepgent/frontend/web/index.html
new file mode 100644
index 000000000..9964a002c
--- /dev/null
+++ b/coding-deepgent/frontend/web/index.html
@@ -0,0 +1,524 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>coding-deepgent web ui</title>
+    <style>
+      :root {
+        color-scheme: light;
+        --bg: #f3f6fb;
+        --panel: #ffffff;
+        --border: #d9e1ec;
+        --text: #17212f;
+        --muted: #65758b;
+        --accent: #0f62fe;
+        --accent-soft: #d9e7ff;
+        --success: #18794e;
+        --warning: #9a6700;
+        --danger: #b42318;
+      }
+
+      * {
+        box-sizing: border-box;
+      }
+
+      body {
+        margin: 0;
+        font-family:
+          "SFMono-Regular",
+          "Consolas",
+          "Liberation Mono",
+          "Menlo",
+          monospace;
+        background: linear-gradient(180deg, #f6f8fc 0%, #eef3f9 100%);
+        color: var(--text);
+      }
+
+      main {
+        max-width: 1080px;
+        margin: 0 auto;
+        padding: 24px 16px 48px;
+      }
+
+      .header {
+        margin-bottom: 16px;
+      }
+
+      .header h1 {
+        margin: 0;
+        font-size: 22px;
+      }
+
+      .header p {
+        margin: 8px 0 0;
+        color: var(--muted);
+      }
+
+      .layout {
+        display: grid;
+        grid-template-columns: 2fr 1fr;
+        gap: 16px;
+      }
+
+      .panel {
+        background: var(--panel);
+        border: 1px solid var(--border);
+        border-radius: 16px;
+        padding: 16px;
+        box-shadow: 0 12px 32px rgba(15, 23, 42, 0.05);
+      }
+
+      .stack {
+        display: flex;
+        flex-direction: column;
+        gap: 12px;
+      }
+
+      label {
+        display: block;
+        font-size: 12px;
+        color: var(--muted);
+        margin-bottom: 6px;
+      }
+
+      input,
+      textarea,
+      button {
+        font: inherit;
+      }
+
+      input,
+      textarea {
+        width: 100%;
+        border: 1px solid var(--border);
+        border-radius: 12px;
+        padding: 10px 12px;
+        background: #fff;
+      }
+
+      textarea {
+        min-height: 120px;
+        resize: vertical;
+      }
+
+      .controls {
+        display: flex;
+        gap: 10px;
+        align-items: center;
+      }
+
+      button {
+        border: 0;
+        border-radius: 999px;
+        padding: 10px 16px;
+        background: var(--accent);
+        color: white;
+        cursor: pointer;
+      }
+
+      button.secondary {
+        background: #e8eef7;
+        color: var(--text);
+      }
+
+      button:disabled {
+        opacity: 0.5;
+        cursor: not-allowed;
+      }
+
+      .status {
+        padding: 10px 12px;
+        border-radius: 12px;
+        background: var(--accent-soft);
+        color: var(--text);
+        font-size: 13px;
+      }
+
+      .message-list {
+        display: flex;
+        flex-direction: column;
+        gap: 10px;
+        min-height: 480px;
+      }
+
+      .message {
+        border: 1px solid var(--border);
+        border-radius: 12px;
+        padding: 12px;
+        background: #fff;
+        white-space: pre-wrap;
+        word-break: break-word;
+      }
+
+      .message header {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        margin-bottom: 8px;
+        color: var(--muted);
+        font-size: 12px;
+      }
+
+      .message.user {
+        border-color: #cfe0ff;
+        background: #f7fbff;
+      }
+
+      .message.assistant {
+        border-color: #d6f0df;
+        background: #f6fffa;
+      }
+
+      .message.tool {
+        border-color: #eadfff;
+        background: #fbf8ff;
+      }
+
+      .message.runtime {
+        border-color: #f3debf;
+        background: #fffaf2;
+      }
+
+      .message.error {
+        border-color: #f6d1cb;
+        background: #fff7f5;
+      }
+
+      .badge {
+        display: inline-flex;
+        align-items: center;
+        gap: 6px;
+        border-radius: 999px;
+        padding: 4px 8px;
+        font-size: 11px;
+        background: #eef3f9;
+      }
+
+      .sidebar-section h2 {
+        margin: 0 0 10px;
+        font-size: 14px;
+      }
+
+      .sidebar-section pre,
+      .sidebar-section ul {
+        margin: 0;
+        white-space: pre-wrap;
+        word-break: break-word;
+      }
+
+      .sidebar-section ul {
+        padding-left: 18px;
+      }
+
+      .muted {
+        color: var(--muted);
+      }
+
+      .permission {
+        border-color: #f2d48b;
+        background: #fffbef;
+      }
+
+      @media (max-width: 960px) {
+        .layout {
+          grid-template-columns: 1fr;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <div class="header">
+        <h1>coding-deepgent web ui</h1>
+        <p>Minimal browser shell over the frontend SSE gateway.</p>
+      </div>
+
+      <div class="layout">
+        <section class="panel stack">
+          <div>
+            <label for="thread-id">Thread ID</label>
+            <input id="thread-id" placeholder="Leave blank to auto-generate" />
+          </div>
+          <div>
+            <label for="prompt">Prompt</label>
+            <textarea id="prompt" placeholder="Ask coding-deepgent something..."></textarea>
+          </div>
+          <div class="controls">
+            <button id="send">Run</button>
+            <button id="clear" class="secondary">Clear</button>
+            <span id="run-meta" class="muted"></span>
+          </div>
+          <div id="status" class="status">Ready.</div>
+          <div id="messages" class="message-list"></div>
+        </section>
+
+        <aside class="stack">
+          <section class="panel sidebar-section">
+            <h2>Todo Snapshot</h2>
+            <ul id="todos">
+              <li class="muted">No todos yet.</li>
+            </ul>
+          </section>
+          <section class="panel sidebar-section">
+            <h2>Recovery Brief</h2>
+            <pre id="recovery" class="muted">No recovery brief yet.</pre>
+          </section>
+          <section class="panel sidebar-section">
+            <h2>Permission</h2>
+            <div id="permission" class="muted">No pending permission.</div>
+          </section>
+        </aside>
+      </div>
+    </main>
+
+    <script>
+      const state = {
+        eventSource: null,
+        assistantById: new Map(),
+        pendingPermission: null,
+      };
+
+      const elements = {
+        threadId: document.getElementById("thread-id"),
+        prompt: document.getElementById("prompt"),
+        send: document.getElementById("send"),
+        clear: document.getElementById("clear"),
+        status: document.getElementById("status"),
+        messages: document.getElementById("messages"),
+        todos: document.getElementById("todos"),
+        recovery: document.getElementById("recovery"),
+        permission: document.getElementById("permission"),
+        runMeta: document.getElementById("run-meta"),
+      };
+
+      function setStatus(text) {
+        elements.status.textContent = text;
+      }
+
+      function appendMessage(kind, title, text, meta) {
+        const card = document.createElement("article");
+        card.className = `message ${kind}`;
+        const header = document.createElement("header");
+        const titleNode = document.createElement("strong");
+        titleNode.textContent = title;
+        const metaNode = document.createElement("span");
+        metaNode.textContent = meta || "";
+        header.append(titleNode, metaNode);
+        const body = document.createElement("div");
+        body.textContent = text;
+        card.append(header, body);
+        elements.messages.append(card);
+        card.scrollIntoView({ block: "end" });
+        return body;
+      }
+
+      function upsertAssistant(messageId, text, streaming) {
+        let entry = state.assistantById.get(messageId);
+        if (!entry) {
+          const body = appendMessage("assistant", "Assistant", "", streaming ? "streaming" : "");
+          entry = { body };
+          state.assistantById.set(messageId, entry);
+        }
+        entry.body.textContent = text;
+      }
+
+      function renderTodos(items) {
+        elements.todos.innerHTML = "";
+        if (!items.length) {
+          const li = document.createElement("li");
+          li.className = "muted";
+          li.textContent = "No todos yet.";
+          elements.todos.append(li);
+          return;
+        }
+        for (const item of items) {
+          const li = document.createElement("li");
+          const suffix =
+            item.status === "in_progress" && item.activeForm
+              ? ` (${item.activeForm})`
+              : "";
+          li.textContent = `[${item.status}] ${item.content}${suffix}`;
+          elements.todos.append(li);
+        }
+      }
+
+      function renderPermission(permission) {
+        if (!permission) {
+          elements.permission.className = "muted";
+          elements.permission.textContent = "No pending permission.";
+          return;
+        }
+        elements.permission.className = "message permission";
+        elements.permission.innerHTML = `
+          <header><strong>${permission.tool}</strong><span>pending</span></header>
+          <div>${permission.description}</div>
+          <div class="muted" style="margin-top:10px;">
+            This web shell currently visualizes permission requests only. True runtime HITL gating is not wired yet.
+          </div>
+        `;
+      }
+
+      function handleEvent(eventName, payload) {
+        switch (eventName) {
+          case "metadata":
+            elements.runMeta.textContent = `${payload.run_id} / ${payload.thread_id}`;
+            break;
+          case "session_started":
+            setStatus(`Session started: ${payload.session_id}`);
+            break;
+          case "user_message":
+            appendMessage("user", "You", payload.text);
+            break;
+          case "assistant_delta": {
+            const current = state.assistantById.get(payload.message_id)?.body.textContent || "";
+            upsertAssistant(payload.message_id, current + payload.text, true);
+            setStatus("Streaming assistant output...");
+            break;
+          }
+          case "assistant_message":
+            upsertAssistant(payload.message_id, payload.text, false);
+            break;
+          case "tool_started":
+            appendMessage("tool", `Tool: ${payload.name}`, payload.summary || "started");
+            break;
+          case "tool_finished":
+            appendMessage("tool", `Tool: ${payload.name}`, payload.preview || "completed");
+            break;
+          case "tool_failed":
+            appendMessage("error", `Tool failed: ${payload.name}`, payload.error);
+            break;
+          case "runtime_event":
+            appendMessage(
+              payload.kind.includes("error") ? "error" : "runtime",
+              payload.kind,
+              payload.message
+            );
+            break;
+          case "todo_snapshot":
+            renderTodos(payload.items || []);
+            break;
+          case "recovery_brief":
+            elements.recovery.textContent = payload.text || "";
+            break;
+          case "permission_requested":
+            state.pendingPermission = { ...payload, runId: state.currentRunId };
+            renderPermission(state.pendingPermission);
+            setStatus(`Waiting for permission: ${payload.tool}`);
+            break;
+          case "permission_resolved":
+            appendMessage("runtime", "Permission", payload.message || `Decision: ${payload.decision}`);
+            state.pendingPermission = null;
+            renderPermission(null);
+            break;
+          case "run_failed":
+            appendMessage("error", "Run failed", payload.error);
+            setStatus(`Failed: ${payload.error}`);
+            break;
+          case "run_finished":
+            setStatus(`Run finished: ${payload.status}`);
+            if (state.eventSource) {
+              state.eventSource.close();
+              state.eventSource = null;
+            }
+            break;
+          default:
+            appendMessage("runtime", eventName, JSON.stringify(payload));
+        }
+      }
+
+      async function startRun() {
+        const prompt = elements.prompt.value.trim();
+        const threadId = elements.threadId.value.trim();
+        if (!prompt) {
+          setStatus("Prompt is required.");
+          return;
+        }
+
+        if (state.eventSource) {
+          state.eventSource.close();
+          state.eventSource = null;
+        }
+
+        state.assistantById.clear();
+        state.pendingPermission = null;
+        renderPermission(null);
+        setStatus("Creating run...");
+
+        const response = await fetch("/api/runs", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            prompt,
+            thread_id: threadId || undefined,
+          }),
+        });
+
+        const payload = await response.json();
+        if (!response.ok) {
+          setStatus(payload.detail || "Failed to create run.");
+          return;
+        }
+
+        state.currentRunId = payload.run_id;
+        if (!threadId) {
+          elements.threadId.value = payload.thread_id;
+        }
+        setStatus("Connecting stream...");
+
+        const eventSource = new EventSource(`/api/runs/${payload.run_id}/stream`);
+        state.eventSource = eventSource;
+
+        eventSource.addEventListener("end", () => {
+          setStatus("Stream closed.");
+          eventSource.close();
+        });
+
+        eventSource.onmessage = (messageEvent) => {
+          const payload = JSON.parse(messageEvent.data);
+          handleEvent("message", payload);
+        };
+
+        const namedEvents = [
+          "metadata",
+          "session_started",
+          "user_message",
+          "assistant_delta",
+          "assistant_message",
+          "tool_started",
+          "tool_finished",
+          "tool_failed",
+          "runtime_event",
+          "todo_snapshot",
+          "recovery_brief",
+          "permission_requested",
+          "permission_resolved",
+          "run_finished",
+          "run_failed",
+          "error",
+        ];
+
+        for (const name of namedEvents) {
+          eventSource.addEventListener(name, (messageEvent) => {
+            const payload = JSON.parse(messageEvent.data);
+            handleEvent(name, payload);
+          });
+        }
+
+        eventSource.onerror = () => {
+          setStatus("Stream connection error.");
+        };
+      }
+
+      elements.send.addEventListener("click", startRun);
+      elements.clear.addEventListener("click", () => {
+        elements.messages.innerHTML = "";
+        state.assistantById.clear();
+        renderTodos([]);
+        elements.recovery.textContent = "No recovery brief yet.";
+        renderPermission(null);
+        setStatus("Cleared.");
+      });
+    </script>
+  </body>
+  </html>
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..c8ac6306f
--- /dev/null
+++ b/coding-deepgent/pyproject.toml
@@ -0,0 +1,45 @@
+[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",
+  "redis>=7.0.0",
+  "SQLAlchemy>=2.0.0",
+  "boto3>=1.34.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",
+]
+web = [
+  "fastapi>=0.115.0",
+  "uvicorn>=0.34.0",
+]
+
+[project.scripts]
+coding-deepgent = "coding_deepgent.cli:cli"
+coding-deepgent-ui = "coding_deepgent.cli:ui_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..f715ce494
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/__init__.py
@@ -0,0 +1,20 @@
+"""coding-deepgent public package surface."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+__all__ = ["agent_loop", "build_agent"]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "agent_loop":
+        from .app import agent_loop
+
+        return agent_loop
+    if name == "build_agent":
+        from .app import build_agent
+
+        return build_agent
+    raise AttributeError(name)
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/acceptance.py b/coding-deepgent/src/coding_deepgent/acceptance.py
new file mode 100644
index 000000000..66bdb6725
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/acceptance.py
@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from coding_deepgent.settings import Settings
+
+
+@dataclass(frozen=True, slots=True)
+class AcceptanceCheck:
+    name: str
+    status: str
+    detail: str
+
+
+def circle1_acceptance_checks(settings: Settings) -> tuple[AcceptanceCheck, ...]:
+    return (
+        AcceptanceCheck(
+            name="workflow_a_repository_takeover",
+            status="pass",
+            detail=(
+                "runtime/tool/task/plan CLI surfaces are present; validation remains "
+                "local and deterministic."
+            ),
+        ),
+        AcceptanceCheck(
+            name="workflow_b_long_session_continuity",
+            status="pass",
+            detail=(
+                "sessions inspect/history/projection/timeline/evidence/events/permissions "
+                "surfaces expose resume and context state."
+            ),
+        ),
+        AcceptanceCheck(
+            name="workflow_c_decomposition",
+            status="pass",
+            detail=(
+                "durable tasks/plans and active-TUI background subagent controls are "
+                "available without mailbox/team-runtime."
+            ),
+        ),
+        AcceptanceCheck(
+            name="local_extension_seams",
+            status="pass",
+            detail=(
+                f"skills={settings.skill_dir}; mcp=.mcp.json; "
+                f"hooks=LocalHookRegistry; plugins={settings.plugin_dir}"
+            ),
+        ),
+        AcceptanceCheck(
+            name="circle2_boundaries",
+            status="pass",
+            detail=(
+                "mailbox, coordinator, remote/IDE, daemon/cron, and marketplace "
+                "lifecycle remain outside Circle 1."
+            ),
+        ),
+    )
+
+
+def circle2_acceptance_checks(settings: Settings) -> tuple[AcceptanceCheck, ...]:
+    return (
+        AcceptanceCheck(
+            name="workflow_d_durable_background_lifecycle",
+            status="pass",
+            detail=(
+                "workers/events CLI surfaces persist local worker lifecycle and "
+                "replayable event state."
+            ),
+        ),
+        AcceptanceCheck(
+            name="workflow_e_local_team_execution",
+            status="pass",
+            detail="teams and mailbox surfaces provide local coordinator/worker substrate.",
+        ),
+        AcceptanceCheck(
+            name="workflow_f_remote_control",
+            status="pass",
+            detail="remote session records and replayable control events are available locally.",
+        ),
+        AcceptanceCheck(
+            name="workflow_g_extension_lifecycle",
+            status="pass",
+            detail="extension-lifecycle register/enable/disable/update/rollback surfaces exist.",
+        ),
+        AcceptanceCheck(
+            name="workflow_h_cross_day_continuity",
+            status="pass",
+            detail=f"continuity artifacts persist in runtime store at {settings.store_path}.",
+        ),
+    )
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..679b4edd9
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/agent_loop_service.py
@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from collections.abc import Callable, MutableMapping
+from typing import Any, cast
+
+from coding_deepgent.agent_runtime_service import (
+    invoke_agent,
+    resolve_compiled_agent,
+    session_payload,
+    update_session_state,
+)
+from coding_deepgent.compact import project_messages_with_stats
+from coding_deepgent.containers import AppContainer
+from coding_deepgent.hooks.dispatcher import dispatch_runtime_hook
+from coding_deepgent.memory import (
+    build_long_term_memory_snapshot,
+    runtime_memory_service,
+    write_long_term_memory_snapshot,
+)
+from coding_deepgent.memory.store import MemoryStore
+from coding_deepgent.rendering import latest_assistant_text
+from coding_deepgent.runtime import RuntimeEvent, RuntimeInvocation
+from coding_deepgent.sessions.evidence_events import append_runtime_event_evidence
+from coding_deepgent.sessions.records import SessionContext, TranscriptProjection
+
+
+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,
+    transcript_projection: TranscriptProjection | None = None,
+) -> str:
+    active_container = container or build_container()
+    invocation = build_runtime_invocation(
+        container=active_container,
+        session_id=session_id,
+        session_context=session_context,
+        transcript_projection=transcript_projection,
+    )
+    projection_result = project_messages_with_stats(messages)
+    normalized = projection_result.messages
+    if projection_result.repair_stats.orphan_tombstoned:
+        _emit_agent_event(
+            invocation,
+            kind="orphan_tombstoned",
+            message="Projection repair tombstoned orphaned tool result material.",
+            metadata={
+                "source": "message_projection",
+                "reason": projection_result.repair_stats.reason or "unknown",
+                "tombstoned_count": projection_result.repair_stats.orphan_tombstoned,
+                "message_count": len(normalized),
+            },
+        )
+
+    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
+
+    try:
+        result = invoke_agent(
+            resolve_compiled_agent(active_container, build_agent),
+            {"messages": normalized, **session_payload(session_state)},
+            invocation,
+        )
+    except Exception as exc:
+        _emit_agent_event(
+            invocation,
+            kind="query_error",
+            message="Agent query failed during invoke.",
+            metadata={
+                "source": "agent_loop",
+                "phase": "agent_invoke",
+                "error_class": type(exc).__name__,
+                "retry_count": 0,
+            },
+        )
+        raise
+    update_session_state(session_state, result)
+    memory_service = runtime_memory_service(invocation)
+    final_text = latest_assistant_text(result)
+    if memory_service is not None and final_text:
+        latest_user = normalized[-1]["content"] if normalized else ""
+        memory_service.enqueue_extraction(
+            project_scope=str(invocation.context.workdir),
+            agent_scope=invocation.context.agent_name,
+            source="agent_loop",
+            text=f"User: {latest_user}\n\nAssistant: {final_text}",
+        )
+    write_long_term_memory_snapshot(
+        session_state,
+        build_long_term_memory_snapshot(_runtime_store(active_container)),
+    )
+    if final_text:
+        messages.append({"role": "assistant", "content": final_text})
+    return final_text
+
+
+def _emit_agent_event(
+    invocation: RuntimeInvocation,
+    *,
+    kind: str,
+    message: str,
+    metadata: dict[str, object],
+) -> None:
+    event = RuntimeEvent(
+        kind=kind,
+        message=message,
+        session_id=invocation.context.session_id,
+        metadata=metadata,
+    )
+    invocation.context.event_sink.emit(event)
+    append_runtime_event_evidence(context=invocation.context, event=event)
+
+
+def _runtime_store(active_container: object) -> MemoryStore | None:
+    runtime = getattr(active_container, "runtime", None)
+    if runtime is None:
+        return None
+    store_provider = getattr(runtime, "store", None)
+    if callable(store_provider):
+        return cast(MemoryStore | None, store_provider())
+    return None
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..abc4f585b
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/agent_runtime_service.py
@@ -0,0 +1,67 @@
+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]:
+    payload = {
+        "todos": session_state.get("todos", []),
+        "rounds_since_update": session_state.get("rounds_since_update", 0),
+    }
+    if "long_term_memory" in session_state:
+        payload["long_term_memory"] = session_state["long_term_memory"]
+    if "session_memory" in session_state:
+        payload["session_memory"] = session_state["session_memory"]
+    return payload
+
+
+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),
+        }
+    )
+    if "session_memory" in result:
+        session_state["session_memory"] = result["session_memory"]
+    if "long_term_memory" in result:
+        session_state["long_term_memory"] = result["long_term_memory"]
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..34c1ba42d
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/agent_service.py
@@ -0,0 +1,88 @@
+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.runtime import RuntimeAgentBuildRequest, RuntimeAgentRole
+from coding_deepgent.runtime.agent_factory import create_runtime_agent
+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_runtime_agent(
+        RuntimeAgentBuildRequest(
+            role=RuntimeAgentRole.MAIN,
+            model=model,
+            tools=tools,
+            system_prompt=system_prompt,
+            middleware=middleware,
+            state_schema=state_schema,
+            context_schema=context_schema,
+            checkpointer=checkpointer,
+            store=store,
+            name="coding-deepgent",
+        ),
+        create_agent_factory=create_agent_factory,
+    )
+
+
+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..5e407e6b9
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/app.py
@@ -0,0 +1,69 @@
+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, TranscriptProjection
+
+
+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,
+    transcript_projection: TranscriptProjection | 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,
+        transcript_projection=transcript_projection,
+    )
+
+
+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,
+    transcript_projection: TranscriptProjection | 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,
+        transcript_projection=transcript_projection,
+    )
diff --git a/coding-deepgent/src/coding_deepgent/bootstrap.py b/coding-deepgent/src/coding_deepgent/bootstrap.py
new file mode 100644
index 000000000..74c064898
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/bootstrap.py
@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import replace
+from typing import Any
+
+from dependency_injector import providers
+
+from coding_deepgent.containers import AppContainer
+from coding_deepgent.sessions.records import SessionContext, TranscriptProjection
+
+
+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,
+    transcript_projection: TranscriptProjection | None = None,
+):
+    invocation = container.runtime.invocation(
+        session_id=session_id,
+        session_context=session_context,
+        transcript_projection=transcript_projection,
+        memory_service=container.memory_backend.service(),
+    )
+    system_prompt = container.system_prompt()
+    visible_tool_projection = container.tool_system.capability_registry().project("main")
+    tool_policy = container.tool_system.policy()
+    return replace(
+        invocation,
+        context=replace(
+            invocation.context,
+            rendered_system_prompt=system_prompt,
+            visible_tool_projection=visible_tool_projection,
+            tool_policy=tool_policy,
+        ),
+    )
diff --git a/coding-deepgent/src/coding_deepgent/cli.py b/coding-deepgent/src/coding_deepgent/cli.py
new file mode 100644
index 000000000..8aa93defd
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/cli.py
@@ -0,0 +1,1255 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, cast
+
+import typer
+from click.exceptions import ClickException
+from typer.main import get_command
+
+from coding_deepgent import cli_service
+from coding_deepgent.acceptance import circle1_acceptance_checks, circle2_acceptance_checks
+from coding_deepgent.frontend.bridge import run_stdio_bridge
+from coding_deepgent.logging_config import configure_logging
+from coding_deepgent.memory.backend import MemoryJobStatus, migrate_memory_schema
+from coding_deepgent.memory.schemas import MemoryType
+from coding_deepgent.renderers.text import (
+    render_acceptance_table,
+    render_config_table,
+    render_doctor_table,
+    render_evidence_table,
+    render_extension_table,
+    render_object_detail,
+    render_plan_table,
+    render_session_history_table,
+    render_session_inspect_view,
+    render_session_projection_table,
+    render_session_table,
+    render_session_timeline_table,
+    render_task_table,
+)
+from coding_deepgent.rendering import extract_text
+from coding_deepgent.settings import build_openai_model
+from coding_deepgent.sessions import ProjectionMode, build_session_inspect_view
+from coding_deepgent.sessions.records import TranscriptProjection
+from coding_deepgent.sessions.session_memory import write_session_memory_artifact
+
+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.")
+tasks_app = typer.Typer(help="Inspect and control durable task records.")
+plans_app = typer.Typer(help="Inspect and control durable plan artifacts.")
+skills_app = typer.Typer(help="Inspect and validate local skills.")
+mcp_app = typer.Typer(help="Inspect and validate local MCP configuration.")
+hooks_app = typer.Typer(help="Inspect supported local hook events.")
+plugins_app = typer.Typer(help="Inspect and validate local plugin manifests.")
+acceptance_app = typer.Typer(help="Run deterministic acceptance harnesses.")
+events_app = typer.Typer(help="Inspect and control replayable local events.")
+workers_app = typer.Typer(help="Inspect and control durable local workers.")
+mailbox_app = typer.Typer(help="Send and acknowledge local mailbox messages.")
+teams_app = typer.Typer(help="Inspect and control local team runs.")
+remote_app = typer.Typer(help="Record local remote-control sessions and replay events.")
+lifecycle_app = typer.Typer(help="Manage local extension lifecycle state.")
+continuity_app = typer.Typer(help="Manage cross-day continuity artifacts.")
+memory_app = typer.Typer(help="Manage durable long-term memory backend and jobs.")
+app.add_typer(config_app, name="config")
+app.add_typer(sessions_app, name="sessions")
+app.add_typer(tasks_app, name="tasks")
+app.add_typer(plans_app, name="plans")
+app.add_typer(skills_app, name="skills")
+app.add_typer(mcp_app, name="mcp")
+app.add_typer(hooks_app, name="hooks")
+app.add_typer(plugins_app, name="plugins")
+app.add_typer(acceptance_app, name="acceptance")
+app.add_typer(events_app, name="events")
+app.add_typer(workers_app, name="workers")
+app.add_typer(mailbox_app, name="mailbox")
+app.add_typer(teams_app, name="teams")
+app.add_typer(remote_app, name="remote")
+app.add_typer(lifecycle_app, name="extension-lifecycle")
+app.add_typer(continuity_app, name="continuity")
+app.add_typer(memory_app, name="memory")
+
+
+def agent_loop(*args: Any, **kwargs: Any) -> str:
+    from coding_deepgent.app import agent_loop
+
+    return agent_loop(*args, **kwargs)
+
+
+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,
+    transcript_projection: TranscriptProjection | None = None,
+) -> str:
+    return cli_service.run_once(
+        prompt=prompt,
+        run_agent=agent_loop,
+        history=history,
+        session_state=session_state,
+        session_id=session_id,
+        transcript_projection=transcript_projection,
+        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,
+    transcript_projection: TranscriptProjection | None = None,
+) -> None:
+    runtime = build_cli_runtime()
+    try:
+        result = runtime.run_prompt(
+            prompt,
+            history,
+            session_state,
+            session_id,
+            transcript_projection,
+        )
+    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))
+
+
+@tasks_app.command("list")
+def tasks_list(
+    include_terminal: bool = typer.Option(
+        False,
+        "--all",
+        help="Include completed and cancelled tasks.",
+    ),
+) -> None:
+    settings = build_cli_runtime().settings_loader()
+    records = [
+        record.model_dump()
+        for record in cli_service.task_records(
+            settings,
+            include_terminal=include_terminal,
+        )
+    ]
+    typer.echo(render_task_table(records))
+
+
+@tasks_app.command("get")
+def tasks_get(
+    task_id: str = typer.Argument(..., help="Durable task identifier."),
+) -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        record = cli_service.task_record(settings, task_id)
+    except KeyError as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_object_detail("Task", record.model_dump()))
+
+
+@tasks_app.command("create")
+def tasks_create(
+    title: str = typer.Argument(..., help="Task title."),
+    description: str = typer.Option("", "--description"),
+    depends_on: list[str] | None = typer.Option(
+        None,
+        "--depends-on",
+        help="Repeat to add dependency task ids.",
+    ),
+    owner: str | None = typer.Option(None, "--owner"),
+    metadata: list[str] | None = typer.Option(
+        None,
+        "--metadata",
+        help="Repeat as key=value.",
+    ),
+) -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        record = cli_service.create_task_record(
+            settings,
+            title=title,
+            description=description,
+            depends_on=depends_on,
+            owner=owner,
+            metadata=_metadata_options(metadata),
+        )
+    except ValueError as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_object_detail("Task", record.model_dump()))
+
+
+@tasks_app.command("update")
+def tasks_update(
+    task_id: str = typer.Argument(..., help="Durable task identifier."),
+    status: str | None = typer.Option(None, "--status"),
+    depends_on: list[str] | None = typer.Option(
+        None,
+        "--depends-on",
+        help="Repeat to replace dependencies.",
+    ),
+    owner: str | None = typer.Option(None, "--owner"),
+    metadata: list[str] | None = typer.Option(
+        None,
+        "--metadata",
+        help="Repeat as key=value.",
+    ),
+) -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        record = cli_service.update_task_record(
+            settings,
+            task_id=task_id,
+            status=status,
+            depends_on=depends_on,
+            owner=owner,
+            metadata=_metadata_options(metadata) if metadata is not None else None,
+        )
+    except (KeyError, ValueError) as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_object_detail("Task", record.model_dump()))
+
+
+@plans_app.command("list")
+def plans_list() -> None:
+    settings = build_cli_runtime().settings_loader()
+    records = [record.model_dump() for record in cli_service.plan_records(settings)]
+    typer.echo(render_plan_table(records))
+
+
+@plans_app.command("get")
+def plans_get(
+    plan_id: str = typer.Argument(..., help="Durable plan identifier."),
+) -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        record = cli_service.plan_record(settings, plan_id)
+    except KeyError as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_object_detail("Plan", record.model_dump()))
+
+
+@plans_app.command("save")
+def plans_save(
+    title: str = typer.Argument(..., help="Plan title."),
+    content: str = typer.Option(..., "--content", help="Plan content."),
+    verification: str = typer.Option(
+        ...,
+        "--verification",
+        help="Verification criteria.",
+    ),
+    task_ids: list[str] | None = typer.Option(
+        None,
+        "--task-id",
+        help="Repeat to associate durable tasks.",
+    ),
+    metadata: list[str] | None = typer.Option(
+        None,
+        "--metadata",
+        help="Repeat as key=value.",
+    ),
+) -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        record = cli_service.create_plan_record(
+            settings,
+            title=title,
+            content=content,
+            verification=verification,
+            task_ids=task_ids,
+            metadata=_metadata_options(metadata),
+        )
+    except ValueError as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_object_detail("Plan", record.model_dump()))
+
+
+@skills_app.command("list")
+def skills_list() -> None:
+    settings = build_cli_runtime().settings_loader()
+    typer.echo(render_extension_table("Skills", cli_service.skill_rows(settings)))
+
+
+@skills_app.command("inspect")
+def skills_inspect(name: str = typer.Argument(..., help="Skill name.")) -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        detail = cli_service.skill_detail(settings, name)
+    except (KeyError, ValueError) as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_object_detail("Skill", detail))
+
+
+@skills_app.command("validate")
+def skills_validate() -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        rows = cli_service.skill_rows(settings)
+    except (OSError, ValueError) as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_extension_table("Skills", rows))
+
+
+@skills_app.command("debug")
+def skills_debug(name: str = typer.Argument(..., help="Skill name.")) -> None:
+    skills_inspect(name)
+
+
+@mcp_app.command("list")
+def mcp_list() -> None:
+    settings = build_cli_runtime().settings_loader()
+    typer.echo(render_extension_table("MCP Servers", cli_service.mcp_rows(settings)))
+
+
+@mcp_app.command("inspect")
+def mcp_inspect(name: str = typer.Argument(..., help="MCP server name.")) -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        detail = cli_service.mcp_detail(settings, name)
+    except (KeyError, ValueError) as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_object_detail("MCP Server", detail))
+
+
+@mcp_app.command("validate")
+def mcp_validate() -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        rows = cli_service.mcp_rows(settings)
+    except (OSError, ValueError) as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_extension_table("MCP Servers", rows))
+
+
+@mcp_app.command("debug")
+def mcp_debug(name: str = typer.Argument(..., help="MCP server name.")) -> None:
+    mcp_inspect(name)
+
+
+@hooks_app.command("list")
+def hooks_list() -> None:
+    typer.echo(render_extension_table("Hooks", cli_service.hook_rows()))
+
+
+@hooks_app.command("inspect")
+def hooks_inspect(name: str = typer.Argument(..., help="Hook event name.")) -> None:
+    try:
+        detail = cli_service.hook_detail(name)
+    except KeyError as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_object_detail("Hook", detail))
+
+
+@hooks_app.command("validate")
+def hooks_validate() -> None:
+    typer.echo(render_extension_table("Hooks", cli_service.hook_rows()))
+
+
+@hooks_app.command("debug")
+def hooks_debug(name: str = typer.Argument(..., help="Hook event name.")) -> None:
+    hooks_inspect(name)
+
+
+@plugins_app.command("list")
+def plugins_list() -> None:
+    settings = build_cli_runtime().settings_loader()
+    typer.echo(render_extension_table("Plugins", cli_service.plugin_rows(settings)))
+
+
+@plugins_app.command("inspect")
+def plugins_inspect(name: str = typer.Argument(..., help="Plugin name.")) -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        detail = cli_service.plugin_detail(settings, name)
+    except (KeyError, ValueError) as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_object_detail("Plugin", detail))
+
+
+@plugins_app.command("validate")
+def plugins_validate() -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        rows = cli_service.validate_plugins(settings)
+    except (OSError, ValueError) as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_extension_table("Plugins", rows))
+
+
+@plugins_app.command("debug")
+def plugins_debug(name: str = typer.Argument(..., help="Plugin name.")) -> None:
+    plugins_inspect(name)
+
+
+@acceptance_app.command("circle1")
+def acceptance_circle1() -> None:
+    settings = build_cli_runtime().settings_loader()
+    rows = [
+        {
+            "name": check.name,
+            "status": check.status,
+            "detail": check.detail,
+        }
+        for check in circle1_acceptance_checks(settings)
+    ]
+    typer.echo(render_acceptance_table(rows, title="Circle 1 Acceptance"))
+
+
+@acceptance_app.command("circle2")
+def acceptance_circle2() -> None:
+    settings = build_cli_runtime().settings_loader()
+    rows = [
+        {
+            "name": check.name,
+            "status": check.status,
+            "detail": check.detail,
+        }
+        for check in circle2_acceptance_checks(settings)
+    ]
+    typer.echo(render_acceptance_table(rows, title="Circle 2 Acceptance"))
+
+
+@events_app.command("list")
+def events_list(
+    stream_id: str = typer.Argument(..., help="Event stream identifier."),
+    include_internal: bool = typer.Option(False, "--internal"),
+) -> None:
+    settings = build_cli_runtime().settings_loader()
+    typer.echo(
+        render_extension_table(
+            "Events",
+            cli_service.event_rows(
+                settings,
+                stream_id=stream_id,
+                include_internal=include_internal,
+            ),
+        )
+    )
+
+
+@events_app.command("append")
+def events_append(
+    stream_id: str = typer.Argument(...),
+    kind: str = typer.Argument(...),
+) -> None:
+    settings = build_cli_runtime().settings_loader()
+    typer.echo(render_object_detail("Event", cli_service.append_event_row(settings, stream_id=stream_id, kind=kind)))
+
+
+@events_app.command("ack")
+def events_ack(stream_id: str = typer.Argument(...), event_id: str = typer.Argument(...)) -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        payload = cli_service.ack_event_row(settings, stream_id=stream_id, event_id=event_id)
+    except KeyError as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_object_detail("Event", payload))
+
+
+@workers_app.command("list")
+def workers_list(include_terminal: bool = typer.Option(False, "--all")) -> None:
+    settings = build_cli_runtime().settings_loader()
+    typer.echo(
+        render_extension_table(
+            "Workers",
+            cli_service.worker_rows(settings, include_terminal=include_terminal),
+        )
+    )
+
+
+@workers_app.command("create")
+def workers_create(
+    kind: str = typer.Argument("local"),
+    session_id: str = typer.Option("default", "--session-id"),
+) -> None:
+    settings = build_cli_runtime().settings_loader()
+    typer.echo(render_object_detail("Worker", cli_service.create_worker_row(settings, kind=kind, session_id=session_id)))
+
+
+@workers_app.command("heartbeat")
+def workers_heartbeat(worker_id: str = typer.Argument(...)) -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        payload = cli_service.heartbeat_worker_row(settings, worker_id)
+    except KeyError as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_object_detail("Worker", payload))
+
+
+@workers_app.command("stop")
+def workers_stop(worker_id: str = typer.Argument(...)) -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        payload = cli_service.stop_worker_row(settings, worker_id)
+    except KeyError as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_object_detail("Worker", payload))
+
+
+@workers_app.command("complete")
+def workers_complete(
+    worker_id: str = typer.Argument(...),
+    status: str = typer.Option("completed", "--status"),
+    summary: str | None = typer.Option(None, "--summary"),
+) -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        payload = cli_service.complete_worker_row(
+            settings,
+            worker_id,
+            status=status,
+            summary=summary,
+        )
+    except (KeyError, ValueError) as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_object_detail("Worker", payload))
+
+
+@mailbox_app.command("list")
+def mailbox_list(recipient: str | None = typer.Option(None, "--recipient")) -> None:
+    settings = build_cli_runtime().settings_loader()
+    typer.echo(render_extension_table("Mailbox", cli_service.mailbox_rows(settings, recipient=recipient)))
+
+
+@mailbox_app.command("send")
+def mailbox_send(
+    recipient: str = typer.Argument(...),
+    subject: str = typer.Argument(...),
+    body: str = typer.Argument(...),
+    sender: str = typer.Option("user", "--sender"),
+    delivery_key: str | None = typer.Option(None, "--delivery-key"),
+) -> None:
+    settings = build_cli_runtime().settings_loader()
+    typer.echo(
+        render_object_detail(
+            "Mailbox Message",
+            cli_service.send_mailbox_row(
+                settings,
+                sender=sender,
+                recipient=recipient,
+                subject=subject,
+                body=body,
+                delivery_key=delivery_key,
+            ),
+        )
+    )
+
+
+@mailbox_app.command("ack")
+def mailbox_ack(message_id: str = typer.Argument(...)) -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        payload = cli_service.ack_mailbox_row(settings, message_id)
+    except KeyError as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_object_detail("Mailbox Message", payload))
+
+
+@teams_app.command("list")
+def teams_list() -> None:
+    settings = build_cli_runtime().settings_loader()
+    typer.echo(render_extension_table("Teams", cli_service.team_rows(settings)))
+
+
+@teams_app.command("create")
+def teams_create(title: str = typer.Argument(...)) -> None:
+    settings = build_cli_runtime().settings_loader()
+    typer.echo(render_object_detail("Team", cli_service.create_team_row(settings, title=title)))
+
+
+@teams_app.command("assign")
+def teams_assign(team_id: str = typer.Argument(...), worker_id: str = typer.Argument(...)) -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        payload = cli_service.assign_team_worker_row(settings, team_id=team_id, worker_id=worker_id)
+    except KeyError as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_object_detail("Team", payload))
+
+
+@teams_app.command("progress")
+def teams_progress(team_id: str = typer.Argument(...), message: str = typer.Argument(...)) -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        payload = cli_service.progress_team_row(settings, team_id=team_id, message=message)
+    except KeyError as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_object_detail("Team", payload))
+
+
+@teams_app.command("complete")
+def teams_complete(team_id: str = typer.Argument(...), summary: str = typer.Argument(...)) -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        payload = cli_service.complete_team_row(settings, team_id=team_id, summary=summary)
+    except (KeyError, ValueError) as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_object_detail("Team", payload))
+
+
+@remote_app.command("list")
+def remote_list() -> None:
+    settings = build_cli_runtime().settings_loader()
+    typer.echo(render_extension_table("Remote Sessions", cli_service.remote_rows(settings)))
+
+
+@remote_app.command("register")
+def remote_register(
+    session_id: str = typer.Argument(...),
+    client_name: str = typer.Argument(...),
+) -> None:
+    settings = build_cli_runtime().settings_loader()
+    typer.echo(render_object_detail("Remote Session", cli_service.register_remote_row(settings, session_id=session_id, client_name=client_name)))
+
+
+@remote_app.command("control")
+def remote_control(remote_id: str = typer.Argument(...), command: str = typer.Argument(...)) -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        payload = cli_service.remote_control_row(settings, remote_id=remote_id, command=command)
+    except (KeyError, ValueError) as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_object_detail("Remote Event", payload))
+
+
+@remote_app.command("replay")
+def remote_replay(remote_id: str = typer.Argument(...)) -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        rows = cli_service.remote_replay_rows(settings, remote_id=remote_id)
+    except KeyError as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_extension_table("Remote Events", rows))
+
+
+@remote_app.command("close")
+def remote_close(remote_id: str = typer.Argument(...)) -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        payload = cli_service.close_remote_row(settings, remote_id)
+    except KeyError as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_object_detail("Remote Session", payload))
+
+
+@lifecycle_app.command("list")
+def lifecycle_list() -> None:
+    settings = build_cli_runtime().settings_loader()
+    typer.echo(render_extension_table("Extension Lifecycle", cli_service.lifecycle_rows(settings)))
+
+
+@lifecycle_app.command("register")
+def lifecycle_register(
+    name: str = typer.Argument(...),
+    kind: str = typer.Argument(...),
+    source: str = typer.Argument(...),
+) -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        payload = cli_service.register_lifecycle_row(settings, name=name, kind=kind, source=source)
+    except ValueError as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_object_detail("Extension", payload))
+
+
+@lifecycle_app.command("enable")
+def lifecycle_enable(extension_id: str = typer.Argument(...)) -> None:
+    settings = build_cli_runtime().settings_loader()
+    typer.echo(render_object_detail("Extension", cli_service.set_lifecycle_enabled(settings, extension_id, enabled=True)))
+
+
+@lifecycle_app.command("disable")
+def lifecycle_disable(extension_id: str = typer.Argument(...)) -> None:
+    settings = build_cli_runtime().settings_loader()
+    typer.echo(render_object_detail("Extension", cli_service.set_lifecycle_enabled(settings, extension_id, enabled=False)))
+
+
+@lifecycle_app.command("update")
+def lifecycle_update(extension_id: str = typer.Argument(...), version: str | None = typer.Option(None, "--version")) -> None:
+    settings = build_cli_runtime().settings_loader()
+    typer.echo(render_object_detail("Extension", cli_service.update_lifecycle_row(settings, extension_id, version=version)))
+
+
+@lifecycle_app.command("rollback")
+def lifecycle_rollback(extension_id: str = typer.Argument(...)) -> None:
+    settings = build_cli_runtime().settings_loader()
+    typer.echo(render_object_detail("Extension", cli_service.rollback_lifecycle_row(settings, extension_id)))
+
+
+@continuity_app.command("list")
+def continuity_list(include_stale: bool = typer.Option(False, "--all")) -> None:
+    settings = build_cli_runtime().settings_loader()
+    typer.echo(render_extension_table("Continuity", cli_service.continuity_rows(settings, include_stale=include_stale)))
+
+
+@continuity_app.command("save")
+def continuity_save(
+    title: str = typer.Argument(...),
+    content: str = typer.Argument(...),
+    session_id: str | None = typer.Option(None, "--session-id"),
+) -> None:
+    settings = build_cli_runtime().settings_loader()
+    typer.echo(render_object_detail("Continuity", cli_service.save_continuity_row(settings, title=title, content=content, session_id=session_id)))
+
+
+@continuity_app.command("show")
+def continuity_show(artifact_id: str = typer.Argument(...)) -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        payload = cli_service.continuity_detail(settings, artifact_id)
+    except KeyError as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_object_detail("Continuity", payload))
+
+
+@continuity_app.command("stale")
+def continuity_stale(artifact_id: str = typer.Argument(...)) -> None:
+    settings = build_cli_runtime().settings_loader()
+    try:
+        payload = cli_service.stale_continuity_row(settings, artifact_id)
+    except KeyError as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(render_object_detail("Continuity", payload))
+
+
+@sessions_app.command("inspect")
+def sessions_inspect(
+    session_id: str = typer.Argument(..., help="Session identifier to inspect."),
+    projection_mode: str = typer.Option(
+        "selected",
+        "--projection",
+        help="Projection to inspect: selected, raw, compact, or collapse.",
+    ),
+    limit: int = typer.Option(
+        20,
+        "--limit",
+        min=1,
+        max=200,
+        help="Maximum rows per inspect section.",
+    ),
+    no_recovery: bool = typer.Option(
+        False,
+        "--no-recovery",
+        help="Hide the recovery brief section.",
+    ),
+    no_model: bool = typer.Option(
+        False,
+        "--no-model",
+        help="Hide the model projection section.",
+    ),
+    no_raw: bool = typer.Option(
+        False,
+        "--no-raw",
+        help="Hide the raw transcript visibility section.",
+    ),
+) -> None:
+    runtime = build_cli_runtime()
+    try:
+        loaded = runtime.load_session(session_id)
+        mode = _projection_mode(projection_mode)
+        view = build_session_inspect_view(loaded, projection_mode=mode)
+    except KeyError as exc:
+        raise ClickException(str(exc)) from exc
+    except ValueError as exc:
+        raise ClickException(str(exc)) from exc
+    typer.echo(
+        render_session_inspect_view(
+            view,
+            show_recovery=not no_recovery,
+            show_model=not no_model,
+            show_raw=not no_raw,
+            limit=limit,
+        )
+    )
+
+
+@sessions_app.command("history")
+def sessions_history(
+    session_id: str = typer.Argument(..., help="Session identifier to inspect."),
+    limit: int = typer.Option(50, "--limit", min=1, max=500),
+) -> None:
+    runtime = build_cli_runtime()
+    try:
+        loaded = runtime.load_session(session_id)
+    except KeyError as exc:
+        raise ClickException(str(exc)) from exc
+    view = build_session_inspect_view(loaded, projection_mode="raw")
+    typer.echo(render_session_history_table(view, limit=limit))
+
+
+@sessions_app.command("projection")
+def sessions_projection(
+    session_id: str = typer.Argument(..., help="Session identifier to inspect."),
+    projection_mode: str = typer.Option(
+        "selected",
+        "--projection",
+        help="Projection to inspect: selected, raw, compact, or collapse.",
+    ),
+    limit: int = typer.Option(50, "--limit", min=1, max=500),
+) -> None:
+    runtime = build_cli_runtime()
+    try:
+        loaded = runtime.load_session(session_id)
+        mode = _projection_mode(projection_mode)
+    except (KeyError, ValueError) as exc:
+        raise ClickException(str(exc)) from exc
+    view = build_session_inspect_view(loaded, projection_mode=mode)
+    typer.echo(render_session_projection_table(view, limit=limit))
+
+
+@sessions_app.command("timeline")
+def sessions_timeline(
+    session_id: str = typer.Argument(..., help="Session identifier to inspect."),
+    limit: int = typer.Option(50, "--limit", min=1, max=500),
+) -> None:
+    runtime = build_cli_runtime()
+    try:
+        loaded = runtime.load_session(session_id)
+    except KeyError as exc:
+        raise ClickException(str(exc)) from exc
+    view = build_session_inspect_view(loaded)
+    typer.echo(render_session_timeline_table(view, limit=limit))
+
+
+@sessions_app.command("evidence")
+def sessions_evidence(
+    session_id: str = typer.Argument(..., help="Session identifier to inspect."),
+    kind: str | None = typer.Option(None, "--kind", help="Optional evidence kind."),
+    limit: int = typer.Option(50, "--limit", min=1, max=500),
+) -> None:
+    runtime = build_cli_runtime()
+    try:
+        loaded = runtime.load_session(session_id)
+    except KeyError as exc:
+        raise ClickException(str(exc)) from exc
+    rows = cli_service.session_evidence_rows(loaded, kind=kind)
+    typer.echo(render_evidence_table("Session Evidence", rows, limit=limit))
+
+
+@sessions_app.command("events")
+def sessions_events(
+    session_id: str = typer.Argument(..., help="Session identifier to inspect."),
+    event_kind: str | None = typer.Option(
+        None,
+        "--event-kind",
+        help="Optional runtime event kind metadata filter.",
+    ),
+    limit: int = typer.Option(50, "--limit", min=1, max=500),
+) -> None:
+    runtime = build_cli_runtime()
+    try:
+        loaded = runtime.load_session(session_id)
+    except KeyError as exc:
+        raise ClickException(str(exc)) from exc
+    rows = cli_service.session_evidence_rows(
+        loaded,
+        kind="runtime_event",
+        event_kind=event_kind,
+    )
+    typer.echo(render_evidence_table("Runtime Events", rows, limit=limit))
+
+
+@sessions_app.command("permissions")
+def sessions_permissions(
+    session_id: str = typer.Argument(..., help="Session identifier to inspect."),
+    limit: int = typer.Option(50, "--limit", min=1, max=500),
+) -> None:
+    runtime = build_cli_runtime()
+    try:
+        loaded = runtime.load_session(session_id)
+    except KeyError as exc:
+        raise ClickException(str(exc)) from exc
+    rows = cli_service.permission_evidence_rows(loaded)
+    typer.echo(render_evidence_table("Permission And Hook Events", rows, limit=limit))
+
+
+@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."
+    ),
+    session_memory: str | None = typer.Option(
+        None,
+        "--session-memory",
+        help="Optional explicit session-memory artifact to persist and use for this resumed run.",
+    ),
+    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 (
+            session_memory is not None
+            or
+            compact_summary is not None
+            or generate_compact_summary
+            or compact_instructions is not None
+        ):
+            raise ClickException("session continuation options require --prompt.")
+        typer.echo(cli_service.recovery_brief_text(loaded))
+        typer.echo("Re-run with --prompt to continue.")
+        raise typer.Exit()
+    if session_memory is not None:
+        try:
+            write_session_memory_artifact(
+                loaded.state,
+                content=session_memory,
+                message_count=loaded.summary.message_count,
+            )
+        except ValueError as exc:
+            raise ClickException(str(exc)) from exc
+    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:
+        transcript_projection = None
+        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,
+            )
+            transcript_projection = cli_service.compacted_history_projection(
+                loaded,
+                history,
+            )
+        elif compact_summary is not None:
+            history = cli_service.compacted_continuation_history(
+                loaded,
+                summary=compact_summary,
+                keep_last=compact_keep_last,
+            )
+            transcript_projection = cli_service.compacted_history_projection(
+                loaded,
+                history,
+            )
+        else:
+            history = cli_service.selected_continuation_history(loaded)
+            transcript_projection = cli_service.selected_continuation_projection(
+                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,
+        transcript_projection=transcript_projection,
+    )
+
+
+@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 _projection_mode(value: str) -> ProjectionMode:
+    if value not in {"selected", "raw", "compact", "collapse"}:
+        raise ValueError("projection must be one of: selected, raw, compact, collapse")
+    return cast(ProjectionMode, value)
+
+
+def _metadata_options(values: list[str] | None) -> dict[str, str]:
+    if not values:
+        return {}
+    parsed: dict[str, str] = {}
+    for item in values:
+        key, separator, value = item.partition("=")
+        key = key.strip()
+        value = value.strip()
+        if not separator or not key or not value:
+            raise ValueError("metadata entries must use key=value with non-empty values")
+        parsed[key] = value
+    return parsed
+
+
+@app.command("ui")
+def ui(
+    fake: bool = typer.Option(
+        False,
+        "--fake",
+        help="Start the React/Ink CLI frontend with deterministic fake responses.",
+    ),
+) -> None:
+    raise typer.Exit(_run_frontend_ui(fake=fake))
+
+
+def _frontend_cli_dir() -> Path:
+    return Path(__file__).resolve().parents[2] / "frontend" / "cli"
+
+
+def _run_frontend_ui(*, fake: bool = False) -> int:
+    frontend_dir = _frontend_cli_dir()
+    if not frontend_dir.exists():
+        raise ClickException(f"Frontend CLI package not found: {frontend_dir}")
+    if not (frontend_dir / "package.json").exists():
+        raise ClickException(f"Frontend CLI package.json not found: {frontend_dir}")
+    if not (frontend_dir / "node_modules").exists():
+        raise ClickException(
+            "Frontend CLI dependencies are not installed. "
+            "Run `npm --prefix frontend/cli install` from `coding-deepgent/`."
+        )
+    script = "start:fake" if fake else "start"
+    try:
+        result = subprocess.run(["npm", "run", script], cwd=frontend_dir)
+    except FileNotFoundError as exc:
+        raise ClickException(
+            "npm is required to start the React/Ink CLI frontend."
+        ) from exc
+    return int(result.returncode)
+
+
+@app.command("ui-bridge")
+def ui_bridge(
+    fake: bool = typer.Option(
+        False,
+        "--fake",
+        help="Run the frontend JSONL bridge with deterministic fake responses.",
+    ),
+) -> None:
+    run_stdio_bridge(fake=fake)
+
+
+def _load_ui_gateway_runtime():
+    try:
+        import uvicorn
+        from coding_deepgent.frontend.gateway import create_app
+    except ModuleNotFoundError as exc:
+        raise ClickException(
+            "ui-gateway requires optional web dependencies. Install with `pip install -e .[web]`."
+        ) from exc
+    return create_app, uvicorn.run
+
+
+@app.command("ui-gateway")
+def ui_gateway(
+    fake: bool = typer.Option(
+        False,
+        "--fake",
+        help="Start the frontend SSE gateway with deterministic fake responses.",
+    ),
+    host: str = typer.Option("127.0.0.1", "--host"),
+    port: int = typer.Option(2027, "--port", min=1, max=65535),
+) -> None:
+    create_app, uvicorn_run = _load_ui_gateway_runtime()
+    uvicorn_run(create_app(fake=fake), host=host, port=port)
+
+
+@memory_app.command("migrate")
+def memory_migrate() -> None:
+    from coding_deepgent.app import build_container
+
+    container = build_container()
+    migrate_memory_schema(container.memory_backend.engine())
+    typer.echo("Memory backend schema is ready.")
+
+
+@memory_app.command("jobs")
+def memory_jobs(
+    status: str | None = typer.Option(
+        None, "--status", help="Optional job status filter."
+    ),
+    agent_scope: str | None = typer.Option(
+        None, "--agent-scope", help="Optional agent scope filter."
+    ),
+    job_type: str | None = typer.Option(
+        None, "--job-type", help="Optional job type filter."
+    ),
+    limit: int = typer.Option(20, "--limit", min=1, max=100),
+) -> None:
+    from coding_deepgent.app import build_container
+
+    container = build_container()
+    settings = build_cli_runtime().settings_loader()
+    status_filter = MemoryJobStatus(status) if status is not None else None
+    jobs = container.memory_backend.service().list_jobs(
+        project_scope=str(settings.workdir),
+        agent_scope=agent_scope,
+        job_type=job_type,
+        status=status_filter,
+        limit=limit,
+    )
+    if not jobs:
+        typer.echo("No memory jobs found.")
+        raise typer.Exit()
+    for job in jobs:
+        typer.echo(
+            f"{job.id} {job.job_type} {job.status.value} scope={job.agent_scope or 'global'} dedupe={job.dedupe_key}"
+        )
+
+
+@memory_app.command("records")
+def memory_records(
+    memory_type: str | None = typer.Option(
+        None, "--type", help="Optional memory type filter."
+    ),
+    agent_scope: str | None = typer.Option(
+        None, "--agent-scope", help="Optional agent scope filter."
+    ),
+    limit: int = typer.Option(20, "--limit", min=1, max=100),
+) -> None:
+    from coding_deepgent.app import build_container
+
+    container = build_container()
+    settings = build_cli_runtime().settings_loader()
+    records = container.memory_backend.service().list_records(
+        project_scope=str(settings.workdir),
+        memory_type=cast(MemoryType, memory_type) if memory_type is not None else None,
+        agent_scope=agent_scope,
+        limit=limit,
+    )
+    if not records:
+        typer.echo("No memory records found.")
+        raise typer.Exit()
+    for record in records:
+        typer.echo(
+            f"{record.id} {record.record.type} scope={record.agent_scope or 'global'} status={record.status.value} source={record.source}"
+        )
+
+
+@memory_app.command("agent-scopes")
+def memory_agent_scopes() -> None:
+    from coding_deepgent.app import build_container
+
+    container = build_container()
+    settings = build_cli_runtime().settings_loader()
+    scopes = container.memory_backend.service().list_agent_scopes(
+        project_scope=str(settings.workdir)
+    )
+    if not scopes:
+        typer.echo("No agent memory scopes found.")
+        raise typer.Exit()
+    for scope in scopes:
+        typer.echo(scope)
+
+
+@memory_app.command("worker-run-once")
+def memory_worker_run_once() -> None:
+    from coding_deepgent.app import build_container
+
+    container = build_container()
+    job = container.memory_backend.service().process_next_job()
+    if job is None:
+        typer.echo("No memory job available.")
+        raise typer.Exit()
+    typer.echo(f"Processed memory job {job.id} -> {job.status.value}")
+
+
+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)
+
+
+def ui_cli(argv: list[str] | None = None) -> int:
+    args = sys.argv[1:] if argv is None else argv
+    return main(["ui", *args])
+
+
+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..c7f76a92d
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/cli_service.py
@@ -0,0 +1,1053 @@
+from __future__ import annotations
+
+import importlib.util
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Sequence, cast
+
+from langchain.agents import create_agent
+
+from coding_deepgent import bootstrap
+from coding_deepgent.compact import (
+    compact_metadata,
+    compact_messages_with_summary,
+    generate_compact_summary,
+)
+from coding_deepgent.continuity import (
+    get_artifact,
+    list_artifacts,
+    mark_stale,
+    save_artifact,
+)
+from coding_deepgent.event_stream import (
+    ack_event,
+    append_event,
+    list_events,
+)
+from coding_deepgent.extension_lifecycle import (
+    disable_extension,
+    enable_extension,
+    list_extensions,
+    register_extension,
+    rollback_extension,
+    update_extension,
+)
+from coding_deepgent.extension_lifecycle.store import ExtensionKind
+from coding_deepgent.logging_config import safe_environment_snapshot
+from coding_deepgent.mailbox import (
+    ack_message,
+    list_messages,
+    send_message,
+)
+from coding_deepgent.mcp import langchain_mcp_adapters_available, load_local_mcp_config
+from coding_deepgent.plugins import PluginRegistry, discover_local_plugins
+from coding_deepgent.remote import (
+    close_remote_session,
+    list_remote_sessions,
+    register_remote_session,
+    replay_remote_events,
+    send_remote_control,
+)
+from coding_deepgent.settings import Settings, load_settings
+from coding_deepgent.settings import build_openai_model as build_model
+from coding_deepgent.skills import discover_local_skills
+from coding_deepgent.hooks import HookEventName
+from coding_deepgent.teams import (
+    assign_worker,
+    complete_team,
+    create_team,
+    list_teams,
+    update_progress,
+)
+from coding_deepgent.tasks import (
+    PlanArtifact,
+    TaskStatus,
+    TaskRecord,
+    create_plan,
+    create_task,
+    get_plan,
+    get_task,
+    list_plans,
+    list_tasks,
+    update_task,
+)
+from coding_deepgent.tasks.store import TaskStore
+from coding_deepgent.worker_runtime import (
+    complete_worker,
+    create_worker,
+    heartbeat_worker,
+    list_workers,
+    request_worker_stop,
+)
+from coding_deepgent.worker_runtime.store import WorkerStatus
+from coding_deepgent.sessions import (
+    LoadedSession,
+    SessionLoadError,
+    SessionMessage,
+    SessionEvidence,
+    TranscriptProjection,
+    build_recovery_brief,
+    build_resume_context_message,
+    render_recovery_brief,
+)
+from coding_deepgent.sessions.contribution_registry import (
+    COMPACT_ASSIST_CONTRIBUTIONS,
+    COMPACT_SUMMARY_UPDATE_CONTRIBUTIONS,
+)
+from coding_deepgent.sessions.contributions import (
+    apply_compact_summary_update_contributions,
+    compact_assist_text,
+)
+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,
+            TranscriptProjection | 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("store_backend", "resolved", settings.store_backend),
+        DoctorCheck("store_path", "ready", str(settings.store_path)),
+        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 session_evidence_rows(
+    loaded: LoadedSession,
+    *,
+    kind: str | None = None,
+    event_kind: str | None = None,
+) -> list[dict[str, Any]]:
+    rows = [_evidence_row(item) for item in loaded.evidence]
+    if kind is not None:
+        rows = [row for row in rows if row["kind"] == kind]
+    if event_kind is not None:
+        rows = [
+            row
+            for row in rows
+            if isinstance(row.get("metadata"), dict)
+            and row["metadata"].get("event_kind") == event_kind
+        ]
+    return rows
+
+
+def permission_evidence_rows(loaded: LoadedSession) -> list[dict[str, Any]]:
+    rows = session_evidence_rows(loaded, kind="runtime_event")
+    return [
+        row
+        for row in rows
+        if isinstance(row.get("metadata"), dict)
+        and row["metadata"].get("event_kind") in {"permission_denied", "hook_blocked"}
+    ]
+
+
+def _evidence_row(item: SessionEvidence) -> dict[str, Any]:
+    return {
+        "kind": item.kind,
+        "summary": item.summary,
+        "status": item.status,
+        "created_at": item.created_at,
+        "subject": item.subject,
+        "metadata": item.metadata or {},
+    }
+
+
+def skill_rows(settings: Settings) -> list[dict[str, Any]]:
+    return [
+        {
+            "name": skill.metadata.name,
+            "status": "valid",
+            "description": skill.metadata.description,
+            "path": str(skill.path),
+        }
+        for skill in discover_local_skills(
+            workdir=settings.workdir,
+            skill_dir=settings.skill_dir,
+        )
+    ]
+
+
+def skill_detail(settings: Settings, name: str) -> dict[str, Any]:
+    for row in skill_rows(settings):
+        if row["name"] == name:
+            return row
+    raise KeyError(f"Unknown skill: {name}")
+
+
+def mcp_rows(settings: Settings) -> list[dict[str, Any]]:
+    loaded = load_local_mcp_config(workdir=settings.workdir)
+    if loaded is None:
+        return []
+    return [
+        {
+            "name": name,
+            "status": "configured",
+            "description": f"{server.transport}",
+            "path": str(loaded.path),
+        }
+        for name, server in loaded.config.mcpServers.items()
+    ]
+
+
+def mcp_detail(settings: Settings, name: str) -> dict[str, Any]:
+    loaded = load_local_mcp_config(workdir=settings.workdir)
+    if loaded is None:
+        raise KeyError(f"Unknown MCP server: {name}")
+    server = loaded.config.mcpServers.get(name)
+    if server is None:
+        raise KeyError(f"Unknown MCP server: {name}")
+    return {
+        "name": name,
+        "status": "configured",
+        "transport": server.transport,
+        "command": server.command,
+        "args": list(server.args),
+        "url": server.url,
+        "path": str(loaded.path),
+        "adapter_available": langchain_mcp_adapters_available(),
+    }
+
+
+def hook_rows() -> list[dict[str, Any]]:
+    events: tuple[HookEventName, ...] = (
+        "SessionStart",
+        "UserPromptSubmit",
+        "PreToolUse",
+        "PostToolUse",
+        "PermissionDenied",
+        "PreCompact",
+        "PostCompact",
+    )
+    return [
+        {
+            "name": event,
+            "status": "supported",
+            "description": "local sync hook event",
+            "path": "runtime LocalHookRegistry",
+        }
+        for event in events
+    ]
+
+
+def hook_detail(name: str) -> dict[str, Any]:
+    for row in hook_rows():
+        if row["name"] == name:
+            return row
+    raise KeyError(f"Unknown hook event: {name}")
+
+
+def plugin_rows(settings: Settings) -> list[dict[str, Any]]:
+    return [
+        {
+            "name": plugin.manifest.name,
+            "status": "valid",
+            "description": plugin.manifest.description,
+            "path": str(plugin.path),
+        }
+        for plugin in discover_local_plugins(
+            workdir=settings.workdir,
+            plugin_dir=settings.plugin_dir,
+        )
+    ]
+
+
+def plugin_detail(settings: Settings, name: str) -> dict[str, Any]:
+    for plugin in discover_local_plugins(
+        workdir=settings.workdir,
+        plugin_dir=settings.plugin_dir,
+    ):
+        if plugin.manifest.name == name:
+            return {
+                "name": plugin.manifest.name,
+                "description": plugin.manifest.description,
+                "version": plugin.manifest.version,
+                "skills": list(plugin.manifest.skills),
+                "tools": list(plugin.manifest.tools),
+                "resources": list(plugin.manifest.resources),
+                "agents": list(plugin.manifest.agents),
+                "path": str(plugin.path),
+            }
+    raise KeyError(f"Unknown plugin: {name}")
+
+
+def validate_plugins(settings: Settings) -> list[dict[str, Any]]:
+    plugins = discover_local_plugins(
+        workdir=settings.workdir,
+        plugin_dir=settings.plugin_dir,
+    )
+    registry = PluginRegistry(plugins)
+    container = _build_container_for_settings(settings)
+    known_tools = set(container.capability_registry().names())
+    known_skills = {
+        row["name"]
+        for row in skill_rows(settings)
+        if isinstance(row.get("name"), str)
+    }
+    registry.validate(known_tools=known_tools, known_skills=known_skills)
+    return [
+        {
+            "name": item.plugin_name,
+            "status": "valid",
+            "description": f"tools={len(item.tools)} skills={len(item.skills)} resources={len(item.resources)} agents={len(item.agents)}",
+            "path": "",
+        }
+        for item in registry.declarations()
+    ]
+
+
+def event_rows(
+    settings: Settings,
+    *,
+    stream_id: str,
+    include_internal: bool = False,
+) -> list[dict[str, Any]]:
+    return [
+        {
+            "name": event.event_id,
+            "status": event.kind,
+            "description": f"seq={event.sequence} acked={event.acked}",
+            "path": event.stream_id,
+        }
+        for event in list_events(
+            cast(Any, _runtime_store(settings)),
+            stream_id=stream_id,
+            include_internal=include_internal,
+        )
+    ]
+
+
+def append_event_row(settings: Settings, *, stream_id: str, kind: str) -> dict[str, Any]:
+    event = append_event(
+        cast(Any, _runtime_store(settings)),
+        stream_id=stream_id,
+        kind=kind,
+    )
+    return {
+        "event_id": event.event_id,
+        "stream_id": event.stream_id,
+        "sequence": event.sequence,
+        "kind": event.kind,
+    }
+
+
+def ack_event_row(settings: Settings, *, stream_id: str, event_id: str) -> dict[str, Any]:
+    event = ack_event(
+        cast(Any, _runtime_store(settings)),
+        stream_id=stream_id,
+        event_id=event_id,
+    )
+    return event.model_dump()
+
+
+def worker_rows(settings: Settings, *, include_terminal: bool = False) -> list[dict[str, Any]]:
+    return [
+        {
+            "name": worker.worker_id,
+            "status": worker.status,
+            "description": f"{worker.kind} session={worker.session_id} stop={worker.stop_requested}",
+            "path": worker.owner or "-",
+        }
+        for worker in list_workers(
+            cast(Any, _runtime_store(settings)),
+            include_terminal=include_terminal,
+        )
+    ]
+
+
+def create_worker_row(settings: Settings, *, kind: str, session_id: str = "default") -> dict[str, Any]:
+    return create_worker(
+        cast(Any, _runtime_store(settings)),
+        kind=kind,
+        session_id=session_id,
+    ).model_dump()
+
+
+def heartbeat_worker_row(settings: Settings, worker_id: str) -> dict[str, Any]:
+    return heartbeat_worker(cast(Any, _runtime_store(settings)), worker_id).model_dump()
+
+
+def stop_worker_row(settings: Settings, worker_id: str) -> dict[str, Any]:
+    return request_worker_stop(cast(Any, _runtime_store(settings)), worker_id).model_dump()
+
+
+def complete_worker_row(
+    settings: Settings,
+    worker_id: str,
+    *,
+    status: str,
+    summary: str | None = None,
+) -> dict[str, Any]:
+    return complete_worker(
+        cast(Any, _runtime_store(settings)),
+        worker_id,
+        status=cast(WorkerStatus, status),
+        result_summary=summary,
+    ).model_dump()
+
+
+def mailbox_rows(settings: Settings, *, recipient: str | None = None) -> list[dict[str, Any]]:
+    return [
+        {
+            "name": message.message_id,
+            "status": message.status,
+            "description": f"{message.sender} -> {message.recipient}: {message.subject}",
+            "path": message.delivery_key or "-",
+        }
+        for message in list_messages(cast(Any, _runtime_store(settings)), recipient=recipient)
+    ]
+
+
+def send_mailbox_row(
+    settings: Settings,
+    *,
+    sender: str,
+    recipient: str,
+    subject: str,
+    body: str,
+    delivery_key: str | None = None,
+) -> dict[str, Any]:
+    return send_message(
+        cast(Any, _runtime_store(settings)),
+        sender=sender,
+        recipient=recipient,
+        subject=subject,
+        body=body,
+        delivery_key=delivery_key,
+    ).model_dump()
+
+
+def ack_mailbox_row(settings: Settings, message_id: str) -> dict[str, Any]:
+    return ack_message(cast(Any, _runtime_store(settings)), message_id).model_dump()
+
+
+def team_rows(settings: Settings) -> list[dict[str, Any]]:
+    return [
+        {
+            "name": team.team_id,
+            "status": team.status,
+            "description": f"{team.title} workers={len(team.worker_ids)}",
+            "path": team.coordinator,
+        }
+        for team in list_teams(cast(Any, _runtime_store(settings)))
+    ]
+
+
+def create_team_row(settings: Settings, *, title: str) -> dict[str, Any]:
+    return create_team(cast(Any, _runtime_store(settings)), title=title).model_dump()
+
+
+def assign_team_worker_row(settings: Settings, *, team_id: str, worker_id: str) -> dict[str, Any]:
+    return assign_worker(
+        cast(Any, _runtime_store(settings)),
+        team_id=team_id,
+        worker_id=worker_id,
+    ).model_dump()
+
+
+def progress_team_row(settings: Settings, *, team_id: str, message: str) -> dict[str, Any]:
+    return update_progress(
+        cast(Any, _runtime_store(settings)),
+        team_id=team_id,
+        message=message,
+    ).model_dump()
+
+
+def complete_team_row(settings: Settings, *, team_id: str, summary: str) -> dict[str, Any]:
+    return complete_team(
+        cast(Any, _runtime_store(settings)),
+        team_id=team_id,
+        summary=summary,
+    ).model_dump()
+
+
+def remote_rows(settings: Settings) -> list[dict[str, Any]]:
+    return [
+        {
+            "name": remote.remote_id,
+            "status": remote.status,
+            "description": f"session={remote.session_id} client={remote.client_name}",
+            "path": f"last_seq={remote.last_sequence_sent}",
+        }
+        for remote in list_remote_sessions(cast(Any, _runtime_store(settings)))
+    ]
+
+
+def register_remote_row(settings: Settings, *, session_id: str, client_name: str) -> dict[str, Any]:
+    return register_remote_session(
+        cast(Any, _runtime_store(settings)),
+        session_id=session_id,
+        client_name=client_name,
+    ).model_dump()
+
+
+def remote_control_row(settings: Settings, *, remote_id: str, command: str) -> dict[str, Any]:
+    return send_remote_control(
+        cast(Any, _runtime_store(settings)),
+        remote_id=remote_id,
+        command=command,
+    ).model_dump()
+
+
+def remote_replay_rows(settings: Settings, *, remote_id: str) -> list[dict[str, Any]]:
+    return [
+        {
+            "name": event.event_id,
+            "status": event.kind,
+            "description": f"seq={event.sequence}",
+            "path": event.stream_id,
+        }
+        for event in replay_remote_events(cast(Any, _runtime_store(settings)), remote_id=remote_id)
+    ]
+
+
+def close_remote_row(settings: Settings, remote_id: str) -> dict[str, Any]:
+    return close_remote_session(cast(Any, _runtime_store(settings)), remote_id).model_dump()
+
+
+def lifecycle_rows(settings: Settings) -> list[dict[str, Any]]:
+    return [
+        {
+            "name": item.extension_id,
+            "status": item.status,
+            "description": f"{item.kind}:{item.name}",
+            "path": item.source,
+        }
+        for item in list_extensions(cast(Any, _runtime_store(settings)))
+    ]
+
+
+def register_lifecycle_row(
+    settings: Settings,
+    *,
+    name: str,
+    kind: str,
+    source: str,
+) -> dict[str, Any]:
+    return register_extension(
+        cast(Any, _runtime_store(settings)),
+        name=name,
+        kind=cast(ExtensionKind, kind),
+        source=source,
+    ).model_dump()
+
+
+def set_lifecycle_enabled(settings: Settings, extension_id: str, *, enabled: bool) -> dict[str, Any]:
+    store = cast(Any, _runtime_store(settings))
+    return (
+        enable_extension(store, extension_id)
+        if enabled
+        else disable_extension(store, extension_id)
+    ).model_dump()
+
+
+def update_lifecycle_row(settings: Settings, extension_id: str, *, version: str | None) -> dict[str, Any]:
+    return update_extension(
+        cast(Any, _runtime_store(settings)),
+        extension_id,
+        version=version,
+    ).model_dump()
+
+
+def rollback_lifecycle_row(settings: Settings, extension_id: str) -> dict[str, Any]:
+    return rollback_extension(cast(Any, _runtime_store(settings)), extension_id).model_dump()
+
+
+def continuity_rows(settings: Settings, *, include_stale: bool = False) -> list[dict[str, Any]]:
+    return [
+        {
+            "name": item.artifact_id,
+            "status": item.status,
+            "description": item.title,
+            "path": item.session_id or "-",
+        }
+        for item in list_artifacts(cast(Any, _runtime_store(settings)), include_stale=include_stale)
+    ]
+
+
+def save_continuity_row(
+    settings: Settings,
+    *,
+    title: str,
+    content: str,
+    session_id: str | None = None,
+) -> dict[str, Any]:
+    return save_artifact(
+        cast(Any, _runtime_store(settings)),
+        title=title,
+        content=content,
+        session_id=session_id,
+    ).model_dump()
+
+
+def continuity_detail(settings: Settings, artifact_id: str) -> dict[str, Any]:
+    return get_artifact(cast(Any, _runtime_store(settings)), artifact_id).model_dump()
+
+
+def stale_continuity_row(settings: Settings, artifact_id: str) -> dict[str, Any]:
+    return mark_stale(cast(Any, _runtime_store(settings)), artifact_id).model_dump()
+
+
+def task_records(
+    settings: Settings,
+    *,
+    include_terminal: bool = False,
+) -> list[TaskRecord]:
+    return list_tasks(
+        cast(TaskStore, _runtime_store(settings)),
+        include_terminal=include_terminal,
+    )
+
+
+def task_record(settings: Settings, task_id: str) -> TaskRecord:
+    return get_task(cast(TaskStore, _runtime_store(settings)), task_id)
+
+
+def create_task_record(
+    settings: Settings,
+    *,
+    title: str,
+    description: str = "",
+    depends_on: list[str] | None = None,
+    owner: str | None = None,
+    metadata: dict[str, str] | None = None,
+) -> TaskRecord:
+    return create_task(
+        cast(TaskStore, _runtime_store(settings)),
+        title=title,
+        description=description,
+        depends_on=depends_on,
+        owner=owner,
+        metadata=metadata,
+    )
+
+
+def update_task_record(
+    settings: Settings,
+    *,
+    task_id: str,
+    status: str | None = None,
+    depends_on: list[str] | None = None,
+    owner: str | None = None,
+    metadata: dict[str, str] | None = None,
+) -> TaskRecord:
+    return update_task(
+        cast(TaskStore, _runtime_store(settings)),
+        task_id=task_id,
+        status=cast(TaskStatus | None, status),
+        depends_on=depends_on,
+        owner=owner,
+        metadata=metadata,
+    )
+
+
+def plan_records(settings: Settings) -> list[PlanArtifact]:
+    return list_plans(cast(TaskStore, _runtime_store(settings)))
+
+
+def plan_record(settings: Settings, plan_id: str) -> PlanArtifact:
+    return get_plan(cast(TaskStore, _runtime_store(settings)), plan_id)
+
+
+def create_plan_record(
+    settings: Settings,
+    *,
+    title: str,
+    content: str,
+    verification: str,
+    task_ids: list[str] | None = None,
+    metadata: dict[str, str] | None = None,
+) -> PlanArtifact:
+    return create_plan(
+        cast(TaskStore, _runtime_store(settings)),
+        title=title,
+        content=content,
+        verification=verification,
+        task_ids=task_ids,
+        metadata=metadata,
+    )
+
+
+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,
+    transcript_projection: TranscriptProjection | 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,
+        transcript_projection=transcript_projection,
+    )
+
+
+def recovery_brief_text(loaded: LoadedSession) -> str:
+    return render_recovery_brief(build_recovery_brief(loaded))
+
+
+def _conversation_messages(messages: Sequence[SessionMessage]) -> list[dict[str, Any]]:
+    return [message.as_conversation_dict() for message in messages]
+
+
+def _project_transcript_projection(
+    messages: list[dict[str, Any]],
+    entry_ids: list[tuple[str, ...]],
+) -> TranscriptProjection:
+    projected_messages: list[dict[str, Any]] = []
+    projected_ids: list[tuple[str, ...]] = []
+    for message, ids in zip(messages, entry_ids, strict=True):
+        normalized = {"role": message.get("role", "user"), "content": message.get("content", "")}
+        if "metadata" in message:
+            normalized["metadata"] = message["metadata"]
+        if projected_messages and projected_messages[-1].get("role") == normalized.get("role") and isinstance(projected_messages[-1].get("content"), str) and isinstance(normalized.get("content"), str) and set(projected_messages[-1].keys()) == {"role", "content"} and set(normalized.keys()) == {"role", "content"}:
+            projected_messages[-1]["content"] = (
+                f"{projected_messages[-1]['content']}\n\n{normalized['content']}"
+            )
+            projected_ids[-1] = (*projected_ids[-1], *ids)
+            continue
+        projected_messages.append(normalized)
+        projected_ids.append(ids)
+    return TranscriptProjection(entries=tuple(projected_ids))
+
+
+def continuation_projection(loaded: LoadedSession) -> TranscriptProjection:
+    messages = continuation_history(loaded)
+    return _project_transcript_projection(
+        messages,
+        [()] + [(message.message_id,) for message in loaded.history],
+    )
+
+
+def selected_continuation_projection(loaded: LoadedSession) -> TranscriptProjection:
+    if loaded.collapsed_history_source.mode == "collapse":
+        return _collapsed_projection(loaded, selected_continuation_history(loaded))
+    if loaded.compacted_history_source.mode != "compact":
+        return continuation_projection(loaded)
+    compact = loaded.compacts[loaded.compacted_history_source.compact_index or 0]
+    return _compacted_projection_from_end_message_id(
+        loaded,
+        end_message_id=compact.end_message_id,
+        messages=selected_continuation_history(loaded),
+    )
+
+
+def compacted_history_projection(
+    loaded: LoadedSession,
+    history: list[dict[str, Any]],
+) -> TranscriptProjection:
+    if len(history) < 3:
+        return continuation_projection(loaded)
+    boundary = compact_metadata(history[1])
+    if boundary is None:
+        return continuation_projection(loaded)
+    end_message_id = boundary.get("end_message_id")
+    if not isinstance(end_message_id, str) or not end_message_id.strip():
+        return continuation_projection(loaded)
+    return _compacted_projection_from_end_message_id(
+        loaded,
+        end_message_id=end_message_id.strip(),
+        messages=history,
+    )
+
+
+def _compacted_projection_from_end_message_id(
+    loaded: LoadedSession,
+    *,
+    end_message_id: str,
+    messages: list[dict[str, Any]],
+) -> TranscriptProjection:
+    message_index_by_id = {
+        message.message_id: index for index, message in enumerate(loaded.history)
+    }
+    end_index = message_index_by_id.get(end_message_id, -1)
+    tail_entries = [
+        (message.message_id,) for message in loaded.history[end_index + 1 :]
+    ]
+    return _project_transcript_projection(
+        messages,
+        [(), (), *([()] if len(messages) > 2 else []), *tail_entries],
+    )
+
+
+def continuation_history(loaded: LoadedSession) -> list[dict[str, Any]]:
+    return [
+        build_resume_context_message(loaded),
+        *_conversation_messages(loaded.history),
+    ]
+
+
+def selected_continuation_history(loaded: LoadedSession) -> list[dict[str, Any]]:
+    if loaded.collapsed_history_source.mode == "collapse":
+        return [
+            build_resume_context_message(loaded),
+            *[dict(message) for message in loaded.collapsed_history],
+        ]
+    return [
+        build_resume_context_message(loaded),
+        *[dict(message) for message in loaded.compacted_history],
+    ]
+
+
+def _collapsed_projection(
+    loaded: LoadedSession,
+    messages: list[dict[str, Any]],
+) -> TranscriptProjection:
+    selected = _selected_collapse_spans(loaded)
+    if not selected:
+        return continuation_projection(loaded)
+    entries: list[tuple[str, ...]] = []
+    cursor = 0
+    for start_index, end_index, _collapse_index in selected:
+        entries.extend(
+            (message.message_id,) for message in loaded.history[cursor:start_index]
+        )
+        entries.extend(((), ()))
+        cursor = end_index + 1
+    entries.extend((message.message_id,) for message in loaded.history[cursor:])
+    return _project_transcript_projection(messages, [(), *entries])
+
+
+def _selected_collapse_spans(
+    loaded: LoadedSession,
+) -> list[tuple[int, int, int]]:
+    id_to_index = {
+        message.message_id: index for index, message in enumerate(loaded.history)
+    }
+    selected: list[tuple[int, int, int]] = []
+    covered_indexes: set[int] = set()
+    for collapse_index in range(len(loaded.collapses) - 1, -1, -1):
+        collapse = loaded.collapses[collapse_index]
+        start_index = id_to_index.get(collapse.start_message_id)
+        end_index = id_to_index.get(collapse.end_message_id)
+        if start_index is None or end_index is None or end_index < start_index:
+            continue
+        covered_slice = tuple(
+            message.message_id
+            for message in loaded.history[start_index : end_index + 1]
+        )
+        if (
+            collapse.covered_message_ids is not None
+            and collapse.covered_message_ids != covered_slice
+        ):
+            continue
+        span_indexes = set(range(start_index, end_index + 1))
+        if covered_indexes & span_indexes:
+            continue
+        covered_indexes.update(span_indexes)
+        selected.append((start_index, end_index, collapse_index))
+    return sorted(selected, key=lambda item: item[0])
+
+
+def compacted_continuation_history(
+    loaded: LoadedSession,
+    *,
+    summary: str,
+    keep_last: int = 4,
+) -> list[dict[str, Any]]:
+    artifact = compact_messages_with_summary(
+        _conversation_messages(loaded.history),
+        summary=summary,
+        keep_last=keep_last,
+    )
+    covered_messages = list(loaded.history[: artifact.summarized_message_count])
+    if covered_messages:
+        artifact.messages[0]["metadata"]["coding_deepgent_compact"]["start_message_id"] = covered_messages[0].message_id
+        artifact.messages[0]["metadata"]["coding_deepgent_compact"]["end_message_id"] = covered_messages[-1].message_id
+        artifact.messages[0]["metadata"]["coding_deepgent_compact"]["covered_message_ids"] = [
+            message.message_id for message in covered_messages
+        ]
+    return [
+        build_resume_context_message(loaded),
+        *artifact.messages,
+    ]
+
+
+def compacted_continuation_projection(
+    loaded: LoadedSession,
+    *,
+    summary: str,
+    keep_last: int = 4,
+) -> TranscriptProjection:
+    artifact = compact_messages_with_summary(
+        _conversation_messages(loaded.history),
+        summary=summary,
+        keep_last=keep_last,
+    )
+    tail_entries = [
+        (message.message_id,)
+        for message in loaded.history[artifact.summarized_message_count :]
+    ]
+    messages = [
+        build_resume_context_message(loaded),
+        *artifact.messages,
+    ]
+    return _project_transcript_projection(
+        messages,
+        [(), (), (), *tail_entries],
+    )
+
+
+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(
+        _conversation_messages(loaded.history),
+        summarizer,
+        custom_instructions=custom_instructions,
+        assist_context=compact_assist_text(loaded, COMPACT_ASSIST_CONTRIBUTIONS),
+    )
+    apply_compact_summary_update_contributions(
+        loaded,
+        summary=summary,
+        contributions=COMPACT_SUMMARY_UPDATE_CONTRIBUTIONS,
+    )
+    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, transcript_projection: run_once(
+            settings=active_settings_loader(),
+            prompt=prompt,
+            run_agent=run_agent,
+            history=history,
+            session_state=session_state,
+            session_id=session_id,
+            transcript_projection=transcript_projection,
+        ),
+        doctor_checks=lambda: doctor_checks(active_settings_loader()),
+    )
+
+
+def _runtime_store(settings: Settings) -> object:
+    container = _build_container_for_settings(settings)
+    store = container.runtime.store()
+    if store is None:
+        raise RuntimeError("Runtime store is not configured")
+    return store
+
+
+def _build_container_for_settings(settings: Settings):
+    container = bootstrap.build_container(
+        settings_loader=lambda: settings,
+        model_factory=build_model,
+        create_agent_factory=create_agent,
+    )
+    bootstrap.validate_container_startup(container=container)
+    return container
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..092d5f083
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/compact/__init__.py
@@ -0,0 +1,163 @@
+from .budget import BudgetedText, TRUNCATION_MARKER, apply_tool_result_budget
+from .artifacts import (
+    COLLAPSE_BOUNDARY_PREFIX,
+    COLLAPSE_METADATA_KEY,
+    COLLAPSE_SUMMARY_PREFIX,
+    COMPACT_BOUNDARY_PREFIX,
+    COMPACT_METADATA_KEY,
+    COMPACT_SUMMARY_PREFIX,
+    CompactArtifact,
+    build_collapse_boundary_message,
+    build_collapse_summary_message,
+    compact_metadata,
+    compact_messages_with_summary,
+    compact_record_from_messages,
+    format_compact_summary,
+    is_compact_artifact_message,
+)
+from .projection import (
+    ORPHAN_TOOL_RESULT_TOMBSTONE,
+    ProjectMessagesResult,
+    ProjectionRepairStats,
+    project_messages,
+    project_messages_with_stats,
+)
+from .runtime_pressure import (
+    DEFAULT_AUTO_COMPACT_THRESHOLD_TOKENS,
+    DEFAULT_COLLAPSE_THRESHOLD_TOKENS,
+    DEFAULT_KEEP_RECENT_TOOL_RESULTS,
+    DEFAULT_KEEP_RECENT_MESSAGES,
+    DEFAULT_KEEP_RECENT_MESSAGES_AFTER_COLLAPSE,
+    DEFAULT_KEEP_RECENT_MESSAGES_AFTER_SNIP,
+    DEFAULT_MICROCOMPACT_MIN_CONTENT_CHARS,
+    DEFAULT_MICROCOMPACT_MIN_PRUNE_SAVED_TOKENS,
+    DEFAULT_MICROCOMPACT_MIN_SAVED_TOKENS,
+    DEFAULT_MICROCOMPACT_PROTECT_RECENT_TOKENS,
+    DEFAULT_MICROCOMPACT_TIME_GAP_MINUTES,
+    DEFAULT_SNIP_THRESHOLD_TOKENS,
+    LIVE_COLLAPSE_BOUNDARY_PREFIX,
+    LIVE_COLLAPSE_SUMMARY_PREFIX,
+    LIVE_COMPACT_BOUNDARY_PREFIX,
+    LIVE_COMPACT_RESTORATION_PREFIX,
+    LIVE_COMPACT_SUMMARY_PREFIX,
+    LIVE_SNIP_BOUNDARY_PREFIX,
+    MICROCOMPACT_CLEARED_MESSAGE,
+    AutoCompactResult,
+    LiveCompactionResult,
+    MicrocompactResult,
+    MicrocompactStats,
+    RuntimePressureMiddleware,
+    TimeBasedMicrocompactDecision,
+    collapse_live_messages_with_result,
+    collapse_live_messages_with_summary,
+    drain_collapse_projection_messages,
+    compact_live_messages_with_result,
+    compact_live_messages_with_summary,
+    estimate_message_tokens,
+    is_prompt_too_long_error,
+    maybe_collapse_messages,
+    maybe_auto_compact_messages,
+    maybe_auto_compact_messages_with_status,
+    microcompact_messages,
+    microcompact_messages_with_stats,
+    maybe_time_based_microcompact_messages,
+    reactive_compact_messages,
+    snip_messages,
+)
+from .summarizer import (
+    COMPACT_SUMMARY_PROMPT,
+    build_compact_summary_prompt,
+    build_compact_summary_request,
+    generate_compact_summary,
+)
+from .tool_results import (
+    DEFAULT_PREVIEW_CHARS,
+    PERSISTED_OUTPUT_CLOSING_TAG,
+    PERSISTED_OUTPUT_TAG,
+    TOOL_RESULTS_DIR,
+    PersistedToolResult,
+    build_large_tool_result_message,
+    maybe_persist_large_tool_result,
+    persist_tool_result,
+    sanitize_path_segment,
+    tool_results_dir,
+)
+
+__all__ = [
+    "BudgetedText",
+    "build_collapse_boundary_message",
+    "build_collapse_summary_message",
+    "COLLAPSE_BOUNDARY_PREFIX",
+    "COLLAPSE_METADATA_KEY",
+    "COLLAPSE_SUMMARY_PREFIX",
+    "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",
+    "PERSISTED_OUTPUT_CLOSING_TAG",
+    "PERSISTED_OUTPUT_TAG",
+    "ORPHAN_TOOL_RESULT_TOMBSTONE",
+    "ProjectMessagesResult",
+    "ProjectionRepairStats",
+    "project_messages",
+    "project_messages_with_stats",
+    "PersistedToolResult",
+    "DEFAULT_PREVIEW_CHARS",
+    "DEFAULT_KEEP_RECENT_TOOL_RESULTS",
+    "DEFAULT_KEEP_RECENT_MESSAGES",
+    "DEFAULT_KEEP_RECENT_MESSAGES_AFTER_COLLAPSE",
+    "DEFAULT_KEEP_RECENT_MESSAGES_AFTER_SNIP",
+    "DEFAULT_MICROCOMPACT_MIN_CONTENT_CHARS",
+    "DEFAULT_MICROCOMPACT_MIN_PRUNE_SAVED_TOKENS",
+    "DEFAULT_MICROCOMPACT_MIN_SAVED_TOKENS",
+    "DEFAULT_MICROCOMPACT_PROTECT_RECENT_TOKENS",
+    "DEFAULT_MICROCOMPACT_TIME_GAP_MINUTES",
+    "DEFAULT_AUTO_COMPACT_THRESHOLD_TOKENS",
+    "DEFAULT_COLLAPSE_THRESHOLD_TOKENS",
+    "DEFAULT_SNIP_THRESHOLD_TOKENS",
+    "TOOL_RESULTS_DIR",
+    "build_large_tool_result_message",
+    "collapse_live_messages_with_result",
+    "collapse_live_messages_with_summary",
+    "drain_collapse_projection_messages",
+    "compact_live_messages_with_result",
+    "compact_live_messages_with_summary",
+    "estimate_message_tokens",
+    "is_prompt_too_long_error",
+    "LIVE_COLLAPSE_BOUNDARY_PREFIX",
+    "LIVE_COLLAPSE_SUMMARY_PREFIX",
+    "LIVE_COMPACT_BOUNDARY_PREFIX",
+    "LIVE_COMPACT_RESTORATION_PREFIX",
+    "LIVE_COMPACT_SUMMARY_PREFIX",
+    "LIVE_SNIP_BOUNDARY_PREFIX",
+    "MICROCOMPACT_CLEARED_MESSAGE",
+    "AutoCompactResult",
+    "LiveCompactionResult",
+    "MicrocompactResult",
+    "MicrocompactStats",
+    "TimeBasedMicrocompactDecision",
+    "maybe_persist_large_tool_result",
+    "maybe_collapse_messages",
+    "maybe_auto_compact_messages",
+    "maybe_auto_compact_messages_with_status",
+    "maybe_time_based_microcompact_messages",
+    "RuntimePressureMiddleware",
+    "microcompact_messages",
+    "microcompact_messages_with_stats",
+    "reactive_compact_messages",
+    "snip_messages",
+    "persist_tool_result",
+    "sanitize_path_segment",
+    "tool_results_dir",
+]
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..ea1e51efc
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/compact/artifacts.py
@@ -0,0 +1,343 @@
+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"
+COLLAPSE_BOUNDARY_PREFIX = "coding-deepgent collapse boundary"
+COLLAPSE_SUMMARY_PREFIX = (
+    "This session is being continued from a collapsed conversation."
+)
+COLLAPSE_METADATA_KEY = "coding_deepgent_collapse"
+
+
+@dataclass(frozen=True, slots=True)
+class CompactArtifact:
+    trigger: Literal["manual"]
+    summary: str
+    original_message_count: int
+    summarized_message_count: int
+    kept_message_count: int
+    start_message_id: str | None
+    end_message_id: str | None
+    covered_message_ids: tuple[str, ...] | None
+    messages: list[dict[str, Any]]
+
+
+def compact_messages_with_summary(
+    messages: list[dict[str, Any]],
+    *,
+    summary: str,
+    keep_last: int = 4,
+    start_message_id: str | None = None,
+    end_message_id: str | None = None,
+    covered_message_ids: list[str] | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> 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),
+            start_message_id=start_message_id,
+            end_message_id=end_message_id,
+            covered_message_ids=covered_message_ids,
+            metadata=metadata,
+        ),
+        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),
+        start_message_id=start_message_id,
+        end_message_id=end_message_id,
+        covered_message_ids=tuple(covered_message_ids)
+        if covered_message_ids is not None
+        else None,
+        messages=artifact_messages,
+    )
+
+
+def build_compact_boundary_message(
+    *,
+    trigger: str,
+    original_message_count: int,
+    summarized_message_count: int,
+    kept_message_count: int,
+    start_message_id: str | None = None,
+    end_message_id: str | None = None,
+    covered_message_ids: list[str] | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    compact_metadata_payload: dict[str, Any] = {
+        "kind": "boundary",
+        "trigger": trigger,
+        "original_message_count": original_message_count,
+        "summarized_message_count": summarized_message_count,
+        "kept_message_count": kept_message_count,
+    }
+    if start_message_id is not None:
+        compact_metadata_payload["start_message_id"] = start_message_id
+    if end_message_id is not None:
+        compact_metadata_payload["end_message_id"] = end_message_id
+    if covered_message_ids:
+        compact_metadata_payload["covered_message_ids"] = list(covered_message_ids)
+    if metadata is not None:
+        compact_metadata_payload["metadata"] = deepcopy(metadata)
+    return {
+        "role": "system",
+        "metadata": {COMPACT_METADATA_KEY: compact_metadata_payload},
+        "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 build_collapse_boundary_message(
+    *,
+    trigger: str,
+    original_message_count: int,
+    collapsed_message_count: int,
+    kept_message_count: int,
+    start_message_id: str,
+    end_message_id: str,
+    covered_message_ids: list[str] | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    collapse_metadata_payload: dict[str, Any] = {
+        "kind": "boundary",
+        "trigger": trigger,
+        "original_message_count": original_message_count,
+        "collapsed_message_count": collapsed_message_count,
+        "kept_message_count": kept_message_count,
+        "start_message_id": start_message_id,
+        "end_message_id": end_message_id,
+    }
+    if covered_message_ids:
+        collapse_metadata_payload["covered_message_ids"] = list(covered_message_ids)
+    if metadata is not None:
+        collapse_metadata_payload["metadata"] = deepcopy(metadata)
+    return {
+        "role": "system",
+        "metadata": {COLLAPSE_METADATA_KEY: collapse_metadata_payload},
+        "content": [
+            {
+                "type": "text",
+                "text": (
+                    f"{COLLAPSE_BOUNDARY_PREFIX}: trigger={trigger}; "
+                    f"original_messages={original_message_count}; "
+                    f"collapsed_messages={collapsed_message_count}; "
+                    f"kept_messages={kept_message_count}"
+                ),
+            }
+        ],
+    }
+
+
+def build_collapse_summary_message(summary: str) -> dict[str, Any]:
+    return {
+        "role": "user",
+        "metadata": {
+            COLLAPSE_METADATA_KEY: {
+                "kind": "summary",
+                "summary": summary,
+            }
+        },
+        "content": [
+            {
+                "type": "text",
+                "text": f"{COLLAPSE_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
+    start_message_id = boundary.get("start_message_id")
+    end_message_id = boundary.get("end_message_id")
+    covered_message_ids = boundary.get("covered_message_ids")
+    metadata = boundary.get("metadata")
+    if not isinstance(start_message_id, str) or not start_message_id.strip():
+        return None
+    if not isinstance(end_message_id, str) or not end_message_id.strip():
+        return None
+    if covered_message_ids is not None and (
+        not isinstance(covered_message_ids, list)
+        or not covered_message_ids
+        or any(not isinstance(item, str) or not item.strip() for item in covered_message_ids)
+    ):
+        return None
+    if metadata is not None and not isinstance(metadata, dict):
+        return None
+    return {
+        "trigger": str(boundary.get("trigger", "manual")),
+        "summary": summary_text.strip(),
+        "start_message_id": start_message_id.strip(),
+        "end_message_id": end_message_id.strip(),
+        "covered_message_ids": [item.strip() for item in covered_message_ids]
+        if isinstance(covered_message_ids, list)
+        else None,
+        "metadata": deepcopy(metadata) if isinstance(metadata, dict) else None,
+    }
+
+
+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 _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..395a49da4
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/compact/projection.py
@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import Any
+
+from coding_deepgent.compact.budget import apply_tool_result_budget
+
+ORPHAN_TOOL_RESULT_TOMBSTONE = (
+    "[Orphaned tool_result tombstoned: missing matching tool_use]"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectionRepairStats:
+    orphan_tombstoned: int = 0
+    reason: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectMessagesResult:
+    messages: list[dict[str, Any]]
+    repair_stats: ProjectionRepairStats = ProjectionRepairStats()
+
+
+def project_messages(
+    messages: list[dict[str, Any]],
+    *,
+    max_chars_per_message: int | None = None,
+) -> list[dict[str, Any]]:
+    return project_messages_with_stats(
+        messages,
+        max_chars_per_message=max_chars_per_message,
+    ).messages
+
+
+def project_messages_with_stats(
+    messages: list[dict[str, Any]],
+    *,
+    max_chars_per_message: int | None = None,
+) -> ProjectMessagesResult:
+    projected: list[dict[str, Any]] = []
+    known_tool_use_ids: set[str] = set()
+    orphan_tombstoned = 0
+
+    for message in messages:
+        normalized = _normalize_message(
+            message, max_chars_per_message=max_chars_per_message
+        )
+        current_tool_use_ids = _message_tool_use_ids(normalized)
+        normalized, message_tombstoned = _repair_orphan_tool_results(
+            normalized,
+            known_tool_use_ids=known_tool_use_ids | current_tool_use_ids,
+        )
+        orphan_tombstoned += message_tombstoned
+        known_tool_use_ids.update(current_tool_use_ids)
+        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 ProjectMessagesResult(
+        messages=projected,
+        repair_stats=ProjectionRepairStats(
+            orphan_tombstoned=orphan_tombstoned,
+            reason="missing_tool_use" if orphan_tombstoned else None,
+        ),
+    )
+
+
+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
+
+
+def _repair_orphan_tool_results(
+    message: dict[str, Any],
+    *,
+    known_tool_use_ids: set[str],
+) -> tuple[dict[str, Any], int]:
+    content = message.get("content")
+    if not isinstance(content, list):
+        return message, 0
+    repaired_blocks: list[Any] = []
+    tombstoned = 0
+    changed = False
+    for block in content:
+        if not isinstance(block, dict) or block.get("type") != "tool_result":
+            repaired_blocks.append(block)
+            continue
+        tool_use_id = block.get("tool_use_id")
+        if isinstance(tool_use_id, str) and tool_use_id in known_tool_use_ids:
+            repaired_blocks.append(block)
+            continue
+        repaired_blocks.append({"type": "text", "text": ORPHAN_TOOL_RESULT_TOMBSTONE})
+        tombstoned += 1
+        changed = True
+    if not changed:
+        return message, 0
+    repaired = dict(message)
+    repaired["content"] = repaired_blocks
+    return repaired, tombstoned
+
+
+def _message_tool_use_ids(message: dict[str, Any]) -> set[str]:
+    ids: set[str] = set()
+    content = message.get("content")
+    if isinstance(content, list):
+        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)
+    tool_calls = message.get("tool_calls")
+    if isinstance(tool_calls, list):
+        for tool_call in tool_calls:
+            if not isinstance(tool_call, dict):
+                continue
+            tool_call_id = tool_call.get("id")
+            if isinstance(tool_call_id, str) and tool_call_id:
+                ids.add(tool_call_id)
+    return ids
diff --git a/coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py b/coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py
new file mode 100644
index 000000000..18555d718
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/compact/runtime_pressure.py
@@ -0,0 +1,1883 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, cast
+
+from langchain.agents.middleware import AgentMiddleware, ModelRequest, ModelResponse
+from langchain.messages import HumanMessage, SystemMessage
+from langchain_core.messages import AIMessage, BaseMessage, ToolMessage
+
+from coding_deepgent.compact.summarizer import generate_compact_summary
+from coding_deepgent.hooks.dispatcher import dispatch_context_hook
+from coding_deepgent.hooks.events import HookEventName
+from coding_deepgent.runtime.events import RuntimeEvent
+from coding_deepgent.runtime.prompt_dump import dump_model_request_if_enabled
+from coding_deepgent.sessions.evidence_events import append_runtime_event_evidence
+from coding_deepgent.sessions.records import SessionContext, TranscriptProjection
+from coding_deepgent.sessions.store_jsonl import JsonlSessionStore
+from coding_deepgent.sessions.session_memory import (
+    compact_summary_assist_text,
+    read_session_memory_artifact,
+    session_memory_metrics,
+    update_session_memory_from_summary,
+)
+from coding_deepgent.tool_system.capabilities import CapabilityRegistry
+
+MICROCOMPACT_CLEARED_MESSAGE = "[Old tool result content cleared]"
+DEFAULT_KEEP_RECENT_TOOL_RESULTS = 3
+DEFAULT_MICROCOMPACT_MIN_CONTENT_CHARS = 120
+LIVE_SNIP_BOUNDARY_PREFIX = "coding-deepgent live snip boundary"
+LIVE_COLLAPSE_BOUNDARY_PREFIX = "coding-deepgent live collapse boundary"
+LIVE_COLLAPSE_SUMMARY_PREFIX = "This session is being continued from a collapsed live context."
+LIVE_COMPACT_BOUNDARY_PREFIX = "coding-deepgent live compact boundary"
+LIVE_COMPACT_SUMMARY_PREFIX = "This session is being continued from a compacted live invocation."
+LIVE_COMPACT_RESTORATION_PREFIX = "Restored persisted tool outputs:"
+DEFAULT_AUTO_COMPACT_THRESHOLD_TOKENS = 8000
+DEFAULT_KEEP_RECENT_MESSAGES = 4
+DEFAULT_SNIP_THRESHOLD_TOKENS = None
+DEFAULT_KEEP_RECENT_MESSAGES_AFTER_SNIP = 12
+DEFAULT_COLLAPSE_THRESHOLD_TOKENS = 12000
+DEFAULT_KEEP_RECENT_MESSAGES_AFTER_COLLAPSE = 8
+DEFAULT_MICROCOMPACT_TIME_GAP_MINUTES = None
+DEFAULT_MICROCOMPACT_MIN_SAVED_TOKENS = 0
+DEFAULT_MICROCOMPACT_PROTECT_RECENT_TOKENS = None
+DEFAULT_MICROCOMPACT_MIN_PRUNE_SAVED_TOKENS = 0
+
+
+def _utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+@dataclass(frozen=True, slots=True)
+class MicrocompactStats:
+    cleared_tool_results: int = 0
+    kept_tool_results: int = 0
+    tokens_saved_estimate: int = 0
+    keep_recent_tool_results: int = DEFAULT_KEEP_RECENT_TOOL_RESULTS
+    protected_recent_tokens: int | None = DEFAULT_MICROCOMPACT_PROTECT_RECENT_TOKENS
+
+
+@dataclass(frozen=True, slots=True)
+class MicrocompactResult:
+    messages: list[BaseMessage]
+    stats: MicrocompactStats
+
+
+@dataclass(frozen=True, slots=True)
+class TimeBasedMicrocompactDecision:
+    attempted: bool
+    result: MicrocompactResult | None = None
+    gap_minutes: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class AutoCompactResult:
+    messages: list[BaseMessage]
+    attempted: bool = False
+    compacted: bool = False
+    failed: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class LiveCompactionResult:
+    boundary_message: SystemMessage
+    summary_message: HumanMessage
+    preserved_tail: tuple[BaseMessage, ...]
+    trigger: str
+    restoration_messages: tuple[SystemMessage, ...] = ()
+    original_token_estimate: int = 0
+    projected_token_estimate: int = 0
+
+    @property
+    def restored_path_count(self) -> int:
+        return sum(
+            max(0, len(str(message.content).splitlines()) - 1)
+            for message in self.restoration_messages
+        )
+
+    def render(self) -> list[BaseMessage]:
+        return [
+            self.boundary_message,
+            self.summary_message,
+            *self.restoration_messages,
+            *self.preserved_tail,
+        ]
+
+
+@dataclass(frozen=True, slots=True)
+class PostAutocompactCanary:
+    pre_compact_total: int
+    post_compact_total: int
+    trigger: str
+
+
+def _with_projected_token_estimate(result: LiveCompactionResult) -> LiveCompactionResult:
+    return LiveCompactionResult(
+        boundary_message=result.boundary_message,
+        summary_message=result.summary_message,
+        restoration_messages=result.restoration_messages,
+        preserved_tail=result.preserved_tail,
+        trigger=result.trigger,
+        original_token_estimate=result.original_token_estimate,
+        projected_token_estimate=estimate_message_tokens(result.render()),
+    )
+
+
+def microcompact_messages(
+    messages: Sequence[BaseMessage],
+    *,
+    registry: CapabilityRegistry,
+    keep_recent_tool_results: int = DEFAULT_KEEP_RECENT_TOOL_RESULTS,
+    min_content_chars: int = DEFAULT_MICROCOMPACT_MIN_CONTENT_CHARS,
+    protect_recent_tokens: int | None = DEFAULT_MICROCOMPACT_PROTECT_RECENT_TOKENS,
+    min_saved_tokens: int = DEFAULT_MICROCOMPACT_MIN_PRUNE_SAVED_TOKENS,
+) -> list[BaseMessage]:
+    return microcompact_messages_with_stats(
+        messages,
+        registry=registry,
+        keep_recent_tool_results=keep_recent_tool_results,
+        min_content_chars=min_content_chars,
+        protect_recent_tokens=protect_recent_tokens,
+        min_saved_tokens=min_saved_tokens,
+    ).messages
+
+
+def microcompact_messages_with_stats(
+    messages: Sequence[BaseMessage],
+    *,
+    registry: CapabilityRegistry,
+    keep_recent_tool_results: int = DEFAULT_KEEP_RECENT_TOOL_RESULTS,
+    min_content_chars: int = DEFAULT_MICROCOMPACT_MIN_CONTENT_CHARS,
+    protect_recent_tokens: int | None = DEFAULT_MICROCOMPACT_PROTECT_RECENT_TOKENS,
+    min_saved_tokens: int = DEFAULT_MICROCOMPACT_MIN_PRUNE_SAVED_TOKENS,
+) -> MicrocompactResult:
+    if keep_recent_tool_results < 0:
+        raise ValueError("keep_recent_tool_results must be non-negative")
+    if protect_recent_tokens is not None and protect_recent_tokens < 1:
+        raise ValueError("protect_recent_tokens must be positive")
+    if min_saved_tokens < 0:
+        raise ValueError("min_saved_tokens must be non-negative")
+
+    eligible_tool_calls = _eligible_tool_calls(messages, registry=registry)
+    if not eligible_tool_calls:
+        return MicrocompactResult(
+            messages=list(messages),
+            stats=MicrocompactStats(
+                keep_recent_tool_results=keep_recent_tool_results,
+                protected_recent_tokens=protect_recent_tokens,
+            ),
+        )
+
+    compactable_indexes = [
+        index
+        for index, message in enumerate(messages)
+        if _is_compactable_tool_result(
+            message,
+            eligible_tool_calls=eligible_tool_calls,
+            min_content_chars=min_content_chars,
+        )
+    ]
+    if protect_recent_tokens is None and len(compactable_indexes) <= keep_recent_tool_results:
+        return MicrocompactResult(
+            messages=list(messages),
+            stats=MicrocompactStats(
+                kept_tool_results=len(compactable_indexes),
+                keep_recent_tool_results=keep_recent_tool_results,
+                protected_recent_tokens=protect_recent_tokens,
+            ),
+        )
+
+    rewritten = list(messages)
+    if protect_recent_tokens is None:
+        indexes_to_clear = compactable_indexes[:-keep_recent_tool_results or None]
+        kept_count = len(compactable_indexes) - len(indexes_to_clear)
+    else:
+        indexes_to_clear = _token_budget_indexes_to_clear(
+            messages,
+            compactable_indexes=compactable_indexes,
+            protect_recent_tokens=protect_recent_tokens,
+        )
+        kept_count = len(compactable_indexes) - len(indexes_to_clear)
+        if not indexes_to_clear:
+            return MicrocompactResult(
+                messages=list(messages),
+                stats=MicrocompactStats(
+                    kept_tool_results=kept_count,
+                    keep_recent_tool_results=kept_count,
+                    protected_recent_tokens=protect_recent_tokens,
+                ),
+            )
+    tokens_saved_estimate = 0
+    for index in indexes_to_clear:
+        message = rewritten[index]
+        if isinstance(message, ToolMessage):
+            original_tokens = _estimate_message_tokens(message)
+            rewritten[index] = message.model_copy(
+                update={"content": _microcompacted_content(message)}
+            )
+            tokens_saved_estimate += max(
+                0, original_tokens - _estimate_message_tokens(rewritten[index])
+            )
+    if tokens_saved_estimate < min_saved_tokens:
+        return MicrocompactResult(
+            messages=list(messages),
+            stats=MicrocompactStats(
+                kept_tool_results=len(compactable_indexes),
+                keep_recent_tool_results=keep_recent_tool_results,
+                protected_recent_tokens=protect_recent_tokens,
+            ),
+        )
+    return MicrocompactResult(
+        messages=rewritten,
+        stats=MicrocompactStats(
+            cleared_tool_results=len(indexes_to_clear),
+            kept_tool_results=kept_count,
+            tokens_saved_estimate=tokens_saved_estimate,
+            keep_recent_tool_results=(
+                keep_recent_tool_results
+                if protect_recent_tokens is None
+                else kept_count
+            ),
+            protected_recent_tokens=protect_recent_tokens,
+        ),
+    )
+
+
+def _microcompact_event_metadata(stats: MicrocompactStats) -> dict[str, object]:
+    metadata: dict[str, object] = {
+        "source": "runtime_pressure",
+        "strategy": "microcompact",
+        "cleared_tool_results": stats.cleared_tool_results,
+        "tools_cleared": stats.cleared_tool_results,
+        "tools_kept": stats.kept_tool_results,
+        "tokens_saved_estimate": stats.tokens_saved_estimate,
+        "keep_recent": stats.keep_recent_tool_results,
+    }
+    if stats.protected_recent_tokens is not None:
+        metadata["protected_recent_tokens"] = stats.protected_recent_tokens
+    return metadata
+
+
+def maybe_time_based_microcompact_messages(
+    messages: Sequence[BaseMessage],
+    *,
+    registry: CapabilityRegistry,
+    context: object,
+    gap_threshold_minutes: int | None,
+    now: Callable[[], datetime] = _utc_now,
+    keep_recent_tool_results: int = DEFAULT_KEEP_RECENT_TOOL_RESULTS,
+    min_content_chars: int = DEFAULT_MICROCOMPACT_MIN_CONTENT_CHARS,
+    min_saved_tokens: int = DEFAULT_MICROCOMPACT_MIN_SAVED_TOKENS,
+    main_entrypoint: str = "coding-deepgent",
+    main_agent_name: str = "coding-deepgent",
+) -> TimeBasedMicrocompactDecision:
+    if gap_threshold_minutes is None:
+        return TimeBasedMicrocompactDecision(attempted=False)
+    if gap_threshold_minutes < 1:
+        raise ValueError("gap_threshold_minutes must be positive")
+    if min_saved_tokens < 0:
+        raise ValueError("min_saved_tokens must be non-negative")
+    if not _is_main_runtime_context(
+        context,
+        main_entrypoint=main_entrypoint,
+        main_agent_name=main_agent_name,
+    ):
+        return TimeBasedMicrocompactDecision(attempted=False)
+
+    last_assistant_timestamp = _latest_assistant_timestamp(messages)
+    if last_assistant_timestamp is None:
+        return TimeBasedMicrocompactDecision(attempted=False)
+
+    gap = now() - last_assistant_timestamp
+    gap_minutes = max(0, int(gap.total_seconds() // 60))
+    if gap_minutes < gap_threshold_minutes:
+        return TimeBasedMicrocompactDecision(attempted=False)
+
+    result = microcompact_messages_with_stats(
+        messages,
+        registry=registry,
+        keep_recent_tool_results=max(1, keep_recent_tool_results),
+        min_content_chars=min_content_chars,
+    )
+    if result.messages == list(messages):
+        return TimeBasedMicrocompactDecision(
+            attempted=True,
+            result=None,
+            gap_minutes=gap_minutes,
+        )
+    if result.stats.tokens_saved_estimate < min_saved_tokens:
+        return TimeBasedMicrocompactDecision(
+            attempted=True,
+            result=None,
+            gap_minutes=gap_minutes,
+        )
+    return TimeBasedMicrocompactDecision(
+        attempted=True,
+        result=result,
+        gap_minutes=gap_minutes,
+    )
+
+
+def _time_based_microcompact_event_metadata(
+    *, stats: MicrocompactStats, gap_minutes: int
+) -> dict[str, object]:
+    metadata = _microcompact_event_metadata(stats)
+    metadata.update(
+        {
+            "trigger": "time_gap",
+            "gap_minutes": gap_minutes,
+        }
+    )
+    return metadata
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimePressureMiddleware(AgentMiddleware):
+    registry: CapabilityRegistry
+    keep_recent_tool_results: int = DEFAULT_KEEP_RECENT_TOOL_RESULTS
+    min_content_chars: int = DEFAULT_MICROCOMPACT_MIN_CONTENT_CHARS
+    snip_threshold_tokens: int | None = DEFAULT_SNIP_THRESHOLD_TOKENS
+    keep_recent_messages_after_snip: int = DEFAULT_KEEP_RECENT_MESSAGES_AFTER_SNIP
+    collapse_threshold_tokens: int | None = DEFAULT_COLLAPSE_THRESHOLD_TOKENS
+    model_context_window_tokens: int | None = None
+    collapse_trigger_ratio: float | None = None
+    keep_recent_messages_after_collapse: int = DEFAULT_KEEP_RECENT_MESSAGES_AFTER_COLLAPSE
+    auto_compact_threshold_tokens: int | None = DEFAULT_AUTO_COMPACT_THRESHOLD_TOKENS
+    keep_recent_messages: int = DEFAULT_KEEP_RECENT_MESSAGES
+    auto_compact_max_failures: int | None = None
+    auto_compact_ptl_retry_limit: int = 0
+    microcompact_time_gap_minutes: int | None = DEFAULT_MICROCOMPACT_TIME_GAP_MINUTES
+    microcompact_min_saved_tokens: int = DEFAULT_MICROCOMPACT_MIN_SAVED_TOKENS
+    microcompact_protect_recent_tokens: int | None = (
+        DEFAULT_MICROCOMPACT_PROTECT_RECENT_TOKENS
+    )
+    microcompact_min_prune_saved_tokens: int = (
+        DEFAULT_MICROCOMPACT_MIN_PRUNE_SAVED_TOKENS
+    )
+    main_entrypoint: str = "coding-deepgent"
+    main_agent_name: str = "coding-deepgent"
+    now: Callable[[], datetime] = _utc_now
+    _auto_compact_failure_count: int = field(default=0, init=False, compare=False, repr=False)
+    _pending_post_autocompact_turn: PostAutocompactCanary | None = field(
+        default=None,
+        init=False,
+        compare=False,
+        repr=False,
+    )
+
+    def wrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], ModelResponse],
+    ) -> ModelResponse:
+        current_projection = _runtime_transcript_projection(request)
+        processed = snip_messages(
+            request.messages,
+            threshold_tokens=self.snip_threshold_tokens,
+            keep_recent_messages=self.keep_recent_messages_after_snip,
+        )
+        if _is_snipped(processed):
+            current_projection = _projection_after_snip(
+                request.messages,
+                current_projection,
+                keep_recent_messages=self.keep_recent_messages_after_snip,
+            )
+            _emit_runtime_pressure_event(
+                request,
+                kind="snip",
+                message="Runtime pressure middleware snipped older live history.",
+                metadata={
+                    "source": "runtime_pressure",
+                    "strategy": "snip",
+                    "hidden_messages": _snip_hidden_message_count(processed),
+                },
+            )
+        before_microcompact = processed
+        context = getattr(request.runtime, "context", None)
+        time_based_microcompact = maybe_time_based_microcompact_messages(
+            before_microcompact,
+            registry=self.registry,
+            context=context,
+            gap_threshold_minutes=self.microcompact_time_gap_minutes,
+            now=self.now,
+            keep_recent_tool_results=self.keep_recent_tool_results,
+            min_content_chars=self.min_content_chars,
+            min_saved_tokens=self.microcompact_min_saved_tokens,
+            main_entrypoint=self.main_entrypoint,
+            main_agent_name=self.main_agent_name,
+        )
+        if time_based_microcompact.result is not None:
+            processed = time_based_microcompact.result.messages
+            _emit_runtime_pressure_event(
+                request,
+                kind="microcompact",
+                message="Runtime pressure middleware microcompacted older tool results.",
+                metadata=_time_based_microcompact_event_metadata(
+                    stats=time_based_microcompact.result.stats,
+                    gap_minutes=time_based_microcompact.gap_minutes or 0,
+                ),
+            )
+        elif not time_based_microcompact.attempted:
+            microcompact_result = microcompact_messages_with_stats(
+                before_microcompact,
+                registry=self.registry,
+                keep_recent_tool_results=self.keep_recent_tool_results,
+                min_content_chars=self.min_content_chars,
+                protect_recent_tokens=self.microcompact_protect_recent_tokens,
+                min_saved_tokens=self.microcompact_min_prune_saved_tokens,
+            )
+            processed = microcompact_result.messages
+            if processed != list(before_microcompact):
+                _emit_runtime_pressure_event(
+                    request,
+                    kind="microcompact",
+                    message="Runtime pressure middleware microcompacted older tool results.",
+                    metadata=_microcompact_event_metadata(microcompact_result.stats),
+                )
+        session_memory_assist = _session_memory_assist_text(request.state, processed)
+        collapse_source_messages = list(processed)
+        collapse_source_projection = current_projection
+        processed = maybe_collapse_messages(
+            processed,
+            summarizer=request.model,
+            threshold_tokens=self.collapse_threshold_tokens,
+            context_window_tokens=self.model_context_window_tokens,
+            trigger_ratio=self.collapse_trigger_ratio,
+            keep_recent_messages=self.keep_recent_messages_after_collapse,
+            assist_context=session_memory_assist,
+        )
+        if _is_collapsed(processed):
+            _append_collapse_record(
+                request,
+                source_messages=collapse_source_messages,
+                projection=collapse_source_projection,
+                collapsed_messages=processed,
+                threshold_tokens=self.collapse_threshold_tokens,
+                context_window_tokens=self.model_context_window_tokens,
+                trigger_ratio=self.collapse_trigger_ratio,
+                used_session_memory_assist=session_memory_assist is not None,
+            )
+            collapse_pressure = _pressure_metadata(
+                collapse_source_messages,
+                context_window_tokens=self.model_context_window_tokens,
+            )
+            _emit_runtime_pressure_event(
+                request,
+                kind="context_collapse",
+                message="Runtime pressure middleware collapsed older live history.",
+                metadata={
+                    "source": "runtime_pressure",
+                    "strategy": "context_collapse",
+                    "collapsed_messages": _collapse_collapsed_message_count(processed),
+                    "used_session_memory_assist": session_memory_assist is not None,
+                    "restored_path_count": _restored_path_count(processed),
+                    **collapse_pressure,
+                },
+            )
+            self._set_pending_post_autocompact_turn(
+                pre_compact_total=estimate_message_tokens(collapse_source_messages),
+                post_compact_total=estimate_message_tokens(processed),
+                trigger="context_collapse",
+            )
+        if self._should_skip_auto_compact():
+            _emit_runtime_pressure_event(
+                request,
+                kind="auto_compact",
+                message="Runtime pressure middleware skipped proactive auto-compact after repeated failures.",
+                metadata={
+                    "source": "runtime_pressure",
+                    "strategy": "auto",
+                    "trigger": "failure_circuit_breaker",
+                    "failure_count": self._auto_compact_failure_count,
+                    "max_failures": self.auto_compact_max_failures or 0,
+                },
+            )
+        else:
+            auto_compact_source = list(processed)
+            auto_compact_source_tokens = estimate_message_tokens(auto_compact_source)
+            auto_compact_attempted = (
+                self.auto_compact_threshold_tokens is not None
+                and auto_compact_source_tokens >= self.auto_compact_threshold_tokens
+            )
+            if auto_compact_attempted:
+                _emit_runtime_pressure_event(
+                    request,
+                    kind="auto_compact",
+                    message="Runtime pressure middleware started proactive auto-compact.",
+                    metadata={
+                        "source": "runtime_pressure",
+                        "strategy": "auto",
+                        "outcome": "attempted",
+                        "pre_compact_total": auto_compact_source_tokens,
+                        "message_count": len(auto_compact_source),
+                    },
+                )
+            auto_compact_result = maybe_auto_compact_messages_with_status(
+                processed,
+                summarizer=request.model,
+                threshold_tokens=self.auto_compact_threshold_tokens,
+                keep_recent_messages=self.keep_recent_messages,
+                assist_context=session_memory_assist,
+                state=request.state,
+                ptl_retry_limit=self.auto_compact_ptl_retry_limit,
+                hook_context=context,
+            )
+            processed = auto_compact_result.messages
+            if auto_compact_result.compacted:
+                self._reset_auto_compact_failure_count()
+                _emit_runtime_pressure_event(
+                    request,
+                    kind="auto_compact",
+                    message="Runtime pressure middleware proactively compacted live history.",
+                    metadata={
+                        "source": "runtime_pressure",
+                        "strategy": "auto",
+                        "outcome": "succeeded",
+                        "pre_compact_total": auto_compact_source_tokens,
+                        "post_compact_total": estimate_message_tokens(processed),
+                        "tokens_saved_estimate": max(
+                            0,
+                            auto_compact_source_tokens
+                            - estimate_message_tokens(processed),
+                        ),
+                        "hidden_messages": _auto_compact_hidden_message_count(
+                            auto_compact_source,
+                            processed,
+                        ),
+                        "used_session_memory_assist": session_memory_assist is not None,
+                        "restored_path_count": _restored_path_count(processed),
+                    },
+                )
+                self._set_pending_post_autocompact_turn(
+                    pre_compact_total=auto_compact_source_tokens,
+                    post_compact_total=estimate_message_tokens(processed),
+                    trigger="auto_compact",
+                )
+            elif auto_compact_result.failed:
+                self._increment_auto_compact_failure_count()
+        active_request = (
+            request
+            if processed == list(request.messages)
+            else request.override(messages=cast(list[Any], processed))
+        )
+        try:
+            return self._call_model_handler_with_observability(
+                request,
+                active_request,
+                handler,
+            )
+        except Exception as exc:
+            if not is_prompt_too_long_error(exc):
+                raise
+            drained = drain_collapse_projection_messages(active_request.messages)
+            if drained != list(active_request.messages):
+                _emit_runtime_pressure_event(
+                    request,
+                    kind="context_collapse",
+                    message="Runtime pressure middleware drained collapse projection before reactive compact.",
+                    metadata={
+                        "source": "runtime_pressure",
+                        "strategy": "context_collapse",
+                        "trigger": "overflow_drain",
+                        "drained_summaries": _drained_collapse_summary_count(
+                            active_request.messages
+                        ),
+                    },
+                )
+                drained_request = active_request.override(messages=cast(list[Any], drained))
+                try:
+                    return self._call_model_handler_with_observability(
+                        request,
+                        drained_request,
+                        handler,
+                    )
+                except Exception as drained_exc:
+                    if not is_prompt_too_long_error(drained_exc):
+                        raise
+                    active_request = drained_request
+            compacted = reactive_compact_messages(
+                active_request.messages,
+                summarizer=request.model,
+                keep_recent_messages=self.keep_recent_messages,
+                assist_context=_session_memory_assist_text(
+                    active_request.state, active_request.messages
+                ),
+                state=active_request.state,
+            )
+            if compacted == list(active_request.messages):
+                raise
+            _emit_runtime_pressure_event(
+                request,
+                kind="reactive_compact",
+                message="Runtime pressure middleware retried with reactive compact.",
+                metadata={
+                    "source": "runtime_pressure",
+                    "strategy": "reactive",
+                    "used_session_memory_assist": _session_memory_assist_text(
+                        active_request.state, active_request.messages
+                    )
+                    is not None,
+                    "restored_path_count": _restored_path_count(compacted),
+                },
+            )
+            return self._call_model_handler_with_observability(
+                request,
+                active_request.override(messages=cast(list[Any], compacted)),
+                handler,
+            )
+
+    def _call_model_handler_with_observability(
+        self,
+        original_request: ModelRequest,
+        active_request: ModelRequest,
+        handler: Callable[[ModelRequest], ModelResponse],
+    ) -> ModelResponse:
+        context = getattr(original_request.runtime, "context", None)
+        input_tokens = estimate_message_tokens(active_request.messages)
+        dump_model_request_if_enabled(
+            context,
+            request=active_request,
+            messages=active_request.messages,
+            input_token_estimate=input_tokens,
+        )
+        response = handler(active_request)
+        output_tokens = _response_token_estimate(response)
+        _emit_runtime_pressure_event(
+            original_request,
+            kind="token_budget",
+            message="Model call completed with bounded token-budget estimates.",
+            metadata={
+                "source": "runtime_pressure",
+                "strategy": "model_call",
+                "input_token_estimate": input_tokens,
+                "output_token_estimate": output_tokens,
+                "total_token_estimate": input_tokens + output_tokens,
+                "message_count": len(active_request.messages),
+                "response_message_count": _response_message_count(response),
+            },
+        )
+        self._emit_pending_post_autocompact_turn(
+            original_request,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+        )
+        return response
+
+    def _set_pending_post_autocompact_turn(
+        self,
+        *,
+        pre_compact_total: int,
+        post_compact_total: int,
+        trigger: str,
+    ) -> None:
+        object.__setattr__(
+            self,
+            "_pending_post_autocompact_turn",
+            PostAutocompactCanary(
+                pre_compact_total=pre_compact_total,
+                post_compact_total=post_compact_total,
+                trigger=trigger,
+            ),
+        )
+
+    def _emit_pending_post_autocompact_turn(
+        self,
+        request: ModelRequest,
+        *,
+        input_tokens: int,
+        output_tokens: int,
+    ) -> None:
+        pending = self._pending_post_autocompact_turn
+        if pending is None:
+            return
+        object.__setattr__(self, "_pending_post_autocompact_turn", None)
+        _emit_runtime_pressure_event(
+            request,
+            kind="post_autocompact_turn",
+            message="First turn after compact completed with canary metrics.",
+            metadata={
+                "source": "runtime_pressure",
+                "trigger": pending.trigger,
+                "pre_compact_total": pending.pre_compact_total,
+                "post_compact_total": pending.post_compact_total,
+                "new_turn_input": input_tokens,
+                "new_turn_output": output_tokens,
+            },
+        )
+
+    def _should_skip_auto_compact(self) -> bool:
+        return (
+            self.auto_compact_max_failures is not None
+            and self._auto_compact_failure_count >= self.auto_compact_max_failures
+        )
+
+    def _increment_auto_compact_failure_count(self) -> None:
+        if self.auto_compact_max_failures is None:
+            return
+        object.__setattr__(
+            self,
+            "_auto_compact_failure_count",
+            self._auto_compact_failure_count + 1,
+        )
+
+    def _reset_auto_compact_failure_count(self) -> None:
+        if self._auto_compact_failure_count == 0:
+            return
+        object.__setattr__(self, "_auto_compact_failure_count", 0)
+
+
+def _eligible_tool_calls(
+    messages: Sequence[BaseMessage], *, registry: CapabilityRegistry
+) -> set[str]:
+    eligible: set[str] = set()
+    for message in messages:
+        if not isinstance(message, AIMessage):
+            continue
+        for call in message.tool_calls:
+            tool_name = call.get("name")
+            tool_call_id = call.get("id")
+            if not isinstance(tool_name, str) or not isinstance(tool_call_id, str):
+                continue
+            capability = registry.get(tool_name)
+            if capability is not None and capability.microcompact_eligible:
+                eligible.add(tool_call_id)
+    return eligible
+
+
+def _is_compactable_tool_result(
+    message: BaseMessage,
+    *,
+    eligible_tool_calls: set[str],
+    min_content_chars: int,
+) -> bool:
+    if not isinstance(message, ToolMessage):
+        return False
+    if message.status != "success":
+        return False
+    if message.tool_call_id not in eligible_tool_calls:
+        return False
+    return len(str(message.content)) > min_content_chars
+
+
+def _microcompacted_content(message: ToolMessage) -> str:
+    artifact = message.artifact if isinstance(message.artifact, dict) else {}
+    path = artifact.get("path")
+    if isinstance(path, str) and path.strip():
+        return f"{MICROCOMPACT_CLEARED_MESSAGE} Full output remains available at: {path.strip()}"
+    return MICROCOMPACT_CLEARED_MESSAGE
+
+
+def _token_budget_indexes_to_clear(
+    messages: Sequence[BaseMessage],
+    *,
+    compactable_indexes: Sequence[int],
+    protect_recent_tokens: int,
+) -> list[int]:
+    protected_indexes: set[int] = set()
+    remaining_tokens = protect_recent_tokens
+    for index in reversed(compactable_indexes):
+        message_tokens = _estimate_message_tokens(messages[index])
+        if not protected_indexes:
+            protected_indexes.add(index)
+            remaining_tokens = max(0, remaining_tokens - message_tokens)
+            continue
+        if message_tokens > remaining_tokens:
+            break
+        protected_indexes.add(index)
+        remaining_tokens -= message_tokens
+    return [index for index in compactable_indexes if index not in protected_indexes]
+
+
+def _is_main_runtime_context(
+    context: object,
+    *,
+    main_entrypoint: str,
+    main_agent_name: str,
+) -> bool:
+    return (
+        getattr(context, "entrypoint", None) == main_entrypoint
+        and getattr(context, "agent_name", None) == main_agent_name
+    )
+
+
+def _latest_assistant_timestamp(messages: Sequence[BaseMessage]) -> datetime | None:
+    for message in reversed(messages):
+        if not isinstance(message, AIMessage):
+            continue
+        timestamp = _message_timestamp(message)
+        if timestamp is not None:
+            return timestamp
+    return None
+
+
+def _message_timestamp(message: BaseMessage) -> datetime | None:
+    for metadata in (message.additional_kwargs, message.response_metadata):
+        for key in ("timestamp", "created_at", "createdAt"):
+            value = metadata.get(key)
+            if isinstance(value, datetime):
+                return _ensure_aware_datetime(value)
+            if isinstance(value, str):
+                parsed = _parse_datetime(value)
+                if parsed is not None:
+                    return parsed
+    return None
+
+
+def _parse_datetime(value: str) -> datetime | None:
+    normalized = value.strip()
+    if not normalized:
+        return None
+    if normalized.endswith("Z"):
+        normalized = f"{normalized[:-1]}+00:00"
+    try:
+        return _ensure_aware_datetime(datetime.fromisoformat(normalized))
+    except ValueError:
+        return None
+
+
+def _ensure_aware_datetime(value: datetime) -> datetime:
+    if value.tzinfo is None:
+        return value.replace(tzinfo=timezone.utc)
+    return value.astimezone(timezone.utc)
+
+
+def snip_messages(
+    messages: Sequence[BaseMessage],
+    *,
+    threshold_tokens: int | None,
+    keep_recent_messages: int = DEFAULT_KEEP_RECENT_MESSAGES_AFTER_SNIP,
+) -> list[BaseMessage]:
+    if threshold_tokens is None:
+        return list(messages)
+    if threshold_tokens < 1:
+        raise ValueError("threshold_tokens must be positive")
+    if keep_recent_messages < 0:
+        raise ValueError("keep_recent_messages must be non-negative")
+    clean_messages = [
+        message.model_copy(deep=True)
+        for message in messages
+        if not _is_live_pressure_artifact_message(message)
+    ]
+    if estimate_message_tokens(clean_messages) < threshold_tokens:
+        return list(messages)
+
+    keep_start = _adjust_keep_start_for_live_tool_pairs(
+        clean_messages,
+        max(0, len(clean_messages) - keep_recent_messages),
+    )
+    preserved_tail = clean_messages[keep_start:]
+    hidden_count = keep_start
+    if hidden_count <= 0:
+        return list(messages)
+    return [
+        SystemMessage(
+            content=(
+                f"{LIVE_SNIP_BOUNDARY_PREFIX}: "
+                f"original_messages={len(clean_messages)}; "
+                f"hidden_messages={hidden_count}; "
+                f"kept_messages={len(preserved_tail)}"
+            )
+        ),
+        *preserved_tail,
+    ]
+
+
+def maybe_collapse_messages(
+    messages: Sequence[BaseMessage],
+    *,
+    summarizer: Any,
+    threshold_tokens: int | None,
+    context_window_tokens: int | None = None,
+    trigger_ratio: float | None = None,
+    keep_recent_messages: int = DEFAULT_KEEP_RECENT_MESSAGES_AFTER_COLLAPSE,
+    assist_context: str | None = None,
+) -> list[BaseMessage]:
+    if threshold_tokens is None and (
+        context_window_tokens is None or trigger_ratio is None
+    ):
+        return list(messages)
+    if threshold_tokens is not None and threshold_tokens < 1:
+        raise ValueError("threshold_tokens must be positive")
+    if context_window_tokens is not None and context_window_tokens < 1:
+        raise ValueError("context_window_tokens must be positive")
+    if trigger_ratio is not None and not 0 <= trigger_ratio <= 1:
+        raise ValueError("trigger_ratio must be between 0 and 1")
+    if keep_recent_messages < 0:
+        raise ValueError("keep_recent_messages must be non-negative")
+    if not _collapse_pressure_exceeded(
+        messages,
+        threshold_tokens=threshold_tokens,
+        context_window_tokens=context_window_tokens,
+        trigger_ratio=trigger_ratio,
+    ):
+        return list(messages)
+    try:
+        summary = generate_compact_summary(
+            _messages_as_compact_dicts(messages),
+            summarizer,
+            assist_context=assist_context,
+        )
+    except Exception:
+        return list(messages)
+    return collapse_live_messages_with_summary(
+        messages,
+        summary=summary,
+        keep_recent_messages=keep_recent_messages,
+    )
+
+
+def collapse_live_messages_with_summary(
+    messages: Sequence[BaseMessage],
+    *,
+    summary: str,
+    keep_recent_messages: int = DEFAULT_KEEP_RECENT_MESSAGES_AFTER_COLLAPSE,
+) -> list[BaseMessage]:
+    if not _has_collapsible_source(
+        messages,
+        keep_recent_messages=keep_recent_messages,
+    ):
+        return list(messages)
+    return collapse_live_messages_with_result(
+        messages,
+        summary=summary,
+        keep_recent_messages=keep_recent_messages,
+    ).render()
+
+
+def collapse_live_messages_with_result(
+    messages: Sequence[BaseMessage],
+    *,
+    summary: str,
+    keep_recent_messages: int = DEFAULT_KEEP_RECENT_MESSAGES_AFTER_COLLAPSE,
+) -> LiveCompactionResult:
+    if not messages:
+        raise ValueError("messages are required for collapse")
+    if keep_recent_messages < 0:
+        raise ValueError("keep_recent_messages must be non-negative")
+    if not summary.strip():
+        raise ValueError("summary is required for collapse")
+
+    clean_messages = [
+        message.model_copy(deep=True)
+        for message in messages
+        if not _is_live_pressure_artifact_message(message)
+    ]
+    keep_start = _collapse_keep_start_index(
+        clean_messages,
+        keep_recent_messages=keep_recent_messages,
+    )
+    collapsed_source = clean_messages[:keep_start]
+    preserved_tail = clean_messages[keep_start:]
+    if not collapsed_source:
+        raise ValueError("collapse requires messages outside the preserved tail")
+    restored_paths = _restored_persisted_output_paths(
+        compacted_messages=collapsed_source,
+        preserved_tail=preserved_tail,
+    )
+
+    restoration_messages: list[SystemMessage] = []
+    if restored_paths:
+        restoration_messages.append(
+            SystemMessage(
+                content=(
+                    f"{LIVE_COMPACT_RESTORATION_PREFIX}\n"
+                    + "\n".join(f"- {path}" for path in restored_paths)
+                )
+            )
+        )
+    result = LiveCompactionResult(
+        boundary_message=SystemMessage(
+            content=(
+                f"{LIVE_COLLAPSE_BOUNDARY_PREFIX}: "
+                f"original_messages={len(clean_messages)}; "
+                f"collapsed_messages={len(collapsed_source)}; "
+                f"kept_messages={len(preserved_tail)}"
+            )
+        ),
+        summary_message=HumanMessage(
+            content=f"{LIVE_COLLAPSE_SUMMARY_PREFIX}\n\nSummary:\n{summary.strip()}"
+        ),
+        restoration_messages=tuple(restoration_messages),
+        preserved_tail=tuple(preserved_tail),
+        trigger="context_collapse",
+        original_token_estimate=estimate_message_tokens(clean_messages),
+    )
+    return _with_projected_token_estimate(result)
+
+
+def _collapse_pressure_exceeded(
+    messages: Sequence[BaseMessage],
+    *,
+    threshold_tokens: int | None,
+    context_window_tokens: int | None,
+    trigger_ratio: float | None,
+) -> bool:
+    estimated_tokens = estimate_message_tokens(messages)
+    if threshold_tokens is not None and estimated_tokens >= threshold_tokens:
+        return True
+    if (
+        context_window_tokens is not None
+        and trigger_ratio is not None
+        and estimated_tokens / context_window_tokens >= trigger_ratio
+    ):
+        return True
+    return False
+
+
+def maybe_auto_compact_messages(
+    messages: Sequence[BaseMessage],
+    *,
+    summarizer: Any,
+    threshold_tokens: int | None,
+    keep_recent_messages: int = DEFAULT_KEEP_RECENT_MESSAGES,
+    assist_context: str | None = None,
+    state: Any = None,
+    ptl_retry_limit: int = 0,
+    hook_context: object | None = None,
+) -> list[BaseMessage]:
+    return maybe_auto_compact_messages_with_status(
+        messages,
+        summarizer=summarizer,
+        threshold_tokens=threshold_tokens,
+        keep_recent_messages=keep_recent_messages,
+        assist_context=assist_context,
+        state=state,
+        ptl_retry_limit=ptl_retry_limit,
+        hook_context=hook_context,
+    ).messages
+
+
+def maybe_auto_compact_messages_with_status(
+    messages: Sequence[BaseMessage],
+    *,
+    summarizer: Any,
+    threshold_tokens: int | None,
+    keep_recent_messages: int = DEFAULT_KEEP_RECENT_MESSAGES,
+    assist_context: str | None = None,
+    state: Any = None,
+    ptl_retry_limit: int = 0,
+    hook_context: object | None = None,
+) -> AutoCompactResult:
+    if ptl_retry_limit < 0:
+        raise ValueError("ptl_retry_limit must be non-negative")
+    if threshold_tokens is None:
+        return AutoCompactResult(messages=list(messages))
+    if threshold_tokens < 1:
+        raise ValueError("threshold_tokens must be positive")
+    if estimate_message_tokens(messages) < threshold_tokens:
+        return AutoCompactResult(messages=list(messages))
+    summary_source = list(messages)
+    pre_compact_context = _compact_hook_additional_context(
+        hook_context,
+        event="PreCompact",
+        data={"trigger": "auto_compact", "message_count": len(summary_source)},
+    )
+    post_compact_context = _compact_hook_additional_context(
+        hook_context,
+        event="PostCompact",
+        data={"trigger": "auto_compact", "message_count": len(messages)},
+    )
+    summarizer_assist = _combine_assist_context(assist_context, pre_compact_context)
+    attempts = 0
+    try:
+        while True:
+            try:
+                summary = generate_compact_summary(
+                    _messages_as_compact_dicts(summary_source),
+                    summarizer,
+                    assist_context=summarizer_assist,
+                )
+                break
+            except Exception as exc:
+                if not is_prompt_too_long_error(exc) or attempts >= ptl_retry_limit:
+                    raise
+                next_source = _drop_oldest_compact_source_group(summary_source)
+                if not next_source or len(next_source) == len(summary_source):
+                    raise
+                summary_source = next_source
+                attempts += 1
+        _maybe_refresh_session_memory_state(state, messages=messages, summary=summary)
+        compacted = compact_live_messages_with_summary(
+            messages,
+            summary=summary,
+            keep_recent_messages=keep_recent_messages,
+            state=state,
+            post_compact_context=post_compact_context,
+        )
+    except Exception:
+        return AutoCompactResult(messages=list(messages), attempted=True, failed=True)
+    return AutoCompactResult(
+        messages=compacted,
+        attempted=True,
+        compacted=True,
+    )
+
+
+def compact_live_messages_with_summary(
+    messages: Sequence[BaseMessage],
+    *,
+    summary: str,
+    keep_recent_messages: int = DEFAULT_KEEP_RECENT_MESSAGES,
+    state: Any = None,
+    post_compact_context: Sequence[str] = (),
+) -> list[BaseMessage]:
+    return compact_live_messages_with_result(
+        messages,
+        summary=summary,
+        keep_recent_messages=keep_recent_messages,
+        state=state,
+        post_compact_context=post_compact_context,
+    ).render()
+
+
+def compact_live_messages_with_result(
+    messages: Sequence[BaseMessage],
+    *,
+    summary: str,
+    keep_recent_messages: int = DEFAULT_KEEP_RECENT_MESSAGES,
+    state: Any = None,
+    post_compact_context: Sequence[str] = (),
+) -> LiveCompactionResult:
+    if not messages:
+        raise ValueError("messages are required for compaction")
+    if keep_recent_messages < 0:
+        raise ValueError("keep_recent_messages must be non-negative")
+    if not summary.strip():
+        raise ValueError("summary is required for compaction")
+
+    clean_messages = [
+        message.model_copy(deep=True)
+        for message in messages
+        if not _is_live_pressure_artifact_message(message)
+    ]
+    keep_start = _adjust_keep_start_for_live_tool_pairs(
+        clean_messages,
+        max(0, len(clean_messages) - keep_recent_messages),
+    )
+    preserved_tail = clean_messages[keep_start:]
+    if not preserved_tail:
+        raise ValueError("compaction requires a preserved tail")
+    restored_paths = _restored_persisted_output_paths(
+        compacted_messages=clean_messages[:keep_start],
+        preserved_tail=preserved_tail,
+    )
+
+    restoration_messages: list[SystemMessage] = []
+    if restored_paths:
+        restoration_messages.append(
+            SystemMessage(
+                content=(
+                    f"{LIVE_COMPACT_RESTORATION_PREFIX}\n"
+                    + "\n".join(f"- {path}" for path in restored_paths)
+                )
+            )
+        )
+    restoration_messages.extend(_post_compact_state_restoration_messages(state))
+    restoration_messages.extend(
+        _post_compact_hook_restoration_messages(post_compact_context)
+    )
+    result = LiveCompactionResult(
+        boundary_message=SystemMessage(
+            content=(
+                f"{LIVE_COMPACT_BOUNDARY_PREFIX}: "
+                f"original_messages={len(clean_messages)}; "
+                f"summarized_messages={keep_start}; "
+                f"kept_messages={len(preserved_tail)}"
+            )
+        ),
+        summary_message=HumanMessage(
+            content=f"{LIVE_COMPACT_SUMMARY_PREFIX}\n\nSummary:\n{summary.strip()}"
+        ),
+        restoration_messages=tuple(restoration_messages),
+        preserved_tail=tuple(preserved_tail),
+        trigger="auto_compact",
+        original_token_estimate=estimate_message_tokens(clean_messages),
+    )
+    return _with_projected_token_estimate(result)
+
+
+def reactive_compact_messages(
+    messages: Sequence[BaseMessage],
+    *,
+    summarizer: Any,
+    keep_recent_messages: int = DEFAULT_KEEP_RECENT_MESSAGES,
+    assist_context: str | None = None,
+    state: Any = None,
+) -> list[BaseMessage]:
+    summary = generate_compact_summary(
+        _messages_as_compact_dicts(messages),
+        summarizer,
+        assist_context=assist_context,
+    )
+    _maybe_refresh_session_memory_state(state, messages=messages, summary=summary)
+    return compact_live_messages_with_summary(
+        messages,
+        summary=summary,
+        keep_recent_messages=keep_recent_messages,
+        state=state,
+    )
+
+
+def drain_collapse_projection_messages(
+    messages: Sequence[BaseMessage],
+) -> list[BaseMessage]:
+    drained: list[BaseMessage] = []
+    index = 0
+    changed = False
+    while index < len(messages):
+        message = messages[index]
+        if (
+            isinstance(message, SystemMessage)
+            and str(message.content).startswith(LIVE_COLLAPSE_BOUNDARY_PREFIX)
+            and index + 1 < len(messages)
+            and isinstance(messages[index + 1], HumanMessage)
+            and str(messages[index + 1].content).startswith(
+                LIVE_COLLAPSE_SUMMARY_PREFIX
+            )
+        ):
+            drained.append(
+                SystemMessage(
+                    content=(
+                        f"{LIVE_COLLAPSE_BOUNDARY_PREFIX}: "
+                        "trigger=overflow_drain; drained_summaries=1"
+                    )
+                )
+            )
+            index += 2
+            changed = True
+            continue
+        drained.append(message)
+        index += 1
+    return drained if changed else list(messages)
+
+
+def estimate_message_tokens(messages: Sequence[BaseMessage]) -> int:
+    return sum(_estimate_message_tokens(message) for message in messages)
+
+
+def _response_token_estimate(response: object) -> int:
+    result = getattr(response, "result", None)
+    if isinstance(result, Sequence) and not isinstance(result, (str, bytes, bytearray)):
+        total = 0
+        for item in result:
+            if isinstance(item, BaseMessage):
+                total += _estimate_message_tokens(item)
+            else:
+                total += _estimate_text_tokens(str(item))
+        return total
+    if result is not None:
+        return _estimate_text_tokens(str(result))
+    structured = getattr(response, "structured_response", None)
+    if structured is not None:
+        return _estimate_text_tokens(str(structured))
+    return 0
+
+
+def _response_message_count(response: object) -> int:
+    result = getattr(response, "result", None)
+    if isinstance(result, Sequence) and not isinstance(result, (str, bytes, bytearray)):
+        return len(result)
+    return 1 if result is not None else 0
+
+
+def _estimate_message_tokens(message: BaseMessage) -> int:
+    text = _message_text(message)
+    if not text:
+        return 0
+    return _estimate_text_tokens(text)
+
+
+def _estimate_text_tokens(text: str) -> int:
+    if not text:
+        return 0
+    return max(1, (len(text) + 3) // 4)
+
+
+def _message_text(message: BaseMessage) -> str:
+    if isinstance(message, AIMessage):
+        parts = [str(message.content or "")]
+        if message.tool_calls:
+            parts.extend(
+                f"{call.get('name', '')} {call.get('args', {})}" for call in message.tool_calls
+            )
+        return "\n".join(part for part in parts if part).strip()
+    if isinstance(message, ToolMessage):
+        return str(message.content or "").strip()
+    return str(getattr(message, "content", "")).strip()
+
+
+def _messages_as_compact_dicts(messages: Sequence[BaseMessage]) -> list[dict[str, Any]]:
+    rendered: list[dict[str, Any]] = []
+    for message in messages:
+        if isinstance(message, SystemMessage):
+            role = "system"
+        elif isinstance(message, AIMessage):
+            role = "assistant"
+        else:
+            role = "user"
+        rendered.append({"role": role, "content": _message_text(message)})
+    return rendered
+
+
+def _drop_oldest_compact_source_group(
+    messages: Sequence[BaseMessage],
+) -> list[BaseMessage]:
+    if len(messages) <= 1:
+        return []
+    first = messages[0]
+    drop_count = 1
+    if isinstance(first, AIMessage):
+        tool_call_ids = {
+            str(call["id"])
+            for call in first.tool_calls
+            if isinstance(call.get("id"), str)
+        }
+        while drop_count < len(messages):
+            candidate = messages[drop_count]
+            if not isinstance(candidate, ToolMessage):
+                break
+            if candidate.tool_call_id not in tool_call_ids:
+                break
+            drop_count += 1
+    elif isinstance(first, ToolMessage):
+        while drop_count < len(messages) and isinstance(messages[drop_count], ToolMessage):
+            drop_count += 1
+    return list(messages[drop_count:])
+
+
+def _has_collapsible_source(
+    messages: Sequence[BaseMessage], *, keep_recent_messages: int
+) -> bool:
+    clean_messages = [
+        message.model_copy(deep=True)
+        for message in messages
+        if not _is_live_pressure_artifact_message(message)
+    ]
+    keep_start = _collapse_keep_start_index(
+        clean_messages,
+        keep_recent_messages=keep_recent_messages,
+    )
+    return keep_start > 0
+
+
+def _is_live_compact_message(message: BaseMessage) -> bool:
+    content = str(getattr(message, "content", ""))
+    return content.startswith(LIVE_COMPACT_BOUNDARY_PREFIX) or content.startswith(
+        LIVE_COMPACT_SUMMARY_PREFIX
+    )
+
+
+def _is_live_collapse_message(message: BaseMessage) -> bool:
+    content = str(getattr(message, "content", ""))
+    return content.startswith(LIVE_COLLAPSE_BOUNDARY_PREFIX) or content.startswith(
+        LIVE_COLLAPSE_SUMMARY_PREFIX
+    )
+
+
+def _is_live_snip_message(message: BaseMessage) -> bool:
+    content = str(getattr(message, "content", ""))
+    return content.startswith(LIVE_SNIP_BOUNDARY_PREFIX)
+
+
+def _is_live_pressure_artifact_message(message: BaseMessage) -> bool:
+    return (
+        _is_live_compact_message(message)
+        or _is_live_collapse_message(message)
+        or _is_live_snip_message(message)
+        or str(getattr(message, "content", "")).startswith(LIVE_COMPACT_RESTORATION_PREFIX)
+    )
+
+
+def _adjust_keep_start_for_live_tool_pairs(
+    messages: Sequence[BaseMessage], start_index: int
+) -> int:
+    if start_index <= 0 or start_index >= len(messages):
+        return start_index
+
+    needed_tool_calls = {
+        message.tool_call_id
+        for message in messages[start_index:]
+        if isinstance(message, ToolMessage) and message.tool_call_id
+    }
+    if not needed_tool_calls:
+        return start_index
+
+    kept_tool_calls: set[str] = set()
+    for message in messages[start_index:]:
+        if isinstance(message, AIMessage):
+            kept_tool_calls.update(
+                str(call["id"])
+                for call in message.tool_calls
+                if isinstance(call.get("id"), str)
+            )
+    missing = needed_tool_calls - kept_tool_calls
+    adjusted = start_index
+    for index in range(start_index - 1, -1, -1):
+        message = messages[index]
+        if isinstance(message, AIMessage):
+            tool_calls = {
+                str(call["id"])
+                for call in message.tool_calls
+                if isinstance(call.get("id"), str)
+            }
+            if missing & tool_calls:
+                adjusted = index
+                missing -= tool_calls
+            if not missing:
+                break
+    return adjusted
+
+
+def _collapse_keep_start_index(
+    messages: Sequence[BaseMessage], *, keep_recent_messages: int
+) -> int:
+    start_index = _adjust_keep_start_for_live_tool_pairs(
+        messages,
+        max(0, len(messages) - keep_recent_messages),
+    )
+    return _adjust_keep_start_for_assistant_round(messages, start_index)
+
+
+def _adjust_keep_start_for_assistant_round(
+    messages: Sequence[BaseMessage], start_index: int
+) -> int:
+    """Avoid cutting the preserved tail in the middle of a recent assistant round.
+
+    Public `cc-haha` evidence shows compaction/collapse logic prefers
+    assistant API-round boundaries rather than arbitrary message cuts. Locally
+    we do not have the same message-id topology, but we can still avoid
+    splitting a recent assistant-led work unit by snapping backward to the
+    nearest preceding assistant message when the preserved tail currently starts
+    on a non-assistant message.
+    """
+
+    if start_index <= 0 or start_index >= len(messages):
+        return start_index
+    if isinstance(messages[start_index], AIMessage):
+        return start_index
+    for index in range(start_index - 1, -1, -1):
+        if isinstance(messages[index], AIMessage):
+            return index
+    return start_index
+
+
+def _restored_persisted_output_paths(
+    *,
+    compacted_messages: Sequence[BaseMessage],
+    preserved_tail: Sequence[BaseMessage],
+) -> list[str]:
+    preserved_paths = {
+        path for message in preserved_tail if (path := _persisted_output_path(message)) is not None
+    }
+    restored: list[str] = []
+    for message in compacted_messages:
+        path = _persisted_output_path(message)
+        if path is None or path in preserved_paths or path in restored:
+            continue
+        restored.append(path)
+    return restored
+
+
+def _post_compact_state_restoration_messages(state: Any) -> list[SystemMessage]:
+    if not isinstance(state, dict):
+        return []
+    todos = state.get("todos")
+    if not isinstance(todos, list):
+        return []
+    active_lines: list[str] = []
+    for item in todos:
+        if not isinstance(item, dict):
+            continue
+        status = item.get("status")
+        if status not in {"pending", "in_progress"}:
+            continue
+        content = item.get("content")
+        if not isinstance(content, str) or not content.strip():
+            continue
+        active_lines.append(f"- [{status}] {content.strip()}")
+        if len(active_lines) >= 6:
+            break
+    if not active_lines:
+        return []
+    return [
+        SystemMessage(
+            content=(
+                "Post-compact restored state:\n"
+                "Active todos:\n"
+                + "\n".join(active_lines)
+            )
+        )
+    ]
+
+
+def _post_compact_hook_restoration_messages(
+    contexts: Sequence[str],
+) -> list[SystemMessage]:
+    cleaned = tuple(_bounded_context_line(context) for context in contexts)
+    lines = tuple(line for line in cleaned if line)
+    if not lines:
+        return []
+    return [
+        SystemMessage(
+            content=(
+                "PostCompact hook context:\n"
+                + "\n".join(f"- {line}" for line in lines[:6])
+            )
+        )
+    ]
+
+
+def _compact_hook_additional_context(
+    context: object | None,
+    *,
+    event: HookEventName,
+    data: dict[str, object],
+) -> tuple[str, ...]:
+    if context is None:
+        return ()
+    outcome = dispatch_context_hook(
+        context=context,
+        session_id=str(getattr(context, "session_id", "unknown")),
+        event=event,
+        data=data,
+    )
+    if outcome is None or outcome.blocked:
+        return ()
+    return tuple(
+        line
+        for item in outcome.additional_context
+        if (line := _bounded_context_line(item))
+    )
+
+
+def _combine_assist_context(
+    assist_context: str | None, additions: Sequence[str]
+) -> str | None:
+    parts = [assist_context.strip()] if assist_context and assist_context.strip() else []
+    parts.extend(additions)
+    return "\n\n".join(parts) if parts else None
+
+
+def _bounded_context_line(value: str) -> str:
+    line = " ".join(value.strip().split())
+    if not line:
+        return ""
+    return line[:1000]
+
+
+def _persisted_output_path(message: BaseMessage) -> str | None:
+    if not isinstance(message, ToolMessage):
+        return None
+    artifact = message.artifact if isinstance(message.artifact, dict) else None
+    if artifact is None or artifact.get("kind") != "persisted_output":
+        return None
+    path = artifact.get("path")
+    return path.strip() if isinstance(path, str) and path.strip() else None
+
+
+def _auto_compact_hidden_message_count(
+    source_messages: Sequence[BaseMessage],
+    compacted_messages: Sequence[BaseMessage],
+) -> int:
+    if compacted_messages:
+        content = str(getattr(compacted_messages[0], "content", ""))
+        for part in content.split(";"):
+            key, separator, value = part.strip().partition("=")
+            if separator and key == "summarized_messages":
+                try:
+                    return max(0, int(value))
+                except ValueError:
+                    break
+    source_count = len(
+        [
+            message
+            for message in source_messages
+            if not _is_live_pressure_artifact_message(message)
+        ]
+    )
+    compacted_count = len(
+        [
+            message
+            for message in compacted_messages
+            if not _is_live_pressure_artifact_message(message)
+        ]
+    )
+    return max(0, source_count - compacted_count)
+
+
+def is_prompt_too_long_error(error: Exception) -> bool:
+    message = str(error).lower()
+    return any(
+        pattern in message
+        for pattern in (
+            "prompt too long",
+            "context length",
+            "maximum context length",
+            "context window",
+            "too many tokens",
+            "token limit",
+        )
+    )
+
+
+def _session_memory_assist_text(
+    state: Any, messages: Sequence[BaseMessage]
+) -> str | None:
+    if not isinstance(state, dict):
+        return None
+    artifact = read_session_memory_artifact(state)
+    if artifact is None:
+        return None
+    metrics = session_memory_metrics(_messages_as_compact_dicts(messages))
+    return compact_summary_assist_text(
+        artifact,
+        current_message_count=metrics.message_count,
+        current_token_count=metrics.estimated_token_count,
+        current_tool_call_count=metrics.tool_call_count,
+    )
+
+
+def _maybe_refresh_session_memory_state(
+    state: Any, *, messages: Sequence[BaseMessage], summary: str
+) -> bool:
+    if not isinstance(state, dict):
+        return False
+    return update_session_memory_from_summary(
+        state,
+        messages=_messages_as_compact_dicts(messages),
+        summary=summary,
+        source="live_compact",
+    )
+
+
+def _emit_runtime_pressure_event(
+    request: ModelRequest,
+    *,
+    kind: str,
+    message: str,
+    metadata: dict[str, object],
+) -> None:
+    context = getattr(request.runtime, "context", None)
+    sink = getattr(context, "event_sink", None)
+    session_id = str(getattr(context, "session_id", "unknown"))
+    runtime_event = RuntimeEvent(
+        kind=kind,
+        message=message,
+        session_id=session_id,
+        metadata=metadata,
+    )
+    emit = getattr(sink, "emit", None)
+    if callable(emit):
+        emit(runtime_event)
+    append_runtime_event_evidence(context=context, event=runtime_event)
+
+
+def _count_compacted_tool_results(messages: Sequence[BaseMessage]) -> int:
+    return sum(
+        1
+        for message in messages
+        if isinstance(message, ToolMessage)
+        and str(message.content).startswith(MICROCOMPACT_CLEARED_MESSAGE)
+    )
+
+
+def _is_snipped(messages: Sequence[BaseMessage]) -> bool:
+    return bool(messages) and isinstance(messages[0], SystemMessage) and str(
+        messages[0].content
+    ).startswith(LIVE_SNIP_BOUNDARY_PREFIX)
+
+
+def _is_collapsed(messages: Sequence[BaseMessage]) -> bool:
+    return bool(messages) and isinstance(messages[0], SystemMessage) and str(
+        messages[0].content
+    ).startswith(LIVE_COLLAPSE_BOUNDARY_PREFIX)
+
+
+def _is_live_compacted(messages: Sequence[BaseMessage]) -> bool:
+    return bool(messages) and isinstance(messages[0], SystemMessage) and str(
+        messages[0].content
+    ).startswith(LIVE_COMPACT_BOUNDARY_PREFIX)
+
+
+def _snip_hidden_message_count(messages: Sequence[BaseMessage]) -> int:
+    return _metadata_count_from_first_message(messages, "hidden_messages")
+
+
+def _collapse_collapsed_message_count(messages: Sequence[BaseMessage]) -> int:
+    return _metadata_count_from_first_message(messages, "collapsed_messages")
+
+
+def _metadata_count_from_first_message(
+    messages: Sequence[BaseMessage], field_name: str
+) -> int:
+    if not messages:
+        return 0
+    content = str(getattr(messages[0], "content", ""))
+    marker = f"{field_name}="
+    if marker not in content:
+        return 0
+    raw_value = content.split(marker, 1)[1].split(";", 1)[0].strip()
+    try:
+        return max(0, int(raw_value))
+    except ValueError:
+        return 0
+
+
+def _restored_path_count(messages: Sequence[BaseMessage]) -> int:
+    for message in messages:
+        if isinstance(message, SystemMessage) and str(message.content).startswith(
+            LIVE_COMPACT_RESTORATION_PREFIX
+        ):
+            return max(0, len(str(message.content).splitlines()) - 1)
+    return 0
+
+
+def _runtime_transcript_projection(
+    request: ModelRequest,
+) -> TranscriptProjection | None:
+    context = getattr(request.runtime, "context", None)
+    projection = getattr(context, "transcript_projection", None)
+    return projection if isinstance(projection, TranscriptProjection) else None
+
+
+def _projection_after_snip(
+    messages: Sequence[BaseMessage],
+    projection: TranscriptProjection | None,
+    *,
+    keep_recent_messages: int,
+) -> TranscriptProjection | None:
+    if projection is None or len(projection.entries) != len(messages):
+        return projection
+    clean_pairs = [
+        (message, entry)
+        for message, entry in zip(messages, projection.entries, strict=True)
+        if not _is_live_pressure_artifact_message(message)
+    ]
+    clean_messages = [message for message, _entry in clean_pairs]
+    clean_entries = [entry for _message, entry in clean_pairs]
+    keep_start = _adjust_keep_start_for_live_tool_pairs(
+        clean_messages,
+        max(0, len(clean_messages) - keep_recent_messages),
+    )
+    if keep_start <= 0:
+        return projection
+    return TranscriptProjection(entries=((), *clean_entries[keep_start:]))
+
+
+def _append_collapse_record(
+    request: ModelRequest,
+    *,
+    source_messages: Sequence[BaseMessage],
+    projection: TranscriptProjection | None,
+    collapsed_messages: Sequence[BaseMessage],
+    threshold_tokens: int | None,
+    context_window_tokens: int | None,
+    trigger_ratio: float | None,
+    used_session_memory_assist: bool,
+) -> bool:
+    context = getattr(request.runtime, "context", None)
+    session_context = getattr(context, "session_context", None)
+    if not isinstance(session_context, SessionContext):
+        return False
+    if projection is None or len(projection.entries) != len(source_messages):
+        return False
+    collapsed_count = _collapse_collapsed_message_count(collapsed_messages)
+    if collapsed_count <= 0:
+        return False
+    covered_message_ids = _covered_projection_ids_for_prefix(
+        source_messages,
+        projection,
+        collapsed_count,
+    )
+    if not covered_message_ids:
+        return False
+    summary = _collapse_summary_text(collapsed_messages)
+    if summary is None:
+        return False
+    pressure_metadata = _pressure_metadata(
+        source_messages,
+        context_window_tokens=context_window_tokens,
+    )
+    JsonlSessionStore(session_context.store_dir).append_collapse(
+        session_context,
+        trigger="threshold_tokens",
+        summary=summary,
+        start_message_id=covered_message_ids[0],
+        end_message_id=covered_message_ids[-1],
+        covered_message_ids=list(covered_message_ids),
+        metadata={
+            "source": "runtime_pressure",
+            "strategy": "context_collapse",
+            "estimated_token_count": estimate_message_tokens(source_messages),
+            "threshold_tokens": threshold_tokens,
+            "context_window_tokens": context_window_tokens,
+            "trigger_ratio_percent": int(trigger_ratio * 100)
+            if trigger_ratio is not None
+            else None,
+            "entrypoint": getattr(context, "entrypoint", None),
+            "agent_name": getattr(context, "agent_name", None),
+            "used_session_memory_assist": used_session_memory_assist,
+            **pressure_metadata,
+        },
+    )
+    return True
+
+
+def _covered_projection_ids_for_prefix(
+    messages: Sequence[BaseMessage],
+    projection: TranscriptProjection,
+    collapsed_count: int,
+) -> tuple[str, ...]:
+    covered: list[str] = []
+    remaining = collapsed_count
+    for message, entry in zip(messages, projection.entries, strict=True):
+        if _is_live_pressure_artifact_message(message):
+            continue
+        covered.extend(entry)
+        remaining -= 1
+        if remaining <= 0:
+            break
+    return tuple(covered)
+
+
+def _collapse_summary_text(messages: Sequence[BaseMessage]) -> str | None:
+    if len(messages) < 2 or not isinstance(messages[1], HumanMessage):
+        return None
+    prefix = f"{LIVE_COLLAPSE_SUMMARY_PREFIX}\n\nSummary:\n"
+    content = str(messages[1].content)
+    if not content.startswith(prefix):
+        return None
+    summary = content[len(prefix) :].strip()
+    return summary or None
+
+
+def _pressure_metadata(
+    messages: Sequence[BaseMessage],
+    *,
+    context_window_tokens: int | None,
+) -> dict[str, int]:
+    estimated_tokens = estimate_message_tokens(messages)
+    metadata = {"estimated_token_count": estimated_tokens}
+    if context_window_tokens is not None and context_window_tokens > 0:
+        metadata["context_window_tokens"] = context_window_tokens
+        metadata["estimated_token_ratio_percent"] = int(
+            (estimated_tokens / context_window_tokens) * 100
+        )
+    return metadata
+
+
+def _drained_collapse_summary_count(messages: Sequence[BaseMessage]) -> int:
+    count = 0
+    for index, message in enumerate(messages[:-1]):
+        if (
+            isinstance(message, SystemMessage)
+            and str(message.content).startswith(LIVE_COLLAPSE_BOUNDARY_PREFIX)
+            and isinstance(messages[index + 1], HumanMessage)
+            and str(messages[index + 1].content).startswith(
+                LIVE_COLLAPSE_SUMMARY_PREFIX
+            )
+        ):
+            count += 1
+    return count
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..eddbd2c2f
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/compact/summarizer.py
@@ -0,0 +1,124 @@
+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,
+    assist_context: str | None = None,
+) -> list[dict[str, Any]]:
+    request = [*deepcopy(messages)]
+    if assist_context and assist_context.strip():
+        request.append(
+            {
+                "role": "system",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": assist_context.strip(),
+                    }
+                ],
+            }
+        )
+    request.append(
+        {
+            "role": "user",
+            "content": [
+                {
+                    "type": "text",
+                    "text": build_compact_summary_prompt(custom_instructions),
+                }
+            ],
+        }
+    )
+    return request
+
+
+def generate_compact_summary(
+    messages: list[dict[str, Any]],
+    summarizer: CompactSummarizer | Callable[[list[dict[str, Any]]], Any],
+    *,
+    custom_instructions: str | None = None,
+    assist_context: str | None = None,
+) -> str:
+    request = build_compact_summary_request(
+        messages,
+        custom_instructions=custom_instructions,
+        assist_context=assist_context,
+    )
+    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/compact/tool_results.py b/coding-deepgent/src/coding_deepgent/compact/tool_results.py
new file mode 100644
index 000000000..1e24d3d64
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/compact/tool_results.py
@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from langchain.messages import ToolMessage
+
+from coding_deepgent.runtime.context import RuntimeContext
+
+PERSISTED_OUTPUT_TAG = "<persisted-output>"
+PERSISTED_OUTPUT_CLOSING_TAG = "</persisted-output>"
+TOOL_RESULTS_DIR = ".coding-deepgent/tool-results"
+DEFAULT_PREVIEW_CHARS = 2000
+
+
+@dataclass(frozen=True, slots=True)
+class PersistedToolResult:
+    relative_path: str
+    absolute_path: Path
+    original_length: int
+    preview: str
+    has_more: bool
+    serialized_kind: str
+
+
+def maybe_persist_large_tool_result(
+    result: ToolMessage,
+    *,
+    runtime_context: RuntimeContext,
+    max_inline_chars: int | None,
+    preview_chars: int = DEFAULT_PREVIEW_CHARS,
+) -> ToolMessage:
+    if result.status != "success":
+        return result
+    if max_inline_chars is None or max_inline_chars < 1:
+        return result
+
+    serialized, serialized_kind = _serialize_content(result.content)
+    if len(serialized) <= max_inline_chars:
+        return result
+
+    persisted = persist_tool_result(
+        serialized,
+        runtime_context=runtime_context,
+        tool_call_id=result.tool_call_id,
+        serialized_kind=serialized_kind,
+        preview_chars=preview_chars,
+    )
+    artifact = {
+        "kind": "persisted_output",
+        "path": persisted.relative_path,
+        "original_length": persisted.original_length,
+        "preview_chars": preview_chars,
+        "serialized_kind": persisted.serialized_kind,
+        "has_more": persisted.has_more,
+    }
+    if result.artifact is not None:
+        artifact["upstream_artifact"] = result.artifact
+
+    return ToolMessage(
+        content=build_large_tool_result_message(persisted),
+        tool_call_id=result.tool_call_id,
+        artifact=artifact,
+        status=result.status,
+        additional_kwargs=dict(result.additional_kwargs),
+        response_metadata=dict(result.response_metadata),
+        name=result.name,
+        id=result.id,
+    )
+
+
+def persist_tool_result(
+    content: str,
+    *,
+    runtime_context: RuntimeContext,
+    tool_call_id: str,
+    serialized_kind: str,
+    preview_chars: int = DEFAULT_PREVIEW_CHARS,
+) -> PersistedToolResult:
+    result_dir = tool_results_dir(runtime_context)
+    result_dir.mkdir(parents=True, exist_ok=True)
+    filename = f"{sanitize_path_segment(tool_call_id)}.{_file_extension(serialized_kind)}"
+    absolute_path = result_dir / filename
+    if not absolute_path.exists():
+        absolute_path.write_text(content, encoding="utf-8")
+
+    preview = content[:preview_chars]
+    relative_path = absolute_path.relative_to(runtime_context.workdir).as_posix()
+    return PersistedToolResult(
+        relative_path=relative_path,
+        absolute_path=absolute_path,
+        original_length=len(content),
+        preview=preview,
+        has_more=len(content) > preview_chars,
+        serialized_kind=serialized_kind,
+    )
+
+
+def tool_results_dir(runtime_context: RuntimeContext) -> Path:
+    return (
+        runtime_context.workdir
+        / TOOL_RESULTS_DIR
+        / sanitize_path_segment(runtime_context.session_id)
+    )
+
+
+def build_large_tool_result_message(result: PersistedToolResult) -> str:
+    lines = [
+        PERSISTED_OUTPUT_TAG,
+        (
+            f"Output too large ({result.original_length} chars). "
+            f"Full output saved to: {result.relative_path}"
+        ),
+        "",
+        f"Preview (first {len(result.preview)} chars):",
+        result.preview,
+    ]
+    if result.has_more:
+        lines.append("...")
+    lines.append(PERSISTED_OUTPUT_CLOSING_TAG)
+    return "\n".join(lines)
+
+
+def sanitize_path_segment(value: str) -> str:
+    sanitized = re.sub(r"[^A-Za-z0-9._-]+", "-", value.strip())
+    return sanitized.strip(".-") or "value"
+
+
+def _serialize_content(content: Any) -> tuple[str, str]:
+    if isinstance(content, str):
+        return content, "text"
+    if isinstance(content, list):
+        return json.dumps(content, ensure_ascii=False, sort_keys=True, default=str), "json"
+    return str(content), "text"
+
+
+def _file_extension(serialized_kind: str) -> str:
+    return "json" if serialized_kind == "json" else "txt"
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..53894a521
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/containers/__init__.py
@@ -0,0 +1,17 @@
+from .app import AppContainer
+from .filesystem import FilesystemContainer
+from .memory_backend import MemoryBackendContainer
+from .runtime import RuntimeContainer
+from .sessions import SessionsContainer
+from .todo import TodoContainer
+from .tool_system import ToolSystemContainer
+
+__all__ = [
+    "AppContainer",
+    "FilesystemContainer",
+    "MemoryBackendContainer",
+    "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..6ee1b5d62
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/containers/app.py
@@ -0,0 +1,145 @@
+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.compact import RuntimePressureMiddleware
+from coding_deepgent import extensions_service
+from coding_deepgent.memory import MemoryContextMiddleware
+from coding_deepgent.sessions.session_memory_middleware import (
+    SessionMemoryContextMiddleware,
+)
+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 .memory_backend import MemoryBackendContainer
+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)
+    memory_backend: Any = providers.Container(MemoryBackendContainer, 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
+    )
+    session_memory_middleware: Any = providers.Factory(SessionMemoryContextMiddleware)
+    session_memory_middleware_list: Any = providers.Callable(
+        agent_service.singleton_list, session_memory_middleware
+    )
+    runtime_pressure_middleware: Any = providers.Factory(
+        RuntimePressureMiddleware,
+        registry=tool_system.capability_registry,
+        keep_recent_tool_results=settings.provided.keep_recent_tool_results,
+        microcompact_time_gap_minutes=settings.provided.microcompact_time_gap_minutes,
+        microcompact_min_saved_tokens=settings.provided.microcompact_min_saved_tokens,
+        microcompact_protect_recent_tokens=(
+            settings.provided.microcompact_protect_recent_tokens
+        ),
+        microcompact_min_prune_saved_tokens=(
+            settings.provided.microcompact_min_prune_saved_tokens
+        ),
+        main_entrypoint=settings.provided.entrypoint,
+        main_agent_name=settings.provided.agent_name,
+        snip_threshold_tokens=settings.provided.snip_threshold_tokens,
+        keep_recent_messages_after_snip=(
+            settings.provided.keep_recent_messages_after_snip
+        ),
+        collapse_threshold_tokens=settings.provided.collapse_threshold_tokens,
+        keep_recent_messages_after_collapse=(
+            settings.provided.keep_recent_messages_after_collapse
+        ),
+        model_context_window_tokens=settings.provided.model_context_window_tokens,
+        collapse_trigger_ratio=settings.provided.collapse_trigger_ratio,
+        auto_compact_threshold_tokens=settings.provided.auto_compact_threshold_tokens,
+        auto_compact_max_failures=settings.provided.auto_compact_max_failures,
+        auto_compact_ptl_retry_limit=settings.provided.auto_compact_ptl_retry_limit,
+        keep_recent_messages=settings.provided.keep_recent_messages_after_compact,
+    )
+    runtime_pressure_middleware_list: Any = providers.Callable(
+        agent_service.singleton_list, runtime_pressure_middleware
+    )
+    middleware: Any = providers.Callable(
+        agent_service.combine_middleware,
+        todo.middleware_list,
+        memory_middleware_list,
+        session_memory_middleware_list,
+        runtime_pressure_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/memory_backend.py b/coding-deepgent/src/coding_deepgent/containers/memory_backend.py
new file mode 100644
index 000000000..44197f587
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/containers/memory_backend.py
@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from typing import Any
+
+from dependency_injector import containers, providers
+from redis import Redis
+
+from coding_deepgent.memory.extractor import extract_memory_candidates
+from coding_deepgent.memory.archive import (
+    S3ArchiveSettings,
+    S3MemoryArchiveStore,
+)
+from coding_deepgent.memory.backend import (
+    create_memory_engine,
+    migrate_memory_schema,
+    SqlAlchemyMemoryRepository,
+)
+from coding_deepgent.memory.queue import InMemoryQueue, RedisMemoryQueue
+from coding_deepgent.memory.service import MemoryService
+from coding_deepgent.settings import Settings
+
+
+def _resolve_memory_database_url(settings: Settings) -> str:
+    if settings.postgres_url:
+        return settings.postgres_url
+    db_path = (settings.workdir / ".coding-deepgent" / "memory.db").resolve()
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    return f"sqlite+pysqlite:///{db_path}"
+
+
+def _build_memory_queue(settings: Settings):
+    if settings.redis_url:
+        return RedisMemoryQueue(Redis.from_url(settings.redis_url))
+    return InMemoryQueue()
+
+
+def _build_archive_store(settings: Settings):
+    if settings.offload_backend != "s3":
+        return None
+    required = (
+        settings.s3_bucket,
+        settings.s3_endpoint_url,
+        settings.s3_region,
+        settings.s3_access_key_id,
+        settings.s3_secret_access_key,
+    )
+    if any(value in (None, "") for value in required):
+        return None
+    assert settings.s3_secret_access_key is not None
+    return S3MemoryArchiveStore(
+        S3ArchiveSettings(
+            bucket=str(settings.s3_bucket),
+            endpoint_url=str(settings.s3_endpoint_url),
+            region=str(settings.s3_region),
+            access_key_id=str(settings.s3_access_key_id),
+            secret_access_key=settings.s3_secret_access_key.get_secret_value(),
+        )
+    )
+
+
+class MemoryBackendContainer(containers.DeclarativeContainer):
+    settings: Any = providers.Dependency()
+
+    engine: Any = providers.Singleton(create_memory_engine, providers.Callable(_resolve_memory_database_url, settings))
+    migrate: Any = providers.Callable(migrate_memory_schema, engine)
+    repository: Any = providers.Singleton(SqlAlchemyMemoryRepository, engine)
+    queue: Any = providers.Singleton(_build_memory_queue, settings)
+    archive_store: Any = providers.Singleton(_build_archive_store, settings)
+    extractor: Any = providers.Object(extract_memory_candidates)
+    service: Any = providers.Singleton(
+        MemoryService,
+        repository=repository,
+        queue=queue,
+        archive_store=archive_store,
+        extractor=extractor,
+    )
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..47b8abc07
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/containers/runtime.py
@@ -0,0 +1,48 @@
+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 (
+    PlanningState,
+    QueuedRuntimeEventSink,
+    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(QueuedRuntimeEventSink)
+    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,
+        store_path=settings.provided.store_path,
+    )
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..140e12862
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/containers/tool_system.py
@@ -0,0 +1,166 @@
+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 delete_memory, list_memory, 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 (
+    resume_fork,
+    resume_subagent,
+    run_fork,
+    run_subagent,
+    run_subagent_background,
+    subagent_list,
+    subagent_send_input,
+    subagent_stop,
+    subagent_status,
+)
+from coding_deepgent.tool_system.deferred import invoke_deferred_tool, tool_search
+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, list_memory, delete_memory])
+    )
+    skill_tools: Any = providers.Dependency(default=providers.Object([load_skill]))
+    deferred_bridge_tools: Any = providers.Dependency(
+        default=providers.Object([tool_search, invoke_deferred_tool])
+    )
+    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,
+                run_fork,
+                run_subagent_background,
+                subagent_list,
+                subagent_status,
+                subagent_send_input,
+                subagent_stop,
+                resume_subagent,
+                resume_fork,
+            ]
+        )
+    )
+    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,
+        deferred_bridge_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,
+        deferred_bridge_tools=deferred_bridge_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.project("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/continuity/__init__.py b/coding-deepgent/src/coding_deepgent/continuity/__init__.py
new file mode 100644
index 000000000..f3f6e19b5
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/continuity/__init__.py
@@ -0,0 +1,17 @@
+from .store import (
+    CONTINUITY_NAMESPACE,
+    ContinuityArtifact,
+    get_artifact,
+    list_artifacts,
+    mark_stale,
+    save_artifact,
+)
+
+__all__ = [
+    "CONTINUITY_NAMESPACE",
+    "ContinuityArtifact",
+    "get_artifact",
+    "list_artifacts",
+    "mark_stale",
+    "save_artifact",
+]
diff --git a/coding-deepgent/src/coding_deepgent/continuity/store.py b/coding-deepgent/src/coding_deepgent/continuity/store.py
new file mode 100644
index 000000000..08dc1fff8
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/continuity/store.py
@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from datetime import UTC, datetime
+from hashlib import sha256
+from typing import Literal, Protocol
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from coding_deepgent.event_stream import append_event
+
+CONTINUITY_NAMESPACE = ("coding_deepgent_continuity",)
+ContinuityStatus = Literal["current", "stale"]
+
+
+class ContinuityStore(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]: ...
+
+
+class ContinuityArtifact(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    artifact_id: str
+    title: str = Field(..., min_length=1)
+    content: str = Field(..., min_length=1)
+    session_id: str | None = None
+    source: str = Field(default="manual", min_length=1)
+    status: ContinuityStatus = "current"
+    created_at: str
+    updated_at: str
+
+
+def save_artifact(
+    store: ContinuityStore,
+    *,
+    title: str,
+    content: str,
+    session_id: str | None = None,
+    source: str = "manual",
+) -> ContinuityArtifact:
+    now = _now()
+    artifact = ContinuityArtifact(
+        artifact_id=_artifact_id(title=title, created_at=now),
+        title=title.strip(),
+        content=content.strip(),
+        session_id=session_id,
+        source=source.strip(),
+        created_at=now,
+        updated_at=now,
+    )
+    store.put(CONTINUITY_NAMESPACE, artifact.artifact_id, artifact.model_dump())
+    append_event(
+        store,
+        stream_id="continuity",
+        kind="continuity_saved",
+        payload={"artifact_id": artifact.artifact_id, "title": artifact.title},
+    )
+    return artifact
+
+
+def get_artifact(store: ContinuityStore, artifact_id: str) -> ContinuityArtifact:
+    item = store.get(CONTINUITY_NAMESPACE, artifact_id)
+    if item is None:
+        raise KeyError(f"Unknown continuity artifact: {artifact_id}")
+    return ContinuityArtifact.model_validate(_item_value(item))
+
+
+def list_artifacts(
+    store: ContinuityStore,
+    *,
+    include_stale: bool = False,
+) -> list[ContinuityArtifact]:
+    records = [
+        ContinuityArtifact.model_validate(_item_value(item))
+        for item in store.search(CONTINUITY_NAMESPACE)
+    ]
+    if not include_stale:
+        records = [record for record in records if record.status == "current"]
+    return sorted(records, key=lambda record: record.artifact_id)
+
+
+def mark_stale(store: ContinuityStore, artifact_id: str) -> ContinuityArtifact:
+    artifact = get_artifact(store, artifact_id)
+    updated = artifact.model_copy(update={"status": "stale", "updated_at": _now()})
+    store.put(CONTINUITY_NAMESPACE, updated.artifact_id, updated.model_dump())
+    append_event(
+        store,
+        stream_id="continuity",
+        kind="continuity_stale",
+        payload={"artifact_id": updated.artifact_id},
+    )
+    return updated
+
+
+def _item_value(item: object) -> dict[str, object]:
+    value = getattr(item, "value", item)
+    return value if isinstance(value, dict) else {}
+
+
+def _artifact_id(*, title: str, created_at: str) -> str:
+    digest = sha256(f"{title}\0{created_at}".encode("utf-8")).hexdigest()
+    return f"cont-{digest[:12]}"
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat().replace("+00:00", "Z")
diff --git a/coding-deepgent/src/coding_deepgent/event_stream/__init__.py b/coding-deepgent/src/coding_deepgent/event_stream/__init__.py
new file mode 100644
index 000000000..8fac681a1
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/event_stream/__init__.py
@@ -0,0 +1,17 @@
+from .store import (
+    EVENT_STREAM_NAMESPACE,
+    EventRecord,
+    ack_event,
+    append_event,
+    get_event,
+    list_events,
+)
+
+__all__ = [
+    "EVENT_STREAM_NAMESPACE",
+    "EventRecord",
+    "ack_event",
+    "append_event",
+    "get_event",
+    "list_events",
+]
diff --git a/coding-deepgent/src/coding_deepgent/event_stream/store.py b/coding-deepgent/src/coding_deepgent/event_stream/store.py
new file mode 100644
index 000000000..b01c3fdb0
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/event_stream/store.py
@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from datetime import UTC, datetime
+from hashlib import sha256
+from typing import Any, Literal, Protocol
+
+from pydantic import BaseModel, ConfigDict, Field
+
+EVENT_STREAM_NAMESPACE = "coding_deepgent_event_stream"
+EventVisibility = Literal["visible", "internal"]
+
+
+class EventStore(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]: ...
+
+
+class EventRecord(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    event_id: str
+    stream_id: str
+    sequence: int = Field(..., ge=1)
+    kind: str = Field(..., min_length=1)
+    visibility: EventVisibility = "visible"
+    payload: dict[str, Any] = Field(default_factory=dict)
+    created_at: str
+    acked: bool = False
+    acked_at: str | None = None
+
+
+def event_namespace(stream_id: str) -> tuple[str, ...]:
+    return (EVENT_STREAM_NAMESPACE, stream_id.strip() or "default")
+
+
+def append_event(
+    store: EventStore,
+    *,
+    stream_id: str,
+    kind: str,
+    payload: dict[str, Any] | None = None,
+    visibility: EventVisibility = "visible",
+) -> EventRecord:
+    records = list_events(store, stream_id=stream_id, include_internal=True)
+    sequence = (records[-1].sequence + 1) if records else 1
+    event_id = _event_id(stream_id=stream_id, sequence=sequence, kind=kind)
+    record = EventRecord(
+        event_id=event_id,
+        stream_id=stream_id.strip() or "default",
+        sequence=sequence,
+        kind=kind.strip(),
+        visibility=visibility,
+        payload=payload or {},
+        created_at=_now(),
+    )
+    store.put(event_namespace(record.stream_id), record.event_id, record.model_dump())
+    return record
+
+
+def get_event(store: EventStore, *, stream_id: str, event_id: str) -> EventRecord:
+    item = store.get(event_namespace(stream_id), event_id)
+    if item is None:
+        raise KeyError(f"Unknown event: {event_id}")
+    return EventRecord.model_validate(_item_value(item))
+
+
+def list_events(
+    store: EventStore,
+    *,
+    stream_id: str,
+    after_sequence: int | None = None,
+    include_internal: bool = False,
+) -> list[EventRecord]:
+    records = [
+        EventRecord.model_validate(_item_value(item))
+        for item in store.search(event_namespace(stream_id))
+    ]
+    if after_sequence is not None:
+        records = [record for record in records if record.sequence > after_sequence]
+    if not include_internal:
+        records = [record for record in records if record.visibility == "visible"]
+    return sorted(records, key=lambda record: record.sequence)
+
+
+def ack_event(store: EventStore, *, stream_id: str, event_id: str) -> EventRecord:
+    record = get_event(store, stream_id=stream_id, event_id=event_id)
+    updated = record.model_copy(update={"acked": True, "acked_at": _now()})
+    store.put(event_namespace(stream_id), updated.event_id, updated.model_dump())
+    return updated
+
+
+def _item_value(item: object) -> dict[str, object]:
+    value = getattr(item, "value", item)
+    return value if isinstance(value, dict) else {}
+
+
+def _event_id(*, stream_id: str, sequence: int, kind: str) -> str:
+    digest = sha256(f"{stream_id}\0{sequence}\0{kind}".encode("utf-8")).hexdigest()
+    return f"evt-{digest[:12]}"
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat().replace("+00:00", "Z")
diff --git a/coding-deepgent/src/coding_deepgent/extension_lifecycle/__init__.py b/coding-deepgent/src/coding_deepgent/extension_lifecycle/__init__.py
new file mode 100644
index 000000000..2b9533aa6
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/extension_lifecycle/__init__.py
@@ -0,0 +1,23 @@
+from .store import (
+    EXTENSION_NAMESPACE,
+    ExtensionRecord,
+    disable_extension,
+    enable_extension,
+    get_extension,
+    list_extensions,
+    register_extension,
+    rollback_extension,
+    update_extension,
+)
+
+__all__ = [
+    "EXTENSION_NAMESPACE",
+    "ExtensionRecord",
+    "disable_extension",
+    "enable_extension",
+    "get_extension",
+    "list_extensions",
+    "register_extension",
+    "rollback_extension",
+    "update_extension",
+]
diff --git a/coding-deepgent/src/coding_deepgent/extension_lifecycle/store.py b/coding-deepgent/src/coding_deepgent/extension_lifecycle/store.py
new file mode 100644
index 000000000..b8e8b9a1a
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/extension_lifecycle/store.py
@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from datetime import UTC, datetime
+from hashlib import sha256
+from typing import Any, Literal, Protocol
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from coding_deepgent.event_stream import append_event
+
+EXTENSION_NAMESPACE = ("coding_deepgent_extension_lifecycle",)
+ExtensionKind = Literal["skill", "mcp", "hook", "plugin"]
+ExtensionStatus = Literal["installed", "enabled", "disabled", "failed"]
+
+
+class ExtensionStore(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]: ...
+
+
+class ExtensionRecord(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    extension_id: str
+    name: str = Field(..., min_length=1)
+    kind: ExtensionKind
+    source: str = Field(..., min_length=1)
+    version: str | None = None
+    status: ExtensionStatus = "installed"
+    previous_status: ExtensionStatus | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    created_at: str
+    updated_at: str
+
+
+def register_extension(
+    store: ExtensionStore,
+    *,
+    name: str,
+    kind: ExtensionKind,
+    source: str,
+    version: str | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> ExtensionRecord:
+    existing = _find_by_name_kind(store, name=name, kind=kind)
+    if existing is not None:
+        return existing
+    now = _now()
+    record = ExtensionRecord(
+        extension_id=_extension_id(name=name, kind=kind, created_at=now),
+        name=name.strip(),
+        kind=kind,
+        source=source.strip(),
+        version=version,
+        metadata=metadata or {},
+        created_at=now,
+        updated_at=now,
+    )
+    return _save(store, record, event_kind="extension_registered")
+
+
+def get_extension(store: ExtensionStore, extension_id: str) -> ExtensionRecord:
+    item = store.get(EXTENSION_NAMESPACE, extension_id)
+    if item is None:
+        raise KeyError(f"Unknown extension: {extension_id}")
+    return ExtensionRecord.model_validate(_item_value(item))
+
+
+def list_extensions(store: ExtensionStore) -> list[ExtensionRecord]:
+    return sorted(
+        [
+            ExtensionRecord.model_validate(_item_value(item))
+            for item in store.search(EXTENSION_NAMESPACE)
+        ],
+        key=lambda item: item.extension_id,
+    )
+
+
+def enable_extension(store: ExtensionStore, extension_id: str) -> ExtensionRecord:
+    record = get_extension(store, extension_id)
+    return _transition(store, record, status="enabled", event_kind="extension_enabled")
+
+
+def disable_extension(store: ExtensionStore, extension_id: str) -> ExtensionRecord:
+    record = get_extension(store, extension_id)
+    return _transition(store, record, status="disabled", event_kind="extension_disabled")
+
+
+def update_extension(
+    store: ExtensionStore,
+    extension_id: str,
+    *,
+    version: str | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> ExtensionRecord:
+    record = get_extension(store, extension_id)
+    updated = record.model_copy(
+        update={
+            "version": version if version is not None else record.version,
+            "metadata": {**record.metadata, **(metadata or {})},
+            "updated_at": _now(),
+        }
+    )
+    return _save(store, updated, event_kind="extension_updated")
+
+
+def rollback_extension(store: ExtensionStore, extension_id: str) -> ExtensionRecord:
+    record = get_extension(store, extension_id)
+    if record.previous_status is None:
+        return record
+    return _transition(
+        store,
+        record,
+        status=record.previous_status,
+        event_kind="extension_rollback",
+    )
+
+
+def _transition(
+    store: ExtensionStore,
+    record: ExtensionRecord,
+    *,
+    status: ExtensionStatus,
+    event_kind: str,
+) -> ExtensionRecord:
+    return _save(
+        store,
+        record.model_copy(
+            update={
+                "status": status,
+                "previous_status": record.status,
+                "updated_at": _now(),
+            }
+        ),
+        event_kind=event_kind,
+    )
+
+
+def _save(
+    store: ExtensionStore,
+    record: ExtensionRecord,
+    *,
+    event_kind: str,
+) -> ExtensionRecord:
+    store.put(EXTENSION_NAMESPACE, record.extension_id, record.model_dump())
+    append_event(
+        store,
+        stream_id=f"extension:{record.extension_id}",
+        kind=event_kind,
+        payload={"extension_id": record.extension_id, "status": record.status},
+    )
+    return record
+
+
+def _find_by_name_kind(
+    store: ExtensionStore,
+    *,
+    name: str,
+    kind: ExtensionKind,
+) -> ExtensionRecord | None:
+    for record in list_extensions(store):
+        if record.name == name and record.kind == kind:
+            return record
+    return None
+
+
+def _item_value(item: object) -> dict[str, object]:
+    value = getattr(item, "value", item)
+    return value if isinstance(value, dict) else {}
+
+
+def _extension_id(*, name: str, kind: str, created_at: str) -> str:
+    digest = sha256(f"{name}\0{kind}\0{created_at}".encode("utf-8")).hexdigest()
+    return f"ext-{digest[:12]}"
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat().replace("+00:00", "Z")
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..6a70a198d
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/extensions_service.py
@@ -0,0 +1,62 @@
+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
+from coding_deepgent.subagents.loader import discover_plugin_subagent_definitions
+
+
+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,
+    )
+    discover_plugin_subagent_definitions(
+        workdir=settings.workdir,
+        plugin_dir=settings.plugin_dir,
+    )
+    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/frontend/__init__.py b/coding-deepgent/src/coding_deepgent/frontend/__init__.py
new file mode 100644
index 000000000..55bf12361
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/frontend/__init__.py
@@ -0,0 +1,47 @@
+"""Frontend bridge contracts for external CLI/Web renderers."""
+
+from .protocol import (
+    AssistantMessageEvent,
+    FrontendEvent,
+    FrontendInput,
+    ProtocolErrorEvent,
+    RunFinishedEvent,
+    RunFailedEvent,
+    SessionStartedEvent,
+    SubmitPromptInput,
+    TodoSnapshotEvent,
+    UserMessageEvent,
+    parse_frontend_event,
+    parse_frontend_input,
+    serialize_frontend_event,
+    dump_frontend_event,
+)
+from .client import FrontendClient
+from .runs import FrontendRunManager, FrontendRunService, RunRecord, RunStatus
+from .stream_bridge import END_SENTINEL, HEARTBEAT_SENTINEL, MemoryStreamBridge, StreamEntry
+
+__all__ = [
+    "AssistantMessageEvent",
+    "FrontendEvent",
+    "FrontendInput",
+    "FrontendClient",
+    "FrontendRunManager",
+    "FrontendRunService",
+    "RunRecord",
+    "RunStatus",
+    "StreamEntry",
+    "MemoryStreamBridge",
+    "HEARTBEAT_SENTINEL",
+    "END_SENTINEL",
+    "dump_frontend_event",
+    "ProtocolErrorEvent",
+    "RunFailedEvent",
+    "RunFinishedEvent",
+    "SessionStartedEvent",
+    "SubmitPromptInput",
+    "TodoSnapshotEvent",
+    "UserMessageEvent",
+    "parse_frontend_event",
+    "parse_frontend_input",
+    "serialize_frontend_event",
+]
diff --git a/coding-deepgent/src/coding_deepgent/frontend/adapters/__init__.py b/coding-deepgent/src/coding_deepgent/frontend/adapters/__init__.py
new file mode 100644
index 000000000..7dccdf62c
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/frontend/adapters/__init__.py
@@ -0,0 +1,2 @@
+"""Transport adapters for frontend event streams."""
+
diff --git a/coding-deepgent/src/coding_deepgent/frontend/adapters/jsonl.py b/coding-deepgent/src/coding_deepgent/frontend/adapters/jsonl.py
new file mode 100644
index 000000000..a32bdf15d
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/frontend/adapters/jsonl.py
@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import sys
+from collections.abc import Iterable
+from typing import TextIO
+
+from coding_deepgent.settings import Settings, load_settings
+
+from coding_deepgent.frontend.producer import (
+    BridgeSession,
+    ControlRunner,
+    PermissionResumeRunner,
+    PromptRunner,
+    build_default_bridge_runners,
+    build_default_prompt_runner,
+    build_fake_bridge_runners,
+)
+from coding_deepgent.frontend.protocol import (
+    FrontendEvent,
+    parse_frontend_input,
+    protocol_error_from_exception,
+    serialize_frontend_event,
+)
+
+
+def run_jsonl_bridge(
+    input_stream: Iterable[str],
+    output_stream: TextIO,
+    *,
+    settings: Settings | None = None,
+    prompt_runner: PromptRunner | None = None,
+    permission_resume_runner: PermissionResumeRunner | None = None,
+    control_runner: ControlRunner | None = None,
+) -> None:
+    active_settings = settings or load_settings()
+    active_prompt_runner = prompt_runner
+    active_permission_resume_runner = permission_resume_runner
+    active_control_runner = control_runner
+    if (
+        active_prompt_runner is None
+        and active_permission_resume_runner is None
+        and active_control_runner is None
+    ):
+        (
+            active_prompt_runner,
+            active_permission_resume_runner,
+            active_control_runner,
+        ) = build_default_bridge_runners(active_settings, hitl=True)
+    session = BridgeSession(
+        settings=active_settings,
+        prompt_runner=active_prompt_runner or build_default_prompt_runner(active_settings),
+        permission_resume_runner=active_permission_resume_runner,
+        control_runner=active_control_runner,
+    )
+    for line in input_stream:
+        if not line.strip():
+            continue
+        try:
+            request = parse_frontend_input(line)
+        except Exception as exc:
+            _emit(output_stream, protocol_error_from_exception(exc))
+            continue
+        should_exit = session.handle(request, lambda event: _emit(output_stream, event))
+        if should_exit:
+            break
+
+
+def run_stdio_bridge(*, fake: bool = False) -> None:
+    if fake:
+        runner, resume_runner, control_runner = build_fake_bridge_runners()
+        run_jsonl_bridge(
+            sys.stdin,
+            sys.stdout,
+            prompt_runner=runner,
+            permission_resume_runner=resume_runner,
+            control_runner=control_runner,
+        )
+        return
+    runner, resume_runner, control_runner = build_default_bridge_runners(load_settings(), hitl=True)
+    run_jsonl_bridge(
+        sys.stdin,
+        sys.stdout,
+        prompt_runner=runner,
+        permission_resume_runner=resume_runner,
+        control_runner=control_runner,
+    )
+
+
+def _emit(output_stream: TextIO, event: FrontendEvent) -> None:
+    output_stream.write(serialize_frontend_event(event) + "\n")
+    output_stream.flush()
diff --git a/coding-deepgent/src/coding_deepgent/frontend/adapters/sse.py b/coding-deepgent/src/coding_deepgent/frontend/adapters/sse.py
new file mode 100644
index 000000000..c66d1138c
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/frontend/adapters/sse.py
@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Generator
+from typing import Any
+
+from coding_deepgent.frontend.stream_bridge import (
+    END_SENTINEL,
+    HEARTBEAT_SENTINEL,
+    MemoryStreamBridge,
+)
+
+
+def format_sse(event: str, data: Any, *, event_id: str | None = None) -> str:
+    payload = json.dumps(data, default=str, ensure_ascii=False)
+    parts = [f"event: {event}", f"data: {payload}"]
+    if event_id:
+        parts.append(f"id: {event_id}")
+    parts.append("")
+    parts.append("")
+    return "\n".join(parts)
+
+
+def sse_consumer(
+    bridge: MemoryStreamBridge,
+    run_id: str,
+    *,
+    last_event_id: str | None = None,
+    heartbeat_interval: float = 15.0,
+) -> Generator[str, None, None]:
+    for entry in bridge.subscribe(
+        run_id, last_event_id=last_event_id, heartbeat_interval=heartbeat_interval
+    ):
+        if entry is HEARTBEAT_SENTINEL:
+            yield ": heartbeat\n\n"
+            continue
+        if entry is END_SENTINEL:
+            yield format_sse("end", None, event_id=entry.id or None)
+            return
+        yield format_sse(entry.event, entry.data, event_id=entry.id or None)
diff --git a/coding-deepgent/src/coding_deepgent/frontend/bridge.py b/coding-deepgent/src/coding_deepgent/frontend/bridge.py
new file mode 100644
index 000000000..493e76d88
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/frontend/bridge.py
@@ -0,0 +1,35 @@
+"""Backward-compatible imports for the frontend JSONL bridge.
+
+New code should import runtime event production from
+`coding_deepgent.frontend.producer` and transport behavior from
+`coding_deepgent.frontend.adapters.jsonl`.
+"""
+
+from .adapters.jsonl import run_jsonl_bridge, run_stdio_bridge
+from .producer import (
+    BridgeSession,
+    EventEmitter,
+    PermissionResumeRunner,
+    PromptRunner,
+    PromptRunResult,
+    _run_streaming_prompt,
+    build_default_bridge_runners,
+    build_default_prompt_runner,
+    build_fake_bridge_runners,
+    build_fake_prompt_runner,
+)
+
+__all__ = [
+    "BridgeSession",
+    "EventEmitter",
+    "PermissionResumeRunner",
+    "PromptRunner",
+    "PromptRunResult",
+    "_run_streaming_prompt",
+    "build_default_bridge_runners",
+    "build_default_prompt_runner",
+    "build_fake_bridge_runners",
+    "build_fake_prompt_runner",
+    "run_jsonl_bridge",
+    "run_stdio_bridge",
+]
diff --git a/coding-deepgent/src/coding_deepgent/frontend/client.py b/coding-deepgent/src/coding_deepgent/frontend/client.py
new file mode 100644
index 000000000..23a5377e7
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/frontend/client.py
@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import queue
+import threading
+from collections.abc import Generator
+
+from coding_deepgent.settings import Settings, load_settings
+
+from .producer import (
+    BridgeSession,
+    ControlRunner,
+    PermissionResumeRunner,
+    PromptRunner,
+    build_default_bridge_runners,
+    build_default_prompt_runner,
+    build_fake_bridge_runners,
+    build_fake_prompt_runner,
+)
+from .protocol import FrontendEvent, FrontendInput, SubmitPromptInput
+
+
+class FrontendClient:
+    """Embedded Python client for frontend events.
+
+    This client consumes the same `FrontendEvent` contract as the React/Ink CLI
+    without going through the JSONL transport. It is intended for tests,
+    scripts, and future non-HTTP adapters.
+    """
+
+    def __init__(
+        self,
+        *,
+        settings: Settings | None = None,
+        prompt_runner: PromptRunner | None = None,
+        permission_resume_runner: PermissionResumeRunner | None = None,
+        control_runner: ControlRunner | None = None,
+        fake: bool = False,
+    ) -> None:
+        active_settings = settings or load_settings()
+        runner = prompt_runner
+        resume_runner = permission_resume_runner
+        active_control_runner = control_runner
+        if runner is None and resume_runner is None and active_control_runner is None:
+            if fake:
+                runner, resume_runner, active_control_runner = build_fake_bridge_runners()
+            else:
+                runner, resume_runner, active_control_runner = build_default_bridge_runners(
+                    active_settings, hitl=True
+                )
+        active_runner = runner or (
+            build_fake_prompt_runner()
+            if fake
+            else build_default_prompt_runner(active_settings)
+        )
+        self._session = BridgeSession(
+            settings=active_settings,
+            prompt_runner=active_runner,
+            permission_resume_runner=resume_runner,
+            control_runner=active_control_runner,
+        )
+        self._lock = threading.Lock()
+
+    def send(self, request: FrontendInput) -> Generator[FrontendEvent, None, None]:
+        """Send one frontend input and yield resulting events synchronously."""
+        with self._lock:
+            yield from _stream_session_events(self._session, request)
+
+    def stream_prompt(self, prompt: str) -> Generator[FrontendEvent, None, None]:
+        """Convenience wrapper around `send({"type":"submit_prompt", ...})`."""
+        yield from self.send(SubmitPromptInput(text=prompt))
+
+    def chat(self, prompt: str) -> str:
+        """Run one prompt and return the final assistant text."""
+        final_text = ""
+        for event in self.stream_prompt(prompt):
+            if event.type == "assistant_message":
+                final_text = event.text
+        return final_text
+
+
+def _stream_session_events(
+    session: BridgeSession,
+    request: FrontendInput,
+) -> Generator[FrontendEvent, None, None]:
+    events: queue.Queue[FrontendEvent | Exception | None] = queue.Queue()
+
+    def worker() -> None:
+        try:
+            session.handle(request, lambda event: events.put(event))
+        except Exception as exc:  # pragma: no cover - defensive background propagation
+            events.put(exc)
+        finally:
+            events.put(None)
+
+    thread = threading.Thread(target=worker, daemon=True)
+    thread.start()
+    while True:
+        item = events.get()
+        if item is None:
+            break
+        if isinstance(item, Exception):
+            raise item
+        yield item
+    thread.join()
diff --git a/coding-deepgent/src/coding_deepgent/frontend/event_mapping.py b/coding-deepgent/src/coding_deepgent/frontend/event_mapping.py
new file mode 100644
index 000000000..911a9e7fb
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/frontend/event_mapping.py
@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any, Literal, cast
+
+from coding_deepgent.runtime import RuntimeEvent
+from coding_deepgent.sessions import LoadedSession, build_session_inspect_view
+from coding_deepgent.subagents.background import BACKGROUND_SUBAGENT_MANAGER
+from coding_deepgent.tasks.store import TaskStore, list_tasks
+
+from .protocol import (
+    BackgroundSubagentItemPayload,
+    BackgroundSubagentSnapshotEvent,
+    ContextSnapshotEvent,
+    RuntimeEventPayload,
+    SubagentItemPayload,
+    SubagentSnapshotEvent,
+    TaskItemPayload,
+    TaskSnapshotEvent,
+    TodoItemPayload,
+    TodoSnapshotEvent,
+    ToolFailedEvent,
+    ToolFinishedEvent,
+    ToolStartedEvent,
+)
+
+ContextProjectionMode = Literal["raw", "compact", "collapse"]
+
+
+def todo_snapshot_from_state(state: Mapping[str, Any]) -> TodoSnapshotEvent:
+    raw_items = state.get("todos", [])
+    items: list[TodoItemPayload] = []
+    if isinstance(raw_items, list):
+        for raw in raw_items:
+            if not isinstance(raw, Mapping):
+                continue
+            content = raw.get("content")
+            status = raw.get("status")
+            if not isinstance(content, str) or status not in {
+                "pending",
+                "in_progress",
+                "completed",
+            }:
+                continue
+            active_form = raw.get("activeForm")
+            items.append(
+                TodoItemPayload(
+                    content=content,
+                    status=status,
+                    activeForm=active_form if isinstance(active_form, str) else None,
+                )
+            )
+    return TodoSnapshotEvent(items=items)
+
+
+def task_snapshot_from_store(store: object | None) -> TaskSnapshotEvent:
+    if store is None:
+        return TaskSnapshotEvent(items=[])
+    try:
+        records = list_tasks(cast(TaskStore, store))
+    except Exception:
+        return TaskSnapshotEvent(items=[])
+    return TaskSnapshotEvent(
+        items=[
+            TaskItemPayload(
+                id=record.id,
+                content=record.title,
+                status=record.status,
+                owner=record.owner,
+            )
+            for record in records
+        ]
+    )
+
+
+def context_snapshot_from_loaded(loaded: LoadedSession) -> ContextSnapshotEvent:
+    view = build_session_inspect_view(loaded)
+    latest_event = view.timeline[-1].event_type if view.timeline else None
+    return ContextSnapshotEvent(
+        projection_mode=cast(ContextProjectionMode, view.projection_mode),
+        history_messages=len(view.raw_messages),
+        model_messages=len(view.model_projection),
+        visible_messages=view.visible_raw_count,
+        hidden_messages=view.hidden_raw_count,
+        compact_count=view.compact_count,
+        collapse_count=view.collapse_count,
+        session_memory_status=view.session_memory.status,
+        latest_event=latest_event,
+    )
+
+
+def subagent_snapshot_from_loaded(
+    loaded: LoadedSession,
+    *,
+    limit: int = 5,
+) -> SubagentSnapshotEvent:
+    messages = loaded.sidechain_messages[-limit:] if limit > 0 else []
+    return SubagentSnapshotEvent(
+        total=len(loaded.sidechain_messages),
+        items=[
+            SubagentItemPayload(
+                created_at=message.created_at,
+                agent_type=message.agent_type,
+                role=message.role,
+                content=message.content[:500],
+                subagent_thread_id=message.subagent_thread_id,
+            )
+            for message in messages
+        ],
+    )
+
+
+def background_subagent_snapshot_from_runtime(
+    runtime: object,
+    *,
+    include_terminal: bool = True,
+    limit: int = 8,
+) -> BackgroundSubagentSnapshotEvent:
+    try:
+        runs = BACKGROUND_SUBAGENT_MANAGER.list_runs(
+            runtime=cast(Any, runtime),
+            include_terminal=include_terminal,
+        )
+    except Exception:
+        return BackgroundSubagentSnapshotEvent(total=0, items=[])
+    selected = runs[-limit:] if limit > 0 else ()
+    return BackgroundSubagentSnapshotEvent(
+        total=len(runs),
+        items=[
+            BackgroundSubagentItemPayload(
+                run_id=run.run_id,
+                status=run.status,
+                mode=run.mode,
+                agent_type=run.agent_type,
+                progress_summary=run.progress_summary,
+                pending_inputs=len(run.pending_inputs),
+                total_invocations=run.total_invocations,
+            )
+            for run in selected
+        ],
+    )
+
+
+def runtime_events_to_frontend(
+    events: Iterable[RuntimeEvent],
+) -> list[RuntimeEventPayload | ToolStartedEvent | ToolFinishedEvent | ToolFailedEvent]:
+    mapped: list[
+        RuntimeEventPayload | ToolStartedEvent | ToolFinishedEvent | ToolFailedEvent
+    ] = []
+    for event in events:
+        metadata = dict(event.metadata)
+        source = metadata.get("source")
+        phase = metadata.get("phase")
+        tool_name = metadata.get("tool")
+        tool_call_id = metadata.get("tool_call_id")
+        if source == "tool_guard" and isinstance(tool_name, str):
+            mapped.extend(
+                _tool_guard_event(
+                    phase=str(phase or event.kind),
+                    tool_name=tool_name,
+                    tool_call_id=str(tool_call_id or f"{event.session_id}:{event.kind}"),
+                    message=event.message,
+                )
+            )
+            continue
+        mapped.append(
+            RuntimeEventPayload(
+                kind=event.kind,
+                message=event.message,
+                metadata=_safe_metadata(metadata),
+            )
+        )
+    return mapped
+
+
+def _tool_guard_event(
+    *,
+    phase: str,
+    tool_name: str,
+    tool_call_id: str,
+    message: str,
+) -> list[ToolStartedEvent | ToolFinishedEvent | ToolFailedEvent]:
+    if phase == "allowed":
+        return [
+            ToolStartedEvent(
+                tool_call_id=tool_call_id,
+                name=tool_name,
+                summary=message,
+            )
+        ]
+    if phase == "completed":
+        return [
+            ToolFinishedEvent(
+                tool_call_id=tool_call_id,
+                name=tool_name,
+                preview=message,
+            )
+        ]
+    if phase in {"failed", "permission_denied", "permission_ask", "feedback_blocked"}:
+        return [
+            ToolFailedEvent(
+                tool_call_id=tool_call_id,
+                name=tool_name,
+                error=message,
+            )
+        ]
+    return []
+
+
+def _safe_metadata(metadata: Mapping[str, Any]) -> dict[str, Any]:
+    safe: dict[str, Any] = {}
+    for key, value in metadata.items():
+        if isinstance(value, str | int | float | bool) or value is None:
+            safe[str(key)] = value
+    return safe
diff --git a/coding-deepgent/src/coding_deepgent/frontend/gateway.py b/coding-deepgent/src/coding_deepgent/frontend/gateway.py
new file mode 100644
index 000000000..3f02fefa7
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/frontend/gateway.py
@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import Any
+
+from fastapi import FastAPI, Header, HTTPException
+from fastapi.responses import HTMLResponse, StreamingResponse
+from pydantic import BaseModel, Field
+
+from coding_deepgent.settings import Settings, load_settings
+
+from .adapters.sse import sse_consumer
+from .producer import PromptRunner
+from .runs import FrontendRunConflictError, FrontendRunService, RunRecord
+from .web import load_web_ui_html
+
+
+class RunCreateRequest(BaseModel):
+    prompt: str = Field(..., min_length=1)
+    thread_id: str | None = None
+
+
+class RunResponse(BaseModel):
+    run_id: str
+    thread_id: str
+    status: str
+    created_at: str
+    updated_at: str
+    error: str | None = None
+
+
+def create_app(
+    *,
+    fake: bool = False,
+    settings: Settings | None = None,
+    prompt_runner: PromptRunner | None = None,
+) -> FastAPI:
+    active_settings = settings or load_settings()
+    service = FrontendRunService(
+        settings=active_settings,
+        fake=fake,
+        prompt_runner=prompt_runner,
+    )
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        app.state.frontend_run_service = service
+        yield
+
+    app = FastAPI(
+        title="coding-deepgent frontend gateway",
+        version="0.1.0",
+        lifespan=lifespan,
+    )
+
+    @app.get("/health")
+    async def health() -> dict[str, str]:
+        return {"status": "healthy", "service": "coding-deepgent-frontend-gateway"}
+
+    @app.get("/ui", response_class=HTMLResponse)
+    async def web_ui() -> HTMLResponse:
+        return HTMLResponse(load_web_ui_html())
+
+    @app.post("/api/runs", response_model=RunResponse)
+    async def create_run(body: RunCreateRequest) -> RunResponse:
+        record = _start_run(service, body)
+        return _record_to_response(record)
+
+    @app.post("/api/runs/stream")
+    async def stream_run(body: RunCreateRequest) -> StreamingResponse:
+        record = _start_run(service, body)
+        return StreamingResponse(
+            sse_consumer(service.bridge, record.run_id),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+                "X-Accel-Buffering": "no",
+                "Content-Location": f"/api/runs/{record.run_id}",
+            },
+        )
+
+    @app.get("/api/runs/{run_id}", response_model=RunResponse)
+    async def get_run(run_id: str) -> RunResponse:
+        record = service.run_manager.get(run_id)
+        if record is None:
+            raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+        return _record_to_response(record)
+
+    @app.get("/api/runs/{run_id}/stream")
+    async def join_run_stream(
+        run_id: str,
+        last_event_id: str | None = Header(default=None, alias="Last-Event-ID"),
+    ) -> StreamingResponse:
+        record = service.run_manager.get(run_id)
+        if record is None:
+            raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+        return StreamingResponse(
+            sse_consumer(service.bridge, run_id, last_event_id=last_event_id),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+                "X-Accel-Buffering": "no",
+            },
+        )
+
+    return app
+
+
+def _start_run(service: FrontendRunService, body: RunCreateRequest) -> RunRecord:
+    thread_id = body.thread_id or f"thread-{service.settings.workdir.name}"
+    try:
+        return service.start_run(thread_id=thread_id, prompt=body.prompt)
+    except FrontendRunConflictError as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+
+
+def _record_to_response(record: RunRecord) -> RunResponse:
+    payload: dict[str, Any] = {
+        "run_id": record.run_id,
+        "thread_id": record.thread_id,
+        "status": record.status,
+        "created_at": record.created_at,
+        "updated_at": record.updated_at,
+        "error": record.error,
+    }
+    return RunResponse(**payload)
diff --git a/coding-deepgent/src/coding_deepgent/frontend/producer.py b/coding-deepgent/src/coding_deepgent/frontend/producer.py
new file mode 100644
index 000000000..cbb243b82
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/frontend/producer.py
@@ -0,0 +1,1279 @@
+from __future__ import annotations
+
+import sys
+import uuid
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
+from functools import partial
+from types import SimpleNamespace
+from typing import Any, Literal, cast
+
+from langchain_core.messages import AIMessage, AIMessageChunk, ToolMessage
+from langgraph.types import Command
+
+from coding_deepgent import cli_service
+from coding_deepgent.agent_runtime_service import (
+    resolve_compiled_agent,
+    session_payload,
+    supports_keyword_argument,
+    update_session_state,
+)
+from coding_deepgent.compact import compact_record_from_messages, project_messages_with_stats
+from coding_deepgent.rendering import latest_assistant_text
+from coding_deepgent.runtime import (
+    RuntimeEvent,
+    build_runnable_config,
+    build_runtime_context,
+    default_runtime_state,
+)
+from coding_deepgent.sessions import LoadedSession
+from coding_deepgent.sessions.service import recorded_session_store
+from coding_deepgent.settings import Settings
+from coding_deepgent.subagents.background import BACKGROUND_SUBAGENT_MANAGER
+
+from .event_mapping import (
+    background_subagent_snapshot_from_runtime,
+    context_snapshot_from_loaded,
+    runtime_events_to_frontend,
+    subagent_snapshot_from_loaded,
+    task_snapshot_from_store,
+    todo_snapshot_from_state,
+)
+from .protocol import (
+    AssistantDeltaEvent,
+    AssistantMessageEvent,
+    BackgroundSubagentSnapshotEvent,
+    ContextSnapshotEvent,
+    FrontendEvent,
+    FrontendInput,
+    PermissionResolvedEvent,
+    PermissionRequestedEvent,
+    ProtocolErrorEvent,
+    RecoveryBriefEvent,
+    RefreshSnapshotsInput,
+    RunBackgroundSubagentControlInput,
+    RunFailedEvent,
+    RunFinishedEvent,
+    RuntimeEventPayload,
+    SessionStartedEvent,
+    SubagentSendInputControl,
+    SubmitPromptInput,
+    SubagentStopInputControl,
+    SubagentSnapshotEvent,
+    TaskItemPayload,
+    TaskSnapshotEvent,
+    ToolFailedEvent,
+    ToolFinishedEvent,
+    ToolStartedEvent,
+    UserMessageEvent,
+)
+
+
+@dataclass(frozen=True)
+class PromptRunResult:
+    text: str
+    runtime_events: tuple[RuntimeEvent, ...] = ()
+    recovery_brief: str | None = None
+    pending_permissions: tuple[PendingPermissionRequest, ...] = ()
+    task_snapshot: tuple[TaskItemPayload, ...] = ()
+    context_snapshot: ContextSnapshotEvent | None = None
+    subagent_snapshot: SubagentSnapshotEvent | None = None
+    background_subagent_snapshot: BackgroundSubagentSnapshotEvent | None = None
+
+
+@dataclass(frozen=True)
+class ControlRunResult:
+    events: tuple[FrontendEvent, ...] = ()
+    recovery_brief: str | None = None
+    task_snapshot: tuple[TaskItemPayload, ...] = ()
+    context_snapshot: ContextSnapshotEvent | None = None
+    subagent_snapshot: SubagentSnapshotEvent | None = None
+    background_subagent_snapshot: BackgroundSubagentSnapshotEvent | None = None
+
+
+EventEmitter = Callable[[FrontendEvent], None]
+PromptRunner = Callable[
+    [str, list[dict[str, Any]], dict[str, Any], str, str, EventEmitter],
+    PromptRunResult,
+]
+PermissionResumeRunner = Callable[
+    [dict[str, Any], list[dict[str, Any]], dict[str, Any], str, str, EventEmitter],
+    PromptRunResult,
+]
+ControlRunner = Callable[
+    [FrontendInput, dict[str, Any], str, EventEmitter],
+    ControlRunResult,
+]
+
+FRONTEND_HITL_ENTRYPOINT = "coding-deepgent-frontend"
+
+
+@dataclass(frozen=True)
+class PendingPermissionRequest:
+    request_id: str
+    tool: str
+    description: str
+    options: tuple[Literal["approve", "reject"], ...] = ("approve", "reject")
+
+
+def _task_snapshot_items(container: Any) -> tuple[TaskItemPayload, ...]:
+    runtime = getattr(container, "runtime", None)
+    if runtime is None:
+        return ()
+    store_provider = getattr(runtime, "store", None)
+    if not callable(store_provider):
+        return ()
+    try:
+        store = store_provider()
+    except Exception:
+        return ()
+    return tuple(task_snapshot_from_store(store).items)
+
+
+def _background_subagent_snapshot(runtime: object) -> BackgroundSubagentSnapshotEvent:
+    return background_subagent_snapshot_from_runtime(
+        runtime,
+        include_terminal=True,
+    )
+
+
+@dataclass
+class BridgeSession:
+    settings: Settings
+    prompt_runner: PromptRunner
+    permission_resume_runner: PermissionResumeRunner | None = None
+    control_runner: ControlRunner | None = None
+    session_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    history: list[dict[str, Any]] = field(default_factory=list)
+    session_state: dict[str, Any] = field(default_factory=default_runtime_state)
+    pending_permission_requests: dict[str, PendingPermissionRequest] = field(
+        default_factory=dict
+    )
+    pending_assistant_message_id: str | None = None
+    started: bool = False
+
+    def handle(self, request: FrontendInput, emit: EventEmitter) -> bool:
+        if isinstance(request, SubmitPromptInput):
+            self._handle_prompt(request, emit)
+            return False
+        if request.type == "permission_decision":
+            self._handle_permission_decision(request, emit)
+            return False
+        if request.type in {
+            "refresh_snapshots",
+            "run_background_subagent",
+            "subagent_send_input",
+            "subagent_stop",
+        }:
+            self._handle_control(request, emit)
+            return False
+        if request.type == "interrupt":
+            emit(
+                RuntimeEventPayload(
+                    kind="interrupt_requested",
+                    message="Interrupt requested by frontend.",
+                )
+            )
+            return False
+        if request.type == "exit":
+            emit(RunFinishedEvent(session_id=self.session_id, status="exited"))
+            return True
+        emit(ProtocolErrorEvent(error=f"unsupported input type: {request.type}"))
+        return False
+
+    def _handle_prompt(self, request: SubmitPromptInput, emit: EventEmitter) -> None:
+        self._ensure_started(emit)
+
+        user_id = f"user-{uuid.uuid4().hex[:12]}"
+        assistant_id = f"assistant-{uuid.uuid4().hex[:12]}"
+        emit(UserMessageEvent(id=user_id, text=request.text))
+        try:
+            result = self.prompt_runner(
+                request.text,
+                self.history,
+                self.session_state,
+                self.session_id,
+                assistant_id,
+                emit,
+            )
+        except Exception as exc:
+            emit(
+                RunFailedEvent(
+                    session_id=self.session_id,
+                    error=_bounded_error(exc),
+                )
+            )
+            return
+
+        if result.pending_permissions:
+            self.pending_assistant_message_id = assistant_id
+            self.pending_permission_requests = {
+                permission.request_id: permission
+                for permission in result.pending_permissions
+            }
+            for permission in result.pending_permissions:
+                emit(
+                    PermissionRequestedEvent(
+                        request_id=permission.request_id,
+                        tool=permission.tool,
+                        description=permission.description,
+                        options=list(permission.options),
+                    )
+                )
+            return
+
+        self.pending_assistant_message_id = None
+        self.pending_permission_requests.clear()
+        self._emit_completed_run(result, assistant_id=assistant_id, emit=emit)
+
+    def _handle_control(self, request: FrontendInput, emit: EventEmitter) -> None:
+        self._ensure_started(emit)
+        if self.control_runner is None:
+            emit(ProtocolErrorEvent(error="frontend control runner is not configured"))
+            return
+        try:
+            result = self.control_runner(
+                request,
+                self.session_state,
+                self.session_id,
+                emit,
+            )
+        except Exception as exc:
+            emit(
+                ProtocolErrorEvent(
+                    error=_bounded_error(exc),
+                )
+            )
+            return
+        self._emit_control_result(result, emit=emit)
+
+    def _handle_permission_decision(self, request, emit: EventEmitter) -> None:
+        pending = self.pending_permission_requests.get(request.request_id)
+        if pending is None:
+            emit(
+                ProtocolErrorEvent(
+                    error=f"Unknown permission request id: {request.request_id}"
+                )
+            )
+            return
+
+        emit(
+            PermissionResolvedEvent(
+                request_id=request.request_id,
+                decision=request.decision,
+                message=request.message,
+            )
+        )
+
+        assistant_id = self.pending_assistant_message_id
+        if assistant_id is None:
+            self.pending_permission_requests.clear()
+            emit(
+                ProtocolErrorEvent(
+                    error="Missing pending assistant message id for permission resume"
+                )
+            )
+            return
+
+        if self.permission_resume_runner is None:
+            self.pending_permission_requests.pop(request.request_id, None)
+            return
+
+        try:
+            result = self.permission_resume_runner(
+                {
+                    request.request_id: {
+                        "decision": request.decision,
+                        "message": request.message,
+                    }
+                },
+                self.history,
+                self.session_state,
+                self.session_id,
+                assistant_id,
+                emit,
+            )
+        except Exception as exc:
+            self.pending_assistant_message_id = None
+            self.pending_permission_requests.clear()
+            emit(
+                RunFailedEvent(
+                    session_id=self.session_id,
+                    error=_bounded_error(exc),
+                )
+            )
+            return
+
+        if result.pending_permissions:
+            self.pending_permission_requests = {
+                permission.request_id: permission
+                for permission in result.pending_permissions
+            }
+            for permission in result.pending_permissions:
+                emit(
+                    PermissionRequestedEvent(
+                        request_id=permission.request_id,
+                        tool=permission.tool,
+                        description=permission.description,
+                        options=list(permission.options),
+                    )
+                )
+            return
+
+        self.pending_assistant_message_id = None
+        self.pending_permission_requests.clear()
+        self._emit_completed_run(result, assistant_id=assistant_id, emit=emit)
+
+    def _emit_completed_run(
+        self,
+        result: PromptRunResult,
+        *,
+        assistant_id: str,
+        emit: EventEmitter,
+    ) -> None:
+        for event in runtime_events_to_frontend(result.runtime_events):
+            emit(event)
+        self._emit_snapshot_result(result, emit=emit)
+        emit(AssistantMessageEvent(message_id=assistant_id, text=result.text))
+        if result.recovery_brief:
+            emit(RecoveryBriefEvent(text=result.recovery_brief))
+        emit(RunFinishedEvent(session_id=self.session_id))
+
+    def _emit_control_result(
+        self,
+        result: ControlRunResult,
+        *,
+        emit: EventEmitter,
+    ) -> None:
+        for event in result.events:
+            emit(event)
+        self._emit_snapshot_result(result, emit=emit)
+        if result.recovery_brief:
+            emit(RecoveryBriefEvent(text=result.recovery_brief))
+
+    def _emit_snapshot_result(
+        self,
+        result: PromptRunResult | ControlRunResult,
+        *,
+        emit: EventEmitter,
+    ) -> None:
+        emit(todo_snapshot_from_state(self.session_state))
+        emit(TaskSnapshotEvent(items=list(result.task_snapshot)))
+        if result.context_snapshot is not None:
+            emit(result.context_snapshot)
+        if result.subagent_snapshot is not None:
+            emit(result.subagent_snapshot)
+        if result.background_subagent_snapshot is not None:
+            emit(result.background_subagent_snapshot)
+
+    def _ensure_started(self, emit: EventEmitter) -> None:
+        if self.started:
+            return
+        self.started = True
+        emit(
+            SessionStartedEvent(
+                session_id=self.session_id,
+                workdir=str(self.settings.workdir),
+            )
+        )
+
+
+@dataclass
+class _DefaultFrontendBridgeRunner:
+    settings: Settings
+    hitl: bool = False
+    emitted_events: int = 0
+
+    def __post_init__(self) -> None:
+        self.settings = _frontend_runner_settings(self.settings, hitl=self.hitl)
+        self.container = _build_container_for_settings(self.settings)
+        from coding_deepgent.app import agent_loop, build_agent, build_runtime_invocation
+
+        self._agent_loop = agent_loop
+        self._build_agent = build_agent
+        self._build_runtime_invocation = build_runtime_invocation
+        self._event_sink = self.container.runtime.event_sink()
+
+    def run_prompt(
+        self,
+        prompt: str,
+        history: list[dict[str, Any]],
+        session_state: dict[str, Any],
+        session_id: str,
+        assistant_message_id: str,
+        emit: EventEmitter,
+    ) -> PromptRunResult:
+        if not _force_nonstreaming():
+            try:
+                return _run_streaming_prompt(
+                    settings=self.settings,
+                    prompt=prompt,
+                    history=history,
+                    session_state=session_state,
+                    session_id=session_id,
+                    assistant_message_id=assistant_message_id,
+                    emit=emit,
+                    container=self.container,
+                    event_sink=self._event_sink,
+                    emitted_events=lambda: self.emitted_events,
+                    set_emitted_events=self._set_emitted_events,
+                    build_agent=self._build_agent,
+                    build_runtime_invocation=self._build_runtime_invocation,
+                )
+            except (AttributeError, TypeError, NotImplementedError):
+                pass
+
+        result = cli_service.run_once(
+            settings=self.settings,
+            prompt=prompt,
+            run_agent=partial(self._agent_loop, container=self.container),
+            history=history,
+            session_state=session_state,
+            session_id=session_id,
+        )
+        snapshot = _event_sink_snapshot(self._event_sink)
+        new_events = snapshot[self.emitted_events :]
+        self.emitted_events = len(snapshot)
+        recovery_brief, context_snapshot, subagent_snapshot = _session_visibility(
+            self.settings,
+            session_id,
+        )
+        return PromptRunResult(
+            text=result,
+            runtime_events=tuple(new_events),
+            recovery_brief=recovery_brief,
+            task_snapshot=_task_snapshot_items(self.container),
+            context_snapshot=context_snapshot,
+            subagent_snapshot=subagent_snapshot,
+            background_subagent_snapshot=_background_subagent_snapshot(
+                _control_runtime(
+                    container=self.container,
+                    settings=self.settings,
+                    session_id=session_id,
+                )
+            ),
+        )
+
+    def resume_permission(
+        self,
+        resume_values: dict[str, Any],
+        history: list[dict[str, Any]],
+        session_state: dict[str, Any],
+        session_id: str,
+        assistant_message_id: str,
+        emit: EventEmitter,
+    ) -> PromptRunResult:
+        if _force_nonstreaming():
+            raise RuntimeError("Frontend permission resume requires streaming mode.")
+        return _resume_streaming_prompt(
+            settings=self.settings,
+            resume_values=resume_values,
+            history=history,
+            session_state=session_state,
+            session_id=session_id,
+            assistant_message_id=assistant_message_id,
+            emit=emit,
+            container=self.container,
+            event_sink=self._event_sink,
+            emitted_events=lambda: self.emitted_events,
+            set_emitted_events=self._set_emitted_events,
+            build_agent=self._build_agent,
+            build_runtime_invocation=self._build_runtime_invocation,
+        )
+
+    def _set_emitted_events(self, value: int) -> None:
+        self.emitted_events = value
+
+    def control(
+        self,
+        request: FrontendInput,
+        session_state: dict[str, Any],
+        session_id: str,
+        emit: EventEmitter,
+    ) -> ControlRunResult:
+        del session_state, emit
+        runtime = _control_runtime(
+            container=self.container,
+            settings=self.settings,
+            session_id=session_id,
+        )
+        if isinstance(request, RefreshSnapshotsInput):
+            return _control_result_for_runtime(
+                self.container,
+                self.settings,
+                session_id=session_id,
+            )
+        if isinstance(request, RunBackgroundSubagentControlInput):
+            record = BACKGROUND_SUBAGENT_MANAGER.start_subagent(
+                task=request.task,
+                runtime=cast(Any, runtime),
+                agent_type=request.agent_type,
+                plan_id=request.plan_id,
+                max_turns=request.max_turns,
+            )
+            return _control_result_for_runtime(
+                self.container,
+                self.settings,
+                session_id=session_id,
+                message=f"Started background subagent {record.run_id}.",
+            )
+        if isinstance(request, SubagentSendInputControl):
+            record = BACKGROUND_SUBAGENT_MANAGER.send_input(
+                run_id=request.run_id,
+                message=request.message,
+                runtime=cast(Any, runtime),
+            )
+            return _control_result_for_runtime(
+                self.container,
+                self.settings,
+                session_id=session_id,
+                message=f"Queued follow-up input for {record.run_id}.",
+            )
+        if isinstance(request, SubagentStopInputControl):
+            record = BACKGROUND_SUBAGENT_MANAGER.stop(
+                run_id=request.run_id,
+                runtime=cast(Any, runtime),
+            )
+            return _control_result_for_runtime(
+                self.container,
+                self.settings,
+                session_id=session_id,
+                message=f"Updated {record.run_id} to {record.status}.",
+            )
+        raise RuntimeError(f"unsupported control input: {request.type}")
+
+
+@dataclass
+class _FakeFrontendBridgeRunner:
+    pending_prompt: str | None = None
+
+    def run_prompt(
+        self,
+        prompt: str,
+        history: list[dict[str, Any]],
+        session_state: dict[str, Any],
+        session_id: str,
+        assistant_message_id: str,
+        emit: EventEmitter,
+    ) -> PromptRunResult:
+        del session_id
+        history.append({"role": "user", "content": prompt})
+        if "permission" in prompt.lower():
+            self.pending_prompt = prompt
+            return PromptRunResult(
+                text="",
+                pending_permissions=(
+                    PendingPermissionRequest(
+                        request_id=f"fake-permission-{uuid.uuid4().hex[:8]}",
+                        tool="fake_write",
+                        description="Fake permission request; no destructive action ran.",
+                    ),
+                ),
+            )
+        return self._complete_fake_prompt(
+            prompt=prompt,
+            assistant_message_id=assistant_message_id,
+            session_state=session_state,
+            emit=emit,
+        )
+
+    def resume_permission(
+        self,
+        resume_values: dict[str, Any],
+        history: list[dict[str, Any]],
+        session_state: dict[str, Any],
+        session_id: str,
+        assistant_message_id: str,
+        emit: EventEmitter,
+    ) -> PromptRunResult:
+        del history, session_id
+        prompt = self.pending_prompt or "permission"
+        self.pending_prompt = None
+        decision_payload: Any = next(iter(resume_values.values()), {})
+        if isinstance(decision_payload, dict):
+            decision = str(decision_payload.get("decision", "reject")).strip().lower()
+            message = decision_payload.get("message")
+        else:
+            decision = str(decision_payload).strip().lower()
+            message = None
+        if decision != "approve":
+            error = message if isinstance(message, str) and message else "Fake permission request rejected."
+            emit(
+                ToolFailedEvent(
+                    tool_call_id="fake-write-call",
+                    name="fake_write",
+                    error=error,
+                )
+            )
+            return PromptRunResult(
+                text="Fake response: permission rejected.",
+                runtime_events=(
+                    RuntimeEvent(
+                        kind="permission_denied",
+                        message="Fake permission rejected.",
+                        session_id="fake",
+                        metadata={
+                            "source": "frontend_bridge",
+                            "tool": "fake_write",
+                            "policy_code": "permission_required",
+                            "permission_behavior": "ask",
+                        },
+                    ),
+                ),
+            )
+        return self._complete_fake_prompt(
+            prompt=prompt,
+            assistant_message_id=assistant_message_id,
+            session_state=session_state,
+            emit=emit,
+        )
+
+    def _complete_fake_prompt(
+        self,
+        *,
+        prompt: str,
+        assistant_message_id: str,
+        session_state: dict[str, Any],
+        emit: EventEmitter,
+    ) -> PromptRunResult:
+        emit(
+            ToolStartedEvent(
+                tool_call_id=f"fake-tool-{uuid.uuid4().hex[:8]}",
+                name="fake_tool",
+                summary="Preparing fake response.",
+            )
+        )
+        prefix = "Fake response: "
+        for chunk in (prefix, prompt):
+            emit(AssistantDeltaEvent(message_id=assistant_message_id, text=chunk))
+        if "fail" in prompt.lower():
+            raise RuntimeError("Fake streaming failure after partial output.")
+        response = f"Fake response: {prompt}"
+        session_state["todos"] = [
+            {
+                "content": "Review frontend request",
+                "status": "completed",
+                "activeForm": "Reviewing frontend request",
+            },
+            {
+                "content": "Render CLI response",
+                "status": "in_progress",
+                "activeForm": "Rendering CLI response",
+            },
+        ]
+        emit(
+            ToolFinishedEvent(
+                tool_call_id="fake-tool-complete",
+                name="fake_tool",
+                preview="Fake tool completed.",
+            )
+        )
+        event = RuntimeEvent(
+            kind="fake_prompt",
+            message="Fake prompt completed through frontend bridge.",
+            session_id="fake",
+            metadata={"source": "frontend_bridge", "mode": "fake"},
+        )
+        return PromptRunResult(
+            text=response,
+            runtime_events=(event,),
+            recovery_brief="Fake recovery brief: bridge protocol is healthy.",
+            task_snapshot=(),
+            context_snapshot=ContextSnapshotEvent(
+                projection_mode="raw",
+                history_messages=2,
+                model_messages=2,
+                visible_messages=2,
+                hidden_messages=0,
+                compact_count=0,
+                collapse_count=0,
+                session_memory_status="missing",
+            ),
+            subagent_snapshot=SubagentSnapshotEvent(total=0, items=[]),
+            background_subagent_snapshot=BackgroundSubagentSnapshotEvent(total=0, items=[]),
+        )
+
+    def control(
+        self,
+        request: FrontendInput,
+        session_state: dict[str, Any],
+        session_id: str,
+        emit: EventEmitter,
+    ) -> ControlRunResult:
+        del session_state, session_id, emit
+        if isinstance(request, RefreshSnapshotsInput):
+            message = "Refreshed frontend snapshots."
+        elif isinstance(request, RunBackgroundSubagentControlInput):
+            message = "Started fake background subagent."
+        elif isinstance(request, SubagentSendInputControl):
+            message = f"Queued fake follow-up for {request.run_id}."
+        elif isinstance(request, SubagentStopInputControl):
+            message = f"Stopped fake background run {request.run_id}."
+        else:
+            raise RuntimeError(f"unsupported control input: {request.type}")
+        return ControlRunResult(
+            events=(RuntimeEventPayload(kind="control", message=message),),
+            context_snapshot=ContextSnapshotEvent(
+                projection_mode="raw",
+                history_messages=0,
+                model_messages=0,
+                visible_messages=0,
+                hidden_messages=0,
+                compact_count=0,
+                collapse_count=0,
+                session_memory_status="missing",
+            ),
+            subagent_snapshot=SubagentSnapshotEvent(total=0, items=[]),
+            background_subagent_snapshot=BackgroundSubagentSnapshotEvent(
+                total=0,
+                items=[],
+            ),
+        )
+
+
+def build_default_bridge_runners(
+    settings: Settings,
+    *,
+    hitl: bool = False,
+) -> tuple[PromptRunner, PermissionResumeRunner, ControlRunner]:
+    runner = _DefaultFrontendBridgeRunner(settings=settings, hitl=hitl)
+    return runner.run_prompt, runner.resume_permission, runner.control
+
+
+def build_default_prompt_runner(
+    settings: Settings,
+    *,
+    hitl: bool = False,
+) -> PromptRunner:
+    return build_default_bridge_runners(settings, hitl=hitl)[0]
+
+
+def build_fake_bridge_runners() -> tuple[PromptRunner, PermissionResumeRunner, ControlRunner]:
+    runner = _FakeFrontendBridgeRunner()
+    return runner.run_prompt, runner.resume_permission, runner.control
+
+
+def build_fake_prompt_runner() -> PromptRunner:
+    return build_fake_bridge_runners()[0]
+
+def _run_streaming_prompt(
+    *,
+    settings: Settings,
+    prompt: str,
+    history: list[dict[str, Any]],
+    session_state: dict[str, Any],
+    session_id: str,
+    assistant_message_id: str,
+    emit: EventEmitter,
+    container: Any,
+    event_sink: object,
+    emitted_events: Callable[[], int],
+    set_emitted_events: Callable[[int], None],
+    build_agent: Callable[..., Any],
+    build_runtime_invocation: Callable[..., Any],
+) -> PromptRunResult:
+    return _stream_graph_run(
+        settings=settings,
+        graph_input_factory=lambda normalized: {
+            "messages": normalized,
+            **session_payload(session_state),
+        },
+        prompt=prompt,
+        history=history,
+        session_state=session_state,
+        session_id=session_id,
+        assistant_message_id=assistant_message_id,
+        emit=emit,
+        container=container,
+        event_sink=event_sink,
+        emitted_events=emitted_events,
+        set_emitted_events=set_emitted_events,
+        build_agent=build_agent,
+        build_runtime_invocation=build_runtime_invocation,
+        append_user_prompt=True,
+    )
+
+
+def _resume_streaming_prompt(
+    *,
+    settings: Settings,
+    resume_values: dict[str, Any],
+    history: list[dict[str, Any]],
+    session_state: dict[str, Any],
+    session_id: str,
+    assistant_message_id: str,
+    emit: EventEmitter,
+    container: Any,
+    event_sink: object,
+    emitted_events: Callable[[], int],
+    set_emitted_events: Callable[[int], None],
+    build_agent: Callable[..., Any],
+    build_runtime_invocation: Callable[..., Any],
+) -> PromptRunResult:
+    return _stream_graph_run(
+        settings=settings,
+        graph_input_factory=lambda _normalized: Command(resume=resume_values),
+        prompt=None,
+        history=history,
+        session_state=session_state,
+        session_id=session_id,
+        assistant_message_id=assistant_message_id,
+        emit=emit,
+        container=container,
+        event_sink=event_sink,
+        emitted_events=emitted_events,
+        set_emitted_events=set_emitted_events,
+        build_agent=build_agent,
+        build_runtime_invocation=build_runtime_invocation,
+        append_user_prompt=False,
+    )
+
+
+def _stream_graph_run(
+    *,
+    settings: Settings,
+    graph_input_factory: Callable[[list[dict[str, Any]]], Any],
+    prompt: str | None,
+    history: list[dict[str, Any]],
+    session_state: dict[str, Any],
+    session_id: str,
+    assistant_message_id: str,
+    emit: EventEmitter,
+    container: Any,
+    event_sink: object,
+    emitted_events: Callable[[], int],
+    set_emitted_events: Callable[[int], None],
+    build_agent: Callable[..., Any],
+    build_runtime_invocation: Callable[..., Any],
+    append_user_prompt: bool,
+) -> PromptRunResult:
+    context = _recording_context(settings, session_id, history)
+    if append_user_prompt and prompt is not None:
+        history.append({"role": "user", "content": prompt})
+        context.store.append_message(context.session, role="user", content=prompt)
+
+    invocation = build_runtime_invocation(
+        container=container,
+        session_id=session_id,
+        session_context=context.session,
+    )
+    projection_result = project_messages_with_stats(history)
+    normalized = projection_result.messages
+    if projection_result.repair_stats.orphan_tombstoned:
+        emit(
+            RuntimeEventPayload(
+                kind="orphan_tombstoned",
+                message="Projection repair tombstoned orphaned tool result material.",
+                metadata={
+                    "source": "message_projection",
+                    "tombstoned_count": projection_result.repair_stats.orphan_tombstoned,
+                },
+            )
+        )
+    compiled_agent = resolve_compiled_agent(container, build_agent)
+
+    final_state: dict[str, Any] | None = None
+    delta_text: list[str] = []
+    graph_input = graph_input_factory(normalized)
+    for part in _stream_agent_parts(compiled_agent, graph_input, invocation):
+        pending_permissions = _pending_permissions_from_stream_part(part)
+        if pending_permissions:
+            return PromptRunResult(
+                text="",
+                pending_permissions=tuple(pending_permissions),
+            )
+        for frontend_event in _frontend_events_from_stream_part(
+            part, assistant_message_id=assistant_message_id
+        ):
+            emit(frontend_event)
+            if isinstance(frontend_event, AssistantDeltaEvent):
+                delta_text.append(frontend_event.text)
+        snapshot = _event_sink_snapshot(event_sink)
+        new_events = snapshot[emitted_events():]
+        if new_events:
+            for event in runtime_events_to_frontend(new_events):
+                emit(event)
+            set_emitted_events(len(snapshot))
+        state = _state_from_stream_part(part)
+        if state is not None:
+            final_state = state
+
+    if final_state is not None:
+        update_session_state(session_state, final_state)
+    final_text = latest_assistant_text(final_state) if final_state is not None else ""
+    if not final_text:
+        final_text = "".join(delta_text).strip()
+    if final_text:
+        history.append({"role": "assistant", "content": final_text})
+        context.store.append_message(context.session, role="assistant", content=final_text)
+    context.store.append_state_snapshot(context.session, state=session_state)
+    context.store.append_evidence(
+        context.session,
+        kind="runtime",
+        summary="Prompt completed through coding-deepgent streaming frontend bridge.",
+        status="completed",
+        subject="frontend.ui_bridge.stream",
+    )
+    recovery_brief, context_snapshot, subagent_snapshot = _session_visibility(
+        settings,
+        session_id,
+    )
+    return PromptRunResult(
+        text=final_text,
+        recovery_brief=recovery_brief,
+        task_snapshot=_task_snapshot_items(container),
+        context_snapshot=context_snapshot,
+        subagent_snapshot=subagent_snapshot,
+        background_subagent_snapshot=_background_subagent_snapshot(
+            _control_runtime(
+                container=container,
+                settings=settings,
+                session_id=session_id,
+            )
+        ),
+    )
+
+
+@dataclass(frozen=True)
+class _RecordingContext:
+    store: Any
+    session: Any
+
+
+def _recording_context(
+    settings: Settings,
+    session_id: str,
+    history: list[dict[str, Any]],
+) -> _RecordingContext:
+    store = recorded_session_store(settings)
+    session = store.create_session(
+        workdir=settings.workdir,
+        session_id=session_id,
+        entrypoint=settings.entrypoint,
+    )
+    compact_record = compact_record_from_messages(history)
+    if compact_record is not None:
+        store.append_compact(session, **compact_record)
+    return _RecordingContext(store=store, session=session)
+
+
+def _stream_agent_parts(
+    compiled_agent: Any,
+    payload: Any,
+    invocation: Any,
+) -> Iterable[Any]:
+    stream = compiled_agent.stream
+    kwargs: dict[str, Any] = {
+        "stream_mode": ["messages", "updates", "custom", "values"],
+    }
+    if supports_keyword_argument(stream, "version"):
+        kwargs["version"] = "v2"
+    if supports_keyword_argument(stream, "context"):
+        kwargs["context"] = invocation.context
+    if supports_keyword_argument(stream, "config"):
+        kwargs["config"] = invocation.config
+    return stream(payload, **kwargs)
+
+
+def _frontend_events_from_stream_part(
+    part: Any, *, assistant_message_id: str
+) -> list[FrontendEvent]:
+    part_type, data = _stream_part_type_and_data(part)
+    if part_type == "messages":
+        chunk, _metadata = data
+        text = _message_chunk_text(chunk)
+        return (
+            [AssistantDeltaEvent(message_id=assistant_message_id, text=text)]
+            if text
+            else []
+        )
+    if part_type == "updates":
+        return _events_from_update_data(data)
+    if part_type == "custom":
+        return [
+            RuntimeEventPayload(
+                kind="custom",
+                message=_bounded_custom_message(data),
+            )
+        ]
+    return []
+
+
+def _stream_part_type_and_data(part: Any) -> tuple[str, Any]:
+    if isinstance(part, dict) and "type" in part:
+        return str(part.get("type")), part.get("data")
+    if isinstance(part, tuple) and len(part) == 2:
+        return str(part[0]), part[1]
+    return "unknown", part
+
+
+def _state_from_stream_part(part: Any) -> dict[str, Any] | None:
+    part_type, data = _stream_part_type_and_data(part)
+    if part_type == "values" and isinstance(data, dict) and "__interrupt__" not in data:
+        return data
+    return None
+
+
+def _pending_permissions_from_stream_part(
+    part: Any,
+) -> list[PendingPermissionRequest]:
+    part_type, data = _stream_part_type_and_data(part)
+    if part_type not in {"updates", "values"} or not isinstance(data, dict):
+        return []
+    return _pending_permissions_from_interrupts(data.get("__interrupt__"))
+
+
+def _pending_permissions_from_interrupts(
+    raw_interrupts: Any,
+) -> list[PendingPermissionRequest]:
+    if isinstance(raw_interrupts, tuple | list):
+        interrupts = list(raw_interrupts)
+    elif raw_interrupts is None:
+        return []
+    else:
+        interrupts = [raw_interrupts]
+
+    requests: list[PendingPermissionRequest] = []
+    for interrupt in interrupts:
+        request_id = getattr(interrupt, "id", None)
+        payload = getattr(interrupt, "value", None)
+        if not isinstance(request_id, str) or not request_id.strip():
+            continue
+        if not isinstance(payload, dict):
+            continue
+        if payload.get("kind") != "permission_request":
+            continue
+        tool = payload.get("tool")
+        description = payload.get("description")
+        options = payload.get("options", ("approve", "reject"))
+        if not isinstance(tool, str) or not isinstance(description, str):
+            continue
+        normalized_options = tuple(
+            option for option in options if option in {"approve", "reject"}
+        )
+        requests.append(
+            PendingPermissionRequest(
+                request_id=request_id,
+                tool=tool,
+                description=description,
+                options=normalized_options or ("approve", "reject"),
+            )
+        )
+    return requests
+
+
+def _events_from_update_data(data: Any) -> list[FrontendEvent]:
+    events: list[FrontendEvent] = []
+    if not isinstance(data, dict):
+        return events
+    for node_name, update in data.items():
+        if not isinstance(update, dict):
+            continue
+        messages = update.get("messages")
+        if isinstance(messages, list) and messages:
+            events.extend(_events_from_messages(node_name=str(node_name), messages=messages))
+    return events
+
+
+def _events_from_messages(*, node_name: str, messages: list[Any]) -> list[FrontendEvent]:
+    events: list[FrontendEvent] = []
+    for message in messages:
+        if isinstance(message, AIMessage):
+            for tool_call in message.tool_calls:
+                tool_id = str(tool_call.get("id") or f"{node_name}:tool")
+                name = str(tool_call.get("name") or "tool")
+                events.append(
+                    ToolStartedEvent(
+                        tool_call_id=tool_id,
+                        name=name,
+                        summary=f"{name} requested by model.",
+                    )
+                )
+        elif isinstance(message, ToolMessage):
+            tool_call_id = str(getattr(message, "tool_call_id", "") or f"{node_name}:tool")
+            status = getattr(message, "status", None)
+            content = str(getattr(message, "content", "") or "")
+            if status == "error":
+                events.append(
+                    ToolFailedEvent(
+                        tool_call_id=tool_call_id,
+                        name=str(getattr(message, "name", None) or "tool"),
+                        error=content[:500],
+                    )
+                )
+            else:
+                events.append(
+                    ToolFinishedEvent(
+                        tool_call_id=tool_call_id,
+                        name=str(getattr(message, "name", None) or "tool"),
+                        preview=content[:500],
+                    )
+                )
+    return events
+
+
+def _message_chunk_text(chunk: Any) -> str:
+    if isinstance(chunk, AIMessageChunk):
+        return _content_text(chunk.content)
+    content_blocks = getattr(chunk, "content_blocks", None)
+    if isinstance(content_blocks, list):
+        return "".join(
+            str(block.get("text", ""))
+            for block in content_blocks
+            if isinstance(block, dict) and block.get("type") in {"text", "output_text"}
+        )
+    content = getattr(chunk, "content", None)
+    return _content_text(content)
+
+
+def _content_text(content: Any) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        texts: list[str] = []
+        for block in content:
+            if isinstance(block, dict):
+                text = block.get("text")
+                if isinstance(text, str):
+                    texts.append(text)
+        return "".join(texts)
+    return ""
+
+
+def _bounded_custom_message(data: Any) -> str:
+    if isinstance(data, str):
+        return data[:500]
+    return str(data)[:500]
+
+
+def _force_nonstreaming() -> bool:
+    value = str(sys.argv).lower()
+    return "--non-streaming" in value
+
+
+def _event_sink_snapshot(event_sink: object) -> tuple[RuntimeEvent, ...]:
+    snapshot = getattr(event_sink, "snapshot", None)
+    if callable(snapshot):
+        return tuple(snapshot())
+    return ()
+
+
+def _control_runtime(
+    *,
+    container: Any,
+    settings: Settings,
+    session_id: str,
+) -> SimpleNamespace:
+    runtime_container = getattr(container, "runtime", None)
+    event_sink_provider = getattr(runtime_container, "event_sink", None)
+    hook_registry_provider = getattr(runtime_container, "hook_registry", None)
+    event_sink = event_sink_provider() if callable(event_sink_provider) else None
+    hook_registry = hook_registry_provider() if callable(hook_registry_provider) else None
+    session_context = recorded_session_store(settings).create_session(
+        workdir=settings.workdir,
+        session_id=session_id,
+        entrypoint=FRONTEND_HITL_ENTRYPOINT,
+    )
+    return SimpleNamespace(
+        store=runtime_container.store() if runtime_container is not None else None,
+        context=build_runtime_context(
+            settings,
+            cast(Any, event_sink),
+            cast(Any, hook_registry),
+            session_id=session_id,
+            entrypoint=FRONTEND_HITL_ENTRYPOINT,
+            session_context=session_context,
+        ),
+        config=build_runnable_config(session_id=session_id),
+    )
+
+
+def _control_result_for_runtime(
+    container: Any,
+    settings: Settings,
+    *,
+    session_id: str,
+    message: str | None = None,
+) -> ControlRunResult:
+    recovery_brief, context_snapshot, subagent_snapshot = _session_visibility(
+        settings,
+        session_id,
+    )
+    runtime = _control_runtime(
+        container=container,
+        settings=settings,
+        session_id=session_id,
+    )
+    events: tuple[FrontendEvent, ...] = ()
+    if message is not None:
+        events = (RuntimeEventPayload(kind="control", message=message),)
+    return ControlRunResult(
+        events=events,
+        recovery_brief=recovery_brief,
+        task_snapshot=_task_snapshot_items(container),
+        context_snapshot=context_snapshot,
+        subagent_snapshot=subagent_snapshot,
+        background_subagent_snapshot=_background_subagent_snapshot(runtime),
+    )
+
+
+def _recovery_brief(settings: Settings, session_id: str) -> str | None:
+    loaded = _loaded_session_or_none(settings, session_id)
+    if loaded is None:
+        return None
+    return cli_service.recovery_brief_text(loaded)
+
+
+def _session_visibility(
+    settings: Settings,
+    session_id: str,
+) -> tuple[str | None, ContextSnapshotEvent | None, SubagentSnapshotEvent | None]:
+    loaded = _loaded_session_or_none(settings, session_id)
+    if loaded is None:
+        return None, None, None
+    return (
+        cli_service.recovery_brief_text(loaded),
+        context_snapshot_from_loaded(loaded),
+        subagent_snapshot_from_loaded(loaded),
+    )
+
+
+def _loaded_session_or_none(
+    settings: Settings,
+    session_id: str,
+) -> LoadedSession | None:
+    try:
+        return cli_service.load_session(settings, session_id)
+    except Exception:
+        return None
+
+
+def _bounded_error(error: Exception) -> str:
+    detail = " ".join(str(error).split()).strip()
+    if not detail:
+        detail = type(error).__name__
+    return detail[:500]
+
+
+def _frontend_runner_settings(settings: Settings, *, hitl: bool) -> Settings:
+    if not hitl:
+        return settings
+    updates: dict[str, Any] = {"entrypoint": FRONTEND_HITL_ENTRYPOINT}
+    if settings.checkpointer_backend == "none":
+        updates["checkpointer_backend"] = "memory"
+    return settings.model_copy(update=updates)
+
+
+def _build_container_for_settings(settings: Settings) -> Any:
+    from langchain.agents import create_agent
+
+    from coding_deepgent import bootstrap
+    from coding_deepgent.settings import build_openai_model
+
+    container = bootstrap.build_container(
+        settings_loader=lambda: settings,
+        model_factory=build_openai_model,
+        create_agent_factory=create_agent,
+    )
+    bootstrap.validate_container_startup(container=container)
+    return container
diff --git a/coding-deepgent/src/coding_deepgent/frontend/protocol.py b/coding-deepgent/src/coding_deepgent/frontend/protocol.py
new file mode 100644
index 000000000..c7fe3106a
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/frontend/protocol.py
@@ -0,0 +1,296 @@
+from __future__ import annotations
+
+import json
+from typing import Annotated, Any, Literal, TypeAlias
+
+from pydantic import BaseModel, ConfigDict, Field, TypeAdapter, ValidationError
+
+
+class StrictModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class TodoItemPayload(StrictModel):
+    content: str
+    status: Literal["pending", "in_progress", "completed"]
+    activeForm: str | None = None
+
+
+class TaskItemPayload(StrictModel):
+    id: str
+    content: str
+    status: str
+    owner: str | None = None
+
+
+class SessionStartedEvent(StrictModel):
+    type: Literal["session_started"] = "session_started"
+    session_id: str
+    workdir: str
+
+
+class UserMessageEvent(StrictModel):
+    type: Literal["user_message"] = "user_message"
+    id: str
+    text: str
+
+
+class AssistantDeltaEvent(StrictModel):
+    type: Literal["assistant_delta"] = "assistant_delta"
+    message_id: str
+    text: str
+
+
+class AssistantMessageEvent(StrictModel):
+    type: Literal["assistant_message"] = "assistant_message"
+    message_id: str
+    text: str
+
+
+class ToolStartedEvent(StrictModel):
+    type: Literal["tool_started"] = "tool_started"
+    tool_call_id: str
+    name: str
+    summary: str = ""
+
+
+class ToolFinishedEvent(StrictModel):
+    type: Literal["tool_finished"] = "tool_finished"
+    tool_call_id: str
+    name: str
+    status: Literal["success"] = "success"
+    preview: str = ""
+
+
+class ToolFailedEvent(StrictModel):
+    type: Literal["tool_failed"] = "tool_failed"
+    tool_call_id: str
+    name: str
+    error: str
+
+
+class PermissionRequestedEvent(StrictModel):
+    type: Literal["permission_requested"] = "permission_requested"
+    request_id: str
+    tool: str
+    description: str
+    options: list[Literal["approve", "reject"]] = Field(
+        default_factory=lambda: _default_permission_options()
+    )
+
+
+class PermissionResolvedEvent(StrictModel):
+    type: Literal["permission_resolved"] = "permission_resolved"
+    request_id: str
+    decision: Literal["approve", "reject"]
+    message: str | None = None
+
+
+class TodoSnapshotEvent(StrictModel):
+    type: Literal["todo_snapshot"] = "todo_snapshot"
+    items: list[TodoItemPayload]
+
+
+class TaskSnapshotEvent(StrictModel):
+    type: Literal["task_snapshot"] = "task_snapshot"
+    items: list[TaskItemPayload]
+
+
+class ContextSnapshotEvent(StrictModel):
+    type: Literal["context_snapshot"] = "context_snapshot"
+    projection_mode: Literal["raw", "compact", "collapse"]
+    history_messages: int = Field(..., ge=0)
+    model_messages: int = Field(..., ge=0)
+    visible_messages: int = Field(..., ge=0)
+    hidden_messages: int = Field(..., ge=0)
+    compact_count: int = Field(..., ge=0)
+    collapse_count: int = Field(..., ge=0)
+    session_memory_status: Literal["missing", "current", "stale"]
+    latest_event: str | None = None
+
+
+class SubagentItemPayload(StrictModel):
+    created_at: str
+    agent_type: str
+    role: str
+    content: str
+    subagent_thread_id: str
+
+
+class SubagentSnapshotEvent(StrictModel):
+    type: Literal["subagent_snapshot"] = "subagent_snapshot"
+    total: int = Field(..., ge=0)
+    items: list[SubagentItemPayload]
+
+
+class BackgroundSubagentItemPayload(StrictModel):
+    run_id: str
+    status: Literal["queued", "running", "completed", "failed", "cancelled"]
+    mode: Literal["background_subagent", "background_fork"]
+    agent_type: str
+    progress_summary: str
+    pending_inputs: int = Field(..., ge=0)
+    total_invocations: int = Field(..., ge=0)
+
+
+class BackgroundSubagentSnapshotEvent(StrictModel):
+    type: Literal["background_subagent_snapshot"] = "background_subagent_snapshot"
+    total: int = Field(..., ge=0)
+    items: list[BackgroundSubagentItemPayload]
+
+
+class RuntimeEventPayload(StrictModel):
+    type: Literal["runtime_event"] = "runtime_event"
+    kind: str
+    message: str
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class RecoveryBriefEvent(StrictModel):
+    type: Literal["recovery_brief"] = "recovery_brief"
+    text: str
+
+
+class RunFinishedEvent(StrictModel):
+    type: Literal["run_finished"] = "run_finished"
+    session_id: str
+    status: Literal["completed", "exited"] = "completed"
+
+
+class RunFailedEvent(StrictModel):
+    type: Literal["run_failed"] = "run_failed"
+    session_id: str
+    error: str
+
+
+class ProtocolErrorEvent(StrictModel):
+    type: Literal["protocol_error"] = "protocol_error"
+    error: str
+
+
+FrontendEvent: TypeAlias = Annotated[
+    SessionStartedEvent
+    | UserMessageEvent
+    | AssistantDeltaEvent
+    | AssistantMessageEvent
+    | ToolStartedEvent
+    | ToolFinishedEvent
+    | ToolFailedEvent
+    | PermissionRequestedEvent
+    | PermissionResolvedEvent
+    | TodoSnapshotEvent
+    | TaskSnapshotEvent
+    | ContextSnapshotEvent
+    | SubagentSnapshotEvent
+    | BackgroundSubagentSnapshotEvent
+    | RuntimeEventPayload
+    | RecoveryBriefEvent
+    | RunFinishedEvent
+    | RunFailedEvent
+    | ProtocolErrorEvent,
+    Field(discriminator="type"),
+]
+
+
+class SubmitPromptInput(StrictModel):
+    type: Literal["submit_prompt"] = "submit_prompt"
+    text: str
+
+
+class PermissionDecisionInput(StrictModel):
+    type: Literal["permission_decision"] = "permission_decision"
+    request_id: str
+    decision: Literal["approve", "reject"]
+    message: str | None = None
+
+
+class InterruptInput(StrictModel):
+    type: Literal["interrupt"] = "interrupt"
+
+
+class ExitInput(StrictModel):
+    type: Literal["exit"] = "exit"
+
+
+class RefreshSnapshotsInput(StrictModel):
+    type: Literal["refresh_snapshots"] = "refresh_snapshots"
+
+
+class RunBackgroundSubagentControlInput(StrictModel):
+    type: Literal["run_background_subagent"] = "run_background_subagent"
+    task: str = Field(..., min_length=1)
+    agent_type: str = "general"
+    plan_id: str | None = Field(default=None, min_length=1)
+    max_turns: int = Field(default=25, ge=1, le=25)
+
+
+class SubagentSendInputControl(StrictModel):
+    type: Literal["subagent_send_input"] = "subagent_send_input"
+    run_id: str = Field(..., min_length=1)
+    message: str = Field(..., min_length=1)
+
+
+class SubagentStopInputControl(StrictModel):
+    type: Literal["subagent_stop"] = "subagent_stop"
+    run_id: str = Field(..., min_length=1)
+
+
+FrontendInput: TypeAlias = Annotated[
+    SubmitPromptInput
+    | PermissionDecisionInput
+    | InterruptInput
+    | ExitInput
+    | RefreshSnapshotsInput
+    | RunBackgroundSubagentControlInput
+    | SubagentSendInputControl
+    | SubagentStopInputControl,
+    Field(discriminator="type"),
+]
+
+
+_EVENT_ADAPTER: TypeAdapter[FrontendEvent] = TypeAdapter(FrontendEvent)
+_INPUT_ADAPTER: TypeAdapter[FrontendInput] = TypeAdapter(FrontendInput)
+
+
+def _default_permission_options() -> list[Literal["approve", "reject"]]:
+    return ["approve", "reject"]
+
+
+def parse_frontend_event(payload: str | bytes | dict[str, Any]) -> FrontendEvent:
+    raw = _coerce_json_payload(payload)
+    return _EVENT_ADAPTER.validate_python(raw)
+
+
+def parse_frontend_input(payload: str | bytes | dict[str, Any]) -> FrontendInput:
+    raw = _coerce_json_payload(payload)
+    return _INPUT_ADAPTER.validate_python(raw)
+
+
+def serialize_frontend_event(event: FrontendEvent) -> str:
+    return _EVENT_ADAPTER.dump_json(event, exclude_none=True).decode("utf-8")
+
+
+def dump_frontend_event(event: FrontendEvent) -> dict[str, Any]:
+    payload = _EVENT_ADAPTER.dump_python(event, exclude_none=True)
+    if not isinstance(payload, dict):
+        raise ValueError("frontend event payload must serialize to an object")
+    return payload
+
+
+def _coerce_json_payload(payload: str | bytes | dict[str, Any]) -> dict[str, Any]:
+    if isinstance(payload, dict):
+        return payload
+    try:
+        decoded = json.loads(payload)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"invalid JSON payload: {exc.msg}") from exc
+    if not isinstance(decoded, dict):
+        raise ValueError("frontend protocol payload must be a JSON object")
+    return decoded
+
+
+def protocol_error_from_exception(error: Exception) -> ProtocolErrorEvent:
+    if isinstance(error, ValidationError):
+        detail = error.errors()[0].get("msg", "validation error")
+        return ProtocolErrorEvent(error=str(detail))
+    return ProtocolErrorEvent(error=str(error) or type(error).__name__)
diff --git a/coding-deepgent/src/coding_deepgent/frontend/runs.py b/coding-deepgent/src/coding_deepgent/frontend/runs.py
new file mode 100644
index 000000000..f0fdec809
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/frontend/runs.py
@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import threading
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Literal
+
+from coding_deepgent.settings import Settings, load_settings
+
+from .producer import BridgeSession, PromptRunner, build_default_prompt_runner, build_fake_prompt_runner
+from .protocol import FrontendEvent, SubmitPromptInput, dump_frontend_event
+from .stream_bridge import MemoryStreamBridge
+
+RunStatus = Literal["pending", "running", "completed", "failed", "interrupted"]
+
+
+def _now_iso() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+@dataclass
+class RunRecord:
+    run_id: str
+    thread_id: str
+    status: RunStatus
+    created_at: str
+    updated_at: str
+    error: str | None = None
+    worker: threading.Thread | None = field(default=None, repr=False)
+
+
+class FrontendRunManager:
+    def __init__(self) -> None:
+        self._runs: dict[str, RunRecord] = {}
+        self._lock = threading.Lock()
+
+    def create(self, thread_id: str) -> RunRecord:
+        run_id = str(uuid.uuid4())
+        now = _now_iso()
+        record = RunRecord(
+            run_id=run_id,
+            thread_id=thread_id,
+            status="pending",
+            created_at=now,
+            updated_at=now,
+        )
+        with self._lock:
+            self._runs[run_id] = record
+        return record
+
+    def create_or_reject(self, thread_id: str) -> RunRecord:
+        with self._lock:
+            inflight = [
+                record
+                for record in self._runs.values()
+                if record.thread_id == thread_id
+                and record.status in {"pending", "running"}
+            ]
+            if inflight:
+                raise FrontendRunConflictError(
+                    f"Thread {thread_id} already has an active run"
+                )
+        return self.create(thread_id)
+
+    def get(self, run_id: str) -> RunRecord | None:
+        with self._lock:
+            return self._runs.get(run_id)
+
+    def list_by_thread(self, thread_id: str) -> list[RunRecord]:
+        with self._lock:
+            return [record for record in self._runs.values() if record.thread_id == thread_id]
+
+    def set_status(self, run_id: str, status: RunStatus, *, error: str | None = None) -> None:
+        with self._lock:
+            record = self._runs.get(run_id)
+            if record is None:
+                return
+            record.status = status
+            record.updated_at = _now_iso()
+            if error is not None:
+                record.error = error
+
+
+class FrontendRunService:
+    """Background run lifecycle for future SSE/Gateway consumers."""
+
+    def __init__(
+        self,
+        *,
+        bridge: MemoryStreamBridge | None = None,
+        run_manager: FrontendRunManager | None = None,
+        settings: Settings | None = None,
+        prompt_runner: PromptRunner | None = None,
+        fake: bool = False,
+    ) -> None:
+        self.bridge = bridge or MemoryStreamBridge()
+        self.run_manager = run_manager or FrontendRunManager()
+        self.settings = settings or load_settings()
+        self.prompt_runner = prompt_runner or (
+            build_fake_prompt_runner() if fake else build_default_prompt_runner(self.settings)
+        )
+        self._sessions: dict[str, BridgeSession] = {}
+        self._lock = threading.Lock()
+
+    def start_run(self, *, thread_id: str, prompt: str) -> RunRecord:
+        record = self.run_manager.create_or_reject(thread_id)
+        self.bridge.publish(
+            record.run_id,
+            "metadata",
+            {"run_id": record.run_id, "thread_id": record.thread_id},
+        )
+        worker = threading.Thread(
+            target=self._run_worker,
+            args=(record, prompt),
+            daemon=True,
+        )
+        record.worker = worker
+        worker.start()
+        return record
+
+    def _run_worker(self, record: RunRecord, prompt: str) -> None:
+        self.run_manager.set_status(record.run_id, "running")
+        session = self._session_for(record.thread_id)
+        try:
+            session.handle(
+                SubmitPromptInput(text=prompt),
+                lambda event: self._publish_frontend_event(record.run_id, event),
+            )
+        except Exception as exc:  # pragma: no cover - defensive worker failure
+            self.run_manager.set_status(record.run_id, "failed", error=str(exc))
+            self.bridge.publish(
+                record.run_id,
+                "error",
+                {"message": str(exc), "name": type(exc).__name__},
+            )
+        else:
+            current = self.run_manager.get(record.run_id)
+            if current is not None and current.status == "running":
+                self.run_manager.set_status(record.run_id, "completed")
+        finally:
+            self.bridge.publish_end(record.run_id)
+
+    def _publish_frontend_event(self, run_id: str, event: FrontendEvent) -> None:
+        self.bridge.publish(run_id, event.type, dump_frontend_event(event))
+        if event.type == "run_failed":
+            self.run_manager.set_status(run_id, "failed", error=event.error)
+        elif event.type == "run_finished":
+            current = self.run_manager.get(run_id)
+            if current is not None and current.status == "running":
+                self.run_manager.set_status(run_id, "completed")
+
+    def _session_for(self, thread_id: str) -> BridgeSession:
+        with self._lock:
+            session = self._sessions.get(thread_id)
+            if session is None:
+                session = BridgeSession(
+                    settings=self.settings,
+                    prompt_runner=self.prompt_runner,
+                    session_id=thread_id,
+                )
+                self._sessions[thread_id] = session
+            return session
+
+
+class FrontendRunConflictError(RuntimeError):
+    """Raised when a thread already has a pending/running frontend run."""
diff --git a/coding-deepgent/src/coding_deepgent/frontend/stream_bridge.py b/coding-deepgent/src/coding_deepgent/frontend/stream_bridge.py
new file mode 100644
index 000000000..a6e2f3b0c
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/frontend/stream_bridge.py
@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Generator
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class StreamEntry:
+    id: str
+    event: str
+    data: Any
+
+
+HEARTBEAT_SENTINEL = StreamEntry(id="", event="__heartbeat__", data=None)
+END_SENTINEL = StreamEntry(id="", event="__end__", data=None)
+
+
+@dataclass
+class _RunStream:
+    entries: list[StreamEntry] = field(default_factory=list)
+    condition: threading.Condition = field(default_factory=threading.Condition)
+    ended: bool = False
+    start_offset: int = 0
+
+
+class MemoryStreamBridge:
+    """In-memory per-run event log for future SSE consumers."""
+
+    def __init__(self, *, max_entries: int = 256) -> None:
+        if max_entries < 1:
+            raise ValueError("max_entries must be positive")
+        self._max_entries = max_entries
+        self._streams: dict[str, _RunStream] = {}
+        self._counters: dict[str, int] = {}
+        self._lock = threading.Lock()
+
+    def publish(self, run_id: str, event: str, data: Any) -> None:
+        stream = self._get_or_create_stream(run_id)
+        entry = StreamEntry(id=self._next_id(run_id), event=event, data=data)
+        with stream.condition:
+            stream.entries.append(entry)
+            if len(stream.entries) > self._max_entries:
+                overflow = len(stream.entries) - self._max_entries
+                del stream.entries[:overflow]
+                stream.start_offset += overflow
+            stream.condition.notify_all()
+
+    def publish_end(self, run_id: str) -> None:
+        stream = self._get_or_create_stream(run_id)
+        with stream.condition:
+            stream.ended = True
+            stream.condition.notify_all()
+
+    def subscribe(
+        self,
+        run_id: str,
+        *,
+        last_event_id: str | None = None,
+        heartbeat_interval: float = 15.0,
+    ) -> Generator[StreamEntry, None, None]:
+        stream = self._get_or_create_stream(run_id)
+        next_offset = self._resolve_start_offset(stream, last_event_id)
+        while True:
+            with stream.condition:
+                if next_offset < stream.start_offset:
+                    next_offset = stream.start_offset
+                local_index = next_offset - stream.start_offset
+                if 0 <= local_index < len(stream.entries):
+                    entry = stream.entries[local_index]
+                    next_offset += 1
+                elif stream.ended:
+                    entry = END_SENTINEL
+                else:
+                    notified = stream.condition.wait(timeout=heartbeat_interval)
+                    if not notified:
+                        entry = HEARTBEAT_SENTINEL
+                    else:
+                        continue
+            yield entry
+            if entry is END_SENTINEL:
+                return
+
+    def cleanup(self, run_id: str) -> None:
+        with self._lock:
+            self._streams.pop(run_id, None)
+            self._counters.pop(run_id, None)
+
+    def _get_or_create_stream(self, run_id: str) -> _RunStream:
+        with self._lock:
+            stream = self._streams.get(run_id)
+            if stream is None:
+                stream = _RunStream()
+                self._streams[run_id] = stream
+                self._counters[run_id] = 0
+            return stream
+
+    def _next_id(self, run_id: str) -> str:
+        with self._lock:
+            current = self._counters.get(run_id, 0)
+            self._counters[run_id] = current + 1
+        return f"{int(time.time() * 1000)}-{current}"
+
+    def _resolve_start_offset(
+        self, stream: _RunStream, last_event_id: str | None
+    ) -> int:
+        if last_event_id is None:
+            return stream.start_offset
+        for index, entry in enumerate(stream.entries):
+            if entry.id == last_event_id:
+                return stream.start_offset + index + 1
+        return stream.start_offset
+
diff --git a/coding-deepgent/src/coding_deepgent/frontend/web.py b/coding-deepgent/src/coding_deepgent/frontend/web.py
new file mode 100644
index 000000000..b4f521090
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/frontend/web.py
@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def load_web_ui_html() -> str:
+    path = Path(__file__).resolve().parents[3] / "frontend" / "web" / "index.html"
+    return path.read_text(encoding="utf-8")
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..3f94dcd40
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/hooks/events.py
@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+HookEventName = Literal[
+    "SessionStart",
+    "UserPromptSubmit",
+    "PreToolUse",
+    "PostToolUse",
+    "PermissionDenied",
+    "PreCompact",
+    "PostCompact",
+]
+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..bd3cc0a45
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/logging_config.py
@@ -0,0 +1,77 @@
+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")
+
+
+def logger_for(
+    component: str,
+    *,
+    agent_name: str | None = None,
+    session_id: str | None = None,
+    **fields: object,
+) -> Any:
+    logger = structlog.get_logger("coding_deepgent").bind(
+        component=component.strip() or "runtime"
+    )
+    if agent_name is not None:
+        logger = logger.bind(agent_name=agent_name)
+    if session_id is not None:
+        logger = logger.bind(session_id=session_id)
+    if fields:
+        logger = logger.bind(**fields)
+    return logger
diff --git a/coding-deepgent/src/coding_deepgent/mailbox/__init__.py b/coding-deepgent/src/coding_deepgent/mailbox/__init__.py
new file mode 100644
index 000000000..b7de6f490
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/mailbox/__init__.py
@@ -0,0 +1,17 @@
+from .store import (
+    MAILBOX_NAMESPACE,
+    MailboxMessage,
+    ack_message,
+    get_message,
+    list_messages,
+    send_message,
+)
+
+__all__ = [
+    "MAILBOX_NAMESPACE",
+    "MailboxMessage",
+    "ack_message",
+    "get_message",
+    "list_messages",
+    "send_message",
+]
diff --git a/coding-deepgent/src/coding_deepgent/mailbox/store.py b/coding-deepgent/src/coding_deepgent/mailbox/store.py
new file mode 100644
index 000000000..fc185cf54
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/mailbox/store.py
@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from datetime import UTC, datetime
+from hashlib import sha256
+from typing import Any, Literal, Protocol
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from coding_deepgent.event_stream import append_event
+
+MAILBOX_NAMESPACE = ("coding_deepgent_mailbox",)
+MessageStatus = Literal["pending", "acked", "cancelled"]
+
+
+class MailboxStore(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]: ...
+
+
+class MailboxMessage(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    message_id: str
+    sender: str = Field(..., min_length=1)
+    recipient: str = Field(..., min_length=1)
+    subject: str = Field(..., min_length=1)
+    body: str = Field(..., min_length=1)
+    status: MessageStatus = "pending"
+    delivery_key: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    created_at: str
+    acked_at: str | None = None
+
+
+def send_message(
+    store: MailboxStore,
+    *,
+    sender: str,
+    recipient: str,
+    subject: str,
+    body: str,
+    delivery_key: str | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> MailboxMessage:
+    if delivery_key:
+        existing = _message_by_delivery_key(store, delivery_key)
+        if existing is not None:
+            return existing
+    created_at = _now()
+    message = MailboxMessage(
+        message_id=_message_id(sender=sender, recipient=recipient, created_at=created_at),
+        sender=sender.strip(),
+        recipient=recipient.strip(),
+        subject=subject.strip(),
+        body=body.strip(),
+        delivery_key=delivery_key,
+        metadata=metadata or {},
+        created_at=created_at,
+    )
+    store.put(MAILBOX_NAMESPACE, message.message_id, message.model_dump())
+    append_event(
+        store,
+        stream_id=f"mailbox:{message.recipient}",
+        kind="mailbox_message_sent",
+        payload=message.model_dump(),
+    )
+    return message
+
+
+def get_message(store: MailboxStore, message_id: str) -> MailboxMessage:
+    item = store.get(MAILBOX_NAMESPACE, message_id)
+    if item is None:
+        raise KeyError(f"Unknown mailbox message: {message_id}")
+    return MailboxMessage.model_validate(_item_value(item))
+
+
+def list_messages(
+    store: MailboxStore,
+    *,
+    recipient: str | None = None,
+    status: MessageStatus | None = None,
+) -> list[MailboxMessage]:
+    records = [
+        MailboxMessage.model_validate(_item_value(item))
+        for item in store.search(MAILBOX_NAMESPACE)
+    ]
+    if recipient is not None:
+        records = [record for record in records if record.recipient == recipient]
+    if status is not None:
+        records = [record for record in records if record.status == status]
+    return sorted(records, key=lambda record: record.created_at)
+
+
+def ack_message(store: MailboxStore, message_id: str) -> MailboxMessage:
+    message = get_message(store, message_id)
+    updated = message.model_copy(update={"status": "acked", "acked_at": _now()})
+    store.put(MAILBOX_NAMESPACE, updated.message_id, updated.model_dump())
+    append_event(
+        store,
+        stream_id=f"mailbox:{updated.recipient}",
+        kind="mailbox_message_acked",
+        payload={"message_id": updated.message_id},
+    )
+    return updated
+
+
+def _message_by_delivery_key(
+    store: MailboxStore,
+    delivery_key: str,
+) -> MailboxMessage | None:
+    for message in list_messages(store):
+        if message.delivery_key == delivery_key:
+            return message
+    return None
+
+
+def _item_value(item: object) -> dict[str, object]:
+    value = getattr(item, "value", item)
+    return value if isinstance(value, dict) else {}
+
+
+def _message_id(*, sender: str, recipient: str, created_at: str) -> str:
+    digest = sha256(f"{sender}\0{recipient}\0{created_at}".encode("utf-8")).hexdigest()
+    return f"msg-{digest[:12]}"
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat().replace("+00:00", "Z")
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..62a6cfcf0
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/mcp/adapters.py
@@ -0,0 +1,84 @@
+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 or not descriptor.hints.read_only
+            else "workspace_write"
+        ),
+        execution="plain_tool",
+        exposure="deferred",
+        rendering_result="tool_message",
+        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..76f6e3d68
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/memory/__init__.py
@@ -0,0 +1,71 @@
+from .feedback_enforcement import (
+    FeedbackEnforcementDecision,
+    evaluate_feedback_enforcement,
+)
+from .middleware import MemoryContextMiddleware
+from .policy import MemoryQualityDecision, evaluate_memory_quality
+from .recall import recall_memories, render_memories
+from .runtime_support import (
+    runtime_agent_scope,
+    runtime_memory_service,
+    runtime_project_scope,
+)
+from .state_snapshot import (
+    LONG_TERM_MEMORY_STATE_KEY,
+    LongTermMemoryEntrySnapshot,
+    LongTermMemorySnapshot,
+    build_long_term_memory_snapshot,
+    read_long_term_memory_snapshot,
+    write_long_term_memory_snapshot,
+)
+from .schemas import (
+    DeleteMemoryInput,
+    ListMemoryInput,
+    MemoryRecord,
+    MemoryType,
+    SaveMemoryInput,
+)
+from .store import (
+    MEMORY_ROOT_NAMESPACE,
+    MemoryEntry,
+    delete_memory_record,
+    list_memory_entries,
+    list_memory_records,
+    memory_namespace,
+    save_memory_record,
+)
+from .tools import delete_memory, list_memory, save_memory
+
+__all__ = [
+    "MEMORY_ROOT_NAMESPACE",
+    "FeedbackEnforcementDecision",
+    "LONG_TERM_MEMORY_STATE_KEY",
+    "LongTermMemoryEntrySnapshot",
+    "LongTermMemorySnapshot",
+    "MemoryContextMiddleware",
+    "MemoryEntry",
+    "MemoryQualityDecision",
+    "MemoryRecord",
+    "MemoryType",
+    "DeleteMemoryInput",
+    "ListMemoryInput",
+    "SaveMemoryInput",
+    "build_long_term_memory_snapshot",
+    "delete_memory",
+    "delete_memory_record",
+    "evaluate_feedback_enforcement",
+    "evaluate_memory_quality",
+    "list_memory",
+    "list_memory_entries",
+    "list_memory_records",
+    "memory_namespace",
+    "read_long_term_memory_snapshot",
+    "recall_memories",
+    "render_memories",
+    "runtime_agent_scope",
+    "runtime_memory_service",
+    "runtime_project_scope",
+    "save_memory",
+    "save_memory_record",
+    "write_long_term_memory_snapshot",
+]
diff --git a/coding-deepgent/src/coding_deepgent/memory/archive.py b/coding-deepgent/src/coding_deepgent/memory/archive.py
new file mode 100644
index 000000000..84f6537f9
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/memory/archive.py
@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from io import BytesIO
+from typing import Protocol
+
+import boto3  # type: ignore[import-untyped]
+from botocore.client import Config  # type: ignore[import-untyped]
+
+
+class MemoryArchiveStore(Protocol):
+    def put_json(self, *, object_key: str, payload: dict[str, object]) -> str: ...
+
+
+@dataclass(frozen=True, slots=True)
+class S3ArchiveSettings:
+    bucket: str
+    endpoint_url: str
+    region: str
+    access_key_id: str
+    secret_access_key: str
+
+
+class S3MemoryArchiveStore:
+    def __init__(self, settings: S3ArchiveSettings) -> None:
+        self.settings = settings
+        self.client = boto3.client(
+            "s3",
+            endpoint_url=settings.endpoint_url,
+            region_name=settings.region,
+            aws_access_key_id=settings.access_key_id,
+            aws_secret_access_key=settings.secret_access_key,
+            config=Config(
+                s3={"addressing_style": "path"},
+                proxies={},
+            ),
+        )
+
+    def put_json(self, *, object_key: str, payload: dict[str, object]) -> str:
+        body = json.dumps(payload, ensure_ascii=False, sort_keys=True).encode("utf-8")
+        self.client.upload_fileobj(
+            BytesIO(body),
+            self.settings.bucket,
+            object_key,
+            ExtraArgs={"ContentType": "application/json"},
+        )
+        return object_key
+
+
+class InMemoryArchiveStore:
+    def __init__(self) -> None:
+        self.objects: dict[str, dict[str, object]] = {}
+
+    def put_json(self, *, object_key: str, payload: dict[str, object]) -> str:
+        self.objects[object_key] = dict(payload)
+        return object_key
diff --git a/coding-deepgent/src/coding_deepgent/memory/backend.py b/coding-deepgent/src/coding_deepgent/memory/backend.py
new file mode 100644
index 000000000..abb97987a
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/memory/backend.py
@@ -0,0 +1,459 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import Any, Protocol
+from uuid import uuid4
+
+import psycopg
+from sqlalchemy import (
+    JSON,
+    DateTime,
+    Engine,
+    MetaData,
+    or_,
+    String,
+    Text,
+    create_engine,
+    desc,
+    select,
+)
+from sqlalchemy.orm import DeclarativeBase, Mapped, Session, mapped_column
+from sqlalchemy.engine import URL, make_url
+
+from coding_deepgent.memory.schemas import MemoryRecord, MemoryType
+
+
+def _utc_now() -> datetime:
+    return datetime.now(UTC)
+
+
+class MemoryRecordStatus(StrEnum):
+    ACTIVE = "active"
+    ARCHIVED = "archived"
+    DELETED = "deleted"
+
+
+class MemoryJobStatus(StrEnum):
+    QUEUED = "queued"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class Base(DeclarativeBase):
+    metadata = MetaData()
+
+
+class MemoryRecordRow(Base):
+    __tablename__ = "memory_records"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True)
+    project_scope: Mapped[str] = mapped_column(String(512), index=True)
+    agent_scope: Mapped[str | None] = mapped_column(String(128), nullable=True, index=True)
+    memory_type: Mapped[str] = mapped_column(String(32), index=True)
+    payload: Mapped[dict[str, Any]] = mapped_column(JSON)
+    source: Mapped[str] = mapped_column(String(64))
+    status: Mapped[str] = mapped_column(String(32), index=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+
+class MemoryVersionRow(Base):
+    __tablename__ = "memory_versions"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True)
+    memory_record_id: Mapped[str] = mapped_column(String(36), index=True)
+    payload: Mapped[dict[str, Any]] = mapped_column(JSON)
+    source: Mapped[str] = mapped_column(String(64))
+    status: Mapped[str] = mapped_column(String(32))
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+
+class MemoryExtractionJobRow(Base):
+    __tablename__ = "memory_extraction_jobs"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True)
+    project_scope: Mapped[str] = mapped_column(String(512), index=True)
+    agent_scope: Mapped[str | None] = mapped_column(String(128), nullable=True, index=True)
+    status: Mapped[str] = mapped_column(String(32), index=True)
+    job_type: Mapped[str] = mapped_column(String(64), index=True)
+    dedupe_key: Mapped[str] = mapped_column(String(256), unique=True, index=True)
+    payload: Mapped[dict[str, Any]] = mapped_column(JSON)
+    archive_object_key: Mapped[str | None] = mapped_column(String(512), nullable=True)
+    error_message: Mapped[str | None] = mapped_column(Text, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+
+class AgentMemoryScopeRow(Base):
+    __tablename__ = "agent_memory_scopes"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True)
+    project_scope: Mapped[str] = mapped_column(String(512), index=True)
+    agent_scope: Mapped[str] = mapped_column(String(128), index=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+
+@dataclass(frozen=True, slots=True)
+class DurableMemoryRecord:
+    id: str
+    project_scope: str
+    agent_scope: str | None
+    record: MemoryRecord
+    source: str
+    status: MemoryRecordStatus
+    created_at: datetime
+    updated_at: datetime
+
+
+@dataclass(frozen=True, slots=True)
+class DurableMemoryVersion:
+    id: str
+    memory_record_id: str
+    payload: dict[str, Any]
+    source: str
+    status: str
+    created_at: datetime
+
+
+@dataclass(frozen=True, slots=True)
+class DurableMemoryJob:
+    id: str
+    project_scope: str
+    agent_scope: str | None
+    status: MemoryJobStatus
+    job_type: str
+    dedupe_key: str
+    payload: dict[str, Any]
+    archive_object_key: str | None
+    error_message: str | None
+    created_at: datetime
+    updated_at: datetime
+
+
+def create_memory_engine(database_url: str) -> Engine:
+    if database_url.startswith("postgres://"):
+        database_url = "postgresql+psycopg://" + database_url[len("postgres://") :]
+    elif database_url.startswith("postgresql://"):
+        database_url = "postgresql+psycopg://" + database_url[len("postgresql://") :]
+    return create_engine(database_url, future=True)
+
+
+def migrate_memory_schema(engine: Engine) -> None:
+    _ensure_postgres_database_exists(engine.url)
+    Base.metadata.create_all(engine)
+
+
+def _ensure_postgres_database_exists(database_url: URL | str) -> None:
+    url = make_url(database_url) if isinstance(database_url, str) else database_url
+    if url.get_backend_name() != "postgresql":
+        return
+    database = url.database
+    if not database:
+        return
+    with psycopg.connect(
+        host=url.host,
+        port=url.port,
+        user=url.username,
+        password=url.password,
+        dbname="postgres",
+        autocommit=True,
+    ) as conn:
+        with conn.cursor() as cur:
+            cur.execute("SELECT 1 FROM pg_database WHERE datname = %s", (database,))
+            if cur.fetchone() is not None:
+                return
+            cur.execute(f'CREATE DATABASE "{database}"')
+
+
+class DurableMemoryRepository(Protocol):
+    def save_record(
+        self,
+        *,
+        project_scope: str,
+        agent_scope: str | None,
+        record: MemoryRecord,
+        source: str,
+    ) -> DurableMemoryRecord: ...
+
+    def list_records(
+        self,
+        *,
+        project_scope: str,
+        memory_type: MemoryType | None = None,
+        agent_scope: str | None = None,
+        include_deleted: bool = False,
+        limit: int = 20,
+    ) -> list[DurableMemoryRecord]: ...
+
+    def delete_record(
+        self,
+        *,
+        record_id: str,
+        deleted_by: str,
+    ) -> bool: ...
+
+    def append_job(
+        self,
+        *,
+        project_scope: str,
+        agent_scope: str | None,
+        job_type: str,
+        dedupe_key: str,
+        payload: dict[str, Any],
+    ) -> DurableMemoryJob: ...
+
+    def get_job(self, job_id: str) -> DurableMemoryJob | None: ...
+
+    def list_jobs(
+        self,
+        *,
+        project_scope: str,
+        agent_scope: str | None = None,
+        job_type: str | None = None,
+        status: MemoryJobStatus | None = None,
+        limit: int = 20,
+    ) -> list[DurableMemoryJob]: ...
+
+    def update_job_status(
+        self,
+        *,
+        job_id: str,
+        status: MemoryJobStatus,
+        error_message: str | None = None,
+        archive_object_key: str | None = None,
+    ) -> DurableMemoryJob: ...
+
+    def ensure_agent_scope(self, *, project_scope: str, agent_scope: str) -> None: ...
+    def list_agent_scopes(self, *, project_scope: str) -> list[str]: ...
+
+
+class SqlAlchemyMemoryRepository:
+    def __init__(self, engine: Engine) -> None:
+        self.engine = engine
+        migrate_memory_schema(engine)
+
+    def save_record(
+        self,
+        *,
+        project_scope: str,
+        agent_scope: str | None,
+        record: MemoryRecord,
+        source: str,
+    ) -> DurableMemoryRecord:
+        now = _utc_now()
+        row = MemoryRecordRow(
+            id=str(uuid4()),
+            project_scope=project_scope,
+            agent_scope=agent_scope,
+            memory_type=record.type,
+            payload=record.model_dump(),
+            source=source,
+            status=MemoryRecordStatus.ACTIVE.value,
+            created_at=now,
+            updated_at=now,
+        )
+        version = MemoryVersionRow(
+            id=str(uuid4()),
+            memory_record_id=row.id,
+            payload=row.payload,
+            source=source,
+            status=row.status,
+            created_at=now,
+        )
+        with Session(self.engine, expire_on_commit=False) as session:
+            session.add(row)
+            session.add(version)
+            session.commit()
+        return _record_from_row(row)
+
+    def list_records(
+        self,
+        *,
+        project_scope: str,
+        memory_type: MemoryType | None = None,
+        agent_scope: str | None = None,
+        include_deleted: bool = False,
+        limit: int = 20,
+    ) -> list[DurableMemoryRecord]:
+        stmt = select(MemoryRecordRow).where(MemoryRecordRow.project_scope == project_scope)
+        if memory_type is not None:
+            stmt = stmt.where(MemoryRecordRow.memory_type == memory_type)
+        if agent_scope is not None:
+            stmt = stmt.where(
+                or_(
+                    MemoryRecordRow.agent_scope == agent_scope,
+                    MemoryRecordRow.agent_scope.is_(None),
+                )
+            )
+        if not include_deleted:
+            stmt = stmt.where(MemoryRecordRow.status != MemoryRecordStatus.DELETED.value)
+        stmt = stmt.order_by(desc(MemoryRecordRow.updated_at)).limit(limit)
+        with Session(self.engine) as session:
+            rows = session.scalars(stmt).all()
+        return [_record_from_row(row) for row in rows]
+
+    def delete_record(self, *, record_id: str, deleted_by: str) -> bool:
+        with Session(self.engine, expire_on_commit=False) as session:
+            row = session.get(MemoryRecordRow, record_id)
+            if row is None:
+                return False
+            row.status = MemoryRecordStatus.DELETED.value
+            row.updated_at = _utc_now()
+            session.add(
+                MemoryVersionRow(
+                    id=str(uuid4()),
+                    memory_record_id=row.id,
+                    payload=row.payload,
+                    source=deleted_by,
+                    status=row.status,
+                    created_at=row.updated_at,
+                )
+            )
+            session.commit()
+            return True
+
+    def append_job(
+        self,
+        *,
+        project_scope: str,
+        agent_scope: str | None,
+        job_type: str,
+        dedupe_key: str,
+        payload: dict[str, Any],
+    ) -> DurableMemoryJob:
+        with Session(self.engine, expire_on_commit=False) as session:
+            existing = session.scalar(
+                select(MemoryExtractionJobRow).where(
+                    MemoryExtractionJobRow.dedupe_key == dedupe_key
+                )
+            )
+            if existing is not None:
+                return _job_from_row(existing)
+            now = _utc_now()
+            row = MemoryExtractionJobRow(
+                id=str(uuid4()),
+                project_scope=project_scope,
+                agent_scope=agent_scope,
+                status=MemoryJobStatus.QUEUED.value,
+                job_type=job_type,
+                dedupe_key=dedupe_key,
+                payload=payload,
+                archive_object_key=None,
+                error_message=None,
+                created_at=now,
+                updated_at=now,
+            )
+            session.add(row)
+            session.commit()
+            return _job_from_row(row)
+
+    def get_job(self, job_id: str) -> DurableMemoryJob | None:
+        with Session(self.engine, expire_on_commit=False) as session:
+            row = session.get(MemoryExtractionJobRow, job_id)
+        return _job_from_row(row) if row is not None else None
+
+    def list_jobs(
+        self,
+        *,
+        project_scope: str,
+        agent_scope: str | None = None,
+        job_type: str | None = None,
+        status: MemoryJobStatus | None = None,
+        limit: int = 20,
+    ) -> list[DurableMemoryJob]:
+        stmt = select(MemoryExtractionJobRow).where(
+            MemoryExtractionJobRow.project_scope == project_scope
+        )
+        if agent_scope is not None:
+            stmt = stmt.where(MemoryExtractionJobRow.agent_scope == agent_scope)
+        if job_type is not None:
+            stmt = stmt.where(MemoryExtractionJobRow.job_type == job_type)
+        if status is not None:
+            stmt = stmt.where(MemoryExtractionJobRow.status == status.value)
+        stmt = stmt.order_by(desc(MemoryExtractionJobRow.updated_at)).limit(limit)
+        with Session(self.engine, expire_on_commit=False) as session:
+            rows = session.scalars(stmt).all()
+        return [_job_from_row(row) for row in rows]
+
+    def update_job_status(
+        self,
+        *,
+        job_id: str,
+        status: MemoryJobStatus,
+        error_message: str | None = None,
+        archive_object_key: str | None = None,
+    ) -> DurableMemoryJob:
+        with Session(self.engine, expire_on_commit=False) as session:
+            row = session.get(MemoryExtractionJobRow, job_id)
+            if row is None:
+                raise KeyError(f"Unknown memory extraction job: {job_id}")
+            row.status = status.value
+            row.updated_at = _utc_now()
+            row.error_message = error_message
+            row.archive_object_key = archive_object_key
+            session.commit()
+            return _job_from_row(row)
+
+    def ensure_agent_scope(self, *, project_scope: str, agent_scope: str) -> None:
+        with Session(self.engine, expire_on_commit=False) as session:
+            existing = session.scalar(
+                select(AgentMemoryScopeRow).where(
+                    AgentMemoryScopeRow.project_scope == project_scope,
+                    AgentMemoryScopeRow.agent_scope == agent_scope,
+                )
+            )
+            if existing is not None:
+                return
+            now = _utc_now()
+            session.add(
+                AgentMemoryScopeRow(
+                    id=str(uuid4()),
+                    project_scope=project_scope,
+                    agent_scope=agent_scope,
+                    created_at=now,
+                    updated_at=now,
+                )
+            )
+            session.commit()
+
+    def list_agent_scopes(self, *, project_scope: str) -> list[str]:
+        stmt = (
+            select(AgentMemoryScopeRow.agent_scope)
+            .where(AgentMemoryScopeRow.project_scope == project_scope)
+            .order_by(AgentMemoryScopeRow.agent_scope)
+        )
+        with Session(self.engine, expire_on_commit=False) as session:
+            return list(session.scalars(stmt).all())
+
+
+def _record_from_row(row: MemoryRecordRow) -> DurableMemoryRecord:
+    return DurableMemoryRecord(
+        id=row.id,
+        project_scope=row.project_scope,
+        agent_scope=row.agent_scope,
+        record=MemoryRecord.model_validate(row.payload),
+        source=row.source,
+        status=MemoryRecordStatus(row.status),
+        created_at=row.created_at,
+        updated_at=row.updated_at,
+    )
+
+
+def _job_from_row(row: MemoryExtractionJobRow) -> DurableMemoryJob:
+    return DurableMemoryJob(
+        id=row.id,
+        project_scope=row.project_scope,
+        agent_scope=row.agent_scope,
+        status=MemoryJobStatus(row.status),
+        job_type=row.job_type,
+        dedupe_key=row.dedupe_key,
+        payload=dict(row.payload),
+        archive_object_key=row.archive_object_key,
+        error_message=row.error_message,
+        created_at=row.created_at,
+        updated_at=row.updated_at,
+    )
diff --git a/coding-deepgent/src/coding_deepgent/memory/extractor.py b/coding-deepgent/src/coding_deepgent/memory/extractor.py
new file mode 100644
index 000000000..efac9347e
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/memory/extractor.py
@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+
+from coding_deepgent.memory.schemas import MemoryRecord
+from coding_deepgent.memory.service import ExtractionCandidate
+
+URL_RE = re.compile(r"https?://\S+")
+DATE_RE = re.compile(r"\b\d{4}-\d{2}-\d{2}\b")
+
+
+def extract_memory_candidates(candidate: ExtractionCandidate) -> list[MemoryRecord]:
+    text = " ".join(candidate.text.split())
+    lowered = text.casefold()
+    records: list[MemoryRecord] = []
+
+    if _looks_like_feedback(lowered):
+        records.append(
+            MemoryRecord(
+                type="feedback",
+                rule=_first_sentence(text),
+                why="Auto-extracted from user/assistant interaction.",
+                how_to_apply="Apply this guidance in future related actions unless a stronger project rule conflicts.",
+                source="auto_extract",
+            )
+        )
+
+    if URL_RE.search(text):
+        records.append(
+            MemoryRecord(
+                type="reference",
+                label="Auto-extracted external reference",
+                pointer=URL_RE.search(text).group(0),  # type: ignore[union-attr]
+                purpose="External resource mentioned during work.",
+                how_to_apply="Use when later work refers to the same external system or document.",
+                source="auto_extract",
+            )
+        )
+
+    if _looks_like_project_fact(lowered):
+        effective_date = DATE_RE.search(text)
+        records.append(
+            MemoryRecord(
+                type="project",
+                fact_or_decision=_first_sentence(text),
+                why="Auto-extracted from a likely project decision or long-lived constraint.",
+                how_to_apply="Treat as a project-level fact until contradicted by fresher evidence.",
+                effective_date=effective_date.group(0) if effective_date else None,
+                source="auto_extract",
+            )
+        )
+
+    return _dedupe_records(records)
+
+
+def _looks_like_feedback(lowered: str) -> bool:
+    return any(
+        phrase in lowered
+        for phrase in (
+            "do not ",
+            "don't ",
+            "must ",
+            "before ",
+            "prefer ",
+            "always ",
+        )
+    )
+
+
+def _looks_like_project_fact(lowered: str) -> bool:
+    return any(
+        phrase in lowered
+        for phrase in (
+            "because ",
+            "deadline",
+            "release",
+            "migration",
+            "we use ",
+            "we are ",
+        )
+    )
+
+
+def _first_sentence(text: str) -> str:
+    return text.split(".")[0].strip() or text[:200].strip()
+
+
+def _dedupe_records(records: Sequence[MemoryRecord]) -> list[MemoryRecord]:
+    seen: set[tuple[str, str]] = set()
+    result: list[MemoryRecord] = []
+    for record in records:
+        key = (record.type, record.identity_text())
+        if key in seen:
+            continue
+        seen.add(key)
+        result.append(record)
+    return result
diff --git a/coding-deepgent/src/coding_deepgent/memory/feedback_enforcement.py b/coding-deepgent/src/coding_deepgent/memory/feedback_enforcement.py
new file mode 100644
index 000000000..3739dd68c
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/memory/feedback_enforcement.py
@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+
+from coding_deepgent.memory.recall import recall_memories
+from coding_deepgent.memory.service import MemoryService
+from coding_deepgent.memory.schemas import MemoryRecord
+from coding_deepgent.memory.store import MemoryStore
+
+DEPENDENCY_FILES = (
+    "package.json",
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    "pyproject.toml",
+    "requirements.txt",
+    "requirements-dev.txt",
+)
+DEPENDENCY_COMMAND_HINTS = (
+    "npm install",
+    "npm add",
+    "pnpm add",
+    "yarn add",
+    "pip install",
+    "poetry add",
+    "uv add",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class FeedbackEnforcementDecision:
+    blocked: bool
+    message: str = ""
+    matched_rule: str | None = None
+
+
+def evaluate_feedback_enforcement(
+    *,
+    store: MemoryStore | None,
+    service: MemoryService | None = None,
+    project_scope: str = "default",
+    agent_scope: str | None = None,
+    tool_name: str,
+    args: Mapping[str, object],
+) -> FeedbackEnforcementDecision:
+    feedback_memories = recall_memories(
+        store,
+        service=service,
+        project_scope=project_scope,
+        agent_scope=agent_scope,
+        memory_type="feedback",
+        limit=50,
+    )
+    for record in feedback_memories:
+        decision = _evaluate_feedback_record(record, tool_name=tool_name, args=args)
+        if decision.blocked:
+            return decision
+    return FeedbackEnforcementDecision(blocked=False)
+
+
+def _evaluate_feedback_record(
+    record: MemoryRecord,
+    *,
+    tool_name: str,
+    args: Mapping[str, object],
+) -> FeedbackEnforcementDecision:
+    text = _feedback_text(record)
+    command = str(args.get("command", ""))
+    path = str(args.get("path", ""))
+
+    if "lint" in text and "commit" in text and tool_name == "bash":
+        normalized_command = command.casefold()
+        if "git commit" in normalized_command:
+            return _blocked(
+                record,
+                "Feedback requires running lint before commit. Run lint first, then retry the commit.",
+            )
+
+    if ("dependency" in text or "package.json" in text) and (
+        "confirm" in text or "approval" in text
+    ):
+        lowered_path = path.casefold()
+        lowered_command = command.casefold()
+        if tool_name in {"write_file", "edit_file"} and any(
+            dependency_file in lowered_path for dependency_file in DEPENDENCY_FILES
+        ):
+            return _blocked(
+                record,
+                "Feedback requires confirmation before dependency changes. Stop and confirm before editing dependency files.",
+            )
+        if tool_name == "bash" and any(
+            hint in lowered_command for hint in DEPENDENCY_COMMAND_HINTS
+        ):
+            return _blocked(
+                record,
+                "Feedback requires confirmation before dependency changes. Stop and confirm before running dependency install commands.",
+            )
+
+    if "generated" in text and (
+        "do not modify" in text or "don't modify" in text or "avoid modifying" in text
+    ):
+        if tool_name in {"write_file", "edit_file"} and "generated" in path.casefold():
+            return _blocked(
+                record,
+                "Feedback forbids modifying generated files. Do not edit generated paths directly.",
+            )
+    return FeedbackEnforcementDecision(blocked=False)
+
+
+def _feedback_text(record: MemoryRecord) -> str:
+    pieces: Sequence[str | None] = (record.rule, record.why, record.how_to_apply)
+    return " ".join(part.casefold() for part in pieces if part)
+
+
+def _blocked(record: MemoryRecord, message: str) -> FeedbackEnforcementDecision:
+    return FeedbackEnforcementDecision(
+        blocked=True,
+        message=message,
+        matched_rule=record.rule,
+    )
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..d93a1facd
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/memory/middleware.py
@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from collections.abc import Callable, MutableMapping
+from dataclasses import dataclass
+from typing import Any, cast
+
+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.runtime_support import (
+    runtime_agent_scope,
+    runtime_memory_service,
+    runtime_project_scope,
+)
+from coding_deepgent.memory.schemas import MemoryType
+from coding_deepgent.memory.state_snapshot import (
+    build_long_term_memory_snapshot,
+    build_long_term_memory_snapshot_from_durable_records,
+    write_long_term_memory_snapshot,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class MemoryContextMiddleware(AgentMiddleware):
+    memory_type: MemoryType | None = None
+    limit: int = 5
+    snapshot_limit: int = 12
+
+    def wrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], ModelResponse],
+    ) -> ModelResponse:
+        store = getattr(request.runtime, "store", None)
+        service = runtime_memory_service(request.runtime)
+        project_scope = runtime_project_scope(request.runtime)
+        agent_scope = runtime_agent_scope(request.runtime)
+        if hasattr(request.state, "__setitem__"):
+            write_long_term_memory_snapshot(
+                cast(MutableMapping[str, Any], request.state),
+                (
+                    build_long_term_memory_snapshot_from_durable_records(
+                        service.list_records(project_scope=project_scope, limit=self.snapshot_limit)
+                    )
+                    if service is not None
+                    else build_long_term_memory_snapshot(store, limit=self.snapshot_limit)
+                ),
+            )
+        query = " ".join(
+            str(message.content)
+            for message in request.messages[-3:]
+            if hasattr(message, "content")
+        )
+        memories = recall_memories(
+            store,
+            service=service,
+            project_scope=project_scope,
+            agent_scope=agent_scope,
+            memory_type=self.memory_type,
+            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.memory_type}"
+                    if self.memory_type is not None
+                    else "memory.long_term"
+                ),
+                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..66be36d85
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/memory/policy.py
@@ -0,0 +1,124 @@
+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",
+    "derivable_information",
+    "relative_time",
+]
+
+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",
+)
+DERIVABLE_INFORMATION_PHRASES = (
+    "api endpoint",
+    "api endpoints",
+    "file list",
+    "file path",
+    "package.json",
+    "readme.md",
+    "src/",
+    "tests/",
+)
+RELATIVE_TIME_PHRASES = (
+    "today",
+    "tomorrow",
+    "yesterday",
+    "next week",
+    "this week",
+    "next month",
+    "this month",
+    "next monday",
+    "next tuesday",
+    "next wednesday",
+    "next thursday",
+    "next friday",
+    "next saturday",
+    "next sunday",
+)
+
+
+@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.search_text())
+    if len(normalized.split()) <= 2:
+        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",
+        )
+
+    if record.type == "project" and any(
+        phrase in normalized for phrase in DERIVABLE_INFORMATION_PHRASES
+    ):
+        return MemoryQualityDecision(
+            allowed=False,
+            category="derivable_information",
+            reason="memory looks derivable from repository structure or code",
+        )
+
+    if record.type == "project" and any(
+        phrase in normalized for phrase in RELATIVE_TIME_PHRASES
+    ):
+        return MemoryQualityDecision(
+            allowed=False,
+            category="relative_time",
+            reason="project memory must use absolute dates instead of relative time",
+        )
+
+    dedupe_key = normalize_memory_content(record.identity_text())
+    for existing in existing_records:
+        if normalize_memory_content(existing.identity_text()) == dedupe_key:
+            return MemoryQualityDecision(
+                allowed=False,
+                category="duplicate",
+                reason=f"duplicate memory already exists in {record.type}",
+            )
+
+    return MemoryQualityDecision(
+        allowed=True,
+        category="accepted",
+        reason="memory is durable reusable knowledge",
+    )
diff --git a/coding-deepgent/src/coding_deepgent/memory/queue.py b/coding-deepgent/src/coding_deepgent/memory/queue.py
new file mode 100644
index 000000000..8e9a11215
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/memory/queue.py
@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import json
+from collections import deque
+from dataclasses import asdict, dataclass
+from typing import Any, Deque, Protocol, cast
+
+from redis import Redis
+
+
+@dataclass(frozen=True, slots=True)
+class MemoryJobEnvelope:
+    job_id: str
+    job_type: str
+    dedupe_key: str
+
+
+class MemoryQueue(Protocol):
+    def enqueue(self, envelope: MemoryJobEnvelope) -> None: ...
+    def dequeue(self) -> MemoryJobEnvelope | None: ...
+
+
+class RedisMemoryQueue:
+    def __init__(self, client: Redis, *, queue_name: str = "coding-deepgent:memory-jobs") -> None:
+        self.client = client
+        self.queue_name = queue_name
+
+    def enqueue(self, envelope: MemoryJobEnvelope) -> None:
+        self.client.rpush(self.queue_name, json.dumps(asdict(envelope)))
+
+    def dequeue(self) -> MemoryJobEnvelope | None:
+        item = cast(Any, self.client.lpop(self.queue_name))
+        if item is None:
+            return None
+        if isinstance(item, bytes):
+            item = item.decode("utf-8")
+        payload = json.loads(item)
+        return MemoryJobEnvelope(**payload)
+
+
+class InMemoryQueue:
+    def __init__(self) -> None:
+        self._items: Deque[MemoryJobEnvelope] = deque()
+
+    def enqueue(self, envelope: MemoryJobEnvelope) -> None:
+        self._items.append(envelope)
+
+    def dequeue(self) -> MemoryJobEnvelope | None:
+        if not self._items:
+            return None
+        return self._items.popleft()
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..7f05ca77f
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/memory/recall.py
@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Sequence
+
+from coding_deepgent.memory.schemas import MEMORY_TYPE_ORDER, MemoryRecord, MemoryType
+from coding_deepgent.memory.service import MemoryService
+from coding_deepgent.memory.store import MemoryStore, list_memory_records
+
+
+def recall_memories(
+    store: MemoryStore | None,
+    *,
+    service: MemoryService | None = None,
+    project_scope: str = "default",
+    agent_scope: str | None = None,
+    memory_type: MemoryType | None = None,
+    query: str = "",
+    limit: int = 5,
+) -> list[MemoryRecord]:
+    if service is None and store is None:
+        return []
+
+    selected_types = (memory_type,) if memory_type is not None else MEMORY_TYPE_ORDER
+    if service is not None:
+        records = [
+            durable.record
+            for selected_type in selected_types
+            for durable in service.list_records(
+                project_scope=project_scope,
+                memory_type=selected_type,
+                agent_scope=agent_scope,
+                limit=limit,
+            )
+        ]
+    else:
+        assert store is not None
+        records = [
+            record
+            for selected_type in selected_types
+            for record in list_memory_records(store, selected_type)
+        ]
+    query_terms = {term.casefold() for term in query.split()}
+    if query_terms:
+        records = [
+            record
+            for record in records
+            if query_terms & set(record.search_text().casefold().split())
+        ]
+    records.sort(key=lambda record: (record.priority, record.identity_text()))
+    return records[:limit]
+
+
+def render_memories(records: Sequence[MemoryRecord]) -> str | None:
+    if not records:
+        return None
+
+    grouped: dict[MemoryType, list[MemoryRecord]] = defaultdict(list)
+    for record in records:
+        grouped[record.type].append(record)
+
+    lines = ["Relevant long-term memory:"]
+    for memory_type in MEMORY_TYPE_ORDER:
+        if memory_type not in grouped:
+            continue
+        lines.append(_type_heading(memory_type))
+        for record in grouped[memory_type]:
+            lines.extend(_render_record_lines(record))
+    return "\n".join(lines)
+
+
+def _type_heading(memory_type: MemoryType) -> str:
+    headings: dict[MemoryType, str] = {
+        "feedback": "Feedback memory:",
+        "project": "Project memory:",
+        "reference": "Reference memory:",
+        "user": "User memory:",
+    }
+    return headings[memory_type]
+
+
+def _render_record_lines(record: MemoryRecord) -> list[str]:
+    if record.type == "feedback":
+        return [
+            f"- Rule: {record.rule}",
+            f"  Why: {record.why}",
+            f"  How to apply: {record.how_to_apply}",
+        ]
+    if record.type == "project":
+        lines = [
+            f"- Decision: {record.fact_or_decision}",
+            f"  Why: {record.why}",
+            f"  How to apply: {record.how_to_apply}",
+        ]
+        if record.effective_date is not None:
+            lines.append(f"  Effective date: {record.effective_date}")
+        return lines
+    if record.type == "reference":
+        return [
+            f"- Label: {record.label}",
+            f"  Pointer: {record.pointer}",
+            f"  Purpose: {record.purpose}",
+            f"  How to apply: {record.how_to_apply}",
+        ]
+    return [
+        f"- Profile: {record.profile}",
+        f"  Why it matters: {record.why_it_matters}",
+        f"  How to apply: {record.how_to_apply}",
+    ]
diff --git a/coding-deepgent/src/coding_deepgent/memory/runtime_support.py b/coding-deepgent/src/coding_deepgent/memory/runtime_support.py
new file mode 100644
index 000000000..788044ef4
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/memory/runtime_support.py
@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from coding_deepgent.memory.service import MemoryService
+
+
+def runtime_memory_service(runtime: object) -> MemoryService | None:
+    context = getattr(runtime, "context", None)
+    service = getattr(context, "memory_service", None)
+    return service if isinstance(service, MemoryService) else None
+
+
+def runtime_project_scope(runtime: object) -> str:
+    context = getattr(runtime, "context", None)
+    workdir = getattr(context, "workdir", None)
+    if workdir is None:
+        return "default"
+    return str(workdir)
+
+
+def runtime_agent_scope(runtime: object) -> str | None:
+    context = getattr(runtime, "context", None)
+    agent_name = getattr(context, "agent_name", None)
+    entrypoint = getattr(context, "entrypoint", "")
+    if not isinstance(agent_name, str) or not agent_name:
+        return None
+    if isinstance(entrypoint, str) and (
+        entrypoint.startswith("run_subagent:") or entrypoint == "run_fork"
+    ):
+        return agent_name
+    return None
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..9b33fb63e
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/memory/schemas.py
@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+import re
+from typing import Literal
+
+from langchain.tools import ToolRuntime
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+MemoryType = Literal["user", "feedback", "project", "reference"]
+MEMORY_TYPE_ORDER: tuple[MemoryType, ...] = (
+    "feedback",
+    "project",
+    "reference",
+    "user",
+)
+MEMORY_TYPE_PRIORITY: dict[MemoryType, int] = {
+    memory_type: index for index, memory_type in enumerate(MEMORY_TYPE_ORDER)
+}
+_DATE_PATTERN = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+
+class _MemoryFields(BaseModel):
+    type: MemoryType = Field(..., description="Long-term memory type.")
+    source: str = Field(default="agent", description="Source label for this memory entry.")
+
+    profile: str | None = Field(
+        default=None, description="Durable user background or collaboration profile."
+    )
+    why_it_matters: str | None = Field(
+        default=None, description="Why this user profile matters for collaboration."
+    )
+
+    rule: str | None = Field(
+        default=None, description="Behavioral rule validated or corrected by the user."
+    )
+    why: str | None = Field(
+        default=None, description="Why this memory matters or why the rule/decision exists."
+    )
+    how_to_apply: str | None = Field(
+        default=None, description="How to apply this memory in future work."
+    )
+
+    fact_or_decision: str | None = Field(
+        default=None, description="Non-derivable project fact or decision."
+    )
+    effective_date: str | None = Field(
+        default=None,
+        description="Absolute effective date in YYYY-MM-DD when time is part of the project memory.",
+    )
+
+    label: str | None = Field(
+        default=None, description="Short label for an external reference."
+    )
+    pointer: str | None = Field(
+        default=None, description="External pointer such as a URL, channel, or system identifier."
+    )
+    purpose: str | None = Field(
+        default=None, description="What the external reference is used for."
+    )
+
+    @field_validator(
+        "source",
+        "profile",
+        "why_it_matters",
+        "rule",
+        "why",
+        "how_to_apply",
+        "fact_or_decision",
+        "effective_date",
+        "label",
+        "pointer",
+        "purpose",
+        mode="before",
+    )
+    @classmethod
+    def _strip_optional_text(cls, value: object) -> object:
+        if value is None:
+            return None
+        if not isinstance(value, str):
+            return value
+        value = value.strip()
+        if not value:
+            raise ValueError("value required")
+        return value
+
+    @model_validator(mode="after")
+    def _validate_type_shape(self) -> _MemoryFields:
+        required_by_type: dict[MemoryType, tuple[str, ...]] = {
+            "user": ("profile", "why_it_matters", "how_to_apply"),
+            "feedback": ("rule", "why", "how_to_apply"),
+            "project": ("fact_or_decision", "why", "how_to_apply"),
+            "reference": ("label", "pointer", "purpose", "how_to_apply"),
+        }
+        allowed_by_type: dict[MemoryType, set[str]] = {
+            "user": {"profile", "why_it_matters", "how_to_apply"},
+            "feedback": {"rule", "why", "how_to_apply"},
+            "project": {"fact_or_decision", "why", "how_to_apply", "effective_date"},
+            "reference": {"label", "pointer", "purpose", "how_to_apply"},
+        }
+        for field_name in required_by_type[self.type]:
+            if getattr(self, field_name) is None:
+                raise ValueError(f"{field_name} is required when type={self.type}")
+
+        for field_name in (
+            "profile",
+            "why_it_matters",
+            "rule",
+            "why",
+            "how_to_apply",
+            "fact_or_decision",
+            "effective_date",
+            "label",
+            "pointer",
+            "purpose",
+        ):
+            if (
+                field_name not in allowed_by_type[self.type]
+                and getattr(self, field_name) is not None
+            ):
+                raise ValueError(f"{field_name} is not allowed when type={self.type}")
+
+        if self.effective_date is not None and not _DATE_PATTERN.fullmatch(
+            self.effective_date
+        ):
+            raise ValueError("effective_date must use YYYY-MM-DD")
+        return self
+
+
+class MemoryRecord(_MemoryFields):
+    model_config = ConfigDict(extra="forbid")
+
+    def identity_text(self) -> str:
+        if self.type == "user":
+            return "\n".join(
+                (self.profile or "", self.why_it_matters or "", self.how_to_apply or "")
+            )
+        if self.type == "feedback":
+            return "\n".join((self.rule or "", self.why or "", self.how_to_apply or ""))
+        if self.type == "project":
+            return "\n".join(
+                (
+                    self.fact_or_decision or "",
+                    self.why or "",
+                    self.how_to_apply or "",
+                    self.effective_date or "",
+                )
+            )
+        return "\n".join(
+            (
+                self.label or "",
+                self.pointer or "",
+                self.purpose or "",
+                self.how_to_apply or "",
+            )
+        )
+
+    def search_text(self) -> str:
+        return self.identity_text()
+
+    @property
+    def priority(self) -> int:
+        return MEMORY_TYPE_PRIORITY[self.type]
+
+
+class SaveMemoryInput(_MemoryFields):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    runtime: ToolRuntime
+
+
+class ListMemoryInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    type: MemoryType | None = Field(
+        default=None,
+        description="Optional memory type filter. Omit to list every long-term memory type.",
+    )
+    limit: int = Field(
+        default=20, ge=1, le=100, description="Maximum number of memory entries to return."
+    )
+    runtime: ToolRuntime
+
+
+class DeleteMemoryInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    type: MemoryType = Field(..., description="Memory type that owns the entry.")
+    key: str = Field(..., min_length=1, description="Exact memory entry key to delete.")
+    runtime: ToolRuntime
+
+    @field_validator("key")
+    @classmethod
+    def _key_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/service.py b/coding-deepgent/src/coding_deepgent/memory/service.py
new file mode 100644
index 000000000..b7412f9ff
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/memory/service.py
@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from hashlib import sha256
+from typing import Callable
+
+from coding_deepgent.memory.archive import MemoryArchiveStore
+from coding_deepgent.memory.backend import (
+    DurableMemoryJob,
+    DurableMemoryRecord,
+    DurableMemoryRepository,
+    MemoryJobStatus,
+)
+from coding_deepgent.memory.policy import evaluate_memory_quality
+from coding_deepgent.memory.queue import MemoryJobEnvelope, MemoryQueue
+from coding_deepgent.memory.schemas import MemoryRecord, MemoryType
+
+
+@dataclass(frozen=True, slots=True)
+class ExtractionCandidate:
+    project_scope: str
+    agent_scope: str | None
+    source: str
+    text: str
+
+
+class MemoryService:
+    def __init__(
+        self,
+        *,
+        repository: DurableMemoryRepository,
+        queue: MemoryQueue,
+        archive_store: MemoryArchiveStore | None = None,
+        extractor: Callable[[ExtractionCandidate], list[MemoryRecord]] | None = None,
+    ) -> None:
+        self.repository = repository
+        self.queue = queue
+        self.archive_store = archive_store
+        self.extractor = extractor or (lambda candidate: [])
+
+    def save_record(
+        self,
+        *,
+        project_scope: str,
+        agent_scope: str | None,
+        record: MemoryRecord,
+        source: str,
+    ) -> DurableMemoryRecord:
+        existing = self.repository.list_records(
+            project_scope=project_scope,
+            memory_type=record.type,
+            agent_scope=agent_scope,
+            limit=200,
+        )
+        quality = evaluate_memory_quality(
+            record, existing_records=[item.record for item in existing]
+        )
+        if not quality.allowed:
+            raise ValueError(quality.reason)
+        if agent_scope is not None:
+            self.repository.ensure_agent_scope(
+                project_scope=project_scope, agent_scope=agent_scope
+            )
+        stored = self.repository.save_record(
+            project_scope=project_scope,
+            agent_scope=agent_scope,
+            record=record,
+            source=source,
+        )
+        self.enqueue_snapshot_refresh(
+            project_scope=project_scope,
+            agent_scope=agent_scope,
+            trigger=f"save:{record.type}",
+        )
+        return stored
+
+    def list_records(
+        self,
+        *,
+        project_scope: str,
+        memory_type: MemoryType | None = None,
+        agent_scope: str | None = None,
+        limit: int = 20,
+    ) -> list[DurableMemoryRecord]:
+        return self.repository.list_records(
+            project_scope=project_scope,
+            memory_type=memory_type,
+            agent_scope=agent_scope,
+            limit=limit,
+        )
+
+    def delete_record(
+        self,
+        *,
+        record_id: str,
+        deleted_by: str,
+        project_scope: str,
+        agent_scope: str | None,
+    ) -> bool:
+        deleted = self.repository.delete_record(record_id=record_id, deleted_by=deleted_by)
+        if deleted:
+            self.enqueue_snapshot_refresh(
+                project_scope=project_scope,
+                agent_scope=agent_scope,
+                trigger="delete",
+            )
+        return deleted
+
+    def enqueue_extraction(
+        self,
+        *,
+        project_scope: str,
+        agent_scope: str | None,
+        source: str,
+        text: str,
+    ) -> DurableMemoryJob:
+        dedupe_key = _dedupe_key("extract", project_scope, agent_scope, text)
+        job = self.repository.append_job(
+            project_scope=project_scope,
+            agent_scope=agent_scope,
+            job_type="extract_long_term_memory",
+            dedupe_key=dedupe_key,
+            payload={"source": source, "text": text},
+        )
+        self.queue.enqueue(
+            MemoryJobEnvelope(
+                job_id=job.id, job_type=job.job_type, dedupe_key=job.dedupe_key
+            )
+        )
+        return job
+
+    def enqueue_snapshot_refresh(
+        self,
+        *,
+        project_scope: str,
+        agent_scope: str | None,
+        trigger: str,
+    ) -> DurableMemoryJob:
+        dedupe_key = _dedupe_key("snapshot", project_scope, agent_scope, trigger)
+        job = self.repository.append_job(
+            project_scope=project_scope,
+            agent_scope=agent_scope,
+            job_type="refresh_agent_memory_snapshot",
+            dedupe_key=dedupe_key,
+            payload={"trigger": trigger},
+        )
+        self.queue.enqueue(
+            MemoryJobEnvelope(
+                job_id=job.id, job_type=job.job_type, dedupe_key=job.dedupe_key
+            )
+        )
+        return job
+
+    def list_jobs(
+        self,
+        *,
+        project_scope: str,
+        agent_scope: str | None = None,
+        job_type: str | None = None,
+        status: MemoryJobStatus | None = None,
+        limit: int = 20,
+    ) -> list[DurableMemoryJob]:
+        return self.repository.list_jobs(
+            project_scope=project_scope,
+            agent_scope=agent_scope,
+            job_type=job_type,
+            status=status,
+            limit=limit,
+        )
+
+    def list_agent_scopes(self, *, project_scope: str) -> list[str]:
+        return self.repository.list_agent_scopes(project_scope=project_scope)
+
+    def process_next_job(self) -> DurableMemoryJob | None:
+        envelope = self.queue.dequeue()
+        if envelope is None:
+            return None
+        job = self.repository.update_job_status(
+            job_id=envelope.job_id, status=MemoryJobStatus.RUNNING
+        )
+        try:
+            if job.job_type == "extract_long_term_memory":
+                self._process_extraction_job(job)
+                archive_object_key = None
+            elif job.job_type == "refresh_agent_memory_snapshot":
+                archive_object_key = self._process_snapshot_job(job)
+            else:
+                raise ValueError(f"Unsupported memory job type: {job.job_type}")
+            return self.repository.update_job_status(
+                job_id=job.id,
+                status=MemoryJobStatus.COMPLETED,
+                archive_object_key=archive_object_key,
+            )
+        except Exception as exc:
+            return self.repository.update_job_status(
+                job_id=job.id,
+                status=MemoryJobStatus.FAILED,
+                error_message=str(exc),
+            )
+
+    def _process_extraction_job(self, job: DurableMemoryJob) -> None:
+        candidate = ExtractionCandidate(
+            project_scope=job.project_scope,
+            agent_scope=job.agent_scope,
+            source=str(job.payload.get("source", "auto")),
+            text=str(job.payload.get("text", "")),
+        )
+        for record in self.extractor(candidate):
+            self.save_record(
+                project_scope=job.project_scope,
+                agent_scope=job.agent_scope,
+                record=record,
+                source="auto_extract",
+            )
+
+    def _process_snapshot_job(self, job: DurableMemoryJob) -> str | None:
+        if self.archive_store is None:
+            return None
+        records = self.repository.list_records(
+            project_scope=job.project_scope,
+            agent_scope=job.agent_scope,
+            limit=500,
+        )
+        object_key = _snapshot_object_key(
+            project_scope=job.project_scope,
+            agent_scope=job.agent_scope,
+        )
+        return self.archive_store.put_json(
+            object_key=object_key,
+            payload={
+                "project_scope": job.project_scope,
+                "agent_scope": job.agent_scope,
+                "records": [record.record.model_dump() for record in records],
+            },
+        )
+
+
+def _dedupe_key(
+    kind: str, project_scope: str, agent_scope: str | None, text: str
+) -> str:
+    payload = f"{kind}\0{project_scope}\0{agent_scope or ''}\0{text}"
+    return sha256(payload.encode("utf-8")).hexdigest()[:24]
+
+
+def _snapshot_object_key(*, project_scope: str, agent_scope: str | None) -> str:
+    slug = project_scope.strip("/").replace("/", "_")
+    scope = (agent_scope or "global").replace("/", "_")
+    return f"memory-snapshots/{slug}/{scope}.json"
diff --git a/coding-deepgent/src/coding_deepgent/memory/state_snapshot.py b/coding-deepgent/src/coding_deepgent/memory/state_snapshot.py
new file mode 100644
index 000000000..d6eab68f2
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/memory/state_snapshot.py
@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, MutableMapping
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from coding_deepgent.memory.schemas import MEMORY_TYPE_ORDER, MemoryRecord, MemoryType
+from coding_deepgent.memory.store import MemoryEntry, MemoryStore, list_memory_entries
+
+if TYPE_CHECKING:
+    from coding_deepgent.memory.backend import DurableMemoryRecord
+
+LONG_TERM_MEMORY_STATE_KEY = "long_term_memory"
+
+
+class LongTermMemoryEntrySnapshot(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    key: str = Field(..., min_length=1)
+    type: MemoryType
+    summary: str = Field(..., min_length=1)
+
+    @field_validator("key", "summary")
+    @classmethod
+    def _text_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("value required")
+        return value
+
+
+class LongTermMemorySnapshot(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    entries: list[LongTermMemoryEntrySnapshot] = Field(default_factory=list)
+    updated_at: str = Field(..., min_length=1)
+
+    @field_validator("updated_at")
+    @classmethod
+    def _updated_at_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("value required")
+        return value
+
+
+def build_long_term_memory_snapshot(
+    store: MemoryStore | None,
+    *,
+    limit: int = 12,
+) -> LongTermMemorySnapshot | None:
+    if store is None:
+        return None
+    entries = [
+        LongTermMemoryEntrySnapshot(
+            key=entry.key,
+            type=entry.record.type,
+            summary=_memory_entry_summary(entry),
+        )
+        for memory_type in MEMORY_TYPE_ORDER
+        for entry in list_memory_entries(store, memory_type)
+    ][:limit]
+    if not entries:
+        return None
+    return LongTermMemorySnapshot(
+        entries=entries,
+        updated_at=datetime.now(UTC).isoformat().replace("+00:00", "Z"),
+    )
+
+
+def build_long_term_memory_snapshot_from_records(
+    records: Sequence[MemoryRecord],
+    *,
+    limit: int = 12,
+) -> LongTermMemorySnapshot | None:
+    entries = [
+        LongTermMemoryEntrySnapshot(
+            key=f"record-{index}",
+            type=record.type,
+            summary=_record_summary(record),
+        )
+        for index, record in enumerate(records[:limit], start=1)
+    ]
+    if not entries:
+        return None
+    return LongTermMemorySnapshot(
+        entries=entries,
+        updated_at=datetime.now(UTC).isoformat().replace("+00:00", "Z"),
+    )
+
+
+def build_long_term_memory_snapshot_from_durable_records(
+    records: Sequence["DurableMemoryRecord"],
+    *,
+    limit: int = 12,
+) -> LongTermMemorySnapshot | None:
+    entries = [
+        LongTermMemoryEntrySnapshot(
+            key=record.id,
+            type=record.record.type,
+            summary=_record_summary(record.record),
+        )
+        for record in records[:limit]
+    ]
+    if not entries:
+        return None
+    return LongTermMemorySnapshot(
+        entries=entries,
+        updated_at=datetime.now(UTC).isoformat().replace("+00:00", "Z"),
+    )
+
+
+def read_long_term_memory_snapshot(
+    state: Mapping[str, Any],
+) -> LongTermMemorySnapshot | None:
+    value = state.get(LONG_TERM_MEMORY_STATE_KEY)
+    if not isinstance(value, dict):
+        return None
+    try:
+        return LongTermMemorySnapshot.model_validate(value)
+    except ValidationError:
+        return None
+
+
+def write_long_term_memory_snapshot(
+    state: MutableMapping[str, Any],
+    snapshot: LongTermMemorySnapshot | None,
+) -> None:
+    if snapshot is None:
+        state.pop(LONG_TERM_MEMORY_STATE_KEY, None)
+        return
+    state[LONG_TERM_MEMORY_STATE_KEY] = snapshot.model_dump()
+
+
+def _memory_entry_summary(entry: MemoryEntry) -> str:
+    record = entry.record
+    return _record_summary(record)
+
+
+def _record_summary(record: MemoryRecord) -> str:
+    if record.type == "feedback":
+        return str(record.rule)
+    if record.type == "project":
+        return str(record.fact_or_decision)
+    if record.type == "reference":
+        return f"{record.label} -> {record.pointer}"
+    return str(record.profile)
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..5f94a533b
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/memory/store.py
@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from hashlib import sha256
+from typing import Iterable, Protocol
+
+from coding_deepgent.memory.schemas import MemoryRecord, MemoryType
+
+MEMORY_ROOT_NAMESPACE = "coding_deepgent_memory"
+
+
+class MemoryStore(Protocol):
+    def put(
+        self, namespace: tuple[str, ...], key: str, value: dict[str, object]
+    ) -> None: ...
+    def delete(self, namespace: tuple[str, ...], key: str) -> None: ...
+    def search(self, namespace: tuple[str, ...]) -> Iterable[object]: ...
+
+
+def memory_namespace(memory_type: MemoryType) -> tuple[str, ...]:
+    return (MEMORY_ROOT_NAMESPACE, memory_type)
+
+
+def memory_key(record: MemoryRecord) -> str:
+    digest = sha256(f"{record.type}\0{record.identity_text()}".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.type), key, record.model_dump())
+    return key
+
+
+@dataclass(frozen=True, slots=True)
+class MemoryEntry:
+    key: str
+    record: MemoryRecord
+
+
+def list_memory_records(
+    store: MemoryStore, memory_type: MemoryType
+) -> list[MemoryRecord]:
+    return [entry.record for entry in list_memory_entries(store, memory_type)]
+
+
+def list_memory_entries(
+    store: MemoryStore, memory_type: MemoryType
+) -> list[MemoryEntry]:
+    records: list[MemoryEntry] = []
+    for item in store.search(memory_namespace(memory_type)):
+        value = getattr(item, "value", item)
+        key = getattr(item, "key", None)
+        if isinstance(value, dict) and value and isinstance(key, str):
+            records.append(
+                MemoryEntry(key=key, record=MemoryRecord.model_validate(value))
+            )
+    return records
+
+
+def delete_memory_record(store: MemoryStore, *, memory_type: MemoryType, key: str) -> bool:
+    existing_keys = {entry.key for entry in list_memory_entries(store, memory_type)}
+    if key not in existing_keys:
+        return False
+    store.delete(memory_namespace(memory_type), key)
+    return True
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..8fa4e96eb
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/memory/tools.py
@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+from typing import cast
+
+from langchain.tools import ToolRuntime, tool
+
+from coding_deepgent.memory.schemas import (
+    DeleteMemoryInput,
+    ListMemoryInput,
+    MemoryRecord,
+    MemoryType,
+    SaveMemoryInput,
+)
+from coding_deepgent.memory.policy import evaluate_memory_quality
+from coding_deepgent.memory.runtime_support import (
+    runtime_agent_scope,
+    runtime_memory_service,
+    runtime_project_scope,
+)
+from coding_deepgent.memory.store import (
+    delete_memory_record,
+    list_memory_entries,
+    list_memory_records,
+    save_memory_record,
+)
+
+
+@tool(
+    "save_memory",
+    args_schema=SaveMemoryInput,
+    description=(
+        "Save durable long-term memory using one of four types: feedback, project, "
+        "reference, or user. Save only non-derivable information that should remain "
+        "useful across sessions. Do not save transient todos, current plans, task "
+        "status, recovery notes, repository structure, duplicates, or relative dates."
+    ),
+)
+def save_memory(
+    type: str,
+    runtime: ToolRuntime,
+    source: str = "agent",
+    profile: str | None = None,
+    why_it_matters: str | None = None,
+    rule: str | None = None,
+    why: str | None = None,
+    how_to_apply: str | None = None,
+    fact_or_decision: str | None = None,
+    effective_date: str | None = None,
+    label: str | None = None,
+    pointer: str | None = None,
+    purpose: str | None = None,
+) -> str:
+    """Save structured long-term memory through the LangGraph store seam."""
+
+    service = runtime_memory_service(runtime)
+    validated = SaveMemoryInput(
+        type=cast(MemoryType, type),
+        source=source,
+        profile=profile,
+        why_it_matters=why_it_matters,
+        rule=rule,
+        why=why,
+        how_to_apply=how_to_apply,
+        fact_or_decision=fact_or_decision,
+        effective_date=effective_date,
+        label=label,
+        pointer=pointer,
+        purpose=purpose,
+        runtime=runtime,
+    )
+    if service is not None:
+        stored = service.save_record(
+            project_scope=runtime_project_scope(runtime),
+            agent_scope=runtime_agent_scope(runtime),
+            record=MemoryRecord(
+                type=validated.type,
+                source=validated.source,
+                profile=validated.profile,
+                why_it_matters=validated.why_it_matters,
+                rule=validated.rule,
+                why=validated.why,
+                how_to_apply=validated.how_to_apply,
+                fact_or_decision=validated.fact_or_decision,
+                effective_date=validated.effective_date,
+                label=validated.label,
+                pointer=validated.pointer,
+                purpose=validated.purpose,
+            ),
+            source=validated.source,
+        )
+        return f"Saved {validated.type} memory {stored.id}."
+
+    store = runtime.store
+    if store is None:
+        return "Memory store is not configured; memory was not saved."
+    record = MemoryRecord(
+        type=validated.type,
+        source=validated.source,
+        profile=validated.profile,
+        why_it_matters=validated.why_it_matters,
+        rule=validated.rule,
+        why=validated.why,
+        how_to_apply=validated.how_to_apply,
+        fact_or_decision=validated.fact_or_decision,
+        effective_date=validated.effective_date,
+        label=validated.label,
+        pointer=validated.pointer,
+        purpose=validated.purpose,
+    )
+    quality = evaluate_memory_quality(
+        record, existing_records=list_memory_records(store, validated.type)
+    )
+    if not quality.allowed:
+        return f"Memory not saved: {quality.reason}."
+
+    key = save_memory_record(store, record)
+    return f"Saved {validated.type} memory {key}."
+
+
+@tool(
+    "list_memory",
+    args_schema=ListMemoryInput,
+    description=(
+        "List saved long-term memory entries. Optionally filter by one memory type. "
+        "Use this before deleting or auditing memory."
+    ),
+)
+def list_memory(
+    runtime: ToolRuntime,
+    type: str | None = None,
+    limit: int = 20,
+) -> str:
+    service = runtime_memory_service(runtime)
+    if service is not None:
+        selected_types: tuple[MemoryType, ...] = (
+            (cast(MemoryType, type),)
+            if type is not None
+            else ("feedback", "project", "reference", "user")
+        )
+        durable_entries = [
+            (memory_type, item)
+            for memory_type in selected_types
+            for item in service.list_records(
+                project_scope=runtime_project_scope(runtime),
+                memory_type=memory_type,
+                agent_scope=runtime_agent_scope(runtime),
+                limit=limit,
+            )
+        ][:limit]
+        if not durable_entries:
+            return "No long-term memory entries found."
+        lines = ["Long-term memory entries:"]
+        for memory_type, item in durable_entries:
+            lines.append(f"- [{memory_type}] {item.id}: {_memory_entry_summary(item.record)}")
+        return "\n".join(lines)
+
+    store = runtime.store
+    if store is None:
+        return "Memory store is not configured; no memory entries are available."
+
+    store_selected_types: tuple[MemoryType, ...] = (
+        (cast(MemoryType, type),)
+        if type is not None
+        else ("feedback", "project", "reference", "user")
+    )
+    store_entries = [
+        (memory_type, entry)
+        for memory_type in store_selected_types
+        for entry in list_memory_entries(store, memory_type)
+    ][:limit]
+    if not store_entries:
+        return "No long-term memory entries found."
+
+    lines = ["Long-term memory entries:"]
+    for memory_type, entry in store_entries:
+        lines.append(f"- [{memory_type}] {entry.key}: {_memory_entry_summary(entry.record)}")
+    return "\n".join(lines)
+
+
+@tool(
+    "delete_memory",
+    args_schema=DeleteMemoryInput,
+    description=(
+        "Delete one long-term memory entry by exact type and key. "
+        "Use list_memory first to inspect keys."
+    ),
+)
+def delete_memory(type: str, key: str, runtime: ToolRuntime) -> str:
+    service = runtime_memory_service(runtime)
+    if service is not None:
+        deleted = service.delete_record(
+            record_id=key,
+            deleted_by="tool",
+            project_scope=runtime_project_scope(runtime),
+            agent_scope=runtime_agent_scope(runtime),
+        )
+        if not deleted:
+            return f"Memory not deleted: no {type} memory exists with key {key}."
+        return f"Deleted {type} memory {key}."
+
+    store = runtime.store
+    if store is None:
+        return "Memory store is not configured; memory was not deleted."
+    deleted = delete_memory_record(store, memory_type=cast(MemoryType, type), key=key)
+    if not deleted:
+        return f"Memory not deleted: no {type} memory exists with key {key}."
+    return f"Deleted {type} memory {key}."
+
+
+def _memory_entry_summary(record: MemoryRecord) -> str:
+    if record.type == "feedback":
+        return str(record.rule)
+    if record.type == "project":
+        return str(record.fact_or_decision)
+    if record.type == "reference":
+        return f"{record.label} -> {record.pointer}"
+    return str(record.profile)
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..1ee93eb91
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/plugins/registry.py
@@ -0,0 +1,103 @@
+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, ...]
+    agents: 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,
+                agents=plugin.manifest.agents,
+            )
+            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 declared_agents(self) -> tuple[str, ...]:
+        return tuple(agent for item in self.declarations() for agent in item.agents)
+
+    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,
+                    agents=item.agents,
+                )
+            )
+        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..f7e21df40
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/plugins/schemas.py
@@ -0,0 +1,58 @@
+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, ...] = ()
+    agents: 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", "agents")
+    @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..0d25f37cb
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/prompting/builder.py
@@ -0,0 +1,79 @@
+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
+from coding_deepgent.rules import render_project_rules_for_prompt
+
+
+@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
+    rules_context: str | None = None
+    memory_context: str | None = None
+
+    @property
+    def system_prompt_parts(self) -> tuple[str, ...]:
+        parts = [*self.default_system_prompt]
+        if self.rules_context:
+            parts.append(self.rules_context)
+        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.",
+        (
+            "Some low-frequency or extension tools are deferred. Use ToolSearch to "
+            "discover their exact schemas, then invoke_deferred_tool to execute one "
+            "deferred tool by exact name."
+        ),
+    )
+
+
+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,
+        rules_context=render_project_rules_for_prompt(workdir),
+        memory_context=render_memories(memories),
+    )
diff --git a/coding-deepgent/src/coding_deepgent/remote/__init__.py b/coding-deepgent/src/coding_deepgent/remote/__init__.py
new file mode 100644
index 000000000..5d54fb7cd
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/remote/__init__.py
@@ -0,0 +1,21 @@
+from .store import (
+    REMOTE_NAMESPACE,
+    RemoteSession,
+    close_remote_session,
+    get_remote_session,
+    list_remote_sessions,
+    register_remote_session,
+    replay_remote_events,
+    send_remote_control,
+)
+
+__all__ = [
+    "REMOTE_NAMESPACE",
+    "RemoteSession",
+    "close_remote_session",
+    "get_remote_session",
+    "list_remote_sessions",
+    "register_remote_session",
+    "replay_remote_events",
+    "send_remote_control",
+]
diff --git a/coding-deepgent/src/coding_deepgent/remote/store.py b/coding-deepgent/src/coding_deepgent/remote/store.py
new file mode 100644
index 000000000..a75233dd0
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/remote/store.py
@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from datetime import UTC, datetime
+from hashlib import sha256
+from typing import Any, Literal, Protocol
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from coding_deepgent.event_stream import EventRecord, append_event, list_events
+
+REMOTE_NAMESPACE = ("coding_deepgent_remote_sessions",)
+RemoteStatus = Literal["active", "closed"]
+
+
+class RemoteStore(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]: ...
+
+
+class RemoteSession(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    remote_id: str
+    session_id: str = Field(..., min_length=1)
+    client_name: str = Field(..., min_length=1)
+    status: RemoteStatus = "active"
+    last_sequence_sent: int = 0
+    created_at: str
+    updated_at: str
+
+
+def register_remote_session(
+    store: RemoteStore,
+    *,
+    session_id: str,
+    client_name: str,
+) -> RemoteSession:
+    now = _now()
+    remote = RemoteSession(
+        remote_id=_remote_id(session_id=session_id, client_name=client_name, created_at=now),
+        session_id=session_id.strip(),
+        client_name=client_name.strip(),
+        created_at=now,
+        updated_at=now,
+    )
+    store.put(REMOTE_NAMESPACE, remote.remote_id, remote.model_dump())
+    append_event(
+        store,
+        stream_id=f"remote:{remote.remote_id}",
+        kind="remote_registered",
+        payload=remote.model_dump(),
+    )
+    return remote
+
+
+def get_remote_session(store: RemoteStore, remote_id: str) -> RemoteSession:
+    item = store.get(REMOTE_NAMESPACE, remote_id)
+    if item is None:
+        raise KeyError(f"Unknown remote session: {remote_id}")
+    return RemoteSession.model_validate(_item_value(item))
+
+
+def list_remote_sessions(store: RemoteStore) -> list[RemoteSession]:
+    return sorted(
+        [
+            RemoteSession.model_validate(_item_value(item))
+            for item in store.search(REMOTE_NAMESPACE)
+        ],
+        key=lambda item: item.remote_id,
+    )
+
+
+def send_remote_control(
+    store: RemoteStore,
+    *,
+    remote_id: str,
+    command: str,
+    payload: dict[str, Any] | None = None,
+) -> EventRecord:
+    remote = get_remote_session(store, remote_id)
+    if remote.status != "active":
+        raise ValueError("remote session is closed")
+    return append_event(
+        store,
+        stream_id=f"remote:{remote.remote_id}",
+        kind=f"control:{command.strip()}",
+        payload=payload or {},
+    )
+
+
+def replay_remote_events(
+    store: RemoteStore,
+    *,
+    remote_id: str,
+    after_sequence: int | None = None,
+) -> list[EventRecord]:
+    remote = get_remote_session(store, remote_id)
+    return list_events(
+        store,
+        stream_id=f"remote:{remote.remote_id}",
+        after_sequence=after_sequence,
+        include_internal=False,
+    )
+
+
+def close_remote_session(store: RemoteStore, remote_id: str) -> RemoteSession:
+    remote = get_remote_session(store, remote_id)
+    updated = remote.model_copy(update={"status": "closed", "updated_at": _now()})
+    store.put(REMOTE_NAMESPACE, updated.remote_id, updated.model_dump())
+    append_event(
+        store,
+        stream_id=f"remote:{updated.remote_id}",
+        kind="remote_closed",
+        payload={"remote_id": updated.remote_id},
+    )
+    return updated
+
+
+def _item_value(item: object) -> dict[str, object]:
+    value = getattr(item, "value", item)
+    return value if isinstance(value, dict) else {}
+
+
+def _remote_id(*, session_id: str, client_name: str, created_at: str) -> str:
+    digest = sha256(f"{session_id}\0{client_name}\0{created_at}".encode("utf-8")).hexdigest()
+    return f"remote-{digest[:12]}"
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat().replace("+00:00", "Z")
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..97300cd0a
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/renderers/text.py
@@ -0,0 +1,394 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from io import StringIO
+import json
+from typing import Any
+
+from rich import box
+from rich.console import Console
+from rich.table import Table
+
+from coding_deepgent.sessions.inspection import SessionInspectView
+
+_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)
+
+
+def render_task_table(tasks: Sequence[Mapping[str, Any]]) -> str:
+    if not tasks:
+        return "No tasks recorded."
+    table = Table(title="Tasks", box=box.SIMPLE_HEAVY)
+    table.add_column("Task", style="cyan", no_wrap=True)
+    table.add_column("Status", no_wrap=True)
+    table.add_column("Ready", no_wrap=True)
+    table.add_column("Owner", no_wrap=True)
+    table.add_column("Depends On")
+    table.add_column("Title")
+    for task in tasks:
+        metadata = task.get("metadata", {})
+        ready = "-"
+        if isinstance(metadata, Mapping):
+            ready = str(metadata.get("ready", "-"))
+        depends_on = task.get("depends_on", [])
+        depends_text = ", ".join(str(item) for item in depends_on) if isinstance(depends_on, Sequence) and not isinstance(depends_on, str) else "-"
+        table.add_row(
+            str(task.get("id", "unknown")),
+            str(task.get("status", "-")),
+            ready,
+            str(task.get("owner", "-") or "-"),
+            depends_text or "-",
+            str(task.get("title", "")),
+        )
+    return _render_table(table)
+
+
+def render_plan_table(plans: Sequence[Mapping[str, Any]]) -> str:
+    if not plans:
+        return "No plans recorded."
+    table = Table(title="Plans", box=box.SIMPLE_HEAVY)
+    table.add_column("Plan", style="cyan", no_wrap=True)
+    table.add_column("Title")
+    table.add_column("Tasks")
+    table.add_column("Verification")
+    for plan in plans:
+        task_ids = plan.get("task_ids", [])
+        tasks_text = ", ".join(str(item) for item in task_ids) if isinstance(task_ids, Sequence) and not isinstance(task_ids, str) else "-"
+        table.add_row(
+            str(plan.get("id", "unknown")),
+            str(plan.get("title", "")),
+            tasks_text or "-",
+            _preview(plan.get("verification", "")),
+        )
+    return _render_table(table)
+
+
+def render_subagent_table(runs: Sequence[Mapping[str, Any]]) -> str:
+    if not runs:
+        return "No background subagent runs recorded."
+    table = Table(title="Subagents", box=box.SIMPLE_HEAVY)
+    table.add_column("Run", style="cyan", no_wrap=True)
+    table.add_column("Status", no_wrap=True)
+    table.add_column("Mode", no_wrap=True)
+    table.add_column("Agent", no_wrap=True)
+    table.add_column("Pending", justify="right", no_wrap=True)
+    table.add_column("Calls", justify="right", no_wrap=True)
+    table.add_column("Progress")
+    for run in runs:
+        pending_inputs = run.get("pending_inputs", [])
+        pending_count = (
+            len(pending_inputs)
+            if isinstance(pending_inputs, Sequence) and not isinstance(pending_inputs, str)
+            else 0
+        )
+        table.add_row(
+            str(run.get("run_id", "unknown")),
+            str(run.get("status", "-")),
+            str(run.get("mode", "-")),
+            str(run.get("agent_type", "-")),
+            str(pending_count),
+            str(run.get("total_invocations", 0)),
+            _preview(run.get("progress_summary", "")),
+        )
+    return _render_table(table)
+
+
+def render_object_detail(title: str, payload: Mapping[str, Any]) -> str:
+    table = Table(title=title, box=box.SIMPLE_HEAVY, show_header=False)
+    table.add_column("Key", style="cyan", no_wrap=True)
+    table.add_column("Value")
+    for key in sorted(payload):
+        table.add_row(str(key), _preview(payload[key], limit=500))
+    return _render_table(table)
+
+
+def render_session_inspect_view(
+    view: SessionInspectView,
+    *,
+    show_recovery: bool = True,
+    show_model: bool = True,
+    show_raw: bool = True,
+    limit: int = 20,
+) -> str:
+    lines: list[str] = ["Session Inspect", ""]
+    lines.extend(
+        [
+            f"session_id: {view.session_id}",
+            f"workdir: {view.workdir}",
+            f"transcript: {view.transcript_path}",
+            f"created_at: {view.created_at or '-'}",
+            f"updated_at: {view.updated_at or '-'}",
+            (
+                "counts: "
+                f"messages={view.message_count} "
+                f"evidence={view.evidence_count} "
+                f"compacts={view.compact_count} "
+                f"collapses={view.collapse_count} "
+                f"sidechain={view.sidechain_count}"
+            ),
+            (
+                "projection: "
+                f"mode={view.projection_mode} "
+                f"model_messages={len(view.model_projection)} "
+                f"raw_visible={view.visible_raw_count} "
+                f"raw_hidden={view.hidden_raw_count}"
+            ),
+            _session_memory_line(view),
+        ]
+    )
+    if show_recovery:
+        lines.extend(("", "Recovery Brief", _indent(view.recovery_brief)))
+    lines.extend(("", "Compression Timeline"))
+    lines.extend(_timeline_lines(view, limit=limit))
+    if show_model:
+        lines.extend(("", "Model Projection"))
+        lines.extend(_projection_lines(view, limit=limit))
+    if show_raw:
+        lines.extend(("", "Raw Transcript Visibility"))
+        lines.extend(_raw_lines(view, limit=limit))
+    return "\n".join(lines).rstrip()
+
+
+def render_session_history_table(
+    view: SessionInspectView,
+    *,
+    limit: int = 50,
+) -> str:
+    return "\n".join(["Raw Transcript Visibility", *_raw_lines(view, limit=limit)])
+
+
+def render_session_projection_table(
+    view: SessionInspectView,
+    *,
+    limit: int = 50,
+) -> str:
+    return "\n".join(
+        [
+            f"Model Projection ({view.projection_mode})",
+            *_projection_lines(view, limit=limit),
+        ]
+    )
+
+
+def render_session_timeline_table(
+    view: SessionInspectView,
+    *,
+    limit: int = 50,
+) -> str:
+    return "\n".join(["Compression Timeline", *_timeline_lines(view, limit=limit)])
+
+
+def render_evidence_table(
+    title: str,
+    evidence: Sequence[Mapping[str, Any]],
+    *,
+    limit: int = 50,
+) -> str:
+    if not evidence:
+        return f"No {title.lower()} recorded."
+    table = Table(title=title, box=box.SIMPLE_HEAVY)
+    table.add_column("Created", no_wrap=True)
+    table.add_column("Kind", style="cyan", no_wrap=True)
+    table.add_column("Status", no_wrap=True)
+    table.add_column("Subject", no_wrap=True)
+    table.add_column("Summary")
+    for item in evidence[:limit]:
+        table.add_row(
+            str(item.get("created_at", "-")),
+            str(item.get("kind", "-")),
+            str(item.get("status", "-")),
+            str(item.get("subject", "-") or "-"),
+            _preview(item.get("summary", "")),
+        )
+    rendered = _render_table(table)
+    if len(evidence) > limit:
+        rendered = f"{rendered}\n... {len(evidence) - limit} more"
+    return rendered
+
+
+def render_extension_table(
+    title: str,
+    rows: Sequence[Mapping[str, Any]],
+) -> str:
+    if not rows:
+        return f"No {title.lower()} recorded."
+    table = Table(title=title, box=box.SIMPLE_HEAVY)
+    table.add_column("Name", style="cyan", no_wrap=True)
+    table.add_column("Status", no_wrap=True)
+    table.add_column("Description")
+    table.add_column("Path")
+    for row in rows:
+        table.add_row(
+            str(row.get("name", "unknown")),
+            str(row.get("status", "-")),
+            _preview(row.get("description", "")),
+            str(row.get("path", "-")),
+        )
+    return _render_table(table)
+
+
+def render_acceptance_table(
+    rows: Sequence[Mapping[str, Any]],
+    *,
+    title: str = "Acceptance",
+) -> str:
+    table = Table(title=title, box=box.SIMPLE_HEAVY)
+    table.add_column("Check", style="cyan", no_wrap=True)
+    table.add_column("Status", no_wrap=True)
+    table.add_column("Detail")
+    for row in rows:
+        table.add_row(
+            str(row.get("name", "unknown")),
+            str(row.get("status", "unknown")),
+            str(row.get("detail", "")),
+        )
+    return _render_table(table)
+
+
+def _session_memory_line(view: SessionInspectView) -> str:
+    memory = view.session_memory
+    if memory.status == "missing":
+        return (
+            "session_memory: missing "
+            f"(messages={memory.current_message_count}; "
+            f"tokens~={memory.estimated_token_count}; tools={memory.tool_call_count})"
+        )
+    return (
+        f"session_memory: {memory.status} "
+        f"source={memory.source or '-'} "
+        f"artifact_messages={memory.artifact_message_count} "
+        f"current_messages={memory.current_message_count} "
+        f"tokens~={memory.estimated_token_count} "
+        f"tools={memory.tool_call_count} "
+        f"preview={_preview(memory.content)}"
+    )
+
+
+def _timeline_lines(view: SessionInspectView, *, limit: int) -> list[str]:
+    if not view.timeline:
+        return ["- none"]
+    rows = []
+    for event in view.timeline[:limit]:
+        affected = ",".join(event.affected_message_ids) or "-"
+        tools = ",".join(event.affected_tool_call_ids) or "-"
+        rows.append(
+            "- "
+            f"{event.event_id} {event.event_type} "
+            f"trigger={event.trigger or '-'} "
+            f"source={event.source or '-'} "
+            f"messages={affected} "
+            f"tools={tools} "
+            f"summary={_preview(event.summary)}"
+        )
+    return _with_limit(rows, len(view.timeline), limit)
+
+
+def _projection_lines(view: SessionInspectView, *, limit: int) -> list[str]:
+    if not view.model_projection:
+        return ["- none"]
+    rows = []
+    for index, message in enumerate(view.model_projection[:limit]):
+        source_id = message.message_id or message.event_id or "-"
+        covered = ",".join(message.covered_message_ids) or "-"
+        rows.append(
+            "- "
+            f"#{index} role={message.role} source={message.source} "
+            f"id={source_id} covers={covered} "
+            f"preview={_preview(message.content)}"
+        )
+    return _with_limit(rows, len(view.model_projection), limit)
+
+
+def _raw_lines(view: SessionInspectView, *, limit: int) -> list[str]:
+    if not view.raw_messages:
+        return ["- none"]
+    rows = []
+    for message in view.raw_messages[:limit]:
+        visibility = "visible" if message.model_visible else "hidden"
+        hidden_by = ",".join(message.hidden_by_event_ids) or "-"
+        rows.append(
+            "- "
+            f"{message.message_id} role={message.role} {visibility} "
+            f"hidden_by={hidden_by} preview={_preview(message.content)}"
+        )
+    return _with_limit(rows, len(view.raw_messages), limit)
+
+
+def _with_limit(rows: list[str], total: int, limit: int) -> list[str]:
+    if total > limit:
+        rows.append(f"- ... {total - limit} more")
+    return rows
+
+
+def _indent(text: str) -> str:
+    return "\n".join(f"  {line}" if line else "" for line in text.splitlines())
+
+
+def _preview(value: Any, *, limit: int = 120) -> str:
+    if value is None:
+        text = ""
+    elif isinstance(value, str):
+        text = value
+    else:
+        try:
+            text = json.dumps(value, ensure_ascii=True, sort_keys=True)
+        except TypeError:
+            text = str(value)
+    text = " ".join(text.split())
+    if len(text) > limit:
+        return f"{text[: limit - 3]}..."
+    return text
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/rules/__init__.py b/coding-deepgent/src/coding_deepgent/rules/__init__.py
new file mode 100644
index 000000000..71fb20e69
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/rules/__init__.py
@@ -0,0 +1,17 @@
+from .files import (
+    RULES_DIRNAME,
+    RULES_FILENAME,
+    project_rules_path,
+    project_rules_signal,
+    read_project_rules,
+    render_project_rules_for_prompt,
+)
+
+__all__ = [
+    "RULES_DIRNAME",
+    "RULES_FILENAME",
+    "project_rules_path",
+    "project_rules_signal",
+    "read_project_rules",
+    "render_project_rules_for_prompt",
+]
diff --git a/coding-deepgent/src/coding_deepgent/rules/files.py b/coding-deepgent/src/coding_deepgent/rules/files.py
new file mode 100644
index 000000000..f38f6d21c
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/rules/files.py
@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+RULES_DIRNAME = ".coding-deepgent"
+RULES_FILENAME = "RULES.md"
+
+
+def project_rules_path(workdir: Path) -> Path:
+    return workdir / RULES_DIRNAME / RULES_FILENAME
+
+
+def read_project_rules(workdir: Path) -> str | None:
+    path = project_rules_path(workdir)
+    if not path.exists() or not path.is_file():
+        return None
+    content = path.read_text(encoding="utf-8").strip()
+    if not content:
+        return None
+    return content
+
+
+def render_project_rules_for_prompt(workdir: Path) -> str | None:
+    content = read_project_rules(workdir)
+    if content is None:
+        return None
+    return (
+        "Project-level rules:\n"
+        f"{content}\n\n"
+        "Treat these rules as persistent behavior constraints for this project."
+    )
+
+
+def project_rules_signal(workdir: Path) -> str:
+    path = project_rules_path(workdir)
+    if path.exists() and path.is_file():
+        return f"- present: {RULES_DIRNAME}/{RULES_FILENAME}"
+    return "- none"
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..c6b3d0c47
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/runtime/__init__.py
@@ -0,0 +1,53 @@
+from .checkpointing import select_checkpointer, select_store
+from .context import RuntimeContext
+from .file_store import FileStore
+from .agent_factory import (
+    RuntimeAgentBuildRequest,
+    RuntimeAgentFactory,
+    create_runtime_agent,
+)
+from .events import (
+    InMemoryEventSink,
+    NullEventSink,
+    QueuedRuntimeEventSink,
+    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
+from .roles import CURRENT_RUNTIME_ROLES, FUTURE_TEAM_RUNTIME_ROLES, RuntimeAgentRole
+
+__all__ = [
+    "DEFAULT_SESSION_ID",
+    "CURRENT_RUNTIME_ROLES",
+    "FileStore",
+    "FUTURE_TEAM_RUNTIME_ROLES",
+    "InMemoryEventSink",
+    "NullEventSink",
+    "QueuedRuntimeEventSink",
+    "PlanningState",
+    "RuntimeAgentBuildRequest",
+    "RuntimeAgentFactory",
+    "RuntimeAgentRole",
+    "RuntimeContext",
+    "RuntimeEvent",
+    "RuntimeEventSink",
+    "RuntimeInvocation",
+    "RuntimeState",
+    "RuntimeTodoState",
+    "build_runnable_config",
+    "build_runtime_context",
+    "build_runtime_invocation",
+    "create_runtime_agent",
+    "default_runtime_state",
+    "resolve_session_id",
+    "select_checkpointer",
+    "select_store",
+]
diff --git a/coding-deepgent/src/coding_deepgent/runtime/agent_factory.py b/coding-deepgent/src/coding_deepgent/runtime/agent_factory.py
new file mode 100644
index 000000000..9af69fb71
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/runtime/agent_factory.py
@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from langchain.agents import create_agent as langchain_create_agent
+
+from coding_deepgent.runtime.roles import RuntimeAgentRole
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeAgentBuildRequest:
+    role: RuntimeAgentRole
+    name: str
+    model: Any
+    tools: Sequence[object]
+    system_prompt: str
+    middleware: Sequence[object] = ()
+    context_schema: type[Any] | None = None
+    state_schema: type[Any] | None = None
+    checkpointer: Any = None
+    store: Any = None
+
+
+class RuntimeAgentFactory(Protocol):
+    def __call__(
+        self,
+        request: RuntimeAgentBuildRequest,
+        *,
+        create_agent_factory: Callable[..., Any] | None = None,
+    ) -> Any: ...
+
+
+def create_runtime_agent(
+    request: RuntimeAgentBuildRequest,
+    *,
+    create_agent_factory: Callable[..., Any] | None = None,
+) -> Any:
+    factory = create_agent_factory or langchain_create_agent
+    kwargs: dict[str, Any] = {
+        "model": request.model,
+        "tools": list(request.tools),
+        "system_prompt": request.system_prompt,
+        "middleware": list(request.middleware),
+        "name": request.name,
+    }
+    if request.context_schema is not None:
+        kwargs["context_schema"] = request.context_schema
+    if request.state_schema is not None:
+        kwargs["state_schema"] = request.state_schema
+    if request.checkpointer is not None:
+        kwargs["checkpointer"] = request.checkpointer
+    if request.store is not None:
+        kwargs["store"] = request.store
+    return factory(**kwargs)
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..2f6b33c2f
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/runtime/checkpointing.py
@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import Literal
+from pathlib import Path
+
+from langgraph.checkpoint.memory import InMemorySaver
+from langgraph.store.memory import InMemoryStore
+
+from .file_store import FileStore
+
+CheckpointerBackend = Literal["none", "memory"]
+StoreBackend = Literal["none", "memory", "file"]
+
+
+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, *, store_path: Path | None = None):
+    if backend == "none":
+        return None
+    if backend == "memory":
+        return InMemoryStore()
+    if backend == "file":
+        if store_path is None:
+            raise ValueError("file store backend requires store_path")
+        return FileStore(store_path)
+    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..16370818d
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/runtime/context.py
@@ -0,0 +1,34 @@
+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.memory.service import MemoryService
+    from coding_deepgent.sessions.records import SessionContext, TranscriptProjection
+    from coding_deepgent.tool_system import ToolPoolProjection, ToolPolicy
+
+
+@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
+    transcript_projection: TranscriptProjection | None = None
+    model_context_window_tokens: int | None = None
+    subagent_spawn_guard_ratio: float | None = None
+    rendered_system_prompt: str | None = None
+    visible_tool_projection: ToolPoolProjection | None = None
+    tool_policy: ToolPolicy | None = None
+    memory_service: MemoryService | None = None
+    plugin_dir: Path = Path("plugins")
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..bc846f443
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/runtime/events.py
@@ -0,0 +1,82 @@
+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)
+
+
+class QueuedRuntimeEventSink:
+    def __init__(
+        self,
+        sink: RuntimeEventSink | None = None,
+        *,
+        max_pending: int = 1024,
+    ) -> None:
+        if max_pending < 1:
+            raise ValueError("max_pending must be positive")
+        self._sink = sink
+        self._pending: list[RuntimeEvent] = []
+        self._max_pending = max_pending
+
+    @property
+    def attached(self) -> bool:
+        return self._sink is not None
+
+    @property
+    def pending_count(self) -> int:
+        return len(self._pending)
+
+    def emit(self, event: RuntimeEvent) -> None:
+        if self._sink is not None:
+            self._sink.emit(event)
+            return
+        if len(self._pending) >= self._max_pending:
+            raise RuntimeError("runtime event queue is full before sink attachment")
+        self._pending.append(event)
+
+    def attach(self, sink: RuntimeEventSink) -> None:
+        if sink is self:
+            raise ValueError("queued runtime event sink cannot attach to itself")
+        if self._sink is sink:
+            return
+        if self._sink is not None:
+            raise RuntimeError("runtime event sink is already attached")
+        for event in self._pending:
+            sink.emit(event)
+        self._pending.clear()
+        self._sink = sink
+
+    def snapshot(self) -> tuple[RuntimeEvent, ...]:
+        sink_snapshot = getattr(self._sink, "snapshot", None)
+        if callable(sink_snapshot):
+            return tuple(sink_snapshot())
+        return tuple(self._pending)
diff --git a/coding-deepgent/src/coding_deepgent/runtime/file_store.py b/coding-deepgent/src/coding_deepgent/runtime/file_store.py
new file mode 100644
index 000000000..2d6fc5d98
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/runtime/file_store.py
@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from threading import RLock
+from typing import Any, Iterable
+
+from langgraph.store.base import (
+    BaseStore,
+    GetOp,
+    Item,
+    ListNamespacesOp,
+    MatchCondition,
+    Op,
+    PutOp,
+    Result,
+    SearchItem,
+    SearchOp,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class _StoredValue:
+    value: dict[str, Any]
+    created_at: str
+    updated_at: str
+
+
+class FileStore(BaseStore):
+    """Small JSON-backed LangGraph store for local durable task/plan state."""
+
+    _locks: dict[Path, RLock] = {}
+
+    def __init__(self, path: Path) -> None:
+        self._path = path.expanduser().resolve()
+        self._lock = self._locks.setdefault(self._path, RLock())
+
+    def batch(self, ops: Iterable[Op]) -> list[Result]:
+        with self._lock:
+            payload = self._load_payload()
+            results: list[Result] = []
+            dirty = False
+            for op in ops:
+                if isinstance(op, GetOp):
+                    results.append(self._get(payload, op))
+                    continue
+                if isinstance(op, SearchOp):
+                    results.append(self._search(payload, op))
+                    continue
+                if isinstance(op, ListNamespacesOp):
+                    results.append(self._list_namespaces(payload, op))
+                    continue
+                if isinstance(op, PutOp):
+                    self._put(payload, op)
+                    results.append(None)
+                    dirty = True
+                    continue
+                raise TypeError(f"Unsupported store op: {type(op).__name__}")
+            if dirty:
+                self._save_payload(payload)
+            return results
+
+    async def abatch(self, ops: Iterable[Op]) -> list[Result]:
+        return self.batch(ops)
+
+    def _get(self, payload: dict[str, Any], op: GetOp) -> Item | None:
+        namespace_key = _namespace_key(op.namespace)
+        records = payload.get("records", {})
+        namespace_records = records.get(namespace_key, {})
+        raw = namespace_records.get(op.key)
+        if not isinstance(raw, dict):
+            return None
+        stored = _coerce_stored_value(raw)
+        if stored is None:
+            return None
+        return Item(
+            namespace=op.namespace,
+            key=op.key,
+            value=stored.value,
+            created_at=_parse_timestamp(stored.created_at),
+            updated_at=_parse_timestamp(stored.updated_at),
+        )
+
+    def _search(self, payload: dict[str, Any], op: SearchOp) -> list[SearchItem]:
+        matched: list[SearchItem] = []
+        records = payload.get("records", {})
+        for namespace_key, namespace_records in records.items():
+            namespace = _split_namespace_key(namespace_key)
+            if not _has_prefix(namespace, op.namespace_prefix):
+                continue
+            if not isinstance(namespace_records, dict):
+                continue
+            for key, raw in namespace_records.items():
+                if not isinstance(key, str):
+                    continue
+                stored = _coerce_stored_value(raw)
+                if stored is None or not _matches_filter(stored.value, op.filter):
+                    continue
+                matched.append(
+                    SearchItem(
+                        namespace=namespace,
+                        key=key,
+                        value=stored.value,
+                        created_at=_parse_timestamp(stored.created_at),
+                        updated_at=_parse_timestamp(stored.updated_at),
+                        score=None,
+                    )
+                )
+        matched.sort(key=lambda item: (item.namespace, item.key))
+        return matched[op.offset : op.offset + op.limit]
+
+    def _list_namespaces(
+        self,
+        payload: dict[str, Any],
+        op: ListNamespacesOp,
+    ) -> list[tuple[str, ...]]:
+        candidates: set[tuple[str, ...]] = set()
+        records = payload.get("records", {})
+        for namespace_key in records:
+            if not isinstance(namespace_key, str):
+                continue
+            namespace = _split_namespace_key(namespace_key)
+            if not _matches_namespace_conditions(namespace, op.match_conditions):
+                continue
+            if op.max_depth is not None:
+                namespace = namespace[: op.max_depth]
+            candidates.add(namespace)
+        ordered = sorted(candidates)
+        return ordered[op.offset : op.offset + op.limit]
+
+    def _put(self, payload: dict[str, Any], op: PutOp) -> None:
+        records = payload.setdefault("records", {})
+        namespace_key = _namespace_key(op.namespace)
+        namespace_records = records.setdefault(namespace_key, {})
+        if op.value is None:
+            if isinstance(namespace_records, dict):
+                namespace_records.pop(op.key, None)
+            if not namespace_records:
+                records.pop(namespace_key, None)
+            return
+        now = _timestamp_now()
+        raw_existing = namespace_records.get(op.key) if isinstance(namespace_records, dict) else None
+        existing = _coerce_stored_value(raw_existing) if isinstance(raw_existing, dict) else None
+        namespace_records[op.key] = {
+            "value": json.loads(json.dumps(op.value)),
+            "created_at": existing.created_at if existing is not None else now,
+            "updated_at": now,
+        }
+
+    def _load_payload(self) -> dict[str, Any]:
+        if not self._path.exists():
+            return {"records": {}}
+        try:
+            raw = json.loads(self._path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            raise RuntimeError(f"Invalid file store payload: {self._path}") from exc
+        if not isinstance(raw, dict):
+            raise RuntimeError(f"Invalid file store payload: {self._path}")
+        records = raw.get("records", {})
+        if not isinstance(records, dict):
+            raise RuntimeError(f"Invalid file store records: {self._path}")
+        return {"records": records}
+
+    def _save_payload(self, payload: dict[str, Any]) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._path.write_text(
+            json.dumps(payload, ensure_ascii=False, sort_keys=True, indent=2),
+            encoding="utf-8",
+        )
+
+
+def _namespace_key(namespace: tuple[str, ...]) -> str:
+    return "\u241f".join(namespace)
+
+
+def _split_namespace_key(namespace_key: str) -> tuple[str, ...]:
+    if not namespace_key:
+        return ()
+    return tuple(namespace_key.split("\u241f"))
+
+
+def _coerce_stored_value(raw: object) -> _StoredValue | None:
+    if not isinstance(raw, dict):
+        return None
+    value = raw.get("value")
+    created_at = raw.get("created_at")
+    updated_at = raw.get("updated_at")
+    if not isinstance(value, dict):
+        return None
+    if not isinstance(created_at, str) or not isinstance(updated_at, str):
+        return None
+    return _StoredValue(value=value, created_at=created_at, updated_at=updated_at)
+
+
+def _parse_timestamp(value: str) -> datetime:
+    return datetime.fromisoformat(value.replace("Z", "+00:00")).astimezone(UTC)
+
+
+def _timestamp_now() -> str:
+    return datetime.now(UTC).isoformat().replace("+00:00", "Z")
+
+
+def _has_prefix(namespace: tuple[str, ...], prefix: tuple[str, ...]) -> bool:
+    return namespace[: len(prefix)] == prefix
+
+
+def _matches_filter(value: dict[str, Any], expected: dict[str, Any] | None) -> bool:
+    if not expected:
+        return True
+    return all(value.get(key) == candidate for key, candidate in expected.items())
+
+
+def _matches_namespace_conditions(
+    namespace: tuple[str, ...],
+    conditions: tuple[MatchCondition, ...] | None,
+) -> bool:
+    if not conditions:
+        return True
+    return all(_matches_namespace_condition(namespace, condition) for condition in conditions)
+
+
+def _matches_namespace_condition(
+    namespace: tuple[str, ...],
+    condition: MatchCondition,
+) -> bool:
+    path = tuple(str(part) for part in condition.path)
+    if condition.match_type == "prefix":
+        return _matches_namespace_pattern(namespace[: len(path)], path)
+    if condition.match_type == "suffix":
+        return _matches_namespace_pattern(namespace[-len(path) :], path)
+    return False
+
+
+def _matches_namespace_pattern(
+    namespace: tuple[str, ...],
+    pattern: tuple[str, ...],
+) -> bool:
+    if len(namespace) != len(pattern):
+        return False
+    return all(target == candidate or candidate == "*" for target, candidate in zip(namespace, pattern, strict=True))
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..bbe1285fb
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/runtime/invocation.py
@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+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.memory.service import MemoryService
+    from coding_deepgent.sessions.records import SessionContext, TranscriptProjection
+    from coding_deepgent.tool_system import ToolPoolProjection, ToolPolicy
+
+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, Any]:
+    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,
+    transcript_projection: TranscriptProjection | None = None,
+    rendered_system_prompt: str | None = None,
+    visible_tool_projection: ToolPoolProjection | None = None,
+    tool_policy: ToolPolicy | None = None,
+    memory_service: MemoryService | 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,
+        transcript_projection=transcript_projection,
+        model_context_window_tokens=settings.model_context_window_tokens,
+        subagent_spawn_guard_ratio=settings.subagent_spawn_guard_ratio,
+        rendered_system_prompt=rendered_system_prompt,
+        visible_tool_projection=visible_tool_projection,
+        tool_policy=tool_policy,
+        memory_service=memory_service,
+        plugin_dir=settings.plugin_dir,
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeInvocation:
+    context: RuntimeContext
+    config: dict[str, Any]
+
+    @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,
+    transcript_projection: TranscriptProjection | None = None,
+    rendered_system_prompt: str | None = None,
+    visible_tool_projection: ToolPoolProjection | None = None,
+    tool_policy: ToolPolicy | None = None,
+    memory_service: MemoryService | 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,
+            transcript_projection=transcript_projection,
+            rendered_system_prompt=rendered_system_prompt,
+            visible_tool_projection=visible_tool_projection,
+            tool_policy=tool_policy,
+            memory_service=memory_service,
+        ),
+        config=build_runnable_config(session_id=resolved_session_id),
+    )
diff --git a/coding-deepgent/src/coding_deepgent/runtime/prompt_dump.py b/coding-deepgent/src/coding_deepgent/runtime/prompt_dump.py
new file mode 100644
index 000000000..13e9a6afa
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/runtime/prompt_dump.py
@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+from collections.abc import Mapping, Sequence
+from datetime import UTC, datetime
+from pathlib import Path
+
+PROMPT_DUMP_ENV = "CODING_DEEPGENT_DUMP_PROMPTS"
+PROMPT_DUMP_DIR = ".coding-deepgent/prompt-dumps"
+MAX_DUMP_STRING_CHARS = 20_000
+MAX_DUMP_SEQUENCE_ITEMS = 200
+
+_SECRET_NAME_PARTS = ("api_key", "token", "secret", "password", "authorization")
+
+
+def prompt_dump_enabled(env: Mapping[str, str] | None = None) -> bool:
+    active_env = env or os.environ
+    return active_env.get(PROMPT_DUMP_ENV, "").strip() == "1"
+
+
+def dump_model_request_if_enabled(
+    context: object,
+    *,
+    request: object,
+    messages: Sequence[object],
+    input_token_estimate: int | None = None,
+    env: Mapping[str, str] | None = None,
+) -> Path | None:
+    if not prompt_dump_enabled(env):
+        return None
+    workdir = getattr(context, "workdir", None)
+    if not isinstance(workdir, Path):
+        return None
+    path = _dump_path(context)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    record = {
+        "record_type": "model_request",
+        "version": 1,
+        "timestamp": datetime.now(UTC).isoformat().replace("+00:00", "Z"),
+        "session_id": str(getattr(context, "session_id", "unknown")),
+        "agent_name": str(getattr(context, "agent_name", "unknown")),
+        "entrypoint": str(getattr(context, "entrypoint", "unknown")),
+        "model": type(getattr(request, "model", None)).__name__,
+        "input_token_estimate": input_token_estimate,
+        "system_message": _message_payload(getattr(request, "system_message", None)),
+        "messages": [_message_payload(message) for message in messages],
+        "tool_names": _tool_names(getattr(request, "tools", ())),
+        "tool_choice": _safe_value(getattr(request, "tool_choice", None)),
+        "model_settings": _safe_value(getattr(request, "model_settings", {})),
+    }
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(record, ensure_ascii=False, sort_keys=True, default=str))
+        handle.write("\n")
+    return path
+
+
+def _dump_path(context: object) -> Path:
+    workdir = getattr(context, "workdir")
+    session_id = _safe_path_part(str(getattr(context, "session_id", "unknown")))
+    agent_name = _safe_path_part(str(getattr(context, "agent_name", "agent")))
+    return workdir / PROMPT_DUMP_DIR / f"{session_id}__{agent_name}.jsonl"
+
+
+def _safe_path_part(value: str) -> str:
+    cleaned = re.sub(r"[^A-Za-z0-9_.-]+", "-", value.strip())
+    return cleaned.strip(".-") or "unknown"
+
+
+def _message_payload(message: object) -> dict[str, object] | None:
+    if message is None:
+        return None
+    if isinstance(message, dict):
+        payload = {
+            "role": _safe_value(message.get("role")),
+            "content": _safe_value(message.get("content")),
+        }
+        if "tool_calls" in message:
+            payload["tool_calls"] = _safe_value(message.get("tool_calls"))
+        return payload
+    payload = {
+        "type": str(getattr(message, "type", type(message).__name__)),
+        "content": _safe_value(getattr(message, "content", "")),
+    }
+    tool_calls = getattr(message, "tool_calls", None)
+    if tool_calls:
+        payload["tool_calls"] = _safe_value(tool_calls)
+    tool_call_id = getattr(message, "tool_call_id", None)
+    if tool_call_id:
+        payload["tool_call_id"] = _safe_value(tool_call_id)
+    return payload
+
+
+def _tool_names(tools: object) -> list[str]:
+    if not isinstance(tools, Sequence) or isinstance(tools, (str, bytes, bytearray)):
+        return []
+    names: list[str] = []
+    for tool in tools[:MAX_DUMP_SEQUENCE_ITEMS]:
+        name = getattr(tool, "name", None) or getattr(tool, "__name__", None)
+        names.append(str(name or type(tool).__name__))
+    return names
+
+
+def _safe_value(value: object, *, field_name: str = "") -> object:
+    if any(part in field_name.lower() for part in _SECRET_NAME_PARTS):
+        return "<redacted>"
+    if value is None or isinstance(value, (bool, int, float)):
+        return value
+    if isinstance(value, str):
+        if len(value) <= MAX_DUMP_STRING_CHARS:
+            return value
+        return {
+            "text": value[:MAX_DUMP_STRING_CHARS],
+            "truncated": True,
+            "original_chars": len(value),
+        }
+    if isinstance(value, Mapping):
+        return {
+            str(key): _safe_value(item, field_name=str(key))
+            for key, item in list(value.items())[:MAX_DUMP_SEQUENCE_ITEMS]
+        }
+    if isinstance(value, Sequence) and not isinstance(value, (bytes, bytearray)):
+        return [
+            _safe_value(item, field_name=field_name)
+            for item in list(value)[:MAX_DUMP_SEQUENCE_ITEMS]
+        ]
+    return str(value)
diff --git a/coding-deepgent/src/coding_deepgent/runtime/roles.py b/coding-deepgent/src/coding_deepgent/runtime/roles.py
new file mode 100644
index 000000000..112f878d5
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/runtime/roles.py
@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class RuntimeAgentRole(StrEnum):
+    MAIN = "main"
+    SUBAGENT = "subagent"
+    FORK = "fork"
+    COORDINATOR = "coordinator"
+    WORKER = "worker"
+
+
+CURRENT_RUNTIME_ROLES = (
+    RuntimeAgentRole.MAIN,
+    RuntimeAgentRole.SUBAGENT,
+    RuntimeAgentRole.FORK,
+)
+FUTURE_TEAM_RUNTIME_ROLES = (
+    RuntimeAgentRole.COORDINATOR,
+    RuntimeAgentRole.WORKER,
+)
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..c91f22131
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/runtime/state.py
@@ -0,0 +1,29 @@
+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]
+    long_term_memory: NotRequired[dict[str, Any]]
+    session_memory: NotRequired[dict[str, Any]]
+
+
+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..28f1cc73a
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/__init__.py
@@ -0,0 +1,98 @@
+from .compression_view import (
+    CompressionTimelineEvent,
+    CompressionView,
+    ProjectionMode,
+    ProjectionMessageView,
+    RawTranscriptMessageView,
+    build_compression_view,
+)
+from .inspection import (
+    SessionInspectView,
+    SessionMemoryInspect,
+    build_session_inspect_view,
+)
+from .langgraph import thread_config_for_session, thread_id_for_session
+from .ports import SessionStore
+from .records import (
+    COLLAPSE_EVENT_KIND,
+    CollapsedHistorySource,
+    COMPACT_EVENT_KIND,
+    CompactedHistorySource,
+    EVIDENCE_RECORD_TYPE,
+    LoadedSession,
+    MessageReference,
+    SessionCollapse,
+    SessionCompact,
+    SessionContext,
+    SessionEvidence,
+    SessionLoadError,
+    SessionMessage,
+    SessionSidechainMessage,
+    SessionSummary,
+    SUBAGENT_MESSAGE_EVENT_KIND,
+    TranscriptProjection,
+    TRANSCRIPT_EVENT_RECORD_TYPE,
+    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",
+    "COLLAPSE_EVENT_KIND",
+    "CollapsedHistorySource",
+    "COMPACT_EVENT_KIND",
+    "CompactedHistorySource",
+    "EVIDENCE_RECORD_TYPE",
+    "MessageReference",
+    "RecoveryBrief",
+    "SessionCollapse",
+    "SessionContext",
+    "SessionCompact",
+    "SessionEvidence",
+    "SessionLoadError",
+    "SessionMessage",
+    "SessionSidechainMessage",
+    "SessionStore",
+    "SessionSummary",
+    "SUBAGENT_MESSAGE_EVENT_KIND",
+    "TranscriptProjection",
+    "TRANSCRIPT_EVENT_RECORD_TYPE",
+    "JsonlSessionStore",
+    "CompressionTimelineEvent",
+    "CompressionView",
+    "ProjectionMode",
+    "ProjectionMessageView",
+    "RawTranscriptMessageView",
+    "SessionInspectView",
+    "SessionMemoryInspect",
+    "apply_resume_state",
+    "build_recovery_brief",
+    "build_compression_view",
+    "build_session_inspect_view",
+    "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/compression_view.py b/coding-deepgent/src/coding_deepgent/sessions/compression_view.py
new file mode 100644
index 000000000..6edcf1303
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/compression_view.py
@@ -0,0 +1,374 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from .records import LoadedSession, SessionCollapse, SessionCompact, SessionMessage
+
+ProjectionMode = Literal["selected", "raw", "compact", "collapse"]
+ProjectionSource = Literal[
+    "raw",
+    "compact_boundary",
+    "compact_summary",
+    "collapse_boundary",
+    "collapse_summary",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class RawTranscriptMessageView:
+    message_id: str
+    created_at: str
+    role: str
+    content: str
+    metadata: dict[str, Any] | None
+    model_visible: bool
+    hidden_by_event_ids: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectionMessageView:
+    role: str
+    content: Any
+    source: ProjectionSource
+    message_id: str | None = None
+    event_id: str | None = None
+    covered_message_ids: tuple[str, ...] = ()
+    metadata: dict[str, Any] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class CompressionTimelineEvent:
+    event_id: str
+    event_type: str
+    created_at: str
+    trigger: str | None
+    summary: str
+    affected_message_ids: tuple[str, ...] = ()
+    affected_tool_call_ids: tuple[str, ...] = ()
+    source: str | None = None
+    metadata: dict[str, Any] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class CompressionView:
+    raw_messages: tuple[RawTranscriptMessageView, ...]
+    model_projection: tuple[ProjectionMessageView, ...]
+    timeline: tuple[CompressionTimelineEvent, ...]
+    projection_mode: ProjectionMode
+
+
+def build_compression_view(
+    loaded: LoadedSession,
+    *,
+    projection_mode: ProjectionMode = "selected",
+) -> CompressionView:
+    resolved_mode = _resolve_projection_mode(loaded, projection_mode)
+    projection = _projection_messages(loaded, resolved_mode)
+    hidden_by_message = _hidden_message_events(projection)
+    return CompressionView(
+        raw_messages=_raw_message_views(loaded.history, hidden_by_message),
+        model_projection=projection,
+        timeline=_timeline_events(loaded),
+        projection_mode=resolved_mode,
+    )
+
+
+def _resolve_projection_mode(
+    loaded: LoadedSession,
+    projection_mode: ProjectionMode,
+) -> ProjectionMode:
+    if projection_mode != "selected":
+        return projection_mode
+    if loaded.collapsed_history_source.mode == "collapse":
+        return "collapse"
+    if loaded.compacted_history_source.mode == "compact":
+        return "compact"
+    return "raw"
+
+
+def _projection_messages(
+    loaded: LoadedSession,
+    projection_mode: ProjectionMode,
+) -> tuple[ProjectionMessageView, ...]:
+    if projection_mode == "raw":
+        return tuple(_raw_projection_message(message) for message in loaded.history)
+    if projection_mode == "compact":
+        compact_index = loaded.compacted_history_source.compact_index
+        if compact_index is None:
+            return tuple(_raw_projection_message(message) for message in loaded.history)
+        return _compact_projection_messages(loaded, compact_index)
+    if projection_mode == "collapse":
+        spans = _selected_collapse_spans(loaded)
+        if not spans:
+            return tuple(_raw_projection_message(message) for message in loaded.history)
+        return _collapse_projection_messages(loaded, spans)
+    return tuple(_raw_projection_message(message) for message in loaded.history)
+
+
+def _raw_projection_message(message: SessionMessage) -> ProjectionMessageView:
+    return ProjectionMessageView(
+        role=message.role,
+        content=message.content,
+        source="raw",
+        message_id=message.message_id,
+        metadata=deepcopy(message.metadata) if message.metadata is not None else None,
+    )
+
+
+def _compact_projection_messages(
+    loaded: LoadedSession,
+    compact_index: int,
+) -> tuple[ProjectionMessageView, ...]:
+    compact = loaded.compacts[compact_index]
+    event_id = f"compact-{compact_index}"
+    end_index = _message_index_by_id(loaded.history).get(compact.end_message_id, -1)
+    affected = _covered_message_ids(loaded.history, compact)
+    messages: list[ProjectionMessageView] = [
+        ProjectionMessageView(
+            role="system",
+            content=_projection_content(loaded.compacted_history, 0),
+            source="compact_boundary",
+            event_id=event_id,
+            covered_message_ids=affected,
+            metadata=deepcopy(compact.metadata) if compact.metadata is not None else None,
+        ),
+        ProjectionMessageView(
+            role="user",
+            content=_projection_content(loaded.compacted_history, 1),
+            source="compact_summary",
+            event_id=event_id,
+            covered_message_ids=affected,
+        ),
+    ]
+    messages.extend(
+        _raw_projection_message(message) for message in loaded.history[end_index + 1 :]
+    )
+    return tuple(messages)
+
+
+def _collapse_projection_messages(
+    loaded: LoadedSession,
+    spans: list[tuple[int, int, int]],
+) -> tuple[ProjectionMessageView, ...]:
+    messages: list[ProjectionMessageView] = []
+    cursor = 0
+    for start_index, end_index, collapse_index in spans:
+        messages.extend(
+            _raw_projection_message(message)
+            for message in loaded.history[cursor:start_index]
+        )
+        collapse = loaded.collapses[collapse_index]
+        event_id = f"collapse-{collapse_index}"
+        affected = _covered_message_ids(loaded.history, collapse)
+        messages.extend(
+            (
+                ProjectionMessageView(
+                    role="system",
+                    content=_collapse_boundary_text(collapse),
+                    source="collapse_boundary",
+                    event_id=event_id,
+                    covered_message_ids=affected,
+                    metadata=(
+                        deepcopy(collapse.metadata)
+                        if collapse.metadata is not None
+                        else None
+                    ),
+                ),
+                ProjectionMessageView(
+                    role="user",
+                    content=collapse.summary,
+                    source="collapse_summary",
+                    event_id=event_id,
+                    covered_message_ids=affected,
+                ),
+            )
+        )
+        cursor = end_index + 1
+    messages.extend(_raw_projection_message(message) for message in loaded.history[cursor:])
+    return tuple(messages)
+
+
+def _timeline_events(loaded: LoadedSession) -> tuple[CompressionTimelineEvent, ...]:
+    events: list[CompressionTimelineEvent] = []
+    for index, compact in enumerate(loaded.compacts):
+        event_id = f"compact-{index}"
+        metadata = deepcopy(compact.metadata) if compact.metadata is not None else None
+        events.append(
+            CompressionTimelineEvent(
+                event_id=event_id,
+                event_type="compact",
+                created_at=compact.created_at,
+                trigger=compact.trigger,
+                summary=compact.summary,
+                affected_message_ids=_covered_message_ids(loaded.history, compact),
+                source=_metadata_source(metadata),
+                metadata=metadata,
+            )
+        )
+    for index, collapse in enumerate(loaded.collapses):
+        event_id = f"collapse-{index}"
+        metadata = deepcopy(collapse.metadata) if collapse.metadata is not None else None
+        events.append(
+            CompressionTimelineEvent(
+                event_id=event_id,
+                event_type="collapse",
+                created_at=collapse.created_at,
+                trigger=collapse.trigger,
+                summary=collapse.summary,
+                affected_message_ids=_covered_message_ids(loaded.history, collapse),
+                source=_metadata_source(metadata),
+                metadata=metadata,
+            )
+        )
+    for index, evidence in enumerate(loaded.evidence):
+        if evidence.kind != "runtime_event":
+            continue
+        metadata = deepcopy(evidence.metadata) if evidence.metadata is not None else None
+        events.append(
+            CompressionTimelineEvent(
+                event_id=f"runtime-event-{index}",
+                event_type=_runtime_event_type(evidence.metadata),
+                created_at=evidence.created_at,
+                trigger=_metadata_text(evidence.metadata, "trigger"),
+                summary=evidence.summary,
+                affected_message_ids=_metadata_string_tuple(
+                    evidence.metadata,
+                    "affected_message_ids",
+                ),
+                affected_tool_call_ids=_metadata_string_tuple(
+                    evidence.metadata,
+                    "affected_tool_call_ids",
+                ),
+                source=_metadata_source(metadata),
+                metadata=metadata,
+            )
+        )
+    return tuple(sorted(events, key=lambda event: (event.created_at, event.event_id)))
+
+
+def _raw_message_views(
+    messages: list[SessionMessage],
+    hidden_by_message: dict[str, tuple[str, ...]],
+) -> tuple[RawTranscriptMessageView, ...]:
+    return tuple(
+        RawTranscriptMessageView(
+            message_id=message.message_id,
+            created_at=message.created_at,
+            role=message.role,
+            content=message.content,
+            metadata=deepcopy(message.metadata) if message.metadata is not None else None,
+            model_visible=message.message_id not in hidden_by_message,
+            hidden_by_event_ids=hidden_by_message.get(message.message_id, ()),
+        )
+        for message in messages
+    )
+
+
+def _hidden_message_events(
+    projection: tuple[ProjectionMessageView, ...],
+) -> dict[str, tuple[str, ...]]:
+    hidden: dict[str, list[str]] = {}
+    for message in projection:
+        if message.source == "raw" or message.event_id is None:
+            continue
+        for message_id in message.covered_message_ids:
+            hidden.setdefault(message_id, [])
+            if message.event_id not in hidden[message_id]:
+                hidden[message_id].append(message.event_id)
+    return {
+        message_id: tuple(event_ids)
+        for message_id, event_ids in hidden.items()
+    }
+
+
+def _selected_collapse_spans(
+    loaded: LoadedSession,
+) -> list[tuple[int, int, int]]:
+    id_to_index = _message_index_by_id(loaded.history)
+    selected: list[tuple[int, int, int]] = []
+    covered_indexes: set[int] = set()
+    for collapse_index in range(len(loaded.collapses) - 1, -1, -1):
+        collapse = loaded.collapses[collapse_index]
+        start_index = id_to_index.get(collapse.start_message_id)
+        end_index = id_to_index.get(collapse.end_message_id)
+        if start_index is None or end_index is None or end_index < start_index:
+            continue
+        covered_slice = tuple(
+            message.message_id
+            for message in loaded.history[start_index : end_index + 1]
+        )
+        if (
+            collapse.covered_message_ids is not None
+            and collapse.covered_message_ids != covered_slice
+        ):
+            continue
+        span_indexes = set(range(start_index, end_index + 1))
+        if covered_indexes & span_indexes:
+            continue
+        covered_indexes.update(span_indexes)
+        selected.append((start_index, end_index, collapse_index))
+    return sorted(selected, key=lambda item: item[0])
+
+
+def _covered_message_ids(
+    messages: list[SessionMessage],
+    event: SessionCompact | SessionCollapse,
+) -> tuple[str, ...]:
+    if event.covered_message_ids is not None:
+        return event.covered_message_ids
+    index_by_id = _message_index_by_id(messages)
+    start_index = index_by_id.get(event.start_message_id)
+    end_index = index_by_id.get(event.end_message_id)
+    if start_index is None or end_index is None or end_index < start_index:
+        return ()
+    return tuple(message.message_id for message in messages[start_index : end_index + 1])
+
+
+def _message_index_by_id(messages: list[SessionMessage]) -> dict[str, int]:
+    return {message.message_id: index for index, message in enumerate(messages)}
+
+
+def _projection_content(messages: list[dict[str, Any]], index: int) -> Any:
+    if index >= len(messages):
+        return ""
+    return deepcopy(messages[index].get("content", ""))
+
+
+def _collapse_boundary_text(collapse: SessionCollapse) -> str:
+    affected_count = len(collapse.covered_message_ids or ())
+    return (
+        "coding-deepgent collapse boundary: "
+        f"trigger={collapse.trigger}; collapsed_messages={affected_count}"
+    )
+
+
+def _runtime_event_type(metadata: dict[str, Any] | None) -> str:
+    value = _metadata_text(metadata, "event_kind")
+    return value or "runtime_event"
+
+
+def _metadata_source(metadata: dict[str, Any] | None) -> str | None:
+    return _metadata_text(metadata, "source")
+
+
+def _metadata_text(metadata: dict[str, Any] | None, key: str) -> str | None:
+    if not isinstance(metadata, dict):
+        return None
+    value = metadata.get(key)
+    return value if isinstance(value, str) and value else None
+
+
+def _metadata_string_tuple(
+    metadata: dict[str, Any] | None,
+    key: str,
+) -> tuple[str, ...]:
+    if not isinstance(metadata, dict):
+        return ()
+    value = metadata.get(key)
+    if isinstance(value, str) and value:
+        return (value,)
+    if isinstance(value, list):
+        return tuple(item for item in value if isinstance(item, str) and item)
+    return ()
diff --git a/coding-deepgent/src/coding_deepgent/sessions/contribution_registry.py b/coding-deepgent/src/coding_deepgent/sessions/contribution_registry.py
new file mode 100644
index 000000000..44081569e
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/contribution_registry.py
@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from .contributions import (
+    CompactAssistContribution,
+    CompactSummaryUpdateContribution,
+    RecoveryBriefContribution,
+    RuntimeStateContribution,
+)
+from .long_term_memory import (
+    recovery_brief_contribution as long_term_memory_recovery_brief_contribution,
+    runtime_state_contribution as long_term_memory_runtime_state_contribution,
+)
+from .project_rules import (
+    recovery_brief_contribution as project_rules_recovery_brief_contribution,
+)
+from .session_memory import (
+    compact_assist_contribution,
+    compact_summary_update_contribution,
+    recovery_brief_contribution,
+    runtime_state_contribution,
+)
+from .runtime_pressure import recovery_brief_contribution as runtime_pressure_recovery_brief_contribution
+from .subagent_activity import recovery_brief_contribution as subagent_activity_recovery_brief_contribution
+
+RUNTIME_STATE_CONTRIBUTIONS: tuple[RuntimeStateContribution, ...] = (
+    long_term_memory_runtime_state_contribution(),
+    runtime_state_contribution(),
+)
+
+RECOVERY_BRIEF_CONTRIBUTIONS: tuple[RecoveryBriefContribution, ...] = (
+    project_rules_recovery_brief_contribution(),
+    long_term_memory_recovery_brief_contribution(),
+    recovery_brief_contribution(),
+    runtime_pressure_recovery_brief_contribution(),
+    subagent_activity_recovery_brief_contribution(),
+)
+
+RESUME_CONTEXT_CONTRIBUTIONS: tuple[RecoveryBriefContribution, ...] = (
+    runtime_pressure_recovery_brief_contribution(),
+)
+
+COMPACT_ASSIST_CONTRIBUTIONS: tuple[CompactAssistContribution, ...] = (
+    compact_assist_contribution(),
+)
+
+COMPACT_SUMMARY_UPDATE_CONTRIBUTIONS: tuple[
+    CompactSummaryUpdateContribution, ...
+] = (
+    compact_summary_update_contribution(),
+)
diff --git a/coding-deepgent/src/coding_deepgent/sessions/contributions.py b/coding-deepgent/src/coding_deepgent/sessions/contributions.py
new file mode 100644
index 000000000..00a0c7951
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/contributions.py
@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from .records import LoadedSession
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeStateContribution:
+    key: str
+    coerce: Callable[[Mapping[str, Any]], object | None]
+
+
+@dataclass(frozen=True, slots=True)
+class RecoveryBriefSection:
+    title: str
+    lines: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class RecoveryBriefContribution:
+    name: str
+    render: Callable[[LoadedSession], RecoveryBriefSection | None]
+
+
+@dataclass(frozen=True, slots=True)
+class CompactAssistContribution:
+    name: str
+    render: Callable[[LoadedSession], str | None]
+
+
+@dataclass(frozen=True, slots=True)
+class CompactSummaryUpdateContribution:
+    name: str
+    update: Callable[[LoadedSession, str], bool]
+
+
+def coerce_runtime_state_contributions(
+    state: Mapping[str, Any],
+    contributions: Sequence[RuntimeStateContribution],
+) -> dict[str, object]:
+    coerced: dict[str, object] = {}
+    for contribution in contributions:
+        value = contribution.coerce(state)
+        if value is not None:
+            coerced[contribution.key] = value
+    return coerced
+
+
+def build_recovery_brief_sections(
+    loaded_session: LoadedSession,
+    contributions: Sequence[RecoveryBriefContribution],
+) -> tuple[RecoveryBriefSection, ...]:
+    sections: list[RecoveryBriefSection] = []
+    for contribution in contributions:
+        section = contribution.render(loaded_session)
+        if section is not None:
+            sections.append(section)
+    return tuple(sections)
+
+
+def compact_assist_text(
+    loaded_session: LoadedSession,
+    contributions: Sequence[CompactAssistContribution],
+) -> str | None:
+    parts: list[str] = []
+    for contribution in contributions:
+        text = contribution.render(loaded_session)
+        if text and text.strip():
+            parts.append(text.strip())
+    return "\n\n".join(parts) if parts else None
+
+
+def apply_compact_summary_update_contributions(
+    loaded_session: LoadedSession,
+    *,
+    summary: str,
+    contributions: Sequence[CompactSummaryUpdateContribution],
+) -> tuple[str, ...]:
+    updated: list[str] = []
+    for contribution in contributions:
+        if contribution.update(loaded_session, summary):
+            updated.append(contribution.name)
+    return tuple(updated)
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..af8e140f1
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/evidence_events.py
@@ -0,0 +1,182 @@
+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",
+        "snip",
+        "microcompact",
+        "context_collapse",
+        "auto_compact",
+        "post_autocompact_turn",
+        "orphan_tombstoned",
+        "query_error",
+        "reactive_compact",
+        "subagent_spawn_guard",
+    }
+)
+
+
+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",
+        "outcome",
+        "phase",
+        "error_class",
+        "strategy",
+        "trigger",
+    ):
+        value = event.metadata.get(key)
+        if isinstance(value, str) and value:
+            metadata[key] = value
+    reason = event.metadata.get("reason")
+    if (
+        event.kind != "hook_blocked"
+        and isinstance(reason, str)
+        and reason
+    ):
+        metadata["reason"] = reason
+    blocked = event.metadata.get("blocked")
+    if isinstance(blocked, bool):
+        metadata["blocked"] = blocked
+    for key in (
+        "hidden_messages",
+        "cleared_tool_results",
+        "tools_cleared",
+        "tools_kept",
+        "tokens_saved_estimate",
+        "keep_recent",
+        "protected_recent_tokens",
+        "gap_minutes",
+        "failure_count",
+        "max_failures",
+        "collapsed_messages",
+        "restored_path_count",
+        "estimated_token_count",
+        "context_window_tokens",
+        "estimated_token_ratio_percent",
+        "drained_summaries",
+        "pre_compact_total",
+        "post_compact_total",
+        "new_turn_input",
+        "new_turn_output",
+        "input_token_estimate",
+        "output_token_estimate",
+        "total_token_estimate",
+        "response_message_count",
+        "message_count",
+        "tombstoned_count",
+        "retry_count",
+    ):
+        value = event.metadata.get(key)
+        if isinstance(value, int) and value >= 0:
+            metadata[key] = value
+    used_session_memory_assist = event.metadata.get("used_session_memory_assist")
+    if isinstance(used_session_memory_assist, bool):
+        metadata["used_session_memory_assist"] = used_session_memory_assist
+    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}."
+    if event.kind == "snip":
+        hidden = metadata.get("hidden_messages", 0)
+        return f"Live snip hid {hidden} older messages from the model call."
+    if event.kind == "microcompact":
+        cleared = metadata.get("cleared_tool_results", 0)
+        return f"Live microcompact cleared {cleared} older tool results."
+    if event.kind == "context_collapse":
+        collapsed = metadata.get("collapsed_messages", 0)
+        return f"Live context collapse summarized {collapsed} older messages."
+    if event.kind == "auto_compact":
+        if metadata.get("outcome") == "attempted":
+            return "Live auto-compact attempt started."
+        if metadata.get("trigger") == "failure_circuit_breaker":
+            return "Live auto-compact skipped after repeated failures."
+        return "Live auto-compact summarized history."
+    if event.kind == "post_autocompact_turn":
+        return "Post-auto-compact turn completed with bounded canary metrics."
+    if event.kind == "orphan_tombstoned":
+        count = metadata.get("tombstoned_count", 0)
+        return f"Projection repair tombstoned {count} orphaned tool blocks."
+    if event.kind == "query_error":
+        phase = metadata.get("phase", "unknown")
+        error_class = metadata.get("error_class", "Exception")
+        return f"Agent query failed during {phase}: {error_class}."
+    if event.kind == "reactive_compact":
+        return "Reactive compact retried after prompt-too-long."
+    if event.kind == "subagent_spawn_guard":
+        return "Subagent spawn blocked by context pressure guard."
+    return event.message
+
+
+def _status(event: RuntimeEvent) -> str:
+    if event.kind == "hook_blocked":
+        return "blocked"
+    if event.kind == "permission_denied":
+        return "denied"
+    if event.kind in {
+        "snip",
+        "microcompact",
+        "context_collapse",
+        "auto_compact",
+        "post_autocompact_turn",
+        "orphan_tombstoned",
+        "reactive_compact",
+        "subagent_spawn_guard",
+    }:
+        if event.kind == "auto_compact" and event.metadata.get("outcome") == "attempted":
+            return "recorded"
+        return "completed"
+    if event.kind == "query_error":
+        return "failed"
+    return "recorded"
+
+
+def _subject(metadata: dict[str, object]) -> str | None:
+    for key in ("tool", "hook_event", "strategy", "phase", "reason"):
+        value = metadata.get(key)
+        if isinstance(value, str) and value:
+            return value
+    return None
diff --git a/coding-deepgent/src/coding_deepgent/sessions/inspection.py b/coding-deepgent/src/coding_deepgent/sessions/inspection.py
new file mode 100644
index 000000000..29bb86f64
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/inspection.py
@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from .compression_view import (
+    CompressionTimelineEvent,
+    ProjectionMessageView,
+    ProjectionMode,
+    RawTranscriptMessageView,
+    build_compression_view,
+)
+from .records import LoadedSession
+from .resume import build_recovery_brief, render_recovery_brief
+from .session_memory import (
+    read_session_memory_artifact,
+    session_memory_metrics,
+    session_memory_status,
+)
+
+SessionMemoryInspectStatus = Literal["missing", "current", "stale"]
+
+
+@dataclass(frozen=True, slots=True)
+class SessionMemoryInspect:
+    status: SessionMemoryInspectStatus
+    source: str | None
+    content: str | None
+    artifact_message_count: int | None
+    current_message_count: int
+    estimated_token_count: int
+    tool_call_count: int
+
+
+@dataclass(frozen=True, slots=True)
+class SessionInspectView:
+    session_id: str
+    workdir: str
+    transcript_path: str
+    created_at: str | None
+    updated_at: str | None
+    message_count: int
+    evidence_count: int
+    compact_count: int
+    collapse_count: int
+    sidechain_count: int
+    recovery_brief: str
+    projection_mode: ProjectionMode
+    raw_messages: tuple[RawTranscriptMessageView, ...]
+    model_projection: tuple[ProjectionMessageView, ...]
+    timeline: tuple[CompressionTimelineEvent, ...]
+    session_memory: SessionMemoryInspect
+
+    @property
+    def visible_raw_count(self) -> int:
+        return sum(1 for message in self.raw_messages if message.model_visible)
+
+    @property
+    def hidden_raw_count(self) -> int:
+        return len(self.raw_messages) - self.visible_raw_count
+
+
+def build_session_inspect_view(
+    loaded: LoadedSession,
+    *,
+    projection_mode: ProjectionMode = "selected",
+) -> SessionInspectView:
+    compression = build_compression_view(loaded, projection_mode=projection_mode)
+    return SessionInspectView(
+        session_id=loaded.summary.session_id,
+        workdir=str(loaded.summary.workdir),
+        transcript_path=str(loaded.summary.transcript_path),
+        created_at=loaded.summary.created_at,
+        updated_at=loaded.summary.updated_at,
+        message_count=loaded.summary.message_count,
+        evidence_count=loaded.summary.evidence_count,
+        compact_count=loaded.summary.compact_count,
+        collapse_count=loaded.summary.collapse_count,
+        sidechain_count=len(loaded.sidechain_messages),
+        recovery_brief=render_recovery_brief(build_recovery_brief(loaded)),
+        projection_mode=compression.projection_mode,
+        raw_messages=compression.raw_messages,
+        model_projection=compression.model_projection,
+        timeline=compression.timeline,
+        session_memory=_session_memory_inspect(loaded),
+    )
+
+
+def _session_memory_inspect(loaded: LoadedSession) -> SessionMemoryInspect:
+    metrics = session_memory_metrics(loaded.history)
+    artifact = read_session_memory_artifact(loaded.state)
+    if artifact is None:
+        return SessionMemoryInspect(
+            status="missing",
+            source=None,
+            content=None,
+            artifact_message_count=None,
+            current_message_count=metrics.message_count,
+            estimated_token_count=metrics.estimated_token_count,
+            tool_call_count=metrics.tool_call_count,
+        )
+    return SessionMemoryInspect(
+        status=session_memory_status(
+            artifact,
+            current_message_count=metrics.message_count,
+            current_token_count=metrics.estimated_token_count,
+            current_tool_call_count=metrics.tool_call_count,
+        ),
+        source=artifact.source,
+        content=artifact.content,
+        artifact_message_count=artifact.message_count,
+        current_message_count=metrics.message_count,
+        estimated_token_count=metrics.estimated_token_count,
+        tool_call_count=metrics.tool_call_count,
+    )
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/long_term_memory.py b/coding-deepgent/src/coding_deepgent/sessions/long_term_memory.py
new file mode 100644
index 000000000..34c791952
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/long_term_memory.py
@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from coding_deepgent.memory.state_snapshot import (
+    LONG_TERM_MEMORY_STATE_KEY,
+    read_long_term_memory_snapshot,
+)
+
+from .contributions import (
+    RecoveryBriefContribution,
+    RecoveryBriefSection,
+    RuntimeStateContribution,
+)
+from .records import LoadedSession
+
+
+def runtime_state_contribution() -> RuntimeStateContribution:
+    return RuntimeStateContribution(
+        key=LONG_TERM_MEMORY_STATE_KEY,
+        coerce=lambda state: (
+            snapshot.model_dump()
+            if (snapshot := read_long_term_memory_snapshot(state)) is not None
+            else None
+        ),
+    )
+
+
+def recovery_brief_contribution() -> RecoveryBriefContribution:
+    def render(loaded_session: LoadedSession) -> RecoveryBriefSection:
+        snapshot = read_long_term_memory_snapshot(loaded_session.state)
+        lines = (
+            ("- none",)
+            if snapshot is None or not snapshot.entries
+            else tuple(
+                f"- [{entry.type}] {entry.summary} (key={entry.key})"
+                for entry in snapshot.entries
+            )
+        )
+        return RecoveryBriefSection(title="Long-term memory:", lines=lines)
+
+    return RecoveryBriefContribution(name=LONG_TERM_MEMORY_STATE_KEY, render=render)
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..4909ea6da
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/ports.py
@@ -0,0 +1,91 @@
+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,
+        metadata: dict[str, Any] | None = None,
+    ) -> Path: ...
+
+    def append_state_snapshot(
+        self,
+        context: SessionContext,
+        *,
+        state: dict[str, Any],
+    ) -> 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: ...
+
+    def append_sidechain_message(
+        self,
+        context: SessionContext,
+        *,
+        agent_type: str,
+        role: str,
+        content: str,
+        subagent_thread_id: str,
+        parent_message_id: str | None = None,
+        parent_thread_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> Path: ...
+
+    def append_compact(
+        self,
+        context: SessionContext,
+        *,
+        trigger: str,
+        summary: str,
+        start_message_id: str,
+        end_message_id: str,
+        covered_message_ids: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> Path: ...
+
+    def append_collapse(
+        self,
+        context: SessionContext,
+        *,
+        trigger: str,
+        summary: str,
+        start_message_id: str,
+        end_message_id: str,
+        covered_message_ids: list[str] | None = None,
+        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/project_rules.py b/coding-deepgent/src/coding_deepgent/sessions/project_rules.py
new file mode 100644
index 000000000..ed0d5edda
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/project_rules.py
@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from coding_deepgent.rules import project_rules_signal
+
+from .contributions import RecoveryBriefContribution, RecoveryBriefSection
+from .records import LoadedSession
+
+
+def recovery_brief_contribution() -> RecoveryBriefContribution:
+    def render(loaded_session: LoadedSession) -> RecoveryBriefSection:
+        return RecoveryBriefSection(
+            title="Project rules:",
+            lines=(project_rules_signal(loaded_session.context.workdir),),
+        )
+
+    return RecoveryBriefContribution(name="project_rules", render=render)
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..b87db43dc
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/records.py
@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Literal
+
+SESSION_RECORD_VERSION = 1
+MESSAGE_RECORD_TYPE = "message"
+TRANSCRIPT_EVENT_RECORD_TYPE = "transcript_event"
+STATE_SNAPSHOT_RECORD_TYPE = "state_snapshot"
+EVIDENCE_RECORD_TYPE = "evidence"
+COMPACT_EVENT_KIND = "compact"
+COLLAPSE_EVENT_KIND = "collapse"
+SUBAGENT_MESSAGE_EVENT_KIND = "subagent_message"
+
+
+def iso_timestamp_now() -> str:
+    return datetime.now(UTC).isoformat().replace("+00:00", "Z")
+
+
+def message_id_for_index(index: int) -> str:
+    if index < 0:
+        raise ValueError("message index must be non-negative")
+    return f"msg-{index:06d}"
+
+
+@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
+    collapse_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 SessionMessage:
+    message_id: str
+    created_at: str
+    role: str
+    content: str
+    metadata: dict[str, Any] | None = None
+
+    def as_conversation_dict(self) -> dict[str, Any]:
+        message: dict[str, Any] = {
+            "role": self.role,
+            "content": self.content,
+        }
+        if self.metadata is not None:
+            message["metadata"] = deepcopy(self.metadata)
+        return message
+
+
+@dataclass(frozen=True, slots=True)
+class SessionSidechainMessage:
+    created_at: str
+    agent_type: str
+    role: str
+    content: str
+    subagent_thread_id: str
+    parent_message_id: str | None = None
+    parent_thread_id: str | None = None
+    metadata: dict[str, Any] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class TranscriptProjection:
+    entries: tuple[tuple[str, ...], ...]
+
+    def covered_message_ids_for_prefix(self, count: int) -> tuple[str, ...]:
+        if count <= 0:
+            return ()
+        covered: list[str] = []
+        for entry in self.entries[:count]:
+            covered.extend(entry)
+        return tuple(covered)
+
+
+@dataclass(frozen=True, slots=True)
+class MessageReference:
+    start_message_id: str
+    end_message_id: str
+    covered_message_ids: tuple[str, ...] | None = None
+
+    def as_payload(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "start_message_id": self.start_message_id,
+            "end_message_id": self.end_message_id,
+        }
+        if self.covered_message_ids:
+            payload["covered_message_ids"] = list(self.covered_message_ids)
+        return payload
+
+
+@dataclass(frozen=True, slots=True)
+class SessionCompact:
+    trigger: str
+    summary: str
+    created_at: str
+    start_message_id: str
+    end_message_id: str
+    covered_message_ids: tuple[str, ...] | None = None
+    metadata: dict[str, Any] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class SessionCollapse:
+    trigger: str
+    summary: str
+    created_at: str
+    start_message_id: str
+    end_message_id: str
+    covered_message_ids: tuple[str, ...] | None = None
+    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 CollapsedHistorySource:
+    mode: Literal["raw", "collapse"]
+    reason: str
+    collapse_index: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class LoadedSession:
+    context: SessionContext
+    history: list[SessionMessage]
+    compacted_history: list[dict[str, Any]]
+    compacted_history_source: CompactedHistorySource
+    collapsed_history: list[dict[str, Any]]
+    collapsed_history_source: CollapsedHistorySource
+    state: dict[str, Any]
+    evidence: list[SessionEvidence]
+    compacts: list[SessionCompact]
+    summary: SessionSummary
+    collapses: list[SessionCollapse] = field(default_factory=list)
+    sidechain_messages: list[SessionSidechainMessage] = field(default_factory=list)
+
+
+class SessionLoadError(RuntimeError):
+    """Raised when a targeted session cannot be resumed from valid transcript records."""
+
+
+def make_message_record(
+    context: SessionContext,
+    *,
+    message_id: str,
+    role: str,
+    content: str,
+    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(),
+        "message_id": message_id,
+        "role": role,
+        "content": content,
+    }
+    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_transcript_event_record(
+    context: SessionContext,
+    *,
+    event_kind: str,
+    payload: dict[str, Any],
+) -> dict[str, Any]:
+    return {
+        "record_type": TRANSCRIPT_EVENT_RECORD_TYPE,
+        "version": SESSION_RECORD_VERSION,
+        "session_id": context.session_id,
+        "timestamp": iso_timestamp_now(),
+        "event_kind": event_kind,
+        "payload": payload,
+    }
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..62cd2221c
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/resume.py
@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+from collections.abc import Callable, MutableMapping, Sequence
+from dataclasses import dataclass
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+
+from .contribution_registry import (
+    RECOVERY_BRIEF_CONTRIBUTIONS,
+    RESUME_CONTEXT_CONTRIBUTIONS,
+)
+from .contributions import (
+    RecoveryBriefContribution,
+    RecoveryBriefSection,
+    build_recovery_brief_sections,
+)
+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, ...]
+    contribution_sections: tuple[RecoveryBriefSection, ...]
+    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,
+    contribution_set: Sequence[RecoveryBriefContribution] = RECOVERY_BRIEF_CONTRIBUTIONS,
+) -> 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,
+        contribution_sections=build_recovery_brief_sections(
+            loaded_session,
+            contribution_set,
+        ),
+        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")
+
+    for section in brief.contribution_sections:
+        lines.append(section.title)
+        lines.extend(section.lines)
+
+    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, contribution_set=RESUME_CONTEXT_CONTRIBUTIONS))}"
+        ),
+    }
+
+
+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/runtime_pressure.py b/coding-deepgent/src/coding_deepgent/sessions/runtime_pressure.py
new file mode 100644
index 000000000..384f1de04
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/runtime_pressure.py
@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from collections import Counter
+
+from .contributions import RecoveryBriefContribution, RecoveryBriefSection
+from .records import LoadedSession
+
+RUNTIME_PRESSURE_EVENT_KINDS = (
+    "snip",
+    "microcompact",
+    "context_collapse",
+    "auto_compact",
+    "reactive_compact",
+)
+
+
+def recovery_brief_contribution() -> RecoveryBriefContribution:
+    def render(loaded_session: LoadedSession) -> RecoveryBriefSection | None:
+        counts = Counter(
+            str(item.metadata.get("event_kind"))
+            for item in loaded_session.evidence
+            if item.kind == "runtime_event"
+            and isinstance(item.metadata, dict)
+            and item.metadata.get("event_kind") in RUNTIME_PRESSURE_EVENT_KINDS
+            and item.metadata.get("outcome") != "attempted"
+        )
+        if not counts:
+            return None
+        lines = tuple(
+            f"- {event_kind}: {counts.get(event_kind, 0)}"
+            for event_kind in RUNTIME_PRESSURE_EVENT_KINDS
+            if counts.get(event_kind, 0) > 0
+        )
+        return RecoveryBriefSection(title="Runtime pressure:", lines=lines or ("- none",))
+
+    return RecoveryBriefContribution(name="runtime_pressure", render=render)
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..081b152be
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/service.py
@@ -0,0 +1,117 @@
+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
+from coding_deepgent.runtime import default_runtime_state
+from coding_deepgent.settings import Settings
+from coding_deepgent.sessions.records import (
+    LoadedSession,
+    SessionSummary,
+    TranscriptProjection,
+)
+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 _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,
+    transcript_projection: TranscriptProjection | 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 []
+
+    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,
+        )
+
+    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
+    if transcript_projection is not None and _supports_keyword_argument(
+        run_agent, "transcript_projection"
+    ):
+        run_agent_kwargs["transcript_projection"] = transcript_projection
+    result = run_agent(transcript, **run_agent_kwargs)
+
+    if context is not None:
+        store.append_message(
+            context,
+            role="assistant",
+            content=result,
+        )
+        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/session_memory.py b/coding-deepgent/src/coding_deepgent/sessions/session_memory.py
new file mode 100644
index 000000000..f5f71e7a8
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/session_memory.py
@@ -0,0 +1,345 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, MutableMapping, Sequence
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from langchain_core.messages import AIMessage, BaseMessage, ToolMessage
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator
+
+from .contributions import (
+    CompactAssistContribution,
+    CompactSummaryUpdateContribution,
+    RecoveryBriefContribution,
+    RecoveryBriefSection,
+    RuntimeStateContribution,
+)
+from .records import LoadedSession, SessionMessage, iso_timestamp_now
+
+SESSION_MEMORY_STATE_KEY = "session_memory"
+DEFAULT_SESSION_MEMORY_UPDATE_MESSAGE_DELTA = 4
+DEFAULT_SESSION_MEMORY_UPDATE_TOKEN_DELTA = 5000
+DEFAULT_SESSION_MEMORY_UPDATE_TOOL_CALL_DELTA = 3
+SessionMemoryStatus = Literal["current", "stale"]
+
+
+@dataclass(frozen=True, slots=True)
+class SessionMemoryMetrics:
+    message_count: int
+    estimated_token_count: int
+    tool_call_count: int
+
+
+class SessionMemoryArtifact(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    content: str = Field(..., min_length=1, max_length=4000)
+    source: str = Field(default="manual", min_length=1, max_length=64)
+    message_count: int = Field(default=0, ge=0)
+    updated_at: str = Field(..., min_length=1)
+    token_count: int | None = Field(default=None, ge=0)
+    tool_call_count: int | None = Field(default=None, ge=0)
+
+    @field_validator("content", "source", "updated_at")
+    @classmethod
+    def _text_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("value required")
+        return value
+
+
+def read_session_memory_artifact(
+    state: Mapping[str, Any],
+) -> SessionMemoryArtifact | None:
+    value = state.get(SESSION_MEMORY_STATE_KEY)
+    if not isinstance(value, dict):
+        return None
+    try:
+        return SessionMemoryArtifact.model_validate(value)
+    except ValidationError:
+        return None
+
+
+def write_session_memory_artifact(
+    state: MutableMapping[str, Any],
+    *,
+    content: str,
+    message_count: int,
+    source: str = "manual",
+    token_count: int | None = None,
+    tool_call_count: int | None = None,
+) -> SessionMemoryArtifact:
+    artifact = SessionMemoryArtifact(
+        content=content,
+        source=source,
+        message_count=message_count,
+        updated_at=iso_timestamp_now(),
+        token_count=token_count,
+        tool_call_count=tool_call_count,
+    )
+    state[SESSION_MEMORY_STATE_KEY] = artifact.model_dump(exclude_none=True)
+    return artifact
+
+
+def session_memory_status(
+    artifact: SessionMemoryArtifact,
+    *,
+    current_message_count: int,
+    current_token_count: int = 0,
+    current_tool_call_count: int = 0,
+    min_message_delta: int = DEFAULT_SESSION_MEMORY_UPDATE_MESSAGE_DELTA,
+    min_token_delta: int = DEFAULT_SESSION_MEMORY_UPDATE_TOKEN_DELTA,
+    min_tool_call_delta: int = DEFAULT_SESSION_MEMORY_UPDATE_TOOL_CALL_DELTA,
+) -> SessionMemoryStatus:
+    if min_message_delta < 1 or min_token_delta < 1 or min_tool_call_delta < 1:
+        raise ValueError("session memory thresholds must be at least 1")
+    if current_message_count - artifact.message_count >= min_message_delta:
+        return "stale"
+    if (
+        artifact.token_count is not None
+        and current_token_count - artifact.token_count >= min_token_delta
+    ):
+        return "stale"
+    if (
+        artifact.tool_call_count is not None
+        and current_tool_call_count - artifact.tool_call_count >= min_tool_call_delta
+    ):
+        return "stale"
+    return "current"
+
+
+def compact_summary_assist_text(
+    artifact: SessionMemoryArtifact | None,
+    *,
+    current_message_count: int,
+    current_token_count: int = 0,
+    current_tool_call_count: int = 0,
+) -> str | None:
+    if artifact is None:
+        return None
+    if artifact.message_count < current_message_count:
+        return None
+    if (
+        session_memory_status(
+            artifact,
+            current_message_count=current_message_count,
+            current_token_count=current_token_count,
+            current_tool_call_count=current_tool_call_count,
+        )
+        != "current"
+    ):
+        return None
+    return (
+        "Session memory artifact:\n"
+        f"{artifact.content}\n\n"
+        "Use it as a bounded continuity aid. If it conflicts with the transcript, "
+        "prefer the transcript."
+    )
+
+
+def render_session_memory_line(
+    artifact: SessionMemoryArtifact,
+    *,
+    current_message_count: int,
+    current_token_count: int = 0,
+    current_tool_call_count: int = 0,
+) -> str:
+    status = session_memory_status(
+        artifact,
+        current_message_count=current_message_count,
+        current_token_count=current_token_count,
+        current_tool_call_count=current_tool_call_count,
+    )
+    return (
+        f"- [{status}] {artifact.content} "
+        f"(source={artifact.source}; messages={artifact.message_count})"
+    )
+
+
+def should_refresh_session_memory(
+    state: Mapping[str, Any],
+    *,
+    current_message_count: int,
+    current_token_count: int = 0,
+    current_tool_call_count: int = 0,
+    min_message_delta: int = DEFAULT_SESSION_MEMORY_UPDATE_MESSAGE_DELTA,
+    min_token_delta: int = DEFAULT_SESSION_MEMORY_UPDATE_TOKEN_DELTA,
+    min_tool_call_delta: int = DEFAULT_SESSION_MEMORY_UPDATE_TOOL_CALL_DELTA,
+) -> bool:
+    artifact = read_session_memory_artifact(state)
+    if artifact is None:
+        return True
+    if min_message_delta < 1 or min_token_delta < 1 or min_tool_call_delta < 1:
+        raise ValueError("session memory thresholds must be at least 1")
+
+    message_delta = current_message_count - artifact.message_count
+    token_delta = current_token_count - (artifact.token_count or 0)
+    tool_call_delta = current_tool_call_count - (artifact.tool_call_count or 0)
+    return (
+        message_delta >= min_message_delta
+        or token_delta >= min_token_delta
+        or tool_call_delta >= min_tool_call_delta
+    )
+
+
+def session_memory_metrics(
+    messages: Sequence[dict[str, Any] | SessionMessage | BaseMessage],
+) -> SessionMemoryMetrics:
+    return SessionMemoryMetrics(
+        message_count=len(messages),
+        estimated_token_count=sum(_estimated_message_tokens(message) for message in messages),
+        tool_call_count=sum(_message_tool_call_count(message) for message in messages),
+    )
+
+
+def _estimated_message_tokens(message: dict[str, Any] | SessionMessage | BaseMessage) -> int:
+    text = _message_text(message)
+    if not text:
+        return 0
+    return max(1, (len(text) + 3) // 4)
+
+
+def _message_text(message: dict[str, Any] | SessionMessage | BaseMessage) -> str:
+    if isinstance(message, AIMessage):
+        parts = [str(message.content or "")]
+        if message.tool_calls:
+            parts.extend(
+                f"{call.get('name', '')} {call.get('args', {})}" for call in message.tool_calls
+            )
+        return "\n".join(part for part in parts if part).strip()
+    if isinstance(message, ToolMessage):
+        return str(message.content or "").strip()
+    if isinstance(message, BaseMessage):
+        return str(getattr(message, "content", "")).strip()
+    if isinstance(message, SessionMessage):
+        content = message.content
+    else:
+        content = message.get("content", "")
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        text_parts: list[str] = []
+        for block in content:
+            if not isinstance(block, dict):
+                continue
+            text = block.get("text")
+            if isinstance(text, str):
+                text_parts.append(text)
+            elif isinstance(block.get("content"), str):
+                text_parts.append(str(block["content"]))
+        return "\n".join(text_parts)
+    return str(content)
+
+
+def _message_tool_call_count(
+    message: dict[str, Any] | SessionMessage | BaseMessage,
+) -> int:
+    if isinstance(message, AIMessage):
+        return len(message.tool_calls)
+    if isinstance(message, ToolMessage):
+        return 0
+    if isinstance(message, BaseMessage):
+        return 0
+    if isinstance(message, SessionMessage):
+        content = message.content
+        tool_calls: Any = None
+    else:
+        content = message.get("content", "")
+        tool_calls = message.get("tool_calls")
+    count = 0
+    if isinstance(content, list):
+        count += sum(
+            1
+            for block in content
+            if isinstance(block, dict) and block.get("type") == "tool_use"
+        )
+    if isinstance(tool_calls, list):
+        count += len(tool_calls)
+    return count
+
+
+def runtime_state_contribution() -> RuntimeStateContribution:
+    return RuntimeStateContribution(
+        key=SESSION_MEMORY_STATE_KEY,
+        coerce=lambda state: (
+            artifact.model_dump(exclude_none=True)
+            if (artifact := read_session_memory_artifact(state)) is not None
+            else None
+        ),
+    )
+
+
+def recovery_brief_contribution() -> RecoveryBriefContribution:
+    def render(loaded_session: LoadedSession) -> RecoveryBriefSection:
+        artifact = read_session_memory_artifact(loaded_session.state)
+        metrics = session_memory_metrics(loaded_session.history)
+        lines = (
+            ("- none",)
+            if artifact is None
+            else (
+                render_session_memory_line(
+                    artifact,
+                    current_message_count=metrics.message_count,
+                    current_token_count=metrics.estimated_token_count,
+                    current_tool_call_count=metrics.tool_call_count,
+                ),
+            )
+        )
+        return RecoveryBriefSection(title="Current-session memory:", lines=lines)
+
+    return RecoveryBriefContribution(name=SESSION_MEMORY_STATE_KEY, render=render)
+
+
+def compact_assist_contribution() -> CompactAssistContribution:
+    def render(loaded_session: LoadedSession) -> str | None:
+        metrics = session_memory_metrics(loaded_session.history)
+        return compact_summary_assist_text(
+            read_session_memory_artifact(loaded_session.state),
+            current_message_count=metrics.message_count,
+            current_token_count=metrics.estimated_token_count,
+            current_tool_call_count=metrics.tool_call_count,
+        )
+
+    return CompactAssistContribution(name=SESSION_MEMORY_STATE_KEY, render=render)
+
+
+def compact_summary_update_contribution() -> CompactSummaryUpdateContribution:
+    def update(loaded_session: LoadedSession, summary: str) -> bool:
+        return update_session_memory_from_summary(
+            loaded_session.state,
+            messages=loaded_session.history,
+            summary=summary,
+            source="generated_compact",
+        )
+
+    return CompactSummaryUpdateContribution(
+        name=SESSION_MEMORY_STATE_KEY,
+        update=update,
+    )
+
+
+def update_session_memory_from_summary(
+    state: MutableMapping[str, Any],
+    *,
+    messages: Sequence[dict[str, Any] | SessionMessage],
+    summary: str,
+    source: str,
+) -> bool:
+    metrics = session_memory_metrics(messages)
+    if not should_refresh_session_memory(
+        state,
+        current_message_count=metrics.message_count,
+        current_token_count=metrics.estimated_token_count,
+        current_tool_call_count=metrics.tool_call_count,
+    ):
+        return False
+    write_session_memory_artifact(
+        state,
+        content=summary,
+        message_count=metrics.message_count,
+        token_count=metrics.estimated_token_count,
+        tool_call_count=metrics.tool_call_count,
+        source=source,
+    )
+    return True
diff --git a/coding-deepgent/src/coding_deepgent/sessions/session_memory_middleware.py b/coding-deepgent/src/coding_deepgent/sessions/session_memory_middleware.py
new file mode 100644
index 000000000..3370e925b
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/session_memory_middleware.py
@@ -0,0 +1,67 @@
+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.sessions.session_memory import (
+    read_session_memory_artifact,
+    session_memory_metrics,
+    session_memory_status,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class SessionMemoryContextMiddleware(AgentMiddleware):
+    def wrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], ModelResponse],
+    ) -> ModelResponse:
+        artifact = read_session_memory_artifact(request.state)
+        if artifact is None:
+            return handler(request)
+        metrics = session_memory_metrics(request.messages)
+
+        payloads = [
+            ContextPayload(
+                kind="memory",
+                source="memory.current_session",
+                priority=210,
+                text=_render_current_session_memory(
+                    artifact.content,
+                    status=session_memory_status(
+                        artifact,
+                        current_message_count=metrics.message_count,
+                        current_token_count=metrics.estimated_token_count,
+                        current_tool_call_count=metrics.tool_call_count,
+                    ),
+                ),
+            )
+        ]
+        current_blocks = (
+            request.system_message.content_blocks if request.system_message else []
+        )
+        return handler(
+            request.override(
+                system_message=SystemMessage(
+                    content=merge_system_message_content(
+                        current_blocks, payloads
+                    )  # type: ignore[list-item]
+                )
+            )
+        )
+
+
+def _render_current_session_memory(content: str, *, status: str) -> str:
+    return (
+        "Current-session memory:\n"
+        f"- [{status}] {content}\n\n"
+        "Treat this as the working summary of the active long conversation."
+    )
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..32a4a31e2
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/store_jsonl.py
@@ -0,0 +1,794 @@
+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.artifacts import (
+    build_collapse_boundary_message,
+    build_collapse_summary_message,
+    build_compact_boundary_message,
+    build_compact_summary_message,
+)
+from coding_deepgent.runtime import default_runtime_state
+
+from .contribution_registry import RUNTIME_STATE_CONTRIBUTIONS
+from .contributions import coerce_runtime_state_contributions
+from .records import (
+    COLLAPSE_EVENT_KIND,
+    CollapsedHistorySource,
+    COMPACT_EVENT_KIND,
+    EVIDENCE_RECORD_TYPE,
+    LoadedSession,
+    MESSAGE_RECORD_TYPE,
+    SUBAGENT_MESSAGE_EVENT_KIND,
+    TRANSCRIPT_EVENT_RECORD_TYPE,
+    SESSION_RECORD_VERSION,
+    STATE_SNAPSHOT_RECORD_TYPE,
+    CompactedHistorySource,
+    MessageReference,
+    SessionContext,
+    SessionCollapse,
+    SessionCompact,
+    SessionEvidence,
+    SessionLoadError,
+    SessionMessage,
+    SessionSidechainMessage,
+    SessionSummary,
+    make_evidence_record,
+    make_message_record,
+    make_state_snapshot_record,
+    make_transcript_event_record,
+    message_id_for_index,
+)
+
+
+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,
+        metadata: dict[str, Any] | None = None,
+    ) -> Path:
+        record = make_message_record(
+            context,
+            message_id=self._next_message_id(context),
+            role=role,
+            content=content,
+            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_sidechain_message(
+        self,
+        context: SessionContext,
+        *,
+        agent_type: str,
+        role: str,
+        content: str,
+        subagent_thread_id: str,
+        parent_message_id: str | None = None,
+        parent_thread_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> Path:
+        payload: dict[str, Any] = {
+            "agent_type": agent_type.strip(),
+            "role": role.strip(),
+            "content": content,
+            "subagent_thread_id": subagent_thread_id.strip(),
+        }
+        if parent_message_id is not None and parent_message_id.strip():
+            payload["parent_message_id"] = parent_message_id.strip()
+        if parent_thread_id is not None and parent_thread_id.strip():
+            payload["parent_thread_id"] = parent_thread_id.strip()
+        if metadata is not None:
+            payload["metadata"] = json.loads(json.dumps(metadata))
+        record = make_transcript_event_record(
+            context,
+            event_kind=SUBAGENT_MESSAGE_EVENT_KIND,
+            payload=payload,
+        )
+        self._append_record(context.transcript_path, record)
+        return context.transcript_path
+
+    def append_compact(
+        self,
+        context: SessionContext,
+        *,
+        trigger: str,
+        summary: str,
+        start_message_id: str,
+        end_message_id: str,
+        covered_message_ids: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> Path:
+        payload = MessageReference(
+            start_message_id=start_message_id,
+            end_message_id=end_message_id,
+            covered_message_ids=tuple(covered_message_ids)
+            if covered_message_ids is not None
+            else None,
+        ).as_payload()
+        payload["trigger"] = trigger.strip()
+        payload["summary"] = summary.strip()
+        if metadata is not None:
+            payload["metadata"] = json.loads(json.dumps(metadata))
+        record = make_transcript_event_record(
+            context,
+            event_kind=COMPACT_EVENT_KIND,
+            payload=payload,
+        )
+        self._append_record(context.transcript_path, record)
+        return context.transcript_path
+
+    def append_collapse(
+        self,
+        context: SessionContext,
+        *,
+        trigger: str,
+        summary: str,
+        start_message_id: str,
+        end_message_id: str,
+        covered_message_ids: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> Path:
+        payload = MessageReference(
+            start_message_id=start_message_id,
+            end_message_id=end_message_id,
+            covered_message_ids=tuple(covered_message_ids)
+            if covered_message_ids is not None
+            else None,
+        ).as_payload()
+        payload["trigger"] = trigger.strip()
+        payload["summary"] = summary.strip()
+        if metadata is not None:
+            payload["metadata"] = json.loads(json.dumps(metadata))
+        record = make_transcript_event_record(
+            context,
+            event_kind=COLLAPSE_EVENT_KIND,
+            payload=payload,
+        )
+        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[SessionMessage] = []
+        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] = []
+        collapses: list[SessionCollapse] = []
+        sidechain_messages: list[SessionSidechainMessage] = []
+
+        for record in self._iter_valid_records(context.transcript_path):
+            if record.get("session_id") != session_id:
+                continue
+            record_cwd = record.get("cwd")
+            if isinstance(record_cwd, str) and record_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:
+                message = self._coerce_message(record)
+                if message is not None:
+                    history.append(message)
+                    if first_prompt is None and message.role == "user":
+                        first_prompt = message.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 == TRANSCRIPT_EVENT_RECORD_TYPE:
+                compact_item = self._coerce_compact(record)
+                if compact_item is not None:
+                    compacts.append(compact_item)
+                    continue
+                collapse_item = self._coerce_collapse(record)
+                if collapse_item is not None:
+                    collapses.append(collapse_item)
+                    continue
+                sidechain_item = self._coerce_sidechain_message(record)
+                if sidechain_item is not None:
+                    sidechain_messages.append(sidechain_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),
+            collapse_count=len(collapses),
+        )
+        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
+        )
+        collapsed_history, collapsed_history_source = self._build_collapsed_history(
+            history,
+            collapses,
+        )
+        return LoadedSession(
+            context=context,
+            history=history,
+            compacted_history=compacted_history,
+            compacted_history_source=compacted_history_source,
+            collapsed_history=collapsed_history,
+            collapsed_history_source=collapsed_history_source,
+            state=state,
+            evidence=evidence,
+            compacts=compacts,
+            summary=summary,
+            collapses=collapses,
+            sidechain_messages=sidechain_messages,
+        )
+
+    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 _next_message_id(self, context: SessionContext) -> str:
+        message_count = sum(
+            1
+            for record in self._iter_valid_records(context.transcript_path)
+            if record.get("session_id") == context.session_id
+            and record.get("record_type") == MESSAGE_RECORD_TYPE
+        )
+        return message_id_for_index(message_count)
+
+    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
+
+        coerced = {
+            "todos": deepcopy(todos),
+            "rounds_since_update": rounds_since_update,
+        }
+        coerced.update(
+            coerce_runtime_state_contributions(state, RUNTIME_STATE_CONTRIBUTIONS)
+        )
+        return coerced
+
+    def _coerce_message(self, record: dict[str, Any]) -> SessionMessage | None:
+        message_id = record.get("message_id")
+        role = record.get("role")
+        content = record.get("content")
+        created_at = record.get("timestamp")
+        metadata = record.get("metadata")
+        if not isinstance(message_id, str) or not message_id.strip():
+            return None
+        if not isinstance(role, str) or not role.strip():
+            return None
+        if not isinstance(content, str):
+            return None
+        if not isinstance(created_at, str) or not created_at.strip():
+            return None
+        if metadata is not None and not isinstance(metadata, dict):
+            return None
+        return SessionMessage(
+            message_id=message_id.strip(),
+            created_at=created_at,
+            role=role.strip(),
+            content=content,
+            metadata=deepcopy(metadata) if isinstance(metadata, dict) else None,
+        )
+
+    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:
+        payload = self._coerce_transcript_reference_payload(
+            record,
+            event_kind=COMPACT_EVENT_KIND,
+        )
+        if payload is None:
+            return None
+        return SessionCompact(
+            trigger=payload["trigger"],
+            summary=payload["summary"],
+            created_at=payload["created_at"],
+            start_message_id=payload["start_message_id"],
+            end_message_id=payload["end_message_id"],
+            covered_message_ids=payload["covered_message_ids"],
+            metadata=payload["metadata"],
+        )
+
+    def _coerce_collapse(self, record: dict[str, Any]) -> SessionCollapse | None:
+        payload = self._coerce_transcript_reference_payload(
+            record,
+            event_kind=COLLAPSE_EVENT_KIND,
+        )
+        if payload is None:
+            return None
+        return SessionCollapse(
+            trigger=payload["trigger"],
+            summary=payload["summary"],
+            created_at=payload["created_at"],
+            start_message_id=payload["start_message_id"],
+            end_message_id=payload["end_message_id"],
+            covered_message_ids=payload["covered_message_ids"],
+            metadata=payload["metadata"],
+        )
+
+    def _coerce_sidechain_message(
+        self,
+        record: dict[str, Any],
+    ) -> SessionSidechainMessage | None:
+        if record.get("event_kind") != SUBAGENT_MESSAGE_EVENT_KIND:
+            return None
+        payload = record.get("payload")
+        created_at = record.get("timestamp")
+        if not isinstance(payload, dict):
+            return None
+        agent_type = payload.get("agent_type")
+        role = payload.get("role")
+        content = payload.get("content")
+        subagent_thread_id = payload.get("subagent_thread_id")
+        parent_message_id = payload.get("parent_message_id")
+        parent_thread_id = payload.get("parent_thread_id")
+        metadata = payload.get("metadata")
+        if not isinstance(created_at, str) or not created_at.strip():
+            return None
+        if not isinstance(agent_type, str) or not agent_type.strip():
+            return None
+        if not isinstance(role, str) or not role.strip():
+            return None
+        if not isinstance(content, str):
+            return None
+        if not isinstance(subagent_thread_id, str) or not subagent_thread_id.strip():
+            return None
+        if parent_message_id is not None and not isinstance(parent_message_id, str):
+            return None
+        if parent_thread_id is not None and not isinstance(parent_thread_id, str):
+            return None
+        if metadata is not None and not isinstance(metadata, dict):
+            return None
+        return SessionSidechainMessage(
+            created_at=created_at,
+            agent_type=agent_type.strip(),
+            role=role.strip(),
+            content=content,
+            subagent_thread_id=subagent_thread_id.strip(),
+            parent_message_id=parent_message_id.strip()
+            if isinstance(parent_message_id, str) and parent_message_id.strip()
+            else None,
+            parent_thread_id=parent_thread_id.strip()
+            if isinstance(parent_thread_id, str) and parent_thread_id.strip()
+            else None,
+            metadata=deepcopy(metadata) if isinstance(metadata, dict) else None,
+        )
+
+    def _coerce_transcript_reference_payload(
+        self,
+        record: dict[str, Any],
+        *,
+        event_kind: str,
+    ) -> dict[str, Any] | None:
+        if record.get("event_kind") != event_kind:
+            return None
+        payload = record.get("payload")
+        created_at = record.get("timestamp")
+        if not isinstance(payload, dict):
+            return None
+        trigger = payload.get("trigger")
+        summary = payload.get("summary")
+        start_message_id = payload.get("start_message_id")
+        end_message_id = payload.get("end_message_id")
+        covered_message_ids = payload.get("covered_message_ids")
+        metadata = payload.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(start_message_id, str) or not start_message_id.strip():
+            return None
+        if not isinstance(end_message_id, str) or not end_message_id.strip():
+            return None
+        if covered_message_ids is not None and (
+            not isinstance(covered_message_ids, list)
+            or not covered_message_ids
+            or any(
+                not isinstance(item, str) or not item.strip()
+                for item in covered_message_ids
+            )
+        ):
+            return None
+        if metadata is not None and not isinstance(metadata, dict):
+            return None
+        return {
+            "trigger": trigger.strip(),
+            "summary": summary.strip(),
+            "created_at": created_at,
+            "start_message_id": start_message_id.strip(),
+            "end_message_id": end_message_id.strip(),
+            "covered_message_ids": tuple(
+                item.strip() for item in covered_message_ids
+            )
+            if isinstance(covered_message_ids, list)
+            else None,
+            "metadata": deepcopy(metadata) if isinstance(metadata, dict) else None,
+        }
+
+    def _build_compacted_history(
+        self,
+        history: list[SessionMessage],
+        compacts: list[SessionCompact],
+    ) -> tuple[list[dict[str, Any]], CompactedHistorySource]:
+        projected_history = [message.as_conversation_dict() for message in history]
+        if not compacts:
+            return projected_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(history, compact)
+            if compacted is not None:
+                return compacted, CompactedHistorySource(
+                    mode="compact",
+                    reason="latest_valid_compact",
+                    compact_index=index,
+                )
+        return projected_history, CompactedHistorySource(
+            mode="raw", reason="no_valid_compact"
+        )
+
+    def _build_history_for_compact(
+        self,
+        raw_history: list[SessionMessage],
+        compact: SessionCompact,
+    ) -> list[dict[str, Any]] | None:
+        id_to_index = {
+            message.message_id: index for index, message in enumerate(raw_history)
+        }
+        start_index = id_to_index.get(compact.start_message_id)
+        end_index = id_to_index.get(compact.end_message_id)
+        if start_index is None or end_index is None or start_index != 0 or end_index < start_index:
+            return None
+        covered_slice = tuple(
+            message.message_id for message in raw_history[start_index : end_index + 1]
+        )
+        if compact.covered_message_ids is not None and compact.covered_message_ids != covered_slice:
+            return None
+        preserved_tail = [
+            message.as_conversation_dict() for message in raw_history[end_index + 1 :]
+        ]
+        return [
+            build_compact_boundary_message(
+                trigger=compact.trigger,
+                original_message_count=len(raw_history),
+                summarized_message_count=end_index + 1,
+                kept_message_count=len(preserved_tail),
+                start_message_id=compact.start_message_id,
+                end_message_id=compact.end_message_id,
+                covered_message_ids=list(compact.covered_message_ids)
+                if compact.covered_message_ids is not None
+                else None,
+                metadata=deepcopy(compact.metadata) if compact.metadata is not None else None,
+            ),
+            build_compact_summary_message(compact.summary),
+            *preserved_tail,
+        ]
+
+    def _build_collapsed_history(
+        self,
+        history: list[SessionMessage],
+        collapses: list[SessionCollapse],
+    ) -> tuple[list[dict[str, Any]], CollapsedHistorySource]:
+        projected_history = [message.as_conversation_dict() for message in history]
+        if not collapses:
+            return projected_history, CollapsedHistorySource(
+                mode="raw",
+                reason="no_collapses",
+            )
+
+        selected: list[tuple[int, int, int, SessionCollapse]] = []
+        covered_indexes: set[int] = set()
+        id_to_index = {
+            message.message_id: index for index, message in enumerate(history)
+        }
+        for collapse_index in range(len(collapses) - 1, -1, -1):
+            collapse = collapses[collapse_index]
+            span = self._collapse_span(history, id_to_index, collapse)
+            if span is None:
+                continue
+            start_index, end_index = span
+            span_indexes = set(range(start_index, end_index + 1))
+            if covered_indexes & span_indexes:
+                continue
+            covered_indexes.update(span_indexes)
+            selected.append((start_index, end_index, collapse_index, collapse))
+
+        if not selected:
+            return projected_history, CollapsedHistorySource(
+                mode="raw",
+                reason="no_valid_collapse",
+            )
+
+        selected.sort(key=lambda item: item[0])
+        collapsed: list[dict[str, Any]] = []
+        cursor = 0
+        for start_index, end_index, _collapse_index, collapse in selected:
+            collapsed.extend(
+                message.as_conversation_dict() for message in history[cursor:start_index]
+            )
+            collapsed.extend(
+                self._collapse_projection_messages(
+                    history=history,
+                    collapse=collapse,
+                    start_index=start_index,
+                    end_index=end_index,
+                )
+            )
+            cursor = end_index + 1
+        collapsed.extend(message.as_conversation_dict() for message in history[cursor:])
+        latest_index = max(item[2] for item in selected)
+        return collapsed, CollapsedHistorySource(
+            mode="collapse",
+            reason="valid_collapses",
+            collapse_index=latest_index,
+        )
+
+    def _collapse_span(
+        self,
+        history: list[SessionMessage],
+        id_to_index: dict[str, int],
+        collapse: SessionCollapse,
+    ) -> tuple[int, int] | None:
+        start_index = id_to_index.get(collapse.start_message_id)
+        end_index = id_to_index.get(collapse.end_message_id)
+        if start_index is None or end_index is None or end_index < start_index:
+            return None
+        covered_slice = tuple(
+            message.message_id for message in history[start_index : end_index + 1]
+        )
+        if (
+            collapse.covered_message_ids is not None
+            and collapse.covered_message_ids != covered_slice
+        ):
+            return None
+        return start_index, end_index
+
+    def _collapse_projection_messages(
+        self,
+        *,
+        history: list[SessionMessage],
+        collapse: SessionCollapse,
+        start_index: int,
+        end_index: int,
+    ) -> list[dict[str, Any]]:
+        kept_message_count = len(history) - (end_index - start_index + 1)
+        covered_message_ids = [
+            message.message_id for message in history[start_index : end_index + 1]
+        ]
+        return [
+            build_collapse_boundary_message(
+                trigger=collapse.trigger,
+                original_message_count=len(history),
+                collapsed_message_count=len(covered_message_ids),
+                kept_message_count=kept_message_count,
+                start_message_id=collapse.start_message_id,
+                end_message_id=collapse.end_message_id,
+                covered_message_ids=covered_message_ids,
+                metadata=(
+                    deepcopy(collapse.metadata)
+                    if collapse.metadata is not None
+                    else None
+                ),
+            ),
+            build_collapse_summary_message(collapse.summary),
+        ]
+
+    def latest_message_id(self, context: SessionContext) -> str | None:
+        latest: str | None = None
+        for record in self._iter_valid_records(context.transcript_path):
+            if (
+                record.get("session_id") == context.session_id
+                and record.get("record_type") == MESSAGE_RECORD_TYPE
+                and isinstance(record.get("message_id"), str)
+            ):
+                latest = str(record["message_id"])
+        return latest
diff --git a/coding-deepgent/src/coding_deepgent/sessions/subagent_activity.py b/coding-deepgent/src/coding_deepgent/sessions/subagent_activity.py
new file mode 100644
index 000000000..59322496d
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/sessions/subagent_activity.py
@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from .contributions import RecoveryBriefContribution, RecoveryBriefSection
+from .records import LoadedSession
+
+
+def recovery_brief_contribution() -> RecoveryBriefContribution:
+    def render(loaded_session: LoadedSession) -> RecoveryBriefSection | None:
+        notifications = [
+            item
+            for item in loaded_session.evidence
+            if item.kind == "subagent_notification"
+        ][-3:]
+        if not notifications:
+            return None
+        return RecoveryBriefSection(
+            title="Subagent activity:",
+            lines=tuple(
+                f"- [{item.status}] {item.summary}" for item in notifications
+            ),
+        )
+
+    return RecoveryBriefContribution(name="subagent_activity", render=render)
diff --git a/coding-deepgent/src/coding_deepgent/settings.py b/coding-deepgent/src/coding_deepgent/settings.py
new file mode 100644
index 000000000..9f5f9ae99
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/settings.py
@@ -0,0 +1,178 @@
+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", "file"]
+OffloadBackend = Literal["none", "s3"]
+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"))
+    store_path: Path = Field(default=Path(".coding-deepgent/store.json"))
+    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 = "file"
+    postgres_url: str | None = Field(default=None, alias="POSTGRES_URL")
+    redis_url: str | None = Field(default=None, alias="REDIS_URL")
+    offload_backend: OffloadBackend = Field(default="none", alias="OFFLOAD_BACKEND")
+    s3_bucket: str | None = Field(default=None, alias="S3_BUCKET")
+    s3_endpoint_url: str | None = Field(default=None, alias="S3_ENDPOINT_URL")
+    s3_region: str | None = Field(default=None, alias="S3_REGION")
+    s3_access_key_id: str | None = Field(default=None, alias="S3_ACCESS_KEY_ID")
+    s3_secret_access_key: SecretStr | None = Field(
+        default=None, alias="S3_SECRET_ACCESS_KEY"
+    )
+    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)
+    auto_compact_threshold_tokens: int | None = Field(default=8000, ge=1)
+    auto_compact_max_failures: int | None = Field(default=None, ge=1)
+    auto_compact_ptl_retry_limit: int = Field(default=0, ge=0)
+    snip_threshold_tokens: int | None = Field(default=None, ge=1)
+    collapse_threshold_tokens: int | None = Field(default=12000, ge=1)
+    model_context_window_tokens: int | None = Field(default=None, ge=1)
+    collapse_trigger_ratio: float | None = Field(default=None, ge=0.0, le=1.0)
+    subagent_spawn_guard_ratio: float | None = Field(default=None, ge=0.0, le=1.0)
+    keep_recent_tool_results: int = Field(default=3, ge=0)
+    microcompact_time_gap_minutes: int | None = Field(default=None, ge=1)
+    microcompact_min_saved_tokens: int = Field(default=0, ge=0)
+    microcompact_protect_recent_tokens: int | None = Field(default=None, ge=1)
+    microcompact_min_prune_saved_tokens: int = Field(default=0, ge=0)
+    keep_recent_messages_after_snip: int = Field(default=12, ge=0)
+    keep_recent_messages_after_collapse: int = Field(default=8, ge=0)
+    keep_recent_messages_after_compact: int = Field(default=4, ge=0)
+
+    @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.store_path.is_absolute():
+            self.store_path = (self.workdir / self.store_path).resolve()
+        else:
+            self.store_path = self.store_path.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,
+    model_name: str | 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": (model_name or active_settings.model_name).strip(),
+        "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..3ff148ec5
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/subagents/__init__.py
@@ -0,0 +1,110 @@
+from .schemas import (
+    AgentDefinition,
+    BackgroundSubagentRun,
+    BackgroundSubagentListInput,
+    BackgroundRuntimeSnapshot,
+    BackgroundSubagentSendInput,
+    BackgroundSubagentStatusInput,
+    BackgroundSubagentStopInput,
+    BuiltinSubagentType,
+    ForkPlaceholderLayout,
+    ForkResultEnvelope,
+    RunBackgroundSubagentInput,
+    ResumeForkInput,
+    ResumeSubagentInput,
+    RunForkInput,
+    RunSubagentInput,
+    SubagentResultEnvelope,
+    SubagentType,
+    ToolPoolIdentitySnapshot,
+    ToolSurfaceSnapshot,
+    VerifierSubagentResult,
+)
+from .background import (
+    run_subagent_background,
+    subagent_list,
+    subagent_send_input,
+    subagent_stop,
+    subagent_status,
+)
+from .definitions import (
+    BUILTIN_AGENT_DEFINITIONS,
+    DEFAULT_CHILD_TOOLS,
+    EXPLORE_CHILD_TOOLS,
+    FILE_ONLY_CHILD_TOOLS,
+    FORBIDDEN_CHILD_TOOLS,
+    PLAN_CHILD_TOOLS,
+    VERIFIER_EXTRA_TOOLS,
+    agent_definition,
+    child_capability_registry,
+    child_tool_allowlist,
+    resolve_agent_definition,
+)
+from .results import ForkResult, SubagentResult
+from .forking import (
+    FORK_PLACEHOLDER_LAYOUT_VERSION,
+    FORK_RECURSION_GUARD_MARKER,
+    FORK_MAX_TURNS,
+)
+from .tools import (
+    resume_fork,
+    resume_fork_task,
+    resume_subagent,
+    resume_subagent_task,
+    run_fork,
+    run_fork_task,
+    run_subagent,
+    run_subagent_task,
+)
+
+__all__ = [
+    "AgentDefinition",
+    "BackgroundSubagentRun",
+    "BackgroundSubagentListInput",
+    "BackgroundRuntimeSnapshot",
+    "BackgroundSubagentSendInput",
+    "BackgroundSubagentStatusInput",
+    "BackgroundSubagentStopInput",
+    "BuiltinSubagentType",
+    "BUILTIN_AGENT_DEFINITIONS",
+    "DEFAULT_CHILD_TOOLS",
+    "EXPLORE_CHILD_TOOLS",
+    "FILE_ONLY_CHILD_TOOLS",
+    "FORK_PLACEHOLDER_LAYOUT_VERSION",
+    "FORK_RECURSION_GUARD_MARKER",
+    "ForkPlaceholderLayout",
+    "ForkResult",
+    "ForkResultEnvelope",
+    "FORK_MAX_TURNS",
+    "FORBIDDEN_CHILD_TOOLS",
+    "PLAN_CHILD_TOOLS",
+    "RunBackgroundSubagentInput",
+    "ResumeForkInput",
+    "ResumeSubagentInput",
+    "RunForkInput",
+    "RunSubagentInput",
+    "SubagentResult",
+    "SubagentResultEnvelope",
+    "SubagentType",
+    "ToolPoolIdentitySnapshot",
+    "ToolSurfaceSnapshot",
+    "VerifierSubagentResult",
+    "VERIFIER_EXTRA_TOOLS",
+    "agent_definition",
+    "child_capability_registry",
+    "child_tool_allowlist",
+    "resolve_agent_definition",
+    "resume_fork",
+    "resume_fork_task",
+    "resume_subagent",
+    "resume_subagent_task",
+    "run_subagent_background",
+    "run_fork",
+    "run_fork_task",
+    "run_subagent",
+    "run_subagent_task",
+    "subagent_list",
+    "subagent_send_input",
+    "subagent_stop",
+    "subagent_status",
+]
diff --git a/coding-deepgent/src/coding_deepgent/subagents/background.py b/coding-deepgent/src/coding_deepgent/subagents/background.py
new file mode 100644
index 000000000..aaecd9da1
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/subagents/background.py
@@ -0,0 +1,654 @@
+from __future__ import annotations
+
+import json
+import threading
+import uuid
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Protocol
+
+from langchain.tools import ToolRuntime, tool
+
+from coding_deepgent.sessions.records import SessionContext
+from coding_deepgent.sessions.store_jsonl import JsonlSessionStore
+from coding_deepgent.subagents.schemas import (
+    BackgroundSubagentListInput,
+    BackgroundSubagentRun,
+    BackgroundRuntimeSnapshot,
+    BackgroundSubagentSendInput,
+    BackgroundSubagentStatusInput,
+    BackgroundSubagentStopInput,
+    RunBackgroundSubagentInput,
+)
+from coding_deepgent.subagents.forking import fingerprint_text, tool_surface_snapshot
+from coding_deepgent.subagents.tools import (
+    resume_fork_task,
+    resume_subagent_task,
+    resolve_agent_definition,
+    run_fork_task,
+    run_subagent_task,
+)
+
+BACKGROUND_SUBAGENT_NAMESPACE = ("coding_deepgent_subagent_background_runs",)
+TERMINAL_BACKGROUND_STATUSES = {"completed", "failed", "cancelled"}
+
+
+class BackgroundRunStore(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]: ...
+
+
+@dataclass(frozen=True, slots=True)
+class BackgroundWorkerHandle:
+    thread: threading.Thread
+    snapshot: BackgroundRuntimeSnapshot
+
+
+def _store(runtime: ToolRuntime) -> BackgroundRunStore:
+    if runtime.store is None:
+        raise RuntimeError("Background subagent runtime requires task/store support")
+    return runtime.store
+
+
+def _item_value(item: object) -> dict[str, object]:
+    value = getattr(item, "value", item)
+    return value if isinstance(value, dict) else {}
+
+
+def save_background_run(
+    store: BackgroundRunStore,
+    record: BackgroundSubagentRun,
+) -> BackgroundSubagentRun:
+    store.put(BACKGROUND_SUBAGENT_NAMESPACE, record.run_id, record.model_dump())
+    return record
+
+
+def get_background_run(store: BackgroundRunStore, run_id: str) -> BackgroundSubagentRun:
+    item = store.get(BACKGROUND_SUBAGENT_NAMESPACE, run_id)
+    if item is None:
+        raise KeyError(f"Unknown background subagent run: {run_id}")
+    return BackgroundSubagentRun.model_validate(_item_value(item))
+
+
+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_workdir(runtime: ToolRuntime) -> str:
+    context = getattr(runtime, "context", None)
+    workdir = getattr(context, "workdir", None)
+    return str(workdir) if workdir is not None else ""
+
+
+def _runtime_snapshot(
+    runtime: ToolRuntime,
+    *,
+    parent_thread_id: str,
+) -> BackgroundRuntimeSnapshot:
+    context = getattr(runtime, "context", None)
+    session_id = str(getattr(context, "session_id", parent_thread_id) or parent_thread_id)
+    entrypoint = str(getattr(context, "entrypoint", "unknown") or "unknown")
+    agent_name = str(getattr(context, "agent_name", "coding-deepgent") or "coding-deepgent")
+    rendered_prompt = getattr(context, "rendered_system_prompt", None)
+    rendered_prompt_fingerprint = (
+        fingerprint_text(rendered_prompt)
+        if isinstance(rendered_prompt, str) and rendered_prompt.strip()
+        else None
+    )
+    projection = getattr(context, "visible_tool_projection", None)
+    tool_pool_fingerprint: str | None = None
+    if projection is not None:
+        try:
+            tool_pool_fingerprint = tool_surface_snapshot(projection).fingerprint
+        except Exception:
+            tool_pool_fingerprint = None
+    return BackgroundRuntimeSnapshot(
+        session_id=session_id,
+        parent_thread_id=parent_thread_id,
+        workdir=_runtime_workdir(runtime),
+        entrypoint=entrypoint,
+        agent_name=agent_name,
+        has_session_context=isinstance(getattr(context, "session_context", None), SessionContext),
+        rendered_prompt_fingerprint=rendered_prompt_fingerprint,
+        tool_pool_fingerprint=tool_pool_fingerprint,
+    )
+
+
+def _append_notification(
+    runtime: ToolRuntime,
+    record: BackgroundSubagentRun,
+) -> None:
+    context = getattr(runtime, "context", None)
+    session_context = getattr(context, "session_context", None)
+    if not isinstance(session_context, SessionContext):
+        return
+    status = (
+        "completed"
+        if record.status == "completed"
+        else "cancelled"
+        if record.status == "cancelled"
+        else "failed"
+    )
+    summary = (
+        f"{record.title} completed."
+        if record.status == "completed"
+        else f"{record.title} cancelled."
+        if record.status == "cancelled"
+        else f"{record.title} failed."
+    )
+    JsonlSessionStore(session_context.store_dir).append_evidence(
+        session_context,
+        kind="subagent_notification",
+        summary=summary,
+        status=status,
+        subject=record.run_id,
+        metadata={
+            "run_id": record.run_id,
+            "mode": record.mode,
+            "agent_type": record.agent_type,
+            "child_thread_id": record.child_thread_id,
+            "status": record.status,
+            "pending_inputs": len(record.pending_inputs),
+            "total_invocations": record.total_invocations,
+            "runtime_snapshot": record.runtime_snapshot.model_dump()
+            if record.runtime_snapshot is not None
+            else None,
+        },
+    )
+
+
+def _clip_activity(text: str, *, limit: int = 96) -> str:
+    stripped = text.strip()
+    if len(stripped) <= limit:
+        return stripped
+    return f"{stripped[: limit - 3].rstrip()}..."
+
+
+def _recent_activities(*items: str) -> list[str]:
+    activities = [_clip_activity(item) for item in items if item.strip()]
+    return activities[-5:]
+
+
+def _result_summary(content: str) -> str:
+    for line in content.splitlines():
+        stripped = line.strip()
+        if stripped:
+            return _clip_activity(stripped, limit=72)
+    return "No summary yet."
+
+
+def _background_title(*, mode: str, agent_type: str) -> str:
+    if mode == "background_fork":
+        return "Background fork"
+    return f"Background subagent: {agent_type}"
+
+
+def _terminal_progress(record: BackgroundSubagentRun) -> str:
+    if record.status == "completed":
+        return f"{record.title} completed."
+    if record.status == "cancelled":
+        return f"{record.title} cancelled."
+    return f"{record.title} failed."
+
+
+class BackgroundSubagentManager:
+    def __init__(self) -> None:
+        self._lock = threading.RLock()
+        self._workers: dict[str, BackgroundWorkerHandle] = {}
+
+    def is_active(self, run_id: str) -> bool:
+        worker = self._workers.get(run_id)
+        return worker is not None and worker.thread.is_alive()
+
+    def start_subagent(
+        self,
+        *,
+        task: str,
+        runtime: ToolRuntime,
+        agent_type: str,
+        plan_id: str | None,
+        max_turns: int | None,
+    ) -> BackgroundSubagentRun:
+        definition = resolve_agent_definition(agent_type, runtime=runtime)
+        run_id = f"bgrun-{uuid.uuid4().hex[:12]}"
+        parent_thread_id = _runtime_thread_id(runtime)
+        child_thread_id = f"{parent_thread_id}:{agent_type}:{run_id}"
+        runtime_snapshot = _runtime_snapshot(runtime, parent_thread_id=parent_thread_id)
+        record = BackgroundSubagentRun(
+            run_id=run_id,
+            mode="background_subagent",
+            agent_type=agent_type,
+            status="queued",
+            title=_background_title(mode="background_subagent", agent_type=agent_type),
+            parent_thread_id=parent_thread_id,
+            child_thread_id=child_thread_id,
+            workdir=_runtime_workdir(runtime),
+            requested_max_turns=max_turns,
+            effective_max_turns=min(max_turns or definition.max_turns, definition.max_turns),
+            model_profile=definition.model_profile,
+            plan_id=plan_id,
+            runtime_snapshot=runtime_snapshot,
+            pending_inputs=[task],
+            progress_summary="Queued background subagent run.",
+            summary_text="Queued background subagent run.",
+            recent_activities=_recent_activities(f"Queued: {task}"),
+        )
+        return self._start_record(record=record, runtime=runtime)
+
+    def start_fork(
+        self,
+        *,
+        intent: str,
+        runtime: ToolRuntime,
+        max_turns: int | None,
+    ) -> BackgroundSubagentRun:
+        run_id = f"bgfork-{uuid.uuid4().hex[:12]}"
+        parent_thread_id = _runtime_thread_id(runtime)
+        child_thread_id = f"{parent_thread_id}:fork:{run_id}"
+        effective_max_turns = 25 if max_turns is None else min(max_turns, 25)
+        runtime_snapshot = _runtime_snapshot(runtime, parent_thread_id=parent_thread_id)
+        record = BackgroundSubagentRun(
+            run_id=run_id,
+            mode="background_fork",
+            agent_type="fork",
+            status="queued",
+            title=_background_title(mode="background_fork", agent_type="fork"),
+            parent_thread_id=parent_thread_id,
+            child_thread_id=child_thread_id,
+            workdir=_runtime_workdir(runtime),
+            requested_max_turns=max_turns,
+            effective_max_turns=effective_max_turns,
+            runtime_snapshot=runtime_snapshot,
+            pending_inputs=[intent],
+            progress_summary="Queued background fork run.",
+            summary_text="Queued background fork run.",
+            recent_activities=_recent_activities(f"Queued: {intent}"),
+        )
+        return self._start_record(record=record, runtime=runtime)
+
+    def status(self, *, run_id: str, runtime: ToolRuntime) -> BackgroundSubagentRun:
+        with self._lock:
+            return get_background_run(_store(runtime), run_id)
+
+    def list_runs(
+        self, *, runtime: ToolRuntime, include_terminal: bool = False
+    ) -> tuple[BackgroundSubagentRun, ...]:
+        with self._lock:
+            records = [
+                BackgroundSubagentRun.model_validate(_item_value(item))
+                for item in _store(runtime).search(BACKGROUND_SUBAGENT_NAMESPACE)
+            ]
+        if not include_terminal:
+            records = [
+                record
+                for record in records
+                if record.status not in TERMINAL_BACKGROUND_STATUSES
+            ]
+        return tuple(sorted(records, key=lambda record: record.run_id))
+
+    def send_input(
+        self,
+        *,
+        run_id: str,
+        message: str,
+        runtime: ToolRuntime,
+    ) -> BackgroundSubagentRun:
+        with self._lock:
+            record = get_background_run(_store(runtime), run_id)
+            if record.status in {"failed", "cancelled"}:
+                raise RuntimeError("Cannot send input to a failed or cancelled background run")
+            updated = record.model_copy(
+                update={
+                    "pending_inputs": [*record.pending_inputs, message],
+                    "status": "running" if self.is_active(run_id) else "queued",
+                    "stop_requested": False,
+                    "progress_summary": (
+                        f"{record.title} is processing queued follow-up input."
+                        if self.is_active(run_id)
+                        else f"Queued follow-up input for {record.title.lower()}."
+                    ),
+                    "recent_activities": _recent_activities(
+                        *record.recent_activities,
+                        f"Queued follow-up: {message}",
+                    ),
+                    "notified": False,
+                    "error": None,
+                }
+            )
+            save_background_run(_store(runtime), updated)
+            if not self.is_active(run_id):
+                self._spawn_worker(run_id=run_id, runtime=runtime)
+            return get_background_run(_store(runtime), run_id)
+
+    def stop(
+        self,
+        *,
+        run_id: str,
+        runtime: ToolRuntime,
+    ) -> BackgroundSubagentRun:
+        with self._lock:
+            record = get_background_run(_store(runtime), run_id)
+            if record.status in TERMINAL_BACKGROUND_STATUSES:
+                return record
+            updated = record.model_copy(
+                update={
+                    "stop_requested": True,
+                    "progress_summary": f"Stop requested for {record.title.lower()}.",
+                    "recent_activities": _recent_activities(
+                        *record.recent_activities,
+                        "Stop requested",
+                    ),
+                }
+            )
+            if not self.is_active(run_id):
+                updated = updated.model_copy(
+                    update={
+                        "status": "cancelled",
+                        "pending_inputs": [],
+                        "progress_summary": _terminal_progress(
+                            updated.model_copy(update={"status": "cancelled"})
+                        ),
+                    }
+                )
+                if not updated.notified:
+                    _append_notification(runtime, updated)
+                    updated = updated.model_copy(update={"notified": True})
+            save_background_run(_store(runtime), updated)
+            return get_background_run(_store(runtime), run_id)
+
+    def _start_record(
+        self,
+        *,
+        record: BackgroundSubagentRun,
+        runtime: ToolRuntime,
+    ) -> BackgroundSubagentRun:
+        with self._lock:
+            save_background_run(_store(runtime), record)
+            self._spawn_worker(run_id=record.run_id, runtime=runtime)
+            return get_background_run(_store(runtime), record.run_id)
+
+    def _spawn_worker(self, *, run_id: str, runtime: ToolRuntime) -> None:
+        worker = self._workers.get(run_id)
+        if worker is not None and worker.thread.is_alive():
+            return
+        record = get_background_run(_store(runtime), run_id)
+        snapshot = record.runtime_snapshot or _runtime_snapshot(
+            runtime,
+            parent_thread_id=record.parent_thread_id,
+        )
+        thread = threading.Thread(
+            target=self._worker,
+            kwargs={"run_id": run_id, "runtime": runtime, "snapshot": snapshot},
+            daemon=True,
+            name=f"coding-deepgent-background-agent-{run_id}",
+        )
+        self._workers[run_id] = BackgroundWorkerHandle(thread=thread, snapshot=snapshot)
+        thread.start()
+
+    def _worker(
+        self,
+        *,
+        run_id: str,
+        runtime: ToolRuntime,
+        snapshot: BackgroundRuntimeSnapshot,
+    ) -> None:
+        del snapshot  # durable facts live on the run record; live runtime drives current invoke.
+        try:
+            while True:
+                with self._lock:
+                    record = get_background_run(_store(runtime), run_id)
+                    if record.stop_requested:
+                        cancelled = record.model_copy(
+                            update={
+                                "status": "cancelled",
+                                "pending_inputs": [],
+                                "progress_summary": _terminal_progress(
+                                    record.model_copy(update={"status": "cancelled"})
+                                ),
+                                "summary_text": _result_summary(record.latest_result or "Cancelled."),
+                            }
+                        )
+                        if not cancelled.notified:
+                            _append_notification(runtime, cancelled)
+                            cancelled = cancelled.model_copy(update={"notified": True})
+                        save_background_run(_store(runtime), cancelled)
+                        return
+                    if not record.pending_inputs:
+                        terminal = (
+                            record
+                            if record.status in TERMINAL_BACKGROUND_STATUSES
+                            else record.model_copy(
+                                update={
+                                    "status": "completed",
+                                    "progress_summary": _terminal_progress(
+                                        record.model_copy(update={"status": "completed"})
+                                    ),
+                                }
+                            )
+                        )
+                        if terminal.status in TERMINAL_BACKGROUND_STATUSES and not terminal.notified:
+                            _append_notification(runtime, terminal)
+                            terminal = terminal.model_copy(update={"notified": True})
+                        save_background_run(_store(runtime), terminal)
+                        return
+
+                    current_input = record.pending_inputs[0]
+                    updated = record.model_copy(
+                        update={
+                            "pending_inputs": record.pending_inputs[1:],
+                            "status": "running",
+                            "progress_summary": f"{record.title} is running.",
+                            "recent_activities": _recent_activities(
+                                *record.recent_activities,
+                                f"Started: {current_input}",
+                            ),
+                        }
+                    )
+                    save_background_run(_store(runtime), updated)
+
+                try:
+                    result: object
+                    if updated.mode == "background_fork":
+                        if updated.total_invocations == 0:
+                            result = run_fork_task(
+                                intent=current_input,
+                                runtime=runtime,
+                                max_turns=updated.requested_max_turns,
+                                run_id=updated.run_id,
+                            )
+                        else:
+                            result = resume_fork_task(
+                                child_thread_id=updated.child_thread_id,
+                                runtime=runtime,
+                                follow_up=current_input,
+                            )
+                    elif updated.total_invocations == 0:
+                        result = run_subagent_task(
+                            task=current_input,
+                            runtime=runtime,
+                            agent_type=updated.agent_type,
+                            plan_id=updated.plan_id,
+                            max_turns=updated.requested_max_turns,
+                            run_id=updated.run_id,
+                        )
+                    else:
+                        result = resume_subagent_task(
+                            subagent_thread_id=updated.child_thread_id,
+                            runtime=runtime,
+                            follow_up=current_input,
+                        )
+                except Exception as exc:
+                    with self._lock:
+                        failed = get_background_run(_store(runtime), run_id).model_copy(
+                            update={
+                                "status": "failed",
+                                "error": str(exc),
+                                "progress_summary": _terminal_progress(
+                                    updated.model_copy(update={"status": "failed"})
+                                ),
+                                "summary_text": _result_summary(str(exc)),
+                                "recent_activities": _recent_activities(
+                                    *updated.recent_activities,
+                                    f"Failed: {exc}",
+                                ),
+                            }
+                        )
+                        if not failed.notified:
+                            _append_notification(runtime, failed)
+                            failed = failed.model_copy(update={"notified": True})
+                        save_background_run(_store(runtime), failed)
+                    return
+
+                with self._lock:
+                    latest = get_background_run(_store(runtime), run_id)
+                    if latest.stop_requested:
+                        next_status = "cancelled"
+                        next_summary = _terminal_progress(
+                            latest.model_copy(update={"status": "cancelled"})
+                        )
+                    else:
+                        next_status = "running" if latest.pending_inputs else "completed"
+                        next_summary = (
+                            f"{latest.title} has queued follow-up input."
+                            if latest.pending_inputs
+                            else _terminal_progress(
+                                latest.model_copy(update={"status": "completed"})
+                            )
+                        )
+                    updated_record = latest.model_copy(
+                        update={
+                            "status": next_status,
+                            "child_thread_id": getattr(
+                                result,
+                                "child_thread_id",
+                                latest.child_thread_id,
+                            ),
+                            "latest_result": str(getattr(result, "content", "")),
+                            "summary_text": _result_summary(
+                                str(getattr(result, "content", ""))
+                            ),
+                            "rendered_prompt_fingerprint": getattr(
+                                result,
+                                "rendered_prompt_fingerprint",
+                                latest.rendered_prompt_fingerprint,
+                            ),
+                            "tool_pool_fingerprint": getattr(
+                                getattr(result, "tool_pool_identity", None),
+                                "fingerprint",
+                                latest.tool_pool_fingerprint,
+                            ),
+                            "placeholder_layout_version": getattr(
+                                getattr(result, "placeholder_layout", None),
+                                "version",
+                                latest.placeholder_layout_version,
+                            ),
+                            "error": None,
+                            "progress_summary": next_summary,
+                            "recent_activities": _recent_activities(
+                                *latest.recent_activities,
+                                f"Completed: {getattr(result, 'content', '')}",
+                            ),
+                            "input_tokens": latest.input_tokens
+                            + int(getattr(result, "input_tokens", 0)),
+                            "output_tokens": latest.output_tokens
+                            + int(getattr(result, "output_tokens", 0)),
+                            "total_tokens": latest.total_tokens
+                            + int(getattr(result, "total_tokens", 0)),
+                            "total_duration_ms": latest.total_duration_ms
+                            + int(getattr(result, "total_duration_ms", 0)),
+                            "total_tool_use_count": latest.total_tool_use_count
+                            + int(getattr(result, "total_tool_use_count", 0)),
+                            "total_invocations": latest.total_invocations + 1,
+                        }
+                    )
+                    if updated_record.status in TERMINAL_BACKGROUND_STATUSES and not updated_record.notified:
+                        _append_notification(runtime, updated_record)
+                        updated_record = updated_record.model_copy(update={"notified": True})
+                    save_background_run(_store(runtime), updated_record)
+                    if updated_record.status in TERMINAL_BACKGROUND_STATUSES:
+                        return
+        finally:
+            with self._lock:
+                self._workers.pop(run_id, None)
+
+
+BACKGROUND_SUBAGENT_MANAGER = BackgroundSubagentManager()
+
+
+@tool(
+    "run_subagent_background",
+    args_schema=RunBackgroundSubagentInput,
+    description="Start a background subagent run and return immediately with a run id.",
+)
+def run_subagent_background(
+    task: str,
+    runtime: ToolRuntime,
+    agent_type: str = "general",
+    plan_id: str | None = None,
+    max_turns: int = 25,
+) -> str:
+    record = BACKGROUND_SUBAGENT_MANAGER.start_subagent(
+        task=task,
+        runtime=runtime,
+        agent_type=agent_type,
+        plan_id=plan_id,
+        max_turns=max_turns,
+    )
+    return record.model_dump_json()
+
+
+@tool(
+    "subagent_status",
+    args_schema=BackgroundSubagentStatusInput,
+    description="Read one background subagent or background fork status by run id.",
+)
+def subagent_status(run_id: str, runtime: ToolRuntime) -> str:
+    return BACKGROUND_SUBAGENT_MANAGER.status(run_id=run_id, runtime=runtime).model_dump_json()
+
+
+@tool(
+    "subagent_list",
+    args_schema=BackgroundSubagentListInput,
+    description="List background subagent and background fork runs.",
+)
+def subagent_list(runtime: ToolRuntime, include_terminal: bool = False) -> str:
+    runs = BACKGROUND_SUBAGENT_MANAGER.list_runs(
+        runtime=runtime,
+        include_terminal=include_terminal,
+    )
+    return json.dumps({"runs": [run.model_dump() for run in runs]})
+
+
+@tool(
+    "subagent_send_input",
+    args_schema=BackgroundSubagentSendInput,
+    description="Queue follow-up input for an existing background subagent or background fork run.",
+)
+def subagent_send_input(run_id: str, message: str, runtime: ToolRuntime) -> str:
+    return BACKGROUND_SUBAGENT_MANAGER.send_input(
+        run_id=run_id,
+        message=message,
+        runtime=runtime,
+    ).model_dump_json()
+
+
+@tool(
+    "subagent_stop",
+    args_schema=BackgroundSubagentStopInput,
+    description="Request stop for an active or queued background subagent or background fork run.",
+)
+def subagent_stop(run_id: str, runtime: ToolRuntime) -> str:
+    return BACKGROUND_SUBAGENT_MANAGER.stop(run_id=run_id, runtime=runtime).model_dump_json()
diff --git a/coding-deepgent/src/coding_deepgent/subagents/definitions.py b/coding-deepgent/src/coding_deepgent/subagents/definitions.py
new file mode 100644
index 000000000..96edd57a1
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/subagents/definitions.py
@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from langchain.tools import ToolRuntime
+from langchain_core.tools import BaseTool
+
+from coding_deepgent.filesystem import glob_search, grep_search, read_file
+from coding_deepgent.runtime import RuntimeContext
+from coding_deepgent.subagents.loader import (
+    discover_local_subagent_definitions,
+    discover_plugin_subagent_definitions,
+)
+from coding_deepgent.subagents.schemas import AgentDefinition
+from coding_deepgent.tasks import plan_get, task_get, task_list
+from coding_deepgent.tool_system.capabilities import (
+    CapabilityRegistry,
+    ToolCapability,
+    build_capability_registry,
+)
+
+FILE_ONLY_CHILD_TOOLS = ("read_file", "glob", "grep")
+DEFAULT_CHILD_TOOLS = ("read_file", "glob", "grep", "task_get", "task_list", "plan_get")
+EXPLORE_CHILD_TOOLS = FILE_ONLY_CHILD_TOOLS
+PLAN_CHILD_TOOLS = DEFAULT_CHILD_TOOLS
+VERIFIER_EXTRA_TOOLS = ()
+FORBIDDEN_CHILD_TOOLS = (
+    "bash",
+    "write_file",
+    "edit_file",
+    "TodoWrite",
+    "save_memory",
+    "task_create",
+    "task_update",
+    "plan_save",
+    "load_skill",
+    "run_subagent",
+    "run_fork",
+)
+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,
+}
+
+BUILTIN_AGENT_DEFINITIONS: dict[str, AgentDefinition] = {
+    "general": AgentDefinition(
+        agent_type="general",
+        description="Read-only general-purpose research subagent.",
+        when_to_use=(
+            "Use for bounded codebase research, file inspection, and durable "
+            "task/plan reads that do not modify workspace or state."
+        ),
+        instructions=(
+            "You are a read-only general-purpose research subagent. Inspect the "
+            "workspace and durable task/plan state, then return a concise answer "
+            "to the parent agent."
+        ),
+        tool_allowlist=DEFAULT_CHILD_TOOLS,
+        disallowed_tools=FORBIDDEN_CHILD_TOOLS,
+        max_turns=25,
+        model_profile=None,
+    ),
+    "verifier": AgentDefinition(
+        agent_type="verifier",
+        description="Read-only verification specialist for saved plan artifacts.",
+        when_to_use=(
+            "Use after implementation to inspect evidence against a durable "
+            "plan and return PASS, FAIL, or PARTIAL."
+        ),
+        instructions=(
+            "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."
+        ),
+        tool_allowlist=DEFAULT_CHILD_TOOLS,
+        disallowed_tools=FORBIDDEN_CHILD_TOOLS,
+        max_turns=5,
+        model_profile=None,
+    ),
+    "explore": AgentDefinition(
+        agent_type="explore",
+        description="Read-only code exploration specialist.",
+        when_to_use=(
+            "Use for targeted repository exploration, relevant-file discovery, "
+            "and grounded codebase explanation."
+        ),
+        instructions=(
+            "You are a read-only exploration specialist. Inspect the repository, "
+            "identify the most relevant files and concrete code paths, and report "
+            "findings without speculating beyond the evidence you can read."
+        ),
+        tool_allowlist=EXPLORE_CHILD_TOOLS,
+        disallowed_tools=FORBIDDEN_CHILD_TOOLS,
+        max_turns=12,
+        model_profile=None,
+    ),
+    "plan": AgentDefinition(
+        agent_type="plan",
+        description="Read-only planning specialist for implementation shaping.",
+        when_to_use=(
+            "Use for turning a goal into a concrete implementation plan, risk "
+            "list, and execution order grounded in current repository state."
+        ),
+        instructions=(
+            "You are a read-only planning specialist. Use the repository and "
+            "durable task/plan state to produce a concrete implementation plan, "
+            "call out risks, and keep recommendations tightly grounded in the "
+            "current codebase."
+        ),
+        tool_allowlist=PLAN_CHILD_TOOLS,
+        disallowed_tools=FORBIDDEN_CHILD_TOOLS,
+        max_turns=15,
+        model_profile=None,
+    ),
+}
+
+
+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",
+            source="builtin",
+            trusted=True,
+            exposure="child_only",
+            rendering_result="tool_message",
+            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",
+        source="builtin",
+        trusted=True,
+        exposure="child_only",
+        rendering_result="tool_message",
+        tags=("read", "workspace"),
+    )
+
+
+def agent_definition(agent_type: str) -> AgentDefinition:
+    return BUILTIN_AGENT_DEFINITIONS[agent_type]
+
+
+def child_tool_allowlist(agent_type: str) -> tuple[str, ...]:
+    return agent_definition(agent_type).tool_allowlist
+
+
+def child_capability_registry() -> CapabilityRegistry:
+    return build_capability_registry(
+        builtin_capabilities=tuple(
+            _child_tool_capability(name) for name in CHILD_TOOL_OBJECTS
+        ),
+        extension_capabilities=(),
+    )
+
+
+def _validate_agent_definition(definition: AgentDefinition) -> None:
+    unknown_tools = sorted(
+        item for item in definition.tool_allowlist if item not in CHILD_TOOL_OBJECTS
+    )
+    if unknown_tools:
+        raise ValueError(
+            f"Unknown child tools in `{definition.agent_type}`: {', '.join(unknown_tools)}"
+        )
+    unknown_disallowed = sorted(
+        item
+        for item in definition.disallowed_tools
+        if item not in CHILD_TOOL_OBJECTS and item not in FORBIDDEN_CHILD_TOOLS
+    )
+    if unknown_disallowed:
+        raise ValueError(
+            "Unknown disallowed tools in "
+            f"`{definition.agent_type}`: {', '.join(unknown_disallowed)}"
+        )
+
+
+def _runtime_workdir(runtime: ToolRuntime | None) -> Path | None:
+    context = getattr(runtime, "context", None)
+    if isinstance(context, RuntimeContext):
+        return context.workdir
+    return None
+
+
+def _runtime_plugin_dir(runtime: ToolRuntime | None) -> Path:
+    context = getattr(runtime, "context", None)
+    if isinstance(context, RuntimeContext):
+        return context.plugin_dir
+    return Path("plugins")
+
+
+def _agent_definitions_for_workdir(
+    workdir: Path | None,
+    *,
+    plugin_dir: Path,
+) -> dict[str, AgentDefinition]:
+    definitions: dict[str, AgentDefinition] = dict(BUILTIN_AGENT_DEFINITIONS)
+    if workdir is None:
+        return definitions
+    for definition in discover_plugin_subagent_definitions(
+        workdir=workdir,
+        plugin_dir=plugin_dir,
+    ):
+        if definition.agent_type in definitions:
+            raise ValueError(
+                f"Subagent definition `{definition.agent_type}` collides with an existing agent"
+            )
+        _validate_agent_definition(definition)
+        definitions[definition.agent_type] = definition
+    for definition in discover_local_subagent_definitions(workdir=workdir):
+        if definition.agent_type in definitions:
+            raise ValueError(
+                f"Subagent definition `{definition.agent_type}` collides with an existing agent"
+            )
+        _validate_agent_definition(definition)
+        definitions[definition.agent_type] = definition
+    return definitions
+
+
+def resolve_agent_definition(
+    agent_type: str, *, runtime: ToolRuntime | None = None
+) -> AgentDefinition:
+    definitions = _agent_definitions_for_workdir(
+        _runtime_workdir(runtime),
+        plugin_dir=_runtime_plugin_dir(runtime),
+    )
+    try:
+        return definitions[agent_type]
+    except KeyError as exc:
+        raise KeyError(f"Unknown subagent definition: {agent_type}") from exc
diff --git a/coding-deepgent/src/coding_deepgent/subagents/forking.py b/coding-deepgent/src/coding_deepgent/subagents/forking.py
new file mode 100644
index 000000000..6b5f76fe9
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/subagents/forking.py
@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Sequence
+from typing import Any, cast
+
+from langchain.tools import ToolRuntime
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage, ToolMessage
+
+from coding_deepgent.runtime import RuntimeContext
+from coding_deepgent.subagents.schemas import (
+    ForkPlaceholderLayout,
+    ToolPoolIdentitySnapshot,
+    ToolSurfaceSnapshot,
+)
+from coding_deepgent.tool_system import ToolPoolProjection
+
+FORK_RECURSION_GUARD_MARKER = "<CODING_DEEPGENT_FORK>"
+FORK_PLACEHOLDER_LAYOUT_VERSION = "fork_tool_result_v1"
+FORK_REPLACEMENT_STATE_HOOK = "preserve_tool_result_ids"
+FORK_MAX_TURNS = 25
+
+
+def fingerprint_text(value: str) -> str:
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()[:16]
+
+
+def stable_json(value: Any) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"))
+
+
+def tool_surface_snapshot(projection: ToolPoolProjection) -> ToolPoolIdentitySnapshot:
+    tools: list[ToolSurfaceSnapshot] = []
+    for visible_order, capability in enumerate(projection.capabilities):
+        schema = cast(Any, capability.tool.tool_call_schema).model_json_schema()
+        tools.append(
+            ToolSurfaceSnapshot(
+                name=capability.name,
+                visible_order=visible_order,
+                schema_fingerprint=fingerprint_text(stable_json(schema)),
+                description=str(getattr(capability.tool, "description", "")).strip()
+                or capability.name,
+            )
+        )
+    fingerprint = fingerprint_text(stable_json([tool.model_dump() for tool in tools]))
+    return ToolPoolIdentitySnapshot(fingerprint=fingerprint, tools=tools)
+
+
+def fork_placeholder_layout(messages: Sequence[BaseMessage]) -> ForkPlaceholderLayout:
+    paired_tool_call_ids = [
+        message.tool_call_id.strip()
+        for message in messages
+        if isinstance(message, ToolMessage) and message.tool_call_id.strip()
+    ]
+    return ForkPlaceholderLayout(
+        version=FORK_PLACEHOLDER_LAYOUT_VERSION,
+        paired_tool_call_ids=paired_tool_call_ids,
+        placeholder_messages=[
+            f"<fork-tool-result:{tool_call_id}>"
+            for tool_call_id in paired_tool_call_ids
+        ],
+        replacement_state_hook=FORK_REPLACEMENT_STATE_HOOK,
+    )
+
+
+def fork_directive(intent: str) -> str:
+    return "\n".join(
+        [
+            FORK_RECURSION_GUARD_MARKER,
+            "Fork child contract: inherit the parent rendered prompt and visible tools exactly.",
+            f"Branch intent: {intent.strip()}",
+            "Return only the branch result needed by the parent.",
+        ]
+    )
+
+
+def runtime_visible_tool_projection(runtime: ToolRuntime) -> ToolPoolProjection:
+    context = getattr(runtime, "context", None)
+    projection = getattr(context, "visible_tool_projection", None)
+    if not isinstance(projection, ToolPoolProjection):
+        raise RuntimeError("Fork requires a visible tool projection in runtime context")
+    return projection
+
+
+def runtime_rendered_system_prompt(runtime: ToolRuntime) -> str:
+    context = getattr(runtime, "context", None)
+    prompt = getattr(context, "rendered_system_prompt", None)
+    if not isinstance(prompt, str) or not prompt.strip():
+        raise RuntimeError("Fork requires a rendered system prompt in runtime context")
+    return prompt
+
+
+def message_tool_call_ids(message: BaseMessage) -> tuple[str, ...]:
+    if isinstance(message, AIMessage):
+        return tuple(
+            str(item.get("id", "")).strip()
+            for item in message.tool_calls
+            if isinstance(item, dict) and str(item.get("id", "")).strip()
+        )
+    content = getattr(message, "content", None)
+    if isinstance(content, list):
+        return tuple(
+            str(block.get("id", "")).strip()
+            for block in content
+            if isinstance(block, dict)
+            and block.get("type") == "tool_use"
+            and str(block.get("id", "")).strip()
+        )
+    return ()
+
+
+def tool_result_call_id(message: BaseMessage) -> str | None:
+    if isinstance(message, ToolMessage):
+        tool_call_id = getattr(message, "tool_call_id", None)
+        if isinstance(tool_call_id, str) and tool_call_id.strip():
+            return tool_call_id.strip()
+    return None
+
+
+def normalize_fork_source_messages(
+    source_messages: Sequence[BaseMessage],
+) -> list[BaseMessage]:
+    paired_tool_result_ids = {
+        tool_call_id
+        for message in source_messages
+        if (tool_call_id := tool_result_call_id(message)) is not None
+    }
+    normalized: list[BaseMessage] = []
+    for message in source_messages:
+        tool_call_ids = message_tool_call_ids(message)
+        if tool_call_ids and any(
+            tool_call_id not in paired_tool_result_ids
+            for tool_call_id in tool_call_ids
+        ):
+            continue
+        normalized.append(message)
+    return normalized
+
+
+def message_contains_marker(message: BaseMessage, marker: str) -> bool:
+    content = getattr(message, "content", "")
+    if isinstance(content, str):
+        return marker in content
+    if isinstance(content, list):
+        for block in content:
+            if isinstance(block, dict):
+                text = block.get("text")
+                if isinstance(text, str) and marker in text:
+                    return True
+    return False
+
+
+def fork_recursion_guard(
+    *,
+    runtime: ToolRuntime,
+    source_messages: Sequence[BaseMessage],
+) -> str | None:
+    context = getattr(runtime, "context", None)
+    if isinstance(context, RuntimeContext) and context.entrypoint == "run_fork":
+        return "Fork blocked: fork children cannot spawn nested forks."
+    if any(
+        message_contains_marker(message, FORK_RECURSION_GUARD_MARKER)
+        for message in source_messages
+    ):
+        return "Fork blocked: recursion guard marker already exists in the active message prefix."
+    return None
+
+
+def fork_payload_messages(
+    *,
+    source_messages: Sequence[BaseMessage],
+    intent: str,
+) -> list[BaseMessage]:
+    normalized_messages = normalize_fork_source_messages(source_messages)
+    return [*normalized_messages, HumanMessage(content=fork_directive(intent))]
diff --git a/coding-deepgent/src/coding_deepgent/subagents/loader.py b/coding-deepgent/src/coding_deepgent/subagents/loader.py
new file mode 100644
index 000000000..4f85975a8
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/subagents/loader.py
@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from coding_deepgent.plugins import discover_local_plugins
+from coding_deepgent.subagents.schemas import AgentDefinition
+
+SUBAGENT_DIRNAME = ".coding-deepgent"
+SUBAGENT_FILE_NAME = "SUBAGENTS.json"
+PLUGIN_SUBAGENT_FILE_NAME = "subagents.json"
+
+
+class LocalSubagentCatalog(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    agents: tuple[AgentDefinition, ...] = Field(default_factory=tuple)
+
+    @field_validator("agents")
+    @classmethod
+    def _agent_names_must_be_unique(
+        cls, value: tuple[AgentDefinition, ...]
+    ) -> tuple[AgentDefinition, ...]:
+        names = [item.agent_type for item in value]
+        if len(set(names)) != len(names):
+            raise ValueError("duplicate agent definitions are not allowed")
+        return value
+
+
+def local_subagent_path(workdir: Path) -> Path:
+    return workdir / SUBAGENT_DIRNAME / SUBAGENT_FILE_NAME
+
+
+def parse_local_subagent_catalog(path: Path) -> LocalSubagentCatalog:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    return LocalSubagentCatalog.model_validate(data)
+
+
+def parse_plugin_subagent_catalog(path: Path) -> LocalSubagentCatalog:
+    return parse_local_subagent_catalog(path)
+
+
+def discover_local_subagent_definitions(*, workdir: Path) -> tuple[AgentDefinition, ...]:
+    path = local_subagent_path(workdir)
+    if not path.exists():
+        return ()
+    if not path.is_file():
+        raise FileNotFoundError(f"Local subagent catalog is not a file: {path}")
+    return parse_local_subagent_catalog(path).agents
+
+
+def discover_plugin_subagent_definitions(
+    *,
+    workdir: Path,
+    plugin_dir: Path,
+) -> tuple[AgentDefinition, ...]:
+    definitions: list[AgentDefinition] = []
+    for plugin in discover_local_plugins(workdir=workdir, plugin_dir=plugin_dir):
+        declared_agents = plugin.manifest.agents
+        if not declared_agents:
+            continue
+        catalog_path = plugin.root / PLUGIN_SUBAGENT_FILE_NAME
+        if not catalog_path.is_file():
+            raise FileNotFoundError(
+                f"Plugin `{plugin.manifest.name}` declares agents but is missing {PLUGIN_SUBAGENT_FILE_NAME}"
+            )
+        catalog = parse_plugin_subagent_catalog(catalog_path)
+        catalog_names = {item.agent_type for item in catalog.agents}
+        if catalog_names != set(declared_agents):
+            raise ValueError(
+                f"Plugin `{plugin.manifest.name}` agent catalog mismatch: manifest={sorted(declared_agents)} catalog={sorted(catalog_names)}"
+            )
+        for definition in catalog.agents:
+            if not definition.agent_type.startswith(f"{plugin.manifest.name}:"):
+                raise ValueError(
+                    f"Plugin subagent `{definition.agent_type}` must be namespaced with `{plugin.manifest.name}:`"
+                )
+            definitions.append(definition)
+    return tuple(definitions)
diff --git a/coding-deepgent/src/coding_deepgent/subagents/results.py b/coding-deepgent/src/coding_deepgent/subagents/results.py
new file mode 100644
index 000000000..f5cfe6f97
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/subagents/results.py
@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+
+from coding_deepgent.subagents.schemas import ForkPlaceholderLayout, ToolPoolIdentitySnapshot
+
+
+@dataclass(frozen=True, slots=True)
+class SubagentResult:
+    content: str
+    agent_type: str
+    tool_allowlist: tuple[str, ...]
+    input_tokens: int = 0
+    output_tokens: int = 0
+    total_tokens: int = 0
+    total_duration_ms: int = 0
+    total_tool_use_count: int = 0
+    plan_id: str | None = None
+    plan_title: str | None = None
+    verification: str | None = None
+    task_ids: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class ForkResult:
+    content: str
+    fork_run_id: str
+    parent_thread_id: str
+    child_thread_id: str
+    rendered_prompt_fingerprint: str
+    tool_pool_identity: ToolPoolIdentitySnapshot
+    placeholder_layout: ForkPlaceholderLayout
+    input_tokens: int = 0
+    output_tokens: int = 0
+    total_tokens: int = 0
+    total_duration_ms: int = 0
+    total_tool_use_count: int = 0
+
+
+ChildAgentFactory = Callable[[str, Sequence[str]], Callable[[str], str]]
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..6435309f2
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/subagents/schemas.py
@@ -0,0 +1,389 @@
+from __future__ import annotations
+
+import re
+from typing import Literal
+
+from langchain.tools import ToolRuntime
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+_IDENTIFIER = re.compile(r"^[A-Za-z_][A-Za-z0-9_:-]*$")
+
+BuiltinSubagentType = Literal["general", "verifier", "explore", "plan"]
+SubagentType = str
+BackgroundRunStatus = Literal["queued", "running", "completed", "failed", "cancelled"]
+
+
+class AgentDefinition(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    agent_type: SubagentType
+    description: str = Field(..., min_length=1)
+    when_to_use: str = Field(..., min_length=1)
+    instructions: str | None = Field(default=None, min_length=1)
+    tool_allowlist: tuple[str, ...] = Field(default_factory=tuple)
+    disallowed_tools: tuple[str, ...] = Field(default_factory=tuple)
+    max_turns: int = Field(..., ge=1, le=25)
+    model_profile: str | None = Field(default=None, min_length=1)
+
+    @field_validator(
+        "agent_type",
+        "description",
+        "when_to_use",
+        "instructions",
+        "model_profile",
+        mode="before",
+    )
+    @classmethod
+    def _optional_text_must_not_be_blank(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        value = str(value).strip()
+        if not value:
+            raise ValueError("value required")
+        return value
+
+    @field_validator("agent_type")
+    @classmethod
+    def _agent_type_must_be_identifier(cls, value: str) -> str:
+        if not _IDENTIFIER.fullmatch(value):
+            raise ValueError("agent_type must be a local identifier")
+        return value
+
+    @field_validator("tool_allowlist", "disallowed_tools")
+    @classmethod
+    def _tools_must_not_be_blank(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        cleaned = tuple(item.strip() for item in value)
+        if any(not item for item in cleaned):
+            raise ValueError("tool names must not be blank")
+        if len(set(cleaned)) != len(cleaned):
+            raise ValueError("tool names must be unique")
+        return cleaned
+
+    @model_validator(mode="after")
+    def _tool_sets_must_not_overlap(self) -> "AgentDefinition":
+        overlap = set(self.tool_allowlist) & set(self.disallowed_tools)
+        if overlap:
+            raise ValueError("tool_allowlist and disallowed_tools overlap")
+        return self
+
+
+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: str = 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=25,
+        ge=1,
+        le=25,
+        description="Requested child turn ceiling. Agent definitions may impose a lower limit.",
+    )
+
+    @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
+
+    @field_validator("agent_type")
+    @classmethod
+    def _agent_type_must_be_identifier(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("agent_type required")
+        if not _IDENTIFIER.fullmatch(value):
+            raise ValueError("agent_type must be a local identifier")
+        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 RunForkInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    intent: str = Field(
+        ...,
+        min_length=1,
+        description="Short branch-specific intent for a same-config sibling fork.",
+    )
+    runtime: ToolRuntime
+    background: bool = Field(
+        default=False,
+        description="Run the fork in the background and return a background run record.",
+    )
+    max_turns: int = Field(
+        default=25,
+        ge=1,
+        le=25,
+        description="Requested child turn ceiling for the forked sibling branch.",
+    )
+
+    @field_validator("intent")
+    @classmethod
+    def _intent_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("intent required")
+        return value
+
+
+class ToolSurfaceSnapshot(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(..., min_length=1)
+    visible_order: int = Field(..., ge=0)
+    schema_fingerprint: str = Field(..., min_length=1)
+    description: str = Field(..., min_length=1)
+
+
+class ToolPoolIdentitySnapshot(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    fingerprint: str = Field(..., min_length=1)
+    tools: list[ToolSurfaceSnapshot] = Field(default_factory=list)
+
+
+class ForkPlaceholderLayout(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    version: str = Field(..., min_length=1)
+    paired_tool_call_ids: list[str] = Field(default_factory=list)
+    placeholder_messages: list[str] = Field(default_factory=list)
+    replacement_state_hook: str = Field(..., min_length=1)
+
+
+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)
+    input_tokens: int = Field(..., ge=0)
+    output_tokens: int = Field(..., ge=0)
+    total_tokens: int = Field(..., ge=0)
+    total_duration_ms: int = Field(..., ge=0)
+    total_tool_use_count: int = Field(..., ge=0)
+
+
+class SubagentResultEnvelope(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    agent_type: str = Field(..., min_length=1)
+    content: str = Field(..., min_length=1)
+    tool_allowlist: list[str] = Field(default_factory=list)
+    input_tokens: int = Field(..., ge=0)
+    output_tokens: int = Field(..., ge=0)
+    total_tokens: int = Field(..., ge=0)
+    total_duration_ms: int = Field(..., ge=0)
+    total_tool_use_count: int = Field(..., ge=0)
+
+
+class ForkResultEnvelope(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    mode: Literal["fork"] = "fork"
+    content: str = Field(..., min_length=1)
+    fork_run_id: str = Field(..., min_length=1)
+    parent_thread_id: str = Field(..., min_length=1)
+    child_thread_id: str = Field(..., min_length=1)
+    rendered_prompt_fingerprint: str = Field(..., min_length=1)
+    tool_pool_identity: ToolPoolIdentitySnapshot
+    placeholder_layout: ForkPlaceholderLayout
+    input_tokens: int = Field(..., ge=0)
+    output_tokens: int = Field(..., ge=0)
+    total_tokens: int = Field(..., ge=0)
+    total_duration_ms: int = Field(..., ge=0)
+    total_tool_use_count: int = Field(..., ge=0)
+
+
+class RunBackgroundSubagentInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    task: str = Field(
+        ...,
+        min_length=1,
+        description="Initial task for a background subagent run.",
+    )
+    runtime: ToolRuntime
+    agent_type: str = Field(
+        default="general", description="Built-in, local, or plugin subagent type."
+    )
+    plan_id: str | None = Field(
+        default=None,
+        min_length=1,
+        description="Durable plan artifact id. Required for verifier agents.",
+    )
+    max_turns: int = Field(
+        default=25,
+        ge=1,
+        le=25,
+        description="Requested child turn ceiling for the background run.",
+    )
+
+    @field_validator("task", "agent_type")
+    @classmethod
+    def _background_text_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("value required")
+        return value
+
+    @model_validator(mode="after")
+    def _verifier_requires_plan(self) -> "RunBackgroundSubagentInput":
+        if self.agent_type == "verifier" and self.plan_id is None:
+            raise ValueError("verifier subagents require plan_id")
+        return self
+
+
+class BackgroundSubagentStatusInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    run_id: str = Field(..., min_length=1)
+    runtime: ToolRuntime
+
+
+class BackgroundSubagentListInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    runtime: ToolRuntime
+    include_terminal: bool = Field(
+        default=False,
+        description="Include completed, failed, and cancelled background runs.",
+    )
+
+
+class BackgroundSubagentSendInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    run_id: str = Field(..., min_length=1)
+    message: str = Field(..., min_length=1)
+    runtime: ToolRuntime
+
+    @field_validator("message")
+    @classmethod
+    def _message_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("message required")
+        return value
+
+
+class BackgroundSubagentStopInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    run_id: str = Field(..., min_length=1)
+    runtime: ToolRuntime
+
+
+class BackgroundRuntimeSnapshot(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    session_id: str = Field(..., min_length=1)
+    parent_thread_id: str = Field(..., min_length=1)
+    workdir: str = Field(..., min_length=1)
+    entrypoint: str = Field(..., min_length=1)
+    agent_name: str = Field(..., min_length=1)
+    has_session_context: bool = False
+    rendered_prompt_fingerprint: str | None = Field(default=None, min_length=1)
+    tool_pool_fingerprint: str | None = Field(default=None, min_length=1)
+
+
+class ResumeSubagentInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    subagent_thread_id: str = Field(..., min_length=1)
+    runtime: ToolRuntime
+    follow_up: str | None = Field(
+        default=None,
+        min_length=1,
+        description="Optional follow-up instruction when resuming the recorded child thread.",
+    )
+
+    @field_validator("subagent_thread_id", "follow_up")
+    @classmethod
+    def _resume_text_must_not_be_blank(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        value = value.strip()
+        if not value:
+            raise ValueError("value required")
+        return value
+
+
+class ResumeForkInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    child_thread_id: str = Field(..., min_length=1)
+    runtime: ToolRuntime
+    follow_up: str | None = Field(
+        default=None,
+        min_length=1,
+        description="Optional follow-up instruction when resuming the recorded fork thread.",
+    )
+
+    @field_validator("child_thread_id", "follow_up")
+    @classmethod
+    def _fork_resume_text_must_not_be_blank(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        value = value.strip()
+        if not value:
+            raise ValueError("value required")
+        return value
+
+
+class BackgroundSubagentRun(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    run_id: str = Field(..., min_length=1)
+    mode: Literal["background_subagent", "background_fork"] = "background_subagent"
+    agent_type: str = Field(..., min_length=1)
+    status: BackgroundRunStatus
+    title: str = Field(..., min_length=1)
+    parent_thread_id: str = Field(..., min_length=1)
+    child_thread_id: str = Field(..., min_length=1)
+    workdir: str = Field(..., min_length=1)
+    requested_max_turns: int | None = Field(default=None, ge=1, le=25)
+    effective_max_turns: int = Field(..., ge=1, le=25)
+    model_profile: str | None = Field(default=None, min_length=1)
+    plan_id: str | None = Field(default=None, min_length=1)
+    pending_inputs: list[str] = Field(default_factory=list)
+    progress_summary: str = Field(..., min_length=1)
+    summary_text: str | None = None
+    rendered_prompt_fingerprint: str | None = None
+    tool_pool_fingerprint: str | None = None
+    placeholder_layout_version: str | None = None
+    runtime_snapshot: BackgroundRuntimeSnapshot | None = None
+    recent_activities: list[str] = Field(default_factory=list)
+    latest_result: str | None = None
+    error: str | None = None
+    stop_requested: bool = False
+    input_tokens: int = Field(default=0, ge=0)
+    output_tokens: int = Field(default=0, ge=0)
+    total_tokens: int = Field(default=0, ge=0)
+    total_duration_ms: int = Field(default=0, ge=0)
+    total_tool_use_count: int = Field(default=0, ge=0)
+    total_invocations: int = Field(default=0, ge=0)
+    notified: bool = False
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..3b50f0cbf
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/subagents/tools.py
@@ -0,0 +1,1482 @@
+from __future__ import annotations
+
+import json
+import re
+import time
+import uuid
+from collections.abc import Sequence
+from dataclasses import replace
+from pathlib import Path
+from typing import Any, cast
+
+from langchain.tools import ToolRuntime, tool
+from langchain_core.messages import (
+    AIMessage,
+    BaseMessage,
+    HumanMessage,
+    SystemMessage,
+    ToolMessage,
+)
+from langchain_core.tools import BaseTool
+
+from coding_deepgent.compact.runtime_pressure import estimate_message_tokens
+from coding_deepgent.rendering import latest_assistant_text
+import coding_deepgent.runtime.agent_factory as runtime_agent_factory
+from coding_deepgent.runtime import (
+    RuntimeAgentBuildRequest,
+    RuntimeAgentRole,
+    RuntimeContext,
+    RuntimeEvent,
+    RuntimeInvocation,
+)
+from coding_deepgent.sessions.evidence_events import append_runtime_event_evidence
+from coding_deepgent.sessions.records import LoadedSession, SessionContext, SessionSidechainMessage
+from coding_deepgent.sessions.store_jsonl import JsonlSessionStore
+from coding_deepgent.settings import build_openai_model
+from coding_deepgent.subagents.definitions import (
+    BUILTIN_AGENT_DEFINITIONS,
+    child_capability_registry,
+    resolve_agent_definition,
+)
+from coding_deepgent.subagents.forking import (
+    FORK_MAX_TURNS,
+    FORK_PLACEHOLDER_LAYOUT_VERSION,
+    FORK_REPLACEMENT_STATE_HOOK,
+    fingerprint_text as _fingerprint_text,
+    fork_directive as _fork_directive,
+    fork_payload_messages as _fork_payload_messages,
+    fork_placeholder_layout as _fork_placeholder_layout,
+    fork_recursion_guard as _fork_recursion_guard,
+    normalize_fork_source_messages as _normalize_fork_source_messages,
+    runtime_rendered_system_prompt as _runtime_rendered_system_prompt,
+    runtime_visible_tool_projection as _runtime_visible_tool_projection,
+    tool_surface_snapshot as _tool_surface_snapshot,
+)
+from coding_deepgent.subagents.results import ChildAgentFactory, ForkResult, SubagentResult
+from coding_deepgent.subagents.schemas import (
+    AgentDefinition,
+    ForkPlaceholderLayout,
+    ForkResultEnvelope,
+    ResumeForkInput,
+    ResumeSubagentInput,
+    RunSubagentInput,
+    RunForkInput,
+    SubagentType,
+    SubagentResultEnvelope,
+    ToolPoolIdentitySnapshot,
+    VerifierSubagentResult,
+)
+from coding_deepgent.tasks.store import get_plan
+from coding_deepgent.tool_system import (
+    CapabilityRegistry,
+    ToolGuardMiddleware,
+    ToolPoolProjection,
+)
+
+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",
+}
+SUBAGENT_RESUME_VERSION = "subagent_resume_v1"
+FORK_RESUME_VERSION = "fork_resume_v1"
+DEFAULT_RESUME_FOLLOW_UP = "Continue the current task from the recorded sidechain state."
+DEFAULT_FORK_RESUME_FOLLOW_UP = "Continue the current branch from the recorded fork state."
+READ_ONLY_BOUNDARY_PROMPT = (
+    "You are strictly read-only. Do not modify files, tasks, plans, memory, or "
+    "invoke nested subagents. If a task requires mutation, explain what the "
+    "parent agent should do instead."
+)
+
+
+def _json_clone(value: Any) -> Any:
+    return json.loads(json.dumps(value))
+
+
+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 _agent_system_prompt(*, definition: AgentDefinition, context: RuntimeContext) -> str:
+    allowed_tools = ", ".join(definition.tool_allowlist)
+    sections = [
+        definition.instructions
+        or "You are a read-only subagent. Use the available tools only when they materially improve the result.",
+        READ_ONLY_BOUNDARY_PROMPT,
+    ]
+    if definition.agent_type == "verifier":
+        sections.append(
+            "Use only the available tools when they materially improve the verification result. "
+            "Cite concrete evidence from commands or tool reads in your final answer."
+        )
+    sections.extend(
+        [
+            f"Workspace: {context.workdir}",
+            f"Allowed tools: {allowed_tools}",
+        ]
+    )
+    if definition.agent_type == "verifier":
+        sections.append(
+            "End with a final line exactly `VERDICT: PASS`, `VERDICT: FAIL`, or `VERDICT: PARTIAL`."
+        )
+    return "\n\n".join(sections)
+
+
+def _effective_max_turns(definition: AgentDefinition, requested_max_turns: int | None) -> int:
+    if requested_max_turns is None:
+        return definition.max_turns
+    return min(requested_max_turns, definition.max_turns)
+
+
+def _recursion_limit_for_max_turns(max_turns: int) -> int:
+    return max(3, (max_turns * 2) + 1)
+
+
+def _build_thread_config(*, thread_id: str, max_turns: int) -> dict[str, Any]:
+    return {
+        "configurable": {"thread_id": thread_id},
+        "recursion_limit": _recursion_limit_for_max_turns(max_turns),
+    }
+
+
+def _runtime_tool_policy(runtime: ToolRuntime) -> Any:
+    context = getattr(runtime, "context", None)
+    return cast(Any, getattr(context, "tool_policy", None))
+
+
+def _child_runtime_invocation(
+    *,
+    runtime: ToolRuntime,
+    definition: AgentDefinition,
+    max_turns: int,
+    run_id: str | None = None,
+) -> RuntimeInvocation:
+    context = getattr(runtime, "context", None)
+    if not isinstance(context, RuntimeContext):
+        raise RuntimeError("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))
+    suffix = f":{run_id}" if run_id else ""
+    return RuntimeInvocation(
+        context=replace(
+            context,
+            agent_name=f"{context.agent_name}-{definition.agent_type}",
+            entrypoint=f"run_subagent:{definition.agent_type}",
+        ),
+        config=_build_thread_config(
+            thread_id=f"{parent_thread_id}:{definition.agent_type}{suffix}",
+            max_turns=max_turns,
+        ),
+    )
+
+
+def _fork_runtime_invocation(
+    *,
+    runtime: ToolRuntime,
+    max_turns: int,
+    run_id: str,
+) -> RuntimeInvocation:
+    context = getattr(runtime, "context", None)
+    if not isinstance(context, RuntimeContext):
+        raise RuntimeError("Fork requires runtime context")
+    parent_thread_id = _runtime_thread_id(runtime)
+    visible_tool_projection = _runtime_visible_tool_projection(runtime)
+    rendered_system_prompt = _runtime_rendered_system_prompt(runtime)
+    return RuntimeInvocation(
+        context=replace(
+            context,
+            agent_name=f"{context.agent_name}-fork",
+            entrypoint="run_fork",
+            rendered_system_prompt=rendered_system_prompt,
+            visible_tool_projection=visible_tool_projection,
+            tool_policy=_runtime_tool_policy(runtime),
+        ),
+        config=_build_thread_config(
+            thread_id=f"{parent_thread_id}:fork:{run_id}",
+            max_turns=max_turns,
+        ),
+    )
+
+
+def _child_tools(definition: AgentDefinition) -> list[BaseTool]:
+    return child_capability_registry().tools_for_names(definition.tool_allowlist)
+
+
+def _child_middleware(definition: AgentDefinition) -> list[ToolGuardMiddleware]:
+    registry = child_capability_registry()
+    return [ToolGuardMiddleware(registry=registry)]
+
+
+def _fork_middleware(runtime: ToolRuntime, projection: ToolPoolProjection) -> list[ToolGuardMiddleware]:
+    registry = CapabilityRegistry(projection.capabilities)
+    return [
+        ToolGuardMiddleware(
+            registry=registry,
+            policy=cast(Any, _runtime_tool_policy(runtime)),
+        )
+    ]
+
+
+def _fork_source_messages(runtime: ToolRuntime) -> list[BaseMessage]:
+    state = getattr(runtime, "state", None)
+    if not isinstance(state, dict):
+        raise RuntimeError("Fork requires runtime state messages")
+    messages = state.get("messages")
+    if not isinstance(messages, list) or not all(
+        isinstance(message, BaseMessage) for message in messages
+    ):
+        raise RuntimeError("Fork requires runtime state messages")
+    return list(messages)
+
+
+def _execute_child_subagent(
+    *,
+    task: str,
+    runtime: ToolRuntime,
+    definition: AgentDefinition,
+    max_turns: int,
+    run_id: str | None = None,
+) -> dict[str, Any]:
+    from coding_deepgent.agent_runtime_service import invoke_agent
+
+    invocation = _child_runtime_invocation(
+        runtime=runtime,
+        definition=definition,
+        max_turns=max_turns,
+        run_id=run_id,
+    )
+    system_prompt = _agent_system_prompt(
+        definition=definition, context=invocation.context
+    )
+    agent = runtime_agent_factory.create_runtime_agent(
+        RuntimeAgentBuildRequest(
+            role=RuntimeAgentRole.SUBAGENT,
+            model=build_openai_model(model_name=definition.model_profile),
+            tools=_child_tools(definition),
+            system_prompt=system_prompt,
+            middleware=_child_middleware(definition),
+            context_schema=RuntimeContext,
+            store=runtime.store,
+            name=invocation.context.agent_name,
+        )
+    )
+    result = invoke_agent(
+        agent,
+        {"messages": [{"role": "user", "content": task}]},
+        invocation,
+    )
+    content = _final_child_text(result).strip()
+    if not content:
+        raise RuntimeError("Subagent returned no assistant content")
+    return {"content": content, "raw_result": result, "invocation": invocation}
+
+
+def _enqueue_agent_private_memory(
+    *,
+    invocation: RuntimeInvocation,
+    source: str,
+    task: str,
+    content: str,
+) -> None:
+    service = getattr(invocation.context, "memory_service", None)
+    if service is None:
+        return
+    agent_scope = invocation.context.agent_name
+    if not isinstance(agent_scope, str) or not agent_scope.strip():
+        return
+    service.enqueue_extraction(
+        project_scope=str(invocation.context.workdir),
+        agent_scope=agent_scope,
+        source=source,
+        text=f"Task: {task}\n\nAssistant: {content}",
+    )
+
+
+def _final_child_text(result: Any) -> str:
+    content = latest_assistant_text(result).strip()
+    if content:
+        return content
+    messages = result.get("messages", []) if isinstance(result, dict) else []
+    for message in reversed(messages):
+        if isinstance(message, dict):
+            text = str(message.get("content") or "").strip()
+        else:
+            text = str(getattr(message, "content", "") or "").strip()
+        if text:
+            return text
+    return ""
+
+
+def _tool_use_count(result: Any) -> int:
+    messages = result.get("messages", []) if isinstance(result, dict) else []
+    count = 0
+    for message in messages:
+        if isinstance(message, AIMessage):
+            count += len(message.tool_calls)
+            continue
+        if not isinstance(message, dict):
+            continue
+        tool_calls = message.get("tool_calls")
+        if isinstance(tool_calls, list):
+            count += len(tool_calls)
+        content = message.get("content")
+        if isinstance(content, list):
+            count += sum(
+                1
+                for block in content
+                if isinstance(block, dict) and block.get("type") == "tool_use"
+            )
+    return count
+
+
+def _result_metrics(
+    *,
+    task: str,
+    content: str,
+    raw_result: Any,
+    duration_ms: int,
+) -> dict[str, int]:
+    input_tokens = estimate_message_tokens([HumanMessage(content=task)])
+    output_tokens = estimate_message_tokens([HumanMessage(content=content)])
+    return {
+        "input_tokens": input_tokens,
+        "output_tokens": output_tokens,
+        "total_tokens": input_tokens + output_tokens,
+        "total_duration_ms": duration_ms,
+        "total_tool_use_count": _tool_use_count(raw_result),
+    }
+
+
+def _definition_origin(agent_type: str) -> str:
+    if agent_type in BUILTIN_AGENT_DEFINITIONS:
+        return "builtin"
+    if ":" in agent_type:
+        return "plugin"
+    return "local"
+
+
+def _activity_summary(content: str, *, limit: int = 72) -> str:
+    first_line = next((line.strip() for line in content.splitlines() if line.strip()), "")
+    if not first_line:
+        return "No summary yet."
+    if len(first_line) <= limit:
+        return first_line
+    return f"{first_line[: limit - 3].rstrip()}..."
+
+
+def _runtime_workdir(runtime: ToolRuntime | None) -> Path | None:
+    context = getattr(runtime, "context", None)
+    if isinstance(context, RuntimeContext):
+        return context.workdir
+    return None
+
+
+def _runtime_workdir_string(runtime: ToolRuntime | None) -> str:
+    workdir = _runtime_workdir(runtime)
+    if workdir is None:
+        return ""
+    return str(workdir.resolve())
+
+
+def _validate_recorded_workdir(
+    *,
+    runtime: ToolRuntime,
+    metadata: dict[str, Any],
+) -> None:
+    expected_workdir = metadata.get("workdir")
+    if not isinstance(expected_workdir, str) or not expected_workdir.strip():
+        return
+    current_workdir = _runtime_workdir(runtime)
+    if current_workdir is None:
+        raise RuntimeError("Resume requires runtime workdir context")
+    if str(current_workdir.resolve()) != expected_workdir.strip():
+        raise RuntimeError("Resume requires the same recorded workdir")
+    if not current_workdir.exists() or not current_workdir.is_dir():
+        raise RuntimeError("Resume requires an existing recorded workdir")
+
+
+def _subagent_resume_metadata(
+    *,
+    definition: AgentDefinition,
+    runtime: ToolRuntime | None,
+    requested_max_turns: int | None,
+    effective_max_turns: int,
+    plan_id: str | None = None,
+) -> dict[str, Any]:
+    metadata: dict[str, Any] = {
+        "resume_version": SUBAGENT_RESUME_VERSION,
+        "agent_origin": _definition_origin(definition.agent_type),
+        "requested_max_turns": requested_max_turns,
+        "effective_max_turns": effective_max_turns,
+        "model_profile": definition.model_profile,
+        "tool_allowlist": list(definition.tool_allowlist),
+        "workdir": _runtime_workdir_string(runtime),
+    }
+    if plan_id is not None:
+        metadata["plan_id"] = plan_id
+    return metadata
+
+
+def _fork_resume_metadata(
+    *,
+    runtime: ToolRuntime | None,
+    run_id: str,
+    requested_max_turns: int | None,
+    effective_max_turns: int,
+    tool_pool_identity: ToolPoolIdentitySnapshot,
+    prompt_fingerprint: str,
+    placeholder_layout: ForkPlaceholderLayout,
+) -> dict[str, Any]:
+    return {
+        "resume_version": FORK_RESUME_VERSION,
+        "fork_run_id": run_id,
+        "requested_max_turns": requested_max_turns,
+        "effective_max_turns": effective_max_turns,
+        "tool_pool_fingerprint": tool_pool_identity.fingerprint,
+        "rendered_prompt_fingerprint": prompt_fingerprint,
+        "placeholder_layout_version": placeholder_layout.version,
+        "placeholder_messages": list(placeholder_layout.placeholder_messages),
+        "workdir": _runtime_workdir_string(runtime),
+    }
+
+
+def _sidechain_entry_metadata(message: Any) -> dict[str, Any] | None:
+    metadata: dict[str, Any] = {}
+    if isinstance(message, ToolMessage):
+        tool_call_id = getattr(message, "tool_call_id", None)
+        if isinstance(tool_call_id, str) and tool_call_id.strip():
+            metadata["tool_call_id"] = tool_call_id.strip()
+    if isinstance(message, AIMessage) and message.tool_calls:
+        metadata["tool_calls"] = _json_clone(message.tool_calls)
+    if isinstance(message, dict):
+        tool_calls = message.get("tool_calls")
+        if isinstance(tool_calls, list) and tool_calls:
+            metadata["tool_calls"] = _json_clone(tool_calls)
+        tool_call_id = message.get("tool_call_id")
+        if isinstance(tool_call_id, str) and tool_call_id.strip():
+            metadata["tool_call_id"] = tool_call_id.strip()
+        content = message.get("content")
+    else:
+        content = getattr(message, "content", "")
+    if isinstance(content, list) and content:
+        metadata["structured_content"] = _json_clone(content)
+    return metadata or None
+
+
+def _merge_sidechain_metadata(
+    root_metadata: dict[str, Any] | None,
+    entry_metadata: dict[str, Any] | None,
+) -> dict[str, Any] | None:
+    if root_metadata is None and entry_metadata is None:
+        return None
+    merged: dict[str, Any] = {}
+    if root_metadata is not None:
+        merged.update(_json_clone(root_metadata))
+    if entry_metadata is not None:
+        merged["sidechain_entry"] = _json_clone(entry_metadata)
+    return merged
+
+
+def _record_sidechain_messages(
+    *,
+    runtime: ToolRuntime | None,
+    agent_type: str,
+    child_invocation: RuntimeInvocation,
+    task: str,
+    raw_result: Any,
+    metadata: dict[str, Any] | None = None,
+) -> bool:
+    if runtime is None:
+        return False
+    context = getattr(runtime, "context", None)
+    if not isinstance(context, RuntimeContext):
+        return False
+    session_context = context.session_context
+    if not isinstance(session_context, SessionContext):
+        return False
+    store = JsonlSessionStore(session_context.store_dir)
+    parent_message_id = store.latest_message_id(session_context)
+    parent_thread_id = _runtime_thread_id(runtime)
+    subagent_thread_id = str(
+        child_invocation.config.get("configurable", {}).get(
+            "thread_id", child_invocation.context.session_id
+        )
+    )
+    store.append_sidechain_message(
+        session_context,
+        agent_type=agent_type,
+        role="user",
+        content=task,
+        subagent_thread_id=subagent_thread_id,
+        parent_message_id=parent_message_id,
+        parent_thread_id=parent_thread_id,
+        metadata=metadata,
+    )
+    for role, content, entry_metadata in _sidechain_message_entries(raw_result):
+        store.append_sidechain_message(
+            session_context,
+            agent_type=agent_type,
+            role=role,
+            content=content,
+            subagent_thread_id=subagent_thread_id,
+            parent_message_id=parent_message_id,
+            parent_thread_id=parent_thread_id,
+            metadata=_merge_sidechain_metadata(metadata, entry_metadata),
+        )
+    return True
+
+
+def _sidechain_message_entries(
+    raw_result: Any,
+) -> list[tuple[str, str, dict[str, Any] | None]]:
+    messages = raw_result.get("messages", []) if isinstance(raw_result, dict) else []
+    entries: list[tuple[str, str, dict[str, Any] | None]] = []
+    for message in messages:
+        role = _sidechain_message_role(message)
+        content = _sidechain_message_text(message)
+        if role is None or not content:
+            continue
+        entries.append((role, content, _sidechain_entry_metadata(message)))
+    return entries
+
+
+def _sidechain_thread_entries(
+    loaded: LoadedSession, *, thread_id: str
+) -> list[SessionSidechainMessage]:
+    return [
+        item for item in loaded.sidechain_messages if item.subagent_thread_id == thread_id
+    ]
+
+
+def _sidechain_root_metadata(
+    entries: Sequence[SessionSidechainMessage],
+) -> dict[str, Any]:
+    if not entries:
+        raise RuntimeError("No sidechain messages recorded for the requested thread")
+    metadata = entries[0].metadata
+    if not isinstance(metadata, dict):
+        return {}
+    return metadata
+
+
+def _reconstruct_sidechain_message(entry: SessionSidechainMessage) -> BaseMessage:
+    metadata = entry.metadata or {}
+    sidechain_entry = metadata.get("sidechain_entry")
+    structured_content = (
+        sidechain_entry.get("structured_content")
+        if isinstance(sidechain_entry, dict)
+        else None
+    )
+    content: Any = structured_content if structured_content is not None else entry.content
+    if entry.role == "assistant":
+        tool_calls = (
+            sidechain_entry.get("tool_calls")
+            if isinstance(sidechain_entry, dict)
+            else None
+        )
+        if isinstance(tool_calls, list) and tool_calls:
+            return AIMessage(content=content, tool_calls=cast(Any, tool_calls))
+        return AIMessage(content=content)
+    if entry.role == "tool":
+        tool_call_id = (
+            sidechain_entry.get("tool_call_id")
+            if isinstance(sidechain_entry, dict)
+            else None
+        )
+        if not isinstance(tool_call_id, str) or not tool_call_id.strip():
+            raise RuntimeError(
+                f"Cannot resume tool sidechain message without tool_call_id for thread {entry.subagent_thread_id}"
+            )
+        return ToolMessage(content=content, tool_call_id=tool_call_id.strip())
+    if entry.role == "system":
+        return SystemMessage(content=content)
+    return HumanMessage(content=content)
+
+
+def _resume_sidechain_messages(
+    loaded: LoadedSession, *, thread_id: str
+) -> tuple[list[SessionSidechainMessage], list[BaseMessage]]:
+    entries = _sidechain_thread_entries(loaded, thread_id=thread_id)
+    if not entries:
+        raise RuntimeError(f"Unknown sidechain thread: {thread_id}")
+    return entries, [_reconstruct_sidechain_message(item) for item in entries]
+
+
+def _recorded_effective_max_turns(
+    metadata: dict[str, Any], *, fallback: int
+) -> int:
+    value = metadata.get("effective_max_turns")
+    if isinstance(value, int) and value >= 1:
+        return value
+    return fallback
+
+
+def _sidechain_message_role(message: Any) -> str | None:
+    if isinstance(message, dict):
+        role = message.get("role")
+        return str(role) if isinstance(role, str) and role else None
+    message_type = getattr(message, "type", None)
+    if isinstance(message_type, str) and message_type:
+        return "assistant" if message_type == "ai" else message_type
+    return None
+
+
+def _sidechain_message_text(message: Any) -> str:
+    if isinstance(message, dict):
+        content = message.get("content")
+    else:
+        content = getattr(message, "content", "")
+    if isinstance(content, str):
+        return content.strip()
+    if isinstance(content, list):
+        texts: list[str] = []
+        for block in content:
+            if isinstance(block, dict):
+                text = block.get("text")
+                if isinstance(text, str) and text.strip():
+                    texts.append(text.strip())
+        return "\n".join(texts).strip()
+    return str(content).strip() if content else ""
+
+
+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 _resumed_child_runtime_invocation(
+    *,
+    runtime: ToolRuntime,
+    definition: AgentDefinition,
+    thread_id: str,
+    max_turns: int,
+) -> RuntimeInvocation:
+    context = getattr(runtime, "context", None)
+    if not isinstance(context, RuntimeContext):
+        raise RuntimeError("Subagent resume requires runtime context")
+    return RuntimeInvocation(
+        context=replace(
+            context,
+            agent_name=f"{context.agent_name}-{definition.agent_type}",
+            entrypoint=f"run_subagent:{definition.agent_type}",
+        ),
+        config=_build_thread_config(thread_id=thread_id, max_turns=max_turns),
+    )
+
+
+def _resumed_fork_runtime_invocation(
+    *,
+    runtime: ToolRuntime,
+    thread_id: str,
+    max_turns: int,
+) -> RuntimeInvocation:
+    context = getattr(runtime, "context", None)
+    if not isinstance(context, RuntimeContext):
+        raise RuntimeError("Fork resume requires runtime context")
+    rendered_system_prompt = _runtime_rendered_system_prompt(runtime)
+    visible_tool_projection = _runtime_visible_tool_projection(runtime)
+    return RuntimeInvocation(
+        context=replace(
+            context,
+            agent_name=f"{context.agent_name}-fork",
+            entrypoint="run_fork",
+            rendered_system_prompt=rendered_system_prompt,
+            visible_tool_projection=visible_tool_projection,
+            tool_policy=_runtime_tool_policy(runtime),
+        ),
+        config=_build_thread_config(thread_id=thread_id, max_turns=max_turns),
+    )
+
+
+def _execute_fork_subagent(
+    *,
+    intent: str,
+    runtime: ToolRuntime,
+    max_turns: int,
+    run_id: str,
+) -> dict[str, Any]:
+    from coding_deepgent.agent_runtime_service import invoke_agent
+
+    projection = _runtime_visible_tool_projection(runtime)
+    invocation = _fork_runtime_invocation(
+        runtime=runtime,
+        max_turns=max_turns,
+        run_id=run_id,
+    )
+    source_messages = _fork_source_messages(runtime)
+    guard_message = _fork_recursion_guard(runtime=runtime, source_messages=source_messages)
+    if guard_message is not None:
+        raise RuntimeError(guard_message)
+    agent = runtime_agent_factory.create_runtime_agent(
+        RuntimeAgentBuildRequest(
+            role=RuntimeAgentRole.FORK,
+            model=build_openai_model(),
+            tools=projection.tools(),
+            system_prompt=_runtime_rendered_system_prompt(runtime),
+            middleware=_fork_middleware(runtime, projection),
+            context_schema=RuntimeContext,
+            store=runtime.store,
+            name=invocation.context.agent_name,
+        )
+    )
+    result = invoke_agent(
+        agent,
+        {"messages": _fork_payload_messages(source_messages=source_messages, intent=intent)},
+        invocation,
+    )
+    content = _final_child_text(result).strip()
+    if not content:
+        raise RuntimeError("Fork returned no assistant content")
+    return {
+        "content": content,
+        "raw_result": result,
+        "invocation": invocation,
+        "projection": projection,
+        "source_messages": source_messages,
+    }
+
+
+def _load_recorded_sidechain_thread(
+    *, runtime: ToolRuntime, thread_id: str
+) -> tuple[LoadedSession, list[SessionSidechainMessage], list[BaseMessage]]:
+    context = getattr(runtime, "context", None)
+    if not isinstance(context, RuntimeContext):
+        raise RuntimeError("Sidechain resume requires runtime context")
+    session_context = context.session_context
+    if not isinstance(session_context, SessionContext):
+        raise RuntimeError("Sidechain resume requires a recorded session context")
+    loaded = JsonlSessionStore(session_context.store_dir).load_session(
+        session_id=session_context.session_id,
+        workdir=session_context.workdir,
+    )
+    entries, messages = _resume_sidechain_messages(loaded, thread_id=thread_id)
+    return loaded, entries, messages
+
+
+def resume_subagent_task(
+    *,
+    subagent_thread_id: str,
+    runtime: ToolRuntime,
+    follow_up: str | None = None,
+) -> SubagentResult:
+    from coding_deepgent.agent_runtime_service import invoke_agent
+
+    _, entries, messages = _load_recorded_sidechain_thread(
+        runtime=runtime,
+        thread_id=subagent_thread_id,
+    )
+    agent_type = entries[0].agent_type
+    if agent_type == "fork":
+        raise ValueError("Use resume_fork_task() for fork sidechain threads")
+    definition = resolve_agent_definition(agent_type, runtime=runtime)
+    root_metadata = _sidechain_root_metadata(entries)
+    _validate_recorded_workdir(runtime=runtime, metadata=root_metadata)
+    effective_max_turns = _recorded_effective_max_turns(
+        root_metadata,
+        fallback=definition.max_turns,
+    )
+    invocation = _resumed_child_runtime_invocation(
+        runtime=runtime,
+        definition=definition,
+        thread_id=subagent_thread_id,
+        max_turns=effective_max_turns,
+    )
+    follow_up_prompt = (follow_up or DEFAULT_RESUME_FOLLOW_UP).strip()
+    agent = runtime_agent_factory.create_runtime_agent(
+        RuntimeAgentBuildRequest(
+            role=RuntimeAgentRole.SUBAGENT,
+            model=build_openai_model(model_name=definition.model_profile),
+            tools=_child_tools(definition),
+            system_prompt=_agent_system_prompt(definition=definition, context=invocation.context),
+            middleware=_child_middleware(definition),
+            context_schema=RuntimeContext,
+            store=runtime.store,
+            name=invocation.context.agent_name,
+        )
+    )
+    started_at = time.perf_counter()
+    result = invoke_agent(
+        agent,
+        {"messages": [*messages, HumanMessage(content=follow_up_prompt)]},
+        invocation,
+    )
+    content = _final_child_text(result).strip()
+    if not content:
+        raise RuntimeError("Resumed subagent returned no assistant content")
+    _record_sidechain_messages(
+        runtime=runtime,
+        agent_type=definition.agent_type,
+        child_invocation=invocation,
+        task=follow_up_prompt,
+        raw_result=result,
+        metadata=root_metadata,
+    )
+    _enqueue_agent_private_memory(
+        invocation=invocation,
+        source=f"subagent_{definition.agent_type}_resume",
+        task=follow_up_prompt,
+        content=content,
+    )
+    metrics = _result_metrics(
+        task=follow_up_prompt,
+        content=content,
+        raw_result=result,
+        duration_ms=max(0, int((time.perf_counter() - started_at) * 1000)),
+    )
+    return SubagentResult(
+        content=content,
+        agent_type=definition.agent_type,
+        tool_allowlist=definition.tool_allowlist,
+        input_tokens=metrics["input_tokens"],
+        output_tokens=metrics["output_tokens"],
+        total_tokens=metrics["total_tokens"],
+        total_duration_ms=metrics["total_duration_ms"],
+        total_tool_use_count=metrics["total_tool_use_count"],
+        plan_id=cast(Any, root_metadata.get("plan_id")) if agent_type == "verifier" else None,
+    )
+
+
+def resume_fork_task(
+    *,
+    child_thread_id: str,
+    runtime: ToolRuntime,
+    follow_up: str | None = None,
+) -> ForkResult:
+    from coding_deepgent.agent_runtime_service import invoke_agent
+
+    _, entries, messages = _load_recorded_sidechain_thread(
+        runtime=runtime,
+        thread_id=child_thread_id,
+    )
+    if entries[0].agent_type != "fork":
+        raise ValueError("Requested sidechain thread is not a fork thread")
+    root_metadata = _sidechain_root_metadata(entries)
+    _validate_recorded_workdir(runtime=runtime, metadata=root_metadata)
+    expected_prompt_fingerprint = root_metadata.get("rendered_prompt_fingerprint")
+    current_prompt_fingerprint = _fingerprint_text(_runtime_rendered_system_prompt(runtime))
+    if (
+        isinstance(expected_prompt_fingerprint, str)
+        and expected_prompt_fingerprint != current_prompt_fingerprint
+    ):
+        raise RuntimeError("Fork resume requires the same rendered system prompt fingerprint")
+    current_projection = _runtime_visible_tool_projection(runtime)
+    current_tool_pool = _tool_surface_snapshot(current_projection)
+    expected_tool_pool = root_metadata.get("tool_pool_fingerprint")
+    if isinstance(expected_tool_pool, str) and expected_tool_pool != current_tool_pool.fingerprint:
+        raise RuntimeError("Fork resume requires the same visible tool projection fingerprint")
+    effective_max_turns = _recorded_effective_max_turns(
+        root_metadata,
+        fallback=FORK_MAX_TURNS,
+    )
+    invocation = _resumed_fork_runtime_invocation(
+        runtime=runtime,
+        thread_id=child_thread_id,
+        max_turns=effective_max_turns,
+    )
+    follow_up_prompt = (follow_up or DEFAULT_FORK_RESUME_FOLLOW_UP).strip()
+    agent = runtime_agent_factory.create_runtime_agent(
+        RuntimeAgentBuildRequest(
+            role=RuntimeAgentRole.FORK,
+            model=build_openai_model(),
+            tools=current_projection.tools(),
+            system_prompt=_runtime_rendered_system_prompt(runtime),
+            middleware=_fork_middleware(runtime, current_projection),
+            context_schema=RuntimeContext,
+            store=runtime.store,
+            name=invocation.context.agent_name,
+        )
+    )
+    started_at = time.perf_counter()
+    result = invoke_agent(
+        agent,
+        {"messages": [*messages, HumanMessage(content=follow_up_prompt)]},
+        invocation,
+    )
+    content = _final_child_text(result).strip()
+    if not content:
+        raise RuntimeError("Resumed fork returned no assistant content")
+    placeholder_layout = ForkPlaceholderLayout.model_validate(
+        {
+            "version": str(root_metadata.get("placeholder_layout_version", FORK_PLACEHOLDER_LAYOUT_VERSION)),
+            "paired_tool_call_ids": [],
+            "placeholder_messages": list(root_metadata.get("placeholder_messages", []))
+            if isinstance(root_metadata.get("placeholder_messages"), list)
+            else [],
+            "replacement_state_hook": FORK_REPLACEMENT_STATE_HOOK,
+        }
+    )
+    _record_sidechain_messages(
+        runtime=runtime,
+        agent_type="fork",
+        child_invocation=invocation,
+        task=follow_up_prompt,
+        raw_result=result,
+        metadata=root_metadata,
+    )
+    _enqueue_agent_private_memory(
+        invocation=invocation,
+        source="fork_resume",
+        task=follow_up_prompt,
+        content=content,
+    )
+    metrics = _result_metrics(
+        task=follow_up_prompt,
+        content=content,
+        raw_result=result,
+        duration_ms=max(0, int((time.perf_counter() - started_at) * 1000)),
+    )
+    return ForkResult(
+        content=content,
+        fork_run_id=str(root_metadata.get("fork_run_id", "resumed")),
+        parent_thread_id=_runtime_thread_id(runtime),
+        child_thread_id=child_thread_id,
+        rendered_prompt_fingerprint=current_prompt_fingerprint,
+        tool_pool_identity=current_tool_pool,
+        placeholder_layout=placeholder_layout,
+        input_tokens=metrics["input_tokens"],
+        output_tokens=metrics["output_tokens"],
+        total_tokens=metrics["total_tokens"],
+        total_duration_ms=metrics["total_duration_ms"],
+        total_tool_use_count=metrics["total_tool_use_count"],
+    )
+
+
+def run_subagent_task(
+    *,
+    task: str,
+    agent_type: str = "general",
+    runtime: ToolRuntime | None = None,
+    plan_id: str | None = None,
+    max_turns: int | None = None,
+    run_id: str | None = None,
+    child_agent_factory: ChildAgentFactory | None = None,
+) -> SubagentResult:
+    definition = resolve_agent_definition(agent_type, runtime=runtime)
+    allowlist = definition.tool_allowlist
+    effective_max_turns = _effective_max_turns(definition, max_turns)
+    guard_message = _subagent_spawn_pressure_guard(runtime)
+    if guard_message is not None:
+        output_tokens = estimate_message_tokens([HumanMessage(content=guard_message)])
+        return SubagentResult(
+            content=guard_message,
+            agent_type=agent_type,
+            tool_allowlist=allowlist,
+            output_tokens=output_tokens,
+            total_tokens=output_tokens,
+        )
+    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,
+        )
+        started_at = time.perf_counter()
+        if child_agent_factory is None:
+            execution = _execute_child_subagent(
+                task=verifier_task,
+                runtime=runtime,
+                definition=definition,
+                max_turns=effective_max_turns,
+                run_id=run_id or plan.id,
+            )
+            content = str(execution["content"])
+            raw_result = execution["raw_result"]
+            _record_sidechain_messages(
+                runtime=runtime,
+                agent_type=definition.agent_type,
+                child_invocation=cast(RuntimeInvocation, execution["invocation"]),
+                task=verifier_task,
+                raw_result=raw_result,
+                metadata=_subagent_resume_metadata(
+                    definition=definition,
+                    runtime=runtime,
+                    requested_max_turns=max_turns,
+                    effective_max_turns=effective_max_turns,
+                    plan_id=plan.id,
+                ),
+            )
+            _enqueue_agent_private_memory(
+                invocation=cast(RuntimeInvocation, execution["invocation"]),
+                source="subagent_verifier",
+                task=verifier_task,
+                content=content,
+            )
+        else:
+            content = child_agent_factory(agent_type, allowlist)(verifier_task)
+            raw_result = {"messages": [{"role": "assistant", "content": content}]}
+        duration_ms = max(0, int((time.perf_counter() - started_at) * 1000))
+        metrics = _result_metrics(
+            task=verifier_task,
+            content=content,
+            raw_result=raw_result,
+            duration_ms=duration_ms,
+        )
+        return SubagentResult(
+            content=content,
+            agent_type=agent_type,
+            tool_allowlist=allowlist,
+            input_tokens=metrics["input_tokens"],
+            output_tokens=metrics["output_tokens"],
+            total_tokens=metrics["total_tokens"],
+            total_duration_ms=metrics["total_duration_ms"],
+            total_tool_use_count=metrics["total_tool_use_count"],
+            plan_id=plan.id,
+            plan_title=plan.title,
+            verification=plan.verification,
+            task_ids=tuple(plan.task_ids),
+        )
+    if runtime is None:
+        raise RuntimeError("General subagent requires runtime context")
+    started_at = time.perf_counter()
+    if child_agent_factory is None:
+        execution = _execute_child_subagent(
+            task=task,
+            runtime=runtime,
+            definition=definition,
+            max_turns=effective_max_turns,
+            run_id=run_id,
+        )
+        content = str(execution["content"])
+        raw_result = execution["raw_result"]
+        _record_sidechain_messages(
+            runtime=runtime,
+            agent_type=definition.agent_type,
+            child_invocation=cast(RuntimeInvocation, execution["invocation"]),
+            task=task,
+            raw_result=raw_result,
+            metadata=_subagent_resume_metadata(
+                definition=definition,
+                runtime=runtime,
+                requested_max_turns=max_turns,
+                effective_max_turns=effective_max_turns,
+            ),
+        )
+        _enqueue_agent_private_memory(
+            invocation=cast(RuntimeInvocation, execution["invocation"]),
+            source=f"subagent_{definition.agent_type}",
+            task=task,
+            content=content,
+        )
+    else:
+        content = child_agent_factory(agent_type, allowlist)(task)
+        raw_result = {"messages": [{"role": "assistant", "content": content}]}
+    duration_ms = max(0, int((time.perf_counter() - started_at) * 1000))
+    metrics = _result_metrics(
+        task=task,
+        content=content,
+        raw_result=raw_result,
+        duration_ms=duration_ms,
+    )
+    return SubagentResult(
+        content=content,
+        agent_type=agent_type,
+        tool_allowlist=allowlist,
+        input_tokens=metrics["input_tokens"],
+        output_tokens=metrics["output_tokens"],
+        total_tokens=metrics["total_tokens"],
+        total_duration_ms=metrics["total_duration_ms"],
+        total_tool_use_count=metrics["total_tool_use_count"],
+    )
+
+
+def run_fork_task(
+    *,
+    intent: str,
+    runtime: ToolRuntime,
+    max_turns: int | None = None,
+    run_id: str | None = None,
+) -> ForkResult:
+    effective_max_turns = FORK_MAX_TURNS if max_turns is None else min(max_turns, FORK_MAX_TURNS)
+    guard_message = _subagent_spawn_pressure_guard(runtime)
+    if guard_message is not None:
+        output_tokens = estimate_message_tokens([HumanMessage(content=guard_message)])
+        tool_pool_identity = _tool_surface_snapshot(_runtime_visible_tool_projection(runtime))
+        return ForkResult(
+            content=guard_message,
+            fork_run_id="blocked",
+            parent_thread_id=_runtime_thread_id(runtime),
+            child_thread_id=_runtime_thread_id(runtime),
+            rendered_prompt_fingerprint=_fingerprint_text(
+                _runtime_rendered_system_prompt(runtime)
+            ),
+            tool_pool_identity=tool_pool_identity,
+            placeholder_layout=_fork_placeholder_layout(_fork_source_messages(runtime)),
+            output_tokens=output_tokens,
+            total_tokens=output_tokens,
+        )
+
+    active_run_id = run_id or uuid.uuid4().hex[:12]
+    projection = _runtime_visible_tool_projection(runtime)
+    tool_pool_identity = _tool_surface_snapshot(projection)
+    rendered_system_prompt = _runtime_rendered_system_prompt(runtime)
+    prompt_fingerprint = _fingerprint_text(rendered_system_prompt)
+    normalized_source_messages = _normalize_fork_source_messages(
+        _fork_source_messages(runtime)
+    )
+    placeholder_layout = _fork_placeholder_layout(normalized_source_messages)
+    started_at = time.perf_counter()
+    execution = _execute_fork_subagent(
+        intent=intent,
+        runtime=runtime,
+        max_turns=effective_max_turns,
+        run_id=active_run_id,
+    )
+    content = str(execution["content"])
+    raw_result = execution["raw_result"]
+    invocation = cast(RuntimeInvocation, execution["invocation"])
+    _record_sidechain_messages(
+        runtime=runtime,
+        agent_type="fork",
+        child_invocation=invocation,
+        task=_fork_directive(intent),
+        raw_result=raw_result,
+        metadata=_fork_resume_metadata(
+            runtime=runtime,
+            run_id=active_run_id,
+            requested_max_turns=max_turns,
+            effective_max_turns=effective_max_turns,
+            tool_pool_identity=tool_pool_identity,
+            prompt_fingerprint=prompt_fingerprint,
+            placeholder_layout=placeholder_layout,
+        ),
+    )
+    _enqueue_agent_private_memory(
+        invocation=invocation,
+        source="fork",
+        task=intent,
+        content=content,
+    )
+    duration_ms = max(0, int((time.perf_counter() - started_at) * 1000))
+    metrics = _result_metrics(
+        task=intent,
+        content=content,
+        raw_result=raw_result,
+        duration_ms=duration_ms,
+    )
+    child_thread_id = str(
+        invocation.config.get("configurable", {}).get(
+            "thread_id", invocation.context.session_id
+        )
+    )
+    return ForkResult(
+        content=content,
+        fork_run_id=active_run_id,
+        parent_thread_id=_runtime_thread_id(runtime),
+        child_thread_id=child_thread_id,
+        rendered_prompt_fingerprint=prompt_fingerprint,
+        tool_pool_identity=tool_pool_identity,
+        placeholder_layout=placeholder_layout,
+        input_tokens=metrics["input_tokens"],
+        output_tokens=metrics["output_tokens"],
+        total_tokens=metrics["total_tokens"],
+        total_duration_ms=metrics["total_duration_ms"],
+        total_tool_use_count=metrics["total_tool_use_count"],
+    )
+
+
+def _subagent_spawn_pressure_guard(runtime: ToolRuntime | None) -> str | None:
+    if runtime is None:
+        return None
+    context = getattr(runtime, "context", None)
+    if not isinstance(context, RuntimeContext):
+        return None
+    context_window = context.model_context_window_tokens
+    guard_ratio = context.subagent_spawn_guard_ratio
+    if context_window is None or guard_ratio is None or context_window < 1:
+        return None
+    state = getattr(runtime, "state", None)
+    if not isinstance(state, dict):
+        return None
+    messages = state.get("messages")
+    if not isinstance(messages, list) or not all(
+        isinstance(message, BaseMessage) for message in messages
+    ):
+        return None
+    estimated_tokens = estimate_message_tokens(messages)
+    ratio = estimated_tokens / context_window
+    if ratio < guard_ratio:
+        return None
+    ratio_percent = int(ratio * 100)
+    guard_percent = int(guard_ratio * 100)
+    message = (
+        "Subagent spawn blocked: current context pressure is "
+        f"{ratio_percent}% of the configured model window, above the "
+        f"{guard_percent}% guard threshold. Collapse or compact context first."
+    )
+    event = RuntimeEvent(
+        kind="subagent_spawn_guard",
+        message=message,
+        session_id=context.session_id,
+        metadata={
+            "source": "runtime_pressure",
+            "strategy": "spawn_guard",
+            "estimated_token_count": estimated_tokens,
+            "context_window_tokens": context_window,
+            "estimated_token_ratio_percent": ratio_percent,
+            "trigger": "pressure_ratio",
+        },
+    )
+    context.event_sink.emit(event)
+    append_runtime_event_evidence(context=context, event=event)
+    return message
+
+
+@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 = 25,
+) -> str:
+    """Run one bounded synchronous subagent task."""
+    result = run_subagent_task(
+        task=task,
+        runtime=runtime,
+        agent_type=agent_type,
+        plan_id=plan_id,
+        max_turns=max_turns,
+    )
+    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,
+            input_tokens=result.input_tokens,
+            output_tokens=result.output_tokens,
+            total_tokens=result.total_tokens,
+            total_duration_ms=result.total_duration_ms,
+            total_tool_use_count=result.total_tool_use_count,
+        ).model_dump_json()
+    return SubagentResultEnvelope(
+        agent_type=result.agent_type,
+        content=result.content,
+        tool_allowlist=list(result.tool_allowlist),
+        input_tokens=result.input_tokens,
+        output_tokens=result.output_tokens,
+        total_tokens=result.total_tokens,
+        total_duration_ms=result.total_duration_ms,
+        total_tool_use_count=result.total_tool_use_count,
+    ).model_dump_json()
+
+
+@tool(
+    "run_fork",
+    args_schema=RunForkInput,
+    description="Fork the current same-config conversation into a sibling branch with inherited prompt and visible tools.",
+)
+def run_fork(
+    intent: str,
+    runtime: ToolRuntime,
+    background: bool = False,
+    max_turns: int = 25,
+) -> str:
+    """Run one bounded same-config sibling fork."""
+    if background:
+        from coding_deepgent.subagents.background import BACKGROUND_SUBAGENT_MANAGER
+
+        return BACKGROUND_SUBAGENT_MANAGER.start_fork(
+            intent=intent,
+            runtime=runtime,
+            max_turns=max_turns,
+        ).model_dump_json()
+    result = run_fork_task(
+        intent=intent,
+        runtime=runtime,
+        max_turns=max_turns,
+    )
+    return ForkResultEnvelope(
+        content=result.content,
+        fork_run_id=result.fork_run_id,
+        parent_thread_id=result.parent_thread_id,
+        child_thread_id=result.child_thread_id,
+        rendered_prompt_fingerprint=result.rendered_prompt_fingerprint,
+        tool_pool_identity=result.tool_pool_identity,
+        placeholder_layout=result.placeholder_layout,
+        input_tokens=result.input_tokens,
+        output_tokens=result.output_tokens,
+        total_tokens=result.total_tokens,
+        total_duration_ms=result.total_duration_ms,
+        total_tool_use_count=result.total_tool_use_count,
+    ).model_dump_json()
+
+
+@tool(
+    "resume_subagent",
+    args_schema=ResumeSubagentInput,
+    description="Resume one recorded subagent sidechain thread by exact thread id.",
+)
+def resume_subagent(
+    subagent_thread_id: str,
+    runtime: ToolRuntime,
+    follow_up: str | None = None,
+) -> str:
+    """Resume one previously recorded child subagent thread."""
+    result = resume_subagent_task(
+        subagent_thread_id=subagent_thread_id,
+        runtime=runtime,
+        follow_up=follow_up,
+    )
+    return SubagentResultEnvelope(
+        agent_type=result.agent_type,
+        content=result.content,
+        tool_allowlist=list(result.tool_allowlist),
+        input_tokens=result.input_tokens,
+        output_tokens=result.output_tokens,
+        total_tokens=result.total_tokens,
+        total_duration_ms=result.total_duration_ms,
+        total_tool_use_count=result.total_tool_use_count,
+    ).model_dump_json()
+
+
+@tool(
+    "resume_fork",
+    args_schema=ResumeForkInput,
+    description="Resume one recorded fork child thread by exact child thread id.",
+)
+def resume_fork(
+    child_thread_id: str,
+    runtime: ToolRuntime,
+    follow_up: str | None = None,
+) -> str:
+    """Resume one previously recorded fork child thread."""
+    result = resume_fork_task(
+        child_thread_id=child_thread_id,
+        runtime=runtime,
+        follow_up=follow_up,
+    )
+    return ForkResultEnvelope(
+        content=result.content,
+        fork_run_id=result.fork_run_id,
+        parent_thread_id=result.parent_thread_id,
+        child_thread_id=result.child_thread_id,
+        rendered_prompt_fingerprint=result.rendered_prompt_fingerprint,
+        tool_pool_identity=result.tool_pool_identity,
+        placeholder_layout=result.placeholder_layout,
+        input_tokens=result.input_tokens,
+        output_tokens=result.output_tokens,
+        total_tokens=result.total_tokens,
+        total_duration_ms=result.total_duration_ms,
+        total_tool_use_count=result.total_tool_use_count,
+    ).model_dump_json()
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..54fcab88d
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/tasks/__init__.py
@@ -0,0 +1,60 @@
+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_plans,
+    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_plans",
+    "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..0a312d331
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/tasks/store.py
@@ -0,0 +1,263 @@
+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 list_plans(store: TaskStore) -> list[PlanArtifact]:
+    records = [
+        PlanArtifact.model_validate(_item_value(item))
+        for item in store.search(plan_namespace())
+    ]
+    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/teams/__init__.py b/coding-deepgent/src/coding_deepgent/teams/__init__.py
new file mode 100644
index 000000000..e82c40813
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/teams/__init__.py
@@ -0,0 +1,21 @@
+from .store import (
+    TEAM_NAMESPACE,
+    TeamRun,
+    assign_worker,
+    complete_team,
+    create_team,
+    get_team,
+    list_teams,
+    update_progress,
+)
+
+__all__ = [
+    "TEAM_NAMESPACE",
+    "TeamRun",
+    "assign_worker",
+    "complete_team",
+    "create_team",
+    "get_team",
+    "list_teams",
+    "update_progress",
+]
diff --git a/coding-deepgent/src/coding_deepgent/teams/store.py b/coding-deepgent/src/coding_deepgent/teams/store.py
new file mode 100644
index 000000000..25233d73d
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/teams/store.py
@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from datetime import UTC, datetime
+from hashlib import sha256
+from typing import Any, Literal, Protocol
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from coding_deepgent.event_stream import append_event
+
+TEAM_NAMESPACE = ("coding_deepgent_teams",)
+TeamStatus = Literal["planning", "running", "completed", "cancelled"]
+
+
+class TeamStore(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]: ...
+
+
+class TeamRun(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    team_id: str
+    title: str = Field(..., min_length=1)
+    coordinator: str = Field(default="coordinator", min_length=1)
+    status: TeamStatus = "planning"
+    worker_ids: list[str] = Field(default_factory=list)
+    task_ids: list[str] = Field(default_factory=list)
+    progress: list[str] = Field(default_factory=list)
+    summary: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    created_at: str
+    updated_at: str
+
+
+def create_team(
+    store: TeamStore,
+    *,
+    title: str,
+    coordinator: str = "coordinator",
+    task_ids: list[str] | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> TeamRun:
+    now = _now()
+    team = TeamRun(
+        team_id=_team_id(title=title, created_at=now),
+        title=title.strip(),
+        coordinator=coordinator.strip(),
+        task_ids=task_ids or [],
+        metadata=metadata or {},
+        created_at=now,
+        updated_at=now,
+    )
+    return _save(store, team, event_kind="team_created")
+
+
+def get_team(store: TeamStore, team_id: str) -> TeamRun:
+    item = store.get(TEAM_NAMESPACE, team_id)
+    if item is None:
+        raise KeyError(f"Unknown team: {team_id}")
+    return TeamRun.model_validate(_item_value(item))
+
+
+def list_teams(store: TeamStore) -> list[TeamRun]:
+    return sorted(
+        [TeamRun.model_validate(_item_value(item)) for item in store.search(TEAM_NAMESPACE)],
+        key=lambda team: team.team_id,
+    )
+
+
+def assign_worker(store: TeamStore, *, team_id: str, worker_id: str) -> TeamRun:
+    team = get_team(store, team_id)
+    workers = team.worker_ids if worker_id in team.worker_ids else [*team.worker_ids, worker_id]
+    return _save(
+        store,
+        team.model_copy(
+            update={"worker_ids": workers, "status": "running", "updated_at": _now()}
+        ),
+        event_kind="team_worker_assigned",
+    )
+
+
+def update_progress(store: TeamStore, *, team_id: str, message: str) -> TeamRun:
+    team = get_team(store, team_id)
+    return _save(
+        store,
+        team.model_copy(
+            update={"progress": [*team.progress, message.strip()], "updated_at": _now()}
+        ),
+        event_kind="team_progress",
+    )
+
+
+def complete_team(
+    store: TeamStore,
+    *,
+    team_id: str,
+    summary: str,
+    status: TeamStatus = "completed",
+) -> TeamRun:
+    if status not in {"completed", "cancelled"}:
+        raise ValueError("team completion status must be completed or cancelled")
+    team = get_team(store, team_id)
+    return _save(
+        store,
+        team.model_copy(
+            update={"status": status, "summary": summary.strip(), "updated_at": _now()}
+        ),
+        event_kind=f"team_{status}",
+    )
+
+
+def _save(store: TeamStore, team: TeamRun, *, event_kind: str) -> TeamRun:
+    store.put(TEAM_NAMESPACE, team.team_id, team.model_dump())
+    append_event(
+        store,
+        stream_id=f"team:{team.team_id}",
+        kind=event_kind,
+        payload={"team_id": team.team_id, "status": team.status},
+    )
+    return team
+
+
+def _item_value(item: object) -> dict[str, object]:
+    value = getattr(item, "value", item)
+    return value if isinstance(value, dict) else {}
+
+
+def _team_id(*, title: str, created_at: str) -> str:
+    digest = sha256(f"{title}\0{created_at}".encode("utf-8")).hexdigest()
+    return f"team-{digest[:12]}"
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat().replace("+00:00", "Z")
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..effceaf80
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/tool_system/__init__.py
@@ -0,0 +1,27 @@
+from .capabilities import (
+    CapabilityRegistry,
+    KNOWN_TOOL_EXPOSURES,
+    TOOL_PROJECTION_EXPOSURES,
+    ToolCapability,
+    ToolPoolProjection,
+    build_builtin_capabilities,
+    build_capability_registry,
+    build_default_registry,
+)
+from .middleware import ToolGuardMiddleware
+from .policy import ToolPolicy, ToolPolicyCode, ToolPolicyDecision
+
+__all__ = [
+    "CapabilityRegistry",
+    "KNOWN_TOOL_EXPOSURES",
+    "TOOL_PROJECTION_EXPOSURES",
+    "ToolCapability",
+    "ToolPoolProjection",
+    "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..970400d50
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/tool_system/capabilities.py
@@ -0,0 +1,793 @@
+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
+
+KNOWN_TOOL_EXPOSURES = frozenset({"main", "child_only", "extension", "deferred"})
+TOOL_PROJECTION_EXPOSURES = {
+    "main": ("main", "extension"),
+    "child": ("child_only",),
+    "extension": ("extension",),
+    "deferred": ("deferred",),
+}
+
+
+@dataclass(frozen=True)
+class ToolCapability:
+    name: str
+    tool: BaseTool
+    domain: str
+    read_only: bool
+    destructive: bool
+    concurrency_safe: bool
+    source: str
+    trusted: bool
+    family: str
+    mutation: str
+    execution: str
+    exposure: str
+    rendering_result: str
+    enabled: bool = True
+    tags: tuple[str, ...] = field(default_factory=tuple)
+    persist_large_output: bool = False
+    max_inline_result_chars: int | None = None
+    microcompact_eligible: bool = False
+
+
+@dataclass(frozen=True)
+class ToolPoolProjection:
+    name: str
+    capabilities: tuple[ToolCapability, ...]
+
+    def names(self) -> list[str]:
+        return [capability.name for capability in self.capabilities]
+
+    def tools(self) -> list[BaseTool]:
+        return [capability.tool for capability in self.capabilities]
+
+    def metadata(self) -> dict[str, ToolCapability]:
+        return {capability.name: capability for capability in self.capabilities}
+
+
+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")
+        for capability in ordered:
+            _validate_capability(capability)
+
+    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 capabilities_for_exposure(
+        self,
+        *exposures: str,
+        enabled_only: bool = True,
+    ) -> tuple[ToolCapability, ...]:
+        return tuple(
+            capability
+            for capability in self._capabilities.values()
+            if (not enabled_only or capability.enabled)
+            and capability.exposure in exposures
+        )
+
+    def names_for_exposure(
+        self,
+        *exposures: str,
+        enabled_only: bool = True,
+    ) -> list[str]:
+        return [
+            capability.name
+            for capability in self.capabilities_for_exposure(
+                *exposures,
+                enabled_only=enabled_only,
+            )
+        ]
+
+    def tools_for_exposure(
+        self,
+        *exposures: str,
+        enabled_only: bool = True,
+    ) -> list[BaseTool]:
+        return [
+            capability.tool
+            for capability in self.capabilities_for_exposure(
+                *exposures,
+                enabled_only=enabled_only,
+            )
+        ]
+
+    def capabilities_for_projection(
+        self,
+        projection: str,
+        *,
+        enabled_only: bool = True,
+    ) -> tuple[ToolCapability, ...]:
+        exposures = TOOL_PROJECTION_EXPOSURES.get(projection)
+        if exposures is None:
+            raise ValueError(f"Unknown tool projection: {projection}")
+        return self.capabilities_for_exposure(*exposures, enabled_only=enabled_only)
+
+    def project(
+        self,
+        projection: str,
+        *,
+        enabled_only: bool = True,
+    ) -> ToolPoolProjection:
+        return ToolPoolProjection(
+            name=projection,
+            capabilities=self.capabilities_for_projection(
+                projection,
+                enabled_only=enabled_only,
+            ),
+        )
+
+    def names_for_projection(
+        self,
+        projection: str,
+        *,
+        enabled_only: bool = True,
+    ) -> list[str]:
+        return [
+            capability.name
+            for capability in self.capabilities_for_projection(
+                projection,
+                enabled_only=enabled_only,
+            )
+        ]
+
+    def tools_for_projection(
+        self,
+        projection: str,
+        *,
+        enabled_only: bool = True,
+    ) -> list[BaseTool]:
+        return self.project(projection, enabled_only=enabled_only).tools()
+
+    def tools_for_names(self, names: Sequence[str]) -> list[BaseTool]:
+        return [self.require(name).tool for name in names]
+
+    def main_tools(self) -> list[BaseTool]:
+        return self.tools_for_projection("main")
+
+    def main_names(self) -> list[str]:
+        return self.names_for_projection("main")
+
+    def child_names(self) -> list[str]:
+        return self.names_for_projection("child")
+
+    def declarable_names(self) -> list[str]:
+        return self.names_for_exposure("main", "extension", "deferred")
+
+    def metadata(self) -> dict[str, ToolCapability]:
+        return dict(self._capabilities)
+
+
+def _validate_capability(capability: ToolCapability) -> None:
+    tool_name = str(getattr(capability.tool, "name", type(capability.tool).__name__))
+    if capability.name != tool_name:
+        raise ValueError(
+            f"Tool capability name {capability.name!r} must match tool name {tool_name!r}"
+        )
+    for field_name in (
+        "name",
+        "domain",
+        "source",
+        "family",
+        "mutation",
+        "execution",
+        "exposure",
+        "rendering_result",
+    ):
+        value = getattr(capability, field_name)
+        if not isinstance(value, str) or not value.strip() or value == "unknown":
+            raise ValueError(
+                f"Tool capability {capability.name!r} has invalid {field_name}"
+            )
+    if capability.exposure not in KNOWN_TOOL_EXPOSURES:
+        raise ValueError(
+            f"Tool capability {capability.name!r} has invalid exposure {capability.exposure!r}"
+        )
+    if getattr(capability.tool, "args_schema", None) is None:
+        raise ValueError(f"Tool capability {capability.name!r} is missing args_schema")
+    if getattr(capability.tool, "tool_call_schema", None) is None:
+        raise ValueError(
+            f"Tool capability {capability.name!r} is missing tool_call_schema"
+        )
+    if capability.persist_large_output and (
+        capability.max_inline_result_chars is None
+        or capability.max_inline_result_chars < 1
+    ):
+        raise ValueError(
+            f"Tool capability {capability.name!r} must set max_inline_result_chars"
+        )
+    if capability.microcompact_eligible and not capability.persist_large_output:
+        raise ValueError(
+            f"Tool capability {capability.name!r} must persist output before microcompact"
+        )
+
+
+def build_default_registry(*, include_discovery: bool = False) -> CapabilityRegistry:
+    from .deferred import invoke_deferred_tool, tool_search
+
+    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=(),
+            deferred_bridge_tools=(tool_search, invoke_deferred_tool),
+            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],
+    deferred_bridge_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,
+        *deferred_bridge_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,
+            source="builtin",
+            trusted=True,
+            family="filesystem",
+            mutation="workspace_write",
+            execution="plain_tool",
+            exposure="main",
+            rendering_result="tool_message_or_persisted_output",
+            tags=("shell", "workspace"),
+            persist_large_output=True,
+            max_inline_result_chars=4000,
+            microcompact_eligible=True,
+        ),
+        ToolCapability(
+            name="read_file",
+            tool=tool_by_name["read_file"],
+            domain="filesystem",
+            read_only=True,
+            destructive=False,
+            concurrency_safe=True,
+            source="builtin",
+            trusted=True,
+            family="filesystem",
+            mutation="read",
+            execution="plain_tool",
+            exposure="main",
+            rendering_result="tool_message_or_persisted_output",
+            tags=("read", "workspace"),
+            persist_large_output=True,
+            max_inline_result_chars=4000,
+            microcompact_eligible=True,
+        ),
+        ToolCapability(
+            name="write_file",
+            tool=tool_by_name["write_file"],
+            domain="filesystem",
+            read_only=False,
+            destructive=True,
+            concurrency_safe=False,
+            source="builtin",
+            trusted=True,
+            family="filesystem",
+            mutation="workspace_write",
+            execution="plain_tool",
+            exposure="main",
+            rendering_result="tool_message",
+            tags=("write", "workspace"),
+        ),
+        ToolCapability(
+            name="edit_file",
+            tool=tool_by_name["edit_file"],
+            domain="filesystem",
+            read_only=False,
+            destructive=True,
+            concurrency_safe=False,
+            source="builtin",
+            trusted=True,
+            family="filesystem",
+            mutation="workspace_write",
+            execution="plain_tool",
+            exposure="main",
+            rendering_result="tool_message",
+            tags=("edit", "workspace"),
+        ),
+        ToolCapability(
+            name="TodoWrite",
+            tool=tool_by_name["TodoWrite"],
+            domain="todo",
+            read_only=False,
+            destructive=False,
+            concurrency_safe=False,
+            source="builtin",
+            trusted=True,
+            family="todo",
+            mutation="state_update",
+            execution="command_update",
+            exposure="main",
+            rendering_result="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,
+                source="builtin",
+                trusted=True,
+                family="filesystem",
+                mutation="read",
+                execution="plain_tool",
+                exposure="child_only",
+                rendering_result="tool_message_or_persisted_output",
+                tags=("discovery", "workspace"),
+                persist_large_output=True,
+                max_inline_result_chars=4000,
+                microcompact_eligible=True,
+            )
+        )
+    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,
+                source="builtin",
+                trusted=True,
+                family="filesystem",
+                mutation="read",
+                execution="plain_tool",
+                exposure="child_only",
+                rendering_result="tool_message_or_persisted_output",
+                tags=("discovery", "workspace"),
+                persist_large_output=True,
+                max_inline_result_chars=4000,
+                microcompact_eligible=True,
+            )
+        )
+    for tool_name, read_only, destructive, mutation in (
+        ("save_memory", False, False, "durable_store"),
+        ("list_memory", True, False, "read"),
+        ("delete_memory", False, False, "durable_store"),
+    ):
+        if tool_name in tool_by_name:
+            capabilities.append(
+                ToolCapability(
+                    name=tool_name,
+                    tool=tool_by_name[tool_name],
+                    domain="memory",
+                    family="memory",
+                    mutation=mutation,
+                    execution="plain_tool",
+                    read_only=read_only,
+                    destructive=destructive,
+                    concurrency_safe=read_only,
+                    source="builtin",
+                    trusted=True,
+                    exposure="main",
+                    rendering_result="tool_message",
+                    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",
+                rendering_result="tool_message",
+                tags=("skill",),
+            )
+        )
+    if "ToolSearch" in tool_by_name:
+        capabilities.append(
+            ToolCapability(
+                name="ToolSearch",
+                tool=tool_by_name["ToolSearch"],
+                domain="tool_system",
+                family="tool_system",
+                mutation="read",
+                execution="plain_tool",
+                read_only=True,
+                destructive=False,
+                concurrency_safe=True,
+                source="builtin",
+                trusted=True,
+                exposure="main",
+                rendering_result="tool_message",
+                tags=("tool_search", "deferred"),
+            )
+        )
+    if "invoke_deferred_tool" in tool_by_name:
+        capabilities.append(
+            ToolCapability(
+                name="invoke_deferred_tool",
+                tool=tool_by_name["invoke_deferred_tool"],
+                domain="tool_system",
+                family="tool_system",
+                mutation="orchestration",
+                execution="plain_tool",
+                read_only=False,
+                destructive=False,
+                concurrency_safe=False,
+                source="builtin",
+                trusted=True,
+                exposure="main",
+                rendering_result="tool_message",
+                tags=("tool_search", "deferred"),
+            )
+        )
+    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",
+                    rendering_result="tool_message",
+                    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",
+                    rendering_result="tool_message",
+                    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",
+                    rendering_result="tool_message",
+                    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",
+                    rendering_result="tool_message",
+                    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",
+                    rendering_result="tool_message",
+                    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",
+                    rendering_result="tool_message",
+                    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",
+                rendering_result="tool_message",
+                tags=("subagent",),
+            )
+        )
+    if "run_subagent_background" in tool_by_name:
+        capabilities.append(
+            ToolCapability(
+                name="run_subagent_background",
+                tool=tool_by_name["run_subagent_background"],
+                domain="subagents",
+                family="subagents",
+                mutation="orchestration",
+                execution="child_agent_bridge",
+                read_only=False,
+                destructive=False,
+                concurrency_safe=False,
+                source="builtin",
+                trusted=True,
+                exposure="deferred",
+                rendering_result="tool_message",
+                tags=("subagent", "background"),
+            )
+        )
+    if "subagent_status" in tool_by_name:
+        capabilities.append(
+            ToolCapability(
+                name="subagent_status",
+                tool=tool_by_name["subagent_status"],
+                domain="subagents",
+                family="subagents",
+                mutation="read",
+                execution="plain_tool",
+                read_only=True,
+                destructive=False,
+                concurrency_safe=True,
+                source="builtin",
+                trusted=True,
+                exposure="deferred",
+                rendering_result="tool_message",
+                tags=("subagent", "background", "read"),
+            )
+        )
+    if "subagent_list" in tool_by_name:
+        capabilities.append(
+            ToolCapability(
+                name="subagent_list",
+                tool=tool_by_name["subagent_list"],
+                domain="subagents",
+                family="subagents",
+                mutation="read",
+                execution="plain_tool",
+                read_only=True,
+                destructive=False,
+                concurrency_safe=True,
+                source="builtin",
+                trusted=True,
+                exposure="deferred",
+                rendering_result="tool_message",
+                tags=("subagent", "background", "read", "list"),
+            )
+        )
+    if "subagent_send_input" in tool_by_name:
+        capabilities.append(
+            ToolCapability(
+                name="subagent_send_input",
+                tool=tool_by_name["subagent_send_input"],
+                domain="subagents",
+                family="subagents",
+                mutation="orchestration",
+                execution="plain_tool",
+                read_only=False,
+                destructive=False,
+                concurrency_safe=False,
+                source="builtin",
+                trusted=True,
+                exposure="deferred",
+                rendering_result="tool_message",
+                tags=("subagent", "background"),
+            )
+        )
+    if "subagent_stop" in tool_by_name:
+        capabilities.append(
+            ToolCapability(
+                name="subagent_stop",
+                tool=tool_by_name["subagent_stop"],
+                domain="subagents",
+                family="subagents",
+                mutation="orchestration",
+                execution="plain_tool",
+                read_only=False,
+                destructive=False,
+                concurrency_safe=False,
+                source="builtin",
+                trusted=True,
+                exposure="deferred",
+                rendering_result="tool_message",
+                tags=("subagent", "background"),
+            )
+        )
+    if "resume_subagent" in tool_by_name:
+        capabilities.append(
+            ToolCapability(
+                name="resume_subagent",
+                tool=tool_by_name["resume_subagent"],
+                domain="subagents",
+                family="subagents",
+                mutation="orchestration",
+                execution="child_agent_bridge",
+                read_only=False,
+                destructive=False,
+                concurrency_safe=False,
+                source="builtin",
+                trusted=True,
+                exposure="deferred",
+                rendering_result="tool_message",
+                tags=("subagent", "resume"),
+            )
+        )
+    if "resume_fork" in tool_by_name:
+        capabilities.append(
+            ToolCapability(
+                name="resume_fork",
+                tool=tool_by_name["resume_fork"],
+                domain="subagents",
+                family="subagents",
+                mutation="orchestration",
+                execution="fork_bridge",
+                read_only=False,
+                destructive=False,
+                concurrency_safe=False,
+                source="builtin",
+                trusted=True,
+                exposure="deferred",
+                rendering_result="tool_message",
+                tags=("subagent", "fork", "resume"),
+            )
+        )
+    if "run_fork" in tool_by_name:
+        capabilities.append(
+            ToolCapability(
+                name="run_fork",
+                tool=tool_by_name["run_fork"],
+                domain="subagents",
+                family="subagents",
+                mutation="orchestration",
+                execution="fork_bridge",
+                read_only=False,
+                destructive=False,
+                concurrency_safe=False,
+                source="builtin",
+                trusted=True,
+                exposure="main",
+                rendering_result="tool_message",
+                tags=("subagent", "fork"),
+            )
+        )
+    return tuple(capabilities)
diff --git a/coding-deepgent/src/coding_deepgent/tool_system/deferred.py b/coding-deepgent/src/coding_deepgent/tool_system/deferred.py
new file mode 100644
index 000000000..a72b5d9c1
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/tool_system/deferred.py
@@ -0,0 +1,349 @@
+from __future__ import annotations
+
+import inspect
+import json
+import re
+from collections.abc import Mapping
+from typing import Any, cast
+
+from langchain.messages import ToolMessage
+from langchain.tools import ToolRuntime, tool
+from langchain.tools.tool_node import ToolCallRequest
+from langgraph.types import Command
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from .capabilities import CapabilityRegistry, ToolCapability
+from .middleware import ToolGuardMiddleware
+from .policy import ToolPolicy
+
+_WORD_SPLIT = re.compile(r"[\W_]+")
+
+
+class ToolSearchInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    query: str = Field(
+        ...,
+        min_length=1,
+        description=(
+            "Search deferred tools by exact name or keywords. Use "
+            "`select:<tool_name>` or `select:<tool_a>,<tool_b>` for exact selection."
+        ),
+    )
+    max_results: int = Field(
+        default=5,
+        ge=1,
+        le=20,
+        description="Maximum deferred-tool matches to return.",
+    )
+
+    @field_validator("query")
+    @classmethod
+    def _query_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("query required")
+        return value
+
+
+class DeferredToolMatch(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(..., min_length=1)
+    description: str = Field(..., min_length=1)
+    source: str = Field(..., min_length=1)
+    execution: str = Field(..., min_length=1)
+    rendering_result: str = Field(..., min_length=1)
+    tags: list[str] = Field(default_factory=list)
+    parameters: dict[str, Any] = Field(default_factory=dict)
+    call_via: str = Field(..., min_length=1)
+
+
+class ToolSearchResult(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    query: str = Field(..., min_length=1)
+    total_deferred_tools: int = Field(..., ge=0)
+    matches: list[DeferredToolMatch] = Field(default_factory=list)
+
+
+class InvokeDeferredToolInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    tool_name: str = Field(
+        ...,
+        min_length=1,
+        description=(
+            "Exact deferred tool name returned by ToolSearch. "
+            "Only tools on the deferred surface are allowed."
+        ),
+    )
+    arguments: dict[str, Any] = Field(
+        default_factory=dict,
+        description="JSON object matching the deferred tool's parameters schema exactly.",
+    )
+    runtime: ToolRuntime
+
+    @field_validator("tool_name")
+    @classmethod
+    def _tool_name_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("tool_name required")
+        return value
+
+
+def _runtime_policy(runtime: ToolRuntime) -> ToolPolicy:
+    context = getattr(runtime, "context", None)
+    policy = getattr(context, "tool_policy", None)
+    if not isinstance(policy, ToolPolicy):
+        raise RuntimeError("Deferred tool bridge requires tool policy in runtime context")
+    return policy
+
+
+def _runtime_registry(runtime: ToolRuntime) -> CapabilityRegistry:
+    registry = _runtime_policy(runtime).registry
+    if not isinstance(registry, CapabilityRegistry):
+        raise RuntimeError("Deferred tool bridge requires capability registry access")
+    return registry
+
+
+def _deferred_capabilities(
+    registry: CapabilityRegistry,
+) -> tuple[ToolCapability, ...]:
+    return registry.capabilities_for_projection("deferred")
+
+
+def _normalize_search_tokens(value: str) -> tuple[str, ...]:
+    camel_split = re.sub(r"([a-z0-9])([A-Z])", r"\1 \2", value)
+    pieces = _WORD_SPLIT.split(camel_split.lower())
+    return tuple(piece for piece in pieces if piece)
+
+
+def _searchable_text(capability: ToolCapability) -> str:
+    description = str(getattr(capability.tool, "description", "") or "")
+    return " ".join(
+        (
+            capability.name,
+            description,
+            capability.source,
+            capability.domain,
+            capability.family,
+            capability.execution,
+            capability.rendering_result,
+            *capability.tags,
+        )
+    ).lower()
+
+
+def _search_score(capability: ToolCapability, terms: tuple[str, ...]) -> int:
+    searchable = _searchable_text(capability)
+    name_lower = capability.name.lower()
+    name_tokens = set(_normalize_search_tokens(capability.name))
+    score = 0
+    for term in terms:
+        if term == name_lower:
+            score += 100
+            continue
+        if name_lower.startswith(term):
+            score += 60
+            continue
+        if term in name_tokens:
+            score += 40
+            continue
+        if term in searchable:
+            score += 20
+            continue
+        return -1
+    return score
+
+
+def _selected_deferred_capabilities(
+    registry: CapabilityRegistry,
+    *,
+    query: str,
+    max_results: int,
+) -> tuple[ToolCapability, ...]:
+    deferred = _deferred_capabilities(registry)
+    query = query.strip()
+    lowered = query.lower()
+    if lowered.startswith("select:"):
+        requested = [
+            item.strip().lower()
+            for item in query.split(":", 1)[1].split(",")
+            if item.strip()
+        ]
+        selected: list[ToolCapability] = []
+        for tool_name in requested:
+            for capability in deferred:
+                if capability.name.lower() == tool_name:
+                    selected.append(capability)
+                    break
+        return tuple(selected[:max_results])
+
+    terms = tuple(term for term in _normalize_search_tokens(query) if term)
+    if not terms:
+        return ()
+
+    scored = [
+        (capability, _search_score(capability, terms))
+        for capability in deferred
+    ]
+    ranked = [
+        capability
+        for capability, score in sorted(
+            scored,
+            key=lambda item: (-item[1], item[0].name),
+        )
+        if score >= 0
+    ]
+    return tuple(ranked[:max_results])
+
+
+def _tool_parameters(capability: ToolCapability) -> dict[str, Any]:
+    schema = cast(Any, capability.tool.tool_call_schema)
+    return cast(dict[str, Any], schema.model_json_schema())
+
+
+def _render_match(capability: ToolCapability) -> DeferredToolMatch:
+    description = str(getattr(capability.tool, "description", "") or "").strip()
+    return DeferredToolMatch(
+        name=capability.name,
+        description=description or capability.name,
+        source=capability.source,
+        execution=capability.execution,
+        rendering_result=capability.rendering_result,
+        tags=list(capability.tags),
+        parameters=_tool_parameters(capability),
+        call_via=(
+            "invoke_deferred_tool(tool_name=<name>, arguments=<json object matching parameters>)"
+        ),
+    )
+
+
+@tool(
+    "ToolSearch",
+    args_schema=ToolSearchInput,
+    description=(
+        "Search deferred tools and return their full JSON parameter schemas. "
+        "Use this before invoke_deferred_tool when the current visible tool list "
+        "does not expose the needed advanced or extension capability."
+    ),
+)
+def tool_search(
+    query: str,
+    runtime: ToolRuntime,
+    max_results: int = 5,
+) -> str:
+    registry = _runtime_registry(runtime)
+    matches = _selected_deferred_capabilities(
+        registry,
+        query=query,
+        max_results=max_results,
+    )
+    return ToolSearchResult(
+        query=query,
+        total_deferred_tools=len(_deferred_capabilities(registry)),
+        matches=[_render_match(capability) for capability in matches],
+    ).model_dump_json()
+
+
+def _validated_deferred_args(
+    capability: ToolCapability,
+    arguments: Mapping[str, Any],
+) -> dict[str, Any]:
+    schema = cast(Any, capability.tool.tool_call_schema)
+    validated = schema.model_validate(dict(arguments))
+    return cast(dict[str, Any], validated.model_dump())
+
+
+def _call_tool_function(
+    capability: ToolCapability,
+    *,
+    runtime: ToolRuntime,
+    arguments: dict[str, Any],
+) -> ToolMessage | Command[Any]:
+    tool_object = capability.tool
+    tool_func = getattr(tool_object, "func", None)
+    if callable(tool_func):
+        kwargs = dict(arguments)
+        if "runtime" in inspect.signature(tool_func).parameters:
+            kwargs["runtime"] = runtime
+        result = tool_func(**kwargs)
+    else:
+        result = tool_object.invoke(arguments)
+    if isinstance(result, (ToolMessage, Command)):
+        return result
+    rendered = result if isinstance(result, str) else json.dumps(result)
+    return ToolMessage(
+        content=rendered,
+        tool_call_id=str(getattr(runtime, "tool_call_id", "") or ""),
+    )
+
+
+def _execute_deferred_capability(
+    request: ToolCallRequest,
+    capability: ToolCapability,
+) -> ToolMessage | Command[Any]:
+    validated_args = _validated_deferred_args(
+        capability,
+        cast(Mapping[str, Any], request.tool_call.get("args", {})),
+    )
+    return _call_tool_function(
+        capability,
+        runtime=request.runtime,
+        arguments=validated_args,
+    )
+
+
+@tool(
+    "invoke_deferred_tool",
+    args_schema=InvokeDeferredToolInput,
+    description=(
+        "Execute one deferred tool by exact name. Use ToolSearch first, then pass "
+        "arguments that exactly match the deferred tool's parameters schema."
+    ),
+)
+def invoke_deferred_tool(
+    tool_name: str,
+    arguments: dict[str, Any],
+    runtime: ToolRuntime,
+) -> ToolMessage | Command[Any]:
+    registry = _runtime_registry(runtime)
+    capability = registry.get(tool_name)
+    if capability is None or capability.exposure != "deferred" or not capability.enabled:
+        return ToolMessage(
+            content=f"Error: Unknown deferred tool `{tool_name}`.",
+            tool_call_id=str(getattr(runtime, "tool_call_id", "") or ""),
+            status="error",
+        )
+
+    tool_policy = _runtime_policy(runtime)
+    context = getattr(runtime, "context", None)
+    middleware = ToolGuardMiddleware(
+        registry=registry,
+        policy=tool_policy,
+        event_sink=getattr(context, "event_sink", None),
+    )
+    tool_call = {
+        "name": capability.name,
+        "args": dict(arguments),
+        "id": str(getattr(runtime, "tool_call_id", "") or f"deferred:{capability.name}"),
+        "type": "tool_call",
+    }
+    request = ToolCallRequest(
+        tool_call=cast(Any, tool_call),
+        tool=capability.tool,
+        state=getattr(runtime, "state", None),
+        runtime=runtime,
+    )
+    result = middleware.wrap_tool_call(
+        request,
+        lambda current_request: _execute_deferred_capability(
+            current_request,
+            capability,
+        ),
+    )
+    if isinstance(result, Command):
+        return result
+    return result
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..e662952a4
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/tool_system/middleware.py
@@ -0,0 +1,393 @@
+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, interrupt
+
+from coding_deepgent.compact.tool_results import maybe_persist_large_tool_result
+from coding_deepgent.hooks.dispatcher import dispatch_context_hook
+from coding_deepgent.hooks.events import HookEventName
+from coding_deepgent.memory import evaluate_feedback_enforcement
+from coding_deepgent.memory.runtime_support import (
+    runtime_agent_scope,
+    runtime_memory_service,
+    runtime_project_scope,
+)
+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]:
+        feedback_decision = evaluate_feedback_enforcement(
+            store=getattr(request.runtime, "store", None),
+            service=runtime_memory_service(request.runtime),
+            project_scope=runtime_project_scope(request.runtime),
+            agent_scope=runtime_agent_scope(request.runtime),
+            tool_name=str(request.tool_call["name"]),
+            args=dict(request.tool_call.get("args", {})),
+        )
+        if feedback_decision.blocked:
+            feedback_result = ToolMessage(
+                content=feedback_decision.message,
+                tool_call_id=str(request.tool_call.get("id") or ""),
+                status="error",
+            )
+            feedback_policy = ToolPolicyDecision(
+                allowed=False,
+                code=ToolPolicyCode.PERMISSION_DENIED,
+                message=feedback_decision.message,
+                behavior="deny",
+            )
+            self._emit(
+                request=request,
+                phase="feedback_blocked",
+                decision=feedback_policy,
+                result=feedback_result,
+            )
+            self._dispatch_hook(
+                request=request,
+                event="PermissionDenied",
+                data={
+                    "tool": str(request.tool_call["name"]),
+                    "policy_code": "feedback_blocked",
+                    "message": feedback_decision.message,
+                    "matched_rule": feedback_decision.matched_rule or "",
+                },
+            )
+            return feedback_result
+
+        decision = self.policy.evaluate(request.tool_call)
+        tool_call_id = request.tool_call.get("id")
+
+        if not decision.allowed:
+            if (
+                decision.code == ToolPolicyCode.PERMISSION_REQUIRED
+                and _frontend_hitl_enabled(request.runtime)
+            ):
+                resolution = interrupt(
+                    _permission_interrupt_payload(request=request, decision=decision)
+                )
+                return self._handle_permission_interrupt_resolution(
+                    request=request,
+                    decision=decision,
+                    tool_call_id=str(tool_call_id or ""),
+                    resolution=resolution,
+                    handler=handler,
+                )
+            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",
+            )
+
+        return self._execute_allowed_tool_call(
+            request=request,
+            decision=decision,
+            tool_call_id=str(tool_call_id or ""),
+            handler=handler,
+        )
+
+    def _execute_allowed_tool_call(
+        self,
+        *,
+        request: ToolCallRequest,
+        decision: ToolPolicyDecision,
+        tool_call_id: str,
+        handler: Callable[[ToolCallRequest], ToolMessage | Command[Any]],
+    ) -> ToolMessage | Command[Any]:
+        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=tool_call_id,
+                status="error",
+            )
+
+        self._emit(request=request, phase="allowed", decision=decision)
+        try:
+            result = handler(request)
+        except Exception as exc:
+            failure = ToolMessage(
+                content=_bounded_tool_failure_message(exc),
+                tool_call_id=str(tool_call_id or ""),
+                status="error",
+            )
+            self._emit(
+                request=request,
+                phase="failed",
+                decision=decision,
+                result=failure,
+            )
+            return failure
+        result = self._process_tool_result(request=request, result=result)
+        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 _handle_permission_interrupt_resolution(
+        self,
+        *,
+        request: ToolCallRequest,
+        decision: ToolPolicyDecision,
+        tool_call_id: str,
+        resolution: Any,
+        handler: Callable[[ToolCallRequest], ToolMessage | Command[Any]],
+    ) -> ToolMessage | Command[Any]:
+        approve, message = _normalize_permission_resolution(
+            resolution,
+            tool_name=str(request.tool_call["name"]),
+        )
+        if approve:
+            return self._execute_allowed_tool_call(
+                request=request,
+                decision=decision,
+                tool_call_id=tool_call_id,
+                handler=handler,
+            )
+
+        rejected = ToolMessage(
+            content=message or f"User rejected `{request.tool_call['name']}`",
+            tool_call_id=tool_call_id,
+            status="error",
+        )
+        self._emit(
+            request=request,
+            phase="permission_denied",
+            decision=decision,
+            result=rejected,
+        )
+        self._dispatch_hook(
+            request=request,
+            event="PermissionDenied",
+            data={
+                "tool": str(request.tool_call["name"]),
+                "policy_code": decision.code.value,
+                "message": str(rejected.content),
+            },
+        )
+        return rejected
+
+    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 _process_tool_result(
+        self,
+        *,
+        request: ToolCallRequest,
+        result: ToolMessage | Command[Any],
+    ) -> ToolMessage | Command[Any]:
+        if not isinstance(result, ToolMessage):
+            return result
+        capability = self.registry.get(str(request.tool_call["name"]))
+        if capability is None or not capability.persist_large_output:
+            return result
+        context = getattr(request.runtime, "context", None)
+        if context is None:
+            return result
+        try:
+            return maybe_persist_large_tool_result(
+                result,
+                runtime_context=context,
+                max_inline_chars=capability.max_inline_result_chars,
+            )
+        except OSError:
+            return result
+
+
+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
+
+
+def _bounded_tool_failure_message(error: Exception) -> str:
+    detail = " ".join(str(error).split()).strip()
+    if detail:
+        detail = detail[:240]
+        return f"Error: {type(error).__name__}: {detail}"
+    return f"Error: {type(error).__name__}"
+
+
+def _frontend_hitl_enabled(runtime: object) -> bool:
+    context = getattr(runtime, "context", None)
+    entrypoint = getattr(context, "entrypoint", "")
+    return isinstance(entrypoint, str) and entrypoint.startswith(
+        "coding-deepgent-frontend"
+    )
+
+
+def _permission_interrupt_payload(
+    *,
+    request: ToolCallRequest,
+    decision: ToolPolicyDecision,
+) -> dict[str, object]:
+    return {
+        "kind": "permission_request",
+        "tool": str(request.tool_call["name"]),
+        "description": decision.message,
+        "options": ["approve", "reject"],
+    }
+
+
+def _normalize_permission_resolution(
+    resolution: Any,
+    *,
+    tool_name: str,
+) -> tuple[bool, str | None]:
+    if isinstance(resolution, bool):
+        return resolution, None
+    if isinstance(resolution, str):
+        normalized = resolution.strip().lower()
+        if normalized in {"approve", "approved", "allow", "allowed", "true"}:
+            return True, None
+        if normalized in {"reject", "rejected", "deny", "denied", "false"}:
+            return False, f"User rejected `{tool_name}`"
+    if isinstance(resolution, dict):
+        decision = str(
+            resolution.get("decision", resolution.get("type", "reject"))
+        ).strip().lower()
+        message = resolution.get("message")
+        normalized_message = message if isinstance(message, str) and message else None
+        if decision == "approve":
+            return True, normalized_message
+        if decision == "reject":
+            return False, normalized_message or f"User rejected `{tool_name}`"
+    raise ValueError(f"Unsupported permission resolution payload for `{tool_name}`")
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/src/coding_deepgent/worker_runtime/__init__.py b/coding-deepgent/src/coding_deepgent/worker_runtime/__init__.py
new file mode 100644
index 000000000..6104960f2
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/worker_runtime/__init__.py
@@ -0,0 +1,21 @@
+from .store import (
+    WORKER_NAMESPACE,
+    WorkerRecord,
+    complete_worker,
+    create_worker,
+    get_worker,
+    heartbeat_worker,
+    list_workers,
+    request_worker_stop,
+)
+
+__all__ = [
+    "WORKER_NAMESPACE",
+    "WorkerRecord",
+    "complete_worker",
+    "create_worker",
+    "get_worker",
+    "heartbeat_worker",
+    "list_workers",
+    "request_worker_stop",
+]
diff --git a/coding-deepgent/src/coding_deepgent/worker_runtime/store.py b/coding-deepgent/src/coding_deepgent/worker_runtime/store.py
new file mode 100644
index 000000000..5efdc4336
--- /dev/null
+++ b/coding-deepgent/src/coding_deepgent/worker_runtime/store.py
@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from datetime import UTC, datetime
+from hashlib import sha256
+from typing import Any, Literal, Protocol
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from coding_deepgent.event_stream import append_event
+
+WORKER_NAMESPACE = ("coding_deepgent_workers",)
+WorkerStatus = Literal["queued", "running", "idle", "completed", "failed", "cancelled"]
+
+
+class WorkerStore(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]: ...
+
+
+class WorkerRecord(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    worker_id: str
+    kind: str = Field(default="local", min_length=1)
+    session_id: str = Field(default="default", min_length=1)
+    status: WorkerStatus = "queued"
+    owner: str | None = None
+    payload: dict[str, Any] = Field(default_factory=dict)
+    result_summary: str | None = None
+    stop_requested: bool = False
+    created_at: str
+    updated_at: str
+    heartbeat_at: str | None = None
+
+
+def create_worker(
+    store: WorkerStore,
+    *,
+    kind: str,
+    session_id: str = "default",
+    owner: str | None = None,
+    payload: dict[str, Any] | None = None,
+) -> WorkerRecord:
+    now = _now()
+    worker_id = _worker_id(kind=kind, session_id=session_id, created_at=now)
+    record = WorkerRecord(
+        worker_id=worker_id,
+        kind=kind.strip(),
+        session_id=session_id.strip() or "default",
+        owner=owner,
+        payload=payload or {},
+        created_at=now,
+        updated_at=now,
+    )
+    return _save(store, record, event_kind="worker_created")
+
+
+def get_worker(store: WorkerStore, worker_id: str) -> WorkerRecord:
+    item = store.get(WORKER_NAMESPACE, worker_id)
+    if item is None:
+        raise KeyError(f"Unknown worker: {worker_id}")
+    return WorkerRecord.model_validate(_item_value(item))
+
+
+def list_workers(
+    store: WorkerStore,
+    *,
+    include_terminal: bool = False,
+) -> list[WorkerRecord]:
+    records = [
+        WorkerRecord.model_validate(_item_value(item))
+        for item in store.search(WORKER_NAMESPACE)
+    ]
+    if not include_terminal:
+        records = [
+            record
+            for record in records
+            if record.status not in {"completed", "failed", "cancelled"}
+        ]
+    return sorted(records, key=lambda record: record.worker_id)
+
+
+def heartbeat_worker(store: WorkerStore, worker_id: str) -> WorkerRecord:
+    record = get_worker(store, worker_id)
+    now = _now()
+    return _save(
+        store,
+        record.model_copy(
+            update={"status": "running", "heartbeat_at": now, "updated_at": now}
+        ),
+        event_kind="worker_heartbeat",
+    )
+
+
+def request_worker_stop(store: WorkerStore, worker_id: str) -> WorkerRecord:
+    record = get_worker(store, worker_id)
+    return _save(
+        store,
+        record.model_copy(update={"stop_requested": True, "updated_at": _now()}),
+        event_kind="worker_stop_requested",
+    )
+
+
+def complete_worker(
+    store: WorkerStore,
+    worker_id: str,
+    *,
+    status: WorkerStatus = "completed",
+    result_summary: str | None = None,
+) -> WorkerRecord:
+    if status not in {"completed", "failed", "cancelled"}:
+        raise ValueError("worker completion status must be terminal")
+    record = get_worker(store, worker_id)
+    return _save(
+        store,
+        record.model_copy(
+            update={
+                "status": status,
+                "result_summary": result_summary,
+                "updated_at": _now(),
+            }
+        ),
+        event_kind=f"worker_{status}",
+    )
+
+
+def _save(store: WorkerStore, record: WorkerRecord, *, event_kind: str) -> WorkerRecord:
+    store.put(WORKER_NAMESPACE, record.worker_id, record.model_dump())
+    append_event(
+        store,
+        stream_id=f"worker:{record.worker_id}",
+        kind=event_kind,
+        payload={
+            "worker_id": record.worker_id,
+            "status": record.status,
+            "session_id": record.session_id,
+        },
+    )
+    return record
+
+
+def _item_value(item: object) -> dict[str, object]:
+    value = getattr(item, "value", item)
+    return value if isinstance(value, dict) else {}
+
+
+def _worker_id(*, kind: str, session_id: str, created_at: str) -> str:
+    digest = sha256(f"{kind}\0{session_id}\0{created_at}".encode("utf-8")).hexdigest()
+    return f"worker-{digest[:12]}"
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat().replace("+00:00", "Z")
diff --git a/coding-deepgent/tests/README.md b/coding-deepgent/tests/README.md
new file mode 100644
index 000000000..24b22ead2
--- /dev/null
+++ b/coding-deepgent/tests/README.md
@@ -0,0 +1,66 @@
+# coding-deepgent Tests
+
+Product tests are grouped by domain so focused validation can match the
+implementation boundary being changed.
+
+## Layout
+
+- `runtime/` - agent construction, app wiring, runtime events, runtime state.
+- `subagents/` - subagent, fork, resume, background run, and verifier contracts.
+- `tool_system/` - capability registry, tool policy middleware, deferred tools,
+  and large tool-result storage.
+- `sessions/` - JSONL session, recovery, evidence, contributions, and session
+  memory continuity.
+- `compact/` - compact artifacts, message projection, runtime pressure, and
+  summarization support.
+- `frontend/` - Python frontend protocol, JSONL bridge, and event mapping.
+- `memory/` - long-term memory store, tools, middleware, CLI, and integration.
+- `tasks/` - durable task graph, plan artifacts, TodoWrite, and planning renderers.
+- `extensions/` - MCP, plugin, skill, and hook extension surfaces.
+- `filesystem/` - workspace filesystem tools and path safety.
+- `permissions/` - permission modes, rules, and filesystem policy integration.
+- `cli/` - Typer/Rich CLI, renderer, resume, compact, doctor, and UI command paths.
+- `config/` - settings, logging, prompting, rules, and context payload rendering.
+- `structure/` - architecture, package shape, and tutorial/reference isolation.
+
+## Command Groups
+
+Run commands from `coding-deepgent/` unless noted otherwise.
+
+Release smoke:
+
+```bash
+pytest -q tests/runtime tests/subagents tests/tool_system tests/sessions tests/frontend
+npm --prefix frontend/cli run typecheck
+npm --prefix frontend/cli test
+```
+
+Domain focused examples:
+
+```bash
+pytest -q tests/subagents
+pytest -q tests/tool_system tests/permissions tests/filesystem
+pytest -q tests/sessions tests/compact
+pytest -q tests/frontend
+pytest -q tests/memory
+pytest -q tests/tasks
+pytest -q tests/extensions
+pytest -q tests/cli
+pytest -q tests/config tests/structure
+```
+
+Deep regression:
+
+```bash
+pytest -q tests
+npm --prefix frontend/cli run typecheck
+npm --prefix frontend/cli test
+```
+
+## Cleanup Rules
+
+- Do not delete contract coverage just to reduce test count.
+- When merging or deleting a test, identify the replacement coverage first.
+- Keep tests deterministic and no-network.
+- Prefer shared fixtures only when they remove real duplication without hiding
+  the boundary being asserted.
diff --git a/coding-deepgent/tests/cli/test_cli.py b/coding-deepgent/tests/cli/test_cli.py
new file mode 100644
index 000000000..f61f3ecf5
--- /dev/null
+++ b/coding-deepgent/tests/cli/test_cli.py
@@ -0,0 +1,1612 @@
+from __future__ import annotations
+
+import builtins
+import json
+from dataclasses import replace
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+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, SessionMessage
+from coding_deepgent.sessions.records import message_id_for_index
+from coding_deepgent.sessions.session_memory import (
+    SESSION_MEMORY_STATE_KEY,
+    write_session_memory_artifact,
+)
+from coding_deepgent.settings import Settings, load_settings
+
+runner = CliRunner()
+
+
+def _history_summary(history: list[SessionMessage]) -> list[tuple[str, str, str]]:
+    return [(item.message_id, item.role, item.content) for item in history]
+
+
+def _session_messages(*messages: tuple[str, str]) -> list[SessionMessage]:
+    return [
+        SessionMessage(
+            message_id=message_id_for_index(index),
+            created_at=f"2026-04-16T00:00:0{index}Z",
+            role=role,
+            content=content,
+        )
+        for index, (role, content) in enumerate(messages)
+    ]
+
+
+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,
+        transcript_projection=None,
+    ) -> str:
+        captured["prompt"] = prompt
+        captured["history"] = history
+        captured["session_state"] = session_state
+        captured["session_id"] = session_id
+        captured["transcript_projection"] = transcript_projection
+        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,
+        "transcript_projection": 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 "tasks" in result.stdout
+    assert "plans" in result.stdout
+    assert "config" in result.stdout
+    assert "doctor" in result.stdout
+    assert "ui" in result.stdout
+    assert "ui-gateway" 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 test_ui_command_runs_frontend_script(monkeypatch) -> None:
+    captured: dict[str, object] = {}
+
+    def fake_run(args, *, cwd):
+        captured["args"] = args
+        captured["cwd"] = cwd
+        return SimpleNamespace(returncode=0)
+
+    monkeypatch.setattr(cli.subprocess, "run", fake_run)
+
+    result = runner.invoke(cli.app, ["ui", "--fake"])
+
+    assert result.exit_code == 0
+    assert captured["args"] == ["npm", "run", "start:fake"]
+    assert str(captured["cwd"]).endswith("coding-deepgent/frontend/cli")
+
+
+def test_ui_console_script_entry_runs_ui_command(monkeypatch) -> None:
+    captured: dict[str, object] = {}
+
+    def fake_run_frontend_ui(*, fake: bool) -> int:
+        captured["fake"] = fake
+        return 0
+
+    monkeypatch.setattr(cli, "_run_frontend_ui", fake_run_frontend_ui)
+
+    assert cli.ui_cli(["--fake"]) == 0
+    assert captured == {"fake": True}
+
+
+def test_ui_command_reports_missing_frontend_dependencies(monkeypatch, tmp_path: Path) -> None:
+    frontend_dir = tmp_path / "frontend" / "cli"
+    frontend_dir.mkdir(parents=True)
+    (frontend_dir / "package.json").write_text("{}", encoding="utf-8")
+    monkeypatch.setattr(cli, "_frontend_cli_dir", lambda: frontend_dir)
+
+    result = runner.invoke(cli.app, ["ui"])
+
+    assert result.exit_code != 0
+    assert "Frontend CLI dependencies are not installed" in result.stderr
+
+
+def test_ui_command_reports_missing_npm(monkeypatch, tmp_path: Path) -> None:
+    frontend_dir = tmp_path / "frontend" / "cli"
+    frontend_dir.mkdir(parents=True)
+    (frontend_dir / "package.json").write_text("{}", encoding="utf-8")
+    (frontend_dir / "node_modules").mkdir()
+    monkeypatch.setattr(cli, "_frontend_cli_dir", lambda: frontend_dir)
+
+    def fake_run(args, *, cwd):
+        del args, cwd
+        raise FileNotFoundError("npm")
+
+    monkeypatch.setattr(cli.subprocess, "run", fake_run)
+
+    result = runner.invoke(cli.app, ["ui", "--fake"])
+
+    assert result.exit_code != 0
+    assert "npm is required" in result.stderr
+
+
+def test_ui_gateway_command_runs_uvicorn(monkeypatch) -> None:
+    captured: dict[str, object] = {}
+    fake_app = object()
+
+    def fake_create_app(*, fake):
+        captured["fake"] = fake
+        return fake_app
+
+    def fake_run(app, *, host, port):
+        captured["app"] = app
+        captured["host"] = host
+        captured["port"] = port
+
+    monkeypatch.setattr(cli, "_load_ui_gateway_runtime", lambda: (fake_create_app, fake_run))
+
+    result = runner.invoke(cli.app, ["ui-gateway", "--fake", "--host", "0.0.0.0", "--port", "3030"])
+
+    assert result.exit_code == 0
+    assert captured["fake"] is True
+    assert captured["app"] is fake_app
+    assert captured["host"] == "0.0.0.0"
+    assert captured["port"] == 3030
+
+
+def test_load_ui_gateway_runtime_reports_missing_web_dependencies(monkeypatch) -> None:
+    original_import = builtins.__import__
+
+    def fake_import(name, *args, **kwargs):
+        if name == "uvicorn":
+            raise ModuleNotFoundError("No module named 'uvicorn'", name="uvicorn")
+        return original_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", fake_import)
+
+    with pytest.raises(cli.ClickException, match="optional web dependencies"):
+        cli._load_ui_gateway_runtime()
+
+
+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, transcript_projection=None
+) -> str:
+    del prompt, history, session_state, session_id, transcript_projection
+    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_inspect_renders_projection_visibility(
+    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-inspect")
+    store.append_message(context, role="user", content="first")
+    store.append_message(context, role="assistant", content="second")
+    store.append_collapse(
+        context,
+        trigger="threshold_tokens",
+        summary="First message collapsed.",
+        start_message_id=message_id_for_index(0),
+        end_message_id=message_id_for_index(0),
+        covered_message_ids=[message_id_for_index(0)],
+    )
+    state = {"todos": [], "rounds_since_update": 0}
+    write_session_memory_artifact(
+        state,
+        content="Current focus is inspect.",
+        message_count=2,
+        token_count=2,
+        tool_call_count=0,
+    )
+    store.append_state_snapshot(context, state=state)
+    loaded = store.load_session(session_id="session-inspect", 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", "inspect", "session-inspect", "--limit", "5"],
+    )
+
+    assert result.exit_code == 0
+    assert "Session Inspect" in result.stdout
+    assert "projection: mode=collapse" in result.stdout
+    assert "session_memory: current" in result.stdout
+    assert "Compression Timeline" in result.stdout
+    assert "collapse-0 collapse" in result.stdout
+    assert "Model Projection" in result.stdout
+    assert "source=collapse_summary" in result.stdout
+    assert "Raw Transcript Visibility" in result.stdout
+    assert "msg-000000 role=user hidden" in result.stdout
+
+
+def test_sessions_history_projection_timeline_and_events_commands(
+    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-ux")
+    store.append_message(context, role="user", content="first")
+    store.append_message(context, role="assistant", content="second")
+    store.append_collapse(
+        context,
+        trigger="threshold_tokens",
+        summary="First collapsed.",
+        start_message_id=message_id_for_index(0),
+        end_message_id=message_id_for_index(0),
+        covered_message_ids=[message_id_for_index(0)],
+    )
+    store.append_evidence(
+        context,
+        kind="runtime_event",
+        summary="Tool write_file denied by permission_denied.",
+        status="denied",
+        metadata={"event_kind": "permission_denied", "source": "tool_guard"},
+    )
+    loaded = store.load_session(session_id="session-ux", 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)
+
+    history = runner.invoke(cli.app, ["sessions", "history", "session-ux"])
+    projection = runner.invoke(cli.app, ["sessions", "projection", "session-ux"])
+    timeline = runner.invoke(cli.app, ["sessions", "timeline", "session-ux"])
+    events = runner.invoke(cli.app, ["sessions", "events", "session-ux"])
+    permissions = runner.invoke(cli.app, ["sessions", "permissions", "session-ux"])
+
+    assert history.exit_code == 0
+    assert "Raw Transcript Visibility" in history.stdout
+    assert projection.exit_code == 0
+    assert "Model Projection (collapse)" in projection.stdout
+    assert timeline.exit_code == 0
+    assert "Compression Timeline" in timeline.stdout
+    assert events.exit_code == 0
+    assert "Tool write_file denied" in events.stdout
+    assert permissions.exit_code == 0
+    assert "permission_denied" in permissions.stdout
+
+
+def test_tasks_list_renders_durable_task_table(monkeypatch) -> None:
+    monkeypatch.setattr(
+        cli_service,
+        "task_records",
+        lambda settings, include_terminal=False: [
+            cli_service.TaskRecord(
+                id="task-1",
+                title="Implement control surface",
+                status="pending",
+                owner="kun",
+                metadata={"ready": "true"},
+            )
+        ],
+    )
+
+    result = runner.invoke(cli.app, ["tasks", "list"])
+
+    assert result.exit_code == 0
+    assert "Tasks" in result.stdout
+    assert "task-1" in result.stdout
+    assert "Implement control surface" in result.stdout
+
+
+def test_tasks_create_parses_metadata(monkeypatch) -> None:
+    captured: dict[str, object] = {}
+
+    def fake_create_task_record(settings, **kwargs):
+        del settings
+        captured.update(kwargs)
+        return cli_service.TaskRecord(
+            id="task-1",
+            title=str(kwargs["title"]),
+            description=str(kwargs["description"]),
+            owner=kwargs["owner"],
+            metadata=kwargs["metadata"] or {},
+        )
+
+    monkeypatch.setattr(cli_service, "create_task_record", fake_create_task_record)
+
+    result = runner.invoke(
+        cli.app,
+        [
+            "tasks",
+            "create",
+            "Ship control surface",
+            "--description",
+            "Add CLI controls",
+            "--owner",
+            "kun",
+            "--metadata",
+            "type=workflow",
+            "--metadata",
+            "priority=high",
+        ],
+    )
+
+    assert result.exit_code == 0
+    assert captured["metadata"] == {"type": "workflow", "priority": "high"}
+    assert "Ship control surface" in result.stdout
+    assert "Task" in result.stdout
+
+
+def test_plans_list_and_save_use_cli_service(monkeypatch) -> None:
+    monkeypatch.setattr(
+        cli_service,
+        "plan_records",
+        lambda settings: [
+            cli_service.PlanArtifact(
+                id="plan-1",
+                title="Ship plan",
+                content="Implement controls.",
+                verification="pytest -q coding-deepgent/tests",
+                task_ids=["task-1"],
+            )
+        ],
+    )
+
+    saved: dict[str, object] = {}
+
+    def fake_create_plan_record(settings, **kwargs):
+        del settings
+        saved.update(kwargs)
+        return cli_service.PlanArtifact(
+            id="plan-2",
+            title=str(kwargs["title"]),
+            content=str(kwargs["content"]),
+            verification=str(kwargs["verification"]),
+            task_ids=list(kwargs["task_ids"] or []),
+            metadata=kwargs["metadata"] or {},
+        )
+
+    monkeypatch.setattr(cli_service, "create_plan_record", fake_create_plan_record)
+
+    list_result = runner.invoke(cli.app, ["plans", "list"])
+    save_result = runner.invoke(
+        cli.app,
+        [
+            "plans",
+            "save",
+            "Control plan",
+            "--content",
+            "Implement CLI controls.",
+            "--verification",
+            "pytest -q coding-deepgent/tests/cli/test_cli.py",
+            "--task-id",
+            "task-1",
+            "--metadata",
+            "phase=wave2b",
+        ],
+    )
+
+    assert list_result.exit_code == 0
+    assert "Plans" in list_result.stdout
+    assert "plan-1" in list_result.stdout
+    assert save_result.exit_code == 0
+    assert saved["metadata"] == {"phase": "wave2b"}
+    assert saved["task_ids"] == ["task-1"]
+    assert "Control plan" in save_result.stdout
+
+
+def test_extension_and_acceptance_commands_use_cli_service(monkeypatch) -> None:
+    monkeypatch.setattr(
+        cli_service,
+        "skill_rows",
+        lambda settings: [
+            {
+                "name": "demo",
+                "status": "valid",
+                "description": "Demo skill",
+                "path": "/tmp/skills/demo/SKILL.md",
+            }
+        ],
+    )
+    monkeypatch.setattr(
+        cli_service,
+        "mcp_rows",
+        lambda settings: [
+            {
+                "name": "docs",
+                "status": "configured",
+                "description": "stdio",
+                "path": "/tmp/.mcp.json",
+            }
+        ],
+    )
+    monkeypatch.setattr(
+        cli_service,
+        "plugin_rows",
+        lambda settings: [
+            {
+                "name": "demo_plugin",
+                "status": "valid",
+                "description": "Demo plugin",
+                "path": "/tmp/plugins/demo/plugin.json",
+            }
+        ],
+    )
+
+    skills = runner.invoke(cli.app, ["skills", "list"])
+    mcp = runner.invoke(cli.app, ["mcp", "list"])
+    hooks = runner.invoke(cli.app, ["hooks", "list"])
+    plugins = runner.invoke(cli.app, ["plugins", "list"])
+    acceptance = runner.invoke(cli.app, ["acceptance", "circle1"])
+
+    assert skills.exit_code == 0
+    assert "demo" in skills.stdout
+    assert mcp.exit_code == 0
+    assert "docs" in mcp.stdout
+    assert hooks.exit_code == 0
+    assert "UserPromptSubmit" in hooks.stdout
+    assert plugins.exit_code == 0
+    assert "demo_plugin" in plugins.stdout
+    assert acceptance.exit_code == 0
+    assert "workflow_a_repository_takeover" in acceptance.stdout
+
+
+def test_circle2_cli_surfaces_write_to_durable_store(monkeypatch, tmp_path: Path) -> None:
+    settings = Settings(workdir=tmp_path, model_name="gpt-test")
+    runtime = cli_service.CliRuntime(
+        settings_loader=lambda: settings,
+        list_sessions=lambda: [],
+        load_session=_empty_history,
+        run_prompt=_unused_run_prompt,
+        doctor_checks=lambda: [],
+    )
+    monkeypatch.setattr(cli, "build_cli_runtime", lambda: runtime)
+
+    worker = runner.invoke(cli.app, ["workers", "create", "assistant"])
+    mailbox = runner.invoke(
+        cli.app,
+        [
+            "mailbox",
+            "send",
+            "worker-1",
+            "task",
+            "do it",
+            "--sender",
+            "coordinator",
+            "--delivery-key",
+            "delivery-1",
+        ],
+    )
+    team = runner.invoke(cli.app, ["teams", "create", "Ship feature"])
+    remote = runner.invoke(cli.app, ["remote", "register", "session-1", "ide"])
+    lifecycle = runner.invoke(
+        cli.app,
+        ["extension-lifecycle", "register", "demo", "plugin", "local"],
+    )
+    continuity = runner.invoke(
+        cli.app,
+        ["continuity", "save", "Next step", "Continue tomorrow."],
+    )
+    acceptance = runner.invoke(cli.app, ["acceptance", "circle2"])
+
+    assert worker.exit_code == 0
+    assert cli_service.worker_rows(settings)
+    assert mailbox.exit_code == 0
+    assert len(cli_service.mailbox_rows(settings, recipient="worker-1")) == 1
+    assert team.exit_code == 0
+    assert cli_service.team_rows(settings)
+    assert remote.exit_code == 0
+    assert cli_service.remote_rows(settings)
+    assert lifecycle.exit_code == 0
+    assert cli_service.lifecycle_rows(settings)
+    assert continuity.exit_code == 0
+    assert cli_service.continuity_rows(settings)
+    assert acceptance.exit_code == 0
+    assert "workflow_d_durable_background_lifecycle" in acceptance.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,
+        transcript_projection=None,
+    ) -> str:
+        captured["prompt"] = prompt
+        captured["history"] = history
+        captured["session_state"] = session_state
+        captured["session_id"] = session_id
+        captured["transcript_projection"] = transcript_projection
+        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"
+    assert captured["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"},
+    ]
+    assert captured["session_state"] == {
+        "todos": [
+            {
+                "content": "Continue work",
+                "status": "in_progress",
+                "activeForm": "Continuing",
+            }
+        ],
+        "rounds_since_update": 1,
+    }
+    assert captured["session_id"] == "session-1"
+    assert captured["transcript_projection"] is not None
+    assert "resumed" in result.stdout
+
+
+def test_sessions_resume_session_memory_option_updates_state_before_run(
+    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,
+        transcript_projection=None,
+    ) -> str:
+        captured["prompt"] = prompt
+        captured["history"] = history
+        captured["session_state"] = session_state
+        captured["session_id"] = session_id
+        captured["transcript_projection"] = transcript_projection
+        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",
+            "--session-memory",
+            "Current focus is deterministic assist.",
+        ],
+    )
+
+    assert result.exit_code == 0
+    assert captured["prompt"] == "continue"
+    assert isinstance(captured["session_state"], dict)
+    artifact = captured["session_state"][SESSION_MEMORY_STATE_KEY]
+    assert artifact["content"] == "Current focus is deterministic assist."
+    assert artifact["source"] == "manual"
+    assert artifact["message_count"] == 1
+    assert artifact["updated_at"]
+    history = captured["history"]
+    assert isinstance(history, list)
+    assert "Current-session memory:" not in str(history[0]["content"])
+    assert "Current focus is deterministic assist." not in str(history[0]["content"])
+    assert captured["session_id"] == "session-1"
+
+
+def test_sessions_resume_rejects_session_memory_without_prompt(
+    monkeypatch, tmp_path: Path
+) -> None:
+    loaded = _loaded_session(tmp_path)
+
+    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-1",
+            "--session-memory",
+            "Current focus is deterministic assist.",
+        ],
+    )
+
+    assert result.exit_code != 0
+    assert result.exception is not None
+
+
+def test_sessions_resume_rejects_blank_session_memory(
+    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, transcript_projection=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",
+            "--session-memory",
+            "   ",
+        ],
+    )
+
+    assert result.exit_code != 0
+    assert called == []
+
+
+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")
+    store.append_message(context, role="assistant", content="done")
+    store.append_compact(
+        context,
+        trigger="manual",
+        summary="Earlier work was summarized.",
+        start_message_id=message_id_for_index(0),
+        end_message_id=message_id_for_index(0),
+        covered_message_ids=[message_id_for_index(0)],
+    )
+    store.append_message(context, role="user", content="after compact")
+    store.append_message(context, role="assistant", content="after compact answer")
+    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,
+        transcript_projection=None,
+    ) -> str:
+        captured["prompt"] = prompt
+        captured["history"] = history
+        captured["session_state"] = session_state
+        captured["session_id"] = session_id
+        captured["transcript_projection"] = transcript_projection
+        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")
+    store.append_message(context, role="assistant", content="done")
+    store.append_compact(
+        context,
+        trigger="manual",
+        summary="Earlier work was summarized.",
+        start_message_id=message_id_for_index(0),
+        end_message_id=message_id_for_index(0),
+        covered_message_ids=[message_id_for_index(0)],
+    )
+    store.append_message(context, role="user", content="after compact")
+    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_prefers_loaded_collapsed_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")
+    store.append_message(context, role="assistant", content="done")
+    store.append_collapse(
+        context,
+        trigger="threshold_tokens",
+        summary="Earlier work was collapsed.",
+        start_message_id=message_id_for_index(0),
+        end_message_id=message_id_for_index(0),
+        covered_message_ids=[message_id_for_index(0)],
+    )
+    loaded = store.load_session(session_id="session-1", workdir=workdir)
+
+    history = cli_service.selected_continuation_history(loaded)
+    projection = cli_service.selected_continuation_projection(loaded)
+
+    assert history[0]["role"] == "system"
+    assert history[1:] == loaded.collapsed_history
+    assert projection.entries[0] == ()
+    assert projection.entries[1] == ()
+    assert projection.entries[2] == ()
+    assert projection.entries[3] == (message_id_for_index(1),)
+
+
+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")
+    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.",
+        start_message_id=message_id_for_index(0),
+        end_message_id=message_id_for_index(0),
+        covered_message_ids=[message_id_for_index(0)],
+    )
+    store.append_message(context, role="assistant", content="after compact")
+
+    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,
+        transcript_projection=None,
+    ) -> str:
+        captured["prompt"] = prompt
+        captured["history"] = history
+        captured["session_state"] = session_state
+        captured["session_id"] = session_id
+        captured["transcript_projection"] = transcript_projection
+        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,
+        transcript_projection=None,
+    ) -> str:
+        captured["prompt"] = prompt
+        captured["history"] = history
+        captured["session_state"] = session_state
+        captured["session_id"] = session_id
+        captured["transcript_projection"] = transcript_projection
+        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_generated_compact_summary_uses_session_memory_assist(
+    monkeypatch, tmp_path: Path
+) -> None:
+    captured: dict[str, object] = {}
+    loaded = _loaded_session(tmp_path)
+    summarizer = FakeCompactSummarizer("<summary>Generated compact summary.</summary>")
+
+    def fake_run_prompt(
+        prompt: str,
+        history=None,
+        session_state=None,
+        session_id=None,
+        transcript_projection=None,
+    ) -> str:
+        captured["prompt"] = prompt
+        captured["history"] = history
+        captured["session_state"] = session_state
+        captured["session_id"] = session_id
+        captured["transcript_projection"] = transcript_projection
+        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",
+            "--session-memory",
+            "Current focus is deterministic assist.",
+            "--generate-compact-summary",
+        ],
+    )
+
+    assert result.exit_code == 0
+    assert len(summarizer.requests) == 1
+    assert summarizer.requests[0][-2]["role"] == "system"
+    assert "Current focus is deterministic assist." in str(
+        summarizer.requests[0][-2]["content"]
+    )
+
+
+def test_generated_compacted_continuation_history_ignores_stale_session_memory_assist(
+    tmp_path: Path,
+) -> None:
+    loaded = _loaded_session(tmp_path)
+    loaded.state[SESSION_MEMORY_STATE_KEY] = {
+        "content": "Current focus is deterministic assist.",
+        "source": "manual",
+        "message_count": 0,
+        "updated_at": "2026-04-15T00:00:00Z",
+    }
+    summarizer = FakeCompactSummarizer("<summary>Generated compact summary.</summary>")
+
+    history = cli_service.generated_compacted_continuation_history(
+        loaded,
+        summarizer=summarizer,
+        keep_last=1,
+    )
+
+    assert len(summarizer.requests) == 1
+    assert len(summarizer.requests[0]) == 2
+    assert summarizer.requests[0][0] == {"role": "assistant", "content": "existing"}
+    assert summarizer.requests[0][-1]["role"] == "user"
+    assert "Session memory artifact" not in str(summarizer.requests[0])
+    assert isinstance(history, list)
+
+
+def test_generated_compacted_continuation_history_refreshes_missing_session_memory(
+    tmp_path: Path,
+) -> None:
+    loaded = _loaded_session(tmp_path)
+    summarizer = FakeCompactSummarizer("<summary>Generated compact summary.</summary>")
+
+    cli_service.generated_compacted_continuation_history(
+        loaded,
+        summarizer=summarizer,
+        keep_last=1,
+    )
+
+    assert loaded.state[SESSION_MEMORY_STATE_KEY]["content"] == (
+        "Generated compact summary."
+    )
+    assert loaded.state[SESSION_MEMORY_STATE_KEY]["source"] == "generated_compact"
+    assert loaded.state[SESSION_MEMORY_STATE_KEY]["message_count"] == 1
+
+
+def test_generated_compacted_continuation_history_refreshes_stale_enough_memory(
+    tmp_path: Path,
+) -> None:
+    loaded = _loaded_session(tmp_path)
+    loaded.state[SESSION_MEMORY_STATE_KEY] = {
+        "content": "Old memory.",
+        "source": "manual",
+        "message_count": 1,
+        "updated_at": "2026-04-15T00:00:00Z",
+    }
+    loaded = replace(
+        loaded,
+        history=_session_messages(
+            ("user", "one"),
+            ("assistant", "two"),
+            ("user", "three"),
+            ("assistant", "four"),
+            ("user", "five"),
+        ),
+        summary=replace(loaded.summary, message_count=5),
+    )
+    summarizer = FakeCompactSummarizer("<summary>Generated compact summary.</summary>")
+
+    cli_service.generated_compacted_continuation_history(
+        loaded,
+        summarizer=summarizer,
+        keep_last=1,
+    )
+
+    assert loaded.state[SESSION_MEMORY_STATE_KEY]["content"] == (
+        "Generated compact summary."
+    )
+    assert loaded.state[SESSION_MEMORY_STATE_KEY]["source"] == "generated_compact"
+    assert loaded.state[SESSION_MEMORY_STATE_KEY]["message_count"] == 5
+
+
+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, transcript_projection=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, transcript_projection=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, transcript_projection=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.",
+        start_message_id=message_id_for_index(0),
+        end_message_id=message_id_for_index(0),
+        covered_message_ids=[message_id_for_index(0)],
+    )
+    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 _history_summary(loaded.history) == [
+        (message_id_for_index(0), "user", "first"),
+        (message_id_for_index(1), "assistant", "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 _history_summary(resumed.history) == [
+        (message_id_for_index(0), "user", "first"),
+        (message_id_for_index(1), "assistant", "done"),
+        (message_id_for_index(2), "user", "second"),
+        (message_id_for_index(3), "assistant", "done"),
+    ]
+    assert resumed.summary.evidence_count == 2
+    assert [record["message_id"] for record in message_records] == [
+        message_id_for_index(0),
+        message_id_for_index(1),
+        message_id_for_index(2),
+        message_id_for_index(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 _history_summary(resumed.history) == [
+        (message_id_for_index(0), "user", "first"),
+        (message_id_for_index(1), "assistant", "done"),
+        (message_id_for_index(2), "user", "second"),
+        (message_id_for_index(3), "assistant", "done"),
+    ]
+    assert resumed.summary.compact_count == 1
+    assert resumed.compacts[0].summary == "Earlier work was summarized."
+    assert resumed.compacts[0].start_message_id == message_id_for_index(0)
+    assert resumed.compacts[0].end_message_id == message_id_for_index(0)
+    assert resumed.compacts[0].covered_message_ids == (message_id_for_index(0),)
+    assert [record["message_id"] for record in message_records] == [
+        message_id_for_index(0),
+        message_id_for_index(1),
+        message_id_for_index(2),
+        message_id_for_index(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/cli/test_renderers.py b/coding-deepgent/tests/cli/test_renderers.py
new file mode 100644
index 000000000..28beb1c6a
--- /dev/null
+++ b/coding-deepgent/tests/cli/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/cli/test_rendering.py b/coding-deepgent/tests/cli/test_rendering.py
new file mode 100644
index 000000000..183caf064
--- /dev/null
+++ b/coding-deepgent/tests/cli/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/compact/test_compact_artifacts.py b/coding-deepgent/tests/compact/test_compact_artifacts.py
new file mode 100644
index 000000000..419b12ad8
--- /dev/null
+++ b/coding-deepgent/tests/compact/test_compact_artifacts.py
@@ -0,0 +1,196 @@
+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_record_from_messages,
+    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_record_from_messages_uses_message_references() -> None:
+    artifact = compact_messages_with_summary(
+        [
+            {"role": "user", "content": "old request"},
+            {"role": "assistant", "content": "old answer"},
+            {"role": "user", "content": "recent request"},
+        ],
+        summary="Earlier work established the compact boundary.",
+        keep_last=1,
+        start_message_id="msg-000000",
+        end_message_id="msg-000001",
+        covered_message_ids=["msg-000000", "msg-000001"],
+        metadata={"source": "test"},
+    )
+
+    assert compact_record_from_messages(artifact.messages) == {
+        "trigger": "manual",
+        "summary": "Earlier work established the compact boundary.",
+        "start_message_id": "msg-000000",
+        "end_message_id": "msg-000001",
+        "covered_message_ids": ["msg-000000", "msg-000001"],
+        "metadata": {"source": "test"},
+    }
+
+
+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_preserves_pair_for_dynamic_projection_tool_name() -> None:
+    tool_use_message = {
+        "role": "assistant",
+        "content": [
+            {
+                "type": "tool_use",
+                "id": "call-ext",
+                "name": "mcp__docs__lookup",
+                "input": {"query": "policy"},
+            }
+        ],
+    }
+    tool_result_message = {
+        "role": "user",
+        "content": [
+            {
+                "type": "tool_result",
+                "tool_use_id": "call-ext",
+                "content": "doc result",
+            }
+        ],
+    }
+
+    artifact = compact_messages_with_summary(
+        [
+            {"role": "user", "content": "old"},
+            tool_use_message,
+            tool_result_message,
+        ],
+        summary="Summary",
+        keep_last=1,
+    )
+
+    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/compact/test_compact_budget.py b/coding-deepgent/tests/compact/test_compact_budget.py
new file mode 100644
index 000000000..70b5ebe25
--- /dev/null
+++ b/coding-deepgent/tests/compact/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/compact/test_compact_summarizer.py b/coding-deepgent/tests/compact/test_compact_summarizer.py
new file mode 100644
index 000000000..267bba685
--- /dev/null
+++ b/coding-deepgent/tests/compact/test_compact_summarizer.py
@@ -0,0 +1,110 @@
+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_build_compact_summary_request_includes_session_memory_assist() -> None:
+    request = build_compact_summary_request(
+        [{"role": "user", "content": "hello"}],
+        assist_context="Session memory artifact:\nKeep repo focus.",
+    )
+
+    assert request[-2]["role"] == "system"
+    assert "Session memory artifact" in str(request[-2]["content"])
+    assert request[-1]["role"] == "user"
+
+
+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_passes_session_memory_assist_to_summarizer() -> None:
+    summarizer = FakeSummarizer("<summary>Keep the compact summary.</summary>")
+
+    generate_compact_summary(
+        [{"role": "user", "content": "old"}],
+        summarizer,
+        assist_context="Session memory artifact:\nKeep repo focus.",
+    )
+
+    assert summarizer.requests[0][-2]["role"] == "system"
+    assert "Keep repo focus." in str(summarizer.requests[0][-2]["content"])
+
+
+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/compact/test_message_projection.py b/coding-deepgent/tests/compact/test_message_projection.py
new file mode 100644
index 000000000..051c86be5
--- /dev/null
+++ b/coding-deepgent/tests/compact/test_message_projection.py
@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from typing import Any
+
+from coding_deepgent.compact import (
+    ORPHAN_TOOL_RESULT_TOMBSTONE,
+    TRUNCATION_MARKER,
+    project_messages,
+    project_messages_with_stats,
+)
+
+
+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": "assistant",
+            "content": [{"type": "tool_use", "id": "call-1", "name": "read_file"}],
+        },
+        {
+            "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},
+    ]
+
+
+def test_project_messages_tombstones_orphan_tool_result_blocks() -> None:
+    result = project_messages_with_stats(
+        [
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "tool_result",
+                        "tool_use_id": "missing-call",
+                        "content": "raw output",
+                    }
+                ],
+            }
+        ]
+    )
+
+    assert result.messages == [
+        {
+            "role": "user",
+            "content": [{"type": "text", "text": ORPHAN_TOOL_RESULT_TOMBSTONE}],
+        }
+    ]
+    assert result.repair_stats.orphan_tombstoned == 1
+    assert result.repair_stats.reason == "missing_tool_use"
+
+
+def test_project_messages_preserves_matched_tool_result_blocks() -> None:
+    messages: list[dict[str, Any]] = [
+        {
+            "role": "assistant",
+            "content": [{"type": "tool_use", "id": "call-1", "name": "read_file"}],
+        },
+        {
+            "role": "user",
+            "content": [
+                {"type": "tool_result", "tool_use_id": "call-1", "content": "ok"}
+            ],
+        },
+    ]
+
+    result = project_messages_with_stats(messages)
+
+    assert result.messages == messages
+    assert result.repair_stats.orphan_tombstoned == 0
+
+
+def test_project_messages_preserves_pairing_for_dynamic_extension_tool_names() -> None:
+    messages: list[dict[str, Any]] = [
+        {
+            "role": "assistant",
+            "content": [
+                {"type": "tool_use", "id": "call-ext", "name": "mcp__docs__lookup"}
+            ],
+        },
+        {
+            "role": "user",
+            "content": [
+                {
+                    "type": "tool_result",
+                    "tool_use_id": "call-ext",
+                    "content": "doc result",
+                }
+            ],
+        },
+    ]
+
+    result = project_messages_with_stats(messages)
+
+    assert result.messages == messages
+    assert result.repair_stats.orphan_tombstoned == 0
diff --git a/coding-deepgent/tests/compact/test_runtime_pressure.py b/coding-deepgent/tests/compact/test_runtime_pressure.py
new file mode 100644
index 000000000..edc8a9c8b
--- /dev/null
+++ b/coding-deepgent/tests/compact/test_runtime_pressure.py
@@ -0,0 +1,1723 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from collections.abc import Sequence
+from typing import Any, cast
+
+from langchain.agents.middleware import ModelRequest, ModelResponse
+from langchain.messages import AIMessage, HumanMessage, SystemMessage, ToolMessage
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.language_models.fake_chat_models import FakeMessagesListChatModel
+from langchain_core.messages import AnyMessage, BaseMessage
+from langchain_core.prompt_values import PromptValue
+from langgraph.runtime import Runtime
+from langchain_core.runnables import RunnableConfig
+from pydantic import PrivateAttr
+
+from coding_deepgent.compact import (
+    LIVE_COLLAPSE_BOUNDARY_PREFIX,
+    LIVE_COLLAPSE_SUMMARY_PREFIX,
+    LIVE_COMPACT_BOUNDARY_PREFIX,
+    LIVE_COMPACT_RESTORATION_PREFIX,
+    LIVE_COMPACT_SUMMARY_PREFIX,
+    LIVE_SNIP_BOUNDARY_PREFIX,
+    MICROCOMPACT_CLEARED_MESSAGE,
+    RuntimePressureMiddleware,
+    collapse_live_messages_with_result,
+    collapse_live_messages_with_summary,
+    drain_collapse_projection_messages,
+    compact_live_messages_with_result,
+    compact_live_messages_with_summary,
+    estimate_message_tokens,
+    is_prompt_too_long_error,
+    maybe_collapse_messages,
+    maybe_auto_compact_messages,
+    maybe_time_based_microcompact_messages,
+    microcompact_messages,
+    reactive_compact_messages,
+    snip_messages,
+)
+from coding_deepgent.hooks import HookResult, LocalHookRegistry
+from coding_deepgent.runtime import InMemoryEventSink, RuntimeContext, RuntimeEvent
+from coding_deepgent.sessions import (
+    COLLAPSE_EVENT_KIND,
+    JsonlSessionStore,
+    TranscriptProjection,
+    build_recovery_brief,
+    render_recovery_brief,
+)
+from coding_deepgent.tool_system import build_default_registry
+
+MessageLike = BaseMessage | list[str] | tuple[str, str] | str | dict[str, Any]
+ModelInput = PromptValue | str | Sequence[MessageLike]
+
+
+class FakeSummarizer(FakeMessagesListChatModel):
+    _requests: list[list[dict[str, Any]]] = PrivateAttr(default_factory=list)
+
+    def __init__(self, response: str) -> None:
+        super().__init__(responses=[AIMessage(content=response)])
+
+    @property
+    def requests(self) -> list[list[dict[str, Any]]]:
+        return self._requests
+
+    def invoke(
+        self,
+        input: ModelInput,
+        config: RunnableConfig | None = None,
+        **kwargs: Any,
+    ) -> AIMessage:
+        if isinstance(input, list):
+            self._requests.append(cast(list[dict[str, Any]], input))
+        return super().invoke(input, config=config, **kwargs)
+
+
+class FailingSummarizer(FakeMessagesListChatModel):
+    _requests: list[list[dict[str, Any]]] = PrivateAttr(default_factory=list)
+
+    def __init__(self) -> None:
+        super().__init__(responses=[AIMessage(content="unused")])
+
+    @property
+    def requests(self) -> list[list[dict[str, Any]]]:
+        return self._requests
+
+    def invoke(
+        self,
+        input: ModelInput,
+        config: RunnableConfig | None = None,
+        **kwargs: Any,
+    ) -> AIMessage:
+        del config, kwargs
+        if isinstance(input, list):
+            self._requests.append(cast(list[dict[str, Any]], input))
+        raise RuntimeError("compact summarizer unavailable")
+
+
+class PromptTooLongThenSuccessSummarizer(FakeMessagesListChatModel):
+    _requests: list[list[dict[str, Any]]] = PrivateAttr(default_factory=list)
+
+    def __init__(self, response: str) -> None:
+        super().__init__(responses=[AIMessage(content=response)])
+
+    @property
+    def requests(self) -> list[list[dict[str, Any]]]:
+        return self._requests
+
+    def invoke(
+        self,
+        input: ModelInput,
+        config: RunnableConfig | None = None,
+        **kwargs: Any,
+    ) -> AIMessage:
+        if isinstance(input, list):
+            self._requests.append(cast(list[dict[str, Any]], input))
+        if len(self._requests) == 1:
+            raise RuntimeError("prompt too long for compact request")
+        return super().invoke(input, config=config, **kwargs)
+
+
+class PromptTooLongSummarizer(FakeMessagesListChatModel):
+    _requests: list[list[dict[str, Any]]] = PrivateAttr(default_factory=list)
+
+    def __init__(self) -> None:
+        super().__init__(responses=[AIMessage(content="unused")])
+
+    @property
+    def requests(self) -> list[list[dict[str, Any]]]:
+        return self._requests
+
+    def invoke(
+        self,
+        input: ModelInput,
+        config: RunnableConfig | None = None,
+        **kwargs: Any,
+    ) -> AIMessage:
+        del config, kwargs
+        if isinstance(input, list):
+            self._requests.append(cast(list[dict[str, Any]], input))
+        raise RuntimeError("prompt too long for compact request")
+
+
+def runtime_context(
+    tmp_path: Path,
+    *,
+    session_store: JsonlSessionStore | None = None,
+    entrypoint: str = "test",
+    agent_name: str = "test-agent",
+    transcript_projection: TranscriptProjection | None = None,
+) -> RuntimeContext:
+    session_context = None
+    if session_store is not None:
+        session_context = session_store.create_session(
+            workdir=tmp_path, session_id="session-1"
+        )
+        session_store.append_message(session_context, role="user", content="start")
+    return RuntimeContext(
+        session_id="session-1",
+        workdir=tmp_path,
+        trusted_workdirs=(),
+        entrypoint=entrypoint,
+        agent_name=agent_name,
+        skill_dir=tmp_path / "skills",
+        event_sink=InMemoryEventSink(),
+        hook_registry=LocalHookRegistry(),
+        session_context=session_context,
+        transcript_projection=transcript_projection,
+    )
+
+
+def _unused_model() -> BaseChatModel:
+    return FakeMessagesListChatModel(responses=[AIMessage(content="unused")])
+
+
+def _runtime(
+    context: RuntimeContext | None = None,
+    *,
+    store: object | None = None,
+) -> Runtime[Any]:
+    return Runtime(context=context, store=cast(Any, store))
+
+
+def _request(
+    *,
+    model: BaseChatModel,
+    messages: list[AnyMessage],
+    context: RuntimeContext | None = None,
+    state: dict[str, Any] | None = None,
+    model_settings: dict[str, Any] | None = None,
+    store: object | None = None,
+) -> ModelRequest:
+    runtime = _runtime(context, store=store) if (context is not None or store is not None) else None
+    return ModelRequest(
+        model=model,
+        messages=messages,
+        system_message=SystemMessage(content="Base"),
+        tool_choice=None,
+        tools=[],
+        response_format=None,
+        state=cast(Any, state if state is not None else {"messages": []}),
+        runtime=runtime,
+        model_settings=model_settings or {},
+    )
+
+
+def _ok_response(text: str = "ok") -> ModelResponse:
+    return ModelResponse(result=[AIMessage(content=text)])
+
+
+def _events(context: RuntimeContext) -> tuple[RuntimeEvent, ...]:
+    return cast(InMemoryEventSink, context.event_sink).snapshot()
+
+
+def _read_call(tool_call_id: str) -> AIMessage:
+    return AIMessage(
+        content="",
+        tool_calls=[
+            {
+                "name": "read_file",
+                "args": {"path": f"{tool_call_id}.txt"},
+                "id": tool_call_id,
+                "type": "tool_call",
+            }
+        ],
+    )
+
+
+def _assistant_at(timestamp: str) -> AIMessage:
+    return AIMessage(content="completed previous turn", additional_kwargs={"timestamp": timestamp})
+
+
+def test_microcompact_messages_clears_older_eligible_tool_results() -> None:
+    registry = build_default_registry(include_discovery=True)
+    messages = [
+        HumanMessage(content="inspect files"),
+        _read_call("call-1"),
+        ToolMessage(
+            content="x" * 500,
+            tool_call_id="call-1",
+            artifact={"path": ".coding-deepgent/tool-results/session-1/call-1.txt"},
+        ),
+        _read_call("call-2"),
+        ToolMessage(
+            content="y" * 500,
+            tool_call_id="call-2",
+            artifact={"path": ".coding-deepgent/tool-results/session-1/call-2.txt"},
+        ),
+        _read_call("call-3"),
+        ToolMessage(content="z" * 500, tool_call_id="call-3"),
+        _read_call("call-4"),
+        ToolMessage(content="w" * 500, tool_call_id="call-4"),
+    ]
+
+    result = microcompact_messages(
+        messages,
+        registry=registry,
+        keep_recent_tool_results=2,
+    )
+
+    assert result[2].content == (
+        f"{MICROCOMPACT_CLEARED_MESSAGE} "
+        "Full output remains available at: .coding-deepgent/tool-results/session-1/call-1.txt"
+    )
+    assert result[4].content == (
+        f"{MICROCOMPACT_CLEARED_MESSAGE} "
+        "Full output remains available at: .coding-deepgent/tool-results/session-1/call-2.txt"
+    )
+    assert result[6].content == "z" * 500
+    assert result[8].content == "w" * 500
+
+
+def test_microcompact_messages_skips_ineligible_tool_results() -> None:
+    registry = build_default_registry(include_discovery=True)
+    messages = [
+        AIMessage(
+            content="",
+            tool_calls=[
+                {
+                    "name": "TodoWrite",
+                    "args": {"todos": []},
+                    "id": "todo-1",
+                    "type": "tool_call",
+                }
+            ],
+        ),
+        ToolMessage(content="x" * 500, tool_call_id="todo-1"),
+    ]
+
+    result = microcompact_messages(messages, registry=registry, keep_recent_tool_results=0)
+
+    assert result[1].content == "x" * 500
+
+
+def test_microcompact_messages_can_use_token_budget_protection() -> None:
+    registry = build_default_registry(include_discovery=True)
+    messages = [
+        HumanMessage(content="inspect files"),
+        _read_call("call-1"),
+        ToolMessage(content="a" * 400, tool_call_id="call-1"),
+        _read_call("call-2"),
+        ToolMessage(content="b" * 160, tool_call_id="call-2"),
+        _read_call("call-3"),
+        ToolMessage(content="c" * 160, tool_call_id="call-3"),
+        _read_call("call-4"),
+        ToolMessage(content="d" * 160, tool_call_id="call-4"),
+    ]
+
+    result = microcompact_messages(
+        messages,
+        registry=registry,
+        keep_recent_tool_results=0,
+        protect_recent_tokens=100,
+    )
+
+    assert result[2].content == MICROCOMPACT_CLEARED_MESSAGE
+    assert result[4].content == MICROCOMPACT_CLEARED_MESSAGE
+    assert result[6].content == "c" * 160
+    assert result[8].content == "d" * 160
+
+
+def test_microcompact_messages_token_budget_keeps_at_least_one_result() -> None:
+    registry = build_default_registry(include_discovery=True)
+    messages = [
+        _read_call("call-1"),
+        ToolMessage(content="x" * 500, tool_call_id="call-1"),
+        _read_call("call-2"),
+        ToolMessage(content="y" * 500, tool_call_id="call-2"),
+    ]
+
+    result = microcompact_messages(
+        messages,
+        registry=registry,
+        keep_recent_tool_results=0,
+        protect_recent_tokens=1,
+    )
+
+    assert result[1].content == MICROCOMPACT_CLEARED_MESSAGE
+    assert result[3].content == "y" * 500
+
+
+def test_microcompact_messages_token_budget_respects_min_saved_tokens() -> None:
+    registry = build_default_registry(include_discovery=True)
+    messages = [
+        _read_call("call-1"),
+        ToolMessage(content="x" * 500, tool_call_id="call-1"),
+        _read_call("call-2"),
+        ToolMessage(content="y" * 500, tool_call_id="call-2"),
+    ]
+
+    result = microcompact_messages(
+        messages,
+        registry=registry,
+        keep_recent_tool_results=0,
+        protect_recent_tokens=1,
+        min_saved_tokens=10_000,
+    )
+
+    assert result == messages
+
+
+def test_time_based_microcompact_skips_when_disabled(tmp_path: Path) -> None:
+    registry = build_default_registry(include_discovery=True)
+
+    decision = maybe_time_based_microcompact_messages(
+        [
+            _assistant_at("2026-04-16T10:00:00Z"),
+            _read_call("call-1"),
+            ToolMessage(content="x" * 500, tool_call_id="call-1"),
+        ],
+        registry=registry,
+        context=runtime_context(
+            tmp_path,
+            entrypoint="coding-deepgent",
+            agent_name="coding-deepgent",
+        ),
+        gap_threshold_minutes=None,
+        now=lambda: datetime(2026, 4, 16, 12, 0, tzinfo=timezone.utc),
+    )
+
+    assert decision.attempted is False
+    assert decision.result is None
+
+
+def test_time_based_microcompact_skips_non_main_context(tmp_path: Path) -> None:
+    registry = build_default_registry(include_discovery=True)
+
+    decision = maybe_time_based_microcompact_messages(
+        [
+            _assistant_at("2026-04-16T10:00:00Z"),
+            _read_call("call-1"),
+            ToolMessage(content="x" * 500, tool_call_id="call-1"),
+        ],
+        registry=registry,
+        context=runtime_context(
+            tmp_path,
+            entrypoint="run_subagent:verifier",
+            agent_name="coding-deepgent-verifier",
+        ),
+        gap_threshold_minutes=60,
+        now=lambda: datetime(2026, 4, 16, 12, 0, tzinfo=timezone.utc),
+    )
+
+    assert decision.attempted is False
+    assert decision.result is None
+
+
+def test_time_based_microcompact_skips_without_assistant_timestamp(
+    tmp_path: Path,
+) -> None:
+    registry = build_default_registry(include_discovery=True)
+
+    decision = maybe_time_based_microcompact_messages(
+        [
+            _read_call("call-1"),
+            ToolMessage(content="x" * 500, tool_call_id="call-1"),
+        ],
+        registry=registry,
+        context=runtime_context(
+            tmp_path,
+            entrypoint="coding-deepgent",
+            agent_name="coding-deepgent",
+        ),
+        gap_threshold_minutes=60,
+        now=lambda: datetime(2026, 4, 16, 12, 0, tzinfo=timezone.utc),
+    )
+
+    assert decision.attempted is False
+    assert decision.result is None
+
+
+def test_time_based_microcompact_skips_under_gap_threshold(tmp_path: Path) -> None:
+    registry = build_default_registry(include_discovery=True)
+
+    decision = maybe_time_based_microcompact_messages(
+        [
+            _assistant_at("2026-04-16T11:30:00Z"),
+            _read_call("call-1"),
+            ToolMessage(content="x" * 500, tool_call_id="call-1"),
+        ],
+        registry=registry,
+        context=runtime_context(
+            tmp_path,
+            entrypoint="coding-deepgent",
+            agent_name="coding-deepgent",
+        ),
+        gap_threshold_minutes=60,
+        now=lambda: datetime(2026, 4, 16, 12, 0, tzinfo=timezone.utc),
+    )
+
+    assert decision.attempted is False
+    assert decision.result is None
+
+
+def test_snip_messages_hides_older_projection_and_preserves_tool_pair() -> None:
+    messages = [
+        HumanMessage(content="old request"),
+        _read_call("call-1"),
+        ToolMessage(content="result", tool_call_id="call-1"),
+    ]
+
+    result = snip_messages(
+        messages,
+        threshold_tokens=1,
+        keep_recent_messages=1,
+    )
+
+    assert str(result[0].content).startswith(LIVE_SNIP_BOUNDARY_PREFIX)
+    assert "hidden_messages=1" in str(result[0].content)
+    assert isinstance(result[1], AIMessage)
+    assert isinstance(result[2], ToolMessage)
+    assert messages[0].content == "old request"
+
+
+def test_runtime_pressure_middleware_rewrites_request_messages_before_model_call() -> None:
+    registry = build_default_registry(include_discovery=True)
+    middleware = RuntimePressureMiddleware(registry=registry, keep_recent_tool_results=1)
+    captured: dict[str, object] = {}
+
+    def handler(request: ModelRequest):
+        captured["messages"] = request.messages
+        return _ok_response()
+
+    request = _request(
+        model=_unused_model(),
+        messages=[
+            HumanMessage(content="inspect files"),
+            _read_call("call-1"),
+            ToolMessage(content="x" * 500, tool_call_id="call-1"),
+            _read_call("call-2"),
+            ToolMessage(content="y" * 500, tool_call_id="call-2"),
+        ],
+    )
+
+    middleware.wrap_model_call(request, handler)
+
+    compacted = captured["messages"]
+    assert isinstance(compacted, list)
+    assert compacted[2].content == MICROCOMPACT_CLEARED_MESSAGE
+    assert compacted[4].content == "y" * 500
+
+
+def test_runtime_pressure_middleware_runs_time_based_microcompact(
+    tmp_path: Path,
+) -> None:
+    registry = build_default_registry(include_discovery=True)
+    context = runtime_context(
+        tmp_path,
+        entrypoint="coding-deepgent",
+        agent_name="coding-deepgent",
+    )
+    middleware = RuntimePressureMiddleware(
+        registry=registry,
+        auto_compact_threshold_tokens=None,
+        keep_recent_tool_results=0,
+        microcompact_time_gap_minutes=60,
+        main_entrypoint="coding-deepgent",
+        main_agent_name="coding-deepgent",
+        now=lambda: datetime(2026, 4, 16, 12, 5, tzinfo=timezone.utc),
+    )
+    captured: dict[str, object] = {}
+
+    def handler(request: ModelRequest):
+        captured["messages"] = request.messages
+        return _ok_response()
+
+    request = _request(
+        model=_unused_model(),
+        messages=[
+            HumanMessage(content="inspect files"),
+            _read_call("call-1"),
+            ToolMessage(content="x" * 500, tool_call_id="call-1"),
+            _assistant_at("2026-04-16T10:00:00Z"),
+            _read_call("call-2"),
+            ToolMessage(content="y" * 500, tool_call_id="call-2"),
+            _read_call("call-3"),
+            ToolMessage(content="z" * 500, tool_call_id="call-3"),
+        ],
+        context=context,
+    )
+
+    middleware.wrap_model_call(request, handler)
+
+    messages = captured["messages"]
+    assert isinstance(messages, list)
+    assert messages[2].content == MICROCOMPACT_CLEARED_MESSAGE
+    assert messages[5].content == MICROCOMPACT_CLEARED_MESSAGE
+    assert messages[7].content == "z" * 500
+    events = _events(context)
+    assert [event.kind for event in events] == ["microcompact", "token_budget"]
+    assert events[0].metadata["trigger"] == "time_gap"
+    assert events[0].metadata["gap_minutes"] == 125
+    assert events[0].metadata["tools_cleared"] == 2
+    assert events[0].metadata["tools_kept"] == 1
+    assert events[0].metadata["keep_recent"] == 1
+    assert events[0].metadata["tokens_saved_estimate"] > 0
+
+
+def test_runtime_pressure_middleware_runs_token_budget_microcompact(
+    tmp_path: Path,
+) -> None:
+    registry = build_default_registry(include_discovery=True)
+    context = runtime_context(tmp_path)
+    middleware = RuntimePressureMiddleware(
+        registry=registry,
+        auto_compact_threshold_tokens=None,
+        keep_recent_tool_results=0,
+        microcompact_protect_recent_tokens=100,
+    )
+
+    request = _request(
+        model=_unused_model(),
+        messages=[
+            _read_call("call-1"),
+            ToolMessage(content="a" * 400, tool_call_id="call-1"),
+            _read_call("call-2"),
+            ToolMessage(content="b" * 160, tool_call_id="call-2"),
+            _read_call("call-3"),
+            ToolMessage(content="c" * 160, tool_call_id="call-3"),
+            _read_call("call-4"),
+            ToolMessage(content="d" * 160, tool_call_id="call-4"),
+        ],
+        context=context,
+    )
+
+    middleware.wrap_model_call(request, lambda _request: _ok_response())
+
+    events = _events(context)
+    assert [event.kind for event in events] == ["microcompact", "token_budget"]
+    assert events[0].metadata["tools_cleared"] == 2
+    assert events[0].metadata["tools_kept"] == 2
+    assert events[0].metadata["keep_recent"] == 2
+    assert events[0].metadata["protected_recent_tokens"] == 100
+    assert events[0].metadata["tokens_saved_estimate"] > 0
+
+
+def test_time_based_microcompact_min_saved_tokens_skips_low_value_clear(
+    tmp_path: Path,
+) -> None:
+    registry = build_default_registry(include_discovery=True)
+    context = runtime_context(
+        tmp_path,
+        entrypoint="coding-deepgent",
+        agent_name="coding-deepgent",
+    )
+    middleware = RuntimePressureMiddleware(
+        registry=registry,
+        auto_compact_threshold_tokens=None,
+        keep_recent_tool_results=0,
+        min_content_chars=1,
+        microcompact_time_gap_minutes=60,
+        microcompact_min_saved_tokens=10_000,
+        main_entrypoint="coding-deepgent",
+        main_agent_name="coding-deepgent",
+        now=lambda: datetime(2026, 4, 16, 12, 5, tzinfo=timezone.utc),
+    )
+    captured: dict[str, object] = {}
+
+    request = _request(
+        model=_unused_model(),
+        messages=[
+            _assistant_at("2026-04-16T10:00:00Z"),
+            _read_call("call-1"),
+            ToolMessage(content="x" * 100, tool_call_id="call-1"),
+            _read_call("call-2"),
+            ToolMessage(content="y" * 100, tool_call_id="call-2"),
+        ],
+        context=context,
+    )
+
+    def handler(active_request: ModelRequest):
+        captured["messages"] = active_request.messages
+        return _ok_response()
+
+    middleware.wrap_model_call(request, handler)
+
+    messages = captured["messages"]
+    assert isinstance(messages, list)
+    assert messages[2].content == "x" * 100
+    assert messages[4].content == "y" * 100
+    assert [event.kind for event in _events(context)] == ["token_budget"]
+
+
+def test_collapse_live_messages_with_summary_preserves_tool_pair_in_tail() -> None:
+    messages = [
+        HumanMessage(content="old request"),
+        _read_call("call-1"),
+        ToolMessage(content="result", tool_call_id="call-1"),
+    ]
+
+    collapsed = collapse_live_messages_with_summary(
+        messages,
+        summary="Earlier work was collapsed.",
+        keep_recent_messages=1,
+    )
+
+    assert str(collapsed[0].content).startswith(LIVE_COLLAPSE_BOUNDARY_PREFIX)
+    assert str(collapsed[1].content).startswith(LIVE_COLLAPSE_SUMMARY_PREFIX)
+    assert isinstance(collapsed[2], AIMessage)
+    assert isinstance(collapsed[3], ToolMessage)
+
+
+def test_collapse_live_messages_with_summary_preserves_recent_assistant_round() -> None:
+    messages = [
+        HumanMessage(content="old request"),
+        _read_call("call-1"),
+        ToolMessage(content="result", tool_call_id="call-1"),
+        AIMessage(content="assistant checkpoint"),
+        HumanMessage(content="latest user prompt"),
+    ]
+
+    collapsed = collapse_live_messages_with_summary(
+        messages,
+        summary="Earlier work was collapsed.",
+        keep_recent_messages=1,
+    )
+
+    assert str(collapsed[0].content).startswith(LIVE_COLLAPSE_BOUNDARY_PREFIX)
+    assert str(collapsed[1].content).startswith(LIVE_COLLAPSE_SUMMARY_PREFIX)
+    assert isinstance(collapsed[2], AIMessage)
+    assert collapsed[2].content == "assistant checkpoint"
+    assert isinstance(collapsed[3], HumanMessage)
+    assert collapsed[3].content == "latest user prompt"
+
+
+def test_compact_live_messages_with_summary_preserves_tool_pair_in_tail() -> None:
+    messages = [
+        HumanMessage(content="old request"),
+        _read_call("call-1"),
+        ToolMessage(content="result", tool_call_id="call-1"),
+    ]
+
+    compacted = compact_live_messages_with_summary(
+        messages,
+        summary="Keep the recent tool exchange.",
+        keep_recent_messages=1,
+    )
+
+    assert str(compacted[0].content).startswith(LIVE_COMPACT_BOUNDARY_PREFIX)
+    assert str(compacted[1].content).startswith(LIVE_COMPACT_SUMMARY_PREFIX)
+    assert isinstance(compacted[2], AIMessage)
+    assert isinstance(compacted[3], ToolMessage)
+
+
+def test_live_compaction_result_renders_stable_order_with_metadata() -> None:
+    messages = [
+        HumanMessage(content="old request"),
+        _read_call("call-1"),
+        ToolMessage(
+            content="preview",
+            tool_call_id="call-1",
+            artifact={
+                "kind": "persisted_output",
+                "path": ".coding-deepgent/tool-results/session-1/call-1.txt",
+            },
+        ),
+        HumanMessage(content="recent request"),
+    ]
+
+    result = compact_live_messages_with_result(
+        messages,
+        summary="Keep the continuation moving.",
+        keep_recent_messages=1,
+    )
+    rendered = result.render()
+
+    assert result.trigger == "auto_compact"
+    assert result.original_token_estimate > 0
+    assert result.projected_token_estimate > 0
+    assert result.restored_path_count == 1
+    assert str(rendered[0].content).startswith(LIVE_COMPACT_BOUNDARY_PREFIX)
+    assert str(rendered[1].content).startswith(LIVE_COMPACT_SUMMARY_PREFIX)
+    assert str(rendered[2].content).startswith(LIVE_COMPACT_RESTORATION_PREFIX)
+    assert rendered[3].content == "recent request"
+
+
+def test_live_collapse_result_renders_stable_order() -> None:
+    messages = [
+        HumanMessage(content="old request"),
+        HumanMessage(content="recent request"),
+    ]
+
+    result = collapse_live_messages_with_result(
+        messages,
+        summary="Earlier context collapsed.",
+        keep_recent_messages=1,
+    )
+    rendered = result.render()
+
+    assert result.trigger == "context_collapse"
+    assert result.restored_path_count == 0
+    assert str(rendered[0].content).startswith(LIVE_COLLAPSE_BOUNDARY_PREFIX)
+    assert str(rendered[1].content).startswith(LIVE_COLLAPSE_SUMMARY_PREFIX)
+    assert rendered[2].content == "recent request"
+
+
+def test_compact_result_restores_active_todos_from_runtime_state() -> None:
+    messages = [
+        HumanMessage(content="old request"),
+        HumanMessage(content="recent request"),
+    ]
+
+    result = compact_live_messages_with_result(
+        messages,
+        summary="Keep the active plan.",
+        keep_recent_messages=1,
+        state={
+            "todos": [
+                {
+                    "content": "Inspect runtime pressure tests",
+                    "status": "in_progress",
+                    "activeForm": "Inspecting runtime pressure tests",
+                },
+                {
+                    "content": "Run verification",
+                    "status": "pending",
+                    "activeForm": "Running verification",
+                },
+                {
+                    "content": "Done item",
+                    "status": "completed",
+                    "activeForm": "Done",
+                },
+            ]
+        },
+    )
+
+    rendered = result.render()
+    assert str(rendered[2].content).startswith("Post-compact restored state:")
+    assert "[in_progress] Inspect runtime pressure tests" in str(rendered[2].content)
+    assert "[pending] Run verification" in str(rendered[2].content)
+    assert "Done item" not in str(rendered[2].content)
+    assert rendered[3].content == "recent request"
+
+
+def test_auto_compact_uses_pre_and_post_compact_hook_context(tmp_path: Path) -> None:
+    registry = build_default_registry(include_discovery=True)
+    summarizer = FakeSummarizer("<summary>Hook-aware compact summary.</summary>")
+    context = runtime_context(tmp_path)
+    context.hook_registry.register(
+        "PreCompact",
+        lambda _payload: HookResult(additional_context="Preserve schema decisions."),
+    )
+    context.hook_registry.register(
+        "PostCompact",
+        lambda _payload: HookResult(additional_context="Reinforce project constraints."),
+    )
+    middleware = RuntimePressureMiddleware(
+        registry=registry,
+        auto_compact_threshold_tokens=10,
+        keep_recent_messages=1,
+    )
+    captured: dict[str, object] = {}
+
+    request = _request(
+        model=summarizer,
+        messages=[
+            HumanMessage(content="x" * 5000),
+            HumanMessage(content="y" * 5000),
+        ],
+        context=context,
+    )
+
+    def handler(active_request: ModelRequest):
+        captured["messages"] = active_request.messages
+        return _ok_response()
+
+    middleware.wrap_model_call(request, handler)
+
+    assert any(
+        "Preserve schema decisions." in str(item.get("content"))
+        for item in summarizer.requests[0]
+    )
+    messages = captured["messages"]
+    assert isinstance(messages, list)
+    assert "PostCompact hook context:" in str(messages[2].content)
+    assert "Reinforce project constraints." in str(messages[2].content)
+
+
+def test_maybe_collapse_messages_uses_summary_when_threshold_exceeded() -> None:
+    summarizer = FakeSummarizer("<summary>Generated collapse summary.</summary>")
+    messages = [
+        HumanMessage(content="x" * 5000),
+        HumanMessage(content="y" * 5000),
+    ]
+
+    collapsed = maybe_collapse_messages(
+        messages,
+        summarizer=summarizer,
+        threshold_tokens=10,
+        keep_recent_messages=1,
+    )
+
+    assert len(summarizer.requests) == 1
+    assert str(collapsed[0].content).startswith(LIVE_COLLAPSE_BOUNDARY_PREFIX)
+    assert "Generated collapse summary." in str(collapsed[1].content)
+    assert collapsed[2].content == "y" * 5000
+
+
+def test_maybe_collapse_messages_uses_pressure_ratio_when_configured() -> None:
+    summarizer = FakeSummarizer("<summary>Ratio collapse summary.</summary>")
+    messages = [
+        HumanMessage(content="x" * 5000),
+        HumanMessage(content="y" * 5000),
+    ]
+
+    collapsed = maybe_collapse_messages(
+        messages,
+        summarizer=summarizer,
+        threshold_tokens=None,
+        context_window_tokens=3000,
+        trigger_ratio=0.5,
+        keep_recent_messages=1,
+    )
+
+    assert len(summarizer.requests) == 1
+    assert str(collapsed[0].content).startswith(LIVE_COLLAPSE_BOUNDARY_PREFIX)
+    assert "Ratio collapse summary." in str(collapsed[1].content)
+
+
+def test_maybe_collapse_messages_fails_open_on_summarizer_error() -> None:
+    def failing_summarizer(_messages):
+        raise RuntimeError("collapse unavailable")
+
+    messages = [
+        HumanMessage(content="x" * 5000),
+        HumanMessage(content="y" * 5000),
+    ]
+
+    collapsed = maybe_collapse_messages(
+        messages,
+        summarizer=failing_summarizer,
+        threshold_tokens=10,
+        keep_recent_messages=1,
+    )
+
+    assert collapsed == messages
+
+
+def test_runtime_pressure_middleware_persists_collapse_record_when_projection_exists(
+    tmp_path: Path,
+) -> None:
+    store = JsonlSessionStore(tmp_path / "sessions-store")
+    context = runtime_context(
+        tmp_path,
+        session_store=store,
+        transcript_projection=TranscriptProjection(
+            entries=(("msg-000000",), ("msg-000001",))
+        ),
+    )
+    assert context.session_context is not None
+    store.append_message(context.session_context, role="assistant", content="continue")
+    middleware = RuntimePressureMiddleware(
+        registry=build_default_registry(include_discovery=True),
+        collapse_threshold_tokens=10,
+        keep_recent_messages_after_collapse=1,
+        auto_compact_threshold_tokens=None,
+    )
+    request = _request(
+        model=FakeSummarizer("<summary>Generated collapse summary.</summary>"),
+        messages=[
+            HumanMessage(content="x" * 5000),
+            HumanMessage(content="y" * 5000),
+        ],
+        context=context,
+    )
+
+    middleware.wrap_model_call(request, lambda active_request: _ok_response())
+
+    raw_records = [
+        json.loads(line)
+        for line in context.session_context.transcript_path.read_text(encoding="utf-8").splitlines()
+    ]
+    collapse_records = [
+        record for record in raw_records if record.get("event_kind") == COLLAPSE_EVENT_KIND
+    ]
+    loaded = store.load_session(session_id="session-1", workdir=tmp_path)
+
+    assert len(collapse_records) == 1
+    assert loaded.summary.collapse_count == 1
+    assert loaded.collapses[0].summary == "Generated collapse summary."
+    assert loaded.collapses[0].start_message_id == "msg-000000"
+    assert loaded.collapses[0].end_message_id == "msg-000000"
+    assert loaded.collapses[0].covered_message_ids == ("msg-000000",)
+    assert loaded.collapses[0].metadata is not None
+    collapse_metadata = loaded.collapses[0].metadata
+    assert collapse_metadata is not None
+    assert collapse_metadata["source"] == "runtime_pressure"
+
+
+def test_runtime_pressure_middleware_persists_collapse_record_using_assistant_round_boundary(
+    tmp_path: Path,
+) -> None:
+    store = JsonlSessionStore(tmp_path / "sessions-store")
+    context = runtime_context(
+        tmp_path,
+        session_store=store,
+        transcript_projection=TranscriptProjection(
+            entries=(
+                ("msg-000000",),
+                ("msg-000001",),
+                ("msg-000002",),
+                ("msg-000003",),
+                ("msg-000004",),
+            )
+        ),
+    )
+    assert context.session_context is not None
+    store.append_message(context.session_context, role="assistant", content="assistant one")
+    store.append_message(context.session_context, role="user", content="tool result one")
+    store.append_message(context.session_context, role="assistant", content="assistant two")
+    store.append_message(context.session_context, role="user", content="latest user prompt")
+    middleware = RuntimePressureMiddleware(
+        registry=build_default_registry(include_discovery=True),
+        collapse_threshold_tokens=10,
+        keep_recent_messages_after_collapse=1,
+        auto_compact_threshold_tokens=None,
+    )
+    request = _request(
+        model=FakeSummarizer("<summary>Generated collapse summary.</summary>"),
+        messages=[
+            HumanMessage(content="x" * 5000),
+            _read_call("call-1"),
+            ToolMessage(content="result", tool_call_id="call-1"),
+            AIMessage(content="assistant checkpoint"),
+            HumanMessage(content="latest user prompt"),
+        ],
+        context=context,
+    )
+
+    middleware.wrap_model_call(request, lambda active_request: _ok_response())
+
+    loaded = store.load_session(session_id="session-1", workdir=tmp_path)
+
+    assert loaded.summary.collapse_count == 1
+    assert loaded.collapses[0].start_message_id == "msg-000000"
+    assert loaded.collapses[0].end_message_id == "msg-000002"
+    assert loaded.collapses[0].covered_message_ids == (
+        "msg-000000",
+        "msg-000001",
+        "msg-000002",
+    )
+
+
+def test_runtime_pressure_middleware_drains_collapse_projection_before_reactive_compact(
+    tmp_path: Path,
+) -> None:
+    middleware = RuntimePressureMiddleware(
+        registry=build_default_registry(include_discovery=True),
+        collapse_threshold_tokens=10,
+        keep_recent_messages_after_collapse=1,
+        auto_compact_threshold_tokens=None,
+    )
+    context = runtime_context(tmp_path)
+    calls: list[list[BaseMessage]] = []
+    request = _request(
+        model=FakeSummarizer("<summary>Generated collapse summary.</summary>"),
+        messages=[
+            HumanMessage(content="x" * 5000),
+            HumanMessage(content="y" * 5000),
+        ],
+        context=context,
+    )
+
+    def handler(active_request: ModelRequest):
+        calls.append(list(active_request.messages))
+        if len(calls) == 1:
+            raise RuntimeError("prompt too long for current context window")
+        return _ok_response()
+
+    middleware.wrap_model_call(request, handler)
+
+    assert len(calls) == 2
+    assert str(calls[0][0].content).startswith(LIVE_COLLAPSE_BOUNDARY_PREFIX)
+    assert str(calls[0][1].content).startswith(LIVE_COLLAPSE_SUMMARY_PREFIX)
+    assert str(calls[1][0].content).startswith(LIVE_COLLAPSE_BOUNDARY_PREFIX)
+    assert "overflow_drain" in str(calls[1][0].content)
+    assert all(
+        not str(message.content).startswith(LIVE_COLLAPSE_SUMMARY_PREFIX)
+        for message in calls[1]
+        if hasattr(message, "content")
+    )
+    assert [event.kind for event in _events(context)] == [
+        "context_collapse",
+        "context_collapse",
+        "token_budget",
+        "post_autocompact_turn",
+    ]
+
+
+def test_drain_collapse_projection_messages_removes_summary() -> None:
+    drained = drain_collapse_projection_messages(
+        collapse_live_messages_with_summary(
+            [
+                HumanMessage(content="old"),
+                HumanMessage(content="recent"),
+            ],
+            summary="Collapsed context.",
+            keep_recent_messages=1,
+        )
+    )
+
+    assert str(drained[0].content).startswith(LIVE_COLLAPSE_BOUNDARY_PREFIX)
+    assert "overflow_drain" in str(drained[0].content)
+    assert drained[1].content == "recent"
+
+
+def test_maybe_auto_compact_messages_uses_summary_when_threshold_exceeded() -> None:
+    summarizer = FakeSummarizer("<summary>Generated compact summary.</summary>")
+    messages = [
+        HumanMessage(content="x" * 5000),
+        HumanMessage(content="y" * 5000),
+    ]
+
+    compacted = maybe_auto_compact_messages(
+        messages,
+        summarizer=summarizer,
+        threshold_tokens=10,
+        keep_recent_messages=1,
+    )
+
+    assert len(summarizer.requests) == 1
+    assert estimate_message_tokens(messages) > 10
+    assert str(compacted[0].content).startswith(LIVE_COMPACT_BOUNDARY_PREFIX)
+    assert "Generated compact summary." in str(compacted[1].content)
+    assert compacted[2].content == "y" * 5000
+
+
+def test_runtime_pressure_middleware_runs_snip_microcollapse_autocompact_order(
+    tmp_path: Path,
+) -> None:
+    registry = build_default_registry(include_discovery=True)
+    summarizer = FakeSummarizer("<summary>Generated pressure summary.</summary>")
+    context = runtime_context(tmp_path)
+    middleware = RuntimePressureMiddleware(
+        registry=registry,
+        snip_threshold_tokens=10,
+        keep_recent_messages_after_snip=8,
+        keep_recent_tool_results=1,
+        collapse_threshold_tokens=10,
+        keep_recent_messages_after_collapse=2,
+        auto_compact_threshold_tokens=10,
+        keep_recent_messages=1,
+    )
+    captured: dict[str, object] = {}
+
+    def handler(request: ModelRequest):
+        captured["messages"] = request.messages
+        return _ok_response()
+
+    request = _request(
+        model=summarizer,
+        messages=[
+            HumanMessage(content="old context " * 1000),
+            HumanMessage(content="older context " * 1000),
+            _read_call("call-1"),
+            ToolMessage(content="x" * 500, tool_call_id="call-1"),
+            _read_call("call-2"),
+            ToolMessage(content="y" * 500, tool_call_id="call-2"),
+            _read_call("call-3"),
+            ToolMessage(content="z" * 500, tool_call_id="call-3"),
+            HumanMessage(content="tail one " * 5000),
+            HumanMessage(content="tail two " * 5000),
+        ],
+        context=context,
+    )
+
+    middleware.wrap_model_call(request, handler)
+
+    assert [event.kind for event in _events(context)] == [
+        "snip",
+        "microcompact",
+        "context_collapse",
+        "auto_compact",
+        "auto_compact",
+        "token_budget",
+        "post_autocompact_turn",
+    ]
+    assert len(summarizer.requests) == 2
+    messages = captured["messages"]
+    assert isinstance(messages, list)
+    assert str(messages[0].content).startswith(LIVE_COMPACT_BOUNDARY_PREFIX)
+    assert "Generated pressure summary." in str(messages[1].content)
+
+
+def test_compact_live_messages_with_summary_restores_persisted_output_paths() -> None:
+    messages = [
+        HumanMessage(content="old request"),
+        _read_call("call-1"),
+        ToolMessage(
+            content="preview",
+            tool_call_id="call-1",
+            artifact={"kind": "persisted_output", "path": ".coding-deepgent/tool-results/session-1/call-1.txt"},
+        ),
+        HumanMessage(content="recent request"),
+    ]
+
+    compacted = compact_live_messages_with_summary(
+        messages,
+        summary="Keep the continuation moving.",
+        keep_recent_messages=1,
+    )
+
+    assert str(compacted[2].content).startswith(LIVE_COMPACT_RESTORATION_PREFIX)
+    assert ".coding-deepgent/tool-results/session-1/call-1.txt" in str(compacted[2].content)
+    assert compacted[3].content == "recent request"
+
+
+def test_runtime_pressure_middleware_auto_compacts_when_threshold_is_crossed() -> None:
+    registry = build_default_registry(include_discovery=True)
+    summarizer = FakeSummarizer("<summary>Generated compact summary.</summary>")
+    middleware = RuntimePressureMiddleware(
+        registry=registry,
+        auto_compact_threshold_tokens=10,
+        keep_recent_messages=1,
+    )
+    captured: dict[str, object] = {}
+
+    def handler(request: ModelRequest):
+        captured["messages"] = request.messages
+        return _ok_response()
+
+    request = _request(
+        model=summarizer,
+        messages=[
+            HumanMessage(content="x" * 5000),
+            HumanMessage(content="y" * 5000),
+        ],
+        context=runtime_context(Path.cwd()),
+    )
+
+    middleware.wrap_model_call(request, handler)
+
+    compacted = captured["messages"]
+    assert isinstance(compacted, list)
+    assert str(compacted[0].content).startswith(LIVE_COMPACT_BOUNDARY_PREFIX)
+    assert "Generated compact summary." in str(compacted[1].content)
+    assert compacted[2].content == "y" * 5000
+
+
+def test_runtime_pressure_middleware_refreshes_session_memory_after_auto_compact() -> None:
+    registry = build_default_registry(include_discovery=True)
+    summarizer = FakeSummarizer("<summary>Generated compact summary.</summary>")
+    middleware = RuntimePressureMiddleware(
+        registry=registry,
+        auto_compact_threshold_tokens=10,
+        keep_recent_messages=1,
+    )
+    state: dict[str, Any] = {"messages": []}
+
+    request = _request(
+        model=summarizer,
+        messages=[
+            HumanMessage(content="x" * 5000),
+            HumanMessage(content="y" * 5000),
+        ],
+        state=state,
+        context=runtime_context(Path.cwd()),
+    )
+
+    middleware.wrap_model_call(request, lambda _request: _ok_response())
+
+    assert state["session_memory"] == {
+        "content": "Generated compact summary.",
+        "source": "live_compact",
+        "message_count": 2,
+        "updated_at": state["session_memory"]["updated_at"],
+        "token_count": 2500,
+        "tool_call_count": 0,
+    }
+
+
+def test_auto_compact_failure_circuit_breaker_skips_after_max_failures(
+    tmp_path: Path,
+) -> None:
+    registry = build_default_registry(include_discovery=True)
+    summarizer = FailingSummarizer()
+    context = runtime_context(tmp_path)
+    middleware = RuntimePressureMiddleware(
+        registry=registry,
+        auto_compact_threshold_tokens=10,
+        auto_compact_max_failures=2,
+        keep_recent_messages=1,
+    )
+    handler_calls = 0
+
+    def handler(_request: ModelRequest):
+        nonlocal handler_calls
+        handler_calls += 1
+        return _ok_response()
+
+    def request() -> ModelRequest:
+        return _request(
+            model=summarizer,
+            messages=[
+                HumanMessage(content="x" * 5000),
+                HumanMessage(content="y" * 5000),
+            ],
+            context=context,
+        )
+
+    middleware.wrap_model_call(request(), handler)
+    middleware.wrap_model_call(request(), handler)
+    middleware.wrap_model_call(request(), handler)
+
+    assert handler_calls == 3
+    assert len(summarizer.requests) == 2
+    events = _events(context)
+    assert [event.kind for event in events] == [
+        "auto_compact",
+        "token_budget",
+        "auto_compact",
+        "token_budget",
+        "auto_compact",
+        "token_budget",
+    ]
+    assert events[0].metadata["outcome"] == "attempted"
+    assert events[2].metadata["outcome"] == "attempted"
+    assert events[4].metadata == {
+        "source": "runtime_pressure",
+        "strategy": "auto",
+        "trigger": "failure_circuit_breaker",
+        "failure_count": 2,
+        "max_failures": 2,
+    }
+
+
+def test_auto_compact_success_resets_failure_circuit_breaker(tmp_path: Path) -> None:
+    registry = build_default_registry(include_discovery=True)
+    failing = FailingSummarizer()
+    first_success = FakeSummarizer("<summary>Recovered compact summary.</summary>")
+    second_success = FakeSummarizer("<summary>Still allowed summary.</summary>")
+    context = runtime_context(tmp_path)
+    middleware = RuntimePressureMiddleware(
+        registry=registry,
+        auto_compact_threshold_tokens=10,
+        auto_compact_max_failures=2,
+        keep_recent_messages=1,
+    )
+
+    def request(model: BaseChatModel) -> ModelRequest:
+        return _request(
+            model=model,
+            messages=[
+                HumanMessage(content="x" * 5000),
+                HumanMessage(content="y" * 5000),
+            ],
+            context=context,
+        )
+
+    middleware.wrap_model_call(request(failing), lambda _request: _ok_response())
+    middleware.wrap_model_call(
+        request(first_success), lambda _request: _ok_response()
+    )
+    middleware.wrap_model_call(request(failing), lambda _request: _ok_response())
+    middleware.wrap_model_call(
+        request(second_success), lambda _request: _ok_response()
+    )
+
+    assert len(failing.requests) == 2
+    assert len(first_success.requests) == 1
+    assert len(second_success.requests) == 1
+    assert [event.kind for event in _events(context)] == [
+        "auto_compact",
+        "token_budget",
+        "auto_compact",
+        "auto_compact",
+        "token_budget",
+        "post_autocompact_turn",
+        "auto_compact",
+        "token_budget",
+        "auto_compact",
+        "auto_compact",
+        "token_budget",
+        "post_autocompact_turn",
+    ]
+
+
+def test_auto_compact_retries_prompt_too_long_summary_source() -> None:
+    registry = build_default_registry(include_discovery=True)
+    summarizer = PromptTooLongThenSuccessSummarizer(
+        "<summary>Retry compact summary.</summary>"
+    )
+    middleware = RuntimePressureMiddleware(
+        registry=registry,
+        auto_compact_threshold_tokens=10,
+        auto_compact_ptl_retry_limit=1,
+        keep_recent_messages=1,
+    )
+    captured: dict[str, object] = {}
+
+    request = _request(
+        model=summarizer,
+        messages=[
+            HumanMessage(content="oldest context " * 500),
+            HumanMessage(content="x" * 5000),
+            HumanMessage(content="y" * 5000),
+        ],
+        context=runtime_context(Path.cwd()),
+    )
+
+    def handler(active_request: ModelRequest):
+        captured["messages"] = active_request.messages
+        return _ok_response()
+
+    middleware.wrap_model_call(request, handler)
+
+    assert len(summarizer.requests) == 2
+    assert len(summarizer.requests[1]) < len(summarizer.requests[0])
+    messages = captured["messages"]
+    assert isinstance(messages, list)
+    assert str(messages[0].content).startswith(LIVE_COMPACT_BOUNDARY_PREFIX)
+    assert "Retry compact summary." in str(messages[1].content)
+
+
+def test_auto_compact_does_not_retry_non_prompt_too_long_failure() -> None:
+    summarizer = FailingSummarizer()
+
+    maybe_auto_compact_messages(
+        [
+            HumanMessage(content="x" * 5000),
+            HumanMessage(content="y" * 5000),
+        ],
+        summarizer=summarizer,
+        threshold_tokens=10,
+        keep_recent_messages=1,
+        ptl_retry_limit=3,
+    )
+
+    assert len(summarizer.requests) == 1
+
+
+def test_auto_compact_exhausted_ptl_retries_can_trip_circuit_breaker(
+    tmp_path: Path,
+) -> None:
+    registry = build_default_registry(include_discovery=True)
+    summarizer = PromptTooLongSummarizer()
+    context = runtime_context(tmp_path)
+    middleware = RuntimePressureMiddleware(
+        registry=registry,
+        auto_compact_threshold_tokens=10,
+        auto_compact_max_failures=1,
+        auto_compact_ptl_retry_limit=1,
+        keep_recent_messages=1,
+    )
+
+    def request() -> ModelRequest:
+        return _request(
+            model=summarizer,
+            messages=[
+                HumanMessage(content="oldest context " * 500),
+                HumanMessage(content="x" * 5000),
+                HumanMessage(content="y" * 5000),
+            ],
+            context=context,
+        )
+
+    middleware.wrap_model_call(request(), lambda _request: _ok_response())
+    middleware.wrap_model_call(request(), lambda _request: _ok_response())
+
+    assert len(summarizer.requests) == 2
+    events = _events(context)
+    assert [event.kind for event in events] == [
+        "auto_compact",
+        "token_budget",
+        "auto_compact",
+        "token_budget",
+    ]
+    assert events[2].metadata["trigger"] == "failure_circuit_breaker"
+
+
+def test_runtime_pressure_middleware_emits_microcompact_and_auto_events(
+    tmp_path: Path,
+) -> None:
+    registry = build_default_registry(include_discovery=True)
+    summarizer = FakeSummarizer("<summary>Generated compact summary.</summary>")
+    context = runtime_context(tmp_path)
+    middleware = RuntimePressureMiddleware(
+        registry=registry,
+        auto_compact_threshold_tokens=10,
+        keep_recent_tool_results=1,
+        keep_recent_messages=1,
+    )
+
+    request = _request(
+        model=summarizer,
+        messages=[
+            HumanMessage(content="inspect files"),
+            _read_call("call-1"),
+            ToolMessage(content="x" * 500, tool_call_id="call-1"),
+            _read_call("call-2"),
+            ToolMessage(content="y" * 500, tool_call_id="call-2"),
+            _read_call("call-3"),
+            ToolMessage(content="z" * 500, tool_call_id="call-3"),
+            HumanMessage(content="tail"),
+        ],
+        context=context,
+    )
+
+    middleware.wrap_model_call(request, lambda _request: _ok_response())
+
+    events = _events(context)
+    assert [event.kind for event in events] == [
+        "microcompact",
+        "auto_compact",
+        "auto_compact",
+        "token_budget",
+        "post_autocompact_turn",
+    ]
+    assert events[0].metadata["source"] == "runtime_pressure"
+    assert events[0].metadata["strategy"] == "microcompact"
+    assert events[0].metadata["cleared_tool_results"] == 2
+    assert events[0].metadata["tools_cleared"] == 2
+    assert events[0].metadata["tools_kept"] == 1
+    assert events[0].metadata["tokens_saved_estimate"] > 0
+    assert events[0].metadata["keep_recent"] == 1
+    assert events[1].metadata["outcome"] == "attempted"
+    assert events[2].metadata == {
+        "source": "runtime_pressure",
+        "strategy": "auto",
+        "outcome": "succeeded",
+        "pre_compact_total": events[2].metadata["pre_compact_total"],
+        "post_compact_total": events[2].metadata["post_compact_total"],
+        "tokens_saved_estimate": events[2].metadata["tokens_saved_estimate"],
+        "hidden_messages": events[2].metadata["hidden_messages"],
+        "used_session_memory_assist": False,
+        "restored_path_count": 0,
+    }
+    assert events[3].metadata["input_token_estimate"] > 0
+    assert events[3].metadata["output_token_estimate"] > 0
+    assert events[4].metadata["pre_compact_total"] == events[2].metadata["pre_compact_total"]
+    assert events[4].metadata["post_compact_total"] == events[2].metadata["post_compact_total"]
+    assert events[4].metadata["new_turn_input"] == events[3].metadata["input_token_estimate"]
+    assert events[4].metadata["new_turn_output"] == events[3].metadata["output_token_estimate"]
+
+
+def test_runtime_pressure_model_request_dump_is_env_gated(
+    tmp_path: Path,
+    monkeypatch,
+) -> None:
+    registry = build_default_registry(include_discovery=True)
+    context = runtime_context(tmp_path)
+    middleware = RuntimePressureMiddleware(
+        registry=registry,
+        auto_compact_threshold_tokens=None,
+    )
+
+    request = _request(
+        model=_unused_model(),
+        messages=[HumanMessage(content="hello dump")],
+        model_settings={"api_key": "secret", "temperature": 0},
+        context=context,
+    )
+
+    middleware.wrap_model_call(request, lambda _request: _ok_response())
+    dump_path = (
+        tmp_path
+        / ".coding-deepgent"
+        / "prompt-dumps"
+        / "session-1__test-agent.jsonl"
+    )
+    assert not dump_path.exists()
+
+    monkeypatch.setenv("CODING_DEEPGENT_DUMP_PROMPTS", "1")
+    middleware.wrap_model_call(request, lambda _request: _ok_response())
+
+    record = json.loads(dump_path.read_text(encoding="utf-8").splitlines()[0])
+    assert record["record_type"] == "model_request"
+    assert record["messages"][0]["content"] == "hello dump"
+    assert record["model_settings"]["api_key"] == "<redacted>"
+
+
+def test_maybe_auto_compact_messages_passes_session_memory_assist() -> None:
+    summarizer = FakeSummarizer("<summary>Generated compact summary.</summary>")
+    messages = [
+        HumanMessage(content="x" * 5000),
+        HumanMessage(content="y" * 5000),
+    ]
+
+    maybe_auto_compact_messages(
+        messages,
+        summarizer=summarizer,
+        threshold_tokens=10,
+        keep_recent_messages=1,
+        assist_context="Session memory artifact:\nKeep repo focus.",
+    )
+
+    assert len(summarizer.requests) == 1
+    assert summarizer.requests[0][-2]["role"] == "system"
+    assert "Keep repo focus." in str(summarizer.requests[0][-2]["content"])
+
+
+def test_reactive_compact_messages_uses_summarizer_without_threshold() -> None:
+    summarizer = FakeSummarizer("<summary>Reactive compact summary.</summary>")
+    messages = [
+        HumanMessage(content="x" * 5000),
+        HumanMessage(content="y" * 5000),
+    ]
+
+    compacted = reactive_compact_messages(
+        messages,
+        summarizer=summarizer,
+        keep_recent_messages=1,
+    )
+
+    assert len(summarizer.requests) == 1
+    assert str(compacted[0].content).startswith(LIVE_COMPACT_BOUNDARY_PREFIX)
+    assert "Reactive compact summary." in str(compacted[1].content)
+
+
+def test_runtime_pressure_middleware_retries_once_on_prompt_too_long() -> None:
+    registry = build_default_registry(include_discovery=True)
+    summarizer = FakeSummarizer("<summary>Reactive compact summary.</summary>")
+    context = runtime_context(Path.cwd())
+    middleware = RuntimePressureMiddleware(
+        registry=registry,
+        auto_compact_threshold_tokens=None,
+        keep_recent_messages=1,
+    )
+    calls: list[list[BaseMessage]] = []
+
+    def handler(request: ModelRequest):
+        calls.append(list(request.messages))
+        if len(calls) == 1:
+            raise RuntimeError("prompt too long for current context window")
+        return _ok_response()
+
+    request = _request(
+        model=summarizer,
+        messages=[
+            HumanMessage(content="x" * 5000),
+            HumanMessage(content="y" * 5000),
+        ],
+        context=context,
+    )
+
+    middleware.wrap_model_call(request, handler)
+
+    assert len(calls) == 2
+    assert [event.kind for event in _events(context)] == [
+        "reactive_compact",
+        "token_budget",
+    ]
+    assert str(calls[1][0].content).startswith(LIVE_COMPACT_BOUNDARY_PREFIX)
+    assert "Reactive compact summary." in str(calls[1][1].content)
+
+
+def test_is_prompt_too_long_error_matches_expected_phrases() -> None:
+    assert is_prompt_too_long_error(RuntimeError("maximum context length exceeded"))
+    assert not is_prompt_too_long_error(RuntimeError("permission denied"))
+
+
+def test_runtime_pressure_events_append_session_evidence(tmp_path: Path) -> None:
+    registry = build_default_registry(include_discovery=True)
+    session_store = JsonlSessionStore(tmp_path / "sessions")
+    context = runtime_context(tmp_path, session_store=session_store)
+    summarizer = FakeSummarizer("<summary>Generated compact summary.</summary>")
+    middleware = RuntimePressureMiddleware(
+        registry=registry,
+        auto_compact_threshold_tokens=10,
+        keep_recent_messages=1,
+    )
+
+    request = _request(
+        model=summarizer,
+        messages=[
+            HumanMessage(content="x" * 5000),
+            HumanMessage(content="y" * 5000),
+        ],
+        state={
+            "messages": [],
+            "session_memory": {
+                "content": "Keep repo focus.",
+                "source": "manual",
+                "message_count": 2,
+                "updated_at": "2026-04-15T00:00:00Z",
+            },
+        },
+        context=context,
+    )
+
+    middleware.wrap_model_call(request, lambda _request: _ok_response())
+    loaded = session_store.load_session(session_id="session-1", workdir=tmp_path)
+    rendered = render_recovery_brief(build_recovery_brief(loaded))
+
+    assert loaded.summary.evidence_count == 3
+    assert [item.metadata["event_kind"] for item in loaded.evidence if item.metadata] == [
+        "auto_compact",
+        "auto_compact",
+        "post_autocompact_turn",
+    ]
+    assert loaded.evidence[0].status == "recorded"
+    first_metadata = loaded.evidence[0].metadata
+    assert first_metadata is not None
+    assert first_metadata["outcome"] == "attempted"
+    assert loaded.evidence[1].kind == "runtime_event"
+    assert loaded.evidence[1].status == "completed"
+    second_metadata = loaded.evidence[1].metadata
+    assert second_metadata is not None
+    assert second_metadata == {
+        "event_kind": "auto_compact",
+        "source": "runtime_pressure",
+        "strategy": "auto",
+        "outcome": "succeeded",
+        "hidden_messages": second_metadata["hidden_messages"],
+        "pre_compact_total": second_metadata["pre_compact_total"],
+        "post_compact_total": second_metadata["post_compact_total"],
+        "tokens_saved_estimate": second_metadata["tokens_saved_estimate"],
+        "used_session_memory_assist": True,
+        "restored_path_count": 0,
+    }
+    third_metadata = loaded.evidence[2].metadata
+    assert third_metadata is not None
+    assert third_metadata == {
+        "event_kind": "post_autocompact_turn",
+        "source": "runtime_pressure",
+        "trigger": "auto_compact",
+        "pre_compact_total": third_metadata["pre_compact_total"],
+        "post_compact_total": third_metadata["post_compact_total"],
+        "new_turn_input": third_metadata["new_turn_input"],
+        "new_turn_output": third_metadata["new_turn_output"],
+    }
+    assert "[completed] runtime_event: Live auto-compact summarized history." in rendered
+
+
+def test_runtime_pressure_microcompact_evidence_includes_bounded_savings(
+    tmp_path: Path,
+) -> None:
+    registry = build_default_registry(include_discovery=True)
+    session_store = JsonlSessionStore(tmp_path / "sessions")
+    context = runtime_context(tmp_path, session_store=session_store)
+    middleware = RuntimePressureMiddleware(
+        registry=registry,
+        auto_compact_threshold_tokens=None,
+        keep_recent_tool_results=1,
+    )
+
+    request = _request(
+        model=_unused_model(),
+        messages=[
+            HumanMessage(content="inspect files"),
+            _read_call("call-1"),
+            ToolMessage(content="x" * 500, tool_call_id="call-1"),
+            _read_call("call-2"),
+            ToolMessage(content="y" * 500, tool_call_id="call-2"),
+        ],
+        context=context,
+    )
+
+    middleware.wrap_model_call(request, lambda _request: _ok_response())
+    loaded = session_store.load_session(session_id="session-1", workdir=tmp_path)
+
+    assert loaded.summary.evidence_count == 1
+    assert loaded.evidence[0].kind == "runtime_event"
+    metadata = loaded.evidence[0].metadata
+    assert metadata is not None
+    assert metadata["event_kind"] == "microcompact"
+    assert metadata["cleared_tool_results"] == 1
+    assert metadata["tools_cleared"] == 1
+    assert metadata["tools_kept"] == 1
+    assert metadata["tokens_saved_estimate"] > 0
+    assert metadata["keep_recent"] == 1
diff --git a/coding-deepgent/tests/config/test_config.py b/coding-deepgent/tests/config/test_config.py
new file mode 100644
index 000000000..abf450389
--- /dev/null
+++ b/coding-deepgent/tests/config/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/config/test_context_payloads.py b/coding-deepgent/tests/config/test_context_payloads.py
new file mode 100644
index 000000000..1aabc622d
--- /dev/null
+++ b/coding-deepgent/tests/config/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/config/test_logging.py b/coding-deepgent/tests/config/test_logging.py
new file mode 100644
index 000000000..603f547ca
--- /dev/null
+++ b/coding-deepgent/tests/config/test_logging.py
@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from structlog.testing import capture_logs
+
+from coding_deepgent.logging_config import (
+    configure_logging,
+    logger_for,
+    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")
+
+
+def test_logger_for_binds_agent_scope_fields() -> None:
+    configure_logging("DEBUG")
+
+    with capture_logs() as logs:
+        logger_for(
+            "runtime_pressure",
+            agent_name="agent-1",
+            session_id="session-1",
+            entrypoint="test",
+        ).debug("observed")
+
+    assert logs[0]["component"] == "runtime_pressure"
+    assert logs[0]["agent_name"] == "agent-1"
+    assert logs[0]["session_id"] == "session-1"
+    assert logs[0]["entrypoint"] == "test"
diff --git a/coding-deepgent/tests/config/test_prompting.py b/coding-deepgent/tests/config/test_prompting.py
new file mode 100644
index 000000000..f7debfcd1
--- /dev/null
+++ b/coding-deepgent/tests/config/test_prompting.py
@@ -0,0 +1,89 @@
+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_prompt_context_includes_project_rules_before_memory(tmp_path: Path) -> None:
+    rules_dir = tmp_path / ".coding-deepgent"
+    rules_dir.mkdir()
+    (rules_dir / "RULES.md").write_text("Always explain major tradeoffs first.", encoding="utf-8")
+
+    context = build_prompt_context(
+        workdir=tmp_path,
+        agent_name="coding-deepgent",
+        session_id="session-1",
+        entrypoint="coding-deepgent",
+        memories=(),
+    )
+
+    assert "Project-level rules:" in context.system_prompt
+    assert "Always explain major tradeoffs first." in context.system_prompt
+
+
+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"
+
+
+def test_build_system_prompt_places_rules_before_append_prompt(tmp_path: Path) -> None:
+    rules_dir = tmp_path / ".coding-deepgent"
+    rules_dir.mkdir()
+    (rules_dir / "RULES.md").write_text("Do not skip explicit validation.", encoding="utf-8")
+    settings = Settings(
+        workdir=tmp_path,
+        custom_system_prompt="Custom base",
+        append_system_prompt="Appendix",
+        agent_name="coding-deepgent",
+        entrypoint="coding-deepgent",
+    )
+
+    prompt = build_system_prompt(settings)
+
+    assert "Custom base" in prompt
+    assert "Project-level rules:" in prompt
+    assert "Do not skip explicit validation." in prompt
+    assert "Appendix" in prompt
+    assert prompt.index("Project-level rules:") < prompt.index("Appendix")
diff --git a/coding-deepgent/tests/config/test_rules.py b/coding-deepgent/tests/config/test_rules.py
new file mode 100644
index 000000000..61558a3d6
--- /dev/null
+++ b/coding-deepgent/tests/config/test_rules.py
@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from coding_deepgent.sessions import (
+    JsonlSessionStore,
+    build_recovery_brief,
+    build_resume_context_message,
+    render_recovery_brief,
+)
+
+
+def test_recovery_brief_shows_project_rules_signal(tmp_path: Path) -> None:
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+    rules_dir = workdir / ".coding-deepgent"
+    rules_dir.mkdir()
+    (rules_dir / "RULES.md").write_text("Always explain major tradeoffs first.", encoding="utf-8")
+
+    store = JsonlSessionStore(tmp_path / "sessions")
+    context = store.create_session(workdir=workdir, entrypoint="cli")
+    store.append_message(context, role="user", content="resume")
+    store.append_state_snapshot(context, state={"todos": [], "rounds_since_update": 0})
+
+    loaded = store.load_session(session_id=context.session_id, workdir=workdir)
+    rendered = render_recovery_brief(build_recovery_brief(loaded))
+
+    assert "Project rules:" in rendered
+    assert ".coding-deepgent/RULES.md" in rendered
+
+
+def test_resume_context_message_does_not_repeat_project_rules_section(tmp_path: Path) -> None:
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+    rules_dir = workdir / ".coding-deepgent"
+    rules_dir.mkdir()
+    (rules_dir / "RULES.md").write_text("Always explain major tradeoffs first.", encoding="utf-8")
+
+    store = JsonlSessionStore(tmp_path / "sessions")
+    context = store.create_session(workdir=workdir, entrypoint="cli")
+    store.append_message(context, role="user", content="resume")
+    store.append_state_snapshot(context, state={"todos": [], "rounds_since_update": 0})
+
+    loaded = store.load_session(session_id=context.session_id, workdir=workdir)
+    message = build_resume_context_message(loaded)
+
+    assert "Project rules:" not in str(message["content"])
diff --git a/coding-deepgent/tests/conftest.py b/coding-deepgent/tests/conftest.py
new file mode 100644
index 000000000..f2d3e062b
--- /dev/null
+++ b/coding-deepgent/tests/conftest.py
@@ -0,0 +1,88 @@
+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",
+)
+INFRA_ENV_DEFAULTS = {
+    "POSTGRES_URL": "",
+    "CODING_DEEPGENT_POSTGRES_URL": "",
+    "REDIS_URL": "",
+    "CODING_DEEPGENT_REDIS_URL": "",
+    "OFFLOAD_BACKEND": "none",
+    "CODING_DEEPGENT_OFFLOAD_BACKEND": "none",
+    "S3_BUCKET": "",
+    "CODING_DEEPGENT_S3_BUCKET": "",
+    "S3_ENDPOINT_URL": "",
+    "CODING_DEEPGENT_S3_ENDPOINT_URL": "",
+    "S3_REGION": "",
+    "CODING_DEEPGENT_S3_REGION": "",
+    "S3_ACCESS_KEY_ID": "",
+    "CODING_DEEPGENT_S3_ACCESS_KEY_ID": "",
+    "S3_SECRET_ACCESS_KEY": "",
+    "CODING_DEEPGENT_S3_SECRET_ACCESS_KEY": "",
+}
+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)
+    for env_name, value in INFRA_ENV_DEFAULTS.items():
+        os.environ[env_name] = value
+
+    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/extensions/test_hooks.py b/coding-deepgent/tests/extensions/test_hooks.py
new file mode 100644
index 000000000..ba54c8b05
--- /dev/null
+++ b/coding-deepgent/tests/extensions/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/extensions/test_mcp.py b/coding-deepgent/tests/extensions/test_mcp.py
new file mode 100644
index 000000000..66cde780d
--- /dev/null
+++ b/coding-deepgent/tests/extensions/test_mcp.py
@@ -0,0 +1,304 @@
+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 capability.family == "mcp"
+    assert capability.mutation == "read"
+    assert capability.execution == "plain_tool"
+    assert capability.exposure == "deferred"
+    assert capability.rendering_result == "tool_message"
+    assert capability.persist_large_output is False
+    assert capability.microcompact_eligible 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 "mcp__docs__lookup" not in tool_names
+    assert "ToolSearch" in tool_names
+    assert "invoke_deferred_tool" in tool_names
+    assert "mcp__docs__lookup" in container.capability_registry().names()
+    assert "mcp__docs__lookup" in container.capability_registry().names_for_projection(
+        "deferred"
+    )
+    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" not in tool_names
+    assert "mcp__docs__lookup" in container.capability_registry().names_for_projection(
+        "deferred"
+    )
diff --git a/coding-deepgent/tests/extensions/test_plugins.py b/coding-deepgent/tests/extensions/test_plugins.py
new file mode 100644
index 000000000..919fe47fc
--- /dev/null
+++ b/coding-deepgent/tests/extensions/test_plugins.py
@@ -0,0 +1,318 @@
+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 write_plugin_agents(root: Path, plugin_name: str, payload: dict[str, object]) -> Path:
+    plugin_dir = root / plugin_name
+    plugin_dir.mkdir(parents=True, exist_ok=True)
+    path = plugin_dir / "subagents.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"],
+        "agents": [],
+    }
+
+
+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",)
+    assert manifest.agents == ()
+
+    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")
+    assert registry.declared_agents() == ()
+
+    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_app_container_validates_plugin_provided_subagent_definitions(
+    tmp_path: Path,
+) -> None:
+    write_skill(tmp_path / "skills")
+    write_plugin(
+        tmp_path / "plugins",
+        "demo",
+        {
+            **valid_manifest("demo"),
+            "agents": ["demo:docs_review"],
+        },
+    )
+    write_plugin_agents(
+        tmp_path / "plugins",
+        "demo",
+        {
+            "agents": [
+                {
+                    "agent_type": "demo:docs_review",
+                    "description": "Review docs",
+                    "when_to_use": "Use for plugin-provided docs review.",
+                    "instructions": "Review docs from the plugin catalog.",
+                    "tool_allowlist": ["read_file", "glob"],
+                    "disallowed_tools": ["write_file"],
+                    "max_turns": 6,
+                }
+            ]
+        },
+    )
+
+    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"]
+    assert validated.declared_agents() == ("demo:docs_review",)
+
+
+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/extensions/test_skills.py b/coding-deepgent/tests/extensions/test_skills.py
new file mode 100644
index 000000000..98b4e77ac
--- /dev/null
+++ b/coding-deepgent/tests/extensions/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/filesystem/test_tools.py b/coding-deepgent/tests/filesystem/test_tools.py
new file mode 100644
index 000000000..1baf89d43
--- /dev/null
+++ b/coding-deepgent/tests/filesystem/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/coding-deepgent/tests/frontend/test_frontend_bridge.py b/coding-deepgent/tests/frontend/test_frontend_bridge.py
new file mode 100644
index 000000000..74b69ffe0
--- /dev/null
+++ b/coding-deepgent/tests/frontend/test_frontend_bridge.py
@@ -0,0 +1,547 @@
+from __future__ import annotations
+
+import json
+from io import StringIO
+from types import SimpleNamespace
+from pathlib import Path
+from typing import Any
+
+from langchain_core.messages import AIMessage, AIMessageChunk, ToolMessage
+
+from coding_deepgent.frontend.bridge import (
+    PromptRunResult,
+    _run_streaming_prompt,
+    run_jsonl_bridge,
+)
+from coding_deepgent.frontend.producer import PendingPermissionRequest
+from coding_deepgent.frontend.protocol import FrontendEvent
+from coding_deepgent.frontend.protocol import AssistantDeltaEvent, ToolFinishedEvent
+from coding_deepgent.runtime import RuntimeEvent
+from coding_deepgent.settings import Settings
+from coding_deepgent.frontend.protocol import (
+    BackgroundSubagentSnapshotEvent,
+    ContextSnapshotEvent,
+    SubagentSnapshotEvent,
+)
+
+
+def _settings(tmp_path: Path) -> Settings:
+    return Settings(
+        workdir=tmp_path / "workdir",
+        session_dir=tmp_path / "sessions",
+        model_name="gpt-test",
+    )
+
+
+def _events(output: StringIO) -> list[dict[str, Any]]:
+    return [json.loads(line) for line in output.getvalue().splitlines()]
+
+
+def test_jsonl_bridge_runs_prompt_and_emits_ordered_events(tmp_path: Path) -> None:
+    settings = _settings(tmp_path)
+    settings.workdir.mkdir()
+    output = StringIO()
+
+    def runner(
+        prompt: str,
+        history: list[dict[str, Any]],
+        session_state: dict[str, Any],
+        session_id: str,
+        assistant_message_id: str,
+        emit,
+    ) -> PromptRunResult:
+        del assistant_message_id, emit
+        history.append({"role": "user", "content": prompt})
+        history.append({"role": "assistant", "content": "done"})
+        session_state["todos"] = [
+            {
+                "content": "Implement UI",
+                "status": "in_progress",
+                "activeForm": "Implementing UI",
+            }
+        ]
+        return PromptRunResult(
+            text=f"done for {session_id}",
+            runtime_events=(
+                RuntimeEvent(
+                    kind="query_progress",
+                    message="Query progressed.",
+                    session_id=session_id,
+                    metadata={"source": "test", "unsafe": {"nested": "ignored"}},
+                ),
+            ),
+            recovery_brief="Recovery brief text.",
+            context_snapshot=ContextSnapshotEvent(
+                projection_mode="raw",
+                history_messages=2,
+                model_messages=2,
+                visible_messages=2,
+                hidden_messages=0,
+                compact_count=0,
+                collapse_count=0,
+                session_memory_status="missing",
+            ),
+            subagent_snapshot=SubagentSnapshotEvent(total=0, items=[]),
+            background_subagent_snapshot=BackgroundSubagentSnapshotEvent(total=0, items=[]),
+        )
+
+    run_jsonl_bridge(
+        ['{"type":"submit_prompt","text":"hello"}\n', '{"type":"exit"}\n'],
+        output,
+        settings=settings,
+        prompt_runner=runner,
+    )
+
+    events = _events(output)
+    assert [event["type"] for event in events] == [
+        "session_started",
+        "user_message",
+        "runtime_event",
+        "todo_snapshot",
+        "task_snapshot",
+        "context_snapshot",
+        "subagent_snapshot",
+        "background_subagent_snapshot",
+        "assistant_message",
+        "recovery_brief",
+        "run_finished",
+        "run_finished",
+    ]
+    assert events[2]["metadata"] == {"source": "test"}
+    assert events[3]["items"] == [
+        {
+            "content": "Implement UI",
+            "status": "in_progress",
+            "activeForm": "Implementing UI",
+        }
+    ]
+    assert events[4]["items"] == []
+    assert events[5]["type"] == "context_snapshot"
+    assert events[6]["type"] == "subagent_snapshot"
+    assert events[7]["type"] == "background_subagent_snapshot"
+    assert events[8]["text"].startswith("done for ")
+
+
+def test_jsonl_bridge_reports_protocol_errors_and_continues(tmp_path: Path) -> None:
+    settings = _settings(tmp_path)
+    settings.workdir.mkdir()
+    output = StringIO()
+
+    def runner(
+        prompt: str,
+        history: list[dict[str, Any]],
+        session_state: dict[str, Any],
+        session_id: str,
+        assistant_message_id: str,
+        emit,
+    ) -> PromptRunResult:
+        del history, session_state, session_id, assistant_message_id, emit
+        return PromptRunResult(text=f"ok {prompt}")
+
+    run_jsonl_bridge(
+        ["not-json\n", '{"type":"submit_prompt","text":"hello"}\n'],
+        output,
+        settings=settings,
+        prompt_runner=runner,
+    )
+
+    events = _events(output)
+    assert events[0]["type"] == "protocol_error"
+    assert any(event["type"] == "assistant_message" for event in events)
+
+
+def test_jsonl_bridge_streams_runner_events_before_final_message(tmp_path: Path) -> None:
+    settings = _settings(tmp_path)
+    settings.workdir.mkdir()
+    output = StringIO()
+
+    def runner(
+        prompt: str,
+        history: list[dict[str, Any]],
+        session_state: dict[str, Any],
+        session_id: str,
+        assistant_message_id: str,
+        emit,
+    ) -> PromptRunResult:
+        del prompt, session_id
+        history.append({"role": "user", "content": "stream"})
+        emit(AssistantDeltaEvent(message_id=assistant_message_id, text="hel"))
+        emit(AssistantDeltaEvent(message_id=assistant_message_id, text="lo"))
+        emit(
+            ToolFinishedEvent(
+                tool_call_id="call-1",
+                name="fake_tool",
+                preview="finished during stream",
+            )
+        )
+        session_state["todos"] = []
+        return PromptRunResult(
+            text="hello",
+            context_snapshot=ContextSnapshotEvent(
+                projection_mode="raw",
+                history_messages=2,
+                model_messages=2,
+                visible_messages=2,
+                hidden_messages=0,
+                compact_count=0,
+                collapse_count=0,
+                session_memory_status="missing",
+            ),
+            subagent_snapshot=SubagentSnapshotEvent(total=0, items=[]),
+            background_subagent_snapshot=BackgroundSubagentSnapshotEvent(total=0, items=[]),
+        )
+
+    run_jsonl_bridge(
+        ['{"type":"submit_prompt","text":"stream"}\n'],
+        output,
+        settings=settings,
+        prompt_runner=runner,
+    )
+
+    events = _events(output)
+    assert [event["type"] for event in events] == [
+        "session_started",
+        "user_message",
+        "assistant_delta",
+        "assistant_delta",
+        "tool_finished",
+        "todo_snapshot",
+        "task_snapshot",
+        "context_snapshot",
+        "subagent_snapshot",
+        "background_subagent_snapshot",
+        "assistant_message",
+        "run_finished",
+    ]
+    assert events[2]["text"] == "hel"
+    assert events[3]["text"] == "lo"
+
+
+def test_jsonl_bridge_reports_failure_after_partial_stream(tmp_path: Path) -> None:
+    settings = _settings(tmp_path)
+    settings.workdir.mkdir()
+    output = StringIO()
+
+    def runner(
+        prompt: str,
+        history: list[dict[str, Any]],
+        session_state: dict[str, Any],
+        session_id: str,
+        assistant_message_id: str,
+        emit,
+    ) -> PromptRunResult:
+        del prompt, history, session_state, session_id
+        emit(AssistantDeltaEvent(message_id=assistant_message_id, text="partial"))
+        raise RuntimeError("boom")
+
+    run_jsonl_bridge(
+        ['{"type":"submit_prompt","text":"fail"}\n'],
+        output,
+        settings=settings,
+        prompt_runner=runner,
+    )
+
+    events = _events(output)
+    assert [event["type"] for event in events] == [
+        "session_started",
+        "user_message",
+        "assistant_delta",
+        "run_failed",
+    ]
+    assert events[-1]["error"] == "boom"
+
+
+def test_fake_bridge_can_surface_permission_request(tmp_path: Path) -> None:
+    settings = _settings(tmp_path)
+    settings.workdir.mkdir()
+    output = StringIO()
+
+    from coding_deepgent.frontend.bridge import build_fake_prompt_runner
+
+    run_jsonl_bridge(
+        ['{"type":"submit_prompt","text":"permission please"}\n'],
+        output,
+        settings=settings,
+        prompt_runner=build_fake_prompt_runner(),
+    )
+
+    events = _events(output)
+    permission = next(event for event in events if event["type"] == "permission_requested")
+    assert permission["tool"] == "fake_write"
+    assert permission["options"] == ["approve", "reject"]
+
+
+def test_fake_bridge_emits_runtime_visibility_snapshots(tmp_path: Path) -> None:
+    settings = _settings(tmp_path)
+    settings.workdir.mkdir()
+    output = StringIO()
+
+    from coding_deepgent.frontend.bridge import build_fake_prompt_runner
+
+    run_jsonl_bridge(
+        ['{"type":"submit_prompt","text":"inspect runtime"}\n'],
+        output,
+        settings=settings,
+        prompt_runner=build_fake_prompt_runner(),
+    )
+
+    events = _events(output)
+    context = next(event for event in events if event["type"] == "context_snapshot")
+    subagents = next(event for event in events if event["type"] == "subagent_snapshot")
+    background = next(event for event in events if event["type"] == "background_subagent_snapshot")
+    assert context["projection_mode"] == "raw"
+    assert context["session_memory_status"] == "missing"
+    assert subagents == {"type": "subagent_snapshot", "total": 0, "items": []}
+    assert background == {"type": "background_subagent_snapshot", "total": 0, "items": []}
+
+
+def test_fake_bridge_handles_refresh_control_input(tmp_path: Path) -> None:
+    settings = _settings(tmp_path)
+    settings.workdir.mkdir()
+    output = StringIO()
+
+    from coding_deepgent.frontend.bridge import build_fake_bridge_runners
+
+    runner, resume_runner, control_runner = build_fake_bridge_runners()
+    run_jsonl_bridge(
+        ['{"type":"refresh_snapshots"}\n'],
+        output,
+        settings=settings,
+        prompt_runner=runner,
+        permission_resume_runner=resume_runner,
+        control_runner=control_runner,
+    )
+
+    events = _events(output)
+    assert [event["type"] for event in events] == [
+        "session_started",
+        "runtime_event",
+        "todo_snapshot",
+        "task_snapshot",
+        "context_snapshot",
+        "subagent_snapshot",
+        "background_subagent_snapshot",
+    ]
+
+
+def test_jsonl_bridge_resumes_after_permission_decision(tmp_path: Path) -> None:
+    settings = _settings(tmp_path)
+    settings.workdir.mkdir()
+    output = StringIO()
+
+    def runner(
+        prompt: str,
+        history: list[dict[str, Any]],
+        session_state: dict[str, Any],
+        session_id: str,
+        assistant_message_id: str,
+        emit,
+    ) -> PromptRunResult:
+        del prompt, history, session_state, session_id, assistant_message_id, emit
+        return PromptRunResult(
+            text="",
+            pending_permissions=(
+                PendingPermissionRequest(
+                    request_id="perm-1",
+                    tool="write_file",
+                    description="Approval required before running `write_file`",
+                ),
+            ),
+        )
+
+    def resume_runner(
+        decisions: dict[str, Any],
+        history: list[dict[str, Any]],
+        session_state: dict[str, Any],
+        session_id: str,
+        assistant_message_id: str,
+        emit,
+    ) -> PromptRunResult:
+        del session_id
+        assert decisions == {"perm-1": {"decision": "approve", "message": None}}
+        emit(AssistantDeltaEvent(message_id=assistant_message_id, text="done"))
+        history.append({"role": "assistant", "content": "done"})
+        session_state["todos"] = []
+        return PromptRunResult(text="done")
+
+    run_jsonl_bridge(
+        [
+            '{"type":"submit_prompt","text":"ship it"}\n',
+            '{"type":"permission_decision","request_id":"perm-1","decision":"approve"}\n',
+        ],
+        output,
+        settings=settings,
+        prompt_runner=runner,
+        permission_resume_runner=resume_runner,
+    )
+
+    events = _events(output)
+    assert [event["type"] for event in events] == [
+        "session_started",
+        "user_message",
+        "permission_requested",
+        "permission_resolved",
+        "assistant_delta",
+        "todo_snapshot",
+        "task_snapshot",
+        "assistant_message",
+        "run_finished",
+    ]
+    assert events[2]["request_id"] == "perm-1"
+    assert events[5]["items"] == []
+    assert events[6]["items"] == []
+
+
+def test_streaming_prompt_returns_pending_permission_requests(tmp_path: Path) -> None:
+    settings = _settings(tmp_path)
+    settings.workdir.mkdir()
+    emitted: list[FrontendEvent] = []
+    session_state: dict[str, Any] = {}
+    history: list[dict[str, Any]] = []
+
+    class FakeInterrupt:
+        def __init__(self, *, id: str, value: dict[str, Any]) -> None:
+            self.id = id
+            self.value = value
+
+    class FakeAgent:
+        def stream(self, payload, **kwargs):
+            del payload, kwargs
+            yield {
+                "type": "updates",
+                "data": {
+                    "__interrupt__": (
+                        FakeInterrupt(
+                            id="perm-1",
+                            value={
+                                "kind": "permission_request",
+                                "tool": "write_file",
+                                "description": "Approval required",
+                                "options": ["approve", "reject"],
+                            },
+                        ),
+                    )
+                },
+            }
+
+    result = _run_streaming_prompt(
+        settings=settings,
+        prompt="hello",
+        history=history,
+        session_state=session_state,
+        session_id="session-stream",
+        assistant_message_id="assistant-1",
+        emit=emitted.append,
+        container=SimpleNamespace(),
+        event_sink=SimpleNamespace(snapshot=lambda: ()),
+        emitted_events=lambda: 0,
+        set_emitted_events=lambda value: None,
+        build_agent=lambda container=None: FakeAgent(),
+        build_runtime_invocation=lambda **kwargs: SimpleNamespace(
+            context=SimpleNamespace(session_id="session-stream"),
+            config={"configurable": {"thread_id": "session-stream"}},
+        ),
+    )
+
+    assert result.text == ""
+    assert result.pending_permissions == (
+        PendingPermissionRequest(
+            request_id="perm-1",
+            tool="write_file",
+            description="Approval required",
+        ),
+    )
+    assert emitted == []
+
+
+def test_streaming_prompt_maps_langgraph_parts_to_frontend_events(tmp_path: Path) -> None:
+    settings = _settings(tmp_path)
+    settings.workdir.mkdir()
+    emitted: list[FrontendEvent] = []
+    session_state: dict[str, Any] = {}
+    history: list[dict[str, Any]] = []
+
+    class FakeAgent:
+        def stream(self, payload, **kwargs):
+            assert payload["messages"][-1]["content"] == "hello"
+            assert kwargs["stream_mode"] == ["messages", "updates", "custom", "values"]
+            yield {
+                "type": "messages",
+                "data": (AIMessageChunk(content="hel"), {"langgraph_node": "model"}),
+            }
+            yield {
+                "type": "updates",
+                "data": {
+                    "model": {
+                        "messages": [
+                            AIMessage(
+                                content="",
+                                tool_calls=[
+                                    {
+                                        "name": "read_file",
+                                        "args": {"path": "README.md"},
+                                        "id": "call-1",
+                                    }
+                                ],
+                            )
+                        ]
+                    }
+                },
+            }
+            yield {
+                "type": "updates",
+                "data": {
+                    "tools": {
+                        "messages": [
+                            ToolMessage(content="ok", tool_call_id="call-1")
+                        ]
+                    }
+                },
+            }
+            yield {
+                "type": "messages",
+                "data": (AIMessageChunk(content="lo"), {"langgraph_node": "model"}),
+            }
+            yield {
+                "type": "values",
+                "data": {
+                    "messages": [AIMessage(content="hello")],
+                    "todos": [
+                        {
+                            "content": "Stream response",
+                            "status": "completed",
+                            "activeForm": "Streaming response",
+                        }
+                    ],
+                    "rounds_since_update": 3,
+                },
+            }
+
+    result = _run_streaming_prompt(
+        settings=settings,
+        prompt="hello",
+        history=history,
+        session_state=session_state,
+        session_id="session-stream",
+        assistant_message_id="assistant-1",
+        emit=emitted.append,
+        container=SimpleNamespace(),
+        event_sink=SimpleNamespace(snapshot=lambda: ()),
+        emitted_events=lambda: 0,
+        set_emitted_events=lambda value: None,
+        build_agent=lambda container=None: FakeAgent(),
+        build_runtime_invocation=lambda **kwargs: SimpleNamespace(
+            context=SimpleNamespace(session_id="session-stream"),
+            config={"configurable": {"thread_id": "session-stream"}},
+        ),
+    )
+
+    assert result.text == "hello"
+    assert [event.type for event in emitted] == [
+        "assistant_delta",
+        "tool_started",
+        "tool_finished",
+        "assistant_delta",
+    ]
+    assert session_state["todos"][0]["content"] == "Stream response"
+    assert history[-1] == {"role": "assistant", "content": "hello"}
diff --git a/coding-deepgent/tests/frontend/test_frontend_client.py b/coding-deepgent/tests/frontend/test_frontend_client.py
new file mode 100644
index 000000000..98e971429
--- /dev/null
+++ b/coding-deepgent/tests/frontend/test_frontend_client.py
@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from coding_deepgent.frontend.client import FrontendClient
+from coding_deepgent.settings import Settings
+
+
+def _settings(tmp_path: Path) -> Settings:
+    return Settings(
+        workdir=tmp_path / "workdir",
+        session_dir=tmp_path / "sessions",
+        model_name="gpt-test",
+    )
+
+
+def test_frontend_client_stream_prompt_yields_fake_events(tmp_path: Path) -> None:
+    settings = _settings(tmp_path)
+    settings.workdir.mkdir()
+    client = FrontendClient(settings=settings, fake=True)
+
+    events = list(client.stream_prompt("hello"))
+
+    assert [event.type for event in events] == [
+        "session_started",
+        "user_message",
+        "tool_started",
+        "assistant_delta",
+        "assistant_delta",
+        "tool_finished",
+        "runtime_event",
+        "todo_snapshot",
+        "task_snapshot",
+        "context_snapshot",
+        "subagent_snapshot",
+        "background_subagent_snapshot",
+        "assistant_message",
+        "recovery_brief",
+        "run_finished",
+    ]
+
+
+def test_frontend_client_chat_returns_final_assistant_text(tmp_path: Path) -> None:
+    settings = _settings(tmp_path)
+    settings.workdir.mkdir()
+    client = FrontendClient(settings=settings, fake=True)
+
+    result = client.chat("hello")
+
+    assert result == "Fake response: hello"
diff --git a/coding-deepgent/tests/frontend/test_frontend_event_mapping.py b/coding-deepgent/tests/frontend/test_frontend_event_mapping.py
new file mode 100644
index 000000000..cfd90977a
--- /dev/null
+++ b/coding-deepgent/tests/frontend/test_frontend_event_mapping.py
@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+from langgraph.store.memory import InMemoryStore
+
+from coding_deepgent.frontend.event_mapping import (
+    context_snapshot_from_loaded,
+    runtime_events_to_frontend,
+    subagent_snapshot_from_loaded,
+    task_snapshot_from_store,
+    todo_snapshot_from_state,
+)
+from coding_deepgent.runtime import RuntimeEvent
+from coding_deepgent.sessions import JsonlSessionStore
+from coding_deepgent.sessions.records import message_id_for_index
+from coding_deepgent.sessions.session_memory import write_session_memory_artifact
+from coding_deepgent.tasks import create_task
+
+
+def test_todo_snapshot_from_state_filters_invalid_items() -> None:
+    snapshot = todo_snapshot_from_state(
+        {
+            "todos": [
+                {
+                    "content": "Ship CLI",
+                    "status": "in_progress",
+                    "activeForm": "Shipping CLI",
+                },
+                {"content": "Bad status", "status": "unknown"},
+                "not an item",
+            ]
+        }
+    )
+
+    assert [item.model_dump() for item in snapshot.items] == [
+        {
+            "content": "Ship CLI",
+            "status": "in_progress",
+            "activeForm": "Shipping CLI",
+        }
+    ]
+
+
+def test_runtime_tool_guard_events_map_to_tool_events() -> None:
+    mapped = runtime_events_to_frontend(
+        [
+            RuntimeEvent(
+                kind="allowed",
+                message="Tool guard allowed for read_file",
+                session_id="session-1",
+                metadata={
+                    "source": "tool_guard",
+                    "phase": "allowed",
+                    "tool": "read_file",
+                    "tool_call_id": "call-1",
+                },
+            ),
+            RuntimeEvent(
+                kind="completed",
+                message="Tool guard completed for read_file",
+                session_id="session-1",
+                metadata={
+                    "source": "tool_guard",
+                    "phase": "completed",
+                    "tool": "read_file",
+                    "tool_call_id": "call-1",
+                },
+            ),
+        ]
+    )
+
+    assert [event.type for event in mapped] == ["tool_started", "tool_finished"]
+
+
+def test_task_snapshot_from_store_filters_to_active_task_records() -> None:
+    store = InMemoryStore()
+    create_task(store, title="Ship CLI")
+    create_task(store, title="Review tests", owner="kun")
+
+    snapshot = task_snapshot_from_store(store)
+
+    assert sorted(
+        (item.content, item.status, item.owner) for item in snapshot.items
+    ) == [
+        ("Review tests", "pending", "kun"),
+        ("Ship CLI", "pending", None),
+    ]
+
+
+def test_context_snapshot_from_loaded_exposes_projection_counts(tmp_path) -> None:
+    store = JsonlSessionStore(tmp_path / "sessions")
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+    context = store.create_session(workdir=workdir, session_id="session-1")
+    store.append_message(context, role="user", content="first")
+    store.append_message(context, role="assistant", content="second")
+    store.append_collapse(
+        context,
+        trigger="threshold_tokens",
+        summary="Earlier work collapsed.",
+        start_message_id=message_id_for_index(0),
+        end_message_id=message_id_for_index(0),
+        covered_message_ids=[message_id_for_index(0)],
+    )
+    state = {"todos": [], "rounds_since_update": 0}
+    write_session_memory_artifact(
+        state,
+        content="Current focus.",
+        message_count=2,
+        token_count=2,
+        tool_call_count=0,
+    )
+    store.append_state_snapshot(context, state=state)
+    loaded = store.load_session(session_id="session-1", workdir=workdir)
+
+    snapshot = context_snapshot_from_loaded(loaded)
+
+    assert snapshot.projection_mode == "collapse"
+    assert snapshot.history_messages == 2
+    assert snapshot.model_messages == 3
+    assert snapshot.visible_messages == 1
+    assert snapshot.hidden_messages == 1
+    assert snapshot.collapse_count == 1
+    assert snapshot.session_memory_status == "current"
+    assert snapshot.latest_event == "collapse"
+
+
+def test_subagent_snapshot_from_loaded_limits_recent_sidechain_messages(tmp_path) -> None:
+    store = JsonlSessionStore(tmp_path / "sessions")
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+    context = store.create_session(workdir=workdir, session_id="session-1")
+    store.append_message(context, role="user", content="first")
+    for index in range(3):
+        store.append_sidechain_message(
+            context,
+            agent_type="general",
+            role="assistant",
+            content=f"sidechain {index}",
+            subagent_thread_id=f"child-{index}",
+        )
+    loaded = store.load_session(session_id="session-1", workdir=workdir)
+
+    snapshot = subagent_snapshot_from_loaded(loaded, limit=2)
+
+    assert snapshot.total == 3
+    assert [item.content for item in snapshot.items] == ["sidechain 1", "sidechain 2"]
diff --git a/coding-deepgent/tests/frontend/test_frontend_gateway.py b/coding-deepgent/tests/frontend/test_frontend_gateway.py
new file mode 100644
index 000000000..0cfa0d6bb
--- /dev/null
+++ b/coding-deepgent/tests/frontend/test_frontend_gateway.py
@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from pathlib import Path
+import threading
+import time
+
+from fastapi.testclient import TestClient
+
+from coding_deepgent.frontend.gateway import create_app
+from coding_deepgent.frontend.producer import PromptRunResult
+from coding_deepgent.settings import Settings
+
+
+def _settings(tmp_path: Path) -> Settings:
+    return Settings(
+        workdir=tmp_path / "workdir",
+        session_dir=tmp_path / "sessions",
+        model_name="gpt-test",
+    )
+
+
+def test_gateway_health_endpoint(tmp_path: Path) -> None:
+    settings = _settings(tmp_path)
+    settings.workdir.mkdir()
+
+    with TestClient(create_app(fake=True, settings=settings)) as client:
+        response = client.get("/health")
+
+    assert response.status_code == 200
+    assert response.json() == {
+        "status": "healthy",
+        "service": "coding-deepgent-frontend-gateway",
+    }
+
+
+def test_gateway_serves_minimal_web_ui(tmp_path: Path) -> None:
+    settings = _settings(tmp_path)
+    settings.workdir.mkdir()
+
+    with TestClient(create_app(fake=True, settings=settings)) as client:
+        response = client.get("/ui")
+
+    assert response.status_code == 200
+    assert "<title>coding-deepgent web ui</title>" in response.text
+    assert 'id="prompt"' in response.text
+    assert "/api/runs" in response.text
+
+
+def test_gateway_run_stream_returns_sse_events(tmp_path: Path) -> None:
+    settings = _settings(tmp_path)
+    settings.workdir.mkdir()
+
+    with TestClient(create_app(fake=True, settings=settings)) as client:
+        with client.stream("POST", "/api/runs/stream", json={"prompt": "hello"}) as response:
+            content_location = response.headers["Content-Location"]
+            lines = [line for line in response.iter_lines() if line]
+
+    assert response.status_code == 200
+    assert content_location.startswith("/api/runs/")
+    assert any("event: metadata" in line for line in lines)
+    assert any("event: assistant_delta" in line for line in lines)
+    assert any("event: run_finished" in line for line in lines)
+    assert any("event: end" in line for line in lines)
+
+
+def test_gateway_rejects_concurrent_run_on_same_thread(tmp_path: Path) -> None:
+    settings = _settings(tmp_path)
+    settings.workdir.mkdir()
+    release = threading.Event()
+
+    def slow_runner(
+        prompt,
+        history,
+        session_state,
+        session_id,
+        assistant_message_id,
+        emit,
+    ) -> PromptRunResult:
+        del history, session_state, session_id, assistant_message_id, emit
+        release.wait(timeout=2)
+        return PromptRunResult(text=f"done {prompt}")
+
+    with TestClient(create_app(settings=settings, prompt_runner=slow_runner)) as client:
+        response_one = client.post("/api/runs", json={"prompt": "first", "thread_id": "thread-1"})
+        time.sleep(0.05)
+        response_two = client.post("/api/runs", json={"prompt": "second", "thread_id": "thread-1"})
+        release.set()
+
+    assert response_one.status_code == 200
+    assert response_two.status_code == 409
diff --git a/coding-deepgent/tests/frontend/test_frontend_protocol.py b/coding-deepgent/tests/frontend/test_frontend_protocol.py
new file mode 100644
index 000000000..648777c6e
--- /dev/null
+++ b/coding-deepgent/tests/frontend/test_frontend_protocol.py
@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from coding_deepgent.frontend.protocol import (
+    AssistantMessageEvent,
+    ContextSnapshotEvent,
+    RunBackgroundSubagentControlInput,
+    SubmitPromptInput,
+    parse_frontend_event,
+    parse_frontend_input,
+    serialize_frontend_event,
+)
+
+
+def test_frontend_event_serializes_as_jsonl_payload() -> None:
+    payload = serialize_frontend_event(
+        AssistantMessageEvent(message_id="assistant-1", text="hello")
+    )
+
+    assert payload == (
+        '{"type":"assistant_message","message_id":"assistant-1","text":"hello"}'
+    )
+    parsed = parse_frontend_event(payload)
+    assert isinstance(parsed, AssistantMessageEvent)
+    assert parsed.text == "hello"
+
+
+def test_frontend_input_rejects_unknown_extra_fields() -> None:
+    with pytest.raises(ValidationError):
+        parse_frontend_input(
+            {"type": "submit_prompt", "text": "hello", "unexpected": True}
+        )
+
+
+def test_frontend_input_parses_submit_prompt() -> None:
+    parsed = parse_frontend_input('{"type":"submit_prompt","text":"ship it"}')
+
+    assert isinstance(parsed, SubmitPromptInput)
+    assert parsed.text == "ship it"
+
+
+def test_frontend_input_parses_background_subagent_control() -> None:
+    parsed = parse_frontend_input(
+        '{"type":"run_background_subagent","task":"inspect repo","agent_type":"general","max_turns":5}'
+    )
+
+    assert isinstance(parsed, RunBackgroundSubagentControlInput)
+    assert parsed.task == "inspect repo"
+    assert parsed.max_turns == 5
+
+
+def test_frontend_context_snapshot_event_validates_payload() -> None:
+    payload = serialize_frontend_event(
+        ContextSnapshotEvent(
+            projection_mode="collapse",
+            history_messages=6,
+            model_messages=3,
+            visible_messages=2,
+            hidden_messages=4,
+            compact_count=1,
+            collapse_count=1,
+            session_memory_status="stale",
+            latest_event="collapse",
+        )
+    )
+
+    parsed = parse_frontend_event(payload)
+
+    assert isinstance(parsed, ContextSnapshotEvent)
+    assert parsed.projection_mode == "collapse"
+    assert parsed.hidden_messages == 4
+    assert parsed.session_memory_status == "stale"
+
+
+def test_frontend_context_snapshot_rejects_negative_counts() -> None:
+    with pytest.raises(ValidationError):
+        parse_frontend_event(
+            {
+                "type": "context_snapshot",
+                "projection_mode": "raw",
+                "history_messages": -1,
+                "model_messages": 0,
+                "visible_messages": 0,
+                "hidden_messages": 0,
+                "compact_count": 0,
+                "collapse_count": 0,
+                "session_memory_status": "missing",
+            }
+        )
+
+
+def test_frontend_protocol_rejects_non_object_json() -> None:
+    with pytest.raises(ValueError, match="JSON object"):
+        parse_frontend_input("[]")
diff --git a/coding-deepgent/tests/frontend/test_frontend_runs.py b/coding-deepgent/tests/frontend/test_frontend_runs.py
new file mode 100644
index 000000000..9d5c566a6
--- /dev/null
+++ b/coding-deepgent/tests/frontend/test_frontend_runs.py
@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from coding_deepgent.frontend.runs import FrontendRunService
+from coding_deepgent.settings import Settings
+
+
+def _settings(tmp_path: Path) -> Settings:
+    return Settings(
+        workdir=tmp_path / "workdir",
+        session_dir=tmp_path / "sessions",
+        model_name="gpt-test",
+    )
+
+
+def test_run_service_publishes_metadata_and_frontend_events(tmp_path: Path) -> None:
+    settings = _settings(tmp_path)
+    settings.workdir.mkdir()
+    service = FrontendRunService(settings=settings, fake=True)
+
+    record = service.start_run(thread_id="thread-1", prompt="hello")
+    assert record.worker is not None
+    record.worker.join(timeout=5)
+
+    events = list(service.bridge.subscribe(record.run_id, heartbeat_interval=0.01))
+    event_names = [entry.event for entry in events[:-1]]
+    assert event_names[:3] == ["metadata", "session_started", "user_message"]
+    assert "assistant_delta" in event_names
+    assert "assistant_message" in event_names
+    assert "run_finished" in event_names
+
+    refreshed = service.run_manager.get(record.run_id)
+    assert refreshed is not None
+    assert refreshed.status == "completed"
diff --git a/coding-deepgent/tests/frontend/test_frontend_sse.py b/coding-deepgent/tests/frontend/test_frontend_sse.py
new file mode 100644
index 000000000..eda43d407
--- /dev/null
+++ b/coding-deepgent/tests/frontend/test_frontend_sse.py
@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from coding_deepgent.frontend.adapters.sse import format_sse, sse_consumer
+from coding_deepgent.frontend.stream_bridge import MemoryStreamBridge
+
+
+def test_format_sse_includes_event_data_and_id() -> None:
+    frame = format_sse("values", {"title": "hello"}, event_id="evt-1")
+
+    assert "event: values" in frame
+    assert 'data: {"title": "hello"}' in frame
+    assert "id: evt-1" in frame
+
+
+def test_sse_consumer_formats_bridge_entries() -> None:
+    bridge = MemoryStreamBridge()
+    bridge.publish("run-1", "metadata", {"run_id": "run-1"})
+    bridge.publish("run-1", "values", {"title": "hello"})
+    bridge.publish_end("run-1")
+
+    frames = list(sse_consumer(bridge, "run-1", heartbeat_interval=0.01))
+
+    assert frames[0].startswith("event: metadata")
+    assert frames[1].startswith("event: values")
+    assert frames[-1].startswith("event: end")
diff --git a/coding-deepgent/tests/frontend/test_stream_bridge.py b/coding-deepgent/tests/frontend/test_stream_bridge.py
new file mode 100644
index 000000000..db76ec223
--- /dev/null
+++ b/coding-deepgent/tests/frontend/test_stream_bridge.py
@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from coding_deepgent.frontend.stream_bridge import (
+    END_SENTINEL,
+    HEARTBEAT_SENTINEL,
+    MemoryStreamBridge,
+)
+
+
+def test_stream_bridge_replays_events_after_last_event_id() -> None:
+    bridge = MemoryStreamBridge()
+    bridge.publish("run-1", "metadata", {"run_id": "run-1"})
+    bridge.publish("run-1", "values", {"title": "one"})
+    bridge.publish_end("run-1")
+
+    replay = list(bridge.subscribe("run-1", last_event_id=""))
+    assert [entry.event for entry in replay[:-1]] == ["metadata", "values"]
+    assert replay[-1] is END_SENTINEL
+
+    first_event_id = replay[0].id
+    resumed = list(bridge.subscribe("run-1", last_event_id=first_event_id))
+    assert [entry.event for entry in resumed[:-1]] == ["values"]
+    assert resumed[-1] is END_SENTINEL
+
+
+def test_stream_bridge_heartbeat_when_idle() -> None:
+    bridge = MemoryStreamBridge()
+    stream = bridge.subscribe("run-2", heartbeat_interval=0.01)
+    assert next(stream) is HEARTBEAT_SENTINEL
+
diff --git a/coding-deepgent/tests/memory/test_memory.py b/coding-deepgent/tests/memory/test_memory.py
new file mode 100644
index 000000000..9ad028b5f
--- /dev/null
+++ b/coding-deepgent/tests/memory/test_memory.py
@@ -0,0 +1,213 @@
+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 (
+    DeleteMemoryInput,
+    ListMemoryInput,
+    MemoryRecord,
+    SaveMemoryInput,
+    delete_memory_record,
+    list_memory_entries,
+    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"] == ["type"]
+    assert "runtime" not in schema["properties"]
+    assert "type" in schema["properties"]
+    assert "rule" in schema["properties"]
+    assert "fact_or_decision" in schema["properties"]
+
+    with pytest.raises(ValidationError):
+        SaveMemoryInput.model_validate({"task": "do not alias"})
+    with pytest.raises(ValidationError):
+        SaveMemoryInput.model_validate({"type": "feedback", "extra": "nope"})
+    with pytest.raises(ValidationError):
+        SaveMemoryInput.model_validate(
+            {
+                "type": "feedback",
+                "rule": "Run lint before commit",
+            }
+        )
+    with pytest.raises(ValidationError):
+        ListMemoryInput.model_validate({"limit": 0})
+    with pytest.raises(ValidationError):
+        DeleteMemoryInput.model_validate({"type": "feedback", "key": " "})
+
+
+def test_memory_store_save_list_and_recall_are_deterministic() -> None:
+    store = InMemoryStore()
+    first = MemoryRecord(
+        type="feedback",
+        rule="Run lint before commit",
+        why="The repo requires clean validation before code submission",
+        how_to_apply="Before any commit-like completion step, run lint first",
+    )
+    second = MemoryRecord(
+        type="project",
+        fact_or_decision="Use LangChain store for long-term memory",
+        why="Cross-session continuity should not depend on transcript replay alone",
+        how_to_apply="Prefer store-backed memory for durable reusable knowledge",
+    )
+
+    first_key = save_memory_record(store, first)
+    second_key = save_memory_record(store, second)
+
+    assert first_key != second_key
+    assert [record.type for record in list_memory_records(store, "feedback")] == [
+        "feedback"
+    ]
+    assert [record.type for record in list_memory_records(store, "project")] == [
+        "project"
+    ]
+    assert [
+        record.type
+        for record in recall_memories(store, query="lint continuity", limit=2)
+    ] == ["feedback", "project"]
+    assert [record.type for record in recall_memories(store, limit=1)] == ["feedback"]
+    assert recall_memories(None) == []
+
+
+def test_memory_entries_expose_keys_and_delete_is_exact() -> None:
+    store = InMemoryStore()
+    record = MemoryRecord(
+        type="feedback",
+        rule="Run lint before commit",
+        why="The repo requires clean validation before code submission",
+        how_to_apply="Before any commit-like completion step, run lint first",
+    )
+    key = save_memory_record(store, record)
+
+    entries = list_memory_entries(store, "feedback")
+
+    assert [(entry.key, entry.record.type) for entry in entries] == [(key, "feedback")]
+    assert delete_memory_record(store, memory_type="feedback", key="missing") is False
+    assert delete_memory_record(store, memory_type="feedback", key=key) is True
+    assert list_memory_entries(store, "feedback") == []
+
+
+def test_memory_quality_policy_rejects_duplicate_transient_derivable_and_relative_time() -> None:
+    existing = [
+        MemoryRecord(
+            type="feedback",
+            rule="Run lint before commit",
+            why="The repo requires clean validation before code submission",
+            how_to_apply="Before any commit-like completion step, run lint first",
+        )
+    ]
+
+    duplicate = evaluate_memory_quality(
+        MemoryRecord(
+            type="feedback",
+            rule=" run lint before commit ",
+            why=" the repo requires clean validation before code submission ",
+            how_to_apply=" before any commit-like completion step, run lint first ",
+        ),
+        existing_records=existing,
+    )
+    transient = evaluate_memory_quality(
+        MemoryRecord(
+            type="project",
+            fact_or_decision="Currently working on Stage 12D",
+            why="It is the active task right now",
+            how_to_apply="Continue the task in this session",
+        )
+    )
+    derivable = evaluate_memory_quality(
+        MemoryRecord(
+            type="project",
+            fact_or_decision="The file list includes src/ and tests/",
+            why="This is repository structure only",
+            how_to_apply="Read the repo when you need it",
+        )
+    )
+    relative_time = evaluate_memory_quality(
+        MemoryRecord(
+            type="project",
+            fact_or_decision="The migration finishes next Tuesday",
+            why="That is the target release date",
+            how_to_apply="Plan the rollout around next Tuesday",
+        )
+    )
+    durable = evaluate_memory_quality(
+        MemoryRecord(
+            type="project",
+            fact_or_decision="Use LangChain store for long-term memory",
+            why="Cross-session continuity should not depend on transcript replay alone",
+            how_to_apply="Prefer store-backed memory for durable reusable knowledge",
+        ),
+    )
+
+    assert duplicate.allowed is False
+    assert duplicate.category == "duplicate"
+    assert transient.allowed is False
+    assert transient.category == "transient_state"
+    assert derivable.allowed is False
+    assert derivable.category == "derivable_information"
+    assert relative_time.allowed is False
+    assert relative_time.category == "relative_time"
+    assert durable.allowed is True
+    assert durable.category == "accepted"
+
+
+def test_memory_types_are_isolated_for_recall_and_duplicates() -> None:
+    store = InMemoryStore()
+    feedback = MemoryRecord(
+        type="feedback",
+        rule="Run lint before commit",
+        why="The repo requires clean validation before code submission",
+        how_to_apply="Before any commit-like completion step, run lint first",
+    )
+    user = MemoryRecord(
+        type="user",
+        profile="User prefers concise answers by default",
+        why_it_matters="Summaries should stay brief unless depth is requested",
+        how_to_apply="Default to concise status updates and closers",
+    )
+    save_memory_record(store, feedback)
+    save_memory_record(store, user)
+
+    feedback_records = list_memory_records(store, "feedback")
+    user_records = list_memory_records(store, "user")
+    feedback_recall = recall_memories(store, memory_type="feedback", query="lint")
+    user_recall = recall_memories(store, memory_type="user", query="concise")
+
+    duplicate_in_same_type = evaluate_memory_quality(
+        MemoryRecord(
+            type="feedback",
+            rule=" run lint before commit ",
+            why=" the repo requires clean validation before code submission ",
+            how_to_apply=" before any commit-like completion step, run lint first ",
+        ),
+        existing_records=feedback_records,
+    )
+    same_text_other_type = evaluate_memory_quality(
+        MemoryRecord(
+            type="user",
+            profile="Run lint before commit",
+            why_it_matters="The user wants reliable delivery",
+            how_to_apply="Mention lint in completion summaries when relevant",
+        ),
+        existing_records=user_records,
+    )
+
+    assert [record.type for record in feedback_records] == ["feedback"]
+    assert [record.type for record in user_records] == ["user"]
+    assert [record.type for record in feedback_recall] == ["feedback"]
+    assert [record.type for record in user_recall] == ["user"]
+    assert duplicate_in_same_type.allowed is False
+    assert same_text_other_type.allowed is True
diff --git a/coding-deepgent/tests/memory/test_memory_backend.py b/coding-deepgent/tests/memory/test_memory_backend.py
new file mode 100644
index 000000000..7ea803f56
--- /dev/null
+++ b/coding-deepgent/tests/memory/test_memory_backend.py
@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from coding_deepgent.memory.archive import InMemoryArchiveStore
+from coding_deepgent.memory.backend import (
+    MemoryJobStatus,
+    SqlAlchemyMemoryRepository,
+    create_memory_engine,
+    migrate_memory_schema,
+)
+from coding_deepgent.memory.queue import InMemoryQueue
+from coding_deepgent.memory.schemas import MemoryRecord
+from coding_deepgent.memory.service import ExtractionCandidate, MemoryService
+
+
+def _sqlite_repo(tmp_path: Path) -> SqlAlchemyMemoryRepository:
+    engine = create_memory_engine(f"sqlite+pysqlite:///{tmp_path / 'memory.db'}")
+    migrate_memory_schema(engine)
+    return SqlAlchemyMemoryRepository(engine)
+
+
+def test_sqlalchemy_memory_repository_persists_records_and_versions(tmp_path: Path) -> None:
+    repo = _sqlite_repo(tmp_path)
+    stored = repo.save_record(
+        project_scope="repo-a",
+        agent_scope=None,
+        record=MemoryRecord(
+            type="feedback",
+            rule="Run lint before commit",
+            why="The repo requires clean validation before code submission",
+            how_to_apply="Before any commit-like completion step, run lint first",
+        ),
+        source="manual",
+    )
+
+    listed = repo.list_records(project_scope="repo-a")
+
+    assert stored.record.type == "feedback"
+    assert [item.id for item in listed] == [stored.id]
+    assert listed[0].record.rule == "Run lint before commit"
+
+
+def test_memory_service_processes_extraction_and_snapshot_jobs(tmp_path: Path) -> None:
+    repo = _sqlite_repo(tmp_path)
+    queue = InMemoryQueue()
+    archive = InMemoryArchiveStore()
+
+    def extractor(candidate: ExtractionCandidate) -> list[MemoryRecord]:
+        return [
+            MemoryRecord(
+                type="feedback",
+                rule="Run lint before commit",
+                why=f"Extracted from {candidate.source}",
+                how_to_apply="Before any commit-like completion step, run lint first",
+                source="auto_extract",
+            )
+        ]
+
+    service = MemoryService(
+        repository=repo,
+        queue=queue,
+        archive_store=archive,
+        extractor=extractor,
+    )
+
+    extract_job = service.enqueue_extraction(
+        project_scope="repo-a",
+        agent_scope="agent-a",
+        source="agent_loop",
+        text="User: please run lint before commit",
+    )
+    processed_extract = service.process_next_job()
+    assert processed_extract is not None
+    assert processed_extract.id == extract_job.id
+    assert processed_extract.status == MemoryJobStatus.COMPLETED
+
+    stored = service.list_records(project_scope="repo-a", agent_scope="agent-a")
+    assert stored
+    assert stored[0].record.rule == "Run lint before commit"
+    assert service.list_agent_scopes(project_scope="repo-a") == ["agent-a"]
+
+    snapshot_job = service.enqueue_snapshot_refresh(
+        project_scope="repo-a",
+        agent_scope="agent-a",
+        trigger="test",
+    )
+    processed_snapshot = service.process_next_job()
+    assert processed_snapshot is not None
+    assert processed_snapshot.status == MemoryJobStatus.COMPLETED
+    assert processed_snapshot.archive_object_key is not None
+    assert processed_snapshot.archive_object_key in archive.objects
+    assert snapshot_job.job_type == "refresh_agent_memory_snapshot"
diff --git a/coding-deepgent/tests/memory/test_memory_cli.py b/coding-deepgent/tests/memory/test_memory_cli.py
new file mode 100644
index 000000000..f7feafb16
--- /dev/null
+++ b/coding-deepgent/tests/memory/test_memory_cli.py
@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from typer.testing import CliRunner
+
+import coding_deepgent.app as app_module
+from coding_deepgent import cli
+from coding_deepgent.app import build_container as real_build_container
+from coding_deepgent.memory.schemas import MemoryRecord
+
+runner = CliRunner()
+
+
+def test_memory_migrate_command(monkeypatch, tmp_path: Path) -> None:
+    monkeypatch.setenv("CODING_DEEPGENT_WORKDIR", str(tmp_path))
+    monkeypatch.setenv("POSTGRES_URL", "")
+    monkeypatch.setenv("REDIS_URL", "")
+    monkeypatch.setenv("OFFLOAD_BACKEND", "none")
+
+    result = runner.invoke(cli.app, ["memory", "migrate"])
+
+    assert result.exit_code == 0
+    assert "Memory backend schema is ready." in result.stdout
+
+
+def test_memory_jobs_and_worker_commands(monkeypatch, tmp_path: Path) -> None:
+    monkeypatch.setenv("CODING_DEEPGENT_WORKDIR", str(tmp_path))
+    monkeypatch.setenv("POSTGRES_URL", "")
+    monkeypatch.setenv("REDIS_URL", "")
+    monkeypatch.setenv("OFFLOAD_BACKEND", "none")
+    container = real_build_container()
+    service = container.memory_backend.service()
+    service.enqueue_extraction(
+        project_scope=str(tmp_path),
+        agent_scope="coding-deepgent-test",
+        source="agent_loop",
+        text="User: run lint before commit",
+    )
+
+    monkeypatch.setattr(app_module, "build_container", lambda: container)
+
+    jobs_result = runner.invoke(cli.app, ["memory", "jobs"])
+    assert jobs_result.exit_code == 0
+    assert "extract_long_term_memory" in jobs_result.stdout
+    assert "queued" in jobs_result.stdout
+
+    worker_result = runner.invoke(cli.app, ["memory", "worker-run-once"])
+    assert worker_result.exit_code == 0
+    assert "Processed memory job" in worker_result.stdout
+
+    records = service.list_records(
+        project_scope=str(tmp_path), agent_scope="coding-deepgent-test"
+    )
+    assert records
+    assert records[0].record.type == "feedback"
+
+
+def test_memory_records_and_agent_scopes_commands(monkeypatch, tmp_path: Path) -> None:
+    monkeypatch.setenv("CODING_DEEPGENT_WORKDIR", str(tmp_path))
+    monkeypatch.setenv("POSTGRES_URL", "")
+    monkeypatch.setenv("REDIS_URL", "")
+    monkeypatch.setenv("OFFLOAD_BACKEND", "none")
+    container = real_build_container()
+    service = container.memory_backend.service()
+    stored = service.save_record(
+        project_scope=str(tmp_path),
+        agent_scope="coding-deepgent-test",
+        record=MemoryRecord(
+            type="feedback",
+            rule="Run lint before commit",
+            why="CLI inspection test",
+            how_to_apply="Before any commit-like completion step, run lint first",
+        ),
+        source="manual",
+    )
+
+    monkeypatch.setattr(app_module, "build_container", lambda: container)
+
+    records_result = runner.invoke(
+        cli.app, ["memory", "records", "--agent-scope", "coding-deepgent-test"]
+    )
+    assert records_result.exit_code == 0
+    assert stored.id in records_result.stdout
+    assert "coding-deepgent-test" in records_result.stdout
+
+    scopes_result = runner.invoke(cli.app, ["memory", "agent-scopes"])
+    assert scopes_result.exit_code == 0
+    assert "coding-deepgent-test" in scopes_result.stdout
diff --git a/coding-deepgent/tests/memory/test_memory_context.py b/coding-deepgent/tests/memory/test_memory_context.py
new file mode 100644
index 000000000..12d47d87b
--- /dev/null
+++ b/coding-deepgent/tests/memory/test_memory_context.py
@@ -0,0 +1,33 @@
+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(
+                type="feedback",
+                rule="Run lint before commit",
+                why="The repo requires clean validation before code submission",
+                how_to_apply="Before any commit-like completion step, run lint first",
+            )
+        ],
+    )
+
+    assert context.memory_context == (
+        "Relevant long-term memory:\n"
+        "Feedback memory:\n"
+        "- Rule: Run lint before commit\n"
+        "  Why: The repo requires clean validation before code submission\n"
+        "  How to apply: Before any commit-like completion step, run lint first"
+    )
+    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/memory/test_memory_integration.py b/coding-deepgent/tests/memory/test_memory_integration.py
new file mode 100644
index 000000000..8779f67e5
--- /dev/null
+++ b/coding-deepgent/tests/memory/test_memory_integration.py
@@ -0,0 +1,397 @@
+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.language_models.fake_chat_models import FakeMessagesListChatModel
+from langchain_core.messages import AIMessage
+from langgraph.store.memory import InMemoryStore
+from pydantic import PrivateAttr
+
+from coding_deepgent.context_payloads import ContextPayload, merge_system_message_content
+from coding_deepgent.containers import AppContainer
+from coding_deepgent.memory import (
+    LONG_TERM_MEMORY_STATE_KEY,
+    MemoryContextMiddleware,
+    MemoryRecord,
+    delete_memory,
+    list_memory,
+    memory_namespace,
+    save_memory,
+    save_memory_record,
+)
+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": {
+                            "type": "feedback",
+                            "rule": "Run lint before commit",
+                            "why": "The repo requires clean validation before code submission",
+                            "how_to_apply": "Before any commit-like completion step, run lint first",
+                        },
+                        "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 feedback memory" in str(message.content) for message in result["messages"]
+    )
+    records = store.search(memory_namespace("feedback"))
+    assert [item.value["rule"] for item in records] == ["Run lint before commit"]
+
+
+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": {
+                            "type": "project",
+                            "fact_or_decision": "Currently working on Stage 12D",
+                            "why": "It is the active task right now",
+                            "how_to_apply": "Continue the task in this session",
+                        },
+                        "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_list_memory_tool_renders_keys_and_type_filtered_entries() -> None:
+    store = InMemoryStore()
+    entry_key = save_memory_record(
+        store,
+        MemoryRecord(
+            type="feedback",
+            rule="Run lint before commit",
+            why="The repo requires clean validation before code submission",
+            how_to_apply="Before any commit-like completion step, run lint first",
+        ),
+    )
+    model = RecordingFakeModel(
+        responses=[
+            AIMessage(
+                content="",
+                tool_calls=[
+                    {
+                        "name": "list_memory",
+                        "args": {"type": "feedback"},
+                        "id": "mem1",
+                        "type": "tool_call",
+                    }
+                ],
+            ),
+            AIMessage(content="done"),
+        ]
+    )
+
+    agent = create_agent(model=model, tools=[list_memory], store=store)
+    result = agent.invoke({"messages": [{"role": "user", "content": "list"}]})
+
+    assert any("Long-term memory entries:" in str(message.content) for message in result["messages"])
+    assert any(entry_key in str(message.content) for message in result["messages"])
+    assert any("Run lint before commit" in str(message.content) for message in result["messages"])
+
+
+def test_delete_memory_tool_removes_entry_via_create_agent_runtime() -> None:
+    store = InMemoryStore()
+    entry_key = save_memory_record(
+        store,
+        MemoryRecord(
+            type="feedback",
+            rule="Run lint before commit",
+            why="The repo requires clean validation before code submission",
+            how_to_apply="Before any commit-like completion step, run lint first",
+        ),
+    )
+    model = RecordingFakeModel(
+        responses=[
+            AIMessage(
+                content="",
+                tool_calls=[
+                    {
+                        "name": "delete_memory",
+                        "args": {"type": "feedback", "key": entry_key},
+                        "id": "mem1",
+                        "type": "tool_call",
+                    }
+                ],
+            ),
+            AIMessage(content="done"),
+        ]
+    )
+
+    agent = create_agent(model=model, tools=[delete_memory], store=store)
+    result = agent.invoke({"messages": [{"role": "user", "content": "delete"}]})
+
+    assert any(
+        f"Deleted feedback memory {entry_key}." in str(message.content)
+        for message in result["messages"]
+    )
+    assert store.search(memory_namespace("feedback")) == []
+
+
+def test_memory_context_middleware_injects_store_backed_memory() -> None:
+    store = InMemoryStore()
+    save_memory_record(
+        store,
+        MemoryRecord(
+            type="feedback",
+            rule="Run lint before commit",
+            why="The repo requires clean validation before code submission",
+            how_to_apply="Before any commit-like completion step, run lint first",
+        ),
+    )
+    runtime = SimpleNamespace(store=store)
+    captured: dict[str, object] = {}
+
+    def handler(request: ModelRequest):
+        captured["system_message"] = request.system_message
+        captured["state"] = request.state
+        return SimpleNamespace(result="ok")
+
+    middleware = MemoryContextMiddleware()
+    request = ModelRequest(
+        model=RecordingFakeModel(responses=[]),
+        messages=[HumanMessage(content="lint 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 "Feedback memory:" in str(system_message.content)
+    assert "Run lint before commit" in str(system_message.content)
+    assert LONG_TERM_MEMORY_STATE_KEY in cast(dict[str, object], captured["state"])
+
+
+def test_memory_context_payload_renderer_path_is_shared() -> None:
+    payload_text = (
+        "Relevant long-term memory:\n"
+        "Feedback memory:\n"
+        "- Rule: Run lint before commit\n"
+        "  Why: The repo requires clean validation before code submission\n"
+        "  How to apply: Before any commit-like completion step, run lint first"
+    )
+    blocks = merge_system_message_content(
+        [{"type": "text", "text": "Base"}],
+        [
+            ContextPayload(
+                kind="memory",
+                text=payload_text,
+                source="memory.long_term",
+                priority=200,
+            )
+        ],
+    )
+
+    assert blocks == [
+        {"type": "text", "text": "Base"},
+        {"type": "text", "text": payload_text},
+    ]
+
+
+def test_memory_context_middleware_respects_type_scope() -> None:
+    store = InMemoryStore()
+    save_memory_record(
+        store,
+        MemoryRecord(
+            type="project",
+            fact_or_decision="Use JWT for auth",
+            why="Mobile clients need stateless authentication",
+            how_to_apply="Prefer JWT-compatible auth changes",
+        ),
+    )
+    save_memory_record(
+        store,
+        MemoryRecord(
+            type="user",
+            profile="User prefers concise answers by default",
+            why_it_matters="Summaries should stay brief unless depth is requested",
+            how_to_apply="Default to concise status updates and closers",
+        ),
+    )
+    runtime = SimpleNamespace(store=store)
+    captured: dict[str, object] = {}
+
+    def handler(request: ModelRequest):
+        captured["system_message"] = request.system_message
+        return SimpleNamespace(result="ok")
+
+    middleware = MemoryContextMiddleware(memory_type="user")
+    request = ModelRequest(
+        model=RecordingFakeModel(responses=[]),
+        messages=[HumanMessage(content="concise 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 "User prefers concise answers by default" in text
+    assert "Use JWT for auth" 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",
+        "SessionMemoryContextMiddleware",
+        "RuntimePressureMiddleware",
+        "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(
+            type="project",
+            fact_or_decision="Use LangChain store for long-term memory",
+            why="Cross-session continuity should not depend on transcript replay alone",
+            how_to_apply="Prefer store-backed memory for durable reusable knowledge",
+        ),
+    )
+    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 "Project 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/memory/test_memory_module_closeout.py b/coding-deepgent/tests/memory/test_memory_module_closeout.py
new file mode 100644
index 000000000..9d8227d67
--- /dev/null
+++ b/coding-deepgent/tests/memory/test_memory_module_closeout.py
@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, cast
+
+from dependency_injector import providers
+from langchain.messages import ToolMessage
+from langchain.tools.tool_node import ToolCallRequest
+from langgraph.runtime import Runtime
+from langgraph.store.memory import InMemoryStore
+
+from coding_deepgent.containers import AppContainer
+from coding_deepgent.hooks import LocalHookRegistry
+from coding_deepgent.memory import (
+    MemoryRecord,
+    build_long_term_memory_snapshot,
+    save_memory_record,
+    write_long_term_memory_snapshot,
+)
+from coding_deepgent.runtime import InMemoryEventSink, RuntimeContext
+from coding_deepgent.sessions import (
+    JsonlSessionStore,
+    build_recovery_brief,
+    render_recovery_brief,
+)
+from coding_deepgent.sessions.session_memory import SESSION_MEMORY_STATE_KEY
+from coding_deepgent.settings import Settings
+from coding_deepgent.tool_system import ToolGuardMiddleware
+
+
+def test_app_container_exposes_memory_management_tools(tmp_path: Path) -> None:
+    container = AppContainer(
+        settings=providers.Object(Settings(workdir=tmp_path, store_backend="memory")),
+        model=providers.Object(object()),
+        create_agent_factory=providers.Object(lambda **kwargs: object()),
+    )
+
+    tool_names = [
+        getattr(tool, "name", type(tool).__name__)
+        for tool in container.tool_system.tools()
+    ]
+
+    assert "save_memory" in tool_names
+    assert "list_memory" in tool_names
+    assert "delete_memory" in tool_names
+
+
+def test_feedback_memory_blocks_commit_through_tool_guard(tmp_path: Path) -> None:
+    container = AppContainer(
+        settings=providers.Object(Settings(workdir=tmp_path, store_backend="memory")),
+        model=providers.Object(object()),
+        create_agent_factory=providers.Object(lambda **kwargs: object()),
+    )
+    store = container.runtime.store()
+    save_memory_record(
+        store,
+        MemoryRecord(
+            type="feedback",
+            rule="Run lint before commit",
+            why="The repo requires clean validation before code submission",
+            how_to_apply="Before any commit-like completion step, run lint first",
+        ),
+    )
+    sink = InMemoryEventSink()
+    middleware = ToolGuardMiddleware(
+        registry=container.tool_system.capability_registry(),
+        event_sink=sink,
+    )
+    request = ToolCallRequest(
+        tool_call={"name": "bash", "args": {"command": "git commit -m 'x'"}, "id": "call-1"},
+        tool=None,
+        state={},
+        runtime=cast(
+            Any,
+            Runtime(
+                context=RuntimeContext(
+                    session_id="session-1",
+                    workdir=tmp_path,
+                    trusted_workdirs=(),
+                    entrypoint="test",
+                    agent_name="test-agent",
+                    skill_dir=tmp_path / "skills",
+                    event_sink=sink,
+                    hook_registry=LocalHookRegistry(),
+                ),
+                store=store,
+            ),
+        ),
+    )
+
+    result = middleware.wrap_tool_call(
+        request,
+        lambda _request: ToolMessage(content="should not run", tool_call_id="call-1"),
+    )
+
+    assert isinstance(result, ToolMessage)
+    assert result.status == "error"
+    assert "Run lint first" in str(result.content)
+
+
+def test_recovery_brief_separates_long_term_and_current_session_memory(
+    tmp_path: Path,
+) -> None:
+    store = InMemoryStore()
+    save_memory_record(
+        store,
+        MemoryRecord(
+            type="feedback",
+            rule="Run lint before commit",
+            why="The repo requires clean validation before code submission",
+            how_to_apply="Before any commit-like completion step, run lint first",
+        ),
+    )
+    state: dict[str, Any] = {
+        "messages": [],
+        "todos": [],
+        "rounds_since_update": 0,
+        SESSION_MEMORY_STATE_KEY: {
+            "content": "Current repo focus is deterministic assist.",
+            "source": "manual",
+            "message_count": 1,
+            "updated_at": "2026-04-18T00:00:00Z",
+        },
+    }
+    write_long_term_memory_snapshot(state, build_long_term_memory_snapshot(store))
+
+    session_store = JsonlSessionStore(tmp_path / "sessions")
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+    context = session_store.create_session(workdir=workdir, entrypoint="cli")
+    session_store.append_message(context, role="user", content="resume")
+    session_store.append_state_snapshot(context, state=state)
+    loaded = session_store.load_session(session_id=context.session_id, workdir=workdir)
+    rendered = render_recovery_brief(build_recovery_brief(loaded))
+
+    assert "Long-term memory:" in rendered
+    assert "Run lint before commit" in rendered
+    assert "Current-session memory:" in rendered
+    assert "Current repo focus is deterministic assist." in rendered
diff --git a/coding-deepgent/tests/permissions/test_permissions.py b/coding-deepgent/tests/permissions/test_permissions.py
new file mode 100644
index 000000000..fa7edef4f
--- /dev/null
+++ b/coding-deepgent/tests/permissions/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/runtime/test_agent_runtime_service.py b/coding-deepgent/tests/runtime/test_agent_runtime_service.py
new file mode 100644
index 000000000..4b9086e73
--- /dev/null
+++ b/coding-deepgent/tests/runtime/test_agent_runtime_service.py
@@ -0,0 +1,333 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, cast
+
+import pytest
+from dependency_injector import providers
+
+from coding_deepgent.agent_loop_service import run_agent_loop
+from coding_deepgent.agent_runtime_service import session_payload, update_session_state
+from coding_deepgent.compact import ORPHAN_TOOL_RESULT_TOMBSTONE
+from coding_deepgent.containers import AppContainer
+from coding_deepgent.hooks import LocalHookRegistry
+from coding_deepgent.memory import MemoryRecord, save_memory_record
+from coding_deepgent.runtime import InMemoryEventSink, RuntimeContext, RuntimeInvocation
+from coding_deepgent.sessions import JsonlSessionStore
+from coding_deepgent.settings import Settings
+
+
+class CapturingAgent:
+    def __init__(self) -> None:
+        self.payloads: list[dict[str, Any]] = []
+
+    def invoke(
+        self,
+        payload: dict[str, Any],
+        *,
+        context: RuntimeContext,
+        config: dict[str, dict[str, str]],
+    ) -> dict[str, Any]:
+        del context, config
+        self.payloads.append(payload)
+        return {
+            "messages": [
+                *payload["messages"],
+                {"role": "assistant", "content": "ok"},
+            ],
+            "todos": [],
+            "rounds_since_update": 0,
+        }
+
+
+class FailingAgent:
+    def invoke(
+        self,
+        payload: dict[str, Any],
+        *,
+        context: RuntimeContext,
+        config: dict[str, dict[str, str]],
+    ) -> dict[str, Any]:
+        del payload, context, config
+        raise RuntimeError("model transport failed")
+
+
+def _invocation(tmp_path: Path, *, sink: InMemoryEventSink) -> RuntimeInvocation:
+    return RuntimeInvocation(
+        context=RuntimeContext(
+            session_id="session-1",
+            workdir=tmp_path,
+            trusted_workdirs=(),
+            entrypoint="test",
+            agent_name="test-agent",
+            skill_dir=tmp_path / "skills",
+            event_sink=sink,
+            hook_registry=LocalHookRegistry(),
+        ),
+        config={"configurable": {"thread_id": "session-1"}},
+    )
+
+
+def _recorded_invocation(
+    tmp_path: Path,
+    *,
+    sink: InMemoryEventSink,
+    store: JsonlSessionStore,
+) -> RuntimeInvocation:
+    context = store.create_session(workdir=tmp_path, session_id="session-1")
+    store.append_message(context, role="user", content="start")
+    invocation = _invocation(tmp_path, sink=sink)
+    return RuntimeInvocation(
+        context=RuntimeContext(
+            session_id=invocation.context.session_id,
+            workdir=invocation.context.workdir,
+            trusted_workdirs=invocation.context.trusted_workdirs,
+            entrypoint=invocation.context.entrypoint,
+            agent_name=invocation.context.agent_name,
+            skill_dir=invocation.context.skill_dir,
+            event_sink=invocation.context.event_sink,
+            hook_registry=invocation.context.hook_registry,
+            session_context=context,
+        ),
+        config=invocation.config,
+    )
+
+
+def _unused_container() -> AppContainer:
+    raise AssertionError("test provides an active container")
+
+
+def test_session_payload_preserves_session_memory_artifact() -> None:
+    payload = session_payload(
+        {
+            "todos": [],
+            "rounds_since_update": 0,
+            "session_memory": {
+                "content": "Keep repo focus.",
+                "source": "manual",
+                "message_count": 1,
+                "updated_at": "2026-04-15T00:00:00Z",
+            },
+        }
+    )
+
+    assert payload["session_memory"] == {
+        "content": "Keep repo focus.",
+        "source": "manual",
+        "message_count": 1,
+        "updated_at": "2026-04-15T00:00:00Z",
+    }
+
+
+def test_session_payload_preserves_long_term_memory_snapshot() -> None:
+    payload = session_payload(
+        {
+            "todos": [],
+            "rounds_since_update": 0,
+            "long_term_memory": {
+                "entries": [
+                    {
+                        "key": "abc123",
+                        "type": "feedback",
+                        "summary": "Run lint before commit",
+                    }
+                ],
+                "updated_at": "2026-04-18T00:00:00Z",
+            },
+        }
+    )
+
+    assert payload["long_term_memory"] == {
+        "entries": [
+            {
+                "key": "abc123",
+                "type": "feedback",
+                "summary": "Run lint before commit",
+            }
+        ],
+        "updated_at": "2026-04-18T00:00:00Z",
+    }
+
+
+def test_update_session_state_preserves_session_memory_artifact() -> None:
+    state = {"todos": [], "rounds_since_update": 0}
+
+    update_session_state(
+        state,
+        {
+            "todos": [],
+            "rounds_since_update": 1,
+            "session_memory": {
+                "content": "Keep repo focus.",
+                "source": "live_compact",
+                "message_count": 2,
+                "updated_at": "2026-04-15T00:00:00Z",
+            },
+        },
+    )
+
+    assert state["session_memory"] == {
+        "content": "Keep repo focus.",
+        "source": "live_compact",
+        "message_count": 2,
+        "updated_at": "2026-04-15T00:00:00Z",
+    }
+
+
+def test_update_session_state_preserves_long_term_memory_snapshot() -> None:
+    state = {"todos": [], "rounds_since_update": 0}
+
+    update_session_state(
+        state,
+        {
+            "todos": [],
+            "rounds_since_update": 1,
+            "long_term_memory": {
+                "entries": [
+                    {
+                        "key": "abc123",
+                        "type": "feedback",
+                        "summary": "Run lint before commit",
+                    }
+                ],
+                "updated_at": "2026-04-18T00:00:00Z",
+            },
+        },
+    )
+
+    assert state["long_term_memory"] == {
+        "entries": [
+            {
+                "key": "abc123",
+                "type": "feedback",
+                "summary": "Run lint before commit",
+            }
+        ],
+        "updated_at": "2026-04-18T00:00:00Z",
+    }
+
+
+def test_agent_loop_emits_orphan_tombstoned_event_and_uses_repaired_projection(
+    tmp_path: Path,
+) -> None:
+    sink = InMemoryEventSink()
+    store = JsonlSessionStore(tmp_path / "sessions")
+    invocation = _recorded_invocation(tmp_path, sink=sink, store=store)
+    agent = CapturingAgent()
+    messages = [
+        {
+            "role": "user",
+            "content": [
+                {
+                    "type": "tool_result",
+                    "tool_use_id": "missing-call",
+                    "content": "raw output",
+                }
+            ],
+        }
+    ]
+
+    result = run_agent_loop(
+        messages=messages,
+        session_state={},
+        session_id="session-1",
+        container=cast(AppContainer, object()),
+        build_container=_unused_container,
+        build_agent=lambda: agent,
+        build_runtime_invocation=lambda **_: invocation,
+    )
+
+    assert result == "ok"
+    assert agent.payloads[0]["messages"] == [
+        {
+            "role": "user",
+            "content": [{"type": "text", "text": ORPHAN_TOOL_RESULT_TOMBSTONE}],
+        }
+    ]
+    events = sink.snapshot()
+    assert events[0].kind == "orphan_tombstoned"
+    assert events[0].metadata["tombstoned_count"] == 1
+    loaded = store.load_session(session_id="session-1", workdir=tmp_path)
+    assert loaded.evidence[0].metadata == {
+        "event_kind": "orphan_tombstoned",
+        "source": "message_projection",
+        "reason": "missing_tool_use",
+        "tombstoned_count": 1,
+        "message_count": 1,
+    }
+
+
+def test_agent_loop_emits_structured_query_error_event_and_evidence(
+    tmp_path: Path,
+) -> None:
+    sink = InMemoryEventSink()
+    store = JsonlSessionStore(tmp_path / "sessions")
+    invocation = _recorded_invocation(tmp_path, sink=sink, store=store)
+
+    with pytest.raises(RuntimeError, match="model transport failed"):
+        run_agent_loop(
+            messages=[{"role": "user", "content": "hello"}],
+            session_state={},
+            session_id="session-1",
+            container=cast(AppContainer, object()),
+            build_container=_unused_container,
+            build_agent=lambda: FailingAgent(),
+            build_runtime_invocation=lambda **_: invocation,
+        )
+
+    event = sink.snapshot()[0]
+    assert event.kind == "query_error"
+    assert event.metadata == {
+        "source": "agent_loop",
+        "phase": "agent_invoke",
+        "error_class": "RuntimeError",
+        "retry_count": 0,
+    }
+    loaded = store.load_session(session_id="session-1", workdir=tmp_path)
+    assert loaded.evidence[0].status == "failed"
+    assert loaded.evidence[0].metadata == {
+        "event_kind": "query_error",
+        "source": "agent_loop",
+        "phase": "agent_invoke",
+        "error_class": "RuntimeError",
+        "retry_count": 0,
+    }
+
+
+def test_run_agent_loop_refreshes_long_term_memory_snapshot_from_store(
+    tmp_path: Path,
+) -> None:
+    sink = InMemoryEventSink()
+    container = AppContainer(
+        settings=providers.Object(Settings(workdir=tmp_path, store_backend="memory")),
+        model=providers.Object(object()),
+        create_agent_factory=providers.Object(lambda **kwargs: object()),
+    )
+    save_memory_record(
+        container.runtime.store(),
+        MemoryRecord(
+            type="feedback",
+            rule="Run lint before commit",
+            why="The repo requires clean validation before code submission",
+            how_to_apply="Before any commit-like completion step, run lint first",
+        ),
+    )
+    invocation = _invocation(tmp_path, sink=sink)
+    session_state: dict[str, Any] = {}
+
+    result = run_agent_loop(
+        messages=[{"role": "user", "content": "hello"}],
+        session_state=session_state,
+        session_id="session-1",
+        container=container,
+        build_container=_unused_container,
+        build_agent=lambda: CapturingAgent(),
+        build_runtime_invocation=lambda **_: invocation,
+    )
+
+    assert result == "ok"
+    assert session_state["long_term_memory"]["entries"][0]["type"] == "feedback"
+    assert (
+        session_state["long_term_memory"]["entries"][0]["summary"]
+        == "Run lint before commit"
+    )
diff --git a/coding-deepgent/tests/runtime/test_app.py b/coding-deepgent/tests/runtime/test_app.py
new file mode 100644
index 000000000..7d005f557
--- /dev/null
+++ b/coding-deepgent/tests/runtime/test_app.py
@@ -0,0 +1,493 @@
+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.compact import RuntimePressureMiddleware
+from coding_deepgent.sessions.session_memory_middleware import (
+    SessionMemoryContextMiddleware,
+)
+from coding_deepgent.runtime import (
+    InMemoryEventSink,
+    QueuedRuntimeEventSink,
+    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",
+    "list_memory",
+    "delete_memory",
+    "load_skill",
+    "ToolSearch",
+    "invoke_deferred_tool",
+    "task_create",
+    "task_get",
+    "task_list",
+    "task_update",
+    "plan_save",
+    "plan_get",
+    "run_subagent",
+    "run_fork",
+]
+
+
+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) == 5
+    assert isinstance(middleware[0], PlanContextMiddleware)
+    assert isinstance(middleware[1], MemoryContextMiddleware)
+    assert isinstance(middleware[2], SessionMemoryContextMiddleware)
+    assert isinstance(middleware[3], RuntimePressureMiddleware)
+    assert isinstance(middleware[4], 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_build_agent_wires_runtime_pressure_settings(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)
+    container = AppContainer(
+        settings=providers.Object(
+            Settings(
+                auto_compact_threshold_tokens=1234,
+                auto_compact_max_failures=2,
+                auto_compact_ptl_retry_limit=3,
+                snip_threshold_tokens=2345,
+                collapse_threshold_tokens=3456,
+                model_context_window_tokens=20000,
+                collapse_trigger_ratio=0.75,
+                subagent_spawn_guard_ratio=0.95,
+                keep_recent_tool_results=5,
+                microcompact_time_gap_minutes=60,
+                microcompact_min_saved_tokens=100,
+                microcompact_protect_recent_tokens=40000,
+                microcompact_min_prune_saved_tokens=20000,
+                keep_recent_messages_after_snip=7,
+                keep_recent_messages_after_collapse=8,
+                keep_recent_messages_after_compact=6,
+                agent_name="custom-agent",
+                entrypoint="custom-entrypoint",
+            )
+        ),
+        model=providers.Object(object()),
+        create_agent_factory=providers.Object(fake_create_agent),
+    )
+
+    agent = app.build_agent(container=container)
+
+    assert agent is not None
+    middleware = cast(Sequence[object], captured["middleware"])
+    runtime_pressure = cast(RuntimePressureMiddleware, middleware[3])
+    assert runtime_pressure.auto_compact_threshold_tokens == 1234
+    assert runtime_pressure.auto_compact_max_failures == 2
+    assert runtime_pressure.auto_compact_ptl_retry_limit == 3
+    assert runtime_pressure.snip_threshold_tokens == 2345
+    assert runtime_pressure.collapse_threshold_tokens == 3456
+    assert runtime_pressure.model_context_window_tokens == 20000
+    assert runtime_pressure.collapse_trigger_ratio == 0.75
+    assert runtime_pressure.keep_recent_tool_results == 5
+    assert runtime_pressure.microcompact_time_gap_minutes == 60
+    assert runtime_pressure.microcompact_min_saved_tokens == 100
+    assert runtime_pressure.microcompact_protect_recent_tokens == 40000
+    assert runtime_pressure.microcompact_min_prune_saved_tokens == 20000
+    assert runtime_pressure.main_agent_name == "custom-agent"
+    assert runtime_pressure.main_entrypoint == "custom-entrypoint"
+    assert runtime_pressure.keep_recent_messages_after_snip == 7
+    assert runtime_pressure.keep_recent_messages_after_collapse == 8
+    assert runtime_pressure.keep_recent_messages == 6
+
+
+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_runtime_container_uses_queued_event_sink_by_default(tmp_path: Path) -> None:
+    container = AppContainer(
+        settings=providers.Object(Settings(workdir=tmp_path)),
+        model=providers.Object(object()),
+        create_agent_factory=providers.Object(lambda **kwargs: object()),
+    )
+
+    assert isinstance(container.runtime.event_sink(), QueuedRuntimeEventSink)
+
+
+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/runtime/test_circle2_substrate.py b/coding-deepgent/tests/runtime/test_circle2_substrate.py
new file mode 100644
index 000000000..c197b6a05
--- /dev/null
+++ b/coding-deepgent/tests/runtime/test_circle2_substrate.py
@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from langgraph.store.memory import InMemoryStore
+
+from coding_deepgent.continuity import get_artifact, list_artifacts, save_artifact
+from coding_deepgent.event_stream import ack_event, append_event, list_events
+from coding_deepgent.extension_lifecycle import (
+    disable_extension,
+    enable_extension,
+    register_extension,
+    rollback_extension,
+)
+from coding_deepgent.mailbox import ack_message, list_messages, send_message
+from coding_deepgent.remote import (
+    close_remote_session,
+    register_remote_session,
+    replay_remote_events,
+    send_remote_control,
+)
+from coding_deepgent.teams import assign_worker, complete_team, create_team
+from coding_deepgent.worker_runtime import (
+    complete_worker,
+    create_worker,
+    heartbeat_worker,
+    request_worker_stop,
+)
+
+
+def test_event_stream_appends_replays_and_acks() -> None:
+    store = InMemoryStore()
+
+    first = append_event(store, stream_id="session-1", kind="started")
+    second = append_event(store, stream_id="session-1", kind="progress")
+    acked = ack_event(store, stream_id="session-1", event_id=first.event_id)
+
+    assert [event.sequence for event in list_events(store, stream_id="session-1")] == [
+        1,
+        2,
+    ]
+    assert list_events(store, stream_id="session-1", after_sequence=1)[0].event_id == second.event_id
+    assert acked.acked is True
+
+
+def test_worker_runtime_records_heartbeat_stop_and_completion() -> None:
+    store = InMemoryStore()
+
+    worker = create_worker(store, kind="assistant", session_id="session-1")
+    running = heartbeat_worker(store, worker.worker_id)
+    stopping = request_worker_stop(store, worker.worker_id)
+    completed = complete_worker(store, worker.worker_id, result_summary="done")
+
+    assert running.status == "running"
+    assert stopping.stop_requested is True
+    assert completed.status == "completed"
+
+
+def test_mailbox_send_is_idempotent_and_ackable() -> None:
+    store = InMemoryStore()
+
+    first = send_message(
+        store,
+        sender="coordinator",
+        recipient="worker-1",
+        subject="task",
+        body="do it",
+        delivery_key="delivery-1",
+    )
+    second = send_message(
+        store,
+        sender="coordinator",
+        recipient="worker-1",
+        subject="task",
+        body="do it",
+        delivery_key="delivery-1",
+    )
+    acked = ack_message(store, first.message_id)
+
+    assert first.message_id == second.message_id
+    assert acked.status == "acked"
+    assert len(list_messages(store, recipient="worker-1")) == 1
+
+
+def test_team_remote_extension_and_continuity_records() -> None:
+    store = InMemoryStore()
+
+    worker = create_worker(store, kind="assistant", session_id="session-1")
+    team = create_team(store, title="Ship feature")
+    team = assign_worker(store, team_id=team.team_id, worker_id=worker.worker_id)
+    team = complete_team(store, team_id=team.team_id, summary="done")
+    remote = register_remote_session(
+        store,
+        session_id="session-1",
+        client_name="ide",
+    )
+    event = send_remote_control(store, remote_id=remote.remote_id, command="stop")
+    extension = register_extension(
+        store,
+        name="demo",
+        kind="plugin",
+        source="local",
+    )
+    enabled = enable_extension(store, extension.extension_id)
+    disabled = disable_extension(store, extension.extension_id)
+    rolled_back = rollback_extension(store, extension.extension_id)
+    artifact = save_artifact(
+        store,
+        title="Next step",
+        content="Continue implementation.",
+        session_id="session-1",
+    )
+
+    assert team.status == "completed"
+    assert replay_remote_events(store, remote_id=remote.remote_id)[-1].event_id == event.event_id
+    assert close_remote_session(store, remote.remote_id).status == "closed"
+    assert enabled.status == "enabled"
+    assert disabled.status == "disabled"
+    assert rolled_back.status == "enabled"
+    assert get_artifact(store, artifact.artifact_id).title == "Next step"
+    assert list_artifacts(store)[0].artifact_id == artifact.artifact_id
diff --git a/coding-deepgent/tests/runtime/test_file_store.py b/coding-deepgent/tests/runtime/test_file_store.py
new file mode 100644
index 000000000..f5029c7a4
--- /dev/null
+++ b/coding-deepgent/tests/runtime/test_file_store.py
@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from coding_deepgent.runtime import FileStore, select_store
+from coding_deepgent.settings import Settings
+
+
+def test_file_store_roundtrips_across_instances(tmp_path: Path) -> None:
+    path = tmp_path / "store.json"
+    first = FileStore(path)
+    first.put(("tasks",), "task-1", {"title": "Implement"})
+
+    second = FileStore(path)
+    item = second.get(("tasks",), "task-1")
+    results = second.search(("tasks",))
+
+    assert item is not None
+    assert item.value == {"title": "Implement"}
+    assert len(results) == 1
+    assert results[0].key == "task-1"
+    assert results[0].value["title"] == "Implement"
+
+
+def test_file_store_delete_and_namespace_listing(tmp_path: Path) -> None:
+    store = FileStore(tmp_path / "store.json")
+    store.put(("tasks", "active"), "task-1", {"title": "Implement"})
+    store.put(("plans",), "plan-1", {"title": "Plan"})
+
+    namespaces = store.list_namespaces(prefix=("tasks",))
+    store.delete(("tasks", "active"), "task-1")
+
+    assert namespaces == [("tasks", "active")]
+    assert store.get(("tasks", "active"), "task-1") is None
+
+
+def test_select_store_file_backend_uses_store_path(tmp_path: Path) -> None:
+    store = select_store("file", store_path=tmp_path / "store.json")
+
+    assert isinstance(store, FileStore)
+
+
+def test_settings_default_store_backend_is_file_and_path_is_project_relative(
+    tmp_path: Path,
+) -> None:
+    settings = Settings(workdir=tmp_path)
+
+    assert settings.store_backend == "file"
+    assert settings.store_path == (tmp_path / ".coding-deepgent" / "store.json").resolve()
diff --git a/coding-deepgent/tests/runtime/test_runtime_events.py b/coding-deepgent/tests/runtime/test_runtime_events.py
new file mode 100644
index 000000000..ddefbc918
--- /dev/null
+++ b/coding-deepgent/tests/runtime/test_runtime_events.py
@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import pytest
+
+from coding_deepgent.runtime import (
+    InMemoryEventSink,
+    QueuedRuntimeEventSink,
+    RuntimeEvent,
+)
+
+
+def test_queued_runtime_event_sink_drains_pending_events_in_order() -> None:
+    queued = QueuedRuntimeEventSink()
+    queued.emit(RuntimeEvent(kind="first", message="one", session_id="session-1"))
+    queued.emit(RuntimeEvent(kind="second", message="two", session_id="session-1"))
+    concrete = InMemoryEventSink()
+
+    queued.attach(concrete)
+
+    assert queued.pending_count == 0
+    assert [event.kind for event in concrete.snapshot()] == ["first", "second"]
+    queued.emit(RuntimeEvent(kind="third", message="three", session_id="session-1"))
+    assert [event.kind for event in concrete.snapshot()] == [
+        "first",
+        "second",
+        "third",
+    ]
+
+
+def test_queued_runtime_event_sink_rejects_unsafe_duplicate_attachment() -> None:
+    queued = QueuedRuntimeEventSink()
+    concrete = InMemoryEventSink()
+    queued.attach(concrete)
+    queued.attach(concrete)
+
+    with pytest.raises(RuntimeError, match="already attached"):
+        queued.attach(InMemoryEventSink())
diff --git a/coding-deepgent/tests/runtime/test_runtime_foundation_contract.py b/coding-deepgent/tests/runtime/test_runtime_foundation_contract.py
new file mode 100644
index 000000000..4326080dc
--- /dev/null
+++ b/coding-deepgent/tests/runtime/test_runtime_foundation_contract.py
@@ -0,0 +1,247 @@
+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[2]
+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",
+    "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")
+    web_dependencies = _dependency_names("web")
+
+    if _is_runtime_foundation_or_later():
+        assert {
+            "dependency-injector",
+            "pydantic-settings",
+            "typer",
+            "rich",
+            "structlog",
+        } <= runtime_dependencies
+        assert {"ruff", "mypy"} <= dev_dependencies
+        assert {"fastapi", "uvicorn"} <= web_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/runtime/test_state.py b/coding-deepgent/tests/runtime/test_state.py
new file mode 100644
index 000000000..8e1e39148
--- /dev/null
+++ b/coding-deepgent/tests/runtime/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/sessions/test_session_contributions.py b/coding-deepgent/tests/sessions/test_session_contributions.py
new file mode 100644
index 000000000..ec88917ea
--- /dev/null
+++ b/coding-deepgent/tests/sessions/test_session_contributions.py
@@ -0,0 +1,444 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from coding_deepgent.sessions.contributions import (
+    CompactAssistContribution,
+    CompactSummaryUpdateContribution,
+    RecoveryBriefContribution,
+    RecoveryBriefSection,
+    RuntimeStateContribution,
+    apply_compact_summary_update_contributions,
+    build_recovery_brief_sections,
+    coerce_runtime_state_contributions,
+    compact_assist_text,
+)
+from coding_deepgent.sessions.records import (
+    CollapsedHistorySource,
+    CompactedHistorySource,
+    LoadedSession,
+    SessionContext,
+    SessionEvidence,
+    SessionMessage,
+    SessionSummary,
+)
+from coding_deepgent.sessions.runtime_pressure import (
+    recovery_brief_contribution as runtime_pressure_recovery_brief_contribution,
+)
+from coding_deepgent.sessions.subagent_activity import (
+    recovery_brief_contribution as subagent_activity_recovery_brief_contribution,
+)
+from coding_deepgent.sessions.session_memory import (
+    SESSION_MEMORY_STATE_KEY,
+    compact_summary_assist_text,
+    compact_summary_update_contribution,
+    read_session_memory_artifact,
+    session_memory_status,
+    should_refresh_session_memory,
+    session_memory_metrics,
+)
+
+
+def _loaded_session(state: dict[str, Any] | None = None) -> LoadedSession:
+    workdir = Path("/tmp/work")
+    return LoadedSession(
+        context=SessionContext(
+            session_id="session-1",
+            workdir=workdir,
+            store_dir=Path("/tmp/store"),
+            transcript_path=Path("/tmp/store/session-1.jsonl"),
+        ),
+        history=[
+            SessionMessage(
+                message_id="msg-000000",
+                created_at="2026-04-15T00:00:00Z",
+                role="user",
+                content="hello",
+            )
+        ],
+        compacted_history=[{"role": "user", "content": "hello"}],
+        compacted_history_source=CompactedHistorySource(
+            mode="raw",
+            reason="no_compacts",
+            compact_index=None,
+        ),
+        collapsed_history=[{"role": "user", "content": "hello"}],
+        collapsed_history_source=CollapsedHistorySource(
+            mode="raw",
+            reason="no_collapses",
+            collapse_index=None,
+        ),
+        state=state or {},
+        evidence=[],
+        compacts=[],
+        summary=SessionSummary(
+            session_id="session-1",
+            workdir=workdir,
+            transcript_path=Path("/tmp/store/session-1.jsonl"),
+            created_at="2026-04-15T00:00:00Z",
+            updated_at="2026-04-15T00:00:00Z",
+            first_prompt="hello",
+            message_count=1,
+        ),
+    )
+
+
+def _loaded_session_with_evidence(
+    evidence: list[SessionEvidence],
+) -> LoadedSession:
+    loaded = _loaded_session()
+    return LoadedSession(
+        context=loaded.context,
+        history=loaded.history,
+        compacted_history=loaded.compacted_history,
+        compacted_history_source=loaded.compacted_history_source,
+        collapsed_history=loaded.collapsed_history,
+        collapsed_history_source=loaded.collapsed_history_source,
+        state=loaded.state,
+        evidence=evidence,
+        compacts=loaded.compacts,
+        summary=loaded.summary,
+        collapses=loaded.collapses,
+    )
+
+
+def test_runtime_state_contributions_coerce_only_valid_values() -> None:
+    contributions = (
+        RuntimeStateContribution(
+            key="valid",
+            coerce=lambda state: state.get("valid") if state.get("valid") else None,
+        ),
+        RuntimeStateContribution(key="missing", coerce=lambda state: None),
+    )
+
+    assert coerce_runtime_state_contributions(
+        {"valid": {"ok": True}},
+        contributions,
+    ) == {"valid": {"ok": True}}
+
+
+def test_recovery_brief_contributions_skip_empty_sections() -> None:
+    contributions = (
+        RecoveryBriefContribution(
+            name="empty",
+            render=lambda loaded: None,
+        ),
+        RecoveryBriefContribution(
+            name="visible",
+            render=lambda loaded: RecoveryBriefSection(
+                title="Visible:",
+                lines=("- one",),
+            ),
+        ),
+    )
+
+    assert build_recovery_brief_sections(
+        _loaded_session(),
+        contributions,
+    ) == (RecoveryBriefSection(title="Visible:", lines=("- one",)),)
+
+
+def test_compact_assist_contributions_join_non_blank_text() -> None:
+    contributions = (
+        CompactAssistContribution(name="blank", render=lambda loaded: " "),
+        CompactAssistContribution(name="first", render=lambda loaded: "First assist."),
+        CompactAssistContribution(name="none", render=lambda loaded: None),
+        CompactAssistContribution(name="second", render=lambda loaded: "Second assist."),
+    )
+
+    assert (
+        compact_assist_text(_loaded_session(), contributions)
+        == "First assist.\n\nSecond assist."
+    )
+
+
+def test_compact_summary_update_contributions_report_updated_names() -> None:
+    seen: list[str] = []
+
+    def update(loaded: LoadedSession, summary: str) -> bool:
+        del loaded
+        seen.append(summary)
+        return True
+
+    contributions = (
+        CompactSummaryUpdateContribution(
+            name="skip",
+            update=lambda loaded, summary: False,
+        ),
+        CompactSummaryUpdateContribution(
+            name="update",
+            update=update,
+        ),
+    )
+
+    assert apply_compact_summary_update_contributions(
+        _loaded_session(),
+        summary="Generated summary.",
+        contributions=contributions,
+    ) == ("update",)
+    assert seen == ["Generated summary."]
+
+
+def test_session_memory_refresh_policy_detects_missing_and_stale_artifacts() -> None:
+    assert should_refresh_session_memory({}, current_message_count=1)
+    assert should_refresh_session_memory(
+        {
+            SESSION_MEMORY_STATE_KEY: {
+                "content": "old",
+                "source": "manual",
+                "message_count": 1,
+                "updated_at": "2026-04-15T00:00:00Z",
+            }
+        },
+        current_message_count=5,
+    )
+    assert not should_refresh_session_memory(
+        {
+            SESSION_MEMORY_STATE_KEY: {
+                "content": "recent",
+                "source": "manual",
+                "message_count": 4,
+                "updated_at": "2026-04-15T00:00:00Z",
+            }
+        },
+        current_message_count=5,
+    )
+
+
+def test_session_memory_refresh_policy_uses_token_and_tool_call_pressure() -> None:
+    state = {
+        SESSION_MEMORY_STATE_KEY: {
+            "content": "recent",
+            "source": "manual",
+            "message_count": 10,
+            "token_count": 100,
+            "tool_call_count": 1,
+            "updated_at": "2026-04-15T00:00:00Z",
+        }
+    }
+
+    assert should_refresh_session_memory(
+        state,
+        current_message_count=10,
+        current_token_count=5100,
+        current_tool_call_count=1,
+    )
+    assert should_refresh_session_memory(
+        state,
+        current_message_count=10,
+        current_token_count=100,
+        current_tool_call_count=4,
+    )
+    assert not should_refresh_session_memory(
+        state,
+        current_message_count=10,
+        current_token_count=200,
+        current_tool_call_count=2,
+    )
+
+
+def test_session_memory_status_uses_token_and_tool_call_pressure() -> None:
+    state = {
+        SESSION_MEMORY_STATE_KEY: {
+            "content": "recent",
+            "source": "manual",
+            "message_count": 10,
+            "token_count": 100,
+            "tool_call_count": 1,
+            "updated_at": "2026-04-15T00:00:00Z",
+        }
+    }
+    artifact = read_session_memory_artifact(state)
+
+    assert artifact is not None
+    assert (
+        session_memory_status(
+            artifact,
+            current_message_count=10,
+            current_token_count=5100,
+            current_tool_call_count=1,
+        )
+        == "stale"
+    )
+    assert (
+        session_memory_status(
+            artifact,
+            current_message_count=10,
+            current_token_count=100,
+            current_tool_call_count=4,
+        )
+        == "stale"
+    )
+    assert (
+        session_memory_status(
+            artifact,
+            current_message_count=11,
+            current_token_count=150,
+            current_tool_call_count=1,
+        )
+        == "current"
+    )
+
+
+def test_compact_summary_assist_text_skips_stale_token_pressure() -> None:
+    state = {
+        SESSION_MEMORY_STATE_KEY: {
+            "content": "recent",
+            "source": "manual",
+            "message_count": 10,
+            "token_count": 100,
+            "tool_call_count": 1,
+            "updated_at": "2026-04-15T00:00:00Z",
+        }
+    }
+    artifact = read_session_memory_artifact(state)
+    assert artifact is not None
+    assert (
+        compact_summary_assist_text(
+            artifact,
+            current_message_count=10,
+            current_token_count=5100,
+            current_tool_call_count=1,
+        )
+        is None
+    )
+
+
+def test_session_memory_metrics_estimates_tokens_and_tool_calls() -> None:
+    metrics = session_memory_metrics(
+        [
+            {"role": "user", "content": "abcd"},
+            {
+                "role": "assistant",
+                "content": [
+                    {"type": "text", "text": "abcdefgh"},
+                    {"type": "tool_use", "id": "tool-1"},
+                ],
+            },
+            {"role": "assistant", "content": "", "tool_calls": [{"name": "demo"}]},
+        ]
+    )
+
+    assert metrics.message_count == 3
+    assert metrics.estimated_token_count == 3
+    assert metrics.tool_call_count == 2
+
+
+def test_session_memory_compact_summary_update_provider_refreshes_state() -> None:
+    loaded = _loaded_session()
+
+    assert compact_summary_update_contribution().update(
+        loaded,
+        "Generated compact summary.",
+    )
+
+    assert loaded.state[SESSION_MEMORY_STATE_KEY]["content"] == (
+        "Generated compact summary."
+    )
+    assert loaded.state[SESSION_MEMORY_STATE_KEY]["source"] == "generated_compact"
+    assert loaded.state[SESSION_MEMORY_STATE_KEY]["message_count"] == 1
+    assert loaded.state[SESSION_MEMORY_STATE_KEY]["token_count"] == 2
+    assert loaded.state[SESSION_MEMORY_STATE_KEY]["tool_call_count"] == 0
+
+
+def test_session_memory_compact_summary_update_provider_skips_recent_state() -> None:
+    loaded = _loaded_session(
+        {
+            SESSION_MEMORY_STATE_KEY: {
+                "content": "Recent memory.",
+                "source": "manual",
+                "message_count": 1,
+                "updated_at": "2026-04-15T00:00:00Z",
+            }
+        }
+    )
+
+    assert not compact_summary_update_contribution().update(
+        loaded,
+        "Generated compact summary.",
+    )
+    assert loaded.state[SESSION_MEMORY_STATE_KEY]["content"] == "Recent memory."
+
+
+def test_runtime_pressure_recovery_brief_contribution_counts_events() -> None:
+    loaded = _loaded_session_with_evidence(
+        [
+            SessionEvidence(
+                kind="runtime_event",
+                summary="micro",
+                status="completed",
+                created_at="2026-04-15T00:00:00Z",
+                metadata={"event_kind": "microcompact"},
+            ),
+            SessionEvidence(
+                kind="runtime_event",
+                summary="auto",
+                status="completed",
+                created_at="2026-04-15T00:00:01Z",
+                metadata={"event_kind": "auto_compact"},
+            ),
+            SessionEvidence(
+                kind="runtime_event",
+                summary="auto-2",
+                status="completed",
+                created_at="2026-04-15T00:00:02Z",
+                metadata={"event_kind": "auto_compact"},
+            ),
+        ]
+    )
+
+    section = runtime_pressure_recovery_brief_contribution().render(loaded)
+
+    assert section == RecoveryBriefSection(
+        title="Runtime pressure:",
+        lines=("- microcompact: 1", "- auto_compact: 2"),
+    )
+
+
+def test_subagent_activity_recovery_brief_contribution_lists_recent_notifications() -> None:
+    loaded = _loaded_session_with_evidence(
+        [
+            SessionEvidence(
+                kind="subagent_notification",
+                summary="Old background subagent completed.",
+                status="completed",
+                created_at="2026-04-15T00:00:00Z",
+            ),
+            SessionEvidence(
+                kind="runtime_event",
+                summary="Unrelated runtime event.",
+                status="completed",
+                created_at="2026-04-15T00:00:01Z",
+            ),
+            SessionEvidence(
+                kind="subagent_notification",
+                summary="Background fork completed.",
+                status="completed",
+                created_at="2026-04-15T00:00:02Z",
+            ),
+            SessionEvidence(
+                kind="subagent_notification",
+                summary="Background subagent failed.",
+                status="failed",
+                created_at="2026-04-15T00:00:03Z",
+            ),
+            SessionEvidence(
+                kind="subagent_notification",
+                summary="Background fork cancelled.",
+                status="cancelled",
+                created_at="2026-04-15T00:00:04Z",
+            ),
+        ]
+    )
+
+    section = subagent_activity_recovery_brief_contribution().render(loaded)
+
+    assert section == RecoveryBriefSection(
+        title="Subagent activity:",
+        lines=(
+            "- [completed] Background fork completed.",
+            "- [failed] Background subagent failed.",
+            "- [cancelled] Background fork cancelled.",
+        ),
+    )
diff --git a/coding-deepgent/tests/sessions/test_session_memory_middleware.py b/coding-deepgent/tests/sessions/test_session_memory_middleware.py
new file mode 100644
index 000000000..4d2946af9
--- /dev/null
+++ b/coding-deepgent/tests/sessions/test_session_memory_middleware.py
@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+from typing import Any, cast
+
+from langchain.agents.middleware import ModelRequest
+from langchain.messages import HumanMessage, SystemMessage
+from langchain_core.language_models.fake_chat_models import FakeMessagesListChatModel
+from pydantic import PrivateAttr
+
+from coding_deepgent.sessions.session_memory import SESSION_MEMORY_STATE_KEY
+from coding_deepgent.sessions.session_memory_middleware import (
+    SessionMemoryContextMiddleware,
+)
+
+
+class RecordingFakeModel(FakeMessagesListChatModel):
+    _bound_tool_names: list[str] = PrivateAttr(default_factory=list)
+
+    def bind_tools(self, tools, *, tool_choice=None, **kwargs):
+        del tools, tool_choice, kwargs
+        return self
+
+
+def test_session_memory_context_middleware_injects_current_session_memory() -> None:
+    captured: dict[str, object] = {}
+
+    def handler(request: ModelRequest):
+        captured["system_message"] = request.system_message
+        return SimpleNamespace(result="ok")
+
+    middleware = SessionMemoryContextMiddleware()
+    request = ModelRequest(
+        model=RecordingFakeModel(responses=[]),
+        messages=[HumanMessage(content="continue")],
+        system_message=SystemMessage(content="Base"),
+        tool_choice=None,
+        tools=[],
+        response_format=None,
+        state=cast(
+            Any,
+            {
+            "messages": [],
+            SESSION_MEMORY_STATE_KEY: {
+                "content": "Current repo focus is deterministic assist.",
+                "source": "manual",
+                "message_count": 1,
+                "updated_at": "2026-04-18T00:00:00Z",
+            },
+            },
+        ),
+        runtime=SimpleNamespace(store=None),  # 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 "Current-session memory:" in text
+    assert "Current repo focus is deterministic assist." in text
+
+
+def test_session_memory_context_middleware_marks_stale_when_token_pressure_exceeds_threshold() -> None:
+    captured: dict[str, object] = {}
+
+    def handler(request: ModelRequest):
+        captured["system_message"] = request.system_message
+        return SimpleNamespace(result="ok")
+
+    middleware = SessionMemoryContextMiddleware()
+    request = ModelRequest(
+        model=RecordingFakeModel(responses=[]),
+        messages=[HumanMessage(content="x" * 24000)],
+        system_message=SystemMessage(content="Base"),
+        tool_choice=None,
+        tools=[],
+        response_format=None,
+        state=cast(
+            Any,
+            {
+                "messages": [],
+                SESSION_MEMORY_STATE_KEY: {
+                    "content": "Current repo focus is deterministic assist.",
+                    "source": "manual",
+                    "message_count": 1,
+                    "token_count": 10,
+                    "tool_call_count": 0,
+                    "updated_at": "2026-04-18T00:00:00Z",
+                },
+            },
+        ),
+        runtime=SimpleNamespace(store=None),  # 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 "Current-session memory:" in text
+    assert "[stale]" in text
diff --git a/coding-deepgent/tests/sessions/test_sessions.py b/coding-deepgent/tests/sessions/test_sessions.py
new file mode 100644
index 000000000..92a6a6621
--- /dev/null
+++ b/coding-deepgent/tests/sessions/test_sessions.py
@@ -0,0 +1,1095 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import pytest
+
+from coding_deepgent.sessions import (
+    COLLAPSE_EVENT_KIND,
+    COMPACT_EVENT_KIND,
+    EVIDENCE_RECORD_TYPE,
+    JsonlSessionStore,
+    SessionMessage,
+    SessionLoadError,
+    TRANSCRIPT_EVENT_RECORD_TYPE,
+    build_compression_view,
+    build_recovery_brief,
+    render_recovery_brief,
+    resume_session,
+    thread_config_for_session,
+)
+from coding_deepgent.sessions.records import message_id_for_index
+from coding_deepgent.sessions.session_memory import SESSION_MEMORY_STATE_KEY
+from coding_deepgent.memory import LONG_TERM_MEMORY_STATE_KEY
+from coding_deepgent.compact import COLLAPSE_BOUNDARY_PREFIX, COLLAPSE_SUMMARY_PREFIX
+
+
+def _history_summary(history: list[SessionMessage]) -> list[tuple[str, str, str]]:
+    return [(item.message_id, item.role, item.content) for item in history]
+
+
+def _projected_history(history: list[SessionMessage]) -> list[dict[str, Any]]:
+    return [item.as_conversation_dict() for item in history]
+
+
+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")
+    store.append_state_snapshot(context, state={"todos": [], "rounds_since_update": 0})
+    store.append_message(context, role="assistant", content="planned")
+    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]["message_id"] == message_id_for_index(0)
+    assert raw_records[2]["message_id"] == message_id_for_index(1)
+    assert _history_summary(loaded.history) == [
+        (message_id_for_index(0), "user", "plan this"),
+        (message_id_for_index(1), "assistant", "planned"),
+    ]
+    assert loaded.compacted_history == _projected_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_jsonl_session_roundtrip_preserves_session_memory_artifact(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")
+    store.append_state_snapshot(
+        context,
+        state={
+            "todos": [],
+            "rounds_since_update": 0,
+            SESSION_MEMORY_STATE_KEY: {
+                "content": "Current repo focus is deterministic assist.",
+                "source": "manual",
+                "message_count": 1,
+                "updated_at": "2026-04-15T00:00:00Z",
+            },
+        },
+    )
+
+    loaded = store.load_session(session_id=context.session_id, workdir=workdir)
+
+    assert loaded.state[SESSION_MEMORY_STATE_KEY] == {
+        "content": "Current repo focus is deterministic assist.",
+        "source": "manual",
+        "message_count": 1,
+        "updated_at": "2026-04-15T00:00:00Z",
+    }
+
+
+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 _history_summary(loaded.history) == [
+        (message_id_for_index(0), "user", "resume me")
+    ]
+    assert loaded.state == {
+        "todos": [
+            {"content": "Inspect", "status": "in_progress", "activeForm": "Inspecting"}
+        ],
+        "rounds_since_update": 3,
+    }
+
+
+def test_load_session_ignores_invalid_session_memory_artifact(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": [],
+            "rounds_since_update": 0,
+            SESSION_MEMORY_STATE_KEY: {
+                "content": "   ",
+                "source": "manual",
+                "message_count": 1,
+                "updated_at": "2026-04-15T00:00:00Z",
+            },
+        },
+    )
+
+    loaded = store.load_session(session_id=context.session_id, workdir=workdir)
+
+    assert loaded.state == {
+        "todos": [],
+        "rounds_since_update": 0,
+    }
+
+
+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_recovery_brief_renders_session_memory_status(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": [],
+            "rounds_since_update": 0,
+            SESSION_MEMORY_STATE_KEY: {
+                "content": "Current repo focus is deterministic assist.",
+                "source": "manual",
+                "message_count": 1,
+                "updated_at": "2026-04-15T00:00:00Z",
+            },
+        },
+    )
+
+    rendered = render_recovery_brief(
+        build_recovery_brief(
+            store.load_session(session_id=context.session_id, workdir=workdir)
+        )
+    )
+
+    assert "Current-session memory:" in rendered
+    assert "[current] Current repo focus is deterministic assist." in rendered
+
+
+def test_recovery_brief_marks_stale_session_memory_status(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_message(context, role="assistant", content="continued")
+    store.append_message(context, role="user", content="follow up")
+    store.append_message(context, role="assistant", content="more work")
+    store.append_message(context, role="user", content="final prompt")
+    store.append_state_snapshot(
+        context,
+        state={
+            "todos": [],
+            "rounds_since_update": 0,
+            SESSION_MEMORY_STATE_KEY: {
+                "content": "Current repo focus is deterministic assist.",
+                "source": "manual",
+                "message_count": 1,
+                "updated_at": "2026-04-15T00:00:00Z",
+            },
+        },
+    )
+
+    rendered = render_recovery_brief(
+        build_recovery_brief(
+            store.load_session(session_id=context.session_id, workdir=workdir)
+        )
+    )
+
+    assert "[stale] Current repo focus is deterministic assist." in rendered
+
+
+def test_recovery_brief_renders_long_term_memory_snapshot(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="resume")
+    store.append_state_snapshot(
+        context,
+        state={
+            "todos": [],
+            "rounds_since_update": 0,
+            LONG_TERM_MEMORY_STATE_KEY: {
+                "entries": [
+                    {
+                        "key": "fb-1",
+                        "type": "feedback",
+                        "summary": "Run lint before commit",
+                    },
+                    {
+                        "key": "proj-1",
+                        "type": "project",
+                        "summary": "Use JWT for auth",
+                    },
+                ],
+                "updated_at": "2026-04-18T00:00:00Z",
+            },
+        },
+    )
+
+    rendered = render_recovery_brief(
+        build_recovery_brief(
+            store.load_session(session_id=context.session_id, workdir=workdir)
+        )
+    )
+
+    assert "Long-term memory:" in rendered
+    assert "[feedback] Run lint before commit (key=fb-1)" in rendered
+    assert "[project] Use JWT for auth (key=proj-1)" 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")
+    store.append_compact(
+        context,
+        trigger="manual",
+        summary="Older work was summarized.",
+        start_message_id=message_id_for_index(0),
+        end_message_id=message_id_for_index(0),
+        covered_message_ids=[message_id_for_index(0)],
+        metadata={"source": "test"},
+    )
+    store.append_message(context, role="assistant", content="continued")
+
+    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"] == TRANSCRIPT_EVENT_RECORD_TYPE
+    assert raw_records[1]["event_kind"] == COMPACT_EVENT_KIND
+    assert _history_summary(loaded.history) == [
+        (message_id_for_index(0), "user", "start"),
+        (message_id_for_index(1), "assistant", "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].start_message_id == message_id_for_index(0)
+    assert loaded.compacts[0].end_message_id == message_id_for_index(0)
+    assert loaded.compacts[0].covered_message_ids == (message_id_for_index(0),)
+    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_collapse_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")
+    store.append_message(context, role="assistant", content="continued")
+    store.append_collapse(
+        context,
+        trigger="threshold_tokens",
+        summary="Older work was collapsed.",
+        start_message_id=message_id_for_index(0),
+        end_message_id=message_id_for_index(0),
+        covered_message_ids=[message_id_for_index(0)],
+        metadata={"source": "runtime_pressure"},
+    )
+
+    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"] == TRANSCRIPT_EVENT_RECORD_TYPE
+    assert raw_records[-1]["event_kind"] == COLLAPSE_EVENT_KIND
+    assert _history_summary(loaded.history) == [
+        (message_id_for_index(0), "user", "start"),
+        (message_id_for_index(1), "assistant", "continued"),
+    ]
+    assert loaded.summary.collapse_count == 1
+    assert loaded.collapses[0].trigger == "threshold_tokens"
+    assert loaded.collapses[0].summary == "Older work was collapsed."
+    assert loaded.collapses[0].start_message_id == message_id_for_index(0)
+    assert loaded.collapses[0].end_message_id == message_id_for_index(0)
+    assert loaded.collapses[0].covered_message_ids == (message_id_for_index(0),)
+    assert loaded.collapses[0].metadata == {"source": "runtime_pressure"}
+
+
+def test_sidechain_message_roundtrip_stays_out_of_parent_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="parent prompt")
+    store.append_sidechain_message(
+        context,
+        agent_type="general",
+        role="user",
+        content="Inspect the repository",
+        subagent_thread_id="session-1:general",
+        parent_message_id=message_id_for_index(0),
+        parent_thread_id="session-1",
+    )
+    store.append_sidechain_message(
+        context,
+        agent_type="general",
+        role="assistant",
+        content="Found the relevant files.",
+        subagent_thread_id="session-1:general",
+        parent_message_id=message_id_for_index(0),
+        parent_thread_id="session-1",
+    )
+
+    loaded = store.load_session(session_id=context.session_id, workdir=workdir)
+
+    assert _history_summary(loaded.history) == [
+        (message_id_for_index(0), "user", "parent prompt")
+    ]
+    assert loaded.compacted_history == _projected_history(loaded.history)
+    assert loaded.collapsed_history == _projected_history(loaded.history)
+    assert len(loaded.sidechain_messages) == 2
+    assert loaded.sidechain_messages[0].agent_type == "general"
+    assert loaded.sidechain_messages[0].role == "user"
+    assert loaded.sidechain_messages[0].content == "Inspect the repository"
+    assert loaded.sidechain_messages[0].parent_message_id == message_id_for_index(0)
+    assert loaded.sidechain_messages[0].parent_thread_id == "session-1"
+    assert loaded.sidechain_messages[0].subagent_thread_id == "session-1:general"
+    assert loaded.sidechain_messages[1].role == "assistant"
+    assert loaded.sidechain_messages[1].content == "Found the relevant files."
+
+
+def test_load_session_collapsed_history_uses_newest_non_overlapping_collapses(
+    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_message(context, role="user", content="third")
+    store.append_collapse(
+        context,
+        trigger="threshold_tokens",
+        summary="older collapse",
+        start_message_id=message_id_for_index(0),
+        end_message_id=message_id_for_index(0),
+        covered_message_ids=[message_id_for_index(0)],
+    )
+    store.append_collapse(
+        context,
+        trigger="threshold_tokens",
+        summary="newer collapse",
+        start_message_id=message_id_for_index(0),
+        end_message_id=message_id_for_index(1),
+        covered_message_ids=[message_id_for_index(0), message_id_for_index(1)],
+    )
+
+    loaded = store.load_session(session_id=context.session_id, workdir=workdir)
+
+    assert loaded.collapsed_history_source.mode == "collapse"
+    assert loaded.collapsed_history_source.collapse_index == 1
+    assert loaded.collapsed_history[0]["role"] == "system"
+    assert COLLAPSE_BOUNDARY_PREFIX in str(loaded.collapsed_history[0]["content"])
+    assert COLLAPSE_SUMMARY_PREFIX in str(loaded.collapsed_history[1]["content"])
+    assert "newer collapse" in str(loaded.collapsed_history[1]["content"])
+    assert "older collapse" not in str(loaded.collapsed_history[1]["content"])
+    assert loaded.collapsed_history[2] == {"role": "user", "content": "third"}
+
+
+def test_load_session_collapsed_history_falls_back_to_raw_on_invalid_refs(
+    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_collapse(
+        context,
+        trigger="threshold_tokens",
+        summary="invalid collapse",
+        start_message_id="msg-unknown",
+        end_message_id="msg-unknown",
+    )
+
+    loaded = store.load_session(session_id=context.session_id, workdir=workdir)
+
+    assert loaded.collapsed_history == _projected_history(loaded.history)
+    assert loaded.collapsed_history_source.mode == "raw"
+    assert loaded.collapsed_history_source.reason == "no_valid_collapse"
+
+
+def test_compression_view_exposes_raw_projection_and_timeline(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_message(context, role="user", content="third")
+    store.append_compact(
+        context,
+        trigger="manual",
+        summary="First message compacted.",
+        start_message_id=message_id_for_index(0),
+        end_message_id=message_id_for_index(0),
+        covered_message_ids=[message_id_for_index(0)],
+        metadata={"source": "manual"},
+    )
+    store.append_collapse(
+        context,
+        trigger="threshold_tokens",
+        summary="First two messages collapsed.",
+        start_message_id=message_id_for_index(0),
+        end_message_id=message_id_for_index(1),
+        covered_message_ids=[message_id_for_index(0), message_id_for_index(1)],
+        metadata={"source": "runtime_pressure"},
+    )
+    store.append_evidence(
+        context,
+        kind="runtime_event",
+        summary="Live microcompact cleared older tool results.",
+        status="completed",
+        metadata={
+            "event_kind": "microcompact",
+            "source": "runtime_pressure",
+            "trigger": "time_gap",
+            "affected_tool_call_ids": ["call-1"],
+        },
+    )
+
+    loaded = store.load_session(session_id=context.session_id, workdir=workdir)
+    view = build_compression_view(loaded)
+
+    assert view.projection_mode == "collapse"
+    assert [(message.message_id, message.model_visible) for message in view.raw_messages] == [
+        (message_id_for_index(0), False),
+        (message_id_for_index(1), False),
+        (message_id_for_index(2), True),
+    ]
+    assert view.raw_messages[0].hidden_by_event_ids == ("collapse-0",)
+    assert [message.source for message in view.model_projection] == [
+        "collapse_boundary",
+        "collapse_summary",
+        "raw",
+    ]
+    assert view.model_projection[0].covered_message_ids == (
+        message_id_for_index(0),
+        message_id_for_index(1),
+    )
+    timeline_by_type = {event.event_type: event for event in view.timeline}
+    assert timeline_by_type["compact"].affected_message_ids == (message_id_for_index(0),)
+    assert timeline_by_type["collapse"].affected_message_ids == (
+        message_id_for_index(0),
+        message_id_for_index(1),
+    )
+    assert timeline_by_type["microcompact"].affected_tool_call_ids == ("call-1",)
+    assert timeline_by_type["microcompact"].trigger == "time_gap"
+
+
+def test_compression_view_can_force_raw_projection(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_collapse(
+        context,
+        trigger="threshold_tokens",
+        summary="First collapsed.",
+        start_message_id=message_id_for_index(0),
+        end_message_id=message_id_for_index(0),
+        covered_message_ids=[message_id_for_index(0)],
+    )
+
+    loaded = store.load_session(session_id=context.session_id, workdir=workdir)
+    view = build_compression_view(loaded, projection_mode="raw")
+
+    assert view.projection_mode == "raw"
+    assert view.raw_messages[0].model_visible
+    assert view.model_projection[0].source == "raw"
+    assert view.model_projection[0].message_id == message_id_for_index(0)
+
+
+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": TRANSCRIPT_EVENT_RECORD_TYPE,
+                    "version": 1,
+                    "session_id": context.session_id,
+                    "timestamp": "2026-04-13T00:00:00Z",
+                    "event_kind": COMPACT_EVENT_KIND,
+                    "payload": {
+                        "trigger": "",
+                        "summary": "bad",
+                        "start_message_id": message_id_for_index(0),
+                        "end_message_id": message_id_for_index(0),
+                    },
+                }
+            )
+            + "\n"
+        )
+        handle.write(
+            json.dumps(
+                {
+                    "record_type": TRANSCRIPT_EVENT_RECORD_TYPE,
+                    "version": 1,
+                    "session_id": "other",
+                    "timestamp": "2026-04-13T00:00:01Z",
+                    "event_kind": COMPACT_EVENT_KIND,
+                    "payload": {
+                        "trigger": "manual",
+                        "summary": "foreign",
+                        "start_message_id": message_id_for_index(0),
+                        "end_message_id": message_id_for_index(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}",
+            start_message_id=message_id_for_index(0),
+            end_message_id=message_id_for_index(0),
+            covered_message_ids=[message_id_for_index(0)],
+        )
+
+    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",
+        start_message_id="msg-unknown",
+        end_message_id="msg-unknown",
+        covered_message_ids=["msg-unknown"],
+    )
+
+    loaded = store.load_session(session_id=context.session_id, workdir=workdir)
+
+    assert _history_summary(loaded.history) == [
+        (message_id_for_index(0), "user", "first"),
+        (message_id_for_index(1), "assistant", "second"),
+    ]
+    assert loaded.compacted_history == _projected_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")
+    store.append_message(context, role="assistant", content="second")
+    store.append_compact(
+        context,
+        trigger="manual",
+        summary="valid compact",
+        start_message_id=message_id_for_index(0),
+        end_message_id=message_id_for_index(0),
+        covered_message_ids=[message_id_for_index(0)],
+    )
+    store.append_compact(
+        context,
+        trigger="manual",
+        summary="invalid compact",
+        start_message_id="msg-unknown",
+        end_message_id="msg-unknown",
+        covered_message_ids=["msg-unknown"],
+    )
+
+    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")
+    store.append_message(context, role="assistant", content="second")
+    store.append_message(context, role="user", content="third")
+    store.append_compact(
+        context,
+        trigger="manual",
+        summary="older compact",
+        start_message_id=message_id_for_index(0),
+        end_message_id=message_id_for_index(0),
+        covered_message_ids=[message_id_for_index(0)],
+    )
+    store.append_compact(
+        context,
+        trigger="manual",
+        summary="newer compact",
+        start_message_id=message_id_for_index(0),
+        end_message_id=message_id_for_index(1),
+        covered_message_ids=[message_id_for_index(0), message_id_for_index(1)],
+    )
+
+    loaded = store.load_session(session_id=context.session_id, workdir=workdir)
+
+    assert _history_summary(loaded.history) == [
+        (message_id_for_index(0), "user", "first"),
+        (message_id_for_index(1), "assistant", "second"),
+        (message_id_for_index(2), "user", "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 _history_summary(loaded.history) == [
+        (message_id_for_index(0), "user", "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 _history_summary(loaded.history) == [
+        (message_id_for_index(0), "user", "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/structure/test_architecture_reshape.py b/coding-deepgent/tests/structure/test_architecture_reshape.py
new file mode 100644
index 000000000..44ad8d0db
--- /dev/null
+++ b/coding-deepgent/tests/structure/test_architecture_reshape.py
@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+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/structure/test_contract.py b/coding-deepgent/tests/structure/test_contract.py
new file mode 100644
index 000000000..17a3abb36
--- /dev/null
+++ b/coding-deepgent/tests/structure/test_contract.py
@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import ast
+import json
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+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/structure/test_structure.py b/coding-deepgent/tests/structure/test_structure.py
new file mode 100644
index 000000000..52ea6cc42
--- /dev/null
+++ b/coding-deepgent/tests/structure/test_structure.py
@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+import ast
+import json
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+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
+
+
+def test_runtime_domains_do_not_import_frontend_adapters() -> None:
+    forbidden_prefixes = (
+        "coding_deepgent.frontend.adapters",
+        "coding_deepgent.frontend.bridge",
+    )
+    allowed_roots = {
+        PACKAGE_ROOT / "frontend",
+        PACKAGE_ROOT / "cli.py",
+    }
+    for path in _python_files():
+        if any(path == root or root in path.parents for root in allowed_roots):
+            continue
+        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:
+                    assert not alias.name.startswith(forbidden_prefixes), path
+            if isinstance(node, ast.ImportFrom):
+                module = node.module or ""
+                assert not module.startswith(forbidden_prefixes), path
diff --git a/coding-deepgent/tests/subagents/test_subagents.py b/coding-deepgent/tests/subagents/test_subagents.py
new file mode 100644
index 000000000..759004972
--- /dev/null
+++ b/coding-deepgent/tests/subagents/test_subagents.py
@@ -0,0 +1,2104 @@
+from __future__ import annotations
+
+import json
+import threading
+import time
+from dataclasses import replace
+from pathlib import Path
+from typing import Any, cast
+from types import SimpleNamespace
+
+import pytest
+from langchain.messages import AIMessage, HumanMessage, ToolMessage
+from langgraph.store.memory import InMemoryStore
+from pydantic import ValidationError
+
+from coding_deepgent.hooks import LocalHookRegistry
+from coding_deepgent.memory.archive import InMemoryArchiveStore
+from coding_deepgent.memory.backend import SqlAlchemyMemoryRepository, create_memory_engine, migrate_memory_schema
+from coding_deepgent.memory.queue import InMemoryQueue
+from coding_deepgent.memory.service import MemoryService
+import coding_deepgent.runtime.agent_factory as runtime_agent_factory
+from coding_deepgent.runtime import InMemoryEventSink, RuntimeContext
+from coding_deepgent.sessions import JsonlSessionStore, build_recovery_brief, render_recovery_brief
+from coding_deepgent.sessions.records import message_id_for_index
+from coding_deepgent.subagents import tools as subagent_tools
+from coding_deepgent.subagents import (
+    BackgroundSubagentRun,
+    BUILTIN_AGENT_DEFINITIONS,
+    DEFAULT_CHILD_TOOLS,
+    FORK_PLACEHOLDER_LAYOUT_VERSION,
+    FORK_RECURSION_GUARD_MARKER,
+    FORBIDDEN_CHILD_TOOLS,
+    ForkResultEnvelope,
+    EXPLORE_CHILD_TOOLS,
+    PLAN_CHILD_TOOLS,
+    ResumeForkInput,
+    ResumeSubagentInput,
+    RunForkInput,
+    RunSubagentInput,
+    SubagentResultEnvelope,
+    VerifierSubagentResult,
+    agent_definition,
+    child_capability_registry,
+    child_tool_allowlist,
+    resume_fork,
+    resolve_agent_definition,
+    resume_fork_task,
+    resume_subagent,
+    resume_subagent_task,
+    run_subagent_background,
+    run_fork,
+    run_fork_task,
+    run_subagent,
+    run_subagent_task,
+    subagent_list,
+    subagent_send_input,
+    subagent_stop,
+    subagent_status,
+)
+from coding_deepgent.tasks import create_plan, create_task
+from coding_deepgent.tool_system import ToolPolicy, build_default_registry
+
+
+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 _memory_service(tmp_path: Path) -> MemoryService:
+    engine = create_memory_engine(f"sqlite+pysqlite:///{tmp_path / 'memory.db'}")
+    migrate_memory_schema(engine)
+    return MemoryService(
+        repository=SqlAlchemyMemoryRepository(engine),
+        queue=InMemoryQueue(),
+        archive_store=InMemoryArchiveStore(),
+    )
+
+
+def patch_runtime_agent_factory(monkeypatch: pytest.MonkeyPatch, factory) -> None:
+    def fake_create_runtime_agent(request, *, create_agent_factory=None):
+        del create_agent_factory
+        return factory(
+            model=request.model,
+            tools=list(request.tools),
+            system_prompt=request.system_prompt,
+            middleware=list(request.middleware),
+            context_schema=request.context_schema,
+            state_schema=request.state_schema,
+            checkpointer=request.checkpointer,
+            store=request.store,
+            name=request.name,
+            role=request.role,
+        )
+
+    monkeypatch.setattr(
+        runtime_agent_factory,
+        "create_runtime_agent",
+        fake_create_runtime_agent,
+    )
+
+
+def write_local_subagents(
+    workdir: Path, payload: dict[str, object]
+) -> Path:
+    root = workdir / ".coding-deepgent"
+    root.mkdir(parents=True, exist_ok=True)
+    path = root / "SUBAGENTS.json"
+    path.write_text(json.dumps(payload), encoding="utf-8")
+    return path
+
+
+def write_plugin(tmp_path: Path, name: str, payload: dict[str, object]) -> Path:
+    plugin_dir = tmp_path / "plugins" / name
+    plugin_dir.mkdir(parents=True, exist_ok=True)
+    path = plugin_dir / "plugin.json"
+    path.write_text(json.dumps(payload), encoding="utf-8")
+    return path
+
+
+def write_plugin_agents(tmp_path: Path, name: str, payload: dict[str, object]) -> Path:
+    plugin_dir = tmp_path / "plugins" / name
+    plugin_dir.mkdir(parents=True, exist_ok=True)
+    path = plugin_dir / "subagents.json"
+    path.write_text(json.dumps(payload), encoding="utf-8")
+    return path
+
+
+def runtime_with_fork_context_and_store(store: InMemoryStore) -> SimpleNamespace:
+    registry = build_default_registry()
+    projection = registry.project("main")
+    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(),
+            rendered_system_prompt="Main system prompt",
+            visible_tool_projection=projection,
+            tool_policy=ToolPolicy(registry=registry),
+        ),
+        config={"configurable": {"thread_id": "session-1"}},
+        state={"messages": [HumanMessage(content="Parent context")]},
+    )
+
+
+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
+    assert child_tool_allowlist("explore") == EXPLORE_CHILD_TOOLS
+    assert child_tool_allowlist("plan") == PLAN_CHILD_TOOLS
+    assert set(FORBIDDEN_CHILD_TOOLS).isdisjoint(child_tool_allowlist("verifier"))
+    assert agent_definition("general").max_turns == 25
+    assert agent_definition("verifier").max_turns == 5
+    assert set(BUILTIN_AGENT_DEFINITIONS) == {
+        "general",
+        "verifier",
+        "explore",
+        "plan",
+    }
+    child_registry = child_capability_registry()
+    assert child_registry.child_names() == list(DEFAULT_CHILD_TOOLS)
+    assert child_registry.tools_for_names(child_tool_allowlist("general")) == [
+        child_registry.require(name).tool for name in DEFAULT_CHILD_TOOLS
+    ]
+
+
+def test_run_subagent_task_passes_effective_max_turns_via_recursion_limit(
+    monkeypatch,
+) -> None:
+    runtime = runtime_with_context_and_store(InMemoryStore())
+    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": "planned"}]}
+
+    patch_runtime_agent_factory(monkeypatch, lambda **_kwargs: FakeChildAgent())
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+
+    run_subagent_task(
+        task="Plan the work",
+        runtime=cast(Any, runtime),
+        agent_type="plan",
+        max_turns=50,
+    )
+
+    assert captured["invoke_kwargs"]["config"]["configurable"]["thread_id"] == "session-1:plan"
+    assert captured["invoke_kwargs"]["config"]["recursion_limit"] == 31
+
+
+def test_run_subagent_task_routes_custom_model_profile(monkeypatch, tmp_path: Path) -> None:
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+    write_local_subagents(
+        workdir,
+        {
+            "agents": [
+                {
+                    "agent_type": "docs_review",
+                    "description": "Review docs",
+                    "when_to_use": "Use for repository documentation review.",
+                    "instructions": "Review the docs and summarize issues.",
+                    "tool_allowlist": ["read_file", "glob"],
+                    "disallowed_tools": ["write_file"],
+                    "max_turns": 7,
+                    "model_profile": "gpt-test-profile",
+                }
+            ]
+        },
+    )
+    runtime = runtime_with_context_and_store(InMemoryStore())
+    runtime.context = replace(runtime.context, workdir=workdir)
+    captured: dict[str, Any] = {}
+
+    patch_runtime_agent_factory(
+        monkeypatch,
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [{"role": "assistant", "content": "reviewed"}]
+            }
+        ),
+    )
+
+    def fake_build_openai_model(**kwargs: Any) -> object:
+        captured["model_kwargs"] = kwargs
+        return object()
+
+    monkeypatch.setattr(subagent_tools, "build_openai_model", fake_build_openai_model)
+
+    result = run_subagent_task(
+        task="Review docs",
+        runtime=cast(Any, runtime),
+        agent_type="docs_review",
+    )
+
+    assert result.agent_type == "docs_review"
+    assert captured["model_kwargs"]["model_name"] == "gpt-test-profile"
+
+
+def test_resolve_agent_definition_loads_repo_local_custom_agents(tmp_path: Path) -> None:
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+    write_local_subagents(
+        workdir,
+        {
+            "agents": [
+                {
+                    "agent_type": "api_mapper",
+                    "description": "Map API surfaces",
+                    "when_to_use": "Use for API surface comparison.",
+                    "instructions": "Map API surfaces and report the differences.",
+                    "tool_allowlist": ["read_file", "glob", "grep"],
+                    "disallowed_tools": ["write_file", "bash"],
+                    "max_turns": 6,
+                }
+            ]
+        },
+    )
+    runtime = runtime_with_context_and_store(InMemoryStore())
+    runtime.context = replace(runtime.context, workdir=workdir)
+
+    definition = resolve_agent_definition("api_mapper", runtime=cast(Any, runtime))
+
+    assert definition.agent_type == "api_mapper"
+    assert definition.instructions == "Map API surfaces and report the differences."
+    assert definition.tool_allowlist == ("read_file", "glob", "grep")
+
+
+def test_run_subagent_executes_repo_local_custom_agent(monkeypatch, tmp_path: Path) -> None:
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+    write_local_subagents(
+        workdir,
+        {
+            "agents": [
+                {
+                    "agent_type": "docs_review",
+                    "description": "Review docs",
+                    "when_to_use": "Use for documentation review.",
+                    "instructions": "Review documentation files and summarize concrete issues.",
+                    "tool_allowlist": ["read_file", "glob"],
+                    "disallowed_tools": ["write_file"],
+                    "max_turns": 7,
+                }
+            ]
+        },
+    )
+    runtime = runtime_with_context_and_store(InMemoryStore())
+    runtime.context = replace(runtime.context, workdir=workdir)
+    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": "docs reviewed"}]}
+
+    def fake_create_agent(**kwargs: Any) -> FakeChildAgent:
+        captured["agent_kwargs"] = kwargs
+        return FakeChildAgent()
+
+    patch_runtime_agent_factory(monkeypatch, fake_create_agent)
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+
+    result = run_subagent_task(
+        task="Review docs",
+        runtime=cast(Any, runtime),
+        agent_type="docs_review",
+    )
+
+    assert result.content == "docs reviewed"
+    assert [tool.name for tool in captured["agent_kwargs"]["tools"]] == ["read_file", "glob"]
+    assert "Review documentation files and summarize concrete issues." in captured["agent_kwargs"]["system_prompt"]
+
+
+def test_resolve_agent_definition_loads_plugin_provided_agents(tmp_path: Path) -> None:
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+    write_plugin(
+        workdir,
+        "demo",
+        {
+            "name": "demo",
+            "description": "Demo plugin",
+            "version": "1.0.0",
+            "skills": [],
+            "tools": [],
+            "resources": [],
+            "agents": ["demo:docs_review"],
+        },
+    )
+    write_plugin_agents(
+        workdir,
+        "demo",
+        {
+            "agents": [
+                {
+                    "agent_type": "demo:docs_review",
+                    "description": "Plugin docs review",
+                    "when_to_use": "Use for plugin-provided docs review.",
+                    "instructions": "Review docs from plugin agent.",
+                    "tool_allowlist": ["read_file", "glob"],
+                    "disallowed_tools": ["write_file"],
+                    "max_turns": 6,
+                }
+            ]
+        },
+    )
+    runtime = runtime_with_context_and_store(InMemoryStore())
+    runtime.context = replace(
+        runtime.context,
+        workdir=workdir,
+        plugin_dir=workdir / "plugins",
+    )
+
+    definition = resolve_agent_definition("demo:docs_review", runtime=cast(Any, runtime))
+
+    assert definition.agent_type == "demo:docs_review"
+    assert definition.tool_allowlist == ("read_file", "glob")
+
+
+def test_run_subagent_background_and_status(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,
+    )
+    patch_runtime_agent_factory(
+        monkeypatch,
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [{"role": "assistant", "content": "background result"}]
+            }
+        ),
+    )
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+
+    started = BackgroundSubagentRun.model_validate_json(
+        cast(Any, run_subagent_background).func(
+            "Inspect in background",
+            runtime,
+            agent_type="general",
+        )
+    )
+
+    for _ in range(20):
+        current = BackgroundSubagentRun.model_validate_json(
+            cast(Any, subagent_status).func(started.run_id, runtime)
+        )
+        if current.status == "completed":
+            break
+        time.sleep(0.05)
+    else:
+        raise AssertionError("background run did not complete")
+
+    assert current.latest_result == "background result"
+    assert current.total_invocations == 1
+    assert current.runtime_snapshot is not None
+    assert current.runtime_snapshot.parent_thread_id == "session-1"
+    assert current.runtime_snapshot.workdir == str(workdir)
+    assert current.notified is True
+    loaded = session_store.load_session(session_id="session-1", workdir=workdir)
+    assert loaded.evidence[-1].kind == "subagent_notification"
+
+
+def test_subagent_list_reports_active_and_terminal_background_runs(
+    monkeypatch,
+    tmp_path: Path,
+) -> None:
+    task_store = InMemoryStore()
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+    runtime = runtime_with_recorded_session(
+        task_store,
+        session_store=JsonlSessionStore(tmp_path / "sessions"),
+        workdir=workdir,
+    )
+    release = threading.Event()
+
+    def slow_agent(**_kwargs):
+        def invoke(_payload, **_invoke_kwargs):
+            release.wait(timeout=2)
+            return {"messages": [{"role": "assistant", "content": "background result"}]}
+
+        return SimpleNamespace(invoke=invoke)
+
+    patch_runtime_agent_factory(monkeypatch, slow_agent)
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+
+    started = BackgroundSubagentRun.model_validate_json(
+        cast(Any, run_subagent_background).func(
+            "Inspect in background",
+            runtime,
+            agent_type="general",
+        )
+    )
+
+    active = json.loads(cast(Any, subagent_list).func(runtime))
+    assert [run["run_id"] for run in active["runs"]] == [started.run_id]
+
+    release.set()
+    for _ in range(20):
+        current = BackgroundSubagentRun.model_validate_json(
+            cast(Any, subagent_status).func(started.run_id, runtime)
+        )
+        if current.status == "completed":
+            break
+        time.sleep(0.05)
+    else:
+        raise AssertionError("background run did not complete")
+
+    active_after_completion = json.loads(cast(Any, subagent_list).func(runtime))
+    assert active_after_completion["runs"] == []
+
+    all_runs = json.loads(cast(Any, subagent_list).func(runtime, include_terminal=True))
+    assert [run["run_id"] for run in all_runs["runs"]] == [started.run_id]
+
+
+def test_run_fork_background_and_status(monkeypatch, tmp_path: Path) -> None:
+    task_store = InMemoryStore()
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+    session_store = JsonlSessionStore(tmp_path / "sessions")
+    registry = build_default_registry()
+    runtime = runtime_with_recorded_session(
+        task_store,
+        session_store=session_store,
+        workdir=workdir,
+    )
+    runtime.context = replace(
+        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=runtime.context.session_context,
+            rendered_system_prompt="Main system prompt",
+            visible_tool_projection=registry.project("main"),
+            tool_policy=ToolPolicy(registry=registry),
+        ),
+        plugin_dir=workdir / "plugins",
+    )
+    runtime.state = {"messages": [HumanMessage(content="Parent context")]}
+    patch_runtime_agent_factory(
+        monkeypatch,
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [{"role": "assistant", "content": "background fork result"}]
+            }
+        ),
+    )
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+
+    started = BackgroundSubagentRun.model_validate_json(
+        cast(Any, run_fork).func(
+            "Explore another branch",
+            runtime,
+            background=True,
+        )
+    )
+
+    for _ in range(20):
+        current = BackgroundSubagentRun.model_validate_json(
+            cast(Any, subagent_status).func(started.run_id, runtime)
+        )
+        if current.status == "completed":
+            break
+        time.sleep(0.05)
+    else:
+        raise AssertionError("background fork did not complete")
+
+    assert current.mode == "background_fork"
+    assert current.agent_type == "fork"
+    assert current.latest_result == "background fork result"
+    assert current.summary_text == "background fork result"
+    assert current.child_thread_id.startswith("session-1:fork:")
+    assert current.rendered_prompt_fingerprint is not None
+    assert current.tool_pool_fingerprint is not None
+    assert current.runtime_snapshot is not None
+    assert current.runtime_snapshot.rendered_prompt_fingerprint is not None
+    assert current.runtime_snapshot.tool_pool_fingerprint is not None
+    assert current.placeholder_layout_version == FORK_PLACEHOLDER_LAYOUT_VERSION
+
+
+def test_background_subagent_send_input_reactivates_finished_run(
+    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,
+    )
+    responses = iter(["first background result", "second background result"])
+
+    patch_runtime_agent_factory(
+        monkeypatch,
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [{"role": "assistant", "content": next(responses)}]
+            }
+        ),
+    )
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+
+    started = BackgroundSubagentRun.model_validate_json(
+        cast(Any, run_subagent_background).func(
+            "Inspect in background",
+            runtime,
+            agent_type="general",
+        )
+    )
+
+    for _ in range(20):
+        current = BackgroundSubagentRun.model_validate_json(
+            cast(Any, subagent_status).func(started.run_id, runtime)
+        )
+        if current.status == "completed":
+            break
+        time.sleep(0.05)
+    else:
+        raise AssertionError("background run did not complete")
+
+    queued = BackgroundSubagentRun.model_validate_json(
+        cast(Any, subagent_send_input).func(
+            started.run_id,
+            "Continue the background inspection",
+            runtime,
+        )
+    )
+
+    assert queued.run_id == started.run_id
+
+    for _ in range(20):
+        current = BackgroundSubagentRun.model_validate_json(
+            cast(Any, subagent_status).func(started.run_id, runtime)
+        )
+        if current.total_invocations == 2 and current.status == "completed":
+            break
+        time.sleep(0.05)
+    else:
+        raise AssertionError("background continuation did not complete")
+
+    assert current.latest_result == "second background result"
+    assert current.total_invocations == 2
+
+
+def test_background_fork_send_input_reuses_same_thread_and_continuity(
+    monkeypatch, tmp_path: Path
+) -> None:
+    task_store = InMemoryStore()
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+    session_store = JsonlSessionStore(tmp_path / "sessions")
+    registry = build_default_registry()
+    runtime = runtime_with_recorded_session(
+        task_store,
+        session_store=session_store,
+        workdir=workdir,
+    )
+    runtime.context = replace(
+        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=runtime.context.session_context,
+            rendered_system_prompt="Main system prompt",
+            visible_tool_projection=registry.project("main"),
+            tool_policy=ToolPolicy(registry=registry),
+        ),
+        plugin_dir=workdir / "plugins",
+    )
+    runtime.state = {"messages": [HumanMessage(content="Parent context")]}
+    responses = iter(["fork first result", "fork second result"])
+    patch_runtime_agent_factory(
+        monkeypatch,
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [{"role": "assistant", "content": next(responses)}]
+            }
+        ),
+    )
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+
+    started = BackgroundSubagentRun.model_validate_json(
+        cast(Any, run_fork).func("Explore another branch", runtime, background=True)
+    )
+
+    for _ in range(20):
+        current = BackgroundSubagentRun.model_validate_json(
+            cast(Any, subagent_status).func(started.run_id, runtime)
+        )
+        if current.status == "completed":
+            break
+        time.sleep(0.05)
+    else:
+        raise AssertionError("background fork did not complete")
+
+    first_thread_id = current.child_thread_id
+    first_fingerprint = current.rendered_prompt_fingerprint
+    first_tool_pool = current.tool_pool_fingerprint
+
+    cast(Any, subagent_send_input).func(
+        started.run_id,
+        "Continue the fork",
+        runtime,
+    )
+
+    for _ in range(20):
+        current = BackgroundSubagentRun.model_validate_json(
+            cast(Any, subagent_status).func(started.run_id, runtime)
+        )
+        if current.total_invocations == 2 and current.status == "completed":
+            break
+        time.sleep(0.05)
+    else:
+        raise AssertionError("background fork continuation did not complete")
+
+    assert current.child_thread_id == first_thread_id
+    assert current.rendered_prompt_fingerprint == first_fingerprint
+    assert current.tool_pool_fingerprint == first_tool_pool
+    assert current.latest_result == "fork second result"
+
+
+def test_subagent_stop_cancels_running_background_run(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,
+    )
+    gate = __import__("threading").Event()
+
+    class BlockingAgent:
+        def invoke(self, payload: dict[str, Any], **kwargs: Any) -> dict[str, Any]:
+            gate.wait(timeout=1.0)
+            return {"messages": [{"role": "assistant", "content": "after stop"}]}
+
+    patch_runtime_agent_factory(monkeypatch, lambda **_kwargs: BlockingAgent())
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+
+    started = BackgroundSubagentRun.model_validate_json(
+        cast(Any, run_subagent_background).func(
+            "Inspect in background",
+            runtime,
+            agent_type="general",
+        )
+    )
+    time.sleep(0.05)
+
+    stopped = BackgroundSubagentRun.model_validate_json(
+        cast(Any, subagent_stop).func(started.run_id, runtime)
+    )
+    assert stopped.stop_requested is True
+    gate.set()
+
+    for _ in range(20):
+        current = BackgroundSubagentRun.model_validate_json(
+            cast(Any, subagent_status).func(started.run_id, runtime)
+        )
+        if current.status == "cancelled":
+            break
+        time.sleep(0.05)
+    else:
+        raise AssertionError("background run did not cancel")
+
+    assert current.notified is True
+    assert current.status == "cancelled"
+
+
+def test_subagent_stop_cancels_running_background_fork(monkeypatch, tmp_path: Path) -> None:
+    task_store = InMemoryStore()
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+    session_store = JsonlSessionStore(tmp_path / "sessions")
+    registry = build_default_registry()
+    runtime = runtime_with_recorded_session(
+        task_store,
+        session_store=session_store,
+        workdir=workdir,
+    )
+    runtime.context = replace(
+        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=runtime.context.session_context,
+            rendered_system_prompt="Main system prompt",
+            visible_tool_projection=registry.project("main"),
+            tool_policy=ToolPolicy(registry=registry),
+        ),
+        plugin_dir=workdir / "plugins",
+    )
+    runtime.state = {"messages": [HumanMessage(content="Parent context")]}
+    gate = __import__("threading").Event()
+
+    class BlockingForkAgent:
+        def invoke(self, payload: dict[str, Any], **kwargs: Any) -> dict[str, Any]:
+            gate.wait(timeout=1.0)
+            return {"messages": [{"role": "assistant", "content": "after stop"}]}
+
+    patch_runtime_agent_factory(monkeypatch, lambda **_kwargs: BlockingForkAgent())
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+
+    started = BackgroundSubagentRun.model_validate_json(
+        cast(Any, run_fork).func("Explore another branch", runtime, background=True)
+    )
+    time.sleep(0.05)
+
+    stopped = BackgroundSubagentRun.model_validate_json(
+        cast(Any, subagent_stop).func(started.run_id, runtime)
+    )
+    assert stopped.stop_requested is True
+    gate.set()
+
+    for _ in range(20):
+        current = BackgroundSubagentRun.model_validate_json(
+            cast(Any, subagent_status).func(started.run_id, runtime)
+        )
+        if current.status == "cancelled":
+            break
+        time.sleep(0.05)
+    else:
+        raise AssertionError("background fork did not cancel")
+
+    assert current.mode == "background_fork"
+    assert current.status == "cancelled"
+
+
+def test_run_fork_filters_incomplete_tool_calls_and_exposes_placeholder_messages(
+    monkeypatch,
+) -> None:
+    runtime = runtime_with_fork_context_and_store(InMemoryStore())
+    captured: dict[str, Any] = {}
+    runtime.state = {
+        "messages": [
+            HumanMessage(content="Parent context"),
+            AIMessage(
+                content=[{"type": "tool_use", "id": "call-1", "name": "read_file"}],
+                tool_calls=[{"id": "call-1", "name": "read_file", "args": {}}],
+            ),
+            AIMessage(
+                content=[{"type": "tool_use", "id": "call-2", "name": "glob"}],
+                tool_calls=[{"id": "call-2", "name": "glob", "args": {}}],
+            ),
+            ToolMessage(content="glob result", tool_call_id="call-2"),
+        ]
+    }
+
+    class FakeForkAgent:
+        def invoke(self, payload: dict[str, Any], **kwargs: Any) -> dict[str, Any]:
+            captured["payload"] = payload
+            return {"messages": [{"role": "assistant", "content": "fork result"}]}
+
+    patch_runtime_agent_factory(monkeypatch, lambda **_kwargs: FakeForkAgent())
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+
+    result = run_fork_task(
+        intent="Explore another branch",
+        runtime=cast(Any, runtime),
+        max_turns=99,
+    )
+
+    payload_messages = captured["payload"]["messages"]
+    assert len(payload_messages) == 4
+    assert result.placeholder_layout.placeholder_messages == ["<fork-tool-result:call-2>"]
+    assert result.total_tokens == result.input_tokens + result.output_tokens
+    assert result.child_thread_id.startswith("session-1:fork:")
+    assert result.placeholder_layout.version == FORK_PLACEHOLDER_LAYOUT_VERSION
+    assert result.parent_thread_id == "session-1"
+    assert result.rendered_prompt_fingerprint
+    assert result.tool_pool_identity.fingerprint
+    assert result.total_tool_use_count == 0
+    assert result.total_duration_ms >= 0
+    assert result.fork_run_id
+    assert result.child_thread_id != result.parent_thread_id
+    assert result.input_tokens > 0
+    assert result.output_tokens > 0
+    assert result.placeholder_layout.paired_tool_call_ids == ["call-2"]
+    assert result.placeholder_layout.placeholder_messages == ["<fork-tool-result:call-2>"]
+    assert result.placeholder_layout.replacement_state_hook
+    assert result.parent_thread_id == "session-1"
+    assert result.child_thread_id.startswith("session-1:fork:")
+    assert result.tool_pool_identity.fingerprint
+    assert payload_messages[1].tool_calls[0]["id"] == "call-2"
+    assert payload_messages[2].tool_call_id == "call-2"
+
+
+def test_resume_subagent_task_reuses_recorded_thread(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,
+    )
+    patch_runtime_agent_factory(
+        monkeypatch,
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [{"role": "assistant", "content": "first result"}]
+            }
+        ),
+    )
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+    cast(Any, run_subagent).func("Inspect the repository", runtime)
+
+    captured: dict[str, Any] = {}
+
+    class ResumeAgent:
+        def invoke(self, payload: dict[str, Any], **kwargs: Any) -> dict[str, Any]:
+            captured["payload"] = payload
+            captured["invoke_kwargs"] = kwargs
+            return {"messages": [{"role": "assistant", "content": "resumed result"}]}
+
+    patch_runtime_agent_factory(monkeypatch, lambda **_kwargs: ResumeAgent())
+
+    result = resume_subagent_task(
+        subagent_thread_id="session-1:general",
+        runtime=cast(Any, runtime),
+        follow_up="Continue the inspection",
+    )
+
+    assert result.content == "resumed result"
+    assert captured["invoke_kwargs"]["config"]["configurable"]["thread_id"] == "session-1:general"
+    assert captured["payload"]["messages"][-1].content == "Continue the inspection"
+
+
+def test_resume_fork_task_reuses_recorded_thread(monkeypatch, tmp_path: Path) -> None:
+    task_store = InMemoryStore()
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+    session_store = JsonlSessionStore(tmp_path / "sessions")
+    registry = build_default_registry()
+    runtime = runtime_with_recorded_session(
+        task_store,
+        session_store=session_store,
+        workdir=workdir,
+    )
+    runtime.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=runtime.context.session_context,
+        rendered_system_prompt="Main system prompt",
+        visible_tool_projection=registry.project("main"),
+        tool_policy=ToolPolicy(registry=registry),
+    )
+    runtime.state = {"messages": [HumanMessage(content="Parent context")]}
+    patch_runtime_agent_factory(
+        monkeypatch,
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [{"role": "assistant", "content": "fork result"}]
+            }
+        ),
+    )
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+
+    first_result = ForkResultEnvelope.model_validate_json(
+        cast(Any, run_fork).func("Explore another branch", runtime)
+    )
+
+    captured: dict[str, Any] = {}
+
+    class ResumeForkAgent:
+        def invoke(self, payload: dict[str, Any], **kwargs: Any) -> dict[str, Any]:
+            captured["payload"] = payload
+            captured["invoke_kwargs"] = kwargs
+            return {"messages": [{"role": "assistant", "content": "fork resumed"}]}
+
+    patch_runtime_agent_factory(monkeypatch, lambda **_kwargs: ResumeForkAgent())
+
+    result = resume_fork_task(
+        child_thread_id=first_result.child_thread_id,
+        runtime=cast(Any, runtime),
+        follow_up="Keep exploring",
+    )
+
+    assert result.content == "fork resumed"
+    assert captured["invoke_kwargs"]["config"]["configurable"]["thread_id"] == first_result.child_thread_id
+    assert captured["payload"]["messages"][-1].content == "Keep exploring"
+
+
+def test_resume_subagent_tool_returns_structured_result(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,
+    )
+    patch_runtime_agent_factory(
+        monkeypatch,
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [{"role": "assistant", "content": "first result"}]
+            }
+        ),
+    )
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+    cast(Any, run_subagent).func("Inspect the repository", runtime)
+
+    patch_runtime_agent_factory(
+        monkeypatch,
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [{"role": "assistant", "content": "resumed result"}]
+            }
+        ),
+    )
+
+    output = cast(Any, resume_subagent).func(
+        "session-1:general",
+        runtime,
+        "Continue the inspection",
+    )
+    result = SubagentResultEnvelope.model_validate_json(output)
+
+    assert result.agent_type == "general"
+    assert result.content == "resumed result"
+
+
+def test_resume_fork_tool_returns_structured_result(monkeypatch, tmp_path: Path) -> None:
+    task_store = InMemoryStore()
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+    session_store = JsonlSessionStore(tmp_path / "sessions")
+    registry = build_default_registry()
+    runtime = runtime_with_recorded_session(
+        task_store,
+        session_store=session_store,
+        workdir=workdir,
+    )
+    runtime.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=runtime.context.session_context,
+        rendered_system_prompt="Main system prompt",
+        visible_tool_projection=registry.project("main"),
+        tool_policy=ToolPolicy(registry=registry),
+    )
+    runtime.state = {"messages": [HumanMessage(content="Parent context")]}
+    patch_runtime_agent_factory(
+        monkeypatch,
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [{"role": "assistant", "content": "fork result"}]
+            }
+        ),
+    )
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+
+    first_result = ForkResultEnvelope.model_validate_json(
+        cast(Any, run_fork).func("Explore another branch", runtime)
+    )
+    patch_runtime_agent_factory(
+        monkeypatch,
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [{"role": "assistant", "content": "fork resumed"}]
+            }
+        ),
+    )
+
+    output = cast(Any, resume_fork).func(
+        first_result.child_thread_id,
+        runtime,
+        "Keep exploring",
+    )
+    result = ForkResultEnvelope.model_validate_json(output)
+
+    assert result.content == "fork resumed"
+    assert result.child_thread_id == first_result.child_thread_id
+
+
+def test_resume_fork_task_requires_matching_prompt_fingerprint(
+    monkeypatch, tmp_path: Path
+) -> None:
+    task_store = InMemoryStore()
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+    session_store = JsonlSessionStore(tmp_path / "sessions")
+    registry = build_default_registry()
+    runtime = runtime_with_recorded_session(
+        task_store,
+        session_store=session_store,
+        workdir=workdir,
+    )
+    runtime.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=runtime.context.session_context,
+        rendered_system_prompt="Main system prompt",
+        visible_tool_projection=registry.project("main"),
+        tool_policy=ToolPolicy(registry=registry),
+    )
+    runtime.state = {"messages": [HumanMessage(content="Parent context")]}
+    patch_runtime_agent_factory(
+        monkeypatch,
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [{"role": "assistant", "content": "fork result"}]
+            }
+        ),
+    )
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+
+    first_result = ForkResultEnvelope.model_validate_json(
+        cast(Any, run_fork).func("Explore another branch", runtime)
+    )
+    runtime.context = replace(runtime.context, rendered_system_prompt="Changed prompt")
+
+    with pytest.raises(RuntimeError, match="rendered system prompt fingerprint"):
+        resume_fork_task(
+            child_thread_id=first_result.child_thread_id,
+            runtime=cast(Any, runtime),
+        )
+
+
+def test_resume_subagent_task_requires_matching_workdir(
+    monkeypatch, tmp_path: Path
+) -> None:
+    task_store = InMemoryStore()
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+    other_workdir = tmp_path / "other"
+    other_workdir.mkdir()
+    session_store = JsonlSessionStore(tmp_path / "sessions")
+    runtime = runtime_with_recorded_session(
+        task_store,
+        session_store=session_store,
+        workdir=workdir,
+    )
+    patch_runtime_agent_factory(
+        monkeypatch,
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [{"role": "assistant", "content": "first result"}]
+            }
+        ),
+    )
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+    cast(Any, run_subagent).func("Inspect the repository", runtime)
+    runtime.context = replace(runtime.context, workdir=other_workdir)
+
+    with pytest.raises(RuntimeError, match="same recorded workdir"):
+        resume_subagent_task(
+            subagent_thread_id="session-1:general",
+            runtime=cast(Any, runtime),
+        )
+
+
+def test_resume_fork_task_requires_matching_workdir(
+    monkeypatch, tmp_path: Path
+) -> None:
+    task_store = InMemoryStore()
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+    other_workdir = tmp_path / "other"
+    other_workdir.mkdir()
+    session_store = JsonlSessionStore(tmp_path / "sessions")
+    registry = build_default_registry()
+    runtime = runtime_with_recorded_session(
+        task_store,
+        session_store=session_store,
+        workdir=workdir,
+    )
+    runtime.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=runtime.context.session_context,
+        rendered_system_prompt="Main system prompt",
+        visible_tool_projection=registry.project("main"),
+        tool_policy=ToolPolicy(registry=registry),
+    )
+    runtime.state = {"messages": [HumanMessage(content="Parent context")]}
+    patch_runtime_agent_factory(
+        monkeypatch,
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [{"role": "assistant", "content": "fork result"}]
+            }
+        ),
+    )
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+
+    first_result = ForkResultEnvelope.model_validate_json(
+        cast(Any, run_fork).func("Explore another branch", runtime)
+    )
+    runtime.context = replace(runtime.context, workdir=other_workdir)
+
+    with pytest.raises(RuntimeError, match="same recorded workdir"):
+        resume_fork_task(
+            child_thread_id=first_result.child_thread_id,
+            runtime=cast(Any, runtime),
+        )
+
+
+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()
+    schema = cast(Any, run_subagent.tool_call_schema).model_json_schema()
+    assert set(schema["properties"]) == {"task", "agent_type", "plan_id", "max_turns"}
+    assert {
+        "mailbox",
+        "message",
+        "team",
+        "worker",
+        "coordinator",
+        "scratchpad",
+        "send_message",
+    }.isdisjoint(schema["properties"])
+
+    with pytest.raises(ValidationError):
+        RunSubagentInput.model_validate(
+            {"task": "x", "background": True, "runtime": runtime}
+        )
+
+
+def test_resume_subagent_tool_schema_rejects_runtime_creep_fields() -> None:
+    runtime = SimpleNamespace()
+    schema = cast(Any, resume_subagent.tool_call_schema).model_json_schema()
+    assert set(schema["properties"]) == {"subagent_thread_id", "follow_up"}
+
+    with pytest.raises(ValidationError):
+        ResumeSubagentInput.model_validate(
+            {"subagent_thread_id": "session-1:general", "runtime": runtime, "extra": True}
+        )
+
+
+def test_run_subagent_task_general_executes_real_read_only_child_agent(
+    monkeypatch,
+) -> None:
+    runtime = runtime_with_context_and_store(InMemoryStore())
+    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": "general result"}]}
+
+    def fake_create_agent(**kwargs: Any) -> FakeChildAgent:
+        captured["agent_kwargs"] = kwargs
+        return FakeChildAgent()
+
+    patch_runtime_agent_factory(monkeypatch, fake_create_agent)
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+
+    result = run_subagent_task(
+        task="Inspect the repository",
+        runtime=cast(Any, runtime),
+        agent_type="general",
+    )
+
+    assert result.content == "general result"
+    assert result.agent_type == "general"
+    assert result.input_tokens > 0
+    assert result.output_tokens > 0
+    assert result.total_tokens == result.input_tokens + result.output_tokens
+    assert [tool.name for tool in captured["agent_kwargs"]["tools"]] == [
+        "read_file",
+        "glob",
+        "grep",
+        "task_get",
+        "task_list",
+        "plan_get",
+    ]
+    assert set(FORBIDDEN_CHILD_TOOLS).isdisjoint(
+        tool.name for tool in captured["agent_kwargs"]["tools"]
+    )
+    assert "read-only general-purpose" in captured["agent_kwargs"]["system_prompt"]
+    assert captured["agent_kwargs"]["name"] == "coding-deepgent-general"
+    assert captured["payload"] == {
+        "messages": [{"role": "user", "content": "Inspect the repository"}]
+    }
+    assert captured["invoke_kwargs"]["context"].entrypoint == "run_subagent:general"
+    assert (
+        captured["invoke_kwargs"]["config"]["configurable"]["thread_id"]
+        == "session-1:general"
+    )
+
+
+def test_run_subagent_task_general_enqueues_agent_private_memory(tmp_path: Path, monkeypatch) -> None:
+    runtime = runtime_with_context_and_store(InMemoryStore())
+    service = _memory_service(tmp_path)
+    runtime.context = replace(runtime.context, memory_service=service)
+    patch_runtime_agent_factory(
+        monkeypatch,
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [{"role": "assistant", "content": "general result"}]
+            }
+        ),
+    )
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+
+    run_subagent_task(
+        task="Inspect the repository",
+        runtime=cast(Any, runtime),
+        agent_type="general",
+    )
+
+    jobs = service.list_jobs(
+        project_scope=str(Path.cwd()),
+        agent_scope="coding-deepgent-general",
+    )
+    assert jobs
+    assert jobs[0].job_type == "extract_long_term_memory"
+
+
+def test_run_subagent_tool_returns_structured_general_result(monkeypatch) -> None:
+    runtime = runtime_with_context_and_store(InMemoryStore())
+    patch_runtime_agent_factory(
+        monkeypatch,
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [{"role": "assistant", "content": "general result"}]
+            }
+        ),
+    )
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+
+    output = cast(Any, run_subagent).func("Inspect the repository", runtime)
+    result = SubagentResultEnvelope.model_validate_json(output)
+
+    assert result.agent_type == "general"
+    assert result.content == "general result"
+    assert result.tool_allowlist == [
+        "read_file",
+        "glob",
+        "grep",
+        "task_get",
+        "task_list",
+        "plan_get",
+    ]
+    assert result.total_tokens == result.input_tokens + result.output_tokens
+
+
+def test_run_subagent_records_sidechain_messages_in_parent_session(
+    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,
+    )
+    patch_runtime_agent_factory(
+        monkeypatch,
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [{"role": "assistant", "content": "general result"}]
+            }
+        ),
+    )
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+
+    output = cast(Any, run_subagent).func("Inspect the repository", runtime)
+    result = SubagentResultEnvelope.model_validate_json(output)
+    loaded = session_store.load_session(session_id="session-1", workdir=workdir)
+
+    assert result.content == "general result"
+    assert [
+        (item.message_id, item.role, item.content) for item in loaded.history
+    ] == [(message_id_for_index(0), "user", "start")]
+    assert [(item.role, item.content) for item in loaded.sidechain_messages] == [
+        ("user", "Inspect the repository"),
+        ("assistant", "general result"),
+    ]
+    assert loaded.sidechain_messages[0].parent_message_id == message_id_for_index(0)
+    assert loaded.sidechain_messages[0].parent_thread_id == "session-1"
+    assert loaded.sidechain_messages[0].subagent_thread_id == "session-1:general"
+
+
+def test_subagent_result_falls_back_to_last_text_when_final_message_is_tool_only(
+    monkeypatch,
+) -> None:
+    runtime = runtime_with_context_and_store(InMemoryStore())
+    patch_runtime_agent_factory(
+        monkeypatch,
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [
+                    {"role": "assistant", "content": "fallback text"},
+                    {
+                        "role": "assistant",
+                        "content": [
+                            {
+                                "type": "tool_use",
+                                "id": "call-1",
+                                "name": "read_file",
+                            }
+                        ],
+                    },
+                ]
+            }
+        ),
+    )
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+
+    result = run_subagent_task(
+        task="Inspect the repository",
+        runtime=cast(Any, runtime),
+        agent_type="general",
+    )
+
+    assert result.content == "fallback text"
+
+
+def test_run_fork_tool_schema_rejects_runtime_creep_fields() -> None:
+    runtime = SimpleNamespace()
+    schema = cast(Any, run_fork.tool_call_schema).model_json_schema()
+    assert set(schema["properties"]) == {"intent", "background", "max_turns"}
+    assert {
+        "mailbox",
+        "message",
+        "team",
+        "worker",
+        "coordinator",
+        "scratchpad",
+        "send_message",
+    }.isdisjoint(schema["properties"])
+
+    with pytest.raises(ValidationError):
+        RunForkInput.model_validate(
+            {"intent": "branch", "runtime": runtime, "agent_type": "general"}
+        )
+
+
+def test_background_tools_do_not_claim_mailbox_or_team_runtime_schema() -> None:
+    forbidden = {
+        "mailbox",
+        "team",
+        "worker",
+        "coordinator",
+        "scratchpad",
+        "send_message",
+    }
+    background_schemas = [
+        cast(Any, run_subagent_background.tool_call_schema).model_json_schema(),
+        cast(Any, subagent_status.tool_call_schema).model_json_schema(),
+        cast(Any, subagent_send_input.tool_call_schema).model_json_schema(),
+        cast(Any, subagent_stop.tool_call_schema).model_json_schema(),
+    ]
+    for schema in background_schemas:
+        assert forbidden.isdisjoint(schema["properties"])
+
+
+def test_resume_fork_tool_schema_rejects_runtime_creep_fields() -> None:
+    runtime = SimpleNamespace()
+    schema = cast(Any, resume_fork.tool_call_schema).model_json_schema()
+    assert set(schema["properties"]) == {"child_thread_id", "follow_up"}
+
+    with pytest.raises(ValidationError):
+        ResumeForkInput.model_validate(
+            {"child_thread_id": "session-1:fork:run", "runtime": runtime, "extra": True}
+        )
+
+
+def test_run_fork_task_executes_same_config_sibling_branch(monkeypatch) -> None:
+    runtime = runtime_with_fork_context_and_store(InMemoryStore())
+    captured: dict[str, Any] = {}
+
+    class FakeForkAgent:
+        def invoke(self, payload: dict[str, Any], **kwargs: Any) -> dict[str, Any]:
+            captured["payload"] = payload
+            captured["invoke_kwargs"] = kwargs
+            return {"messages": [{"role": "assistant", "content": "fork result"}]}
+
+    def fake_create_agent(**kwargs: Any) -> FakeForkAgent:
+        captured["agent_kwargs"] = kwargs
+        return FakeForkAgent()
+
+    patch_runtime_agent_factory(monkeypatch, fake_create_agent)
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+
+    result = run_fork_task(
+        intent="Check an alternate implementation path",
+        runtime=cast(Any, runtime),
+    )
+
+    assert result.content == "fork result"
+    assert result.parent_thread_id == "session-1"
+    assert result.child_thread_id.startswith("session-1:fork:")
+    assert result.fork_run_id
+    assert result.rendered_prompt_fingerprint
+    assert result.tool_pool_identity.tools[0].name == "bash"
+    assert result.placeholder_layout.version == FORK_PLACEHOLDER_LAYOUT_VERSION
+    assert captured["agent_kwargs"]["system_prompt"] == "Main system prompt"
+    assert [tool.name for tool in captured["agent_kwargs"]["tools"]] == [
+        tool.name for tool in runtime.context.visible_tool_projection.tools()
+    ]
+    payload_messages = captured["payload"]["messages"]
+    assert isinstance(payload_messages[0], HumanMessage)
+    assert payload_messages[0].content == "Parent context"
+    assert isinstance(payload_messages[-1], HumanMessage)
+    assert FORK_RECURSION_GUARD_MARKER in payload_messages[-1].content
+    assert "Branch intent: Check an alternate implementation path" in payload_messages[-1].content
+    assert captured["invoke_kwargs"]["context"].entrypoint == "run_fork"
+    assert captured["invoke_kwargs"]["config"]["configurable"]["thread_id"].startswith(
+        "session-1:fork:"
+    )
+
+
+def test_run_fork_tool_returns_structured_result(monkeypatch) -> None:
+    runtime = runtime_with_fork_context_and_store(InMemoryStore())
+    patch_runtime_agent_factory(
+        monkeypatch,
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [{"role": "assistant", "content": "fork result"}]
+            }
+        ),
+    )
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+
+    output = cast(Any, run_fork).func("Explore another branch", runtime)
+    result = ForkResultEnvelope.model_validate_json(output)
+
+    assert result.mode == "fork"
+    assert result.content == "fork result"
+    assert result.parent_thread_id == "session-1"
+    assert result.child_thread_id.startswith("session-1:fork:")
+    assert result.tool_pool_identity.fingerprint
+    assert result.placeholder_layout.version == FORK_PLACEHOLDER_LAYOUT_VERSION
+    assert result.total_tokens == result.input_tokens + result.output_tokens
+
+
+def test_run_fork_records_sidechain_messages_with_contract_metadata(
+    monkeypatch, tmp_path: Path
+) -> None:
+    task_store = InMemoryStore()
+    workdir = tmp_path / "repo"
+    workdir.mkdir()
+    session_store = JsonlSessionStore(tmp_path / "sessions")
+    registry = build_default_registry()
+    runtime = runtime_with_recorded_session(
+        task_store,
+        session_store=session_store,
+        workdir=workdir,
+    )
+    runtime.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=runtime.context.session_context,
+        rendered_system_prompt="Main system prompt",
+        visible_tool_projection=registry.project("main"),
+        tool_policy=ToolPolicy(registry=registry),
+    )
+    runtime.state = {"messages": [HumanMessage(content="Parent context")]}
+    patch_runtime_agent_factory(
+        monkeypatch,
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [{"role": "assistant", "content": "fork result"}]
+            }
+        ),
+    )
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+
+    output = cast(Any, run_fork).func("Explore another branch", runtime)
+    result = ForkResultEnvelope.model_validate_json(output)
+    loaded = session_store.load_session(session_id="session-1", workdir=workdir)
+
+    assert [(item.role, item.content) for item in loaded.sidechain_messages[-2:]] == [
+        ("user", payload_messages := loaded.sidechain_messages[-2].content),
+        ("assistant", "fork result"),
+    ]
+    assert FORK_RECURSION_GUARD_MARKER in payload_messages
+    assert loaded.sidechain_messages[-2].agent_type == "fork"
+    assert loaded.sidechain_messages[-2].metadata is not None
+    assert loaded.sidechain_messages[-2].metadata["fork_run_id"] == result.fork_run_id
+    assert (
+        loaded.sidechain_messages[-2].metadata["placeholder_layout_version"]
+        == FORK_PLACEHOLDER_LAYOUT_VERSION
+    )
+    assert (
+        loaded.sidechain_messages[-2].metadata["tool_pool_fingerprint"]
+        == result.tool_pool_identity.fingerprint
+    )
+
+
+def test_run_fork_rejects_recursive_fork_marker(monkeypatch) -> None:
+    runtime = runtime_with_fork_context_and_store(InMemoryStore())
+    runtime.state = {
+        "messages": [HumanMessage(content=f"Parent\n{FORK_RECURSION_GUARD_MARKER}")]
+    }
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: object())
+
+    with pytest.raises(RuntimeError, match="recursion guard marker"):
+        run_fork_task(intent="nested fork", runtime=cast(Any, runtime))
+
+
+def test_run_subagent_pressure_guard_blocks_high_pressure() -> None:
+    runtime = SimpleNamespace(
+        store=InMemoryStore(),
+        state={"messages": [HumanMessage(content="x" * 5000)]},
+        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(),
+            model_context_window_tokens=1000,
+            subagent_spawn_guard_ratio=0.5,
+        ),
+    )
+
+    result = run_subagent_task(
+        task="inspect",
+        runtime=cast(Any, runtime),
+    )
+
+    assert result.content.startswith("Subagent spawn blocked")
+    assert runtime.context.event_sink.snapshot()[0].kind == "subagent_spawn_guard"
+
+
+def test_run_subagent_pressure_guard_records_evidence(tmp_path: Path) -> None:
+    session_store = JsonlSessionStore(tmp_path / "sessions-store")
+    runtime = runtime_with_recorded_session(
+        InMemoryStore(),
+        session_store=session_store,
+        workdir=tmp_path,
+    )
+    runtime.state = {"messages": [HumanMessage(content="x" * 5000)]}
+    runtime.context = RuntimeContext(
+        session_id=runtime.context.session_id,
+        workdir=runtime.context.workdir,
+        trusted_workdirs=runtime.context.trusted_workdirs,
+        entrypoint=runtime.context.entrypoint,
+        agent_name=runtime.context.agent_name,
+        skill_dir=runtime.context.skill_dir,
+        event_sink=runtime.context.event_sink,
+        hook_registry=runtime.context.hook_registry,
+        session_context=runtime.context.session_context,
+        model_context_window_tokens=1000,
+        subagent_spawn_guard_ratio=0.5,
+    )
+
+    output = cast(Any, run_subagent).func("inspect", runtime)
+    result = SubagentResultEnvelope.model_validate_json(output)
+    loaded = session_store.load_session(session_id="session-1", workdir=tmp_path)
+
+    assert result.content.startswith("Subagent spawn blocked")
+    assert loaded.evidence[0].kind == "runtime_event"
+    assert loaded.evidence[0].metadata is not None
+    assert loaded.evidence[0].metadata["event_kind"] == "subagent_spawn_guard"
+
+
+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()
+
+    patch_runtime_agent_factory(monkeypatch, fake_create_agent)
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: 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 result.input_tokens > 0
+    assert result.output_tokens > 0
+    assert result.total_tokens == result.input_tokens + result.output_tokens
+    assert result.total_tool_use_count == 0
+    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],
+    )
+
+    patch_runtime_agent_factory(
+        monkeypatch,
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [{"role": "assistant", "content": "VERDICT: PASS"}]
+            }
+        ),
+    )
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: 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"
+    assert result.input_tokens > 0
+    assert result.output_tokens > 0
+    assert result.total_tokens == result.input_tokens + result.output_tokens
+    assert result.total_tool_use_count == 0
+
+
+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],
+    )
+
+    patch_runtime_agent_factory(
+        monkeypatch,
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [
+                    {
+                        "role": "assistant",
+                        "content": "Checked targeted tests.\nVERDICT: FAIL",
+                    }
+                ]
+            }
+        ),
+    )
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: 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],
+    )
+
+    patch_runtime_agent_factory(
+        monkeypatch,
+        lambda **_kwargs: SimpleNamespace(
+            invoke=lambda payload, **kwargs: {
+                "messages": [
+                    {
+                        "role": "assistant",
+                        "content": "Checked targeted tests.\nVERDICT: PASS",
+                    }
+                ]
+            }
+        ),
+    )
+    monkeypatch.setattr(subagent_tools, "build_openai_model", lambda **_kwargs: 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/tasks/test_planning.py b/coding-deepgent/tests/tasks/test_planning.py
new file mode 100644
index 000000000..77998462f
--- /dev/null
+++ b/coding-deepgent/tests/tasks/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/tasks/test_planning_renderer.py b/coding-deepgent/tests/tasks/test_planning_renderer.py
new file mode 100644
index 000000000..e0554c6e6
--- /dev/null
+++ b/coding-deepgent/tests/tasks/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/tasks/test_tasks.py b/coding-deepgent/tests/tasks/test_tasks.py
new file mode 100644
index 000000000..2ffb5b339
--- /dev/null
+++ b/coding-deepgent/tests/tasks/test_tasks.py
@@ -0,0 +1,299 @@
+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,
+    list_plans,
+    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"
+    )
+
+
+def test_list_plans_is_deterministic() -> None:
+    store = InMemoryStore()
+    task = create_task(store, title="Implement feature")
+    first = create_plan(
+        store,
+        title="B plan",
+        content="Second",
+        verification="pytest -q tests/test_tasks.py",
+        task_ids=[task.id],
+    )
+    second = create_plan(
+        store,
+        title="A plan",
+        content="First",
+        verification="pytest -q tests/test_tasks.py",
+        task_ids=[task.id],
+    )
+
+    plans = list_plans(store)
+
+    assert [plan.id for plan in plans] == sorted([first.id, second.id])
diff --git a/coding-deepgent/tests/tasks/test_todo_domain.py b/coding-deepgent/tests/tasks/test_todo_domain.py
new file mode 100644
index 000000000..5fdd5c8ff
--- /dev/null
+++ b/coding-deepgent/tests/tasks/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[2]
+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/tool_system/test_tool_result_storage.py b/coding-deepgent/tests/tool_system/test_tool_result_storage.py
new file mode 100644
index 000000000..8093f8d54
--- /dev/null
+++ b/coding-deepgent/tests/tool_system/test_tool_result_storage.py
@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from langchain.messages import ToolMessage
+
+from coding_deepgent.compact import (
+    PERSISTED_OUTPUT_CLOSING_TAG,
+    PERSISTED_OUTPUT_TAG,
+    maybe_persist_large_tool_result,
+    tool_results_dir,
+)
+from coding_deepgent.hooks import LocalHookRegistry
+from coding_deepgent.runtime import InMemoryEventSink, RuntimeContext
+
+
+def runtime_context(workdir: Path) -> RuntimeContext:
+    return RuntimeContext(
+        session_id="session-1",
+        workdir=workdir,
+        trusted_workdirs=(),
+        entrypoint="test",
+        agent_name="test-agent",
+        skill_dir=workdir / "skills",
+        event_sink=InMemoryEventSink(),
+        hook_registry=LocalHookRegistry(),
+    )
+
+
+def test_maybe_persist_large_tool_result_replaces_large_content_with_preview(
+    tmp_path: Path,
+) -> None:
+    context = runtime_context(tmp_path)
+    message = ToolMessage(content="x" * 5000, tool_call_id="call:1")
+
+    result = maybe_persist_large_tool_result(
+        message,
+        runtime_context=context,
+        max_inline_chars=4000,
+        preview_chars=20,
+    )
+
+    assert result is not message
+    assert PERSISTED_OUTPUT_TAG in str(result.content)
+    assert PERSISTED_OUTPUT_CLOSING_TAG in str(result.content)
+    assert ".coding-deepgent/tool-results/session-1/call-1.txt" in str(result.content)
+    assert result.artifact == {
+        "kind": "persisted_output",
+        "path": ".coding-deepgent/tool-results/session-1/call-1.txt",
+        "original_length": 5000,
+        "preview_chars": 20,
+        "serialized_kind": "text",
+        "has_more": True,
+    }
+    stored = tool_results_dir(context) / "call-1.txt"
+    assert stored.exists()
+    assert stored.read_text(encoding="utf-8") == "x" * 5000
+
+
+def test_maybe_persist_large_tool_result_keeps_small_content_inline(
+    tmp_path: Path,
+) -> None:
+    context = runtime_context(tmp_path)
+    message = ToolMessage(content="small", tool_call_id="call-1")
+
+    result = maybe_persist_large_tool_result(
+        message,
+        runtime_context=context,
+        max_inline_chars=4000,
+    )
+
+    assert result is message
+    assert not tool_results_dir(context).exists()
+
+
+def test_maybe_persist_large_tool_result_preserves_existing_artifact(
+    tmp_path: Path,
+) -> None:
+    context = runtime_context(tmp_path)
+    message = ToolMessage(
+        content="y" * 4500,
+        tool_call_id="call-1",
+        artifact={"upstream": True},
+    )
+
+    result = maybe_persist_large_tool_result(
+        message,
+        runtime_context=context,
+        max_inline_chars=4000,
+        preview_chars=10,
+    )
+
+    assert result.artifact == {
+        "kind": "persisted_output",
+        "path": ".coding-deepgent/tool-results/session-1/call-1.txt",
+        "original_length": 4500,
+        "preview_chars": 10,
+        "serialized_kind": "text",
+        "has_more": True,
+        "upstream_artifact": {"upstream": True},
+    }
diff --git a/coding-deepgent/tests/tool_system/test_tool_search.py b/coding-deepgent/tests/tool_system/test_tool_search.py
new file mode 100644
index 000000000..5d4e7e435
--- /dev/null
+++ b/coding-deepgent/tests/tool_system/test_tool_search.py
@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any, cast
+
+import pytest
+from dependency_injector import providers
+from langgraph.types import Command
+from langchain.tools import tool
+from pydantic import ValidationError
+
+from coding_deepgent.containers import AppContainer
+from coding_deepgent.hooks import LocalHookRegistry
+from coding_deepgent.mcp import MCPSourceMetadata, MCPToolDescriptor, adapt_mcp_tool_descriptor
+from coding_deepgent.runtime import InMemoryEventSink, RuntimeContext
+from coding_deepgent.settings import Settings
+from coding_deepgent.tool_system import ToolCapability, ToolPolicy, build_capability_registry
+from coding_deepgent.tool_system.deferred import (
+    InvokeDeferredToolInput,
+    ToolSearchInput,
+    ToolSearchResult,
+    invoke_deferred_tool,
+    tool_search,
+)
+
+
+@tool("audit_tool", description="Audit one candidate by query.")
+def audit_tool(query: str) -> str:
+    return f"audit:{query}"
+
+
+@tool("update_tool", description="Update one candidate by query.")
+def update_tool(query: str) -> Command:
+    return Command(update={"audit_query": query})
+
+
+@tool("mcp__docs__lookup", description="Lookup docs by query.")
+def docs_lookup(query: str) -> str:
+    return f"docs:{query}"
+
+
+def runtime_for(registry, *, workdir: Path):
+    return SimpleNamespace(
+        tool_call_id="call-1",
+        state={},
+        store=None,
+        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=LocalHookRegistry(),
+            tool_policy=ToolPolicy(registry=registry),
+            visible_tool_projection=registry.project("main"),
+        ),
+    )
+
+
+def product_registry(workdir: Path):
+    container = AppContainer(
+        settings=providers.Object(Settings(workdir=workdir)),
+        model=providers.Object(object()),
+        create_agent_factory=providers.Object(lambda **kwargs: object()),
+    )
+    return container.capability_registry()
+
+
+def test_tool_search_schema_is_strict_and_hides_runtime() -> None:
+    schema = cast(Any, tool_search.tool_call_schema).model_json_schema()
+
+    assert tool_search.name == "ToolSearch"
+    assert "runtime" not in schema["properties"]
+
+    with pytest.raises(ValidationError):
+        ToolSearchInput.model_validate({"query": " "})
+    with pytest.raises(ValidationError):
+        ToolSearchInput.model_validate({"query": "search", "extra": True})
+    with pytest.raises(ValidationError):
+        InvokeDeferredToolInput.model_validate(
+            {"tool_name": "audit_tool", "arguments": {}, "extra": True}
+        )
+
+
+def test_tool_search_returns_deferred_builtin_subagent_controls(tmp_path: Path) -> None:
+    registry = product_registry(tmp_path)
+    runtime = runtime_for(registry, workdir=tmp_path)
+
+    result = ToolSearchResult.model_validate_json(
+        cast(Any, tool_search).func("background subagent", runtime)
+    )
+
+    names = [item.name for item in result.matches]
+    assert result.total_deferred_tools >= 6
+    assert "run_subagent_background" in names
+    assert "subagent_list" in names
+    assert "subagent_status" in names
+
+
+def test_tool_search_selects_exact_deferred_mcp_tool(tmp_path: Path) -> None:
+    base_registry = product_registry(tmp_path)
+    capability = adapt_mcp_tool_descriptor(
+        MCPToolDescriptor(
+            name="mcp__docs__lookup",
+            tool=docs_lookup,
+            source=MCPSourceMetadata(server_name="docs", transport="stdio"),
+        )
+    )
+    registry = build_capability_registry(
+        builtin_capabilities=tuple(base_registry.metadata().values()),
+        extension_capabilities=(capability,),
+    )
+    runtime = runtime_for(registry, workdir=tmp_path)
+
+    result = ToolSearchResult.model_validate_json(
+        cast(Any, tool_search).func("select:mcp__docs__lookup", runtime)
+    )
+
+    assert [item.name for item in result.matches] == ["mcp__docs__lookup"]
+    assert result.matches[0].source == "mcp:docs"
+
+
+def test_invoke_deferred_tool_executes_custom_deferred_capability(tmp_path: Path) -> None:
+    base_registry = product_registry(tmp_path)
+    deferred_capability = ToolCapability(
+        name="audit_tool",
+        tool=audit_tool,
+        domain="demo",
+        read_only=True,
+        destructive=False,
+        concurrency_safe=True,
+        source="builtin",
+        trusted=True,
+        family="demo",
+        mutation="read",
+        execution="plain_tool",
+        exposure="deferred",
+        rendering_result="tool_message",
+    )
+    registry = build_capability_registry(
+        builtin_capabilities=tuple(base_registry.metadata().values()),
+        extension_capabilities=(deferred_capability,),
+    )
+    runtime = runtime_for(registry, workdir=tmp_path)
+
+    output = cast(Any, invoke_deferred_tool).func(
+        "audit_tool",
+        {"query": "safety check"},
+        runtime,
+    )
+
+    assert str(output.content) == "audit:safety check"
+
+
+def test_invoke_deferred_tool_preserves_command_update_results(tmp_path: Path) -> None:
+    base_registry = product_registry(tmp_path)
+    deferred_capability = ToolCapability(
+        name="update_tool",
+        tool=update_tool,
+        domain="demo",
+        read_only=False,
+        destructive=False,
+        concurrency_safe=False,
+        source="builtin",
+        trusted=True,
+        family="demo",
+        mutation="orchestration",
+        execution="plain_tool",
+        exposure="deferred",
+        rendering_result="command",
+    )
+    registry = build_capability_registry(
+        builtin_capabilities=tuple(base_registry.metadata().values()),
+        extension_capabilities=(deferred_capability,),
+    )
+    runtime = runtime_for(registry, workdir=tmp_path)
+
+    output = cast(Any, invoke_deferred_tool).func(
+        "update_tool",
+        {"query": "state sync"},
+        runtime,
+    )
+
+    assert isinstance(output, Command)
+    assert output.update == {"audit_query": "state sync"}
+
+
+def test_invoke_deferred_tool_executes_deferred_mcp_capability(tmp_path: Path) -> None:
+    base_registry = product_registry(tmp_path)
+    capability = adapt_mcp_tool_descriptor(
+        MCPToolDescriptor(
+            name="mcp__docs__lookup",
+            tool=docs_lookup,
+            source=MCPSourceMetadata(server_name="docs", transport="stdio"),
+        )
+    )
+    registry = build_capability_registry(
+        builtin_capabilities=tuple(base_registry.metadata().values()),
+        extension_capabilities=(capability,),
+    )
+    runtime = runtime_for(registry, workdir=tmp_path)
+
+    output = cast(Any, invoke_deferred_tool).func(
+        "mcp__docs__lookup",
+        {"query": "tool search"},
+        runtime,
+    )
+
+    assert str(output.content) == "docs:tool search"
diff --git a/coding-deepgent/tests/tool_system/test_tool_system_middleware.py b/coding-deepgent/tests/tool_system/test_tool_system_middleware.py
new file mode 100644
index 000000000..d77cb5dd7
--- /dev/null
+++ b/coding-deepgent/tests/tool_system/test_tool_system_middleware.py
@@ -0,0 +1,575 @@
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+
+from langchain.messages import ToolMessage
+from langchain.tools import tool
+from langgraph.store.memory import InMemoryStore
+from langgraph.types import Command
+
+from coding_deepgent.hooks import HookPayload, HookResult, LocalHookRegistry
+from coding_deepgent.memory import MemoryRecord, save_memory, save_memory_record
+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.tool_system.deferred import invoke_deferred_tool, tool_search
+from coding_deepgent.filesystem import bash, edit_file, glob_search, grep_search, read_file, write_file
+from coding_deepgent.todo.tools import todo_write
+
+
+@tool("mcp__docs__write", description="Write docs through MCP.")
+def mcp_docs_write(path: str, content: str) -> str:
+    return f"wrote {path}: {content}"
+
+
+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,),
+            deferred_bridge_tools=(tool_search, invoke_deferred_tool),
+            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,
+    *,
+    store: object | None = None,
+    entrypoint: str = "test",
+):
+    hook_registry = LocalHookRegistry()
+    runtime = SimpleNamespace(
+        context=RuntimeContext(
+            session_id="session-1",
+            workdir=Path.cwd(),
+            trusted_workdirs=(),
+            entrypoint=entrypoint,
+            agent_name="test-agent",
+            skill_dir=Path.cwd() / "skills",
+            event_sink=sink or InMemoryEventSink(),
+            hook_registry=hook_registry,
+        ),
+        store=store,
+    )
+    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_persists_large_tool_output_for_eligible_tools(tmp_path: Path) -> None:
+    registry = canonical_registry()
+    sink = InMemoryEventSink()
+    middleware = ToolGuardMiddleware(
+        registry=registry,
+        policy=ToolPolicy(
+            registry=registry,
+            permission_manager=PermissionManager(mode="default", workdir=tmp_path),
+        ),
+        event_sink=sink,
+    )
+    req = request("read_file", {"path": "README.md"}, sink)
+    req.runtime.context = RuntimeContext(
+        session_id="session-1",
+        workdir=tmp_path,
+        trusted_workdirs=(),
+        entrypoint="test",
+        agent_name="test-agent",
+        skill_dir=tmp_path / "skills",
+        event_sink=sink,
+        hook_registry=LocalHookRegistry(),
+    )
+
+    result = middleware.wrap_tool_call(
+        req,
+        lambda _request: ToolMessage(content="x" * 5000, tool_call_id="call-1"),
+    )
+
+    assert isinstance(result, ToolMessage)
+    assert ".coding-deepgent/tool-results/session-1/call-1.txt" in str(result.content)
+    stored = tmp_path / ".coding-deepgent" / "tool-results" / "session-1" / "call-1.txt"
+    assert stored.exists()
+    assert stored.read_text(encoding="utf-8") == "x" * 5000
+
+
+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_hitl_approve_resumes_and_calls_handler(monkeypatch) -> 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)
+    calls: list[str] = []
+
+    monkeypatch.setattr(
+        "coding_deepgent.tool_system.middleware.interrupt",
+        lambda payload: {"decision": "approve", "payload": payload},
+    )
+
+    result = middleware.wrap_tool_call(
+        request(
+            "write_file",
+            {"path": "README.md", "content": "x"},
+            sink,
+            entrypoint="coding-deepgent-frontend",
+        ),
+        lambda _request: calls.append("called")
+        or ToolMessage(content="ok", tool_call_id="call-1"),
+    )
+
+    assert isinstance(result, ToolMessage)
+    assert result.content == "ok"
+    assert calls == ["called"]
+    assert [event.kind for event in sink.snapshot()] == ["allowed", "completed"]
+
+
+def test_tool_guard_hitl_reject_returns_bounded_error(monkeypatch) -> 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)
+
+    monkeypatch.setattr(
+        "coding_deepgent.tool_system.middleware.interrupt",
+        lambda payload: {"decision": "reject", "message": "No writes today", "payload": payload},
+    )
+
+    result = middleware.wrap_tool_call(
+        request(
+            "write_file",
+            {"path": "README.md", "content": "x"},
+            sink,
+            entrypoint="coding-deepgent-frontend",
+        ),
+        lambda _request: ToolMessage(content="should not run", tool_call_id="call-1"),
+    )
+
+    assert isinstance(result, ToolMessage)
+    assert result.status == "error"
+    assert str(result.content) == "No writes today"
+    assert [event.kind for event in sink.snapshot()] == ["permission_denied"]
+
+
+def test_tool_guard_blocks_git_commit_when_feedback_requires_lint_first() -> None:
+    registry = canonical_registry()
+    sink = InMemoryEventSink()
+    store = InMemoryStore()
+    save_memory_record(
+        store,
+        MemoryRecord(
+            type="feedback",
+            rule="Run lint before commit",
+            why="The repo requires clean validation before code submission",
+            how_to_apply="Before any commit-like completion step, run lint first",
+        ),
+    )
+    middleware = ToolGuardMiddleware(registry=registry, event_sink=sink)
+
+    result = middleware.wrap_tool_call(
+        request("bash", {"command": "git commit -m 'x'"}, sink, store=store),
+        lambda _request: ToolMessage(content="should not run", tool_call_id="call-1"),
+    )
+
+    assert isinstance(result, ToolMessage)
+    assert result.status == "error"
+    assert "Run lint first" in str(result.content)
+    events = sink.snapshot()
+    assert [event.kind for event in events] == ["feedback_blocked"]
+    assert events[0].metadata["policy_code"] == "permission_denied"
+
+
+def test_tool_guard_blocks_dependency_file_edits_when_feedback_requires_confirmation() -> None:
+    registry = canonical_registry()
+    sink = InMemoryEventSink()
+    store = InMemoryStore()
+    save_memory_record(
+        store,
+        MemoryRecord(
+            type="feedback",
+            rule="Confirm before dependency changes",
+            why="Dependency edits can trigger version conflicts",
+            how_to_apply="Stop and confirm before changing package.json or install dependencies",
+        ),
+    )
+    middleware = ToolGuardMiddleware(registry=registry, event_sink=sink)
+
+    result = middleware.wrap_tool_call(
+        request(
+            "write_file",
+            {"path": "package.json", "content": "{}"},
+            sink,
+            store=store,
+        ),
+        lambda _request: ToolMessage(content="should not run", tool_call_id="call-1"),
+    )
+
+    assert isinstance(result, ToolMessage)
+    assert result.status == "error"
+    assert "confirmation before dependency changes" in str(result.content)
+    assert [event.kind for event in sink.snapshot()] == ["feedback_blocked"]
+
+
+def test_tool_guard_blocks_generated_path_edits_when_feedback_forbids_it() -> None:
+    registry = canonical_registry()
+    sink = InMemoryEventSink()
+    store = InMemoryStore()
+    save_memory_record(
+        store,
+        MemoryRecord(
+            type="feedback",
+            rule="Do not modify generated files",
+            why="They are regenerated by tooling",
+            how_to_apply="Avoid editing generated paths directly",
+        ),
+    )
+    middleware = ToolGuardMiddleware(registry=registry, event_sink=sink)
+
+    result = middleware.wrap_tool_call(
+        request(
+            "edit_file",
+            {"path": "src/generated/client.py", "old_text": "a", "new_text": "b"},
+            sink,
+            store=store,
+        ),
+        lambda _request: ToolMessage(content="should not run", tool_call_id="call-1"),
+    )
+
+    assert isinstance(result, ToolMessage)
+    assert result.status == "error"
+    assert "generated files" in str(result.content)
+    assert [event.kind for event in sink.snapshot()] == ["feedback_blocked"]
+
+
+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 result.tool_call_id == "call-1"
+    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",
+        "phase": "permission_denied",
+        "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=mcp_docs_write,
+        domain="mcp",
+        read_only=False,
+        destructive=True,
+        concurrency_safe=False,
+        source="mcp:docs",
+        trusted=False,
+        family="mcp",
+        mutation="workspace_write",
+        execution="plain_tool",
+        exposure="extension",
+        rendering_result="tool_message",
+    )
+    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"]
+
+
+def test_tool_guard_converts_tool_exception_to_protocol_error_message() -> None:
+    registry = canonical_registry()
+    sink = InMemoryEventSink()
+    middleware = ToolGuardMiddleware(registry=registry, event_sink=sink)
+
+    result = middleware.wrap_tool_call(
+        request("TodoWrite", {}, sink),
+        lambda _request: (_ for _ in ()).throw(RuntimeError("backend exploded")),
+    )
+
+    assert isinstance(result, ToolMessage)
+    assert result.status == "error"
+    assert result.tool_call_id == "call-1"
+    assert str(result.content) == "Error: RuntimeError: backend exploded"
+    events = sink.snapshot()
+    assert [event.kind for event in events] == ["allowed", "failed"]
+    assert events[1].metadata["tool_call_id"] == "call-1"
+    assert events[1].metadata["result_type"] == "ToolMessage"
diff --git a/coding-deepgent/tests/tool_system/test_tool_system_registry.py b/coding-deepgent/tests/tool_system/test_tool_system_registry.py
new file mode 100644
index 000000000..63f73eb9f
--- /dev/null
+++ b/coding-deepgent/tests/tool_system/test_tool_system_registry.py
@@ -0,0 +1,340 @@
+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 (
+    TOOL_PROJECTION_EXPOSURES,
+    ToolCapability,
+    build_builtin_capabilities,
+    build_capability_registry,
+)
+
+
+EXPECTED_MAIN_TOOL_NAMES = [
+    "bash",
+    "read_file",
+    "write_file",
+    "edit_file",
+    "TodoWrite",
+    "save_memory",
+    "list_memory",
+    "delete_memory",
+    "load_skill",
+    "ToolSearch",
+    "invoke_deferred_tool",
+    "task_create",
+    "task_get",
+    "task_list",
+    "task_update",
+    "plan_save",
+    "plan_get",
+    "run_subagent",
+    "run_fork",
+]
+
+EXPECTED_DEFERRED_TOOL_NAMES = [
+    "run_subagent_background",
+    "subagent_status",
+    "subagent_list",
+    "subagent_send_input",
+    "subagent_stop",
+    "resume_subagent",
+    "resume_fork",
+]
+
+
+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
+
+
+def test_role_based_projection_api_is_deterministic(tmp_path: Path) -> None:
+    registry = _container(tmp_path).capability_registry()
+    main_projection = registry.project("main")
+    child_projection = registry.project("child")
+
+    assert TOOL_PROJECTION_EXPOSURES == {
+        "main": ("main", "extension"),
+        "child": ("child_only",),
+        "extension": ("extension",),
+        "deferred": ("deferred",),
+    }
+    assert main_projection.name == "main"
+    assert child_projection.name == "child"
+    assert main_projection.names() == EXPECTED_MAIN_TOOL_NAMES
+    assert child_projection.names() == ["glob", "grep"]
+    assert [tool.name for tool in child_projection.tools()] == ["glob", "grep"]
+    assert set(child_projection.metadata()) == {"glob", "grep"}
+    assert registry.names_for_projection("main") == EXPECTED_MAIN_TOOL_NAMES
+    assert registry.names_for_projection("child") == ["glob", "grep"]
+    assert registry.names_for_projection("extension") == []
+    assert registry.names_for_projection("deferred") == EXPECTED_DEFERRED_TOOL_NAMES
+    assert [tool.name for tool in registry.tools_for_projection("child")] == [
+        "glob",
+        "grep",
+    ]
+    with pytest.raises(ValueError, match="Unknown tool projection"):
+        registry.names_for_projection("missing")
+
+
+@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"
+
+
+@tool("mcp__docs__lookup", description="Lookup docs by query.")
+def extension_lookup(query: str) -> str:
+    return query
+
+
+@tool("disabled_demo", description="Disabled demo capability.")
+def disabled_demo() -> str:
+    return "disabled"
+
+
+@tool("audit_tool", description="Audit test tool.")
+def audit_tool(query: str) -> str:
+    return query
+
+
+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=(),
+            deferred_bridge_tools=(),
+            task_tools=(),
+            subagent_tools=(),
+        )
+
+
+def test_registered_capabilities_have_five_factor_metadata_and_schema(
+    tmp_path: Path,
+) -> None:
+    registry = _container(tmp_path).capability_registry()
+
+    for capability in registry.metadata().values():
+        assert capability.name == getattr(capability.tool, "name")
+        assert capability.tool.args_schema is not None
+        assert capability.tool.tool_call_schema is not None
+        assert capability.domain
+        assert capability.source
+        assert capability.family
+        assert capability.mutation
+        assert capability.execution
+        assert capability.exposure in {"main", "extension", "child_only", "deferred"}
+        assert capability.rendering_result
+        public_schema = capability.tool.tool_call_schema.model_json_schema()
+        public_fields = set(public_schema.get("properties", {}))
+        assert "runtime" not in public_fields
+        assert "tool_call_id" not in public_fields
+
+
+def test_builtin_capability_safe_opt_ins_are_explicit(tmp_path: Path) -> None:
+    registry = _container(tmp_path).capability_registry()
+    persisted_tools = {
+        capability.name
+        for capability in registry.metadata().values()
+        if capability.persist_large_output
+    }
+    microcompact_tools = {
+        capability.name
+        for capability in registry.metadata().values()
+        if capability.microcompact_eligible
+    }
+
+    assert persisted_tools == {"bash", "read_file", "glob", "grep"}
+    assert microcompact_tools == persisted_tools
+    for capability in registry.metadata().values():
+        if capability.persist_large_output:
+            assert capability.max_inline_result_chars == 4000
+            assert capability.rendering_result == "tool_message_or_persisted_output"
+        if capability.mutation in {
+            "workspace_write",
+            "state_update",
+            "durable_store",
+            "orchestration",
+        }:
+            assert capability.read_only is False
+            assert capability.concurrency_safe is False
+
+
+def test_capability_registry_rejects_name_mismatch_and_unknown_metadata() -> None:
+    with pytest.raises(ValueError, match="must match tool name"):
+        build_capability_registry(
+            builtin_capabilities=(
+                ToolCapability(
+                    name="wrong_name",
+                    tool=audit_tool,
+                    domain="demo",
+                    read_only=True,
+                    destructive=False,
+                    concurrency_safe=True,
+                    source="builtin",
+                    trusted=True,
+                    family="demo",
+                    mutation="read",
+                    execution="plain_tool",
+                    exposure="main",
+                    rendering_result="tool_message",
+                ),
+            ),
+            extension_capabilities=(),
+        )
+
+    with pytest.raises(ValueError, match="invalid rendering_result"):
+        build_capability_registry(
+            builtin_capabilities=(
+                ToolCapability(
+                    name="audit_tool",
+                    tool=audit_tool,
+                    domain="demo",
+                    read_only=True,
+                    destructive=False,
+                    concurrency_safe=True,
+                    source="builtin",
+                    trusted=True,
+                    family="demo",
+                    mutation="read",
+                    execution="plain_tool",
+                    exposure="main",
+                    rendering_result="unknown",
+                ),
+            ),
+            extension_capabilities=(),
+        )
+
+
+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=extension_lookup,
+        domain="mcp",
+        read_only=True,
+        destructive=False,
+        concurrency_safe=True,
+        source="mcp:docs",
+        trusted=False,
+        family="mcp",
+        mutation="read",
+        execution="plain_tool",
+        exposure="extension",
+        rendering_result="tool_message",
+        tags=("read", "server:docs"),
+    )
+    disabled_capability = ToolCapability(
+        name="disabled_demo",
+        tool=disabled_demo,
+        domain="demo",
+        read_only=True,
+        destructive=False,
+        concurrency_safe=True,
+        source="builtin",
+        trusted=True,
+        family="demo",
+        mutation="read",
+        execution="plain_tool",
+        enabled=False,
+        exposure="main",
+        rendering_result="tool_message",
+    )
+    deferred_capability = ToolCapability(
+        name="audit_tool",
+        tool=audit_tool,
+        domain="demo",
+        read_only=True,
+        destructive=False,
+        concurrency_safe=True,
+        source="builtin",
+        trusted=True,
+        family="demo",
+        mutation="read",
+        execution="plain_tool",
+        exposure="deferred",
+        rendering_result="tool_message",
+    )
+    registry = build_capability_registry(
+        builtin_capabilities=tuple(base_registry.metadata().values()),
+        extension_capabilities=(
+            extension_capability,
+            disabled_capability,
+            deferred_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()
+    assert registry.names_for_projection("extension") == ["mcp__docs__lookup"]
+    assert registry.names_for_projection("deferred") == [
+        *EXPECTED_DEFERRED_TOOL_NAMES,
+        "audit_tool",
+    ]
+    assert "audit_tool" not in registry.main_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/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/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/skills/agent-builder/SKILL.md b/skills/agent-builder/SKILL.md
deleted file mode 100644
index 9ea16ebf5..000000000
--- a/skills/agent-builder/SKILL.md
+++ /dev/null
@@ -1,129 +0,0 @@
----
-name: agent-builder
-description: |
-  Design and build AI agents for any domain. Use when users:
-  (1) ask to "create an agent", "build an assistant", or "design an AI system"
-  (2) want to understand agent architecture, agentic patterns, or autonomous AI
-  (3) need help with capabilities, subagents, planning, or skill mechanisms
-  (4) ask about Claude Code, Cursor, or similar agent internals
-  (5) want to build agents for business, research, creative, or operational tasks
-  Keywords: agent, assistant, autonomous, workflow, tool use, multi-step, orchestration
----
-
-# Agent Builder
-
-Build AI agents for any domain - customer service, research, operations, creative work, or specialized business processes.
-
-## The Core Philosophy
-
-> **The model already knows how to be an agent. Your job is to get out of the way.**
-
-An agent is not complex engineering. It's a simple loop that invites the model to act:
-
-```
-LOOP:
-  Model sees: context + available capabilities
-  Model decides: act or respond
-  If act: execute capability, add result, continue
-  If respond: return to user
-```
-
-**That's it.** The magic isn't in the code - it's in the model. Your code just provides the opportunity.
-
-## The Three Elements
-
-### 1. Capabilities (What can it DO?)
-
-Atomic actions the agent can perform: search, read, create, send, query, modify.
-
-**Design principle**: Start with 3-5 capabilities. Add more only when the agent consistently fails because a capability is missing.
-
-### 2. Knowledge (What does it KNOW?)
-
-Domain expertise injected on-demand: policies, workflows, best practices, schemas.
-
-**Design principle**: Make knowledge available, not mandatory. Load it when relevant, not upfront.
-
-### 3. Context (What has happened?)
-
-The conversation history - the thread connecting actions into coherent behavior.
-
-**Design principle**: Context is precious. Isolate noisy subtasks. Truncate verbose outputs. Protect clarity.
-
-## Agent Design Thinking
-
-Before building, understand:
-
-- **Purpose**: What should this agent accomplish?
-- **Domain**: What world does it operate in? (customer service, research, operations, creative...)
-- **Capabilities**: What 3-5 actions are essential?
-- **Knowledge**: What expertise does it need access to?
-- **Trust**: What decisions can you delegate to the model?
-
-**CRITICAL**: Trust the model. Don't over-engineer. Don't pre-specify workflows. Give it capabilities and let it reason.
-
-## Progressive Complexity
-
-Start simple. Add complexity only when real usage reveals the need:
-
-| Level | What to add | When to add it |
-|-------|-------------|----------------|
-| Basic | 3-5 capabilities | Always start here |
-| Planning | Progress tracking | Multi-step tasks lose coherence |
-| Subagents | Isolated child agents | Exploration pollutes context |
-| Skills | On-demand knowledge | Domain expertise needed |
-
-**Most agents never need to go beyond Level 2.**
-
-## Domain Examples
-
-**Business**: CRM queries, email, calendar, approvals
-**Research**: Database search, document analysis, citations
-**Operations**: Monitoring, tickets, notifications, escalation
-**Creative**: Asset generation, editing, collaboration, review
-
-The pattern is universal. Only the capabilities change.
-
-## Key Principles
-
-1. **The model IS the agent** - Code just runs the loop
-2. **Capabilities enable** - What it CAN do
-3. **Knowledge informs** - What it KNOWS how to do
-4. **Constraints focus** - Limits create clarity
-5. **Trust liberates** - Let the model reason
-6. **Iteration reveals** - Start minimal, evolve from usage
-
-## Anti-Patterns
-
-| Pattern | Problem | Solution |
-|---------|---------|----------|
-| Over-engineering | Complexity before need | Start simple |
-| Too many capabilities | Model confusion | 3-5 to start |
-| Rigid workflows | Can't adapt | Let model decide |
-| Front-loaded knowledge | Context bloat | Load on-demand |
-| Micromanagement | Undercuts intelligence | Trust the model |
-
-## Resources
-
-**Philosophy & Theory**:
-- `references/agent-philosophy.md` - Deep dive into why agents work
-
-**Implementation**:
-- `references/minimal-agent.py` - Complete working agent (~80 lines)
-- `references/tool-templates.py` - Capability definitions
-- `references/subagent-pattern.py` - Context isolation
-
-**Scaffolding**:
-- `scripts/init_agent.py` - Generate new agent projects
-
-## The Agent Mindset
-
-**From**: "How do I make the system do X?"
-**To**: "How do I enable the model to do X?"
-
-**From**: "What's the workflow for this task?"
-**To**: "What capabilities would help accomplish this?"
-
-The best agent code is almost boring. Simple loops. Clear capabilities. Clean context. The magic isn't in the code.
-
-**Give the model capabilities and knowledge. Trust it to figure out the rest.**
diff --git a/skills/agent-builder/references/agent-philosophy.md b/skills/agent-builder/references/agent-philosophy.md
deleted file mode 100644
index dd5e36fed..000000000
--- a/skills/agent-builder/references/agent-philosophy.md
+++ /dev/null
@@ -1,154 +0,0 @@
-# The Philosophy of Agent Harness Engineering
-
-> **The model already knows how to be an agent. Your job is to build it a world worth acting in.**
-
-## The Fundamental Truth
-
-Strip away every framework, every library, every architectural pattern. What remains?
-
-A loop. A model. An invitation to act.
-
-The agent is not the code. The agent is the model itself -- a vast neural network trained on humanity's collective problem-solving, reasoning, and tool use. The code merely provides the opportunity for the model to express its agency.
-
-The code is the harness. The model is the agent. These are not interchangeable. Confuse them, and you will build the wrong thing.
-
-## What an Agent IS
-
-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.
-
-A human is an agent: a biological neural network shaped by evolution. DeepMind's DQN is an agent: a convolutional network that learned to play Atari from raw pixels. OpenAI Five is an agent: five networks that learned Dota 2 teamwork through self-play. Claude is an agent: a language model that learned to reason and act from the breadth of human knowledge.
-
-In every case, the agent is the trained model. Not the game engine. Not the Dota 2 client. Not the terminal. The model.
-
-## What an Agent Is NOT
-
-Prompt plumbing is not agency. Wiring together LLM API calls with if-else branches, node graphs, and hardcoded routing logic does not produce an agent. It produces a brittle pipeline -- a Rube Goldberg machine with an LLM wedged in as a text-completion node.
-
-You cannot engineer your way to agency. Agency is learned, not programmed. No amount of glue code will emergently produce autonomous behavior. Those systems are the modern resurrection of GOFAI -- symbolic rule systems the field abandoned decades ago, now spray-painted with an LLM veneer.
-
-## The Harness: What We Actually Build
-
-If the model is the agent, then what is the code? It is the **harness** -- the environment that gives the agent the ability to perceive and act in a specific domain.
-
-```
-Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions
-```
-
-### Tools: The Agent's Hands
-
-Tools answer: **What can the agent DO?**
-
-Each tool is an atomic action the agent can take in its environment. File read/write, shell execution, API calls, browser control, database queries. The model needs to understand what each tool does, but not how to sequence them -- it will figure that out.
-
-**Design principle**: Atomic, composable, well-described. Start with 3-5. Add more only when the model consistently fails to accomplish tasks because a tool is missing.
-
-### Knowledge: The Agent's Expertise
-
-Knowledge answers: **What does the agent KNOW?**
-
-Domain expertise that turns a general agent into a domain specialist. Product documentation, architectural decisions, regulatory requirements, style guides. Inject on-demand (via tool_result), not upfront (via system prompt). Progressive disclosure preserves context for what matters.
-
-**Design principle**: Available but not mandatory. The agent should know what knowledge exists and pull what it needs.
-
-### Context: The Agent's Memory
-
-Context is the thread connecting individual actions into coherent behavior. What has been said, tried, learned, and decided.
-
-**Design principle**: Context is precious. Protect it. Isolate subtasks that generate noise (s04). Compress when history grows long (s06). Persist goals beyond single conversations (s07).
-
-### Permissions: The Agent's Boundaries
-
-Permissions answer: **What is the agent ALLOWED to do?**
-
-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.
-
-**Design principle**: Constraints focus behavior, not limit it. "One task in_progress at a time" forces sequential focus. "Read-only subagent" prevents accidental modifications.
-
-### Task-Process Data: The Agent's Training Signal
-
-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 evolve the agent.
-
-## The Universal Loop
-
-Every effective agent -- regardless of domain -- follows the same pattern:
-
-```
-LOOP:
-  Model sees: conversation history + available tools
-  Model decides: act or respond
-  If act: tool executed, result added to context, loop continues
-  If respond: answer returned, loop ends
-```
-
-This is not a simplification. This is the actual architecture. Everything else is harness engineering -- mechanisms layered on top of this loop to make the agent more effective. The loop belongs to the agent. The mechanisms belong to the harness.
-
-## Principles of Harness Engineering
-
-### Trust the Model
-
-The most important principle: **trust the model**.
-
-Don't anticipate every edge case. Don't build elaborate decision trees. Don't pre-specify the workflow.
-
-The model is better at reasoning than any rule system you could write. Your conditional logic will fail on edge cases. The model will reason through them.
-
-**Give the model tools and knowledge. Let it figure out how to use them.**
-
-### Constraints Enable
-
-This seems paradoxical, but constraints don't limit agents -- they focus them.
-
-A todo list with "only one task in progress" forces sequential focus. A subagent with read-only access prevents accidental modifications. A context compression threshold keeps history from overwhelming.
-
-The best constraints prevent the model from getting lost, not micromanage its approach.
-
-### Progressive Complexity
-
-Never build everything upfront.
-
-```
-Level 0: Model + one tool (bash)                     -- s01
-Level 1: Model + tool dispatch map                    -- s02
-Level 2: Model + planning                             -- s03
-Level 3: Model + subagents + skills                   -- s04, s05
-Level 4: Model + context management + persistence     -- s06, s07, s08
-Level 5: Model + teams + autonomy + isolation         -- s09-s12
-```
-
-Start at the lowest level that might work. Move up only when real usage reveals the need.
-
-## The Mind Shift
-
-Building harnesses requires a fundamental shift in thinking:
-
-**From**: "How do I make the system do X?"
-**To**: "How do I enable the model to do X?"
-
-**From**: "What should happen when the user says Y?"
-**To**: "What tools would help address Y?"
-
-**From**: "What's the workflow for this task?"
-**To**: "What does the model need to figure out the workflow?"
-
-**From**: "I'm building an agent."
-**To**: "I'm building a harness for the agent."
-
-The best harness code is almost boring. Simple loops. Clear tool definitions. Clean context management. The magic isn't in the code -- it's in the model.
-
-## The Vehicle Metaphor
-
-The model is the driver. The harness is the vehicle.
-
-A coding agent's vehicle is its IDE, terminal, and filesystem. A farm agent's vehicle is its sensor array, irrigation controls, and weather data. A hotel agent's vehicle is its booking system, guest channels, and facility APIs.
-
-The driver generalizes. The vehicle specializes. Your job as a harness engineer is to build the best vehicle for your domain -- one that gives the driver maximum visibility, precise controls, and clear boundaries.
-
-Build the cockpit. Build the dashboard. Build the controls. The pilot is already trained.
-
-## Conclusion
-
-The model is the agent. The code is the harness. Know which one you're building.
-
-You are not writing intelligence. You are building the world intelligence inhabits. The quality of that world -- how clearly the agent can perceive, how precisely it can act, how rich its knowledge -- directly determines how effectively the intelligence can express itself.
-
-Build great harnesses. The agent will do the rest.
diff --git a/skills/agent-builder/references/minimal-agent.py b/skills/agent-builder/references/minimal-agent.py
deleted file mode 100644
index 9eae11d6f..000000000
--- a/skills/agent-builder/references/minimal-agent.py
+++ /dev/null
@@ -1,149 +0,0 @@
-#!/usr/bin/env python3
-"""
-Minimal Agent Template - Copy and customize this.
-
-This is the simplest possible working agent (~80 lines).
-It has everything you need: 3 tools + loop.
-
-Usage:
-    1. Set ANTHROPIC_API_KEY environment variable
-    2. python minimal-agent.py
-    3. Type commands, 'q' to quit
-"""
-
-from anthropic import Anthropic
-from pathlib import Path
-import subprocess
-import os
-
-# Configuration
-client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
-MODEL = os.getenv("MODEL_NAME", "claude-sonnet-4-20250514")
-WORKDIR = Path.cwd()
-
-# System prompt - keep it simple
-SYSTEM = f"""You are a coding agent at {WORKDIR}.
-
-Rules:
-- Use tools to complete tasks
-- Prefer action over explanation
-- Summarize what you did when done"""
-
-# Minimal tool set - add more as needed
-TOOLS = [
-    {
-        "name": "bash",
-        "description": "Run 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"]
-        }
-    },
-]
-
-
-def execute_tool(name: str, args: dict) -> str:
-    """Execute a tool and return result."""
-    if name == "bash":
-        try:
-            r = subprocess.run(
-                args["command"], shell=True, cwd=WORKDIR,
-                capture_output=True, text=True, timeout=60
-            )
-            return (r.stdout + r.stderr).strip() or "(empty)"
-        except subprocess.TimeoutExpired:
-            return "Error: Timeout"
-
-    if name == "read_file":
-        try:
-            return (WORKDIR / args["path"]).read_text()[:50000]
-        except Exception as e:
-            return f"Error: {e}"
-
-    if name == "write_file":
-        try:
-            p = WORKDIR / args["path"]
-            p.parent.mkdir(parents=True, exist_ok=True)
-            p.write_text(args["content"])
-            return f"Wrote {len(args['content'])} bytes to {args['path']}"
-        except Exception as e:
-            return f"Error: {e}"
-
-    return f"Unknown tool: {name}"
-
-
-def agent(prompt: str, history: list = None) -> str:
-    """Run the agent loop."""
-    if history is None:
-        history = []
-
-    history.append({"role": "user", "content": prompt})
-
-    while True:
-        response = client.messages.create(
-            model=MODEL,
-            system=SYSTEM,
-            messages=history,
-            tools=TOOLS,
-            max_tokens=8000,
-        )
-
-        # Build assistant message
-        history.append({"role": "assistant", "content": response.content})
-
-        # If no tool calls, return text
-        if response.stop_reason != "tool_use":
-            return "".join(b.text for b in response.content if hasattr(b, "text"))
-
-        # Execute tools
-        results = []
-        for block in response.content:
-            if block.type == "tool_use":
-                print(f"> {block.name}: {block.input}")
-                output = execute_tool(block.name, block.input)
-                print(f"  {output[:100]}...")
-                results.append({
-                    "type": "tool_result",
-                    "tool_use_id": block.id,
-                    "content": output
-                })
-
-        history.append({"role": "user", "content": results})
-
-
-if __name__ == "__main__":
-    print(f"Minimal Agent - {WORKDIR}")
-    print("Type 'q' to quit.\n")
-
-    history = []
-    while True:
-        try:
-            query = input(">> ").strip()
-        except (EOFError, KeyboardInterrupt):
-            break
-        if query in ("q", "quit", "exit", ""):
-            break
-        print(agent(query, history))
-        print()
diff --git a/skills/agent-builder/references/subagent-pattern.py b/skills/agent-builder/references/subagent-pattern.py
deleted file mode 100644
index 0a337db1e..000000000
--- a/skills/agent-builder/references/subagent-pattern.py
+++ /dev/null
@@ -1,243 +0,0 @@
-"""
-Subagent Pattern - How to implement Task tool for context isolation.
-
-The key insight: spawn child agents with ISOLATED context to prevent
-"context pollution" where exploration details fill up the main conversation.
-"""
-
-import time
-import sys
-
-# Assuming client, MODEL, execute_tool are defined elsewhere
-
-
-# =============================================================================
-# AGENT TYPE REGISTRY
-# =============================================================================
-
-AGENT_TYPES = {
-    # Explore: Read-only, for searching and analyzing
-    "explore": {
-        "description": "Read-only agent for exploring code, finding files, searching",
-        "tools": ["bash", "read_file"],  # No write access!
-        "prompt": "You are an exploration agent. Search and analyze, but NEVER modify files. Return a concise summary of what you found.",
-    },
-
-    # Code: Full-powered, for implementation
-    "code": {
-        "description": "Full agent for implementing features and fixing bugs",
-        "tools": "*",  # All tools
-        "prompt": "You are a coding agent. Implement the requested changes efficiently. Return a summary of what you changed.",
-    },
-
-    # Plan: Read-only, for design work
-    "plan": {
-        "description": "Planning agent for designing implementation strategies",
-        "tools": ["bash", "read_file"],  # Read-only
-        "prompt": "You are a planning agent. Analyze the codebase and output a numbered implementation plan. Do NOT make any changes.",
-    },
-
-    # Add your own types here...
-    # "test": {
-    #     "description": "Testing agent for running and analyzing tests",
-    #     "tools": ["bash", "read_file"],
-    #     "prompt": "Run tests and report results. Don't modify code.",
-    # },
-}
-
-
-def get_agent_descriptions() -> str:
-    """Generate descriptions for Task tool schema."""
-    return "\n".join(
-        f"- {name}: {cfg['description']}"
-        for name, cfg in AGENT_TYPES.items()
-    )
-
-
-def get_tools_for_agent(agent_type: str, base_tools: list) -> list:
-    """
-    Filter tools based on agent type.
-
-    '*' means all base tools.
-    Otherwise, whitelist specific tool names.
-
-    Note: Subagents don't get Task tool to prevent infinite recursion.
-    """
-    allowed = AGENT_TYPES.get(agent_type, {}).get("tools", "*")
-
-    if allowed == "*":
-        return base_tools  # All base tools, but NOT Task
-
-    return [t for t in base_tools if t["name"] in allowed]
-
-
-# =============================================================================
-# TASK TOOL DEFINITION
-# =============================================================================
-
-TASK_TOOL = {
-    "name": "Task",
-    "description": f"""Spawn a subagent for a focused subtask.
-
-Subagents run in ISOLATED context - they don't see parent's history.
-Use this to keep the main conversation clean.
-
-Agent types:
-{get_agent_descriptions()}
-
-Example uses:
-- Task(explore): "Find all files using the auth module"
-- Task(plan): "Design a migration strategy for the database"
-- Task(code): "Implement the user registration form"
-""",
-    "input_schema": {
-        "type": "object",
-        "properties": {
-            "description": {
-                "type": "string",
-                "description": "Short task name (3-5 words) for progress display"
-            },
-            "prompt": {
-                "type": "string",
-                "description": "Detailed instructions for the subagent"
-            },
-            "agent_type": {
-                "type": "string",
-                "enum": list(AGENT_TYPES.keys()),
-                "description": "Type of agent to spawn"
-            },
-        },
-        "required": ["description", "prompt", "agent_type"],
-    },
-}
-
-
-# =============================================================================
-# SUBAGENT EXECUTION
-# =============================================================================
-
-def run_task(description: str, prompt: str, agent_type: str,
-             client, model: str, workdir, base_tools: list, execute_tool) -> str:
-    """
-    Execute a subagent task with isolated context.
-
-    Key concepts:
-    1. ISOLATED HISTORY - subagent starts fresh, no parent context
-    2. FILTERED TOOLS - based on agent type permissions
-    3. AGENT-SPECIFIC PROMPT - specialized behavior
-    4. RETURNS SUMMARY ONLY - parent sees just the final result
-
-    Args:
-        description: Short name for progress display
-        prompt: Detailed instructions for subagent
-        agent_type: Key from AGENT_TYPES
-        client: Anthropic client
-        model: Model to use
-        workdir: Working directory
-        base_tools: List of tool definitions
-        execute_tool: Function to execute tools
-
-    Returns:
-        Final text output from subagent
-    """
-    if agent_type not in AGENT_TYPES:
-        return f"Error: Unknown agent type '{agent_type}'"
-
-    config = AGENT_TYPES[agent_type]
-
-    # Agent-specific system prompt
-    sub_system = f"""You are a {agent_type} subagent at {workdir}.
-
-{config["prompt"]}
-
-Complete the task and return a clear, concise summary."""
-
-    # Filtered tools for this agent type
-    sub_tools = get_tools_for_agent(agent_type, base_tools)
-
-    # KEY: ISOLATED message history!
-    # The subagent starts fresh, doesn't see parent's conversation
-    sub_messages = [{"role": "user", "content": prompt}]
-
-    # Progress display
-    print(f"  [{agent_type}] {description}")
-    start = time.time()
-    tool_count = 0
-
-    # Run the same agent loop (but silently)
-    while True:
-        response = client.messages.create(
-            model=model,
-            system=sub_system,
-            messages=sub_messages,
-            tools=sub_tools,
-            max_tokens=8000,
-        )
-
-        # Check if done
-        if response.stop_reason != "tool_use":
-            break
-
-        # Execute tools
-        tool_calls = [b for b in response.content if b.type == "tool_use"]
-        results = []
-
-        for tc in tool_calls:
-            tool_count += 1
-            output = execute_tool(tc.name, tc.input)
-            results.append({
-                "type": "tool_result",
-                "tool_use_id": tc.id,
-                "content": output
-            })
-
-            # Update progress (in-place on same line)
-            elapsed = time.time() - start
-            sys.stdout.write(
-                f"\r  [{agent_type}] {description} ... {tool_count} tools, {elapsed:.1f}s"
-            )
-            sys.stdout.flush()
-
-        sub_messages.append({"role": "assistant", "content": response.content})
-        sub_messages.append({"role": "user", "content": results})
-
-    # Final progress update
-    elapsed = time.time() - start
-    sys.stdout.write(
-        f"\r  [{agent_type}] {description} - done ({tool_count} tools, {elapsed:.1f}s)\n"
-    )
-
-    # Extract and return ONLY the final text
-    # This is what the parent agent sees - a clean summary
-    for block in response.content:
-        if hasattr(block, "text"):
-            return block.text
-
-    return "(subagent returned no text)"
-
-
-# =============================================================================
-# USAGE EXAMPLE
-# =============================================================================
-
-"""
-# In your main agent's execute_tool function:
-
-def execute_tool(name: str, args: dict) -> str:
-    if name == "Task":
-        return run_task(
-            description=args["description"],
-            prompt=args["prompt"],
-            agent_type=args["agent_type"],
-            client=client,
-            model=MODEL,
-            workdir=WORKDIR,
-            base_tools=BASE_TOOLS,
-            execute_tool=execute_tool  # Pass self for recursion
-        )
-    # ... other tools ...
-
-
-# In your TOOLS list:
-TOOLS = BASE_TOOLS + [TASK_TOOL]
-"""
diff --git a/skills/agent-builder/references/tool-templates.py b/skills/agent-builder/references/tool-templates.py
deleted file mode 100644
index 952cd698f..000000000
--- a/skills/agent-builder/references/tool-templates.py
+++ /dev/null
@@ -1,271 +0,0 @@
-"""
-Tool Templates - Copy and customize these for your agent.
-
-Each tool needs:
-1. Definition (JSON schema for the model)
-2. Implementation (Python function)
-"""
-
-from pathlib import Path
-import subprocess
-
-WORKDIR = Path.cwd()
-
-
-# =============================================================================
-# TOOL DEFINITIONS (for TOOLS list)
-# =============================================================================
-
-BASH_TOOL = {
-    "name": "bash",
-    "description": "Run a shell command. Use for: ls, find, grep, git, npm, python, etc.",
-    "input_schema": {
-        "type": "object",
-        "properties": {
-            "command": {
-                "type": "string",
-                "description": "The shell command to execute"
-            }
-        },
-        "required": ["command"],
-    },
-}
-
-READ_FILE_TOOL = {
-    "name": "read_file",
-    "description": "Read file contents. Returns UTF-8 text.",
-    "input_schema": {
-        "type": "object",
-        "properties": {
-            "path": {
-                "type": "string",
-                "description": "Relative path to the file"
-            },
-            "limit": {
-                "type": "integer",
-                "description": "Max lines to read (default: all)"
-            },
-        },
-        "required": ["path"],
-    },
-}
-
-WRITE_FILE_TOOL = {
-    "name": "write_file",
-    "description": "Write content to a file. Creates parent directories if needed.",
-    "input_schema": {
-        "type": "object",
-        "properties": {
-            "path": {
-                "type": "string",
-                "description": "Relative path for the file"
-            },
-            "content": {
-                "type": "string",
-                "description": "Content to write"
-            },
-        },
-        "required": ["path", "content"],
-    },
-}
-
-EDIT_FILE_TOOL = {
-    "name": "edit_file",
-    "description": "Replace exact text in a file. Use for surgical edits.",
-    "input_schema": {
-        "type": "object",
-        "properties": {
-            "path": {
-                "type": "string",
-                "description": "Relative path to the file"
-            },
-            "old_text": {
-                "type": "string",
-                "description": "Exact text to find (must match precisely)"
-            },
-            "new_text": {
-                "type": "string",
-                "description": "Replacement text"
-            },
-        },
-        "required": ["path", "old_text", "new_text"],
-    },
-}
-
-TODO_WRITE_TOOL = {
-    "name": "TodoWrite",
-    "description": "Update the task list. Use to plan and track progress.",
-    "input_schema": {
-        "type": "object",
-        "properties": {
-            "items": {
-                "type": "array",
-                "description": "Complete list of tasks",
-                "items": {
-                    "type": "object",
-                    "properties": {
-                        "content": {"type": "string", "description": "Task description"},
-                        "status": {"type": "string", "enum": ["pending", "in_progress", "completed"]},
-                        "activeForm": {"type": "string", "description": "Present tense, e.g. 'Reading files'"},
-                    },
-                    "required": ["content", "status", "activeForm"],
-                },
-            }
-        },
-        "required": ["items"],
-    },
-}
-
-TASK_TOOL_TEMPLATE = """
-# Generate dynamically with agent types
-TASK_TOOL = {
-    "name": "Task",
-    "description": f"Spawn a subagent for a focused subtask.\\n\\nAgent types:\\n{get_agent_descriptions()}",
-    "input_schema": {
-        "type": "object",
-        "properties": {
-            "description": {"type": "string", "description": "Short task name (3-5 words)"},
-            "prompt": {"type": "string", "description": "Detailed instructions"},
-            "agent_type": {"type": "string", "enum": list(AGENT_TYPES.keys())},
-        },
-        "required": ["description", "prompt", "agent_type"],
-    },
-}
-"""
-
-
-# =============================================================================
-# TOOL IMPLEMENTATIONS
-# =============================================================================
-
-def safe_path(p: str) -> Path:
-    """
-    Security: Ensure path stays within workspace.
-    Prevents ../../../etc/passwd attacks.
-    """
-    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:
-    """
-    Execute shell command with safety checks.
-
-    Safety features:
-    - Blocks obviously dangerous commands
-    - 60 second timeout
-    - Output truncated to 50KB
-    """
-    dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
-    if any(d in command for d in dangerous):
-        return "Error: Dangerous command blocked"
-
-    try:
-        result = subprocess.run(
-            command,
-            shell=True,
-            cwd=WORKDIR,
-            capture_output=True,
-            text=True,
-            timeout=60
-        )
-        output = (result.stdout + result.stderr).strip()
-        return output[:50000] if output else "(no output)"
-
-    except subprocess.TimeoutExpired:
-        return "Error: Command timed out (60s)"
-    except Exception as e:
-        return f"Error: {e}"
-
-
-def run_read_file(path: str, limit: int = None) -> str:
-    """
-    Read file contents with optional line limit.
-
-    Features:
-    - Safe path resolution
-    - Optional line limit for large files
-    - Output truncated to 50KB
-    """
-    try:
-        text = safe_path(path).read_text()
-        lines = text.splitlines()
-
-        if limit and limit < len(lines):
-            lines = lines[:limit]
-            lines.append(f"... ({len(text.splitlines()) - limit} more lines)")
-
-        return "\n".join(lines)[:50000]
-
-    except Exception as e:
-        return f"Error: {e}"
-
-
-def run_write_file(path: str, content: str) -> str:
-    """
-    Write content to file, creating parent directories if needed.
-
-    Features:
-    - Safe path resolution
-    - Auto-creates parent directories
-    - Returns byte count for confirmation
-    """
-    try:
-        fp = safe_path(path)
-        fp.parent.mkdir(parents=True, exist_ok=True)
-        fp.write_text(content)
-        return f"Wrote {len(content)} bytes to {path}"
-
-    except Exception as e:
-        return f"Error: {e}"
-
-
-def run_edit_file(path: str, old_text: str, new_text: str) -> str:
-    """
-    Replace exact text in a file (surgical edit).
-
-    Features:
-    - Exact string matching (not regex)
-    - Only replaces first occurrence (safety)
-    - Clear error if text not found
-    """
-    try:
-        fp = safe_path(path)
-        content = fp.read_text()
-
-        if old_text not in content:
-            return f"Error: Text not found in {path}"
-
-        new_content = content.replace(old_text, new_text, 1)
-        fp.write_text(new_content)
-        return f"Edited {path}"
-
-    except Exception as e:
-        return f"Error: {e}"
-
-
-# =============================================================================
-# DISPATCHER PATTERN
-# =============================================================================
-
-def execute_tool(name: str, args: dict) -> str:
-    """
-    Dispatch tool call to implementation.
-
-    This pattern makes it easy to add new tools:
-    1. Add definition to TOOLS list
-    2. Add implementation function
-    3. Add case to this dispatcher
-    """
-    if name == "bash":
-        return run_bash(args["command"])
-    if name == "read_file":
-        return run_read_file(args["path"], args.get("limit"))
-    if name == "write_file":
-        return run_write_file(args["path"], args["content"])
-    if name == "edit_file":
-        return run_edit_file(args["path"], args["old_text"], args["new_text"])
-    # Add more tools here...
-    return f"Unknown tool: {name}"
diff --git a/skills/agent-builder/scripts/init_agent.py b/skills/agent-builder/scripts/init_agent.py
deleted file mode 100644
index 2f401157e..000000000
--- a/skills/agent-builder/scripts/init_agent.py
+++ /dev/null
@@ -1,279 +0,0 @@
-#!/usr/bin/env python3
-"""
-Agent Scaffold Script - Create a new agent project with best practices.
-
-Usage:
-    python init_agent.py <agent-name> [--level 0-4] [--path <output-dir>]
-
-Examples:
-    python init_agent.py my-agent                 # Level 1 (4 tools)
-    python init_agent.py my-agent --level 0      # Minimal (bash only)
-    python init_agent.py my-agent --level 2      # With TodoWrite
-    python init_agent.py my-agent --path ./bots  # Custom output directory
-"""
-
-import argparse
-import sys
-from pathlib import Path
-
-# Agent templates for each level
-TEMPLATES = {
-    0: '''#!/usr/bin/env python3
-"""
-Level 0 Agent - Bash is All You Need (~50 lines)
-
-Core insight: One tool (bash) can do everything.
-Subagents via self-recursion: python {name}.py "subtask"
-"""
-
-from anthropic import Anthropic
-from dotenv import load_dotenv
-import subprocess
-import os
-
-load_dotenv()
-
-client = Anthropic(
-    api_key=os.getenv("ANTHROPIC_API_KEY"),
-    base_url=os.getenv("ANTHROPIC_BASE_URL")
-)
-MODEL = os.getenv("MODEL_NAME", "claude-sonnet-4-20250514")
-
-SYSTEM = """You are a coding agent. Use bash for everything:
-- Read: cat, grep, find, ls
-- Write: echo 'content' > file
-- Subagent: python {name}.py "subtask"
-"""
-
-TOOL = [{{
-    "name": "bash",
-    "description": "Execute shell command",
-    "input_schema": {{"type": "object", "properties": {{"command": {{"type": "string"}}}}, "required": ["command"]}}
-}}]
-
-def run(prompt, history=[]):
-    history.append({{"role": "user", "content": prompt}})
-    while True:
-        r = client.messages.create(model=MODEL, system=SYSTEM, messages=history, tools=TOOL, max_tokens=8000)
-        history.append({{"role": "assistant", "content": r.content}})
-        if r.stop_reason != "tool_use":
-            return "".join(b.text for b in r.content if hasattr(b, "text"))
-        results = []
-        for b in r.content:
-            if b.type == "tool_use":
-                print(f"> {{b.input['command']}}")
-                try:
-                    out = subprocess.run(b.input["command"], shell=True, capture_output=True, text=True, timeout=60)
-                    output = (out.stdout + out.stderr).strip() or "(empty)"
-                except Exception as e:
-                    output = f"Error: {{e}}"
-                results.append({{"type": "tool_result", "tool_use_id": b.id, "content": output[:50000]}})
-        history.append({{"role": "user", "content": results}})
-
-if __name__ == "__main__":
-    h = []
-    print("{name} - Level 0 Agent\\nType 'q' to quit.\\n")
-    while (q := input(">> ").strip()) not in ("q", "quit", ""):
-        print(run(q, h), "\\n")
-''',
-
-    1: '''#!/usr/bin/env python3
-"""
-Level 1 Agent - Model as Agent (~200 lines)
-
-Core insight: 4 tools cover 90% of coding tasks.
-The model IS the agent. Code just runs the loop.
-"""
-
-from anthropic import Anthropic
-from dotenv import load_dotenv
-from pathlib import Path
-import subprocess
-import os
-
-load_dotenv()
-
-client = Anthropic(
-    api_key=os.getenv("ANTHROPIC_API_KEY"),
-    base_url=os.getenv("ANTHROPIC_BASE_URL")
-)
-MODEL = os.getenv("MODEL_NAME", "claude-sonnet-4-20250514")
-WORKDIR = Path.cwd()
-
-SYSTEM = f"""You are a coding agent at {{WORKDIR}}.
-
-Rules:
-- Prefer tools over prose. Act, don't just explain.
-- Never invent file paths. Use ls/find first if unsure.
-- Make minimal changes. Don't over-engineer.
-- After finishing, summarize what changed."""
-
-TOOLS = [
-    {{"name": "bash", "description": "Run 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"]}}}},
-]
-
-def safe_path(p: str) -> Path:
-    """Prevent path escape attacks."""
-    path = (WORKDIR / p).resolve()
-    if not path.is_relative_to(WORKDIR):
-        raise ValueError(f"Path escapes workspace: {{p}}")
-    return path
-
-def execute(name: str, args: dict) -> str:
-    """Execute a tool and return result."""
-    if name == "bash":
-        dangerous = ["rm -rf /", "sudo", "shutdown", "> /dev/"]
-        if any(d in args["command"] for d in dangerous):
-            return "Error: Dangerous command blocked"
-        try:
-            r = subprocess.run(args["command"], shell=True, cwd=WORKDIR, capture_output=True, text=True, timeout=60)
-            return (r.stdout + r.stderr).strip()[:50000] or "(empty)"
-        except subprocess.TimeoutExpired:
-            return "Error: Timeout (60s)"
-        except Exception as e:
-            return f"Error: {{e}}"
-
-    if name == "read_file":
-        try:
-            return safe_path(args["path"]).read_text()[:50000]
-        except Exception as e:
-            return f"Error: {{e}}"
-
-    if name == "write_file":
-        try:
-            p = safe_path(args["path"])
-            p.parent.mkdir(parents=True, exist_ok=True)
-            p.write_text(args["content"])
-            return f"Wrote {{len(args['content'])}} bytes to {{args['path']}}"
-        except Exception as e:
-            return f"Error: {{e}}"
-
-    if name == "edit_file":
-        try:
-            p = safe_path(args["path"])
-            content = p.read_text()
-            if args["old_text"] not in content:
-                return f"Error: Text not found in {{args['path']}}"
-            p.write_text(content.replace(args["old_text"], args["new_text"], 1))
-            return f"Edited {{args['path']}}"
-        except Exception as e:
-            return f"Error: {{e}}"
-
-    return f"Unknown tool: {{name}}"
-
-def agent(prompt: str, history: list = None) -> str:
-    """Run the agent loop."""
-    if history is None:
-        history = []
-    history.append({{"role": "user", "content": prompt}})
-
-    while True:
-        response = client.messages.create(
-            model=MODEL, system=SYSTEM, messages=history, tools=TOOLS, max_tokens=8000
-        )
-        history.append({{"role": "assistant", "content": response.content}})
-
-        if response.stop_reason != "tool_use":
-            return "".join(b.text for b in response.content if hasattr(b, "text"))
-
-        results = []
-        for block in response.content:
-            if block.type == "tool_use":
-                print(f"> {{block.name}}: {{str(block.input)[:100]}}")
-                output = execute(block.name, block.input)
-                print(f"  {{output[:100]}}...")
-                results.append({{"type": "tool_result", "tool_use_id": block.id, "content": output}})
-        history.append({{"role": "user", "content": results}})
-
-if __name__ == "__main__":
-    print(f"{name} - Level 1 Agent at {{WORKDIR}}")
-    print("Type 'q' to quit.\\n")
-    h = []
-    while True:
-        try:
-            query = input(">> ").strip()
-        except (EOFError, KeyboardInterrupt):
-            break
-        if query in ("q", "quit", "exit", ""):
-            break
-        print(agent(query, h), "\\n")
-''',
-}
-
-ENV_TEMPLATE = '''# API Configuration
-ANTHROPIC_API_KEY=sk-xxx
-ANTHROPIC_BASE_URL=https://api.anthropic.com
-MODEL_NAME=claude-sonnet-4-20250514
-'''
-
-
-def create_agent(name: str, level: int, output_dir: Path):
-    """Create a new agent project."""
-    # Validate level
-    if level not in TEMPLATES and level not in (2, 3, 4):
-        print(f"Error: Level {level} not yet implemented in scaffold.")
-        print("Available levels: 0 (minimal), 1 (4 tools)")
-        print("For levels 2-4, copy from mini-claude-code repository.")
-        sys.exit(1)
-
-    # Create output directory
-    agent_dir = output_dir / name
-    agent_dir.mkdir(parents=True, exist_ok=True)
-
-    # Write agent file
-    agent_file = agent_dir / f"{name}.py"
-    template = TEMPLATES.get(level, TEMPLATES[1])
-    agent_file.write_text(template.format(name=name))
-    print(f"Created: {agent_file}")
-
-    # Write .env.example
-    env_file = agent_dir / ".env.example"
-    env_file.write_text(ENV_TEMPLATE)
-    print(f"Created: {env_file}")
-
-    # Write .gitignore
-    gitignore = agent_dir / ".gitignore"
-    gitignore.write_text(".env\n__pycache__/\n*.pyc\n")
-    print(f"Created: {gitignore}")
-
-    print(f"\nAgent '{name}' created at {agent_dir}")
-    print(f"\nNext steps:")
-    print(f"  1. cd {agent_dir}")
-    print(f"  2. cp .env.example .env")
-    print(f"  3. Edit .env with your API key")
-    print(f"  4. pip install anthropic python-dotenv")
-    print(f"  5. python {name}.py")
-
-
-def main():
-    parser = argparse.ArgumentParser(
-        description="Scaffold a new AI coding agent project",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""
-Levels:
-  0  Minimal (~50 lines) - Single bash tool, self-recursion for subagents
-  1  Basic (~200 lines)  - 4 core tools: bash, read, write, edit
-  2  Todo (~300 lines)   - + TodoWrite for structured planning
-  3  Subagent (~450)     - + Task tool for context isolation
-  4  Skills (~550)       - + Skill tool for domain expertise
-        """
-    )
-    parser.add_argument("name", help="Name of the agent to create")
-    parser.add_argument("--level", type=int, default=1, choices=[0, 1, 2, 3, 4],
-                       help="Complexity level (default: 1)")
-    parser.add_argument("--path", type=Path, default=Path.cwd(),
-                       help="Output directory (default: current directory)")
-
-    args = parser.parse_args()
-    create_agent(args.name, args.level, args.path)
-
-
-if __name__ == "__main__":
-    main()
diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md
deleted file mode 100644
index a9d7984af..000000000
--- a/skills/code-review/SKILL.md
+++ /dev/null
@@ -1,157 +0,0 @@
----
-name: code-review
-description: Perform thorough code reviews with security, performance, and maintainability analysis. Use when user asks to review code, check for bugs, or audit a codebase.
----
-
-# Code Review Skill
-
-You now have expertise in conducting comprehensive code reviews. Follow this structured approach:
-
-## Review Checklist
-
-### 1. Security (Critical)
-
-Check for:
-- [ ] **Injection vulnerabilities**: SQL, command, XSS, template injection
-- [ ] **Authentication issues**: Hardcoded credentials, weak auth
-- [ ] **Authorization flaws**: Missing access controls, IDOR
-- [ ] **Data exposure**: Sensitive data in logs, error messages
-- [ ] **Cryptography**: Weak algorithms, improper key management
-- [ ] **Dependencies**: Known vulnerabilities (check with `npm audit`, `pip-audit`)
-
-```bash
-# Quick security scans
-npm audit                    # Node.js
-pip-audit                    # Python
-cargo audit                  # Rust
-grep -r "password\|secret\|api_key" --include="*.py" --include="*.js"
-```
-
-### 2. Correctness
-
-Check for:
-- [ ] **Logic errors**: Off-by-one, null handling, edge cases
-- [ ] **Race conditions**: Concurrent access without synchronization
-- [ ] **Resource leaks**: Unclosed files, connections, memory
-- [ ] **Error handling**: Swallowed exceptions, missing error paths
-- [ ] **Type safety**: Implicit conversions, any types
-
-### 3. Performance
-
-Check for:
-- [ ] **N+1 queries**: Database calls in loops
-- [ ] **Memory issues**: Large allocations, retained references
-- [ ] **Blocking operations**: Sync I/O in async code
-- [ ] **Inefficient algorithms**: O(n^2) when O(n) possible
-- [ ] **Missing caching**: Repeated expensive computations
-
-### 4. Maintainability
-
-Check for:
-- [ ] **Naming**: Clear, consistent, descriptive
-- [ ] **Complexity**: Functions > 50 lines, deep nesting > 3 levels
-- [ ] **Duplication**: Copy-pasted code blocks
-- [ ] **Dead code**: Unused imports, unreachable branches
-- [ ] **Comments**: Outdated, redundant, or missing where needed
-
-### 5. Testing
-
-Check for:
-- [ ] **Coverage**: Critical paths tested
-- [ ] **Edge cases**: Null, empty, boundary values
-- [ ] **Mocking**: External dependencies isolated
-- [ ] **Assertions**: Meaningful, specific checks
-
-## Review Output Format
-
-```markdown
-## Code Review: [file/component name]
-
-### Summary
-[1-2 sentence overview]
-
-### Critical Issues
-1. **[Issue]** (line X): [Description]
-   - Impact: [What could go wrong]
-   - Fix: [Suggested solution]
-
-### Improvements
-1. **[Suggestion]** (line X): [Description]
-
-### Positive Notes
-- [What was done well]
-
-### Verdict
-[ ] Ready to merge
-[ ] Needs minor changes
-[ ] Needs major revision
-```
-
-## Common Patterns to Flag
-
-### Python
-```python
-# Bad: SQL injection
-cursor.execute(f"SELECT * FROM users WHERE id = {user_id}")
-# Good:
-cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))
-
-# Bad: Command injection
-os.system(f"ls {user_input}")
-# Good:
-subprocess.run(["ls", user_input], check=True)
-
-# Bad: Mutable default argument
-def append(item, lst=[]):  # Bug: shared mutable default
-# Good:
-def append(item, lst=None):
-    lst = lst or []
-```
-
-### JavaScript/TypeScript
-```javascript
-// Bad: Prototype pollution
-Object.assign(target, userInput)
-// Good:
-Object.assign(target, sanitize(userInput))
-
-// Bad: eval usage
-eval(userCode)
-// Good: Never use eval with user input
-
-// Bad: Callback hell
-getData(x => process(x, y => save(y, z => done(z))))
-// Good:
-const data = await getData();
-const processed = await process(data);
-await save(processed);
-```
-
-## Review Commands
-
-```bash
-# Show recent changes
-git diff HEAD~5 --stat
-git log --oneline -10
-
-# Find potential issues
-grep -rn "TODO\|FIXME\|HACK\|XXX" .
-grep -rn "password\|secret\|token" . --include="*.py"
-
-# Check complexity (Python)
-pip install radon && radon cc . -a
-
-# Check dependencies
-npm outdated  # Node
-pip list --outdated  # Python
-```
-
-## Review Workflow
-
-1. **Understand context**: Read PR description, linked issues
-2. **Run the code**: Build, test, run locally if possible
-3. **Read top-down**: Start with main entry points
-4. **Check tests**: Are changes tested? Do tests pass?
-5. **Security scan**: Run automated tools
-6. **Manual review**: Use checklist above
-7. **Write feedback**: Be specific, suggest fixes, be kind
diff --git a/skills/mcp-builder/SKILL.md b/skills/mcp-builder/SKILL.md
deleted file mode 100644
index 338ff3ce9..000000000
--- a/skills/mcp-builder/SKILL.md
+++ /dev/null
@@ -1,213 +0,0 @@
----
-name: mcp-builder
-description: Build MCP (Model Context Protocol) servers that give Claude new capabilities. Use when user wants to create an MCP server, add tools to Claude, or integrate external services.
----
-
-# MCP Server Building Skill
-
-You now have expertise in building MCP (Model Context Protocol) servers. MCP enables Claude to interact with external services through a standardized protocol.
-
-## What is MCP?
-
-MCP servers expose:
-- **Tools**: Functions Claude can call (like API endpoints)
-- **Resources**: Data Claude can read (like files or database records)
-- **Prompts**: Pre-built prompt templates
-
-## Quick Start: Python MCP Server
-
-### 1. Project Setup
-
-```bash
-# Create project
-mkdir my-mcp-server && cd my-mcp-server
-python3 -m venv venv && source venv/bin/activate
-
-# Install MCP SDK
-pip install mcp
-```
-
-### 2. Basic Server Template
-
-```python
-#!/usr/bin/env python3
-"""my_server.py - A simple MCP server"""
-
-from mcp.server import Server
-from mcp.server.stdio import stdio_server
-from mcp.types import Tool, TextContent
-
-# Create server instance
-server = Server("my-server")
-
-# Define a tool
-@server.tool()
-async def hello(name: str) -> str:
-    """Say hello to someone.
-
-    Args:
-        name: The name to greet
-    """
-    return f"Hello, {name}!"
-
-@server.tool()
-async def add_numbers(a: int, b: int) -> str:
-    """Add two numbers together.
-
-    Args:
-        a: First number
-        b: Second number
-    """
-    return str(a + b)
-
-# Run server
-async def main():
-    async with stdio_server() as (read, write):
-        await server.run(read, write)
-
-if __name__ == "__main__":
-    import asyncio
-    asyncio.run(main())
-```
-
-### 3. Register with Claude
-
-Add to `~/.claude/mcp.json`:
-```json
-{
-  "mcpServers": {
-    "my-server": {
-      "command": "python3",
-      "args": ["/path/to/my_server.py"]
-    }
-  }
-}
-```
-
-## TypeScript MCP Server
-
-### 1. Setup
-
-```bash
-mkdir my-mcp-server && cd my-mcp-server
-npm init -y
-npm install @modelcontextprotocol/sdk
-```
-
-### 2. Template
-
-```typescript
-// src/index.ts
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-
-const server = new Server({
-  name: "my-server",
-  version: "1.0.0",
-});
-
-// Define tools
-server.setRequestHandler("tools/list", async () => ({
-  tools: [
-    {
-      name: "hello",
-      description: "Say hello to someone",
-      inputSchema: {
-        type: "object",
-        properties: {
-          name: { type: "string", description: "Name to greet" },
-        },
-        required: ["name"],
-      },
-    },
-  ],
-}));
-
-server.setRequestHandler("tools/call", async (request) => {
-  if (request.params.name === "hello") {
-    const name = request.params.arguments.name;
-    return { content: [{ type: "text", text: `Hello, ${name}!` }] };
-  }
-  throw new Error("Unknown tool");
-});
-
-// Start server
-const transport = new StdioServerTransport();
-server.connect(transport);
-```
-
-## Advanced Patterns
-
-### External API Integration
-
-```python
-import httpx
-from mcp.server import Server
-
-server = Server("weather-server")
-
-@server.tool()
-async def get_weather(city: str) -> str:
-    """Get current weather for a city."""
-    async with httpx.AsyncClient() as client:
-        resp = await client.get(
-            f"https://api.weatherapi.com/v1/current.json",
-            params={"key": "YOUR_API_KEY", "q": city}
-        )
-        data = resp.json()
-        return f"{city}: {data['current']['temp_c']}C, {data['current']['condition']['text']}"
-```
-
-### Database Access
-
-```python
-import sqlite3
-from mcp.server import Server
-
-server = Server("db-server")
-
-@server.tool()
-async def query_db(sql: str) -> str:
-    """Execute a read-only SQL query."""
-    if not sql.strip().upper().startswith("SELECT"):
-        return "Error: Only SELECT queries allowed"
-
-    conn = sqlite3.connect("data.db")
-    cursor = conn.execute(sql)
-    rows = cursor.fetchall()
-    conn.close()
-    return str(rows)
-```
-
-### Resources (Read-only Data)
-
-```python
-@server.resource("config://settings")
-async def get_settings() -> str:
-    """Application settings."""
-    return open("settings.json").read()
-
-@server.resource("file://{path}")
-async def read_file(path: str) -> str:
-    """Read a file from the workspace."""
-    return open(path).read()
-```
-
-## Testing
-
-```bash
-# Test with MCP Inspector
-npx @anthropics/mcp-inspector python3 my_server.py
-
-# Or send test messages directly
-echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | python3 my_server.py
-```
-
-## Best Practices
-
-1. **Clear tool descriptions**: Claude uses these to decide when to call tools
-2. **Input validation**: Always validate and sanitize inputs
-3. **Error handling**: Return meaningful error messages
-4. **Async by default**: Use async/await for I/O operations
-5. **Security**: Never expose sensitive operations without auth
-6. **Idempotency**: Tools should be safe to retry
diff --git a/skills/pdf/SKILL.md b/skills/pdf/SKILL.md
deleted file mode 100644
index ddbce006f..000000000
--- a/skills/pdf/SKILL.md
+++ /dev/null
@@ -1,112 +0,0 @@
----
-name: pdf
-description: Process PDF files - extract text, create PDFs, merge documents. Use when user asks to read PDF, create PDF, or work with PDF files.
----
-
-# PDF Processing Skill
-
-You now have expertise in PDF manipulation. Follow these workflows:
-
-## Reading PDFs
-
-**Option 1: Quick text extraction (preferred)**
-```bash
-# Using pdftotext (poppler-utils)
-pdftotext input.pdf -  # Output to stdout
-pdftotext input.pdf output.txt  # Output to file
-
-# If pdftotext not available, try:
-python3 -c "
-import fitz  # PyMuPDF
-doc = fitz.open('input.pdf')
-for page in doc:
-    print(page.get_text())
-"
-```
-
-**Option 2: Page-by-page with metadata**
-```python
-import fitz  # pip install pymupdf
-
-doc = fitz.open("input.pdf")
-print(f"Pages: {len(doc)}")
-print(f"Metadata: {doc.metadata}")
-
-for i, page in enumerate(doc):
-    text = page.get_text()
-    print(f"--- Page {i+1} ---")
-    print(text)
-```
-
-## Creating PDFs
-
-**Option 1: From Markdown (recommended)**
-```bash
-# Using pandoc
-pandoc input.md -o output.pdf
-
-# With custom styling
-pandoc input.md -o output.pdf --pdf-engine=xelatex -V geometry:margin=1in
-```
-
-**Option 2: Programmatically**
-```python
-from reportlab.lib.pagesizes import letter
-from reportlab.pdfgen import canvas
-
-c = canvas.Canvas("output.pdf", pagesize=letter)
-c.drawString(100, 750, "Hello, PDF!")
-c.save()
-```
-
-**Option 3: From HTML**
-```bash
-# Using wkhtmltopdf
-wkhtmltopdf input.html output.pdf
-
-# Or with Python
-python3 -c "
-import pdfkit
-pdfkit.from_file('input.html', 'output.pdf')
-"
-```
-
-## Merging PDFs
-
-```python
-import fitz
-
-result = fitz.open()
-for pdf_path in ["file1.pdf", "file2.pdf", "file3.pdf"]:
-    doc = fitz.open(pdf_path)
-    result.insert_pdf(doc)
-result.save("merged.pdf")
-```
-
-## Splitting PDFs
-
-```python
-import fitz
-
-doc = fitz.open("input.pdf")
-for i in range(len(doc)):
-    single = fitz.open()
-    single.insert_pdf(doc, from_page=i, to_page=i)
-    single.save(f"page_{i+1}.pdf")
-```
-
-## Key Libraries
-
-| Task | Library | Install |
-|------|---------|---------|
-| Read/Write/Merge | PyMuPDF | `pip install pymupdf` |
-| Create from scratch | ReportLab | `pip install reportlab` |
-| HTML to PDF | pdfkit | `pip install pdfkit` + wkhtmltopdf |
-| Text extraction | pdftotext | `brew install poppler` / `apt install poppler-utils` |
-
-## Best Practices
-
-1. **Always check if tools are installed** before using them
-2. **Handle encoding issues** - PDFs may contain various character encodings
-3. **Large PDFs**: Process page by page to avoid memory issues
-4. **OCR for scanned PDFs**: Use `pytesseract` if text extraction returns empty
diff --git a/tests/test_agents_smoke.py b/tests/test_agents_smoke.py
deleted file mode 100644
index 9f693ed4a..000000000
--- a/tests/test_agents_smoke.py
+++ /dev/null
@@ -1,23 +0,0 @@
-from __future__ import annotations
-
-from pathlib import Path
-import py_compile
-
-import pytest
-
-
-ROOT = Path(__file__).resolve().parents[1]
-AGENTS_DIR = ROOT / "agents"
-AGENT_FILES = sorted(
-    path for path in AGENTS_DIR.glob("*.py") if path.name != "__init__.py"
-)
-AGENT_IDS = [path.name for path in AGENT_FILES]
-
-
-@pytest.mark.parametrize("agent_path", AGENT_FILES, ids=AGENT_IDS)
-def test_agent_scripts_compile(agent_path: Path) -> None:
-    _ = py_compile.compile(str(agent_path), doraise=True)
-
-
-def test_agent_scripts_exist() -> None:
-    assert AGENT_FILES, "expected at least one agent script"
diff --git a/tests/test_s_full_background.py b/tests/test_s_full_background.py
deleted file mode 100644
index 4bdb10b5a..000000000
--- a/tests/test_s_full_background.py
+++ /dev/null
@@ -1,67 +0,0 @@
-import importlib.util
-import os
-import sys
-import tempfile
-import types
-import unittest
-from pathlib import Path
-
-
-REPO_ROOT = Path(__file__).resolve().parents[1]
-MODULE_PATH = REPO_ROOT / "agents" / "s_full.py"
-
-
-def load_s_full_module(temp_cwd: Path):
-    fake_anthropic = types.ModuleType("anthropic")
-
-    class FakeAnthropic:
-        def __init__(self, *args, **kwargs):
-            self.messages = types.SimpleNamespace(create=None)
-
-    fake_dotenv = types.ModuleType("dotenv")
-    setattr(fake_anthropic, "Anthropic", FakeAnthropic)
-    setattr(fake_dotenv, "load_dotenv", lambda override=True: None)
-
-    previous_anthropic = sys.modules.get("anthropic")
-    previous_dotenv = sys.modules.get("dotenv")
-    previous_cwd = Path.cwd()
-    spec = importlib.util.spec_from_file_location("s_full_under_test", MODULE_PATH)
-    if spec is None or spec.loader is None:
-        raise RuntimeError(f"Unable to load {MODULE_PATH}")
-    module = importlib.util.module_from_spec(spec)
-
-    sys.modules["anthropic"] = fake_anthropic
-    sys.modules["dotenv"] = fake_dotenv
-    try:
-        os.chdir(temp_cwd)
-        os.environ.setdefault("MODEL_ID", "test-model")
-        spec.loader.exec_module(module)
-        return module
-    finally:
-        os.chdir(previous_cwd)
-        if previous_anthropic is None:
-            sys.modules.pop("anthropic", None)
-        else:
-            sys.modules["anthropic"] = previous_anthropic
-        if previous_dotenv is None:
-            sys.modules.pop("dotenv", None)
-        else:
-            sys.modules["dotenv"] = previous_dotenv
-
-
-class BackgroundManagerTests(unittest.TestCase):
-    def test_check_returns_running_placeholder_when_result_is_none(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            module = load_s_full_module(Path(tmp))
-            manager = module.BackgroundManager()
-            manager.tasks["abc123"] = {
-                "status": "running",
-                "command": "sleep 1",
-                "result": None,
-            }
-
-            self.assertEqual(manager.check("abc123"), "[running] (running)")
-
-
-if __name__ == "__main__":
-    unittest.main()
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
 }