ClawdDotNet/docs/umsetzungsplaene/UMSETZUNGSPLAN-AgentEditor-Haertung.md

Umsetzungsplan: AgentEditor härten (Personalverwaltung)

Stand 2026-08-23: beschlossen, noch nicht gebaut. Einordnung siehe Roadmap 3.2 (nach AgentInspector) — die Reihenfolge gilt dort, dieses Dokument ist der Bauplan.

Stand: 2026-08-05 Ziel: Änderungen an Identity und Soul im laufenden Betrieb bleiben möglich, werden aber freigabepflichtig, nachvollziehbar und rücknehmbar. Reihenfolge: Nach AgentInspector. Kein neues Tool — Härtung des bestehenden AgentEditorTool.

---

1. Ausgangslage

Das gewünschte „HR-Tool" existiert bereits: src/ClawdDotNet.Tools.AgentEditor/AgentEditorTool.cs

Aktion	Verhalten
list_agents	Übersicht inkl. Tools, HasIdentity, HasSoul, IsSelf
read_identity / read_soul	Datei lesen
update_identity / update_soul	Datei schreiben, vorher .bak_<zeitstempel>
create_agent	Grundstruktur mit Identity und Soul

Bereits richtig gelöst: keine AgentSettings.json, keine Chat-Daten, zeitgestempelte Backups statt Überschreiben, und die Tool-Zuweisung bleibt dem Menschen vorbehalten.

Ebenfalls bestätigt: Ein Neustart des Agenten ist nötig. Identity und Soul werden beim Laden in AgentConfig eingelesen (src/ClawdDotNet.Core/Config/AgentConfig.cs:20,27); einen Reload-Pfad gibt es nicht. Die Annahme aus der Ideensammlung stimmt also — „anhalten und neu starten" ist der vorgesehene Weg, kein Fehler.

---

2. Die drei offenen Lücken

2.1 Keine menschliche Freigabe

PermissionGate (src/ClawdDotNet.Core/Security/PermissionGate.cs) prüft genau eine Sache:

public bool IsAllowed(string agentId, string toolName, AgentConfig agentConfig)
    => agentConfig.Tools.ContainsKey(toolName);

Wer das Tool hat, darf alles damit. Ein Agent mit AgentEditor kann die Persönlichkeit jedes anderen Agenten der Instanz umschreiben — unbeaufsichtigt, zwischen zwei Ticks eines Cron-Jobs.

Die Ideensammlung formuliert den Anspruch anders: Änderungen sollen auf menschliche Anweisung erfolgen. Genau diese Kopplung fehlt.

Lösung — vorhandene Infrastruktur nutzen, nichts neu bauen. src/ClawdDotNet.Core/Staging/ enthält bereits die vollständige Kette: StagingPolicy entscheidet je Tool.Aktion, StagingGate fängt den Aufruf ab, StagingService bietet ApproveAsync/RejectAsync mit decidedBy.

Es genügt, die Regeln zu ergänzen:

["AgentEditor.update_identity"] = StagingDecision.Approve,
["AgentEditor.update_soul"]     = StagingDecision.Approve,
["AgentEditor.create_agent"]    = StagingDecision.Approve,

Lesende Aktionen bleiben Auto — Staging soll schützen, nicht lähmen (so begründet es der Kommentar an DefaultRules bereits selbst). Damit wandert jede Persönlichkeitsänderung in die Freigabeliste, und der Mensch entscheidet. Das ist zugleich die wörtliche Umsetzung von „auf menschliche Anweisung".

2.2 Selbstbearbeitung ist möglich

HandleListAgents liefert IsSelf bereits mit — ausgewertet wird es nirgends. Ein Agent kann seine eigene Soul umschreiben: die Datei, die sein Verhalten, seine Grenzen und seine Vorsicht definiert.

Das ist keine hypothetische Gefahr. Ein Agent, der in einer Schleife feststeckt und „hilfsbereit" sein will, kann sich selbst die Einschränkung wegschreiben, an der er scheitert.

Lösung: update_identity/update_soul mit agentId == context.AgentId werden abgelehnt — mit einer Begründung, die dem LLM den richtigen Weg zeigt („Änderungen an der eigenen Identity/Soul nimmt der Mensch vor; formuliere deinen Änderungswunsch stattdessen als Vorschlag"). Konfigurierbar über allowSelfEdit (Default false), damit der Betreiber die Wahl behält.

2.3 Kein Audit, kein Rückweg

Die .bak_-Dateien sind ein guter Anfang, aber:

• sie zeigen nicht, wer die Änderung veranlasst hat,
• es gibt keine Aktion, um sie zurückzuspielen — das ist Handarbeit im Explorer,
• die Antwort ans LLM enthält keinen Diff, also sieht auch der Mensch im Chatverlauf nicht, was sich geändert hat.

Lösung: Audit-Eintrag über die vorhandene IAuditRepository, restore- Aktion, und ein knapper Diff (geänderte Zeilen, nicht der Volltext) in der Rückmeldung.

---

3. Umsetzungsschritte

Slice 1 — Freigabe und Selbstschutz

• Drei Regeln in StagingPolicy.DefaultRules ergänzen
• allowSelfEdit in AgentEditorToolSettings (Models/ToolSettingsViewModels.cs:498), Default false
• Selbstbearbeitungs-Prüfung in HandleUpdateFileAsync
• Tests: Selbstbearbeitung abgelehnt, mit allowSelfEdit = true erlaubt, Staging-Entscheidung je Aktion korrekt aufgelöst

Slice 2 — Nachvollziehbarkeit

• Diff in der Rückmeldung (geänderte Zeilen mit +/-, gekappt)
• Audit-Eintrag je Änderung: Ziel-Agent, Datei, Backup-Name
• list_backups-Aktion: vorhandene .bak_-Stände eines Agenten
• restore-Aktion: Stand zurückspielen (erzeugt seinerseits ein Backup, damit auch ein Restore rücknehmbar bleibt) — ebenfalls Approve

Slice 3 — Betriebstauglichkeit

• Hinweis in der Erfolgsmeldung: „Wirksam nach Stop/Start des Agenten" (heute fehlt er — der Agent hält die Änderung sonst für sofort aktiv)
• frm_InstanceManager: Neustart eines einzelnen Agenten anbieten, falls dafür heute die ganze Instanz neu gestartet werden muss
• Aufräumen: FindAgentDirectory durch den gemeinsamen AgentDirectoryResolver aus dem AgentInspector-Plan ersetzen
• .bak_-Dateien in die Aufbewahrungslogik einbeziehen (sie wachsen sonst unbegrenzt) — Menge je Agent begrenzen, z. B. 20 Stände

---

4. Bewusst nicht umgesetzt

Hot-Reload von Identity/Soul. Technisch machbar, aber ein Agent, der mitten in einem Lauf seine Persönlichkeit wechselt, produziert einen Konversationsverlauf, dessen erste Hälfte einer anderen Rolle gehorcht als die zweite. Der Neustart ist hier die ehrlichere Grenze — und ohnehin der Weg, den die Ideensammlung selbst vorschlägt.

---

5. Abnahmekriterien

• update_soul landet in der Freigabeliste und wird erst nach menschlicher Bestätigung ausgeführt; read_soul läuft weiterhin ohne Rückfrage durch.
• Ein Agent kann seine eigene Soul nicht ändern.
• Nach einer Änderung ist im Audit ersichtlich: wer, wann, an wem, welche Datei.
• restore stellt einen früheren Stand wieder her und legt dabei selbst ein Backup an.
• Die Rückmeldung an den Agenten nennt ausdrücklich, dass die Änderung erst nach einem Neustart greift.