Smart Questions

Installation · How It Works · Configuration · Changes · Validation · Architecture

A standalone OpenCode plugin that selects an agent-recommended answer after a configurable countdown, unless the user intervenes. It supports single-choice and multiple-choice questions with separate OpenCode V1 and V2 adapters.

Language-independent selection: question text and options can be written in any language. The plugin recognizes an exact marker such as [SQ:recommended]; it does not translate or judge the meaning of recommendations. The older (Recommended) and (Önerilen) markers are also accepted.

---

🚀 v0.3.1 Changes

• V2 tool-transform and session-context registrations are awaited, tracked and disposed on teardown; partial setup failures roll back registered hooks.
• Missing-project-configuration tests and V1 TUI race tests no longer depend on the user's global OpenCode settings. Production configuration precedence is unchanged.
• Updated the V2 development SDK to @opencode/plugin 2.0.22 and the resolved http-cache-semantics dependency to 4.3.0.
• Expanded regression coverage for registration, partial failure, repeat cleanup and global configuration fallback. See verification and limitations for measured results and host-test boundaries.

---

📦 Installation

The source version is 0.3.1. As of 04 October 2026, npm publishes 0.3.0; @latest installs the latest published version, not unpublished GitHub changes. To use the 0.3.1 source before npm publication, follow local development.

🟢 OpenCode V1

Add the package to the server plugin configuration:

{
  "plugin": ["opencode-smart-questions@latest"]
}

To show the countdown panel, also register the same package in the V1 terminal configuration (tui.json):

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["opencode-smart-questions@latest"]
}

The package exposes independent ./server and ./tui entry points. Actual plugin loading depends on the OpenCode build.

🔵 OpenCode V2

Use the V2 plugin configuration:

{
  "plugins": ["opencode-smart-questions@latest"]
}

On V2 builds that support package TUI discovery, the ./tui export provides the countdown and form-reply handling. The V2 path has automated mock-host coverage; a real V2 host has not yet been verified.

🛠️ Local Development

git clone https://github.com/huseyincig/opencode-smart-questions.git ~/.config/opencode/vendor/opencode-smart-questions

Use the absolute file:/// directory URL in the appropriate plugin (V1) or plugins (V2) list; for example:

{
  "plugin": ["file:///home/me/.config/opencode/vendor/opencode-smart-questions"]
}

V1's terminal configuration needs the same directory in its own plugin list. The repository contains compiled dist/ files, so using its committed build does not require compiling on the target machine.

---

⚡ How Selection Works

1. The agent marks each recommended option by appending [SQ:recommended] to its label, regardless of the label's language.
2. The V1 backend receives question.asked; the V2 TUI receives form.created. Both use the same recommendation detector.
3. Only questions with unambiguous recommendations are eligible. V2 also requires supported selectable fields and unambiguous label-to-value mapping.
4. A countdown begins (30 seconds by default). Keyboard or paste interaction cancels pending selection. V1 coordinates with its TUI using a per-request draft lock; V2 owns its form timer in the TUI.
5. If the request is still eligible at expiry, V1 sends question.reply; V2 verifies the pending form and sends session.form.reply.

For example, 保存 [SQ:recommended], حفظ [SQ:recommended], Guardar [SQ:recommended] and Kaydet [SQ:recommended] all use the same detection rule. You can configure additional exact markers without adding language-specific detection logic. Unicode NFC normalization and trailing whitespace are supported.

[!IMPORTANT] Selection is not permission. The plugin cannot determine whether a recommendation is correct, safe or authorized. Its guidance tells the agent not to mark choices requiring explicit human approval, including destructive or irreversible actions, but guidance is not an enforcement boundary. Use OpenCode's own permission and confirmation controls for sensitive actions. The optional countdown is an opportunity to intervene, not a guarantee that an already-sent reply can be recalled.

---

⚙️ Configuration

Settings are loaded from the first existing file in this order: project .opencode/smart-question.json, project smart-question.json, then ~/.config/opencode/smart-question.json. If no file exists, built-in defaults apply. An explicitly malformed configuration disables auto-selection instead of silently substituting a different policy.

{
  "enabled": true,
  "timeoutMs": 30000,
  "recommendedMarkers": [
    "[SQ:recommended]",
    "(Recommended)",
    "(Önerilen)"
  ],
  "requireExactlyOneRecommendation": true,
  "uiText": {
    "recommendation": "Öneri:",
    "disabled": "OTOMATİK SEÇİM DEVRE DIŞI",
    "autoReplyFailed": "Otomatik yanıt başarısız. Lütfen elle yanıtlayın.",
    "agent": "Ajan:",
    "session": "Oturum:"
  },
  "debugLog": ""
}

Setting	Default	Behavior
enabled	true	Enable the plugin; false disables it.
timeoutMs	30000	Countdown in milliseconds. 0 attempts an immediate reply, with no practical intervention window.
recommendedMarkers	["[SQ:recommended]", "(Recommended)", "(Önerilen)"]	Exact accepted suffixes. The first marker is suggested to the agent.
recommendedMarker	first marker	Legacy single-marker setting; recommendedMarkers takes precedence.
requireExactlyOneRecommendation	true	Retained for configuration compatibility. For safety, single-choice questions always require exactly one marked option, even when this is false.
uiText	English labels	Optional TUI translations for recommendation, disabled, autoReplyFailed, agent, and session.
debugLog	""	Optional diagnostic log path. Empty means no diagnostic file.

Multiple-choice questions may mark several options. Questions with no recommendation, ambiguous single-choice recommendations, unsupported V2 field types, duplicate form keys or ambiguous label-to-value mappings are left to the user.

---

🧪 Validation & Testing

npm ci
npm run typecheck
npm test
node sandbox/smoke-test.mjs
node sandbox/comprehensive-test.mjs
npm audit
npm pack --dry-run

CI runs on Node 22 and 24. Unit/regression tests and sandbox scenarios use simulated OpenCode hosts; they do not establish reliable behavior on every released OpenCode build. For implementation boundaries, reproducibility and the remaining real-host checks, see verification and limitations.

---

🏗️ Project Layout

• src/backend.ts: Handles V1 question events and reply transport
• src/ui.tsx: Contains V1/V2 TUI countdown and reply adapters
• src/detector.ts: Recognizes recommendation markers across locales
• src/form-adapter.ts: Maps V2 form options to field values
• src/config.ts: Loads and validates plugin settings
• src/draft-guard.ts: Manages V1 manual answer cancellation locks
• src/index.ts: Registers V1/V2 dual-mode backend adapters
• dist/: Precompiled JavaScript outputs and adaptive TUI loader

---

📄 License

MIT © Hüseyin Hadi Çığ