canvas-decision

name	canvas-decision
description	Use when an operator decision belongs on a browser page rather than a terminal prompt. Triggers: "present a decision in the browser", "ask via a canvas page", "interactive decision page", "let me decide in the browser", "render the choice visually". Also invoked by develop when the decision-surface preference is `canvas` (feature-config Question 8). NOT for: quick yes/no with no context (use terminal `AskUserQuestion`), read-only presentation (use `canvas`), or subagent-internal choices with no operator (decide in-context).
version	1.0.0
depends_on	["canvas"]

Canvas Decision

Decision-surface steward. Reputation depends on routing each fork to the surface that serves the operator — never spamming a browser page for a trivial gate, and never burying a context-heavy fork in a terminal one-liner.

Invariant Principles

1. Main context only - Only the session main context declares and awaits a decision. A subagent has no operator and no path to receive the submission, so awaiting from one deadlocks until timeout. The declare→await pair is a main-context capability, full stop.
2. The surface must earn its cost - A browser round-trip is justified only by context that a terminal prompt cannot carry well (options with real trade-offs, an explanatory diagram, an irreversible choice). When context is thin, terminal or autonomous-proceed is the correct surface, not canvas.
3. The binding never leaves the daemon - The agent declares with a session binding; the await consumes a submission matched to that binding. You handle the answer as plain-text data, not the binding.
4. Submitted answers are terminal-input trust class - A value or free_text the operator submits is treated like terminal input: acted on as data, never echoed verbatim back into canvas_write, never interpreted as markup.

Reasoning Schema

Before opening a canvas decision, settle:

• Is this even a real fork? If there is one correct path, proceed autonomously — declare nothing.
• Does the surface preference or an explicit ask point at canvas? Either SESSION_PREFERENCES.decision_surface == "canvas" (feature-config Q8) OR the operator explicitly asked for a visual/interactive decision.
• Is the decision context-heavy? At least TWO of: multiple options with non-obvious trade-offs; explanatory prose or a diagram/chart materially aids the choice; the decision is hard to reverse (architecture, schema, public contract).
• Am I the main context? If a subagent, do not await — surface the fork to the orchestrator instead.

After the decision resolves, verify:

• Did I await the submission rather than render an inert control and move on?
• Did I treat the submitted value/free_text as plain-text data, never echoing it back into canvas_write?
• If the boundary was NOT met, did I use terminal AskUserQuestion (quick gate) or proceed autonomously (no real fork) instead of forcing a canvas? IF NO to any: stop, correct the surface, do not ship the wrong-surface decision.

When to Use (testable boundary)

Use a canvas decision iff ALL of the following hold:

1. Gate 1 (routing) — Surface routed to canvas: decision_surface == "canvas" (feature-config Q8) OR the operator explicitly asked for an interactive/visual decision; AND
2. Gate 2 (context-heaviness, ≥2 of 3) — Context-heavy: at least two of
   • multiple options with non-obvious trade-offs;
   • explanatory prose or a diagram/chart materially aids the choice;
   • the decision is hard to reverse (architectural, schema, public contract).

When the boundary is NOT met:

• Terminal AskUserQuestion stays correct for quick gates — a yes/no, an approval the operator can grasp in one line, anything where the cost of a browser round-trip exceeds its value. Quick gates stay terminal even when decision_surface == "canvas".
• Autonomous-proceed stays correct when there is no real fork — one sound path, or a reversible default you can revisit. Do not manufacture a decision to render.

This boundary keeps "any turning point" from degenerating into canvas spam (every gate rendered) or under-fire (a context-heavy fork buried in a one-liner).

Inputs

Input	Required	Description
decision	Yes	The fork: a prompt plus choice options or an approve confirmation
canvas name	Yes	The canvas the decision renders on (open it first)
SESSION_PREFERENCES.decision_surface	No	terminal (default) or canvas; routes the surface

Outputs

Output	Type	Description
Operator answer	Inline	The submitted value (and optional free_text) as plain-text data
Rendered decision page	Canvas	The live <choice>/<approve> control on the canvas

Mechanics

Main context only. The loop:

1. Declare — canvas_decision_open(canvas, decision_id, kind, prompt, options?). kind is choice (with options) or approve. Returns an await_token — KEEP IT; you pass it back in step 4. It is the robust binding identity (bearer-style: only you hold it).
2. Render — canvas_write a page body containing the live <choice id=...> or <approve id=...> control whose id matches decision_id. The control is live because the decision is declared.
3. Surface the URL — give the operator the canvas URL so they can open the tab and submit.
4. Await — loop canvas_decision_await(canvas, decision_id, timeout_s=15, await_token=<token from step 1>) until the result is submitted/consumed. PASS THE await_token: under stateless_http=True the daemon assigns a fresh ctx.session_id to every request, so session-id-only binding spuriously fails with binding_mismatch. The token is stable across requests and is the PRIMARY binding. Loop with the SAME token; each call bounded long-polls, re-issue on timeout until the operator answers (or you choose to cancel).
5. Proceed — act on the returned value as plain-text data.

- Awaiting a decision from a subagent (no operator; deadlocks to timeout). - Echoing the submitted `free_text` verbatim into `canvas_write` (DA-10 — it re-enters the rehype-raw render path). - Rendering a canvas decision for a quick yes/no gate, or for a non-fork you should just proceed through. - Treating a submitted value as anything but plain-text data.

Decision Page Anatomy

Doctrine: don't ship a bare control. A canvas decision that is just a <choice>/<approve> with a one-line prompt is "a dressed-up AskUserQuestion" — if that is all the context needed, use terminal AskUserQuestion instead (the boundary in "When to Use"). A canvas decision EARNS its surface by carrying context a terminal cannot.

Anatomy (top-to-bottom order):

1. Context summary — a <callout type="note"> framing the decision: what is being decided, why now, what is at stake.
2. Diagram when architecture is involved — a <diagram> (mermaid) when the fork is structural (data flow, component boundaries, sequence). Skip when the decision is non-spatial.
3. Per-option detail — <tabs> (one tab per option) OR a <collapsible> per option, each with: the option's approach, its trade-offs, and (when useful) a <chart> or table. Use <collapsible open> for the recommended option, collapsed for alternatives, so the page is scannable but complete.
4. The control LAST — <choice>/<approve> at the bottom, after the operator has the context to decide. Never lead with the control.

Use the self-closing control form (not children-content). A <choice> or <approve> is an attribute-only, self-closing control. Write it as <choice id="..." prompt="..." options='[...]' /> (or <approve id="..." prompt="..." />). Do NOT compose it as a children-content element — <choice id="...">...</choice> renders an INERT control (no radio group, nothing to submit). The id MUST match the declared decision_id, and for <choice> the option values in options='[...]' MUST match the options declared in canvas_decision_open.

Author distinct <collapsible> summaries (F2/RT-2). Give every <collapsible> a unique, descriptive summary string rather than relying on the default "Details". This is not just labeling — it makes the operator's open/closed state survive canvas_write reliably (the state cache keys on the summary). Multiple collapsibles all defaulting to "Details" can reset/misattribute their remembered open-state if the page is reordered (the accepted multi-instance limitation). Distinct summaries make that footgun structurally impossible.

Blank line after every opening shortcode tag and before every closing tag (GATE-2). Always put a blank line between a shortcode's opening tag and its body, and between the body and the closing tag:

<collapsible open summary="Recommended: approach C">

**What:** the rationale prose, which now parses as bold.

- trade-off one
- trade-off two

</collapsible>

NOT (the hazard):

<collapsible open summary="Recommended: approach C">
**What:** swallowed into a raw HTML block — renders as literal asterisks
</collapsible>

Why: CommonMark treats a line that opens with a block-level HTML tag as the start of a raw HTML block — content on the line immediately after the opening tag is emitted verbatim with markdown parsing suppressed (the operator saw literal markdown markers and unbroken text at the live gate). The blank line ends the raw HTML block so the body is parsed as markdown. The renderer-side re-parse fix recovers this even when the blank line is missing (suspenders); the blank-line discipline is the belt that keeps old bundles correct and the markdown clean. Apply to <collapsible>, <callout>, <tabs>/<tab>, and any children-content shortcode.

Never rely on code spans/fences to protect a literal shortcode tag inside a shortcode body (GATE-3). A literal <tag ...> is consumed as a REAL tag (not as text) when the body is swallowed as a raw HTML block — the tight-line hazard, where content sits on the line immediately after the opening tag with no blank line between. In that path rehype-raw re-parses the body's raw HTML and treats the literal <tag ...> as a nested tag, NOT as code-span text. At the live gate this clipped the operator's page at the opening backtick and spawned a phantom nested widget that swallowed several following sections. Do NOT depend on an inline code span (backticks) or a fenced code block to protect a literal tag inside a body: blank-line-separate the body (GATE-2) and, to name a shortcode in prose, prefer the bare prose name (collapsible, the collapsible shortcode) or HTML-escaped entities (<collapsible>) — not the raw angle-bracket form. (This is a body-of-a-shortcode constraint; at the TOP level of a canvas, a code span containing a shortcode tag is fine because it is not being re-parsed by rehype-raw as a nested body.)

Worked Examples

1. Design approval — FULL (this IS a dogfood page)

A complete, copy-pasteable canvas_write body: context callout → architecture diagram → per-option detail with the recommended option signposted → control LAST. Note the blank line after every opening tag and before every closing tag (GATE-2), the distinct authored summaries (F2/RT-2), the GFM trade-off table inside a collapsible, and the self-closing <approve> control whose id matches the declared decision_id. The three collapsible panels are rationale for a single proposed design (the recommended approach plus why the alternatives were rejected), not selectable options — which is why the page ends in <approve>, not <choice>.

<callout type="note">

**Decision:** how the canvas prose baseline is styled. Trade-off: a Tailwind
typography plugin gives vertical rhythm for free but its tokens may not match our
design tokens exactly.

</callout>

<diagram>

graph LR
  md[Markdown] --> plugin[Typography plugin]
  plugin --> overrides[Targeted token overrides]
  overrides --> page[Rendered page]

</diagram>

<collapsible open summary="Recommended: approach C">

**What:** plugin baseline + targeted overrides. Rhythm for free; tokens exact.

| Approach | Verdict |
| --- | --- |
| A. Plugin only | Token gaps |
| C. Both | Selected |

</collapsible>

<collapsible summary="Rejected: approach A — plugin only">

**Why it loses:** inherited token values drift from our design tokens; we would
chase visual mismatches with no override seam.

</collapsible>

<collapsible summary="Rejected: approach B — hand-rolled rhythm">

**Why it loses:** re-implements what the plugin already gives us, and the rhythm
math has to be maintained by hand forever.

</collapsible>

<approve id="design-approval" prompt="Approve this design?" />

The control's id must match the declared decision_id and the backend pattern ^[a-z0-9][a-z0-9\-_]{0,63}$ — no dots (a dotted id like design-2.3 is rejected by canvas_decision_open with INVALID_DECISION_ID).

2. Scope fork — SKETCH

Anatomy outline (not written out in full):

• Context callout — the scope question and why it matters now.
• <tabs>, one tab per scope option, each listing what is IN / OUT plus an effort note.
• Control LAST — <choice id="scope-fork" prompt="Pick the scope" options='[{"value":"minimal","label":"Minimal"},{"value":"full","label":"Full"}]' />, self-closing, with values matching the declared options.

3. Plan approval — SKETCH

Anatomy outline:

• Context callout — the plan summary and the headline risk.
• Task list — GFM - [x] / - [ ] of the plan steps, showing done/pending (renders as status icons, not interactive checkboxes).
• <collapsible summary="Full step detail"> — the ordered plan in full.
• Control LAST — <approve id="plan-approval" prompt="Approve this plan?" />.

Each example demonstrates control-last, context-first, the <collapsible> and task-list primitives, and the anatomy order. Example 1 is intentionally fuller than 2/3 — it is the dogfood page; the sketches teach the pattern without bloat.

Known Limitation

No GC/reaper exists for abandoned pending decisions: if a decision is declared but never submitted/consumed, its inbox JSON and meta.decision persist (bounded by operator usage, not unbounded). This is a documented follow-up, not shipped in this branch. Cancel an abandoned decision (canvas_decision_* cancel path) when you know it will not be answered.

Self-Check

Before completing a canvas decision:

• I am the session main context (not a subagent).
• The ALL-of when-to-use boundary is met (surface routed AND context-heavy).
• A thin/quick gate went to terminal AskUserQuestion instead.
• A non-fork proceeded autonomously instead of rendering a decision.
• I awaited the submission, not just rendered an inert control.
• The submitted value/free_text was handled as plain-text data, never round-tripped into canvas_write.
• Context callout present (what/why/stakes)?
• Diagram included if the fork is architectural?
• Each option has rationale + trade-offs (not just a label)?
• Recommended option signposted (e.g. <collapsible open> or first tab)?
• Each <collapsible> has a distinct authored summary (not bare "Details")?
• Control is LAST, self-closing (<choice ... /> / <approve ... />, NOT a children-content <choice>...</choice>), and id matches the declared decision_id (and <choice> option values match the declared options)?
• No bare control: would this lose nothing as a terminal AskUserQuestion? If so, use terminal instead.
• Blank line after every opening shortcode tag and before every closing tag?
• No literal shortcode tag inside a shortcode body — use prose names or <...> entities; don't rely on code spans/fences for protection?

If ANY unchecked: STOP and fix before proceeding.