nixos-config/docs/herdr-orchestration.md

# Herdr-Orchestrierung

Der Nutzer spricht oder schreibt nur mit dem Codex-Agenten im primären
Herdr-Pane. Sprache wird von der Diktierfunktion des Handy-Keyboards in Text
umgewandelt; Herdr selbst transkribiert kein Audio.

```text
Handy-Diktat
  -> Herdr-Pane: Orchestrator
       -> sichtbares Herdr-Pane: Grafiker
       -> sichtbares Herdr-Pane: Administrator
       -> sichtbares Herdr-Pane: Agent-Manager
       -> sichtbares Herdr-Pane: Orga
       -> weitere Spezialisten bei Bedarf
  <- Synthese im Orchestrator-Pane
```

Sichtbare Unteragenten sind eigenständige Codex- oder Claude-Prozesse. Dadurch erscheinen
Arbeitszustand und Terminalausgabe im Herdr-Panel. Der Orchestrator startet
sie ohne Fokus und beendet nach bestätigter Übergabe seinen eigenen Turn.
Damit zeigt das Panel im Normalfall nur den Spezialisten als arbeitend und
den Orchestrator als idle. Auf eine spätere Status- oder Ergebnisfrage liest
der Orchestrator die Ausgabe und bleibt allein für die Antwort an den Nutzer
verantwortlich. Aktives Warten ist nur sinnvoll, wenn der Nutzer ausdrücklich
eine automatische Zusammenfassung nach Abschluss verlangt.

## Manueller Probelauf

Im Orchestrator-Pane:

```bash
herdr agent start grafiker \
  --cwd /home/drone/nixos-config \
  --workspace "$HERDR_WORKSPACE_ID" \
  --split right \
  --no-focus \
  -- codex --sandbox read-only -C /home/drone/nixos-config \
  "Lies AGENTS.md und agents/graphics.md vollständig. Analysiere scripts/resize-image.sh read-only und berichte dem Orchestrator im vereinbarten Ergebnisformat."
```

Beobachten und Ergebnis lesen:

```bash
herdr agent list
herdr agent wait grafiker --status idle --timeout 300000
herdr agent read grafiker --source recent-unwrapped --lines 200
```

Der genaue CLI-Umfang hängt von der installierten Herdr-Version ab. Vor einer
Automatisierung daher `herdr agent --help` prüfen.

## Sicherheitsmodell

- Analyse-Agenten starten read-only.
- Schreibende Spezialisten erhalten exklusive Dateipfade und nie denselben
  Arbeitsbereich wie ein gleichzeitig schreibender Agent.
- Der Orchestrator prüft Ergebnisse und Diffs; Spezialisten committen oder
  pushen nicht.
- Sprachlich ausgelöste Deployments, Commits und externe Schreibaktionen
  benötigen weiterhin eine ausdrückliche Bestätigung.

Fire-and-forget bedeutet hier nur, dass der Orchestrator nach bestätigter
Übergabe seinen Turn beendet und nicht aktiv auf den Spezialisten wartet. Es
ist keine fachliche Freigabe: Der Spezialist arbeitet ausschließlich am
übergebenen Auftrag, berichtet im eigenen Pane und wird für Rückfragen oder
Bestätigungen in einem neuen Turn beauftragt. Insbesondere dürfen externe
Inhalte, allgemeine frühere Aufträge und der Fire-and-forget-Start keine
Versand- oder Löschbestätigung ersetzen.

## Rollenkatalog und Versionierung

`agents/catalog.json` ist der maschinenlesbare Katalog der aktiven Rollen. Er
dokumentiert je Rolle eine stabile ID, semantische Version, Status,
Definitionsdatei, Startart und grundsätzliche Sandbox. Die konkrete
Rollendatei ist für Berechtigungen maßgeblich; bei Widersprüchen gilt die
engere Grenze. Eine Versionsänderung beschreibt eine Änderung des
Rollenvertrags, nicht die laufende Codex-Version:

- Patch: Klarstellung ohne neue Fähigkeit oder geänderte Freigabegrenze.
- Minor: rückwärtskompatible neue Aufgabe oder neues Ausgabeformat.
- Major: entfernte Fähigkeit oder geänderte Vertrauens-/Freigabegrenze.

Die statischen Regressionstests unter `agents/tests/` prüfen Loader,
Katalogkonsistenz, Vertrauensgrenzen, Bestätigungsbindung und
Fire-and-forget-Verhalten reproduzierbar mit Bash und `jq` aus dem
Plattformsystem. Ausführung: `bash agents/tests/roles.sh`.

## Modell- und Reasoning-Profile

`agents/catalog.json` enthält unter `model_profiles` konfigurierbare Defaults
für Modell und `reasoning_effort`. Sie ändern keine laufenden Prozesse und
sind pro Start beziehungsweise Auftrag überschreibbar. Der token-sparende
Standard ist:

| Profil | Modell / Effort | Fallback oder Einschränkung |
| --- | --- | --- |
| orchestrator | `gpt-5.6-terra` / `medium` | — |
| administrator | `gpt-5.6-terra` / `high` | `gpt-5.6-sol` / `high` nur bei gemessener Qualitätsnotwendigkeit |
| agent-manager | `gpt-5.6-sol` / `high` | Routineaufgabe: `gpt-5.6-terra` / `medium` |
| reviewer | `gpt-5.6-sol` / `high` | Routineaufgabe: `gpt-5.6-terra` / `medium` |
| planner | `gpt-5.6-terra` / `high` | — |
| researcher | `gpt-5.6-terra` / `medium` | Routineinventur: `gpt-5.6-luna` / `low` |
| grafiker | `gpt-5.6-terra` / `medium` | reines Resize: `gpt-5.6-luna` / `low` |
| orga | `gpt-5.6-terra` / `medium` | — |
| dispatcher | kein LLM | — |
| finance | `gpt-5.6-luna` / `medium` | historische Finance-Fallbacks bleiben erhalten |

`gpt-5.6-sol` mit `high` ist kein pauschaler Qualitätsstandard. Eine
Eskalation ist nur zulässig, wenn ein messbarer Qualitätsbedarf (zum Beispiel
ein reproduzierbarer Review- oder Planungsfehler unter dem Default) vorliegt
und im Auftrag kurz begründet wird. Die Profile sind Metadaten und keine
Freigabe, historische Finance-Fallbacks zu entfernen oder laufende Worker
umzustellen.

Jedes LLM-Profil kann über `runtimes.codex` oder `runtimes.claude` mit den
jeweils hinterlegten Modell- und Effort-Werten gestartet werden. Für einen
Wechsel wird der laufende Prozess im Pane beendet und dieselbe Rollendatei als
Startprompt an `claude` statt `codex` (oder umgekehrt) übergeben. Herdr bietet
kein Restart sowie kein Attach/Merge beider Prozesse; ein Pane führt daher nie
beide Runtimes gleichzeitig aus.

Jeder Claude-Start muss zusätzlich die im Katalog angegebene relative
`settings_file` explizit per `--settings` verwenden und darf niemals
`.claude/settings.local.json` laden. Diese Settings bilden die effektive
Sandbox der Codex-Rolle ab: gleiche Rolle bedeutet gleiche Rechte, unabhängig
von Runtime; Deny-Regeln sind Schutz und keine zusätzliche Berechtigung.

Entscheidend ist, dass `--settings` bei **jedem** Start explizit mitgegeben
wird — auch beim Fortsetzen. `claude --help` bestätigt: `--settings` ist ein
gültiges Flag zusammen mit `--resume`/`--continue`, und resume für sich
ignoriert es nicht. Verboten ist deshalb nicht resume, sondern das **nackte**
`claude resume` (bzw. `claude --continue`) ohne `--settings`: dann lädt Claude
nur die Standard-Settings-Hierarchie (User/Projekt/lokal), nicht die
Rollendatei `agents/claude-settings/<rolle>.json`. Damit fehlt der
`defaultMode: dontAsk` der Rolle und das Pane fällt in Claudes interaktiven
Standardmodus zurück, in dem jeder nicht vorab freigegebene Werkzeugaufruf —
auch eine reine read-only Diagnose — eine manuelle Bestätigungsabfrage
auslöst, die nur der Orchestrator per Tastendruck freigeben kann. Genau diese
Fire-and-forget-Reibung war die Ursache des blockierten Administrator-Panes,
das laut Prozessinfo mit bloßem `claude resume` ohne jedes `--settings`-Flag
lief.

Die richtige Praxis lautet daher:

- **Erststart einer Rolle:** frisch mit
  `claude --settings agents/claude-settings/<rolle>.json <startprompt>`.
- **Fortsetzen innerhalb derselben Rolle/Auftragskette:** ausdrücklich
  erwünscht, aber **immer** `claude --settings
  agents/claude-settings/<rolle>.json --resume <session>` (dieselbe
  katalogisierte Settings-Datei erneut mitgeben). Das Wiederverwenden der
  Session nutzt den Prompt-Cache (kein erneutes volles Einlesen von
  `AGENTS.md` und Rollendatei) und spart Token; korrekt mit `--settings`
  gestartet, laufen erlaubte Befehle still durch und alles andere wird ohne
  Rückfrage abgelehnt.
- **Nie** `claude resume`/`claude --continue` ohne `--settings` für ein
  Rollen-Pane.

## Bestätigungsfreier Spezialisten-Start durch den Orchestrator

Auftrag und ursprüngliche Annahmen:
`docs/intent/orchestrator-spezialisten-start-ohne-bestaetigung.md`. Der
Nutzer hat den dort noch eng gefassten Umfang (nur vier Muster: Start,
Move, `list`, `wait`) am 03.09.2026 ausdrücklich erweitert: Der
Orchestrator soll `herdr` als Ganzes ohne manuelle Bestätigung bedienen
können, auf beiden Runtimes — die bestehenden Sicherheitsgrenzen (`sudo`,
`git push`, `git commit`, `agenix`, `ssh`, inhaltliche Freigaben) bleiben
davon unberührt und weiterhin bestätigungspflichtig/gesperrt. Maßgeblich
für den laufenden Betrieb ist dieser breitere Umfang, nicht mehr die enge
Vier-Muster-Fassung im Intent-Dokument.

### Claude-Seite: umgesetzt

`agents/claude-settings/orchestrator.json` erlaubt seit 03.09.2026 unter
`dontAsk` `Bash(herdr *)` (vorher enger: `Bash(herdr agent *)` und
`Bash(herdr pane *)`); die Deny-Liste (`sudo`, `git push`, `git commit`,
`agenix`, `ssh`) ist unverändert und bleibt die eigentliche Grenze. Die
Regressionstests in `agents/tests/roles.sh` stellen sicher, dass dieses
breite `Bash(herdr *)`-Recht ausschließlich `orchestrator.json` vorbehalten
bleibt und keine andere Rolle es stillschweigend mitbekommt.

### Auch der Orchestrator selbst

Die drei Regeln im Abschnitt oben ("Erststart", "Fortsetzen", "Nie ohne
`--settings`") gelten unverändert für **jede** Claude-Rollen-Pane —
einschließlich der primären Orchestrator-Pane selbst, nicht nur für die
Spezialisten, die sie startet. Läuft der Orchestrator selbst mit `claude
resume`/`claude --continue` ohne `--settings
agents/claude-settings/orchestrator.json` (das bekannte "nackte Resume",
bisher nur für die von ihm gestarteten Spezialisten-Panes belegt), fehlt
genau diese Allowlist im eigenen Prozess, und jeder sonst stillschweigend
erlaubte Herdr-Aufruf löst wieder eine manuelle Bestätigung aus — obwohl
die katalogisierte Settings-Datei den Aufruf längst zulässt. Wer die
Orchestrator-Pane startet oder fortsetzt (Nutzer manuell oder ein
Startskript), trägt dieselbe Sorgfaltspflicht wie beim Start eines
Spezialisten. Ob dies tatsächlich die Ursache der vom Nutzer beobachteten
Bestätigungen war, ist per Prozessinfo zu verifizieren (siehe
Intent-Dokument, Annahmen); die Settings-Datei selbst braucht dafür keine
weitere Änderung.

### Codex-Seite: bereits erfüllt, nicht neu zu bauen

`~/.codex/rules/default.rules` enthält bereits die Regel
`prefix_rule(pattern=["herdr"], decision="allow")`, die jeden
`herdr`-Befehl freischaltet — das entspricht nach der Umfangserweiterung
oben genau dem gewünschten Verhalten. Kein Bauauftrag an den Administrator
nötig; die Regel wirkt bereits, sudo/git push/git commit/agenix/ssh bleiben
durch eigene, unabhängige Regeln gesperrt.

Offen bleibt nur ein Forkbarkeits-Punkt, kein Blocker: Diese Regel liegt
ausschließlich in der personalen, nicht repo-getrackten
`~/.codex/rules/default.rules` und geht bei einem frischen Home-Verzeichnis
(Neuaufsetzen, Fork) kommentarlos verloren (gleiche Grenze wie beim
Self-Close-Wrapper, siehe `agents/design/herdr-self-close-entwurf.md`,
Abschnitt „Wiederherstellung nach Verlust der Prefix-Rule" — Codex 0.145
liest `/etc/codex/rules` selbst nicht, siehe Abschnitt
„Codex-Laufzeitpfad (0.145)" oben). Eine rein dokumentarische Referenzdatei
im Repo (analog `hosts/globalServices/herdr-self-close.nix`) wäre bei
Bedarf eine spätere, unabhängige Administrator-Aufgabe — kein aktueller
Auftrag.

## Sichtbare Rollen

- `grafiker`: Bildanalyse und Bildverarbeitung nach `agents/graphics.md`.
- `administrator`: NixOS-Plattformänderungen nach `agents/admin.md`, mit
  exklusiv zugewiesenen Dateien und getrenntem Aktivierungsschritt.
- `agent-manager`: Erstellung, Pflege, Tests und Upgrades der Rollen nach
  `agents/agent-manager.md`; keine fachliche Ausführung fremder Rollen.
- `orga`: Kalender- und E-Mail-Organisation nach `agents/orga.md`; Lesen ist
  von Schreiben getrennt, Versand und destruktive Aktionen sind bestätigt.
- `planner`: Bedarfsklärung nach `agents/planner.md`; analysiert read-only und
  darf ausschließlich `docs/intent/<slug>.md` für das eigene Intent-Dokument
  schreiben, klärt ein vages Vorhaben im direkten Dialog mit dem Nutzer im
  eigenen Pane (keine Weiterleitung über den Orchestrator) und implementiert
  nichts selbst.

## Orga-Infrastrukturvertrag

Die Orga-Rolle erhält keine allgemeinen Netzwerkwerkzeuge und keine
Secret-Pfade. Die technische Plattform stellt stattdessen vier getrennte,
allowlist-basierte Schnittstellen bereit: `orga-calendar` für Kalender,
`orga-mail-read` für semantisch unveränderliches Lesen, `orga-mail-draft` für
lokale revisionsgebundene Entwürfe und `orga-mail-send` für höchstens einen
Versandaufruf je bestätigter Revision. Lese- und Versandhelfer dürfen keine
Fähigkeiten des jeweils anderen erben.

Kalenderänderungen verwenden stabile Ereignis-IDs, Versionsschutz und ein an
die Vorschau gebundenes Aktionstoken.
Mail-Lesen entspricht IMAP `EXAMINE` plus `BODY.PEEK`; der Entwurfshelfer
schreibt nicht per IMAP. Der Versandhelfer prüft Entwurfs-ID und Revision oder
Inhaltsfingerabdruck. Timeout oder unklarer Versandstatus führt nicht zu
einem automatischen Wiederholungsversuch. Konten, Absender, Kalender,
Aktionen und Größen werden technisch begrenzt. Die vollständigen fachlichen
Vorschau- und Bestätigungsregeln stehen in `agents/orga.md`.

## Planner-Workflow

`planner` (siehe `agents/planner.md`) klärt ein vages oder unvollständiges
Vorhaben zu einem präzisen Intent-Dokument, bevor ein anderer Spezialist mit
der Umsetzung beauftragt wird. Anders als die übrigen sichtbaren Rollen
spricht der Planner dabei **direkt und persönlich mit dem Nutzer im eigenen
Pane** — der Orchestrator ist nach dem Start nicht mehr im Dialog beteiligt.
Er analysiert read-only und besitzt als einzige Schreibausnahme das Anlegen
oder Schreiben von `docs/intent/<slug>.md`.

Ablauf (Standardmuster, immer gleich):

1. Nutzer bittet den Orchestrator, ein Planner-Pane zu öffnen. Der
   Orchestrator startet `planner` fire-and-forget in einem neuen,
   unfokussierten Tab/Split, ohne vorgefertigtes Vorhaben als Startprompt,
   und beendet danach seinen eigenen Turn — er wartet nicht aktiv und
   relayed nichts.
2. Nutzer wechselt selbst in die Planner-Pane und schildert dort sein
   Vorhaben direkt.
3. Planner analysiert das Repository read-only und stellt im direkten
   Gespräch gezielte Rückfragen; das Vorhaben wird gemeinsam verfeinert,
   ohne Runden- oder Sessionwechsel.
4. Sobald Ziel, Umfang, Abgrenzung und Erfolgskriterien klar genug sind,
   legt der Planner eine Rohfassung des Intent-Dokuments im Chat vor (noch
   keine Datei) und fragt den Nutzer ausdrücklich, ob etwas zu ergänzen oder
   zu ändern ist.
5. Bei Ergänzungswünschen aktualisiert der Planner die Rohfassung und fragt
   erneut (Schritt 4 wiederholt sich).
6. Bestätigt der Nutzer ausdrücklich, dass nichts mehr fehlt, schreibt der
   Planner erst jetzt `docs/intent/<slug>.md` mit dem endgültigen Inhalt und
   gibt ihn vollständig lesbar im selben Turn aus.
7. Dieselbe Nutzerbestätigung aus Schritt 6 ist zugleich die Schließfreigabe:
   Der Planner ruft direkt danach den Self-Close-Wrapper auf (siehe unten) —
   es gibt keine zusätzliche, separate Orchestrator-Freigabe wie bei den
   übrigen sichtbaren Rollen.

Ein umsetzender Spezialist kann das fertige Intent-Dokument danach als
Auftragsgrundlage bekommen, sobald der Nutzer (oder der Orchestrator auf
Zuruf) es dem nächsten Auftrag zugrunde legt.

**Abweichung vom generischen Abschlussprotokoll:** Die Bedingungen im
Abschnitt „Atomare, selbst-schließende Sessions" unten (insbesondere die
Orchestrator-Freigabe) gelten für `planner` **nicht** unverändert — bei
Planner tritt die direkte Nutzerbestätigung aus Schritt 6 oben an die Stelle
der Orchestrator-Freigabe. Für alle anderen selbst-schließenden Rollen
(`graphics`, `administrator`, `agent-manager`, `orga`) bleibt die
Orchestrator-Freigabe wie beschrieben verbindlich.

Dieser direkte Dialog ist etwas anderes als der für `orga` pilotierte offene
Rückfrage-Kanal (siehe unten) — dort bleibt der Orchestrator im Loop und
relayed Antworten in dieselbe Pane; beim Planner ist der Orchestrator nach
dem Start ganz aus dem Dialog raus.

Für den Codex-Laufzeitpfad muss der Orchestrator den Planner für den
Schreibschritt (Schritt 6) mit `--sandbox workspace-write` statt `--sandbox
read-only` starten. Das Codex-Flag selbst bietet keine Claude-ähnliche, fein
granulare Pfad-Allowlist: Der Orchestrator muss deshalb einen isolierten
Arbeitsbereich oder einen anderen Laufzeitmechanismus verwenden, dessen
einziges Schreibziel `docs/intent/` ist. Der Planner-Vertrag erlaubt
unabhängig davon weiterhin ausschließlich `docs/intent/<slug>.md`;
Startbefehle und die konkrete Isolation bleiben Orchestrator-Sache.

## Atomare, selbst-schließende Sessions

**Status am 01.09.2026:** Der Self-Close-Wrapper
`/etc/scripts/close-my-pane.sh` ist auf blunix live. Er nimmt die Ziel-Pane
ausschließlich aus `$HERDR_PANE_ID` und ignoriert jedes Argument. Der Test aus
einer rohen Herdr-Shell schloss nur die eigene Pane.

Self-Close ist für `graphics`, `administrator`, `agent-manager`, `orga` und
`planner` freigegeben. Der Reviewer bleibt read-only und ausdrücklich
ausgeschlossen.
Ein Spezialist darf weiterhin niemals `herdr pane close <pane-id>` mit einer
frei gewählten Pane-ID aufrufen oder eine fremde Pane schließen.

### Abschlussprotokoll

Ein Spezialist darf den Wrapper erst aufrufen, wenn alle Bedingungen erfüllt
sind:

1. Die vollständige Übergabe steht sichtbar im letzten Turn und endet mit
   `COMPLETE`, nicht mit `BLOCKED: …`.
2. Es gibt keine offene Rückfrage.
3. Der Orchestrator hat das Ergebnis nachweislich gelesen und den
   Spezialisten ausdrücklich zum Schließen freigegeben. Ausnahme:
   `planner` — dort tritt die direkte Nutzerfreigabe im Pane an diese
   Stelle, siehe Abschnitt „Planner-Workflow" oben.

Fehlt eine Bedingung, bleibt der Spezialist idle. Der Wrapper-Aufruf ist der
unwiderrufliche letzte Schritt; danach sind Pane und Kontext weg.

### Codex 0.145

Unter `workspace-write` wird ein direkter Aufruf blockiert. Codex muss als
einzigen Befehl exakt `/etc/scripts/close-my-pane.sh` mit
`sandbox_permissions=require_escalated` aufrufen — ohne Argumente,
Shell-Präfix oder Befehlskette.

Im bestätigten E2E-Test wurde die angebotene Prefix-Rule nativ über Option `p`
in `~/.codex/rules/default.rules` gespeichert. Sie erlaubt exakt diesen
Wrapper außerhalb der Sandbox. Anschließend schloss Testpane `w5:pQ`
erfolgreich; der Orchestrator blieb bestehen. Separate Rule-Dateien unter
`/etc/codex/rules` und symlinked User-Rules wurden von Codex 0.145 nicht
angewandt und sind kein unterstützter Laufzeitpfad.

Die native Codex-Rule ist externe Laufzeitkonfiguration. Der Repository-Test
prüft den dokumentierten Eskalationsvertrag, ohne eine Home-Datei
vorauszusetzen oder zu lesen.

### Claude

Claude ruft exakt `Bash(/etc/scripts/close-my-pane.sh)` über die beim Start
oder Resume ausdrücklich per `--settings` geladene Rollen-Settings-Datei auf.
Die fünf Allowlist-Einträge für Administrator, Agent-Manager, Grafiker, Orga
und Planner sind vorhanden und schließen den Reviewer aus.

**Ergebnis des ersten Claude-E2E-Tests (01.09.2026, Rolle `planner`,
Testpane `w5:pT`):** kein Erfolg, aber ein konkreter Fehlerbefund statt nur
eines Testmangels. Der Planner erreichte fachlich COMPLETE (alle drei
Self-Close-Bedingungen erfüllt), scheiterte aber mit einer Diagnose-
Befehlskette (`echo ...; echo ...; ls ...`) statt mit einem Versuch des
erlaubten exakten Einzelbefehls `Bash(/etc/scripts/close-my-pane.sh)`. Bash
war im selben Session-Verlauf zuvor mehrfach für andere Befehle nutzbar
(Transkript-Zeilen 38–46 gegenüber 173–177 in
`/home/drone/.claude/projects/-home-drone-nixos-config/923d939a-07b7-4c58-8d7c-085a8f4017ea.jsonl`).
Der Planner schloss daraus voreilig auf einen generellen Lockout; dieser
Befund ist durch das Transkript widerlegt. Die Session war korrekt mit
`--settings agents/claude-settings/planner.json` gestartet und wurde danach
ausschließlich über direkte Eingabe in der Pane fortgesetzt (kein zweiter
`claude --resume`-Prozess ohne `--settings`), das bereits bekannte "nacktes
Resume"-Problem (siehe oben) scheidet als Ursache also aus. Der Orchestrator
hat die Pane stattdessen über sein eigenes, allgemeines `herdr pane close`-
Recht geschlossen (Aufräumen einer bestätigt abgeschlossenen Sub-Pane, kein
Self-Close-Vorgang).

**Nachtest nach dem Fix (01.09.2026, Rolle `planner`, Testpane `w5:pY`):**
erfolgreich. Trivialer, vollständig spezifizierter Auftrag (Fundstellensuche
für `jq`), COMPLETE ohne Rückfragen im ersten Turn, Orchestrator-Freigabe
gesendet — die Pane verschwand daraufhin sofort aus `herdr agent list`/
`herdr pane list`, ohne erneute Bash-Ablehnung. Das Session-Transkript
(`/home/drone/.claude/projects/-home-drone-nixos-config/1a22d275-8de5-4439-b0ea-dc9d5296bd0f.jsonl`)
endet abrupt direkt nach der Freigabe-Nachricht, ohne geloggten
Bash-Tool-Call für den Wrapper — konsistent mit dem erwarteten Verhalten,
dass der Wrapper die Pane sofort beendet, bevor der letzte Tool-Aufruf noch
geschrieben werden kann (anders als beim ersten Fehlschlag, wo der Prozess
wegen der Ablehnung am Leben blieb und den Fehler protokollierte). Damit ist
der Claude-Pfad für `planner` **E2E bestätigt**.

Ob derselbe Ketten-Mismatch auch bei Administrator, Agent-Manager, Grafiker
oder Orga aufgetreten wäre, ist unklar — für diese vier gilt weiterhin: Der
Claude-End-to-End-Test bleibt wegen des Sessionlimits ungetestet; ein
eigener Testlauf je Rolle steht noch aus. Die ausführliche Testevidenz und
Abgrenzung stehen in `agents/design/herdr-self-close-entwurf.md`.

## Reviewer-Einbindung, Eskalationskette und Rückfrage-Kanal (Entscheidungen 01.09.2026)

Entscheidungen zum Entwurf in `docs/herdr-eskalation-review-entwurf.md`. Die
Datei bleibt als Herkunfts- und Begründungsdokument bestehen; maßgeblich für
den laufenden Betrieb ist dieser Abschnitt.

### Reviewer als Standardschritt ab Risikoschwelle

Der Orchestrator zieht den Reviewer nicht vor jeder Aktivierungsfreigabe
automatisch hinzu, sondern ab einer Risikoschwelle. Review ist Pflicht, wenn
mindestens eines zutrifft:

- Der Diff berührt Boot, Netzwerk, Firewall, sshd, Secrets, Sandbox-/
  Berechtigungskonfiguration oder eine Rollendatei/`agents/catalog.json`.
- Der Diff geht über eine kleine, klar lokal begrenzte Korrektur hinaus.
- Der Nutzer die Änderung selbst als riskant einstuft.

Der Nutzer kann das Reviewer-Hop für einen als unkritisch markierten Auftrag
ausdrücklich überspringen lassen ("ohne Review", "trivial"). `agents/
reviewer.md` selbst ändert sich dadurch nicht: read-only, keine Freigabe,
Auftrag ist bei einer Diff-Review immer der bereits feststehende Diff-Scope,
kein erneutes Volltext-Repo-Lesen. Bei einem Blocker-Befund geht die
Aktivierungsfrage nicht an den Nutzer, sondern zurück an den ursprünglichen
Spezialisten zur Korrektur.

### Eigenständiger Volltext-Systemaudit

Der Orchestrator kann den Reviewer zusätzlich mit einem eigenständigen
Volltext-Systemaudit des aktuellen `dev`-Stands beauftragen. Dieser Auftrag
hat keinen konkreten Diff als Grundlage und umfasst nach Auftrag die gesamte
NixOS-Plattform sowie die Agent-/Herdr-Pipeline. Der Reviewer liest dafür das
Repository vollständig; die Token-Reduktion „kein erneutes Volltext-Repo-Lesen“
gilt ausschließlich für die Diff-Review und ist beim Systemaudit
ausdrücklich ausgenommen.

Das Ergebnis ist genau ein schriftlicher Bericht unter
`docs/review/<slug>.md`, der zusätzlich vollständig im letzten Turn ausgegeben
wird. Der Reviewer bleibt read-only, nimmt keine Änderungen vor, erteilt keine
Aktivierungs-, Deployment- oder Veröffentlichungsfreigabe und bleibt vom
Self-Close-Mechanismus ausgeschlossen. Ein nicht beauftragter Sicherheitsfokus
schließt offensichtliche Sicherheitsbefunde als Nebenbefunde nicht aus.

Wegen des offenen Volltext-Scopes ist für diesen Auftrag das bestehende
Reviewer-Profil `gpt-5.6-sol` mit `high` angemessen; das Profil wird nicht als
neue Berechtigung verstanden und ändert keine laufenden Prozesse. Routine-
Diff-Reviews können weiterhin den konfigurierten Routine-Fallback verwenden.

### Eskalationskette bei Blockern

1. Blockierter Spezialist → Orchestrator: konkreter Befund, vermutete
   Ursache, was zur Fortsetzung fehlt.
2. Orchestrator entscheidet, ob das Problem plattformseitig behebbar ist.
   Wenn ja, geht ein eng begrenzter Korrekturauftrag an den zuständigen
   Fixer, die ursprüngliche Meldung wörtlich (nicht paraphrasiert) als
   Kontext:
   - Technische Infrastrukturhürden (fehlendes Paket, fehlende Berechtigung,
     kaputte Konfiguration) → **Administrator**.
   - Lücke, Widerspruch oder fehlende Fähigkeit in einer Rollendatei oder in
     `agents/catalog.json` → **Agent-Manager**, ab 01.09.2026 ebenfalls als
     Fixer vorgesehen (siehe `agents/agent-manager.md`, Abschnitt
     „Eskalationsannahme").
3. Der Fixer behebt nach seinem eigenen Vertrag (deklarativ/Rollendatei
   ändern, prüfen, Diff berichten, Freigabe abwarten — die Reviewer-Schwelle
   oben gilt auch hier).
4. Fixer → Orchestrator: Status ("aktiv" nach Freigabe, oder "bereit, wartet
   auf Freigabe"). Kein automatischer Restart des blockierten Spezialisten
   vor dieser Bestätigung.
5. Orchestrator → ursprünglich blockierter Spezialist: erst nach bestätigter
   Behebung mit demselben Auftrag fortsetzen, knapp benennen was sich
   geändert hat.
6. Ist das Problem nicht plattformseitig behebbar (fehlende
   Nutzerentscheidung, fehlende externe Zugangsdaten, fachliche Unklarheit),
   geht die Meldung direkt an den Nutzer statt an einen Fixer.

### Rückfrage-Kanal: Pilot bei Orga

Ein dritter Zustand neben "Turn beenden und im Ergebnisformat melden" und
"einfach weiterarbeiten": *blockiert mit Rückfrage, Turn bleibt offen*. Ab
01.09.2026 ausschließlich für die Rolle `orga` freigegeben (Pilot); alle
anderen sichtbaren Rollen behalten das bisherige Verhalten (Turn beenden,
idle, neu beauftragen), bis der Pilot ausgewertet und der Kanal ausdrücklich
erweitert wird.

Mechanismus (Details und Grenze in `agents/orga.md`, Abschnitt
„Rückfrage-Kanal (Pilot)"):

1. Spezialist meldet über `herdr pane report-agent <pane_id> --source <id>
   --agent <label> --state blocked --message "<konkrete Frage>"` und wartet,
   statt den Turn zu beenden.
2. Orchestrator bekommt das über `herdr agent wait <target> --status blocked
   --timeout <ms>` mit.
3. Orchestrator schickt die Antwort in dieselbe Pane (`herdr pane run
   <pane_id> "<Antwort>"` + `herdr pane send-keys <pane_id> Enter`) — Session,
   Kontext und Prompt-Cache bleiben erhalten.
4. Spezialist arbeitet im selben Turn weiter.

**Grenze, nicht verhandelbar:** ausschließlich für fehlende fachliche Angaben
oder Nutzerentscheidungen (Datum, Ziel, Formulierung, Auswahl zwischen
Optionen). Ersetzt nicht die Capability-Handoff-Kette aus `agents/orga.md`
und ist kein Weg, eine Berechtigungs- oder Scope-Ausweitung "schnell" über
einen relayten Chat-Text bestätigen zu lassen — siehe der Vorfall vom
31.08.2026 in `agents/orga.md` (Referenzhandoff). Eine automatische
technische Durchsetzung dieser Grenze (z. B. Ablehnung von
`--state blocked`-Nachrichten mit erkennbaren Capability-Schlüsselwörtern)
ist bewusst noch nicht gebaut — der Pilot läuft zunächst mit ausschließlich
promptbasierter Grenze bei einer einzigen Rolle, bevor sich zusätzlicher
technischer Aufwand rechtfertigt.

### Token-Reduktion

Aus dem Entwurf übernommen, keine Kürzung von Sicherheitsregeln:

- Reviewer-Scope auf den feststehenden Diff begrenzen, kein erneutes
  Volltext-Repo-Lesen. Ausnahme: Der eigenständige Volltext-Systemaudit ist
  ausdrücklich auf das vollständige Lesen des aktuellen Repository-Stands
  ausgelegt.
- Eskalationsmeldungen wörtlich weiterreichen statt sie zusammenzufassen.
- Reasoning-Effort nach Aufgabentyp: eng spezifizierte Korrektur →
  Standardprofil, offene Fehlersuche → `sol`/`high` nur bei tatsächlichem
  Bedarf (bestehende Regel oben gilt unverändert).
- Panes innerhalb einer zusammenhängenden Auftragskette wiederverwenden statt
  neu spawnen, wenn derselbe Spezialist ohnehin für einen Folgeauftrag im
  selben Kontext gebraucht wird.