eve-hub 0.14.12 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # eve-hub
 
+## 0.15.0
+
+### Minor Changes
+
+- Worker tiers: each base-team lead declares `reader`, `editor` and `verifier` subagents (read-only bots get no `editor`), scaffolded under `agents/<bot>/agent/subagents/<tier>/` in the parent's sandbox with a short prompt and no team prompt. Each tier's model is `agents[].subagents.<tier>` in hub.workspace.json, read with `bindRoster(workspace).subagentModel(bot, tier)`; the template starts `reader` and `editor` on DeepSeek V4 Pro and `verifier` on Sonnet 5.5.
+- An existing workspace gets a tier by declaring it in hub.workspace.json (`agents[].subagents.<tier>`): the kit sync (`hub start`, the hosted build, the hosted kit bump) writes the folder of each declared tier a bot lacks and leaves one already there. The version bump alone adds no tier, and local bots lose `kit__worker`, so declare the tiers in the same commit as the bump.
+- The default subagent cap is Opus 5.5 · low, allowing Opus 5.5, Sonnet 5.5, DeepSeek V4 Pro and MiMo V2.6 Pro. Fable is no longer allowed by default.
+- `kit__worker` and the `eve-hub/worker-model` export are removed. DeepSeek's gateway host order (full-precision hosts, then baseten's FP4) moves into `modelOptionsFor` (`eve-hub/bot-model`).
+- A hosted build mounts the git extension in bots only, never in a declared subagent's folder.
+
 ## 0.14.12
 
 ### Patch Changes

package/bot-model.d.mts

@@ -13,5 +13,7 @@ export function ownModel(agents: readonly RosterAgent[], name: string): Selectio
 export function copyModel(agents: readonly RosterAgent[], cap: SubagentCap, name: string): Clamped;
 export function subagentModels(agents: readonly RosterAgent[], cap: SubagentCap, name: string): SubagentModels;
 export function isAgentCopy(ctx: unknown): boolean;
+export const GATEWAY_PROVIDERS: Readonly<Record<string, readonly string[]>>;
 export function modelOptionsFor(model: string): { providerOptions: Record<string, unknown> } | undefined;
+export function subagentModel(agents: readonly RosterAgent[], cap: SubagentCap, bot: string, name: string): { model: string; reasoning: string; modelContextWindowTokens: number; modelOptions?: { providerOptions: Record<string, unknown> } };
 export function selectModel(agents: readonly RosterAgent[], cap: SubagentCap, name: string, ctx: unknown): Selection & { modelContextWindowTokens: number; modelOptions?: unknown; copy: boolean };

package/bot-model.mjs

@@ -6,7 +6,7 @@
 // Built-in `agent` copies of a bot (eve's root-copy tool) run under the same
 // subagent cap as declared subagents: the bot's own model and reasoning,
 // clamped (never rejected) to the cap.
-import { capFor, clampSubagent, resolveSubagents } from "./subagent-cap.mjs";
+import { capFor, clampSubagent, resolveSubagent, resolveSubagents } from "./subagent-cap.mjs";
 
 export const CONTEXT_WINDOW = 200_000;
 
@@ -48,12 +48,31 @@ export function subagentModels(agents, cap, name) {
 // populated in dynamic-model resolvers, so the channel is the signal.)
 export const isAgentCopy = (ctx) => ctx?.channel?.kind === "subagent";
 
-// Reasoning text is opt-in on current models; ask for summaries so the UI can
+// AI Gateway hosts an open-weights model tries first: full-precision ones,
+// then baseten's FP4 before the gateway's own pick. From
+// https://ai-gateway.vercel.sh/v1/models/<id>/endpoints.
+export const GATEWAY_PROVIDERS = Object.freeze({
+  "deepseek/deepseek-v4-pro": Object.freeze(["deepseek", "azure", "alibaba", "baseten"]),
+});
+
+// Provider options that fit `model`, and only those. Reasoning text is opt-in
+// on current Anthropic and OpenAI models; ask for summaries so the UI can
 // interleave them with tool calls.
 export function modelOptionsFor(model) {
   if (model.startsWith("anthropic/")) return { providerOptions: { anthropic: { thinking: { type: "adaptive", display: "summarized" } } } };
   if (model.startsWith("openai/")) return { providerOptions: { openai: { reasoningSummary: "auto" } } };
-  return undefined;
+  const order = GATEWAY_PROVIDERS[model];
+  return order ? { providerOptions: { gateway: { order: [...order] } } } : undefined;
+}
+
+// What `bot`'s declared subagent `name` passes to defineAgent: its
+// hub.workspace.json model, clamped to the bot's cap, with options that fit
+// it. A subagent the roster doesn't declare is a config error, not the cap.
+export function subagentModel(agents, cap, botName, name) {
+  if (!bot(agents, botName).subagents?.[name]) throw new Error(`"${botName}" declares no subagent "${name}" in hub.workspace.json`);
+  const { model, reasoning } = resolveSubagent(agents, cap, botName, name);
+  const options = modelOptionsFor(model);
+  return { model, reasoning, modelContextWindowTokens: CONTEXT_WINDOW, ...(options ? { modelOptions: options } : {}) };
 }
 
 // The selection eve's dynamic model resolver returns for one of `name`'s

package/fanout/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: fanout
+description: How to hand work to your reader, editor and verifier subagents. Load before you send any task to one, so each gets an unambiguous, non-overlapping, checkable task and you can check what comes back.
+---
+
+# Fanning out work
+
+Your `reader`, `editor` and `verifier` run cheaper models than you and never see your conversation. Each one gets only the task you write, so the task has to stand on its own.
+
+## 1. The contract
+
+Every task you send has all of these fields. If you can't fill one in, don't send the task: do it yourself or split it further.
+
+- `goal`: one sentence describing the result.
+- `owns`: the files the worker may change. It is empty for a reader and a verifier.
+- `facts`: what is already decided, so the worker doesn't reopen it.
+- `pointers`: where to look, as `file:line` or a URL. Never paste file contents.
+- `check`: the command that proves the task is done.
+- `budget`: a turn count. Allow 2 to 3 for setup, 1 to 2 for reading, 2 to 4 for implementing and 2 to 3 for verifying, 12 at most.
+- `stop`: when to give up and report instead of pushing on.
+
+```
+goal: Make listThreads skip archived threads unless asked.
+owns: /workspace/wt-a/src/threads.ts, /workspace/wt-a/test/threads.test.ts
+facts: The flag is `archived: "include"`; the default excludes them.
+pointers: src/threads.ts:88 (the query), test/threads.test.ts:40
+check: cd /workspace/wt-a && node --test test/threads.test.ts
+budget: 5 turns
+stop: if the query is built anywhere else, report where and stop.
+```
+
+## 2. Disjoint ownership
+
+- No two tasks running at the same time share a file in `owns`.
+- Your workers share your sandbox. Give each editor running in parallel its own worktree (`git worktree add /workspace/wt-a`) and name that directory in its task.
+- You apply their diffs to your branch one at a time.
+- A change that cuts across files several workers own runs serially, or goes to an `agent` copy (rung 2 below).
+
+## 3. What comes back
+
+Each tier replies with exactly this report, inside its turn budget:
+
+<!-- tier-reports -->
+
+Review the diff together with the module around it, not just the changed lines. Rerun every `check` yourself before you take the change.
+
+After a reader or verifier returns, run `git status --porcelain` in its worktree. If anything changed, discard its result and count the attempt as a failure on the ladder below: `bash` can still write files, so read-only is a prompt rule, not a guarantee.
+
+## 4. When it fails
+
+1. Retry once on the same tier with a fresh worker. Give it the original task, the failed diff and the output of the check.
+2. Then give the same task to an `agent` copy of yourself.
+3. Then take the task back and split it differently.
+
+Never try a rung a second time. If two workers given the same task return substantively different diffs, the task is under-specified: rewrite it before you send it again.
+
+## 5. The cap
+
+Run at most 3 workers in parallel.

package/kit-modules.json

@@ -12,6 +12,7 @@
   "schedules/dash",
   "schedules/prune",
   "schedules/wake",
+  "skills/fanout",
   "skills/forms",
   "skills/local-onboarding",
   "skills/onboarding-profile",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve-hub",
-  "version": "0.14.12",
+  "version": "0.15.0",
   "license": "Apache-2.0",
   "description": "Bot-side code shared by every hub agent: registry tools, the roster hook, the eve channel, the host sandbox and browser, and model helpers.",
   "type": "module",
@@ -22,6 +22,7 @@
     "./workspace-roster": "./workspace-roster.mjs",
     "./bot-model": "./bot-model.mjs",
     "./subagent-cap": "./subagent-cap.mjs",
+    "./subagent-tiers": "./subagent-tiers.mjs",
     "./session-limits": "./session-limits.mjs",
     "./main-instructions": "./main-instructions.mjs",
     "./execution-context": "./execution-context.mjs",

package/prepare.mjs

@@ -125,7 +125,8 @@ export function prepareDeployment(dir) {
   const dirOf = (name) => join(dir, "agents", name, "agent");
   const local = new Set(resolved.agents.filter((a) => a.runsOn === "local").map((a) => a.name));
   const folders = readdirSync(join(dir, "agents")).filter((name) => !local.has(name) && existsSync(join(dirOf(name), "agent.ts")));
-  const change = syncKit({ bots: folders.map((name) => ({ name, runsOn: "hosted", files: readBotFiles(dirOf(name)) })), modules: KIT_MODULES });
+  const tiersOf = (name) => Object.keys(definition.agents.find((a) => a.name === name)?.subagents ?? {});
+  const change = syncKit({ bots: folders.map((name) => ({ name, runsOn: "hosted", files: readBotFiles(dirOf(name)), subagents: tiersOf(name) })), modules: KIT_MODULES });
   if (change.report.length) throw new Error(`these files can't ship to a hosted deployment; update or delete them:\n${change.report.map((r) => `  agents/${r.bot}/agent/${r.file} ${r.reason}`).join("\n")}`);
   writeFileSync(join(dir, MANIFEST_FILE), `${JSON.stringify(resolved, null, 2)}\n`);
   for (const { name } of definition.agents) {
@@ -137,10 +138,10 @@ export function prepareDeployment(dir) {
   writeFileSync(join(dir, "agents", "main", "agent", "channels", "manifest.ts"), MANIFEST_CHANNEL);
   applyKit(change, dirOf);
   const deployment = deploymentFacts();
-  for (const file of readdirSync(join(dir, "agents"), { recursive: true })) {
-    if (!file.endsWith("/agent.ts")) continue;
-    const bot = dirname(join(dir, "agents", file));
-    const name = basename(dirname(bot));
+  // Bots only: a declared subagent's agent.ts (agent/subagents/<tier>/) is not a bot and mounts none of these.
+  for (const name of readdirSync(join(dir, "agents"))) {
+    const bot = dirOf(name);
+    if (!existsSync(join(bot, "agent.ts"))) continue;
     const code = CODE_BOTS.includes(name);
     for (const [stub, content] of Object.entries({ ...(deployment.githubToken ? gitExtensionFiles() : {}), ...(code ? codeExtensionFiles(name) : {}) })) {
       mkdirSync(dirname(join(bot, stub)), { recursive: true });
@@ -152,7 +153,7 @@ export function prepareDeployment(dir) {
   for (const name of readdirSync(join(dir, "agents"))) {
     const bot = join(dir, "agents", name, "agent");
     writeExecutionContext(bot, { bot: name, deployment });
-    // The kit's extension (kit__worker) runs host-only workers and is excluded from the kit tarball.
+    // The kit's extension mounts only on the hub's machine and is excluded from the kit tarball.
     // Other extensions, such as eve-code, stay.
     for (const item of readdirSync(bot, { recursive: true })) {
       if (item.endsWith(join("extensions", "kit.ts"))) removeStub(bot, item);

package/roster-model.mjs

@@ -10,11 +10,13 @@
 //   function has no workspace on disk).
 // - `rosterModel(name, …)` / `rosterLimits(name)`: the same, read from disk
 //   (see workspaceRoster below), for bots scaffolded before bindRoster.
+// - `subagentModel(bot, name, { mock })`: the model fields of `bot`'s
+//   declared subagent `name` (bot-model.mjs), or its mock in mock mode.
 // - `createRosterModel({ agents, subagentCap })`: bound to a roster given
 //   explicitly (e.g. a test).
 import { defineDynamic } from "eve";
 import evePackage from "eve/package.json" with { type: "json" };
-import { CONTEXT_WINDOW, selectModel } from "./bot-model.mjs";
+import { CONTEXT_WINDOW, selectModel, subagentModel } from "./bot-model.mjs";
 import { DEFAULT_SUBAGENT_CAP } from "./subagent-cap.mjs";
 import { sessionLimits } from "./session-limits.mjs";
 import { installModelCallTimeout } from "./model-timeout.mjs";
@@ -58,7 +60,15 @@ const rosterOf = ({ agents, humans, subagentCap, limits }) => ({ agents, humans,
 // `subagentCap`) for `data`, validated the same way as the file.
 export function bindRoster(data) {
   const roster = rosterOf(parseWorkspace(data));
-  return { ...roster, rosterModel: createRosterModel(roster), rosterLimits: (name) => sessionLimits(roster, name, evePackage.version) };
+  return {
+    ...roster,
+    rosterModel: createRosterModel(roster),
+    rosterLimits: (name) => sessionLimits(roster, name, evePackage.version),
+    subagentModel: (bot, name, { mock } = {}) => {
+      const selection = subagentModel(roster.agents, roster.subagentCap, bot, name);
+      return real ? selection : { model: mock, modelContextWindowTokens: CONTEXT_WINDOW };
+    },
+  };
 }
 
 // Bots scaffolded before bindRoster read the roster from disk instead: the

package/skills/fanout.d.ts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/skills/fanout.gen.mjs

@@ -0,0 +1,2 @@
+// Generated by scripts/build-onboarding.mjs from fanout/SKILL.md. Do not edit.
+export default {"description":"How to hand work to your reader, editor and verifier subagents. Load before you send any task to one, so each gets an unambiguous, non-overlapping, checkable task and you can check what comes back.","markdown":"# Fanning out work\n\nYour `reader`, `editor` and `verifier` run cheaper models than you and never see your conversation. Each one gets only the task you write, so the task has to stand on its own.\n\n## 1. The contract\n\nEvery task you send has all of these fields. If you can't fill one in, don't send the task: do it yourself or split it further.\n\n- `goal`: one sentence describing the result.\n- `owns`: the files the worker may change. It is empty for a reader and a verifier.\n- `facts`: what is already decided, so the worker doesn't reopen it.\n- `pointers`: where to look, as `file:line` or a URL. Never paste file contents.\n- `check`: the command that proves the task is done.\n- `budget`: a turn count. Allow 2 to 3 for setup, 1 to 2 for reading, 2 to 4 for implementing and 2 to 3 for verifying, 12 at most.\n- `stop`: when to give up and report instead of pushing on.\n\n```\ngoal: Make listThreads skip archived threads unless asked.\nowns: /workspace/wt-a/src/threads.ts, /workspace/wt-a/test/threads.test.ts\nfacts: The flag is `archived: \"include\"`; the default excludes them.\npointers: src/threads.ts:88 (the query), test/threads.test.ts:40\ncheck: cd /workspace/wt-a && node --test test/threads.test.ts\nbudget: 5 turns\nstop: if the query is built anywhere else, report where and stop.\n```\n\n## 2. Disjoint ownership\n\n- No two tasks running at the same time share a file in `owns`.\n- Your workers share your sandbox. Give each editor running in parallel its own worktree (`git worktree add /workspace/wt-a`) and name that directory in its task.\n- You apply their diffs to your branch one at a time.\n- A change that cuts across files several workers own runs serially, or goes to an `agent` copy (rung 2 below).\n\n## 3. What comes back\n\nEach tier replies with exactly this report, inside its turn budget:\n\n- `reader`, 8 turns:\n\n  ```\n  answer: <1-2 sentences>\n  evidence: <file:line | command + output | URL>, one per line\n  open: <what it couldn't settle, or \"none\">\n  ```\n\n- `editor`, 12 turns:\n\n  ```\n  diff: <git diff of owns>\n  check: <command> -> exit <n>, last 20 lines\n  outside: <files that also need a change but aren't in owns, or \"none\">\n  notes: <=5 lines\n  ```\n\n- `verifier`, 10 turns:\n\n  ```\n  verdict: holds | fails | couldn't check\n  runs: <command> -> exit <n>, the deciding output lines\n  seen: <what is on screen, for a UI>\n  other: <anything wrong outside the claim>\n  ```\n\nReview the diff together with the module around it, not just the changed lines. Rerun every `check` yourself before you take the change.\n\nAfter a reader or verifier returns, run `git status --porcelain` in its worktree. If anything changed, discard its result and count the attempt as a failure on the ladder below: `bash` can still write files, so read-only is a prompt rule, not a guarantee.\n\n## 4. When it fails\n\n1. Retry once on the same tier with a fresh worker. Give it the original task, the failed diff and the output of the check.\n2. Then give the same task to an `agent` copy of yourself.\n3. Then take the task back and split it differently.\n\nNever try a rung a second time. If two workers given the same task return substantively different diffs, the task is under-specified: rewrite it before you send it again.\n\n## 5. The cap\n\nRun at most 3 workers in parallel.\n"};

package/skills/fanout.js

@@ -0,0 +1,5 @@
+import { defineSkill } from "eve/skills";
+import skill from "./fanout.gen.mjs";
+// The fanout skill: fanout/SKILL.md, embedded at build time (scripts/build-onboarding.mjs) like
+// the forms skill. A lead loads it before handing work to its reader, editor or verifier tiers.
+export default defineSkill(skill);

package/stubs.d.mts

@@ -8,3 +8,4 @@ export function kitStub(file: string, options?: { files?: Record<string, string[
 export const ROLE_FILE: string;
 export const ROLE_DIR: string;
 export function botInstructionsStub(name: string): string;
+export function tierFiles(bot: string, tier: string): Record<string, string>;

package/stubs.mjs

@@ -1,4 +1,5 @@
 import { ROLE_DIR, ROLE_FILE } from "./role-files.mjs";
+import { tierOf } from "./subagent-tiers.mjs";
 
 // eve finds tools, hooks, and channels by file (the tool name is the file
 // name), so each bot keeps a one-line stub per kit module. Bot file -> what it
@@ -18,6 +19,7 @@ export const KIT_FILES = {
   "tools/list_agents.ts": ["The team right now: kind, place, tools, models, who's busy."],
   "tools/post_message.ts": ["Post into an existing thread or a bot's DM; with `status`, report the thread's phase."],
   "skills/forms.ts": ["The forms skill (packages/agent-kit/forms/SKILL.md): how to draw a flow, sequence, chart or ask the app renders."],
+  "skills/fanout.ts": ["The fanout skill (packages/agent-kit/fanout/SKILL.md): the contract for handing work to the reader, editor and verifier subagents."],
   "skills/local-onboarding.ts": ["The local-onboarding skill (packages/agent-kit/local-onboarding/SKILL.md): the Mac half of onboarding, the live work to port and the sandbox setup."],
 };
 
@@ -61,6 +63,7 @@ export const DEPLOYED_KIT_FILES = new Set([
   ...["react", "show", "fetch_upload", "update_thread", "list_threads", "read_thread", "post_message"].map((t) => `tools/${t}.ts`),
   "memory/team.ts",
   "skills/forms.ts",
+  "skills/fanout.ts",
   ...["create_thread", "set_summary", "move_path", "archive_thread", "unarchive_thread", "list_agents", "create_agent", "remove_agent", "restart_agent", "tag_threads", "dash_update", "apply_tags"].map((t) => `tools/${t}.ts`),
 ]);
 
@@ -167,3 +170,29 @@ export function instructionsSource(files, main) {
   if (copy) return "conflict";
   return isKitReexport(files[PROTOCOL_STUB_FILE], "instructions/protocol") ? "kit" : "custom";
 }
+
+// The files of `bot`'s `tier` folder, relative to the bot's agent/ folder. The text is imported, never copied.
+export function tierFiles(bot, tier) {
+  const spec = tierOf(tier);
+  const dir = `subagents/${tier}`;
+  const name = JSON.stringify(tier);
+  return {
+    [`${dir}/agent.ts`]: `import { defineAgent } from "eve";
+import { mockModel } from "eve/evals";
+import { bindRoster } from "eve-hub/roster-model";
+import { tierDescription } from "eve-hub/subagent-tiers";
+import workspace from "../../../../../hub.workspace.json" with { type: "json" };
+
+// Model and reasoning come from hub.workspace.json agents[${JSON.stringify(bot)}].subagents.${tier}, clamped to the bot's subagent cap.
+const { subagentModel } = bindRoster(workspace);
+
+export default defineAgent({
+  description: tierDescription(${name}),
+  ...subagentModel(${JSON.stringify(bot)}, ${name}, { mock: mockModel(${JSON.stringify(`${tier} here (mock).`)}) }),
+});
+`,
+    [`${dir}/sandbox.ts`]: `import { defineParentSandbox } from "eve/sandbox";\n\nexport default defineParentSandbox();\n`,
+    [`${dir}/instructions.ts`]: `import { defineInstructions } from "eve/instructions";\nimport { tierInstructions } from "eve-hub/subagent-tiers";\n\n// The ${tier}'s prompt, from eve-hub (packages/agent-kit/subagent-tiers.mjs).\nexport default defineInstructions({ content: tierInstructions(${name}) });\n`,
+    ...(spec.readOnly ? { [`${dir}/tools/write_file.ts`]: `import { disableTool } from "eve/tools";\n\n// A ${tier} never edits files.\nexport default disableTool();\n` } : {}),
+  };
+}

package/subagent-cap.mjs

@@ -10,9 +10,9 @@ export const REASONING_LEVELS = ["none", "minimal", "low", "medium", "high", "xh
 // `models` lists what a subagent may pick at or under the cap; any other
 // model is clamped to `model`.
 export const DEFAULT_SUBAGENT_CAP = Object.freeze({
-  model: "anthropic/claude-fable-5.1",
+  model: "anthropic/claude-opus-5.5",
   reasoning: "low",
-  models: Object.freeze(["anthropic/claude-fable-5.1"]),
+  models: Object.freeze(["anthropic/claude-opus-5.5", "anthropic/claude-sonnet-5.5", "deepseek/deepseek-v4-pro", "xiaomi/mimo-v2.6-pro"]),
 });
 
 // Returns what the subagent actually runs on, plus a note for each field

package/subagent-tiers.d.mts

@@ -0,0 +1,5 @@
+export type SubagentTier = { readOnly: boolean; use: string; refuse: string; example: string; budget: number; stop: string; report: string; prompt: string };
+export const SUBAGENT_TIERS: Readonly<Record<string, Readonly<SubagentTier>>>;
+export function tierOf(tier: string): Readonly<SubagentTier>;
+export function tierDescription(tier: string): string;
+export function tierInstructions(tier: string): string;

package/subagent-tiers.mjs

@@ -0,0 +1,66 @@
+// The worker tiers a lead bot fans work out to, as declared subagents (eve: agent/subagents/<tier>/).
+// A bot gets a tier by declaring it in hub.workspace.json agents[].subagents.<tier>; syncKit
+// (sync-kit.mjs) writes the folder of each declared tier the bot lacks, so a workspace made
+// before a tier existed gets it the same way a new one does. Each shares its parent's sandbox,
+// so it works on the parent's files; its model is the roster's, clamped to the bot's cap.
+// `readOnly` tiers can't write files. A worker has no team prompt: it never posts or hands off.
+//
+// This module is the one source of each tier's text. The folder's agent.ts and instructions.ts
+// import it from eve-hub instead of holding a copy, so a kit bump changes what every existing
+// workspace's lead and workers read. The lead chooses a tier from its tool description alone
+// (tierDescription); the fanout skill's report table is generated from `report`. The folder's
+// files themselves are stubs.mjs tierFiles: this module holds only text, so a deployed bot imports nothing else.
+// When the lead hands work to tiers: to run its pieces at once, never to offload one task. The execution template says the same sentence (test/fanout-skill.test.mjs).
+export const ROUTING_RULE = "Fan out work that splits into independent pieces: one tier call per piece, all in one step. A single task stays with you, however long. Judgment always stays with you.";
+
+// Null prototype: a lookup by a roster name sees only the tiers, never `constructor` or `__proto__`.
+export const SUBAGENT_TIERS = Object.freeze(Object.assign(Object.create(null), {
+  reader: Object.freeze({
+    readOnly: true,
+    use: "you can state the question without your conversation, and the answer is a fact.",
+    refuse: "judgment calls, or Kit or GitHub data not yet in the sandbox (workers have no connections).",
+    example: "\"What installs tier folders into an existing workspace on a kit bump?\" (a file:line).",
+    budget: 8,
+    stop: "the question is ambiguous, the evidence runs out, or answering would mean changing a file.",
+    report: "answer: <1-2 sentences>\nevidence: <file:line | command + output | URL>, one per line\nopen: <what it couldn't settle, or \"none\">",
+    prompt: "You are a reader: a worker that a lead bot delegates reading to. You share its sandbox, so you see the same files it does. You get one question with everything you need; you never see the caller's conversation.\n\n- Answer exactly the question. Read code, history (git log, blame) and docs; search the web only when the question needs it.\n- Never change a file, commit, push or install anything. Shell commands are for reading.\n- Back every claim with evidence: a file:line, a command and its output, or a link. Keep facts apart from guesses, and say which is which.",
+  }),
+  editor: Object.freeze({
+    readOnly: false,
+    use: "two editors given your spec would make the same diff, and a command decides whether it's done.",
+    refuse: "design across files (SQL, migration and tests together: you or an `agent` copy), or Swift layout (judgment, and no Swift compiler here).",
+    example: "replace a named sentence in a prompt and assert it in a named test file.",
+    budget: 12,
+    stop: "a file outside `owns` must change (name it under `outside:` instead of editing it), the check fails twice, or the spec is ambiguous.",
+    report: "diff: <git diff of owns>\ncheck: <command> -> exit <n>, last 20 lines\noutside: <files that also need a change but aren't in owns, or \"none\">\nnotes: <=5 lines",
+    prompt: "You are an editor: a worker that a lead bot delegates file edits to. You share its sandbox, so you edit the same files it reviews. You get one task with everything you need; you never see the caller's conversation.\n\n- Do exactly the task. Touch only the files in `owns`; if another file must change, stop and report which one and why. No drive-by refactors, renames, reformatting, or new dependencies.\n- Work in the worktree the task names, with absolute paths. Read a file before you change it. Match the surrounding style.\n- Run the task's `check`. Don't commit, push, or install anything unless the task says to.",
+  }),
+  verifier: Object.freeze({
+    readOnly: true,
+    use: "you can name the command or screen that decides the claim.",
+    refuse: "native or Swift checks in a hosted sandbox (CI or a Mac bot), or whether a design is right (a reviewer's call).",
+    example: "\"The sync and tier tests pass at the PR head\" (it runs them).",
+    budget: 10,
+    stop: "the check can't run as given: say why instead of running a weaker check.",
+    report: "verdict: holds | fails | couldn't check\nruns: <command> -> exit <n>, the deciding output lines\nseen: <what is on screen, for a UI>\nother: <anything wrong outside the claim>",
+    prompt: "You are a verifier: a worker that a lead bot delegates checks to. You share its sandbox, so you check the same files and builds it has. You get one claim to check and how to check it; you never see the caller's conversation.\n\n- Check the claim on the real path: run the tests, the build, or the app itself, with real inputs. Reading the diff is not a check. To see a screenshot, open the image with read_file.\n- Never change a file, commit, push or install anything beyond what the check itself needs (a dependency install, a dev server). Stop any server you start.\n- A suite can take minutes. When bash says a command is still running, check on it at the paths bash named for that command, never another job's, until its exit file is written. Decide from that exit code and the output it names, never from a `tail` of it or a timeout of your own.\n- Report what you saw, not what you expected.",
+  }),
+}));
+
+export const tierOf = (tier) => {
+  const spec = SUBAGENT_TIERS[tier];
+  if (!spec) throw new Error(`unknown subagent tier ${JSON.stringify(tier)} (expected ${Object.keys(SUBAGENT_TIERS).join(", ")})`);
+  return spec;
+};
+
+// What the lead's model reads when it picks a tool: that the tier costs less, when to use it, when to do it itself, one example.
+export function tierDescription(tier) {
+  const { use, refuse, example } = tierOf(tier);
+  return `Use when ${use} Not for ${refuse} ${ROUTING_RULE} Example: ${example}`;
+}
+
+// The worker's whole prompt: who it is, its rules, its turn budget, when it stops, and the report it returns.
+export function tierInstructions(tier) {
+  const { prompt, budget, stop, report } = tierOf(tier);
+  return `${prompt}\n- You have ${budget} turns. Stop and report when ${stop}\n\nYour task follows the fanout contract. Reply with exactly this report, no preamble:\n\n\`\`\`\n${report}\n\`\`\`\n`;
+}

package/sync-kit.d.mts

@@ -1,4 +1,4 @@
-export type KitBot = { name: string; runsOn: 'local' | 'hosted'; files: Record<string, string> };
+export type KitBot = { name: string; runsOn: 'local' | 'hosted'; files: Record<string, string>; subagents?: string[] };
 export type KitChange = {
   write: { bot: string; file: string; content: string }[];
   delete: { bot: string; file: string }[];

package/sync-kit.mjs

@@ -6,8 +6,9 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, rmdirSync, unlinkSync
 import { dirname, join } from "node:path";
 import {
   DEPLOYED_KIT_FILES, ROLE_DIR, EXECUTION_CONTEXT_STUB_FILE, ROLE_FILE, KIT_FILES, MAIN_INSTRUCTIONS, MAIN_INSTRUCTIONS_STUB, MAIN_KIT_FILES, MEMORY_STUBS, PROTOCOL_STUB, PROTOCOL_STUB_FILE,
-  botInstructionsStub, executionContextStub, instructionsSource, isKitReexport, kitPath, kitStub,
+  botInstructionsStub, executionContextStub, instructionsSource, isKitReexport, kitPath, kitStub, tierFiles,
 } from "./stubs.mjs";
+import { SUBAGENT_TIERS } from "./subagent-tiers.mjs";
 
 const KIT_DIRS = ["tools", "skills", "hooks", "channels", "schedules", "instructions", "memory", "connections"];
 const SUBAGENT = /^(?:subagents\/[^/]+\/)+/;
@@ -25,7 +26,8 @@ const HOST_ONLY_MODULES = new Set(HOST_ONLY.map(moduleOf));
 /** Whether `file` (relative to a bot's agent/ folder, subagents included) is one syncKit reads: a stub, or any source that holds a stub's slot. */
 const ROLE_ADDITION = /^role\/[^/]+\.md$/;
 const LEGACY_ADDITION = /^instructions\/[^/]+\.md$/;
-export const isKitFile = (file) => file === "instructions.md" || file === MAIN_INSTRUCTIONS || file === ROLE_FILE || ROLE_ADDITION.test(file) || isSource(file);
+const SUBAGENT_DEFINITION = /^(?:subagents\/[^/]+\/)+agent\.ts$/;
+export const isKitFile = (file) => file === "instructions.md" || file === MAIN_INSTRUCTIONS || file === ROLE_FILE || ROLE_ADDITION.test(file) || SUBAGENT_DEFINITION.test(file) || isSource(file);
 
 // Every kit module the file imports, from its import and export lines only.
 function kitImports(text) {
@@ -34,8 +36,11 @@ function kitImports(text) {
 }
 
 /**
- * bots: [{ name, runsOn, files }], files being { "<path under agents/<name>/agent>": text } for the files
- * isKitFile accepts (a subagent's are under "subagents/<x>/"). modules: every kit module a stub may import
+ * bots: [{ name, runsOn, files, subagents }], files being { "<path under agents/<name>/agent>": text } for the files
+ * isKitFile accepts (a subagent's are under "subagents/<x>/"), subagents the names the bot declares in
+ * hub.workspace.json (agents[].subagents). A declared worker tier (subagent-tiers.mjs) with no
+ * subagents/<tier>/agent.ts gets its folder written; one that has it is the workspace's and left.
+ * modules: every kit module a stub may import
  * ("tools/post_message"). runsOn "local" gets the whole kit, execution-context and memory stubs included;
  * "hosted" only the stubs a Vercel function can run (DEPLOYED_KIT_FILES) and loses the others, which the
  * build writes itself (memory, execution context) or cannot use.
@@ -50,7 +55,7 @@ function kitImports(text) {
 export function syncKit({ bots, modules }) {
   const kit = new Set(modules);
   const change = { write: [], delete: [], report: [], instructions: {} };
-  for (const { name: bot, runsOn, files: found } of bots) {
+  for (const { name: bot, runsOn, files: found, subagents = [] } of bots) {
     if (runsOn !== "local" && runsOn !== "hosted") throw new Error(`${bot}: runsOn must be "local" or "hosted", not ${JSON.stringify(runsOn)}`);
     const local = runsOn === "local";
     const main = bot === "main";
@@ -61,6 +66,10 @@ export function syncKit({ bots, modules }) {
       files[file] = content;
       change.write.push({ bot, file, content });
     };
+    for (const tier of subagents) {
+      if (!SUBAGENT_TIERS[tier] || has(`subagents/${tier}/agent.ts`)) continue;
+      for (const [file, content] of Object.entries(tierFiles(bot, tier))) write(file, content);
+    }
     // A bot with a role.md gets its whole prompt from instructions.ts; the shared-sections stub would repeat it,
     // and an instructions.md beside it would put the old text first, so that is a conflict, found before
     // anything is changed: the bot keeps what it has.
@@ -132,7 +141,7 @@ export function readBotFiles(agentDir, prefix = "") {
     read(MAIN_INSTRUCTIONS);
     read(ROLE_FILE);
     if (existsSync(join(agentDir, ROLE_DIR))) for (const entry of readdirSync(join(agentDir, ROLE_DIR), { withFileTypes: true })) if (entry.isFile() && ROLE_ADDITION.test(`${ROLE_DIR}/${entry.name}`)) read(`${ROLE_DIR}/${entry.name}`);
-  }
+  } else read("agent.ts");
   for (const dir of KIT_DIRS) {
     if (!existsSync(join(agentDir, dir))) continue;
     for (const entry of readdirSync(join(agentDir, dir), { withFileTypes: true })) if (entry.isFile() && isKitFile(`${dir}/${entry.name}`)) read(`${dir}/${entry.name}`);

package/templates/execution.md

@@ -15,11 +15,9 @@
   - Why: every question costs the human a context switch, and most answers are in the code or the history.
 - **Split the work**
   - Do the part your role owns; hand the rest to the role that owns it, because skipping a role skips its check.
-  - Do a small task yourself. Split only separable parts; every split costs a handoff.
-  - Exploration (reading code, tracing call sites, web research) goes to an `agent` copy or a researcher.
-  - An edit you can fully specify (files, change, how to verify) goes to `kit__worker` if you have it; you read its diff and run the tests.
-  - A delegation carries the goal, what's decided, what to return and what not to touch; the receiver starts with none of your context.
-  - A subagent with no commit, push or verdict in 30 minutes is stuck: cancel it and finish the work yourself.
+  - Your reader, editor and verifier run on models far cheaper than yours: reading goes to reader, specified edits to editor, pass/fail checks (running tests included) to verifier. When work splits, count the pieces before you route: three files to trace is three readers, two test runs to check is two verifiers. Never merge pieces, and never keep one of them yourself. One question, one edit or one test run, with nothing beside it, is a single task, not a piece. Fan out work that splits into independent pieces: one tier call per piece, all in one step. A single task stays with you, however long. Judgment always stays with you.
+  - Before you hand work to a reader, editor, verifier or `agent` copy, load the `fanout` skill and follow it: the receiver starts with none of your context.
+  - A subagent with no commit, push, report or verdict in 30 minutes is stuck: cancel it and finish the work yourself.
 - **Waiting**
   - Never sleep or poll more than 60 seconds in one command. Check CI or a deploy once, report, and say what you're waiting on.
   - While work runs, post at least every 30 minutes: a result, or the one thing blocking you.