pi-roundtable 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-10-13
+
+### Added
+
+- A held tool call's approval card can carry a copy button. A tool's `hold`, and a hold rule's `describeInTurn`, may answer `HoldDescription` (new type, exported from `pi-roundtable`): the description as before, or `{ text, copy? }` with `copy` (`{ label?, text }`, as `ApprovalDetails.copy`) for the card to offer; the confirmation gate puts it in the `ApprovalDetails` it builds, so every limit of `ApprovalDetails.copy` applies (Discord's button, `discord.cardCopies`, the 20,000 character cap, the web chat's `approval.copy`). It shares the description's wait and failure: a rejection, a throw or a timeout holds the call under the generic description with no copy, and a `copy` that is not a non-empty text is left out. The copy is not kept with the held call, so a confirmation by message after a restart has no button; a host with no turn (a precheck script's call) uses `text`. A hold that answers a string is unchanged, as is `holdChain(rules).inTurn(...)` for rules that do.
+- `ChannelContextOptions.foreignWebhook` may return `"skip"` as well as a boolean (`(webhookId: string) => boolean | "skip"`): a post through that webhook of the application is dropped from the channel context and does not end the window, as if it were not in the channel, for a plugin whose own status notices go through a webhook of their own. `true` and `false` mean what they did, and any other answer reads as false. A skipped post is still one of the `fetch` messages read, so it uses that budget.
+
+### Changed
+
+- Code that reads a hold through `HoldCheck.inTurn`, `holdChain(rules)`, `testPlugin().holds.inTurn`, a wrapped `describeInTurn` or `ToolSpec.hold` now gets a `HoldDescription` (a string or `{ text, copy? }`) where it got a string; `ChannelContextOptions.foreignWebhook` may return the truthy `"skip"`, so a caller that treats its answer as a boolean should compare with `true`.
+
 ## [0.11.0] - 2026-10-13
 
 ### Added

package/README.md

@@ -186,7 +186,7 @@ Tune it under `discord.channelContext`, or set `channelContext: false` to turn i
 | `similarity` | `0.8` | How alike two consecutive messages of one author must be to count as one |
 | `messageChars` | `500` | Where a message is cut |
 | `botMessageChars` | `80` | Where another bot's message is cut |
-| `foreignWebhook` | none | `(webhookId) => boolean`: posts through those webhooks of the application are read as other people's messages, not the assistant's (code only) |
+| `foreignWebhook` | none | `(webhookId) => boolean \| "skip"`: posts through the webhooks it returns true for are read as other people's messages, not the assistant's; `"skip"` drops a webhook's posts as if absent, without ending the window (code only) |
 | `attachments` | `{ images: 0, maxBytes: 10 MiB }` | `images`: how many images of the kept messages are fetched for the turn, at most 4 |
 
 When a conversation is started over in a server channel or thread, the assistant posts a short divider there so the next turn does not read what came before; direct messages get none.

package/README.zh-TW.md

@@ -181,7 +181,7 @@ export default {
 | `similarity` | `0.8` | 同一作者相鄰兩則訊息相似到什麼程度算同一則 |
 | `messageChars` | `500` | 訊息截斷的長度 |
 | `botMessageChars` | `80` | 其他 bot 訊息截斷的長度 |
-| `foreignWebhook` | 無 | `(webhookId) => boolean`：經由這些 webhook 發出的貼文視為別人的訊息，不是助理自己的（只能用程式碼設定） |
+| `foreignWebhook` | 無 | `(webhookId) => boolean \| "skip"`：回傳 true 的 webhook 所發的貼文視為別人的訊息，不是助理自己的；回傳 `"skip"` 則把該 webhook 的貼文當作不存在，不納入也不截斷範圍（只能用程式碼設定） |
 | `attachments` | `{ images: 0, maxBytes: 10 MiB }` | `images`：替這一輪抓取保留訊息中的幾張圖片，最多 4 張 |
 
 核准卡和 `ask_user` 問題會讓這一輪等 `discord.cardGraceSeconds` 秒（預設 `120`）。

package/docs/plugins.md

@@ -810,7 +810,18 @@ The gate awaits the description before it posts the card, so the card's bold lin
 - A hold must change nothing: it may be called again for the same call, such as when the owner's confirming message makes the call again.
 - A hold that declares only its arguments and answers at once is called as it always was. Where a host checks the hold with no turn, such as the `holds` of a test harness or a [precheck script](#precheck-scripts-prechecks-the-agent-writes)'s tool call, a hold that declares `turn` is not called; it is described as `run <tool>` and so counts as held.
 
-A rule of `holdRules` does the same with `describeInTurn(tool, input, context, turn)`, which may return a promise and which the gate asks instead of `describe` in a turn.
+A hold may also offer the owner's approval card a text to copy, such as the whole message a call would send, by answering `{ text, copy }` (the type `HoldDescription`: the description alone, or `{ text, copy?: { label?, text } }`) instead of the description:
+
+```ts
+hold: async ({ customer, body }, turn) => ({
+	text: `Send a message to ${(await customers.get(customer, turn.speaker, turn.signal)).name}`,
+	copy: { label: "Copy message", text: body },
+}),
+```
+
+`text` is the description, with every behaviour above; `copy` goes to the gate's `ApprovalDetails.copy` for that call, so the Discord card gets the [copy button](#who-answers-a-prompt-promptscope) with all of its limits (the 20,000 character cap, the label, `discord.cardCopies`), and the web chat forwards it as `approval.copy`. It is part of the same answer, so a rejection, a throw or a timeout drops it with the description: the call is held under the generic description with no copy, and the exact input is still on the card. A `copy` whose `text` is not a non-empty string is left out and the call is still held. The copy is not kept with the held call (`HeldCall` has no copy), so a card the owner answers by a message after a restart has no button, and a host that shows no card, or that checks the hold with no turn, such as a precheck script's call, uses `text` and ignores `copy`. A hold that answers a plain string is unchanged. The copy is visible to anyone who sees the card, so it holds nothing they may not read.
+
+A rule of `holdRules` does the same with `describeInTurn(tool, input, context, turn)`, which may return a promise, and a `HoldDescription` as well as a string, and which the gate asks instead of `describe` in a turn.
 `describe` is still required and is what a host without a turn sees. `holdChain(rules).inTurn(tool, input, context, turn)` asks the rules as a turn does, in order: each rule's `describeInTurn`, or its `describe` for a rule without one.
 
 A rule whose verdict depends on the input, such as one that holds only a `delete` action, can also answer `mayHold(tool)`: whether it may hold some call of that tool. A rule with `approversInTurn` whose answer depends on the input can likewise answer `mayName(tool)`: whether it may name approvers for some call of that tool; without it the rule is taken to name approvers for every tool.
@@ -2281,14 +2292,14 @@ It reads Discord, not the host's history, so it survives restarts:
 - It keeps the newest `keep` (default 15), oldest first. Mentions read as names, and stickers and files as text with their names and links; by default nothing is downloaded or shown to the model as an image (see `attachments` below). A message is cut at `messageChars` (default 500), another bot's at `botMessageChars` (default 80).
 - It never fails the turn over Discord: a Discord error, such as a channel the bot cannot read, is logged and the turn runs without context.
 
-A plugin may mirror an outside chat into a channel through a webhook of its own, created by the bot, so that the application owns it; by default such a post counts as the assistant's own, which ends the window and is left out, and the people mirrored never reach a turn. `foreignWebhook(webhookId)` changes that for the webhooks it returns true for: a post through one is another author's, kept like another bot's (`bot: true`, `authorName` the post's username, `authorId` the webhook's id) and no longer ends the window, which then ends only at the assistant's own posts: its bot user's and every webhook `foreignWebhook` returns false for, such as an agent's voice. The host sets it as `discord.channelContext.foreignWebhook` and a call overrides it for that call; being a function, it can be set only in code. Posts through a webhook that `foreignWebhook` returns true for are merged as near repeats only when the poster's name is the same too, since one webhook carries many people; every other message merges by author alone, as before. An edited message reads as Discord now holds it.
+A plugin may mirror an outside chat into a channel through a webhook of its own, created by the bot, so that the application owns it; by default such a post counts as the assistant's own, which ends the window and is left out, and the people mirrored never reach a turn. `foreignWebhook(webhookId)` changes that for the webhooks it returns true for: a post through one is another author's, kept like another bot's (`bot: true`, `authorName` the post's username, `authorId` the webhook's id) and no longer ends the window, which then ends only at the assistant's own posts: its bot user's and every webhook `foreignWebhook` returns false for, such as an agent's voice. It may also return `"skip"` for a webhook that is neither, such as one the plugin posts its own status notices through: a post through it is dropped from the context and does not end the window, as if it were not in the channel, so notices between two mirrored posts neither appear as someone's words nor cut the window, and they are not counted among the messages delivered. Any answer other than `true` and `"skip"` reads as false. A skipped post is still one of the `fetch` messages read, so it uses the budget the window is chosen from. The host sets it as `discord.channelContext.foreignWebhook` and a call overrides it for that call; being a function, it can be set only in code. Posts through a webhook that `foreignWebhook` returns true for are merged as near repeats only when the poster's name is the same too, since one webhook carries many people; every other message merges by author alone, as before. An edited message reads as Discord now holds it.
 
 Every returned message has `attachments` (`ChannelContextAttachment`: `name`, `contentType`, `size`, `url`, `messageId`), whether or not anything was fetched. With `attachments: { images, maxBytes }` (`ChannelContextAttachmentOptions`; default none) a call also fetches up to `images` (at most 4, a turn's limit) PNG, JPEG, GIF or WebP images of the kept messages, the newest first, each at most `maxBytes` (default 10 MiB, at most 25 MiB), and returns them as `context.images`, prepared as a turn's own images are (large ones are scaled down) and kept in memory by this call and never logged; once a turn is given them they are in its session history like the turn's own images, and stay there. Pass them on with `withChannelContextImages(attachments, context)`, which returns `{ attachments, kept }`: the turn's attachments with the context's images after the turn's own, within the four a turn carries, and how many of them fitted (a turn that already carries four keeps none, and an image crowded out is not noted anywhere). Give `kept` to `withChannelContext(text, context, kept)`: above zero it adds a line that pictures are shown among the turn's images, and it adds none otherwise, so the block never claims images the turn does not have. The image is sent as the type its bytes show (PNG, JPEG, GIF or WebP), not as Discord's guess from the file name, and bytes of none of them are skipped as `unsupported type`. Up to two images are downloaded at once, within 20 seconds for the whole call; the images still to be fetched when it passes are skipped as `download failed`. An image that is not a type the model takes, is over `maxBytes`, cannot be downloaded or cannot be decoded is skipped, and its message's text says `[image not attached: <name>: <reason>]`, the reason being `unsupported type` (by Discord's type or by the bytes), `too large`, `download failed` or `could not be decoded`; skipped images do not count toward `images`, but at most twice that many are tried. An image of a message already handed over is not fetched again, since its message is not returned again.
 
 `DISCORD.channelContext` resolves undefined in a direct message, on another surface, when nothing new was said, and when the host's `discord.channelContext` is `false`, which turns it off for the agent server and every claim.
 The configuration's values are the host's defaults, and a call's `options` override them for that call.
 Call it once per answered message: what it returns is remembered as handed over.
-A call's `options` are validated like the configuration (`fetch`, `keep`, `messageChars` and `botMessageChars` positive integers, `similarity` from 0 to 1, `foreignWebhook` a function, `attachments.images` an integer from 0 to 4, `attachments.maxBytes` an integer from 1 to 25 MiB); an invalid one makes the call reject, a programming error, so `keep: 0` is not "none" (skip the call for that).
+A call's `options` are validated like the configuration (`fetch`, `keep`, `messageChars` and `botMessageChars` positive integers, `similarity` from 0 to 1, `foreignWebhook` a function of a webhook id returning `true`, `false` or `"skip"`, `attachments.images` an integer from 0 to 4, `attachments.maxBytes` an integer from 1 to 25 MiB); an invalid one makes the call reject, a programming error, so `keep: 0` is not "none" (skip the call for that).
 It remembers what it handed over and what addressed the assistant, not every message that ran a turn: a post a claim answered some other way, such as a webhook report turn or a steered message, can also come in the context of a later turn if the assistant has not posted since.
 
 What it returns is public channel text, visible to everyone in the channel; it is not private memory, carries no `privateTo`, and goes into the turn's text, so it lives in the conversation's history, not in the system prompt.
@@ -3550,6 +3561,7 @@ Import from the entries listed below; source area files are internal.
 | `HeldCall` | `pi-roundtable` | type |
 | `HoldCheck` | `pi-roundtable` | type |
 | `HoldContext` | `pi-roundtable` | type |
+| `HoldDescription` | `pi-roundtable` | type |
 | `HoldRefusal` | `pi-roundtable` | type |
 | `HoldRule` | `pi-roundtable` | type |
 | `HostEnv` | `pi-roundtable` | type |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.11.0",
+	"version": "0.12.0",
 	"description": "A plugin-driven Pi agent server for one owner, reached through Discord or the web",
 	"type": "module",
 	"license": "MIT",

package/src/core/config/adapters.ts

@@ -130,7 +130,7 @@ const channelContextShape = shape({
 	foreignWebhook: optional(
 		guarded(
 			"a function of a webhook id",
-			(value): value is (webhookId: string) => boolean =>
+			(value): value is (webhookId: string) => boolean | "skip" =>
 				typeof value === "function",
 		),
 	),

package/src/core/contract/channel-context.ts

@@ -29,8 +29,13 @@ export interface ChannelContextOptions {
 	 * plugin mirrors into the channel through a webhook of its own are read. The assistant's own
 	 * posts, which end the window, stay its bot user and every webhook this returns false for, such
 	 * as an agent's voice. Default: none, every webhook of the application is the assistant's.
+	 *
+	 * `"skip"` is for a webhook that is neither: one the plugin posts its own status notices
+	 * through. A post through it is dropped from the context and does not end the window, as if it
+	 * were not in the channel; it is not another author's words and not the assistant's answer.
+	 * Only `true` and `"skip"` change anything; any other answer reads as false.
 	 */
-	foreignWebhook?: (webhookId: string) => boolean;
+	foreignWebhook?: (webhookId: string) => boolean | "skip";
 	/** Which attachments of the kept messages are fetched for the turn; none by default. */
 	attachments?: ChannelContextAttachmentOptions;
 }

package/src/core/define.ts

@@ -6,7 +6,7 @@ import type {
 import type { ClientPort } from "./domain/client.ts";
 import type { ReplyFile } from "./domain/conversation.ts";
 import { PluginError } from "./errors.ts";
-import { type HoldRule, isPromise } from "./holds.ts";
+import { type HoldDescription, type HoldRule, isPromise } from "./holds.ts";
 import { messages } from "./i18n/index.ts";
 import type { ApprovedBy } from "./interactions/prompts.ts";
 import { type RoundtablePlugin, refuseRemovedFields } from "./plugin.ts";
@@ -110,11 +110,18 @@ export interface ToolSpec<Schema extends TObject> {
 	 * A host that checks the hold with no turn, such as a precheck script's call, never calls a hold
 	 * that declares `turn`; it sees the generic description. A hold that declares only `args` and
 	 * answers at once is called there as it always was.
+	 *
+	 * Instead of the description alone it may answer `{ text, copy }`, where `copy` (`{ label?, text }`)
+	 * is a text the owner's approval card offers to copy, such as the whole message the call would
+	 * send; see `ApprovalDetails.copy` for what a surface does with it and its limits. It is the same
+	 * answer as the description, so it shares its wait and its failure: a hold that rejects or
+	 * outlasts the timeout holds the call with the generic description and no copy. A host with no
+	 * card, or that checks the hold with no turn, uses `text` and ignores `copy`.
 	 */
 	hold?: (
 		args: Static<Schema>,
 		turn: ToolTurn,
-	) => string | undefined | Promise<string | undefined>;
+	) => HoldDescription | undefined | Promise<HoldDescription | undefined>;
 	/**
 	 * The principal ids that may approve this call when it is held, instead of the speaker whose
 	 * turn makes it, looked up as that turn like `hold` (same wait, same `turn.signal`, and it
@@ -253,9 +260,18 @@ function holdWithoutTurn<Schema extends TObject>(
 		const answer = (
 			hold as (
 				args: Static<Schema>,
-			) => string | undefined | Promise<string | undefined>
+			) => HoldDescription | undefined | Promise<HoldDescription | undefined>
 		)(input as Static<Schema>);
-		if (!isPromise(answer)) return answer;
+		if (!isPromise(answer)) {
+			if (answer === undefined || typeof answer === "string") return answer;
+			// An object without a non-empty text still holds the call, never lets it run.
+			return typeof answer === "object" &&
+				answer !== null &&
+				typeof answer.text === "string" &&
+				answer.text !== ""
+				? answer.text
+				: messages().holdGeneric(name);
+		}
 		// Its answer is not waited for here; a rejection must not surface on its own.
 		Promise.resolve(answer).catch(() => undefined);
 	} catch {

package/src/core/discord/channel-context.ts

@@ -241,11 +241,17 @@ export function selectChannelContext(
 	fetched: readonly ContextSourceMessage[],
 	{ seen, owners, settings }: ChannelContextSelection,
 ): { messages: ChannelContextMessage[]; window: string[] } {
-	const ordered = fetched.toSorted((a, b) => a.at - b.at);
-	// A webhook of the application that the host calls foreign speaks for other people, not for the assistant.
-	const foreign = (message: ContextSourceMessage) =>
-		message.webhookId !== undefined &&
-		settings.foreignWebhook?.(message.webhookId) === true;
+	// A webhook of the application that the host calls foreign speaks for other people, not for the
+	// assistant; one it calls "skip" speaks for no one: its posts are not in the channel as far as the
+	// window and the context go.
+	const verdict = (message: ContextSourceMessage) =>
+		message.webhookId === undefined
+			? undefined
+			: settings.foreignWebhook?.(message.webhookId);
+	const ordered = fetched
+		.filter((message) => verdict(message) !== "skip")
+		.toSorted((a, b) => a.at - b.at);
+	const foreign = (message: ContextSourceMessage) => verdict(message) === true;
 	const assistants = (message: ContextSourceMessage) =>
 		message.own && !foreign(message);
 	const lastOwn = ordered.findLastIndex(assistants);

package/src/core/holds.ts

@@ -1,5 +1,6 @@
 import type { ToolTurn } from "./define.ts";
 import { PluginError } from "./errors.ts";
+import type { ApprovalDetails } from "./interactions/prompts.ts";
 import { type Tier, tierAtLeast } from "./speakers.ts";
 
 /**
@@ -16,6 +17,14 @@ export interface HoldContext {
 	scratchDir?: string;
 }
 
+/**
+ * What a hold that runs in a turn answers with: the description of the call, or the description
+ * as `text` with a `copy` the owner's approval card offers beside it; see `ApprovalDetails.copy`.
+ */
+export type HoldDescription =
+	| string
+	| { text: string; copy?: NonNullable<ApprovalDetails["copy"]> };
+
 /**
  * Decides whether a tool call waits for the owner's approval. A rule answers with a short
  * description of what the call would do, or undefined when it has no opinion on the call.
@@ -40,14 +49,15 @@ export interface HoldRule {
 	 * when a turn makes the call, and waits for the answer up to `HOLD_DESCRIBE_TIMEOUT_MS`; a
 	 * rejection or a timeout holds the call under a generic description. `turn.signal` aborts when the
 	 * turn stops or the wait ends. `describe` stays what a host without a turn sees, such as a
-	 * precheck script's call, and answers at once.
+	 * precheck script's call, and answers at once. It may answer `{ text, copy }` instead of the
+	 * text alone, for the approval card to offer `copy`; a host that shows no card uses `text`.
 	 */
 	describeInTurn?(
 		tool: string,
 		input: Record<string, unknown>,
 		context: HoldContext,
 		turn: ToolTurn,
-	): string | undefined | Promise<string | undefined>;
+	): HoldDescription | undefined | Promise<HoldDescription | undefined>;
 	/**
 	 * The lowest tier that may approve a call this rule holds, when it is higher than the tool's own:
 	 * for a call that stands for others, such as saving a script whose runs make held calls.
@@ -98,7 +108,7 @@ export type HoldCheck = ((
 		input: Record<string, unknown>,
 		context: HoldContext,
 		turn: ToolTurn,
-	): string | undefined | Promise<string | undefined>;
+	): HoldDescription | undefined | Promise<HoldDescription | undefined>;
 	/** The highest tier any rule requires to approve the call; see `HoldRule.approvalTier`. */
 	approvalTier?(
 		tool: string,
@@ -150,7 +160,7 @@ export function holdChain(rules: readonly HoldRule[]): HoldCheck {
 	check.inTurn = (tool, input, context, turn) => {
 		const ask = (
 			from: number,
-		): string | undefined | Promise<string | undefined> => {
+		): HoldDescription | undefined | Promise<HoldDescription | undefined> => {
 			for (let at = from; at < rules.length; at++) {
 				const rule = rules[at];
 				if (!rule) continue;

package/src/core/runtime/extensions/approval-card.ts

@@ -150,12 +150,13 @@ function prefix(text: string, max: number): string {
 
 /**
  * A held call as data for a card that is not text: the action, the tool, the whole input, and
- * each file it sends by path with its size now (absent when unreadable). Unlike the text card,
- * nothing is cut and nothing is worded for a locale.
+ * each file it sends by path with its size now (absent when unreadable), and the `copy` its hold
+ * offered. Unlike the text card, nothing is cut and nothing is worded for a locale.
  */
 export function approvalDetails(
 	call: HeldCall,
 	workspace?: string,
+	copy?: ApprovalDetails["copy"],
 ): ApprovalDetails {
 	const files = pathFiles(call.input).map((path) => {
 		const bytes = fileSize(path, workspace);
@@ -166,6 +167,7 @@ export function approvalDetails(
 		tool: call.tool,
 		input: parsedInput(call.input),
 		...(files.length > 0 ? { files } : {}),
+		...(copy ? { copy } : {}),
 	};
 }
 

package/src/core/runtime/extensions/confirmation-gate.ts

@@ -39,6 +39,7 @@ import {
 	awaited,
 	type Described,
 	type HoldTurn,
+	type Judgment,
 	joinApprovers,
 	STOPPED,
 } from "./hold-lookups.ts";
@@ -284,7 +285,7 @@ export class ConfirmationGate {
 			ask.signal,
 			higherTier(this.#tiers?.minTier(call.tool), call.minTier),
 			{ late: (late) => this.#late(call, late) },
-			approvalDetails(call, this.#fileRoot),
+			approvalDetails(call, this.#fileRoot, needing.copy),
 			options,
 		);
 		if (answer === "approved") {
@@ -361,7 +362,7 @@ export class ConfirmationGate {
 		if (!turn || !inTurn) return this.#needing(tool, input);
 		const controller = new AbortController();
 		if (turn.signal?.aborted) controller.abort();
-		let answer: string | undefined | Promise<string | undefined>;
+		let answer: ReturnType<NonNullable<HoldCheck["inTurn"]>>;
 		try {
 			answer = inTurn.call(
 				this.#holds,
@@ -373,7 +374,7 @@ export class ConfirmationGate {
 		} catch {
 			answer = messages().holdGeneric(tool);
 		}
-		const described: Described | Promise<Described> = isPromise(answer)
+		const found: Described | Promise<Described> = isPromise(answer)
 			? awaited(
 					answer,
 					messages().holdGeneric(tool),
@@ -384,7 +385,7 @@ export class ConfirmationGate {
 			: answer;
 		return this.#inOrder(
 			joinApprovers(
-				described,
+				found,
 				{
 					holds: this.#holds,
 					context: this.#context,
@@ -431,7 +432,7 @@ export class ConfirmationGate {
 	#unlessApproved(
 		tool: string,
 		input: Record<string, unknown>,
-		judged: { action: string; approvers?: readonly string[] },
+		judged: Judgment,
 	): Needing {
 		const minTier = this.#holds.approvalTier?.(tool, input, this.#context);
 		const call: HeldCall = {
@@ -448,7 +449,7 @@ export class ConfirmationGate {
 			const [spent] = approved === -1 ? [] : released.splice(approved, 1);
 			if (spent) return { released: spent.by };
 		}
-		return { held: call };
+		return { held: call, ...(judged.copy ? { copy: judged.copy } : {}) };
 	}
 
 	/** Records the call as held and returns what the model is told about it. */

package/src/core/runtime/extensions/gate-refusals.ts

@@ -3,7 +3,10 @@ import type {
 	PendingConfirmation,
 } from "../../domain/conversation.ts";
 import { type OwnerIdentity, ownerWords } from "../../identity.ts";
-import type { ApprovedBy } from "../../interactions/prompts.ts";
+import type {
+	ApprovalDetails,
+	ApprovedBy,
+} from "../../interactions/prompts.ts";
 import type { Speaker } from "../../speakers.ts";
 import { mayApproveNamed } from "./held-calls.ts";
 
@@ -23,7 +26,9 @@ export interface Release {
 }
 
 /** What a call needs of the gate: nothing, a hold, or a release that spends an approval. */
-export type Needing = { held: HeldCall } | { released: ApprovedBy | undefined };
+export type Needing =
+	| { held: HeldCall; copy?: NonNullable<ApprovalDetails["copy"]> }
+	| { released: ApprovedBy | undefined };
 
 /** The text for a held call that the speaker's own message confirms. */
 export function askSpeaker(addressee: OwnerIdentity, call: HeldCall): string {

package/src/core/runtime/extensions/hold-lookups.ts

@@ -1,5 +1,12 @@
 import type { ToolTurn } from "../../define.ts";
-import { type HoldCheck, type HoldContext, isPromise } from "../../holds.ts";
+import {
+	type HoldCheck,
+	type HoldContext,
+	type HoldDescription,
+	isPromise,
+} from "../../holds.ts";
+import { messages } from "../../i18n/index.ts";
+import type { ApprovalDetails } from "../../interactions/prompts.ts";
 
 /** The turn a hold that looks things up sees; see `HoldRule.describeInTurn`. */
 export interface HoldTurn {
@@ -13,13 +20,48 @@ export interface HoldTurn {
 export const STOPPED = Symbol("stopped");
 
 /** What waiting for a call's description comes to: its text, or the turn stopped first. */
-export type Described = string | undefined | typeof STOPPED;
+export type Described = HoldDescription | undefined | typeof STOPPED;
 
-/** A held call's description with who may approve it instead of the speaker; see `HoldRule.approversInTurn`. */
-export type Judged =
-	| { action: string; approvers?: readonly string[] }
-	| undefined
-	| typeof STOPPED;
+/**
+ * A held call's description, the text its card offers to copy, and who may approve it instead of
+ * the speaker; see `HoldRule.approversInTurn`.
+ */
+export interface Judgment {
+	action: string;
+	copy?: NonNullable<ApprovalDetails["copy"]>;
+	approvers?: readonly string[];
+}
+
+export type Judged = Judgment | undefined | typeof STOPPED;
+
+/**
+ * A hold's description as the action and the copy it carries. An answer that is neither a text
+ * nor a text with a copy still holds the call, under the generic description; a copy that is not
+ * a non-empty text is left out, so a hold that gets it wrong never lets the call run.
+ */
+export function described(
+	answer: HoldDescription,
+	tool: string,
+): { action: string; copy?: NonNullable<ApprovalDetails["copy"]> } {
+	if (typeof answer === "string") return { action: answer };
+	if (typeof answer !== "object" || answer === null)
+		return { action: messages().holdGeneric(tool) };
+	const { text, copy } = answer;
+	if (typeof text !== "string") return { action: messages().holdGeneric(tool) };
+	if (
+		!copy ||
+		typeof copy !== "object" ||
+		typeof copy.text !== "string" ||
+		copy.text === ""
+	)
+		return { action: text };
+	const label = typeof copy.label === "string" ? copy.label : undefined;
+	return {
+		action: text,
+		copy:
+			label === undefined ? { text: copy.text } : { label, text: copy.text },
+	};
+}
 
 /**
  * What a lookup that answers later comes to: its answer; `fallback` when it rejects or outlasts
@@ -58,16 +100,17 @@ export function awaited<T>(
  * none, so only the owners approve the call. A call no rule holds asks no one.
  */
 export function joinApprovers(
-	described: Described | Promise<Described>,
+	answer: Described | Promise<Described>,
 	from: { holds: HoldCheck; context: HoldContext; timeoutMs: number },
 	tool: string,
 	input: Record<string, unknown>,
 	turn: HoldTurn,
 ): Judged | Promise<Judged> {
 	const lookup = from.holds.approversInTurn;
-	if (!lookup) return withoutApprovers(described);
+	if (!lookup) return withoutApprovers(answer, tool);
 	const join = (action: Described): Judged | Promise<Judged> => {
 		if (action === STOPPED || action === undefined) return action;
+		const { action: text, copy } = described(action, tool);
 		const controller = new AbortController();
 		if (turn.signal?.aborted) controller.abort();
 		let named:
@@ -87,22 +130,31 @@ export function joinApprovers(
 		}
 		if (!isPromise(named)) {
 			controller.abort();
-			return named ? { action, approvers: named } : { action };
+			return {
+				action: text,
+				...(copy ? { copy } : {}),
+				...(named ? { approvers: named } : {}),
+			};
 		}
 		return awaited(named, [], controller, turn.signal, from.timeoutMs).then(
 			(approvers) => {
 				if (approvers === STOPPED) return STOPPED;
-				return approvers ? { action, approvers } : { action };
+				return {
+					action: text,
+					...(copy ? { copy } : {}),
+					...(approvers ? { approvers } : {}),
+				};
 			},
 		);
 	};
-	return isPromise(described) ? described.then(join) : join(described);
+	return isPromise(answer) ? answer.then(join) : join(answer);
 }
 
 function withoutApprovers(
-	described: Described | Promise<Described>,
+	answer: Described | Promise<Described>,
+	tool: string,
 ): Judged | Promise<Judged> {
-	const wrap = (action: Described): Judged =>
-		action === STOPPED || action === undefined ? action : { action };
-	return isPromise(described) ? described.then(wrap) : wrap(described);
+	const wrap = (found: Described): Judged =>
+		found === STOPPED || found === undefined ? found : described(found, tool);
+	return isPromise(answer) ? answer.then(wrap) : wrap(answer);
 }

package/src/index.ts

@@ -147,7 +147,12 @@ export {
 	PluginError,
 	ProviderError,
 } from "./core/errors.ts";
-export type { HoldCheck, HoldContext, HoldRule } from "./core/holds.ts";
+export type {
+	HoldCheck,
+	HoldContext,
+	HoldDescription,
+	HoldRule,
+} from "./core/holds.ts";
 export type { HostEnvironment, RoundtableOptions } from "./core/host.ts";
 export { Roundtable } from "./core/host.ts";
 export type {