opencode-courier 0.11.0 → 0.12.0

package/README.md

@@ -18,7 +18,7 @@ A narrated tour of the terminal UI: the tree panel, the asks inbox, failing chil
 ## Quickstart
 
 ```bash
-npm install -g @opencode/cli@2.1.3   # OpenCode V2, the version courier is tested on
+npm install -g @opencode/cli@2.1.4   # OpenCode V2, the version courier is tested on
 opencode plugin add opencode-courier
 opencode
 ```
@@ -38,7 +38,8 @@ prompt again.
 OpenCode's own [`subagent` tool](https://opencode.ai/v2/docs/agents) hands back a child's final
 answer. Use it when one result is all you need. Use courier for more:
 
-- **Messages mid-run.** A child reports progress or asks its parent at any time.
+- **Messages mid-run.** A child reports progress or asks its parent at any time, and its parent
+  passes a finding that changes the other parts on to the children it affects.
 - **Waking an idle session.** A message, a schedule or a GitHub webhook starts a new turn.
 - **Parallel edits.** `isolate: true` gives a child its own git worktree and branch to merge.
 - **Asks reach you.** A child's permission requests and questions come to you through the top
@@ -60,10 +61,10 @@ split a task and how to check and merge the parts. Every detail: [the reference]
 ## Install
 
 Requires OpenCode V2: the `opencode` command from `@opencode/cli`. Each release is tested against
-one OpenCode version; this one is tested on **OpenCode 2.1.3** (check with `opencode --version`).
+one OpenCode version; this one is tested on **OpenCode 2.1.4** (check with `opencode --version`).
 
 ```bash
-npm install -g @opencode/cli@2.1.3
+npm install -g @opencode/cli@2.1.4
 opencode plugin add opencode-courier
 ```
 
@@ -76,13 +77,13 @@ name, without a version: OpenCode offers updates only for an entry without an ex
 <!-- compat-table:start rows=3: generated by script/compat-table.ts from the release tags -->
 | opencode-courier | OpenCode V2 (`opencode` and `@opencode/plugin`) |
 |---|---|
+| 0.11.1, 0.12.0 | 2.1.4 |
 | 0.11.0 | 2.1.3 |
 | 0.10.2, 0.10.3 | 2.1.2 |
-| 0.10.1 | 2.1.0 |
 <!-- compat-table:end -->
 
 Every release: [the full table](docs/reference.md#the-opencode-version). The server part loads on
-any V2 host from 2.0.4 on. The terminal part is tested on OpenCode 2.1.3 only.
+any V2 host from 2.0.4 on. The terminal part is tested on OpenCode 2.1.4 only.
 
 ## Options
 
@@ -97,11 +98,11 @@ Set the server options on the plugin's entry in the **global** config,
 
 | Option | Default | |
 |---|---|---|
-| `maxDepth` | `3` | How deep a tree goes. Your session is depth 0. A session at `maxDepth` cannot start sessions. |
+| `maxDepth` | `5` | How deep a tree goes. Your session is depth 0. A session at `maxDepth` cannot start sessions. |
 | `maxChildren` | `5` | Live children one session may have. |
-| `maxTotal` | `20` | Live spawned sessions in one tree. |
+| `maxTotal` | `30` | Live spawned sessions in one tree. |
 | `memory` | `true` | Keep a record of each session tree for later orchestrators ([memory](docs/reference.md#memory)). |
-| `nativeChildren` | `false` | Create non-isolated children as OpenCode subagents ([native children](docs/reference.md#native-child-sessions)). |
+| `nativeChildren` | `false` | The default for a spawn that does not set `native`: `true` creates non-isolated children as OpenCode subagents ([native children](docs/reference.md#native-child-sessions)). |
 | `webhook` | off | Start the webhook receiver ([webhooks](docs/reference.md#webhooks)). |
 
 The terminal part reads its options only from `~/.config/opencode/cli.json`, in the same entry
@@ -111,7 +112,7 @@ form. Its one option, `"animations": false`, keeps the tree panel still.
 
 | Tool | Does |
 |---|---|
-| `courier_spawn` | Starts a child session with a task and returns at once. `isolate`, `group`, `agent`, `title`. |
+| `courier_spawn` | Starts a child session with a task and returns at once. `isolate`, `group`, `agent`, `model`, `variant`, `native`, `title`. |
 | `courier_send` | Messages a session, waking it if idle. With a `status`, it is a child's report. |
 | `courier_status` / `courier_children` / `courier_tree` | One look at a session, at the sessions it started, or at its whole tree. |
 | `courier_stop` | Stops a session below you and everything under it. |
@@ -143,6 +144,9 @@ More: [in the terminal](docs/reference.md#in-the-terminal).
 - Choose a web search provider before children search, or the first one shows you a form.
 - Use `isolate: true` when children edit files in parallel. The worktree starts from the last
   commit, so keep providers in the global config or commit `opencode.json`.
+- To steer a running tree, open a child from the `/courier tree` panel, tell it what you found and ask
+  it to pass that to its parent, or message the parent directly
+  ([details](docs/reference.md#steering-a-running-tree)).
 - For a long-running child, schedule a `courier_later` check-in, in case the server stops.
 
 ## Contributing

package/dist/index.js

@@ -91,7 +91,16 @@ export const courier = () => Plugin.define({
             directory: ctx.location.directory,
             projectID: ctx.location.project.id,
             now: Date.now,
-            windows: async () => (await ctx.model.list()).data.map((model) => ({ providerID: model.providerID, id: model.id, context: model.limit.context })),
+            models: async () => (await ctx.model.list()).data.map((model) => ({
+                providerID: model.providerID,
+                id: model.id,
+                context: model.limit.context,
+                variants: model.variants.map((variant) => variant.id),
+            })),
+            defaultModel: async () => {
+                const { data } = await ctx.model.default();
+                return data ? { providerID: data.providerID, id: data.id } : undefined;
+            },
             head: headOf,
             dirty: dirtyOf,
             pending: async (sessionID) => {
@@ -142,8 +151,8 @@ export const courier = () => Plugin.define({
         const swept = sweepRecords(ctx.storage, Date.now()).catch((error) => log(`courier memory sweep: ${String(error)}`));
         // The windows the memory reads each part's context use by; a tree whose top runs in a location with memory off is not recorded.
         const windowed = ports
-            .windows()
-            .then((windows) => windows.forEach((window) => memoryState.windows.set(`${window.providerID}/${window.id}`, window)))
+            .models()
+            .then((models) => models.forEach(({ providerID, id, context }) => memoryState.windows.set(`${providerID}/${id}`, { providerID, id, context })))
             .catch((error) => log(`courier memory: cannot list the models' context windows: ${String(error)}`));
         if (!memory)
             memoryState.off.add(ctx.location.directory);

package/dist/memory/tools.js

@@ -20,7 +20,8 @@ export function addMemoryTools(tools, ports) {
     tools.add({
         name: RECALL_TOOL,
         options: { codemode: false },
-        description: "Look once at what earlier session trees in this project did, before you decide whether and how to split a task: " +
+        description: "Look once at what earlier session trees in this project did, at the root, before you decide whether and how to split " +
+            "a task; a session another session started reads none, since the root weighed the records before it split. The listing: " +
             "one line per tree, those the person pinned first and then newest first, with how its top split the task, how each part went (its status, how long it ran, " +
             "what it cost, how full its context got) and whether a spawn was refused; with sessionID, one tree's record in full. " +
             "Records hold no report bodies or files. Call it once at the start, not in a loop, and not to check on sessions you " +

package/dist/skill.d.ts

@@ -3,7 +3,7 @@ import type { Plugin } from "@opencode/plugin";
 export declare const SKILL_DESCRIPTION: string;
 /**
  * The skill's text; it names no limits, which the role part and the brief give for the session's own tree.
- * Steps 3, 4 and 6 repeat the brief's split rule on purpose: the root has no brief, so only the skill gives it.
+ * Steps 1, 3, 4 and 6 repeat the brief's split rule on purpose: the root has no brief, so only the skill gives it.
  */
 export declare const SKILL_CONTENT: string;
 /** The editor OpenCode hands a skill transform. */

package/dist/skill.js

@@ -1,60 +1,115 @@
 import { ONE_PART_LINE, SKILL_ID, SPLIT_LINE } from "./kernel/protocol.js";
 // The courier-orchestrate skill: the playbook a session loads with its skill tool.
 /** Why a model loads the skill, listed with every session's available skills. */
-export const SKILL_DESCRIPTION = "Load at the start of any implementation task that may have independent parts, or when a session started you, to " +
-    "decide whether to split it across OpenCode sessions with courier_spawn and state the decision, and how: plan the " +
-    "parts, start them, end your turn, read the reports, verify the work, integrate it and report upward, and what to do " +
-    "when a part goes wrong.";
+export const SKILL_DESCRIPTION = "Load at the start of any implementation task that may have independent parts, or when a session started you, if " +
+    "courier_spawn is among your tools: how to decide whether to split it across OpenCode sessions and state the decision, " +
+    "plan and start the parts, end your turn, verify and integrate the reports, report upward, and handle a part gone wrong.";
 /**
  * The skill's text; it names no limits, which the role part and the brief give for the session's own tree.
- * Steps 3, 4 and 6 repeat the brief's split rule on purpose: the root has no brief, so only the skill gives it.
+ * Steps 1, 3, 4 and 6 repeat the brief's split rule on purpose: the root has no brief, so only the skill gives it.
  */
 export const SKILL_CONTENT = [
     "How to split a task across OpenCode sessions with opencode-courier, and bring the results back up. Your brief, or the " +
-        "opencode-courier role line in your system prompt, names your depth in the session tree and its limits.",
+        "opencode-courier role line in your system prompt, names your depth in the session tree and its limits. If " +
+        "courier_spawn is not among your tools, you cannot split: do the task yourself, and report upward as your brief says " +
+        "if a session started you.",
     "",
-    "1. Decide: split or do. First call courier_recall once: it lists how earlier trees in this project were split and how " +
-        "each part went, so weigh that; one call, before you decide, never in a loop. Split when the task has 2 or more " +
-        "independent, substantial parts touching separate files or areas; do it yourself when it is small, sequential or " +
-        "tightly coupled. What you read and write yourself stays in your context for every later turn, so keep the deciding, " +
-        "checking and integrating, and hand off the long reading and writing. Only the root, the session nobody started, may " +
-        "start exactly one session for the whole task, and only when the task is heavy (long reading, many edits, long runs) " +
-        "and its own context is worth keeping: it still verifies and integrates that session's report itself (steps 5 to 7), " +
-        "and does a small task itself. Every other session never starts exactly one session for the whole task: it only adds " +
-        "a hop, and a chain of single hops uses up the tree's depth. A part that is itself big and divisible is split again by " +
-        "the session that gets it; at the deepest level a session does its part itself. " +
-        `Say which in one line of your reply, before you start, so that a reasoned decision to do it yourself can be told ` +
+    "1. Decide: split or do.",
+    "   - At the root, first call courier_recall once: it lists how earlier trees in this project were split and how each " +
+        "part went, so weigh that; one call, before you decide, never in a loop. Below the root, read none: the records " +
+        "describe whole trees, and the root weighed them before it split.",
+    "   - Split when the task has 2 or more independent, substantial parts touching separate files or areas; do it yourself " +
+        "when it is small, sequential or tightly coupled. A part that is itself big and divisible is split again by the " +
+        "session that gets it. Several whole jobs in one prompt, such as 4 tickets, are that many parts: each session runs " +
+        "this playbook for its job, stages, review and all, so the tree below you repeats its shape once per job.",
+    "   - What you read and write yourself stays in your context for every later turn, so keep the deciding, checking and " +
+        "integrating, and hand off the long reading and writing.",
+    "   - Only the root, the session nobody started, may start exactly one session for the whole task, and only when the " +
+        "task is heavy (long reading, many edits, long runs) and its own context is worth keeping. It still verifies and " +
+        "integrates that session's report itself (steps 5 to 7), and does a small task itself.",
+    "   - Every other session never starts exactly one session for the whole task: it only adds a hop, and a chain of single " +
+        "hops uses up the tree's depth.",
+    "   - Say which in one line of your reply, before you start, so that a reasoned decision to do it yourself can be told " +
         `from one never made: ${SPLIT_LINE}; the root has a third form, ${ONE_PART_LINE}.`,
-    "   When the core is coupled: an implementation task with one tightly coupled core usually still has independent parts: " +
-        "finding out what the change needs (a session with isolate: false reads the code, or a library's or a host's source, " +
-        "tries things and reports what it found), its e2e scenario, its documentation, sometimes a second test file, and a " +
-        "review of the core by a session with fresh context, which reads the committed diff against the task and the " +
-        "repository's rules and reports its findings (isolate: false, it edits nothing). Weigh each of them. When the other " +
-        "parts depend on names and texts the core fixes, split in stages: the core first, yourself when it is small or by one " +
-        "session when it is big, merged and committed before the rest start; then, if 2 or more parts remain, one session per " +
-        "remaining part, in one group. A staged core is one part of the task, not the whole task, so the rule against starting exactly one " +
-        "session for the whole task does not apply to it when 2 or more parts follow it.",
+    "   Parts a task can have, besides its edits, each one session where it is worth a context of its own:",
+    "   - a scout: a session with isolate: false reads the code, or a library's or a host's source, tries things and " +
+        "reports what it found, before you plan;",
+    "   - the implementers, isolate: true where two edit at once, each with its checks and what to report;",
+    "   - its e2e scenario, its documentation, sometimes a second test file;",
+    "   - a review stage, after the merge, when the changes are done and it is to see the whole: one review session with " +
+        "fresh context, which makes no fixes of its own. Put in its task the diff to read: when you are isolated, your own " +
+        "courier/<session> branch, committed first, against the commit your worktree started from; else your checkout's HEAD, " +
+        "with the merges committed, against the commit you started from, which you note before your first spawn. It may hand the " +
+        "reading to 2 or more reviewers (one group, each reads that diff from one angle and reports its findings), then " +
+        "starts one verifier with their reports: a fresh session that checks each finding against the diff, drops what " +
+        "does not hold, and starts one implementor for what holds, or 2 or more when the fixes are independent, isolate: " +
+        "true each then, merging their branches after (step 7); an implementor fixes what it should and refuses, with the " +
+        "reason, what it should not. Where the code is: when you work in the project's checkout, the review session, the " +
+        "verifier and a lone implementor go without isolate, and it commits in place; when you are isolated, start each of " +
+        "them with isolate: true, so that each worktree starts from the one above, and each merges the branch reported to " +
+        "it before it reports (step 7); reviewers only read and need no worktree. Each reports to the one that started " +
+        "it; the review session reports to " +
+        "you what was found, what held, what was fixed (the commits) and what was refused and why. It does not replace " +
+        "step 6: running the checks on the fixed tree stays yours, and so does settling a refusal you disagree with. Go " +
+        "through steps 3 to 7 once more for the stage, and do its work yourself when the levels below you are too few for " +
+        "it. One session for one stage, after a stage of 2 or more parts or one you did yourself, is a part of the task, " +
+        "like a staged core, not the whole; a reviewer alone with nothing before it is not a stage.",
+    "   When the core is coupled: an implementation task with one tightly coupled core usually still has parts from that " +
+        "list; weigh each of them. When the other parts depend on names and texts the core fixes, split in stages: the core " +
+        "first, yourself when it is small or by one session when it is big, merged and committed before the rest start; then, " +
+        "if 2 or more parts remain, one session per remaining part, in one group. A staged core is one part of the task, not " +
+        "the whole task, so the rule against starting exactly one session for the whole task does not apply to it when 2 or " +
+        "more parts follow it.",
     "2. Plan the parts so that no two edit the same files. Write each task so the session can do it without you: what to " +
         "produce and where, how to check it, what to report. Say if it may split its part further, and to run its checks " +
-        "through the project's scripts (step 6): each permission request of a session below you wakes you and waits on the person.",
+        "through the project's scripts (step 6): each permission request of a session below you wakes you and waits on the person. " +
+        "Name the skills it should load for its part, from those listed to you: it sees the same list, not your choice; one " +
+        "permission rule for skill covers their loads, as one covers the checks. Say in the task when the part is a whole job " +
+        "that delivers itself (step 7), since an isolated session's brief otherwise says its branch is for you to merge.",
     "3. Start them: one courier_spawn per part that runs at once, all with the same group name, so you are woken once with every report; " +
         "isolate: true for each part that edits files in parallel with another (commit your own work first if you are isolated " +
-        "yourself). For long work, courier_later a check-in for yourself, and courier_cancel it when the reports arrive.",
+        "yourself). When each part runs a review stage of its own, count 6 live sessions per part against maxTotal (a part, " +
+        "its review session and its reviewers are live together at the peak): start the parts that fit in one group, and the " +
+        "rest in a group of their own once the first group has reported. A job that depends on another starts after that one " +
+        "is done, as a stage: merged into your checkout, or, when it was delivered instead (step 7), started with isolate: " +
+        "true and told the delivering session's courier/<session> branch, from its report, to merge into its worktree first. " +
+        "Leave model and variant unset, so a part runs on your own model, unless the part plainly calls for another: a " +
+        "cheaper model or a lower variant for a small, well-specified part (a rename, a lookup), a stronger model or a higher " +
+        "variant for a design question or a hard bug. " +
+        "native: true for a part nobody needs to open on its own: it reads, checks or looks something up, reports once and is " +
+        "done; leave it off for a part the person may want to open, or that should outlive you. " +
+        "For long work, courier_later a check-in for yourself, and courier_cancel it when the reports arrive.",
     "4. End your turn: reply without calling more tools. Do not poll with courier_status, courier_children, courier_tree or " +
         "sleep. The group's reports, a blocked report, a question, a permission request, a failed turn or a silent end each start " +
-        "a new turn for you.",
+        "a new turn for you. So does a session's message without a status, and one from the person or from the session that " +
+        "started you.",
+    "   Answering from below: follow the notice. For a permission request, propose once with courier_answer, or reject with " +
+        "the reason when the person has told you to refuse it or it plainly goes against what they asked; the person decides, " +
+        "in OpenCode's prompt in your session. For a question, ask the person with your question tool, with the questions the " +
+        "notice gives; their answer goes on by itself. When the notice says OpenCode already shows it to the person, call " +
+        "nothing unless they give you their answer. Never answer for them.",
+    "   Passing a message on: when it changes what other parts need (an assumption of the split that is wrong, a shared file " +
+        "or API that behaves otherwise, a decision of the person's), pass it on at once with courier_send, only to the sessions " +
+        "it affects, before they go further, then end your turn again; if it breaks the split, courier_stop the parts it breaks " +
+        "and plan them again, or send them a corrected task. If a session started you and its other parts need it too, send it " +
+        "up to that session as well, without a status. Progress that changes nothing for the others goes to no one.",
     "5. Read each report by its status and its artifacts (branch, commits, files, checks). done: verify it. partial: what is " +
         "left and why; have the session finish it with a courier_send, or do it yourself. blocked: make the decision it asks for " +
         "and send it with courier_send; if only the person can make it, ask them with your question tool and pass the answer on. " +
-        "failed: read the error; message the session to try again, start a replacement, or carry on without it.",
-    "6. Verify first-hand: open the files, run the checks. Never hand the checking to another session: a review session's " +
-        "findings are a report to act on, and running the checks is still yours. Run checks through " +
+        "failed: read the error; message the session to try again, start a replacement, or carry on without it. A review " +
+        "stage's report lists what was found, held, fixed and refused: read the refusals, fix or settle yourself any you " +
+        "disagree with, and run the checks on the fixed tree.",
+    "6. Verify first-hand: open the files, run the checks. Never hand the checking to another session: a review stage " +
+        "verifies and fixes below you, and running the checks on what it changed is still yours. Run checks through " +
         "the project's scripts (bun run <script>, npm run <script>), not ./node_modules/.bin/<tool>, so that one permission " +
         "rule covers them: your own permission prompts are relayed nowhere, and each one stalls the whole tree.",
     "7. Integrate: merge each reported branch into your own checkout (git merge courier/<session>), resolve conflicts " +
-        "yourself, run the checks once more, then courier_cleanup the isolated sessions you are done with.",
+        "yourself, run the checks once more, then courier_cleanup the isolated sessions you are done with. When the parts are " +
+        "whole jobs with a deliverable each (a ticket with its own branch or pull request), the session delivers it and " +
+        "reports the link in its message, still naming its courier/<session> branch when it is isolated; you verify each " +
+        "delivery and merge nothing of it into your checkout.",
     "8. Report upward if a session started you: one courier_send to it, with one status for the whole (done only when every " +
-        "part is verified and integrated; partial, blocked or failed otherwise) and the artifacts. At the top, before you reply " +
+        "part is verified and integrated, or verified and delivered; partial, blocked or failed otherwise) and the artifacts. At the top, before you reply " +
         "to the person: if there is something the next tree in this project should know about running a tree like this one (how " +
         "it was split, what a part got wrong and what caught it, what a brief should have said, what the person decided), one " +
         "courier_note with that one line; none when there is nothing. Name the job it comes from and the reason, so that a " +

package/dist/tree/domain.d.ts

@@ -17,7 +17,7 @@ export declare function readLimits(options: unknown): {
     limits: Limits;
     problems: string[];
 };
-/** The `nativeChildren` option: whether a child started without isolate gets OpenCode's own `parentID`; off unless `true`. */
+/** The `nativeChildren` option: whether a child started without isolate or `native` gets OpenCode's own `parentID`; off unless `true`. */
 export declare function readNativeChildren(options: unknown): {
     nativeChildren: boolean;
     problems: string[];
@@ -91,9 +91,27 @@ export interface RosterEntry {
     readonly reports?: "status";
     /** The join group courier_spawn put it in, whose release holds its report; absent for a child in none. */
     readonly group?: string;
-    /** Created with OpenCode's own `parentID` (the `nativeChildren` option), so OpenCode shows its asks in its parent's view. */
+    /** Created with OpenCode's own `parentID` (courier_spawn's `native`, else the `nativeChildren` option), so OpenCode shows its asks in its parent's view. */
     readonly native?: true;
+    /** The model it was started on, as `modelName` writes it, when that is not the model its parent was on. */
+    readonly model?: string;
 }
+/** How a child was started, as courier_children and the panel show it: isolated, native when it is, and its model when not its parent's. */
+export declare function startedAs(entry: RosterEntry): {
+    model?: string | undefined;
+    native?: true | undefined;
+    isolated: boolean;
+};
+/** A model as a session names it: its provider, its id, and its variant, which `"default"` and none both leave to the provider. */
+export interface ModelRef {
+    readonly providerID: string;
+    readonly id: string;
+    readonly variant?: string;
+}
+/** `provider/model` as `courier_spawn` takes it: one slash, nothing empty on either side. */
+export declare function parseModelName(text: string): Pick<ModelRef, "providerID" | "id"> | undefined;
+/** A model as the roster, the panel and the results name it: `provider/model`, with `#variant` for a variant that is not the default. */
+export declare function modelName(model: ModelRef): string;
 /** `lineage` over roster entries already read. */
 export declare function lineageIn(entries: ReadonlyArray<RosterEntry>, sessionID: string): RosterEntry[];
 /** Roster entries by their session, for `lineageBy`. */

package/dist/tree/domain.js

@@ -1,5 +1,5 @@
 import { millis, obj } from "../platform/json.js";
-export const DEFAULT_LIMITS = { maxDepth: 3, maxChildren: 5, maxTotal: 20 };
+export const DEFAULT_LIMITS = { maxDepth: 5, maxChildren: 5, maxTotal: 30 };
 /** The limits in the plugin's options; one that is not a positive integer keeps its default and is named in `problems`. */
 export function readLimits(options) {
     const given = obj(options);
@@ -16,7 +16,7 @@ export function readLimits(options) {
     const limits = { maxDepth: read("maxDepth"), maxChildren: read("maxChildren"), maxTotal: read("maxTotal") };
     return { limits, problems };
 }
-/** The `nativeChildren` option: whether a child started without isolate gets OpenCode's own `parentID`; off unless `true`. */
+/** The `nativeChildren` option: whether a child started without isolate or `native` gets OpenCode's own `parentID`; off unless `true`. */
 export function readNativeChildren(options) {
     const value = obj(options).nativeChildren;
     if (value === undefined || typeof value === "boolean")
@@ -70,6 +70,22 @@ export function cut(nodes, max) {
     }
     return { kept: nodes.filter((node) => kept.has(node.sessionID)), leftOut: nodes.length - kept.size };
 }
+/** How a child was started, as courier_children and the panel show it: isolated, native when it is, and its model when not its parent's. */
+export function startedAs(entry) {
+    return { isolated: entry.isolated, ...(entry.native ? { native: true } : {}), ...(entry.model ? { model: entry.model } : {}) };
+}
+/** `provider/model` as `courier_spawn` takes it: one slash, nothing empty on either side. */
+export function parseModelName(text) {
+    const slash = text.indexOf("/");
+    if (slash <= 0 || slash === text.length - 1)
+        return undefined;
+    return { providerID: text.slice(0, slash), id: text.slice(slash + 1) };
+}
+/** A model as the roster, the panel and the results name it: `provider/model`, with `#variant` for a variant that is not the default. */
+export function modelName(model) {
+    const variant = model.variant && model.variant !== "default" ? `#${model.variant}` : "";
+    return `${model.providerID}/${model.id}${variant}`;
+}
 /** `lineage` over roster entries already read. */
 export function lineageIn(entries, sessionID) {
     return lineageBy(bySession(entries), sessionID);

package/dist/tree/model.d.ts

@@ -0,0 +1,18 @@
+import { type ModelRef } from "./domain.js";
+import type { CourierPorts } from "./ports.js";
+/** What courier_spawn says of the model: `provider/model`, and the variant of whichever model is chosen. */
+export interface ModelChoice {
+    readonly model?: string;
+    readonly variant?: string;
+}
+/**
+ * The model a child runs on: the `model` named, else the agent's, else the one its parent runs on, with the `variant`
+ * named; `parent` is the parent's own, for the roster to tell a child on another one.
+ */
+export declare function chooseModel(ports: CourierPorts, parentID: string, choice: ModelChoice, agent: string | undefined): Promise<{
+    model: undefined;
+    parent: ModelRef | undefined;
+} | {
+    model: ModelRef;
+    parent: ModelRef | undefined;
+}>;

package/dist/tree/model.js

@@ -0,0 +1,65 @@
+import { modelName, parseModelName } from "./domain.js";
+import { modelFormatRefusal, unknownModelRefusal, unknownVariantRefusal, variantWithoutModelRefusal } from "./text.js";
+/**
+ * The model a child runs on: the `model` named, else the agent's, else the one its parent runs on, with the `variant`
+ * named; `parent` is the parent's own, for the roster to tell a child on another one.
+ */
+export async function chooseModel(ports, parentID, choice, agent) {
+    // Some models send null, or an empty string, for an optional field they leave out.
+    const named = trimmed(choice.model);
+    const variant = trimmed(choice.variant);
+    const own = named === undefined ? undefined : parseModelName(named);
+    if (named !== undefined && !own)
+        throw new Error(modelFormatRefusal(named));
+    const parent = await parentModel(ports, parentID);
+    // An agent that cannot be looked up may name a model of its own, which OpenCode applies when none is passed.
+    const inherited = own ? undefined : await inheritedModel(ports, parent, agent).catch(() => undefined);
+    const base = own ?? inherited;
+    if (!base) {
+        if (variant !== undefined)
+            throw new Error(variantWithoutModelRefusal(variant, agent));
+        return { model: undefined, parent };
+    }
+    const chosen = variant ?? base.variant;
+    const model = { providerID: base.providerID, id: base.id, ...(chosen !== undefined ? { variant: chosen } : {}) };
+    if (own || variant !== undefined)
+        await check(ports, model, own !== undefined);
+    return { model, parent };
+}
+/**
+ * The model the parent runs on: its session's, else OpenCode's default. A failed lookup must not keep a child on no
+ * particular model from starting, so it reads as none, and the child then runs on OpenCode's default.
+ */
+async function parentModel(ports, parentID) {
+    const session = await ports.session.get({ sessionID: parentID }).catch(() => undefined);
+    if (!session)
+        return undefined;
+    return session.model ?? (await ports.defaultModel().catch(() => undefined));
+}
+/** The named agent's model, if it names one; else the parent's. */
+async function inheritedModel(ports, parent, agent) {
+    if (!agent)
+        return parent;
+    const named = await ports.agent.get({ agentID: agent, location: { directory: ports.directory } });
+    return named.data.model ?? parent;
+}
+/**
+ * Refuses a model OpenCode does not list, or a variant its model has not; `"default"` is every model's. A listing that
+ * cannot be read checks nothing: OpenCode refuses what it does not know at the child's first turn, which is reported.
+ */
+async function check(ports, model, named) {
+    let known;
+    try {
+        known = await ports.models();
+    }
+    catch (error) {
+        ports.log(`courier_spawn: cannot list the models to check ${modelName(model)} against: ${String(error)}`);
+        return;
+    }
+    const found = known.find((item) => item.providerID === model.providerID && item.id === model.id);
+    if (!found)
+        throw new Error(unknownModelRefusal(model, known, named));
+    if (model.variant !== undefined && model.variant !== "default" && !found.variants.includes(model.variant))
+        throw new Error(unknownVariantRefusal(model, found.variants));
+}
+const trimmed = (value) => (typeof value === "string" ? value.trim() || undefined : (value ?? undefined));

package/dist/tree/panel.js

@@ -1,3 +1,4 @@
+import { startedAs } from "./domain.js";
 import { lastStatus, stoppedSincePrompt } from "./report.js";
 import { standingIn } from "./status.js";
 import { childStore } from "./store.js";
@@ -80,7 +81,7 @@ async function row(ports, windows, { entry, depth, info, running, endedAt, pendi
         ...(stopped ? { stopped } : {}),
         ...reportRow(report, status),
         ...(entry.group && standing ? { group: { name: entry.group, standing } } : {}),
-        isolated: entry.isolated,
+        ...startedAs(entry),
         created: info?.time.created ?? entry.createdAt,
         ...(info && !running && endedAt !== undefined ? { idle: endedAt } : {}),
         ...(info ? { cost: info.cost } : {}),
@@ -96,7 +97,7 @@ async function row(ports, windows, { entry, depth, info, running, endedAt, pendi
 export async function panel(ports, rootID) {
     const { kept, leftOut } = await readTree(ports, rootID);
     const stalled = await stalledAmong(ports, [rootID, ...kept.map((node) => node.entry.sessionID)]);
-    const windows = await ports.windows().catch(() => []);
+    const windows = await ports.models().catch(() => []);
     const rows = await Promise.all(kept.map((node) => row(ports, windows, node, stalled.get(node.entry.sessionID))));
     const own = stalled.get(rootID);
     return { rows, ...(leftOut ? { truncated: leftOut } : {}), ...(own !== undefined ? { stalled: own } : {}) };

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. */
@@ -168,10 +168,12 @@ 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. */
@@ -180,12 +182,16 @@ export interface CourierPorts {
     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;

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/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,14 @@
 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 { childStore, groupStore } from "./store.js";
-import { childBrief, childBranch } from "./text.js";
+import { childBrief, childBranch, nativeIsolateRefusal } 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: its parent's, so it does not fall back to OpenCode's default, which
- * the parent may have been moved off for a reason. An agent that names its own model keeps it.
- */
-async function inheritedModel(ports, parentID, agent) {
-    const parent = await ports.session.get({ sessionID: parentID });
-    if (!parent.model || !agent)
-        return parent.model;
-    const named = await ports.agent.get({ agentID: agent, location: { directory: ports.directory } });
-    return named.data.model ? undefined : 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 +27,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,6 +49,7 @@ 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);
@@ -68,12 +62,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 +79,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 +104,7 @@ async function create(ports, parentID, input) {
         handedDown,
         ...(base ? { base } : {}),
         ...(native ? { native: true } : {}),
+        ...(model && (!parent || modelName(model) !== modelName(parent)) ? { model: modelName(model) } : {}),
     };
 }
 /**

package/dist/tree/status.d.ts

@@ -30,9 +30,11 @@ export declare function listChildren(ports: CourierPorts, parentID: string): Pro
         name: string;
         report: "failed" | "interrupted" | "out" | "unknown" | "deleted" | "dropped" | "held" | "released";
     };
-    directory: string;
-    isolated: boolean;
     created: number;
+    model?: string | undefined;
+    native?: true | undefined;
+    isolated: boolean;
+    directory: string;
     sessionID?: string | undefined;
     title?: string | undefined;
     parentID?: string | undefined;
@@ -44,9 +46,11 @@ export declare function listChildren(ports: CourierPorts, parentID: string): Pro
     pending?: readonly import("./ports.js").Pending[] | undefined;
 } | {
     group?: undefined;
-    directory: string;
-    isolated: boolean;
     created: number;
+    model?: string | undefined;
+    native?: true | undefined;
+    isolated: boolean;
+    directory: string;
     sessionID?: string | undefined;
     title?: string | undefined;
     parentID?: string | undefined;
@@ -62,17 +66,21 @@ export declare function listChildren(ports: CourierPorts, parentID: string): Pro
         name: string;
         report: "failed" | "interrupted" | "out" | "unknown" | "deleted" | "dropped" | "held" | "released";
     };
-    directory: string;
-    isolated: boolean;
     created: number;
+    model?: string | undefined;
+    native?: true | undefined;
+    isolated: boolean;
+    directory: string;
     sessionID: string;
     title: string;
 } | {
     error: string;
     group?: undefined;
-    directory: string;
-    isolated: boolean;
     created: number;
+    model?: string | undefined;
+    native?: true | undefined;
+    isolated: boolean;
+    directory: string;
     sessionID: string;
     title: string;
 })[]>;
@@ -82,9 +90,11 @@ export declare function described(ports: CourierPorts, entry: RosterEntry): Prom
         name: string;
         report: "failed" | "interrupted" | "out" | "unknown" | "deleted" | "dropped" | "held" | "released";
     };
-    directory: string;
-    isolated: boolean;
     created: number;
+    model?: string | undefined;
+    native?: true | undefined;
+    isolated: boolean;
+    directory: string;
     sessionID?: string | undefined;
     title?: string | undefined;
     parentID?: string | undefined;
@@ -96,9 +106,11 @@ export declare function described(ports: CourierPorts, entry: RosterEntry): Prom
     pending?: readonly import("./ports.js").Pending[] | undefined;
 } | {
     group?: undefined;
-    directory: string;
-    isolated: boolean;
     created: number;
+    model?: string | undefined;
+    native?: true | undefined;
+    isolated: boolean;
+    directory: string;
     sessionID?: string | undefined;
     title?: string | undefined;
     parentID?: string | undefined;
@@ -114,17 +126,21 @@ export declare function described(ports: CourierPorts, entry: RosterEntry): Prom
         name: string;
         report: "failed" | "interrupted" | "out" | "unknown" | "deleted" | "dropped" | "held" | "released";
     };
-    directory: string;
-    isolated: boolean;
     created: number;
+    model?: string | undefined;
+    native?: true | undefined;
+    isolated: boolean;
+    directory: string;
     sessionID: string;
     title: string;
 } | {
     error: string;
     group?: undefined;
-    directory: string;
-    isolated: boolean;
     created: number;
+    model?: string | undefined;
+    native?: true | undefined;
+    isolated: boolean;
+    directory: string;
     sessionID: string;
     title: string;
 }>;

package/dist/tree/status.js

@@ -1,5 +1,5 @@
 import { describeFailure } from "../kernel/protocol.js";
-import { standingOf } from "./domain.js";
+import { standingOf, startedAs } from "./domain.js";
 import { current } from "./roster.js";
 import { groupStore } from "./store.js";
 /** A one-off look at a session, for check-ins; not meant to be called in a loop. */
@@ -40,7 +40,7 @@ export async function listChildren(ports, parentID) {
 /** One roster entry as courier_children shows it: what courier_status reports with its directory and group standing, or the error it gave. */
 export async function described(ports, entry) {
     const group = entry.group ? { group: { name: entry.group, report: await standingIn(ports, entry, entry.group) } } : {};
-    const roster = { directory: entry.directory, isolated: entry.isolated, created: entry.createdAt, ...group };
+    const roster = { directory: entry.directory, ...startedAs(entry), created: entry.createdAt, ...group };
     try {
         return { ...(await status(ports, { sessionID: entry.sessionID })), ...roster };
     }

package/dist/tree/subtree.d.ts

@@ -65,9 +65,11 @@ export declare function tree(ports: CourierPorts, rootID: string): Promise<{
             name: string;
             report: "failed" | "interrupted" | "out" | "unknown" | "deleted" | "dropped" | "held" | "released";
         };
-        directory: string;
-        isolated: boolean;
         created: number;
+        model?: string | undefined;
+        native?: true | undefined;
+        isolated: boolean;
+        directory: string;
         sessionID?: string | undefined;
         title?: string | undefined;
         outcome?: "failed" | "interrupted" | "succeeded" | undefined;
@@ -86,9 +88,11 @@ export declare function tree(ports: CourierPorts, rootID: string): Promise<{
         parentID: string;
         depth: number;
         group?: undefined;
-        directory: string;
-        isolated: boolean;
         created: number;
+        model?: string | undefined;
+        native?: true | undefined;
+        isolated: boolean;
+        directory: string;
         sessionID?: string | undefined;
         title?: string | undefined;
         outcome?: "failed" | "interrupted" | "succeeded" | undefined;
@@ -111,9 +115,11 @@ export declare function tree(ports: CourierPorts, rootID: string): Promise<{
             name: string;
             report: "failed" | "interrupted" | "out" | "unknown" | "deleted" | "dropped" | "held" | "released";
         };
-        directory: string;
-        isolated: boolean;
         created: number;
+        model?: string | undefined;
+        native?: true | undefined;
+        isolated: boolean;
+        directory: string;
         sessionID: string;
         title: string;
     } | {
@@ -127,9 +133,11 @@ export declare function tree(ports: CourierPorts, rootID: string): Promise<{
         depth: number;
         error: string;
         group?: undefined;
-        directory: string;
-        isolated: boolean;
         created: number;
+        model?: string | undefined;
+        native?: true | undefined;
+        isolated: boolean;
+        directory: string;
         sessionID: string;
         title: string;
     })[];

package/dist/tree/text.d.ts

@@ -1,3 +1,4 @@
+import { type ModelRef } from "./domain.js";
 import type { Artifacts, CleanupResult, ExecutionError, HeldReport, LeftMember, Limits, Sent } from "./ports.js";
 /** The branch an isolated child commits its work on, and names in the `branch` of its report. */
 export declare const childBranch: (sessionID: string) => string;
@@ -13,11 +14,19 @@ export declare function rolePart(depth: number | null, limits: Limits): string;
 export declare const depthRefusal: (depth: number, maxDepth: number) => string;
 export declare const childrenRefusal: (running: number, maxChildren: number) => string;
 export declare const totalRefusal: (running: number, maxTotal: number) => string;
+export declare const modelFormatRefusal: (given: string) => string;
+/** The model is not among those OpenCode lists; `named` says the caller named it, rather than inherited it and named a variant. */
+export declare function unknownModelRefusal(model: ModelRef, known: ReadonlyArray<Pick<ModelRef, "providerID" | "id">>, named: boolean): string;
+export declare function unknownVariantRefusal(model: ModelRef, variants: ReadonlyArray<string>): string;
+/** A variant was named, but the model it would apply to could not be read: the named agent's, else the caller's own or OpenCode's default. */
+export declare function variantWithoutModelRefusal(variant: string, agent?: string): string;
 /**
  * The body of a report: its text, then the artifacts in a fixed layout, the same for every report,
  * so a parent finds the branch, the commits, the files and the checks without reading prose.
  */
 export declare function reportBody(message: string, artifacts: Artifacts | undefined): string;
+/** courier_spawn's refusal of `native: true` with `isolate: true`: OpenCode gives a session a worktree or a parent, never both. */
+export declare const nativeIsolateRefusal: () => string;
 export declare function spawnText(child: {
     readonly sessionID: string;
     readonly directory: string;
@@ -26,6 +35,8 @@ export declare function spawnText(child: {
     readonly groupError?: string;
     readonly fromParent?: boolean;
     readonly uncommitted?: boolean;
+    /** The model it runs on, when that is not the caller's own. */
+    readonly model?: string;
 }): string;
 /** courier_send's result: for a message to the session that started the sender, whether it was its report. */
 export declare function sendText(sessionID: string, sent?: Pick<Sent, "status" | "report" | "held">): string;

package/dist/tree/text.js

@@ -19,6 +19,9 @@ export function childBrief(parentID, task, depth, limits, branch) {
             "concrete ask, then end your turn and wait for its answer; never end quietly.",
         "A report with a status wakes the parent and is the only way it hears from you, so do not end without sending one. " +
             "A message without a status is progress, not your report: if you end your turn without a report, the parent is told so.",
+        "If you find something the other parts of the job need (an assumption of the split that is wrong, a shared file or API " +
+            "that behaves otherwise, something the person told you), send it to the parent at once with courier_send without a " +
+            "status, then carry on: it passes it on to the sessions it affects. Progress alone is not worth a message.",
         "If you need the person to decide something, use your question tool; it reaches them through the session that started you.",
         "",
         ...(branch ? [...isolationRule(branch, depth < limits.maxDepth), ""] : []),
@@ -48,7 +51,9 @@ function splitRule(parentID, depth, limits) {
         `You are at depth ${depth} of a session tree that goes at most ${limits.maxDepth} deep. Split your task or do it yourself:`,
         "- Split it when it has 2 or more independent parts, each substantial and touching separate files or areas: start one " +
             `session per part with courier_spawn, at most ${limits.maxChildren} of yours running at once and ${limits.maxTotal} in the whole tree.`,
-        "- Do it yourself when it is small, sequential or tightly coupled. Never start exactly one session for the whole task; a core you stage before the rest is one part of it, not the whole, when 2 or more parts follow it.",
+        "- Do it yourself when it is small, sequential or tightly coupled. Never start exactly one session for the whole task. One session for one stage is a part, not the whole: " +
+            "a core you stage before the rest, when 2 or more parts follow it; a review of the parts once you have merged them; the fixing of what a review found once you have verified it. " +
+            "One session alone, with nothing of the task done before it by you or by 2 or more parts, and fewer than 2 parts after it, is the whole task.",
         `- Say which in one line of your reply: ${SPLIT_LINE}.`,
         "- If you split, you orchestrate: start the parts that run at once in one group, with the same group name for each, " +
             "then end your turn while they work. Do not poll with courier_status, courier_children, courier_tree or sleep: the group's " +
@@ -89,6 +94,36 @@ export const childrenRefusal = (running, maxChildren) => `Not started: ${count(r
     `(maxChildren ${maxChildren}). Do this part yourself, or end your turn and start it once one of them has reported.`;
 export const totalRefusal = (running, maxTotal) => `Not started: ${count(running, "session")} in this session tree ${live(running)}, the most allowed at once ` +
     `(maxTotal ${maxTotal}). Do this part yourself, or end your turn and try again once a report has arrived.`;
+// courier_spawn's refusals of a model or a variant OpenCode does not list.
+/** How many models, or providers, a refusal names before it counts the rest. */
+const NAMED = 12;
+const some = (items) => (items.length > NAMED ? `${items.slice(0, NAMED).join(", ")} and ${items.length - NAMED} more` : items.join(", "));
+export const modelFormatRefusal = (given) => `Not started: model must be provider/model, as OpenCode names them (opencode/gpt-5-nano, anthropic/claude-sonnet-4-5), not ${JSON.stringify(given)}. ` +
+    "Leave it unset to run the session on your own model.";
+/** The model is not among those OpenCode lists; `named` says the caller named it, rather than inherited it and named a variant. */
+export function unknownModelRefusal(model, known, named) {
+    const name = `${model.providerID}/${model.id}`;
+    const ids = known.filter((item) => item.providerID === model.providerID).map((item) => item.id);
+    const providers = [...new Set(known.map((item) => item.providerID))];
+    let hint = "No model is listed here at all.";
+    if (ids.length)
+        hint = `The models of ${model.providerID} here are ${some(ids)}.`;
+    else if (providers.length)
+        hint = `The providers here are ${some(providers)}.`;
+    return named
+        ? `Not started: OpenCode lists no model ${name} here. ${hint} Leave model unset to run the session on your own model.`
+        : `Not started: the variant cannot be checked, since OpenCode lists no model ${name} here, the one the session would run on. ${hint}`;
+}
+export function unknownVariantRefusal(model, variants) {
+    const listed = variants.length ? `${variants.join(", ")} and default` : "default alone";
+    return (`Not started: the model ${model.providerID}/${model.id} has no variant ${JSON.stringify(model.variant)}. ` +
+        `Its variants are ${listed}; leave variant unset for the model's default.`);
+}
+/** A variant was named, but the model it would apply to could not be read: the named agent's, else the caller's own or OpenCode's default. */
+export function variantWithoutModelRefusal(variant, agent) {
+    const why = agent ? `the agent ${agent} could not be looked up` : "neither your own model nor OpenCode's default could be read";
+    return `Not started: variant ${JSON.stringify(variant)} needs a model to apply to, and ${why}. Name a model as provider/model, or leave variant unset.`;
+}
 /** The strings of a list given as artifacts, whatever else the model put in it. */
 const strings = (value) => (Array.isArray(value) ? value.flatMap((item) => (typeof item === "string" ? [item.trim()] : [])) : []).filter(Boolean);
 /** A list's line in the artifacts block, or none when it is empty. */
@@ -112,6 +147,9 @@ export function reportBody(message, artifacts) {
     return lines.length ? [message, "", "Artifacts:", ...lines].join("\n") : message;
 }
 // Tool results.
+/** courier_spawn's refusal of `native: true` with `isolate: true`: OpenCode gives a session a worktree or a parent, never both. */
+export const nativeIsolateRefusal = () => "Not started: native: true and isolate: true cannot go together. OpenCode runs a session in a worktree of its own or as a " +
+    "subagent of its parent, never both. Start it with isolate: true alone for a worktree of its own, or with native: true alone for a subagent in your directory.";
 export function spawnText(child) {
     const warning = (child.fromParent ? " Its worktree starts from the commit your own worktree is on." : "") +
         (child.uncommitted
@@ -124,7 +162,8 @@ export function spawnText(child) {
             "turn has ended, you get their reports in one message, which starts a new turn for you; a blocked report, a question " +
             "or a failed turn still reaches you at once."
         : "It will report back with courier_send, which starts a new turn for you.";
-    return (`Started session ${child.sessionID} in ${child.directory}. ${reports} Once you have started every session you need, ` +
+    const on = child.model ? `, on ${child.model}` : "";
+    return (`Started session ${child.sessionID} in ${child.directory}${on}. ${reports} Once you have started every session you need, ` +
         `end your turn: reply without calling more tools. That does not drop the task; you carry on with it when the reports arrive.${warning}`);
 }
 /** courier_send's result: for a message to the session that started the sender, whether it was its report. */

package/dist/tree/tools.d.ts

@@ -9,7 +9,10 @@ export declare const SpawnInput: Schema.Struct<{
     readonly task: Schema.String;
     readonly title: Schema.optional<Schema.String>;
     readonly agent: Schema.optional<Schema.String>;
+    readonly model: Schema.optional<Schema.String>;
+    readonly variant: Schema.optional<Schema.String>;
     readonly isolate: Schema.optional<Schema.Boolean>;
+    readonly native: Schema.optional<Schema.Boolean>;
     readonly group: Schema.optional<Schema.String>;
 }>;
 export declare const SendInput: Schema.Struct<{

package/dist/tree/tools.js

@@ -16,10 +16,26 @@ export const SpawnInput = Schema.Struct({
     task: Schema.String.annotate({ description: "What the new session should do. It is told who started it and how to report back." }),
     title: Schema.optional(Schema.String.annotate({ description: "Session title; defaults to the task's first line." })),
     agent: Schema.optional(Schema.String.annotate({ description: "Agent to run the session with; defaults to the default agent." })),
+    model: Schema.optional(Schema.String.annotate({
+        description: "The model to run the session on, as provider/model (opencode/gpt-5-nano). Leave it unset for your own model, or the " +
+            "agent's own if it names one. Refused when OpenCode does not list it here.",
+    })),
+    variant: Schema.optional(Schema.String.annotate({
+        description: "The model's variant, its reasoning effort as OpenCode names it (low, medium, high, or another the model has). Leave " +
+            "it unset for the chosen model's own; with a model of your own choosing, that is the model's default. Refused when " +
+            "the model has no such variant.",
+    })),
     isolate: Schema.optional(Schema.Boolean.annotate({ description: "Run the session in its own git worktree so parallel sessions don't share files. From a session that is itself " +
             "isolated, the worktree starts from your current commit, not your uncommitted changes: commit first. The session " +
             "commits on a branch named courier/<its session ID> and names it in its report; merge that branch yourself.",
     })),
+    native: Schema.optional(Schema.Boolean.annotate({
+        description: "true starts the session as your OpenCode subagent: it leaves OpenCode's session lists for your subagent tab, the " +
+            "person answers its permission requests and questions in the view of the nearest session above it that is not a " +
+            "subagent, usually the top one, and deleting your session deletes it. false starts a standalone session, whatever the " +
+            "plugin's nativeChildren option says; unset, that option decides. Refused with isolate: true, as a subagent runs in " +
+            "its parent's directory.",
+    })),
     group: Schema.optional(Schema.String.annotate({
         description: "A join group: start the sessions of one batch with the same name, and their reports are held and delivered " +
             "to you in one message once every one of them has reported and your turn has ended, instead of one turn per " +
@@ -72,7 +88,8 @@ export function addTreeTools(tools, ports) {
     tools.add({
         name: "courier_spawn",
         options: { codemode: false },
-        description: "Start a new OpenCode session on a task and return immediately. It runs on your model. The session reports " +
+        description: "Start a new OpenCode session on a task and return immediately. It runs on your model, unless you name a model or a " +
+            "variant (reasoning effort) fit for the task. The session reports " +
             "back with courier_send, which wakes this session, and you are told if its turn fails or ends without a report " +
             "instead, it waits for a permission or it asks a question. Give a batch of parallel sessions one group name to " +
             "be woken once, with all their reports, instead of once per report. DO NOT poll it or call courier_status in a " +

package/dist/tui.js

@@ -1457,6 +1457,8 @@ var Row = Schema3.Struct({
   report: Schema3.optionalKey(Schema3.Struct({ state: Schema3.Literals(["owed", "reported", "ended"]), status: Schema3.optionalKey(Schema3.String), progressed: Schema3.Boolean })),
   group: Schema3.optionalKey(Schema3.Struct({ name: Schema3.String, standing: Schema3.String })),
   isolated: Schema3.Boolean,
+  native: Schema3.optionalKey(Schema3.Boolean),
+  model: Schema3.optionalKey(Schema3.String),
   created: Schema3.Number,
   idle: Schema3.optionalKey(Schema3.Number),
   cost: Schema3.optionalKey(Schema3.Number),
@@ -1740,6 +1742,12 @@ function statusParts(row, now = Date.now()) {
   }, {
     text: row.isolated ? "isolated" : "",
     kind: "plain"
+  }, {
+    text: row.native ? "native" : "",
+    kind: "plain"
+  }, {
+    text: row.model ?? "",
+    kind: "plain"
   }];
   return parts.filter((part) => part.text);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-courier",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Multi-session orchestration for OpenCode V2: spawn child sessions, be woken by them. No polling.",
   "license": "MIT",
   "author": "Ivo Pogace <71701666+ivopogace@users.noreply.github.com>",
@@ -56,14 +56,14 @@
     "test:e2e": "e2e/run.sh"
   },
   "peerDependencies": {
-    "@opencode/plugin": "2.1.3",
+    "@opencode/plugin": "2.1.4",
     "effect": "4.0.1"
   },
   "devDependencies": {
-    "@opencode/plugin": "2.1.3",
-    "@opencode/theme": "2.1.3",
-    "@opentui/core": "0.6.6",
-    "@opentui/solid": "0.6.6",
+    "@opencode/plugin": "2.1.4",
+    "@opencode/theme": "2.1.4",
+    "@opentui/core": "0.6.8",
+    "@opentui/solid": "0.6.8",
     "@types/bun": "1.4.2",
     "@types/node": "26.6.4",
     "effect": "4.0.1",