Skip to content

About

OpenCode v2 plugin: oracle_ask second-opinion tool, /advisor, and an autonomous /goal loop

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

11 Commits

Folders and files

Repository files navigation

opencode-advisor

An OpenCode V2 plugin that gives the agent a second opinion and a way to keep working until a goal is met.

  • Native advisor subagent: runs in the background like every OpenCode subagent and reports back when idle, with a bounded parent-evidence snapshot and read-only tools. OpenCode owns the child lifecycle and continuation; this plugin supplies evidence and model selection. Configure an advisor subagent in your agents directory. The old oracle_ask tool is no longer registered.
  • /advisor: shows or sets the advisor model.
  • /goal <what done looks like>: the agent works turn after turn. After each turn the advisor judges from the transcript whether the goal is met, blocked, or still missing something. Rounds are unlimited by default. The loop stops when the goal is done, and pauses when the agent is blocked, makes no progress for 3 rounds, or hits an explicit -n round limit.

Install

opencode plugin add github:c0dn/opencode-advisor

Requires OpenCode 2.3 or later (subagents always run in the background). The package has a server part (the tool, the goal loop and an RPC) and a TUI part (the slash commands, dialogs and toasts). OpenCode loads both automatically.

Commands

/advisor                                   show the advisor model and where it is set
/advisor <provider/model[#variant]>        set it for this project
/advisor --global <provider/model[#variant]>  set the default for all projects
/advisor reset [--global]                  clear the project (or global) setting

/goal <goal>                               start working autonomously
/goal -n <count> <goal>                   the same, with a round limit
/goal                                      show the current goal
/goal stop                                 drop the goal (the turn in progress finishes)
/goal resume [-n <count>]                 unlimited, or count additional rounds

Goals survive an OpenCode restart. Round updates appear as toasts, and as a desktop notification while the terminal is in the background.

Waiting for background work

Optional agent-owned completion

Set "external_judge": false in this plugin's options to skip goal verdict model calls. The default is true, preserving independent judging. In judge-free mode, an idle turn continues the goal until the agent calls goal_complete({summary: "…", verification: "tests/checks and their results"}). The completion tool is only exposed in this mode and rejects inactive goals, registered waits, and blank evidence. Evidence is reported by the agent, not independently validated. Round limits and interrupted-turn handling still apply; advisor-based stall detection is unavailable. Use /goal stop when blocked. goal_wait still suspends continuation while background work runs.

Disable consultations separately

/advisor off blocks native advisor invocations for this project, including explicit model overrides and follow-ups. /advisor on re-enables them without changing the selected model. Add --global to set the default for all projects; an explicit project setting takes precedence. /advisor displays both the consultation status and goal judge mode. /advisor reset [--global] clears both model and consultation overrides for that scope, restoring inheritance.

These switches are independent: /advisor off does not disable goal verdicts, and external_judge: false does not disable manual consultations. To avoid both kinds of advisor-model calls, use both settings. Turning consultations off blocks new requests; it does not cancel an already-running request.

goal_wait and goal_complete are offered only in a session whose goal is running or waiting. Other sessions, including every subagent, never see them: a subagent that must wait for long work arms its own automation_create, which wakes that subagent, and its next idle report reaches the parent.

When no independent work remains, call goal_wait and end the turn. Waiting uses no model calls or goal rounds. goal_wait only pauses judging; it never delivers results. Delivery is OpenCode's own and happens per item, as soon as each one finishes, so a long subagent can never hold back another result. Failure and cancellation are evidence for the parent, not success.

ids takes any mix of:

  • Shell IDs and child sessionIDs from background launches in this session, e.g. goal_wait({ids: ["sh_…", "ses_…"], reason: "need test and research results"}). They live inside the OpenCode server, so a restart, or the server dropping a shell when it unloads an idle project, loses them.
  • Automation ids (aut_…) from OpenCode's automation_create (enable "experimental": { "schedules": true }). OpenCode renamed schedules to automations in Nov 2026; older sch_… ids still bind and match the renamed wake. Use these for anything long or restart-sensitive: training, long evals, remote jobs. Automations are stored in OpenCode's database and fire even if the server restarted in between. There is no until shell check any more, so use an every trigger whose prompt checks the job's log:
setsid -f bash -c 'python train.py --run 3 >/abs/run3.log 2>&1; echo EXIT=$? >>/abs/run3.log' </dev/null

then automation_create({name: "run3", trigger: {type: "every", every: "10 minutes"}, action: {type: "prompt", prompt: "If /abs/run3.log has an EXIT= line, read it and continue; otherwise do nothing and end the turn."}}) and goal_wait({ids: ["aut_…"], reason: "run3 training"}). A remote job needs no local process at all: have the prompt run the remote status command.

The wake is a normal message, so it arrives whatever state the goal is in. Calling goal_wait again replaces the judging list and never cancels a delivery. Judging resumes once every listed id has been delivered and handled by a parent turn. A subagent report tagged state="running" (the child still owns a running shell, image or nested subagent) is interim; the wait continues until its final report. A child waiting on its own schedule cannot be told apart from a finished one, so for such work arm a schedule in the parent on the same check and wait on that.

Lost and expired dependencies. A shell or subagent is lost when a different OpenCode server process is running than the one that launched it, or when its shell output file disappears (after a 30s grace). Schedules are never lost. A lost dependency, or one still open at the deadline, gets one reconcile turn telling the agent to check the real state before relaunching anything. If the same dependency is lost or expires again, the goal pauses.

The default deadline is 24h (timeoutSeconds: up to 7 days, or 30 days when every id is a schedule). /goal resume overrides a wait and resets the reconcile allowance; /goal stop stops the goal without touching background work. Waits persist across plugin and OpenCode restarts. Waits saved by older versions on detached jobs are dropped with a notice. Do not wait on a persistent dev server itself.

Consultation boundaries

Each advisor child prompt receives a snapshot of its recorded parent's active context (after compaction), not arbitrary sessions or hidden reasoning. The snapshot is capped at 160k characters, with individual results clipped and omissions marked. Follow-up prompts add only evidence since the saved message boundary (including that boundary's potentially updated tool results). Compaction that removes the boundary causes a fresh bounded snapshot. Model/tool steps do not append it again. An explicit native subagent model override wins over /advisor settings.

Advisor and researcher permission hooks deny mutation, shell, nested delegation and approval-dependent actions. Use read/glob/grep and Keenable retrieval (Proteus hosted web tools need no permission); have the parent run authenticated CLI checks. Configure their agent permissions deny-first as well. No custom child runner, polling scheduler or log-monitor plugin is needed.

Waiting checks run at most every five seconds without model calls. A native completion delivered without parent resumption deliberately remains waiting until the parent handles it or the deadline queues a reconcile turn. Common credential paths are denied, but read/search access is not an OS sandbox; do not use these roles for untrusted agents. src/oracle.ts is retained as an unregistered legacy helper and regression fixture, not exposed as a tool.

Configuration

The advisor model is resolved in this order: the /advisor project setting, the --global setting, the plugin's advisorModel option, then OpenCode's default model. Pick a stronger model than the one doing the work.

{
  "plugins": [{ "package": "@c0dn/opencode-advisor", "options": { "advisorModel": "anthropic/claude-opus-4-1" } }]
}

Telling the agent when to use it helps. For example, in AGENTS.md:

- Call native `advisor` for consequential uncertainty, repeated failures or independent
  verification. It reports back when idle; end the turn if you have nothing else to do.
- Call `goal_wait` before ending a goal turn solely to await background work: shell IDs or subagent sessionIDs for short work; for anything long or restart-sensitive, launch it detached, arm `automation_create` with an `every` trigger whose prompt checks the job's log, and wait on the automation id (`aut_…`).
- A message starting `[goal round N/M]` comes from `/goal`: keep working and show verifiable evidence.

Development

bun install
bun test
bun run typecheck

Point OpenCode at a checkout with a file:// entry in opencode.json plugins. Releases are published to npm by GitHub Actions when a GitHub release is created. The tag must match package.json's version, e.g. v0.1.0.

About

OpenCode v2 plugin: oracle_ask second-opinion tool, /advisor, and an autonomous /goal loop

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages