Repository navigation
v1.0.1
- New: the session's native Todo list is drawn from the goal plan. While a plan exists the plugin rewrites the arguments of the model's own
todowritecall intool.execute.before, so the host performs exactly one write and the checklist every client renders is the plan: one row per action in plan order, contenta3 · rebuild dist(the action id,·, and the title bounded to 120 characters), and a plan past 20 actions ending in one counted+N more actions — /goal statusrow. The status map exists to stop the native[✓]asserting something the plugin's own evidence gate refuses — adoneaction becomescompletedonly once it is verified, adoneaction without a passing verdict mirrors asin_progresswith— needs claim/evidence/verdict, and ablockedaction mirrors asin_progresswith— BLOCKED: <reason>, which is what the host's own todo contract asks for. Rows the model wrote itself are kept, below the plan rows, at most 10 of them and each bounded to 120 characters; nothing of the model's is silently deleted, and the tool result names how many were kept and how many the cap trimmed.todowrite({todos: []})is the refresh idiom and it is a redraw, never a delete: with a live plan it re-emits the projection and leaves the kept rows alone, with no live plan it re-emits the last mirrored rows or the terminal snapshot taken when the goal ended, and only in a session that never mirrored anything does an empty call reach the host as an empty list. A stale mirror is nudged at most three times per goal run —Todo panel is stale — call todowrite({todos: []}) once; the plan is copied into it for you.— shared across the auto-continue block andgoal_action_update's result, and/goal resumerefunds the budget in full./goal stop,/goal clearand a genuine completion each hand the list back in one line, because the mirror is one-way and the rows outlive the goal.- New option
mirrorTodos:"plan"(default) or"off"."off"restores 1.0.0 exactly: all threetodowritehooks return before touching anything, every prompt surface that mentions the mirror is silent, andgoal_plan_set's,goal_action_update's andtodowrite's descriptions are the stock bytes — the<existing_todos>offer below is skipped along with the host read that produces it, so an"off"instance makes nosession.todocall at all. The option is static and instance-wide by construction, so it cannot introduce cross-session skew. - There is no "adopt" mode. A session that already has native todo rows when
/goal setruns gets them described back to the model once, in an<existing_todos>block on the goal's first continuation, with the instruction to either record them as the plan throughgoal_plan_set— rewritten as falsifiable claims — or ignore them. The read is best-effort and read-only: nothing is adopted,goal.mirror.extrastarts empty, and a failing or absent host call is logged and skipped rather than blocking/goal set. - The Goal panel becomes an exception list while the mirror is on, because the Todo section is already showing the plan: unverified
doneactions first, thenblocked, thenin_progress, each group in plan order, andpendingactions are not repeated. Adoneaction without a verdict gains the same— needs claim/evidence/verdictsuffix on its panel line that its mirrored row carries, and the progress line gains· todo mirror fresh (5),· todo list stale, or· mirror drift (7≠5)when the panel's own live read of the host's list disagrees with the payload. Under the exception list+N morecounts only the exception rows the 12-row cap dropped, over the published actions rather than the whole plan, so a server-capped plan cannot promise rows the payload does not carry. A payload with noplan.mirror, or one whose state isoff, renders exactly as it did in 1.0.0. metadata.goalpayload is nowv: 3, adding two keys:plan.mirrorandplan.actions[].verified.plan.mirrorcarriesstate("fresh","stale"or"off"),rowsandextra(how many rows the last mirrored write held and how many of those were the model's own), andat(when that write landed,0for never).verifiedis the server's own CEV verdict on each published action —doneand a claim and evidence andverdict: "pass"— and it exists because a consumer cannot re-derive it:claimandevidenceare goal-private prose that never go on the wire, andgoal_plan_setaccepts adoneaction with a passing verdict and no ledger (onlygoal_action_updateenforces the gate), sostatusplusverdictrenders exactly that action as finished. The Goal panel now reads the flag rather than inferring it, which is what puts such an action back in the exception list with its— needs claim/evidence/verdictsuffix, agreeing with the mirrored todo row and the progress count that already named it unverified. Every v2 key is still written and both keys are purely additive. Skew warning, unchanged in shape from the v1→v2 one: the two halves are registered separately (opencode.jsonandtui.json), and the panel never readsvat all, so a 0.11.0 panel against a v3 payload simply lists every action and shows no mirror suffix, and the current panel against a v2 payload does the same. Upgrade both halves together.- Two new hooks:
tool.execute.afterandtool.definition. The freshness stamp lives in the after hook because only that hook proves the host actually wrote the list — between the two hooks the host decodes the arguments and asks for permission, and either can abort the call, so a mirror stamped fresh for a write that never landed would suppress the very nudge that repairs it.tool.definitionappends a static paragraph to the builtintodowritedescription telling the model what the tool now does in a goal-bearing session; it is never gated on goal state, because the hook carries no session id.scripts/verify.mjsrequires both, so the hook surface it checks is now eleven names. A host that does not knowtool.definitionsimply never fires it. - The
todowritedescription suffix is stamped at most once per object. Thetool.definitionhook returns early when the description it was handed already carries the mirror paragraph, so a host that re-triggers the hook against the same output object — or a second registration of this plugin in one directory — cannot double it. OpenCode 1.18.29 rebuilds the description object on everyToolRegistry.tools()call, so this is defensive rather than a fix for an observed host; it is pinned by a unit that stamps one object twice and by a mutation anchor that deletes the guard. - Seven hazards are documented rather than fixed, in
docs/compatibility.md: the suffixedtodowritedescription reaching goal-less sessions in the same project,todowrite: "ask"turning every refresh into a permission modal, hosts wheretodowriteis denied (the mirror never becomes fresh, so the panel reads stale for the whole run and the nudge self-suppresses), another plugin'stool.execute.beforeoverwriting the mirror with no way to detect it, the host's second and hooklesstodowriteimplementation,/undonot rewinding todos, and one deliberate departure from the host's one-in_progressconvention. The same document records the transcript bubbles — which the mirror reaches through theargsrewrite rather than through a plugin slot, so on 1.18.29 they show the mirrored rows andnpm run smoke:todo-safetyre-measures that every run — and thatpriorityis wire-only in the TUI. - The published type declarations carry the whole surface.
index.d.ts:GoalSidebarStatus.vbecomes3,plan.mirror({ state: "fresh" | "stale" | "off"; rows; extra; at }) andverified: booleanon every published action joinGoalSidebarStatus,mirrorTodosjoinsGoalPluginOptions, andtool.execute.afterandtool.definitionjoinGoalPluginHooks.tui.d.ts:GoalPanelModelgains an optionalmirror(state,rows,extra,liveTodoCount,drift), andgoalPanelModelgains a second parameter —goalPanelModel(raw, options?: { liveTodoCount?: number }). That parameter is optional, so a 1.0.0 call site that passes only the payload still typechecks and simply renders no drift comparison. Reading a payload is likewise unchanged; only code that constructs aGoalSidebarStatusliteral has to grow the three new required fields, since that type describes what the server writes. One deliberate asymmetry between the two files: the panel'smirror.stateis declaredstringrather than the server's three-value union, because the panel forwards whatever state the payload carried — a newer server can invent one — and it stands the progress suffix and the drift comparison down for a state it does not recognise, while still treating the mirror as active. Both files are typechecked as a consumer sees them, under NodeNext and Bundler resolution, bynpm run type:check. - The packed type contract exercises the 1.0.1 surface, not just the 1.0.0 one. The
npm run type:checkfixture now setsmirrorTodos: "plan"in itssatisfies GoalPluginOptionsobject with a@ts-expect-errornegative case for an invalid value, callstool.execute.afterandtool.definitionbesidetool.execute.before, readsplan.mirror.stateandplan.mirror.rowsoff aGoalSidebarStatus, and callsgoalPanelModelboth with and without its new options argument — so a declaration that stops compiling for a consumer fails the gate instead of waiting for the next reader.
- New option
- New: two real-host smokes and a benchmark for the mirror.
npm run smoke:todo-mirrorboots a realopencode serveagainst a mock model and asserts the plan is redrawn over a divergent list, with two controls — the same run undermirrorTodos: "off", and a session with no goal — plus the SQLite row order and survival across a restart of the serve process.npm run smoke:todo-safetyis the destructive half, and every assertion in it is about rows surviving: an emptytodowritearriving after/goal stopor after a genuine completion must re-emit the last mirrored rows rather than wipe the list, and the same call in a session that never had a goal must still clear it. Both need theopencodebinary onPATHand a freshly bundleddist/, and neither is inrelease:check, because that binary is not a dev dependency.scripts/bench-todo-mirror.mjsmeasures the metric the design set: the number of distinct persistent checklists the sidebar renders, target one, under"plan"against an"off"control. - Unchanged: the identifier policy, and the state file version. No new wire identifier and no new state path.
STATE_FILE_VERSIONis deliberately not bumped — a mismatch is rejected rather than migrated, so a bump would refuse every existing record; instead the mirror record is normalised on load, and a goal written before 1.0.1 comes back with an empty, never-mirrored one. The part metadata key, the plugin id, the logservicefield and both legacy state paths keep their historicalopencode-goal-pluginstrings, per the standing rule below.
Install: opencode-goal-pro-max-complete-plugin@github:sblattj/opencode-goal-pro-max-complete-plugin#v1.0.1 (see docs/reference.md).