agent-lyceum 0.14.0 → 0.15.0

package/README.md

@@ -90,7 +90,8 @@ Changes take effect on the next session start. If the pane shows `無法取得
     ├── agents/<agent>/{AGENT.md?, memory/}   # project-level persona (optional) + project memory
     ├── shared/common/COMMON.md
     ├── locks/<run-id>.json           # held while that run is active (up to dispatcher.max_concurrent_runs at once)
-    └── runs/<run-id>/{task.md, log.jsonl, state.json, snapshots/, agents/, mail/{inbox,outbox}/<agent>/}
+    ├── task-memory/<run-id>/{<agent>/, _shared/}   # per-run memory, never shared between runs; _shared = the lead's handoff notes for follow-ups
+    └── runs/<run-id>/{task.md, log.jsonl, state.json, result.md, done-<n>.md, followups/<n>.md, snapshots/, agents/, mail/{inbox,outbox}/<agent>/}
 ```
 
 `team.yaml` defines reusable agents; `project.yaml` picks the team and overrides fields. Objects merge field by field, arrays (`can_message`, `owns`) are replaced. Relative paths resolve against the folder of the file they are written in; `~` is allowed.
@@ -148,6 +149,7 @@ A finished (`done`) run can be reopened with a follow-up request: `agent-lyceum
 - **What is kept:** the follow-up is saved as `runs/<run-id>/followups/<n>.md`. Each `done` report is kept as `done-<n>.md`, and `result.md` is always the latest. `state.json` gains `name`, `reopened` and `round_floor` (all optional, so older runs still load). Unresolved blocked integrations stay; the done-contract reminders start afresh for each reopened segment.
 - **Round limit:** `max_rounds` counts from the reopen: `rounds` keeps accumulating, and the limit is the rounds at reopen plus `max_rounds`.
 - **The lead's branch** (runs with a lead worktree): if the branch was already merged into your `HEAD` and the lead worktree is clean and untouched since the run ended, the worktree and the branch (same name, `agent-lyceum/<run-id>/<lead>`) are re-cut from your current `HEAD`, and a line says so. Otherwise the same worktree and branch continue. If a pull request was already recorded (`pr_url`) and the branch was not re-cut, a new `open_pr: true` only pushes ("pull request updated") while that pull request is still open; if it was merged (a squash merge included) or closed, a new pull request is opened instead. If the branch was re-cut, the recorded `pr_url` is cleared (the old URL stays in the run's notes) and a new pull request is opened when asked. agent-lyceum still never merges.
+- **Handoff notes:** before it sends `done`, the lead writes what a follow-up will need into `task-memory/<run-id>/_shared/` in the agent-lyceum home (`MEMORY.md` is the index): decisions and why, interfaces agreed, current state, what is left and the next steps, pitfalls met. Members can read this folder but not write it (a run started with `run --agent` has one agent, which is its own lead and writes it; `call` has none). Once a run is reopened, every wake-up of every agent gets `MEMORY.md` in its prompt (the first 8 KB; a longer index is cut and flagged), and the reopened `task` mail's `Upstream` names it; the first segment's prompts do not contain it. If the lead sends `done` without having changed `MEMORY.md` in that segment, the run is not blocked: a note `shared-not-updated` is added to the run's notes. `clear` deletes the folder with the task memory; `tidy` does not touch it. It holds notes about this task only; lessons that outlive it belong in project or global memory.
 
 ### Opening a pull request
 
@@ -201,6 +203,7 @@ Default rules (everything else in the repo is unrestricted):
 |---|---|
 | own memory dirs, own `outbox/` | writable |
 | any `AGENT.md`, `COMMON.md`, repo `CLAUDE.md`/`AGENTS.md` | read-only; the lead (`can_edit_agent_md`) may edit them |
+| the run's handoff notes `task-memory/<run-id>/_shared/` | the lead writes; every other agent is read-only |
 | other agents' memory/inbox/outbox, `runs/`, config files | not writable |
 
 Enforcement is layered because no single mechanism is complete:
@@ -209,7 +212,7 @@ Enforcement is layered because no single mechanism is complete:
 - **Codex**: `-s workspace-write` with `-c sandbox_workspace_write.writable_roots=[...]` (OS-enforced). Codex cannot forbid a single file inside the repo, so repo `CLAUDE.md`/`AGENTS.md` are protected by **post-hoc detection** only.
 - **All runtimes**: protected files are hashed before the run; after each wake-up unauthorized changes are reverted, logged, and reported to the lead; what was written is kept in `runs/<run-id>/violations/` first.
 
-`doctor` and `run` print every agent's level per category (`os`, `tool-rules`, `post-hoc`, `prompt-only`) and the paths it can write outside the repo. With `dispatcher.strict: true`, a run is refused unless memory, `AGENT.md` and other agents' context are OS-enforced.
+`doctor` and `run` print every agent's level per category (`os`, `tool-rules`, `post-hoc`, `prompt-only`) and the paths it can write outside the repo. With `dispatcher.strict: true`, a run is refused unless memory, `AGENT.md`, other agents' context and (for non-lead agents) the handoff notes are OS-enforced.
 
 Git in agent worktrees: an agent can write its worktree's `.git` pointer file and its private git dir, which could make git read a config or hooks the agent planted. So every git call the dispatcher makes into an agent's worktree pins the git dir, common dir and work tree recorded when the worktree was made, turns off hooks, fsmonitor, external diff and textconv, and refuses a worktree whose git files were redirected or linked elsewhere, whose HEAD is not its own branch, or that contains a nested repository. Claude additionally may not write those pointer files (`denyWrite`); Codex cannot forbid single files and relies on the pinning alone. Residual risks are listed in [spec 15](docs/specs/15-worktree-git-isolation.md#156-殘留風險). This does not claim the dispatcher can never run code an agent planted. A repository using the `reftable` ref backend is refused in worktree modes.
 

package/README.zh-TW.md

@@ -90,8 +90,8 @@ claude --plugin-dir /path/to/agent-lyceum/plugins/status-monitor
     ├── agents/<agent>/{AGENT.md?, memory/}   # 專案層人設（選用）+ 專案記憶
     ├── shared/common/COMMON.md
     ├── locks/<run-id>.json           # 該 run 執行期間持有（同時最多 dispatcher.max_concurrent_runs 個）
-    ├── task-memory/<run-id>/<agent>/   # 任務記憶：每次 run 獨立，不與其他任務共用
-    └── runs/<run-id>/{task.md, log.jsonl, state.json, snapshots/, agents/, mail/{inbox,outbox}/<agent>/}
+    ├── task-memory/<run-id>/{<agent>/, _shared/}   # 任務記憶：每次 run 獨立，不與其他任務共用；_shared 是 lead 為追加要求寫的交接筆記
+    └── runs/<run-id>/{task.md, log.jsonl, state.json, result.md, done-<n>.md, followups/<n>.md, snapshots/, agents/, mail/{inbox,outbox}/<agent>/}
 ```
 
 `team.yaml` 定義可重複使用的 agent；`project.yaml` 選擇團隊並覆寫欄位。物件會逐欄位合併，陣列（`can_message`、`owns`）則整個取代。相對路徑以寫入該路徑的檔案所在資料夾為基準；允許使用 `~`。
@@ -149,6 +149,7 @@ Agent 欄位：`runtime`（`claude-code`|`codex`；若 `model` 可辨識則可
 - **保留什麼：** 追加要求存成 `runs/<run-id>/followups/<n>.md`。每份 `done` 報告保留為 `done-<n>.md`，`result.md` 永遠是最新一份。`state.json` 新增 `name`、`reopened`、`round_floor`（都是選填，舊的 run 照樣能讀）。未解決的 blocked integration 會保留；每段重開的 done 規範提醒重新計算。
 - **輪數上限：** `max_rounds` 從重開時起算：`rounds` 持續累加，上限是重開當下的輪數加 `max_rounds`。
 - **lead 的 branch**（lead 有 worktree 的 run）：若該 branch 已合併進你的 `HEAD`，且 lead 的 worktree 乾淨、自 run 結束後沒被動過，worktree 與 branch（同名，`agent-lyceum/<run-id>/<lead>`）會從你目前的 `HEAD` 重新切出，並印一行說明。否則沿用原本的 worktree 與 branch。若已記錄 PR（`pr_url`）且 branch 沒有重切，新的 `open_pr: true` 只會 push（「pull request updated」），而且只在該 PR 仍開啟時；若它已被合併（含 squash merge）或關閉，就改開一個新的 PR；若 branch 重切了，已記錄的 `pr_url` 會被清掉（舊網址留在 run 的 notes），要求時再開一個新的 PR。agent-lyceum 仍然從不合併。
+- **交接筆記：** lead 在送 `done` 之前，把追加要求會用到的內容寫進 agent-lyceum home 裡的 `task-memory/<run-id>/_shared/`（`MEMORY.md` 為索引）：做過的決定與理由、介面約定、目前狀態、剩下的事與下一步、踩過的坑。成員可讀不可寫（用 `run --agent` 啟動的 run 只有一個 agent，它就是自己的 lead，所以可寫；`call` 沒有這個資料夾）。run 重開後，每個 agent 的每次喚醒都在 prompt 裡拿到 `MEMORY.md`（前 8 KB，較長的索引會被截斷並標示），重開的 `task` 信的 `Upstream` 也會指向它；第一段的 prompt 不含它。若 lead 在該段沒有更動 `MEMORY.md` 就送出 `done`，run 不會被擋，只會在 run 的 notes 加一筆 `shared-not-updated`。`clear` 會連同任務記憶一併刪除；`tidy` 不會動它。只放這個 task 的筆記，跨 task 的教訓仍放 project 或 global memory。
 
 ### 開 PR
 
@@ -202,6 +203,7 @@ agents:
 |---|---|
 | 自己的記憶資料夾、自己的 `outbox/` | 可寫入 |
 | 任何 `AGENT.md`、`COMMON.md`、repo 的 `CLAUDE.md`/`AGENTS.md` | 唯讀；lead（`can_edit_agent_md`）可編輯 |
+| run 的交接筆記 `task-memory/<run-id>/_shared/` | lead 可寫；其他 agent 唯讀 |
 | 其他 agent 的記憶／inbox／outbox、`runs/`、設定檔 | 不可寫入 |
 
 由於沒有單一機制是完整的，防護採分層設計：
@@ -210,7 +212,7 @@ agents:
 - **Codex**：`-s workspace-write` 搭配 `-c sandbox_workspace_write.writable_roots=[...]`（由 OS 強制）。Codex 無法禁止 repo 內的單一檔案，所以 repo 的 `CLAUDE.md`/`AGENTS.md` 只能靠**事後偵測**保護。
 - **所有 runtime**：執行前會對受保護檔案做雜湊；每次喚醒後，未經授權的變更會被還原、記錄，並通報 lead；被寫入的內容會先留存在 `runs/<run-id>/violations/`。
 
-`doctor` 與 `run` 會依類別（`os`、`tool-rules`、`post-hoc`、`prompt-only`）印出每個 agent 的防護等級，以及它能寫入 repo 之外的哪些路徑。設定 `dispatcher.strict: true` 時，除非記憶、`AGENT.md` 與其他 agent 的 context 都由 OS 強制保護，否則拒絕執行。
+`doctor` 與 `run` 會依類別（`os`、`tool-rules`、`post-hoc`、`prompt-only`）印出每個 agent 的防護等級，以及它能寫入 repo 之外的哪些路徑。設定 `dispatcher.strict: true` 時，除非記憶、`AGENT.md`、其他 agent 的 context 與（非 lead 的 agent 的）交接筆記都由 OS 強制保護，否則拒絕執行。
 
 agent worktree 內的 git:agent 能寫它 worktree 的 `.git` 指標檔與私有 git 目錄,可能讓 git 去讀 agent 埋的設定或 hook。因此 dispatcher 對 agent worktree 的每一次 git 呼叫,都釘住 worktree 建立當下記錄的 git dir、common dir 與 work tree,關閉 hook、fsmonitor、external diff 與 textconv,並拒絕使用 git 檔案被改向或連到別處、HEAD 不是它自己的分支、或內含巢狀 repository 的 worktree。Claude 另外不得寫那幾個指標檔(`denyWrite`);Codex 無法禁止單一檔案,只靠釘住。殘留風險列在 [spec 15](docs/specs/15-worktree-git-isolation.md#156-殘留風險)。這**不**表示 dispatcher 絕不會執行 agent 埋下的程式碼。使用 `reftable` ref 後端的 repository 在 worktree 模式下會被拒絕。
 

package/dist/adapters/claude.js

@@ -62,7 +62,7 @@ export function buildClaudeInvocation(input) {
     fs.writeFileSync(systemFile, input.systemPrompt);
     const pol = writePolicy(project, agent);
     const repo = repoDirFor(project, agent.name);
-    const addDirs = [...pol.allowDirs, ...pol.allowFiles.map((f) => path.dirname(f))].filter((d) => !(d === repo || d.startsWith(repo + path.sep)));
+    const addDirs = [...pol.allowDirs, ...pol.readDirs, ...pol.allowFiles.map((f) => path.dirname(f))].filter((d) => !(d === repo || d.startsWith(repo + path.sep)));
     const args = [
         "-p",
         "--output-format",

package/dist/fs-util.d.ts

@@ -2,3 +2,11 @@
 export declare function atomicWrite(file: string, content: string): void;
 /** Is `cmd` an executable file in one of the PATH directories? (No `which`: it may be missing in slim containers.) */
 export declare function findOnPath(cmd: string, pathVar?: string): boolean;
+/**
+ * Up to `limit` bytes of a regular file (symlinks to one are followed), and whether there was more.
+ * undefined for anything else (missing, a directory, a FIFO, a device) or on any error: never throws, never reads a huge file whole.
+ */
+export declare function readFileCapped(file: string, limit: number): {
+    text: string;
+    truncated: boolean;
+} | undefined;

package/dist/fs-util.js

@@ -22,3 +22,39 @@ export function findOnPath(cmd, pathVar = process.env.PATH ?? "") {
         }
     });
 }
+/**
+ * Up to `limit` bytes of a regular file (symlinks to one are followed), and whether there was more.
+ * undefined for anything else (missing, a directory, a FIFO, a device) or on any error: never throws, never reads a huge file whole.
+ */
+export function readFileCapped(file, limit) {
+    let fd;
+    try {
+        if (!fs.statSync(file).isFile())
+            return undefined;
+        fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
+        if (!fs.fstatSync(fd).isFile())
+            return undefined;
+        const buf = Buffer.alloc(limit + 1);
+        let n = 0;
+        while (n < buf.length) {
+            const r = fs.readSync(fd, buf, n, buf.length - n, n);
+            if (r === 0)
+                break;
+            n += r;
+        }
+        if (n <= limit)
+            return { text: buf.subarray(0, n).toString("utf8"), truncated: false };
+        return { text: buf.subarray(0, limit).toString("utf8"), truncated: true };
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch { }
+        }
+    }
+}

package/dist/guard.js

@@ -1,7 +1,7 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { commonFile, mayEditProtected, repoInstructionFiles } from "./policy.js";
+import { commonFile, mayEditProtected, repoInstructionFiles, sharedIndex } from "./policy.js";
 export const MAX_KEEP_BYTES = 1024 * 1024;
 function safeName(file) {
     return file.replace(/[\\/:]/g, "_").replace(/^_+/, "");
@@ -32,6 +32,9 @@ export class ProtectedGuard {
         files.add(commonFile(project));
         for (const f of repoInstructionFiles(project))
             files.add(f);
+        const handoff = sharedIndex(project);
+        if (handoff)
+            files.add(handoff);
         return [...files];
     }
     /** Copy the current protected files into `dir` for the audit trail. */

package/dist/mailbox.js

@@ -5,7 +5,7 @@ import YAML from "yaml";
 import { formatWarning, missingSections, parseSteps } from "./format.js";
 import { atomicWrite } from "./fs-util.js";
 import { deterministicId, fault, RouteJournal, sourceIdOf } from "./message-store.js";
-import { inboxDir, outboxDir } from "./policy.js";
+import { inboxDir, outboxDir, sharedDir } from "./policy.js";
 import { must } from "./assert.js";
 export { atomicWrite };
 export const MESSAGE_TYPES = ["task", "reply", "failure", "done", "ask"];
@@ -33,6 +33,9 @@ export function parseRaw(text) {
 }
 export function ensureProjectDirs(project) {
     fs.mkdirSync(path.join(project.paths.shared, "common"), { recursive: true });
+    const handoff = sharedDir(project);
+    if (handoff)
+        fs.mkdirSync(handoff, { recursive: true });
     for (const name of Object.keys(project.agents)) {
         fs.mkdirSync(path.join(inboxDir(project, name), "read"), { recursive: true });
         fs.mkdirSync(path.join(outboxDir(project, name), "rejected"), { recursive: true });

package/dist/policy.d.ts

@@ -6,6 +6,7 @@ export interface AgentEnforcement {
     memory: Level;
     agentMd: Level;
     otherContext: Level;
+    shared: Level;
     repoInstructions: Level;
     owns: Level;
     /** Absolute paths outside the repo this agent may write. */
@@ -15,6 +16,8 @@ export interface AgentEnforcement {
 export interface WritePolicy {
     /** Directories the agent may write to (besides the repo). */
     allowDirs: string[];
+    /** Directories the agent may read besides the repo and its writable ones, but must not write (the run's handoff notes, for everyone but the lead). */
+    readDirs: string[];
     /** Individual files the agent may write (outside allowDirs). */
     allowFiles: string[];
     /** Files/dirs that must stay unwritable (checked even inside the repo). */
@@ -29,6 +32,12 @@ export declare function inboxDir(project: ResolvedProject, agent: string): strin
 /** The repo's own CLAUDE.md/AGENTS.md: in the lead's worktree when it has one (concurrent runs), else in the repo. */
 export declare function repoInstructionFiles(project: ResolvedProject): string[];
 export declare function memoryDirs(a: ResolvedAgent): string[];
+/** Folder name of a run's handoff notes inside `task-memory/<run-id>/`. Agent names start with a letter or digit, so it cannot be an agent's own folder. */
+export declare const SHARED_DIR = "_shared";
+/** The run's handoff folder: read by every agent, written only by the lead. Undefined outside a run and for `call`. */
+export declare function sharedDir(project: ResolvedProject): string | undefined;
+/** The index of the handoff notes: the one file shown in prompts, and the one the guard watches. */
+export declare function sharedIndex(project: ResolvedProject): string | undefined;
 /** The repo directory this agent works in: its own worktree, or the main repo. */
 export declare function repoDirFor(project: ResolvedProject, agent: string): string;
 export declare function writePolicy(project: ResolvedProject, agent: ResolvedAgent): WritePolicy;

package/dist/policy.js

@@ -19,6 +19,19 @@ export function repoInstructionFiles(project) {
 export function memoryDirs(a) {
     return [a.memory.global, a.memory.project, a.memory.task].filter((x) => !!x);
 }
+/** Folder name of a run's handoff notes inside `task-memory/<run-id>/`. Agent names start with a letter or digit, so it cannot be an agent's own folder. */
+export const SHARED_DIR = "_shared";
+/** The run's handoff folder: read by every agent, written only by the lead. Undefined outside a run and for `call`. */
+export function sharedDir(project) {
+    if (!project.run || project.solo === "call")
+        return undefined;
+    return path.join(project.paths.taskMemory, project.run.id, SHARED_DIR);
+}
+/** The index of the handoff notes: the one file shown in prompts, and the one the guard watches. */
+export function sharedIndex(project) {
+    const dir = sharedDir(project);
+    return dir ? path.join(dir, "MEMORY.md") : undefined;
+}
 const RUN_ENTRIES = ["state.json", "log.jsonl", "log.1.jsonl", "result.md", "task.md", "snapshots", "violations", "agents", "mail"];
 const MAIL_ENTRIES = ["inbox", "claims", "attempts", "journal.jsonl"];
 function entries(dir) {
@@ -54,10 +67,20 @@ export function writePolicy(project, agent) {
     const isLead = agent.name === project.lead && !project.solo;
     const ws = project.workspaces?.[agent.name];
     // A `call` has no mailboxes at all; a solo member of a run keeps its outbox to send `done`.
-    const allowDirs = [...memoryDirs(agent), ...(project.solo === "call" ? [] : [outboxDir(project, agent.name)]), ...(ws ? [ws.gitDir] : [])];
+    const shared = sharedDir(project);
+    const sharedIdx = sharedIndex(project);
+    const mayWriteShared = !!shared && agent.name === project.lead;
+    const allowDirs = [
+        ...memoryDirs(agent),
+        ...(project.solo === "call" ? [] : [outboxDir(project, agent.name)]),
+        ...(ws ? [ws.gitDir] : []),
+        ...(shared && mayWriteShared ? [shared] : []),
+    ];
     const allowFiles = [];
     if (isLead)
         allowFiles.push(commonFile(project));
+    if (mayWriteShared && sharedIdx)
+        allowFiles.push(sharedIdx);
     if (agent.canEditAgentMd) {
         for (const a of Object.values(project.agents))
             allowFiles.push(a.agentMd);
@@ -81,6 +104,8 @@ export function writePolicy(project, agent) {
     addDeny(commonFile(project));
     for (const f of repoInstructionFiles(project))
         addDeny(f);
+    if (shared && !mayWriteShared)
+        deny.push(shared);
     deny.push(...runDenyPaths(project), project.paths.config, path.join(project.home, "team.yaml"));
     // In a worktree: other agents' checkouts are off limits, and so are this checkout's own copies of the protected files.
     for (const [name, other] of Object.entries(project.workspaces ?? {}))
@@ -95,6 +120,7 @@ export function writePolicy(project, agent) {
         deny.push(path.join(ws.root, ".git"), ...["commondir", "config.worktree", "gitdir"].map((f) => path.join(ws.gitDir, f)));
     return {
         allowDirs,
+        readDirs: shared && !mayWriteShared ? [shared] : [],
         allowFiles,
         deny: [...new Set(deny)],
         owns: agent.owns,
@@ -118,17 +144,22 @@ export function enforcementFor(project, agent) {
     const os = osSandboxAvailable();
     const notes = [];
     const parallel = project.dispatcher.max_parallel > 1;
+    const isLeadAgent = agent.name === project.lead;
     let e;
     if (agent.runtime === "claude-code") {
         const lvl = os ? "os" : "tool-rules";
-        e = { memory: lvl, agentMd: lvl, otherContext: lvl, repoInstructions: lvl, owns: parallel ? "tool-rules" : "n/a" };
+        e = { memory: lvl, agentMd: lvl, otherContext: lvl, shared: isLeadAgent ? "n/a" : lvl, repoInstructions: lvl, owns: parallel ? "tool-rules" : "n/a" };
         if (!os)
             notes.push("OS sandbox unavailable (Windows, or Linux without bubblewrap): Bash can bypass Edit rules.");
+        if (!isLeadAgent && !os)
+            notes.push("Without the OS sandbox Bash can write _shared; only the handoff index (_shared/MEMORY.md) is checked after each wake-up.");
     }
     else {
         const lvl = os ? "os" : "prompt-only";
-        e = { memory: lvl, agentMd: lvl, otherContext: lvl, repoInstructions: "post-hoc", owns: parallel ? "prompt-only" : "n/a" };
+        e = { memory: lvl, agentMd: lvl, otherContext: lvl, shared: isLeadAgent ? "n/a" : os ? "os" : "post-hoc", repoInstructions: "post-hoc", owns: parallel ? "prompt-only" : "n/a" };
         notes.push("Codex cannot forbid single files inside the repo; CLAUDE.md/AGENTS.md changes are detected and reverted after each wake-up.");
+        if (!isLeadAgent && !os)
+            notes.push("Without the OS sandbox only the handoff index (_shared/MEMORY.md) is checked after each wake-up; other files in _shared are not protected.");
         if (agent.canEditAgentMd)
             notes.push("can_edit_agent_md widens Codex writable roots to whole agent directories.");
     }

package/dist/prompt.d.ts

@@ -3,6 +3,7 @@ import type { Message } from "./mailbox.js";
 import type { Layer, MemoryFile, MissingPath, ProjectChanges } from "./memory-tidy.js";
 export declare const COMMON_LIMIT: number;
 export declare const MEMORY_INDEX_LIMIT: number;
+export declare const HANDOFF_LIMIT: number;
 export declare const LEAD_BATCH_LIMIT = 5;
 export declare function readPersona(agent: ResolvedAgent): string;
 /** The protocol of an agent working alone: no teammates, no ask. `run --agent` still ends with a `done` mail; `call` just answers. */
@@ -13,7 +14,7 @@ export declare function buildCallUserPrompt(agent: ResolvedAgent, task: string):
 export declare function buildSystemPrompt(project: ResolvedProject, agent: ResolvedAgent): string;
 /** Messages one wake-up handles: the oldest one, or for the lead a run of `reply`/`failure` mail (up to LEAD_BATCH_LIMIT) so it decides once on all of it. */
 export declare function pickMessages(project: ResolvedProject, agent: ResolvedAgent, queue: Message[]): Message[];
-export declare function buildUserPrompt(project: ResolvedProject, agent: ResolvedAgent, unread: Message[], handleCount?: number): string;
+export declare function buildUserPrompt(project: ResolvedProject, agent: ResolvedAgent, unread: Message[], handleCount?: number, handoff?: boolean): string;
 export interface TidyContext {
     layer: Layer;
     /** The memory directory being tidied. */

package/dist/prompt.js

@@ -1,7 +1,8 @@
 import fs from "node:fs";
+import { readFileCapped } from "./fs-util.js";
 import path from "node:path";
 import { REQUIRED_SECTIONS } from "./format.js";
-import { commonFile, memoryDirs, outboxDir, repoDirFor } from "./policy.js";
+import { commonFile, memoryDirs, outboxDir, repoDirFor, sharedDir, sharedIndex } from "./policy.js";
 function memoryLabel(agent, dir) {
     if (dir === agent.memory.task)
         return "task (this task only, isolated)";
@@ -9,16 +10,10 @@ function memoryLabel(agent, dir) {
 }
 export const COMMON_LIMIT = 8 * 1024;
 export const MEMORY_INDEX_LIMIT = 4 * 1024;
+export const HANDOFF_LIMIT = COMMON_LIMIT;
 export const LEAD_BATCH_LIMIT = 5;
 const BATCHABLE = new Set(["reply", "failure"]);
-function readCapped(file, limit) {
-    if (!fs.existsSync(file))
-        return undefined;
-    const buf = fs.readFileSync(file);
-    if (buf.length <= limit)
-        return { text: buf.toString("utf8"), truncated: false };
-    return { text: buf.subarray(0, limit).toString("utf8"), truncated: true };
-}
+const readCapped = readFileCapped;
 /** A PR only needs to say agent-lyceum opened it; no agent or role names. */
 const PR_ATTRIBUTION_RULE = "- If you open a pull request, end its description with a line saying it was opened by agent-lyceum (e.g. `🤖 Opened by agent-lyceum`). Do not name any agent or role in it.";
 /** A tool call that never returns (a server or daemon started in the foreground) burns the whole wake-up timeout and the finished work is thrown away with it. */
@@ -28,6 +23,14 @@ const OPEN_PR_RULE = "Add the frontmatter line `open_pr: true` to `done` only wh
 export function readPersona(agent) {
     return fs.readFileSync(agent.agentMd, "utf8").trim();
 }
+/** What the lead (or a solo agent) is told about the handoff notes: they are what a reopened task starts from. */
+function handoffRule(dir) {
+    return [
+        "",
+        "## Handoff for follow-ups",
+        `This task may be reopened later with a follow-up request, and the agents woken then start with fresh sessions. Before you send \`done\`, write what they need to carry on into \`${dir}\`: keep a \`MEMORY.md\` index there (one line per entry, pointing at a file) and record the decisions made and why, the interfaces agreed, the current state, what is left and what to do next, and the pitfalls met. Your teammates can read this folder but cannot write it; if a report from a teammate holds something worth keeping, add it yourself. Only the index is shown in prompts, and only the first ${HANDOFF_LIMIT / 1024} KB of it, so keep it short. These notes are about this task only; lessons that outlive it belong in your project or global memory.`,
+    ];
+}
 /** The protocol of an agent working alone: no teammates, no ask. `run --agent` still ends with a `done` mail; `call` just answers. */
 export function buildSoloSystemPrompt(project, agent) {
     const isCall = project.solo === "call";
@@ -38,6 +41,9 @@ export function buildSoloSystemPrompt(project, agent) {
     if (!isCall) {
         lines.push("## Finishing", `When the job is finished, create a Markdown file (any name ending in \`.md\`) directly inside \`${outboxDir(project, agent.name)}\` with this exact shape:`, "", "```", "---", "type: done", "subject: <short subject>", "outcome: completed|partial|blocked|failed", "---", "", "## Result", "## Files", "## Verification", "## Not done", "```", "", "That ends the run. `## Result` is the actual deliverable or conclusion (not just \"done\"), `## Files` the paths you created or changed, `## Verification` what you ran or checked and what it showed, `## Not done` anything skipped or unverified (or `None`). Only `completed` means success and it needs all four headings; if work remains or is blocked say `partial`/`blocked`/`failed` (those need only `## Result` and `## Not done`). A summary in your reply text is never delivered: without a `done` mail the run ends as idle with no report. " + OPEN_PR_RULE);
     }
+    const shared = sharedDir(project);
+    if (!isCall && shared)
+        lines.push(...handoffRule(shared));
     lines.push("", "## Memory");
     const mems = memoryDirs(agent);
     if (mems.length === 0)
@@ -111,7 +117,7 @@ export function buildSystemPrompt(project, agent) {
             "Your final `done` mail must also include the full `## Steps` checklist. Tick only steps that were actually done and verified; leave undone ones",
             "(e.g. build, app start, commit) unticked and say so in the mail instead of reporting them as finished.",
         ]
-        : []), "", "## Memory");
+        : []), ...(isLead && sharedDir(project) ? handoffRule(sharedDir(project)) : []), "", "## Memory");
     const mems = memoryDirs(agent);
     if (mems.length === 0)
         lines.push("You have no long-term memory directory.");
@@ -143,7 +149,7 @@ export function pickMessages(project, agent, queue) {
     }
     return run;
 }
-export function buildUserPrompt(project, agent, unread, handleCount = 1) {
+export function buildUserPrompt(project, agent, unread, handleCount = 1, handoff = false) {
     const parts = [];
     const common = readCapped(commonFile(project), COMMON_LIMIT);
     parts.push("# Shared team context (COMMON.md)");
@@ -155,6 +161,14 @@ export function buildUserPrompt(project, agent, unread, handleCount = 1) {
             parts.push(`\n[COMMON.md was truncated at ${COMMON_LIMIT} bytes — the lead should condense it.]`);
         }
     }
+    const handoffFile = handoff ? sharedIndex(project) : undefined;
+    const notes = handoffFile ? readCapped(handoffFile, HANDOFF_LIMIT) : undefined;
+    if (handoffFile && notes?.text.trim()) {
+        parts.push("", `# Handoff notes from earlier segments of this task (${handoffFile})`, notes.text.trim());
+        if (notes.truncated)
+            parts.push(`\n[handoff index truncated at ${HANDOFF_LIMIT} bytes — the lead should condense it.]`);
+        parts.push("The other files in that folder are there to read on demand.");
+    }
     for (const dir of memoryDirs(agent)) {
         const idx = readCapped(path.join(dir, "MEMORY.md"), MEMORY_INDEX_LIMIT);
         const label = memoryLabel(agent, dir).split(" ")[0];

package/dist/run-session.d.ts

@@ -59,6 +59,8 @@ export interface RunOptions {
 export declare class RunSession {
     private readonly opts;
     private readonly resume;
+    /** The handoff index as this segment started; the lead is noted when it is the same at `done`. */
+    private readonly sharedAtStart;
     private readonly invoke;
     private readonly say;
     private readonly cfg;

package/dist/run-session.js

@@ -9,9 +9,9 @@ import { abandonClaim, attemptLogDir, sourceIdOf, beginAttempt, claimMessages, c
 import { isInside } from "./paths.js";
 import { createRunLog } from "./run-log.js";
 import { endOutcome, resolveDoneOutcome } from "./run-outcome.js";
-import { outboxDir, ownsDirs } from "./policy.js";
+import { outboxDir, ownsDirs, sharedIndex } from "./policy.js";
 import { buildSystemPrompt, buildUserPrompt, pickMessages } from "./prompt.js";
-import { atomicWrite } from "./fs-util.js";
+import { atomicWrite, readFileCapped } from "./fs-util.js";
 import { assertWorktreeRunnable, collectAgentChanges, dirtyPaths, existingAgentWorkspace, finishLeadBranch, integrateAgentChanges, prepareAgentWorkspace, recutLeadWorkspace, refusedIntegration, resolveWorkspaceMode, snapshotBase, snapshotHead, toplevel } from "./worktree.js";
 import { bindRunProject, newRunId, newRunState, roundLimit, saveRunState } from "./run-store.js";
 import { soloProject } from "./solo.js";
@@ -24,6 +24,14 @@ export const RESULT_FILE = "result.md";
 export const MAX_DONE_REJECTIONS = 2;
 /** How many times a malformed `ask` goes back to its sender before the lead is told instead. */
 export const MAX_ASK_REJECTIONS = 2;
+/** How much of the handoff index is compared; the prompts show far less. */
+const INDEX_COMPARE_LIMIT = 1024 * 1024;
+/** The text of a file, "" when it is missing, undefined when there is no such file for this run (no handoff folder). */
+function readIndex(file) {
+    if (!file)
+        return undefined;
+    return readFileCapped(file, INDEX_COMPARE_LIMIT)?.text ?? "";
+}
 /** Prompt for a repeat attempt: the earlier one failed and may have changed things already. */
 function retryPrompt(prompt, error) {
     return `${prompt}\n\n# Retry notice\nYour previous attempt at this wake-up failed${error ? ` (${error})` : ""} after possibly changing files already. Its mail was discarded. Check the current state of the repository before redoing the work, and send the mail again.`;
@@ -31,6 +39,8 @@ function retryPrompt(prompt, error) {
 export class RunSession {
     opts;
     resume;
+    /** The handoff index as this segment started; the lead is noted when it is the same at `done`. */
+    sharedAtStart;
     invoke;
     say;
     cfg;
@@ -176,12 +186,14 @@ export class RunSession {
                 const legacy = path.join(runDir, RESULT_FILE);
                 if (!fs.existsSync(prev) && fs.existsSync(legacy))
                     fs.copyFileSync(legacy, prev);
+                const handoffIdx = sharedIndex(project);
+                const handoffLine = handoffIdx && fs.existsSync(handoffIdx) ? ` The handoff notes written for follow-ups are in \`${handoffIdx}\`.` : "";
                 deliver(project, {
                     from: "user",
                     to: project.lead,
                     type: "task",
                     subject: opts.followup.text.split("\n").find((l) => l.trim())?.slice(0, 80) ?? "Follow-up",
-                    body: `## Goal\n${opts.followup.text.trimEnd()}\n\n## Acceptance criteria\nAs stated in the goal; the earlier result still holds unless the goal changes it.\n\n## Scope\nThis run's earlier work and files.\n\n## Upstream\nThe previous final report is in \`${path.join(runDir, `done-${n}.md`)}\`; the original task is in \`${path.join(runDir, "task.md")}\`.\n`,
+                    body: `## Goal\n${opts.followup.text.trimEnd()}\n\n## Acceptance criteria\nAs stated in the goal; the earlier result still holds unless the goal changes it.\n\n## Scope\nThis run's earlier work and files.\n\n## Upstream\nThe previous final report is in \`${path.join(runDir, `done-${n}.md`)}\`; the original task is in \`${path.join(runDir, "task.md")}\`.${handoffLine}\n`,
                 });
                 log("reopen", { n });
             }
@@ -207,6 +219,8 @@ export class RunSession {
         this.log = log;
         this.guard = guard;
         this.state = state;
+        // Only a segment that starts here has a baseline: a fresh run or a follow-up reopen. A plain resume continues one begun by an earlier process.
+        this.sharedAtStart = !resume || opts.followup ? readIndex(sharedIndex(project)) : undefined;
     }
     /** A waiting run only continues once every unanswered question has a valid answer. */
     static assertAnswered(runDir, runId) {
@@ -283,7 +297,7 @@ export class RunSession {
             workDir,
             workspace: spaces[agent.name],
             systemPrompt: buildSystemPrompt(aproject, agent),
-            userPrompt: buildUserPrompt(project, agent, queue, unread.length),
+            userPrompt: buildUserPrompt(project, agent, queue, unread.length, (state.reopened?.length ?? 0) > 0),
             timeoutSec: cfg.wake_timeout_sec,
         };
         let result;
@@ -508,6 +522,13 @@ export class RunSession {
             log("rejected", r);
         }
         if (route.done) {
+            const handoffIdx = sharedIndex(project);
+            const nowShared = handoffIdx && this.sharedAtStart !== undefined ? readIndex(handoffIdx) : undefined;
+            if (nowShared !== undefined && nowShared === this.sharedAtStart) {
+                this.note(nowShared.trim()
+                    ? `shared-not-updated: the lead did not change the handoff notes (${handoffIdx}) in this segment; a follow-up will see them as they are.`
+                    : `shared-not-updated: the lead did not write handoff notes (${handoffIdx}) in this segment, so a follow-up will start without handoff notes.`);
+            }
             this.doneMessage = { subject: route.done.subject, body: route.done.body };
             this.openPrRequested = route.done.meta.open_pr === true;
             const resolved = resolveDoneOutcome(must(contract, "completion contract of the done report"), state.done_rejections ?? 0, state.blocked_integrations ?? []);

package/dist/validate.js

@@ -100,8 +100,8 @@ export function validateProject(project) {
     const enforcement = Object.values(project.agents).map((a) => enforcementFor(project, a));
     if (project.dispatcher.strict) {
         for (const e of enforcement) {
-            for (const k of ["memory", "agentMd", "otherContext"]) {
-                if (e[k] !== "os")
+            for (const k of ["memory", "agentMd", "otherContext", "shared"]) {
+                if (e[k] !== "os" && !(k === "shared" && e[k] === "n/a"))
                     err(`strict: agent "${e.agent}" ${k} protection is "${e[k]}", not OS-enforced.`);
             }
         }
@@ -109,10 +109,10 @@ export function validateProject(project) {
     return { issues, enforcement, ok: !issues.some((i) => i.level === "error") };
 }
 export function formatEnforcement(list) {
-    const header = ["agent", "runtime", "memory", "AGENT.md", "others' ctx", "repo CLAUDE/AGENTS", "owns"];
+    const header = ["agent", "runtime", "memory", "AGENT.md", "others' ctx", "handoff", "repo CLAUDE/AGENTS", "owns"];
     const rows = [header];
     for (const e of list)
-        rows.push([e.agent, e.runtime, e.memory, e.agentMd, e.otherContext, e.repoInstructions, e.owns]);
+        rows.push([e.agent, e.runtime, e.memory, e.agentMd, e.otherContext, e.shared, e.repoInstructions, e.owns]);
     const w = header.map((_, i) => Math.max(...rows.map((r) => (r[i] ?? "").length)));
     const lines = rows.map((r) => r.map((c, i) => c.padEnd(w[i] ?? 0)).join("  ").trimEnd());
     lines.splice(1, 0, w.map((n) => "-".repeat(n)).join("  "));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-lyceum",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Config + dispatcher for teams of Claude Code / Codex agents with scoped context and file-based mailboxes",
   "keywords": [
     "ai",