agent-lyceum 0.6.0 → 0.7.0

package/README.md

@@ -28,7 +28,8 @@ Requires Node 20+, plus `claude` and/or `codex` on your `PATH` (already logged i
 | `project add <name> --dir <repo>` | Register a project. [details](docs/commands.md#project-add) |
 | `project list` / `project remove <name> [--purge]` | List or unregister projects. [details](docs/commands.md#project-list-and-remove) |
 | `validate [-p name] [--task-file f]` | Validate the merged config and show each agent's enforcement level. [details](docs/commands.md#validate) |
-| `run ["task"] [--task-file f] [-p name]` | Give the task to the lead and run until done. [details](docs/commands.md#run) |
+| `run ["task"] [--task-file f] [--agent a] [-p name]` | Give the task to the lead and run until done; with `--agent`, to one member alone. [details](docs/commands.md#run) |
+| `call <agent> ["task"] [--task-file f] [--dir d]` | Call one global agent on its own, outside any project; prints its answer. [details](docs/commands.md#call) |
 | `resume [run-id] [-p name]` | Continue an interrupted or failed run. [details](docs/commands.md#resume) |
 | `answer <run-id> [--no-edit] [-p name]` | Answer the questions a waiting run asked, then continue it. [details](docs/commands.md#answer) |
 | `status [-p name] [--monitor]` | Show agents, mail, the current wake-up and past runs (`--json`, `--monitor`). [details](docs/commands.md#status) |
@@ -41,6 +42,17 @@ Requires Node 20+, plus `claude` and/or `codex` on your `PATH` (already logged i
 
 Ctrl-C cancels a run cleanly and it can be continued with `resume` ([Stopping a run](docs/commands.md#stopping-a-run)). `run` and `resume` exit `0` only when the lead reported `completed`, `2` for partial or blocked, `1` for failed, `3` while waiting for your answers, `130` for cancelled ([Exit codes](docs/commands.md#exit-codes)). Without `-p`, the project is inferred from the current directory ([Choosing the project](docs/commands.md#choosing-the-project)).
 
+## Running one agent on its own
+
+Two ways to give a task to a single agent instead of the whole team. The agent works alone: it cannot mail teammates, ask you questions or edit any `AGENT.md`.
+
+```bash
+npx agent-lyceum run "tidy the form" --agent fe-member -p web   # a member of the project, as an ordinary run
+npx agent-lyceum call pm "is this ready to build?" --dir ~/code/web-app   # a global agent, outside any project
+```
+
+`run --agent` has a run id and the project lock, shows in `status`, and can be resumed; the agent ends the run with its own `done` mail. `call` needs no project at all: the agent comes from `team.yaml`, works in `--dir` (default: the current directory, which must not be inside or above the agent-lyceum home), prints only its final answer on stdout, and keeps `task.md`, `log/` and `result.md` in `<home>/calls/<call-id>/`. Details: [run](docs/commands.md#run) and [call](docs/commands.md#call).
+
 ## Monitor mod (Claude Code)
 
 `plugins/status-monitor` is a Claude Code **mod**, not an ordinary plugin: it is written against Claude Code's mod hooks API (`import type { Register } from 'claude-code'`) and runs inside the Claude Code session, where it adds a status line entry, toasts and a `/status-monitor` pane that poll `agent-lyceum status --json`. It needs a Claude Code build that supports mods; it does not change how agent-lyceum itself runs. It shows live run status for one or several projects.
@@ -75,6 +87,7 @@ Changes take effect on the next session start. If the pane shows `無法取得
 ~/agent-lyceum-config/
 ├── team.yaml                         # global agent library
 ├── agents/<agent>/{AGENT.md, memory/}  # global persona + cross-project memory
+├── calls/<call-id>/{task.md, log/, result.md}   # one folder per `call` (outside any project), plus .lock-<agent>
 └── projects/<project>/
     ├── project.yaml                  # team, repo dir, overrides
     ├── agents/<agent>/{AGENT.md?, memory/}   # project-level persona (optional) + project memory

package/README.zh-TW.md

@@ -28,7 +28,8 @@ npx agent-lyceum status
 | `project add <name> --dir <repo>` | 註冊專案。 [詳細](docs/commands.zh-TW.md#project-add) |
 | `project list` / `project remove <name> [--purge]` | 列出或取消註冊專案。 [詳細](docs/commands.zh-TW.md#project-list-and-remove) |
 | `validate [-p name] [--task-file f]` | 驗證設定並顯示每個 agent 的防護等級。 [詳細](docs/commands.zh-TW.md#validate) |
-| `run ["task"] [--task-file f] [-p name]` | 把任務交給 lead 並執行到結束。 [詳細](docs/commands.zh-TW.md#run) |
+| `run ["task"] [--task-file f] [--agent a] [-p name]` | 把任務交給 lead 並執行到結束；加 `--agent` 則只交給某個成員單獨做。 [詳細](docs/commands.zh-TW.md#run) |
+| `call <agent> ["task"] [--task-file f] [--dir d]` | 單獨呼叫一個 global agent（不需專案），印出它的回答。 [詳細](docs/commands.zh-TW.md#call) |
 | `resume [run-id] [-p name]` | 接續被中斷或失敗的 run。 [詳細](docs/commands.zh-TW.md#resume) |
 | `answer <run-id> [--no-edit] [-p name]` | 回答等待中的 run 提出的問題，並接續執行。 [詳細](docs/commands.zh-TW.md#answer) |
 | `status [-p name] [--monitor]` | 顯示 agent、信件、目前執行與歷次 run（支援 `--json`、`--monitor`）。 [詳細](docs/commands.zh-TW.md#status) |
@@ -41,6 +42,17 @@ npx agent-lyceum status
 
 Ctrl-C 會乾淨地取消 run，之後可用 `resume` 接續（[中止 run](docs/commands.zh-TW.md#中止-run)）。`run`／`resume` 只有在 lead 回報 `completed` 時才 exit `0`；`partial`／`blocked` 為 `2`，`failed` 為 `1`，等待你回答時為 `3`，取消為 `130`（[退出碼](docs/commands.zh-TW.md#退出碼)）。未指定 `-p` 時，專案由目前目錄推斷（[選擇專案](docs/commands.zh-TW.md#選擇專案)）。
 
+## 單獨呼叫一個 agent
+
+有兩種方式把任務只交給單一 agent，而不是整個團隊。該 agent 獨自工作：不能寄信給隊友、不能向你提問、不能修改任何 `AGENT.md`。
+
+```bash
+npx agent-lyceum run "整理表單" --agent fe-member -p web   # 專案裡的一個成員，當作一般 run
+npx agent-lyceum call pm "這個需求可以開工了嗎？" --dir ~/code/web-app   # global agent，不屬於任何專案
+```
+
+`run --agent` 有 run id 與專案鎖、會出現在 `status`、可以 `resume`；agent 用自己寄出的 `done` 結束 run。`call` 完全不需要專案：agent 取自 `team.yaml`，在 `--dir`（預設是目前目錄，且不可位於 agent-lyceum home 之內或之上）工作，stdout 只印它的最終回答，並在 `<home>/calls/<call-id>/` 留下 `task.md`、`log/` 與 `result.md`。細節見 [run](docs/commands.zh-TW.md#run) 與 [call](docs/commands.zh-TW.md#call)。
+
 ## 監控 mod（Claude Code）
 
 `plugins/status-monitor` 是 Claude Code **mod**，不是一般的 plugin：它依 Claude Code 的 mod hooks API 撰寫（`import type { Register } from 'claude-code'`），在 Claude Code session 內執行，提供狀態列、通知與 `/status-monitor` 面板，並輪詢 `agent-lyceum status --json`。需要支援 mod 的 Claude Code 版本；不會改變 agent-lyceum 本身的運作。會顯示一個或多個專案的即時執行狀態。
@@ -75,6 +87,7 @@ claude --plugin-dir /path/to/agent-lyceum/plugins/status-monitor
 ~/agent-lyceum-config/
 ├── team.yaml                         # 全域 agent 庫
 ├── agents/<agent>/{AGENT.md, memory/}  # 全域人設 + 跨專案記憶
+├── calls/<call-id>/{task.md, log/, result.md}   # 每次 `call`（不屬於任何專案）一個資料夾，另有 .lock-<agent>
 └── projects/<project>/
     ├── project.yaml                  # 團隊、repo 路徑、覆寫設定
     ├── agents/<agent>/{AGENT.md?, memory/}   # 專案層人設（選用）+ 專案記憶

package/dist/call.d.ts

@@ -0,0 +1,35 @@
+import { type Invoker } from "./adapters/index.js";
+import { type ResolvedAgent, type ResolvedProject } from "./config.js";
+export declare const CALL_PROJECT = "(call)";
+export declare const callsDir: (home: string) => string;
+export interface CallOptions {
+    home: string;
+    agent: string;
+    task: string;
+    /** Working directory; must exist. */
+    dir: string;
+    invoker?: Invoker;
+    signal?: AbortSignal;
+    say?: (line: string) => void;
+}
+export interface CallResult {
+    callId: string;
+    callDir: string;
+    ok: boolean;
+    cancelled: boolean;
+    /** The agent's final reply (empty when the call failed). */
+    text: string;
+    error?: string;
+    /** Protected files the agent changed and agent-lyceum put back. */
+    reverted: string[];
+}
+/** A global agent (from team.yaml) as a `call` uses it: global persona and memory, nobody to mail, nothing to ask, nothing to edit. */
+export declare function resolveCallAgent(home: string, name: string): ResolvedAgent;
+/** The made-up project a call runs in: the working directory is its repo, and every other path is inside the call's own folder. */
+export declare function callProject(home: string, agent: ResolvedAgent, dir: string, callDir: string): ResolvedProject;
+/** One call per agent at a time (two would write the same global memory). A lock whose process is gone, or that cannot be read, is taken over. */
+export declare function lockAgent(home: string, agent: string, callId: string): {
+    release(): void;
+};
+/** Wake one global agent once, alone, in `dir`. Leaves task.md, log/ and result.md in `<home>/calls/<call-id>/`. */
+export declare function callAgent(o: CallOptions): Promise<CallResult>;

package/dist/call.js

@@ -0,0 +1,162 @@
+import fs from "node:fs";
+import path from "node:path";
+import { realInvoker } from "./adapters/index.js";
+import { must } from "./assert.js";
+import { ConfigError, loadGlobal, resolveProjectFrom } from "./config.js";
+import { atomicWrite } from "./fs-util.js";
+import { ProtectedGuard } from "./guard.js";
+import { assertName, homePaths, isInside } from "./paths.js";
+import { memoryDirs } from "./policy.js";
+import { lockHolderAlive } from "./project-lock.js";
+import { buildCallUserPrompt, buildSoloSystemPrompt } from "./prompt.js";
+import { newRunId } from "./run-store.js";
+import { DISPATCHER_DEFAULTS } from "./schema.js";
+export const CALL_PROJECT = "(call)";
+export const callsDir = (home) => path.join(home, "calls");
+/** A global agent (from team.yaml) as a `call` uses it: global persona and memory, nobody to mail, nothing to ask, nothing to edit. */
+export function resolveCallAgent(home, name) {
+    assertName("agent", name);
+    const g = loadGlobal(home);
+    if (!g.agents[name]) {
+        throw new ConfigError(`"${name}" is not an agent of the global library (${homePaths(home).globalConfig}). Global agents: ${Object.keys(g.agents).join(", ") || "(none)"}.`);
+    }
+    const p = resolveProjectFrom(home, CALL_PROJECT, g, { dir: home, team: { lead: name }, dispatcher: {}, agents: { [name]: {} } });
+    const a = must(p.agents[name], "the resolved agent");
+    if (!a.runtime)
+        throw new ConfigError(`Agent "${name}" has no runtime: set runtime (or a model) for it in team.yaml.`);
+    if (!fs.existsSync(a.agentMd))
+        throw new ConfigError(`AGENT.md of "${name}" not found: ${a.agentMd}`);
+    return {
+        ...a,
+        memory: { global: a.memory.global ?? path.join(homePaths(home).globalAgentsDir, name, "memory") },
+        resume: false,
+        canMessage: [],
+        canAskUser: false,
+        canEditAgentMd: false,
+        owns: [],
+    };
+}
+/** The made-up project a call runs in: the working directory is its repo, and every other path is inside the call's own folder. */
+export function callProject(home, agent, dir, callDir) {
+    const paths = {
+        root: callDir,
+        config: path.join(callDir, "call.yaml"),
+        agentsDir: path.join(callDir, "agents"),
+        shared: path.join(callDir, "shared"),
+        common: path.join(callDir, "shared", "COMMON.md"),
+        inboxRoot: path.join(callDir, "mail", "inbox"),
+        outboxRoot: path.join(callDir, "mail", "outbox"),
+        runs: path.join(callDir, "runs"),
+        taskMemory: path.join(callDir, "task-memory"),
+    };
+    return {
+        home,
+        name: CALL_PROJECT,
+        dir,
+        lead: agent.name,
+        dispatcher: { ...DISPATCHER_DEFAULTS, max_parallel: 1, workspace_mode: "shared" },
+        agents: { [agent.name]: agent },
+        paths,
+        solo: "call",
+    };
+}
+function readHolder(file) {
+    try {
+        const j = JSON.parse(fs.readFileSync(file, "utf8"));
+        return typeof j?.pid === "number" && typeof j?.call_id === "string" ? j : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** One call per agent at a time (two would write the same global memory). A lock whose process is gone, or that cannot be read, is taken over. */
+export function lockAgent(home, agent, callId) {
+    const dir = callsDir(home);
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, `.lock-${agent}`);
+    const mine = JSON.stringify({ pid: process.pid, call_id: callId });
+    for (let attempt = 0;; attempt++) {
+        try {
+            fs.writeFileSync(file, mine, { flag: "wx" });
+            break;
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+            const cur = readHolder(file);
+            if (cur && lockHolderAlive({ pid: cur.pid }))
+                throw new Error(`${agent} is already being called (call ${cur.call_id}, pid ${cur.pid}). Wait for it to finish.`);
+            if (attempt >= 1)
+                throw new Error(`Could not take ${file}; try again.`);
+            fs.rmSync(file, { force: true });
+        }
+    }
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        process.off("exit", release);
+        if (readHolder(file)?.call_id === callId)
+            fs.rmSync(file, { force: true });
+    };
+    process.on("exit", release);
+    return { release };
+}
+/** Wake one global agent once, alone, in `dir`. Leaves task.md, log/ and result.md in `<home>/calls/<call-id>/`. */
+export async function callAgent(o) {
+    const say = o.say ?? ((s) => console.error(s));
+    const agent = resolveCallAgent(o.home, o.agent);
+    const dir = path.resolve(o.dir);
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory())
+        throw new Error(`Working directory not found: ${dir}`);
+    const real = (p) => {
+        try {
+            return fs.realpathSync(p);
+        }
+        catch {
+            return path.resolve(p);
+        }
+    };
+    const realDir = real(dir);
+    const realHome = real(o.home);
+    // The called agent is the only one listed, so only its files are protected: nothing may run where the rest of the home is writable.
+    if (isInside(realHome, realDir) || isInside(realDir, realHome)) {
+        throw new Error(`Working directory ${dir} overlaps the agent-lyceum home ${o.home}: a call could change other agents' files there. Pass a --dir that is neither inside nor above the agent-lyceum home.`);
+    }
+    if (!o.task.trim())
+        throw new Error("No task given: pass it as text or with --task-file.");
+    const callId = newRunId();
+    const callDir = path.join(callsDir(o.home), callId);
+    const lease = lockAgent(o.home, agent.name, callId);
+    try {
+        fs.mkdirSync(path.join(callDir, "log"), { recursive: true });
+        fs.writeFileSync(path.join(callDir, "task.md"), o.task);
+        for (const d of memoryDirs(agent))
+            fs.mkdirSync(d, { recursive: true });
+        const project = callProject(o.home, agent, dir, callDir);
+        const guard = new ProtectedGuard(project);
+        say(`Calling ${agent.name} in ${dir} (call ${callId})`);
+        const invoke = o.invoker ?? realInvoker;
+        const result = await invoke({
+            project,
+            agent,
+            workDir: callDir,
+            systemPrompt: buildSoloSystemPrompt(project, agent),
+            userPrompt: buildCallUserPrompt(agent, o.task),
+            timeoutSec: project.dispatcher.wake_timeout_sec,
+            signal: o.signal,
+            logDir: path.join(callDir, "log"),
+        }).catch((e) => ({ ok: false, text: "", exitCode: null, timedOut: false, error: e.message }));
+        const reverted = guard.check([agent]).map((v) => v.file);
+        for (const f of reverted)
+            say(`warn   ${agent.name} changed ${f}; it was put back.`);
+        const cancelled = !!result.cancelled;
+        const error = result.ok ? undefined : cancelled ? "cancelled" : (result.error ?? (result.timedOut ? "timed out" : "failed"));
+        atomicWrite(path.join(callDir, "result.md"), result.ok ? `${result.text.trimEnd()}\n` : `# Call ${cancelled ? "cancelled" : "failed"}\n\n${error}\n`);
+        return { callId, callDir, ok: result.ok, cancelled, text: result.ok ? result.text : "", error, reverted };
+    }
+    finally {
+        lease.release();
+    }
+}

package/dist/cli.js

@@ -3,7 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import readline from "node:readline/promises";
 import { Command } from "commander";
-import { ConfigError, findProjectForCwd, flattenResolved, listProjects, resolveProject, resolveProjectWithSources } from "./config.js";
+import { ConfigError, findProjectForCwd, flattenResolved, listProjects, loadGlobal, resolveProject, resolveProjectWithSources } from "./config.js";
 import { openInEditor, prepareAnswers } from "./ask-answer.js";
 import { restoreMemory, tidyMemory, tidyStamp } from "./memory-tidy.js";
 import { RESULT_FILE, runTeam } from "./dispatcher.js";
@@ -16,8 +16,10 @@ import { absPath, assertName, projectPaths, resolveHome } from "./paths.js";
 import { addProject, initHome, removeProject } from "./scaffold.js";
 import { buildStatusReport, buildTaskListReport, formatMonitor, formatRunDetail, formatStatusWithLog, formatTaskList, latestUnfinishedRun, runIsAlive } from "./status.js";
 import { prepareTask, readTaskFile } from "./task.js";
+import { callAgent, callProject, callsDir, resolveCallAgent } from "./call.js";
 import { formatEnforcement, validateProject } from "./validate.js";
 import { must } from "./assert.js";
+import { onlyAgent, soloProject } from "./solo.js";
 const program = new Command();
 program
     .name("agent-lyceum")
@@ -251,9 +253,10 @@ async function driveRun(pr, runDir, first, assumeDefaults) {
 }
 program
     .command("run [task]")
-    .description('Start the dispatcher: give the task to the lead. Use "<task>" or --task-file <path>.')
+    .description('Start the dispatcher: give the task to the lead. Use "<task>" or --task-file <path>. With --agent, give it to that one member alone.')
     .option("-p, --project <name>")
     .option("--task-file <path>", "read the task from a file")
+    .option("--agent <name>", "run only this member of the project, alone: it cannot mail teammates or ask you, and its own `done` ends the run")
     .option("--assume-defaults", "when the run stops to ask, use the suggested answer for every question that has one")
     .action(async (task, opts) => {
     try {
@@ -263,7 +266,16 @@ program
             console.error(`${i.level === "error" ? "ERROR" : "warn "}  ${i.message}`);
         if (!res.ok)
             fail("Configuration is invalid; fix the errors above (see `agent-lyceum validate`).");
-        await preflight(pr);
+        let checked = pr;
+        if (opts.agent) {
+            assertName("agent", opts.agent);
+            if (opts.assumeDefaults)
+                console.error("warn   --assume-defaults is ignored with --agent: a solo agent cannot ask questions.");
+            // Fails with the member list (and a hint for a global-only agent) before anything is written.
+            const sp = soloProject(pr, opts.agent, { globalAgents: Object.keys(loadGlobal(home()).agents) });
+            checked = onlyAgent(sp, opts.agent);
+        }
+        await preflight(checked);
         const runId = newRunId();
         const runDir = path.join(pr.paths.runs, runId);
         const lease = takeLock(pr, runId);
@@ -271,9 +283,9 @@ program
         const cancel = cancelOnSignals();
         try {
             const prepared = prepareTask({ text: task, file: opts.taskFile, cwd: process.cwd(), runDir });
-            console.log(`Project ${pr.name} — repo ${pr.dir}`);
+            console.log(`Project ${pr.name} — repo ${pr.dir}${opts.agent ? ` — solo: ${opts.agent}` : ""}`);
             console.log(`Task: ${prepared.source === "file" ? `file ${prepared.sourcePath}` : "text"} (${prepared.bytes} bytes${prepared.inline ? "" : ", passed by reference"})`);
-            summary = await runTeam({ project: pr, task: prepared, runDir, signal: cancel.signal });
+            summary = await runTeam({ project: pr, task: prepared, runDir, soloAgent: opts.agent, signal: cancel.signal });
         }
         finally {
             cancel.dispose();
@@ -298,7 +310,6 @@ program
             console.error(`${i.level === "error" ? "ERROR" : "warn "}  ${i.message}`);
         if (!res.ok)
             fail("Configuration is invalid; fix the errors above (see `agent-lyceum validate`).");
-        await preflight(pr);
         let found;
         if (runId) {
             assertName("run", runId);
@@ -313,6 +324,8 @@ program
                 fail("No unfinished run to resume. Start one with: agent-lyceum run \"<task>\"");
         }
         const { dir, state } = found;
+        // A solo run needs only its own agent's runtime, as when it started.
+        await preflight(state.solo_agent ? onlyAgent(soloProject(pr, state.solo_agent), state.solo_agent) : pr);
         if (!state.end_reason && runIsAlive(state, pr))
             fail(`Run ${state.run_id} is still running (pid ${state.pid}).`);
         if (state.end_reason === "done") {
@@ -500,6 +513,41 @@ program
         fail(e.message);
     }
 });
+program
+    .command("call <agent> [task]")
+    .description("Call one agent of the global library on its own, outside any project: it works in --dir (default: the current directory) and its final answer is printed. It cannot mail anyone or ask you.")
+    .option("--task-file <path>", "read the task from a file")
+    .option("--dir <path>", "the directory the agent works in (default: the current directory)")
+    .action(async (agentName, task, opts) => {
+    try {
+        if (task !== undefined && opts.taskFile)
+            fail("Give the task either as text or with --task-file, not both.");
+        const text = opts.taskFile ? readTaskFile(absPath(opts.taskFile, process.cwd())) : task;
+        if (!text?.trim())
+            fail("Give the task as text or with --task-file.");
+        const h = home();
+        const dir = absPath(opts.dir ?? ".", process.cwd());
+        const agent = resolveCallAgent(h, agentName);
+        await preflight(callProject(h, agent, dir, path.join(callsDir(h), "preflight")));
+        const cancel = cancelOnSignals();
+        let r;
+        try {
+            r = await callAgent({ home: h, agent: agentName, task: text, dir, signal: cancel.signal });
+        }
+        finally {
+            cancel.dispose();
+        }
+        console.error(`Call ${r.callId}: ${r.callDir}`);
+        if (r.cancelled)
+            fail("Cancelled.", 130);
+        if (!r.ok)
+            fail(`Call failed: ${r.error}\nLog: ${path.join(r.callDir, "log")}`);
+        console.log(r.text.trimEnd());
+    }
+    catch (e) {
+        fail(e instanceof ConfigError ? e.message : e.message);
+    }
+});
 const memoryCmd = program.command("memory").description("Look after the agents' long-term memory");
 function layerOpt(v) {
     if (v === undefined || v === "project")

package/dist/config.d.ts

@@ -41,6 +41,8 @@ export interface ResolvedProject {
     };
     /** Agents working in their own git worktree instead of `dir` (set by the dispatcher for the wake-ups in progress). */
     workspaces?: Record<string, AgentWorkspace>;
+    /** Set for a single agent working alone: "run" = inside a run of this project (`run --agent`), "call" = outside any project (`call`). */
+    solo?: "run" | "call";
 }
 export declare function loadGlobal(home: string): {
     agents: Record<string, {
@@ -90,6 +92,8 @@ export declare function loadProjectRaw(home: string, name: string): {
     }>;
 };
 export declare function resolveProject(home: string, name: string): ResolvedProject;
+/** The merge `resolveProject` does, from configs already read: `call` uses it with a made-up project that lists one global agent. */
+export declare function resolveProjectFrom(home: string, name: string, g: ReturnType<typeof loadGlobal>, p: ReturnType<typeof loadProjectRaw>): ResolvedProject;
 /** Registered projects: name -> repo dir (best effort; skips broken configs). */
 export declare function listProjects(home: string): {
     name: string;

package/dist/config.js

@@ -51,8 +51,10 @@ function resolveLayer(p, base) {
     return out;
 }
 export function resolveProject(home, name) {
-    const g = loadGlobal(home);
-    const p = loadProjectRaw(home, name);
+    return resolveProjectFrom(home, name, loadGlobal(home), loadProjectRaw(home, name));
+}
+/** The merge `resolveProject` does, from configs already read: `call` uses it with a made-up project that lists one global agent. */
+export function resolveProjectFrom(home, name, g, p) {
     const paths = projectPaths(home, name);
     const hp = homePaths(home);
     const lead = p.team.lead;

package/dist/policy.js

@@ -49,9 +49,10 @@ export function repoDirFor(project, agent) {
     return project.workspaces?.[agent]?.dir ?? project.dir;
 }
 export function writePolicy(project, agent) {
-    const isLead = agent.name === project.lead;
+    const isLead = agent.name === project.lead && !project.solo;
     const ws = project.workspaces?.[agent.name];
-    const allowDirs = [...memoryDirs(agent), outboxDir(project, agent.name), ...(ws ? [ws.gitDir] : [])];
+    // 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 allowFiles = [];
     if (isLead)
         allowFiles.push(commonFile(project));

package/dist/prompt.d.ts

@@ -5,6 +5,10 @@ export declare const COMMON_LIMIT: number;
 export declare const MEMORY_INDEX_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. */
+export declare function buildSoloSystemPrompt(project: ResolvedProject, agent: ResolvedAgent): string;
+/** The prompt of a `call`: the memory indexes the agent is used to, then the task. */
+export declare function buildCallUserPrompt(agent: ResolvedAgent, task: string): string;
 /** Everything that goes to the runtime's system prompt: the persona plus the team protocol. */
 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. */

package/dist/prompt.js

@@ -22,8 +22,46 @@ function readCapped(file, limit) {
 export function readPersona(agent) {
     return fs.readFileSync(agent.agentMd, "utf8").trim();
 }
+/** 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";
+    const lines = [readPersona(agent), "", "---", "", "# Solo protocol (injected by agent-lyceum)", ""];
+    lines.push(`You are **${agent.name}**, working alone: there is no team, no lead and nobody to mail, and you cannot ask the user questions. You work in \`${repoDirFor(project, agent.name)}\`.`, isCall
+        ? "Do the task you are given. Your final reply text is printed to the user as your answer, so end with the answer or a short report of what you did; nothing else is delivered."
+        : "");
+    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.");
+    }
+    lines.push("", "## Memory");
+    const mems = memoryDirs(agent);
+    if (mems.length === 0)
+        lines.push("You have no long-term memory directory.");
+    for (const m of mems)
+        lines.push(`- ${memoryLabel(agent, m)}: \`${m}\``);
+    if (mems.length) {
+        lines.push("Keep a `MEMORY.md` index in each memory directory (one line per entry, pointing at a file). Its contents are shown in your prompt on every wake-up; you can write only inside these directories.", "Use memory only for durable lessons that stay true across tasks; never record task-specific details there.");
+    }
+    lines.push("", "## Rules", "- Never edit any `AGENT.md`, `COMMON.md`, or the repository's own `CLAUDE.md`/`AGENTS.md`.", "- Never touch another agent's memory, inbox or outbox, or the configuration files of agent-lyceum.");
+    return lines.join("\n");
+}
+/** The prompt of a `call`: the memory indexes the agent is used to, then the task. */
+export function buildCallUserPrompt(agent, task) {
+    const parts = [];
+    for (const dir of memoryDirs(agent)) {
+        const idx = readCapped(path.join(dir, "MEMORY.md"), MEMORY_INDEX_LIMIT);
+        parts.push(`# Your ${memoryLabel(agent, dir).split(" ")[0]} memory index (${dir}/MEMORY.md)`);
+        if (!idx)
+            parts.push("(no MEMORY.md yet — create one when you have something worth keeping)", "");
+        else
+            parts.push(idx.text.trim(), ...(idx.truncated ? [`[index truncated at ${MEMORY_INDEX_LIMIT} bytes — trim it]`] : []), "");
+    }
+    parts.push("# Task", task.trim());
+    return parts.join("\n");
+}
 /** Everything that goes to the runtime's system prompt: the persona plus the team protocol. */
 export function buildSystemPrompt(project, agent) {
+    if (project.solo)
+        return buildSoloSystemPrompt(project, agent);
     const outbox = outboxDir(project, agent.name);
     const mates = Object.keys(project.agents).filter((n) => n !== agent.name);
     const recipients = agent.canMessage === "all" ? mates : agent.canMessage.filter((n) => project.agents[n] && n !== agent.name);

package/dist/run-session.d.ts

@@ -28,6 +28,8 @@ export interface RunSummary {
 }
 export interface RunOptions {
     project: ResolvedProject;
+    /** Run only this member of the project, alone (`run --agent`). A resumed run uses the one recorded in its state. */
+    soloAgent?: string;
     /** The task for a new run; omit when resuming. */
     task?: PreparedTask;
     /** Continue this earlier run (same run dir, sessions and counters) instead of starting a new one. */

package/dist/run-session.js

@@ -14,6 +14,7 @@ import { buildSystemPrompt, buildUserPrompt, pickMessages } from "./prompt.js";
 import { atomicWrite } from "./fs-util.js";
 import { assertWorktreeRunnable, collectAgentChanges, existingAgentWorkspace, integrateAgentChanges, prepareAgentWorkspace, resolveWorkspaceMode, snapshotBase } from "./worktree.js";
 import { bindRunProject, newRunId, newRunState, saveRunState } from "./run-store.js";
+import { soloProject } from "./solo.js";
 import { taskMessageBody } from "./task.js";
 import { must } from "./assert.js";
 export { newRunId };
@@ -62,11 +63,13 @@ export class RunSession {
             throw new Error("runTeam needs a task or a run to resume");
         const invoke = opts.invoker ?? realInvoker;
         const say = opts.log ?? ((s) => console.log(s));
-        const cfg = opts.project.dispatcher;
+        const soloName = resume ? resume.solo_agent : opts.soloAgent;
+        const base = soloName ? soloProject(opts.project, soloName) : opts.project;
+        const cfg = base.dispatcher;
         const runId = path.basename(runDir);
         const layout = resume ? resume.mail_layout : "run";
         // Each run gets its own memory directory per agent and (new runs) its own mailboxes.
-        const project = bindRunProject(opts.project, runDir, layout);
+        const project = bindRunProject(base, runDir, layout);
         // Parallel agents work in their own git worktrees; refuse early (before anything is written) when that cannot be done.
         const wsMode = resolveWorkspaceMode(cfg);
         if (wsMode === "worktree")
@@ -104,6 +107,7 @@ export class RunSession {
                 task_summary: t.subject,
                 mail_layout: layout,
                 workspace_mode: wsMode,
+                solo_agent: soloName,
             });
             const seed = parseSteps(task.content, false);
             if (seed.length)

package/dist/run-store.d.ts

@@ -62,6 +62,8 @@ export interface RunState {
     notes?: string[];
     /** "worktree": non-lead agents work in their own git worktrees. */
     workspace_mode?: "shared" | "worktree";
+    /** Set when the run was started with `run --agent <name>`: that member works alone (a resumed run keeps it). */
+    solo_agent?: string;
     /** Agents whose finished work could not be brought into the repo yet; their work is kept on their branch. */
     blocked_integrations?: {
         agent: string;

package/dist/run-store.js

@@ -37,6 +37,7 @@ const WireState = z
     task_summary: z.string().optional(),
     active: z.record(z.string(), z.any()).optional(),
     wakes: z.array(z.any()).optional(),
+    solo_agent: z.string().optional(),
     steps: z.array(z.object({ text: z.string(), done: z.boolean() })).optional(),
 })
     .passthrough();

package/dist/solo.d.ts

@@ -0,0 +1,12 @@
+import { type ResolvedProject } from "./config.js";
+/**
+ * The project as `run --agent <name>` sees it: `name` is the lead of a team of one, so the task goes to it and its `done` ends the run.
+ * It cannot mail anyone, ask the user, edit any AGENT.md or share the repo with a parallel agent. The other members stay listed, only
+ * so that their files stay protected; nobody mails them, so they are never woken.
+ * `globalAgents` (names in team.yaml) only improves the error message.
+ */
+export declare function soloProject(project: ResolvedProject, name: string, hints?: {
+    globalAgents?: string[];
+}): ResolvedProject;
+/** `project` with only `name` listed: what a preflight of a solo run needs to look at. */
+export declare function onlyAgent(project: ResolvedProject, name: string): ResolvedProject;

package/dist/solo.js

@@ -0,0 +1,28 @@
+import { ConfigError } from "./config.js";
+/**
+ * The project as `run --agent <name>` sees it: `name` is the lead of a team of one, so the task goes to it and its `done` ends the run.
+ * It cannot mail anyone, ask the user, edit any AGENT.md or share the repo with a parallel agent. The other members stay listed, only
+ * so that their files stay protected; nobody mails them, so they are never woken.
+ * `globalAgents` (names in team.yaml) only improves the error message.
+ */
+export function soloProject(project, name, hints = {}) {
+    const a = project.agents[name];
+    if (!a) {
+        const call = hints.globalAgents?.includes(name) ? ` "${name}" is in the global library: use \`agent-lyceum call ${name}\` to run it outside the project.` : "";
+        throw new ConfigError(`Agent "${name}" is not a member of project "${project.name}" (members: ${Object.keys(project.agents).join(", ")}).${call}`);
+    }
+    return {
+        ...project,
+        solo: "run",
+        lead: name,
+        dispatcher: { ...project.dispatcher, max_parallel: 1, workspace_mode: "shared" },
+        agents: { ...project.agents, [name]: { ...a, canMessage: [], canAskUser: false, canEditAgentMd: false, owns: [] } },
+    };
+}
+/** `project` with only `name` listed: what a preflight of a solo run needs to look at. */
+export function onlyAgent(project, name) {
+    const a = project.agents[name];
+    if (!a)
+        throw new ConfigError(`Agent "${name}" is not a member of project "${project.name}" (members: ${Object.keys(project.agents).join(", ")}).`);
+    return { ...project, agents: { [name]: a } };
+}

package/package.json

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