ADR-512: Each shipped Claude Code mod has one wanted state in settings, under mods., and ways manage converges every target to it¶
Summary¶
- Decided: each mod agent-ways ships to Claude Code (today
attendandways-judge) has one wanted state,mods.<name>.install, in the ways config, and its other settings sit beside it under the same name, soattend_mod.*becomesmods.attend.*.ways manage repair, andupdateandreinstallthrough it, converge every enabled target to each mod's wanted state. A wanted mod on a Claude Code below the mod's floor stays pending, is reported with the floor, and is tried again at every later repair. A mod that repair installed and that is later uninstalled by hand is not put back: repair writesinstall: falsefor it in that target's config and says so, so the operator's removal becomes a visible setting. The per-target record file that kept ways-judge installed is removed. Choosing a judge engine writesgate.engineandmods.ways-judge.installtogether, through one step that every writer ofgate.enginecalls.ways manage mod list | check | install | uninstall | repairmanages the mods, reporting until--commit, and the settings screens'modtab gains one node per mod with its state per target, its settings and those actions.ways settings lintandways manage updatename every file that still holds the oldattend_modsection; nothing rewrites those files on its own, andways settings fixmoves the values when the operator runs it. - Trades away: an engine switch now installs or uninstalls a plugin, and switching back costs a reinstall from the local marketplace. Repair now writes a setting on its own, the
install: falsethat records a removal by hand, and keeps a list of the mods it installed in each target so that it can tell a removal by hand from a mod it never installed. A by-hand removal of ways-judge whilegate.engineisclaude-codeleaves the engine and the mod disagreeing in that target until the operator picks again. Attend loses ADR-406's reinstall on every repair. Every file that holdsattend_modkeeps it until the operator runs fix, and until then a project that setattend_mod.listening: activestarts its sessions dormant. A ways-judge install is refused byways manage modon its own: it follows the engine. - One-way? No. Reversible: the change is settings keys, one convergence rule, a per-target list and a CLI group, and can be undone in one session. The rename becomes more work to undo once operators have run
ways settings fixon their files, since undoing it needs the same carry-over in the other direction. - Probes: Confident (heal): you want to pick Claude Code internal once and have agent-ways install its mod whenever Claude Code can run it, so that after a Claude Code upgrade
ways manage updateis the only step. Not confident (by-hand): if you uninstall one of these mods with Claude Code's ownclaude plugin uninstall, repair leaves it uninstalled and writesinstall: falsefor it in that target's settings, whichways manage mod installor the mod tab undoes. - Inversion: at one end Claude Code's plugin list is the truth, and agent-ways installs a mod only when asked and remembers nothing. At the other end agent-ways' settings are the only truth, and repair overrides whatever the operator does in Claude Code. This decision takes installation from the settings, so a wanted mod is installed and kept current without anyone asking again. Removal and enablement sit at the Claude Code end: a removal made there is respected and written back into the settings, and enabling or disabling is left to Claude Code.
Context¶
ADR-406 item 8 has ways manage repair install the attend mod in every enabled target from the app's local marketplace, governed by attend_mod.install. ADR-708 item 9 added the ways-judge mod, installed only when the operator picks Claude Code internal in ways judge-setup. Because that install is on request, the code keeps a record file per target beside the settings merge base, and repair keeps ways-judge installed only where the record exists. The judge engine itself is a separate setting, gate.engine, in the agent file. The settings gate screen and ways settings set write it with no change to the mod, and only ways judge-setup writes the record.
There were two sources of truth for one fact: whether this machine should be running the ways-judge mod. They could disagree. On one host, gate.engine: claude-code was set while Claude Code was below the mod's floor. No record was written, so no later repair or update installed the mod, and the gate failed open until setup was rerun by hand after Claude Code was upgraded. The repair path also never checks a mod's floor; only setup does.
The settings screens have a mod tab that edits attend's settings and nothing else. The operator asked for the lifecycle of the mods (install, uninstall, repair, check) to sit under ways manage, for the tab to gain a level that manages each mod, and for the settings to be named mods.<name>.*. Asked about a mod removed by hand, the operator chose to have repair respect the removal, as ways-judge does today. Asked about files that still hold the old section, the operator chose to have them reported, with the operator running the fix.
Decision¶
The figure shows the writers of each mod's wanted state, and how a repair converges one mod in one enabled target from it.
- One settings section per shipped mod,
mods.<name>. mods.attendholds whatattend_modholds today, under the same key names:install,listening,keepwarm,poll_seconds,slow_poll_seconds,quiet_minutes,preamble_every_turns,headless_pollandkeepalive.*. Each key keeps its type, default and scopes, as ADR-406 item 11 and ADR-414 set them.mods.ways-judgeholdsinstall, default false.installis the wanted state. Its scope is the user config and a target's config (ADR-184 item 2), resolved per target with the target winning; a project cannot set it, since repair acts per target.mods.attend.installkeeps its default of true.- The mods are the plugins
plugins/.claude-plugin/marketplace.jsonlists. Each has aModentry in the ways binary, carrying its floor, and amods.<name>section in the settings registry. A test fails when the marketplace file and the two lists disagree. -
Every reader moves in the same change: the ways binary, the attend mod's
ways settings listcall, attend's keepwarm policy and status, attend-chat's settings editor, sensor-keepwarm, the attend skill and way, and the docs. A process that started before the update and still asks forattend_mod(a running mod module, a runningattend) gets no section and falls back to its defaults, dormant with keepalive off, until it restarts or runs/reload-plugins. A caller that degrades quietly does not fix the name it calls (ADR-507 §2), so no alias is kept. -
The old section is reported where it lives, and moved only by the operator.
attend_modjoins the ways config's retired keys, and no code configures anything from it (ADR-506). ways settings lintreports it in every file that holds it: the user config, each target's config, and the.claude/ways.yamlof every projectways projectsknows. Each line names the file and the command that fixes it.ways manage updatenames the same files, in its what-if report and in its--commitrun, as one ⚠ section after the actions. It rewrites none of them.ways settings fix mods.attend(with--project <dir>for a project file) moves the section when the operator runs it: eachattend_mod.<key>value is written tomods.attend.<key>in the same file, and the old section is removed. Where a file holds both, themods.attendvalue stays, the old one is removed, and fix says which values it dropped. This adds one repair to fix: today fix leaves a top-level key no section owns for a hand edit, because it cannot know what the key meant. A retired key that names its successor is the one case where it can.-
Until a file is fixed, the values in it are not read. A project that set
listening: activestarts dormant, and user tuning reads as defaults. The release that ships this lists the move and the command (ADR-506 §4). The retired-key entry stays as long as the table keeps the entries it holds today. -
The wanted state replaces the record file; repair keeps a list of what it installed. The
ways-judge-installedrecord and the code that writes and forgets it are removed. Repair keeps its per-target state where it keeps it today, in theattend-mod-marketplacefile beside the target's settings merge base. That file already records the folder a repair added the marketplace from. It now also lists the id of each mod a repair has installed in that target and not removed since.executeupdates the list after each call, where it updates thependingline today: an install that succeeds adds the id; an uninstall, or a marketplace removal, made by repair removes the ids it takes out; a failed install adds nothing. The list records what repair did; what is wanted lives only in settings. The first repair after this change adds every mod of ours it finds installed from this app's marketplace in that target, and reads no older file.
For each enabled target, repair (and update and reinstall, which run it) resolves each mod's install and:
- Not wanted: uninstalls the mod where it was installed from this app's marketplace and removes it from the list. It removes the marketplace when no mod is wanted in that target, as ADR-406 item 9 does today.
- Wanted, installed: updates an older copy by ADR-406 item 8's calls.
- Wanted, missing, on the list: removed by hand. Repair does not reinstall it. It writes mods.<name>.install: false in that target's config, removes the id from the list, and reports one line naming the write and ways manage mod install <name> as the way back. The write goes to the target's config, not the user config, because the removal was seen in that one target; a write to the user config would take the mod out of every other target. It goes through the settings writer like any other write, so it is visible in ways settings list, in the mod tab and in git diff of a tracked config. Under --what-if it is reported and not made.
- Wanted, missing, not on the list, host able: never installed, or an install that failed. claude is on PATH, its plugin CLI answers for the target, and claude --version is at or above the mod's floor (min_claude_code). It adds the marketplace and installs the mod, and adds the id to the list.
- Wanted, missing, not on the list, host not able: pending. Repair changes nothing for it and reports one ⚠ line with the reason, the floor and the fix (upgrade Claude Code, then ways manage update --commit). Pending is derived each time from the setting, the list and the host, and is tried again at every later repair. It never fails the repair, as ADR-406 item 8 has it for a failed call.
- Disabled in Claude Code (enabledPlugins false, through /plugin or claude plugin disable): left disabled. Enablement stays Claude Code's control, as ADR-406 item 8 promised the operator. ways manage mod check reports it and names the enable command.
- A plugin of the same name from another marketplace: the operator's; reported and left alone, as today.
- Not wanted because a finding decided it: held. The deciding file is the higher of the target's config and the user config whose text sets mods.<name>.install; with neither, the default decides. A finding decided the false when that file does not parse, when its mods.<name> entry fell back on a bad value or an unknown key and install is not written false there, or, with no file setting the key, when the user config's whole mods section fell back. install then takes its fail-closed reading, false, and repair does not act on it: it leaves the mod installed or not, as it finds it, and reports one ⚠ line naming the finding, its file and line, and the fix. A finding in a file that did not decide changes nothing, and repair acts on an install: false written beside a finding, as ways manage mod uninstall writes it. An installed held mod keeps the marketplace, and the ways-theme mod its theme claim, as a wanted one does.
Note, 2026-10-30: added after 1.48.2 removed
mods.ways-theme.copy_asand an operator's config still held it. The unknown key had the entry ignored,installread false, andways manage update --commituninstalled the mod.
A removal by hand of the whole agent-ways marketplace takes every mod on the list out with it, and repair reads it as a removal by hand of each. A disabled target is withdrawn as today: every mod is uninstalled before its links go, whatever its setting (ADR-184 item 4), and the list is emptied. The settings stay, so enabling the target again installs what is wanted.
This applies to attend and ways-judge alike, and changes ADR-406 item 8 for attend: repair no longer reinstalls an attend mod the operator uninstalled. For ways-judge with gate.engine: claude-code, a removal by hand leaves the engine as it is. That target's sessions find no judge host and resolve as ADR-708 item 2 says for that case, and ways manage mod check reports the disagreement and names both fixes: ways manage mod install ways-judge, or ways judge-setup to pick a key engine.
- The engine choice writes the judge mod's wanted state. One function writes a judge engine, and every writer of
gate.enginecalls it:ways judge-setup, the settings gate screen,ways settings set gate.engineandunset. claude-code: writesmods.ways-judge.install: truein the user config first, thengate.engine: claude-codein the agent file.anthropic,openrouter, unset, or no judge (gate.mode: offfrom setup): writes or clearsgate.enginefirst, thenmods.ways-judge.install: false.- The two settings live in two files, so the write cannot be atomic. The order makes a failure between them leave the mod installed under a key engine, where ADR-708 item 2 has it stand down. It never leaves
claude-codeselected without the mod wanted in the user config. ways judge-setupand the gate screen runways manage mod repair ways-judge --commitafter the write.ways settings setonly writes, and prints the repair command; the mod is installed at that repair or the next update.- A write of
mods.ways-judge.installin the user config that is not part of an engine choice is refused, with the engine command as the fix, so the engine and the user config's wanted state always agree. A target's config may holdmods.ways-judge.install: false, written by the operator or by repair after a removal by hand (item 3), to keep the mod out of that one target;ways manage mod checkreports it whenever the engine isclaude-code. -
claude-codestays selectable and is never the default (ADR-708, alternatives).ways judge-setupkeeps ADR-708 item 9's check and does not offer it on a host below the floor. The gate screen andways settings setaccept it there, write both settings, and report the mod pending with the floor, so the upgrade heals it. -
ways manage mod. A group underways manage(ADR-509 item 1's table gains it):
| Command | What it does |
|---|---|
ways manage mod list |
Each shipped mod: shipped version, wanted state, and per enabled target installed version, pending, removed by hand, disabled or absent. Read-only. |
ways manage mod check [<mod>] |
Read-only diagnosis, per mod and target: Claude Code's version against the floor; the agent-ways marketplace present and this app's; the plugin installed, and its version against the shipped one; enabled in Claude Code; installed state against wanted state; for ways-judge, whether gate.engine agrees in every enabled target. Each problem is one ⚠ line naming its fix command. Exit 0 when every check passes, 3 with any problem, as ways settings lint. |
ways manage mod install <mod> |
Writes mods.<mod>.install: true in the user config, removes an install: false from each enabled target's config, then converges that mod in every enabled target. --target <dir> acts on that target's config only. For ways-judge it is the engine choice of item 4 for claude-code, and its report shows the engine change. |
ways manage mod uninstall <mod> |
Writes install: false in the user config (or with --target <dir> in that target's) and converges. For ways-judge while gate.engine is claude-code it refuses and names ways judge-setup, since removing the judge's host would leave the gate failing open or paying for a key. |
ways manage mod repair [<mod>] |
Converges the mods, or one, in every enabled target, with no projection or settings merge. ways manage repair does the same as one of its stages. |
install, uninstall and repair report what they would change until --commit, in ADR-511's report shape, and follow install.manage_mode as repair and target do (ADR-511 items 1 to 4). A bare ways manage mod opens the settings screens on the mod tab on a terminal, and in a pipe prints its help and exits 2 (ADR-509 item 2). ways status and ways manage update's report name every shipped mod, pending ones with their floor and removed ones with the setting repair wrote, where today they name attend's state and ways-judge's version only.
Clarification, 2026-10-23: the refusal of ways manage mod uninstall ways-judge while gate.engine is claude-code applies to the user config only. With --target <dir> it writes install: false in that target's config, which is item 4's per-target opt-out.
- The settings screens'
modtab gains a level. The tab's prefix becomesmods. Its top level is one node per shipped mod, labelled with its name, shipped version and a one-word state (converged,pending,removed,held,disabled,off,drift). Each node holds: - a read-only row per enabled target with that target's state and, for pending, the floor;
- the mod's settings,
installamong them; for ways-judge, the user config'sinstallis shown read-only with the gate tab named as where it is set; - its actions, queued as the CLI commands of item 5 through
agent_tui::tree::Action:check(reads, verifies),installoruninstall(confirm; touches each enabled target's plugin list, settings.json and config), andrepair(confirm; labelledupdatewhen an installed copy is older than the shipped one). ways-judge'suninstallis absent whilegate.engineisclaude-code, and itsinstallnames the engine change in its confirm text.
mod
├─ attend 0.29.0 removed
│ ├─ ~/.claude installed 0.29.0, enabled
│ ├─ ~/.claude-work removed by hand; install false in this target's config
│ ├─ install true (default)
│ ├─ listening dormant (default)
│ ├─ keepwarm … keepalive … poll_seconds …
│ └─ [check] [install] [uninstall] [repair]
└─ ways-judge 1.43.0 pending
├─ ~/.claude pending: Claude Code 2.1.300 is below 2.1.304
├─ install true (set by gate.engine: claude-code)
└─ [check] [repair]
The scenario script for the ways screens gains the states this tab reaches (tui-verification way).
This amends ADR-406's Decision: item 8's install and update gain the floor check, the pending state, and the rule that a mod removed by hand stays removed and is written back as install: false; item 9's removal is unchanged; item 11's section is renamed to mods.attend. It amends ADR-708's Decision: item 8's engine choice and item 9's setup choice of Claude Code internal now write mods.ways-judge.install through item 4's step, and the mod is kept installed by that setting, not by a record. Earlier records that name attend_mod.* keys (ADR-406, ADR-411, ADR-414, ADR-510) read with mods.attend.* in their place; they are not amended for the name alone.
Consequences¶
Positive¶
- One setting decides whether a mod should be installed, and it lives in the config that reinstall keeps, beside the engine it serves. Engine and mod agree in the user config by construction.
- A host below a mod's floor heals by itself: upgrade Claude Code, run
ways manage update, and every wanted mod installs. The operator never has to remember to rerun setup. - Repair checks every mod's floor before it installs, where today only setup checks ways-judge's.
- A removal made in Claude Code is respected, and it is not hidden in a state file: it shows as a setting the operator can read, change, or undo with one command.
- The operator can see and change each mod's state in one place, from the CLI or the mod tab, and
checknames the fix for each problem. - A third mod needs a marketplace entry, a
Modentry and amods.<name>section, and the lifecycle, CLI and tab follow from those.
Negative¶
- Switching the engine to or from Claude Code internal installs or uninstalls a plugin. Switching back costs a reinstall, which is quick from the local marketplace, and running sessions take the change at their next start or
/reload-plugins. - Repair now writes the ways config itself, for a removal by hand. A repair the operator thought of as converging projections can change a target's settings, and its report has to say so plainly.
- Repair depends on its list of installed mods. If the state root is lost or reset while a mod stays installed, the next repair re-adds the mod to the list, so nothing breaks. If the list is lost after a removal by hand, that removal reads as never installed and repair installs the mod again.
- Attend is no longer reinstalled on every repair. A target where the operator removed it stays without it, and attend's sessions there fall back to Monitor (ADR-406 item 9), until the operator installs it again.
- A by-hand removal of ways-judge under
gate.engine: claude-codeleaves the engine and that target's setting disagreeing. Sessions there judge on a key or not at all (ADR-708 item 2) until the operator acts onmod check's line. - Every file that holds
attend_modkeeps it until the operator runs fix. Until then a project that hadlistening: activestarts sessions dormant and the user's attend tuning reads as defaults. Lint and every update name the files, but nothing fixes them on its own. - During an update, a running mod module or
attendprocess asks for the old section and falls back to defaults until it restarts. ways settings fixlearns one rename repair. It is code that knows the old name, kept only to rewrite files.- The engine write spans two files with an order, and a direct write of
mods.ways-judge.installin the user config is refused, which makes it the onlyinstallkey thatways settings setwill not take there.
Neutral¶
- The marketplace folder record and ADR-406's foreign-marketplace rules are unchanged; the file that holds the folder gains the list.
- ADR-708's session resolution is unchanged; a target that keeps ways-judge out resolves through its no-host path.
- The hidden
ways reconcilekeeps applying with no flag (ADR-511 item 8), so the previous release's updater converges mods by the new rule once the new binary is installed.
Alternatives Considered¶
- Keep the record file and have every writer of
gate.enginewrite it. The smallest change. Rejected: the record lives in state beside the merge base and the engine in config, with different owners and lifetimes, so there would still be two sources of truth, and repair still would not check the floor. - Derive ways-judge's wanted state from
gate.engine, with noinstallkey for it. The two could not disagree by construction, and there would be no two-file write. This is the strongest alternative. Not adopted: it gives ways-judge a lifecycle unlike attend's, somods.<name>.install, themodverbs and the tab would each need a special case for it. It also leaves no setting to record a removal by hand in one target. Item 4's single write step and its refusal in the user config give the same agreement with one shape for every mod. - Reinstall a wanted mod the operator removed by hand. One rule, settings as the only truth. Rejected by the operator, who chose to have repair respect a by-hand removal, as ways-judge does today. Writing the removal back as
install: falsekeeps that behaviour without a hidden record. - Record a removal by hand in a state file, as the
pendingline does today. No settings write by repair. Rejected: the operator's choice would again live outside settings, whereways settings list, the mod tab andcheckcannot show it. - Tell a removal by hand apart using the settings merge base or Claude Code's
enabledPlugins. No new list. Not possible: the merge base holds only hooks and permissions, and Claude Code drops a plugin'senabledPluginsentry on uninstall, so neither shows that a plugin was installed before. - Write the
install: falsefor a removal by hand in the user config. Rejected: a removal seen in one target would take the mod out of every other target. - Keep
attend_modand add ajudge_modsection. No rename and no fix step. Rejected: the operator namedmods.<name>.*, and a top-level section per mod grows the config's top level with every mod. - Read
attend_modas an alias ofmods.attendfor a release. Running processes would keep their settings through the update. Rejected under ADR-506: the fix command moves the values, and the callers that would need the alias fall back safely. - Have
ways manage updaterun the fix on every file it finds. No dormant window. Rejected by the operator, who chose to have the files reported and to run the fix themselves. - Refuse to record a wanted mod on a host below its floor. Rejected: that is the failure that prompted this record. A wanted state that waits for the host lets an upgrade heal it.
- Make
ways settings set gate.enginerun the repair itself. One command would finish the job. Rejected:ways settings setwrites settings and calls no external CLI anywhere else. Setup and the gate screen run the repair, andsetnames it.