pi-roundtable 0.9.6 → 0.9.8

package/src/core/interactions/prompts.ts

@@ -3,17 +3,40 @@ import type { TurnRequest } from "../domain/ports.ts";
 import type { Speaker, Tier } from "../speakers.ts";
 
 /**
- * How a prompt ended: answered yes or no; `expired` when no one could answer it (no one's to
- * approve, or the card could not be posted); `cancelled` when its turn stopped; or `pending` when
- * the turn stopped waiting while the card stays open, its answer to come through `PromptWait`.
+ * How a prompt ended: answered yes or no; `expired` when the card was shown and no one answered
+ * it in time; `unavailable` when no card could be shown (no one may approve the call, the speaker
+ * is below its tier, or the card could not be posted); `cancelled` when its turn stopped; or
+ * `pending` when the turn stopped waiting while the card stays open, its answer to come through
+ * `PromptWait`. A surface that cannot tell the two may answer `expired` for both.
  */
 export type Approval =
 	| "approved"
 	| "declined"
 	| "expired"
+	| "unavailable"
 	| "cancelled"
 	| "pending";
 
+/** A file a held call sends by path; `bytes` is its size when it was read, absent when it could not be. */
+export interface ApprovalFile {
+	path: string;
+	bytes?: number;
+}
+
+/**
+ * What an approval is for, as data: the same facts a card's text shows, so a surface that is not
+ * text (a web client) need not read them back out of the markdown. `input` is the call's whole
+ * input, never cut.
+ */
+export interface ApprovalDetails {
+	/** What the call would do, in plain words. */
+	action: string;
+	tool: string;
+	input: Record<string, unknown>;
+	/** The files the call sends by path; absent when it sends none. */
+	files?: ApprovalFile[];
+}
+
 /** An answer given on a prompt after its turn stopped waiting; `by` names who gave it. */
 export type LateAnswer = { by: string } & (
 	| { kind: "approval"; approved: boolean }
@@ -80,7 +103,7 @@ export interface PromptScope {
 	/**
 	 * Who else may answer: `owners` in a shared conversation, where an approval above the
 	 * speaker's tier goes to the owners; `none` in a private one, which no one else sees, so such
-	 * an approval expires at once.
+	 * an approval comes back `unavailable` at once.
 	 */
 	escalate: "owners" | "none";
 }
@@ -95,7 +118,8 @@ export interface Prompts {
 	 * Asks to approve an action; `signal` cancels the prompt when the turn stops. `minTier` is the
 	 * tier the scope's speaker needs to approve it themselves, `owner` when absent; below it the
 	 * prompt goes to the owners, or, when the scope escalates to no one, resolves `expired` at once.
-	 * `pending` comes only with a `wait`.
+	 * `pending` comes only with a `wait`. `details` is the approval as data beside `message`, its
+	 * text; a surface that shows text only ignores it.
 	 */
 	confirm(
 		title: string,
@@ -103,6 +127,7 @@ export interface Prompts {
 		signal?: AbortSignal,
 		minTier?: Tier,
 		wait?: PromptWait,
+		details?: ApprovalDetails,
 	): Promise<Approval>;
 	/**
 	 * Asks a question; undefined when no one answered it or it was cancelled, and `pending`, only

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

@@ -0,0 +1,210 @@
+import { statSync } from "node:fs";
+import { resolve } from "node:path";
+import type { HeldCall } from "../../domain/conversation.ts";
+import { messages } from "../../i18n/index.ts";
+import type { ApprovalDetails } from "../../interactions/prompts.ts";
+
+/** The fewest characters of a long string value in a held call's input its approval card keeps, when the input does not fit whole. */
+const CARD_VALUE_CHARS = 200;
+
+/** How many characters of the whole input its approval card shows, at most. */
+const CARD_INPUT_CHARS = 1_500;
+
+/** How many hidden key names a card lists, and how long each may be. */
+const CARD_HIDDEN_KEYS = 20;
+const CARD_KEY_CHARS = 40;
+
+/** What an approval card shows of a call's input; see `approvalCard`. */
+export interface CardLimits {
+	/**
+	 * The fewest characters of a long string value (at any depth) kept when the input is over
+	 * `totalChars`; a value is cut only as far as the input needs, never below this. Counted in code points.
+	 */
+	valueChars?: number;
+	/** Longest input shown. An input within it is shown whole; a longer one has its values cut, then the rest dropped. */
+	totalChars?: number;
+}
+
+/**
+ * What an approval card says: the held action's words, the exact call, and each file it sends by
+ * path with the file's size now; relative paths resolve against `workspace`. An input within
+ * `limits.totalChars` is shown whole. A longer one has its string values cut, the longest first
+ * and never below `limits.valueChars`, each marked `… [N chars]` with its original length in code
+ * points, until it fits, so one long value does not push the keys after it out of the card. If it
+ * still does not fit, the rest is dropped and the keys that are no longer shown are listed.
+ */
+export function approvalCard(
+	call: HeldCall,
+	workspace?: string,
+	limits: CardLimits = {},
+): string {
+	const input = shownInput(
+		call.input,
+		limits.valueChars ?? CARD_VALUE_CHARS,
+		limits.totalChars ?? CARD_INPUT_CHARS,
+	);
+	const files = pathFiles(call.input).map(
+		(path) => `\n-# ${messages().cardFile(path, fileSize(path, workspace))}`,
+	);
+	return `**${call.action}**\n-# \`${call.tool}\`\n\`\`\`json\n${input.replaceAll("```", "`\u200b``")}\n\`\`\`${files.join("")}`;
+}
+
+/** The input as a card shows it within `total` characters; see `approvalCard`. */
+function shownInput(input: string, valueChars: number, total: number): string {
+	if (input.length <= total) return input;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(input);
+	} catch {
+		return `${prefix(input, total)}…`;
+	}
+	const longest = longestString(parsed);
+	const cutAt = (limit: number) => cutValues(parsed, limit);
+	let limit = valueChars;
+	if (cutAt(limit).length <= total) {
+		// The largest limit that still fits: the longest values give up characters first.
+		let low = limit;
+		let high = Math.max(low, longest - 1);
+		while (low < high) {
+			const mid = Math.ceil((low + high) / 2);
+			if (cutAt(mid).length <= total) low = mid;
+			else high = mid - 1;
+		}
+		limit = low;
+		return cutAt(limit);
+	}
+	const shown = cutAt(limit);
+	const kept = prefix(shown, total);
+	return `${kept}…${hiddenKeys(parsed, limit, kept.length)}`;
+}
+
+/** The longest string value in `value`, at any depth, in code points; 0 when there is none. */
+// pi-lens-ignore: no-unknown-parameters — tool input is untyped model JSON; this is where it is read
+function longestString(value: unknown): number {
+	let longest = 0;
+	JSON.stringify(value, (_key, v: unknown) => {
+		if (typeof v === "string" && v.length > longest)
+			longest = Math.max(longest, countPoints(v));
+		return v;
+	});
+	return longest;
+}
+
+/** `value` as JSON with each string longer than `limit` code points cut and marked `… [N chars]`. */
+// pi-lens-ignore: no-unknown-parameters — tool input is untyped model JSON; this is where it is read
+function cutValues(value: unknown, limit: number): string {
+	return JSON.stringify(value, (_key, v: unknown) => {
+		if (typeof v !== "string" || v.length <= limit) return v;
+		const points = countPoints(v);
+		if (points <= limit) return v;
+		return `${firstPoints(v, limit)}… [${points} chars]`;
+	});
+}
+
+/** The top-level keys, as a line for the card, whose names fall after the first `shown` characters of the cut input. */
+// pi-lens-ignore: no-unknown-parameters — tool input is untyped model JSON; this is where it is read
+function hiddenKeys(parsed: unknown, limit: number, shown: number): string {
+	if (!isPlainObject(parsed)) return "";
+	const hidden: string[] = [];
+	// Entries are laid out as `{"k":v,"k2":v2}`; an entry starts after the `{` and each comma.
+	let offset = 1;
+	for (const [key, value] of Object.entries(parsed)) {
+		if (offset >= shown) hidden.push(key);
+		offset += `${JSON.stringify(key)}:${cutValues(value, limit)},`.length;
+	}
+	if (hidden.length === 0) return "";
+	const names = hidden
+		.slice(0, CARD_HIDDEN_KEYS)
+		.map((key) => JSON.stringify(firstPoints(key, CARD_KEY_CHARS)));
+	if (hidden.length > CARD_HIDDEN_KEYS) names.push("…");
+	return `\n${messages().cardHiddenKeys(names)}`;
+}
+
+/** How many code points `text` has. */
+function countPoints(text: string): number {
+	let points = 0;
+	for (let i = 0; i < text.length; i++) {
+		const code = text.charCodeAt(i);
+		if (code >= 0xd800 && code <= 0xdbff && i + 1 < text.length) i++;
+		points++;
+	}
+	return points;
+}
+
+/** The first `count` code points of `text`. */
+function firstPoints(text: string, count: number): string {
+	let end = 0;
+	for (let points = 0; points < count && end < text.length; points++) {
+		const code = text.charCodeAt(end);
+		end += code >= 0xd800 && code <= 0xdbff && end + 1 < text.length ? 2 : 1;
+	}
+	return text.slice(0, end);
+}
+
+/** The first `max` characters of `text`, backing off a cut that would split a surrogate pair. */
+function prefix(text: string, max: number): string {
+	if (text.length <= max) return text;
+	const code = text.charCodeAt(max - 1);
+	return text.slice(0, code >= 0xd800 && code <= 0xdbff ? max - 1 : max);
+}
+
+/**
+ * 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.
+ */
+export function approvalDetails(
+	call: HeldCall,
+	workspace?: string,
+): ApprovalDetails {
+	const files = pathFiles(call.input).map((path) => {
+		const bytes = fileSize(path, workspace);
+		return bytes === undefined ? { path } : { path, bytes };
+	});
+	return {
+		action: call.action,
+		tool: call.tool,
+		input: parsedInput(call.input),
+		...(files.length > 0 ? { files } : {}),
+	};
+}
+
+/** A call's input object; `{}` for input that is not one (a held call's always is). */
+function parsedInput(input: string): Record<string, unknown> {
+	try {
+		const parsed: unknown = JSON.parse(input);
+		return isPlainObject(parsed) ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+
+/** The paths of a call's `files` entries that name one. */
+function pathFiles(input: string): string[] {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(input);
+	} catch {
+		return [];
+	}
+	const files = isPlainObject(parsed) ? parsed.files : undefined;
+	if (!Array.isArray(files)) return [];
+	return files.flatMap((file: unknown) =>
+		isPlainObject(file) && typeof file.path === "string" ? [file.path] : [],
+	);
+}
+
+/** A file's size in bytes, or undefined when it cannot be read. */
+function fileSize(path: string, workspace: string | undefined) {
+	try {
+		const info = statSync(resolve(workspace ?? "/", path));
+		return info.isFile() ? info.size : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+// pi-lens-ignore: no-unknown-parameters — tool input is untyped model JSON; this is where it is read
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

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

@@ -1,20 +1,24 @@
-import { statSync } from "node:fs";
-import { resolve } from "node:path";
 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 HoldCheck, type HoldContext, higherTier } from "../../holds.ts";
+import type { HoldRefusal } from "../../domain/progress.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";
 import type { Speaker } from "../../speakers.ts";
 import type { ToolTiers } from "../../tool-tiers.ts";
 import type { PromptSlot } from "../prompt-slot.ts";
-
-/** How much of a held call's input its approval card shows. */
-const CARD_INPUT_CHARS = 1_500;
+import { approvalCard, approvalDetails } from "./approval-card.ts";
 
 /** Held actions older than this cannot be approved any more. */
 export const CONFIRMATION_TTL_MS = 24 * 3_600_000;
@@ -30,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 {
@@ -82,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,
@@ -96,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;
@@ -147,44 +173,62 @@ 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.
+	 * 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 },
-	): Promise<{ reason?: string; approvedOnCard?: true }> {
-		const call = this.#needing(tool, input);
+		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 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) };
+		if (!ask) return { reason: this.#record(call), refused: "held" };
 		const answer = await ask.prompts.confirm(
 			messages().confirmTitle(ask.asker),
 			approvalCard(call, this.#fileRoot),
 			ask.signal,
 			higherTier(this.#tiers?.minTier(call.tool), call.minTier),
 			{ late: (late) => this.#late(call, late) },
+			approvalDetails(call, this.#fileRoot),
 		);
 		if (answer === "approved") return { approvedOnCard: true };
 		if (answer === "pending") {
 			const o = ownerWords(this.#addressee);
 			return {
 				reason: `Awaiting ${o.name}'s approval: this would ${call.action}. Its card stays open, and the call did not run. Do not retry it or ask again in this turn. End your turn now: say briefly that you are waiting for ${o.his} approval on the card. When ${o.he} answers, a new turn tells you.`,
+				refused: "pending",
 			};
 		}
 		if (answer === "declined") {
 			const o = ownerWords(this.#addressee);
 			return {
 				reason: `${o.name} declined this on its approval card: it would ${call.action}. Do not retry it; go on without it, or ask ${o.him} what ${o.he} wants instead.`,
+				refused: "declined",
 			};
 		}
 		if (answer === "cancelled") return { reason: "The turn was stopped." };
-		return { reason: this.#record(call) };
+		// No card was shown: no one may approve it, or it could not be posted.
+		if (answer === "unavailable")
+			return { reason: this.#record(call), refused: "held" };
+		return { reason: this.#record(call), refused: "expired" };
 	}
 
 	/**
@@ -201,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),
@@ -261,49 +407,13 @@ export function confirmedTurnText(
 }
 
 /**
- * What an approval card says: the held action's words, the exact call, and each file it sends by
- * path with the file's size now; relative paths resolve against `workspace`.
+ * 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 approvalCard(call: HeldCall, workspace?: string): string {
-	const input =
-		call.input.length > CARD_INPUT_CHARS
-			? `${call.input.slice(0, CARD_INPUT_CHARS)}…`
-			: call.input;
-	const files = pathFiles(call.input).map(
-		(path) => `\n-# ${messages().cardFile(path, fileSize(path, workspace))}`,
-	);
-	return `**${call.action}**\n-# \`${call.tool}\`\n\`\`\`json\n${input.replaceAll("```", "`\u200b``")}\n\`\`\`${files.join("")}`;
-}
-
-/** The paths of a call's `files` entries that name one. */
-function pathFiles(input: string): string[] {
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(input);
-	} catch {
-		return [];
-	}
-	const files = isPlainObject(parsed) ? parsed.files : undefined;
-	if (!Array.isArray(files)) return [];
-	return files.flatMap((file: unknown) =>
-		isPlainObject(file) && typeof file.path === "string" ? [file.path] : [],
-	);
-}
-
-/** A file's size in bytes, or undefined when it cannot be read. */
-function fileSize(path: string, workspace: string | undefined) {
-	try {
-		const info = statSync(resolve(workspace ?? "/", path));
-		return info.isFile() ? info.size : undefined;
-	} catch {
-		return undefined;
-	}
-}
-
-/** Without a slot, or with an empty one, every call that needs confirmation is held. */
 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. */
@@ -324,12 +434,17 @@ export function confirmationGateExtension(
 				ask = { prompts, asker: slot.asker };
 				if (ctx.signal) ask.signal = ctx.signal;
 			}
-			const { reason, approvedOnCard } = await gate.decide(
+			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);
 			return reason ? { block: true, reason } : undefined;
 		});
 	};

package/src/core/runtime/pi-agent-runtime.ts

@@ -228,8 +228,11 @@ export class PiAgentRuntime implements AgentRuntime {
 		// Text written before the final answer is posted as the turn goes; the final reply stays the caller's.
 		const interim = interimPoster(request, this.#options);
 		// The caller's live view: the text as it streams and each tool, never the thinking.
+		const slot = this.#sessions.slot(key);
 		const progress = request.progress
-			? progressReporter(request.progress)
+			? progressReporter(request.progress, {
+					refusalOf: (id) => slot.refusalOf(id),
+				})
 			: undefined;
 		const unsubscribe = session.subscribe((event) => {
 			progress?.observe(event);
@@ -243,7 +246,6 @@ export class PiAgentRuntime implements AgentRuntime {
 				interim?.messageEnd(event.message);
 			}
 		});
-		const slot = this.#sessions.slot(key);
 		slot.bind(
 			request.interactive
 				? this.#options.prompts?.(request.channel, promptScopeOf(scoped))

package/src/core/runtime/prompt-slot.ts

@@ -1,3 +1,4 @@
+import type { HoldRefusal } from "../domain/progress.ts";
 import { assistantName } from "../i18n/index.ts";
 import type { OwnerQuestion, Prompts } from "../interactions/prompts.ts";
 
@@ -15,6 +16,7 @@ export class PromptSlot {
 	#open = 0;
 	#openSince = 0;
 	#waited = 0;
+	#refused = new Map<string, HoldRefusal>();
 
 	/**
 	 * Binds the turn's prompts; `asker` names who asks, the assistant or an agent. `beforeCard`
@@ -30,6 +32,19 @@ export class PromptSlot {
 		this.#asker = asker;
 		this.#open = 0;
 		this.#waited = 0;
+		this.#refused.clear();
+	}
+
+	/** Notes that a hold refused a tool call, for the progress of the turn to report once. */
+	refuse(toolCallId: string, refusal: HoldRefusal): void {
+		this.#refused.set(toolCallId, refusal);
+	}
+
+	/** Why a hold refused a tool call, once; undefined when it did not. */
+	refusalOf(toolCallId: string): HoldRefusal | undefined {
+		const refusal = this.#refused.get(toolCallId);
+		this.#refused.delete(toolCallId);
+		return refusal;
 	}
 
 	unbind(): void {
@@ -46,9 +61,9 @@ export class PromptSlot {
 		const prompts = this.#prompts;
 		if (!prompts) return undefined;
 		return {
-			confirm: (title, message, signal, minTier, wait) =>
+			confirm: (title, message, signal, minTier, wait, details) =>
 				this.#waiting(() =>
-					prompts.confirm(title, message, signal, minTier, wait),
+					prompts.confirm(title, message, signal, minTier, wait, details),
 				),
 			ask: (title, question: OwnerQuestion, signal, wait) =>
 				this.#waiting(() => prompts.ask(title, question, signal, wait)),