hq/02-DECISIONS/0213-the-operator-sets-the-agents-managed-settings-through-the-agent-module.md

topic, status, date, deciders, reconstructed, extends

topic	status	date	deciders	reconstructed	extends
what runs on it	accepted	2026-10-04	jochen	false	02-DECISIONS/0183-the-anthropic-licence-manager-is-a-module-and-hands-tokens-to-the-agent-over-the-bus.md

213. The operator sets the agent's managed settings through the agent module, under the mesh's own keys

Context

The agent module writes the agent's machine-wide managed settings file (to-be 36 §2). It carries the mesh's own keys only: the attribution convention of its repositories, the connectors kept beside the managed tool servers, and the key-helper for an API-key licence. Every other key was left to the person's own settings, so that the mesh never reverts a person's choice on a push.

That left no place for a rule the operator wants to hold in every session on a machine: what the agent may do without asking, what it must never do, and what its unattended mode allows. These keys are not preferences. They are policy about what an agent may do on the mesh. Set by hand in one person's settings on each machine, they are unmanaged state the mesh cannot see, and the agent refuses to change them itself, as it should.

Considered Options

1. Leave them to each person's settings. Rejected: policy by hand on each machine, invisible to the mesh, and a session cannot be asked to loosen its own permissions.
2. A field per vendor key (permissions, auto mode, environment, hooks) in the module's settings. Rejected: the vendor adds keys, and every one would be a change to the module.
3. One setting holding managed-settings keys, laid under the mesh's own. The operator sets it for the mesh or for one node through the controller's settings verb. The module copies its keys into the managed settings file, then lays the mesh's keys over them.

Decision

Option 3.

1. The agent module takes a setting, managed_settings: an object in the vendor's settings shape. It is set for the whole mesh or for one node, like the module's other settings, through the controller's settings verb.
2. The managed settings file is that object with the mesh's keys laid last: the attribution convention, the connectors kept beside the managed servers, and the key-helper. A setting can neither replace one of these nor add a key-helper that the binding did not ask for.
3. Only the operator sets it, and it is declared state like the role and the extra tool servers. A person's preferences stay in their own settings; the mesh still sets none of them by itself.

Consequences

• The operator's rules for the agent are declared once, for the mesh or per node, and reach every node at the next push. A rule set in the managed settings outranks every other scope, so it holds in every session on the node.
• A setting layer is replaced whole by the controller's verb. Setting this key without the role or the extra tool servers clears those in that layer; the module's documentation says so.
• What got harder: a person cannot override a rule set here, which is the point. A rule that is wrong is wrong on every session of the node until the operator changes the setting.

How it is checked

Rule	Checked by
The operator's keys reach the managed settings file	the agent module's test: an auto-mode allow list and a permissions list set in the setting appear in the rendered file
The mesh's keys always win	the same test: a setting naming the attribution, the connectors key or a key-helper is overridden, and a key-helper appears only for an API-key binding
Live	the setting given for the mesh; the managed settings file on each node carries the key after the next push

References

• ADR 0183 — the agent module and the files it writes
• to-be 36 — the design this amends (§2, §6)
• the vendor's documentation on managed settings and their precedence