one-code-extension 0.1.4 → 0.3.0

package/docs/guide/tools.md

@@ -0,0 +1,175 @@
+# Tools
+
+The model works by calling tools. You do not type tool names; you describe
+the task and the model chooses. This page lists every tool One Code gives
+the model, what each does, what you see when it runs, and how Claude Code's
+tool names map onto them.
+
+Every tool call passes through the permission gate. See
+[Permissions, modes, and auto mode](permissions-modes-and-auto-mode.md).
+
+## Eager and deferred tools
+
+Tools come in two kinds:
+
+- **Eager tools** are in every request. These are the tools the model uses
+  constantly: `read`, `write`, `edit`, `bash`, `Agent`, `skill`,
+  `ask_user_question`, `workflow`, and `tool_search`.
+- **Deferred tools** are listed by name only. When the model needs one, it
+  calls `tool_search` to load the full definition, and the tool stays
+  available for the rest of the session. This keeps the prompt small and
+  works the same way on every model tier and provider.
+
+Run `/tools-deferred` to see which deferred tools are loaded and which are
+still waiting. The list is fixed once the first request has gone out, so a
+tool that appears later (an MCP server that connects slowly, for example)
+is announced to the model separately.
+
+## Files and code
+
+| Tool | What it does |
+|---|---|
+| `read` | Reads a file. Shown as `● Read(path)` in the transcript. |
+| `write` | Creates or overwrites a file. The model must have read an existing file in this conversation before writing it. |
+| `edit` | Replaces an exact string in a file. Shown as `● Update(path)`. The same read-before-write rule applies, and the edit is refused if the file changed on disk since the model last read it. |
+| `notebook_edit` | Edits a Jupyter notebook cell: replace, insert, append, or delete. Editing a code cell clears its outputs. Deferred. |
+| `grep`, `find`, `ls` | pi's search tools. Active only for the smallest model tier; on other tiers, searching goes through `bash`, as in Claude Code. |
+
+The read-before-write and stale-edit guards track file **content**, not tool
+calls, so a file the model changed through a shell command is tracked too.
+When a file changes outside the model's view (you edited it, a formatter
+ran, a `git checkout` happened) the model is told, with the changed lines,
+and must re-read the file before editing it. A file that disappears is
+reported as deleted or moved.
+
+## Shell
+
+`bash` runs a shell command. Its `run_in_background` option starts the
+command detached and returns a task id; output spools to a log file under
+the session directory, and completion is reported to the model as a
+notification. A background shell shows up in the shells section of the
+panel below the editor. See
+[Tasks and background work](tasks-and-background-work.md).
+
+Some command shapes are refused before they run, with a message that steers
+the model to a better route:
+
+- A foreground command that starts with `sleep`, or a polling loop that
+  sleeps, when the wait is not provably short. The model is told to use
+  `run_in_background` or `monitor` instead.
+- A command that would orphan a process (`nohup`, `setsid`, or a trailing
+  `&` with no `wait`).
+- An interactive program that would stop responding without a terminal:
+  `vim`, `git rebase -i`, `git add -p`, `watch`, and similar.
+- Inside a worktree session, a git command aimed at a different checkout.
+
+## Web
+
+| Tool | What it does |
+|---|---|
+| `web_search` | Searches the web. Uses your provider's own search when it has one (Anthropic, OpenAI, Gemini, xAI); otherwise falls back to Brave, then Tavily, then Exa's free keyless endpoint. Results from the keyless endpoint are labelled, and the first use in a session shows a warning. See [Web search](providers-and-models.md#web-search-on-providers-without-a-search-api). Deferred. |
+| `web_fetch` | Fetches a URL and converts it to readable Markdown. Follows same-host redirects; reports cross-host redirects instead of following them. Responses are cached for 15 minutes. With a `prompt`, a small reader model on your provider answers the question against the page, so the page itself stays out of your context; if the reader fails, the raw page is returned with a note. Deferred. |
+| `url_context` | Gemini's page-context tool, available only when a Gemini model is in use. Deferred. |
+
+## Delegation
+
+| Tool | What it does |
+|---|---|
+| `Agent` | Starts a subagent with its own context window. Runs in the background and returns a task id; the result arrives as a notification. Supports forking the current conversation and isolating the agent in a git worktree. |
+| `SendMessage` | Sends a message to an agent that was started earlier: a running one receives it live, a finished one is resumed from its saved session. Deferred. |
+| `list_agents` | Lists the agents started in this session and their status. Deferred. |
+| `workflow` | Runs a JavaScript script that coordinates many agents. This is the `ultracode` mechanism. |
+
+See [Subagents and workflows](subagents-and-workflows.md).
+
+## Planning and asking
+
+| Tool | What it does |
+|---|---|
+| `enter_plan_mode`, `exit_plan_mode` | Switch into plan mode and ask you to approve the plan file. Deferred. See [Plan mode](permissions-modes-and-auto-mode.md#plan-mode). |
+| `ask_user_question` | Asks you up to four structured questions in a tabbed dialog. See [The terminal interface](terminal-interface.md#the-question-dialog). |
+| `skill` | Runs a skill by name. See [Skills](skills-plugins-and-mcp.md#skills). |
+
+## Tasks and background work
+
+| Tool | What it does |
+|---|---|
+| `task_create`, `task_get`, `task_list`, `task_update` | Maintain the structured task list shown in the pinned widget. Deferred. |
+| `monitor` | Watches a long-running command or a WebSocket and reports each output line as an event. Deferred. |
+| `task_output`, `task_stop` | Read the output of a background task or stop it. Deferred. |
+| `schedule_wakeup` | Schedules a prompt for later; the mechanism behind self-paced `/loop`. Deferred. |
+
+See [Tasks and background work](tasks-and-background-work.md).
+
+## Worktrees
+
+`enter_worktree` creates a git worktree under `.claude/worktrees/`, branched
+from the current `HEAD`, and moves the session into it: every shell command
+and relative path then resolves there, and your main working tree is
+untouched. `exit_worktree` leaves it, either keeping the worktree or
+removing it; removal is refused while the worktree has uncommitted or
+unmerged work unless the model passes `discard_changes`. The worktrees
+directory ignores itself in git. Both tools are deferred.
+
+## Diagnostics
+
+`lsp_diagnostics` asks a language server for the diagnostics of one file.
+Separately, after every round of edits, new diagnostics from every running
+server are attached to the last tool result as a `<new-diagnostics>` block,
+including diagnostics in other files that the edit broke. See
+[Language-server diagnostics](configuration.md#language-server-diagnostics).
+Deferred.
+
+## MCP
+
+Every tool an MCP server provides appears as `mcp__<server>__<tool>`,
+deferred until needed. `list_mcp_resources`, `read_mcp_resource`, and
+`read_mcp_resource_dir` read the resources servers expose. See
+[MCP servers](skills-plugins-and-mcp.md#mcp-servers).
+
+## Tool discovery
+
+`tool_search` loads deferred tools. The model passes exact names
+(`select:monitor,task_output`), a required term (`+notebook`), or free
+keywords. If the model calls a tool it has not loaded yet, the call fails
+and the model is steered to `tool_search`.
+
+## Behavior in non-interactive runs
+
+In `-p` and `--mode json` runs the process exits when the turn settles, so
+nothing can run in the background. Tools that would detach work run to
+completion instead and return the output in their result: `bash` with
+`run_in_background`, `Agent`, `monitor`, and `workflow`. Timers such as
+`schedule_wakeup` and `/loop` never fire in these modes.
+
+## Claude Code tool names
+
+Claude Code's tool names are accepted in permission rules and hook
+matchers, and mapped to One Code's names. Case is ignored.
+
+| Claude Code | One Code |
+|---|---|
+| `Bash` | `bash` |
+| `Read`, `Write`, `Edit` | `read`, `write`, `edit` |
+| `Grep`, `Glob`, `LS` | `grep`, `find`, `ls` |
+| `NotebookEdit` | `notebook_edit` |
+| `WebFetch`, `WebSearch` | `web_fetch`, `web_search` |
+| `Task`, `Agent` | `Agent` |
+| `SendMessage` | `SendMessage` |
+| `ListAgents` | `list_agents` |
+| `Skill` | `skill` |
+| `ToolSearch` | `tool_search` |
+| `AskUserQuestion` | `ask_user_question` |
+| `Workflow` | `workflow` |
+| `TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate` | `task_create`, `task_get`, `task_list`, `task_update` |
+| `TodoWrite` | `task_create` |
+| `TaskOutput`, `TaskStop` | `task_output`, `task_stop` |
+| `Monitor` | `monitor` |
+| `ScheduleWakeup` | `schedule_wakeup` |
+| `EnterWorktree`, `ExitWorktree` | `enter_worktree`, `exit_worktree` |
+| `LSP` | `lsp_diagnostics` |
+| `ListMcpResourcesTool`, `ReadMcpResourceTool`, `ReadMcpResourceDirTool` | `list_mcp_resources`, `read_mcp_resource`, `read_mcp_resource_dir` |
+| `mcp__<server>__<tool>` | Unchanged |
+
+Claude Code tools that have no One Code equivalent are listed in
+[Differences from Claude Code](differences-from-claude-code.md#tools-that-are-not-provided).

package/docs/guide/troubleshooting.md

@@ -0,0 +1,175 @@
+# Troubleshooting
+
+Symptoms you might hit, what causes them, and what to do.
+
+## Start with the doctor
+
+Most setup problems show up in the report:
+
+```bash
+onecode doctor
+```
+
+Inside a session, `/doctor report` shows the same report and `/doctor` has
+the model fix what it finds. See [Check your setup with doctor](doctor.md).
+
+## Installation and startup
+
+**`onecode requires Node >= 22.19`.** The bundled app refuses to start on
+older Node, because pi crashes at import time there. Install Node 22.19 or
+later, or use the Homebrew formula, which installs Node for you.
+
+**`brew install` says no matching version was found.** Homebrew refuses
+npm packages published less than a day ago. Wait a day after a release, or
+install with `npm install -g @one-ai/one-code` in the meantime.
+
+**The banner shows `model none`.** No provider has credentials. Run
+`/login`, or set a provider key such as `ANTHROPIC_API_KEY` before
+launching. Two providers offer free models; see
+[Connect your first provider](providers-and-models.md#connect-your-first-provider).
+
+**A warning says the pi version is outside the tested range.** This appears
+on the extension installation when your pi is newer or older than the
+versions One Code was tested against. Most things keep working; if
+something breaks, pin pi to a tested version or use the bundled app, which
+pins pi itself.
+
+**`Failed to load extension` on startup.** The extension package and the
+pi it runs on are out of step. On the bundled app, reinstall it. On your own
+pi, run `pi update --extensions`.
+
+**The stock pi first-run wizard did not appear.** The bundled app seeds
+pi's settings with the One Code theme, quiet startup, and full-screen mode
+on first run, so there is nothing to ask.
+
+## Permissions
+
+**Auto mode is missing from the ctrl+q cycle.** Auto mode needs a model to
+run its classifier. Connect a provider.
+
+**ctrl+q does something else.** On Windows and WSL, pi's default
+keybindings also bind ctrl+q, to queue a follow-up message. Rebind one of
+them in pi's keybindings file.
+
+**Everything prompts, even in auto mode.** Auto mode pauses after several
+blocked actions in a row and prompts you once; approving resumes it. Also
+check `/permissions`: an `ask` rule prompts in every mode.
+
+**An allow rule I wrote has no effect in auto mode.** Broad execution rules
+(`Bash(*)`, wildcarded interpreters, delegation rules) are suspended in
+auto mode so they cannot bypass the classifier. Session grants from the
+approval prompt are also ignored there. Narrow the rule or switch to
+accept-edits or manual mode.
+
+**A project's `defaultMode: "auto"` is ignored.** Project-scope settings
+may not select auto or bypass mode. Set it in `~/.claude/settings.json`
+or pass `--permission-mode auto`.
+
+**`defaultMode` in `~/.onecode/settings.json` does nothing.** The
+permission loader does not read that key from One Code's file. Use a Claude
+Code settings file or the flag.
+
+**The model is denied a write to `.claude/settings.json`.** The auto-mode
+safety floor never lets the model change the gate's own configuration
+unattended. Approve the prompt, or make the edit yourself.
+
+**Every action is denied in a `-p` run.** Nothing can prompt in a
+non-interactive run, so anything that would have prompted is denied. Add
+allow rules, or use auto mode with a provider that can run the classifier.
+
+## Auto-mode classifier
+
+**Actions are blocked with a message about the classifier being
+unavailable.** The classifier model could not be reached or returned
+nothing usable; the gate fails closed. Check `/auto-mode config` for the
+model in use, and `/doctor report` for provider credentials. Set
+`CC_AUTO_MODE_DEBUG=1` to see each verdict on stderr.
+
+**The classifier approves or blocks something it should not.** Choose a
+stronger classifier with `/auto-mode model <provider/model-id>`. A
+Haiku-class classifier is a measurably weaker boundary than a Sonnet-class
+one.
+
+## Models and providers
+
+**The subagent model is stale after switching providers.** A saved
+`/subagent` choice from another provider no longer applies. Run
+`/subagent status`, then `/subagent clear` or pick a model on the current
+provider.
+
+**Cache-hit in the footer is low.** Changing the model or the effort level
+re-caches the conversation once. A `-p` run and every subagent use the
+provider's short cache lifetime. A persistent low rate on an interactive
+session is worth reporting.
+
+**A side call failed on a Gemini or OpenAI model with a message about
+reasoning or temperature.** Some models reject an option others accept.
+One Code avoids these options in its side calls; if you still see this,
+choose a different classifier or reader model and report the model.
+
+## Web search
+
+**A warning about Exa's free keyless endpoint.** Your provider has no
+search of its own and you set no Brave or Tavily key, so search fell back
+to a rate-limited endpoint. Set `BRAVE_SEARCH_API_KEY` or
+`TAVILY_API_KEY`, or add the key to `~/.onecode/settings.json`. See
+[Web search](providers-and-models.md#web-search-on-providers-without-a-search-api).
+
+## Language servers
+
+**No diagnostics appear after edits.** The language server must be on the
+`PATH` One Code was launched with. Run `/lsp` for each server's status and
+`/doctor report` for install hints.
+
+**TypeScript diagnostics fail with a message about `lib/tsserver.js`.**
+TypeScript 7's native compiler does not ship that file, and
+`typescript-language-server` needs it. Install a TypeScript 5.x development
+dependency in the project.
+
+## MCP servers
+
+**A server from `.mcp.json` is disabled.** Project servers run only after
+you approve them. Open `/mcp`, select the server, and choose Enable.
+
+**A server asks for approval again.** Its command or URL changed since you
+approved it. Approvals are tied to the configuration.
+
+**A server needs sign-in.** Open `/mcp`, select the server, and choose
+Authenticate. Tokens are stored under `~/.onecode/mcp-auth/`.
+
+## Hooks
+
+**A project's hooks do not run.** They need one-time approval at startup.
+Restart the session and accept, or check
+`~/.onecode/hooks/project-approvals.json`.
+
+**A hook blocks a call with no message.** A `PreToolUse` or
+`UserPromptSubmit` hook that times out blocks by design. Set
+`CC_HOOKS_DEBUG=1` to see each dispatch and outcome.
+
+## Sessions
+
+**My background shells are gone after `/clear`.** Background work ends
+with the session. The new session lists what was stopped.
+
+**A resumed session is in a different permission mode.** Modes are not
+saved with the session. Pass `--permission-mode` or set a default.
+
+**The `/effort` level reset after a restart.** `/effort` does not save the
+level. Open pi's `/thinking` picker and press **ctrl+s** to save a startup
+default, or pass `--thinking <level>` at launch.
+
+## Interface
+
+**PgUp and PgDn do nothing in a panel.** In full-screen mode pi uses them
+for its scrollback. Use the keys the panel's footer names (**Space** and
+**b** page in the doctor report, for example).
+
+**I want pi's own banner, footer, or spinner back.** Set `CC_NO_BANNER=1`,
+`CC_FOOTER=0`, or the other toggles listed in
+[Environment variables](reference.md#environment-variables).
+
+## Getting help
+
+Report problems at the project's GitHub repository. Include the output of
+`onecode doctor`, your platform, and the model and provider in use.

package/extensions/ask-user/index.ts

@@ -1,64 +1,25 @@
 /**
  * ask-user extension — Claude Code's AskUserQuestion.
  *
- * Asks the user up to four multiple-choice questions, each optionally
- * multi-select, always with a free-text escape hatch. Questions are presented
- * one dialog at a time (pi's UI has no native multi-question widget), and the
- * collected answers come back as one tool result.
+ * Asks the user up to four multiple-choice questions in one tabbed dialog
+ * (widget.ts): a tab per question plus Submit, option previews rendered
+ * beside the list, per-question notes, multi-select checkboxes, an inline
+ * free-text row, and "Chat about this" to decline and discuss in chat
+ * instead. The collected answers come back as one tool result.
  *
  * Replaces the community `pi-ask-user`, which asked one question per call and
  * pulled in a second, conflicting TypeBox.
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { ccToolRenderers } from "../lib/tui-render.ts";
-import {
-	type Answer,
-	buildChoices,
-	DONE_LABEL,
-	formatAnswers,
-	OTHER_LABEL,
-	type Question,
-	resolveSelection,
-	stripMark,
-} from "./questions.ts";
+import { ccToolRenderers, safeThemeBold, safeThemeInverse, safeThemePaint } from "../lib/tui-render.ts";
+import { type Answer, formatAnswers, formatDecline, type Question } from "./questions.ts";
+import { applyWidgetKey, createWidgetState, decodeWidgetKey, renderWidget, type WidgetResult } from "./widget.ts";
 
 const NON_INTERACTIVE =
 	"This session has no interactive UI, so the user cannot be shown a dialog. Ask your question in your reply instead and stop, or proceed under a stated assumption.";
 
-async function askOne(question: Question, ctx: ExtensionContext): Promise<Answer | undefined> {
-	const selected: string[] = [];
-	const title = `${question.header}\n\n${question.question}`;
-
-	// Multi-select loops until the user is done; single-select runs once.
-	for (let round = 0; round < question.options.length + 1; round++) {
-		const choice = await ctx.ui.select(title, buildChoices(question, selected));
-		if (choice === undefined) return undefined; // cancelled
-
-		if (choice === DONE_LABEL) break;
-
-		if (choice === OTHER_LABEL) {
-			const typed = await ctx.ui.input(question.question, "Type your answer");
-			if (typed === undefined) return undefined;
-			return { question: question.question, header: question.header, selected: [typed], freeform: true };
-		}
-
-		const label = resolveSelection(stripMark(choice), question.options);
-		if (!label) break;
-
-		if (!question.multiSelect) {
-			return { question: question.question, header: question.header, selected: [label], freeform: false };
-		}
-
-		const existing = selected.indexOf(label);
-		if (existing >= 0) selected.splice(existing, 1);
-		else selected.push(label);
-	}
-
-	return { question: question.question, header: question.header, selected, freeform: false };
-}
-
 export default function askUserExtension(pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "ask_user_question",
@@ -67,7 +28,7 @@ export default function askUserExtension(pi: ExtensionAPI) {
 			title: (a) => a?.questions?.[0]?.question,
 		}),
 		description:
-			"Ask the user to choose between options when you are blocked on a decision that is genuinely theirs — one you cannot resolve from the request, the code, or a sensible default. Ask up to four questions in one call; each gets a free-text 'Other' choice automatically. Do not use it for choices with an obvious default or for facts you can verify yourself.",
+			"Ask the user to choose between options when you are blocked on a decision that is genuinely theirs — one you cannot resolve from the request, the code, or a sensible default. Ask up to four questions in one call; the user answers them in one tabbed dialog and can decline into a chat discussion instead. Options on single-select questions may carry a `preview` — an ASCII mockup, diagram, or code snippet rendered beside the list while the user compares choices; use previews when seeing the alternatives helps (UI layouts, code style variants), never for plain preference questions. Non-preview questions get a free-text 'Other' row automatically, so never add an 'Other' option yourself. If you recommend a specific option, make it the first in the list and end its label with '(Recommended)'. To switch into plan mode use enter_plan_mode (not this tool); once in plan mode, use this tool only to clarify requirements or choose between approaches before finalizing the plan. Do not use this tool for choices with an obvious default or for facts you can verify yourself.",
 		promptSnippet: "Ask the user to decide between options when genuinely blocked",
 		parameters: Type.Object({
 			questions: Type.Array(
@@ -81,6 +42,12 @@ export default function askUserExtension(pi: ExtensionAPI) {
 						Type.Object({
 							label: Type.String({ description: "Short choice text" }),
 							description: Type.Optional(Type.String({ description: "What choosing this means" })),
+							preview: Type.Optional(
+								Type.String({
+									description:
+										"Preview shown beside the options while this option is focused: an ASCII mockup, diagram, or code snippet that helps the user compare choices. Single-select questions only.",
+								}),
+							),
 						}),
 						{ minItems: 2, maxItems: 4 },
 					),
@@ -93,31 +60,58 @@ export default function askUserExtension(pi: ExtensionAPI) {
 				return { content: [{ type: "text", text: NON_INTERACTIVE }], details: {}, isError: true };
 			}
 
-			const answers: Answer[] = [];
-			for (const question of params.questions as Question[]) {
-				const answer = await askOne(question, ctx);
-				if (!answer) {
-					// Cancelling one question cancels the batch: the remaining answers
-					// would be meaningless without it.
-					return {
-						content: [
-							{
-								type: "text",
-								text:
-									answers.length > 0
-										? `The user cancelled before finishing. Answers so far:\n\n${formatAnswers(answers)}`
-										: "The user cancelled without answering.",
-							},
-						],
-						details: { answers, cancelled: true },
-					};
-				}
-				answers.push(answer);
+			const questions = params.questions as Question[];
+			const outcome = await ctx.ui.custom<WidgetResult>((tui, theme, _keybindings, done) => {
+				const style = {
+					paint: safeThemePaint(theme),
+					bold: safeThemeBold(theme),
+					inverse: safeThemeInverse(theme),
+				};
+				const state = createWidgetState(questions);
+				// The output only changes on input or resize, but pi-tui calls
+				// render every frame — cache by width, drop the cache per keypress.
+				let cache: { width: number; lines: string[] } | undefined;
+				return {
+					render: (width: number) => {
+						if (cache?.width !== width) cache = { width, lines: renderWidget(state, style, width) };
+						return cache.lines;
+					},
+					handleInput: (data: string) => {
+						const key = decodeWidgetKey(data);
+						if (!key) return;
+						const resolved = applyWidgetKey(state, key);
+						if (resolved) return done(resolved);
+						cache = undefined;
+						tui.requestRender();
+					},
+					invalidate: () => {
+						cache = undefined;
+					},
+				};
+			});
+
+			if (!outcome || outcome.kind === "cancel") {
+				const partial = outcome?.kind === "cancel" ? outcome.answers : [];
+				const text =
+					partial.length > 0
+						? `The user cancelled without submitting. They had made these selections before cancelling (NOT submitted — do not treat them as final answers):\n\n${formatAnswers(partial)}`
+						: "The user cancelled without answering.";
+				return {
+					content: [{ type: "text", text }],
+					details: { answers: partial, cancelled: true },
+				};
+			}
+
+			if (outcome.kind === "chat") {
+				return {
+					content: [{ type: "text", text: formatDecline(questions) }],
+					details: { answers: [] as Answer[], declined: true },
+				};
 			}
 
 			return {
-				content: [{ type: "text", text: formatAnswers(answers) }],
-				details: { answers },
+				content: [{ type: "text", text: formatAnswers(outcome.answers) }],
+				details: { answers: outcome.answers },
 			};
 		},
 	});

package/extensions/ask-user/questions.ts

@@ -5,6 +5,8 @@
 export interface QuestionOption {
 	label: string;
 	description?: string;
+	/** Rendered beside the options while this option is focused (single-select only). */
+	preview?: string;
 }
 
 export interface Question {
@@ -20,33 +22,8 @@ export interface Answer {
 	selected: string[];
 	/** True when the user typed their own answer instead of picking. */
 	freeform: boolean;
-}
-
-export const OTHER_LABEL = "Other (type your own answer)";
-export const DONE_LABEL = "Done selecting";
-
-/** `label — description`, so the description is visible in a plain select list. */
-export function formatOptionLabel(option: QuestionOption): string {
-	return option.description ? `${option.label} — ${option.description}` : option.label;
-}
-
-/** Maps a chosen display string back to the option label it came from. */
-export function resolveSelection(display: string, options: QuestionOption[]): string | undefined {
-	return options.find((option) => formatOptionLabel(option) === display)?.label;
-}
-
-export function buildChoices(question: Question, alreadySelected: string[] = []): string[] {
-	const marked = question.options.map((option) => {
-		const label = formatOptionLabel(option);
-		return question.multiSelect && alreadySelected.includes(option.label) ? `✓ ${label}` : label;
-	});
-	const extras = question.multiSelect ? [DONE_LABEL, OTHER_LABEL] : [OTHER_LABEL];
-	return [...marked, ...extras];
-}
-
-/** Strips the multi-select tick so the choice can be matched against options. */
-export function stripMark(display: string): string {
-	return display.startsWith("✓ ") ? display.slice(2) : display;
+	/** Free-text notes the user attached to this answer. */
+	notes?: string;
 }
 
 export function formatAnswers(answers: Answer[]): string {
@@ -54,7 +31,17 @@ export function formatAnswers(answers: Answer[]): string {
 	return answers
 		.map((answer) => {
 			const value = answer.selected.length > 0 ? answer.selected.join(", ") : "(no answer)";
-			return `${answer.question}\n→ ${value}${answer.freeform ? " (typed by the user)" : ""}`;
+			const typed = answer.freeform ? " (typed by the user)" : "";
+			const notes = answer.notes ? `\n→ notes: ${answer.notes}` : "";
+			return `${answer.question}\n→ ${value}${typed}${notes}`;
 		})
 		.join("\n\n");
 }
+
+/** Tool result when the user picks "Chat about this" instead of answering. */
+export function formatDecline(questions: Question[]): string {
+	const list = questions
+		.map((q) => `· ${q.question} (${q.options.map((o) => o.label).join(" / ")})`)
+		.join("\n");
+	return `The user declined to answer and wants to chat about these questions instead:\n\n${list}\n\nAsk them in your reply what they'd like to clarify; don't call ask_user_question again until the discussion resolves it.`;
+}