novox/hq
6
0
Fork 0
Code Issues Pull Requests 6 Releases Wiki Activity

ADR 0216: the agent's configuration is registered through its module, at three scopes, and served as one plugin

Browse Source 
Graduates research 029 and amends design 36 (section 8): skills, subagents,
commands, hooks and output styles in one nox-mesh plugin; servers, settings
and instructions in the managed files; mesh, node and home scopes.
This commit is contained in:
jochen
2026-10-05 11:45:58 +02:00
parent daf2f6d2b1
commit f291d113c8
4 changed files with 233 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
02-DECISIONS/0216-the-agents-configuration-is-registered-through-its-module-at-three-scopes-and-served-as-one-plugin.md
+167
View File
@@ -0,0 +1,167 @@
---
topic: what runs on it
status: accepted
date: 2026-10-05
deciders: jochen
reconstructed: false
extends: 02-DECISIONS/0213-the-operator-sets-the-agents-managed-settings-through-the-agent-module.md
---
# 216. The agent's configuration is registered through its module, at three scopes, and served as one plugin
## Context
The operator wants everything about the coding agent that can be configured to be configured through
the agent module's tools ([research 029](../01-RESEARCH/029-the-agent-configured-through-its-module/00-overview.md)).
That covers subagents, skills, slash commands, hooks, output styles, settings, permissions,
instructions and tool servers. Each is registered once, from any machine, for one machine, several or
all of them.
The agent module already manages three files in the agent's machine-wide managed directory: the
settings, the tool servers and one instruction file ([to-be 36](../03-DESIGN/01-to-be/36-the-operators-agent-on-a-machine.md)).
Tool servers registered through its tools are kept in its state on the bus and reach every machine
they apply to. The vendor has **no machine-wide place for skills, subagents, commands or hooks**; they
live only in a home or a project. Measured on four machines
([029/01](../01-RESEARCH/029-the-agent-configured-through-its-module/01-what-is-configured-today.md)),
what was copied there by hand had drifted and gone stale:
- two skills of a retired system were on all four machines;
- one rule file existed in three versions;
- two contradicting instruction sets were loaded into the same session;
- a subagent existed on one machine only.
The vendor's **plugin** carries skills, subagents, commands, hooks and output styles. A machine-wide
setting can name a marketplace and enable a plugin from it
([029/02](../01-RESEARCH/029-the-agent-configured-through-its-module/02-what-the-vendor-allows.md)).
Tried on one workstation ([029/04](../01-RESEARCH/029-the-agent-configured-through-its-module/04-what-was-confirmed.md)):
- a plugin in a directory marketplace, enabled by the managed settings, loads in every session with no
prompt, read in place, and an edit reaches the next session with no version change;
- its items are offered under the plugin's name;
- its hooks run;
- its tool servers are blocked by the exclusive managed tool-server file.
A plugin cannot carry settings, permission rules or instructions.
The operator also set the scopes. A skill may be meant for:
- every machine;
- one machine;
- one machine's own account, as if written there by hand.
The instruction file the same: the mesh's piece, the node's piece, and further customisation per machine.
## Considered Options
1. **Copy everything into each home**, owned by the mesh path by path. Rejected as the *only* place:
the home is the person's ([ADR 0182](0182-inside-a-home-the-mesh-owns-what-it-places-and-holds-the-rest-as-found.md)),
a mesh item there is indistinguishable from the person's by name, and it fills the directory where
the drift was measured. Kept as one scope of three (below).
2. **A plugin per source:** one for the operator's registrations, one for what other modules
contribute. Rejected: two prefixes to remember for one agent. Where an item came from belongs in
the module's list, not in its name.
3. **Registrations in a repository on the forge**, the plugin built from it. Rejected for now:
registering would be a commit, and the forge would sit on the path to every machine. Configuration
would enter the code review cycle, which it does not need.
4. **One plugin, `nox-mesh`, plus the managed files the module already writes, at three scopes, all
registered through the module's tools and kept in its state on the bus.** Chosen.
## Decision
Option 4.
**1. What goes where.** Each kind of item goes to the one place the vendor honours for it:
| kind | place |
|---|---|
| skills, subagents, slash commands, hooks, output styles | the plugin `nox-mesh` |
| tool servers | the managed tool-server file, as today: the exclusive file blocks a plugin's servers |
| settings and permission rules | the managed settings file: a plugin's settings are dropped |
| instructions | the managed instruction file, in sections: a plugin's instruction file is not loaded |
The plugin is named `nox-mesh` (the operator's choice): the name its items carry in every session, and
not one a person's own plugin is likely to take. It lives in a marketplace directory inside the module's
managed directory, written whole by the module's code. The managed settings name that marketplace and enable the plugin. Those two keys
are the mesh's, laid last like the attribution key (ADR 0213), and no setting replaces them.
**2. Three scopes.** Every registration names one:
- **mesh:** every machine running the agent, including one that joins later.
- **node:** one machine, or a list of them. Rendered into the same plugin and managed files, on those
machines only.
- **home:** the operator account's own agent directory on one machine. The item is placed where the
person's own items live, without the plugin's prefix.
Settings and permission rules take the mesh and node scopes only. The home's settings file stays the
person's.
**3. Instructions follow the scopes.** The managed instruction file holds, in order:
1. the mesh's piece, the same everywhere;
2. the node's piece: its role, and the sections registered for it.
Further customisation per machine is a rule file placed at the home scope. The vendor concatenates
these and does not override, so the module's status tool names any section that contradicts another,
or that calls a tool the mesh no longer serves.
**4. Registered through tools, kept on the bus.** For each kind, the module serves `list`, `register`
and `unregister` tools; for settings, tools that read and set them at a scope. Each registration is a
key in the module's state ([ADR 0201](0201-a-module-keeps-its-current-state-in-key-value-buckets-it-declares-and-reaches-through-the-runtime.md)):
- an item and its files are one value, refused above **256 KiB**, well under the bus's message limit;
- every instance watches the state and renders what applies to its machine.
The settings registered this way are laid over the `managed_settings` layer of ADR 0213. In order:
ADR 0213's setting, then the mesh scope, then the node scope, then the mesh's own keys.
**5. The home scope owns only what it placed.** The module records each home path it placed, in its
state. It writes, changes and removes only those. It refuses to register a name the person already
uses there, rather than overwrite it.
**6. What the module did not place, it reports and can import.**
- A status tool lists the home's items and says which the mesh placed. It also names any that
duplicate a mesh item or call tools no longer served.
- An import tool registers an item found in one machine's home at a scope the operator chooses.
- Removing the original stays the person's act.
- Whether home items load at all stays the operator's choice, through a vendor setting in the managed
settings.
**7. Changing the agent's own settings is the operator's act.** The vendor's guard refuses an agent that
loosens its own settings. A settings or permission tool is called on the operator's word, and the
module does not try to get around that refusal.
## Consequences
- One registration puts a skill, a subagent or a rule on every machine, on some, or in one account. A
machine that joins takes the mesh and node items at its first start. Nothing is copied by hand.
- The plugin's items are named `nox-mesh:<name>`, and a person's own items keep their names. Nothing the
mesh adds can shadow them.
- A change reaches the next session on each machine, or a running one at its next plugin reload.
- **What got harder:**
- an item larger than 256 KiB cannot be registered until the state can hold files in pieces;
- the module's state now holds file content, not only small records;
- the stale files already in the homes stay until the person removes them. The module names them;
it does not remove them.
- **Not decided here:** another module contributing a skill or a subagent to the agent through a seat
([ADR 0210](0210-a-tools-configuration-is-its-seat-holders-and-every-other-module-extends-it-through-the-seat.md)).
The agent module holds no seat yet. When one is decided, contributions land in the same plugin.
## How it is checked
| Rule | Checked by |
|---|---|
| each kind lands in its one place | the module's render test: a registered skill, subagent, command, hook and output style appear in the plugin; a tool server in the managed tool-server file; a setting in the managed settings file; an instruction section in the managed instruction file |
| scopes | the same test, for one machine of two: a mesh item on both, a node item on one, a home item only in that machine's home |
| the marketplace keys are the mesh's | the render test: a setting naming either key is overridden |
| the home scope owns only what it placed | the module's test: a name the person already uses is refused; unregistering removes only the placed path |
| the size limit | the module's test: an item above 256 KiB is refused at registration |
| live | a skill registered at the mesh scope is offered as `nox-mesh:<name>` in a new session on each machine |
## References
- [Research 029](../01-RESEARCH/029-the-agent-configured-through-its-module/00-overview.md) — the evidence, the vendor's rules, and what was confirmed
- [ADR 0213](0213-the-operator-sets-the-agents-managed-settings-through-the-agent-module.md) — the managed settings setting this lays over
- [ADR 0182](0182-inside-a-home-the-mesh-owns-what-it-places-and-holds-the-rest-as-found.md) — what the mesh may do inside a home
- [ADR 0201](0201-a-module-keeps-its-current-state-in-key-value-buckets-it-declares-and-reaches-through-the-runtime.md) — module state on the bus
- [to-be 36](../03-DESIGN/01-to-be/36-the-operators-agent-on-a-machine.md) — the design this amends
02-DECISIONS/README.md
+1
View File
@@ -315,6 +315,7 @@ python3 00-META/checks/index.py fail if stale
- **0213** — [The operator sets the agent's managed settings through the agent module, under the mesh's own keys](0213-the-operator-sets-the-agents-managed-settings-through-the-agent-module.md)
- **0214** — [Backups guard against mistakes, stay on the machine, and are declared by the module that owns the data](0214-backups-guard-against-mistakes-and-stay-on-the-machine.md)
- **0215** — [The machine's message bus is a node seat, and it is never restarted live](0215-the-machines-message-bus-is-a-node-seat-and-is-never-restarted-live.md)
- **0216** — [The agent's configuration is registered through its module, at three scopes, and served as one plugin](0216-the-agents-configuration-is-registered-through-its-module-at-three-scopes-and-served-as-one-plugin.md)
### How it is built