opencode-courier 0.4.0 → 0.5.0

package/README.md

@@ -22,7 +22,7 @@ prompt](#demos)).
 ## Quickstart
 
 ```bash
-npm install -g @opencode/cli@2.0.28   # OpenCode V2, at the version courier is tested on
+npm install -g @opencode/cli@2.0.29   # OpenCode V2, at the version courier is tested on
 opencode plugin add opencode-courier  # by name, so OpenCode offers new releases
 opencode                              # in any folder
 ```
@@ -44,7 +44,7 @@ sometimes stall on a request; if nothing moves for a few minutes, send the promp
 
 Courier is built on OpenCode V2's plugin API (`@opencode/plugin`), not the V1 one
 (`@opencode-ai/plugin`), and needs OpenCode V2. Each release is pinned to one V2 version and tested
-against it end to end; the current one is tested on **OpenCode 2.0.28**. CI also runs the live
+against it end to end; the current one is tested on **OpenCode 2.0.29**. CI also runs the live
 suite on the newest OpenCode release, so a host release that breaks the plugin shows up there
 first. Older releases and their versions: [Supported OpenCode version](#supported-opencode-version).
 
@@ -64,8 +64,9 @@ a self-contained task that needs nothing from you on the way. Use courier when t
 - **Worktree isolation:** `isolate: true` gives a child its own git worktree, so children can edit
   files in parallel; each commits on `courier/<its session ID>` and reports that branch for its
   parent to merge ([nested isolation](docs/reference.md#nested-isolation)).
-- **Relaying to you:** a child's permission requests and questions reach you through the parent,
-  and your answers go back; a form only you can answer is pointed out to you.
+- **Relaying to you:** a child's permission requests and questions reach you through the parent:
+  a request is approved in OpenCode's own permission prompt in the parent's session, never by its
+  model, and your answers go back; a form only you can answer is pointed out to you.
 
 ## How it works
 
@@ -116,7 +117,8 @@ line to the server log naming both ([more](docs/reference.md#the-opencode-versio
 
 | opencode-courier | OpenCode V2 (`opencode` and `@opencode/plugin`) |
 |---|---|
-| 0.4.0 | 2.0.28 |
+| 0.5.0 | 2.0.29 |
+| 0.4.0, 0.4.1 | 2.0.28 |
 | 0.2.3, 0.3.0 | 2.0.26 |
 | 0.2.2 | 2.0.24 |
 | 0.2.1 | 2.0.23 |
@@ -124,12 +126,12 @@ line to the server log naming both ([more](docs/reference.md#the-opencode-versio
 | 0.1.6 | 0.0.0-beta-19271 (the beta line: `opencode2` from `@opencode-ai/cli`, and `@opencode-ai/plugin`) |
 
 The [terminal part](#in-the-terminal) relies on the host to provide its UI modules and is tested on
-OpenCode 2.0.28 only; the server part works as before on older V2 hosts from 2.0.4 on.
+OpenCode 2.0.29 only; the server part works as before on older V2 hosts from 2.0.4 on.
 
 Check yours with `opencode --version`, and install the matching CLI with:
 
 ```bash
-npm install -g @opencode/cli@2.0.28
+npm install -g @opencode/cli@2.0.29
 ```
 
 ### The plugin
@@ -161,7 +163,7 @@ From a local clone, `bun install && npm run build`, then list its `dist` **direc
    as `opencode serve` next to it, cannot pass your answer on to a child the other runs
    ([why](docs/reference.md#two-servers-on-one-data-directory)).
 2. Give the agents that run children the permissions their work needs: a child that hits an approval
-   prompt waits until you answer it through its parent. Let them use the `question` tool if they
+   prompt waits until you answer OpenCode's prompt for it in the parent's session. Let them use the `question` tool if they
    should be able to ask you. Choose a web search provider before children search the web (run one
    web search in your own session, or use OpenCode's "Third-party search" setting), or the first
    child to search shows that prompt in its own session, which only you can answer there.
@@ -188,7 +190,7 @@ From a local clone, `bun install && npm run build`, then list its `dist` **direc
 | `courier_tree` | Lists the whole tree under a session, depth first, with each one's depth and report state. |
 | `courier_stop` | Interrupts a session below you and everything under it, and cancels their scheduled messages; `cleanup: true` removes their worktrees too. |
 | `courier_cleanup` | Removes an isolated child's worktree, unless it holds unsaved work, and forgets the child. |
-| `courier_answer` | Passes your answer to a permission request or a question that a session under this one waits on. |
+| `courier_answer` | Answers a permission request that a session under this one waits on, after OpenCode has asked you in this session, or passes your answer to its question. |
 | `courier_later` | Schedules a message for a session (this one by default) in `delayMinutes` or `at` a time. |
 | `courier_cancel` | Drops a message scheduled with `courier_later`. |
 | `courier_subscribe` | Subscribes a session to webhook deliveries for a topic (`owner/repo`, `owner/repo#12` or a name). |
@@ -212,9 +214,11 @@ Each tool's parameters: [the reference](docs/reference.md#the-tools).
   children, a scheduled message or a webhook is not, nor is one that answers what you typed in its
   session. [More](docs/reference.md#a-child-that-fails).
 - **Permission requests and questions reach you.** A child's request or question is passed to the
-  session at the top of its tree, any number of levels down; that session asks you and passes your
-  answer back, or links its own question to the child's so your pick goes straight to it. Whichever
-  answer comes first counts, and the other is withdrawn.
+  session at the top of its tree, any number of levels down. For a request, that session proposes an
+  answer with `courier_answer`, and OpenCode asks you in its own permission prompt, in that session
+  and under its rules, before anything is passed on: its model cannot approve, only propose. For a
+  question, it asks you and passes your answer back, or links its own question to the child's so your
+  pick goes straight to it. Whichever answer comes first counts, and the other is withdrawn.
   [More](docs/reference.md#a-child-that-asks-for-permission).
 - **Some forms only you can answer**, such as OpenCode's web search asking for a provider: the top
   session is told, and you answer in the child's session. [More](docs/reference.md#a-child-that-shows-a-form).
@@ -264,14 +268,20 @@ courier 2 running · 1 waiting on you · group pair 1/2
 by depth, with what it does, its report and its group's standing; a session that started others gets
 a bar of the parts reported, a leaf how long it ran, its last tool call and its cost. `↑`/`↓` select,
 `enter` opens the session, `s` stops it and everything under it after you confirm, as `courier_stop`
-would, and `q` closes the panel; `/courier stop <session>` stops from the prompt.
+would, and `q` closes the panel; `/courier stop <session>` stops from the prompt. While open, the panel
+follows you between sessions: into one of its tree it keeps that tree, the session on screen marked
+`(on screen)`; elsewhere it shows that session's tree, or hides while you are in a session without one,
+or on the home screen, and shows again once you are back in one; only `q` closes it for good.
 
-`ctrl+x k` (the leader key, then `k`), `/asks`, the palette's "Courier: what waits on you" or a click
+`ctrl+x k` (the leader key, then `k`), `/asks` (or `/ask`), the palette's "Courier: what waits on you" or a click
 on "waiting on you" opens the asks inbox: every permission request, question and form waiting
 anywhere in the tree, oldest first, with where it comes from, answered in a dialog with no model in
 between; the session that started the tree hears once that you settled it. The TUI plays OpenCode's
 sounds for a child's report, a group's release and a new ask ([more](docs/reference.md#in-the-terminal)).
 
+While a permission prompt or form is shown in the session, OpenCode hides the footer, so open the
+inbox with `ctrl+x k` (or `/asks` once the prompt is back).
+
 ## Native child sessions
 
 Off by default. With `"nativeChildren": true` in the plugin's `options`, a child started without
@@ -293,7 +303,8 @@ the courier's own tree, limits and relays work as without the option. What chang
   top session's model is only told. `opencode run` and the TUI's auto-accept mode answer them as their
   own subagents'.
 - **Turn it on only with OpenCode's TUI or the paired app**, which show those prompts; with a bare
-  API client nobody prompts you, and only `courier_answer` is left.
+  API client nobody prompts you, and only `courier_answer` is left, which prompts you in the top
+  session before it passes anything on.
 
 ## Webhooks
 

package/dist/index.js

@@ -95,7 +95,7 @@ export const courier = () => Plugin.define({
             },
         };
         const cleanupPorts = { ...ports, inspect: inspectWorktree };
-        const answerPorts = { storage: ctx.storage, permissions };
+        const answerPorts = { storage: ctx.storage, permissions, assert: (input) => ctx.permission.assert(input) };
         const later = {
             storage: ctx.storage,
             session: ctx.session,

package/dist/person/permission.d.ts

@@ -3,6 +3,12 @@ import { type Pending, type RosterStorage } from "../tree/index.js";
 /** The answers to a permission request, as OpenCode's own prompt offers them. */
 export declare const REPLIES: readonly ["once", "always", "reject"];
 export type Reply = (typeof REPLIES)[number];
+/**
+ * What courier_answer passes on: `once`, which OpenCode first asks the person about in the caller's
+ * session, or `reject`. Never `always`: the plugin grants no standing rule to the caller or the child.
+ */
+export declare const PROPOSALS: readonly ["once", "reject"];
+export type Proposal = (typeof PROPOSALS)[number];
 /** A permission request, as OpenCode's `permission.asked` event carries it. */
 export interface PermissionRequest {
     readonly id: string;
@@ -25,6 +31,8 @@ export interface PermissionAnswered {
 type Context = Plugin.Context;
 /** One location's pending permission requests. OpenCode keeps them per location, so an isolated child's are in its worktree's. */
 export type Permissions = Pick<Context["permission"], "list" | "reply">;
+/** OpenCode's check of a session's permission rules, which asks the person in that session when they say so. */
+export type Assert = Context["permission"]["assert"];
 /** The part of OpenCode's `permission.asked` event the notice is made from. */
 export interface PermissionAsked {
     readonly id: string;
@@ -48,12 +56,20 @@ export interface AnswerPorts {
     readonly storage: RosterStorage;
     /** The permission domains of every loaded location; the request is answered where it is pending. */
     readonly permissions: () => Iterable<Permissions>;
+    /** The caller's location's check, which prompts the person in the caller's session. */
+    readonly assert: Assert;
+}
+/** The courier_answer call a proposal comes from, which OpenCode's prompt in the caller's session is bound to. */
+export interface AnswerCall {
+    readonly messageID: string;
+    readonly callID: string;
 }
 export interface AnswerInput {
     readonly sessionID: string;
     readonly requestID: string;
     readonly reply: string;
     readonly message?: string;
+    readonly call?: AnswerCall;
 }
 /** A session's pending requests in every location, with the domain holding each; a location that cannot be read gives its error. */
 export declare function listEverywhere<D extends Pick<Permissions, "list">>(permissions: Iterable<D>, sessionID: string): Promise<({
@@ -69,8 +85,13 @@ export declare function asksPermission(ports: {
     readonly permissions: () => Iterable<Pick<Permissions, "list">>;
 }, sessionID: string): Promise<boolean>;
 /**
- * Answers a permission request of a session started, directly or through others, from the caller,
- * which must be the top session; `answered` is false when no location loaded here holds the request.
+ * Whether `permission.assert` failed because the person rejected the caller's prompt without a reason,
+ * which OpenCode ends the caller's step on; the tool rethrows it as it is, and the child's request waits on.
+ */
+export declare const isDeclined: (error: unknown) => boolean;
+/**
+ * Answers a permission request of a session started, directly or through others, from the caller, which must be the top
+ * session, a proposed `once` only once OpenCode allowed it there; `answered` is false when no location loaded here holds it.
  */
 export declare function answer(ports: AnswerPorts, waiting: Waiting, callerID: string, input: AnswerInput): Promise<PermissionAnswered>;
 /** The requests a session waits on, in whichever location holds them, for courier_status. */

package/dist/person/permission.js

@@ -1,8 +1,13 @@
 import { describeFailure } from "../kernel/protocol.js";
-import { REJECTED } from "./text.js";
+import { REJECTED, refusedText } from "./text.js";
 import { answeringTop } from "../tree/index.js";
 /** The answers to a permission request, as OpenCode's own prompt offers them. */
 export const REPLIES = ["once", "always", "reject"];
+/**
+ * What courier_answer passes on: `once`, which OpenCode first asks the person about in the caller's
+ * session, or `reject`. Never `always`: the plugin grants no standing rule to the caller or the child.
+ */
+export const PROPOSALS = ["once", "reject"];
 /** A session's pending requests in every location, with the domain holding each; a location that cannot be read gives its error. */
 export function listEverywhere(permissions, sessionID) {
     return Promise.all([...permissions].map((domain) => domain.list({ sessionID }).then((requests) => ({ domain, requests: requests.filter((request) => request.sessionID === sessionID) }), (error) => ({ domain, requests: [], error }))));
@@ -24,28 +29,58 @@ async function locate(ports, sessionID, requestID) {
         throw failed.error;
     return undefined;
 }
+const tagOf = (value) => value?._tag;
 /**
- * Answers a permission request of a session started, directly or through others, from the caller,
- * which must be the top session; `answered` is false when no location loaded here holds the request.
+ * Whether `permission.assert` failed because the person rejected the caller's prompt without a reason,
+ * which OpenCode ends the caller's step on; the tool rethrows it as it is, and the child's request waits on.
  */
-export async function answer(ports, waiting, callerID, input) {
-    const reply = input.reply;
-    if (!REPLIES.includes(reply))
-        throw new Error(`reply must be once, always or reject, not "${input.reply}".`);
-    const { sessionID, requestID } = input;
-    await answeringTop(ports.storage, sessionID, callerID, "permission requests");
-    const found = await locate(ports, sessionID, requestID);
-    if (!found) {
-        waiting.delete(requestID);
-        return { sessionID, requestID, reply, answered: false };
+export const isDeclined = (error) => tagOf(error) === "Permission.DeclinedError";
+/** Why `permission.assert` refused: the caller's rules deny the action, or the person rejected the prompt with a reason. */
+function refusalOf(error) {
+    if (tagOf(error) !== "Tool.Error")
+        return undefined;
+    const { message, error: cause } = error;
+    const tag = tagOf(cause);
+    if (tag !== "Permission.BlockedError" && tag !== "Permission.CorrectedError")
+        return undefined;
+    return typeof message === "string" && message ? message : "not allowed";
+}
+/**
+ * OpenCode's check of the child's request under the caller's rules, which asks the person in the caller's session, with the
+ * request's own action and resources and nothing to save: the reason when refused with one, nothing when allowed, else thrown.
+ */
+async function askCaller(ports, callerID, request, call) {
+    try {
+        await ports.assert({
+            sessionID: callerID,
+            action: request.action,
+            resources: [...request.resources],
+            metadata: { source: "courier", from: request.sessionID, asks: "permission", requestID: request.id },
+            ...(call ? { source: { type: "tool", messageID: call.messageID, id: call.callID } } : {}),
+        });
+        return undefined;
+    }
+    catch (error) {
+        const reason = refusalOf(error);
+        if (reason === undefined)
+            throw error;
+        return reason;
     }
-    if (reply === "always" && !found.request.save?.length)
-        throw new Error(`always is not offered for ${requestID}: it has nothing to save. Ask again with once or reject.`);
+}
+/** The reply as a proposal courier_answer passes on; anything else, `always` in particular, is refused. */
+function proposalOf(reply) {
+    if (PROPOSALS.includes(reply))
+        return reply;
+    const always = reply === "always" ? ": courier_answer grants no standing rule; the person grants one in OpenCode's own prompt, in the asking session or the asks inbox" : "";
+    throw new Error(`reply must be once or reject, not "${reply}"${always}.`);
+}
+/** Replies where the request is pending; a reply that fails leaves the request waiting, unless it no longer does. */
+async function passOn(ports, waiting, found, reply) {
+    const { sessionID, requestID, decision, message } = reply;
     // Off the waiting list first, so the reply event this answer causes does not come back as a notice.
     waiting.delete(requestID);
-    const message = reply === "reject" ? input.message || REJECTED : undefined;
     try {
-        await found.domain.reply({ sessionID, requestID, decision: reply, ...(message ? { message } : {}) });
+        await found.domain.reply({ sessionID, requestID, decision, ...(message ? { message } : {}) });
     }
     catch (error) {
         if (await locate(ports, sessionID, requestID).catch(() => found)) {
@@ -54,6 +89,30 @@ export async function answer(ports, waiting, callerID, input) {
         }
         throw new Error(`${describeFailure("permission.reply", error).message}, but ${requestID} no longer waits, so it was answered, possibly by this call.`);
     }
+}
+/**
+ * Answers a permission request of a session started, directly or through others, from the caller, which must be the top
+ * session, a proposed `once` only once OpenCode allowed it there; `answered` is false when no location loaded here holds it.
+ */
+export async function answer(ports, waiting, callerID, input) {
+    const reply = proposalOf(input.reply);
+    const { sessionID, requestID } = input;
+    await answeringTop(ports.storage, sessionID, callerID, "permission requests");
+    let found = await locate(ports, sessionID, requestID);
+    let refused;
+    if (found && reply === "once") {
+        refused = await askCaller(ports, callerID, found.request, input.call);
+        // Answered meanwhile, in the child's session or the asks inbox, while the person was asked.
+        found = await locate(ports, sessionID, requestID);
+    }
+    if (!found) {
+        waiting.delete(requestID);
+        return { sessionID, requestID, reply, answered: false };
+    }
+    const message = refused ?? (reply === "reject" ? input.message || REJECTED : undefined);
+    await passOn(ports, waiting, found, { sessionID, requestID, decision: refused === undefined ? reply : "reject", ...(message ? { message } : {}) });
+    if (refused !== undefined)
+        throw new Error(refusedText(sessionID, requestID, refused));
     return { sessionID, requestID, reply, answered: true };
 }
 /** The requests a session waits on, in whichever location holds them, for courier_status. */

package/dist/person/text.d.ts

@@ -10,6 +10,11 @@ export declare function answerText(result: AnswerResult): string;
  * rejection, and the child would never report back; with a message, the call fails and it carries on.
  */
 export declare const REJECTED = "Refused by the session that started you. Do without it, or report back why you cannot.";
+/**
+ * The failure of a courier_answer whose proposed once OpenCode refused in the caller's session: a rule
+ * denies the action there, or the person rejected the prompt with a reason, which the child was given.
+ */
+export declare function refusedText(sessionID: string, requestID: string, reason: string): string;
 /** How a notice names where the asking session came from, to the session at the top of its lineage. */
 export declare const origin: (startedBy?: string) => string;
 /** For a notice that a session's turn ended without it finishing. */

package/dist/person/text.js

@@ -12,8 +12,10 @@ export function answerText(result) {
     if (!result.answered)
         return (`${result.sessionID} no longer waits on question ${result.requestID}: it was answered some other way, or the ` +
             "session stopped waiting. Nothing was passed on; tell the person their answer is not needed.");
+    if ("reply" in result && result.reply === "reject")
+        return `Passed on reject for request ${result.requestID} of ${result.sessionID}; its call fails and it carries on, and reports back with courier_send. ${END_TURN}`;
     if ("reply" in result)
-        return `Passed on ${result.reply} for request ${result.requestID} of ${result.sessionID}, which carries on and reports back with courier_send. ${END_TURN}`;
+        return `Allowed in your session, by the person in OpenCode's prompt or by your rules, and passed on ${result.reply} for request ${result.requestID} of ${result.sessionID}, which carries on and reports back with courier_send. ${END_TURN}`;
     const how = result.by === "message" ? " as a message, since its question had been cut off" : "";
     return `Passed the answers to question ${result.requestID} on to ${result.sessionID}${how}; it carries on and reports back with courier_send. ${END_TURN}`;
 }
@@ -23,16 +25,16 @@ export function answerText(result) {
  * rejection, and the child would never report back; with a message, the call fails and it carries on.
  */
 export const REJECTED = "Refused by the session that started you. Do without it, or report back why you cannot.";
+/**
+ * The failure of a courier_answer whose proposed once OpenCode refused in the caller's session: a rule
+ * denies the action there, or the person rejected the prompt with a reason, which the child was given.
+ */
+export function refusedText(sessionID, requestID, reason) {
+    return `not allowed in your session (${reason}). The refusal was passed on with that reason to request ${requestID} of ${sessionID}, so its call fails and it carries on; it reports back with courier_send. Tell the person, and do not propose it again unless they ask.`;
+}
 const MAX_RESOURCES = 20;
 const MAX_RESOURCE_LENGTH = 300;
 const clip = (text) => (text.length > MAX_RESOURCE_LENGTH ? `${text.slice(0, MAX_RESOURCE_LENGTH - 3)}...` : text);
-function alwaysChoice(request) {
-    const save = request.save ?? [];
-    if (!save.length)
-        return [];
-    const scope = save.length === 1 && save[0] === "*" ? `every ${request.action} request` : `requests matching ${save.join(", ")}`;
-    return [`- always: allow it, and from now on ${scope} in this project`];
-}
 /** How a notice names where the asking session came from, to the session at the top of its lineage. */
 export const origin = (startedBy) => startedBy ? `which ${startedBy} started with courier_spawn, a session started from yours,` : "which you started with courier_spawn,";
 /** For a notice that a session's turn ended without it finishing. */
@@ -51,21 +53,21 @@ export function permissionNotice(title, request, startedBy, native = false) {
         ...(resources.length ? ["On:", ...resources] : []),
         ...(request.message ? [`Note: ${request.message}`] : []),
         "",
-        ...(native ? NATIVE_PERMISSION : PERMISSION_ASK),
-        "- once: allow this request only",
-        ...alwaysChoice(request),
-        "- reject: refuse it, with a reason if they give one; the session's call fails and it carries on",
-        `When they have chosen, call courier_answer with sessionID "${request.sessionID}", requestID "${request.id}", reply set to their choice and, with reject, message set to their reason.`,
+        ...(native ? nativePermission(request) : permissionAsk(request)),
     ].join("\n");
 }
-const PERMISSION_ASK = [
-    "Do not decide this yourself. Ask the person you are working with (with your question tool, if you have one), offering exactly these choices:",
+const permissionAsk = (request) => [
+    "You cannot decide this: the person you are working with does, in OpenCode's own permission prompt, which opens in your session when you propose once. Do not ask them in your reply or with your question tool first; propose one of these:",
+    "- once: allow this request only; OpenCode first asks the person in your session, under your permission rules, and it is passed on only once they have allowed it",
+    "- reject: refuse it, with a reason if the person gave one; the session's call fails and it carries on",
+    `Call courier_answer with sessionID "${request.sessionID}", requestID "${request.id}", reply set to the choice and, with reject, message set to the reason.`,
+    "Propose once unless the person has told you to refuse it, or the request plainly goes against what they asked of you; with once, the call returns when they have answered the prompt (or your rules allow the action without one). A refusal there with a reason fails the call with it, which the session is given; one without a reason ends your turn, and the session waits on.",
 ];
-/** For a native child's request, which OpenCode shows the person itself, in the top session's view. */
-const NATIVE_PERMISSION = [
+/** For a native child's request, which OpenCode shows the person itself, in the top session's view: nothing to call. */
+const nativePermission = (request) => [
     "OpenCode already shows this request to the person you are working with, as its own permission prompt in your session (and in the paired app's request dock), where they answer it; you will be told once it is answered.",
-    "Do not ask them yourself, with your question tool or in your reply, and do not decide it: at most tell them in one line that this session waits on their permission, then end your turn.",
-    "Only if they ask you to answer it for them, these are the choices:",
+    "Do not ask them yourself, with your question tool or in your reply, and do not call courier_answer for it, which would only ask them a second time: at most tell them in one line that this session waits on their permission, then end your turn.",
+    `Only if they tell you to answer it for them, call courier_answer with sessionID "${request.sessionID}", requestID "${request.id}" and reply set to once or reject (with reject, message set to the reason); with once, OpenCode asks them again in your session before it is passed on.`,
 ];
 /** What the session told about a permission request is told once it is answered without courier_answer. */
 export function permissionSettledNotice(title, requestID, reply) {

package/dist/person/tools.d.ts

@@ -5,7 +5,7 @@ import { type QuestionPorts } from "./question/index.js";
 export declare const AnswerInput: Schema.Struct<{
     readonly sessionID: Schema.String;
     readonly requestID: Schema.String;
-    readonly reply: Schema.optional<Schema.Literals<readonly ["once", "always", "reject"]>>;
+    readonly reply: Schema.optional<Schema.Literals<readonly ["once", "reject"]>>;
     readonly message: Schema.optional<Schema.String>;
     readonly answers: Schema.optional<Schema.$Array<Schema.Union<readonly [Schema.String, Schema.$Array<Schema.String>]>>>;
 }>;

package/dist/person/tools.js

@@ -1,22 +1,23 @@
 import { Schema } from "effect";
 import { rethrow } from "../kernel/tool.js";
-import { answer, REPLIES } from "./permission.js";
+import { answer, isDeclined, PROPOSALS } from "./permission.js";
 import { answerQuestion, isQuestion } from "./question/index.js";
 import { answerText } from "./text.js";
 export const AnswerInput = Schema.Struct({
     sessionID: Schema.String.annotate({ description: "The session you started that is waiting, as its notice names it." }),
     requestID: Schema.String.annotate({ description: "The request id from the notice." }),
-    reply: Schema.optional(Schema.Literals(REPLIES).annotate({
-        description: "For a permission request: the choice the person made, once, always (only when the notice offers it) or reject.",
+    reply: Schema.optional(Schema.Literals(PROPOSALS).annotate({
+        description: "For a permission request: the answer you propose, once or reject. With once, OpenCode first asks the person in " +
+            "your session, and it is passed on only once they have allowed it; always is not granted through this tool.",
     })),
-    message: Schema.optional(Schema.String.annotate({ description: "For a permission request, with reject: the person's reason, passed on with the refusal." })),
+    message: Schema.optional(Schema.String.annotate({ description: "For a permission request, with reject: the reason, passed on with the refusal." })),
     answers: Schema.optional(Schema.Array(Schema.Union([Schema.String, Schema.Array(Schema.String)])).annotate({
         description: "For a question: one entry per question, in order, each the label the person chose or the text they gave, " +
             "or a list of labels where the question allows several.",
     })),
 });
 // One tool answers both: a question's id is the plugin's own, a permission request's OpenCode's.
-async function answerRequest(ports, callerID, input) {
+async function answerRequest(ports, callerID, input, call) {
     const { sessionID, requestID } = input;
     if (isQuestion(requestID)) {
         if (input.reply !== undefined || input.message !== undefined)
@@ -26,14 +27,15 @@ async function answerRequest(ports, callerID, input) {
         return answerQuestion(ports.questions, callerID, { sessionID, requestID, answers: input.answers });
     }
     if (input.answers !== undefined)
-        throw new Error(`${requestID} is a permission request: pass the person's choice in reply (once, always or reject), not answers.`);
+        throw new Error(`${requestID} is a permission request: pass the answer you propose in reply (once or reject), not answers.`);
     if (input.reply === undefined)
-        throw new Error(`${requestID} is a permission request: reply is required, once, always or reject.`);
+        throw new Error(`${requestID} is a permission request: reply is required, once or reject.`);
     return answer(ports.answer, ports.waiting, callerID, {
         sessionID,
         requestID,
         reply: input.reply,
         ...(input.message !== undefined ? { message: input.message } : {}),
+        ...(call ? { call } : {}),
     });
 }
 /** Adds `courier_answer`. */
@@ -42,13 +44,22 @@ export function addPersonTools(tools, ports) {
         name: "courier_answer",
         options: { codemode: false },
         description: "Pass on the answer to a permission request or a question that a session you started with courier_spawn (or " +
-            "one started from it) waits on, after a notice from it named the request. The answer is the person's, not yours: " +
-            "first ask the person you are working with, offering the choices the notice lists, then call this with what " +
-            "they chose: reply for a permission request, answers for a question. Never choose for them. The session " +
-            "carries on once it has the answer.",
+            "one started from it) waits on, after a notice from it named the request. For a permission request, reply is " +
+            "the answer you propose, once or reject: proposing is not deciding. With once, OpenCode asks the person you are " +
+            "working with in your session, as its own permission prompt for what that session asked, under your permission " +
+            "rules, and the call returns once they have answered; what they allow is passed on, and a refusal with a reason " +
+            "fails this call and is passed on with the reason. Do not ask them in your reply or with your question tool first. " +
+            "For a question, answers is what the person chose: ask them first, with your question tool if you have one, and " +
+            "never answer for them. The session carries on once it has the answer.",
         input: AnswerInput,
         execute: async (input, context) => {
-            const result = await answerRequest(ports, context.sessionID, input).catch(rethrow("courier_answer"));
+            const call = { messageID: context.messageID, callID: context.id };
+            const result = await answerRequest(ports, context.sessionID, input, call).catch((error) => {
+                // A plain rejection of the caller's prompt ends its step, as OpenCode's own tools do: it goes back as it is.
+                if (isDeclined(error))
+                    throw error;
+                return rethrow("courier_answer")(error);
+            });
             return { content: answerText(result), metadata: result };
         },
     });

package/dist/tree/tui.d.ts

@@ -41,8 +41,8 @@ export declare function stoppedLine({ stopped, cancelled }: Stopped): string;
 /** The usage the `/courier` command shows for an input it does not know. */
 export declare const USAGE = "/courier tree opens the session tree; /courier stop [session] stops a session and those under it";
 /**
- * Adds the tree panel to the `session.panel` slot, opened by `/courier tree` or the command palette, and `/courier
- * stop <session>`, which stops a session under the open one after the person confirms.
+ * Adds the tree panel to the `session.panel` slot, opened by `/courier tree` or the palette, which follows the person
+ * between sessions until closed, and `/courier stop <session>`, which stops a session under the open one once confirmed.
  */
 export declare function addTreePanel(ctx: Context): () => void;
 /**

package/dist/tui.js

@@ -518,6 +518,7 @@ function addAsksInbox(ctx) {
     }, SETTLE_MS);
   });
   ctx.keymap.layer(() => ({
+    mode: "global",
     commands: [{
       id: INBOX_COMMAND,
       title: "Courier: what waits on you",
@@ -526,7 +527,8 @@ function addAsksInbox(ctx) {
       bind: "<leader>k",
       palette: true,
       slash: {
-        name: "asks"
+        name: "asks",
+        aliases: ["ask"]
       },
       run: () => void open()
     }]
@@ -550,7 +552,7 @@ import { createTextNode as _$createTextNode } from "@opentui/solid";
 import { insertNode as _$insertNode } from "@opentui/solid";
 import { setProp as _$setProp } from "@opentui/solid";
 import { createElement as _$createElement } from "@opentui/solid";
-import { createEffect, createResource, createSignal, For, onCleanup, Show } from "solid-js";
+import { createEffect, createResource, createRoot, createSignal, For, on, onCleanup, onMount, Show, untrack } from "solid-js";
 
 // src/tree/rpc.ts
 import { Rpc as Rpc2 } from "@opencode/plugin/rpc";
@@ -813,10 +815,12 @@ async function confirmStop(ctx, courier, location, by, target) {
   }
   return true;
 }
+var FOCUS_PROMPT = "pane.focus.left";
 function TreePanel(props) {
   const {
     ctx,
     input,
+    view,
     courier,
     location
   } = props;
@@ -824,7 +828,7 @@ function TreePanel(props) {
   const [read, {
     refetch
   }] = createResource(() => ({
-    sessionID: input.sessionID,
+    sessionID: view.root,
     changed: props.changed()
   }), ({
     sessionID
@@ -839,12 +843,40 @@ function TreePanel(props) {
     sessionID,
     error: reason(error)
   })));
-  const latest = () => read.state === "ready" || read.state === "refreshing" ? read.latest : undefined;
+  const latest = () => read.state === "ready" || read.state === "refreshing" ? read.latest : view.tree && {
+    sessionID: view.root,
+    tree: view.tree
+  };
   const rows = () => latest()?.tree?.rows ?? [];
+  createEffect(() => {
+    const tree = latest()?.tree;
+    if (tree)
+      view.note({
+        tree
+      });
+  });
+  createEffect(() => view.note({
+    presentation: input.presentation,
+    focused: input.focused
+  }));
+  onMount(() => {
+    if (!view.refocus)
+      return;
+    const giveBack = setTimeout(() => ctx.keymap.dispatch(FOCUS_PROMPT));
+    onCleanup(() => clearTimeout(giveBack));
+  });
   const [now, setNow] = createSignal(Date.now());
   const tick = setInterval(() => setNow(Date.now()), TICK_MS);
   onCleanup(() => clearInterval(tick));
   const [selected, setSelected] = createSignal(0);
+  let placed = false;
+  createEffect(() => {
+    const index = placed ? -1 : rows().findIndex((row) => row.sessionID === input.sessionID);
+    if (index < 0)
+      return;
+    placed = true;
+    setSelected(index);
+  });
   const current = () => rows()[Math.min(selected(), rows().length - 1)];
   let scroll;
   createEffect(() => {
@@ -864,7 +896,7 @@ function TreePanel(props) {
   const stopSelected = () => {
     const row = current();
     if (row)
-      confirmStop(ctx, courier, location, input.sessionID, {
+      confirmStop(ctx, courier, location, view.root, {
         sessionID: row.sessionID,
         title: row.title,
         under: reach(rows(), row.sessionID) - 1
@@ -920,7 +952,7 @@ function TreePanel(props) {
       run: () => input.close()
     }]
   }));
-  const root = () => parts(rows(), input.sessionID);
+  const root = () => parts(rows(), view.root);
   const rowColor = (row) => {
     if (row.state === "waiting")
       return theme.text.feedback.warning.base;
@@ -1010,6 +1042,7 @@ function TreePanel(props) {
           _$insert(_el$17, indent, _el$18);
           _$insert(_el$17, () => chosen() ? "\u25B8 " : "  ", _el$18);
           _$insert(_el$17, () => row.title, _el$18);
+          _$insert(_el$17, () => row.sessionID === input.sessionID ? " (on screen)" : "", _el$18);
           _$insert(_el$19, () => statusLine(row));
           _$insert(_el$16, _$createComponent(For, {
             get each() {
@@ -1066,6 +1099,23 @@ function addTreePanel(ctx) {
     location
   } = courierOf(ctx);
   const [changed, stopListening] = changes(ctx, PANEL_CHANGES, PANEL_SETTLE_MS);
+  let following;
+  let attempt = 0;
+  const viewOf = (sessionID) => {
+    const here = following?.at === sessionID ? following : undefined;
+    const refocus = here?.refocus === true;
+    if (here)
+      here.refocus = false;
+    return {
+      root: here?.root ?? sessionID,
+      tree: here?.tree,
+      refocus,
+      note: (fields) => {
+        if (here && following === here)
+          Object.assign(here, fields);
+      }
+    };
+  };
   const release = ctx.ui.slot({
     append: "session.panel",
     render: (input) => _$createComponent(Show, {
@@ -1076,6 +1126,9 @@ function addTreePanel(ctx) {
         return _$createComponent(TreePanel, {
           ctx,
           input,
+          get view() {
+            return viewOf(input.sessionID);
+          },
           courier,
           location,
           changed
@@ -1083,13 +1136,98 @@ function addTreePanel(ctx) {
       }
     })
   });
-  const openPanel = () => {
-    if (!ctx.ui.panel.open(PANEL))
-      ctx.ui.toast.show({
-        title: "courier",
-        message: "Open a session first",
-        variant: "warning"
+  const show = (from, at, root, tree) => {
+    following = {
+      ...from,
+      root,
+      at,
+      to: undefined,
+      tree,
+      refocus: !from.focused
+    };
+    ctx.ui.panel.open(PANEL, {
+      presentation: from.presentation
+    });
+  };
+  const treeOf = (sessionID) => courier.tree({
+    sessionID
+  }, {
+    location: location(sessionID)
+  }).catch(() => {
+    return;
+  });
+  const follow = (from, sessionID) => {
+    const token = ++attempt;
+    const under = (tree) => tree?.rows.some((row) => row.sessionID === sessionID) === true;
+    Object.assign(from, {
+      at: undefined,
+      to: sessionID
+    });
+    if (sessionID === from.root || under(from.tree))
+      return show(from, sessionID, from.root, from.tree);
+    (async () => {
+      const inside = await treeOf(from.root);
+      const own = under(inside) ? undefined : await treeOf(sessionID);
+      if (token !== attempt || following !== from)
+        return;
+      if (under(inside))
+        show(from, sessionID, from.root, inside);
+      else if (own?.rows.length)
+        show(from, sessionID, sessionID, own);
+    })();
+  };
+  const hide = (from) => {
+    ++attempt;
+    Object.assign(from, {
+      at: undefined,
+      to: undefined
+    });
+  };
+  const stopFollowing = createRoot((dispose) => {
+    createEffect(() => {
+      const route = ctx.ui.router.current();
+      const sessionID = route.type === "session" ? route.sessionID : undefined;
+      const shown2 = ctx.ui.panel.current();
+      untrack(() => {
+        if (!following || shown2 && shown2.sessionID === sessionID || !following.at && following.to === sessionID)
+          return;
+        if (!shown2 && sessionID && following.at === sessionID)
+          following = undefined;
+        else if (!sessionID)
+          hide(following);
+        else
+          follow(following, sessionID);
       });
+    });
+    createEffect(on(changed, () => untrack(() => {
+      const route = ctx.ui.router.current();
+      if (!following || following.at || route.type !== "session" || following.to !== route.sessionID || ctx.ui.panel.current())
+        return;
+      following.focused = false;
+      follow(following, route.sessionID);
+    }), {
+      defer: true
+    }));
+    return dispose;
+  });
+  const openPanel = () => {
+    const route = ctx.ui.router.current();
+    const before = following;
+    if (route.type === "session" && following?.at !== route.sessionID)
+      following = {
+        root: route.sessionID,
+        at: route.sessionID,
+        presentation: "panel",
+        focused: true
+      };
+    if (ctx.ui.panel.open(PANEL))
+      return;
+    following = before;
+    ctx.ui.toast.show({
+      title: "courier",
+      message: "Open a session first",
+      variant: "warning"
+    });
   };
   const stopUnder = async (target) => {
     const route = ctx.ui.router.current();
@@ -1153,6 +1291,7 @@ function addTreePanel(ctx) {
     }]
   }));
   return () => {
+    stopFollowing();
     stopListening();
     release();
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-courier",
-  "version": "0.4.0",
+  "version": "0.5.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,12 +56,12 @@
     "test:e2e": "e2e/run.sh"
   },
   "peerDependencies": {
-    "@opencode/plugin": "2.0.28",
+    "@opencode/plugin": "2.0.29",
     "effect": "4.0.1"
   },
   "devDependencies": {
-    "@opencode/plugin": "2.0.28",
-    "@opencode/theme": "2.0.28",
+    "@opencode/plugin": "2.0.29",
+    "@opencode/theme": "2.0.29",
     "@opentui/core": "0.5.17",
     "@opentui/solid": "0.5.17",
     "@types/bun": "1.3.14",