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

2026-10-07 19:43:55 +02:00
parent 79cadf6c96
commit 9ab4ca66ca
3 changed files with 72 additions and 1 deletions
@@ -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.
@@ -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

@@ -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.