@danypops/papyrus 0.19.1 → 0.21.0

package/README.md

@@ -162,11 +162,15 @@ Rounds are a dedicated append-only child table (mirroring Task history's own sha
 
 Blocking is real: `tasks.complete` is refused while any `active` Discussion has a `blocks` edge to that Task. A `deferred` Discussion does not block -- "we will get back to this" is distinct from "resolved."
 
-Run `/discuss` for the interactive panel: browse every Discussion (the real `active`/`deferred`/`settled` state shown per row, not just the shared Doc status glyph), open a scrollable transcript, and reply/defer/resume/settle or block/unblock a task without leaving the TUI. Opening a *new* Discussion is left to the agent (same as Docs/Rules/Skills) -- `/discuss` browses and drives existing ones.
+`open`/`reply` can also pose a structured choice instead of (or alongside) free text: `options` (2-10 entries) plus `options_mode` -- `single` is mutually exclusive (exactly one pick), `multi` allows several. The Discussion remembers the pending choice (`extra.discussion.pendingOptions`/`pendingOptionsMode`) until a `reply` answers it with `selected`, validated against exactly what was offered and the mode's cardinality; a reply can also pose the *next* round's choice in the same call.
+
+Run `/discuss` for the interactive panel: browse every Discussion (the real `active`/`deferred`/`settled` state shown per row, alongside any choice awaiting an answer), open a scrollable transcript showing what was posed and picked in each round, and reply/defer/resume/settle or block/unblock a task without leaving the TUI. Replying to a pending choice shows a real picker -- the native single-select list for `single`, or a checkbox multi-select (space to toggle, enter to confirm) for `multi`, since no built-in multi-select exists in the Pi extension UI. Opening a *new* Discussion is left to the agent (same as Docs/Rules/Skills) -- `/discuss` browses and drives existing ones.
 
 ```bash
 papyrus discuss open --title "Naming" --actor alice --content "Should we rename this?" --blocks-json '["task-id"]' --json
+papyrus discuss open --title "Which approach" --actor alice --content "Pick one" --options-json '["A","B"]' --options-mode single --json
 papyrus discuss reply <discussion-id> --actor bob --content "I think so, here's why..." --json
+papyrus discuss reply <discussion-id> --actor bob --content "Going with B" --selected-json '["B"]' --json
 papyrus discuss defer <discussion-id> --reason "Waiting on design review" --json
 papyrus discuss resume <discussion-id> --json
 papyrus discuss settle <discussion-id> --settlement "Agreed: renaming to X" --json
@@ -175,6 +179,8 @@ papyrus discuss show <discussion-id> --json
 
 ## Tasks
 
+The `tasks` agent tool addresses a task by `name` (its exact title) wherever `id` would otherwise be required -- `dependency_name`/`parent_name`/`child_name`/`root_task_name`/`depends_on_names` are the name-based equivalents of `dependency_id`/`parent_id`/`child_id`/`root_task_id`/`depends_on`. Resolution is an exact, case-insensitive, trimmed title match scoped like a plain list call; an unmatched or ambiguous name fails with a clear error (ambiguous names list the real ids, since that's the one point disambiguation genuinely needs them). Task results returned to the agent likewise lead with name and status, never id, unless two tasks in the same result share a title -- id is a backend implementation detail, not a conversational handle. `id` itself still works exactly as before for every action.
+
 Run `/tasks` for the interactive task panel:
 
 - `/` filters; arrow keys navigate; Enter opens task actions; `s` switches among the persisted current-project, focused-root graph, and explicit all-projects views

package/extension/src/discuss.ts

@@ -15,9 +15,11 @@
 import type { ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
 import type { Artifact } from "../../src/domain/artifact.ts";
 import type { DiscussionAndRounds } from "../../src/discussion-service.ts";
+import { readDiscussionExtra } from "../../src/domain/discussion.ts";
 import { showArtifactBrowser } from "./artifact-browser.ts";
 import { DISCUSSION_STATE_PRESENTATION, DOC_STATUS_PRESENTATION } from "./artifact-status-presentation.ts";
 import { discussionRoundCountOf, discussionStateOf, showDiscussionDetailView } from "./discussion-detail-view.ts";
+import { pickDiscussionOptions } from "./discussion-picker.ts";
 import { callService } from "./service-client.ts";
 
 const SOURCE = "discuss-tui";
@@ -28,7 +30,9 @@ export function discussionRowMeta(discussion: Artifact, theme: Theme): string {
 	const presentation = DISCUSSION_STATE_PRESENTATION[state];
 	const stateText = presentation ? theme.fg(presentation.color, `${presentation.glyph} ${presentation.label}`) : theme.fg("muted", "state unknown");
 	const rounds = discussionRoundCountOf(discussion);
-	return `${stateText} · ${rounds} round${rounds === 1 ? "" : "s"}`;
+	const pending = (() => { try { return readDiscussionExtra(discussion.extra).pendingOptions; } catch { return undefined; } })();
+	const pendingText = pending && pending.length > 0 ? theme.fg("accent", ` · awaiting: ${pending.join("/")}`) : "";
+	return `${stateText} · ${rounds} round${rounds === 1 ? "" : "s"}${pendingText}`;
 }
 
 function discussionActions(discussion: Artifact): string[] {
@@ -54,6 +58,16 @@ export async function showDiscussions(ctx: ExtensionCommandContext): Promise<voi
 				return;
 			}
 			if (choice === "Reply") {
+				const pending = (() => { try { return readDiscussionExtra(discussion.extra); } catch { return undefined; } })();
+				if (pending?.pendingOptions && pending.pendingOptions.length > 0 && pending.pendingOptionsMode) {
+					const selected = await pickDiscussionOptions(commandCtx, pending.pendingOptionsMode, pending.pendingOptions);
+					if (!selected) return; // canceled
+					const elaboration = await commandCtx.ui.input("Elaborate (optional):", selected.join(", "));
+					if (elaboration === undefined) return; // canceled
+					await callService("discuss.reply", { id: discussion.id, actor: ACTOR, content: elaboration || selected.join(", "), selected, source: SOURCE });
+					commandCtx.ui.notify(`Selected: ${selected.join(", ")}`, "info");
+					return;
+				}
 				const content = await commandCtx.ui.input("Reply:", "");
 				if (!content) return;
 				await callService("discuss.reply", { id: discussion.id, actor: ACTOR, content, source: SOURCE });

package/extension/src/discussion-detail-view.ts

@@ -112,7 +112,13 @@ class DiscussionTranscriptViewport {
 		const transcript: TranscriptLine[] = this.rounds.flatMap((round, index) => {
 			const roundHeader = theme.fg("accent", `[round ${round.roundNumber}] `) + theme.bold(round.actor) + theme.fg("dim", ` · ${round.occurredAt}`);
 			const body = renderMarkdownBody(round.content, width - 2, this.activeTheme).map((line) => ({ text: `  ${line}` }));
-			return [{ text: roundHeader }, ...body, ...(index < this.rounds.length - 1 ? [{ text: "" }] : [])];
+			const posed = round.options && round.options.length > 0
+				? [{ text: `  ${theme.fg("muted", `Posed (${round.optionsMode === "multi" ? "pick several" : "pick one"}): ${round.options.join(", ")}`)}` }]
+				: [];
+			const picked = round.selected && round.selected.length > 0
+				? [{ text: `  ${theme.fg("success", `Selected: ${round.selected.join(", ")}`)}` }]
+				: [];
+			return [{ text: roundHeader }, ...body, ...posed, ...picked, ...(index < this.rounds.length - 1 ? [{ text: "" }] : [])];
 		});
 		this.lines = [...header, ...(transcript.length > 0 ? transcript : [{ text: theme.fg("muted", "No rounds recorded.") }])];
 		this.offsetY = Math.min(this.offsetY, Math.max(0, this.lines.length - this.visibleLines));

package/extension/src/discussion-picker.ts

@@ -0,0 +1,59 @@
+/**
+ * discussion-picker.ts — the structured-choice picker for /discuss's "Reply" action.
+ *
+ * "single" mode (mutually exclusive) needs nothing bespoke: the Pi extension UI already
+ * provides exactly that (ctx.ui.select). "multi" (allow several) has no native equivalent
+ * anywhere in @earendil-works/pi-coding-agent or pi-tui (checked both) -- so this is a small,
+ * genuinely domain-specific checkbox-list component, not a generic library replacement.
+ */
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import type { DiscussionOptionsMode } from "../../src/domain/discussion.ts";
+
+/** Toggle with space, confirm with enter (refuses an empty confirm -- at least one pick is required), cancel with escape. */
+async function pickMultiple(ctx: ExtensionCommandContext, title: string, options: string[]): Promise<string[] | undefined> {
+	return ctx.ui.custom<string[] | undefined>((tui, theme, _keybindings, done) => {
+		const checked = new Set<number>();
+		let selectedIndex = 0;
+		return {
+			invalidate() {},
+			render(width: number): string[] {
+				const lines: string[] = [
+					theme.bold(title),
+					theme.fg("muted", "space toggle \u00b7 enter confirm \u00b7 esc cancel"),
+					"",
+				];
+				options.forEach((option, index) => {
+					const cursor = index === selectedIndex ? theme.fg("accent", "\u276f") : " ";
+					const box = checked.has(index) ? theme.fg("success", "[x]") : "[ ]";
+					const label = index === selectedIndex ? theme.bold(option) : option;
+					lines.push(truncateToWidth(`${cursor} ${box} ${label}`, width, ""));
+				});
+				lines.push("");
+				lines.push(theme.fg("dim", `${checked.size} selected`));
+				return lines;
+			},
+			handleInput(data: string) {
+				if (matchesKey(data, "up")) selectedIndex = (selectedIndex - 1 + options.length) % options.length;
+				else if (matchesKey(data, "down")) selectedIndex = (selectedIndex + 1) % options.length;
+				else if (data === " ") { if (checked.has(selectedIndex)) checked.delete(selectedIndex); else checked.add(selectedIndex); }
+				else if (matchesKey(data, "enter")) {
+					if (checked.size === 0) return; // refuse an empty confirm -- selecting nothing isn't a valid answer
+					done([...checked].sort((a, b) => a - b).map((index) => options[index]!));
+					return;
+				} else if (matchesKey(data, "escape")) { done(undefined); return; }
+				else return;
+				tui.requestRender();
+			},
+		};
+	});
+}
+
+/** Picks one (single) or several (multi) of the given options, or undefined if the user cancels. */
+export async function pickDiscussionOptions(ctx: ExtensionCommandContext, mode: DiscussionOptionsMode, options: string[]): Promise<string[] | undefined> {
+	if (mode === "single") {
+		const pick = await ctx.ui.select("Pick one:", options);
+		return pick ? [pick] : undefined;
+	}
+	return pickMultiple(ctx, "Pick one or more:", options);
+}

package/extension/src/domain-tools.ts

@@ -33,6 +33,47 @@ function artifactLine(artifact: Artifact): string {
 	return `${artifact.id} [${artifact.status}] ${artifact.title}`;
 }
 
+/**
+ * Tasks-only: the model's primary interfacing point is the task's NAME, not its id -- id is a
+ * backend detail (a stable key other operations need, and titles aren't guaranteed unique), so
+ * it stays out of what the model reads by default. It only resurfaces when genuinely needed to
+ * tell two same-titled tasks apart (taskLines below), or in a matchTaskByName disambiguation
+ * error, never as a matter of course. This is scoped to the tasks tool specifically -- Docs/
+ * Rules/Skills/Discuss keep the shared artifactLine above unless a similar request covers them.
+ */
+export function taskLine(task: Artifact): string {
+	return `[${task.status}] ${task.title}`;
+}
+
+/** Appends " (id)" only for tasks whose title collides with another in this same result set. */
+export function taskLines(tasks: Artifact[]): string[] {
+	const titleCounts = new Map<string, number>();
+	for (const task of tasks) titleCounts.set(task.title, (titleCounts.get(task.title) ?? 0) + 1);
+	return tasks.map((task) => (titleCounts.get(task.title)! > 1 ? `${taskLine(task)} (${task.id})` : taskLine(task)));
+}
+
+/**
+ * Exact, case-insensitive, trimmed title match against an already-fetched candidate set. Throws
+ * a clear "not found" or "ambiguous -- use id" error rather than guessing at a fuzzy match -- id
+ * remains the one truly unambiguous key, so ambiguity is exactly where it's allowed to resurface.
+ * Pure and synchronous so it's directly testable without a service round-trip.
+ */
+export function matchTaskByName(candidates: Artifact[], name: string): string {
+	const needle = name.trim().toLowerCase();
+	const matches = candidates.filter((task) => task.title.trim().toLowerCase() === needle);
+	if (matches.length === 0) throw new Error(`no task named "${name}" found in this scope`);
+	if (matches.length > 1) {
+		throw new Error(`${matches.length} tasks are named "${name}": ${matches.map((task) => `${task.title} (${task.id})`).join(", ")} -- use id to disambiguate`);
+	}
+	return matches[0]!.id;
+}
+
+/** Resolves a task name to its id, scoped the same way a plain `tasks list` call would be (same project_root/session_id/scope). */
+async function resolveTaskIdByName(baseRequest: Record<string, unknown>, name: string): Promise<string> {
+	const candidates = await callService<Record<string, unknown>, Artifact[]>("tasks.list", { ...baseRequest, text: name });
+	return matchTaskByName(candidates, name);
+}
+
 /**
  * Shared "remove"/"restore" dispatch for every domain tool (tasks/docs/rules/skills) --
  * artifact.remove/restore are kind-agnostic composition-root operations (see service.ts),
@@ -67,10 +108,11 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "tasks",
 		label: "Tasks",
-		description: "Task domain tool. ACTIONS: create, update, list, show, history, scope, set_scope, assign_project, graph, plan, active, focused, focus, pause, unpause, clear_focus, start, submit, complete, reject, retry, cancel, run_gates, set_checklist, depend, undepend, contain, uncontain, remove, restore. Lifecycle is todo → in-progress → review → done, with review failure → rejected and retry → in-progress; canceled is terminal. update can recover a Task accidentally created terminal by setting status=todo with a reason, but cannot rewrite legitimate lifecycle history. Active focus is independent and identifies the one task auto-drive continues. Completion runs gates and checklist-proof review, then focuses one deterministic ready successor without claiming effort. Dependency cycles are rejected. undepend/uncontain are idempotent for an already-absent relationship and never start, complete, or focus work merely because an edge disappeared; uncontain removes both contains and part_of edges atomically. remove moves a Task to a time-gated trash (restorable via restore until the purge deadline; refuses if it is the live Task Focus). Prefer this over low-level papyrus_* tools for task work.",
+		description: "Task domain tool. ACTIONS: create, update, list, show, history, scope, set_scope, assign_project, graph, plan, active, focused, focus, pause, unpause, clear_focus, start, submit, complete, reject, retry, cancel, run_gates, set_checklist, depend, undepend, contain, uncontain, remove, restore. Lifecycle is todo → in-progress → review → done, with review failure → rejected and retry → in-progress; canceled is terminal. update can recover a Task accidentally created terminal by setting status=todo with a reason, but cannot rewrite legitimate lifecycle history. Active focus is independent and identifies the one task auto-drive continues. Completion runs gates and checklist-proof review, then focuses one deterministic ready successor without claiming effort. Dependency cycles are rejected. undepend/uncontain are idempotent for an already-absent relationship and never start, complete, or focus work merely because an edge disappeared; uncontain removes both contains and part_of edges atomically. remove moves a Task to a time-gated trash (restorable via restore until the purge deadline; refuses if it is the live Task Focus). PREFER addressing a task by `name` (its exact title) over `id` for every action -- id is a backend implementation detail, resolved from name automatically, and only needs to appear explicitly when a name is genuinely ambiguous (two tasks share a title; the error will say so and list the real ids to disambiguate with). Task results likewise show name and status, not id, unless two shown tasks share a title. `dependency_name`/`parent_name`/`child_name`/`root_task_name`/`depends_on_names` are the name-based equivalents of `dependency_id`/`parent_id`/`child_id`/`root_task_id`/`depends_on`. Prefer this over low-level papyrus_* tools for task work.",
 		parameters: Type.Object({
 			action: Type.String(),
 			id: Type.Optional(Type.String()),
+			name: Type.Optional(Type.String()),
 			title: Type.Optional(Type.String()),
 			body: Type.Optional(Type.String()),
 			status: Type.Optional(Type.String()),
@@ -86,17 +128,23 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 			checklist: Type.Optional(Type.Record(Type.String(), checklistCriterionSchema)),
 			template_id: Type.Optional(Type.String()),
 			parent_id: Type.Optional(Type.String()),
+			parent_name: Type.Optional(Type.String()),
 			child_id: Type.Optional(Type.String()),
+			child_name: Type.Optional(Type.String()),
 			dependency_id: Type.Optional(Type.String()),
+			dependency_name: Type.Optional(Type.String()),
 			depends_on: Type.Optional(Type.Array(Type.String())),
+			depends_on_names: Type.Optional(Type.Array(Type.String())),
 			project_root: Type.Optional(Type.String()),
 			scope: Type.Optional(Type.Union([Type.Literal("project"), Type.Literal("graph"), Type.Literal("all")])),
 			root_task_id: Type.Optional(Type.String()),
+			root_task_name: Type.Optional(Type.String()),
 		}),
 		renderCall(args, theme) { return renderPapyrusToolCall("Tasks", args, theme); },
 		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },
-		async execute(_id, params, _signal, _onUpdate, ctx) {
+		async execute(_id, rawParams, _signal, _onUpdate, ctx) {
 			try {
+				const params: Record<string, unknown> = { ...rawParams };
 				const action = params.action;
 				// Defaults to this Pi session's own id so Focus reads/writes are isolated per agent
 				// without depending on the model to know or supply its own session identity.
@@ -105,18 +153,37 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 				// session never gets this session's secret smuggled in on its behalf -- the cache only
 				// ever holds this extension's own registered session anyway (see session-identity.ts).
 				const resolvedSessionId = params.session_id ?? ctx.sessionManager.getSessionId();
-				const request = { ...params, project_root: params.project_root ?? ctx.cwd, actor: "agent", source: "pi-tool", session_id: resolvedSessionId, ...sessionSecretField(resolvedSessionId as string) };
+				const baseRequest = { project_root: params.project_root ?? ctx.cwd, actor: "agent", source: "pi-tool", session_id: resolvedSessionId, ...sessionSecretField(resolvedSessionId as string) };
+				// Resolves every *_name field to its *_id counterpart before dispatch, so every action
+				// below can go on reading id/dependency_id/parent_id/child_id/root_task_id exactly as
+				// before -- id-based calls are unaffected; name-based ones are transparently rewritten.
+				const resolveField = async (nameKey: string, idKey: string) => {
+					const nameValue = params[nameKey];
+					if (typeof nameValue === "string" && nameValue.length > 0 && !params[idKey]) {
+						params[idKey] = await resolveTaskIdByName(baseRequest, nameValue);
+					}
+				};
+				await resolveField("name", "id");
+				await resolveField("dependency_name", "dependency_id");
+				await resolveField("parent_name", "parent_id");
+				await resolveField("child_name", "child_id");
+				await resolveField("root_task_name", "root_task_id");
+				const dependsOnNames = params["depends_on_names"];
+				if (Array.isArray(dependsOnNames) && dependsOnNames.length > 0 && !params["depends_on"]) {
+					params["depends_on"] = await Promise.all(dependsOnNames.map((entry) => resolveTaskIdByName(baseRequest, String(entry))));
+				}
+				const request = { ...params, ...baseRequest };
 				if (action === "create") {
 					const artifact = await callService<Record<string, unknown>, Artifact>("tasks.create", request);
-					return text(`Created task ${artifactLine(artifact)}`, createArtifactDetails("tasks.create", artifact));
+					return text(`Created task ${taskLine(artifact)}`, createArtifactDetails("tasks.create", artifact));
 				}
 				if (action === "list") {
 					const rows = await callService<Record<string, unknown>, Artifact[]>("tasks.list", request);
-					return text(rows.length ? rows.map(artifactLine).join("\n") : "No tasks found.", createArtifactListDetails("tasks.list", rows));
+					return text(rows.length ? taskLines(rows).join("\n") : "No tasks found.", createArtifactListDetails("tasks.list", rows));
 				}
 				if (action === "show") {
 					const artifact = await callService<Record<string, unknown>, Artifact>("tasks.show", params);
-					return text(`${artifactLine(artifact)}\n\n${artifact.body}`, createArtifactDetails("tasks.show", artifact));
+					return text(`${taskLine(artifact)}\n\n${artifact.body}`, createArtifactDetails("tasks.show", artifact));
 				}
 				if (action === "history") {
 					const page = await callService<Record<string, unknown>, TaskHistoryPage>("tasks.history", request);
@@ -131,20 +198,20 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 				if (action === "active") {
 					const artifact = await callService<Record<string, unknown>, Artifact | null>("tasks.active", request);
 					return artifact
-						? text(`Active: ${artifactLine(artifact)}`, createArtifactDetails("tasks.active", artifact))
+						? text(`Active: ${taskLine(artifact)}`, createArtifactDetails("tasks.active", artifact))
 						: text("No active task.", createPreviewDetails("tasks.active", "Active task", "No active task."));
 				}
 				if (action === "focused") {
 					const focus = await callService<Record<string, unknown>, { artifact: Artifact; status: string } | null>("tasks.focused", request);
 					return focus
-						? text(`Focused (${focus.status}): ${artifactLine(focus.artifact)}`, createArtifactDetails("tasks.focused", focus.artifact))
+						? text(`Focused (${focus.status}): ${taskLine(focus.artifact)}`, createArtifactDetails("tasks.focused", focus.artifact))
 						: text("No focused task.", createPreviewDetails("tasks.focused", "Focused task", "No focused task."));
 				}
 				if (action === "pause" || action === "unpause") {
 					const operation = action === "pause" ? "tasks.pause" : "tasks.unpause";
 					const focus = await callService<Record<string, unknown>, { artifact: Artifact; status: string }>(operation, request);
 					emitTaskFocusEvent({ taskId: focus.artifact.id, sessionId: request.session_id as string, status: action === "pause" ? "paused" : "unpaused" });
-					return text(`Focused (${focus.status}): ${artifactLine(focus.artifact)}`, createArtifactDetails(operation, focus.artifact));
+					return text(`Focused (${focus.status}): ${taskLine(focus.artifact)}`, createArtifactDetails(operation, focus.artifact));
 				}
 				if (action === "clear_focus") {
 					const result = await callService<Record<string, unknown>, { cleared: boolean }>("tasks.clear_focus", request);
@@ -168,11 +235,16 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 				if (action === "plan") {
 					const plan = await callService<Record<string, unknown>, TaskExecutionPlan>("tasks.plan", request);
 					const byId = new Map(plan.nodes.map((node) => [node.id, node]));
+					const titleCounts = new Map<string, number>();
+					for (const node of plan.nodes) titleCounts.set(node.title, (titleCounts.get(node.title) ?? 0) + 1);
 					const lines = plan.layers.flatMap((layer, index) => [
 						`Layer ${index + 1}`,
 						...layer.map((id) => {
 							const node = byId.get(id);
-							return node ? `  [${node.state}] ${node.id} ${node.title}` : `  [unknown] ${id}`;
+							if (!node) return `  [unknown] ${id}`;
+							return (titleCounts.get(node.title) ?? 0) > 1
+								? `  [${node.state}] ${node.title} (${node.id})`
+								: `  [${node.state}] ${node.title}`;
 						}),
 					]);
 					if (plan.cycleIds.length > 0) lines.push(`Invalid cycle: ${plan.cycleIds.join(", ")}`);
@@ -181,24 +253,25 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 				}
 				if (action === "set_checklist") {
 					const artifact = await callService<Record<string, unknown>, Artifact>("tasks.set_checklist", params);
-					return text(`Updated checklist: ${artifactLine(artifact)}`, createArtifactDetails("tasks.set_checklist", artifact));
+					return text(`Updated checklist: ${taskLine(artifact)}`, createArtifactDetails("tasks.set_checklist", artifact));
 				}
 				if (action === "complete") {
 					const result = await callService<Record<string, unknown>, TaskCompletion>("tasks.complete", request);
 					const gates = result.gates.map((gate) => `${gate.passed ? "✓" : "✗"} ${gate.gate.type}: ${gate.gate.target} — ${gate.output}`).join("\n");
 					const checklist = result.checklist.map((item) => `${item.accepted ? "✓" : "✗"} proof: ${item.item}${item.reason ? ` — ${item.reason}` : ""}`).join("\n");
-					const focused = result.focused ? `\nActive: ${artifactLine(result.focused)}` : "";
+					const focused = result.focused ? `\nActive: ${taskLine(result.focused)}` : "";
+					const blockedLines = taskLines(result.blocked.map((entry) => entry.artifact));
 					const blocked = result.blocked.length > 0
-						? `\nBlocked: ${result.blocked.map((entry) => `${artifactLine(entry.artifact)} waits for ${entry.dependencyIds.join(", ")}`).join("; ")}`
+						? `\nBlocked: ${result.blocked.map((entry, index) => `${blockedLines[index]} waits for ${entry.dependencyIds.join(", ")}`).join("; ")}`
 						: "";
-					const output = `${result.completed ? "Completed" : "Rejected"}: ${artifactLine(result.artifact)}${focused}${blocked}${checklist ? `\n${checklist}` : ""}${gates ? `\n${gates}` : ""}`;
+					const output = `${result.completed ? "Completed" : "Rejected"}: ${taskLine(result.artifact)}${focused}${blocked}${checklist ? `\n${checklist}` : ""}${gates ? `\n${gates}` : ""}`;
 					return text(output, createPreviewDetails("tasks.complete", "Task completion", output));
 				}
 				if (action === "run_gates") {
 					const gates = await callService<Record<string, unknown>, GateResult[]>("tasks.run_gates", request);
 					return text(
 						gates.map((gate) => `${gate.passed ? "✓" : "✗"} ${gate.gate.type}: ${gate.gate.target} — ${gate.output}`).join("\n") || "No gates configured.",
-						createGateRunDetails("tasks.run_gates", params.id ?? "", gates.map((gate) => ({
+						createGateRunDetails("tasks.run_gates", (params.id as string | undefined) ?? "", gates.map((gate) => ({
 							passed: gate.passed, type: gate.gate.type, target: gate.gate.target, output: gate.output,
 						}))),
 					);
@@ -224,7 +297,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 				if (!operation) throw new Error(`unknown tasks action: ${action}`);
 				const artifact = await callService<Record<string, unknown>, Artifact>(operation, request);
 				if (operation === "tasks.focus") emitTaskFocusEvent({ taskId: artifact.id, sessionId: request.session_id as string, status: "focused" });
-				return text(artifactLine(artifact), createArtifactDetails(operation, artifact));
+				return text(taskLine(artifact), createArtifactDetails(operation, artifact));
 			} catch (error) {
 				throw new Error(`tasks failed: ${error instanceof Error ? error.message : error}`);
 			}
@@ -438,7 +511,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "discuss",
 		label: "Discuss",
-		description: "Native Papyrus deliberation with a real lifecycle -- distinct from a one-shot ask: a Discussion persists, takes multiple rounds, and can genuinely block a Task's completion until settled or deferred. ACTIONS: open, reply, defer, resume, settle, block, unblock, show, rounds, list. open starts round 1 and optionally blocks_task_ids immediately. reply is refused once deferred or settled -- resume first. defer is explicitly non-blocking (paused, resumable); settle is terminal and archives the discussion. block/unblock manage the blocking relationship to a task independently of open. A task's completion is refused while any active Discussion blocks it.",
+		description: "Native Papyrus deliberation with a real lifecycle -- distinct from a one-shot ask: a Discussion persists, takes multiple rounds, and can genuinely block a Task's completion until settled or deferred. ACTIONS: open, reply, defer, resume, settle, block, unblock, show, rounds, list. open starts round 1 and optionally blocks_task_ids immediately. reply is refused once deferred or settled -- resume first. defer is explicitly non-blocking (paused, resumable); settle is terminal and archives the discussion. block/unblock manage the blocking relationship to a task independently of open. A task's completion is refused while any active Discussion blocks it. open/reply can pose a structured choice via options (2-10 entries) + options_mode ('single' mutually exclusive, 'multi' allows several); reply answers a currently pending choice via selected, validated against it.",
 		parameters: Type.Object({
 			action: Type.String(),
 			id: Type.Optional(Type.String()),
@@ -454,6 +527,9 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 			state: Type.Optional(Type.String()),
 			after_round: Type.Optional(Type.Number()),
 			limit: Type.Optional(Type.Number()),
+			options: Type.Optional(Type.Array(Type.String())),
+			options_mode: Type.Optional(Type.String()),
+			selected: Type.Optional(Type.Array(Type.String())),
 		}),
 		renderCall(args, theme) { return renderPapyrusToolCall("Discuss", args, theme); },
 		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.19.1",
+  "version": "0.21.0",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],

package/src/adapters/sqlite-discussion-round-store.ts

@@ -1,6 +1,14 @@
 import type { Db } from "../db.ts";
 import { DISCUSSION_ROUNDS_DEFAULT_LIMIT, DISCUSSION_ROUNDS_MAX_LIMIT } from "../constants.ts";
-import { validateDiscussionActor, validateDiscussionContent, type AppendDiscussionRound, type DiscussionRound, type DiscussionRoundQuery } from "../domain/discussion.ts";
+import {
+	validateDiscussionActor,
+	validateDiscussionContent,
+	validateDiscussionOptions,
+	type AppendDiscussionRound,
+	type DiscussionOptionsMode,
+	type DiscussionRound,
+	type DiscussionRoundQuery,
+} from "../domain/discussion.ts";
 import type { DiscussionRoundStore } from "../ports/discussion-round-store.ts";
 
 interface DiscussionRoundRow {
@@ -10,6 +18,9 @@ interface DiscussionRoundRow {
 	actor: string;
 	content: string;
 	occurred_at: string;
+	options: string | null;
+	options_mode: string | null;
+	selected: string | null;
 }
 
 function mapRow(row: DiscussionRoundRow): DiscussionRound {
@@ -20,6 +31,9 @@ function mapRow(row: DiscussionRoundRow): DiscussionRound {
 		actor: row.actor,
 		content: row.content,
 		occurredAt: row.occurred_at,
+		...(row.options !== null ? { options: JSON.parse(row.options) as string[] } : {}),
+		...(row.options_mode !== null ? { optionsMode: row.options_mode as DiscussionOptionsMode } : {}),
+		...(row.selected !== null ? { selected: JSON.parse(row.selected) as string[] } : {}),
 	};
 }
 
@@ -29,10 +43,21 @@ export class SQLiteDiscussionRoundStore implements DiscussionRoundStore {
 	append(round: AppendDiscussionRound, occurredAt: string): DiscussionRound {
 		const content = validateDiscussionContent(round.content);
 		const actor = validateDiscussionActor(round.actor);
+		// selected isn't validated here -- it requires cross-referencing the Discussion's
+		// currently pending options (extra.discussion), which this store, deliberately scoped to
+		// the rounds table alone, has no access to. discussion-service.ts validates it beforehand.
+		const posed = round.options !== undefined || round.optionsMode !== undefined
+			? validateDiscussionOptions(round.options ?? [], round.optionsMode ?? "")
+			: undefined;
 		const result = this.db.prepare(`
-			INSERT INTO discussion_rounds (discussion_id, round_number, actor, content, occurred_at, event_schema_version)
-			VALUES (?, ?, ?, ?, ?, 1)
-		`).run(round.discussionId, round.roundNumber, actor, content, occurredAt);
+			INSERT INTO discussion_rounds (discussion_id, round_number, actor, content, occurred_at, event_schema_version, options, options_mode, selected)
+			VALUES (?, ?, ?, ?, ?, 1, ?, ?, ?)
+		`).run(
+			round.discussionId, round.roundNumber, actor, content, occurredAt,
+			posed ? JSON.stringify(posed.options) : null,
+			posed ? posed.mode : null,
+			round.selected !== undefined ? JSON.stringify(round.selected) : null,
+		);
 		return {
 			id: Number(result.lastInsertRowid),
 			discussionId: round.discussionId,
@@ -40,13 +65,15 @@ export class SQLiteDiscussionRoundStore implements DiscussionRoundStore {
 			actor,
 			content,
 			occurredAt,
+			...(posed ? { options: posed.options, optionsMode: posed.mode } : {}),
+			...(round.selected !== undefined ? { selected: [...round.selected] } : {}),
 		};
 	}
 
 	list(query: DiscussionRoundQuery): DiscussionRound[] {
 		const limit = Math.min(DISCUSSION_ROUNDS_MAX_LIMIT, Math.max(1, Math.floor(query.limit ?? DISCUSSION_ROUNDS_DEFAULT_LIMIT)));
 		const rows = this.db.prepare(`
-			SELECT id, discussion_id, round_number, actor, content, occurred_at
+			SELECT id, discussion_id, round_number, actor, content, occurred_at, options, options_mode, selected
 			FROM discussion_rounds
 			WHERE discussion_id = ? AND round_number > ?
 			ORDER BY round_number ASC

package/src/cli.ts

@@ -118,8 +118,8 @@ const USAGE = `Usage:
   papyrus log append --source <id> --level <debug|info|warning|error> --message <text> --operation-id <id> [--source-label <text>] [--fields-json <json>] [--session-id <id>] [--occurred-at <iso>] [--global] [--json]
   papyrus session register --session-id <id> [--json]
   papyrus session release --session-id <id> [--session-secret <secret>] [--json]
-  papyrus discuss open --title <t> --actor <a> --content <c> [--body <b>] [--labels-json <json>] [--blocks-json <json>] [--json]
-  papyrus discuss reply <id> --actor <a> --content <c> [--json]
+  papyrus discuss open --title <t> --actor <a> --content <c> [--body <b>] [--labels-json <json>] [--blocks-json <json>] [--options-json <json>] [--options-mode single|multi] [--json]
+  papyrus discuss reply <id> --actor <a> --content <c> [--selected-json <json>] [--options-json <json>] [--options-mode single|multi] [--json]
   papyrus discuss defer <id> [--reason <text>] [--json]
   papyrus discuss resume <id> [--json]
   papyrus discuss settle <id> --settlement <text> [--json]
@@ -999,6 +999,9 @@ export async function runDiscussCli(args: string[], client: TaskCliClient): Prom
 	let state: string | undefined;
 	let afterRound: number | undefined;
 	let limit: number | undefined;
+	let options: string[] | undefined;
+	let optionsMode: string | undefined;
+	let selected: string[] | undefined;
 	for (let index = 0; index < args.length; index++) {
 		const argument = args[index]!;
 		if (argument === "--json") continue;
@@ -1009,6 +1012,9 @@ export async function runDiscussCli(args: string[], client: TaskCliClient): Prom
 		if (argument === "--labels-json") { labels = parseJsonStringArrayFlag(args[++index], "--labels-json"); continue; }
 		if (argument === "--blocks-json") { blocksTaskIds = parseJsonStringArrayFlag(args[++index], "--blocks-json"); continue; }
 		if (argument === "--task-id") { taskId = args[++index]; if (!taskId) throw new Error("--task-id requires a value"); continue; }
+		if (argument === "--options-json") { options = parseJsonStringArrayFlag(args[++index], "--options-json"); continue; }
+		if (argument === "--options-mode") { optionsMode = args[++index]; if (!optionsMode) throw new Error("--options-mode requires a value"); continue; }
+		if (argument === "--selected-json") { selected = parseJsonStringArrayFlag(args[++index], "--selected-json"); continue; }
 		if (argument === "--reason") { reason = args[++index]; if (reason === undefined) throw new Error("--reason requires a value"); continue; }
 		if (argument === "--settlement") { settlement = args[++index]; if (!settlement) throw new Error("--settlement requires a value"); continue; }
 		if (argument === "--state") { state = args[++index]; if (!state) throw new Error("--state requires a value"); continue; }
@@ -1031,12 +1037,12 @@ export async function runDiscussCli(args: string[], client: TaskCliClient): Prom
 	switch (action) {
 		case "open": {
 			if (id) throw new Error("discuss open accepts no positional arguments");
-			const result = await client.call<Record<string, unknown>, unknown>("discuss.open", { title, actor, content, body, labels, blocks_task_ids: blocksTaskIds });
+			const result = await client.call<Record<string, unknown>, unknown>("discuss.open", { title, actor, content, body, labels, blocks_task_ids: blocksTaskIds, options, options_mode: optionsMode });
 			return json ? JSON.stringify(result) : JSON.stringify(result, null, 2);
 		}
 		case "reply": {
 			if (!id) throw new Error("discuss reply requires exactly one discussion id");
-			const result = await client.call<Record<string, unknown>, unknown>("discuss.reply", { id, actor, content });
+			const result = await client.call<Record<string, unknown>, unknown>("discuss.reply", { id, actor, content, selected, options, options_mode: optionsMode });
 			return json ? JSON.stringify(result) : JSON.stringify(result, null, 2);
 		}
 		case "defer": {

package/src/constants.ts

@@ -7,7 +7,7 @@ export const DAEMON_PROBE_TIMEOUT_MS = 800;
 export const DAEMON_UNIT_NAME = "papyrus.service";
 export const DAEMON_DIR_ENV = "PAPYRUS_DAEMON_DIR";
 export const SQLITE_BUSY_TIMEOUT_MS = 5_000;
-export const SQLITE_SCHEMA_VERSION = 15;
+export const SQLITE_SCHEMA_VERSION = 16;
 export const SERVICE_MAX_BODY_BYTES = 1_048_576;
 
 export const WAL_CHECKPOINT_INTERVAL_MS = 60_000;
@@ -158,6 +158,14 @@ export const DISCUSSION_LIST_MAX_LIMIT = 200;
 export const DISCUSSION_SETTLEMENT_MAX_CHARACTERS = 4_000;
 export const DISCUSSION_DEFER_REASON_MAX_CHARACTERS = 2_000;
 export const DISCUSSION_ACTOR_MAX_LENGTH = 128;
+/**
+ * A posed choice (open/reply with options): "single" is mutually exclusive (exactly one pick),
+ * "multi" allows several. Mirrors opencode's QuestionV2 labeled-multiple-choice model (the one
+ * piece of prior art surveyed that already solves this), kept native and dependency-free here.
+ */
+export const DISCUSSION_OPTIONS_MIN_COUNT = 2;
+export const DISCUSSION_OPTIONS_MAX_COUNT = 10;
+export const DISCUSSION_OPTION_MAX_LENGTH = 200;
 /** Bounds for the generic graph projection protocol (external bounded contexts). */
 export const GRAPH_PROJECTION_MAX_ARTIFACTS_PER_BATCH = 500;
 export const GRAPH_PROJECTION_MAX_EDGES_PER_BATCH = 1_000;

package/src/db.ts

@@ -235,6 +235,9 @@ CREATE TABLE IF NOT EXISTS discussion_rounds (
 	content       TEXT NOT NULL,
 	occurred_at   TEXT NOT NULL,
 	event_schema_version INTEGER NOT NULL DEFAULT 1,
+	options       TEXT,
+	options_mode  TEXT,
+	selected      TEXT,
 	UNIQUE (discussion_id, round_number)
 );
 CREATE INDEX IF NOT EXISTS discussion_rounds_discussion_idx ON discussion_rounds(discussion_id, round_number, id);
@@ -323,6 +326,7 @@ const CORE_LEDGER_VERSIONS: ReadonlyArray<{ version: number; name: string; check
 	{ version: 5, name: "session-identity", checksum: "1c6a165bbe37f82a100fd34762db70c3f8ab15ff20c3a53c2e60448edc815a5e" },
 	{ version: 6, name: "artifact-trash", checksum: "4a75dbec2892deb54bcc1afdf0d51d81f03a8d10861787d083784a29e5c7e8f9" },
 	{ version: 7, name: "discuss-native", checksum: "ab7bdd04824bd93681917807b817d6e08b9825af90161e3ccd6d6663021dc6a0" },
+	{ version: 8, name: "discuss-options", checksum: "ba1fc5ab7cfe9166d71cc1842f13bc32a0905d08696006cec202196a70c832e8" },
 ];
 
 export function migrationLedger(db: Db): ModuleMigrationRow[] {
@@ -470,6 +474,22 @@ const FUTURE_MIGRATIONS: ReadonlyArray<PapyrusMigration> = [
 			`);
 		},
 	},
+	{
+		version: 16,
+		name: "discuss-options",
+		// See domain/discussion.ts. Nullable, purely additive columns: a round with no posed choice
+		// (the overwhelming majority, before this feature existed) simply stores NULL in all three.
+		// Guarded per-column (SQLite has no `ADD COLUMN IF NOT EXISTS`): a fixture that bootstraps
+		// from the CURRENT SCHEMA text (which already declares these columns) and then only fakes an
+		// older user_version to exercise this migration path must not fail with "duplicate column
+		// name" -- the same class of already-bootstrapped-fixture concern version 9's comment covers.
+		up: (db) => {
+			const existing = new Set((db.prepare("PRAGMA table_info(discussion_rounds)").all() as Array<{ name: string }>).map((row) => row.name));
+			for (const column of ["options", "options_mode", "selected"]) {
+				if (!existing.has(column)) db.exec(`ALTER TABLE discussion_rounds ADD COLUMN ${column} TEXT`);
+			}
+		},
+	},
 ];
 
 /**

package/src/discussion-service.ts

@@ -11,8 +11,11 @@ import {
 	validateDeferReason,
 	validateDiscussionActor,
 	validateDiscussionContent,
+	validateDiscussionOptions,
+	validateSelectedOptions,
 	validateSettlement,
 	type DiscussionExtra,
+	type DiscussionOptionsMode,
 	type DiscussionRound,
 } from "./domain/discussion.ts";
 import type { Artifact } from "./domain/artifact.ts";
@@ -29,6 +32,19 @@ export interface OpenDiscussionInput {
 	body?: string;
 	labels?: string[];
 	blocksTaskIds?: string[];
+	/** Poses a choice on round 1 -- both or neither; see domain/discussion.ts's DiscussionOptionsMode. */
+	options?: string[];
+	optionsMode?: DiscussionOptionsMode;
+}
+
+export interface ReplyInput {
+	actor: string;
+	content: string;
+	/** Answers the Discussion's currently pending posed choice, if any; validated against it. */
+	selected?: string[];
+	/** Poses a new choice on this same round, replacing whatever was previously pending. */
+	options?: string[];
+	optionsMode?: DiscussionOptionsMode;
 }
 
 export interface DiscussionAndRounds {
@@ -52,9 +68,16 @@ export class Discussions {
 		return readDiscussionExtra(discussion.extra);
 	}
 
+	/** Validates a freshly-posed choice; undefined when neither field is given (nothing posed), since both/neither is the only valid shape. */
+	private validatePosedOptions(options: string[] | undefined, optionsMode: DiscussionOptionsMode | undefined): { options: string[]; mode: DiscussionOptionsMode } | undefined {
+		if (options === undefined && optionsMode === undefined) return undefined;
+		return validateDiscussionOptions(options ?? [], optionsMode ?? "");
+	}
+
 	open(input: OpenDiscussionInput, context?: ArtifactEventContext): DiscussionAndRounds {
 		const actor = validateDiscussionActor(input.actor);
 		const content = validateDiscussionContent(input.content);
+		const posed = this.validatePosedOptions(input.options, input.optionsMode);
 		return this.artifacts.atomic(() => {
 			const discussion = this.artifacts.create({
 				kind: "doc",
@@ -63,25 +86,46 @@ export class Discussions {
 				body: input.body ?? "",
 				status: "active",
 				labels: input.labels,
-				extra: { discussion: { state: "active", roundCount: 1 } },
+				extra: {
+					discussion: {
+						state: "active",
+						roundCount: 1,
+						...(posed ? { pendingOptions: posed.options, pendingOptionsMode: posed.mode } : {}),
+					},
+				},
 			}, context);
-			const round = this.rounds.append({ discussionId: discussion.id, roundNumber: 1, actor, content }, new Date().toISOString());
+			const round = this.rounds.append({
+				discussionId: discussion.id, roundNumber: 1, actor, content,
+				...(posed ? { options: posed.options, optionsMode: posed.mode } : {}),
+			}, new Date().toISOString());
 			for (const taskId of input.blocksTaskIds ?? []) this.block(discussion.id, taskId, context);
 			return { discussion: this.artifacts.get(discussion.id)!, rounds: [round] };
 		});
 	}
 
-	reply(discussionId: string, actor: string, content: string, context?: ArtifactEventContext): DiscussionAndRounds {
-		const validActor = validateDiscussionActor(actor);
-		const validContent = validateDiscussionContent(content);
+	reply(discussionId: string, input: ReplyInput, context?: ArtifactEventContext): DiscussionAndRounds {
+		const validActor = validateDiscussionActor(input.actor);
+		const validContent = validateDiscussionContent(input.content);
+		const posed = this.validatePosedOptions(input.options, input.optionsMode);
 		return this.artifacts.atomic(() => {
 			const discussion = requireDiscussion(this.artifacts.get(discussionId), discussionId);
 			const state = this.extra(discussion);
 			if (state.state !== "active") throw new DiscussionError(`discussion "${discussionId}" is ${state.state}; resume it before replying`);
 			if (state.roundCount >= DISCUSSION_MAX_ROUNDS) throw new DiscussionError(`discussion "${discussionId}" has reached its ${DISCUSSION_MAX_ROUNDS}-round limit; settle or defer it`);
+			const selected = input.selected !== undefined ? validateSelectedOptions(input.selected, state.pendingOptions, state.pendingOptionsMode) : undefined;
 			const nextRound = state.roundCount + 1;
-			const round = this.rounds.append({ discussionId, roundNumber: nextRound, actor: validActor, content: validContent }, new Date().toISOString());
-			const updated = this.artifacts.setExtra(discussionId, { ...discussion.extra, discussion: { ...state, roundCount: nextRound } }, context)!;
+			const round = this.rounds.append({
+				discussionId, roundNumber: nextRound, actor: validActor, content: validContent,
+				...(posed ? { options: posed.options, optionsMode: posed.mode } : {}),
+				...(selected ? { selected } : {}),
+			}, new Date().toISOString());
+			const { pendingOptions: _clearedOptions, pendingOptionsMode: _clearedMode, ...answered } = state;
+			const nextState = {
+				...(selected ? answered : state),
+				roundCount: nextRound,
+				...(posed ? { pendingOptions: posed.options, pendingOptionsMode: posed.mode } : {}),
+			};
+			const updated = this.artifacts.setExtra(discussionId, { ...discussion.extra, discussion: nextState }, context)!;
 			return { discussion: updated, rounds: [round] };
 		});
 	}

package/src/domain/discussion.ts

@@ -17,6 +17,9 @@
 import {
 	DISCUSSION_ACTOR_MAX_LENGTH,
 	DISCUSSION_DEFER_REASON_MAX_CHARACTERS,
+	DISCUSSION_OPTION_MAX_LENGTH,
+	DISCUSSION_OPTIONS_MAX_COUNT,
+	DISCUSSION_OPTIONS_MIN_COUNT,
 	DISCUSSION_ROUND_CONTENT_MAX_CHARACTERS,
 	DISCUSSION_SETTLEMENT_MAX_CHARACTERS,
 } from "../constants.ts";
@@ -26,16 +29,26 @@ export const DISCUSSION_SUBTYPE = "discussion";
 export const DISCUSSION_STATES = ["active", "deferred", "settled"] as const;
 export type DiscussionState = typeof DISCUSSION_STATES[number];
 
-/** Persisted in a discussion Doc's `extra.discussion`. */
+/**
+ * A round can pose a choice (options + optionsMode) the way opencode's QuestionV2 poses
+ * labeled multiple-choice options, or answer one (selected). "single" is mutually exclusive
+ * (exactly one pick); "multi" allows several -- see constants.ts.
+ */
+export const DISCUSSION_OPTIONS_MODES = ["single", "multi"] as const;
+export type DiscussionOptionsMode = typeof DISCUSSION_OPTIONS_MODES[number];
+
+/** Persisted in a discussion Doc's `extra.discussion`. pendingOptions/-Mode is the current-state cache of "is there an unanswered posed choice right now" -- cleared once answered, set again whenever a round poses a new one. */
 export interface DiscussionExtra {
 	state: DiscussionState;
 	roundCount: number;
 	deferredReason?: string;
 	settlement?: string;
 	settledAt?: string;
+	pendingOptions?: string[];
+	pendingOptionsMode?: DiscussionOptionsMode;
 }
 
-/** One append-only round of a Discussion -- opening statement is round 1. */
+/** One append-only round of a Discussion -- opening statement is round 1. options/optionsMode/selected are the historical record of what was posed/picked in this specific round (extra.discussion.pendingOptions is the separate, mutable "what's unanswered right now" cache). */
 export interface DiscussionRound {
 	id: number;
 	discussionId: string;
@@ -43,6 +56,9 @@ export interface DiscussionRound {
 	actor: string;
 	content: string;
 	occurredAt: string;
+	options?: string[];
+	optionsMode?: DiscussionOptionsMode;
+	selected?: string[];
 }
 
 export interface AppendDiscussionRound {
@@ -50,6 +66,9 @@ export interface AppendDiscussionRound {
 	roundNumber: number;
 	actor: string;
 	content: string;
+	options?: string[];
+	optionsMode?: DiscussionOptionsMode;
+	selected?: string[];
 }
 
 export interface DiscussionRoundQuery {
@@ -79,6 +98,32 @@ export function validateSettlement(settlement: string): string {
 	return boundedString(settlement, "settlement", DISCUSSION_SETTLEMENT_MAX_CHARACTERS);
 }
 
+/** Validates a freshly-posed choice: 2..DISCUSSION_OPTIONS_MAX_COUNT unique, bounded-length options and a real mode. */
+export function validateDiscussionOptions(options: string[], mode: string): { options: string[]; mode: DiscussionOptionsMode } {
+	if (!(DISCUSSION_OPTIONS_MODES as readonly string[]).includes(mode)) {
+		throw new Error(`options_mode must be one of ${DISCUSSION_OPTIONS_MODES.join(", ")}`);
+	}
+	if (options.length < DISCUSSION_OPTIONS_MIN_COUNT || options.length > DISCUSSION_OPTIONS_MAX_COUNT) {
+		throw new Error(`options must have between ${DISCUSSION_OPTIONS_MIN_COUNT} and ${DISCUSSION_OPTIONS_MAX_COUNT} entries`);
+	}
+	for (const option of options) boundedString(option, "option", DISCUSSION_OPTION_MAX_LENGTH);
+	if (new Set(options).size !== options.length) throw new Error("options must not repeat an entry");
+	return { options: [...options], mode: mode as DiscussionOptionsMode };
+}
+
+/** Validates an answer against the Discussion's currently pending posed choice, if any. */
+export function validateSelectedOptions(selected: string[], pendingOptions: string[] | undefined, pendingMode: DiscussionOptionsMode | undefined): string[] {
+	if (!pendingOptions || pendingOptions.length === 0 || !pendingMode) {
+		throw new Error("this Discussion has no pending options to select from");
+	}
+	if (selected.length === 0) throw new Error("selected must not be empty");
+	if (new Set(selected).size !== selected.length) throw new Error("selected must not repeat an option");
+	const unknown = selected.filter((entry) => !pendingOptions.includes(entry));
+	if (unknown.length > 0) throw new Error(`selected option(s) not offered: ${unknown.join(", ")}`);
+	if (pendingMode === "single" && selected.length > 1) throw new Error('this Discussion\'s pending options are "single": pick exactly one');
+	return [...selected];
+}
+
 /** True for any artifact (already fetched) that is a Discussion, regardless of its current lifecycle state. */
 export function isDiscussionArtifact(artifact: { kind: string; subtype: string }): boolean {
 	return artifact.kind === "doc" && artifact.subtype === DISCUSSION_SUBTYPE;
@@ -97,11 +142,21 @@ export function readDiscussionExtra(extra: Record<string, unknown>): DiscussionE
 	if (typeof roundCount !== "number" || !Number.isInteger(roundCount) || roundCount < 0) {
 		throw new Error("invalid Discussion roundCount");
 	}
+	const pendingOptions = record["pendingOptions"];
+	if (pendingOptions !== undefined && (!Array.isArray(pendingOptions) || pendingOptions.some((entry) => typeof entry !== "string"))) {
+		throw new Error("invalid Discussion pendingOptions");
+	}
+	const pendingOptionsMode = record["pendingOptionsMode"];
+	if (pendingOptionsMode !== undefined && !(DISCUSSION_OPTIONS_MODES as readonly unknown[]).includes(pendingOptionsMode)) {
+		throw new Error("invalid Discussion pendingOptionsMode");
+	}
 	return {
 		state: state as DiscussionState,
 		roundCount,
 		...(typeof record["deferredReason"] === "string" ? { deferredReason: record["deferredReason"] } : {}),
 		...(typeof record["settlement"] === "string" ? { settlement: record["settlement"] } : {}),
 		...(typeof record["settledAt"] === "string" ? { settledAt: record["settledAt"] } : {}),
+		...(pendingOptions !== undefined ? { pendingOptions: pendingOptions as string[] } : {}),
+		...(pendingOptionsMode !== undefined ? { pendingOptionsMode: pendingOptionsMode as DiscussionOptionsMode } : {}),
 	};
 }

package/src/modules/discuss.ts

@@ -49,6 +49,13 @@ function taskId(input: OperationInput): string {
 	return value;
 }
 
+function optionsMode(input: OperationInput): "single" | "multi" | undefined {
+	const value = optionalString(input, "options_mode") ?? optionalString(input, "optionsMode");
+	if (value === undefined) return undefined;
+	if (value !== "single" && value !== "multi") throw new Error('options_mode must be "single" or "multi"');
+	return value;
+}
+
 /** This module's own operation names, the single source of truth src/service.ts's EXPECTED_OPERATION_NAMES spreads in rather than re-listing by hand. */
 export const DISCUSS_OPERATION_NAMES = [
 	"discuss.open", "discuss.reply", "discuss.defer", "discuss.resume", "discuss.settle",
@@ -68,8 +75,16 @@ export function discussOperations(discussions: Discussions): OperationDefinition
 			body: optionalString(input, "body"),
 			labels: optionalStringArray(input, "labels"),
 			blocksTaskIds: optionalStringArray(input, "blocks_task_ids") ?? optionalStringArray(input, "blocksTaskIds"),
+			options: optionalStringArray(input, "options"),
+			optionsMode: optionsMode(input),
+		}, eventContext(input))),
+		define("discuss.reply", (input: OperationInput) => discussions.reply(string(input, "id"), {
+			actor: string(input, "actor"),
+			content: string(input, "content"),
+			selected: optionalStringArray(input, "selected"),
+			options: optionalStringArray(input, "options"),
+			optionsMode: optionsMode(input),
 		}, eventContext(input))),
-		define("discuss.reply", (input: OperationInput) => discussions.reply(string(input, "id"), string(input, "actor"), string(input, "content"), eventContext(input))),
 		define("discuss.defer", (input: OperationInput) => discussions.defer(string(input, "id"), optionalString(input, "reason"), eventContext(input))),
 		define("discuss.resume", (input: OperationInput) => discussions.resume(string(input, "id"), eventContext(input))),
 		define("discuss.settle", (input: OperationInput) => discussions.settle(string(input, "id"), string(input, "settlement"), eventContext(input))),