+ {/* Compact header: 3 lines */}
+
{version}
@@ -54,31 +119,29 @@ export default async function VersionPage({
{tLayer(layer.id)}
)}
-
- {meta.subtitle}
-
-
+
+ {content.subtitle}
+ |
{versionData.loc} LOC
+ |
{versionData.tools.length} {t("tools")}
- {meta.coreAddition && (
-
- {meta.coreAddition}
-
- )}
-
- {meta.keyInsight}
+ {content.keyInsight}
)}
- {/* Client-rendered interactive sections */}
+ {/* Main content: client-rendered tabs (Learn / Code / Deep Dive) */}
{/* 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
("");
- const [versionB, setVersionB] = useState("");
+ const [versionA, setVersionA] = useState(QUICK_COMPARE_PRESETS[0].a);
+ const [versionB, setVersionB] = useState(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 (
-
+
{t("title")}
-
{t("subtitle")}
+
{t("subtitle")}
- {/* Selectors */}
-
-
-
- {t("select_a")}
-
-
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"
- >
- -- select --
- {LEARNING_PATH.map((v) => (
-
- {v} - {VERSION_META[v]?.title}
-
- ))}
-
+
+
+
+ {t("learning_jump")}
+
+ {t("selector_title")}
+
+ {t("selector_note")}
+
+
+
+
+
+
+ {t("select_a")}
+
+ 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"
+ >
+ {t("select_placeholder")}
+ {LEARNING_PATH.map((version) => (
+
+ {version} - {tSession(version)}
+
+ ))}
+
+
+
+
+
+
+
+ {t("select_b")}
+
+ 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"
+ >
+ {t("select_placeholder")}
+ {LEARNING_PATH.map((version) => (
+
+ {version} - {tSession(version)}
+
+ ))}
+
+
-
- {t("select_b")}
-
-
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"
- >
- -- select --
- {LEARNING_PATH.map((v) => (
-
- {v} - {VERSION_META[v]?.title}
-
- ))}
-
+
+
+
+ {pickText(locale, COMPARE_EXTRA_TEXT.quickLabel)}
+
+
+ {pickText(locale, COMPARE_EXTRA_TEXT.quickTitle)}
+
+
+ {pickText(locale, COMPARE_EXTRA_TEXT.quickBody)}
+
+
+
+ {QUICK_COMPARE_PRESETS.map((preset) => (
+ {
+ 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}
+
+ ))}
+
+
+
+ {versionB && previousOfB && previousOfB !== versionA && (
+
+
+ {pickText(locale, COMPARE_EXTRA_TEXT.quickLabel)}
+
+
+ {pickText(locale, COMPARE_EXTRA_TEXT.quickPrevious)}
+
+
+ {pickText(locale, COMPARE_EXTRA_TEXT.quickPreviousBody)}
+
+
+ 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}
+
+
+
+ )}
-
- {/* Results */}
{infoA && infoB && comparison && (
- {/* Side-by-side version info */}
-
-
-
- {metaA?.title || versionA}
- {metaA?.subtitle}
-
-
-
{infoA.loc} LOC
-
{infoA.tools.length} tools
- {metaA &&
{metaA.layer} }
+
+
+
+ {t("learning_jump")}
+
+
+ {tSession(versionA)}
+ {tSession(versionB)}
+
+
+ {progression}
+
+
+
+
+
+
+ {t("carry_from_a")}
+
+
+ {leadA || t("empty_lead")}
+
-
-
-
- {metaB?.title || versionB}
- {metaB?.subtitle}
-
-
-
{infoB.loc} LOC
-
{infoB.tools.length} tools
- {metaB &&
{metaB.layer} }
+
+
+
+ {t("new_in_b")}
+
+
+ {leadB || t("empty_lead")}
+
-
-
-
{t("architecture")}
-
-
-
- {metaA?.title || versionA}
-
-
+
+
+ {t("progression")}
+
+
+ {progression}
+
-
-
- {metaB?.title || versionB}
-
-
+
+
+
+ {pickText(locale, COMPARE_EXTRA_TEXT.goal)}
+
+
+ {guideB?.goal ?? pickText(locale, COMPARE_EXTRA_TEXT.emptyGoal)}
+
+
+
+
+ {[{ version: versionA, info: infoA, lead: leadA }, { version: versionB, info: infoB, lead: leadB }].map(
+ ({ version, info, lead }) => (
+
+
+ {tSession(version)}
+
+ {lead || t("empty_lead")}
+
+
+
+ {info.loc} LOC
+ {info.tools.length} tools
+ {tLayer(info.layer)}
+
+
+ )
+ )}
- {/* Structural diff */}
-
+
- {t("loc_delta")}
+ {t("chapter_distance")}
-
- = 0 ? "text-green-600 dark:text-green-400" : "text-red-600 dark:text-red-400"}>
- {comparison.locDelta >= 0 ? "+" : ""}{comparison.locDelta}
-
- {t("lines")}
-
+ {chapterDistance}
@@ -170,64 +499,195 @@ export default function ComparePage() {
{t("new_tools_in_b")}
-
- {comparison.toolsOnlyB.length}
-
- {comparison.toolsOnlyB.length > 0 && (
-
- {comparison.toolsOnlyB.map((tool) => (
-
- {tool}
-
- ))}
-
- )}
+
{comparison.toolsOnlyB.length}
- {t("new_classes_in_b")}
+ {t("shared_tools_count")}
-
- {comparison.newClasses.length}
-
- {comparison.newClasses.length > 0 && (
-
- {comparison.newClasses.map((cls) => (
-
- {cls}
-
- ))}
-
- )}
+ {comparison.toolsShared.length}
- {t("new_functions_in_b")}
+ {t("new_surface")}
-
- {comparison.newFunctions.length}
-
- {comparison.newFunctions.length > 0 && (
-
- {comparison.newFunctions.map((fn) => (
-
- {fn}
-
- ))}
+ {comparison.newSurface}
+
+
+
+ {jumpDiagnosis && (
+
+
+
+ {pickText(locale, COMPARE_EXTRA_TEXT.diagnosisLabel)}
+
+ {jumpDiagnosis.title}
+
+ {jumpDiagnosis.body}
+
+
+
+
+
+
+ {pickText(locale, COMPARE_EXTRA_TEXT.nextBestLabel)}
+
+
+ {jumpDiagnosis.next}
+
+
+
+
+
+ {pickText(locale, COMPARE_EXTRA_TEXT.bridgeNudge)}
+
+
+ {recommendedBridgeDocs.slice(0, 3).map((doc) => (
+
+ {doc.title}
+
+ ))}
+ {recommendedBridgeDocs.length === 0 && (
+
+ {t("empty_lead")}
+
+ )}
+
- )}
+
+ )}
+
+ {recommendedBridgeDocs.length > 0 && (
+
+
+
+ {pickText(locale, {
+ zh: "跳读辅助",
+ en: "Jump Reading Support",
+ ja: "飛び読み補助",
+ })}
+
+
+ {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)} へ飛ぶ前に、この橋渡し資料を読む`,
+ })}
+
+
+ {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: "比較ページは「何が増えたか」だけでなく、そのジャンプを理解する前に何を補うべきかも示すべきです。",
+ })}
+
+
+
+
+ {recommendedBridgeDocs.map((doc) => (
+
+
+
+
+ {doc.title}
+
+
+ {doc.summary}
+
+
+
+
+ {doc.fallbackLocale && (
+
+ {pickText(locale, {
+ zh: `当前语言缺稿，自动回退到 ${doc.fallbackLocale}`,
+ en: `Missing in this locale, falling back to ${doc.fallbackLocale}`,
+ ja: `この言語では未整備のため ${doc.fallbackLocale} へフォールバック`,
+ })}
+
+ )}
+
+ ))}
+
+ )}
+
+
+
+
+ {pickText(locale, {
+ zh: "主线执行对比",
+ en: "Mainline Flow Comparison",
+ ja: "主線実行の比較",
+ })}
+
+
+ {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つの章の間でどう変わるかを先に見ます。どこで新しい分岐が生まれ、何が主ループへ戻り、何が側車レーンに残るのかを比較します。",
+ })}
+
+
+
+
+
+ {tSession(versionA)}
+
+
+
+
+ {tSession(versionB)}
+
+
+
+
+
+
{t("architecture")}
+
+ {t("architecture_note")}
+
+
+
+
+
+ {tSession(versionA)}
+
+
+
+
+
+ {tSession(versionB)}
+
+
+
+
{t("tool_comparison")}
@@ -235,20 +695,21 @@ export default function ComparePage() {
- {t("only_in")} {metaA?.title || versionA}
+ {t("only_in")} {tSession(versionA)}
{comparison.toolsOnlyA.length === 0 ? (
{t("none")}
) : (
{comparison.toolsOnlyA.map((tool) => (
-
+
{tool}
))}
)}
+
{t("shared")}
@@ -265,16 +726,17 @@ export default function ComparePage() {
)}
+
- {t("only_in")} {metaB?.title || versionB}
+ {t("only_in")} {tSession(versionB)}
{comparison.toolsOnlyB.length === 0 ? (
{t("none")}
) : (
{comparison.toolsOnlyB.map((tool) => (
-
+
{tool}
))}
@@ -284,9 +746,18 @@ export default function ComparePage() {
- {/* Code Diff */}
-
{t("source_diff")}
+
+
{t("source_diff")}
+
+ {t("source_diff_note")} {t("loc_delta")}:{" "}
+ = 0 ? "text-emerald-600 dark:text-emerald-400" : "text-rose-600 dark:text-rose-400"}>
+ {comparison.locDelta >= 0 ? "+" : ""}
+ {comparison.locDelta}
+ {" "}
+ {t("lines")}
+
+
)}
- {/* Empty state */}
{(!versionA || !versionB) && (
-
+
)}
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 (
+
+
Document not found
+
{slug}
+
+ );
+ }
+
+ return (
+
+
+
+
+
+
+
+ {locale === "zh"
+ ? "这页适合什么时候回看"
+ : locale === "ja"
+ ? "このページへ戻るべき場面"
+ : "When This Page Helps"}
+
+
+ {descriptor?.summary?.[locale as "en" | "zh" | "ja"] ??
+ descriptor?.summary?.en}
+
+
+
+ {relatedVersions.length > 0 && (
+
+
+ {locale === "zh"
+ ? "最适合和这些章节一起读"
+ : locale === "ja"
+ ? "いっしょに読むと効く章"
+ : "Best Read Alongside"}
+
+
+ {relatedVersions.map((version) => (
+
+
+ )}
+
+
+
+
+ );
+}
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
= {
- 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 = {
- 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 = {
+ 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 (
@@ -39,13 +262,90 @@ export default function LayersPage() {
{t("subtitle")}
+
+ {t("guide_label")}
+ {t("guide_start_title")}
+
+ {t("guide_start_desc")}
+
+
+
+ {t("guide_label")}
+ {t("guide_middle_title")}
+
+ {t("guide_middle_desc")}
+
+
+
+ {t("guide_label")}
+ {t("guide_finish_title")}
+
+ {t("guide_finish_desc")}
+
+
+
+
+
+ {section.eyebrow}
+
+
+ {section.title}
+
+
+ {section.body}
+
+
+ {section.docs.map((doc) => (
+
+
+
+
+
+ {doc.title}
+
+
+ {doc.summary}
+
+
+
+
+ {pickText(locale, {
+ zh: `当前语言缺稿，自动回退到 ${doc.fallbackLocale}`,
+ en: `Missing in this locale, falling back to ${doc.fallbackLocale}`,
+ ja: `この言語では未整備のため ${doc.fallbackLocale} へフォールバック`,
+ })}
+
+ )}
+
+
+ ))}
+
+ ))}
+
{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 (
- L{index + 1}
+ P{index + 1}
{" "}
- {layer.label}
+ {tLayer(layer.id)}
{t(layer.id)}
+
+ {t(`${layer.id}_outcome`)}
+
+ {checkpoint && (
+
+
+
+
+ {pickText(locale, LAYER_CHECKPOINT_TEXT.label)}
+
+
+ {pickText(locale, checkpoint.title)}
+
+
+ {pickText(locale, LAYER_CHECKPOINT_TEXT.body)}
+
+
+
+
+
+ {pickText(locale, LAYER_CHECKPOINT_TEXT.entry)}
+
+ {checkpoint.entryVersion}
+
+
+ {pickText(locale, LAYER_CHECKPOINT_TEXT.exit)}
+
+ {checkpoint.endVersion}
+
+
+
+
+
+
+ {pickText(locale, LAYER_CHECKPOINT_TEXT.rebuild)}
+
+
+ {pickText(locale, checkpoint.rebuild)}
+
+
+
+ )}
+
- {versionInfos.map(({ id, info, meta }) => (
-
+ {versionInfos.map(({ id, info, meta, content }) => (
+
{id}
- {layer.id}
+ {tLayer(layer.id)}
- {meta?.title || id}
+ {tSession(id) || meta?.title || id}
- {meta?.subtitle && (
+ {meta && (
- {meta.subtitle}
+ {content.subtitle}
)}
@@ -105,9 +457,9 @@ export default function LayersPage() {
{info?.loc ?? "?"} LOC
{info?.tools.length ?? "?"} tools
- {meta?.keyInsight && (
+ {meta && (
- {meta.keyInsight}
+ {content.keyInsight}
)}
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 (
+
+
+ {t("title")}
+
+ {t("subtitle")}
+
+
+
+
+
+ {t("foundation_title")}
+
+
+ {foundationDocs.map((doc) => (
+
+
+ {doc.title[locale] ?? doc.title.en}
+
+
+ {doc.summary[locale] ?? doc.summary.en}
+
+
+ ))}
+
+
+
+
+ {t("deep_dive_title")}
+
+
+ {mechanismDocs.map((doc) => (
+
+
+ {doc.title[locale] ?? doc.title.en}
+
+
+ {doc.summary[locale] ?? doc.summary.en}
+
+
+ ))}
+
+
+ );
+}
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 (
@@ -14,6 +136,96 @@ export default function TimelinePage() {
{t("subtitle")}
+
+
+
+
+ {pick(locale, GUIDE_TEXT.label)}
+
+
+ {GUIDE_TEXT.cards.map((card) => (
+
+
+ {pick(locale, card.title)}
+
+
+ {pick(locale, card.body)}
+
+
+ ))}
+
+
+ {pick(locale, GUIDE_TEXT.supportLabel)}
+
+
+ {pick(locale, GUIDE_TEXT.supportBody)}
+
+
+ {GUIDE_TEXT.links.map((link) => (
+
+
+
+
+
+
+ {pick(locale, GUIDE_TEXT.checkpointLabel)}
+
+
+ {pick(locale, GUIDE_TEXT.checkpointTitle)}
+
+
+ {pick(locale, GUIDE_TEXT.checkpointBody)}
+
+
+ {STAGE_CHECKPOINTS.map((checkpoint) => (
+
+
+ {checkpoint.entryVersion}-{checkpoint.endVersion}
+
+
+ {pick(locale, checkpoint.title)}
+
+
+
+ {pick(locale, GUIDE_TEXT.checkpointRebuild)}
+
+
+ {pick(locale, checkpoint.rebuild)}
+
+
+
+
+ ))}
+
+
);
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
= {
- 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 = {
- 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 = {
- 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 (
-
- {/* Hero Section */}
-
+
+ {/* Hero */}
+
{t("hero_title")}
@@ -53,7 +30,7 @@ export default function HomePage() {
- {/* Core Pattern Section */}
-
-
-
{t("core_pattern")}
-
- {t("core_pattern_desc")}
-
-
-
- agent_loop.py
-
-
-
- while
-
- True
- :
- {"\n"}
- {" "}response = client.messages.
- create
- (
- messages=
- messages
- ,
- tools=
- tools
- )
- {"\n"}
- {" "}if
- response.stop_reason !=
- "tool_use"
- :
- {"\n"}
- {" "}break
- {"\n"}
- {" "}for
- tool_call
- in
- response.content
- :
- {"\n"}
- {" "}result =
- execute_tool
- (
- tool_call.name
- ,
- tool_call.input
- )
- {"\n"}
- {" "}messages.
- append
- (
- result
- )
-
-
-
-
- {/* Message Flow Visualization */}
-
-
-
{t("message_flow")}
-
- {t("message_flow_desc")}
-
-
-
-
-
- {/* Learning Path Preview */}
-
-
-
{t("learning_path")}
-
- {t("learning_path_desc")}
-
-
- {LEARNING_PATH.map((versionId) => {
- const meta = VERSION_META[versionId];
- const data = getVersionData(versionId);
- if (!meta || !data) return null;
- return (
-
-
-
- {versionId}
-
- {data.loc} {t("loc")}
-
-
-
- {meta.title}
-
-
- {meta.keyInsight}
-
-
-
- );
- })}
-
-
- {/* Layer Overview */}
-
-
-
{t("layers_title")}
-
- {t("layers_desc")}
-
-
- {LAYERS.map((layer) => (
-
-
-
-
-
{layer.label}
-
- {layer.versions.length} {t("versions_in_layer")}
-
-
-
- {layer.versions.map((vid) => {
- const meta = VERSION_META[vid];
- return (
-
- {vid}: {meta?.title}
-
-
- );
- })}
-
-
+ {/* Chapter list by stage */}
+
+ {LAYERS.map((layer) => (
+
+
+
+ {tLayer(layer.id)}
+
- ))}
-
+ ))}
= {
- 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();
-
- 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 {
- 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 (
-
- {reversed.map((cls, i) => {
- const isNew = newClassNames.has(cls.name);
- const colorClasses = getLayerColorClasses(cls.introducedIn);
+
+
+
+
+
+
+ {pickDiagramText(locale, UI_TEXT.summaryTitle)}
+
+
+ {content.coreAddition}
+
+
+ {translateArchitectureText(
+ locale,
+ pickDiagramText(locale, blueprint.summary)
+ )}
+
+
+
+
+
+ {visibleSlices.map((sliceId, sliceIndex) => {
+ const slice = blueprint.slices[sliceId] ?? [];
+ const style = SLICE_STYLE[sliceId];
- return (
-
- {i > 0 && (
-
-
-
+ return (
+
+
+
+
+ {pickDiagramText(locale, style.title)}
+
+
+
+ {pickDiagramText(locale, style.note)}
+
-
-
-
+ {slice.map((item, itemIndex) => (
+
+
+
+ {translateArchitectureText(
+ locale,
+ pickDiagramText(locale, item.name)
+ )}
+
+ {item.fresh && (
+
+ {pickDiagramText(locale, UI_TEXT.fresh)}
+
+ )}
+
+
+ {translateArchitectureText(
+ locale,
+ pickDiagramText(locale, item.detail)
+ )}
+
+
+ ))}
+
+
+ );
+ })}
+
+
+
+
+
+
+ {pickDiagramText(locale, UI_TEXT.recordsTitle)}
+
+
+ {pickDiagramText(locale, UI_TEXT.recordsNote)}
+
+
+
+ {blueprint.records.map((record, index) => (
+
+
+
+ {translateArchitectureText(
+ locale,
+ pickDiagramText(locale, record.name)
+ )}
+
+ {record.fresh && (
+
+ {pickDiagramText(locale, UI_TEXT.fresh)}
+
)}
- >
- {cls.name}
-
-
+
+ {translateArchitectureText(
+ locale,
+ pickDiagramText(locale, record.detail)
)}
- >
- {CLASS_DESCRIPTIONS[cls.name] || ""}
-
-
- {cls.introducedIn}
-
- {isNew && (
-
- NEW
-
- )}
-
-
-
+
+ ))}
- No classes in this version (functions only)
- )}
+
- {tools.length > 0 && (
-
- {tools.map((tool) => (
-
+
+ {pickDiagramText(locale, UI_TEXT.handoffTitle)}
+
+
+ {blueprint.handoff.map((step, index) => (
+
- {tool}
-
+
+
+ {index + 1}
+
+
+ {translateArchitectureText(
+ locale,
+ pickDiagramText(locale, step)
+ )}
+
+
))}
-
- )}
+
= {
s12: s12Annotations as AnnotationFile,
};
+const GENERIC_ANNOTATIONS: Record = {
+ 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)[locale] as { title?: string; description?: string } | undefined : undefined;
+ locale !== "en"
+ ? ((decision as unknown as Record)[locale] as DecisionLocaleCopy | undefined)
+ : undefined;
const title = localized?.title || decision.title;
const description = localized?.description || decision.description;
+ const alternatives = localized?.alternatives || decision.alternatives;
return (
@@ -100,13 +753,13 @@ function DecisionCard({
{description}
- {decision.alternatives && (
+ {alternatives && (
{t("alternatives")}
- {decision.alternatives}
+ {alternatives}
)}
@@ -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
= {
+const NODE_COLORS: Record = {
start: "#3B82F6",
process: "#10B981",
decision: "#F59E0B",
@@ -17,6 +19,85 @@ const LAYER_COLORS: Record = {
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)}
)}
@@ -185,54 +268,180 @@ interface ExecutionFlowProps {
}
export function ExecutionFlow({ version }: ExecutionFlowProps) {
- const [flow, setFlow] = useState>(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 (
-
-
-
-
-
-
-
- {flow.edges.map((edge, i) => (
-
+
+
+
+
+ {pickDiagramText(locale, UI_TEXT.readLabel)}
+
+
+ {pickDiagramText(locale, UI_TEXT.readTitle)}
+
+
+ {pickDiagramText(locale, UI_TEXT.readNote)}
+
+
- {flow.nodes.map((node, i) => (
-
-
- ))}
-
+ {guide && (
+
+
+
+ {pickDiagramText(locale, UI_TEXT.focusLabel)}
+
+
+ {guide.focus}
+
+
+
+
+ {pickDiagramText(locale, UI_TEXT.confusionLabel)}
+
+
+ {guide.confusion}
+
+
+
+
+ {pickDiagramText(locale, UI_TEXT.goalLabel)}
+
+
+ {guide.goal}
+
+
+
+ )}
+
+
+
+
+ {pickDiagramText(locale, UI_TEXT.legendLabel)}
+
+
+ {(
+ Object.keys(NODE_GUIDE) as Array
+ ).map((nodeType) => (
+
+
+
+ {pickDiagramText(locale, NODE_GUIDE[nodeType].title)}
+
+
+
+ {pickDiagramText(locale, NODE_GUIDE[nodeType].note)}
+
+
+
+
+
+
+
+
+
+
+ {pickDiagramText(locale, UI_TEXT.sideLane)}
+
+
+ {pickDiagramText(locale, UI_TEXT.sideLaneNote)}
+
+
+
+
+ {pickDiagramText(locale, UI_TEXT.mainline)}
+
+
+ {pickDiagramText(locale, UI_TEXT.mainlineNote)}
+
+
+
+
+ {pickDiagramText(locale, UI_TEXT.sideLane)}
+
+
+ {pickDiagramText(locale, UI_TEXT.sideLaneNote)}
+
+
+
+
+
+
+
+
+
+
+
+
+
+ {flow.edges.map((edge, i) => (
+
+
+ ))}
+
+
+
+
+ {pickDiagramText(locale, UI_TEXT.bottomNote)}
+
+
+
> = {
+ 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> = {
+ 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> = {
+ 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> = {
+ 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> = {
+ 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 (
+
+
+
+ {pick(locale, TOOL_RUNTIME_TEXT.label)}
+
+
+ {pick(locale, TOOL_RUNTIME_TEXT.title)}
+
+
+ {pick(locale, TOOL_RUNTIME_TEXT.note)}
+
+
+
+
+ {pick(locale, TOOL_RUNTIME_TEXT.angleLabel)}
+
+
+ {angle}
+
+
+
+
+
+
+ {TOOL_RUNTIME_TEXT.stages.map((stage) => (
+
+
+ {pick(locale, stage.eyebrow)}
+
+
+ {pick(locale, stage.title)}
+
+
+ {pick(locale, stage.body)}
+
+
+ ))}
+
+
+
+
+
+ {pick(locale, TOOL_RUNTIME_TEXT.safeLane.title)}
+
+
+ {pick(locale, TOOL_RUNTIME_TEXT.safeLane.body)}
+
+
+
+
+ {pick(locale, TOOL_RUNTIME_TEXT.exclusiveLane.title)}
+
+
+ {pick(locale, TOOL_RUNTIME_TEXT.exclusiveLane.body)}
+
+
+
+
+
+
+
+
+ {pick(locale, TOOL_RUNTIME_TEXT.rulesLabel)}
+
+
+ {TOOL_RUNTIME_TEXT.rules.map((rule) => (
+
+
+ {pick(locale, rule.title)}
+
+
+ {pick(locale, rule.body)}
+
+
+ ))}
+
+
+
+
+
+ {pick(locale, TOOL_RUNTIME_TEXT.recordsLabel)}
+
+
+ {TOOL_RUNTIME_TEXT.records.map((record) => (
+
+
+ {record.name}
+
+
+ {pick(locale, record.note)}
+
+
+ ))}
+
+
+
+
+
+ );
+}
+
+function QueryTransitionLens({
+ locale,
+ angle,
+}: {
+ locale: string;
+ angle: string;
+}) {
+ return (
+
+
+
+ {pick(locale, QUERY_TRANSITION_TEXT.label)}
+
+
+ {pick(locale, QUERY_TRANSITION_TEXT.title)}
+
+
+ {pick(locale, QUERY_TRANSITION_TEXT.note)}
+
+
+
+
+ {pick(locale, QUERY_TRANSITION_TEXT.angleLabel)}
+
+
+ {angle}
+
+
+
+
+
+
+ {pick(locale, QUERY_TRANSITION_TEXT.chainLabel)}
+
+
+ {QUERY_TRANSITION_TEXT.chain.map((item, index) => (
+
+
+
+ {pick(locale, item.title)}
+
+
+ {pick(locale, item.body)}
+
+
+ {index < QUERY_TRANSITION_TEXT.chain.length - 1 && (
+
+ )}
+
+ ))}
+
+
+
+
+
+
+ {pick(locale, QUERY_TRANSITION_TEXT.reasonsLabel)}
+
+
+ {QUERY_TRANSITION_TEXT.reasons.map((reason) => (
+
+
+ {reason.name}
+
+
+ {pick(locale, reason.note)}
+
+
+ ))}
+
+
+
+
+
+ {pick(locale, QUERY_TRANSITION_TEXT.guardrailLabel)}
+
+
+ {QUERY_TRANSITION_TEXT.guardrails.map((item) => (
+
+
+ {pick(locale, item.title)}
+
+
+ ))}
+
+
+
+
+
+ );
+}
+
+function TaskRuntimeLens({
+ locale,
+ angle,
+}: {
+ locale: string;
+ angle: string;
+}) {
+ return (
+
+
+
+ {pick(locale, TASK_RUNTIME_TEXT.label)}
+
+
+ {pick(locale, TASK_RUNTIME_TEXT.title)}
+
+
+ {pick(locale, TASK_RUNTIME_TEXT.note)}
+
+
+
+
+ {pick(locale, TASK_RUNTIME_TEXT.angleLabel)}
+
+
+ {angle}
+
+
+
+
+
+
+
+ {pick(locale, TASK_RUNTIME_TEXT.layersLabel)}
+
+
+ {TASK_RUNTIME_TEXT.layers.map((layer) => (
+
+
+ {pick(locale, layer.title)}
+
+
+ {pick(locale, layer.body)}
+
+
+ ))}
+
+
+
+
+
+ {pick(locale, TASK_RUNTIME_TEXT.flowLabel)}
+
+
+ {TASK_RUNTIME_TEXT.flow.map((item, index) => (
+
+
+
+ {pick(locale, item.title)}
+
+
+ {pick(locale, item.body)}
+
+
+ {index < TASK_RUNTIME_TEXT.flow.length - 1 && (
+
+ )}
+
+ ))}
+
+
+
+
+
+
+ {pick(locale, TASK_RUNTIME_TEXT.recordsLabel)}
+
+
+ {TASK_RUNTIME_TEXT.records.map((record) => (
+
+
+ {record.name}
+
+
+ {pick(locale, record.note)}
+
+
+ ))}
+
+
+
+
+ );
+}
+
+function TeamBoundaryLens({
+ locale,
+ angle,
+}: {
+ locale: string;
+ angle: string;
+}) {
+ return (
+
+
+
+ {pick(locale, TEAM_BOUNDARY_TEXT.label)}
+
+
+ {pick(locale, TEAM_BOUNDARY_TEXT.title)}
+
+
+ {pick(locale, TEAM_BOUNDARY_TEXT.note)}
+
+
+
+
+ {pick(locale, TEAM_BOUNDARY_TEXT.angleLabel)}
+
+
+ {angle}
+
+
+
+
+
+
+ {pick(locale, TEAM_BOUNDARY_TEXT.layersLabel)}
+
+
+ {TEAM_BOUNDARY_TEXT.layers.map((layer) => (
+
+
+ {pick(locale, layer.title)}
+
+
+ {pick(locale, layer.body)}
+
+
+ ))}
+
+
+
+
+
+ {pick(locale, TEAM_BOUNDARY_TEXT.rulesLabel)}
+
+
+ {TEAM_BOUNDARY_TEXT.rules.map((rule) => (
+
+
+ {pick(locale, rule.title)}
+
+
+ {pick(locale, rule.body)}
+
+
+ ))}
+
+
+
+
+ );
+}
+
+function CapabilityLayerLens({
+ locale,
+ angle,
+}: {
+ locale: string;
+ angle: string;
+}) {
+ return (
+
+
+
+ {pick(locale, CAPABILITY_LAYER_TEXT.label)}
+
+
+ {pick(locale, CAPABILITY_LAYER_TEXT.title)}
+
+
+ {pick(locale, CAPABILITY_LAYER_TEXT.note)}
+
+
+
+
+ {pick(locale, CAPABILITY_LAYER_TEXT.angleLabel)}
+
+
+ {angle}
+
+
+
+
+
+
+ {pick(locale, CAPABILITY_LAYER_TEXT.layersLabel)}
+
+
+ {CAPABILITY_LAYER_TEXT.layers.map((layer) => (
+
+
+ {pick(locale, layer.title)}
+
+
+ {pick(locale, layer.body)}
+
+
+ ))}
+
+
+
+
+
+ {pick(locale, CAPABILITY_LAYER_TEXT.teachLabel)}
+
+
+ {CAPABILITY_LAYER_TEXT.teach.map((step) => (
+
+
+ {pick(locale, step.title)}
+
+
+ {pick(locale, step.body)}
+
+
+ ))}
+
+
+
+
+ );
+}
+
+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 (
+
+
+
+ {pick(locale, SECTION_TEXT.label)}
+
+
+ {pick(locale, SECTION_TEXT.title)}
+
+
+ {pick(locale, SECTION_TEXT.body)}
+
+
1 ? "2xl:grid-cols-2" : ""}`}>
+ {toolAngle &&
+
+ );
+}
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 (
-
+
{oldLabel}
@@ -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")}
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")}
@@ -79,8 +81,8 @@ function UnifiedView({ changes }: { changes: Change[] }) {
}
return (
-
-
+
+
{rows.map((row, i) => (
-
+
+
{rows.map((row, 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) => ``
);
+ // Wrap markdown tables so wide teaching maps scroll locally instead of
+ // stretching the whole doc page.
+ html = html.replace(//g, '");
+
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 = {
- 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 = {
+ 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 (
-
-
+
+
{LAYERS.map((layer) => (
-
-
+
+
{tLayer(layer.id)}
@@ -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
Promise<{ default: Scenario }>> = {
s01: () => import("@/data/scenarios/s01.json") as Promise<{ default: Scenario }>,
@@ -23,21 +27,1416 @@ const scenarioModules: Record 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 = {
+ 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 = {
+ 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 = {
+ 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(null);
const scrollRef = useRef(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 (
+
+ {t("simulator")}
+
+ {locale === "zh"
+ ? "正在加载当前章节的模拟场景..."
+ : locale === "ja"
+ ? "この章のシミュレーションを読み込んでいます..."
+ : "Loading the simulation scenario for this chapter..."}
+
+
+ );
+ }
+
+ const readyText =
+ locale === "zh"
+ ? "点击播放或单步开始"
+ : locale === "ja"
+ ? "再生またはステップで開始"
+ : "Press Play or Step to begin";
return (
@@ -81,7 +1500,7 @@ export function AgentLoopSimulator({ version }: AgentLoopSimulatorProps) {
>
{sim.visibleSteps.length === 0 && (
- Press Play or Step to begin
+ {readyText}
)}
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")}
>
- {config.label}
+ {label}
{step.toolName && (
{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 = {
- 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 = {
- 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 = {
- 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 (
-
+
{/* Layer Legend */}
@@ -60,7 +63,7 @@ export function Timeline() {
{layer.label}
+ {tLayer(layer.id)}
))}
@@ -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 (
-
- {/* Timeline line + dot */}
-
-
+ {isLayerStart && layerMeta && (
+
-
- {versionId.replace("s", "").replace("_mini", "m")}
-
-
- {!isLast && (
+
+
+
+ {tLayer(meta.layer)}
+
+ {layerRange}
+
+
+
+ {tLayersPage(meta.layer)}
+
+
+ {tLayersPage(`${meta.layer}_outcome`)}
+
+
+
+ {t("layer_legend")}
+
+
+
+ )}
+
+
+ {/* Timeline line + dot */}
+
-
- {/* Content card */}
-
-
-
- {versionId}
-
- {meta.coreAddition}
-
-
-
-
- {meta.title}
-
- {meta.subtitle}
-
-
-
- {/* Stats row */}
-
-
- {data.loc} {tv("loc")}
-
-
- {data.tools.length} {tv("tools")}
+ >
+
+ {versionId.replace("s", "").replace("_mini", "m")}
-
- {/* LOC bar */}
-
-
- {/* Key insight */}
- {meta.keyInsight && (
-
- “{meta.keyInsight}”
-
)}
+
- {/* Link */}
-
+
- {t("learn_more")}
- →
-
-
+
+ {versionId}
+
+ {content.coreAddition}
+
+
+
+
+ {tSession(versionId) || meta.title}
+
+ {content.subtitle}
+
+
+
+ {/* Stats row */}
+
+
+ {data.loc} {tv("loc")}
+
+
+ {data.tools.length} {tv("tools")}
+
+
+
+ {/* LOC bar */}
+
+
+ {/* Key insight */}
+ {content.keyInsight && (
+
+ “{content.keyInsight}”
+
+ )}
+
+ {/* Link */}
+
+ {t("learn_more")}
+
→
+
+
+
);
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
= {
+ 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 = {
+ core: "ring-blue-500/20",
+ hardening: "ring-emerald-500/20",
+ runtime: "ring-amber-500/20",
+ platform: "ring-red-500/20",
+};
+
+const ZH_COPY: Record = {
+ 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 = {
+ 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 (
+
+
+
+
+
+
+ {tLayer(meta.layer)}
+
+ {copy.eyebrow}
+
+
+
+ {title || tSession(version)}
+
+
+ {copy.summary}
+
+
+ {coreAdditionLabel}
+
+ {content.coreAddition}
+
+
+
+
+
+ {hasLateStageTeachingMap(version) && (
+
+
+ )}
+
+
+ {copy.sections.map((section, index) => (
+
+
+ 0{index + 1}
+
+
+ {section.title}
+
+
+ {section.body}
+
+
+ ))}
+
+
+
+
+
+ {copy.flowLabel}
+
+
+ {copy.flow.map((step, index) => (
+
+
+
+ {index + 1}
+
+ {step}
+
+ {index < copy.flow.length - 1 && (
+ ->
+ )}
+
+ ))}
+
+
+
+
+
+
+ {copy.cautionLabel}
+
+
+ {copy.caution}
+
+
+
+
+ {copy.outcomeLabel}
+
+
+ {copy.outcome}
+
+
+
+
+
+ );
+}
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
-
);
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 = {
+ 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 (
+
+
+
+
+
+ {pick(locale, UI_TEXT.label)}
+
+
+
+ {pick(locale, UI_TEXT.title)}
+
+
+ {pick(locale, UI_TEXT.body)}
+
+
+
+
+
+
+
+
+
+
+
+
+
+ {pick(locale, UI_TEXT.systemLanes)}
+
+
+
+ {version.toUpperCase()}
+
+
+ {scenario.lanes.map((lane, laneIndex) => {
+ const laneNodes = scenario.nodes.filter((node) => node.lane === lane.id);
+ return (
+
+
+
+
+ {pick(locale, lane.label)}
+
+
+ {pick(locale, lane.note)}
+
+
+
+
+ {laneNodes.map((node, nodeIndex) => {
+ const isActive = activeNodes.has(node.id);
+ return (
+
+
+ {pick(locale, node.label)}
+
+
+ {pick(locale, node.detail)}
+
+
+ );
+ })}
+
+
+ );
+ })}
+
+
+
+
+
+ {pick(locale, UI_TEXT.activePath)}
+
+
+ {step.activeNodes.map((nodeId, index) => {
+ const node = nodeMap.get(nodeId);
+ if (!node) return null;
+ return (
+
+
+ {pick(locale, node.label)}
+
+ {index < step.activeNodes.length - 1 && (
+ ->
+ )}
+
+ );
+ })}
+
+
+
+ {pick(locale, UI_TEXT.activeRecords)}
+
+
+ {scenario.records.map((record) => {
+ const isActive = activeRecords.has(record.id);
+ return (
+
+
+
+ {pick(locale, record.label)}
+
+ {!isActive && (
+
+ {pick(locale, UI_TEXT.inactiveRecord)}
+
+ )}
+
+
+ {pick(locale, record.note)}
+
+
+ );
+ })}
+
+
+
+ {pick(locale, UI_TEXT.boundary)}
+
+
+ {pick(locale, step.boundary)}
+
+
+
+ {pick(locale, UI_TEXT.writeBack)}
+
+
+ {pick(locale, step.writeBack)}
+
+
+
+
+
> = [
+ { 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;
+ 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 (
- {title || "The Agent While-Loop"}
+ {title || copy.title}
- {/* Left panel: SVG Flowchart (60%) */}
- while (stop_reason === "tool_use")
+ {copy.loopLabel}
+
-
+
- {/* 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 (
@@ -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 }) {
{
+ {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 (
= 5 && (
- iter #2
+ {copy.iterationLabel}
)}
- {/* Right panel: messages[] array (40%) */}
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}
)}
- {visibleMessages.map((msg, i) => (
+
+ {visibleMessages.map((message, index) => (
- {msg.role}
+ {message.role}
- {msg.detail}
+ {message.detail}
))}
- {/* Array index markers */}
{visibleMessages.length > 0 && (
- length: {visibleMessages.length}
+ {copy.lengthLabel}: {visibleMessages.length}
)}
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 (
{/* Annotation */}
@@ -46,7 +49,8 @@ export function StepControls({
@@ -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")}
>
{isPlaying ?
@@ -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")}
>
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
>;
+ records: ArchitectureItem[];
+ handoff: LocalizedText[];
+}
+
+const l = (zh: string, en: string): LocalizedText => ({ zh, en });
+
+export const ARCHITECTURE_BLUEPRINTS: Record = {
+ 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 = {
+ 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 = {
s01: {
nodes: [
@@ -142,14 +284,14 @@ export const EXECUTION_FLOWS: Record = {
{ 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 = {
{ 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 = {
{ 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 = {
{ 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 = {
{ 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 = {
{ 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 = {
{ 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 = {
};
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..17ec65271 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## 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 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\": \"Update your todos. \",\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 | `` 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 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\": \"Update your todos. \",\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 | `` 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 `` 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| |\n| Full git workflow instructions... | ~2000 tokens\n| Step 1: ... |\n| |\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\"\\n{skill['body']}\\n \"\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| |\n| Full git workflow instructions... | ~2000 tokens\n| Step 1: ... |\n| |\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\"\\n{skill['body']}\\n \"\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 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: \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 # \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\"\\n{notif_text}\\n\"\n f\" \"})\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} \"})\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 (`/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} \"})\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\"Task #{unclaimed[0]['id']}: \"\n f\"{unclaimed[0]['subject']} \"})\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\"You are '{name}', role: {role}, \"\n f\"team: {team_name}. Continue your work. \"})\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\"\\n{notif_text}\\n\"\n f\" \"})\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} \"})\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} \"})\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\"Task #{unclaimed[0]['id']}: \"\n f\"{unclaimed[0]['subject']} \"})\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\"You are '{name}', role: {role}, \"\n f\"team: {team_name}. Continue your work. \"})\n messages.insert(1, {\"role\": \"assistant\",\n \"content\": f\"I am {name}. Continuing.\"})\n```\n\n## Read Together\n\n- If teammate, task, and runtime slot are starting to blur into one layer, revisit [`team-task-lane-model.md`](./team-task-lane-model.md) to separate them clearly.\n- If auto-claim makes you wonder where the live execution slot actually lives, keep [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) nearby.\n- If you are starting to forget the core difference between a persistent teammate and a one-shot subagent, revisit [`entity-map.md`](./entity-map.md).\n\n## What Changed From s16\n\n| Component | Before (s16) | After (s17) |\n|----------------|------------------|----------------------------|\n| Tools | 12 | 14 (+idle, +claim_task) |\n| Autonomy | Lead-directed | Self-organizing |\n| Idle phase | None | Poll inbox + task board |\n| Task claiming | Manual only | Auto-claim unclaimed tasks |\n| Identity | System prompt | + re-injection after compress|\n| Timeout | None | 60s idle -> auto shutdown |\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s17_autonomous_agents.py\n```\n\n1. `Create 3 tasks on the board, then spawn alice and bob. Watch them auto-claim.`\n2. `Spawn a coder teammate and let it find work from the task board itself`\n3. `Create tasks with dependencies. Watch teammates respect the blocked order.`\n4. Type `/tasks` to see the task board with owners\n5. Type `/team` to monitor who is working vs idle\n\n## What You've Mastered\n\nAt this point, you can:\n\n- Build teammates that find and claim work from a shared task board without lead intervention\n- Implement an idle polling loop that balances responsiveness with resource efficiency\n- Restore agent identity after context compression so long-running teammates stay coherent\n- Use timeout-based shutdown to prevent abandoned agents from running indefinitely\n\n## What's Next\n\nYour teammates now organize themselves, but they all share the same working directory. When two agents edit the same file at the same time, things break. In s18, you will give each teammate its own isolated worktree -- a separate copy of the codebase where it can work without stepping on anyone else's changes.\n\n## Key Takeaway\n\n> Autonomous teammates scan the task board, claim unclaimed work, and shut down when idle -- removing the lead as a coordination bottleneck.\n"
+ },
+ {
+ "version": "s18",
+ "slug": "s18-worktree-task-isolation",
+ "locale": "en",
+ "title": "s18: Worktree + Task Isolation",
+ "kind": "chapter",
+ "filename": "s18-worktree-task-isolation.md",
+ "content": "# s18: Worktree + Task Isolation\n\n`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > [ s18 ] > s19`\n\n## What You'll Learn\n- How git worktrees (isolated copies of your project directory, managed by git) prevent file conflicts between parallel agents\n- How to bind a task to a dedicated worktree so that \"what to do\" and \"where to do it\" stay cleanly separated\n- How lifecycle events give you an observable record of every create, keep, and remove action\n- How parallel execution lanes let multiple agents work on different tasks without ever stepping on each other's files\n\nWhen two agents both need to edit the same codebase at the same time, you have a problem. Everything you have built so far -- task boards, autonomous agents, team protocols -- assumes that agents work in a single shared directory. That works fine until it does not. This chapter gives every task its own directory, so parallel work stays parallel.\n\n## The Problem\n\nBy s17, your agents can claim tasks, coordinate through team protocols, and complete work autonomously. But all of them run in the same project directory. Imagine agent A is refactoring the authentication module, and agent B is building a new login page. Both need to touch `config.py`. Agent A stages its changes, agent B stages different changes to the same file, and now you have a tangled mess of unstaged edits that neither agent can roll back cleanly.\n\nThe task board tracks *what to do* but has no opinion about *where to do it*. You need a way to give each task its own isolated working directory, so that file-level operations never collide. The fix is straightforward: pair each task with a git worktree -- a separate checkout of the same repository on its own branch. Tasks manage goals; worktrees manage execution context. Bind them by task ID.\n\n## Read Together\n\n- If task, runtime slot, and worktree lane are blurring together in your head, [`team-task-lane-model.md`](./team-task-lane-model.md) separates them clearly.\n- If you want to confirm which fields belong on task records versus worktree records, [`data-structures.md`](./data-structures.md) has the full schema.\n- If you want to see why this chapter comes after tasks and teams in the overall curriculum, [`s00e-reference-module-map.md`](./s00e-reference-module-map.md) has the ordering rationale.\n\n## The Solution\n\nThe system splits into two planes: a control plane (`.tasks/`) that tracks goals, and an execution plane (`.worktrees/`) that manages isolated directories. Each task points to its worktree by name, and each worktree points back to its task by ID.\n\n```\nControl plane (.tasks/) Execution plane (.worktrees/)\n+------------------+ +------------------------+\n| task_1.json | | auth-refactor/ |\n| status: in_progress <------> branch: wt/auth-refactor\n| worktree: \"auth-refactor\" | task_id: 1 |\n+------------------+ +------------------------+\n| task_2.json | | ui-login/ |\n| status: pending <------> branch: wt/ui-login\n| worktree: \"ui-login\" | task_id: 2 |\n+------------------+ +------------------------+\n |\n index.json (worktree registry)\n events.jsonl (lifecycle log)\n\nState machines:\n Task: pending -> in_progress -> completed\n Worktree: absent -> active -> removed | kept\n```\n\n## How It Works\n\n**Step 1.** Create a task. The goal is recorded first, before any directory exists.\n\n```python\nTASKS.create(\"Implement auth refactor\")\n# -> .tasks/task_1.json status=pending worktree=\"\"\n```\n\n**Step 2.** Create a worktree and bind it to the task. Passing `task_id` automatically advances the task to `in_progress` -- you do not need to update the status separately.\n\n```python\nWORKTREES.create(\"auth-refactor\", task_id=1)\n# -> git worktree add -b wt/auth-refactor .worktrees/auth-refactor HEAD\n# -> index.json gets new entry, task_1.json gets worktree=\"auth-refactor\"\n```\n\nThe binding writes state to both sides so you can traverse the relationship from either direction:\n\n```python\ndef bind_worktree(self, task_id, worktree):\n task = self._load(task_id)\n task[\"worktree\"] = worktree\n if task[\"status\"] == \"pending\":\n task[\"status\"] = \"in_progress\"\n self._save(task)\n```\n\n**Step 3.** Run commands in the worktree. The key detail: `cwd` points to the isolated directory, not your main project root. Every file operation happens in a sandbox that cannot collide with other worktrees.\n\n```python\nsubprocess.run(command, shell=True, cwd=worktree_path,\n capture_output=True, text=True, timeout=300)\n```\n\n**Step 4.** Close out the worktree. You have two choices, depending on whether the work is done:\n\n- `worktree_keep(name)` -- preserve the directory for later (useful when a task is paused or needs review).\n- `worktree_remove(name, complete_task=True)` -- remove the directory, mark the bound task as completed, and emit an event. One call handles teardown and completion together.\n\n```python\ndef remove(self, name, force=False, complete_task=False):\n self._run_git([\"worktree\", \"remove\", wt[\"path\"]])\n if complete_task and wt.get(\"task_id\") is not None:\n self.tasks.update(wt[\"task_id\"], status=\"completed\")\n self.tasks.unbind_worktree(wt[\"task_id\"])\n self.events.emit(\"task.completed\", ...)\n```\n\n**Step 5.** Observe the event stream. Every lifecycle step emits a structured event to `.worktrees/events.jsonl`, giving you a complete audit trail of what happened and when:\n\n```json\n{\n \"event\": \"worktree.remove.after\",\n \"task\": {\"id\": 1, \"status\": \"completed\"},\n \"worktree\": {\"name\": \"auth-refactor\", \"status\": \"removed\"},\n \"ts\": 1730000000\n}\n```\n\nEvents emitted: `worktree.create.before/after/failed`, `worktree.remove.before/after/failed`, `worktree.keep`, `task.completed`.\n\nIn the teaching version, `.tasks/` plus `.worktrees/index.json` are enough to reconstruct the visible control-plane state after a crash. The important lesson is not every production edge case. The important lesson is that goal state and execution-lane state must both stay legible on disk.\n\n## What Changed From s17\n\n| Component | Before (s17) | After (s18) |\n|--------------------|----------------------------|----------------------------------------------|\n| Coordination | Task board (owner/status) | Task board + explicit worktree binding |\n| Execution scope | Shared directory | Task-scoped isolated directory |\n| Recoverability | Task status only | Task status + worktree index |\n| Teardown | Task completion | Task completion + explicit keep/remove |\n| Lifecycle visibility | Implicit in logs | Explicit events in `.worktrees/events.jsonl` |\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s18_worktree_task_isolation.py\n```\n\n1. `Create tasks for backend auth and frontend login page, then list tasks.`\n2. `Create worktree \"auth-refactor\" for task 1, then bind task 2 to a new worktree \"ui-login\".`\n3. `Run \"git status --short\" in worktree \"auth-refactor\".`\n4. `Keep worktree \"ui-login\", then list worktrees and inspect events.`\n5. `Remove worktree \"auth-refactor\" with complete_task=true, then list tasks/worktrees/events.`\n\n## What You've Mastered\n\nAt this point, you can:\n\n- Create isolated git worktrees so that parallel agents never produce file conflicts\n- Bind tasks to worktrees with a two-way reference (task points to worktree name, worktree points to task ID)\n- Choose between keeping and removing a worktree at closeout, with automatic task status updates\n- Read the event stream in `events.jsonl` to understand the full lifecycle of every worktree\n\n## What's Next\n\nYou now have agents that can work in complete isolation, each in its own directory with its own branch. But every capability they use -- bash, read, write, edit -- is hard-coded into your Python harness. In s19, you will learn how external programs can provide new capabilities through MCP (Model Context Protocol), so your agent can grow without changing its core code.\n\n## Key Takeaway\n\n> Tasks answer *what work is being done*; worktrees answer *where that work runs*; keeping them separate makes parallel systems far easier to reason about and recover from.\n"
+ },
+ {
+ "version": "s19",
+ "slug": "s19-mcp-plugin",
+ "locale": "en",
+ "title": "s19: MCP & Plugin",
+ "kind": "chapter",
+ "filename": "s19-mcp-plugin.md",
+ "content": "# s19: MCP & Plugin\n\n`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > [ s19 ]`\n\n## What You'll Learn\n- How MCP (Model Context Protocol -- a standard way for the agent to talk to external capability servers) lets your agent gain new tools without changing its core code\n- How tool name normalization with a `mcp__{server}__{tool}` prefix keeps external tools from colliding with native ones\n- How a unified router dispatches tool calls to local handlers or remote servers through the same path\n- How plugin manifests let external capability servers be discovered and launched automatically\n\nUp to this point, every tool your agent uses -- bash, read, write, edit, tasks, worktrees -- lives inside your Python harness. You wrote each one by hand. That works well for a teaching codebase, but a real agent needs to talk to databases, browsers, cloud services, and tools that do not exist yet. Hard-coding every possible capability is not sustainable. This chapter shows how external programs can join your agent through the same tool-routing plane you already built.\n\n## The Problem\n\nYour agent is powerful, but its capabilities are frozen at build time. If you want it to query a Postgres database, you write a new Python handler. If you want it to control a browser, you write another handler. Every new capability means changing the core harness, re-testing the tool router, and redeploying. Meanwhile, other teams are building specialized servers that already know how to talk to these systems. You need a standard protocol so those external servers can expose their tools to your agent, and your agent can call them as naturally as it calls its own native tools -- without rewriting the core loop every time.\n\n## The Solution\n\nMCP gives your agent a standard way to connect to external capability servers over stdio. The agent starts a server process, asks what tools it provides, normalizes their names with a prefix, and routes calls to that server -- all through the same tool pipeline that handles native tools.\n\n```text\nLLM\n |\n | asks to call a tool\n v\nAgent tool router\n |\n +-- native tool -> local Python handler\n |\n +-- MCP tool -> external MCP server\n |\n v\n return result\n```\n\n## Read Together\n\n- If you want to understand how MCP fits into the broader capability surface beyond just tools (resources, prompts, plugin discovery), [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md) covers the full platform boundary.\n- If you want to confirm that external capabilities still return through the same execution surface as native tools, pair this chapter with [`s02b-tool-execution-runtime.md`](./s02b-tool-execution-runtime.md).\n- If query control and external capability routing are drifting apart in your mental model, [`s00a-query-control-plane.md`](./s00a-query-control-plane.md) ties them together.\n\n## How It Works\n\nThere are three essential pieces. Once you understand them, MCP stops being mysterious.\n\n**Step 1.** Build an `MCPClient` that manages the connection to one external server. It starts the server process over stdio, sends a handshake, and caches the list of available tools.\n\n```python\nclass MCPClient:\n def __init__(self, server_name, command, args=None, env=None):\n self.server_name = server_name\n self.command = command\n self.args = args or []\n self.process = None\n self._tools = []\n\n def connect(self):\n self.process = subprocess.Popen(\n [self.command] + self.args,\n stdin=subprocess.PIPE, stdout=subprocess.PIPE,\n stderr=subprocess.PIPE, text=True,\n )\n self._send({\"method\": \"initialize\", \"params\": {\n \"protocolVersion\": \"2024-11-05\",\n \"capabilities\": {},\n \"clientInfo\": {\"name\": \"teaching-agent\", \"version\": \"1.0\"},\n }})\n response = self._recv()\n if response and \"result\" in response:\n self._send({\"method\": \"notifications/initialized\"})\n return True\n return False\n\n def list_tools(self):\n self._send({\"method\": \"tools/list\", \"params\": {}})\n response = self._recv()\n if response and \"result\" in response:\n self._tools = response[\"result\"].get(\"tools\", [])\n return self._tools\n\n def call_tool(self, tool_name, arguments):\n self._send({\"method\": \"tools/call\", \"params\": {\n \"name\": tool_name, \"arguments\": arguments,\n }})\n response = self._recv()\n if response and \"result\" in response:\n content = response[\"result\"].get(\"content\", [])\n return \"\\n\".join(c.get(\"text\", str(c)) for c in content)\n return \"MCP Error: no response\"\n```\n\n**Step 2.** Normalize external tool names with a prefix so they never collide with native tools. The convention is simple: `mcp__{server}__{tool}`.\n\n```text\nmcp__postgres__query\nmcp__browser__open_tab\n```\n\nThis prefix serves double duty: it prevents name collisions, and it tells the router exactly which server should handle the call.\n\n```python\ndef get_agent_tools(self):\n agent_tools = []\n for tool in self._tools:\n prefixed_name = f\"mcp__{self.server_name}__{tool['name']}\"\n agent_tools.append({\n \"name\": prefixed_name,\n \"description\": tool.get(\"description\", \"\"),\n \"input_schema\": tool.get(\"inputSchema\", {\n \"type\": \"object\", \"properties\": {}\n }),\n })\n return agent_tools\n```\n\n**Step 3.** Build one unified router. The router does not care whether a tool is native or external beyond the dispatch decision. If the name starts with `mcp__`, route to the MCP server; otherwise, call the local handler. This keeps the agent loop untouched -- it just sees a flat list of tools.\n\n```python\nif tool_name.startswith(\"mcp__\"):\n return mcp_router.call(tool_name, arguments)\nelse:\n return native_handler(arguments)\n```\n\n**Step 4.** Add plugin discovery. If MCP answers \"how does the agent talk to an external capability server,\" plugins answer \"how are those servers discovered and configured?\" A minimal plugin is a manifest file that tells the harness which servers to launch:\n\n```json\n{\n \"name\": \"my-db-tools\",\n \"version\": \"1.0.0\",\n \"mcpServers\": {\n \"postgres\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-postgres\"]\n }\n }\n}\n```\n\nThis lives in `.claude-plugin/plugin.json`. The `PluginLoader` scans for these manifests, extracts the server configs, and hands them to the `MCPToolRouter` for connection.\n\n**Step 5.** Enforce the safety boundary. This is the most important rule of the entire chapter: external tools must still pass through the same permission gate as native tools. If MCP tools bypass permission checks, you have created a security backdoor at the edge of your system.\n\n```python\ndecision = permission_gate.check(block.name, block.input or {})\n# Same check for \"bash\", \"read_file\", and \"mcp__postgres__query\"\n```\n\n## How It Plugs Into The Full Harness\n\nMCP gets confusing when it is treated like a separate universe. The cleaner model is:\n\n```text\nstartup\n ->\nplugin loader finds manifests\n ->\nserver configs are extracted\n ->\nMCP clients connect and list tools\n ->\nexternal tools are normalized into the same tool pool\n\nruntime\n ->\nLLM emits tool_use\n ->\nshared permission gate\n ->\nnative route or MCP route\n ->\nresult normalization\n ->\ntool_result returns to the same loop\n```\n\nDifferent entry point, same control plane and execution plane.\n\n## Plugin vs Server vs Tool\n\n| Layer | What it is | What it is for |\n|---|---|---|\n| plugin manifest | a config declaration | tells the harness which servers to discover and launch |\n| MCP server | an external process / connection | exposes a set of capabilities |\n| MCP tool | one callable capability from that server | the concrete thing the model invokes |\n\nShortest memory aid:\n\n- plugin = discovery\n- server = connection\n- tool = invocation\n\n## Key Data Structures\n\n### Server config\n\n```python\n{\n \"command\": \"npx\",\n \"args\": [\"-y\", \"...\"],\n \"env\": {}\n}\n```\n\n### Normalized external tool definition\n\n```python\n{\n \"name\": \"mcp__postgres__query\",\n \"description\": \"Run a SQL query\",\n \"input_schema\": {...}\n}\n```\n\n### Client registry\n\n```python\nclients = {\n \"postgres\": mcp_client_instance\n}\n```\n\n## What Changed From s18\n\n| Component | Before (s18) | After (s19) |\n|--------------------|-----------------------------------|--------------------------------------------------|\n| Tool sources | All native (local Python) | Native + external MCP servers |\n| Tool naming | Flat names (`bash`, `read_file`) | Prefixed for externals (`mcp__postgres__query`) |\n| Routing | Single handler map | Unified router: native dispatch + MCP dispatch |\n| Capability growth | Edit harness code for each tool | Add a plugin manifest or connect a server |\n| Permission scope | Native tools only | Native + external tools through same gate |\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s19_mcp_plugin.py\n```\n\n1. Watch how external tools are discovered from plugin manifests at startup.\n2. Type `/tools` to see native and MCP tools listed side by side in one flat pool.\n3. Type `/mcp` to see which MCP servers are connected and how many tools each provides.\n4. Ask the agent to use a tool and notice how results return through the same loop as local tools.\n\n## What You've Mastered\n\nAt this point, you can:\n\n- Connect to external capability servers using the MCP stdio protocol\n- Normalize external tool names with a `mcp__{server}__{tool}` prefix to prevent collisions\n- Route tool calls through a unified dispatcher that handles both native and MCP tools\n- Discover and launch MCP servers automatically through plugin manifests\n- Enforce the same permission checks on external tools as on native ones\n\n## The Full Picture\n\nYou have now walked through the complete design backbone of a production coding agent, from s01 to s19.\n\nYou started with a bare agent loop that calls an LLM and appends tool results. You added tool use, then a persistent task list, then subagents, skill loading, and context compaction. You built a permission system, a hook system, and a memory system. You constructed the system prompt pipeline, added error recovery, and gave agents a full task board with background execution and cron scheduling. You organized agents into teams with coordination protocols, made them autonomous, gave each task its own isolated worktree, and finally opened the door to external capabilities through MCP.\n\nEach chapter added exactly one idea to the system. None of them required you to throw away what came before. The agent you have now is not a toy -- it is a working model of the same architectural decisions that shape real production agents.\n\nIf you want to test your understanding, try rebuilding the complete system from scratch. Start with the agent loop. Add tools. Add tasks. Keep going until you reach MCP. If you can do that without looking back at the chapters, you understand the design. And if you get stuck somewhere in the middle, the chapter that covers that idea will be waiting for you.\n\n## Key Takeaway\n\n> External capabilities should enter the same tool pipeline as native ones -- same naming, same routing, same permissions -- so the agent loop never needs to know the difference.\n"
+ },
+ {
+ "version": null,
+ "slug": "s19a-mcp-capability-layers",
+ "locale": "en",
+ "title": "s19a: MCP Capability Layers",
+ "kind": "bridge",
+ "filename": "s19a-mcp-capability-layers.md",
+ "content": "# s19a: MCP Capability Layers\n\n> **Deep Dive** -- Best read alongside s19. It shows that MCP is more than just external tools.\n\n### When to Read This\n\nAfter reading s19's tools-first approach, when you're ready to see the full MCP capability stack.\n\n---\n\n> `s19` should still keep a tools-first mainline.\n> This bridge note adds the second mental model:\n>\n> **MCP is not only external tool access. It is a stack of capability layers.**\n\n## How to Read This with the Mainline\n\nIf you want to study MCP without drifting away from the teaching goal:\n\n- read [`s19-mcp-plugin.md`](./s19-mcp-plugin.md) first and keep the tools-first path clear\n- then you might find it helpful to revisit [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md) to see how external capability routes back into the unified tool bus\n- if state records begin to blur, you might find it helpful to revisit [`data-structures.md`](./data-structures.md)\n- if concept boundaries blur, you might find it helpful to revisit [`glossary.md`](./glossary.md) and [`entity-map.md`](./entity-map.md)\n\n## Why This Deserves a Separate Bridge Note\n\nFor a teaching repo, keeping the mainline focused on external tools first is correct.\n\nThat is the easiest entry:\n\n- connect an external server\n- receive tool definitions\n- call a tool\n- bring the result back into the agent\n\nBut if you want the system shape to approach real high-completion behavior, you quickly meet deeper questions:\n\n- is the server connected through stdio, HTTP, SSE, or WebSocket\n- why are some servers `connected`, while others are `pending` or `needs-auth`\n- where do resources and prompts fit relative to tools\n- why does elicitation become a special kind of interaction\n- where should OAuth or other auth flows be placed conceptually\n\nWithout a capability-layer map, MCP starts to feel scattered.\n\n## Terms First\n\n### What capability layers means\n\nA capability layer is simply:\n\n> one responsibility slice in a larger system\n\nThe point is to avoid mixing every MCP concern into one bag.\n\n### What transport means\n\nTransport is the connection channel between your agent and an MCP server:\n\n- stdio (standard input/output, good for local processes)\n- HTTP\n- SSE (Server-Sent Events, a one-way streaming protocol over HTTP)\n- WebSocket\n\n### What elicitation means\n\nThis is one of the less familiar terms.\n\nA simple teaching definition is:\n\n> an interaction where the MCP server asks the user for more input before it can continue\n\nSo the system is no longer only:\n\n> agent calls tool -> tool returns result\n\nThe server can also say:\n\n> I need more information before I can finish\n\nThis turns a simple call-and-return into a multi-step conversation between the agent and the server.\n\n## The Minimum Mental Model\n\nA clear six-layer picture:\n\n```text\n1. Config Layer\n what the server configuration looks like\n\n2. Transport Layer\n how the server connection is carried\n\n3. Connection State Layer\n connected / pending / failed / needs-auth\n\n4. Capability Layer\n tools / resources / prompts / elicitation\n\n5. Auth Layer\n whether authentication is required and what state it is in\n\n6. Router Integration Layer\n how MCP routes back into tool routing, permissions, and notifications\n```\n\nThe key lesson is:\n\n**tools are one layer, not the whole MCP story**\n\n## Why the Mainline Should Still Stay Tools-First\n\nThis matters a lot for teaching.\n\nEven though MCP contains multiple layers, the chapter mainline should still teach:\n\n### Step 1: external tools first\n\nBecause that connects most naturally to everything you already learned:\n\n- local tools\n- external tools\n- one shared router\n\n### Step 2: show that more capability layers exist\n\nFor example:\n\n- resources\n- prompts\n- elicitation\n- auth\n\n### Step 3: decide which advanced layers the repo should actually implement\n\nThat matches the teaching goal:\n\n**build the similar system first, then add the heavier platform layers**\n\n## Core Records\n\n### 1. `ScopedMcpServerConfig`\n\nEven a minimal teaching version should expose this idea:\n\n```python\nconfig = {\n \"name\": \"postgres\",\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"...\"],\n \"scope\": \"project\",\n}\n```\n\n`scope` matters because server configuration may come from different places (global user settings, project-level settings, or even per-workspace overrides).\n\n### 2. MCP connection state\n\n```python\nserver_state = {\n \"name\": \"postgres\",\n \"status\": \"connected\", # pending / failed / needs-auth / disabled\n \"config\": {...},\n}\n```\n\n### 3. `MCPToolSpec`\n\n```python\ntool = {\n \"name\": \"mcp__postgres__query\",\n \"description\": \"...\",\n \"input_schema\": {...},\n}\n```\n\n### 4. `ElicitationRequest`\n\n```python\nrequest = {\n \"server_name\": \"some-server\",\n \"message\": \"Please provide additional input\",\n \"requested_schema\": {...},\n}\n```\n\nThe teaching point is not that you need to implement elicitation immediately.\n\nThe point is:\n\n**MCP is not guaranteed to stay a one-way tool invocation forever**\n\n## The Cleaner Platform Picture\n\n```text\nMCP Config\n |\n v\nTransport\n |\n v\nConnection State\n |\n +-- connected\n +-- pending\n +-- needs-auth\n +-- failed\n |\n v\nCapabilities\n +-- tools\n +-- resources\n +-- prompts\n +-- elicitation\n |\n v\nRouter / Permission / Notification Integration\n```\n\n## Why Auth Should Not Dominate the Chapter Mainline\n\nAuth is a real layer in the full platform.\n\nBut if the mainline falls into OAuth or vendor-specific auth flow details too early, beginners lose the actual system shape.\n\nA better teaching order is:\n\n- first explain that an auth layer exists\n- then explain that `connected` and `needs-auth` are different connection states\n- only later, in advanced platform work, expand the full auth state machine\n\nThat keeps the repo honest without derailing your learning path.\n\n## How This Relates to `s19` and `s02a`\n\n- the `s19` chapter keeps teaching the tools-first external capability path\n- this note supplies the broader platform map\n- `s02a` explains how MCP capability eventually reconnects to the unified tool control plane\n\nTogether, they teach the actual idea:\n\n**MCP is an external capability platform, and tools are only the first face of it that enters the mainline**\n\n## Common Beginner Mistakes\n\n### 1. Treating MCP as only an external tool catalog\n\nThat makes resources, prompts, auth, and elicitation feel surprising later.\n\n### 2. Diving into transport or OAuth details too early\n\nThat breaks the teaching mainline.\n\n### 3. Letting MCP tools bypass permission checks\n\nThat opens a dangerous side door in the system boundary.\n\n### 4. Mixing server config, connection state, and exposed capabilities into one blob\n\nThose layers should stay conceptually separate.\n\n## Key Takeaway\n\n**MCP is a six-layer capability platform. Tools are the first layer you build, but resources, prompts, elicitation, auth, and router integration are all part of the full picture.**\n"
+ },
+ {
+ "version": null,
+ "slug": "teaching-scope",
+ "locale": "en",
+ "title": "Teaching Scope",
+ "kind": "bridge",
+ "filename": "teaching-scope.md",
+ "content": "# Teaching Scope\n\nThis document explains what you will learn in this repo, what is deliberately left out, and how each chapter stays aligned with your mental model as it grows.\n\n## The Goal Of This Repo\n\nThis is not a line-by-line commentary on some upstream production codebase.\n\nThe real goal is:\n\n**teach you how to build a high-completion coding-agent harness from scratch.**\n\nThat implies three obligations:\n\n1. you can actually rebuild it\n2. you keep the mainline clear instead of drowning in side detail\n3. you do not absorb mechanisms that do not really exist\n\n## What Every Chapter Should Cover\n\nEvery mainline chapter should make these things explicit:\n\n- what problem the mechanism solves\n- which module or layer it belongs to\n- what state it owns\n- what data structures it introduces\n- how it plugs back into the loop\n- what changes in the runtime flow after it appears\n\nIf you finish a chapter and still cannot say where the mechanism lives or what state it owns, the chapter is not done yet.\n\n## What We Deliberately Keep Simple\n\nThese topics are not forbidden, but they should not dominate your learning path:\n\n- packaging, build, and release flow\n- cross-platform compatibility glue\n- telemetry and enterprise policy wiring\n- historical compatibility branches\n- product-specific naming accidents\n- line-by-line upstream code matching\n\nThose belong in appendices, maintainer notes, or later productization notes, not at the center of the beginner path.\n\n## What \"High Fidelity\" Really Means Here\n\nHigh fidelity in a teaching repo does not mean reproducing every edge detail 1:1.\n\nIt means staying close to the true system backbone:\n\n- core runtime model\n- module boundaries\n- key records\n- state transitions\n- cooperation between major subsystems\n\nIn short:\n\n**be highly faithful to the trunk, and deliberate about teaching simplifications at the edges.**\n\n## Who This Is For\n\nYou do not need to be an expert in agent platforms.\n\nA better assumption about you:\n\n- basic Python is familiar\n- functions, classes, lists, and dictionaries are familiar\n- agent systems may be completely new\n\nThat means the chapters should:\n\n- explain new concepts before using them\n- keep one concept complete in one main place\n- move from \"what it is\" to \"why it exists\" to \"how to build it\"\n\n## Recommended Chapter Structure\n\nMainline chapters should roughly follow this order:\n\n1. what problem appears without this mechanism\n2. first explain the new terms\n3. give the smallest useful mental model\n4. show the core records / data structures\n5. show the smallest correct implementation\n6. show how it plugs into the main loop\n7. show common beginner mistakes\n8. show what a higher-completion version would add later\n\n## Terminology Guideline\n\nIf a chapter introduces a term from these categories, it should explain it:\n\n- design pattern\n- data structure\n- concurrency term\n- protocol / networking term\n- uncommon engineering vocabulary\n\nExamples:\n\n- state machine\n- scheduler\n- queue\n- worktree\n- DAG\n- protocol envelope\n\nDo not drop the name without the explanation.\n\n## Minimal Correct Version Principle\n\nReal mechanisms are often complex, but teaching works best when it does not start with every branch at once.\n\nPrefer this sequence:\n\n1. show the smallest correct version\n2. explain what core problem it already solves\n3. show what later iterations would add\n\nExamples:\n\n- permission system: first `deny -> mode -> allow -> ask`\n- error recovery: first three major recovery branches\n- task system: first task records, dependencies, and unlocks\n- team protocols: first request / response plus `request_id`\n\n## Checklist For Rewriting A Chapter\n\n- Does the first screen explain why the mechanism exists?\n- Are new terms explained before they are used?\n- Is there a small mental model or flow picture?\n- Are key records listed explicitly?\n- Is the plug-in point back into the loop explained?\n- Are core mechanisms separated from peripheral product detail?\n- Are the easiest confusion points called out?\n- Does the chapter avoid inventing mechanisms not supported by the repo?\n\n## How To Use Reverse-Engineered Source Material\n\nReverse-engineered source should be used as:\n\n**maintainer calibration material**\n\nUse it to:\n\n- verify the mainline mechanism is described correctly\n- verify important boundaries and records are not missing\n- verify the teaching implementation did not drift into fiction\n\nIt should never become a prerequisite for understanding the teaching docs.\n\n## Key Takeaway\n\n**The quality of a teaching repo is decided less by how many details it mentions and more by whether the important details are fully explained and the unimportant details are safely omitted.**\n"
+ },
+ {
+ "version": null,
+ "slug": "team-task-lane-model",
+ "locale": "en",
+ "title": "Team Task Lane Model",
+ "kind": "bridge",
+ "filename": "team-task-lane-model.md",
+ "content": "# Team Task Lane Model\n\n> **Deep Dive** -- Best read at the start of Stage 4 (s15-s18). It separates five concepts that look similar but live on different layers.\n\n### When to Read This\n\nBefore you start the team chapters. Keep it open as a reference during s15-s18.\n\n---\n\n> By the time you reach `s15-s18`, the easiest thing to blur is not a function name.\n>\n> It is this:\n>\n> **Who is working, who is coordinating, what records the goal, and what provides the execution lane.**\n\n## What This Bridge Doc Fixes\n\nAcross `s15-s18`, you will encounter these words that can easily blur into one vague idea:\n\n- teammate\n- protocol request\n- task\n- runtime task\n- worktree\n\nThey all relate to work getting done, but they do **not** live on the same layer.\n\nIf you do not separate them, the later chapters start to feel tangled:\n\n- Is a teammate the same thing as a task?\n- What is the difference between `request_id` and `task_id`?\n- Is a worktree just another runtime task?\n- Why can a task be complete while a worktree is still kept?\n\nThis document exists to separate those layers cleanly.\n\n## Recommended Reading Order\n\n1. Read [`s15-agent-teams.md`](./s15-agent-teams.md) for long-lived teammates.\n2. Read [`s16-team-protocols.md`](./s16-team-protocols.md) for tracked request-response coordination.\n3. Read [`s17-autonomous-agents.md`](./s17-autonomous-agents.md) for self-claiming teammates.\n4. Read [`s18-worktree-task-isolation.md`](./s18-worktree-task-isolation.md) for isolated execution lanes.\n\nIf the vocabulary starts to blur, you might find it helpful to revisit:\n\n- [`entity-map.md`](./entity-map.md)\n- [`data-structures.md`](./data-structures.md)\n- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)\n\n## The Core Separation\n\n```text\nteammate\n = who participates over time\n\nprotocol request\n = one tracked coordination request inside the team\n\ntask\n = what should be done\n\nruntime task / execution slot\n = what is actively running right now\n\nworktree\n = where the work executes without colliding with other lanes\n```\n\nThe most common confusion is between the last three:\n\n- `task`\n- `runtime task`\n- `worktree`\n\nAsk three separate questions every time:\n\n- Is this the goal?\n- Is this the running execution unit?\n- Is this the isolated execution directory?\n\n## The Smallest Clean Diagram\n\n```text\nTeam Layer\n teammate: alice (frontend)\n\nProtocol Layer\n request_id=req_01\n kind=plan_approval\n status=pending\n\nWork Graph Layer\n task_id=12\n subject=\"Implement login page\"\n owner=\"alice\"\n status=\"in_progress\"\n\nRuntime Layer\n runtime_id=rt_01\n type=in_process_teammate\n status=running\n\nExecution Lane Layer\n worktree=login-page\n path=.worktrees/login-page\n status=active\n```\n\nOnly one of those records the work goal itself:\n\n> `task_id=12`\n\nThe others support coordination, execution, or isolation around that goal.\n\n## 1. Teammate: Who Is Collaborating\n\nIntroduced in `s15`.\n\nThis layer answers:\n\n- what the long-lived worker is called\n- what role it has\n- whether it is `working`, `idle`, or `shutdown`\n- whether it has its own inbox\n\nExample:\n\n```python\nmember = {\n \"name\": \"alice\",\n \"role\": \"frontend\",\n \"status\": \"idle\",\n}\n```\n\nThe point is not \"another agent instance.\"\n\nThe point is:\n\n> a persistent identity that can repeatedly receive work.\n\n## 2. Protocol Request: What Is Being Coordinated\n\nIntroduced in `s16`.\n\nThis layer answers:\n\n- who asked whom\n- what kind of request this is\n- whether it is still pending or already resolved\n\nExample:\n\n```python\nrequest = {\n \"request_id\": \"a1b2c3d4\",\n \"kind\": \"plan_approval\",\n \"from\": \"alice\",\n \"to\": \"lead\",\n \"status\": \"pending\",\n}\n```\n\nThis is not ordinary chat.\n\nIt is:\n\n> a coordination record whose state can continue to evolve.\n\n## 3. Task: What Should Be Done\n\nThis is the durable work-graph task from `s12`, and it is what `s17` teammates claim.\n\nIt answers:\n\n- what the goal is\n- who owns it\n- what blocks it\n- what progress state it is in\n\nExample:\n\n```python\ntask = {\n \"id\": 12,\n \"subject\": \"Implement login page\",\n \"status\": \"in_progress\",\n \"owner\": \"alice\",\n \"blockedBy\": [],\n}\n```\n\nKeyword:\n\n**goal**\n\nNot directory. Not protocol. Not process.\n\n## 4. Runtime Task / Execution Slot: What Is Running\n\nThis layer was already clarified in the `s13a` bridge doc, but it matters even more in `s15-s18`.\n\nExamples:\n\n- a background shell command\n- a long-lived teammate currently working\n- a monitor process watching an external state\n\nThese are best understood as:\n\n> active execution slots\n\nExample:\n\n```python\nruntime = {\n \"id\": \"rt_01\",\n \"type\": \"in_process_teammate\",\n \"status\": \"running\",\n \"work_graph_task_id\": 12,\n}\n```\n\nImportant boundary:\n\n- one work-graph task may spawn multiple runtime tasks\n- a runtime task is an execution instance, not the durable goal itself\n\n## 5. Worktree: Where the Work Happens\n\nIntroduced in `s18`.\n\nThis layer answers:\n\n- which isolated directory is used\n- which task it is bound to\n- whether that lane is `active`, `kept`, or `removed`\n\nExample:\n\n```python\nworktree = {\n \"name\": \"login-page\",\n \"path\": \".worktrees/login-page\",\n \"task_id\": 12,\n \"status\": \"active\",\n}\n```\n\nKeyword:\n\n**execution boundary**\n\nIt is not the task goal itself. It is the isolated lane where that goal is executed.\n\n## How The Layers Connect\n\n```text\nteammate\n coordinates through protocol requests\n claims a task\n runs as an execution slot\n works inside a worktree lane\n```\n\nIn a more concrete sentence:\n\n> `alice` claims `task #12` and progresses it inside the `login-page` worktree lane.\n\nThat sentence is much cleaner than saying:\n\n> \"alice is doing the login-page worktree task\"\n\nbecause the shorter sentence incorrectly merges:\n\n- the teammate\n- the task\n- the worktree\n\n## Common Mistakes\n\n### 1. Treating teammate and task as the same object\n\nThe teammate executes. The task expresses the goal.\n\n### 2. Treating `request_id` and `task_id` as interchangeable\n\nOne tracks coordination. The other tracks work goals.\n\n### 3. Treating the runtime slot as the durable task\n\nThe running execution may end while the durable task still exists.\n\n### 4. Treating the worktree as the task itself\n\nThe worktree is only the execution lane.\n\n### 5. Saying \"the system works in parallel\" without naming the layers\n\nGood teaching does not stop at \"there are many agents.\"\n\nIt can say clearly:\n\n> teammates provide long-lived collaboration, requests track coordination, tasks record goals, runtime slots carry execution, and worktrees isolate the execution directory.\n\n## What You Should Be Able to Say After Reading This\n\n1. `s17` autonomy claims `s12` work-graph tasks, not `s13` runtime slots.\n2. `s18` worktrees bind execution lanes to tasks; they do not turn tasks into directories.\n3. A teammate can be idle while the task still exists and while the worktree is still kept.\n4. A protocol request tracks a coordination exchange, not a work goal.\n\n## Key Takeaway\n\n**Five things that sound alike -- teammate, protocol request, task, runtime slot, worktree -- live on five separate layers. Naming which layer you mean is how you keep the team chapters from collapsing into confusion.**\n"
+ },
+ {
+ "version": null,
+ "slug": "data-structures",
+ "locale": "zh",
+ "title": "Core Data Structures (核心数据结构总表)",
+ "kind": "bridge",
+ "filename": "data-structures.md",
+ "content": "# Core Data Structures (核心数据结构总表)\n\n> 学习 agent，最容易迷路的地方不是功能太多，而是不知道“状态到底放在哪”。这份文档把主线章节和桥接章节里反复出现的关键数据结构集中列出来，方便你把整套系统看成一张图。\n\n## 推荐联读\n\n建议把这份总表当成“状态地图”来用：\n\n- 先不懂词，就回 [`glossary.md`](./glossary.md)。\n- 先不懂边界，就回 [`entity-map.md`](./entity-map.md)。\n- 如果卡在 `TaskRecord` 和 `RuntimeTaskState`，继续看 [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)。\n- 如果卡在 MCP 为什么还有 resource / prompt / elicitation，继续看 [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)。\n\n## 先记住两个总原则\n\n### 原则 1：区分“内容状态”和“流程状态”\n\n- `messages`、`tool_result`、memory 正文，属于内容状态。\n- `turn_count`、`transition`、`pending_classifier_check`，属于流程状态。\n\n很多初学者会把这两类状态混在一起。 \n一混，后面就很难看懂为什么一个结构完整的系统会需要控制平面。\n\n### 原则 2：区分“持久状态”和“运行时状态”\n\n- task、memory、schedule 这类状态，通常会落盘，跨会话存在。\n- runtime task、当前 permission decision、当前 MCP connection 这类状态，通常只在系统运行时活着。\n\n## 1. 查询与对话控制状态\n\n### Message\n\n作用：保存当前对话和工具往返历史。\n\n最小形状：\n\n```python\nmessage = {\n \"role\": \"user\" | \"assistant\",\n \"content\": \"...\",\n}\n```\n\n支持工具调用后，`content` 常常不再只是字符串，而会变成块列表，其中可能包含：\n\n- text block\n- `tool_use`\n- `tool_result`\n\n相关章节：\n\n- `s01`\n- `s02`\n- `s06`\n- `s10`\n\n### NormalizedMessage\n\n作用：把不同来源的消息整理成统一、稳定、可送给模型 API 的消息格式。\n\n最小形状：\n\n```python\nmessage = {\n \"role\": \"user\" | \"assistant\",\n \"content\": [\n {\"type\": \"text\", \"text\": \"...\"},\n ],\n}\n```\n\n它和普通 `Message` 的区别是：\n\n- `Message` 偏“系统内部记录”\n- `NormalizedMessage` 偏“准备发给模型之前的统一输入”\n\n相关章节：\n\n- `s10`\n- [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md)\n\n### CompactSummary\n\n作用：上下文太长时，用摘要替代旧消息原文。\n\n最小形状：\n\n```python\nsummary = {\n \"task_overview\": \"...\",\n \"current_state\": \"...\",\n \"key_decisions\": [\"...\"],\n \"next_steps\": [\"...\"],\n}\n```\n\n相关章节：\n\n- `s06`\n- `s11`\n\n### SystemPromptBlock\n\n作用：把 system prompt 从一整段大字符串，拆成若干可管理片段。\n\n最小形状：\n\n```python\nblock = {\n \"text\": \"...\",\n \"cache_scope\": None,\n}\n```\n\n你可以把它理解成：\n\n- `text`：这一段提示词正文\n- `cache_scope`：这一段是否可以复用缓存\n\n相关章节：\n\n- `s10`\n- [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md)\n\n### PromptParts\n\n作用：在真正拼成 system prompt 之前，先把各部分拆开管理。\n\n最小形状：\n\n```python\nparts = {\n \"core\": \"...\",\n \"tools\": \"...\",\n \"skills\": \"...\",\n \"memory\": \"...\",\n \"claude_md\": \"...\",\n \"dynamic\": \"...\",\n}\n```\n\n相关章节：\n\n- `s10`\n\n### QueryParams\n\n作用：进入查询主循环时，外部一次性传进来的输入集合。\n\n最小形状：\n\n```python\nparams = {\n \"messages\": [...],\n \"system_prompt\": \"...\",\n \"user_context\": {...},\n \"system_context\": {...},\n \"tool_use_context\": {...},\n \"fallback_model\": None,\n \"max_output_tokens_override\": None,\n \"max_turns\": None,\n}\n```\n\n它的重要点在于：\n\n- 这是“本次 query 的入口输入”\n- 它和循环内部不断变化的状态，不是同一层\n\n相关章节：\n\n- [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)\n\n### QueryState\n\n作用：保存一条 query 在多轮循环之间不断变化的流程状态。\n\n最小形状：\n\n```python\nstate = {\n \"messages\": [...],\n \"tool_use_context\": {...},\n \"turn_count\": 1,\n \"max_output_tokens_recovery_count\": 0,\n \"has_attempted_reactive_compact\": False,\n \"max_output_tokens_override\": None,\n \"pending_tool_use_summary\": None,\n \"stop_hook_active\": False,\n \"transition\": None,\n}\n```\n\n这类字段的共同特点是：\n\n- 它们不是对话内容\n- 它们是“这一轮该怎么继续”的控制状态\n\n相关章节：\n\n- [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)\n- `s11`\n\n### TransitionReason\n\n作用：记录“上一轮为什么继续了，而不是结束”。\n\n最小形状：\n\n```python\ntransition = {\n \"reason\": \"next_turn\",\n}\n```\n\n在更完整的 query 状态里，这个 `reason` 常见会有这些类型：\n\n- `next_turn`\n- `reactive_compact_retry`\n- `token_budget_continuation`\n- `max_output_tokens_recovery`\n- `stop_hook_continuation`\n\n它的价值不是炫技，而是让：\n\n- 日志更清楚\n- 测试更清楚\n- 恢复链路更清楚\n\n相关章节：\n\n- [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)\n- `s11`\n\n## 2. 工具、权限与 hook 执行状态\n\n### ToolSpec\n\n作用：告诉模型“有哪些工具、每个工具要什么输入”。\n\n最小形状：\n\n```python\ntool = {\n \"name\": \"read_file\",\n \"description\": \"Read file contents.\",\n \"input_schema\": {...},\n}\n```\n\n相关章节：\n\n- `s02`\n- `s19`\n\n### ToolDispatchMap\n\n作用：把工具名映射到真实执行函数。\n\n最小形状：\n\n```python\nhandlers = {\n \"read_file\": run_read,\n \"write_file\": run_write,\n \"bash\": run_bash,\n}\n```\n\n相关章节：\n\n- `s02`\n\n### ToolUseContext\n\n作用：把工具运行时需要的共享环境打成一个总线。\n\n最小形状：\n\n```python\ntool_use_context = {\n \"tools\": handlers,\n \"permission_context\": {...},\n \"mcp_clients\": [],\n \"messages\": [...],\n \"app_state\": {...},\n \"cwd\": \"...\",\n \"read_file_state\": {...},\n \"notifications\": [],\n}\n```\n\n这层很关键。 \n因为在更完整的工具执行环境里，工具拿到的不只是 `tool_input`，还包括：\n\n- 当前权限环境\n- 当前消息\n- 当前 app state\n- 当前 MCP client\n- 当前文件读取缓存\n\n相关章节：\n\n- [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md)\n- `s07`\n- `s19`\n\n### PermissionRule\n\n作用：描述某类工具调用命中后该怎么处理。\n\n最小形状：\n\n```python\nrule = {\n \"tool_name\": \"bash\",\n \"rule_content\": \"rm -rf *\",\n \"behavior\": \"deny\",\n}\n```\n\n相关章节：\n\n- `s07`\n\n### PermissionRuleSource\n\n作用：标记一条权限规则是从哪里来的。\n\n最小形状：\n\n```python\nsource = (\n \"userSettings\"\n | \"projectSettings\"\n | \"localSettings\"\n | \"flagSettings\"\n | \"policySettings\"\n | \"cliArg\"\n | \"command\"\n | \"session\"\n)\n```\n\n这个结构的意义是：\n\n- 你不只知道“有什么规则”\n- 还知道“这条规则是谁加进来的”\n\n相关章节：\n\n- `s07`\n\n### PermissionDecision\n\n作用：表示一次工具调用当前该允许、拒绝还是提问。\n\n最小形状：\n\n```python\ndecision = {\n \"behavior\": \"allow\" | \"deny\" | \"ask\",\n \"reason\": \"matched deny rule\",\n}\n```\n\n在更完整的权限流里，`ask` 结果还可能带：\n\n- 修改后的输入\n- 建议写回哪些规则更新\n- 一个后台自动分类检查\n\n相关章节：\n\n- `s07`\n\n### PermissionUpdate\n\n作用：描述“这次权限确认之后，要把什么改回配置里”。\n\n最小形状：\n\n```python\nupdate = {\n \"type\": \"addRules\" | \"removeRules\" | \"setMode\" | \"addDirectories\",\n \"destination\": \"userSettings\" | \"projectSettings\" | \"localSettings\" | \"session\",\n \"rules\": [],\n}\n```\n\n它解决的是一个很容易被漏掉的问题：\n\n用户这次点了“允许”，到底只是这一次放行，还是要写回会话、项目，甚至用户级配置。\n\n相关章节：\n\n- `s07`\n\n### HookContext\n\n作用：把某个 hook 事件发生时的上下文打包给外部脚本。\n\n最小形状：\n\n```python\ncontext = {\n \"event\": \"PreToolUse\",\n \"tool_name\": \"bash\",\n \"tool_input\": {...},\n \"tool_result\": \"...\",\n}\n```\n\n相关章节：\n\n- `s08`\n\n### RecoveryState\n\n作用：记录恢复流程已经尝试到哪里。\n\n最小形状：\n\n```python\nstate = {\n \"continuation_attempts\": 0,\n \"compact_attempts\": 0,\n \"transport_attempts\": 0,\n}\n```\n\n相关章节：\n\n- `s11`\n\n## 3. 持久化工作状态\n\n### TodoItem\n\n作用：当前会话里的轻量计划项。\n\n最小形状：\n\n```python\ntodo = {\n \"content\": \"Read parser.py\",\n \"status\": \"pending\" | \"completed\",\n}\n```\n\n相关章节：\n\n- `s03`\n\n### MemoryEntry\n\n作用：保存跨会话仍然有价值的信息。\n\n最小形状：\n\n```python\nmemory = {\n \"name\": \"prefer_tabs\",\n \"description\": \"User prefers tabs for indentation\",\n \"type\": \"user\" | \"feedback\" | \"project\" | \"reference\",\n \"scope\": \"private\" | \"team\",\n \"body\": \"...\",\n}\n```\n\n这里最重要的不是字段多，而是边界清楚：\n\n- 只存不容易从当前项目状态重新推出来的东西\n- 记忆可能会过时，要验证\n\n相关章节：\n\n- `s09`\n\n### TaskRecord\n\n作用：磁盘上的工作图任务节点。\n\n最小形状：\n\n```python\ntask = {\n \"id\": 12,\n \"subject\": \"Implement auth module\",\n \"description\": \"\",\n \"status\": \"pending\",\n \"blockedBy\": [],\n \"blocks\": [],\n \"owner\": \"\",\n \"worktree\": \"\",\n}\n```\n\n重点字段：\n\n- `blockedBy`：谁挡着我\n- `blocks`：我挡着谁\n- `owner`：谁认领了\n- `worktree`：在哪个隔离目录里做\n\n相关章节：\n\n- `s12`\n- `s17`\n- `s18`\n- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)\n\n### ScheduleRecord\n\n作用：记录未来要触发的调度任务。\n\n最小形状：\n\n```python\nschedule = {\n \"id\": \"job_001\",\n \"cron\": \"0 9 * * 1\",\n \"prompt\": \"Generate weekly report\",\n \"recurring\": True,\n \"durable\": True,\n \"created_at\": 1710000000.0,\n \"last_fired_at\": None,\n}\n```\n\n相关章节：\n\n- `s14`\n\n## 4. 运行时执行状态\n\n### RuntimeTaskState\n\n作用：表示系统里一个“正在运行的执行单元”。\n\n最小形状：\n\n```python\nruntime_task = {\n \"id\": \"b8k2m1qz\",\n \"type\": \"local_bash\",\n \"status\": \"running\",\n \"description\": \"Run pytest\",\n \"start_time\": 1710000000.0,\n \"end_time\": None,\n \"output_file\": \".task_outputs/b8k2m1qz.txt\",\n \"notified\": False,\n}\n```\n\n这和 `TaskRecord` 不是一回事：\n\n- `TaskRecord` 管工作目标\n- `RuntimeTaskState` 管当前执行槽位\n\n相关章节：\n\n- `s13`\n- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)\n\n### TeamMember\n\n作用：记录一个持久队友是谁、在做什么。\n\n最小形状：\n\n```python\nmember = {\n \"name\": \"alice\",\n \"role\": \"coder\",\n \"status\": \"idle\",\n}\n```\n\n相关章节：\n\n- `s15`\n- `s17`\n\n### MessageEnvelope\n\n作用：队友之间传递结构化消息。\n\n最小形状：\n\n```python\nmessage = {\n \"type\": \"message\" | \"shutdown_request\" | \"plan_approval\",\n \"from\": \"lead\",\n \"to\": \"alice\",\n \"request_id\": \"req_001\",\n \"content\": \"...\",\n \"payload\": {},\n \"timestamp\": 1710000000.0,\n}\n```\n\n相关章节：\n\n- `s15`\n- `s16`\n\n### RequestRecord\n\n作用：追踪一个协议请求当前走到哪里。\n\n最小形状：\n\n```python\nrequest = {\n \"request_id\": \"req_001\",\n \"kind\": \"shutdown\" | \"plan_review\",\n \"status\": \"pending\" | \"approved\" | \"rejected\" | \"expired\",\n \"from\": \"lead\",\n \"to\": \"alice\",\n}\n```\n\n相关章节：\n\n- `s16`\n\n### WorktreeRecord\n\n作用：记录一个任务绑定的隔离工作目录。\n\n最小形状：\n\n```python\nworktree = {\n \"name\": \"auth-refactor\",\n \"path\": \".worktrees/auth-refactor\",\n \"branch\": \"wt/auth-refactor\",\n \"task_id\": 12,\n \"status\": \"active\",\n}\n```\n\n相关章节：\n\n- `s18`\n\n### WorktreeEvent\n\n作用：记录 worktree 生命周期事件，便于恢复和排查。\n\n最小形状：\n\n```python\nevent = {\n \"event\": \"worktree.create.after\",\n \"task_id\": 12,\n \"worktree\": \"auth-refactor\",\n \"ts\": 1710000000.0,\n}\n```\n\n相关章节：\n\n- `s18`\n\n## 5. 外部平台与 MCP 状态\n\n### ScopedMcpServerConfig\n\n作用：描述一个 MCP server 应该如何连接，以及它的配置来自哪个作用域。\n\n最小形状：\n\n```python\nconfig = {\n \"name\": \"postgres\",\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"...\"],\n \"scope\": \"project\",\n}\n```\n\n这个 `scope` 很重要，因为 server 配置可能来自：\n\n- 本地\n- 用户\n- 项目\n- 动态注入\n- 插件或托管来源\n\n相关章节：\n\n- `s19`\n- [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md)\n- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)\n- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)\n\n### MCPServerConnectionState\n\n作用：表示一个 MCP server 当前连到了哪一步。\n\n最小形状：\n\n```python\nserver_state = {\n \"name\": \"postgres\",\n \"type\": \"connected\", # pending / failed / needs-auth / disabled\n \"config\": {...},\n}\n```\n\n这层特别重要，因为“有没有接上”不是布尔值，而是多种状态：\n\n- `connected`\n- `pending`\n- `failed`\n- `needs-auth`\n- `disabled`\n\n相关章节：\n\n- `s19`\n- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)\n\n### MCPToolSpec\n\n作用：把外部 MCP 工具转换成 agent 内部统一工具定义。\n\n最小形状：\n\n```python\nmcp_tool = {\n \"name\": \"mcp__postgres__query\",\n \"description\": \"Run a SQL query\",\n \"input_schema\": {...},\n}\n```\n\n相关章节：\n\n- `s19`\n\n### ElicitationRequest\n\n作用：表示 MCP server 反过来向用户请求额外输入。\n\n最小形状：\n\n```python\nrequest = {\n \"server_name\": \"some-server\",\n \"message\": \"Please provide additional input\",\n \"requested_schema\": {...},\n}\n```\n\n它提醒你一件事：\n\n- MCP 不只是“模型主动调工具”\n- 外部 server 也可能反过来请求补充输入\n\n相关章节：\n\n- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)\n\n## 最后用一句话把它们串起来\n\n如果你只想记一条总线索，可以记这个：\n\n```text\nmessages / prompt / query state\n 管本轮输入和继续理由\n\ntools / permissions / hooks\n 管动作怎么安全执行\n\nmemory / task / schedule\n 管跨轮、跨会话的持久工作\n\nruntime task / team / worktree\n 管当前执行车道\n\nmcp\n 管系统怎样向外接能力\n```\n\n这份总表最好配合 [`s00-architecture-overview.md`](./s00-architecture-overview.md) 和 [`entity-map.md`](./entity-map.md) 一起看。\n\n## 教学边界\n\n这份总表只负责做两件事：\n\n- 帮你确认一个状态到底属于哪一层\n- 帮你确认这个状态大概长什么样\n\n它不负责穷举真实系统里的每一个字段、每一条兼容分支、每一种产品化补丁。\n\n如果你已经知道某个状态归谁管、什么时候创建、什么时候销毁，再回到对应章节看执行路径，理解会顺很多。\n"
+ },
+ {
+ "version": null,
+ "slug": "entity-map",
+ "locale": "zh",
+ "title": "Entity Map (系统实体边界图)",
+ "kind": "bridge",
+ "filename": "entity-map.md",
+ "content": "# Entity Map (系统实体边界图)\n\n> 这份文档不是某一章的正文，而是一张“别再混词”的地图。 \n> 到了仓库后半程，真正让读者困惑的往往不是代码，而是：\n>\n> **同一个系统里，为什么会同时出现这么多看起来很像、但其实不是一回事的实体。**\n\n## 这张图和另外几份桥接文档怎么分工\n\n- 这份图先回答：一个词到底属于哪一层。\n- [`glossary.md`](./glossary.md) 先回答：这个词到底是什么意思。\n- [`data-structures.md`](./data-structures.md) 再回答：这个词落到代码里时，状态长什么样。\n- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) 专门补“工作图任务”和“运行时任务”的分层。\n- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md) 专门补 MCP 平台层不是只有 tools。\n\n## 先给一个总图\n\n```text\n对话层\n - message\n - prompt block\n - reminder\n\n动作层\n - tool call\n - tool result\n - hook event\n\n工作层\n - work-graph task\n - runtime task\n - protocol request\n\n执行层\n - subagent\n - teammate\n - worktree lane\n\n平台层\n - mcp server\n - mcp capability\n - memory record\n```\n\n## 最容易混淆的 8 对概念\n\n### 1. Message vs Prompt Block\n\n| 实体 | 它是什么 | 它不是什么 | 常见位置 |\n|---|---|---|---|\n| `Message` | 对话历史中的一条消息 | 不是长期系统规则 | `messages[]` |\n| `Prompt Block` | system prompt 内的一段稳定说明 | 不是某一轮刚发生的事件 | prompt builder |\n\n简单记法：\n\n- message 更像“对话内容”\n- prompt block 更像“系统说明”\n\n### 2. Todo / Plan vs Task\n\n| 实体 | 它是什么 | 它不是什么 |\n|---|---|---|\n| `todo / plan` | 当前轮或当前阶段的过程性安排 | 不是长期持久化工作图 |\n| `task` | 持久化的工作节点 | 不是某一轮的临时思路 |\n\n### 3. Work-Graph Task vs Runtime Task\n\n| 实体 | 它是什么 | 它不是什么 |\n|---|---|---|\n| `work-graph task` | 任务板上的工作节点 | 不是系统里活着的执行单元 |\n| `runtime task` | 当前正在执行的后台/agent/monitor 槽位 | 不是依赖图节点 |\n\n这对概念是整个仓库后半程最关键的区分之一。\n\n### 4. Subagent vs Teammate\n\n| 实体 | 它是什么 | 它不是什么 |\n|---|---|---|\n| `subagent` | 一次性委派执行者 | 不是长期在线成员 |\n| `teammate` | 持久存在、可重复接活的队友 | 不是一次性摘要工具 |\n\n### 5. Protocol Request vs Normal Message\n\n| 实体 | 它是什么 | 它不是什么 |\n|---|---|---|\n| `normal message` | 自由文本沟通 | 不是可追踪的审批流程 |\n| `protocol request` | 带 request_id 的结构化请求 | 不是随便说一句话 |\n\n### 6. Worktree vs Task\n\n| 实体 | 它是什么 | 它不是什么 |\n|---|---|---|\n| `task` | 说明要做什么 | 不是目录 |\n| `worktree` | 说明在哪做 | 不是工作目标 |\n\n### 7. Memory vs CLAUDE.md\n\n| 实体 | 它是什么 | 它不是什么 |\n|---|---|---|\n| `memory` | 跨会话仍有价值、但不易从当前代码直接推出来的信息 | 不是项目规则文件 |\n| `CLAUDE.md` | 长期规则、约束和说明 | 不是用户偏好或项目动态背景 |\n\n### 8. MCP Server vs MCP Tool\n\n| 实体 | 它是什么 | 它不是什么 |\n|---|---|---|\n| `MCP server` | 外部能力提供者 | 不是单个工具定义 |\n| `MCP tool` | 某个 server 暴露出来的一项具体能力 | 不是完整平台连接本身 |\n\n## 一张“是什么 / 存在哪里”的速查表\n\n| 实体 | 主要作用 | 典型存放位置 |\n|---|---|---|\n| `Message` | 当前对话历史 | `messages[]` |\n| `PromptParts` | system prompt 的组装片段 | prompt builder |\n| `PermissionRule` | 工具执行前的决策规则 | settings / session state |\n| `HookEvent` | 某个时机触发的扩展点 | hook config |\n| `MemoryEntry` | 跨会话有价值信息 | `.memory/` |\n| `TaskRecord` | 持久化工作节点 | `.tasks/` |\n| `RuntimeTaskState` | 正在执行的任务槽位 | runtime task manager |\n| `TeamMember` | 持久队友 | `.team/config.json` |\n| `MessageEnvelope` | 队友间结构化消息 | `.team/inbox/*.jsonl` |\n| `RequestRecord` | 审批/关机等协议状态 | request tracker |\n| `WorktreeRecord` | 隔离工作目录记录 | `.worktrees/index.json` |\n| `MCPServerConfig` | 外部 server 配置 | plugin / settings |\n\n## 后半程推荐怎么记\n\n如果你到了 `s15` 以后开始觉得名词多，可以只记这条线：\n\n```text\nmessage / prompt\n 管输入\n\ntool / permission / hook\n 管动作\n\ntask / runtime task / protocol\n 管工作推进\n\nsubagent / teammate / worktree\n 管执行者和执行车道\n\nmcp / memory / claude.md\n 管平台外延和长期上下文\n```\n\n## 初学者最容易心智打结的地方\n\n### 1. 把“任务”这个词用在所有层\n\n这是最常见的混乱来源。\n\n所以建议你在写正文时，尽量直接写全：\n\n- 工作图任务\n- 运行时任务\n- 后台任务\n- 协议请求\n\n不要都叫“任务”。\n\n### 2. 把队友和子 agent 混成一类\n\n如果生命周期不同，就不是同一类实体。\n\n### 3. 把 worktree 当成 task 的别名\n\n一个是“做什么”，一个是“在哪做”。\n\n### 4. 把 memory 当成通用笔记本\n\n它不是。它只保存很特定的一类长期信息。\n\n## 这份图应该怎么用\n\n最好的用法不是读一遍背下来，而是：\n\n- 每次你发现两个词开始混\n- 先来这张图里确认它们是不是一个层级\n- 再回去读对应章节\n\n如果你确认“不在一个层级”，下一步最好立刻去找它们对应的数据结构，而不是继续凭感觉读正文。\n\n## 教学边界\n\n这张图只解决“实体边界”这一个问题。\n\n它不负责展开每个实体的全部字段，也不负责把所有产品化分支一起讲完。\n\n你可以把它当成一张分层地图：\n\n- 先确认词属于哪一层\n- 再去对应章节看机制\n- 最后去 [`data-structures.md`](./data-structures.md) 看状态形状\n\n## 一句话记住\n\n**一个结构完整的系统最怕的不是功能多，而是实体边界不清；边界一清，很多复杂度会自动塌下来。**\n"
+ },
+ {
+ "version": null,
+ "slug": "glossary",
+ "locale": "zh",
+ "title": "Glossary (术语表)",
+ "kind": "bridge",
+ "filename": "glossary.md",
+ "content": "# Glossary (术语表)\n\n> 这份术语表只收录本仓库主线里最重要、最容易让初学者卡住的词。 \n> 如果某个词你看着眼熟但说不清它到底是什么，先回这里。\n\n## 推荐联读\n\n如果你不是单纯查词，而是已经开始分不清“这些词分别活在哪一层”，建议按这个顺序一起看：\n\n- 先看 [`entity-map.md`](./entity-map.md)：搞清每个实体属于哪一层。\n- 再看 [`data-structures.md`](./data-structures.md)：搞清这些词真正落成什么状态结构。\n- 如果你卡在“任务”这个词上，再看 [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)。\n- 如果你卡在 MCP 不只等于 tools，再看 [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)。\n\n## Agent\n\n在这套仓库里，`agent` 指的是： \n**一个能根据输入做判断，并且会调用工具去完成任务的模型。**\n\n你可以简单理解成：\n\n- 模型负责思考\n- harness 负责给模型工作环境\n\n## Harness\n\n`harness` 可以理解成“给 agent 准备好的工作台”。\n\n它包括：\n\n- 工具\n- 文件系统\n- 权限\n- 提示词\n- 记忆\n- 任务系统\n\n模型本身不是 harness。 \nharness 也不是模型。\n\n## Agent Loop\n\n`agent loop` 是系统反复执行的一条主循环：\n\n1. 把当前上下文发给模型\n2. 看模型是要直接回答，还是要调工具\n3. 如果调工具，就执行工具\n4. 把工具结果写回上下文\n5. 再继续下一轮\n\n没有这条循环，就没有 agent 系统。\n\n## Message / Messages\n\n`message` 是一条消息。 \n`messages` 是消息列表。\n\n它通常包含：\n\n- 用户消息\n- assistant 消息\n- tool_result 消息\n\n这份列表就是 agent 最主要的工作记忆。\n\n## Tool\n\n`tool` 是模型可以调用的一种动作。\n\n例如：\n\n- 读文件\n- 写文件\n- 改文件\n- 跑 shell 命令\n- 搜索文本\n\n模型并不直接执行系统命令。 \n模型只是说“我要调哪个工具、传什么参数”，真正执行的是你的代码。\n\n## Tool Schema\n\n`tool schema` 是工具的输入说明。\n\n它告诉模型：\n\n- 这个工具叫什么\n- 这个工具做什么\n- 需要哪些参数\n- 参数是什么类型\n\n可以把它想成“工具使用说明书”。\n\n## Dispatch Map\n\n`dispatch map` 是一张映射表：\n\n```python\n{\n \"read_file\": read_file_handler,\n \"write_file\": write_file_handler,\n \"bash\": bash_handler,\n}\n```\n\n意思是：\n\n- 模型说要调用 `read_file`\n- 代码就去表里找到 `read_file_handler`\n- 然后执行它\n\n## Stop Reason\n\n`stop_reason` 是模型这一轮为什么停下来的原因。\n\n常见的有：\n\n- `end_turn`：模型说完了\n- `tool_use`：模型要调用工具\n- `max_tokens`：模型输出被截断了\n\n它决定主循环下一步怎么走。\n\n## Context\n\n`context` 是模型当前能看到的信息总和。\n\n包括：\n\n- `messages`\n- system prompt\n- 动态补充信息\n- tool_result\n\n上下文不是永久记忆。 \n上下文是“这一轮工作时当前摆在桌上的东西”。\n\n## Compact / Compaction\n\n`compact` 指压缩上下文。\n\n因为对话越长，模型能看到的历史就越多，成本和混乱也会一起增加。\n\n压缩的目标不是“删除有用信息”，而是：\n\n- 保留真正关键的内容\n- 去掉重复和噪声\n- 给后面的轮次腾空间\n\n## Subagent\n\n`subagent` 是从当前 agent 派生出来的一个子任务执行者。\n\n它最重要的价值是：\n\n**把一个大任务放到独立上下文里处理，避免污染父上下文。**\n\n## Fork\n\n`fork` 在本仓库语境里，指一种子 agent 启动方式：\n\n- 不是从空白上下文开始\n- 而是先继承父 agent 的已有上下文\n\n这适合“子任务必须理解当前讨论背景”的场景。\n\n## Permission\n\n`permission` 就是“这个工具调用能不能执行”。\n\n一个好的权限系统通常要回答三件事：\n\n- 应不应该直接拒绝\n- 能不能自动允许\n- 剩下的是不是要问用户\n\n## Permission Mode\n\n`permission mode` 是权限系统的工作模式。\n\n例如：\n\n- `default`：默认询问\n- `plan`：只允许读，不允许写\n- `auto`：简单安全的操作自动过，危险操作再问\n\n## Hook\n\n`hook` 是一个插入点。\n\n意思是： \n在不改主循环代码的前提下，在某个时机额外执行一段逻辑。\n\n例如：\n\n- 工具调用前先检查一下\n- 工具调用后追加一条审计信息\n\n## Memory\n\n`memory` 是跨会话保存的信息。\n\n但不是所有东西都该存 memory。\n\n适合存 memory 的，通常是：\n\n- 用户长期偏好\n- 多次出现的重要反馈\n- 未来别的会话仍然有价值的信息\n\n## System Prompt\n\n`system prompt` 是系统级说明。\n\n它告诉模型：\n\n- 你是谁\n- 你能做什么\n- 你有哪些规则\n- 你应该如何协作\n\n它比普通用户消息更稳定。\n\n## System Reminder\n\n`system reminder` 是每一轮临时追加的动态提醒。\n\n例如：\n\n- 当前目录\n- 当前日期\n- 某个本轮才需要的额外上下文\n\n它和稳定的 system prompt 不是一回事。\n\n## Task\n\n`task` 是持久化任务系统里的一个任务节点。\n\n一个 task 通常不只是一句待办事项，还会带：\n\n- 状态\n- 描述\n- 依赖关系\n- owner\n\n## Dependency Graph\n\n`dependency graph` 指任务之间的依赖关系图。\n\n最简单的理解：\n\n- A 做完，B 才能开始\n- C 和 D 可以并行\n- E 要等 C 和 D 都完成\n\n这类结构能帮助 agent 判断：\n\n- 现在能做什么\n- 什么被卡住了\n- 什么能同时做\n\n## Worktree\n\n`worktree` 是 Git 提供的一个机制：\n\n同一个仓库，可以在多个不同目录里同时展开多个工作副本。\n\n它的价值是：\n\n- 并行做多个任务\n- 不互相污染文件改动\n- 便于多 agent 并行工作\n\n## MCP\n\n`MCP` 是 Model Context Protocol。\n\n你可以先把它理解成一套统一接口，让 agent 能接入外部工具。\n\n它解决的核心问题是：\n\n- 工具不必都写死在主程序里\n- 可以通过统一协议接入外部能力\n\n如果你已经知道“能接外部工具”，但开始分不清 server、connection、tool、resource、prompt 这些层，继续看：\n\n- [`data-structures.md`](./data-structures.md)\n- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)\n\n## Runtime Task\n\n`runtime task` 指的是：\n\n> 系统当前正在运行、等待完成、或者刚刚结束的一条执行单元。\n\n例如：\n\n- 一个后台 `pytest`\n- 一个正在工作的 teammate\n- 一个正在运行的 monitor\n\n它和 `task` 不一样。\n\n- `task` 更像工作目标\n- `runtime task` 更像执行槽位\n\n如果你总把这两个词混掉，不要只在正文里来回翻，直接去看：\n\n- [`entity-map.md`](./entity-map.md)\n- [`data-structures.md`](./data-structures.md)\n- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)\n\n## Teammate\n\n`teammate` 是长期存在的队友 agent。\n\n它和 `subagent` 的区别是：\n\n- `subagent`：一次性委派，干完就结束\n- `teammate`：长期存在，可以反复接任务\n\n如果你发现自己开始把这两个词混用，说明你需要回看：\n\n- `s04`\n- `s15`\n- `entity-map.md`\n\n## Protocol\n\n`protocol` 就是一套提前约好的协作规则。\n\n它回答的是：\n\n- 消息应该长什么样\n- 收到以后要怎么处理\n- 批准、拒绝、超时这些状态怎么记录\n\n在团队章节里，它最常见的形状是：\n\n```text\nrequest\n ->\nresponse\n ->\nstatus update\n```\n\n## Envelope\n\n`envelope` 本意是“信封”。\n\n在程序里，它表示：\n\n> 把正文和一些元信息一起包起来的一条结构化记录。\n\n例如一条协议消息里，正文之外还会附带：\n\n- `from`\n- `to`\n- `request_id`\n- `timestamp`\n\n这整包东西，就可以叫一个 `envelope`。\n\n## State Machine\n\n`state machine` 不是很玄的高级理论。\n\n你可以先把它理解成：\n\n> 一张“状态可以怎么变化”的规则表。\n\n例如：\n\n```text\npending -> approved\npending -> rejected\npending -> expired\n```\n\n这就是一个最小状态机。\n\n## Router\n\n`router` 可以简单理解成“分发器”。\n\n它的任务是：\n\n- 看请求属于哪一类\n- 把它送去正确的处理路径\n\n例如工具层里：\n\n- 本地工具走本地 handler\n- `mcp__...` 工具走 MCP client\n\n## Control Plane\n\n`control plane` 可以理解成“负责协调和控制的一层”。\n\n它通常不直接产出最终业务结果， \n而是负责决定：\n\n- 谁来执行\n- 在什么环境里执行\n- 有没有权限\n- 执行后要不要通知别的模块\n\n这个词第一次看到容易怕。 \n但在本仓库里，你只需要把它先记成：\n\n> 不直接干活，负责协调怎么干活的一层。\n\n## Capability\n\n`capability` 就是“能力项”。\n\n例如在 MCP 里，能力不只可能是工具，还可能包括：\n\n- tools\n- resources\n- prompts\n- elicitation\n\n所以 `capability` 比 `tool` 更宽。\n\n## Resource\n\n`resource` 可以理解成：\n\n> 一个可读取、可引用、但不一定是“执行动作”的外部内容入口。\n\n例如：\n\n- 一份文档\n- 一个只读配置\n- 一块可被模型读取的数据内容\n\n它和 `tool` 的区别是：\n\n- `tool` 更像动作\n- `resource` 更像可读取内容\n\n## Elicitation\n\n`elicitation` 可以先理解成：\n\n> 外部系统反过来向用户要补充输入。\n\n也就是说，不再只是 agent 主动调用外部能力。 \n外部能力也可能说：\n\n“我还缺一点信息，请你补一下。”\n\n## 最容易混的几对词\n\n如果你是初学者，下面这几对词最值得一起记。\n\n| 词对 | 最简单的区分方法 |\n|---|---|\n| `message` vs `system prompt` | 一个更像对话内容，一个更像系统说明 |\n| `todo` vs `task` | 一个更像临时步骤，一个更像持久化工作节点 |\n| `task` vs `runtime task` | 一个管目标，一个管执行 |\n| `subagent` vs `teammate` | 一个一次性，一个长期存在 |\n| `tool` vs `resource` | 一个更像动作，一个更像内容 |\n| `permission` vs `hook` | 一个决定能不能做，一个决定要不要额外插入行为 |\n\n---\n\n如果读文档时又遇到新词卡住，优先回这里，不要硬顶着往后读。\n"
+ },
+ {
+ "version": null,
+ "slug": "s00-architecture-overview",
+ "locale": "zh",
+ "title": "s00: Architecture Overview (架构总览)",
+ "kind": "bridge",
+ "filename": "s00-architecture-overview.md",
+ "content": "# s00: Architecture Overview (架构总览)\n\n> 这一章是全仓库的地图。 \n> 如果你只想先知道“整个系统到底由哪些模块组成、为什么是这个学习顺序”，先读这一章。\n\n## 先说结论\n\n这套仓库的主线是合理的。\n\n它最重要的优点，不是“章节数量多”，而是它把学习过程拆成了四个阶段：\n\n1. 先做出一个真的能工作的 agent。\n2. 再补安全、扩展、记忆和恢复。\n3. 再把临时清单升级成持久化任务系统。\n4. 最后再进入多 agent、隔离执行和外部工具平台。\n\n这个顺序符合初学者的心智。\n\n因为一个新手最需要的，不是先知道所有高级细节，而是先建立一条稳定的主线：\n\n`用户输入 -> 模型思考 -> 调工具 -> 拿结果 -> 继续思考 -> 完成`\n\n只要这条主线还没真正理解，后面的权限、hook、memory、MCP 都会变成一堆零散名词。\n\n## 这套仓库到底要还原什么\n\n本仓库的目标不是逐行复制任何一个生产仓库。\n\n本仓库真正要还原的是：\n\n- 主要模块有哪些\n- 模块之间怎么协作\n- 每个模块的核心职责是什么\n- 关键状态存在哪里\n- 一条请求在系统里是怎么流动的\n\n也就是说，我们追求的是：\n\n**设计主脉络高保真，而不是所有外围实现细节 1:1。**\n\n这很重要。\n\n如果你是为了自己从 0 到 1 做一个类似系统，那么你真正需要掌握的是：\n\n- 核心循环\n- 工具机制\n- 规划与任务\n- 上下文管理\n- 权限与扩展点\n- 持久化\n- 多 agent 协作\n- 工作隔离\n- 外部工具接入\n\n而不是打包、跨平台兼容、历史兼容分支或产品化胶水代码。\n\n## 三条阅读原则\n\n### 1. 先学最小版本，再学结构更完整的版本\n\n比如子 agent。\n\n最小版本只需要：\n\n- 父 agent 发一个子任务\n- 子 agent 用自己的 `messages`\n- 子 agent 返回一个摘要\n\n这已经能解决 80% 的核心问题：上下文隔离。\n\n等这个最小版本你真的能写出来，再去补更完整的能力，比如：\n\n- 继承父上下文的 fork 模式\n- 独立权限\n- 背景运行\n- worktree 隔离\n\n### 2. 每个新名词都必须先解释\n\n本仓库会经常用到一些词：\n\n- `state machine`\n- `dispatch map`\n- `dependency graph`\n- `frontmatter`\n- `worktree`\n- `MCP`\n\n如果你对这些词不熟，不要硬扛。 \n应该立刻去看术语表：[`glossary.md`](./glossary.md)\n\n如果你想先知道“这套仓库到底教什么、不教什么”，建议配合看：\n\n- [`teaching-scope.md`](./teaching-scope.md)\n\n如果你想先把最关键的数据结构建立成整体地图，可以配合看：\n\n- [`data-structures.md`](./data-structures.md)\n\n如果你已经知道章节顺序没问题，但一打开本地 `agents/*.py` 就会重新乱掉，建议再配合看：\n\n- [`s00f-code-reading-order.md`](./s00f-code-reading-order.md)\n\n### 3. 不把复杂外围细节伪装成“核心机制”\n\n好的教学，不是把一切都讲进去。\n\n好的教学，是把真正关键的东西讲完整，把不关键但很复杂的东西先拿掉。\n\n所以本仓库会刻意省略一些不属于主干的内容，比如：\n\n- 打包与发布\n- 企业策略接线\n- 遥测\n- 多客户端表层集成\n- 历史兼容层\n\n## 建议配套阅读的文档\n\n除了主线章节，我建议把下面两份文档当作全程辅助地图：\n\n| 文档 | 用途 |\n|---|---|\n| [`teaching-scope.md`](./teaching-scope.md) | 帮你分清哪些内容属于教学主线，哪些只是维护者侧补充 |\n| [`data-structures.md`](./data-structures.md) | 帮你集中理解整个系统的关键状态和数据结构 |\n| [`s00f-code-reading-order.md`](./s00f-code-reading-order.md) | 帮你把“章节顺序”和“本地代码阅读顺序”对齐，避免重新乱翻源码 |\n\n如果你已经读到中后半程，想把“章节之间缺的那一层”补上，再加看下面这些桥接文档：\n\n| 文档 | 它补的是什么 |\n|---|---|\n| [`s00d-chapter-order-rationale.md`](./s00d-chapter-order-rationale.md) | 为什么这套课要按现在这个顺序讲，哪些重排会把读者心智讲乱 |\n| [`s00e-reference-module-map.md`](./s00e-reference-module-map.md) | 参考仓库里真正重要的模块簇，和当前课程章节是怎样一一对应的 |\n| [`s00a-query-control-plane.md`](./s00a-query-control-plane.md) | 为什么一个更完整的系统不能只靠 `messages[] + while True` |\n| [`s00b-one-request-lifecycle.md`](./s00b-one-request-lifecycle.md) | 一条请求如何从用户输入一路流过 query、tools、permissions、tasks、teams、MCP 再回到主循环 |\n| [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md) | 为什么工具层不只是 `tool_name -> handler` |\n| [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md) | 为什么 system prompt 不是模型完整输入的全部 |\n| [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) | 为什么任务板里的 task 和正在运行的 task 不是一回事 |\n| [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md) | 为什么 MCP 正文先讲 tools-first，但平台层还要再补一张地图 |\n| [`entity-map.md`](./entity-map.md) | 帮你把 message、task、runtime task、subagent、teammate、worktree、MCP server 这些实体彻底分开 |\n\n## 四阶段学习路径\n\n### 阶段 1：核心单 agent (`s01-s06`)\n\n目标：先做出一个能干活的 agent。\n\n| 章节 | 学什么 | 解决什么问题 |\n|---|---|---|\n| `s01` | Agent Loop | 没有循环，就没有 agent |\n| `s02` | Tool Use | 让模型从“会说”变成“会做” |\n| `s03` | Todo / Planning | 防止大任务乱撞 |\n| `s04` | Subagent | 防止上下文被大任务污染 |\n| `s05` | Skills | 按需拿知识，不把所有知识塞进提示词 |\n| `s06` | Context Compact | 防止上下文无限膨胀 |\n\n这一阶段结束后，你已经有了一个真正可运行的 coding agent 雏形。\n\n### 阶段 2：生产加固 (`s07-s11`)\n\n目标：让 agent 不只是能跑，而是更安全、更稳、更可扩展。\n\n| 章节 | 学什么 | 解决什么问题 |\n|---|---|---|\n| `s07` | Permission System | 危险操作先过权限关 |\n| `s08` | Hook System | 不改主循环也能扩展行为 |\n| `s09` | Memory System | 让真正有价值的信息跨会话存在 |\n| `s10` | System Prompt | 把系统说明、工具、约束组装成稳定输入 |\n| `s11` | Error Recovery | 出错后能恢复，而不是直接崩溃 |\n\n### 阶段 3：任务管理 (`s12-s14`)\n\n目标：把“聊天中的清单”升级成“磁盘上的任务图”。\n\n| 章节 | 学什么 | 解决什么问题 |\n|---|---|---|\n| `s12` | Task System | 大任务要有持久结构 |\n| `s13` | Background Tasks | 慢操作不应该卡住前台思考 |\n| `s14` | Cron Scheduler | 让系统能在未来自动做事 |\n\n### 阶段 4：多 agent 与外部系统 (`s15-s19`)\n\n目标：从单 agent 升级成真正的平台。\n\n| 章节 | 学什么 | 解决什么问题 |\n|---|---|---|\n| `s15` | Agent Teams | 让多个 agent 协作 |\n| `s16` | Team Protocols | 让协作有统一规则 |\n| `s17` | Autonomous Agents | 让 agent 自己找活、认领任务 |\n| `s18` | Worktree Isolation | 并行工作时互不踩目录 |\n| `s19` | MCP & Plugin | 接入外部工具与外部能力 |\n\n## 章节速查表：每章到底新增了哪一层状态\n\n很多读者读到中途会开始觉得：\n\n- 这一章到底是在加工具，还是在加状态\n- 这个机制是“输入层”的，还是“执行层”的\n- 学完这一章以后，我手里到底多了一个什么东西\n\n所以这里给一张全局速查表。 \n读每章以前，先看这一行；读完以后，再回来检查自己是不是真的吃透了这一行。\n\n| 章节 | 新增的核心结构 | 它接在系统哪一层 | 学完你应该会什么 |\n|---|---|---|---|\n| `s01` | `messages` / `LoopState` | 主循环 | 手写一个最小 agent 闭环 |\n| `s02` | `ToolSpec` / `ToolDispatchMap` | 工具层 | 把模型意图路由成真实动作 |\n| `s03` | `TodoItem` / `PlanState` | 过程规划层 | 让 agent 按步骤推进，而不是乱撞 |\n| `s04` | `SubagentContext` | 执行隔离层 | 把探索性工作丢进干净子上下文 |\n| `s05` | `SkillRegistry` / `SkillContent` | 知识注入层 | 只在需要时加载额外知识 |\n| `s06` | `CompactSummary` / `PersistedOutput` | 上下文管理层 | 控制上下文大小又不丢主线 |\n| `s07` | `PermissionRule` / `PermissionDecision` | 安全控制层 | 让危险动作先经过决策管道 |\n| `s08` | `HookEvent` / `HookResult` | 扩展控制层 | 不改主循环也能插入扩展逻辑 |\n| `s09` | `MemoryEntry` / `MemoryStore` | 持久上下文层 | 只把真正跨会话有价值的信息留下 |\n| `s10` | `PromptParts` / `SystemPromptBlock` | 输入组装层 | 把模型输入拆成可管理的管道 |\n| `s11` | `RecoveryState` / `TransitionReason` | 恢复控制层 | 出错后知道为什么继续、怎么继续 |\n| `s12` | `TaskRecord` / `TaskStatus` | 工作图层 | 把临时清单升级成持久化任务图 |\n| `s13` | `RuntimeTaskState` / `Notification` | 运行时执行层 | 让慢任务后台运行、稍后回送结果 |\n| `s14` | `ScheduleRecord` / `CronTrigger` | 定时触发层 | 让时间本身成为工作触发器 |\n| `s15` | `TeamMember` / `MessageEnvelope` | 多 agent 基础层 | 让队友长期存在、反复接活 |\n| `s16` | `ProtocolEnvelope` / `RequestRecord` | 协作协议层 | 让团队从自由聊天升级成结构化协作 |\n| `s17` | `ClaimPolicy` / `AutonomyState` | 自治调度层 | 让 agent 空闲时自己找活、恢复工作 |\n| `s18` | `WorktreeRecord` / `TaskBinding` | 隔离执行层 | 给并行任务分配独立工作目录 |\n| `s19` | `MCPServerConfig` / `CapabilityRoute` | 外部能力层 | 把外部能力并入系统主控制面 |\n\n## 整个系统的大图\n\n先看最重要的一张图：\n\n```text\nUser\n |\n v\nmessages[]\n |\n v\n+-------------------------+\n| Agent Loop (s01) |\n| |\n| 1. 组装输入 |\n| 2. 调模型 |\n| 3. 看 stop_reason |\n| 4. 如果要调工具就执行 |\n| 5. 把结果写回 messages |\n| 6. 继续下一轮 |\n+-------------------------+\n |\n +------------------------------+\n | |\n v v\nTool Pipeline Context / State\n(s02, s07, s08) (s03, s06, s09, s10, s11)\n | |\n v v\nTasks / Teams / Worktree / MCP (s12-s19)\n```\n\n你可以把它理解成三层：\n\n### 第一层：主循环\n\n这是系统心脏。\n\n它只做一件事： \n**不停地推动“思考 -> 行动 -> 观察 -> 再思考”的循环。**\n\n### 第二层：横切机制\n\n这些机制不是替代主循环，而是“包在主循环周围”：\n\n- 权限\n- hooks\n- memory\n- prompt 组装\n- 错误恢复\n- 上下文压缩\n\n它们的作用，是让主循环更安全、更稳定、更聪明。\n\n### 第三层：更大的工作平台\n\n这些机制把单 agent 升级成更完整的系统：\n\n- 任务图\n- 后台任务\n- 多 agent 团队\n- worktree 隔离\n- MCP 外部工具\n\n## 你真正需要掌握的关键状态\n\n理解 agent，最重要的不是背很多功能名，而是知道**状态放在哪里**。\n\n下面是这个仓库里最关键的几类状态：\n\n### 1. 对话状态：`messages`\n\n这是 agent 当前上下文的主体。\n\n它保存：\n\n- 用户说了什么\n- 模型回复了什么\n- 调用了哪些工具\n- 工具返回了什么\n\n你可以把它想成 agent 的“工作记忆”。\n\n### 2. 工具注册表：`tools` / `handlers`\n\n这是一张“工具名 -> Python 函数”的映射表。\n\n这类结构常被叫做 `dispatch map`。\n\n意思很简单：\n\n- 模型说“我要调用 `read_file`”\n- 代码就去表里找 `read_file` 对应的函数\n- 找到以后执行\n\n### 3. 计划与任务状态：`todo` / `tasks`\n\n这部分保存：\n\n- 当前有哪些事要做\n- 哪些已经完成\n- 哪些被别的任务阻塞\n- 哪些可以并行\n\n### 4. 权限与策略状态\n\n这部分保存：\n\n- 当前权限模式是什么\n- 允许规则有哪些\n- 拒绝规则有哪些\n- 最近是否连续被拒绝\n\n### 5. 持久化状态\n\n这部分保存那些“不该跟着一次对话一起消失”的东西：\n\n- memory 文件\n- task 文件\n- transcript\n- background task 输出\n- worktree 绑定信息\n\n## 如果你想做出结构完整的版本，至少要有哪些数据结构\n\n如果你的目标是自己写一个结构完整、接近真实主脉络的类似系统，最低限度要把下面这些数据结构设计清楚：\n\n```python\nclass AppState:\n messages: list\n tools: dict\n tool_schemas: list\n\n todo: object | None\n tasks: object | None\n\n permissions: object | None\n hooks: object | None\n memories: object | None\n prompt_builder: object | None\n\n compact_state: dict\n recovery_state: dict\n\n background: object | None\n cron: object | None\n\n teammates: object | None\n worktree_session: dict | None\n mcp_clients: dict\n```\n\n这不是要求你一开始就把这些全写完。\n\n这张表的作用只是告诉你：\n\n**一个像样的 agent 系统，不只是 `messages + tools`。**\n\n它最终会长成一个带很多子模块的状态系统。\n\n## 一条请求是怎么流动的\n\n```text\n1. 用户发来任务\n2. 系统组装 prompt 和上下文\n3. 模型返回普通文本，或者返回 tool_use\n4. 如果返回 tool_use：\n - 先过 permission\n - 再过 hook\n - 然后执行工具\n - 把 tool_result 写回 messages\n5. 主循环继续\n6. 如果任务太大：\n - 可能写入 todo / tasks\n - 可能派生 subagent\n - 可能触发 compact\n - 可能走 background / team / worktree / MCP\n7. 直到模型结束这一轮\n```\n\n这条流是全仓库最重要的主脉络。\n\n你在后面所有章节里看到的机制，本质上都只是插在这条流的不同位置。\n\n## 读者最容易混淆的几组概念\n\n### `Todo` 和 `Task` 不是一回事\n\n- `Todo`：轻量、临时、偏会话内\n- `Task`：持久化、带状态、带依赖关系\n\n### `Memory` 和 `Context` 不是一回事\n\n- `Context`：这一轮工作临时需要的信息\n- `Memory`：未来别的会话也可能仍然有价值的信息\n\n### `Subagent` 和 `Teammate` 不是一回事\n\n- `Subagent`：通常是当前 agent 派生出来的一次性帮手\n- `Teammate`：更偏向长期存在于团队中的协作角色\n\n### `Prompt` 和 `System Reminder` 不是一回事\n\n- `System Prompt`：较稳定的系统级输入\n- `System Reminder`：每轮动态变化的补充上下文\n\n## 这套仓库刻意省略了什么\n\n为了让初学者能顺着学下去，本仓库不会把下面这些内容塞进主线：\n\n- 产品级启动流程里的全部外围初始化\n- 真实商业产品中的账号、策略、遥测、灰度等逻辑\n- 只服务于兼容性和历史负担的复杂分支\n- 某些非常复杂但教学收益很低的边角机制\n\n这不是因为这些东西“不存在”。\n\n而是因为对一个从 0 到 1 造类似系统的读者来说，主干先于枝叶。\n\n## 这一章之后怎么读\n\n推荐顺序：\n\n1. 先读 `s01` 和 `s02`\n2. 然后读 `s03` 到 `s06`\n3. 进入 `s07` 到 `s10`\n4. 接着补 `s11`\n5. 最后再读 `s12` 到 `s19`\n\n如果你在某一章觉得名词开始打结，回来看这一章和术语表就够了。\n\n---\n\n**一句话记住全仓库：**\n\n先做出能工作的最小循环，再一层一层给它补上规划、隔离、安全、记忆、任务、协作和外部能力。\n"
+ },
+ {
+ "version": null,
+ "slug": "s00a-query-control-plane",
+ "locale": "zh",
+ "title": "s00a: Query Control Plane (查询控制平面)",
+ "kind": "bridge",
+ "filename": "s00a-query-control-plane.md",
+ "content": "# s00a: Query Control Plane (查询控制平面)\n\n> 这不是新的主线章节，而是一份桥接文档。 \n> 它用来回答一个问题：\n>\n> **为什么一个结构更完整的 agent，不会只靠 `messages[]` 和一个 `while True` 就够了？**\n\n## 这一篇为什么要存在\n\n主线里的 `s01` 会先教你做出一个最小可运行循环：\n\n```text\n用户输入\n ->\n模型回复\n ->\n如果要调工具就执行\n ->\n把结果喂回去\n ->\n继续下一轮\n```\n\n这条主线是对的，而且必须先学这个。\n\n但当系统开始长功能以后，真正支撑一个完整 harness 的，不再只是“循环”本身，而是：\n\n**一层专门负责管理查询过程的控制平面。**\n\n这一层在真实系统里通常会统一处理：\n\n- 当前对话消息\n- 当前轮次\n- 为什么继续下一轮\n- 是否正在恢复错误\n- 是否已经压缩过上下文\n- 是否需要切换输出预算\n- hook 是否暂时影响了结束条件\n\n如果不把这层讲出来，读者虽然能做出一个能跑的 demo，但很难自己把系统推到接近 95%-99% 的完成度。\n\n## 先解释几个名词\n\n### 什么是 query\n\n这里的 `query` 不是“数据库查询”。\n\n这里说的 query，更接近：\n\n> 系统为了完成用户当前这一次请求，而运行的一整段主循环过程。\n\n也就是说：\n\n- 用户说一句话\n- 系统可能要经过很多轮模型调用和工具调用\n- 最后才结束这一次请求\n\n这整段过程，就可以看成一条 query。\n\n### 什么是控制平面\n\n`控制平面` 这个词第一次看会有点抽象。\n\n它的意思其实很简单：\n\n> 不是直接做业务动作，而是负责协调、调度、决定流程怎么往下走的一层。\n\n在这里：\n\n- 模型回复内容，算“业务内容”\n- 工具执行结果，算“业务动作”\n- 决定“要不要继续下一轮、为什么继续、现在属于哪种继续”，这层就是控制平面\n\n### 什么是 transition\n\n`transition` 可以翻成“转移原因”。\n\n它回答的是：\n\n> 上一轮为什么没有结束，而是继续下一轮了？\n\n例如：\n\n- 因为工具刚执行完\n- 因为输出被截断，要续写\n- 因为刚做完压缩，要重试\n- 因为 hook 要求继续\n- 因为预算还允许继续\n\n## 最小心智模型\n\n先把 query 控制平面想成 3 层：\n\n```text\n1. 输入层\n - messages\n - system prompt\n - user/system context\n\n2. 控制层\n - 当前状态 state\n - 当前轮 turn\n - 当前继续原因 transition\n - 恢复/压缩/预算等标记\n\n3. 执行层\n - 调模型\n - 执行工具\n - 写回消息\n```\n\n它的工作不是“替代主循环”，而是：\n\n**让主循环从一个小 demo，升级成一个能管理很多分支和状态的系统。**\n\n## 为什么只靠 `messages[]` 不够\n\n很多初学者第一次实现 agent 时，会把所有状态都堆进 `messages[]`。\n\n这在最小 demo 里没问题。\n\n但一旦系统长出下面这些能力，就不够了：\n\n- 你要知道自己是不是已经做过一次 reactive compact\n- 你要知道输出被截断已经续写了几次\n- 你要知道这次继续是因为工具，还是因为错误恢复\n- 你要知道当前轮是否启用了特殊输出预算\n\n这些信息不是“对话内容”，而是“流程控制状态”。\n\n所以它们不该都硬塞进 `messages[]` 里。\n\n## 关键数据结构\n\n### 1. QueryParams\n\n这是进入 query 引擎时的外部输入。\n\n最小形状可以这样理解：\n\n```python\nparams = {\n \"messages\": [...],\n \"system_prompt\": \"...\",\n \"user_context\": {...},\n \"system_context\": {...},\n \"tool_use_context\": {...},\n \"fallback_model\": None,\n \"max_output_tokens_override\": None,\n \"max_turns\": None,\n}\n```\n\n它的作用是：\n\n- 带进来这次查询一开始已知的输入\n- 这些值大多不在每轮里随便乱改\n\n### 2. QueryState\n\n这才是跨迭代真正会变化的部分。\n\n最小教学版建议你把它显式做成一个结构：\n\n```python\nstate = {\n \"messages\": [...],\n \"tool_use_context\": {...},\n \"continuation_count\": 0,\n \"has_attempted_compact\": False,\n \"max_output_tokens_override\": None,\n \"stop_hook_active\": False,\n \"turn_count\": 1,\n \"transition\": None,\n}\n```\n\n它的价值在于：\n\n- 把“会变的流程状态”集中放在一起\n- 让每个 continue site 修改的是同一份 state，而不是散落在很多局部变量里\n\n### 3. TransitionReason\n\n建议你单独定义一组继续原因：\n\n```python\nTRANSITIONS = (\n \"tool_result_continuation\",\n \"max_tokens_recovery\",\n \"compact_retry\",\n \"transport_retry\",\n \"stop_hook_continuation\",\n \"budget_continuation\",\n)\n```\n\n这不是为了炫技。\n\n它的作用很实在：\n\n- 日志更清楚\n- 调试更清楚\n- 测试更清楚\n- 教学更清楚\n\n## 最小实现\n\n### 第一步：把外部输入和内部状态分开\n\n```python\ndef query(params):\n state = {\n \"messages\": params[\"messages\"],\n \"tool_use_context\": params[\"tool_use_context\"],\n \"continuation_count\": 0,\n \"has_attempted_compact\": False,\n \"max_output_tokens_override\": params.get(\"max_output_tokens_override\"),\n \"turn_count\": 1,\n \"transition\": None,\n }\n```\n\n### 第二步：每一轮先读 state，再决定如何执行\n\n```python\nwhile True:\n messages = state[\"messages\"]\n transition = state[\"transition\"]\n turn_count = state[\"turn_count\"]\n\n response = call_model(...)\n ...\n```\n\n### 第三步：所有“继续下一轮”的地方都写回 state\n\n```python\nif response.stop_reason == \"tool_use\":\n state[\"messages\"] = append_tool_results(...)\n state[\"transition\"] = \"tool_result_continuation\"\n state[\"turn_count\"] += 1\n continue\n\nif response.stop_reason == \"max_tokens\":\n state[\"messages\"].append({\"role\": \"user\", \"content\": CONTINUE_MESSAGE})\n state[\"continuation_count\"] += 1\n state[\"transition\"] = \"max_tokens_recovery\"\n continue\n```\n\n这一点非常关键。\n\n**不要只做 `continue`，要知道自己为什么 continue。**\n\n## 一张真正清楚的心智图\n\n```text\nparams\n |\n v\ninit state\n |\n v\nquery loop\n |\n +-- normal assistant end --------------> terminal\n |\n +-- tool_use --------------------------> write tool_result -> transition=tool_result_continuation\n |\n +-- max_tokens ------------------------> inject continue -> transition=max_tokens_recovery\n |\n +-- prompt too long -------------------> compact -> transition=compact_retry\n |\n +-- transport error -------------------> backoff -> transition=transport_retry\n |\n +-- stop hook asks to continue --------> transition=stop_hook_continuation\n```\n\n## 它和 `s01`、`s11` 的关系\n\n- `s01` 负责建立“最小主循环”\n- `s11` 负责建立“错误恢复分支”\n- 这一篇负责把两者再往上抽象一层，解释为什么一个更完整的系统会出现一个 query control plane\n\n所以这篇不是替代主线，而是把主线补完整。\n\n## 初学者最容易犯的错\n\n### 1. 把所有控制状态都塞进消息里\n\n这样日志和调试都会很难看，也会让消息层和控制层混在一起。\n\n### 2. `continue` 了，但没有记录为什么继续\n\n短期看起来没问题，系统一复杂就会变成黑盒。\n\n### 3. 每个分支都直接改很多局部变量\n\n这样后面你很难看出“哪些状态是跨轮共享的”。\n\n### 4. 把 query loop 讲成“只是一个 while True”\n\n这对最小 demo 是真话，对一个正在长出控制面的 harness 就不是完整真话了。\n\n## 教学边界\n\n这篇最重要的，不是把所有控制状态一次列满，而是先让你守住三件事：\n\n- query loop 不只是 `while True`，而是一条带着共享状态往前推进的控制面\n- 每次 `continue` 都应该有明确原因，而不是黑盒跳转\n- 消息层、工具回写、压缩恢复、重试恢复，最终都要回到同一份 query 状态上\n\n更细的 `transition taxonomy`、预算跟踪、prefetch 等扩展，可以放到你把这条最小控制面真正手搓稳定以后再补。\n\n## 一句话记住\n\n**更完整的 query loop 不只是“循环”，而是“拿着一份跨轮状态不断推进的查询控制平面”。**\n"
+ },
+ {
+ "version": null,
+ "slug": "s00b-one-request-lifecycle",
+ "locale": "zh",
+ "title": "s00b: One Request Lifecycle (一次请求的完整生命周期)",
+ "kind": "bridge",
+ "filename": "s00b-one-request-lifecycle.md",
+ "content": "# s00b: One Request Lifecycle (一次请求的完整生命周期)\n\n> 这是一份桥接文档。 \n> 它不替代主线章节，而是把整套系统串成一条真正连续的执行链。\n>\n> 它要回答的问题是：\n>\n> **用户的一句话，进入系统以后，到底是怎样一路流动、分发、执行、再回到主循环里的？**\n\n## 为什么必须补这一篇\n\n很多读者在按顺序看教程时，会逐章理解：\n\n- `s01` 讲循环\n- `s02` 讲工具\n- `s03` 讲规划\n- `s07` 讲权限\n- `s09` 讲 memory\n- `s12-s19` 讲任务、多 agent、MCP\n\n每章单看都能懂。\n\n但一旦开始自己实现，就会很容易卡住：\n\n- 这些模块到底谁先谁后？\n- 一条请求进来时，先走 prompt，还是先走 memory？\n- 工具执行前，权限和 hook 在哪一层？\n- task、runtime task、teammate、worktree、MCP 到底是在一次请求里的哪个阶段介入？\n\n所以你需要一张“纵向流程图”。\n\n## 先给一条最重要的总图\n\n```text\n用户请求\n |\n v\nQuery State 初始化\n |\n v\n组装 system prompt / messages / reminders\n |\n v\n调用模型\n |\n +-- 普通回答 -------------------------------> 结束本次请求\n |\n +-- tool_use\n |\n v\n Tool Router\n |\n +-- 权限判断\n +-- Hook 拦截/注入\n +-- 本地工具 / MCP / agent / task / team\n |\n v\n 执行结果\n |\n +-- 可能写入 task / runtime task / memory / worktree 状态\n |\n v\n tool_result 写回 messages\n |\n v\n Query State 更新\n |\n v\n 下一轮继续\n```\n\n你可以把整条链先理解成三层：\n\n1. `Query Loop`\n2. `Tool Control Plane`\n3. `Platform State`\n\n## 第 1 段：用户请求进入查询控制平面\n\n当用户说：\n\n```text\n修复 tests/test_auth.py 的失败，并告诉我原因\n```\n\n系统最先做的，不是立刻跑工具，而是先为这次请求建立一份查询状态。\n\n最小可以理解成：\n\n```python\nquery_state = {\n \"messages\": [{\"role\": \"user\", \"content\": user_text}],\n \"turn_count\": 1,\n \"transition\": None,\n \"tool_use_context\": {...},\n}\n```\n\n这里的重点是：\n\n**这次请求不是“单次 API 调用”，而是一段可能包含很多轮的查询过程。**\n\n如果你对这一层还不够熟，先回看：\n\n- [`s01-the-agent-loop.md`](./s01-the-agent-loop.md)\n- [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)\n\n## 第 2 段：组装本轮真正送给模型的输入\n\n主循环不会直接把原始 `messages` 裸发出去。\n\n在更完整的系统里，它通常会先组装：\n\n- system prompt blocks\n- 规范化后的 messages\n- memory section\n- 当前轮 reminder\n- 工具清单\n\n也就是说，真正发给模型的通常是：\n\n```text\nsystem prompt\n+ normalized messages\n+ tools\n+ optional reminders / attachments\n```\n\n这里涉及的章节是：\n\n- `s09` memory\n- `s10` system prompt\n- `s10a` message & prompt pipeline\n\n这一段的核心心智是：\n\n**system prompt 不是全部输入，它只是输入管道中的一段。**\n\n## 第 3 段：模型产出两类东西\n\n模型这一轮的输出，最关键地分成两种：\n\n### 第一种：普通回复\n\n如果模型直接给出结论或说明，本次请求可能就结束了。\n\n### 第二种：动作意图\n\n也就是工具调用。\n\n例如：\n\n```text\nread_file(\"tests/test_auth.py\")\nbash(\"pytest tests/test_auth.py -q\")\ntodo([...])\nload_skill(\"code-review\")\ntask_create(...)\nmcp__postgres__query(...)\n```\n\n这时候系统真正收到的，不只是“文本”，而是：\n\n> 模型想让真实世界发生某些动作。\n\n## 第 4 段：工具路由层接管动作意图\n\n一旦出现 `tool_use`，系统就进入工具控制平面。\n\n这一层至少要回答：\n\n1. 这是什么工具？\n2. 它应该路由到哪类能力来源？\n3. 执行前要不要先过权限？\n4. hook 有没有要拦截或补充？\n5. 它执行时能访问哪些共享状态？\n\n最小图可以这样看：\n\n```text\ntool_use\n |\n v\nTool Router\n |\n +-- native tool handler\n +-- MCP client\n +-- agent/team/task handler\n```\n\n如果你对这一层不够清楚，回看：\n\n- [`s02-tool-use.md`](./s02-tool-use.md)\n- [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md)\n\n## 第 5 段：权限系统决定“能不能执行”\n\n不是所有动作意图都应该直接变成真实执行。\n\n例如：\n\n- 写文件\n- 跑 bash\n- 改工作目录\n- 调外部服务\n\n这时会先进入权限判断：\n\n```text\ndeny rules\n -> mode\n -> allow rules\n -> ask user\n```\n\n权限系统处理的是：\n\n> 这次动作是否允许发生。\n\n相关章节：\n\n- [`s07-permission-system.md`](./s07-permission-system.md)\n\n## 第 6 段：Hook 可以在边上做扩展\n\n通过权限检查以后，系统还可能在工具执行前后跑 hook。\n\n你可以把 hook 理解成：\n\n> 不改主循环主干，也能插入自定义行为的扩展点。\n\n例如：\n\n- 执行前记录日志\n- 执行后做额外检查\n- 根据结果注入额外提醒\n\n相关章节：\n\n- [`s08-hook-system.md`](./s08-hook-system.md)\n\n## 第 7 段：真正执行动作，并影响不同层的状态\n\n这是很多人最容易低估的一段。\n\n工具执行结果，不只是“一段文本输出”。\n\n它还可能修改系统别的状态层。\n\n### 例子 1：规划状态\n\n如果工具是 `todo`，它会更新的是当前会话计划。\n\n相关章节：\n\n- [`s03-todo-write.md`](./s03-todo-write.md)\n\n### 例子 2：持久任务图\n\n如果工具是 `task_create` / `task_update`，它会修改磁盘上的任务板。\n\n相关章节：\n\n- [`s12-task-system.md`](./s12-task-system.md)\n\n### 例子 3：运行时任务\n\n如果工具启动了后台 bash、后台 agent 或监控任务，它会创建 runtime task。\n\n相关章节：\n\n- [`s13-background-tasks.md`](./s13-background-tasks.md)\n- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)\n\n### 例子 4：多 agent / teammate\n\n如果工具是 `delegate`、`spawn_agent` 一类，它会在平台层生成新的执行单元。\n\n相关章节：\n\n- [`s15-agent-teams.md`](./s15-agent-teams.md)\n- [`s16-team-protocols.md`](./s16-team-protocols.md)\n- [`s17-autonomous-agents.md`](./s17-autonomous-agents.md)\n\n### 例子 5：worktree\n\n如果系统要为某个任务提供隔离工作目录，这会影响文件系统级执行环境。\n\n相关章节：\n\n- [`s18-worktree-task-isolation.md`](./s18-worktree-task-isolation.md)\n\n### 例子 6：MCP\n\n如果调用的是外部 MCP 能力，那么执行主体可能根本不在本地 handler，而在外部能力端。\n\n相关章节：\n\n- [`s19-mcp-plugin.md`](./s19-mcp-plugin.md)\n- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)\n\n## 第 8 段：执行结果被包装回消息流\n\n不管执行落在哪一层，最后都要回到同一个位置：\n\n```text\ntool_result -> messages\n```\n\n这是整个系统最核心的闭环。\n\n因为无论工具背后多复杂，模型下一轮真正能继续工作的依据，仍然是：\n\n> 系统把执行结果重新写回了它可见的消息流。\n\n这也是为什么 `s01` 永远是根。\n\n## 第 9 段：主循环根据结果决定下一轮是否继续\n\n当 `tool_result` 写回以后，查询状态也会一起更新：\n\n- `messages` 变了\n- `turn_count` 增加了\n- `transition` 被记录成某种续行原因\n\n这时系统就进入下一轮。\n\n如果中间发生下面这些情况，控制平面还会继续介入：\n\n- 上下文太长，需要压缩\n- 输出被截断，需要续写\n- 请求失败，需要恢复\n\n相关章节：\n\n- [`s06-context-compact.md`](./s06-context-compact.md)\n- [`s11-error-recovery.md`](./s11-error-recovery.md)\n\n## 第 10 段：哪些信息不会跟着一次请求一起结束\n\n这也是非常容易混的地方。\n\n一次请求结束后，并不是所有状态都随之消失。\n\n### 会跟着当前请求结束的\n\n- 当前轮 messages 中的临时推进过程\n- 会话内 todo 状态\n- 当前轮 reminder\n\n### 可能跨请求继续存在的\n\n- memory\n- 持久任务图\n- runtime task 输出\n- worktree\n- MCP 连接状态\n\n所以你要逐渐学会区分：\n\n```text\nquery-scope state\nsession-scope state\nproject-scope state\nplatform-scope state\n```\n\n## 用一个完整例子串一次\n\n还是用这个请求：\n\n```text\n修复 tests/test_auth.py 的失败，并告诉我原因\n```\n\n系统可能会这样流动：\n\n1. 用户请求进入 `QueryState`\n2. system prompt + memory + tools 被组装好\n3. 模型先调用 `todo`，写出三步计划\n4. 模型调用 `read_file(\"tests/test_auth.py\")`\n5. 工具路由到本地文件读取 handler\n6. 读取结果包装成 `tool_result` 写回消息流\n7. 下一轮模型调用 `bash(\"pytest tests/test_auth.py -q\")`\n8. 权限系统判断这条命令是否可执行\n9. 执行测试，输出太长则先落盘并留预览\n10. 失败日志回到消息流\n11. 模型再读实现文件并修改代码\n12. 修改后再跑测试\n13. 如果对话变长，`s06` 触发压缩\n14. 如果任务被拆给子 agent，`s15-s17` 介入\n15. 最后模型输出结论，本次请求结束\n\n你会发现：\n\n**整套系统再复杂，也始终没有脱离“输入 -> 动作意图 -> 执行 -> 结果写回 -> 下一轮”这条主骨架。**\n\n## 读这篇时最该记住的三件事\n\n### 1. 所有模块都不是平铺摆在那里的\n\n它们是在一次请求的不同阶段依次介入的。\n\n### 2. 真正的闭环只有一个\n\n那就是：\n\n```text\ntool_result 回到 messages\n```\n\n### 3. 很多高级机制，本质上只是围绕这条闭环加的保护层\n\n例如：\n\n- 权限是执行前保护层\n- hook 是扩展层\n- compact 是上下文预算保护层\n- recovery 是出错后的恢复层\n- task/team/worktree/MCP 是更大的平台能力层\n\n## 一句话记住\n\n**一次请求的完整生命周期，本质上就是：系统围绕同一条主循环，把不同模块按阶段接进来，最终持续把真实执行结果送回模型继续推理。**\n"
+ },
+ {
+ "version": null,
+ "slug": "s00c-query-transition-model",
+ "locale": "zh",
+ "title": "s00c: Query Transition Model (查询转移模型)",
+ "kind": "bridge",
+ "filename": "s00c-query-transition-model.md",
+ "content": "# s00c: Query Transition Model (查询转移模型)\n\n> 这篇桥接文档专门解决一个问题：\n>\n> **为什么一个只会 `continue` 的 agent，不足以支撑完整系统，而必须显式知道“为什么继续到下一轮”？**\n\n## 这一篇为什么要存在\n\n主线里：\n\n- `s01` 先教你最小循环\n- `s06` 开始教上下文压缩\n- `s11` 开始教错误恢复\n\n这些都对。 \n但如果你只分别学这几章，脑子里很容易还是停留在一种过于粗糙的理解：\n\n> “反正 `continue` 了就继续呗。”\n\n这在最小 demo 里能跑。 \n但当系统开始长出恢复、压缩和外部控制以后，这样理解会很快失灵。\n\n因为系统继续下一轮的原因其实很多，而且这些原因不是一回事：\n\n- 工具刚执行完，要把结果喂回模型\n- 输出被截断了，要续写\n- 上下文刚压缩完，要重试\n- 运输层刚超时了，要退避后重试\n- stop hook 要求当前 turn 先不要结束\n- token budget 还允许继续推进\n\n如果你不把这些“继续原因”从一开始拆开，后面会出现三个大问题：\n\n- 日志看不清\n- 测试不好写\n- 教学心智会越来越模糊\n\n## 先解释几个名词\n\n### 什么叫 transition\n\n这里的 `transition`，你可以先把它理解成：\n\n> 上一轮为什么转移到了下一轮。\n\n它不是“消息内容”，而是“流程原因”。\n\n### 什么叫 continuation\n\ncontinuation 就是：\n\n> 这条 query 当前还没有结束，要继续推进。\n\n但 continuation 不止一种。\n\n### 什么叫 query boundary\n\nquery boundary 就是一轮和下一轮之间的边界。\n\n每次跨过这个边界，系统最好都知道：\n\n- 这次为什么继续\n- 这次继续前有没有修改状态\n- 这次继续后应该怎么读主循环\n\n## 最小心智模型\n\n先不要把 query 想成一条线。\n\n更接近真实情况的理解是：\n\n```text\n一条 query\n = 一组“继续原因”串起来的状态转移\n```\n\n例如：\n\n```text\n用户输入\n ->\n模型产生 tool_use\n ->\n工具执行完\n ->\ntool_result_continuation\n ->\n模型输出过长\n ->\nmax_tokens_recovery\n ->\n压缩后继续\n ->\ncompact_retry\n ->\n最终结束\n```\n\n这样看，你会更容易理解：\n\n**系统不是单纯在 while loop 里转圈，而是在一串显式的转移原因里推进。**\n\n## 关键数据结构\n\n### 1. QueryState 里的 `transition`\n\n最小版建议就把这类字段显式放进状态里：\n\n```python\nstate = {\n \"messages\": [...],\n \"turn_count\": 3,\n \"has_attempted_compact\": False,\n \"continuation_count\": 1,\n \"transition\": None,\n}\n```\n\n这里的 `transition` 不是可有可无。\n\n它的意义是：\n\n- 当前这轮为什么会出现\n- 下一轮日志应该怎么解释\n- 测试时应该断言哪条路径被走到\n\n### 2. TransitionReason\n\n教学版最小可以先这样分：\n\n```python\nTRANSITIONS = (\n \"tool_result_continuation\",\n \"max_tokens_recovery\",\n \"compact_retry\",\n \"transport_retry\",\n \"stop_hook_continuation\",\n \"budget_continuation\",\n)\n```\n\n这几种原因的本质不一样：\n\n- `tool_result_continuation`\n 是正常主线继续\n- `max_tokens_recovery`\n 是输出被截断后的恢复继续\n- `compact_retry`\n 是上下文处理后的恢复继续\n- `transport_retry`\n 是基础设施抖动后的恢复继续\n- `stop_hook_continuation`\n 是外部控制逻辑阻止本轮结束\n- `budget_continuation`\n 是系统主动利用预算继续推进\n\n### 3. Continuation Budget\n\n更完整的 query 状态不只会说“继续”，还会限制：\n\n- 最多续写几次\n- 最多压缩后重试几次\n- 某类恢复是不是已经尝试过\n\n例如：\n\n```python\nstate = {\n \"max_output_tokens_recovery_count\": 2,\n \"has_attempted_reactive_compact\": True,\n}\n```\n\n这些字段的本质都是：\n\n> continuation 不是无限制的。\n\n## 最小实现\n\n### 第一步：把 continue site 显式化\n\n很多初学者写主循环时，所有继续逻辑都长这样：\n\n```python\ncontinue\n```\n\n教学版应该往前走一步：\n\n```python\nstate[\"transition\"] = \"tool_result_continuation\"\ncontinue\n```\n\n### 第二步：不同继续原因，配不同状态修改\n\n```python\nif response.stop_reason == \"tool_use\":\n state[\"messages\"] = append_tool_results(...)\n state[\"turn_count\"] += 1\n state[\"transition\"] = \"tool_result_continuation\"\n continue\n\nif response.stop_reason == \"max_tokens\":\n state[\"messages\"].append({\n \"role\": \"user\",\n \"content\": CONTINUE_MESSAGE,\n })\n state[\"max_output_tokens_recovery_count\"] += 1\n state[\"transition\"] = \"max_tokens_recovery\"\n continue\n```\n\n重点不是“多写一行”。\n\n重点是：\n\n**每次继续之前，你都要知道自己做了什么状态更新，以及为什么继续。**\n\n### 第三步：把恢复继续和正常继续分开\n\n```python\nif should_retry_transport(error):\n time.sleep(backoff(...))\n state[\"transition\"] = \"transport_retry\"\n continue\n\nif should_recompact(error):\n state[\"messages\"] = compact_messages(state[\"messages\"])\n state[\"transition\"] = \"compact_retry\"\n continue\n```\n\n这时候你就开始得到一条非常清楚的控制链：\n\n```text\n继续\n 不再是一个动作\n 而是一类带原因的转移\n```\n\n## 一张真正应该建立的图\n\n```text\nquery loop\n |\n +-- tool executed --------------------> transition = tool_result_continuation\n |\n +-- output truncated -----------------> transition = max_tokens_recovery\n |\n +-- compact just happened -----------> transition = compact_retry\n |\n +-- network / transport retry -------> transition = transport_retry\n |\n +-- stop hook blocked termination ---> transition = stop_hook_continuation\n |\n +-- budget says keep going ----------> transition = budget_continuation\n```\n\n## 它和逆向仓库主脉络为什么对得上\n\n如果你去看更完整系统的查询入口，会发现它真正难的地方从来不是：\n\n- 再调一次模型\n\n而是：\n\n- 什么时候该继续\n- 继续前改哪份状态\n- 继续属于哪一种路径\n\n所以这篇桥接文档讲的，不是额外装饰，而是完整 query engine 的主骨架之一。\n\n## 它和主线章节怎么接\n\n- `s01` 让你先把 loop 跑起来\n- `s06` 让你知道为什么上下文管理会介入继续路径\n- `s11` 让你知道为什么恢复路径不是一种\n- 这篇则把“继续原因”统一抬成显式状态\n\n所以你可以把它理解成：\n\n> 给前后几章之间补上一条“为什么继续”的统一主线。\n\n## 初学者最容易犯的错\n\n### 1. 只有 `continue`，没有 `transition`\n\n这样日志和测试都会越来越难看。\n\n### 2. 把所有继续都当成一种\n\n这样会把：\n\n- 正常主线继续\n- 错误恢复继续\n- 压缩后重试\n\n全部混成一锅。\n\n### 3. 没有 continuation budget\n\n没有预算，系统就会在某些坏路径里无限试下去。\n\n### 4. 把 `transition` 写进消息文本，而不是流程状态\n\n消息是给模型看的。 \n`transition` 是给系统自己看的。\n\n### 5. 压缩、恢复、hook 都发生了，却没有统一的查询状态\n\n这会导致控制逻辑散落在很多局部变量里，越长越乱。\n\n## 教学边界\n\n这篇最重要的，不是一次枚举完所有 transition 名字，而是先让你守住三件事：\n\n- `continue` 最好总能对应一个显式的 `transition reason`\n- 正常继续、恢复继续、压缩后重试，不应该被混成同一种路径\n- continuation 需要预算和状态，而不是无限重来\n\n只要这三点成立，你就已经能把 `s01 / s06 / s11` 真正串成一条完整主线。 \n更细的 transition taxonomy、预算策略和日志分类，可以放到你把最小 query 状态机写稳以后再补。\n\n## 读完这一篇你应该能说清楚\n\n至少能完整说出这句话：\n\n> 一条 query 不是简单 while loop，而是一串显式 continuation reason 驱动的状态转移。\n\n如果这句话你已经能稳定说清，那么你再回头看 `s11`、`s19`，心智会顺很多。\n"
+ },
+ {
+ "version": null,
+ "slug": "s00d-chapter-order-rationale",
+ "locale": "zh",
+ "title": "s00d: Chapter Order Rationale (为什么是这个章节顺序)",
+ "kind": "bridge",
+ "filename": "s00d-chapter-order-rationale.md",
+ "content": "# s00d: Chapter Order Rationale (为什么是这个章节顺序)\n\n> 这份文档不讲某一个机制本身。 \n> 它专门回答一个更基础的问题：\n>\n> **为什么这套仓库要按现在这个顺序教，而不是按源码目录顺序、功能热闹程度，或者“哪里复杂先讲哪里”。**\n\n## 先说结论\n\n当前这套 `s01 -> s19` 的主线顺序，整体上是合理的。\n\n它最大的优点不是“覆盖面广”，而是：\n\n- 先建立最小闭环\n- 再补横切控制面\n- 再补持久化工作层\n- 最后才扩成多 agent 平台和外部能力总线\n\n这个顺序适合教学，因为它遵守的不是“源码文件先后”，而是：\n\n**机制依赖顺序。**\n\n也就是：\n\n- 后一章需要建立在前一章已经清楚的心智之上\n- 同一层的新概念尽量一起讲完\n- 不把高阶平台能力提前压给还没建立主闭环的读者\n\n如果要把这套课程改到更接近满分，一个很重要的标准不是“加更多内容”，而是：\n\n**让读者始终知道这一章为什么现在学，而不是上一章或下一章。**\n\n这份文档就是干这件事的。\n\n## 这份顺序到底按什么排\n\n不是按这些排：\n\n- 不是按逆向源码里文件顺序排\n- 不是按实现难度排\n- 不是按功能看起来酷不酷排\n- 不是按产品里出现得早不早排\n\n它真正按的是四条依赖线：\n\n1. `主闭环依赖`\n2. `控制面依赖`\n3. `工作状态依赖`\n4. `平台边界依赖`\n\n你可以先把整套课粗暴地看成下面这条线：\n\n```text\n先让 agent 能跑\n -> 再让它不乱跑\n -> 再让它能长期跑\n -> 最后让它能分工跑、隔离跑、接外部能力跑\n```\n\n这才是当前章节顺序最核心的逻辑。\n\n## 一张总图：章节之间真正的依赖关系\n\n```text\ns00 总览与地图\n |\n v\ns01 主循环\n ->\ns02 工具执行\n ->\ns03 会话计划\n ->\ns04 子任务隔离\n ->\ns05 按需知识注入\n ->\ns06 上下文压缩\n\ns06 之后，单 agent 主骨架成立\n |\n v\ns07 权限闸门\n ->\ns08 生命周期 Hook\n ->\ns09 跨会话记忆\n ->\ns10 Prompt / 输入装配\n ->\ns11 恢复与续行\n\ns11 之后，单 agent 的高完成度控制面成立\n |\n v\ns12 持久任务图\n ->\ns13 运行时后台槽位\n ->\ns14 时间触发器\n\ns14 之后，工作系统从“聊天过程”升级成“可持续运行时”\n |\n v\ns15 持久队友\n ->\ns16 协议化协作\n ->\ns17 自治认领\n ->\ns18 worktree 执行车道\n ->\ns19 外部能力总线\n```\n\n如果你记不住所有章节，只记住每段结束后的“系统里多了什么”：\n\n- `s06` 结束：你有了能工作的单 agent\n- `s11` 结束：你有了更稳、更可控的单 agent\n- `s14` 结束：你有了能长期推进工作的运行时\n- `s19` 结束：你有了接近完整的平台边界\n\n## 为什么 `s01-s06` 必须先成一整段\n\n### `s01` 必须最先\n\n因为它定义的是：\n\n- 这套系统的最小入口\n- 每一轮到底怎么推进\n- 工具结果为什么能再次进入模型\n\n如果连这一条都没建立，后面所有内容都会变成“往空气里挂功能”。\n\n### `s02` 必须紧跟 `s01`\n\n因为没有工具，agent 只是会说，不是真的会做。\n\n开发者第一次真正感受到“harness 在做什么”，往往就是在 `s02`：\n\n- 模型产出 `tool_use`\n- 系统找到 handler\n- 执行工具\n- 回写 `tool_result`\n\n这是整个仓库第一条真正的“行动回路”。\n\n### `s03` 放在 `s04` 前面是对的\n\n很多人会直觉上想先讲 subagent，因为它更“高级”。\n\n但教学上不该这样排。\n\n原因很简单：\n\n- `s03` 先解决“当前 agent 自己怎么不乱撞”\n- `s04` 再解决“哪些工作要交给别的执行者”\n\n如果主 agent 连本地计划都没有，就提前进入子 agent，读者只会觉得：\n\n- 为什么要委派\n- 委派和待办到底是什么关系\n- 哪些是主流程，哪些是探索性流程\n\n都不清楚。\n\n所以：\n\n**先有本地计划，再有上下文隔离委派。**\n\n### `s05` 放在 `s06` 前面是对的\n\n这两个章节很多人会低估。\n\n实际上它们解决的是同一类问题的前后两半：\n\n- `s05` 解决：知识不要一开始全塞进来\n- `s06` 解决：已经塞进来的上下文怎么控制体积\n\n如果先讲压缩，再讲技能加载，读者容易误会成：\n\n- 上下文膨胀主要靠“事后压缩”解决\n\n但更合理的心智应该是：\n\n1. 先减少不必要进入上下文的东西\n2. 再处理已经进入上下文、且必须继续保留的东西\n\n所以 `s05 -> s06` 的顺序很合理。\n\n## 为什么 `s07-s11` 应该成一整段“控制面加固”\n\n这五章看起来分散，实际上它们共同在回答同一个问题：\n\n**主循环已经能跑了，但要怎样才能跑得稳、跑得可控、跑得更像一个完整系统。**\n\n### `s07` 权限必须早于 `s08` Hook\n\n因为权限是在问：\n\n- 这件事能不能做\n- 这件事做到哪一步要停\n- 这件事要不要先问用户\n\nHook 是在问：\n\n- 系统这个时刻要不要额外做点什么\n\n如果先讲 Hook，再讲权限，读者很容易误会：\n\n- 安全判断也只是某个 hook\n\n但实际上不是。\n\n更清楚的教学顺序应该是：\n\n1. 先建立“执行前必须先过闸门”的概念\n2. 再建立“主循环周围可以挂扩展点”的概念\n\n也就是：\n\n**先 gate，再 extend。**\n\n### `s09` 记忆放在 `s10` Prompt 前面是对的\n\n这是整套课程里很关键的一条顺序。\n\n很多人容易反过来讲，先讲 prompt，再讲 memory。\n\n但对开发者心智更友好的顺序其实是现在这样：\n\n- `s09` 先讲“长期信息从哪里来、哪些值得留下”\n- `s10` 再讲“这些来源最终怎样被组装进模型输入”\n\n也就是说：\n\n- `memory` 先回答“内容源是什么”\n- `prompt pipeline` 再回答“这些内容源怎么装配”\n\n如果反过来，读者会在 `s10` 里不断追问：\n\n- 为什么这里会有 memory block\n- 这块内容到底是谁准备的\n- 它和 messages、CLAUDE.md、skills 的边界在哪里\n\n所以这一条顺序不要乱换。\n\n### `s11` 放在这一段结尾很合理\n\n因为恢复与续行不是单独一层业务功能，而是：\n\n- 对前面所有输入、执行、状态、权限、压缩分支的总回收\n\n它天然适合做“控制面阶段的收口章”。\n\n只有当读者已经知道：\n\n- 一轮输入怎么组装\n- 执行时会走哪些分支\n- 发生什么状态变化\n\n他才真正看得懂恢复系统在恢复什么。\n\n## 为什么 `s12-s14` 必须先讲“任务图”，再讲“后台运行”，最后讲“定时触发”\n\n这是后半程最容易排错的一段。\n\n### `s12` 必须先于 `s13`\n\n因为 `s12` 解决的是：\n\n- 事情本身是什么\n- 依赖关系是什么\n- 哪个工作节点已完成、未完成、阻塞中\n\n而 `s13` 解决的是：\n\n- 某个执行单元现在是不是正在后台跑\n- 跑到什么状态\n- 结果怎么回流\n\n也就是：\n\n- `task` 是工作目标\n- `runtime task` 是执行槽位\n\n如果没有 `s12` 先铺开 durable work graph，读者到了 `s13` 会把后台任务误当成任务系统本体。\n\n这会直接导致后面：\n\n- cron 概念混乱\n- teammate 认领概念混乱\n- worktree lane 概念混乱\n\n所以这里一定要守住：\n\n**先有目标，再有执行体。**\n\n### `s14` 必须紧跟 `s13`\n\n因为 cron 本质上不是又一种任务。\n\n它只是回答：\n\n**如果现在不是用户当场触发，而是由时间触发一次执行，该怎么接到现有运行时里。**\n\n也就是说：\n\n- 没有 runtime slot，cron 没地方发车\n- 没有 task graph，cron 不知道在触发什么工作\n\n所以最合理顺序一定是：\n\n`task graph -> runtime slot -> schedule trigger`\n\n## 为什么 `s15-s19` 要按“队友 -> 协议 -> 自治 -> 隔离车道 -> 外部能力”排\n\n这一段如果顺序乱了，读者最容易开始觉得：\n\n- 队友、协议、任务、worktree、MCP 全都像“高级功能堆叠”\n\n但其实它们之间有很强的前后依赖。\n\n### `s15` 先定义“谁在系统里长期存在”\n\n这一章先把对象立起来：\n\n- 队友是谁\n- 他们有没有身份\n- 他们是不是可以持续存在\n\n如果连 actor 都还没清楚，协议对象就无从谈起。\n\n### `s16` 再定义“这些 actor 之间按什么规则说话”\n\n协议层不应该早于 actor 层。\n\n因为协议不是凭空存在的。\n\n它一定是服务于：\n\n- 请求谁\n- 谁审批\n- 谁响应\n- 如何回执\n\n所以：\n\n**先有队友，再有协议。**\n\n### `s17` 再进入“队友自己找活”\n\n自治不是“又多一种 agent 功能”。\n\n自治其实是建立在前两章之上的：\n\n- 前提 1：队友是长期存在的\n- 前提 2：队友之间有可追踪的协作规则\n\n只有这两个前提都建立了，自治认领才不会讲成一团雾。\n\n### `s18` 为什么在 `s19` 前面\n\n因为在平台层里，worktree 是执行隔离边界，MCP 是能力边界。\n\n对开发者自己手搓系统来说，更应先搞清：\n\n- 多个执行者如何不互相踩目录\n- 一个任务与一个执行车道如何绑定\n\n这些是“本地多执行者平台”先要解决的问题。\n\n把这个问题讲完后，再去讲：\n\n- 外部 server\n- 外部 tool\n- capability route\n\n开发者才不会把“MCP 很强”误解成“本地平台边界可以先不管”。\n\n### `s19` 放最后是对的\n\n因为它本质上是平台边界的最外层。\n\n它关心的是：\n\n- 本地系统之外的能力如何并入\n- 外部 server 和本地 tool 如何统一纳入 capability bus\n\n这个东西只有在前面这些边界都已经清楚后，读者才真的能吸收：\n\n- 本地 actor\n- 本地 work lane\n- 本地 task / runtime state\n- 外部 capability provider\n\n分别是什么。\n\n## 五种最容易让课程变差的“错误重排”\n\n### 错误 1：把 `s04` 提到 `s03` 前面\n\n坏处：\n\n- 读者先学会“把活丢出去”\n- 却还没学会“本地怎么规划”\n\n最后 subagent 只会变成“遇事就开新 agent”的逃避按钮。\n\n### 错误 2：把 `s10` 提到 `s09` 前面\n\n坏处：\n\n- 输入装配先讲了\n- 但输入源的边界还没立住\n\n结果 prompt pipeline 会看起来像一堆神秘字符串拼接。\n\n### 错误 3：把 `s13` 提到 `s12` 前面\n\n坏处：\n\n- 读者会把后台执行槽位误认成工作任务本体\n- 后面 cron、自治认领、worktree 都会越来越混\n\n### 错误 4：把 `s17` 提到 `s15` 或 `s16` 前面\n\n坏处：\n\n- 还没定义持久队友\n- 也还没定义结构化协作规则\n- 就先讲自治认领\n\n最后“自治”会被理解成模糊的自动轮询魔法。\n\n### 错误 5：把 `s19` 提到 `s18` 前面\n\n坏处：\n\n- 读者会先被外部能力系统吸引注意力\n- 却还没真正看清本地多执行者平台怎么稳定成立\n\n这会让整个课程后半程“看起来很大”，但“落到自己实现时没有抓手”。\n\n## 如果你自己手搓，可以在哪些地方先停\n\n这套课不是说一定要一次把 `s01-s19` 全做完。\n\n更稳的实现节奏是：\n\n### 里程碑 A：先做到 `s06`\n\n你已经有：\n\n- 主循环\n- 工具\n- 计划\n- 子任务隔离\n- 技能按需注入\n- 上下文压缩\n\n这已经足够做出一个“能用的单 agent 原型”。\n\n### 里程碑 B：再做到 `s11`\n\n你多了：\n\n- 权限\n- Hook\n- Memory\n- Prompt pipeline\n- 错误恢复\n\n到这里，单 agent 系统已经接近“高完成度教学实现”。\n\n### 里程碑 C：做到 `s14`\n\n你多了：\n\n- durable task\n- background runtime slot\n- cron trigger\n\n到这里，系统开始脱离“只会跟着当前会话走”的状态。\n\n### 里程碑 D：做到 `s19`\n\n这时再进入：\n\n- persistent teammate\n- protocol\n- autonomy\n- worktree lane\n- MCP / plugin\n\n这时你手里才是接近完整的平台结构。\n\n## 维护者在重排章节前该问自己什么\n\n如果你准备改顺序，先问下面这些问题：\n\n1. 这一章依赖的前置概念，前面有没有已经讲清？\n2. 这次重排会不会让两个同名但不同层的概念更容易混？\n3. 这一章新增的是“目标状态”“运行状态”“执行者”还是“外部能力”？\n4. 如果把它提前，读者会不会只记住名词，反而抓不到最小实现？\n5. 这次重排是在服务开发者实现路径，还是只是在模仿某个源码目录顺序？\n6. 读者按当前章节学完以后，本地代码到底该按什么顺序打开，这条代码阅读顺序有没有一起讲清？\n\n如果第 5 个问题的答案偏向后者，那大概率不该改。\n\n## 一句话记住\n\n**好的章节顺序，不是把所有机制排成一列，而是让每一章都像前一章自然长出来的下一层。**\n"
+ },
+ {
+ "version": null,
+ "slug": "s00e-reference-module-map",
+ "locale": "zh",
+ "title": "s00e: 参考仓库模块映射图",
+ "kind": "bridge",
+ "filename": "s00e-reference-module-map.md",
+ "content": "# s00e: 参考仓库模块映射图\n\n> 这是一份给维护者和认真学习者用的校准文档。 \n> 它不是让读者逐行读逆向源码。\n>\n> 它只回答一个很关键的问题：\n>\n> **如果把参考仓库里真正重要的模块簇，和当前教学仓库的章节顺序对照起来看，现在这套课程顺序到底合不合理？**\n\n## 先说结论\n\n合理。\n\n当前这套 `s01 -> s19` 的顺序，整体上是对的，而且比“按源码目录顺序讲”更接近真实系统的设计主干。\n\n原因很简单：\n\n- 参考仓库里目录很多\n- 但真正决定系统骨架的，是少数几簇控制、状态、任务、团队、隔离执行和外部能力模块\n- 这些高信号模块，和当前教学仓库的四阶段主线基本是对齐的\n\n所以正确动作不是把教程改成“跟着源码树走”。\n\n正确动作是：\n\n- 保留现在这条按依赖关系展开的主线\n- 把它和参考仓库的映射关系讲明白\n- 继续把低价值的产品外围细节挡在主线外\n\n## 这份对照是怎么做的\n\n这次对照主要看的是参考仓库里真正决定系统骨架的部分，例如：\n\n- `Tool.ts`\n- `state/AppStateStore.ts`\n- `coordinator/coordinatorMode.ts`\n- `memdir/*`\n- `services/SessionMemory/*`\n- `services/toolUseSummary/*`\n- `constants/prompts.ts`\n- `tasks/*`\n- `tools/TodoWriteTool/*`\n- `tools/AgentTool/*`\n- `tools/ScheduleCronTool/*`\n- `tools/EnterWorktreeTool/*`\n- `tools/ExitWorktreeTool/*`\n- `tools/MCPTool/*`\n- `services/mcp/*`\n- `plugins/*`\n- `hooks/toolPermission/*`\n\n这些已经足够判断“设计主脉络”。\n\n没有必要为了教学，再把每个命令目录、兼容分支、UI 细节和产品接线全部拖进正文。\n\n## 真正的映射关系\n\n| 参考仓库模块簇 | 典型例子 | 对应教学章节 | 为什么这样放是对的 |\n|---|---|---|---|\n| 查询主循环 + 控制状态 | `Tool.ts`、`AppStateStore.ts`、query / coordinator 状态 | `s00`、`s00a`、`s00b`、`s01`、`s11` | 真实系统绝不只是 `messages[] + while True`。教学上先讲最小循环，再补控制平面，是对的。 |\n| 工具路由与执行面 | `Tool.ts`、原生 tools、tool context、执行辅助逻辑 | `s02`、`s02a`、`s02b` | 参考仓库明确把 tools 做成统一执行面，不只是玩具版分发表。当前拆法是合理的。 |\n| 会话规划 | `TodoWriteTool` | `s03` | 这是“当前会话怎么不乱撞”的小结构，应该早于持久任务图。 |\n| 一次性委派 | `AgentTool` 的最小子集 | `s04` | 参考仓库的 agent 体系很大，但教学仓库先教“新上下文 + 子任务 + 摘要返回”这个最小正确版本，是对的。 |\n| 技能发现与按需加载 | `DiscoverSkillsTool`、`skills/*`、相关 prompt 片段 | `s05` | 技能不是花哨外挂，而是知识注入层，所以应早于 prompt 复杂化和上下文压力。 |\n| 上下文压力与压缩 | `services/toolUseSummary/*`、`services/contextCollapse/*`、compact 逻辑 | `s06` | 参考仓库明确存在显式压缩机制，把这一层放在平台化能力之前完全正确。 |\n| 权限闸门 | `types/permissions.ts`、`hooks/toolPermission/*`、审批处理器 | `s07` | 执行安全是明确闸门，不是“某个 hook 顺手干的事”，所以必须早于 hook。 |\n| Hook 与侧边扩展 | `types/hooks.ts`、hook runner、生命周期接线 | `s08` | 参考仓库把扩展点和权限分开。教学顺序保持“先 gate，再 extend”是对的。 |\n| 持久记忆选择 | `memdir/*`、`services/SessionMemory/*`、记忆提取与筛选 | `s09` | 参考仓库把 memory 处理成“跨会话、选择性装配”的层，不是通用笔记本。 |\n| Prompt 组装 | `constants/prompts.ts`、prompt sections、memory prompt 注入 | `s10`、`s10a` | 参考仓库明显把输入拆成多个 section。教学版把 prompt 讲成流水线，而不是一段大字符串，是正确的。 |\n| 恢复与续行 | query transition、retry 分支、compact retry、token recovery | `s11`、`s00c` | 真实系统里“为什么继续下一轮”是显式存在的，所以恢复应当晚于 loop / tools / compact / permissions / memory / prompt。 |\n| 持久工作图 | 任务记录、任务板、依赖解锁 | `s12` | 当前教程把“持久任务目标”和“会话内待办”分开，是对的。 |\n| 活着的运行时任务 | `tasks/types.ts`、`LocalShellTask`、`LocalAgentTask`、`RemoteAgentTask`、`MonitorMcpTask` | `s13`、`s13a` | 参考仓库里 runtime task 是明确的联合类型，这强烈证明 `TaskRecord` 和 `RuntimeTaskState` 必须分开教。 |\n| 定时触发 | `ScheduleCronTool/*`、`useScheduledTasks` | `s14` | 调度是建在 runtime work 之上的新启动条件，放在 `s13` 后非常合理。 |\n| 持久队友 | `InProcessTeammateTask`、team tools、agent registry | `s15` | 参考仓库清楚地从一次性 subagent 继续长成长期 actor。把 teammate 放到后段是对的。 |\n| 结构化团队协作 | send-message 流、request tracking、coordinator mode | `s16` | 协议必须建立在“已有持久 actor”之上，所以不能提前。 |\n| 自治认领与恢复 | coordinator mode、任务认领、异步 worker 生命周期、resume 逻辑 | `s17` | 参考仓库里的 autonomy 不是魔法，而是建立在 actor、任务和协议之上的。 |\n| Worktree 执行车道 | `EnterWorktreeTool`、`ExitWorktreeTool`、agent worktree 辅助逻辑 | `s18` | 参考仓库把 worktree 当作执行边界 + 收尾状态来处理。当前放在 tasks / teams 后是正确的。 |\n| 外部能力总线 | `MCPTool`、`services/mcp/*`、`plugins/*`、MCP resources / prompts / tools | `s19`、`s19a` | 参考仓库把 MCP / plugin 放在平台最外层边界。把它放最后是合理的。 |\n\n## 这份对照最能证明的 5 件事\n\n### 1. `s03` 应该继续放在 `s12` 前面\n\n参考仓库里同时存在：\n\n- 小范围的会话计划\n- 大范围的持久任务 / 运行时系统\n\n它们不是一回事。\n\n所以教学顺序应当继续保持：\n\n`会话内计划 -> 持久任务图`\n\n### 2. `s09` 应该继续放在 `s10` 前面\n\n参考仓库里的输入装配，明确把 memory 当成输入来源之一。\n\n也就是说：\n\n- `memory` 先回答“内容从哪里来”\n- `prompt pipeline` 再回答“这些内容怎么组装进去”\n\n所以先讲 `s09`，再讲 `s10`，顺序不要反过来。\n\n### 3. `s12` 必须早于 `s13`\n\n`tasks/types.ts` 这类运行时任务联合类型，是这次对照里最强的证据之一。\n\n它非常清楚地说明：\n\n- 持久化的工作目标\n- 当前活着的执行槽位\n\n必须是两层不同状态。\n\n如果先讲 `s13`，读者几乎一定会把这两层混掉。\n\n### 4. `s15 -> s16 -> s17` 的顺序是对的\n\n参考仓库里明确能看到：\n\n- 持久 actor\n- 结构化协作\n- 自治认领 / 恢复\n\n自治必须建立在前两者之上，所以当前顺序合理。\n\n### 5. `s18` 应该继续早于 `s19`\n\n参考仓库把 worktree 当作本地执行边界机制。\n\n这应该先于：\n\n- 外部能力提供者\n- MCP server\n- plugin 装配面\n\n被讲清。\n\n否则读者会误以为“外部能力系统比本地执行边界更核心”。\n\n## 这套教学仓库仍然不该抄进主线的内容\n\n参考仓库里有很多真实但不应该占据主线的内容，例如：\n\n- CLI 命令面的完整铺开\n- UI 渲染细节\n- 遥测与分析分支\n- 远程 / 企业产品接线\n- 平台兼容层\n- 文件名、函数名、行号级 trivia\n\n这些不是假的。\n\n但它们不该成为 0 到 1 教学路径的中心。\n\n## 当前教学最容易漂掉的地方\n\n### 1. 不要把 subagent 和 teammate 混成一个模糊概念\n\n参考仓库里的 `AgentTool` 横跨了：\n\n- 一次性委派\n- 后台 worker\n- 持久 worker / teammate\n- worktree 隔离 worker\n\n这恰恰说明教学仓库应该继续拆开讲：\n\n- `s04`\n- `s15`\n- `s17`\n- `s18`\n\n不要在早期就把这些东西混成一个“大 agent 能力”。\n\n### 2. 不要把 worktree 教成“只是 git 小技巧”\n\n参考仓库里有 closeout、resume、cleanup、dirty-check 等状态。\n\n所以 `s18` 必须继续讲清：\n\n- lane 身份\n- task 绑定\n- keep / remove 收尾\n- 恢复与清理\n\n而不是只讲 `git worktree add`。\n\n### 3. 不要把 MCP 缩成“远程 tools”\n\n参考仓库里明显不只有工具，还有：\n\n- resources\n- prompts\n- elicitation / connection state\n- plugin 中介层\n\n所以 `s19` 可以继续用 tools-first 的教学路径切入，但一定要补平台边界那一层地图。\n\n## 最终判断\n\n如果只拿“章节顺序是否贴近参考仓库的设计主干”这个问题来打分，那么当前这套顺序是过关而且方向正确的。\n\n真正还能继续加分的地方，不再是再做一次大重排，而是：\n\n- 把桥接文档补齐\n- 把实体边界讲得更硬\n- 把多语言内容统一到同一个心智层次\n- 让 web 页面把这套学习地图展示得更清楚\n\n## 一句话记住\n\n**最好的教学顺序，不是源码文件出现的顺序，而是一个初学实现者真正能顺着依赖关系把系统重建出来的顺序。**\n"
+ },
+ {
+ "version": null,
+ "slug": "s00f-code-reading-order",
+ "locale": "zh",
+ "title": "s00f: 本仓库代码阅读顺序",
+ "kind": "bridge",
+ "filename": "s00f-code-reading-order.md",
+ "content": "# s00f: 本仓库代码阅读顺序\n\n> 这份文档不是让你“多看代码”。 \n> 它专门解决另一个问题：\n>\n> **当你已经知道章节顺序是对的以后，本仓库代码到底应该按什么顺序读，才不会把心智重新读乱。**\n\n## 先说结论\n\n不要这样读代码：\n\n- 不要从文件最长的那一章开始\n- 不要随机点一个你觉得“高级”的章节开始\n- 不要先钻 `web/` 再回头猜主线\n- 不要把 19 个 `agents/*.py` 当成一个源码池乱翻\n\n最稳的读法只有一句话：\n\n**文档顺着章节读，代码也顺着章节读。**\n\n而且每一章的代码，都先按同一个模板看：\n\n1. 先看状态结构\n2. 再看工具定义或注册表\n3. 再看“这一轮怎么推进”的主函数\n4. 最后才看 CLI 入口和试运行方式\n\n## 为什么需要这份文档\n\n很多读者不是看不懂某一章文字，而是会在真正打开代码以后重新乱掉。\n\n典型症状是：\n\n- 一上来先盯住 300 行以上的文件底部\n- 先看一堆 `run_*` 函数，却不知道它们挂在哪条主线上\n- 先看“最复杂”的平台章节，然后觉得前面的章节好像都太简单\n- 把 `task`、`runtime task`、`teammate`、`worktree` 在代码里重新混成一团\n\n这份阅读顺序就是为了防止这种情况。\n\n## 读每个 agent 文件时，都先按同一个模板\n\n不管你打开的是哪一章，本仓库里的 `agents/sXX_*.py` 都建议先按下面顺序读：\n\n### 第一步：先看文件头注释\n\n先回答两个问题：\n\n- 这一章到底在教什么\n- 它故意没有教什么\n\n如果连这一步都没建立，后面你会把每个函数都看成同等重要。\n\n### 第二步：先看状态结构或管理器类\n\n优先找这些东西：\n\n- `LoopState`\n- `PlanningState`\n- `CompactState`\n- `TaskManager`\n- `BackgroundManager`\n- `TeammateManager`\n- `WorktreeManager`\n\n原因很简单：\n\n**先知道系统到底记住了什么，后面才看得懂它为什么要这样流动。**\n\n### 第三步：再看工具列表或注册表\n\n优先找这些入口：\n\n- `TOOLS`\n- `TOOL_HANDLERS`\n- 各种 `run_*`\n- `build_tool_pool()`\n\n这一层回答的是：\n\n- 模型到底能调用什么\n- 这些调用会落到哪条执行面上\n\n### 第四步：最后才看主推进函数\n\n重点函数通常长这样：\n\n- `run_one_turn(...)`\n- `agent_loop(...)`\n- 某个 `handle_*`\n\n这一步要回答的是：\n\n- 这一章新机制到底接在主循环哪一环\n- 哪个分支是新增的\n- 新状态是在哪里写入、回流、继续的\n\n### 第五步：最后再看 `if __name__ == \"__main__\"`\n\nCLI 入口当然有用，但它不应该成为第一屏。\n\n因为它通常只是在做：\n\n- 读用户输入\n- 初始化状态\n- 调用 `agent_loop`\n\n真正决定一章心智主干的，不在这里。\n\n## 阶段 1：`s01-s06` 应该怎样读代码\n\n这一段不是在学“很多功能”，而是在学：\n\n**一个单 agent 主骨架到底怎样成立。**\n\n| 章节 | 文件 | 先看什么 | 再看什么 | 读完要确认什么 |\n|---|---|---|---|---|\n| `s01` | `agents/s01_agent_loop.py` | `LoopState` | `TOOLS` -> `execute_tool_calls()` -> `run_one_turn()` -> `agent_loop()` | 你已经能看懂 `messages -> model -> tool_result -> next turn` |\n| `s02` | `agents/s02_tool_use.py` | `safe_path()` | `run_read()` / `run_write()` / `run_edit()` -> `TOOL_HANDLERS` -> `agent_loop()` | 你已经能看懂“主循环不变，工具靠分发面增长” |\n| `s03` | `agents/s03_todo_write.py` | `PlanItem` / `PlanningState` / `TodoManager` | `todo` 相关 handler -> reminder 注入 -> `agent_loop()` | 你已经能看懂“会话计划状态”怎么外显化 |\n| `s04` | `agents/s04_subagent.py` | `AgentTemplate` | `run_subagent()` -> 父 `agent_loop()` | 你已经能看懂“子智能体首先是上下文隔离” |\n| `s05` | `agents/s05_skill_loading.py` | `SkillManifest` / `SkillDocument` / `SkillRegistry` | `get_descriptions()` / `get_content()` -> `agent_loop()` | 你已经能看懂“先发现、再按需加载” |\n| `s06` | `agents/s06_context_compact.py` | `CompactState` | `persist_large_output()` -> `micro_compact()` -> `compact_history()` -> `agent_loop()` | 你已经能看懂“压缩不是删历史，而是转移细节” |\n\n### 这一段最值得反复看的 3 个代码点\n\n1. `state` 在哪里第一次从“聊天内容”升级成“显式系统状态”\n2. `tool_result` 是怎么一直保持为统一回流接口的\n3. 新机制是怎样接进 `agent_loop()` 而不是把 `agent_loop()` 重写烂的\n\n### 这一段读完后，最好的动作\n\n不要立刻去看 `s07`。\n\n先自己从空目录手写一遍下面这些最小件：\n\n- 一个 loop\n- 一个 dispatch map\n- 一个会话计划状态\n- 一个一次性子任务隔离\n- 一个按需技能加载\n- 一个最小压缩层\n\n## 阶段 2：`s07-s11` 应该怎样读代码\n\n这一段不是在学“又多了五种功能”。\n\n它真正是在学：\n\n**单 agent 的控制面是怎样长出来的。**\n\n| 章节 | 文件 | 先看什么 | 再看什么 | 读完要确认什么 |\n|---|---|---|---|---|\n| `s07` | `agents/s07_permission_system.py` | `BashSecurityValidator` / `PermissionManager` | 权限判定入口 -> `run_bash()` -> `agent_loop()` | 你已经能看懂“先 gate，再 execute” |\n| `s08` | `agents/s08_hook_system.py` | `HookManager` | hook 注册与触发 -> `agent_loop()` | 你已经能看懂 hook 是固定时机的插口，不是散落 if |\n| `s09` | `agents/s09_memory_system.py` | `MemoryManager` / `DreamConsolidator` | `run_save_memory()` -> `build_system_prompt()` -> `agent_loop()` | 你已经能看懂 memory 是长期信息层，不是上下文垃圾桶 |\n| `s10` | `agents/s10_system_prompt.py` | `SystemPromptBuilder` | `build_system_reminder()` -> `agent_loop()` | 你已经能看懂输入是流水线，不是单块 prompt |\n| `s11` | `agents/s11_error_recovery.py` | `estimate_tokens()` / `auto_compact()` / `backoff_delay()` | 各恢复分支 -> `agent_loop()` | 你已经能看懂“恢复以后怎样继续下一轮” |\n\n### 这一段读代码时，最容易重新读乱的地方\n\n1. 把权限和 hook 混成一类\n2. 把 memory 和 prompt 装配混成一类\n3. 把 `s11` 看成很多异常判断，而不是“续行控制”\n\n如果你开始混，先回：\n\n- `docs/zh/s00a-query-control-plane.md`\n- `docs/zh/s10a-message-prompt-pipeline.md`\n- `docs/zh/s00c-query-transition-model.md`\n\n## 阶段 3：`s12-s14` 应该怎样读代码\n\n这一段开始，代码理解的关键不再是“工具多了什么”，而是：\n\n**系统第一次真正长出会话外工作状态和运行时槽位。**\n\n| 章节 | 文件 | 先看什么 | 再看什么 | 读完要确认什么 |\n|---|---|---|---|---|\n| `s12` | `agents/s12_task_system.py` | `TaskManager` | 任务创建、依赖、解锁 -> `agent_loop()` | 你已经能看懂 task 是持久工作图，不是 todo |\n| `s13` | `agents/s13_background_tasks.py` | `NotificationQueue` / `BackgroundManager` | 后台执行登记 -> 通知排空 -> `agent_loop()` | 你已经能看懂 background task 是运行槽位 |\n| `s14` | `agents/s14_cron_scheduler.py` | `CronLock` / `CronScheduler` | `cron_matches()` -> schedule 触发 -> `agent_loop()` | 你已经能看懂调度器只负责“未来何时开始” |\n\n### 这一段读代码时一定要守住的边界\n\n- `task` 是工作目标\n- `runtime task` 是正在跑的执行槽位\n- `schedule` 是何时触发工作\n\n只要这三层在代码里重新混掉，后面 `s15-s19` 会一起变难。\n\n## 阶段 4：`s15-s19` 应该怎样读代码\n\n这一段不要当成“功能狂欢”去读。\n\n它真正建立的是：\n\n**平台边界。**\n\n| 章节 | 文件 | 先看什么 | 再看什么 | 读完要确认什么 |\n|---|---|---|---|---|\n| `s15` | `agents/s15_agent_teams.py` | `MessageBus` / `TeammateManager` | 队友名册、邮箱、独立循环 -> `agent_loop()` | 你已经能看懂 teammate 是长期 actor，不是一次性 subagent |\n| `s16` | `agents/s16_team_protocols.py` | `RequestStore` / `TeammateManager` | `handle_shutdown_request()` / `handle_plan_review()` -> `agent_loop()` | 你已经能看懂 request-response + `request_id` |\n| `s17` | `agents/s17_autonomous_agents.py` | `RequestStore` / `TeammateManager` | `is_claimable_task()` / `claim_task()` / `ensure_identity_context()` -> `agent_loop()` | 你已经能看懂自治主线：空闲检查 -> 安全认领 -> 恢复工作 |\n| `s18` | `agents/s18_worktree_task_isolation.py` | `TaskManager` / `WorktreeManager` / `EventBus` | `worktree_enter` 相关生命周期 -> `agent_loop()` | 你已经能看懂 task 管目标，worktree 管执行车道 |\n| `s19` | `agents/s19_mcp_plugin.py` | `CapabilityPermissionGate` / `MCPClient` / `PluginLoader` / `MCPToolRouter` | `build_tool_pool()` / `handle_tool_call()` / `normalize_tool_result()` -> `agent_loop()` | 你已经能看懂外部能力如何接回同一控制面 |\n\n### 这一段最容易误读的地方\n\n1. 把 `s15` 的 teammate 当成 `s04` 的 subagent 放大版\n2. 把 `s17` 自治看成“agent 自己乱跑”\n3. 把 `s18` worktree 看成一个 git 小技巧\n4. 把 `s19` MCP 缩成“只是远程 tools”\n\n## 代码阅读时，哪些文件不要先看\n\n如果你的目标是建立主线心智，下面这些内容不要先看：\n\n- `web/` 里的可视化实现细节\n- `web/src/data/generated/*`\n- `.next/` 或其他构建产物\n- `agents/s_full.py`\n\n原因不是它们没价值。\n\n而是：\n\n- `web/` 解决的是展示与学习界面\n- `generated` 是抽取结果，不是机制本身\n- `s_full.py` 是整合参考，不适合第一次建立边界\n\n## 最推荐的“文档 + 代码 + 运行”循环\n\n每一章最稳的学习动作不是只看文档，也不是只看代码。\n\n推荐固定走这一套：\n\n1. 先读这一章正文\n2. 再读这一章的桥接资料\n3. 再打开对应 `agents/sXX_*.py`\n4. 按“状态 -> 工具 -> 主推进函数 -> CLI 入口”的顺序看\n5. 跑一次这章的 demo\n6. 自己从空目录重写一个最小版本\n\n只要你每章都这样走一次，代码理解会非常稳。\n\n## 初学者最容易犯的 6 个代码阅读错误\n\n### 1. 先看最长文件\n\n这通常只会先把自己看晕。\n\n### 2. 先盯 `run_bash()` 这种工具细节\n\n工具实现细节不是主干。\n\n### 3. 不先找状态结构\n\n这样你永远不知道系统到底记住了什么。\n\n### 4. 把 `agent_loop()` 当成唯一重点\n\n主循环当然重要，但每章真正新增的边界，往往在状态容器和分支入口。\n\n### 5. 读完代码不跑 demo\n\n不实际跑一次，很难建立“这一章到底新增了哪条回路”的感觉。\n\n### 6. 一口气连看三四章代码，不停下来自己重写\n\n这样最容易出现“我好像都看过，但其实自己不会写”的错觉。\n\n## 一句话记住\n\n**代码阅读顺序也必须服从教学顺序：先看边界，再看状态，再看主线如何推进，而不是随机翻源码。**\n"
},
{
"version": "s01",
+ "slug": "s01-the-agent-loop",
"locale": "zh",
- "title": "s01: The Agent Loop (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 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\": \"Update your todos. \",\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 轮后注入 `` |\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\": \"Refresh your plan before continuing. \",\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| |\n| Full git workflow instructions... | ~2000 tokens\n| Step 1: ... |\n| |\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\"\\n{skill['body']}\\n \"\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\n完整审查说明\n \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\nFull output saved to: .task_outputs/tool-results/abc123.txt\nPreview:\n...\n \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 \"\\n\"\n f\"Full output saved to: {stored_path}\\n\"\n f\"Preview:\\n{preview}\\n\"\n \" \"\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\"\\n{notif_text}\\n\"\n f\" \"})\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} \"})\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} \"})\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\"Task #{unclaimed[0]['id']}: \"\n f\"{unclaimed[0]['subject']} \"})\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\"You are '{name}', role: {role}, \"\n f\"team: {team_name}. Continue your work. \"})\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\": \"You are 'alice', role: frontend, team: default. Continue your work. \",\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\"Task #{task['id']}: {task['subject']} \",\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 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 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\": \"Update your todos. \",\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 | `` 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\": \"Refresh your plan before continuing. \",\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| |\n| Full git workflow instructions... | ~2000 tokens\n| Step 1: ... |\n| |\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\"\\n{skill['body']}\\n \"\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| |\n| Full git workflow instructions... | ~2000 tokens\n| Step 1: ... |\n| |\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\"\\n{skill['body']}\\n \"\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 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: \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 # \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\"\\n{notif_text}\\n\"\n f\" \"})\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} \"})\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} \"})\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\"Task #{unclaimed[0]['id']}: \"\n f\"{unclaimed[0]['subject']} \"})\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\"You are '{name}', role: {role}, \"\n f\"team: {team_name}. Continue your work. \"})\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\"\\n{notif_text}\\n \",\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\": \"You are 'alice', role: frontend, team: default. Continue your work. \",\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\"Task #{task['id']}: {task['subject']} \",\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 \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\": \"Update your todos. \"})\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 \"Refresh your current plan before continuing. \"\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\"\\n\"\n f\"{document.body}\\n\"\n \" \"\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 \"\\n\"\n f\"Full output saved to: {rel_path}\\n\"\n \"Preview:\\n\"\n f\"{preview}\\n\"\n \" \"\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\": \"\", \"path\": \"\", \"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 | |\n | Full PDF processing instructions | <-- Layer 2: full body\n | Step 1: ... |\n | Step 2: ... |\n | |\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//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\"\\n{skill['body']}\\n \"\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. /CLAUDE.md (project instructions)\n 3. /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 = \"\\n\" + \"\\n\".join(parts) + \"\\n \"\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\"\\n{notif_text}\\n \"})\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\"\\n{notif_text}\\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 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\"{json.dumps(inbox, indent=2)} \",\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\"{json.dumps(inbox, indent=2)} \",\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\"{json.dumps(inbox, indent=2)} \",\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\"{json.dumps(inbox, indent=2)} \",\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\"You are '{name}', role: {role}, team: {team_name}. Continue your work. \",\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\"Task #{task['id']}: {task['subject']}\\n\"\n f\"{task.get('description', '')} \"\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\"{json.dumps(inbox, indent=2)} \",\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\"You are '{name}', role: {role}, team: {team_name}. Continue your work. \",\n }\n\n\ndef ensure_identity_context(messages: list, name: str, role: str, team_name: str):\n if messages and \"\" 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\"Task #{task['id']}: {task['subject']}\\n\"\n f\"{task.get('description', '')} \"\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\"{json.dumps(inbox, indent=2)} \",\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;
+ summary: Record;
+}
+
+export const BRIDGE_DOCS: Record = {
+ "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
+> = {
+ "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> = {
+ 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> = {
+ 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 = {
- 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, 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, 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(
+ 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;
+ body: Record;
+ rebuild: Record;
+}
+
+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> = {
+ 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
}