Turn generated choices into saved human decisions

A chat thread is fine for discussion. It is a bad place to approve a shortlist, reject two options, add per-option notes, and hand the result back to an agent as durable state.

A chat thread is fine for discussion. It is a bad place to approve a shortlist, reject two options, add per-option notes, and hand the result back to an agent as durable state.

When an agent generates options, turn them into a small picker. Review it on a phone, tap the choices that should survive, dictate notes, submit, and make the agent continue from the saved JSON.

generated options
-> structured choice job
-> Svelte + mdsvex picker
-> token-gated mobile URL through a reviewed tunnel
-> click/dictate feedback
-> saved submission
-> agent resumes from persisted JSON

The Problem

Generated options are useful until they become a wall of text.

The agent offers five reasonable strategies for a checkout fix, billing webhook retry plan, auth/session tradeoff, QA screenshot triage, or design variation. You are away from the desk. The mobile chat thread now expects you to remember option names, type a careful answer, and trust the agent to turn that paragraph back into structured state.

That is where decisions get mushy.

The Move

Generated choices should become data, not another paragraph.

The agent should produce a choice job with stable option ids, titles, descriptions, risk notes, and proof hints. A small review UI renders those choices as cards. The human selects options, adds per-option feedback, adds overall feedback, and submits. The agent waits for the saved submission before continuing.

Use this when the next step needs a human decision:

  • choose among generated UI variations
  • pick a billing webhook idempotency strategy
  • choose an auth/session migration path
  • approve or reject model-council recommendations
  • triage screenshot or debug-packet follow-ups
  • select the first implementation plan after a broad exploration

The Smallest Useful Version

The picker does not need to be elaborate. It needs stable ids, checkboxes, per-option notes, one overall feedback box, draft saving, and a submit button that writes durable JSON.

Choice job:
- jobId:
- title:
- description:

Options:
- id:
  title:
  description:
  risk:
  suggested proof:
  expected evidence:

Human response:
- selected option ids:
- per-option feedback:
- overall feedback:

Resume rule:
- continue only after a saved submission exists
- resume from persisted JSON, not memory

The UI Contract

Web Choices uses a Svelte + mdsvex browser UI. The app shell can be branded and pleasant, but the generated choices stay plain JSON.

Keep this boundary:

  • mdsvex owns the page/template shell
  • Svelte owns cards, selection state, feedback fields, save state, and submit controls
  • generated option text remains data
  • generated option text is not compiled as Svelte or mdsvex source

That boundary matters. A decision surface should not become a tiny CMS that compiles model output as app code.

Persistence Is The Trust Boundary

No saved submission, no continuation.

Drafts are for humans. Submissions are for agents.

I need you to make these decisions before I continue further, and so I look at it, I click the ones I want, give feedback on it, and then submit, and then it continues. So you create a really asynchronous feedback loop between your local agent and how you're talking to it on your phone.

— John Lindquist

The durable state lives under a caller-selected human-in-the-loop output directory, commonly .hitl-choice:

.hitl-choice/
  current-job.json
  drafts/
  submissions.jsonl
  submissions/<submissionId>.json

The agent should wait until a final submission exists, then read selected option ids, per-option feedback, and overall feedback from the saved JSON. It should not infer the decision from visible UI state, draft text, or chat memory.

The Phone Workflow

The phone is for decisions, not implementation.

Click, dictate, click, dictate has been the best workflow for me.

— John Lindquist

The useful mobile loop is intentionally small:

tap option
dictate note
tap option
dictate note
add overall feedback
submit

This works best when the agent has already done the expansion work. The human does the selection work.

Tunnel Boundary

A reviewed, short-lived tunnel can make the local picker reachable from a phone. Keep the specific tunnel product and hostname setup-specific unless the demo evidence is added and sanitized.

The important lesson is not the exact hostname. The important lesson is:

  • keep the local server alive while waiting
  • expose a short-lived token-gated URL
  • let the human submit structured feedback
  • resume from persisted JSON

Do not treat a token-gated URL as full authentication. It is useful friction, not a product security model.

Copyable Artifact: Mobile Decision Surface Brief

Use this when:
- an agent generated several options
- the human needs to choose or annotate them
- the next step should not continue until the choice is saved
- the human may be reviewing from a phone

Choice job:
- jobId:
- title:
- description:
- options:
  - id:
    title:
    description:
    risk:
    suggested proof:
    expected evidence:

UI requirements:
- render options as cards
- allow multiple selection when appropriate
- collect per-option feedback
- collect overall feedback
- save drafts while editing
- write final submission only on submit

Persistence:
- active job: .hitl-choice/current-job.json
- drafts: .hitl-choice/drafts/
- final log: .hitl-choice/submissions.jsonl
- final packet: .hitl-choice/submissions/<submissionId>.json

Agent stop rule:
- wait for a saved submission
- read selected ids and feedback from JSON
- continue only from the persisted submission
- report blocked if no submission exists

Sharing boundary:
- do not expose real tunnel URLs
- do not expose tokens
- do not expose hostnames
- do not expose or share private options or submissions
- do not call the token full authentication

Example prompt:

Turn these billing webhook strategies into a Web Choices job.

Each option needs:
- stable id
- short title
- concrete description
- risk
- suggested proof command
- pass/fail evidence

Serve it as a phone-friendly picker, wait for the saved submission, then continue only from the persisted JSON.

If It Goes Wrong

If the tunnel fails, keep the same job state when possible. Reuse the token only if it was not exposed; otherwise rotate the token, restart the tunnel, and verify the current job is reachable before asking for another decision.

If the server dies, inspect the output directory first. Restart with the same state if drafts or submissions already exist.

If the human says they submitted but the wait command has not returned, check submissions.jsonl, per-submission files, and whatever reviewed server logs or status endpoint the current implementation exposes before regenerating choices.

Claim Boundaries

Web Choices is a local human-in-the-loop pattern with a small web UI and durable files. It is not a production approvals system by default.

Verify timeout behavior, tunnel behavior, mobile rendering, submission persistence, and data handling in the current setup before sharing executable setup instructions.

Source references