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

# Umsetzungsplan: AgentEditor härten (Personalverwaltung)

> 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:

```csharp
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:

```csharp
["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.