opencode-courier 0.11.1 → 0.13.0

package/dist/tree/ports.d.ts

@@ -5,8 +5,8 @@
 import type { Plugin } from "@opencode/plugin";
 import type { Status } from "../kernel/protocol.js";
 import type { Storage } from "../platform/storage.js";
-import type { Limits, Member, RosterEntry } from "./domain.js";
-export type { Artifacts, HeldReport, LeftMember, Limits, Member, RosterEntry, Standing } from "./domain.js";
+import type { Limits, Member, ModelRef, RosterEntry } from "./domain.js";
+export type { Artifacts, HeldReport, LeftMember, Limits, Member, ModelRef, RosterEntry, Standing } from "./domain.js";
 type Context = Plugin.Context;
 export type RosterStorage = Storage;
 /** How a session's wait for a report ended: it reported to its parent, or its turn failed or was interrupted. */
@@ -43,6 +43,8 @@ export interface ChildStore {
     entriesOf(sessionID: string): Promise<RosterEntry[]>;
     /** The session that started a session, by the reverse index alone, without scanning the roster. */
     indexedParent(sessionID: string): Promise<string | undefined>;
+    /** The sessions above a session, its parent first, by the reverse index alone: empty when it does not name the session. */
+    indexedAncestors(sessionID: string): Promise<ReadonlyArray<string>>;
     /** A session's roster entry, by the reverse index alone, without scanning the roster. */
     indexedEntry(sessionID: string): Promise<RosterEntry | undefined>;
     /**
@@ -149,10 +151,42 @@ export interface Sent {
     readonly status?: Status;
     readonly report?: boolean;
     readonly held?: Held;
+    /** The status it was sent with to a session below the sender, where a status means nothing. */
+    readonly dropped?: Status;
+}
+/**
+ * What the `context` hook remembers of a session: its depth, null for one nobody spawned that has started none, and
+ * whether it carries the role entry (`ROLE_KEY`), which then names its role in place of the hook's system part.
+ */
+export interface Role {
+    readonly depth: number | null;
+    readonly entry: boolean;
+}
+/** The keyed session entries, missing on a host before 2.2.0 (every copy's ports carry the host's `session`): an entry is then skipped. */
+export type Instructions = Partial<Pick<Context["session"], "instructions">>;
+/** A keyed session instruction entry: its key, `^[a-z0-9][a-z0-9._-]*$`, and its text. */
+export interface Entry {
+    readonly key: string;
+    readonly value: string;
+}
+/**
+ * Supplies the entries other modules write to a spawned session below `maxDepth` before its prompt, and to a root at its
+ * first spawn beside its role; `src/index.ts` composes it from the modules' suppliers, as it does the `Waits` port.
+ */
+export type Entries = () => Promise<ReadonlyArray<Entry>>;
+/** What writing a parent's `standing` entry needs: the tools', the watcher's and the scheduler's ports all have these. */
+export interface StandingPorts {
+    readonly storage: RosterStorage;
+    readonly now: () => number;
+    readonly session?: Instructions;
+    readonly log?: (message: string) => void;
 }
 /** The slice of the plugin context the courier tools use; tests pass a fake. */
 export interface CourierPorts {
-    readonly session: Pick<Context["session"], "create" | "prompt" | "synthetic" | "get" | "context" | "interrupt">;
+    /** `instructions`, the keyed session entries, is missing on a host before 2.2.0: the role then goes in a system part. */
+    readonly session: Pick<Context["session"], "create" | "prompt" | "synthetic" | "get" | "context" | "interrupt"> & Instructions;
+    /** The entries of other modules a spawned session gets before its prompt, the memory's lessons; none when not given. */
+    readonly entries?: Entries;
     readonly agent: Pick<Context["agent"], "get">;
     readonly worktree: Pick<Context["worktree"], "create" | "remove">;
     /** The project of the plugin's location; an isolated child's worktree is made in it, and removed from it. */
@@ -168,24 +202,30 @@ export interface CourierPorts {
     readonly pending: (sessionID: string) => Promise<ReadonlyArray<Pending>>;
     /** The forms a session shows, which only the person can answer: web search's, a plugin's; not the question tool's. */
     readonly forms: (sessionID: string) => Promise<ReadonlyArray<ShownForm>>;
-    /** The context windows of the models available, by provider and model id, as the panel reads a session's context use. */
-    readonly windows: () => Promise<ReadonlyArray<ModelWindow>>;
+    /** The models available, each with its context window and variants, as courier_spawn checks a choice and the panel reads a session's context use. */
+    readonly models: () => Promise<ReadonlyArray<KnownModel>>;
+    /** OpenCode's default model here, which a session with no model of its own runs on; undefined when there is none. */
+    readonly defaultModel: () => Promise<ModelRef | undefined>;
     readonly limits: Limits;
-    /** The `nativeChildren` option: a child started without isolate is created with OpenCode's own `parentID`. */
+    /** The `nativeChildren` option: a child started without isolate and without `native` is created with OpenCode's own `parentID`. */
     readonly nativeChildren?: boolean;
     readonly gate: SpawnGate;
-    /** The depths the `context` hook remembers; a parent's is dropped when it starts a child. */
-    readonly roles: Map<string, number | null>;
+    /** The roles the `context` hook remembers; a parent's is dropped when it starts a child, a root's kept once its entry is written. */
+    readonly roles: Map<string, Role>;
     /** Has the scheduler deliver what is due now rather than at its next tick: a group a report has just completed. */
     readonly nudge: () => void;
     readonly log: (message: string) => void;
 }
-/** A model's context window in tokens, as `CourierPorts.windows` lists it. */
+/** A model's context window in tokens, as the panel and the memory read a session's context use by. */
 export interface ModelWindow {
     readonly providerID: string;
     readonly id: string;
     readonly context: number;
 }
+/** A model OpenCode lists, as `CourierPorts.models` gives it: its window, and the ids of its variants. */
+export interface KnownModel extends ModelWindow {
+    readonly variants: ReadonlyArray<string>;
+}
 /** A form a session shows, as `CourierPorts.forms` lists it; `person/` keeps them. */
 export interface ShownForm {
     readonly id: string;
@@ -270,6 +310,9 @@ export interface CleanupPorts {
     readonly now: () => number;
     /** Has the scheduler deliver what is due now: a group the forgotten child may have been the last member out of. */
     readonly nudge: () => void;
+    /** For the parent's `standing` entry once the child is forgotten; without them it is left as it was. */
+    readonly session?: Instructions;
+    readonly log?: (message: string) => void;
 }
 export interface StopPorts {
     readonly courier: CourierPorts;
@@ -279,7 +322,8 @@ export interface StopPorts {
 }
 export interface GroupPorts {
     readonly storage: Storage;
-    readonly session: Pick<Context["session"], "synthetic" | "get">;
+    readonly session: Pick<Context["session"], "synthetic" | "get"> & Instructions;
+    readonly now: () => number;
     readonly log: (message: string) => void;
 }
 /** The error of OpenCode's `session.execution.failed` event. */
@@ -293,7 +337,7 @@ export interface ExecutionError {
 export interface WatchPorts {
     readonly storage: RosterStorage;
     /** `context` reads the last reply of a session that ended its turn without reporting; `get` is what every member joins with too. */
-    readonly session: Pick<Context["session"], "synthetic" | "context" | "get">;
+    readonly session: Pick<Context["session"], "synthetic" | "context" | "get"> & Instructions;
     readonly event: Pick<Context["event"], "subscribe">;
     /** The permission domains of every loaded location, which the `Waits` suppliers ask; an isolated child's are in its worktree's. */
     readonly permissions: () => Iterable<Pick<Context["permission"], "list">>;
@@ -320,8 +364,10 @@ export type Waits = (ports: Pick<WatchPorts, "storage" | "permissions">, session
 export interface ContextPorts {
     readonly storage: RosterStorage;
     readonly limits: Limits;
-    /** Each session's depth once looked up: null for one nobody spawned that has started none, until it starts one. */
-    readonly roles: Map<string, number | null>;
+    /** Each session's role once looked up; a session nobody spawned reads as depth null until it starts one. */
+    readonly roles: Map<string, Role>;
+    /** The keyed session entries, listed when a session's role is looked up; missing on a host before 2.2.0, which gets the system part. */
+    readonly instructions?: Context["session"]["instructions"];
     /** Tools of other modules hidden from a leaf alongside courier_spawn; `src/index.ts` names courier_recall and courier_note. */
     readonly hiddenFromLeaf?: ReadonlyArray<string>;
     readonly log: (message: string) => void;

package/dist/tree/roster.d.ts

@@ -1,10 +1,7 @@
 import { type Status } from "../kernel/protocol.js";
+import { type Exists } from "./domain.js";
 import type { RosterEntry, RosterStorage } from "./ports.js";
-/**
- * Entries older than this are dropped when their parent's roster is read, and on plugin setup,
- * except isolated children whose worktree is still there: those stay until courier_cleanup.
- */
-export declare const RETENTION_MS: number;
+export { RETENTION_MS, type Exists } from "./domain.js";
 /** Every parent's children. */
 export declare function allEntries(storage: RosterStorage): Promise<RosterEntry[]>;
 /**
@@ -33,12 +30,7 @@ export declare function reportState(storage: RosterStorage, sessionID: string):
  * person is there. Throws unless the session was spawned and `callerID` is that top; `what` names it.
  */
 export declare function answeringTop(storage: RosterStorage, sessionID: string, callerID: string, what: string): Promise<string>;
-/** Whether a directory still exists; tests pass a fake. */
-export type Exists = (directory: string) => boolean;
-/**
- * Whether an entry is past retention at `now`: recorded more than `RETENTION_MS` before, unless it is an isolated
- * child whose worktree exists, which is kept so it can still be cleaned up.
- */
+/** `domain.ts`'s `isExpired`, asking the file system whether an isolated child's worktree is still there unless a test passes a fake. */
 export declare const isExpired: (entry: RosterEntry, now: number, exists?: Exists) => boolean;
 /** A parent's children, oldest first, after dropping the expired ones. */
 export declare function current(storage: RosterStorage, parentID: string, now: number, exists?: Exists): Promise<RosterEntry[]>;

package/dist/tree/roster.js

@@ -1,13 +1,10 @@
 import { existsSync } from "node:fs";
 import { isStatus } from "../kernel/protocol.js";
+import { isExpired as expiredBy } from "./domain.js";
 import { forgetChild, forgetReports } from "./forget.js";
 import { stoppedSincePrompt } from "./report.js";
 import { childStore } from "./store.js";
-/**
- * Entries older than this are dropped when their parent's roster is read, and on plugin setup,
- * except isolated children whose worktree is still there: those stay until courier_cleanup.
- */
-export const RETENTION_MS = 14 * 24 * 60 * 60_000;
+export { RETENTION_MS } from "./domain.js";
 /** Every parent's children. */
 export async function allEntries(storage) {
     return childStore(storage).all();
@@ -54,11 +51,8 @@ export async function answeringTop(storage, sessionID, callerID, what) {
         throw new Error(`${sessionID}'s ${what} go to ${top}, the session at the top of the sessions started from it with courier_spawn; ${callerID} cannot answer them.`);
     return top;
 }
-/**
- * Whether an entry is past retention at `now`: recorded more than `RETENTION_MS` before, unless it is an isolated
- * child whose worktree exists, which is kept so it can still be cleaned up.
- */
-export const isExpired = (entry, now, exists = existsSync) => now - entry.createdAt > RETENTION_MS && !(entry.isolated && exists(entry.directory));
+/** `domain.ts`'s `isExpired`, asking the file system whether an isolated child's worktree is still there unless a test passes a fake. */
+export const isExpired = (entry, now, exists = existsSync) => expiredBy(entry, now, exists);
 /** Forgets the given entries that are expired at `now`, and returns the rest. */
 async function dropExpired(storage, entries, now, exists) {
     const expired = new Set(entries.filter((entry) => isExpired(entry, now, exists)));

package/dist/tree/rpc-handlers.d.ts

@@ -87,6 +87,8 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                         readonly status?: string | undefined;
                     } | undefined;
                     readonly idle?: number | undefined;
+                    readonly native?: boolean | undefined;
+                    readonly model?: string | undefined;
                     readonly tool?: {
                         readonly name: string;
                         readonly at: number;
@@ -130,6 +132,8 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                         readonly status?: string | undefined;
                     } | undefined;
                     readonly idle?: number | undefined;
+                    readonly native?: boolean | undefined;
+                    readonly model?: string | undefined;
                     readonly tool?: {
                         readonly name: string;
                         readonly at: number;
@@ -159,6 +163,8 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                         readonly standing: import("effect/Schema").String;
                     }>>;
                     readonly isolated: import("effect/Schema").Boolean;
+                    readonly native: import("effect/Schema").optionalKey<import("effect/Schema").Boolean>;
+                    readonly model: import("effect/Schema").optionalKey<import("effect/Schema").String>;
                     readonly created: import("effect/Schema").Number;
                     readonly idle: import("effect/Schema").optionalKey<import("effect/Schema").Number>;
                     readonly cost: import("effect/Schema").optionalKey<import("effect/Schema").Number>;

package/dist/tree/rpc.d.ts

@@ -60,6 +60,10 @@ declare const Row: Schema.Struct<{
         readonly standing: Schema.String;
     }>>;
     readonly isolated: Schema.Boolean;
+    /** Set when it is OpenCode's subagent of its parent (a native child), which OpenCode's session lists leave out. */
+    readonly native: Schema.optionalKey<Schema.Boolean>;
+    /** The model it was started on, `provider/model` with `#variant` when one is set, when that is not its parent's. */
+    readonly model: Schema.optionalKey<Schema.String>;
     readonly created: Schema.Number;
     /** When its last turn ended, if it is not running. */
     readonly idle: Schema.optionalKey<Schema.Number>;
@@ -117,6 +121,10 @@ declare const Tree: Schema.Struct<{
             readonly standing: Schema.String;
         }>>;
         readonly isolated: Schema.Boolean;
+        /** Set when it is OpenCode's subagent of its parent (a native child), which OpenCode's session lists leave out. */
+        readonly native: Schema.optionalKey<Schema.Boolean>;
+        /** The model it was started on, `provider/model` with `#variant` when one is set, when that is not its parent's. */
+        readonly model: Schema.optionalKey<Schema.String>;
         readonly created: Schema.Number;
         /** When its last turn ended, if it is not running. */
         readonly idle: Schema.optionalKey<Schema.Number>;
@@ -258,6 +266,8 @@ export declare const treeRpc: {
                         readonly status?: string | undefined;
                     } | undefined;
                     readonly idle?: number | undefined;
+                    readonly native?: boolean | undefined;
+                    readonly model?: string | undefined;
                     readonly tool?: {
                         readonly name: string;
                         readonly at: number;
@@ -301,6 +311,8 @@ export declare const treeRpc: {
                         readonly status?: string | undefined;
                     } | undefined;
                     readonly idle?: number | undefined;
+                    readonly native?: boolean | undefined;
+                    readonly model?: string | undefined;
                     readonly tool?: {
                         readonly name: string;
                         readonly at: number;
@@ -341,6 +353,10 @@ export declare const treeRpc: {
                         readonly standing: Schema.String;
                     }>>;
                     readonly isolated: Schema.Boolean;
+                    /** Set when it is OpenCode's subagent of its parent (a native child), which OpenCode's session lists leave out. */
+                    readonly native: Schema.optionalKey<Schema.Boolean>;
+                    /** The model it was started on, `provider/model` with `#variant` when one is set, when that is not its parent's. */
+                    readonly model: Schema.optionalKey<Schema.String>;
                     readonly created: Schema.Number;
                     /** When its last turn ended, if it is not running. */
                     readonly idle: Schema.optionalKey<Schema.Number>;

package/dist/tree/rpc.js

@@ -50,6 +50,10 @@ const Row = Schema.Struct({
     /** Its join group, and its standing there: `held`, `out`, how it left, or `released`. */
     group: Schema.optionalKey(Schema.Struct({ name: Schema.String, standing: Schema.String })),
     isolated: Schema.Boolean,
+    /** Set when it is OpenCode's subagent of its parent (a native child), which OpenCode's session lists leave out. */
+    native: Schema.optionalKey(Schema.Boolean),
+    /** The model it was started on, `provider/model` with `#variant` when one is set, when that is not its parent's. */
+    model: Schema.optionalKey(Schema.String),
     created: Schema.Number,
     /** When its last turn ended, if it is not running. */
     idle: Schema.optionalKey(Schema.Number),

package/dist/tree/send.js

@@ -1,5 +1,6 @@
 import { envelope, isStatus, STATUSES } from "../kernel/protocol.js";
 import { groupStanding, holdReport, membershipFor, unholdForBlocked } from "./group.js";
+import { syncStanding } from "./standing.js";
 import { childStore, groupStore } from "./store.js";
 import { reportBody } from "./text.js";
 import { noteSent } from "./wake.js";
@@ -8,37 +9,63 @@ import { noteSent } from "./wake.js";
  * to the one that started it, it is its report or its progress (`noteReport`); a group member's final report is held (`hold`).
  */
 export async function send(ports, from, input) {
-    // Some models send null for an optional field they leave out.
-    const status = input.status ?? undefined;
-    if (status !== undefined && !isStatus(status))
-        throw new Error(`status must be one of ${STATUSES.join(", ")}, not ${JSON.stringify(status)}.`);
+    const { status, dropped } = await statusFor(ports, from, input);
     // Noted first: the delivery may wake the parent, whose turn may end before a later note.
     const noted = await noteReport(ports, from, input.sessionID, status).catch(() => undefined);
     try {
         const held = noted?.member && status && status !== "blocked" ? await hold(ports, noted.member, { at: noted.at, status, message: input.message, ...(input.artifacts ? { artifacts: input.artifacts } : {}) }) : undefined;
+        // The parent's standing before the delivery, which may wake it: its first step then shows the report or progress noted.
+        if (noted)
+            await syncStanding(ports, input.sessionID);
         if (held)
             return { status, report: true, held };
-        const text = envelope(from, reportBody(input.message, input.artifacts), status ? { status } : {});
-        const description = `Message from ${from}`;
-        const delivered = await ports.session.synthetic({
-            sessionID: input.sessionID,
-            text,
-            description,
-            metadata: { source: "courier", from, ...(status ? { status } : {}) },
-            delivery: input.queue ? "queue" : "steer",
-        });
-        // Watched now, not when OpenCode's enqueued event is handled: a spawn in the same step must count the child it wakes.
-        await noteSent(ports, { sessionID: input.sessionID, inboxID: delivered.id, text, description }).catch(() => undefined);
-        // A blocked report, once delivered, is the member's latest word: an earlier report held for it would be stale.
-        if (noted?.member && status === "blocked")
-            await unholdForBlocked(groupStore(ports.storage), noted.member).catch(() => undefined);
-        return { messageID: delivered.id, ...(status ? { status } : {}), ...(noted ? { report: noted.report } : {}) };
+        const delivered = await deliver(ports, from, input, status, noted);
+        return { ...delivered, ...(noted ? { report: noted.report } : {}), ...(dropped ? { dropped } : {}) };
     }
     catch (error) {
         await noted?.undo().catch(() => undefined);
+        // The standing as before the note, once the note is taken back.
+        if (noted)
+            await syncStanding(ports, input.sessionID);
         throw error;
     }
 }
+/** Delivers the message, watches it, and takes a held report back after a blocked one; the message id and status delivered. */
+async function deliver(ports, from, input, status, noted) {
+    const text = envelope(from, reportBody(input.message, input.artifacts), status ? { status } : {});
+    const description = `Message from ${from}`;
+    const delivered = await ports.session.synthetic({
+        sessionID: input.sessionID,
+        text,
+        description,
+        metadata: { source: "courier", from, ...(status ? { status } : {}) },
+        delivery: input.queue ? "queue" : "steer",
+    });
+    // Watched now, not when OpenCode's enqueued event is handled: a spawn in the same step must count the child it wakes.
+    await noteSent(ports, { sessionID: input.sessionID, inboxID: delivered.id, text, description }).catch(() => undefined);
+    // A blocked report, once delivered, is the member's latest word: an earlier report held for it would be stale.
+    if (noted?.member && status === "blocked")
+        await unholdForBlocked(groupStore(ports.storage), noted.member).catch(() => undefined);
+    return { messageID: delivered.id, ...(status ? { status } : {}) };
+}
+/**
+ * The message's status, checked, as OpenCode does not check the schema. A status is a report's: on a message to a
+ * session below the sender it means nothing, so it is `dropped`, and the result says so.
+ */
+async function statusFor(ports, from, input) {
+    // Some models send null for an optional field they leave out.
+    const given = input.status ?? undefined;
+    if (given === undefined)
+        return {};
+    if (!isStatus(given))
+        throw new Error(`status must be one of ${STATUSES.join(", ")}, not ${JSON.stringify(given)}.`);
+    return (await isBelow(ports, from, input.sessionID)) ? { dropped: given } : { status: given };
+}
+/** Whether `from` started `to`, directly or through others, by the reverse index; false when the index does not name `to` or cannot be read. */
+async function isBelow(ports, from, to) {
+    const above = await childStore(ports.storage).indexedAncestors(to).catch(() => []);
+    return above.includes(from);
+}
 /**
  * Notes `from`'s message to `to` when `to` started it: as its report when it carries a status, or when an earlier
  * release briefed `from`, else as progress. Returns which, when, how to take the note back, and `from`'s group membership.

package/dist/tree/spawn.d.ts

@@ -5,12 +5,20 @@ export interface SpawnInput {
     readonly agent?: string;
     readonly isolate?: boolean;
     readonly group?: string;
+    /** `provider/model` to run on; left out, the agent's own model, else the caller's. */
+    readonly model?: string;
+    /** The variant of that model, its reasoning effort; left out, the chosen model's own. */
+    readonly variant?: string;
+    /** Whether the child is OpenCode's subagent of the caller; left out, the `nativeChildren` option decides. */
+    readonly native?: boolean;
 }
 /**
  * Creates a child session, hands it the task and returns at once; the child reports back with
  * courier_send. Refused past a limit, whether or not the `context` hook hid the tool.
  */
 export declare function spawn(ports: CourierPorts, parentID: string, input: SpawnInput): Promise<{
+    native?: boolean | undefined;
+    model?: string | undefined;
     uncommitted?: boolean | undefined;
     fromParent?: boolean | undefined;
     groupError?: string | undefined;

package/dist/tree/spawn.js

@@ -1,24 +1,15 @@
 import { describeFailure } from "../kernel/protocol.js";
-import { isGroupName } from "./domain.js";
+import { isGroupName, modelName } from "./domain.js";
 import { joinGroup, leaveGroup } from "./group.js";
 import { admit } from "./limits.js";
+import { chooseModel } from "./model.js";
+import { putEntries, syncStanding } from "./standing.js";
 import { childStore, groupStore } from "./store.js";
-import { childBrief, childBranch } from "./text.js";
+import { childBrief, childBranch, nativeIsolateRefusal, ROLE_KEY, rolePart } from "./text.js";
 function titleOf(task) {
     const line = task.trim().split("\n")[0] ?? "";
     return line.length > 60 ? `${line.slice(0, 57)}...` : line;
 }
-/**
- * The model a child runs on, always passed on so no OpenCode version falls back to its default:
- * the named agent's own, else its parent's.
- */
-async function inheritedModel(ports, parentID, agent) {
-    const parent = await ports.session.get({ sessionID: parentID });
-    if (!agent)
-        return parent.model;
-    const named = await ports.agent.get({ agentID: agent, location: { directory: ports.directory } });
-    return named.data.model ?? parent.model;
-}
 /** Removes a worktree made for a child that was never created; one that cannot be removed stays. */
 async function dropWorktree(ports, directory) {
     try {
@@ -37,16 +28,19 @@ export async function spawn(ports, parentID, input) {
     const group = typeof input.group === "string" ? input.group.trim() || undefined : (input.group ?? undefined);
     if (group !== undefined && !isGroupName(group))
         throw new Error(`group must be a name of 1 to 60 letters, digits, dots, dashes or underscores, not ${JSON.stringify(group)}.`);
+    const native = typeof input.native === "boolean" ? input.native : undefined;
+    if (native && input.isolate)
+        throw new Error(nativeIsolateRefusal());
     const admitted = await admit(ports, parentID);
     try {
-        return await start(ports, parentID, input, admitted, group);
+        return await start(ports, parentID, { ...input, native }, admitted, group);
     }
     finally {
         admitted.release();
     }
 }
 async function start(ports, parentID, input, admitted, group) {
-    const { worktree, handedDown, ...child } = await create(ports, parentID, input);
+    const { worktree, handedDown, model, ...child } = await create(ports, parentID, input);
     admitted.reservation.sessionID = child.sessionID;
     const entry = {
         ...child,
@@ -56,10 +50,17 @@ async function start(ports, parentID, input, admitted, group) {
         reports: "status",
         ...(worktree ? { source: ports.directory, project: ports.projectID } : {}),
         ...(group ? { group } : {}),
+        ...(model ? { model } : {}),
     };
     const { rosterError, groupError } = await enrol(ports, entry, group);
-    ports.roles.delete(parentID);
-    await handOver(ports, entry, admitted.depth, input.task, !rosterError, !rosterError && !groupError);
+    await nameBoth(ports, parentID, entry.sessionID, admitted.depth);
+    try {
+        await handOver(ports, entry, admitted.depth, input.task, !rosterError, !rosterError && !groupError);
+    }
+    finally {
+        // The parent's standing with the child on it, prompted or failed, announced at its next step.
+        await syncStanding(ports, parentID);
+    }
     return {
         sessionID: entry.sessionID,
         directory: entry.directory,
@@ -68,12 +69,16 @@ async function start(ports, parentID, input, admitted, group) {
         ...(groupError ? { groupError } : {}),
         ...(handedDown ? { fromParent: true } : {}),
         ...(handedDown?.uncommitted ? { uncommitted: true } : {}),
+        ...(model ? { model } : {}),
+        ...(entry.native ? { native: true } : {}),
     };
 }
-/** Creates the child's session, in a worktree of its own if asked, which goes again if the session cannot be created. */
+/**
+ * Creates the child's session, in a worktree of its own if asked, which goes again if the session cannot be created.
+ * `model` names the child's model when it is not its parent's, for the roster and the result.
+ */
 async function create(ports, parentID, input) {
-    // A failed lookup must not keep the child from starting; it then runs on OpenCode's default.
-    const model = await inheritedModel(ports, parentID, input.agent).catch(() => undefined);
+    const { model, parent } = await chooseModel(ports, parentID, input, input.agent);
     const handedDown = input.isolate ? await parentWork(ports, parentID) : undefined;
     const worktree = input.isolate
         ? (await ports.worktree.create({ projectID: ports.projectID, ...(handedDown ? { from: handedDown.directory, branch: handedDown.head } : {}) })).directory
@@ -81,7 +86,7 @@ async function create(ports, parentID, input) {
     const base = worktree ? await ports.head(worktree) : undefined;
     const title = input.title ?? titleOf(input.task);
     // OpenCode takes a location or a parentID, never both, so an isolated child cannot be a native one.
-    const native = ports.nativeChildren === true && !worktree;
+    const native = (input.native ?? ports.nativeChildren === true) && !worktree;
     const child = await ports.session
         .create({
         title,
@@ -106,6 +111,7 @@ async function create(ports, parentID, input) {
         handedDown,
         ...(base ? { base } : {}),
         ...(native ? { native: true } : {}),
+        ...(model && (!parent || modelName(model) !== modelName(parent)) ? { model: modelName(model) } : {}),
     };
 }
 /**
@@ -171,3 +177,50 @@ async function join(ports, entry, group) {
         return describeFailure("group", error).message;
     }
 }
+/**
+ * The child's role and the other modules' entries before its prompt, so its first request carries them, and a root's own at
+ * its first spawn, remembered for the `context` hook; a parent that is no root is forgotten there, as its depth may have changed.
+ */
+async function nameBoth(ports, parentID, childID, depth) {
+    const extra = await extraEntries(ports);
+    await nameRole(ports, childID, depth);
+    if (depth < ports.limits.maxDepth)
+        await putEntries(ports, childID, extra);
+    const rootNamed = ports.roles.get(parentID)?.entry === true;
+    const named = depth === 1 && (rootNamed || (await nameRole(ports, parentID, 0)));
+    if (named && !rootNamed)
+        await putEntries(ports, parentID, extra);
+    if (named)
+        ports.roles.set(parentID, { depth: 0, entry: true });
+    else
+        ports.roles.delete(parentID);
+}
+/** The entries the other modules give a spawned session, the memory's lessons; none when they cannot be read, logged. */
+async function extraEntries(ports) {
+    if (!ports.entries || !ports.session.instructions)
+        return [];
+    try {
+        return await ports.entries();
+    }
+    catch (error) {
+        ports.log(`courier_spawn: the entries of the other modules could not be read, so the session starts without them: ${String(error)}`);
+        return [];
+    }
+}
+/**
+ * Writes a session's role part to its `role` entry: a child's system prompt carries it from its first request, a root's
+ * transcript as an update. False on a host without entries, or when the put failed, logged: the `context` hook adds the part.
+ */
+async function nameRole(ports, sessionID, depth) {
+    const entries = ports.session.instructions?.entry;
+    if (!entries)
+        return false;
+    try {
+        await entries.put({ sessionID, key: ROLE_KEY, value: rolePart(depth, ports.limits) });
+        return true;
+    }
+    catch (error) {
+        ports.log(`courier_spawn: the role entry of ${sessionID} could not be written, so its role goes in a system part: ${String(error)}`);
+        return false;
+    }
+}

package/dist/tree/standing.d.ts

@@ -0,0 +1,17 @@
+import type { Entry, ReportNote, RosterStorage, StandingPorts } from "./ports.js";
+import { type ChildState, type StandingRow } from "./text.js";
+/** A child's state from its report notes, as `reportOf` and the silent-turn rule read them. */
+export declare function stateOf(notes: {
+    readonly [K in "prompt" | "settled" | "progress" | "told" | "stopped"]: ReportNote;
+}): ChildState;
+/** The rows of a parent's standing entry: its unexpired children, oldest first, each with its state and group standing. */
+export declare function standingRows(storage: RosterStorage, parentID: string, now: number): Promise<StandingRow[]>;
+/** What `syncStanding` did to the parent's entry. */
+export type Synced = "put" | "unchanged" | "removed" | "absent" | "skipped";
+/**
+ * Writes a parent's `standing` entry once something of it changed: put when its text differs from the entry's, removed when
+ * the parent has no children left; skipped without the keyed entries. A failure is logged, never thrown.
+ */
+export declare function syncStanding(ports: StandingPorts, parentID: string): Promise<Synced>;
+/** Writes `given` entries to a session, each put logged on failure and never thrown: the session gets its task all the same. */
+export declare function putEntries(ports: StandingPorts, sessionID: string, given: ReadonlyArray<Entry>): Promise<void>;