agent-lyceum 0.26.0 → 0.28.0

package/dist/run-session.js

@@ -1,9 +1,11 @@
 import fs from "node:fs";
 import path from "node:path";
+import { invokeWithSandboxChecks } from "./sandbox-invocation.js";
 import { realInvoker } from "./adapters/index.js";
-import { agentForCandidate, candidatesFor, Cooldowns, defaultSleep, planAttempts, runWithFallback } from "./fallback.js";
+import { agentForCandidate, candidatesFor, Cooldowns, defaultSleep, deferredAttempts, planAttempts, runWithFallback } from "./fallback.js";
 import { briefOf, digestOf, doneContract, mergeSteps, parseSteps } from "./format.js";
 import { ProtectedGuard } from "./guard.js";
+import { listRunLocks, lockHolderAlive } from "./project-lock.js";
 import { addBatch, askersWithAnswers, askReplyPath, checkAnswers, describeCheck, isComplete, markDelivered, parseAskBody, readAskReply, renderAnswers, resolveOptionLetters, writeAskReply } from "./ask-reply.js";
 import { deliver, deliverOnce, ensureAgentDirs, ensureProjectDirs, finishDone, listUnread, PENDING_DIR, readMessageNoFollow, rejectDone, routeOutboxes, unreadFiles } from "./mailbox.js";
 import { instanceContainment } from "./instance-containment.js";
@@ -20,6 +22,7 @@ import { bindRunProject, newRunId, newRunState, roundLimit, roundsLabel, saveRun
 import { soloProject } from "./solo.js";
 import { taskMessageBody } from "./task.js";
 import { must } from "./assert.js";
+import { modelForTier, wakeTier } from "./tiers.js";
 import { openPullRequest, prBody, prTitle, realRunner } from "./open-pr.js";
 export { newRunId };
 export const RESULT_FILE = "result.md";
@@ -37,6 +40,8 @@ function readIndex(file) {
 }
 /** The `state.sessions` key of the session an agent runs in on candidate `c`: a backup has a session of its own. */
 const sessionKeyOf = (agent, c) => (c.primary ? agent.name : `${agent.name}@${c.key}`);
+/** Why `key` is cooling down, for a message. */
+const cooldownKind = (cd, key) => cd.toJSON()[key]?.kind ?? "unknown";
 /** `runtime/model`, or the runtime alone for its default model. */
 const modelLabel = (c) => (c.model ? `${c.runtime}/${c.model}` : c.runtime);
 /** Each model given up on once, in order, with its last failure (retries on the same model are one entry). */
@@ -241,7 +246,8 @@ export class RunSession {
         }
         const saveState = () => saveRunState(runDir, state);
         // Concurrent runs: the repo's instruction files the run can touch are the lead worktree's copies; your own tree is never watched (or restored).
-        const guard = new ProtectedGuard(leadSpace ? { ...project, workspaces: { ...project.workspaces, [project.lead]: leadSpace } } : project);
+        const otherLiveRuns = () => listRunLocks(project.paths.root).filter((l) => l.run_id !== runId && lockHolderAlive(l)).map((l) => l.run_id);
+        const guard = new ProtectedGuard(leadSpace ? { ...project, workspaces: { ...project.workspaces, [project.lead]: leadSpace } } : project, otherLiveRuns);
         if (resume) {
             log("resume", { rounds: state.rounds, interrupted: Object.keys(resume.active ?? {}) });
             if (opts.followup) {
@@ -320,6 +326,21 @@ export class RunSession {
         log("note", { text });
         say(`  ${text}`);
     }
+    /** Spec 24.5.2: log every tier that was dropped; tell the sender once per reason (`no-tiers` is log-only). */
+    noteTierIgnored(route) {
+        for (const t of route.tierIgnored) {
+            this.log("tier_ignored", { from: t.from, id: t.id, to: t.to, reason: t.reason });
+            if (t.reason === "no-tiers")
+                continue;
+            const key = `tier\u0000${t.from}\u0000${t.reason}`;
+            if (this.ignoredNoted.has(key))
+                continue;
+            this.ignoredNoted.add(key);
+            this.note(t.reason === "not-lead"
+                ? `${t.from}'s mail ${t.id} has \`tier\`, but only the lead (${this.project.lead}) can choose a member's tier: it was delivered without one.`
+                : `${t.from}'s mail ${t.id} ("${t.subject}") has \`tier\` but is a ${t.type}: tiers apply to tasks only, so it was delivered without one.`);
+        }
+    }
     /** Bind the project to this run again, after its slot table changed. */
     rebind() {
         this.project = withCapability(bindRunProject(this.base, this.runDir, this.layout, this.state.instances), this.wsMode, this.instanceCheck, this.state.instances);
@@ -555,15 +576,28 @@ export class RunSession {
             timeoutSec: cfg.wake_timeout_sec,
         };
         // Without a fallback chain (one candidate) the loop, its output and its records are exactly those of plain retries (spec 20.2 decision 11).
-        const all = candidatesFor(agent);
+        // A lead's `tier` (spec 24.5.3): only for an agent with a ladder, and only a valid value counts.
+        const tier = agent.tiers && agent.tiers.length >= 2 ? wakeTier(unread.map((m) => m.meta.tier)) : undefined;
+        const all = candidatesFor(agent, tier && agent.tiers ? modelForTier(agent.tiers, tier) : undefined);
         const chain = all.length > 1;
-        const candidates = chain ? planAttempts(agent, cooldowns, Date.now()) : all;
+        const candidates = chain ? planAttempts(all, cooldowns, Date.now()) : all;
+        // Models cooling down at the start are not dropped for good: when the warm ones fail they are tried last, once recovered.
+        const deferred = chain && candidates.length < all.length ? deferredAttempts(all, cooldowns, Date.now()).filter((c) => !candidates.includes(c)) : [];
+        const ceiling = must(all.find((c) => c.primary), "the agent's own model");
+        const tieredFirst = all[0]?.tiered ? all[0] : undefined;
         // The model a backup's calls stand in for: the one switched away from in this wake, or the cooling-down primary it started past.
-        let replaced = candidates[0]?.primary ? undefined : all[0];
+        // A tier's cheaper model is not a fallback (spec 24.7.3): only chain entries have one.
+        let replaced = candidates[0]?.primary || candidates[0]?.tiered ? undefined : ceiling;
+        if (tieredFirst && !candidates[0]?.tiered) {
+            const left = Math.ceil(cooldowns.active(tieredFirst.key, Date.now()) / 1000);
+            say(`  ${agent.name} tier ${tier} model ${modelLabel(tieredFirst)} is cooling down (${cooldownKind(cooldowns, tieredFirst.key)}, ${left}s left): starting on ${modelLabel(candidates[0])}`);
+            log("tier_step_up", { agent: agent.name, tier, from: modelLabel(tieredFirst), to: modelLabel(candidates[0]), reason: "cooldown" });
+        }
         let calls = 0;
         let stoppedByCancel = false;
         const outcome = await runWithFallback({
             candidates,
+            deferred,
             legacy: !chain,
             retry: cfg.retry,
             cooldowns,
@@ -579,9 +613,26 @@ export class RunSession {
                 // The round limit (when one is set) ends the run; this message stays unread for the resume.
                 return state.max_rounds > 0 && state.rounds >= state.max_rounds ? "stop" : undefined;
             },
+            onCooldownWait: (c, ms) => {
+                if (opts.signal?.aborted)
+                    return;
+                say(`  ${agent.name}: no other model is available; waiting ${Math.ceil(ms / 1000)}s for ${modelLabel(c)} to recover`);
+                log("cooldown_wait", { agent: agent.name, model: modelLabel(c), wait_ms: ms });
+            },
             onSwitch: (from, to, kind) => {
-                replaced = from;
+                if (!from.tiered)
+                    replaced = from;
                 this.syncCooldowns();
+                if (from.tiered) {
+                    log("tier_step_up", { agent: agent.name, tier, from: modelLabel(from), to: modelLabel(to), reason: kind ?? "unknown" });
+                    if (opts.signal?.aborted)
+                        return;
+                    say(`  ${agent.name} stepping up from tier ${tier} (${modelLabel(from)}) to ${modelLabel(to)} (${kind ?? "unknown error"})`);
+                    const resumesTo = agent.resume && !!state.sessions[sessionKeyOf(agent, to)];
+                    this.note(`${agent.name}'s tier ${tier} model ${modelLabel(from)} failed (${kind ?? "unknown error"}); it is woken again on ${modelLabel(to)}, which ${resumesTo ? "resumes its own earlier session" : "starts a fresh session"}, and redoes this wake-up. ` +
+                        `Anything the failed attempts already did outside the mailbox (file edits, commands) was not undone: side effects may have happened.`);
+                    return;
+                }
                 if (opts.signal?.aborted)
                     return;
                 say(`  ${agent.name} falling back to ${modelLabel(to)} (${kind ?? "unknown error"})`);
@@ -603,21 +654,21 @@ export class RunSession {
                 const redo = this.redoContext(agent.name, unread.map((m) => m.meta.id), att.id, attempt);
                 const userPrompt = redoUserPrompt(base.userPrompt, { attempt, error: ctx.previous?.error, prior: redo.prior, drafts: redo.drafts, taskMemory: agent.memory.task });
                 const retryN = chain ? ctx.candidateAttempt : attempt;
-                say(`[round ${roundsLabel(state.rounds, state.max_rounds)}] waking ${agent.name} (${chain ? modelLabel(c) : agent.runtime})${retryN ? ` — retry ${retryN}` : ""}`);
+                say(`[round ${roundsLabel(state.rounds, state.max_rounds)}] waking ${agent.name} (${chain ? modelLabel(c) : agent.runtime}${c.tiered ? `, tier ${tier}` : ""})${retryN ? ` — retry ${retryN}` : ""}`);
                 const sessionId = agent.resume ? state.sessions[sessionKey] : undefined;
                 const handling = unread.map((m) => ({ from: m.meta.from, type: m.meta.type, subject: m.meta.subject, brief: briefOf(m.body), digest: digestOf(m.meta.type, m.body) }));
                 // What the panel shows for the message being worked on is uncut; the wake record below keeps the short digest.
                 const activeHandling = unread.map((m, i) => ({ ...handling[i], digest: digestOf(m.meta.type, m.body, true) }));
                 state.active[agent.name] = { round, since: new Date(started).toISOString(), handling: activeHandling };
                 this.saveState();
-                const result = await invoke({
+                const result = await invokeWithSandboxChecks(invoke, {
                     ...base,
                     agent: runAs,
                     signal: opts.signal,
                     logDir: attemptLogDir(runDir, att.id),
                     userPrompt,
                     sessionId,
-                }).catch((e) => ({
+                }, agent, { event: (name, fields) => log(name, fields) }, attempt).catch((e) => ({
                     ok: false,
                     text: "",
                     exitCode: null,
@@ -632,7 +683,7 @@ export class RunSession {
                 state.cache_write_tokens += result.cacheWriteTokens ?? 0;
                 delete state.active[agent.name];
                 // With a chain only: which model ran, what it replaced, why it failed.
-                const which = chain ? { runtime: c.runtime, model: c.model, fallback_from: c.primary || !replaced ? undefined : modelLabel(replaced), kind: result.kind } : {};
+                const which = chain ? { runtime: c.runtime, model: c.model, fallback_from: c.primary || c.tiered ? undefined : modelLabel(replaced ?? ceiling), kind: result.kind } : {};
                 state.wakes.push({
                     round,
                     agent: agent.name,
@@ -645,8 +696,9 @@ export class RunSession {
                     handling,
                     error: result.error,
                     ...which,
+                    ...(tier ? { tier } : {}),
                 });
-                state.last_wake[agent.name] = { at: new Date().toISOString(), ok: result.ok, error: result.error, ...(chain ? { runtime: c.runtime, model: c.model } : {}) };
+                state.last_wake[agent.name] = { at: new Date().toISOString(), ok: result.ok, error: result.error, ...(chain ? { runtime: c.runtime, model: c.model } : {}), ...(tier ? { tier } : {}) };
                 log("wake", {
                     agent: agent.name,
                     runtime: c.runtime,
@@ -659,6 +711,7 @@ export class RunSession {
                     error: result.error,
                     ...(redo.prior.length ? { redo_of: redo.prior.map((a) => a.id) } : {}),
                     ...(chain ? { model: c.model, fallback_from: which.fallback_from, kind: result.kind } : {}),
+                    ...(tier ? { tier } : {}),
                 });
                 this.saveState();
                 if (result.ok) {
@@ -681,6 +734,10 @@ export class RunSession {
                 fault("park:before-finish");
                 finishAttempt(runDir, att.id, "failed", { error: result.error, parked });
                 say(`  ${agent.name} failed: ${result.error ?? "unknown error"}`);
+                if (result.kind === "config" && result.error?.startsWith("sandbox refused")) {
+                    this.note(`${agent.name} attempt ${att.n} was refused before it started (${result.error}); nothing was run, so there are no side effects to undo.`);
+                    return result;
+                }
                 this.note(`${agent.name} attempt ${att.n} failed (${result.error ?? "unknown error"})${parked.length ? `; ${parked.length} output file(s) set aside in ${path.join("mail", "attempts", att.id, "outbox")}` : ""}. ` +
                     `Anything it already did outside its mailbox (file edits, commands) was not undone: side effects may have happened.`);
                 return result;
@@ -820,6 +877,11 @@ export class RunSession {
                     (v.saved ? `\n\nWhat was written is kept at \`${v.saved}\` (sha256 ${v.sha256}${v.truncated ? ", truncated to 1 MiB" : ""}). If it is worth keeping, have an agent that may edit this file redo it.` : ""),
             });
         }
+        // Another run's lead edited a cross-run shared file: kept, not a violation of this batch, nobody is woken for it.
+        for (const u of guard.takeUnattributed()) {
+            say(`  shared file changed by another live run (${u.otherRuns.join(", ")}); kept: ${u.file}`);
+            log("protected-change-unattributed", { ...u });
+        }
         // Crash seam: every wake of the batch is finished and marked output_ready; nothing of it is integrated or routed yet.
         fault("wake:ready");
         batch.forEach((a, i) => {
@@ -851,6 +913,7 @@ export class RunSession {
                 contract = undefined;
             }
         }
+        this.noteTierIgnored(route);
         const askAccepted = this.handleAsks(route);
         for (const d of route.delivered)
             log("route", d);

package/dist/run-store.d.ts

@@ -1,6 +1,6 @@
 import type { ResolvedProject } from "./config.js";
 import type { DigestSection, Step } from "./format.js";
-import { type ErrorKind, type Runtime, type RunOutcome } from "./schema.js";
+import { type ErrorKind, type Runtime, type RunOutcome, type Tier } from "./schema.js";
 import type { ResultBranch } from "./worktree.js";
 export declare const STATE_FILE = "state.json";
 /** The newest state format this version reads. */
@@ -51,6 +51,8 @@ export interface WakeRecord {
     fallback_from?: string;
     /** With a fallback chain only: why the call failed. */
     kind?: ErrorKind;
+    /** The tier this wake ran at (spec 24): set only when every mail it handled carried a valid one. */
+    tier?: Tier;
 }
 /** A model given up on during a wake with a fallback chain, for `failure.tried`. */
 export interface TriedModel {
@@ -123,6 +125,7 @@ export interface RunState {
         error?: string;
         runtime?: Runtime;
         model?: string;
+        tier?: Tier;
     }>;
     /** Process running this dispatcher, so a monitor can tell "running" from "interrupted". */
     pid: number;

package/dist/sandbox-invocation.d.ts

@@ -0,0 +1,35 @@
+import type { WakeInput, WakeResult, Invoker } from "./adapters/types.js";
+import type { ResolvedAgent, ResolvedProject } from "./config.js";
+import { type SandboxPathConflict } from "./policy.js";
+/** Where the `sandbox` and `sandbox-refused` events go: the run's log, or stderr for `call` (spec 25.8). */
+export interface SandboxSink {
+    event(name: string, fields: Record<string, unknown>): void;
+}
+export interface ProtectedPath {
+    path: string;
+    reason: string;
+}
+/**
+ * Everything a sandbox allowance must not reach (spec 25.4.3), canonical. `deep` adds the per-invocation items: the concrete
+ * write policy's deny list, bound workspaces and the git common dir. The agent's own checkout is left out: it is already writable.
+ */
+export declare function protectedPathsFor(project: ResolvedProject, agent: ResolvedAgent, deep: boolean): ProtectedPath[];
+export declare function describeConflict(agent: string, c: SandboxPathConflict, when: "load" | "invocation"): string;
+/** Conflicts of one agent's `write`/`unix_sockets` with the protected set. */
+export declare function sandboxConflictsOf(project: ResolvedProject, agent: ResolvedAgent, deep: boolean): SandboxPathConflict[];
+/** Capability excess of each backup of `agent` over its primary (spec 25.9): `[candidate label, excess...]`. */
+export declare function fallbackCapExcess(agent: ResolvedAgent): {
+    label: string;
+    excess: string[];
+}[];
+/** The refusal, if any, for this invocation. */
+export declare function sandboxRefusal(input: WakeInput, base: ResolvedAgent): {
+    reason: string;
+    path?: string;
+} | undefined;
+/**
+ * The one entry every adapter invocation goes through (spec 25.4.3, 25.19.1): refuses (returning a `config` failure, never
+ * throwing, never spawning) when an allowance reaches a protected path or a backup would widen them; otherwise records
+ * the `sandbox` event and calls `invoke`. An agent without `sandbox`, and a policy-override wake, go straight through.
+ */
+export declare function invokeWithSandboxChecks(invoke: Invoker, input: WakeInput, base: ResolvedAgent, sink: SandboxSink, attempt: number): Promise<WakeResult>;

package/dist/sandbox-invocation.js

@@ -0,0 +1,186 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { canonicalPath } from "./paths.js";
+/**
+ * `canonicalPath` for the sandbox check: a path that is missing (ENOENT/ENOTDIR) falls back to its nearest existing ancestor as
+ * usual, but any other realpath error (EACCES, ELOOP, ...) throws so the invocation is refused (fail closed).
+ */
+function strictCanonical(p) {
+    for (let head = path.resolve(p);; head = path.dirname(head)) {
+        try {
+            fs.realpathSync.native(head);
+            break;
+        }
+        catch (e) {
+            const code = e.code;
+            if (code !== "ENOENT" && code !== "ENOTDIR")
+                throw new Error(`cannot resolve ${head} (${code ?? e.message})`);
+            if (path.dirname(head) === head)
+                break;
+        }
+    }
+    return canonicalPath(p);
+}
+import { inboxDir, memoryDirs, osSandboxAvailable, outboxDir, recordsDir, repoDirFor, repoInstructionFiles, sandboxCapExcess, sandboxCaps, sandboxPathConflicts, sharedContextFiles, writePolicy, } from "./policy.js";
+/** Whether `cwd` or a parent holds a `.git` entry (a directory, or the file of a linked worktree). */
+function insideGitCheckout(cwd) {
+    for (let d = path.resolve(cwd);; d = path.dirname(d)) {
+        if (fs.existsSync(path.join(d, ".git")))
+            return true;
+        if (path.dirname(d) === d)
+            return false;
+    }
+}
+/**
+ * `git rev-parse --git-common-dir` of `cwd`, absolute; undefined when `cwd` is not in a git checkout. Fails closed: when it is a
+ * checkout but the probe fails, throws, so the invocation is refused instead of running with the shared git dir unprotected.
+ */
+function gitCommonDir(cwd) {
+    try {
+        const out = execFileSync("git", ["rev-parse", "--git-common-dir"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 5000 }).trim();
+        if (out)
+            return path.resolve(cwd, out);
+    }
+    catch (e) {
+        if (!insideGitCheckout(cwd))
+            return undefined;
+        throw new Error(`cannot find the git common dir of ${cwd} (git rev-parse --git-common-dir failed: ${e.message.split("\n")[0]})`);
+    }
+    if (insideGitCheckout(cwd))
+        throw new Error(`cannot find the git common dir of ${cwd} (git rev-parse --git-common-dir printed nothing)`);
+    return undefined;
+}
+/**
+ * Everything a sandbox allowance must not reach (spec 25.4.3), canonical. `deep` adds the per-invocation items: the concrete
+ * write policy's deny list, bound workspaces and the git common dir. The agent's own checkout is left out: it is already writable.
+ */
+export function protectedPathsFor(project, agent, deep) {
+    const out = [];
+    const add = (p, reason) => {
+        if (p)
+            out.push({ path: canonicalPath(p), reason });
+    };
+    add(project.home, "agent-lyceum home");
+    add(project.dir, "project directory");
+    add(path.join(os.homedir(), ".claude"), "Claude Code settings");
+    add(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), "Codex settings");
+    for (const a of Object.values(project.agents)) {
+        add(a.agentMd, `AGENT.md of ${a.name}`);
+        for (const m of memoryDirs(a))
+            add(m, `memory of ${a.name}`);
+        add(outboxDir(project, a.name), `outbox of ${a.name}`);
+        add(inboxDir(project, a.name), `inbox of ${a.name}`);
+    }
+    for (const f of sharedContextFiles(project))
+        add(f, "shared context");
+    for (const f of repoInstructionFiles(project))
+        add(f, "repo instruction file");
+    add(recordsDir(project), "project records");
+    if (!deep)
+        return out;
+    for (const d of writePolicy(project, agent).deny)
+        add(d, "write-protected path");
+    if (project.run)
+        add(project.run.dir, "run directory");
+    add(path.join(project.paths.root, "worktrees"), "worktrees root");
+    const own = project.workspaces?.[agent.name];
+    for (const [name, ws] of Object.entries(project.workspaces ?? {})) {
+        if (name === agent.name)
+            continue;
+        add(ws.root, `workspace of ${name}`);
+        add(ws.gitDir, `git dir of ${name}`);
+        add(ws.commonDir, "git common dir");
+    }
+    // The agent's own checkout and git dir are already inside its write scope, so they are not listed; the shared common dir is.
+    add(own?.commonDir ?? gitCommonDir(repoDirFor(project, agent.name)), "git common dir");
+    return out;
+}
+export function describeConflict(agent, c, when) {
+    const suffix = when === "invocation" ? " (checked before invocation)" : "";
+    const rel = c.relation === "equal" ? "is" : c.relation === "inside" ? "is inside" : "contains";
+    return `agent ${agent}: sandbox.${c.key}[${c.index}] ${c.path} ${rel} protected path ${c.protectedPath} (${c.reason}); pick a different directory.${suffix}`;
+}
+/** Conflicts of one agent's `write`/`unix_sockets` with the protected set. */
+export function sandboxConflictsOf(project, agent, deep) {
+    const s = agent.sandbox;
+    if (!s)
+        return [];
+    const entries = [
+        ...s.write.map((p, index) => ({ key: "write", index, path: canonicalPath(p) })),
+        ...s.unixSockets.map((p, index) => ({ key: "unix_sockets", index, path: canonicalPath(p) })),
+    ];
+    return sandboxPathConflicts(entries, protectedPathsFor(project, agent, deep));
+}
+/** Capability excess of each backup of `agent` over its primary (spec 25.9): `[candidate label, excess...]`. */
+export function fallbackCapExcess(agent) {
+    if (!agent.sandbox || !agent.runtime)
+        return [];
+    const primary = sandboxCaps(agent, agent.runtime);
+    const out = [];
+    for (const f of agent.fallback) {
+        const excess = sandboxCapExcess(primary, sandboxCaps(agent, f.runtime));
+        if (excess.length)
+            out.push({ label: `${f.runtime}/${f.model || "(default model)"}`, excess });
+    }
+    return out;
+}
+/** The refusal, if any, for this invocation. */
+export function sandboxRefusal(input, base) {
+    const agent = input.agent;
+    if (!agent.sandbox)
+        return undefined;
+    for (const p of [...agent.sandbox.write, ...agent.sandbox.unixSockets])
+        strictCanonical(p);
+    const c = sandboxConflictsOf(input.project, agent, true)[0];
+    if (c)
+        return { reason: describeConflict(agent.name, c, "invocation"), path: c.path };
+    const f = fallbackCapExcess(base)[0];
+    if (f)
+        return { reason: `agent ${base.name}: fallback ${f.label} would apply more sandbox allowance than the primary (${f.excess.join("; ")}) (checked before invocation)` };
+    return undefined;
+}
+function applied(agent) {
+    const caps = sandboxCaps(agent);
+    const osOn = osSandboxAvailable();
+    if (!osOn)
+        return { write: agent.runtime === "claude-code" ? "tool-rules" : "none", network: "unrestricted", local_binding: "unrestricted", unix_sockets: "unrestricted" };
+    return { write: "os", network: caps.network, local_binding: caps.localBinding ? "on" : "off", unix_sockets: caps.unixSockets ? "on" : "off" };
+}
+/**
+ * The one entry every adapter invocation goes through (spec 25.4.3, 25.19.1): refuses (returning a `config` failure, never
+ * throwing, never spawning) when an allowance reaches a protected path or a backup would widen them; otherwise records
+ * the `sandbox` event and calls `invoke`. An agent without `sandbox`, and a policy-override wake, go straight through.
+ */
+export async function invokeWithSandboxChecks(invoke, input, base, sink, attempt) {
+    const agent = input.agent;
+    if (!agent.sandbox || input.policy)
+        return invoke(input);
+    const refuse = (reason) => ({ ok: false, text: "", exitCode: null, timedOut: false, error: `sandbox refused: ${reason}`, kind: "config" });
+    try {
+        const bad = sandboxRefusal(input, base);
+        if (bad) {
+            sink.event("sandbox-refused", { agent: agent.name, runtime: agent.runtime, reason: bad.reason, ...(bad.path ? { path: bad.path } : {}) });
+            return refuse(bad.reason);
+        }
+        const s = agent.sandbox;
+        sink.event("sandbox", {
+            agent: agent.name,
+            runtime: agent.runtime,
+            model: agent.model,
+            attempt,
+            write: s.write.map(canonicalPath),
+            network: s.network,
+            local_binding: s.localBinding,
+            unix_sockets: s.unixSockets.map(canonicalPath),
+            applied: applied(agent),
+        });
+    }
+    catch (e) {
+        const reason = `${agent.name}: sandbox check failed: ${e.message}`;
+        sink.event("sandbox-refused", { agent: agent.name, runtime: agent.runtime, reason });
+        return refuse(reason);
+    }
+    return invoke(input);
+}

package/dist/scaffold.d.ts

@@ -1,5 +1,6 @@
 /** The lead's guidance on `parallel: true` (spec 23.12 point 5). Only `init` writes it, into a new lead AGENT.md. */
 export declare const LEAD_PARALLEL_HINT = "Mark a task `parallel: true` only when it is independent and touches different files from the other open tasks; list each task's files in `## Scope` first; shared components, types, routes and tokens go first, alone.";
+export declare const GLOBAL_TEAM_YAML = "# Global agent library. Projects pick agents from here by name and may override any field.\n# Relative paths here are resolved against this folder. \"~\" is allowed.\nagents:\n  lead:\n    runtime: claude-code        # claude-code | codex\n    agent_md: agents/lead/AGENT.md\n    memory: { global: agents/lead/memory }\n    # model: opus          # most capable model: keep it for the lead\n  fe-member:\n    runtime: claude-code\n    agent_md: agents/fe-member/AGENT.md\n    memory: { global: agents/fe-member/memory }\n    # model: sonnet        # cheaper model for routine work\n  qa-member:\n    runtime: claude-code\n    agent_md: agents/qa-member/AGENT.md\n    memory: { global: agents/qa-member/memory }\n    # model: sonnet        # cheaper model for routine work\n  # Model hints (comments only):\n  # - a read-only search/explorer role suits \"model: haiku\", the cheapest tier (the alias resolves per provider; on the Anthropic API it is claude-haiku-5-5).\n  # - a reviewer can run on the other runtime (\"runtime: codex\"); leave the codex model unset to use the CLI default.\n";
 export interface InitResult {
     home: string;
     created: string[];

package/dist/scaffold.js

@@ -33,21 +33,27 @@ You verify work: run and write tests, reproduce bugs, and review changes against
 - Besides the standard reply headings, add a \`## Verdict\` section containing \`pass\` or \`fail\`, and put your prioritised list of issues under Open items.
 `,
 };
-const GLOBAL_TEAM_YAML = `# Global agent library. Projects pick agents from here by name and may override any field.
+export const GLOBAL_TEAM_YAML = `# Global agent library. Projects pick agents from here by name and may override any field.
 # Relative paths here are resolved against this folder. "~" is allowed.
 agents:
   lead:
     runtime: claude-code        # claude-code | codex
     agent_md: agents/lead/AGENT.md
     memory: { global: agents/lead/memory }
+    # model: opus          # most capable model: keep it for the lead
   fe-member:
     runtime: claude-code
     agent_md: agents/fe-member/AGENT.md
     memory: { global: agents/fe-member/memory }
+    # model: sonnet        # cheaper model for routine work
   qa-member:
     runtime: claude-code
     agent_md: agents/qa-member/AGENT.md
     memory: { global: agents/qa-member/memory }
+    # model: sonnet        # cheaper model for routine work
+  # Model hints (comments only):
+  # - a read-only search/explorer role suits "model: haiku", the cheapest tier (the alias resolves per provider; on the Anthropic API it is claude-haiku-5-5).
+  # - a reviewer can run on the other runtime ("runtime: codex"); leave the codex model unset to use the CLI default.
 `;
 export function initHome(home) {
     const hp = homePaths(home);

package/dist/schema.d.ts

@@ -12,7 +12,7 @@ export declare function inferRuntime(model: string | undefined): Runtime | undef
 export declare const WEB_LEVELS: readonly ["none", "search", "fetch"];
 export type WebLevel = (typeof WEB_LEVELS)[number];
 /** Why a wake failed, as far as the CLI's output reveals; decides whether to retry, fall back, or stop. */
-export declare const ERROR_KINDS: readonly ["rate_limit", "quota", "timeout", "network", "crash", "auth", "unknown"];
+export declare const ERROR_KINDS: readonly ["rate_limit", "quota", "timeout", "network", "crash", "auth", "config", "unknown"];
 export type ErrorKind = (typeof ERROR_KINDS)[number];
 /** One link of a fallback chain after resolution: runtime and model are filled in (model "" = the runtime's own default). */
 export interface FallbackEntry {
@@ -37,6 +37,14 @@ export declare const FallbackEntryPartial: z.ZodObject<{
     }>>;
 }, z.core.$strict>;
 export type FallbackEntryPartialT = z.infer<typeof FallbackEntryPartial>;
+/** Per-agent sandbox allowances (spec 25); every key is optional and absent = none. */
+export declare const SandboxPartial: z.ZodObject<{
+    write: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    network: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    local_binding: z.ZodOptional<z.ZodBoolean>;
+    unix_sockets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type SandboxPartialT = z.infer<typeof SandboxPartial>;
 export declare const AgentPartial: z.ZodObject<{
     runtime: z.ZodOptional<z.ZodEnum<{
         "claude-code": "claude-code";
@@ -80,6 +88,12 @@ export declare const AgentPartial: z.ZodObject<{
             xhigh: "xhigh";
         }>>;
     }, z.core.$strict>>>;
+    sandbox: z.ZodOptional<z.ZodObject<{
+        write: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        network: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        local_binding: z.ZodOptional<z.ZodBoolean>;
+        unix_sockets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
     owns: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$strict>;
 export type AgentPartialT = z.infer<typeof AgentPartial>;
@@ -113,7 +127,18 @@ export declare const DispatcherPartial: z.ZodObject<{
 /** Settings that no longer exist; files that still carry them load, and `validate` warns. */
 export declare const REMOVED_DISPATCHER_KEYS: readonly ["max_parallel", "max_concurrent_runs", "workspace_mode"];
 export declare const REMOVED_AGENT_KEYS: readonly ["owns"];
+/** One runtime's model ladder, lowest first; `[]` = no ladder for that runtime (overrides team.yaml). */
+export declare const ModelTiersPartial: z.ZodObject<{
+    "claude-code": z.ZodOptional<z.ZodArray<z.ZodString>>;
+    codex: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const TIERS: readonly ["low", "mid", "high"];
+export type Tier = (typeof TIERS)[number];
 export declare const GlobalConfig: z.ZodObject<{
+    model_tiers: z.ZodOptional<z.ZodObject<{
+        "claude-code": z.ZodOptional<z.ZodArray<z.ZodString>>;
+        codex: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
     agents: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         runtime: z.ZodOptional<z.ZodEnum<{
             "claude-code": "claude-code";
@@ -157,6 +182,12 @@ export declare const GlobalConfig: z.ZodObject<{
                 xhigh: "xhigh";
             }>>;
         }, z.core.$strict>>>;
+        sandbox: z.ZodOptional<z.ZodObject<{
+            write: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            network: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            local_binding: z.ZodOptional<z.ZodBoolean>;
+            unix_sockets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
         owns: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
@@ -165,6 +196,10 @@ export declare const ProjectConfig: z.ZodObject<{
     team: z.ZodObject<{
         lead: z.ZodString;
     }, z.core.$strict>;
+    model_tiers: z.ZodOptional<z.ZodObject<{
+        "claude-code": z.ZodOptional<z.ZodArray<z.ZodString>>;
+        codex: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
     dispatcher: z.ZodDefault<z.ZodObject<{
         max_rounds: z.ZodOptional<z.ZodNumber>;
         max_parallel: z.ZodOptional<z.ZodUnknown>;
@@ -235,6 +270,12 @@ export declare const ProjectConfig: z.ZodObject<{
                 xhigh: "xhigh";
             }>>;
         }, z.core.$strict>>>;
+        sandbox: z.ZodOptional<z.ZodObject<{
+            write: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            network: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            local_binding: z.ZodOptional<z.ZodBoolean>;
+            unix_sockets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
         owns: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;

package/dist/schema.js

@@ -21,7 +21,7 @@ export function inferRuntime(model) {
 /** How much of the web an agent may use: nothing, search only, or search plus fetching pages. Unset leaves each runtime's own default alone. */
 export const WEB_LEVELS = ["none", "search", "fetch"];
 /** Why a wake failed, as far as the CLI's output reveals; decides whether to retry, fall back, or stop. */
-export const ERROR_KINDS = ["rate_limit", "quota", "timeout", "network", "crash", "auth", "unknown"];
+export const ERROR_KINDS = ["rate_limit", "quota", "timeout", "network", "crash", "auth", "config", "unknown"];
 const Memory = z
     .object({
     global: z.string().optional(),
@@ -36,6 +36,18 @@ export const FallbackEntryPartial = z
     effort: z.enum(EFFORTS).optional(),
 })
     .strict();
+const DOMAIN_RE = /^(\*\.)?([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+/** Per-agent sandbox allowances (spec 25); every key is optional and absent = none. */
+export const SandboxPartial = z
+    .object({
+    write: z.array(z.string().trim().min(1)).optional(),
+    network: z
+        .array(z.string().trim().toLowerCase().regex(DOMAIN_RE, "expected a host name like registry.npmjs.org or *.example.com (no scheme, port, path or IP)"))
+        .optional(),
+    local_binding: z.boolean().optional(),
+    unix_sockets: z.array(z.string().trim().min(1)).optional(),
+})
+    .strict();
 export const AgentPartial = z
     .object({
     runtime: z.enum(RUNTIMES).optional(),
@@ -49,6 +61,7 @@ export const AgentPartial = z
     can_ask_user: z.boolean().optional(),
     allow_web: z.enum(WEB_LEVELS).optional(),
     fallback: z.array(FallbackEntryPartial).optional(),
+    sandbox: SandboxPartial.optional(),
     /** Removed setting: still accepted (any value) so old files load; ignored, with a warning from `validate`. */
     owns: z.unknown().optional(),
 })
@@ -72,8 +85,17 @@ export const DispatcherPartial = z
 /** Settings that no longer exist; files that still carry them load, and `validate` warns. */
 export const REMOVED_DISPATCHER_KEYS = ["max_parallel", "max_concurrent_runs", "workspace_mode"];
 export const REMOVED_AGENT_KEYS = ["owns"];
+/** One runtime's model ladder, lowest first; `[]` = no ladder for that runtime (overrides team.yaml). */
+export const ModelTiersPartial = z
+    .object({
+    "claude-code": z.array(z.string().trim().min(1)).optional(),
+    codex: z.array(z.string().trim().min(1)).optional(),
+})
+    .strict();
+export const TIERS = ["low", "mid", "high"];
 export const GlobalConfig = z
     .object({
+    model_tiers: ModelTiersPartial.optional(),
     agents: z.record(z.string(), AgentPartial).default({}),
 })
     .strict();
@@ -81,6 +103,7 @@ export const ProjectConfig = z
     .object({
     dir: z.string(),
     team: z.object({ lead: z.string() }).strict(),
+    model_tiers: ModelTiersPartial.optional(),
     dispatcher: DispatcherPartial.default({}),
     agents: z.record(z.string(), AgentPartial).default({}),
 })