opencode-courier 0.4.1 → 0.6.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,9 +44,9 @@ 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
-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).
+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, on `main` and nightly, so a host release that breaks the
+plugin shows up there first. Older releases and their versions: [Supported OpenCode version](#supported-opencode-version).
 
 ## Courier or the built-in subagent tool?
 
@@ -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,6 +117,7 @@ line to the server log naming both ([more](docs/reference.md#the-opencode-versio
 
 | opencode-courier | OpenCode V2 (`opencode` and `@opencode/plugin`) |
 |---|---|
+| 0.5.0, 0.6.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 |
@@ -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).
@@ -222,7 +226,8 @@ Each tool's parameters: [the reference](docs/reference.md#the-tools).
   [terminal](#in-the-terminal). [More](docs/reference.md#seeing-and-stopping-a-subtree).
 
 Children, held reports, scheduled messages and open questions survive a compaction or a restart;
-entries are dropped after 14 days ([roster](docs/reference.md#roster)).
+entries are dropped after 14 days, or at once when OpenCode deletes the child, unless it is isolated
+([roster](docs/reference.md#roster)).
 
 ## Session trees
 
@@ -252,27 +257,34 @@ does not. Each spawned session's brief says when to split its task and when to d
 
 The package ships a part for OpenCode's terminal UI, which the TUI loads from the server's plugin
 list; the server half behaves the same whether or not a TUI is attached. In a session that started
-sessions, the prompt's footer shows what the tree under it is doing: how many run, wait on you or
-are idle, and for each [join group](docs/reference.md#join-groups) how many of its members have
+sessions, the prompt's footer shows what the tree under it is doing: how many run, wait on you (a
+permission request, a question or a form they show) or are idle, and for each [join group](docs/reference.md#join-groups) how many of its members have
 reported:
 
 ```
-courier 2 running · 1 waiting on you · group pair 1/2
+courier 1 waiting on you · 2 running · group pair 1/2
 ```
 
 `/courier tree` opens a panel beside the session with the tree under it, a row per session indented
-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,
+by depth, with what it does, its report and its group's standing; a session waiting on you gets a line per
+request or form (`shows a form: Web Search`), 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. A tree that has
+started more than `maxTotal` sessions over time is listed live ones first, then newest, and the header
+says how many older ones are left out; the footer counts them all. `↑`/`↓` 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. While open, the panel
+would, `x` forgets a `gone` session after you confirm, removing its worktree by `courier_cleanup`'s
+rules, 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 closes if it started none.
+`(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` (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)).
+anywhere in the tree, however many sessions it has, oldest first, after the top session's own permission
+requests, such as the prompt `courier_answer` has OpenCode show there, with where it comes from, kept current
+while it is open as asks arrive or are settled elsewhere, 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 and a group's release, and OpenCode's own for a new ask, which the courier
+adds a notification to for a native child ([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).
@@ -298,7 +310,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

@@ -7,7 +7,7 @@ import { watchFromHub } from "./platform/events.js";
 import { hub, openInProcess, permissions as domains, sharedState } from "./platform/hub.js";
 import { builtVersions, versionNotice } from "./platform/version.js";
 import { addSchedulingTools, cancelScheduled, dueJob, isScheduled } from "./scheduling/index.js";
-import { addPersonTools, asksPermission, asksQuestion, joinRelay, noticeCutOff, pendingOf, pendingQuestions, personEvents, portsAt, registerPersonRpc, relayQuestions, } from "./person/index.js";
+import { addPersonTools, asksPermission, asksQuestion, formsShown, joinRelay, noticeCutOff, pendingOf, pendingQuestions, personEvents, portsAt, registerPersonRpc, relayQuestions, } from "./person/index.js";
 import { addSkill } from "./skill.js";
 import { addTreeTools, deliverReleased, dirtyOf, headOf, inspectWorktree, pruneExpired, readLimits, readNativeChildren, registerTreeRpc, shapeContext, together, treeEvents, waitsOn, } from "./tree/index.js";
 import { addWebhookTools, joinReceiver, readConfig, receiving, subscribedSince, } from "./webhook/index.js";
@@ -15,6 +15,8 @@ import { addWebhookTools, joinReceiver, readConfig, receiving, subscribedSince,
 const gate = sharedState("spawning", () => ({ reserved: new Set(), turn: Promise.resolve() }));
 /** The type of each item enqueued for a spawned session, outside the hub like the gate. */
 const inbox = sharedState("inbox", () => new Map());
+/** The forms shown now, which the person events keep and the footer and tree panel count; outside the hub like the inbox. */
+const shown = sharedState("formsShown", () => new Map());
 /**
  * What each tick of the scheduler does, in order, through the first loaded member, of whichever copy:
  * due `courier_later` messages, then released join groups. Every hub-v2 member's `later` is its LaterPorts.
@@ -30,7 +32,7 @@ const permissions = domains;
 // several subscriptions and copies see the same events. The scheduler's claim set is the hub's own.
 const { watched } = hub;
 const watchState = { seen: watched.seen, inbox };
-const personState = { ...watched, forms: hub.forms };
+const personState = { ...watched, forms: hub.forms, shown };
 /**
  * What a session waits on outside the tree, for the silent-turn rule, cheapest first: a request of its
  * own to the person, then a scheduled message or a webhook it subscribed to since its last prompt.
@@ -93,9 +95,10 @@ export const courier = () => Plugin.define({
                 ]);
                 return [...requests, ...questions];
             },
+            forms: (sessionID) => Promise.resolve(formsShown(shown, sessionID)),
         };
         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,
@@ -123,7 +126,7 @@ export const courier = () => Plugin.define({
         // What the TUI part reads and its stop; a host that cannot register it still gets the rest, the tools included.
         await Promise.resolve()
             .then(() => registerTreeRpc(ctx.rpc, stopPorts))
-            .then(() => registerPersonRpc(ctx.rpc, { questions: questionPorts, permissions, maxTotal: limits.maxTotal }))
+            .then(() => registerPersonRpc(ctx.rpc, { questions: questionPorts, permissions }))
             .catch((error) => log(`courier rpc: not registered, the TUI part shows nothing and cannot stop: ${String(error)}`));
         await ctx.session.hook("context", (event) => shapeContext({ storage: ctx.storage, limits, roles, log }, event));
         const pruned = pruneExpired(ctx.storage, Date.now()).catch((error) => log(`courier roster prune: ${String(error)}`));

package/dist/person/form.d.ts

@@ -1,4 +1,5 @@
-import { type Form, type PersonPorts, type PersonState } from "./ports.js";
+import { type ShownForm } from "../tree/index.js";
+import { type Form, type FormsShown, type PersonPorts, type PersonState } from "./ports.js";
 /** The `metadata.kind` of the forms OpenCode's question tool asks with; the question relay passes those on. */
 export declare const QUESTION_FORM = "question";
 /** The part of OpenCode's `form.created` event the notice is made from. */
@@ -24,3 +25,5 @@ export interface FormSettled {
 export declare function reportForm(ports: PersonPorts, state: PersonState, event: FormCreated): Promise<string[]>;
 /** Tells the session told about a form that it was answered or withdrawn, so it does not send the person to a form that is gone. */
 export declare function reportFormSettled(ports: PersonPorts, state: PersonState, event: FormSettled): Promise<string[]>;
+/** The forms a session shows now, oldest first, as the tree's `forms` port lists them. */
+export declare const formsShown: (shown: FormsShown, sessionID: string) => ShownForm[];

package/dist/person/form.js

@@ -15,6 +15,8 @@ export async function reportForm(ports, state, event) {
     const form = event.data.form;
     if (kindOf(form) === QUESTION_FORM)
         return [];
+    if (!state.forms.settled.has(form.id))
+        setBounded(state.shown, form.id, { sessionID: form.sessionID, title: form.title }, SEEN_MAX);
     const chain = await lineage(ports.storage, form.sessionID);
     // As with a permission request, claimed after the lookup, so a form settled meanwhile is not told.
     if (!chain.length || state.forms.settled.has(form.id) || state.forms.told.has(form.id))
@@ -41,6 +43,7 @@ export async function reportFormSettled(ports, state, event) {
     if (!claim(state.seen, event.id))
         return [];
     const { id, sessionID } = event.data;
+    state.shown.delete(id);
     const telling = state.forms.told.get(id);
     if (!telling) {
         claim(state.forms.settled, id);
@@ -62,3 +65,5 @@ export async function reportFormSettled(ports, state, event) {
     });
     return [topOf(chain)];
 }
+/** The forms a session shows now, oldest first, as the tree's `forms` port lists them. */
+export const formsShown = (shown, sessionID) => [...shown].flatMap(([id, form]) => (form.sessionID === sessionID ? [{ id, title: form.title }] : []));

package/dist/person/index.d.ts

@@ -2,9 +2,10 @@ import type { PendingPrompt, WatchPorts } from "../tree/index.js";
 import type { PersonPorts } from "./ports.js";
 import type { Prompt } from "./question/index.js";
 export { personEvents } from "./events.js";
+export { formsShown } from "./form.js";
 export { asksPermission, pendingOf } from "./permission.js";
 export type { AnswerPorts, Permissions, Waiting } from "./permission.js";
-export type { PersonPorts, PersonState } from "./ports.js";
+export type { FormsShown, PersonPorts, PersonState } from "./ports.js";
 export { registerPersonRpc } from "./rpc-handlers.js";
 export { asksQuestion, joinRelay, noticeCutOff, pendingQuestions, portsAt, relayQuestions } from "./question/index.js";
 export type { QuestionPorts } from "./question/index.js";

package/dist/person/index.js

@@ -1,4 +1,5 @@
 export { personEvents } from "./events.js";
+export { formsShown } from "./form.js";
 export { asksPermission, pendingOf } from "./permission.js";
 export { registerPersonRpc } from "./rpc-handlers.js";
 export { asksQuestion, joinRelay, noticeCutOff, pendingQuestions, portsAt, relayQuestions } from "./question/index.js";

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;
@@ -11,6 +17,7 @@ export interface PermissionRequest {
     readonly resources: ReadonlyArray<string>;
     readonly save?: ReadonlyArray<string>;
     readonly message?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
 }
 /**
  * What answering a permission request did; `answered` is false when no location loaded here held the
@@ -25,6 +32,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 +57,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,10 +86,28 @@ 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 child's request a prompt of courier_answer's asks about, read from the metadata `askCaller` gives it; undefined for any other request. */
+export declare function passedOn(metadata: Readonly<Record<string, unknown>> | undefined): {
+    sessionID: string;
+    requestID: string;
+} | undefined;
+/** The requests a session waits on of its own, in whichever location holds them, each with the child's request it passes on when courier_answer asks it. */
+export declare function ownRequests(permissions: Iterable<Permissions>, sessionID: string): Promise<{
+    request: PermissionRequest;
+    passesOn: {
+        sessionID: string;
+        requestID: string;
+    } | undefined;
+}[]>;
 /** The requests a session waits on, in whichever location holds them, for courier_status. */
 export declare function pendingOf(permissions: Iterable<Permissions>, sessionID: string): Promise<Pending[]>;
 export {};

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,8 +89,47 @@ 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 child's request a prompt of courier_answer's asks about, read from the metadata `askCaller` gives it; undefined for any other request. */
+export function passedOn(metadata) {
+    const { source, asks, from, requestID } = metadata ?? {};
+    if (source !== "courier" || asks !== "permission" || typeof from !== "string" || typeof requestID !== "string")
+        return undefined;
+    return { sessionID: from, requestID };
+}
+/** The requests a session waits on of its own, in whichever location holds them, each with the child's request it passes on when courier_answer asks it. */
+export async function ownRequests(permissions, sessionID) {
+    const found = new Map();
+    for (const { requests } of await listEverywhere(permissions, sessionID))
+        for (const request of requests)
+            found.set(request.id, request);
+    return [...found.values()].map((request) => ({ request, passesOn: passedOn(request.metadata) }));
+}
 /** The requests a session waits on, in whichever location holds them, for courier_status. */
 export async function pendingOf(permissions, sessionID) {
     const found = new Map();

package/dist/person/ports.d.ts

@@ -19,15 +19,21 @@ export interface PersonPorts {
     readonly now: () => number;
     readonly log: (message: string) => void;
 }
+/** The forms spawned sessions and others show, which only the person can answer, by form id; not the question tool's. */
+export type FormsShown = Map<string, {
+    readonly sessionID: string;
+    readonly title: string;
+}>;
 /**
- * What every plugin instance in the process shares of the person events: the handled event ids, shared
- * with the tree's, and the requests and forms the top sessions were told about or that were answered first.
+ * What every plugin instance in the process shares of the person events: the handled event ids (the tree's too),
+ * the requests and forms told about or answered first, and the forms shown now.
  */
 export interface PersonState {
     readonly seen: Set<string>;
     readonly waiting: Waiting;
     readonly answered: Set<string>;
     readonly forms: FormsTold;
+    readonly shown: FormsShown;
 }
 /** The session at the top of a lineage: where its permission requests go, since that is where the person is. */
 export declare const topOf: (chain: RosterEntry[]) => string;

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

@@ -6,12 +6,10 @@ import { type Answered, type Asks } from "./rpc.js";
 export interface PersonRpcPorts {
     readonly questions: QuestionPorts;
     readonly permissions: () => Iterable<Permissions>;
-    /** At most this many sessions of a tree are read, as courier_tree reads them. */
-    readonly maxTotal: number;
 }
 /**
- * The permission requests and questions waiting in the courier tree a session is in, from the roster: read from the
- * top of its lineage down, so each session of the tree sees the same inbox.
+ * The permission requests and questions waiting in the courier tree a session is in, the top's own requests first, read from the
+ * roster from the top of its lineage down, so each session of the tree sees the same inbox.
  */
 export declare function asks(ports: PersonRpcPorts, sessionID: string): Promise<Asks>;
 /** Passes the person's answers to a question on, as courier_answer does; a refusal, such as answers that do not fit, comes back as `problem`. */
@@ -33,6 +31,25 @@ export declare function registerPersonRpc(rpc: Pick<Plugin.Context["rpc"], "regi
                 readonly sessionID: import("effect/Schema").String;
             }>;
             readonly output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly top: string;
+                readonly sessions: readonly {
+                    readonly sessionID: string;
+                    readonly title: string;
+                    readonly parentID: string;
+                    readonly depth: number;
+                    readonly group?: string | undefined;
+                }[];
+                readonly permissions: readonly {
+                    readonly sessionID: string;
+                    readonly resources: readonly string[];
+                    readonly action: string;
+                    readonly requestID: string;
+                    readonly save?: readonly string[] | undefined;
+                    readonly passesOn?: {
+                        readonly sessionID: string;
+                        readonly requestID: string;
+                    } | undefined;
+                }[];
                 readonly questions: readonly {
                     readonly questions: readonly {
                         readonly options: readonly {
@@ -47,13 +64,7 @@ export declare function registerPersonRpc(rpc: Pick<Plugin.Context["rpc"], "regi
                     readonly requestID: string;
                     readonly stopped?: boolean | undefined;
                 }[];
-                readonly permissions: readonly {
-                    readonly sessionID: string;
-                    readonly resources: readonly string[];
-                    readonly action: string;
-                    readonly requestID: string;
-                    readonly save?: readonly string[] | undefined;
-                }[];
+            }, {
                 readonly top: string;
                 readonly sessions: readonly {
                     readonly sessionID: string;
@@ -62,8 +73,17 @@ export declare function registerPersonRpc(rpc: Pick<Plugin.Context["rpc"], "regi
                     readonly depth: number;
                     readonly group?: string | undefined;
                 }[];
-                readonly truncated?: number | undefined;
-            }, {
+                readonly permissions: readonly {
+                    readonly sessionID: string;
+                    readonly resources: readonly string[];
+                    readonly action: string;
+                    readonly requestID: string;
+                    readonly save?: readonly string[] | undefined;
+                    readonly passesOn?: {
+                        readonly sessionID: string;
+                        readonly requestID: string;
+                    } | undefined;
+                }[];
                 readonly questions: readonly {
                     readonly questions: readonly {
                         readonly options: readonly {
@@ -78,22 +98,6 @@ export declare function registerPersonRpc(rpc: Pick<Plugin.Context["rpc"], "regi
                     readonly requestID: string;
                     readonly stopped?: boolean | undefined;
                 }[];
-                readonly permissions: readonly {
-                    readonly sessionID: string;
-                    readonly resources: readonly string[];
-                    readonly action: string;
-                    readonly requestID: string;
-                    readonly save?: readonly string[] | undefined;
-                }[];
-                readonly top: string;
-                readonly sessions: readonly {
-                    readonly sessionID: string;
-                    readonly title: string;
-                    readonly parentID: string;
-                    readonly depth: number;
-                    readonly group?: string | undefined;
-                }[];
-                readonly truncated?: number | undefined;
             }> & import("effect/Schema").Struct<{
                 readonly top: import("effect/Schema").String;
                 readonly sessions: import("effect/Schema").$Array<import("effect/Schema").Struct<{
@@ -109,6 +113,10 @@ export declare function registerPersonRpc(rpc: Pick<Plugin.Context["rpc"], "regi
                     readonly action: import("effect/Schema").String;
                     readonly resources: import("effect/Schema").$Array<import("effect/Schema").String>;
                     readonly save: import("effect/Schema").optionalKey<import("effect/Schema").$Array<import("effect/Schema").String>>;
+                    readonly passesOn: import("effect/Schema").optionalKey<import("effect/Schema").Struct<{
+                        readonly sessionID: import("effect/Schema").String;
+                        readonly requestID: import("effect/Schema").String;
+                    }>>;
                 }>>;
                 readonly questions: import("effect/Schema").$Array<import("effect/Schema").Struct<{
                     readonly sessionID: import("effect/Schema").String;
@@ -124,7 +132,6 @@ export declare function registerPersonRpc(rpc: Pick<Plugin.Context["rpc"], "regi
                     }>>;
                     readonly stopped: import("effect/Schema").optionalKey<import("effect/Schema").Boolean>;
                 }>>;
-                readonly truncated: import("effect/Schema").optionalKey<import("effect/Schema").Int>;
             }>;
         };
         readonly answer: {