paseo-bm-plugin 0.0.0-placeholder.0

package/server/role-extras.ts

@@ -0,0 +1,270 @@
+/**
+ * Additional instructions the user writes for each role (delta
+ * 20260916-setup-screen §3.2).
+ *
+ * Paseo's plugin settings cannot be read on the server, and the instructions
+ * are applied on the server (agent.create hook, manager.ensure), so they live
+ * in the install home as the user's own file, next to `traces/`: no hash in
+ * `install.json`, never touched by an update or `--prune`.
+ *
+ * They are only ever appended after the base instructions, under a heading
+ * that says they cannot override a RULES item.
+ */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+import { resolveInstallHome, TRACES_DIR_NAME, type InstallHomePaseo } from "./install-home";
+import { MANAGER_INSTRUCTIONS } from "./manager-instructions";
+import { REVIEWER_INSTRUCTIONS } from "./reviewer-instructions";
+import { WORKER_INSTRUCTIONS } from "./worker-instructions";
+import { writeStoreFileAtomically } from "./trace-store";
+import { TIMED_OUT, capabilityOf, chooseModeId, lastModesOf, modesFor, profileModeOf, runPostureOf, withTimeout, type ProviderMode } from "./role-mode";
+import { DashboardError } from "../shared/contracts";
+
+export type Role = "manager" | "worker" | "reviewer";
+
+export const ROLE_EXTRAS_FILE = "role-extras.json";
+export const MAX_EXTRA_CHARS = 8000;
+
+export const BASE_INSTRUCTIONS: Readonly<Record<Role, string>> = {
+  manager: MANAGER_INSTRUCTIONS,
+  worker: WORKER_INSTRUCTIONS,
+  reviewer: REVIEWER_INSTRUCTIONS,
+};
+
+/** Placed between the base and the user's text. Agent-facing, so English. */
+export const EXTRA_HEADING = [
+  "## Additional instructions from the user",
+  "",
+  "These add to the rules above and never override a RULES item.",
+].join("\n");
+
+const extrasSchema = z.object({
+  version: z.literal(1),
+  roles: z.object({
+    manager: z.string().max(MAX_EXTRA_CHARS).default(""),
+    worker: z.string().max(MAX_EXTRA_CHARS).default(""),
+    reviewer: z.string().max(MAX_EXTRA_CHARS).default(""),
+  }),
+});
+
+export type RoleExtras = Record<Role, string>;
+
+const EMPTY: RoleExtras = { manager: "", worker: "", reviewer: "" };
+
+/**
+ * Facts the plugin resolves when it builds a role's instructions (delta
+ * 20260917c §4.6, owner decision Q22, errata 2026-09-18). Each is the mode an
+ * agent must pass when it creates its child, because Paseo refuses that
+ * creation without one before any hook runs (K10): the Manager passes the
+ * Worker mode, and the Worker — refused as `bypassPermissions` too — passes
+ * the Reviewer mode.
+ */
+export interface RuntimeFacts {
+  workerModeId?: string | null;
+  reviewerModeId?: string | null;
+  /** The Worker's provider has no modes at all (Pi): the Manager must pass none (delta 20260921 §4.2.3). */
+  workerModeNone?: boolean;
+  /** The Reviewer's provider has no modes at all (Pi): the Worker must pass none. */
+  reviewerModeNone?: boolean;
+}
+
+/**
+ * Reviewer mode the Worker is told when no mode list could ever be read (owner
+ * decision Q9 a). Only for a `bm-reviewer` whose base provider is one of
+ * `REVIEWER_FALLBACK_PROVIDERS`, or cannot be read at all: another provider
+ * does not list `auto`, and Paseo would refuse the creation on it (delta
+ * 20260921 §4.2.2, F4).
+ */
+export const REVIEWER_FALLBACK_MODE = "auto";
+
+/** Base providers known to list `auto` (proposal §1.1). */
+export const REVIEWER_FALLBACK_PROVIDERS: readonly string[] = ["claude", "codex"];
+
+/** Agent-facing, so English. `roles/manager.md` and `roles/worker.md` point at this heading. */
+export const RUNTIME_FACTS_HEADING = "## Runtime facts";
+
+/** The Runtime facts section for a role, or "" when there is nothing to state. */
+export function runtimeFactsText(role: Role, facts: RuntimeFacts = {}): string {
+  const trimmed = (value: string | null | undefined) => (typeof value === "string" ? value.trim() : "");
+  const child = role === "manager" ? "Worker" : role === "worker" ? "Reviewer" : null;
+  if (child === null) return "";
+  const none = role === "manager" ? facts.workerModeNone === true : facts.reviewerModeNone === true;
+  if (none) {
+    return `${RUNTIME_FACTS_HEADING}\n\n${child} mode: none — do not pass \`settings.modeId\` when you create a ${child}; Paseo sets it.`;
+  }
+  const mode = role === "manager" ? trimmed(facts.workerModeId) : trimmed(facts.reviewerModeId);
+  if (mode === "") return "";
+  return `${RUNTIME_FACTS_HEADING}\n\n${child} mode: \`${mode}\` — pass it as \`settings.modeId\` when you create a ${child}.`;
+}
+
+/**
+ * Base instructions, then the Runtime facts, then the user's text. With
+ * neither facts nor text this is the base, byte for byte.
+ */
+export function fullInstructions(role: Role, extra: string, facts: RuntimeFacts = {}): string {
+  const text = extra.trim();
+  const base = BASE_INSTRUCTIONS[role];
+  const factsText = runtimeFactsText(role, facts);
+  if (text === "" && factsText === "") return base;
+  let out = base.trimEnd();
+  if (factsText !== "") out += `\n\n${factsText}`;
+  if (text !== "") out += `\n\n---\n\n${EXTRA_HEADING}\n\n${text}`;
+  return `${out}\n`;
+}
+
+/**
+ * The Runtime facts that apply to a role now. For the Manager: the Worker mode
+ * the hook's own rule picks from `listModes("bm-worker")`; for the Worker: the
+ * Reviewer mode it picks from `listModes("bm-reviewer")`. So what the creator
+ * passes and what the hook would choose are the same value. `{}` when it cannot
+ * be read — the failure is logged, and the creation attempt then fails loudly
+ * with Paseo's list of modes rather than silently.
+ */
+export async function runtimeFactsOf(
+  role: Role,
+  paseo: unknown,
+  cwd?: string,
+  log: (message: string) => void = (message) => console.warn(message),
+): Promise<RuntimeFacts> {
+  if (role === "reviewer") return {};
+  try {
+    if (role === "worker") {
+      const profileModeId = await profileModeOf(paseo, "bm-reviewer");
+      const modes = await modesFor(paseo, "bm-reviewer", undefined, cwd);
+      // Delta 20260921 §4.2.2–§4.2.3: the value the hook's posture rule gives
+      // the Reviewer on an untiered provider, or "none" for one without modes.
+      const byCapability = childModeByCapability("reviewer", modes, profileModeId);
+      if (byCapability !== undefined) {
+        return byCapability === null ? { reviewerModeNone: true } : { reviewerModeId: byCapability };
+      }
+      if (modes === null) {
+        const base = await baseProviderOf(paseo, "bm-reviewer");
+        if (base !== null && !REVIEWER_FALLBACK_PROVIDERS.includes(base)) {
+          // `auto` is Claude's and Codex's; told to a Worker whose Reviewer runs
+          // elsewhere, it would only make Paseo refuse the creation (F4).
+          const last = lastModesOf("bm-reviewer");
+          const fromLast = last === null ? undefined : childModeByCapability("reviewer", last.modes, profileModeId);
+          if (typeof fromLast === "string") {
+            log(`[paseo-bm] could not read the modes of bm-reviewer; the Worker is told to pass the Reviewer mode "${fromLast}" (last list read at ${last!.at}).`);
+            return { reviewerModeId: fromLast };
+          }
+          log(`[paseo-bm] could not read the modes of bm-reviewer (base provider ${base}); the Worker is told no Reviewer mode.`);
+          return {};
+        }
+        // Unlike the Manager's case, the profile's own mode is NOT passed blind:
+        // its tier is unknown, and a Reviewer must never run in a dangerous one.
+        // The fallback is the last list read in this run, through the same
+        // rule, else `auto` — the rule's first choice, listed by Claude and
+        // Codex; a provider without it makes Paseo refuse the creation loudly
+        // (delta 20260918g §4.9, owner decisions Q4 a and Q9 a).
+        const last = lastModesOf("bm-reviewer");
+        const fromLast = last === null ? undefined : chooseModeId("reviewer", last.modes, undefined, profileModeId);
+        const reviewerModeId = fromLast ?? REVIEWER_FALLBACK_MODE;
+        const source = fromLast === undefined ? "static fallback" : `last list read at ${last!.at}`;
+        log(`[paseo-bm] could not read the modes of bm-reviewer; the Worker is told to pass the fallback Reviewer mode "${reviewerModeId}" (${source}).`);
+        return { reviewerModeId };
+      }
+      const reviewerModeId = chooseModeId("reviewer", modes, undefined, profileModeId);
+      return reviewerModeId === undefined ? {} : { reviewerModeId };
+    }
+    const profileModeId = await profileModeOf(paseo, "bm-worker");
+    const modes = await modesFor(paseo, "bm-worker", undefined, cwd);
+    const byCapability = childModeByCapability("worker", modes, profileModeId);
+    if (byCapability !== undefined) {
+      return byCapability === null ? { workerModeNone: true } : { workerModeId: byCapability };
+    }
+    if (modes === null) {
+      // A mode the owner set by hand on the profile is still worth passing:
+      // Paseo validates it and reports its own error if it is wrong.
+      return profileModeId === null ? {} : { workerModeId: profileModeId };
+    }
+    const workerModeId = chooseModeId("worker", modes, undefined, profileModeId);
+    return workerModeId === undefined ? {} : { workerModeId };
+  } catch (error) {
+    log(`[paseo-bm] reading the Runtime facts of ${role} failed: ${error instanceof Error ? error.message : String(error)}`);
+    return {};
+  }
+}
+
+/**
+ * The child mode on an `untiered` provider (the posture rule's mode: the
+ * profile's if listed, else the first listed), `null` for a provider with no
+ * modes, and `undefined` for `tiered` / `unknown`, whose rules stay as they were.
+ */
+function childModeByCapability(
+  role: "worker" | "reviewer",
+  modes: readonly ProviderMode[] | null,
+  profileModeId: string | null,
+): string | null | undefined {
+  const capability = capabilityOf(modes);
+  if (capability === "none") return null;
+  if (capability !== "untiered") return undefined;
+  return runPostureOf(role, "untiered", modes ?? [], null, profileModeId)?.modeId;
+}
+
+/** The `extends` of a paseo-bm provider alias, or `null` when it cannot be read. Never throws. */
+async function baseProviderOf(paseo: unknown, alias: string): Promise<string | null> {
+  const get = (paseo as { config?: { get?: unknown } } | null | undefined)?.config?.get;
+  if (typeof get !== "function") return null;
+  try {
+    const result = await withTimeout(
+      get.call((paseo as { config: unknown }).config) as Promise<{ config?: { providers?: Record<string, { extends?: unknown } | undefined> } }>,
+    );
+    if (result === TIMED_OUT) return null;
+    const base = result?.config?.providers?.[alias]?.extends;
+    return typeof base === "string" && base.trim() !== "" ? base : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The extras in `home`; empty when the file is missing or unreadable. Never throws. */
+export function readRoleExtras(home: string): RoleExtras {
+  try {
+    const parsed = extrasSchema.safeParse(JSON.parse(readFileSync(join(home, ROLE_EXTRAS_FILE), "utf8")));
+    return parsed.success ? parsed.data.roles : { ...EMPTY };
+  } catch {
+    return { ...EMPTY };
+  }
+}
+
+/** Replaces one role's text. Atomic, 0600, and refuses symlinks inside the home. */
+export function saveRoleExtra(home: string, role: Role, text: string): RoleExtras {
+  if (text.length > MAX_EXTRA_CHARS) {
+    throw new DashboardError("E_ROLE_EXTRA_INVALID", `at most ${MAX_EXTRA_CHARS} characters, got ${text.length}`);
+  }
+  const roles = { ...readRoleExtras(home), [role]: text };
+  writeStoreFileAtomically(
+    { tracesDir: join(home, TRACES_DIR_NAME) },
+    join(home, ROLE_EXTRAS_FILE),
+    `${JSON.stringify({ version: 1, roles }, null, 2)}\n`,
+  );
+  return roles;
+}
+
+/** The install home, or null when paseo-bm's home cannot be confirmed. */
+export async function installHomeOf(paseo: unknown, deps: { homedir?: () => string } = {}): Promise<string | null> {
+  try {
+    const resolution = await resolveInstallHome({
+      paseo: paseo as InstallHomePaseo,
+      fs: { readFileSync: (path, encoding) => readFileSync(path, encoding) },
+      homedir: deps.homedir ?? homedir,
+    });
+    return resolution.home;
+  } catch {
+    return null;
+  }
+}
+
+/** Full instructions for a role as they apply now, falling back to the base. */
+export async function currentInstructions(
+  role: Role,
+  paseo: unknown,
+  deps: { homedir?: () => string; cwd?: string } = {},
+): Promise<string> {
+  const home = await installHomeOf(paseo, deps);
+  const facts = await runtimeFactsOf(role, paseo, deps.cwd);
+  return fullInstructions(role, home === null ? "" : readRoleExtras(home)[role], facts);
+}

package/server/role-hook.ts

@@ -0,0 +1,347 @@
+import type { PluginBeforeRequests, PluginServerContext } from "@getpaseo/plugin/server";
+import { roleOfProvider } from "./agent-role";
+import { providerId } from "./provider-id";
+import {
+  LOOKUP_TIMEOUT_MS,
+  ROLE_GETS_MODE,
+  TIMED_OUT,
+  capabilityOf,
+  chooseModeId,
+  featuresFor,
+  modesFor,
+  profileOf,
+  runPostureOf,
+  withTimeout,
+  type ProviderCapability,
+  type ProviderFeature,
+  type ProviderMode,
+  type RoleProfile,
+} from "./role-mode";
+import {
+  BASE_INSTRUCTIONS,
+  fullInstructions,
+  installHomeOf,
+  readRoleExtras,
+  runtimeFactsOf,
+  type RoleExtras,
+  type RuntimeFacts,
+} from "./role-extras";
+
+/**
+ * Role instructions injected into every paseo-bm agent at creation (bm-hld).
+ *
+ * Paseo's `create_agent` tool has no system-prompt parameter, so a Worker the
+ * Manager creates, or a Reviewer the Worker creates, would otherwise start
+ * without its role contract. The daemon runs `before("agent.create")` hooks for
+ * every agent creation, whoever asks for it, so the plugin sets the prompt
+ * there, keyed by the provider id.
+ *
+ * The same hook sets the start mode of Workers and Reviewers (delta 20260917c
+ * §4.6): what the role files used to teach in a paragraph each is one lookup
+ * here, and it cannot be got wrong by an agent.
+ *
+ * Provider ids map to roles through `roleOfProvider` (agent-role.ts), the
+ * same rule every lookup uses to tell paseo-bm agents apart (delta 20260918g):
+ * the three main aliases and the fallback aliases `bm-<role>-fallback-<n>`
+ * (delta 20260921 §4.4.1). Lookups use the agent's real alias.
+ */
+
+export { chooseModeId, type ProviderMode } from "./role-mode";
+
+/** Separates the role instructions from a system prompt that was already set. */
+export const ROLE_PROMPT_SEPARATOR = "\n\n---\n\n";
+
+/** The `agent.create` before-request the daemon hands to the hook. */
+export type AgentCreateRequest = PluginBeforeRequests["agent.create"];
+
+/**
+ * Returns the request with the role instructions in `config.systemPrompt`, or
+ * `undefined` when nothing changes (not a paseo-bm provider, or the prompt
+ * already contains the instructions). Never throws.
+ *
+ * An existing, different system prompt is kept after the instructions,
+ * separated by `ROLE_PROMPT_SEPARATOR`.
+ */
+export function applyRoleInstructions(
+  request: AgentCreateRequest,
+  extras: Partial<RoleExtras> = {},
+  facts: RuntimeFacts = {},
+): AgentCreateRequest | undefined {
+  try {
+    // Typed as required, but never trusted: a malformed request must not throw.
+    const config = (request as Partial<AgentCreateRequest> | null | undefined)?.config;
+    if (config === null || typeof config !== "object") return undefined;
+    const role = roleOfProvider(config.provider);
+    if (role === null) return undefined;
+    const base = BASE_INSTRUCTIONS[role];
+    // The user's additions from the Setup screen come after the base, never instead of it.
+    // Runtime facts sit between the two, so manager.ensure and this hook write the same text.
+    const instructions = fullInstructions(role, extras[role] ?? "", facts);
+
+    const existing = typeof config.systemPrompt === "string" ? config.systemPrompt : "";
+    if (existing.includes(instructions)) return undefined;
+    let systemPrompt: string;
+    if (existing.includes(base)) {
+      // Set by an older call with the base only: upgrade it in place.
+      systemPrompt = existing.replace(base, instructions);
+    } else {
+      systemPrompt = existing.trim() === "" ? instructions : `${instructions}${ROLE_PROMPT_SEPARATOR}${existing}`;
+    }
+    return { ...request, config: { ...config, systemPrompt } };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Returns the request with `config.modeId` set by `chooseModeId`, or
+ * `undefined` when nothing changes. `modes` is `null` when the provider's list
+ * could not be read. Never throws.
+ */
+export function applyRoleMode(
+  request: AgentCreateRequest,
+  modes: readonly ProviderMode[] | null,
+  profileModeId: string | null = null,
+): AgentCreateRequest | undefined {
+  try {
+    if (modes === null) return undefined;
+    const config = (request as Partial<AgentCreateRequest> | null | undefined)?.config;
+    if (config === null || typeof config !== "object") return undefined;
+    const id = providerId(config.provider);
+    const role = roleOfProvider(id);
+    if (id === null || role === null) return undefined;
+    const current = typeof config.modeId === "string" && config.modeId.trim() !== "" ? config.modeId : undefined;
+    const modeId = chooseModeId(role, modes, current, profileModeId);
+    if (modeId === undefined || modeId === current) return undefined;
+    if (current !== undefined) {
+      console.warn(`[paseo-bm] ${id} was created in mode "${current}", which that role must not use; starting it in "${modeId}" instead.`);
+    }
+    return { ...request, config: { ...config, modeId } };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The model a creation request names, or `null`: the daemon's resolved
+ * `config.model` when set, else everything after the FIRST `/` of
+ * `config.provider` (OpenCode model ids contain `/` themselves, so
+ * `bm-worker/anthropic/claude-sonnet-4-6` names `anthropic/claude-sonnet-4-6`).
+ */
+function requestModelOf(config: { provider?: unknown; model?: unknown }): string | null {
+  if (typeof config.model === "string" && config.model.trim() !== "") return config.model;
+  if (typeof config.provider !== "string") return null;
+  const slash = config.provider.indexOf("/");
+  return slash === -1 || slash === config.provider.length - 1 ? null : config.provider.slice(slash + 1);
+}
+
+/**
+ * Returns the request with the thinking level and feature values of the
+ * Worker's or Reviewer's own profile (delta 20260921 §4.1.1, REQ-062 a), or
+ * `undefined` when nothing changes. Never throws.
+ *
+ * - `thinkingOptionId`: the profile's, only when the creator passed none and
+ *   the request's model is the profile's model (or names no model): a
+ *   thinking level belongs to a model and may not exist on another one.
+ * - `featureValues`: the profile's, merged under the creator's, whose keys win.
+ *
+ * The Manager is left alone: `manager.ensure` already passes its profile.
+ */
+export function applyRoleProfile(request: AgentCreateRequest, profile: RoleProfile | null): AgentCreateRequest | undefined {
+  try {
+    if (profile === null) return undefined;
+    const config = (request as Partial<AgentCreateRequest> | null | undefined)?.config;
+    if (config === null || typeof config !== "object") return undefined;
+    const role = roleOfProvider(config.provider);
+    if (role === null) return undefined;
+    if (role !== "worker" && role !== "reviewer") return undefined;
+
+    const next: Record<string, unknown> = { ...config };
+    let changed = false;
+    const current = typeof config.thinkingOptionId === "string" && config.thinkingOptionId.trim() !== "";
+    const model = requestModelOf(config);
+    if (!current && profile.thinkingOptionId !== null && (model === null || model === profile.model)) {
+      next.thinkingOptionId = profile.thinkingOptionId;
+      changed = true;
+    }
+    if (profile.featureValues !== null) {
+      const own = config.featureValues;
+      const creator = own !== null && typeof own === "object" && !Array.isArray(own) ? own : {};
+      const merged = { ...profile.featureValues, ...creator };
+      if (JSON.stringify(merged) !== JSON.stringify(own ?? null)) {
+        next.featureValues = merged;
+        changed = true;
+      }
+    }
+    return changed ? { ...request, config: next as unknown as AgentCreateRequest["config"] } : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Returns the request with the start mode and auto-approve of a Worker or
+ * Reviewer on an `untiered` or `none` provider (delta 20260921 §4.2.2), or
+ * `undefined` when nothing changes. `tiered` and `unknown` providers keep
+ * `applyRoleMode`. Never throws.
+ */
+export function applyRunPosture(
+  request: AgentCreateRequest,
+  capability: ProviderCapability,
+  modes: readonly ProviderMode[] | null,
+  features: readonly ProviderFeature[] | null,
+  profileModeId: string | null = null,
+): AgentCreateRequest | undefined {
+  try {
+    const config = (request as Partial<AgentCreateRequest> | null | undefined)?.config;
+    if (config === null || typeof config !== "object") return undefined;
+    const role = roleOfProvider(config.provider);
+    if (role === null) return undefined;
+    if (!ROLE_GETS_MODE[role]) return undefined;
+    const own = config.featureValues;
+    const current = {
+      ...(typeof config.modeId === "string" && config.modeId.trim() !== "" ? { modeId: config.modeId } : {}),
+      ...(own !== null && typeof own === "object" && !Array.isArray(own) ? { featureValues: own } : {}),
+    };
+    const posture = runPostureOf(role, capability, modes ?? [], features, profileModeId, current);
+    if (posture === undefined || (posture.modeId === undefined && posture.featureValues === undefined)) return undefined;
+    const next: Record<string, unknown> = { ...config };
+    // `null` removes the key: a provider without modes gets neither (review b4).
+    if (posture.modeId === null) delete next.modeId;
+    else if (posture.modeId !== undefined) next.modeId = posture.modeId;
+    if (posture.featureValues === null) delete next.featureValues;
+    else if (posture.featureValues !== undefined) next.featureValues = posture.featureValues;
+    return { ...request, config: next as unknown as AgentCreateRequest["config"] };
+  } catch {
+    return undefined;
+  }
+}
+
+/** Instructions, profile settings and start posture together; `undefined` when none changes. */
+export function applyRoleConfig(
+  request: AgentCreateRequest,
+  extras: Partial<RoleExtras> = {},
+  modes: readonly ProviderMode[] | null = null,
+  facts: RuntimeFacts = {},
+  profileModeId: string | null = null,
+  profile: RoleProfile | null = null,
+  features: readonly ProviderFeature[] | null = null,
+): AgentCreateRequest | undefined {
+  const withInstructions = applyRoleInstructions(request, extras, facts);
+  const withProfile = applyRoleProfile(withInstructions ?? request, profile) ?? withInstructions;
+  const capability = capabilityOf(modes);
+  const posture =
+    capability === "untiered" || capability === "none"
+      ? applyRunPosture(withProfile ?? request, capability, modes, features, profileModeId)
+      : applyRoleMode(withProfile ?? request, modes, profileModeId);
+  return posture ?? withProfile;
+}
+
+/**
+ * The provider id whose modes are worth a lookup, or `null`. A Reviewer needs
+ * the list to recognise a mode it must not run in; a Worker needs it even
+ * when its creator already chose a mode, because the capability class decides
+ * its auto-approve (delta 20260921 §4.2.1: on OpenCode the Worker's chosen
+ * mode is kept but `auto_accept` must still be turned on).
+ */
+function modeLookupFor(request: AgentCreateRequest): string | null {
+  try {
+    const config = (request as Partial<AgentCreateRequest> | null | undefined)?.config;
+    const id = providerId(config?.provider);
+    const role = roleOfProvider(id);
+    if (id === null || role === null) return null;
+    return ROLE_GETS_MODE[role] ? id : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Everything the hook needs from the daemon, gathered under one time budget. */
+async function prepare(
+  request: AgentCreateRequest,
+  paseo: unknown,
+): Promise<{
+  extras: Partial<RoleExtras>;
+  modes: ProviderMode[] | null;
+  facts: RuntimeFacts;
+  profileModeId: string | null;
+  profile: RoleProfile | null;
+  features: ProviderFeature[] | null;
+}> {
+  let extras: Partial<RoleExtras> = {};
+  try {
+    const home = await installHomeOf(paseo);
+    if (home !== null) extras = readRoleExtras(home);
+  } catch {
+    // Without the additions the agent still gets its base instructions.
+  }
+  const cwd = typeof request?.config?.cwd === "string" ? request.config.cwd : undefined;
+  const id = providerId(request?.config?.provider);
+  const role = roleOfProvider(id) ?? undefined;
+  // The Worker's or Reviewer's own profile: its mode (bm-msy), and its
+  // thinking and features (delta 20260921 §4.1.1). One read, whether or not
+  // the mode needs a lookup: a Worker created WITH a mode still gets the
+  // thinking set on its profile.
+  const profile = role === "worker" || role === "reviewer" ? await profileOf(paseo, id!) : null;
+  const lookup = modeLookupFor(request);
+  const profileModeId = lookup === null ? null : (profile?.modeId ?? null);
+  const modes = lookup === null ? null : await modesFor(paseo, lookup, undefined, cwd);
+  // Only an untiered provider (OpenCode) costs the features round trip: its
+  // auto-approve toggle is the one feature the posture rule sets (§4.2.2).
+  const selection = typeof request?.config?.provider === "string" ? request.config.provider : (id ?? "");
+  const features = capabilityOf(modes) === "untiered" ? await featuresFor(paseo, selection, cwd) : null;
+  const facts = role === undefined ? {} : await runtimeFactsOf(role, paseo, cwd);
+  return { extras, modes, facts, profileModeId, profile, features };
+}
+
+function isBmRequest(request: AgentCreateRequest): boolean {
+  try {
+    return roleOfProvider((request as Partial<AgentCreateRequest> | null | undefined)?.config?.provider) !== null;
+  } catch {
+    return false;
+  }
+}
+
+/** The part of the server context this hook needs; `before` is absent on older hosts. */
+export type RoleHookHost = Partial<Pick<PluginServerContext, "before">>;
+
+/**
+ * Registers the `before("agent.create")` hook and returns its remover. On a
+ * host without `before` it logs one line and returns a no-op.
+ */
+export function registerRoleHook(host: RoleHookHost): () => void {
+  if (typeof host.before !== "function") {
+    console.warn(
+      "[paseo-bm] this Paseo host has no before(\"agent.create\") hook; Worker and Reviewer agents will start without role instructions.",
+    );
+    return () => {};
+  }
+  const remove = host.before("agent.create", (input, context) => {
+    const request = (input as { request?: AgentCreateRequest } | undefined)?.request as AgentCreateRequest;
+    // Every agent creation passes here: only paseo-bm's own pay for a lookup.
+    if (!isBmRequest(request)) return undefined;
+    return (async () => {
+      const paseo = (context as { paseo?: unknown } | undefined)?.paseo;
+      // The host fails the whole creation if this hook takes longer than 30 s,
+      // so everything it looks up is raced as ONE budget: a slow daemon costs
+      // the extras, the mode and the facts, never the agent.
+      const prepared = await withTimeout(prepare(request, paseo), LOOKUP_TIMEOUT_MS);
+      if (prepared === TIMED_OUT) {
+        console.warn(
+          `[paseo-bm] preparing the role config took longer than ${LOOKUP_TIMEOUT_MS} ms; the agent starts with its role instructions only.`,
+        );
+        return applyRoleInstructions(request);
+      }
+      return applyRoleConfig(
+        request,
+        prepared.extras,
+        prepared.modes,
+        prepared.facts,
+        prepared.profileModeId,
+        prepared.profile,
+        prepared.features,
+      );
+    })();
+  });
+  return typeof remove === "function" ? remove : () => {};
+}