pi-roundtable 0.9.6 → 0.9.8

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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
+
+- `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.
@@ -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`.
@@ -2365,7 +2397,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 +2420,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 +2558,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 +2567,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,
@@ -2885,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` |
@@ -3014,7 +3054,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 +3308,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 +3360,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 +3577,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 +3625,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 |
@@ -3593,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/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.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/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/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,11 +28,14 @@ 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
 				? `File \`${path}\` (not found now)`
 				: `File \`${path}\` (${formatBytes(bytes)})`,
+		cardHiddenKeys: (keys: readonly string[]) =>
+			`… not shown: ${keys.join(", ")}`,
 	};
 }
 
@@ -57,10 +60,12 @@ 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
 				? `檔案 \`${path}\`（目前找不到）`
 				: `檔案 \`${path}\`（${formatBytes(bytes)}）`,
+		cardHiddenKeys: (keys: readonly string[]) => `… 未顯示：${keys.join("、")}`,
 	};
 }