pi-roundtable 0.9.7 → 0.9.8

package/CHANGELOG.md

@@ -5,6 +5,19 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.8] - 2026-10-10
+
+### Added
+
+- A tool's `hold` may return a promise and takes the turn as a second argument, the `ToolTurn` its `run` receives (the speaker, the channel, the agent, and a `signal`), so a plugin can describe a held call with data it fetches as the current speaker, such as an entity's display name looked up with the speaker's own credentials. The confirmation gate awaits it before it posts the card, so the card, `ApprovalDetails.action` (the web chat's `approval.action`) and the held call carry the fetched text. It waits `HOLD_DESCRIBE_TIMEOUT_MS` (10 seconds, exported from `pi-roundtable/kit`); a rejection, a throw or a timeout holds the call under a generic description (`run <tool>`) and never lets it run. `signal` aborts when the turn stops or the wait ends, and a turn stopped meanwhile opens no card and holds nothing. Calls made together are held and shown in the order they were made, each with its own description.
+- `HoldRule.describeInTurn(tool, input, context, turn)`, the same for a hold rule of a plugin's `holdRules`: it may return a promise and the gate asks it instead of `describe` in a turn. `HoldCheck.inTurn` asks a chain's rules as a turn does. `describe` stays required and is what a host with no turn sees.
+
+### Changed
+
+- A hold that throws, not only one that rejects, is now held under a generic description in a turn; it used to fail the tool call. A hold that declares only its arguments and answers at once behaves exactly as before, and is still called with the arguments alone where a host checks the hold with no turn, such as a precheck script's tool call. A hold that declares `turn` is not called there: it is described as `run <tool>` and counts as held.
+- Hold lookups are awaited one tool call at a time, because the agent loop checks calls one after another: a message with N calls whose lookups hang waits up to N × `HOLD_DESCRIBE_TIMEOUT_MS`, and an approved call in the confirming turn still waits for its lookup. Keep lookups fast. This is documented in `docs/plugins.md`; behavior is unchanged.
+- A hold that declares `turn` through a wrapper (so its arity is not visible), or returns a thenable without `catch`, is now held as `run <tool>` where there is no turn, instead of failing with an obscure `TypeError`.
+
 ## [0.9.7] - 2026-10-10
 
 ### Added

package/docs/plugins.md

@@ -714,6 +714,38 @@ export const cleanup = definePlugin({
 ```
 <!-- /example -->
 
+#### A hold that looks things up
+
+A hold may need something it must fetch as the speaker before it can describe the call, such as the display name of the entity an id stands for, read with the speaker's own credentials.
+A tool's `hold` may then return a promise and takes the turn as a second argument: the `ToolTurn` its `run` receives, with the `speaker`, the `channel` and the `agent` of the turn that makes the call.
+
+```ts
+defineTool({
+	name: "ticket_close",
+	description: "Close a ticket.",
+	parameters: Type.Object({ id: Type.String() }),
+	minTier: "member",
+	hold: async ({ id }, turn) => {
+		const ticket = await tickets.get(id, turn.speaker, turn.signal);
+		return `Close ticket ${ticket.title}`;
+	},
+	run: ({ id }) => tickets.close(id),
+});
+```
+
+The gate awaits the description before it posts the card, so the card's bold line, the `action` of `ApprovalDetails` (the web chat's `approval.action`) and the held call all carry the fetched text.
+
+- `turn.signal` aborts when the turn stops, or when the wait ends. A turn stopped while its description is awaited opens no card and holds nothing.
+- The wait lasts `HOLD_DESCRIBE_TIMEOUT_MS` (10 seconds, exported from `pi-roundtable/kit`). A rejection, a throw or a timeout holds the call under a generic description (`run <tool>`, in the host's locale), never lets it run: the owner still sees the exact input on the card.
+- Returning `undefined` after the lookup lets the call run, as for a hold that answers at once.
+- Calls made together are held, and their cards opened, in the order they were made, each with its own description, whichever lookup returns first.
+- The agent loop runs one tool call's checks after another's, so hold lookups are awaited one call at a time: a model message with N calls whose lookups all hang waits up to N × `HOLD_DESCRIBE_TIMEOUT_MS` before the last card. This holds in the confirming turn too, where an already approved call still waits for its lookup before it is released. Keep lookups fast and give them a short timeout of their own.
+- 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.
+`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.
 It is asked when the input is not known yet, as for a [precheck script](#precheck-scripts-prechecks-the-agent-writes)'s call whose arguments are computed when it runs; a rule without it is judged by `describe` with an empty input.
 A rule whose held call stands for others can answer `approvalTier(tool, input, context)`: the lowest tier that may approve it when higher than the tool's own. The held call keeps it as `minTier`, and both its card and a confirming message require it. A card is answered, and a confirming message accepted, from the speaker whose turn held the call, when their tier is at least `minTier`, and from the owners where the conversation is shared ([who answers a prompt](#who-answers-a-prompt-promptscope)); nobody else in the channel may approve it. The held call records that speaker as `PendingConfirmation.speakerId` and their principal as `principalId`, so a confirming message from another identity of theirs counts after a restart too; a call held without them is the owners' to approve, and one held before 0.9, without a principal, is matched by `speakerId`.
@@ -2893,7 +2925,7 @@ It returns:
 |---|---|
 | `contribution` | What the plugin added, as the host would collect it: `tools`, `prompt`, `seeds`, `events`, `services`, `http`, and the rest |
 | `tools`, `tiers` | The tool names, and the table that says what tier each needs |
-| `holds` | The plugin's `holdRules` chained as the host links them (`holdChain`): `holds(tool, input, { workspace?, scratchDir? })` returns the description of a call that must be approved first, or `undefined` |
+| `holds` | The plugin's `holdRules` chained as the host links them (`holdChain`): `holds(tool, input, { workspace?, scratchDir? })` returns the description of a call that must be approved first, or `undefined`; `holds.inTurn(tool, input, context, turn)` asks them as a turn does, and returns a promise when a hold looks things up |
 | `runTool(name, args, { speaker, channel, workspace }?)` | Runs a tool the way an agent's turn would, in the channel (default `test:1`) for the speaker, and returns the text the model reads; `workspace` (`{ workspace, scratchDir? }`) is the session's `turn.workspace` |
 | `files` | Accepted files from `runTool`, recorded as `{ channel, file: ReplyFile }`; inject a surface with `supportsFiles: true` and pass its channel to test attachment tools |
 | `events` | The events the plugin itself reported through `context.events`, and those of `context.turns` |
@@ -3606,6 +3638,7 @@ Import from the entries listed below; source area files are internal.
 | `formatModelRef` | `pi-roundtable/kit` | value |
 | `headline` | `pi-roundtable/kit` | value |
 | `holdChain` | `pi-roundtable/kit` | value |
+| `HOLD_DESCRIBE_TIMEOUT_MS` | `pi-roundtable/kit` | value |
 | `COMPACT_HEADROOM_TOKENS` | `pi-roundtable/kit` | value |
 | `CompactionTiers` | `pi-roundtable/kit` | value |
 | `compactionEngine` | `pi-roundtable/kit` | value |

package/package.json

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

package/src/core/define.ts

@@ -1,17 +1,14 @@
 import type { Static, TObject } from "typebox";
-import {
-	AttachmentLookupError,
-	openAttachment,
-	type ToolAttachment,
-} from "./attachments/tool-attachment.ts";
+import type { ToolAttachment } from "./attachments/tool-attachment.ts";
 import type { ReplyFile } from "./domain/conversation.ts";
 import { PluginError } from "./errors.ts";
-import type { HoldRule } from "./holds.ts";
+import { type HoldRule, isPromise } from "./holds.ts";
+import { messages } from "./i18n/index.ts";
 import { type RoundtablePlugin, refuseRemovedFields } from "./plugin.ts";
-import { attachReplyFile } from "./reply-files.ts";
 import type { AgentTurnScope, ChannelKey, SessionTool } from "./sessions.ts";
 import { toolError, toolText } from "./shared/tool-result.ts";
 import { type Speaker, TIERS, type Tier } from "./speakers.ts";
+import { toolTurn } from "./tool-turn.ts";
 
 /** Tool names are lowercase words joined by underscores, like every tool the core ships. */
 const TOOL_NAME = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/;
@@ -64,8 +61,22 @@ export interface ToolSpec<Schema extends TObject> {
 	minTier: Tier;
 	/** Whether agents carry the tool in their turns; default true. */
 	agent?: boolean;
-	/** A short description of what the call would do when it must wait for approval; undefined lets it run. */
-	hold?: (args: Static<Schema>) => string | undefined;
+	/**
+	 * A short description of what the call would do when it must wait for approval; undefined lets it
+	 * run. It may answer later, after looking something up as the turn's speaker, such as a name to
+	 * show instead of an id: `turn` is the turn `run` would get, and its `signal` aborts when the
+	 * turn stops or the wait ends. The owner's approval card waits for it up to
+	 * `HOLD_DESCRIBE_TIMEOUT_MS`; a rejection or a timeout holds the call under a generic
+	 * description, so a hold that fails never lets the call run. It must change nothing.
+	 *
+	 * 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.
+	 */
+	hold?: (
+		args: Static<Schema>,
+		turn: ToolTurn,
+	) => string | undefined | Promise<string | undefined>;
 	run(args: Static<Schema>, turn: ToolTurn): Promise<string> | string;
 }
 
@@ -124,29 +135,10 @@ export function defineTool<Schema extends TObject>(
 					execute: async (_toolCallId, params, signal) => {
 						try {
 							return toolText(
-								await spec.run(params as Static<Schema>, {
-									speaker: context.speaker(),
-									channel: context.turnChannel,
-									agent: context.agent,
-									signal,
-									...(context.workspace
-										? { workspace: context.workspace }
-										: {}),
-									attachFile: attachReplyFile,
-									attachment: async (file) => {
-										if (context.attachmentDir === undefined)
-											throw new ToolRefusal(
-												"this session keeps no attachments",
-											);
-										try {
-											return await openAttachment(context.attachmentDir, file);
-										} catch (error) {
-											if (error instanceof AttachmentLookupError)
-												throw new ToolRefusal(error.message);
-											throw error;
-										}
-									},
-								}),
+								await spec.run(
+									params as Static<Schema>,
+									toolTurn(context, signal),
+								),
 							);
 						} catch (error) {
 							if (error instanceof ToolRefusal) return toolError(error.message);
@@ -170,11 +162,38 @@ export function defineTool<Schema extends TObject>(
 		hold: {
 			name: `tool:${name}`,
 			describe: (tool, input) =>
-				tool === name ? hold(input as Static<Schema>) : undefined,
+				tool === name ? holdWithoutTurn(name, hold, input) : undefined,
+			describeInTurn: (tool, input, _context, turn) =>
+				tool === name ? hold(input as Static<Schema>, turn) : undefined,
 		},
 	};
 }
 
+/**
+ * A tool's hold as a host with no turn sees it: called with the arguments alone, unless it declares
+ * the turn, and described generically when it needs the turn or answers later.
+ */
+function holdWithoutTurn<Schema extends TObject>(
+	name: string,
+	hold: NonNullable<ToolSpec<Schema>["hold"]>,
+	input: Record<string, unknown>,
+): string | undefined {
+	if (hold.length >= 2) return messages().holdGeneric(name);
+	try {
+		const answer = (
+			hold as (
+				args: Static<Schema>,
+			) => string | undefined | Promise<string | undefined>
+		)(input as Static<Schema>);
+		if (!isPromise(answer)) return answer;
+		// Its answer is not waited for here; a rejection must not surface on its own.
+		Promise.resolve(answer).catch(() => undefined);
+	} catch {
+		// A hold that needs the turn without declaring it, or that fails: it still counts as held.
+	}
+	return messages().holdGeneric(name);
+}
+
 /**
  * Defines a plugin. It returns the plugin it was given, typed, after checking its name, so a
  * mistake shows where the plugin is written.

package/src/core/holds.ts

@@ -1,6 +1,13 @@
+import type { ToolTurn } from "./define.ts";
 import { PluginError } from "./errors.ts";
 import { type Tier, tierAtLeast } from "./speakers.ts";
 
+/**
+ * How long the confirmation gate waits for a hold that looks things up before it describes the
+ * call generically and holds it anyway, in milliseconds.
+ */
+export const HOLD_DESCRIBE_TIMEOUT_MS = 10_000;
+
 /** What a hold rule knows about the session making the call. */
 export interface HoldContext {
 	/** The shared workspace of a session with a shell; calls reaching outside it may be held. */
@@ -27,6 +34,20 @@ export interface HoldRule {
 	 * `describe` with an empty input.
 	 */
 	mayHold?(tool: string): boolean;
+	/**
+	 * `describe` for a rule that must look something up as the turn's speaker before it can describe
+	 * the call, which it may answer later. The confirmation gate asks it, instead of `describe`,
+	 * 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.
+	 */
+	describeInTurn?(
+		tool: string,
+		input: Record<string, unknown>,
+		context: HoldContext,
+		turn: ToolTurn,
+	): string | undefined | Promise<string | 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.
@@ -46,6 +67,17 @@ export type HoldCheck = ((
 ) => string | undefined) & {
 	/** The name of a rule that may hold some call of `tool` whatever its input; see `HoldRule.mayHold`. */
 	mayHold?(tool: string): string | undefined;
+	/**
+	 * The check as a turn runs it: each rule's `describeInTurn`, or its `describe` for a rule
+	 * without one, asked in order until one describes the call. It answers at once when every rule
+	 * asked did, and otherwise as a promise that rejects when a rule's does.
+	 */
+	inTurn?(
+		tool: string,
+		input: Record<string, unknown>,
+		context: HoldContext,
+		turn: ToolTurn,
+	): string | undefined | Promise<string | undefined>;
 	/** The highest tier any rule requires to approve the call; see `HoldRule.approvalTier`. */
 	approvalTier?(
 		tool: string,
@@ -81,6 +113,26 @@ export function holdChain(rules: readonly HoldRule[]): HoldCheck {
 		}
 		return undefined;
 	};
+	check.inTurn = (tool, input, context, turn) => {
+		const ask = (
+			from: number,
+		): string | undefined | Promise<string | undefined> => {
+			for (let at = from; at < rules.length; at++) {
+				const rule = rules[at];
+				if (!rule) continue;
+				const description = rule.describeInTurn
+					? rule.describeInTurn(tool, input, context, turn)
+					: rule.describe(tool, input, context);
+				if (isPromise(description))
+					return description.then((found) =>
+						found !== undefined ? found : ask(at + 1),
+					);
+				if (description !== undefined) return description;
+			}
+			return undefined;
+		};
+		return ask(0);
+	};
 	check.mayHold = (tool) => rules.find((rule) => rule.mayHold?.(tool))?.name;
 	check.approvalTier = (tool, input, context) =>
 		rules.reduce<Tier | undefined>(
@@ -90,3 +142,12 @@ export function holdChain(rules: readonly HoldRule[]): HoldCheck {
 		);
 	return check;
 }
+
+/** Whether a hold's answer comes later. */
+export function isPromise<T>(value: T | Promise<T>): value is Promise<T> {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		typeof (value as { then?: unknown }).then === "function"
+	);
+}

package/src/core/i18n/conversation.ts

@@ -28,6 +28,7 @@ export function conversationEn(ctx: CatalogContext) {
 		answerReturned: (text: string) => `↩️ Reply:\n${text}`,
 		thinkingAuto: "auto",
 		confirmTitle: (asker: string) => `${asker} wants to run this action`,
+		holdGeneric: (tool: string) => `run ${tool}`,
 		askTitle: (asker: string) => `${asker} has a question for you`,
 		cardFile: (path: string, bytes: number | undefined) =>
 			bytes === undefined
@@ -59,6 +60,7 @@ export function conversationZhTW(
 		answerReturned: (text: string) => `↩️ 回覆：\n${text}`,
 		thinkingAuto: "自動",
 		confirmTitle: (asker: string) => `${asker} 要執行這個動作`,
+		holdGeneric: (tool: string) => `執行 ${tool}`,
 		askTitle: (asker: string) => `${asker} 想問你`,
 		cardFile: (path: string, bytes: number | undefined) =>
 			bytes === undefined

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

@@ -1,10 +1,17 @@
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import type { ToolTurn } from "../../define.ts";
 import type {
 	HeldCall,
 	PendingConfirmation,
 } from "../../domain/conversation.ts";
 import type { HoldRefusal } from "../../domain/progress.ts";
-import { type HoldCheck, type HoldContext, higherTier } from "../../holds.ts";
+import {
+	HOLD_DESCRIBE_TIMEOUT_MS,
+	type HoldCheck,
+	type HoldContext,
+	higherTier,
+	isPromise,
+} from "../../holds.ts";
 import { messages } from "../../i18n/index.ts";
 import { type OwnerIdentity, ownerWords } from "../../identity.ts";
 import type { LateAnswer, Prompts } from "../../interactions/prompts.ts";
@@ -27,6 +34,20 @@ export function unexpired(
 		: pending;
 }
 
+/** The turn a hold that looks things up sees; see `HoldRule.describeInTurn`. */
+export interface HoldTurn {
+	/** Aborts when the turn stops; a call being described then opens no card. */
+	signal?: AbortSignal;
+	/** The turn a hold receives, with `signal` as the signal that ends its wait. */
+	toolTurn(signal: AbortSignal): ToolTurn;
+}
+
+/** The answer of a description wait the turn's stop cut short. */
+const STOPPED = Symbol("stopped");
+
+/** What waiting for a call's description comes to: its text, or the turn stopped first. */
+type Described = string | undefined | typeof STOPPED;
+
 /** JSON with object keys sorted at every level, so equal inputs compare equal. */
 // pi-lens-ignore: no-unknown-parameters — tool input is untyped model JSON; this is where it is read
 export function canonicalJson(value: unknown): string {
@@ -79,12 +100,18 @@ export class ConfirmationGate {
 	readonly #tiers: ToolTiers | undefined;
 	/** Where the session's relative file paths resolve, for the sizes a card shows. */
 	readonly #fileRoot: string | undefined;
+	readonly #describeTimeoutMs: number;
+	/** Settles when the descriptions asked for so far have all been used, in the order they were asked. */
+	#describing: Promise<void> = Promise.resolve();
+	/** Descriptions asked for and not used yet. */
+	#undescribed = 0;
 
 	/**
 	 * `holds` decides which calls wait for the owner. With a workspace, the session has a shell,
 	 * and its writes outside the workspace and the context's scratch dir are held too.
 	 * `fileRoot` is the session's working directory, where a card resolves relative file paths;
-	 * it defaults to the workspace.
+	 * it defaults to the workspace. A hold that looks things up gets `describeTimeoutMs` to answer
+	 * (`HOLD_DESCRIBE_TIMEOUT_MS` by default) before its call is held under a generic description.
 	 */
 	constructor(
 		holds: HoldCheck,
@@ -93,7 +120,9 @@ export class ConfirmationGate {
 		context: HoldContext = {},
 		tiers?: ToolTiers,
 		fileRoot?: string,
+		describeTimeoutMs = HOLD_DESCRIBE_TIMEOUT_MS,
 	) {
+		this.#describeTimeoutMs = describeTimeoutMs;
 		this.#tiers = tiers;
 		this.#fileRoot = fileRoot ?? context.workspace;
 		this.#holds = holds;
@@ -144,26 +173,32 @@ export class ConfirmationGate {
 		tool: string,
 		input: Record<string, unknown>,
 		ask?: { prompts: Prompts; asker: string; signal?: AbortSignal },
+		turn?: HoldTurn,
 	): Promise<string | undefined> {
-		return (await this.decide(tool, input, ask)).reason;
+		return (await this.decide(tool, input, ask, turn)).reason;
 	}
 
 	/**
 	 * `review`, plus whether a card's approval released the call, so its result can say so:
 	 * the card's own message is shown to the person, never to the model. When a hold refuses the
 	 * call, `refused` says how, for the turn's progress to report beside the failed result.
+	 * With `turn`, a hold that looks things up as the turn's speaker is waited for before any card
+	 * opens, and a turn that stops meanwhile opens none.
 	 */
 	async decide(
 		tool: string,
 		input: Record<string, unknown>,
 		ask?: { prompts: Prompts; asker: string; signal?: AbortSignal },
+		turn?: HoldTurn,
 	): Promise<{
 		reason?: string;
 		approvedOnCard?: true;
 		/** Why a hold refused the call, for a surface that tells that from a failure; absent when it ran or the turn stopped. */
 		refused?: HoldRefusal;
 	}> {
-		const call = this.#needing(tool, input);
+		const found = this.#needingIn(tool, input, turn);
+		const call = isPromise(found) ? await found : found;
+		if (call === STOPPED) return { reason: "The turn was stopped." };
 		if (!call) return {};
 		if (!ask) return { reason: this.#record(call), refused: "held" };
 		const answer = await ask.prompts.confirm(
@@ -210,10 +245,112 @@ export class ConfirmationGate {
 
 	/** The call when it needs the owner's confirmation and no approval releases it. */
 	#needing(tool: string, input: Record<string, unknown>): HeldCall | undefined {
-		const context = this.#context;
-		const action = this.#holds(tool, input, context);
-		if (!action) return undefined;
-		const minTier = this.#holds.approvalTier?.(tool, input, context);
+		const action = this.#holds(tool, input, this.#context);
+		return action ? this.#unlessApproved(tool, input, action) : undefined;
+	}
+
+	/**
+	 * `#needing` inside a turn, where a hold may look things up first: the call when it needs the
+	 * owner's confirmation, or `STOPPED` when the turn stopped while its description was awaited.
+	 * It answers at once when every hold asked does and no earlier call is still being described.
+	 */
+	#needingIn(
+		tool: string,
+		input: Record<string, unknown>,
+		turn: HoldTurn | undefined,
+	):
+		| HeldCall
+		| undefined
+		| typeof STOPPED
+		| Promise<HeldCall | undefined | typeof STOPPED> {
+		const inTurn = this.#holds.inTurn;
+		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>;
+		try {
+			answer = inTurn.call(
+				this.#holds,
+				tool,
+				input,
+				this.#context,
+				turn.toolTurn(controller.signal),
+			);
+		} catch {
+			answer = messages().holdGeneric(tool);
+		}
+		const described: Described | Promise<Described> = isPromise(answer)
+			? this.#awaited(answer, tool, controller, turn.signal)
+			: answer;
+		return this.#inOrder(described, (action) => {
+			if (action === STOPPED) return STOPPED;
+			return action ? this.#unlessApproved(tool, input, action) : undefined;
+		});
+	}
+
+	/**
+	 * What a hold that answers later comes to: its text; the generic description when it rejects or
+	 * outlasts the timeout, so the call is still held; `STOPPED` when the turn stops first. Whatever
+	 * the hold is still doing is aborted when the wait ends.
+	 */
+	#awaited(
+		answer: Promise<string | undefined>,
+		tool: string,
+		hold: AbortController,
+		stop: AbortSignal | undefined,
+	): Promise<Described> {
+		return new Promise<Described>((resolve) => {
+			const onStop = () => end(STOPPED);
+			const timer = setTimeout(
+				() => end(messages().holdGeneric(tool)),
+				this.#describeTimeoutMs,
+			);
+			let ended = false;
+			const end = (described: Described) => {
+				if (ended) return;
+				ended = true;
+				clearTimeout(timer);
+				stop?.removeEventListener("abort", onStop);
+				hold.abort();
+				resolve(described);
+			};
+			// Handled first, so a rejection after the wait ended is never left unhandled.
+			answer.then(end, () => end(messages().holdGeneric(tool)));
+			if (stop?.aborted) return end(STOPPED);
+			stop?.addEventListener("abort", onStop, { once: true });
+		});
+	}
+
+	/**
+	 * Hands `described` to `use` after every description asked for before it has been used, so
+	 * calls made together are held, and their cards opened, in the order they were made whichever
+	 * description comes back first.
+	 */
+	#inOrder<T, R>(
+		described: T | Promise<T>,
+		use: (described: T) => R,
+	): R | Promise<R> {
+		if (this.#undescribed === 0 && !isPromise(described)) return use(described);
+		this.#undescribed++;
+		const used = this.#describing.then(() => described).then(use);
+		this.#describing = used.then(
+			() => {
+				this.#undescribed--;
+			},
+			() => {
+				this.#undescribed--;
+			},
+		);
+		return used;
+	}
+
+	/** The call for `action`, unless an approval releases it, which that approval then spends. */
+	#unlessApproved(
+		tool: string,
+		input: Record<string, unknown>,
+		action: string,
+	): HeldCall | undefined {
+		const minTier = this.#holds.approvalTier?.(tool, input, this.#context);
 		const call: HeldCall = {
 			tool,
 			input: canonicalJson(input),
@@ -269,10 +406,14 @@ export function confirmedTurnText(
 	return `(${owner.name} approved the held actions below with this message. Make each call now with exactly this input.)\n${calls}\n\n${text}`;
 }
 
-/** Without a slot, or with an empty one, every call that needs confirmation is held. */
+/**
+ * Without a slot, or with an empty one, every call that needs confirmation is held. `turnOf` builds
+ * the turn a hold that looks things up receives; without it, such a hold is not asked in a turn.
+ */
 export function confirmationGateExtension(
 	gate: ConfirmationGate,
 	slot?: PromptSlot,
+	turnOf?: (signal: AbortSignal) => ToolTurn,
 ): ExtensionFactory {
 	return (pi) => {
 		/** Calls a card's approval released, until their results are back. */
@@ -293,10 +434,14 @@ export function confirmationGateExtension(
 				ask = { prompts, asker: slot.asker };
 				if (ctx.signal) ask.signal = ctx.signal;
 			}
+			const turn: HoldTurn | undefined = turnOf
+				? { toolTurn: turnOf, ...(ctx.signal ? { signal: ctx.signal } : {}) }
+				: undefined;
 			const { reason, approvedOnCard, refused } = await gate.decide(
 				event.toolName,
 				event.input as Record<string, unknown>,
 				ask,
+				turn,
 			);
 			if (approvedOnCard) approved.add(event.toolCallId);
 			if (refused) slot?.refuse(event.toolCallId, refused);

package/src/core/runtime/session-factory.ts

@@ -31,6 +31,7 @@ import { packageDir } from "../shared/package-dir.ts";
 import { readAttachmentExtension } from "../shared/read-attachment-tool.ts";
 import { type Speaker, THE_SPEAKER } from "../speakers.ts";
 import { currentToolNames } from "../tool-tiers.ts";
+import { toolTurn } from "../tool-turn.ts";
 import {
 	CompactionTiers,
 	compactionEngine,
@@ -373,7 +374,9 @@ export class SessionFactory {
 				...(context.workspace
 					? { attachFile: attachFileExtension(context.workspace) }
 					: {}),
-				confirmationGate: confirmationGateExtension(gate, slot),
+				confirmationGate: confirmationGateExtension(gate, slot, (signal) =>
+					toolTurn(context, signal),
+				),
 				askUser: askUserExtension(slot, addressee, () =>
 					turnAddressee(
 						this.#deps.speaker(turnKey),

package/src/core/tool-turn.ts

@@ -0,0 +1,37 @@
+import {
+	AttachmentLookupError,
+	openAttachment,
+} from "./attachments/tool-attachment.ts";
+import type { ToolTurn } from "./define.ts";
+import { ToolRefusal } from "./define.ts";
+import { attachReplyFile } from "./reply-files.ts";
+import type { SessionContext } from "./sessions.ts";
+
+/**
+ * The turn a tool's `run` and `hold` receive, built from the session that makes the call and the
+ * signal that stops it.
+ */
+export function toolTurn(
+	context: SessionContext,
+	signal: AbortSignal | undefined,
+): ToolTurn {
+	return {
+		speaker: context.speaker(),
+		channel: context.turnChannel,
+		agent: context.agent,
+		signal,
+		...(context.workspace ? { workspace: context.workspace } : {}),
+		attachFile: attachReplyFile,
+		attachment: async (file) => {
+			if (context.attachmentDir === undefined)
+				throw new ToolRefusal("this session keeps no attachments");
+			try {
+				return await openAttachment(context.attachmentDir, file);
+			} catch (error) {
+				if (error instanceof AttachmentLookupError)
+					throw new ToolRefusal(error.message);
+				throw error;
+			}
+		},
+	};
+}

package/src/kit/holds.ts

@@ -1,4 +1,5 @@
 // Plugin helpers, versioned like the main entry; see the plugin guide.
-// The chain a host links from every plugin's hold rules, to test a rule set as the host runs it.
+// The chain a host links from every plugin's hold rules, to test a rule set as the host runs it,
+// and how long a hold that looks things up may take.
 
-export { holdChain } from "../core/holds.ts";
+export { HOLD_DESCRIBE_TIMEOUT_MS, holdChain } from "../core/holds.ts";

package/src/kit/index.ts

@@ -52,7 +52,7 @@ export {
 	THINKING_LEVELS,
 	thinkingLabel,
 } from "./domain.ts";
-export { holdChain } from "./holds.ts";
+export { HOLD_DESCRIBE_TIMEOUT_MS, holdChain } from "./holds.ts";
 export type {
 	JevCompactInput,
 	JevCompactOptions,

package/src/testing.ts

@@ -249,7 +249,7 @@ export interface RecordedEvent {
 
 export interface TestPluginResult {
 	contribution: Contribution;
-	/** The hold rules the plugin contributed, chained as the host links them: the description of a call that must be approved first, or undefined. */
+	/** The hold rules the plugin contributed, chained as the host links them: the description of a call that must be approved first, or undefined. `holds.inTurn(tool, input, context, turn)` asks them as a turn does, so a hold that looks things up (and may return a promise) is called with the turn; the plain call has no turn, and counts a hold that declares `turn` as held under `run <tool>`. */
 	holds: HoldCheck;
 	/** What the plugin sees as `context.conversations`, for a test to drive its claims. */
 	conversations: ConversationPort;