pi-roundtable 0.9.6 → 0.9.7

package/CHANGELOG.md

@@ -5,6 +5,19 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.7] - 2026-10-10
+
+### Added
+
+- `ApprovalDetails` and `ApprovalFile` (`{ action, tool, input, files? }`, files as `{ path, bytes? }`): a held call as data, with its whole input and the size of each file it sends by path. `Prompts.confirm` takes it as a new optional last argument, `details`, beside the card's text `message`; the confirmation gate passes it with every card, and a surface that shows text only ignores it (Discord's cards read as before). `approvalDetails` builds it (`approvalDetails(call, workspace?)`), exported from `pi-roundtable/kit` beside `approvalCard`.
+- `Approval` has a new value, `unavailable`: no card could be shown (no one may approve the call, the speaker is below its tier, or the card could not be posted). `expired` now means a card was shown and went unanswered. The Discord and web chat surfaces answer `unavailable` for the first case; a surface that cannot tell the two may keep answering `expired` for both, and the surface contract accepts either.
+- `TurnProgress`'s `tool_end` takes an optional `refused` (`HoldRefusal`: `declined`, `expired`, `pending` or `held`), set when a hold refused the call and absent for a success and for a real failure. A card that was shown and went unanswered is `expired`; one that could not be shown is `held`. It is set through `PromptSlot` (`refuse`, `refusalOf`, in `pi-roundtable/kit`); a turn stopped while its card was open reports none.
+- `approvalCard(call, workspace?, limits?)` takes `CardLimits` (also exported from the kit), `{ valueChars?, totalChars? }`, to set what its card shows of the input.
+
+### Changed
+
+- An approval card shows an input that fits `totalChars` (1,500 by default) whole, exactly as before. Only an input over it has its string values cut, the longest first and never below `valueChars` (200 by default), each marked `… [N chars]` with the original length in code points, until it fits; so the keys after one long value are no longer lost. If it still cannot fit, the rest is dropped and the card lists the top-level keys it no longer shows. A cut never splits a surrogate pair.
+
 ## [0.9.6] - 2026-10-10
 
 ### Fixed

package/docs/plugins.md

@@ -60,7 +60,7 @@ Use the kit's building blocks for a plugin that runs Pi itself, such as a coding
   `ImagePreparationError.reason` is `byte-limit`, `pixel-limit`, or `invalid-image`; hosts can localize refusals without parsing native decoder errors.
   Ordinary 48 MP images and thin 9000×1 images remain admitted.
   This helper is not a downloader or filesystem validator.
-- Work: `promptSlot` (how a run asks the owner while it works), `workTimeout` (a time limit that does not count the time spent waiting on the owner), `runWorkerTask`, `archiveSessions`, and `approvalCard` and `canonicalJson` for the cards of held actions.
+- Work: `promptSlot` (how a run asks the owner while it works), `workTimeout` (a time limit that does not count the time spent waiting on the owner), `runWorkerTask`, `archiveSessions`, and `approvalCard`, `approvalDetails` and `canonicalJson` for the cards of held actions.
   `InterimPoster(posts, { logger, channel, primaryChars?, editMs? })` posts a run's [interim text](#interim-text-what-a-turn-writes-before-its-final-answer) to an `InterimPosts`, such as a dispatch thread's `interim`: feed it `messageEnd(message)` and `toolStart(name)` from the session's events, bind `() => poster.flush()` as the slot's `beforeCard`, and `await poster.flush()` before the final report.
 - Diagnostics: `scrubDiagnostic(text, max = 600)` masks credentials (URL userinfo, token shapes, secret-named assignments and JSON fields, `Authorization`/`Cookie`/`x-api-key` headers, JWTs, PEM blocks), turns control characters other than tab and newline into spaces, and cuts the result at `max` characters.
   It scans only the first `max * 4` characters (at least 4,096), in linear time, so pass it git, gh or provider error text before showing that text to a user.
@@ -648,7 +648,7 @@ A Pi package should use the host's peer dependency on `pi-roundtable`, not bundl
 Transient `SessionContext.runTask` tasks return only text and cannot attach to their parent's reply.
 
 The model attaches a file it already has on disk with the core's `attach_file({ path, filename? })`. A session with a workspace (`SessionContext.workspace`, an agent's) registers it; the path must resolve, symlinks followed, inside the workspace or the scratch dir, a relative path resolves in the workspace, and `filename` defaults to the path's base name. It queues the file with `attachReplyFile`, so `REPLY_FILE_LIMITS` apply and a surface without reply files refuses it as a tool error; its result tells the model the file will appear with its reply. It holds nothing, since it only posts in the channel the turn answers in, and its tier defaults to the owner, like any tool the core's table does not name.
-The Discord tools that upload, `discord_send_message` and `discord_edit_message`, take each file as exactly one of `path` (a local file, read when the call runs, with the same roots; `filename` defaults to its base name) or `dataBase64` with a `filename`, at most 8 MiB in all. A session without a workspace takes only `dataBase64`, and so does remote MCP, whose schemas stay inline only. A path outside the roots, a missing file, or a directory is a tool error naming the path. A held call's card (`approvalCard(call, workspace?)`) lists each file it sends by path with the file's size now, never its bytes.
+The Discord tools that upload, `discord_send_message` and `discord_edit_message`, take each file as exactly one of `path` (a local file, read when the call runs, with the same roots; `filename` defaults to its base name) or `dataBase64` with a `filename`, at most 8 MiB in all. A session without a workspace takes only `dataBase64`, and so does remote MCP, whose schemas stay inline only. A path outside the roots, a missing file, or a directory is a tool error naming the path. A held call's card (`approvalCard(call, workspace?, limits?)`) lists each file it sends by path with the file's size now, never its bytes, and shows an input within `limits.totalChars` (1,500) whole; a longer input has its string values cut, longest first and never below `limits.valueChars` (200), to their start plus `… [N chars]` (N in code points) until it fits, and if it still does not, the rest is dropped and the keys no longer shown are listed. `approvalDetails(call, workspace?)` gives the same call as data (`{ action, tool, input, files? }`, the whole input, files as `{ path, bytes? }`); the gate passes it to `Prompts.confirm` as `details`, for a surface that is not text.
 Calling the helper outside `context.turns.run` or an agent-team turn, or after that turn finishes, throws `ReplyFileError`; direct standalone runtime calls have no reply collector.
 Await work that produces files before returning from the tool.
 A standalone isolated worker may wrap its complete awaited turn in `withReplyFiles(supported, run)` from the main entry.
@@ -2365,7 +2365,7 @@ The agent server claims only `discord:` keys, so claims on your surface's channe
 | `react`, `unreact` | Adds or removes the bot's reaction on a message | no marks on queued or steered messages |
 | `prompts(channel, scope?)` | How those the turn's `PromptScope` names approve a held action or answer `ask_user` inside a running turn, as `Prompts`: `confirm` and `ask`; without a scope, the owners | the action is held until a message approves it |
 | `interim(channel)` | Where a running turn posts the text it writes before its final answer, as `InterimPosts`: `post(text)` sends one message of at most 2000 characters and resolves to an `InterimMessage` whose `edit(text)` changes it in place | only the final reply is posted |
-| `progress(channel, event)` | Shows a turn run through `context.turns` as it goes, such as a live preview in a web chat. `event` is a `TurnProgress`: `{ type: "text", delta }` (the reply's text, joined over 250 ms and always sent before a tool event, never the thinking), `{ type: "tool_start", id, tool, preview? }` (a one-line preview of the arguments, at most 80 characters, never their full text), or `{ type: "tool_end", id, tool, ok }`. The final reply still comes through `sendReply`; a rejection is logged and the turn goes on | only the final reply is shown |
+| `progress(channel, event)` | Shows a turn run through `context.turns` as it goes, such as a live preview in a web chat. `event` is a `TurnProgress`: `{ type: "text", delta }` (the reply's text, joined over 250 ms and always sent before a tool event, never the thinking), `{ type: "tool_start", id, tool, preview? }` (a one-line preview of the arguments, at most 80 characters, never their full text), or `{ type: "tool_end", id, tool, ok, refused? }` (`refused`, only on a failed end that a hold refused, says how: `declined` on its approval card, `expired` when a card was shown and went unanswered, `pending` while the card stays open, or `held` when no card could be shown (no one may approve it, or it could not be posted); it is absent for a success and for a real failure). The final reply still comes through `sendReply`; a rejection is logged and the turn goes on | only the final reply is shown |
 
 Each message a surface delivers says who wrote it in `actor`, the `ActorFacts` the identity service resolves: `provider` and `subject`, such as `discord` and the user id, `name`, `roles` written `<surface>:role:<name>` (left out where the surface does not know them, such as a Discord DM, which is not the same as none), and `legacyId`, the speaker id 0.8 gave the person, so someone carried over keeps their principal.
 A surface that leaves `actor` out has it read from `authorId`, `authorName`, and `authorRoleIds` with its prefix as the provider, and the host warns once that this goes away in 1.0.
@@ -2388,13 +2388,21 @@ A surface's prompts keep these rules:
 
 - The speaker's principal answers their own question on any of their identities the surface knows, and approves a call when their tier is at least its `minTier` (the owner tier when absent) and, for an owner-tier call, the principal is an owner; a surface that can check their tier again when they answer does.
 - Where the scope escalates to the owners, every owner may answer too, and an approval above the speaker's tier is the owners' alone.
-- Where it escalates to no one, nobody else answers, and an approval above the speaker's tier resolves `expired` at once, shown to no one: the call stays held.
+- Where it escalates to no one, nobody else answers, and an approval above the speaker's tier resolves `unavailable` at once, shown to no one: the call stays held. (`expired` is for a card that was shown and went unanswered; a surface that cannot tell the two may answer `expired` for both.)
 - Anyone else is refused, even at the same tier as the speaker.
 - Without a scope, as for a turn with no speaker, the prompts are the owners'.
 
 On Discord the owners are every owner with a Discord identity, and the primary owner always; a card in a thread mentions the identity that spoke when it is theirs and one of the principal's Discord identities, every Discord identity of the principal when the speaker is none of them, and the owners when it goes to them, so a single owner's cards read as they did in 0.8.
 A principal with no Discord identity, such as the reporter of a background report, answers nothing there, so their card goes to the owners; so does an owner-tier call of a turn whose tier defaulted to owner when its principal is not an owner.
-The web chat shows prompts to the conversation's person only: its owners are not on it, so an approval above that person's tier expires at once whatever the scope says.
+The web chat shows prompts to the conversation's person only: its owners are not on it, so an approval above that person's tier comes back `unavailable` at once whatever the scope says.
+
+#### An approval as data: `ApprovalDetails`
+
+`confirm(title, message, signal?, minTier?, wait?, details?)` takes the approval twice: `message` is the card as markdown text, and the optional `details` (`ApprovalDetails`: `{ action, tool, input, files? }`) is the same held call as data, with its whole input (the web chat cuts it only past 256 KiB and says so with `truncated`), and each file it sends by path as `{ path, bytes? }`.
+The confirmation gate and a coding worker's cards pass both.
+A surface that shows text, such as Discord, uses `message` and ignores `details`; the web chat sends `details` to the client as the prompt frame's `approval`, beside the unchanged `title` and `message`.
+A surface or a `Prompts` of your own may ignore it: nothing requires reading it.
+`confirm` resolves `approved`, `declined`, `expired` (a card was shown and went unanswered), `unavailable` (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` (the turn stopped), or `pending` (with a `wait`). Both `expired` and `unavailable` leave the call held for the owner's next message; the turn's progress reports them as `refused: "expired"` and `refused: "held"`.
 
 #### A prompt that outlives its turn: `PromptWait`
 
@@ -2518,7 +2526,7 @@ export class FakeSurface implements ChatSurface {
 	/**
 	 * How a turn asks to approve a held action or answers a question. The scope names who may
 	 * answer: its speaker when their tier holds the call, and the owners unless the conversation
-	 * is private, where a call above the speaker's tier goes to no one and expires at once.
+	 * is private, where a call above the speaker's tier goes to no one and comes back `unavailable` at once.
 	 */
 	prompts(channel: ChannelKey, scope?: PromptScope): Prompts {
 		return {
@@ -2527,7 +2535,7 @@ export class FakeSurface implements ChatSurface {
 					scope !== undefined &&
 					TIERS.indexOf(scope.tier) >= TIERS.indexOf(minTier);
 				const owners = scope?.escalate !== "none";
-				if (!theirs && !owners) return "expired";
+				if (!theirs && !owners) return "unavailable";
 				return this.#ask(channel, title, signal, {
 					...(theirs ? { principalId: scope.principalId } : {}),
 					owners,
@@ -3014,7 +3022,7 @@ It returns:
 A plugin that contributes a `ChatSurface` can test it against the contract every surface keeps.
 `describeSurfaceContract(name, make)` registers one test per check, each on a fresh `SurfaceContractSubject` from `make`: the `surface`, a `channel` of it, and one person on its network, who can `write(text)`, whose `observations()` list what they have seen (`SurfaceObservation`: a reply's text and file names, typing and stop controls going on and off, progress, and prompts opening and closing), and who may `answer(prompt, approved)` an approval; `speaker` is who they are to `surface.prompts`, given as `promptScope(speaker, visibility)`, an owner by default, and every approval the contract asks for needs exactly their tier. `stranger`, when given, is someone else on the network, another principal and not an owner, who knows the id of the person's open approval and may `join()` and `answer(prompt, approved)` it; `owner`, when given, is an owner on the network, another principal than the person, who does the same in the person's private conversation. Both are `SurfaceContractAnswerer`s.
 The contract starts the surface, calls the subject's `join()`, and stops the surface after the subject's `close()`.
-It checks that the surface names a prefix and owns its channel, delivers what the person writes, and shows every chunk of a reply; and, for the parts the surface offers, that it delivers files when `supportsFiles` is set, ends typing and stop controls idempotently, shows progress, and resolves an approval as the person approves or declines it, or `cancelled` when the turn stops, with a `stranger`, that the stranger's answer leaves the person's approval open, and with an `owner`, that an owner's answer leaves it open in a private conversation; and, for a speaker below the owner tier, that a private conversation's approval above their tier resolves `expired` at once and is not shown.
+It checks that the surface names a prefix and owns its channel, delivers what the person writes, and shows every chunk of a reply; and, for the parts the surface offers, that it delivers files when `supportsFiles` is set, ends typing and stop controls idempotently, shows progress, and resolves an approval as the person approves or declines it, or `cancelled` when the turn stops, with a `stranger`, that the stranger's answer leaves the person's approval open, and with an `owner`, that an owner's answer leaves it open in a private conversation; and, for a speaker below the owner tier, that a private conversation's approval above their tier resolves `unavailable` (or `expired`, as older surfaces answer) at once and is not shown.
 A check for a part the surface does not offer passes.
 `checkSurfaceContract(make)` runs the same checks and returns the ones that failed, as `SurfaceContractFailure`s.
 
@@ -3268,6 +3276,8 @@ Import from the entries listed below; source area files are internal.
 | `AgentTeam` | `pi-roundtable` | type |
 | `AgentTurnScope` | `pi-roundtable` | type |
 | `Approval` | `pi-roundtable` | type |
+| `ApprovalDetails` | `pi-roundtable` | type |
+| `ApprovalFile` | `pi-roundtable` | type |
 | `AskOption` | `pi-roundtable` | type |
 | `AttachmentFailure` | `pi-roundtable` | type |
 | `AttachmentPort` | `pi-roundtable` | type |
@@ -3318,6 +3328,7 @@ Import from the entries listed below; source area files are internal.
 | `HeldCall` | `pi-roundtable` | type |
 | `HoldCheck` | `pi-roundtable` | type |
 | `HoldContext` | `pi-roundtable` | type |
+| `HoldRefusal` | `pi-roundtable` | type |
 | `HoldRule` | `pi-roundtable` | type |
 | `HostEnv` | `pi-roundtable` | type |
 | `HostEnvironment` | `pi-roundtable` | type |
@@ -3534,6 +3545,7 @@ Import from the entries listed below; source area files are internal.
 | `AgentTurnRunner` | `pi-roundtable/kit` | type |
 | `AssistantLike` | `pi-roundtable/kit` | type |
 | `Backlog` | `pi-roundtable/kit` | type |
+| `CardLimits` | `pi-roundtable/kit` | type |
 | `CategoryLayout` | `pi-roundtable/kit` | type |
 | `ChannelMessage` | `pi-roundtable/kit` | type |
 | `ChannelQueue` | `pi-roundtable/kit` | type |
@@ -3581,6 +3593,7 @@ Import from the entries listed below; source area files are internal.
 | `YesNoQuestion` | `pi-roundtable/kit` | type |
 | `activeToolsExtension` | `pi-roundtable/kit` | value |
 | `approvalCard` | `pi-roundtable/kit` | value |
+| `approvalDetails` | `pi-roundtable/kit` | value |
 | `archiveSessions` | `pi-roundtable/kit` | value |
 | `attachmentsOf` | `pi-roundtable/kit` | value |
 | `callScheduleTool` | `pi-roundtable/kit` | value |

package/examples/fake-surface.ts

@@ -80,7 +80,7 @@ export class FakeSurface implements ChatSurface {
 	/**
 	 * How a turn asks to approve a held action or answers a question. The scope names who may
 	 * answer: its speaker when their tier holds the call, and the owners unless the conversation
-	 * is private, where a call above the speaker's tier goes to no one and expires at once.
+	 * is private, where a call above the speaker's tier goes to no one and comes back `unavailable` at once.
 	 */
 	prompts(channel: ChannelKey, scope?: PromptScope): Prompts {
 		return {
@@ -89,7 +89,7 @@ export class FakeSurface implements ChatSurface {
 					scope !== undefined &&
 					TIERS.indexOf(scope.tier) >= TIERS.indexOf(minTier);
 				const owners = scope?.escalate !== "none";
-				if (!theirs && !owners) return "expired";
+				if (!theirs && !owners) return "unavailable";
 				return this.#ask(channel, title, signal, {
 					...(theirs ? { principalId: scope.principalId } : {}),
 					owners,

package/package.json

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

package/src/core/discord/owner-cards.ts

@@ -167,42 +167,48 @@ export class OwnerCards implements InteractionModule {
 			confirm: async (title, message, signal, minTier = "owner", wait) => {
 				const audience = await this.#audiences.approval(scope, minTier);
 				// A private conversation's call above its person's tier is no one's to approve.
-				if (!audience) return "expired";
-				return this.#post<Approval>(channelId, signal, "expired", "cancelled", {
-					audience,
-					...(wait
-						? {
-								wait: {
-									pending: "pending",
-									late: (value, by) =>
-										wait.late({
-											kind: "approval",
-											approved: value === "approved",
-											by,
-										}),
-								},
-							}
-						: {}),
-					title,
-					sections: [message],
-					rows: (id, disabled) => [
-						new ActionRowBuilder<ButtonBuilder>().addComponents(
-							new ButtonBuilder()
-								.setCustomId(`${CARD_PREFIX}${id}:yes`)
-								.setLabel(messages().cardRunLabel)
-								.setEmoji("✅")
-								.setStyle(ButtonStyle.Success)
-								.setDisabled(disabled),
-							new ButtonBuilder()
-								.setCustomId(`${CARD_PREFIX}${id}:no`)
-								.setLabel(messages().cardCancelLabel)
-								.setEmoji("❌")
-								.setStyle(ButtonStyle.Secondary)
-								.setDisabled(disabled),
-						),
-					],
-					footer: messages().cardApprovalFooter,
-				});
+				if (!audience) return "unavailable";
+				return this.#post<Approval>(
+					channelId,
+					signal,
+					"unavailable",
+					"cancelled",
+					{
+						audience,
+						...(wait
+							? {
+									wait: {
+										pending: "pending",
+										late: (value, by) =>
+											wait.late({
+												kind: "approval",
+												approved: value === "approved",
+												by,
+											}),
+									},
+								}
+							: {}),
+						title,
+						sections: [message],
+						rows: (id, disabled) => [
+							new ActionRowBuilder<ButtonBuilder>().addComponents(
+								new ButtonBuilder()
+									.setCustomId(`${CARD_PREFIX}${id}:yes`)
+									.setLabel(messages().cardRunLabel)
+									.setEmoji("✅")
+									.setStyle(ButtonStyle.Success)
+									.setDisabled(disabled),
+								new ButtonBuilder()
+									.setCustomId(`${CARD_PREFIX}${id}:no`)
+									.setLabel(messages().cardCancelLabel)
+									.setEmoji("❌")
+									.setStyle(ButtonStyle.Secondary)
+									.setDisabled(disabled),
+							),
+						],
+						footer: messages().cardApprovalFooter,
+					},
+				);
 			},
 			ask: async (title, question, signal, wait) => {
 				const audience = await this.#audiences.question(scope);
@@ -239,13 +245,13 @@ export class OwnerCards implements InteractionModule {
 	}
 
 	/**
-	 * Posts a card and resolves with its answer, `expired` when it could not be posted, or
+	 * Posts a card and resolves with its answer, `unposted` when it could not be posted, or
 	 * `cancelled`; with `wait`, and a way to resume, `wait.pending` once the grace period passes.
 	 */
 	#post<T>(
 		channelId: string,
 		signal: AbortSignal | undefined,
-		expired: T,
+		unposted: T,
 		cancelled: T,
 		card: {
 			audience: Audience;
@@ -350,7 +356,7 @@ export class OwnerCards implements InteractionModule {
 				})
 				.catch((error: unknown) => {
 					logger.warn({ channelId, err: error }, "card not posted");
-					settle(expired, undefined);
+					settle(unposted, undefined);
 				});
 		});
 	}

package/src/core/domain/progress.ts

@@ -4,7 +4,24 @@
  * arguments, never their full text, and ends with whether it succeeded. The final reply still
  * arrives through `sendReply`.
  */
+
+/**
+ * Why a hold refused a tool call, as a tool's end reports it, so a surface need not tell a call
+ * the owner turned down from a call that failed: `declined` on its approval card, `expired` when
+ * a card was shown and went unanswered (the call is held for the owner's next message),
+ * `pending` while the card stays open, and `held` when no card could be shown (no one may approve
+ * it, or it could not be posted; the call waits for the owner's next message). A turn that was stopped is none of these.
+ */
+export type HoldRefusal = "declined" | "expired" | "pending" | "held";
+
 export type TurnProgress =
 	| { type: "text"; delta: string }
 	| { type: "tool_start"; id: string; tool: string; preview?: string }
-	| { type: "tool_end"; id: string; tool: string; ok: boolean };
+	| {
+			type: "tool_end";
+			id: string;
+			tool: string;
+			ok: boolean;
+			/** Set only on a failed end that a hold refused; absent for a success and for a real failure. */
+			refused?: HoldRefusal;
+	  };

package/src/core/i18n/conversation.ts

@@ -33,6 +33,8 @@ export function conversationEn(ctx: CatalogContext) {
 			bytes === undefined
 				? `File \`${path}\` (not found now)`
 				: `File \`${path}\` (${formatBytes(bytes)})`,
+		cardHiddenKeys: (keys: readonly string[]) =>
+			`… not shown: ${keys.join(", ")}`,
 	};
 }
 
@@ -62,5 +64,6 @@ export function conversationZhTW(
 			bytes === undefined
 				? `檔案 \`${path}\`（目前找不到）`
 				: `檔案 \`${path}\`（${formatBytes(bytes)}）`,
+		cardHiddenKeys: (keys: readonly string[]) => `… 未顯示：${keys.join("、")}`,
 	};
 }

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,10 +1,9 @@
-import { statSync } from "node:fs";
-import { resolve } from "node:path";
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
 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 { messages } from "../../i18n/index.ts";
 import { type OwnerIdentity, ownerWords } from "../../identity.ts";
@@ -12,9 +11,7 @@ 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;
@@ -153,38 +150,50 @@ export class ConfirmationGate {
 
 	/**
 	 * `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.
 	 */
 	async decide(
 		tool: string,
 		input: Record<string, unknown>,
 		ask?: { prompts: Prompts; asker: string; signal?: AbortSignal },
-	): Promise<{ reason?: string; approvedOnCard?: true }> {
+	): 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);
 		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" };
 	}
 
 	/**
@@ -260,46 +269,6 @@ 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}`;
 }
 
-/**
- * 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`.
- */
-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,
@@ -324,12 +293,13 @@ export function confirmationGateExtension(
 				ask = { prompts, asker: slot.asker };
 				if (ctx.signal) ask.signal = ctx.signal;
 			}
-			const { reason, approvedOnCard } = await gate.decide(
+			const { reason, approvedOnCard, refused } = await gate.decide(
 				event.toolName,
 				event.input as Record<string, unknown>,
 				ask,
 			);
 			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)),

package/src/core/runtime/turn-progress.ts

@@ -1,5 +1,5 @@
 import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
-import type { TurnProgress } from "../domain/progress.ts";
+import type { HoldRefusal, TurnProgress } from "../domain/progress.ts";
 
 /** How long text is joined before it is sent, so a fast stream costs a few events a second. */
 export const PROGRESS_INTERVAL_MS = 250;
@@ -19,6 +19,11 @@ export interface ProgressReporter {
 
 export interface ProgressReporterOptions {
 	intervalMs?: number;
+	/**
+	 * Why a hold refused a tool's call, asked when a failed tool ends and read once; the gate that
+	 * refused it is how a surface tells that from a failure.
+	 */
+	refusalOf?: (toolCallId: string) => HoldRefusal | undefined;
 	/** Runs `run` after `ms`; returns a cancel. Replaceable in tests. */
 	setTimer?: (run: () => void, ms: number) => () => void;
 }
@@ -104,7 +109,14 @@ export function progressReporter(
 		toolEnd(id, tool, isError) {
 			if (closed) return;
 			flush();
-			send({ type: "tool_end", id, tool, ok: !isError });
+			const refused = isError ? options.refusalOf?.(id) : undefined;
+			send({
+				type: "tool_end",
+				id,
+				tool,
+				ok: !isError,
+				...(refused ? { refused } : {}),
+			});
 		},
 		close() {
 			if (closed) return;

package/src/core/testing/surface-contract.ts

@@ -332,7 +332,7 @@ const CHECKS: readonly Check[] = [
 			answeredOnlyByThem(running, running.subject.owner, "private"),
 	},
 	{
-		name: "a private conversation's approval above the person's tier goes to no one: it expires at once",
+		name: "a private conversation's approval above the person's tier goes to no one: it comes back at once, unshown",
 		applies: (subject) =>
 			subject.surface.prompts !== undefined &&
 			speakerOf(subject).tier !== "owner",
@@ -349,7 +349,8 @@ const CHECKS: readonly Check[] = [
 				Bun.sleep(1000).then(() => "still open" as const),
 			]);
 			expectThat(
-				answer === "expired",
+				// `expired` is what surfaces answered before `unavailable` existed.
+				answer === "unavailable" || answer === "expired",
 				`an approval no one may answer came back ${answer}`,
 			);
 			expectThat(
@@ -444,7 +445,7 @@ export async function checkSurfaceContract(
  * where it offers them, delivers files, ends typing and stop controls idempotently, shows
  * progress, resolves approvals as the person answers or as a stopped turn cancels them, ignores
  * another person's answer to the person's approval, and, in a private conversation, an owner's
- * too, and lets an approval above the person's tier there expire at once, shown to no one. Each
+ * too, and lets an approval above the person's tier there come back at once, shown to no one. Each
  * check gets a fresh subject from `make`; a check for an optional part the surface lacks passes.
  */
 export function describeSurfaceContract(

package/src/index.ts

@@ -118,7 +118,7 @@ export type {
 	InterimTextMode,
 } from "./core/domain/interim.ts";
 export type { TurnConversation, TurnRequest } from "./core/domain/ports.ts";
-export type { TurnProgress } from "./core/domain/progress.ts";
+export type { HoldRefusal, TurnProgress } from "./core/domain/progress.ts";
 export type { DrainOptions } from "./core/drain.ts";
 export {
 	HostStoppingError,
@@ -161,6 +161,8 @@ export type {
 export { SYSTEM_PRINCIPAL } from "./core/identity/principal-store.ts";
 export type {
 	Approval,
+	ApprovalDetails,
+	ApprovalFile,
 	AskOption,
 	LateAnswer,
 	OwnerAnswer,

package/src/kit/index.ts

@@ -158,6 +158,7 @@ export {
 	toolText,
 } from "./tools.ts";
 export type {
+	CardLimits,
 	InterimPosterOptions,
 	McpEndpoint,
 	PromptSlot,
@@ -165,6 +166,7 @@ export type {
 } from "./worker.ts";
 export {
 	approvalCard,
+	approvalDetails,
 	archiveSessions,
 	canonicalJson,
 	InterimPoster,

package/src/kit/worker.ts

@@ -1,10 +1,12 @@
 // Plugin helpers, versioned like the main entry; see the plugin guide.
 // Running a Pi session of your own: MCP servers for it, its work timeout, its held-action cards.
 
+export type { CardLimits } from "../core/runtime/extensions/approval-card.ts";
 export {
 	approvalCard,
-	canonicalJson,
-} from "../core/runtime/extensions/confirmation-gate.ts";
+	approvalDetails,
+} from "../core/runtime/extensions/approval-card.ts";
+export { canonicalJson } from "../core/runtime/extensions/confirmation-gate.ts";
 export type { InterimPosterOptions } from "../core/runtime/interim-text.ts";
 export { InterimPoster } from "../core/runtime/interim-text.ts";
 export type { VirtualServer } from "../core/runtime/mcp.ts";