From 9ab4ca66cabe06f03bf164d1020a9ffca76126e3 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 7 Oct 2026 19:43:55 +0200 Subject: [PATCH] ADR 0243: the agent module removes a home item it did not place only on the person's word, so the old rule files can leave without a remote shell --- ...ly-on-the-persons-word-and-keeps-a-copy.md | 63 +++++++++++++++++++ 02-DECISIONS/README.md | 1 + .../36-the-operators-agent-on-a-machine.md | 9 ++- 3 files changed, 72 insertions(+), 1 deletion(-) create mode 100644 02-DECISIONS/0243-the-agent-module-removes-a-home-item-it-did-not-place-only-on-the-persons-word-and-keeps-a-copy.md diff --git a/02-DECISIONS/0243-the-agent-module-removes-a-home-item-it-did-not-place-only-on-the-persons-word-and-keeps-a-copy.md b/02-DECISIONS/0243-the-agent-module-removes-a-home-item-it-did-not-place-only-on-the-persons-word-and-keeps-a-copy.md new file mode 100644 index 00000000..a76d180f --- /dev/null +++ b/02-DECISIONS/0243-the-agent-module-removes-a-home-item-it-did-not-place-only-on-the-persons-word-and-keeps-a-copy.md @@ -0,0 +1,63 @@ +--- +topic: what runs on it +status: accepted +date: 2026-10-07 +deciders: jochen +reconstructed: false +extends: 02-DECISIONS/0216-the-agents-configuration-is-registered-through-its-module-at-three-scopes-and-served-as-one-plugin.md +--- + +# 243. The agent module removes a home item it did not place only on the person's word, and keeps a copy + +## Context + +[ADR 0216](0216-the-agents-configuration-is-registered-through-its-module-at-three-scopes-and-served-as-one-plugin.md) +gave the agent module the home scope: the coding agent's own folder under the operator account. In +its rule 5 the module "writes, changes and removes only" what it placed there. Rule 6 says it +reports and can import what it did not place, and "removing the original stays the person's act". + +That left the person's act with no channel. Rule files written by hand under a predecessor system +sat in the home of every machine. They told every session to use tools that no longer exist and +contradicted the mesh's own instructions. The operator asked for them to be folded into mesh-wide +instructions and removed. Removing a file on four machines without a tool means a remote shell on +each, which is the work-around the mesh refuses: a missing tool is built in the module that owns +the area, never worked around. + +## Options + +1. **Leave removal outside the mesh.** The person deletes by hand on each machine. This keeps rule 5 + as written, but the mesh's most-used surface then has a task it cannot do, and the deletion + leaves no trace and no way back. +2. **Import, then unregister.** Importing at home scope puts the item under the mesh's care, and + unregistering it removes it. This works today, but it is a trick: the record would say the + mesh placed something it never placed. +3. **A removal tool for what the module did not place, called only on the person's word.** It + keeps a copy and logs the reason, with a restore tool beside it. + +## Decision + +Option 3. + +- The module serves, per machine, a tool that reads one home item it did not place, the + account's own instruction file included. It also serves a tool that removes one such item and + a tool that puts a removed item back. +- The removal tool requires a reason, and it is called only when the person asks for that item to + go, never on an agent's own judgement. That is rule 6's "person's act", made through a tool. +- Before removing, the module copies the item into its own state and checks the copy. If the + copy fails, nothing is removed. The removal is logged with its reason, both in the module's + state and in the journal. +- The tool refuses an item the mesh placed, because unregistering owns those. It also refuses a + symbolic link and a name that leads outside the item's own folder. +- Restore refuses when something already exists at the original path. + +This extends rule 5 of ADR 0216: the module removes what it placed, and also, on the person's +word, what it did not place. Rule 6 stands as written. + +## Consequences + +- An item the mesh did not place can now leave a machine with its reason recorded and its content + kept, and it can come back. +- Whether the person asked is checked by nobody but the caller. The tool's description says so, + and the logged reason is what an audit reads. A tool cannot tell an operator's request from an + agent's initiative, so this rule is checked after the fact, by reading the removal log. +- The kept copies stay in the module's state until removed. Clearing them is not decided here. diff --git a/02-DECISIONS/README.md b/02-DECISIONS/README.md index 7549f3f2..669ae903 100644 --- a/02-DECISIONS/README.md +++ b/02-DECISIONS/README.md @@ -339,6 +339,7 @@ python3 00-META/checks/index.py fail if stale - **0233** — [A module declares the data it holds, and the mesh protects and watches it from that declaration](0233-a-module-declares-the-data-it-holds-and-the-mesh-protects-and-watches-it-from-that.md) - **0235** — [The bus is backed up by its own snapshot of each stream, taken under the bus module's account](0235-the-bus-is-backed-up-by-its-own-snapshot-of-each-stream.md) - **0240** — [A module says how it is healthy, and the node-engine judges it](0240-a-module-says-how-it-is-healthy-and-the-node-engine-judges-it.md) +- **0243** — [The agent module removes a home item it did not place only on the person's word, and keeps a copy](0243-the-agent-module-removes-a-home-item-it-did-not-place-only-on-the-persons-word-and-keeps-a-copy.md) ### How it is built diff --git a/03-DESIGN/01-to-be/36-the-operators-agent-on-a-machine.md b/03-DESIGN/01-to-be/36-the-operators-agent-on-a-machine.md index 8efec9b9..91053c25 100644 --- a/03-DESIGN/01-to-be/36-the-operators-agent-on-a-machine.md +++ b/03-DESIGN/01-to-be/36-the-operators-agent-on-a-machine.md @@ -2,8 +2,9 @@ layer: to-be status: in-progress code: [mesh-catalog modules/claude-code] -updated: 2026-10-05 +updated: 2026-10-07 decisions: + - 02-DECISIONS/0243-the-agent-module-removes-a-home-item-it-did-not-place-only-on-the-persons-word-and-keeps-a-copy.md - 02-DECISIONS/0216-the-agents-configuration-is-registered-through-its-module-at-three-scopes-and-served-as-one-plugin.md - 02-DECISIONS/0213-the-operator-sets-the-agents-managed-settings-through-the-agent-module.md - 02-DECISIONS/0209-a-login-on-a-node-moves-that-node-to-its-account-and-an-api-key-is-added-from-any-node-sealed.md @@ -247,6 +248,10 @@ a section that contradicts another, or that calls a tool the mesh no longer serv **The home scope owns only what it placed.** The module records each home path it placed and touches only those (ADR 0182). It refuses to register a name the person already uses there. +The one exception is a removal the person asks for ([ADR 0243](../../02-DECISIONS/0243-the-agent-module-removes-a-home-item-it-did-not-place-only-on-the-persons-word-and-keeps-a-copy.md)). +On the person's word, with a reason, the module removes an item it did not place. It keeps a checked copy in its own +state and logs the removal, and can put the item back. + **The tools.** - For each kind: list, register and unregister. Each register takes a scope, and a list says where @@ -254,6 +259,8 @@ only those (ADR 0182). It refuses to register a name the person already uses the - For settings and permission rules: read, and set at a scope. - A **status tool** lists the home's own items beside the mesh's and names the stale ones. - An **import tool** registers an item found in one machine's home at a scope the operator chooses. +- A **show tool** reads one home item in full; a **remove tool** takes one away on the person's word, + copy kept and reason logged; a **restore tool** puts a removed item back. An item and its files are one value in the state, refused above 256 KiB.